4c697122ab
Add about page with project philosophy and technical details Add articles about Markdown, templates, and getting started Implement demo content system that shows when no user content exists Update logo to show FolderWeb branding Improve Apache configuration for development environment
165 lines
3.6 KiB
Markdown
165 lines
3.6 KiB
Markdown
# Templates and Customization
|
|
|
|
FolderWeb is built on a simple principle: **never modify defaults, always override**. This guide shows you how to customize your site while keeping it maintainable.
|
|
|
|
## The Override System
|
|
|
|
FolderWeb checks for custom files before falling back to defaults:
|
|
|
|
1. Check `/custom/templates/` → Use custom template
|
|
2. Fall back to `/app/default/templates/` → Use default template
|
|
|
|
This means you can override any part of the system without touching the core files.
|
|
|
|
## Available Templates
|
|
|
|
### Base Template
|
|
The main HTML structure with header, navigation, and footer.
|
|
|
|
**Override**: `/custom/templates/base.php`
|
|
|
|
### Page Template
|
|
Wraps single pages and articles.
|
|
|
|
**Override**: `/custom/templates/page.php`
|
|
|
|
### List Templates
|
|
|
|
FolderWeb includes multiple list view variants:
|
|
|
|
- `list.php` - Simple list
|
|
- `list-grid.php` - Grid layout
|
|
- `list-card-grid.php` - Card grid with images
|
|
- `list-faq.php` - Expandable FAQ format
|
|
|
|
**Select via metadata**:
|
|
|
|
```ini
|
|
page_template = "list-card-grid"
|
|
```
|
|
|
|
## Customizing Styles
|
|
|
|
### Add Your Own CSS
|
|
|
|
Create `/custom/styles/base.css` and it automatically overrides default styles.
|
|
|
|
Example custom stylesheet:
|
|
|
|
```css
|
|
:root {
|
|
--color-primary: oklch(0.5 0.2 270);
|
|
--color-background: oklch(0.98 0 0);
|
|
--font-body: 'Georgia', serif;
|
|
}
|
|
|
|
article h1 {
|
|
color: var(--color-primary);
|
|
font-size: clamp(2rem, 5vw, 3rem);
|
|
}
|
|
```
|
|
|
|
### Modern CSS Features
|
|
|
|
FolderWeb's default styles use modern CSS:
|
|
|
|
- **CSS Nesting** - Scope styles naturally
|
|
- **OKLCH Colors** - Perceptually uniform colors
|
|
- **CSS Grid** - Flexible layouts
|
|
- **Clamp()** - Responsive sizing
|
|
- **Logical Properties** - Better internationalization
|
|
|
|
## Custom Fonts
|
|
|
|
1. Place font files in `/custom/fonts/`
|
|
2. Reference them in your custom CSS:
|
|
|
|
```css
|
|
@font-face {
|
|
font-family: 'MyFont';
|
|
src: url('/fonts/myfont.woff2') format('woff2');
|
|
}
|
|
|
|
body {
|
|
font-family: 'MyFont', sans-serif;
|
|
}
|
|
```
|
|
|
|
## Metadata Options
|
|
|
|
Control content behavior with `metadata.ini` files:
|
|
|
|
```ini
|
|
; Basic fields
|
|
title = "Page Title"
|
|
date = "2025-10-28"
|
|
summary = "Short description"
|
|
|
|
; Navigation
|
|
menu = true
|
|
menu_order = 1
|
|
|
|
; Templates
|
|
page_template = "list-card-grid"
|
|
|
|
; Redirects
|
|
redirect = "https://example.com"
|
|
|
|
; Attachments
|
|
pdf = "document.pdf"
|
|
```
|
|
|
|
## Template Variables
|
|
|
|
Templates have access to specific variables:
|
|
|
|
### Base Template
|
|
- `$content` - Page content
|
|
- `$currentLang` - Current language code
|
|
- `$navigation` - Navigation items array
|
|
- `$pageTitle` - Page title
|
|
|
|
### Page Template
|
|
- `$content` - Article content
|
|
- `$pageMetadata` - Metadata array
|
|
- `$translations` - Translation strings
|
|
|
|
### List Templates
|
|
- `$items` - Array of subitems
|
|
- `$metadata` - Directory metadata
|
|
- `$pageContent` - Intro text
|
|
- `$translations` - Translation strings
|
|
|
|
## Creating a Custom Template
|
|
|
|
Example custom page template:
|
|
|
|
```php
|
|
<?php
|
|
// /custom/templates/page.php
|
|
?>
|
|
<article class="custom-layout">
|
|
<?php if (isset($pageMetadata['date'])): ?>
|
|
<time><?= htmlspecialchars($pageMetadata['date']) ?></time>
|
|
<?php endif; ?>
|
|
|
|
<?= $content ?>
|
|
|
|
<footer>
|
|
<p>Custom footer content</p>
|
|
</footer>
|
|
</article>
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
1. **Never modify `/app/default/`** - Always create overrides in `/custom/`
|
|
2. **Use metadata** - Keep configuration in `metadata.ini` files
|
|
3. **Leverage CSS variables** - Easy theming without rewriting styles
|
|
4. **Keep it simple** - The less custom code, the easier to maintain
|
|
|
|
## Next Steps
|
|
|
|
- Explore default templates in `/app/default/templates/`
|
|
- Study the default CSS in `/app/default/styles/base.css`
|
|
- Check out the [Markdown Guide](/articles/2025-10-15-markdown-guide/) for content formatting
|