Create a simple hero section with title, subtitle, and call-to-action
button Add a features section with icons and descriptions Include a stats section with live data Add a responsive design with modern CSS features
This commit is contained in:
Ruben
parent
f0d50ff8bf
commit
0e19040473
101 changed files with 1356 additions and 7532 deletions
309
docs/index.md
309
docs/index.md
|
|
@ -1,309 +0,0 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue