folderweb/docs/index.md

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