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:

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:

: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:

@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:

; 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
// /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 for content formatting