folderweb/docs/index.md

FolderWeb Documentation

Welcome to FolderWeb—a minimal PHP framework that turns your folder structure into a website. No build steps, no databases, no complexity. Just files, folders, and modern web standards.

What is FolderWeb?

FolderWeb is a file-based content management system that:

• Uses your folder structure as URL structure — Drop files in folders, get pages
• Works without JavaScript — Pure PHP and modern CSS
• Requires no build process — Edit, save, refresh. Done.
• Supports multiple languages — Built-in i18n with URL-based language switching
• Stays maintainable — Code designed to last years or decades

Perfect for blogs, documentation sites, portfolios, and small business websites where simplicity and longevity matter.

Quick Navigation

New to FolderWeb?

Start here to get up and running:

1. Getting Started — Installation and quick start guide
2. Adding Content — Learn how to create pages
3. Styling Your Site — Customize the design
4. Working with Templates — Control presentation

Building a Site?

Practical guides for common tasks:

• Tutorial: Adding Content — Files, folders, metadata
• Tutorial: Styling — Modern CSS techniques
• Tutorial: Templates — Page and list layouts

Need a Reference?

Look up specific features and options:

• Configuration — Config file options
• Metadata — Page and directory metadata
• Template Variables — Available template variables
• Internationalization — Multilingual setup

Extending FolderWeb?

Advanced guides for developers:

• Plugin System — Create plugins with hooks
• Creating Templates — Advanced template creation

Core Concepts

File-Based Routing

Your folder structure is your URL structure:

content/
├── about.md              → /about/
├── blog/
│   ├── index.md          → /blog/
│   └── first-post/
│       └── index.md      → /blog/first-post/
└── contact.html          → /contact/

No configuration, no route definitions—just create folders and files.

Content Types

FolderWeb supports three content types:

• Markdown (.md) — Write in Markdown, get HTML
• HTML (.html) — Static HTML content
• PHP (.php) — Dynamic content with PHP

Mix and match as needed. All three can coexist in the same directory.

Template System

Templates control how content is presented:

• Base template — HTML scaffold (header, nav, footer)
• Page template — Wraps single-page content
• List template — Displays collections (blogs, portfolios)

Override defaults by creating custom/templates/.

Metadata Files

Configure pages with metadata.ini files:

title = "My Page"
summary = "Short description"
date = "2024-12-15"
slug = "custom-url"
menu = 1

Control titles, URLs, navigation, templates, and more.

Plugin System

Extend functionality with a simple hook system:

Hooks::add(Hook::TEMPLATE_VARS, function(array $vars, Context $ctx) {
    $vars['customVariable'] = 'value';
    return $vars;
});

Three hooks provide extensibility without complexity.

Philosophy

FolderWeb follows these principles:

Minimalism

Use only what's strictly necessary. No frameworks, no build tools, no package managers for frontend code. If it doesn't provide clear, lasting value, it doesn't belong.

Longevity

Code should be readable and maintainable for years or decades. Avoid rapidly changing components and dependencies. Favor web standards over abstractions.

Simplicity

HTML, PHP, and CSS. That's it. No preprocessing, no transpiling, no complex build pipelines. Edit a file, refresh the browser, see the result.

Performance

Fast page loads, minimal HTTP requests, no JavaScript parsing delay. Performance metrics displayed in the footer—transparency and pride.

Documentation Structure

docs/
├── 01-getting-started/
│   └── index.md                    # Installation and quick start
├── 02-tutorial/
│   ├── 01-adding-content.md        # How to create content
│   ├── 02-styling.md               # Customizing styles
│   └── 03-templates.md             # Working with templates
├── 03-reference/
│   ├── 01-configuration.md         # Config options
│   ├── 02-metadata.md              # Metadata fields
│   ├── 03-template-variables.md    # Available variables
│   └── 04-internationalization.md  # Multilingual setup
└── 04-development/
    ├── 01-plugin-system.md         # Creating plugins
    └── 02-creating-templates.md    # Advanced templates

Common Tasks

I want to...

...add a new page
→ Create a .md, .html, or .php file in content/
→ See Adding Content

...change the design
→ Edit custom/styles/base.css
→ See Styling Your Site

...customize the layout
→ Copy and edit templates in custom/templates/
→ See Working with Templates

...add a blog
→ Create content/blog/ with dated subfolders
→ See Adding Content

...translate my site
→ Enable the languages plugin and create language files
→ See Internationalization

...add custom functionality
→ Create a plugin in custom/plugins/global/
→ See Plugin System

...add pages to the menu
→ Set menu = 1 in metadata.ini
→ See Metadata Reference

...use a different list layout
→ Set page_template = "list-grid" in metadata.ini
→ See Template Variables

Examples

FolderWeb includes extensive examples in app/default/content/examples/:

• Markdown demo — Full Markdown feature showcase
• Cover images — How cover images work
• Metadata examples — All metadata options demonstrated
• Template demos — Grid and compact list layouts
• Multilingual — Language support examples
• Mixed formats — Combining Markdown, HTML, and PHP

Browse the examples to see features in action.

Getting Help

Read the docs:
Start with Getting Started and work through the tutorial.

Check examples:
Look in app/default/content/examples/ for working code.

Review the code:
FolderWeb is intentionally simple. Read the source in app/ to understand how it works.

File an issue:
Found a bug or have a question? Open an issue on GitHub.

Contributing

FolderWeb is open source and welcomes contributions:

• Report bugs — Open an issue with steps to reproduce
• Suggest features — Propose improvements (but remember: minimalism is key)
• Share plugins — Created a useful plugin? Share it with the community
• Improve docs — Found something unclear? Submit a pull request

What's Next?

Ready to build? Start with Getting Started to install FolderWeb and create your first page.

Or jump straight to:

• Tutorial: Adding Content — Learn the basics
• Configuration Reference — Dive into details
• Plugin System — Extend functionality

---

FolderWeb — Just enough web, nothing more.