folderweb/docs

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, 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 - 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 - Override default templates with your own designs
• Custom Styles - Customize appearance using CSS
• Multi-Language Sites - Set up and manage multiple languages
• Working with Metadata - 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 - Complete directory layout and file conventions
• Metadata - All available metadata fields and their usage
• Templates - Template types and available variables
• Configuration - Configuration options and format
• CSS Variables - 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 - Design principles and thinking behind FolderWeb
• Architecture - How FolderWeb works under the hood

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

🚀 Quick Start

# 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

🎯 Common Tasks

Quick links to frequently needed guides:

Task	Guide
Create a custom template	Custom Templates
Change colors and fonts	Custom Styles
Add multiple languages	Multi-Language Sites
Configure page metadata	Working with Metadata
Look up all metadata fields	Metadata Reference
Find template variables	Templates Reference
Understand file organization	File Structure Reference

💡 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
2. Custom Styles
3. Working with Metadata
4. Philosophy

Path 2: Experienced Developer

1. Philosophy
2. Architecture
3. File Structure Reference
4. Browse How-To Guides as needed

Path 3: Specific Task

1. Find your task in How-To Guides
2. Consult 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 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 - Documentation organization system
• PHP 8.4 Documentation - PHP reference
• Markdown Guide - Markdown syntax
• MDN Web Docs - HTML and CSS reference

---

Start here: Getting Started Tutorial
Main index: Documentation Index