# File Structure Reference Complete reference for FolderWeb's file and directory structure. ## Root Structure ``` project/ ├── app/ # Framework core (never modify) ├── content/ # Your website content ├── custom/ # Your customizations └── .htaccess # Web server configuration (optional) ``` ## App Directory (Framework Core) ``` app/ ├── router.php # Main entry point and request router ├── content.php # Content discovery and parsing functions ├── rendering.php # Template rendering engine ├── context.php # Context object (readonly class) ├── config.php # Configuration loader ├── helpers.php # Utility functions ├── constants.php # File extension constants ├── static.php # Static file server ├── config.ini # Default configuration ├── default/ # Default files (fallback) │ ├── templates/ # Default templates │ │ ├── base.php # HTML wrapper │ │ ├── page.php # Page wrapper │ │ ├── list.php # Simple list │ │ ├── list-grid.php # Grid layout │ │ ├── list-card-grid.php # Card grid │ │ └── list-faq.php # FAQ layout │ ├── styles/ # Default CSS │ │ └── base.css # Main stylesheet │ ├── languages/ # Default translations │ │ ├── en.ini # English │ │ └── no.ini # Norwegian │ └── content/ # Demo content (fallback) └── vendor/ # Third-party libraries └── Parsedown.php # Markdown parser ``` **Important**: Never modify files in `/app/`. All customization goes in `/custom/`. ## Custom Directory ``` custom/ ├── templates/ # Override templates │ ├── base.php # Custom base template │ ├── page.php # Custom page template │ ├── list-*.php # Custom list templates │ └── [custom].php # Your custom templates ├── styles/ # Override styles │ └── base.css # Custom stylesheet ├── languages/ # Override translations │ ├── en.ini # English translations │ ├── no.ini # Norwegian translations │ └── [lang].ini # Other languages ├── fonts/ # Custom web fonts │ └── *.woff2 # Font files ├── assets/ # Root-level assets │ ├── favicon.ico # Site favicon │ ├── robots.txt # Robots file │ ├── logo.svg # Logo │ └── [any file] # Served at root level └── config.ini # Configuration overrides ``` ## Content Directory Your content directory contains all your website pages and assets. ### Basic Structure ``` content/ ├── index.md # Home page ├── about/ # About page │ ├── index.md # Page content │ ├── metadata.ini # Page metadata │ └── team-photo.jpg # Page asset ├── blog/ # Blog (list view) │ ├── metadata.ini # Blog configuration │ ├── 2025-11-01-first-post/ │ │ ├── index.md # Post content │ │ ├── cover.jpg # Cover image │ │ └── metadata.ini # Post metadata │ └── 2025-11-02-second-post/ │ ├── index.md │ ├── cover.webp │ └── metadata.ini └── docs/ # Multi-file page ├── 00-intro.md # Section 1 ├── 01-setup.md # Section 2 ├── 02-usage.md # Section 3 └── metadata.ini # Page metadata ``` ### Content Types #### Single-File Page ``` content/about/ └── index.md ``` URL: `/about/` #### Multi-File Page ``` content/docs/ ├── 00-intro.md ├── 01-setup.md └── 02-usage.md ``` URL: `/docs/` (all files render as one page) #### List View (Directory with Subdirectories) ``` content/blog/ ├── metadata.ini ├── 2025-11-01-post/ │ └── index.md └── 2025-11-02-post/ └── index.md ``` URL: `/blog/` (shows list of posts) ## File Naming Conventions ### Content Files Supported extensions: - `.md` - Markdown (parsed with Parsedown) - `.html` - HTML (included as-is) - `.php` - PHP (executed with access to `$ctx`) ### Language-Specific Files Format: `filename.{lang}.ext` Examples: - `index.md` - Default language - `index.no.md` - Norwegian - `index.fr.md` - French - `about.en.md` - English ### Date Prefixes Format: `YYYY-MM-DD-slug` Examples: - `2025-11-01-my-post` - `2025-11-02-another-post` Dates are automatically extracted and formatted. ### Cover Images Filename: `cover.{ext}` Supported formats: - `cover.jpg` - `cover.jpeg` - `cover.png` - `cover.webp` - `cover.gif` Automatically detected in list views. ### PDF Files Any `.pdf` file in a directory is automatically linked in grid layouts. ### Metadata Files Filename: `metadata.ini` Format: INI with optional language sections. ## File Discovery Order ### Content File Priority For multi-file pages, files are rendered in alphanumerical order: ``` content/docs/ ├── 00-intro.md # First ├── 01-setup.md # Second ├── 02-usage.md # Third └── 99-appendix.md # Last ``` Use numerical prefixes to control order. ### Template Resolution Templates are resolved with custom fallback: 1. `/custom/templates/{name}.php` 2. `/app/default/templates/{name}.php` ### CSS Resolution Stylesheets are resolved with custom fallback: 1. `/custom/styles/base.css` 2. `/app/default/styles/base.css` ### Translation Resolution Translations are resolved with custom fallback: 1. `/custom/languages/{lang}.ini` 2. `/app/default/languages/{lang}.ini` ### Configuration Resolution Configuration is merged: 1. Load `/app/config.ini` 2. Merge with `/custom/config.ini` if exists Custom values override defaults. ## URL Mapping ### Basic Mapping ``` /content/about/index.md → /about/ /content/blog/ → /blog/ /content/docs/ → /docs/ ``` ### Language Prefixes Default language (no prefix): ``` /content/about/index.md → /about/ ``` Other languages (with prefix): ``` /content/about/index.no.md → /no/about/ /content/about/index.fr.md → /fr/about/ ``` ### Translated Slugs With metadata slug overrides: ``` content/about/metadata.ini: [no] slug = "om-oss" [fr] slug = "a-propos" ``` URLs become: - `/about/` (English) - `/no/om-oss/` (Norwegian) - `/fr/a-propos/` (French) ### Trailing Slashes FolderWeb requires trailing slashes for directories. Missing slashes trigger 301 redirects: ``` /blog → 301 redirect to → /blog/ ``` ## Special Files and Directories ### System Files (Ignored) These files are automatically ignored: - `.htaccess` - `.git/` - `.DS_Store` - `node_modules/` - Hidden files/directories (starting with `.`) ### Index Files `index.md`, `index.html`, `index.php` are treated as directory content, not separate routes. ### Metadata Files `metadata.ini` files are configuration, never rendered as content. ## Asset Serving ### Root-Level Assets Files in `/custom/assets/` are served at site root: ``` /custom/assets/robots.txt → yoursite.com/robots.txt /custom/assets/favicon.ico → yoursite.com/favicon.ico /custom/assets/logo.svg → yoursite.com/logo.svg ``` ### Content Assets Files in content directories are accessible at their directory URL: ``` /content/blog/2025-11-01-post/cover.jpg → yoursite.com/blog/2025-11-01-post/cover.jpg /content/about/team-photo.jpg → yoursite.com/about/team-photo.jpg ``` ### CSS Files CSS is served with version hashing: ``` /custom/styles/base.css → yoursite.com/app/styles/base.css?v=abc123def456 ``` ### Font Files Fonts in `/custom/fonts/` are accessible: ``` /custom/fonts/MyFont.woff2 → yoursite.com/custom/fonts/MyFont.woff2 ``` ## File Permissions ### Readable Files The web server must have read access to: - All files in `/app/` - All files in `/content/` - All files in `/custom/` ### Writable Files FolderWeb is read-only. No files require write access. ### Security - Path validation prevents directory traversal - Files must be within document root - Realpath checks ensure proper resolution ## Size Limits - **Read Tool**: Files larger than 50KB are truncated - **No upload limits**: FolderWeb doesn't handle uploads - **No execution limits**: Standard PHP limits apply ## Caching ### CSS Versioning CSS files are versioned with MD5 hash: ```html ``` Hash updates when file content changes. ### No Built-in Cache FolderWeb doesn't implement content caching. Use: - Web server caching (Apache, Nginx) - Reverse proxy (Varnish, Cloudflare) - PHP OPcache for code ## Related - [Metadata Reference](metadata.md) - [Configuration Reference](configuration.md) - [How to Customize Templates](../how-to/custom-templates.md) - [How to Customize Styles](../how-to/custom-styles.md)