2025-11-02 13:46:47 +01:00

8.4 KiB

Raw Blame History

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, organizing content into four types:

🎓 Tutorial

Learning-oriented: Get started with FolderWeb

Getting Started - 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 - Override default templates
Custom Styles - Customize appearance with CSS
Multi-Language Sites - Set up multiple languages
Working with Metadata - Use metadata.ini files

Use these when you need to accomplish a specific task.

📖 Reference

Information-oriented: Look up technical details

File Structure - Complete directory layout
Metadata - All metadata fields
Templates - Template variables and usage
Configuration - Configuration options
CSS Variables - Styling customization

Consult these when you need precise technical information.

💡 Explanation

Understanding-oriented: Understand concepts and design

Philosophy - Design principles and thinking
Architecture - 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

# 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:

[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:

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 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 step-by-step
Check How-To Guides for specific tasks
Consult Reference for technical details
Read 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

New user? Start with the Getting Started Tutorial
Need to do something specific? Browse How-To Guides
Want technical details? Explore Reference Documentation
Curious about design? Read Philosophy and Architecture

FolderWeb: Simple, file-based content publishing for the long term.

8.4 KiB Raw Blame History