folderweb/docs/README.md

# FolderWeb Documentation

Welcome to the FolderWeb documentation! This comprehensive guide covers everything you need to know about building and maintaining websites with FolderWeb.

## 📚 Documentation Organization

This documentation follows the [Diataxis framework](https://diataxis.fr/), organizing content into four distinct types to help you find exactly what you need:

### 🎓 Tutorial (Learning-Oriented)

**Purpose**: Learn by doing  
**For**: Newcomers to FolderWeb

- **[Getting Started](tutorial/00-getting-started.md)** - Build your first FolderWeb site from scratch in 10 minutes

Start here if you're new to FolderWeb. This hands-on tutorial walks you through creating a complete website with pages, blog posts, and custom styling.

### 📋 How-To Guides (Task-Oriented)

**Purpose**: Solve specific problems  
**For**: Users with a specific goal

- **[Custom Templates](how-to/custom-templates.md)** - Override default templates with your own designs
- **[Custom Styles](how-to/custom-styles.md)** - Customize appearance using CSS
- **[Multi-Language Sites](how-to/multi-language.md)** - Set up and manage multiple languages
- **[Working with Metadata](how-to/working-with-metadata.md)** - Control content with metadata.ini files

Use these guides when you know what you want to accomplish and need step-by-step instructions.

### 📖 Reference (Information-Oriented)

**Purpose**: Look up technical details  
**For**: Users who need precise information

- **[File Structure](reference/file-structure.md)** - Complete directory layout and file conventions
- **[Metadata](reference/metadata.md)** - All available metadata fields and their usage
- **[Templates](reference/templates.md)** - Template types and available variables
- **[Configuration](reference/configuration.md)** - Configuration options and format
- **[CSS Variables](reference/css-variables.md)** - All CSS custom properties for styling

Consult these documents when you need to look up specific technical details or API information.

### 💡 Explanation (Understanding-Oriented)

**Purpose**: Understand concepts and design decisions  
**For**: Users who want to understand the "why"

- **[Philosophy](explanation/philosophy.md)** - Design principles and thinking behind FolderWeb
- **[Architecture](explanation/architecture.md)** - How FolderWeb works under the hood

Read these to gain deeper understanding of FolderWeb's design and architecture.

## 🚀 Quick Start

```bash
# 1. Create project directory
mkdir my-website && cd my-website

# 2. Copy framework files
cp -r /path/to/folderweb/app ./app

# 3. Create your first page
mkdir content
echo "# Welcome" > content/index.md

# 4. Start development server
php -S localhost:8000 -t . app/router.php

# 5. Open http://localhost:8000
```

**Next**: Follow the complete [Getting Started Tutorial](tutorial/00-getting-started.md)

## 🎯 Common Tasks

Quick links to frequently needed guides:

| Task | Guide |
|------|-------|
| Create a custom template | [Custom Templates](how-to/custom-templates.md) |
| Change colors and fonts | [Custom Styles](how-to/custom-styles.md) |
| Add multiple languages | [Multi-Language Sites](how-to/multi-language.md) |
| Configure page metadata | [Working with Metadata](how-to/working-with-metadata.md) |
| Look up all metadata fields | [Metadata Reference](reference/metadata.md) |
| Find template variables | [Templates Reference](reference/templates.md) |
| Understand file organization | [File Structure Reference](reference/file-structure.md) |

## 💡 Key Concepts

- **File-based routing**: Your folder structure defines your URL structure
- **Template fallback**: Custom templates automatically override defaults
- **Content types**: Single-file pages, multi-file pages, or list views
- **Language support**: Built-in multi-language with URL prefixes
- **Metadata control**: Configure behavior with simple INI files
- **No build process**: Save and refresh - see changes immediately

## 📋 Requirements

- **PHP**: 8.4 or higher
- **Web server**: Apache, Nginx, or PHP's built-in server
- **Extensions**: Standard PHP (no special extensions required)

## 🗂️ Documentation Files

### Complete File List

```
docs/
├── README.md                           # This file
├── index.md                            # Documentation homepage
│
├── tutorial/
│   └── 00-getting-started.md          # Step-by-step tutorial
│
├── how-to/
│   ├── custom-templates.md            # Override templates
│   ├── custom-styles.md               # Customize CSS
│   ├── multi-language.md              # Multi-language setup
│   └── working-with-metadata.md       # Metadata usage
│
├── reference/
│   ├── file-structure.md              # Directory layout
│   ├── metadata.md                    # Metadata fields
│   ├── templates.md                   # Template reference
│   ├── configuration.md               # Config options
│   └── css-variables.md               # CSS customization
│
└── explanation/
    ├── philosophy.md                  # Design principles
    └── architecture.md                # Technical architecture
```

## 📖 Reading Paths

Choose your path based on your needs:

### Path 1: Complete Beginner

1. [Getting Started Tutorial](tutorial/00-getting-started.md)
2. [Custom Styles](how-to/custom-styles.md)
3. [Working with Metadata](how-to/working-with-metadata.md)
4. [Philosophy](explanation/philosophy.md)

### Path 2: Experienced Developer

1. [Philosophy](explanation/philosophy.md)
2. [Architecture](explanation/architecture.md)
3. [File Structure Reference](reference/file-structure.md)
4. Browse How-To Guides as needed

### Path 3: Specific Task

1. Find your task in [How-To Guides](how-to/)
2. Consult [Reference](reference/) for details
3. Return to task completion

## 🤔 Getting Help

### Documentation Not Enough?

1. **Check the code**: FolderWeb is deliberately simple - reading the source is encouraged
2. **Review examples**: Look at the demo content in `/app/default/content/`
3. **Test locally**: Experiment with a test site to understand behavior

### Common Issues

| Problem | Solution |
|---------|----------|
| Styles not loading | Hard refresh browser (Ctrl+Shift+R) |
| 404 errors | Verify folder exists with content files |
| Language not working | Check `available` in config.ini |
| Metadata not showing | Validate INI syntax with PHP parser |
| Custom template ignored | Ensure file is in `/custom/templates/` |

## 🌟 Philosophy Highlights

FolderWeb embraces:

- **Simplicity**: Just enough, nothing more
- **Longevity**: Works today, works in 2035
- **Transparency**: Readable code, clear behavior
- **Files**: Your content, fully portable
- **No build**: Save and refresh workflow

Read the complete [Philosophy](explanation/philosophy.md) to understand FolderWeb's design principles.

## 📝 Contributing to Documentation

Documentation improvements are welcome:

- Fix typos or unclear explanations
- Add missing examples
- Improve existing guides
- Suggest new how-to guides

Keep documentation:
- Clear and concise
- Accurate and tested
- Organized according to Diataxis principles

## 🔗 External Resources

- [Diataxis Framework](https://diataxis.fr/) - Documentation organization system
- [PHP 8.4 Documentation](https://www.php.net/manual/en/) - PHP reference
- [Markdown Guide](https://www.markdownguide.org/) - Markdown syntax
- [MDN Web Docs](https://developer.mozilla.org/) - HTML and CSS reference

---

**Start here**: [Getting Started Tutorial](tutorial/00-getting-started.md)  
**Main index**: [Documentation Index](index.md)