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](01-getting-started/index.md)** — Installation and quick start guide
2. **[Adding Content](02-tutorial/01-adding-content.md)** — Learn how to create pages
3. **[Styling Your Site](02-tutorial/02-styling.md)** — Customize the design
4. **[Working with Templates](02-tutorial/03-templates.md)** — Control presentation

### Building a Site?

Practical guides for common tasks:

- **[Tutorial: Adding Content](02-tutorial/01-adding-content.md)** — Files, folders, metadata
- **[Tutorial: Styling](02-tutorial/02-styling.md)** — Modern CSS techniques
- **[Tutorial: Templates](02-tutorial/03-templates.md)** — Page and list layouts

### Need a Reference?

Look up specific features and options:

- **[Configuration](03-reference/01-configuration.md)** — Config file options
- **[Metadata](03-reference/02-metadata.md)** — Page and directory metadata
- **[Template Variables](03-reference/03-template-variables.md)** — Available template variables
- **[Internationalization](03-reference/04-internationalization.md)** — Multilingual setup

### Extending FolderWeb?

Advanced guides for developers:

- **[Plugin System](04-development/01-plugin-system.md)** — Create plugins with hooks
- **[Creating Templates](04-development/02-creating-templates.md)** — 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:

```ini
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:

```php
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](02-tutorial/01-adding-content.md)

**...change the design**  
→ Edit `custom/styles/base.css`  
→ See [Styling Your Site](02-tutorial/02-styling.md)

**...customize the layout**  
→ Copy and edit templates in `custom/templates/`  
→ See [Working with Templates](02-tutorial/03-templates.md)

**...add a blog**  
→ Create `content/blog/` with dated subfolders  
→ See [Adding Content](02-tutorial/01-adding-content.md)

**...translate my site**  
→ Enable the languages plugin and create language files  
→ See [Internationalization](03-reference/04-internationalization.md)

**...add custom functionality**  
→ Create a plugin in `custom/plugins/global/`  
→ See [Plugin System](04-development/01-plugin-system.md)

**...add pages to the menu**  
→ Set `menu = 1` in `metadata.ini`  
→ See [Metadata Reference](03-reference/02-metadata.md)

**...use a different list layout**  
→ Set `page_template = "list-grid"` in `metadata.ini`  
→ See [Template Variables](03-reference/03-template-variables.md)

## 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](01-getting-started/index.md) 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](01-getting-started/index.md) to install FolderWeb and create your first page.

Or jump straight to:
- **[Tutorial: Adding Content](02-tutorial/01-adding-content.md)** — Learn the basics
- **[Configuration Reference](03-reference/01-configuration.md)** — Dive into details
- **[Plugin System](04-development/01-plugin-system.md)** — Extend functionality

---

**FolderWeb** — Just enough web, nothing more.