394 lines
9.3 KiB
Markdown
394 lines
9.3 KiB
Markdown
# 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
|
|
<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](metadata.md)
|
|
- [Configuration Reference](configuration.md)
|
|
- [How to Customize Templates](../how-to/custom-templates.md)
|
|
- [How to Customize Styles](../how-to/custom-styles.md)
|