211 lines
7.5 KiB
Markdown
211 lines
7.5 KiB
Markdown
# 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)
|