Update README with clearer structure and features

README.md

@@ -1,35 +1,84 @@
 # FolderWeb
 
-**Just enough, nothing more.** Drop content files in folders, and they become pages. No database, no build process.
+A PHP router that turns folders into websites — and a core you can build upon. Drop files in a directory, and they become pages. No database, no build process.
 
-## What is FolderWeb?
+## How It Works
 
-FolderWeb is a content publishing framework where your file system is your content management system. Create a folder structure that mirrors your site hierarchy, drop files into folders, and they immediately become pages.
+Your file system is your site structure. Create folders, drop in content files, and they're live.
 
-**Core principle**: Simplicity and longevity over features and complexity.
+```
+content/about/intro.md  →  yoursite.com/about/
+```
 
-## Key Features
+No routing configuration. No frontmatter. No build step. Save a file, refresh the browser.
 
-- **File-based routing**: `content/blog/post/` → `yoursite.com/blog/post/`
+Since everything is just files and folders, you can mount your site via SFTP or WebDAV and edit content directly from your local machine — save a file, and the change is live.
-- **Multiple content formats**: Write in Markdown, HTML, or PHP — and mix them freely within the same page. Use Markdown for prose, HTML for structured sections, and PHP when you need dynamic output. Prefix filenames with numbers (`10-intro.md`, `20-gallery.html`) to control render order.
+
-- **Template system**: Override any default template with your own
+## Mix Formats Freely
-- **Multi-language support**: Built-in i18n with URL prefixes and per-file translations
+
-- **Modern CSS**: CSS variables, nesting, OKLCH colors, grid layouts
+A single page can combine Markdown, HTML, and PHP. Use each format where it fits best — Markdown for prose, HTML for layout, PHP for dynamic output. Number prefixes control the order:
-- **No build process**: Save and refresh — see changes immediately
+
+```
+content/services/
+├── 10-intro.md          # Markdown prose
+├── 20-features.html     # Structured HTML section
+└── 30-pricing.php       # Dynamic server-side output
+```
+
+All three render as one page at `/services/`.
+
+## Automatic Content Types
+
+FolderWeb detects what kind of page to render based on your folder structure:
+
+```
+content/about/           # Only files → renders as a page
+content/blog/            # Has subdirectories → renders as a list
+```
+
+Date prefixes in folder names are extracted automatically and stripped from URLs:
+
+```
+content/blog/2025-03-15-my-post/  →  /blog/my-post/  (date: March 15, 2025)
+```
+
+Cover images (`cover.jpg`), metadata (`metadata.ini`), and navigation are all convention-based. Almost nothing needs explicit configuration.
+
+## Customize Without Touching the Core
+
+The `custom/` directory overrides `app/default/` for everything — templates, styles, config, languages, and plugins:
+
+```
+custom/
+├── templates/    # Override any template
+├── styles/       # Your CSS
+├── plugins/      # Your plugins
+├── languages/    # Translation overrides
+└── config.ini    # Configuration overrides
+```
+
+To update FolderWeb, pull the latest `app/`. Your customizations stay untouched.
+
+## What You Need
+
+- PHP 8.4+
+- Apache with mod_rewrite
+
+That's all. One dependency (Parsedown for Markdown). ~1,000 lines of core code.
 
 ## Example Structure
 
 ```
 project/
-├── app/                    # Application (never modify)
+├── app/                    # Core (never modify)
-├── content/                # Your website content
+├── content/                # Your content
-│   ├── front.md           # Home page
+│   ├── front.md
 │   ├── about/
-│   │   └── about-me.md
+│   │   └── about.md
 │   ├── portfolio/
-│   │   ├── 10-intro.md            # Markdown prose
+│   │   ├── 10-intro.md
-│   │   ├── 20-gallery.html        # HTML layout
+│   │   ├── 20-gallery.html
-│   │   └── 30-stats.php           # Dynamic PHP output
+│   │   └── 30-stats.php
 │   └── blog/
 │       ├── metadata.ini
 │       ├── 2025-11-01-first-post/
@@ -46,6 +95,6 @@ project/
 
 ## Documentation
 
-Complete documentation available in [`docs/`](docs/).
+Complete documentation in [`docs/`](docs/).
 
 Start with the **[Getting Started guide](docs/01-getting-started/index.md)** or browse the **[tutorial](docs/02-tutorial/)**.