309 lines
8.4 KiB
Markdown
309 lines
8.4 KiB
Markdown
# FolderWeb Documentation
|
|
|
|
Complete documentation for FolderWeb, a minimalist file-based PHP framework for content websites.
|
|
|
|
## What is FolderWeb?
|
|
|
|
FolderWeb is a file-based content publishing framework. Drop Markdown files in folders, and they become pages. No database, no build process, no JavaScript required. Just PHP, HTML, and CSS.
|
|
|
|
**Core principle**: Your file system is your content management system.
|
|
|
|
## Documentation Structure
|
|
|
|
This documentation follows the [Diataxis framework](https://diataxis.fr/), organizing content into four types:
|
|
|
|
### 🎓 Tutorial
|
|
|
|
**Learning-oriented**: Get started with FolderWeb
|
|
|
|
- [Getting Started](tutorial/00-getting-started.md) - Build your first site in 10 minutes
|
|
|
|
**Start here** if you're new to FolderWeb.
|
|
|
|
### 📋 How-To Guides
|
|
|
|
**Task-oriented**: Solve specific problems
|
|
|
|
- [Custom Templates](how-to/custom-templates.md) - Override default templates
|
|
- [Custom Styles](how-to/custom-styles.md) - Customize appearance with CSS
|
|
- [Multi-Language Sites](how-to/multi-language.md) - Set up multiple languages
|
|
- [Working with Metadata](how-to/working-with-metadata.md) - Use metadata.ini files
|
|
|
|
**Use these** when you need to accomplish a specific task.
|
|
|
|
### 📖 Reference
|
|
|
|
**Information-oriented**: Look up technical details
|
|
|
|
- [File Structure](reference/file-structure.md) - Complete directory layout
|
|
- [Metadata](reference/metadata.md) - All metadata fields
|
|
- [Templates](reference/templates.md) - Template variables and usage
|
|
- [Configuration](reference/configuration.md) - Configuration options
|
|
- [CSS Variables](reference/css-variables.md) - Styling customization
|
|
|
|
**Consult these** when you need precise technical information.
|
|
|
|
### 💡 Explanation
|
|
|
|
**Understanding-oriented**: Understand concepts and design
|
|
|
|
- [Philosophy](explanation/philosophy.md) - Design principles and thinking
|
|
- [Architecture](explanation/architecture.md) - How FolderWeb works
|
|
|
|
**Read these** to understand why FolderWeb works the way it does.
|
|
|
|
## Quick Links
|
|
|
|
### Common Tasks
|
|
|
|
- **Create a page**: Drop `index.md` in a folder
|
|
- **Create a blog**: Make a folder with subdirectories
|
|
- **Add navigation**: Set `menu = true` in `metadata.ini`
|
|
- **Customize look**: Override `/custom/styles/base.css`
|
|
- **Use custom template**: Set `page_template = "template-name"` in metadata
|
|
- **Multi-language**: Configure languages and add `.{lang}.md` files
|
|
|
|
### Key Concepts
|
|
|
|
- **File-based routing**: `content/blog/post/` → `yoursite.com/blog/post/`
|
|
- **Template fallback**: Custom templates override defaults
|
|
- **Language prefixes**: `/en/page/` for English, `/no/page/` for Norwegian
|
|
- **Metadata inheritance**: None - each directory has its own `metadata.ini`
|
|
- **Content types**: Single-file, multi-file, or list view
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# 1. Create project
|
|
mkdir my-site && cd my-site
|
|
|
|
# 2. Copy framework files
|
|
cp -r /path/to/folderweb/app ./app
|
|
|
|
# 3. Create content
|
|
mkdir content
|
|
echo "# Hello World" > content/index.md
|
|
|
|
# 4. Start server
|
|
php -S localhost:8000 -t . app/router.php
|
|
|
|
# 5. Visit http://localhost:8000
|
|
```
|
|
|
|
## System Requirements
|
|
|
|
- **PHP**: 8.4 or higher
|
|
- **Web server**: Apache, Nginx, or PHP built-in server
|
|
- **Extensions**: Standard PHP (no special extensions needed)
|
|
|
|
## File Structure Overview
|
|
|
|
```
|
|
project/
|
|
├── app/ # Framework (never modify)
|
|
│ ├── router.php # Entry point
|
|
│ ├── content.php # Content discovery
|
|
│ ├── rendering.php # Template rendering
|
|
│ └── default/ # Default templates, styles, languages
|
|
├── content/ # Your website content
|
|
│ ├── index.md # Home page
|
|
│ ├── about/ # About page
|
|
│ └── blog/ # Blog with posts
|
|
└── custom/ # Your customizations
|
|
├── templates/ # Custom templates
|
|
├── styles/ # Custom CSS
|
|
├── languages/ # Custom translations
|
|
└── config.ini # Configuration overrides
|
|
```
|
|
|
|
## Core Features
|
|
|
|
### File-Based Routing
|
|
|
|
Your folder structure defines your URLs:
|
|
|
|
```
|
|
content/blog/2025-11-02-post/ → /blog/2025-11-02-post/
|
|
```
|
|
|
|
No route configuration needed.
|
|
|
|
### Multiple Content Types
|
|
|
|
- **Single-file page**: One file in a directory
|
|
- **Multi-file page**: Multiple files combined into one page
|
|
- **List view**: Directory with subdirectories becomes a listing
|
|
|
|
### Template System
|
|
|
|
Six templates included:
|
|
- `base.php` - HTML wrapper
|
|
- `page.php` - Page wrapper
|
|
- `list.php` - Simple list
|
|
- `list-grid.php` - Grid with images
|
|
- `list-card-grid.php` - Card grid
|
|
- `list-faq.php` - Expandable FAQ
|
|
|
|
Override any template in `/custom/templates/`.
|
|
|
|
### Multi-Language Support
|
|
|
|
Configure languages:
|
|
```ini
|
|
[languages]
|
|
default = "en"
|
|
available = "en,no,fr"
|
|
```
|
|
|
|
Create language-specific files:
|
|
```
|
|
index.md # English (default)
|
|
index.no.md # Norwegian
|
|
index.fr.md # French
|
|
```
|
|
|
|
URLs automatically prefixed: `/`, `/no/`, `/fr/`
|
|
|
|
### Metadata System
|
|
|
|
Control behavior with `metadata.ini`:
|
|
|
|
```ini
|
|
title = "My Page"
|
|
date = "2025-11-02"
|
|
summary = "Page description"
|
|
menu = true
|
|
menu_order = 1
|
|
page_template = "list-grid"
|
|
```
|
|
|
|
### Modern CSS
|
|
|
|
Default styles use:
|
|
- CSS custom properties (variables)
|
|
- CSS nesting
|
|
- OKLCH colors
|
|
- Grid layouts
|
|
- Fluid typography with `clamp()`
|
|
- Logical properties
|
|
|
|
Override in `/custom/styles/base.css`.
|
|
|
|
## Philosophy Highlights
|
|
|
|
- **Just enough, nothing more**: Minimal, maintainable code
|
|
- **Longevity over novelty**: Works today, works in 2035
|
|
- **Files are content**: Portable, version-controllable
|
|
- **No JavaScript required**: Pure HTML and CSS
|
|
- **No build process**: Immediate feedback
|
|
|
|
Read the full [Philosophy](explanation/philosophy.md) for more.
|
|
|
|
## Example Use Cases
|
|
|
|
### Personal Blog
|
|
|
|
```
|
|
content/
|
|
├── index.md # About me
|
|
├── blog/ # Blog posts
|
|
│ ├── metadata.ini # page_template = "list-grid"
|
|
│ ├── 2025-11-01-post/
|
|
│ └── 2025-11-02-post/
|
|
└── contact/ # Contact page
|
|
└── index.md
|
|
```
|
|
|
|
### Documentation Site
|
|
|
|
```
|
|
content/
|
|
├── index.md # Introduction
|
|
├── getting-started/ # Multi-file tutorial
|
|
│ ├── 00-install.md
|
|
│ ├── 01-setup.md
|
|
│ └── 02-first-steps.md
|
|
└── reference/ # API reference
|
|
├── metadata.ini # page_template = "list"
|
|
├── functions/
|
|
└── classes/
|
|
```
|
|
|
|
### Portfolio
|
|
|
|
```
|
|
content/
|
|
├── index.md # Homepage
|
|
├── projects/ # Project grid
|
|
│ ├── metadata.ini # page_template = "list-card-grid"
|
|
│ ├── project-1/
|
|
│ │ ├── index.md
|
|
│ │ ├── cover.jpg
|
|
│ │ └── metadata.ini # redirect = "https://project.com"
|
|
│ └── project-2/
|
|
└── about/
|
|
└── index.md
|
|
```
|
|
|
|
## When to Use FolderWeb
|
|
|
|
### ✅ Ideal For
|
|
|
|
- Blogs and content sites
|
|
- Documentation
|
|
- Portfolios
|
|
- Marketing sites
|
|
- Personal websites
|
|
- Projects requiring longevity
|
|
|
|
### ❌ Not Ideal For
|
|
|
|
- User-generated content (no database/auth)
|
|
- E-commerce (use dedicated platform)
|
|
- Social networks (need real-time features)
|
|
- JavaScript-heavy SPAs
|
|
- Sites with thousands of pages (consider static generators)
|
|
|
|
## Getting Help
|
|
|
|
### Documentation
|
|
|
|
- Follow the [Tutorial](tutorial/00-getting-started.md) step-by-step
|
|
- Check [How-To Guides](how-to/) for specific tasks
|
|
- Consult [Reference](reference/) for technical details
|
|
- Read [Explanation](explanation/) for concepts
|
|
|
|
### Common Issues
|
|
|
|
**Styles not loading**: Hard refresh (Ctrl+Shift+R or Cmd+Shift+R)
|
|
|
|
**404 errors**: Check folder exists and has content files
|
|
|
|
**Language not working**: Ensure language is in `available` config
|
|
|
|
**Metadata not appearing**: Verify INI syntax with `parse_ini_file()`
|
|
|
|
**Templates not found**: Check file exists in `/custom/templates/`
|
|
|
|
## Contributing
|
|
|
|
FolderWeb prioritizes stability and simplicity. Contributions should:
|
|
- Maintain simplicity
|
|
- Avoid dependencies
|
|
- Solve real problems
|
|
- Be maintainable long-term
|
|
|
|
## License
|
|
|
|
Check the project repository for license information.
|
|
|
|
## Next Steps
|
|
|
|
1. **New user?** Start with the [Getting Started Tutorial](tutorial/00-getting-started.md)
|
|
2. **Need to do something specific?** Browse [How-To Guides](how-to/)
|
|
3. **Want technical details?** Explore [Reference Documentation](reference/)
|
|
4. **Curious about design?** Read [Philosophy](explanation/philosophy.md) and [Architecture](explanation/architecture.md)
|
|
|
|
---
|
|
|
|
**FolderWeb**: Simple, file-based content publishing for the long term.
|