folderweb/docs/reference/file-structure.md

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:

<link rel="stylesheet" href="/app/styles/base.css?v=abc123def456">

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
• Configuration Reference
• How to Customize Templates
• How to Customize Styles