folderweb/app/default/content/articles/2025-10-28-templates-and-customization/article.md

# 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