46c00c7729
Migrate all 17 docs/content/ files from --- YAML to +++ TOML frontmatter delimiters and key = value syntax. Update 8 embedded frontmatter examples in 7 documentation pages to match (configuration, content-organization, getting-started, security, sections, sitemap, feeds, templates). Update configuration.md frontmatter reference table: add draft and aliases fields, correct date type from string to date.
106 lines
3.4 KiB
Markdown
106 lines
3.4 KiB
Markdown
+++
|
|
title = "Tera Templates"
|
|
description = "Customizable templates without recompilation"
|
|
weight = 1
|
|
+++
|
|
|
|
sukr uses [Tera](https://keats.github.io/tera/), a Jinja2-like templating engine. Templates are loaded at runtime, so you can modify them without recompiling sukr. See the [Tera documentation](https://keats.github.io/tera/docs/) for template authoring syntax (filters, blocks, inheritance).
|
|
|
|
## Template Directory Structure
|
|
|
|
```text
|
|
templates/
|
|
├── base.html # Shared layout (required)
|
|
├── page.html # Standalone pages
|
|
├── homepage.html # Site homepage
|
|
├── section/
|
|
│ ├── default.html # Fallback section index
|
|
│ ├── blog.html # Blog section index
|
|
│ └── projects.html # Projects section index
|
|
└── content/
|
|
├── default.html # Fallback content page
|
|
└── post.html # Blog post
|
|
```
|
|
|
|
## Template Inheritance
|
|
|
|
All templates extend `base.html`:
|
|
|
|
```html
|
|
{% extends "base.html" %} {% block content %}
|
|
<article>
|
|
<h1>{{ page.title }}</h1>
|
|
{{ content | safe }}
|
|
</article>
|
|
{% endblock content %}
|
|
```
|
|
|
|
## Available Context Variables
|
|
|
|
### All Templates
|
|
|
|
| Variable | Description |
|
|
| ------------------- | ----------------------------------- |
|
|
| `config.title` | Site title |
|
|
| `config.author` | Site author |
|
|
| `config.nested_nav` | Whether hierarchical nav is enabled |
|
|
| `nav` | Array of navigation items |
|
|
| `page_path` | Current page path |
|
|
| `prefix` | Relative path prefix for assets |
|
|
| `base_url` | Canonical base URL |
|
|
| `title` | Current page title |
|
|
|
|
Each nav item has:
|
|
|
|
- `label` — Display text
|
|
- `path` — URL path
|
|
- `weight` — Sort order
|
|
- `children` — Child nav items (when `nested_nav` is true)
|
|
|
|
### Page Templates
|
|
|
|
| Variable | Description |
|
|
| ------------------ | ------------------------------------ |
|
|
| `page.title` | Page title |
|
|
| `page.description` | Page description |
|
|
| `page.toc` | Whether TOC is enabled for this page |
|
|
| `content` | Rendered HTML content |
|
|
| `anchors` | Array of heading anchors for TOC |
|
|
|
|
Each anchor in `anchors` has:
|
|
|
|
- `id` — Heading slug (for `href="#id"`)
|
|
- `label` — Heading text
|
|
- `level` — Heading level (2-6, h1 excluded)
|
|
|
|
### Section Templates
|
|
|
|
| Variable | Description |
|
|
| --------------------- | --------------------------------- |
|
|
| `section.title` | Section title |
|
|
| `section.description` | Section description |
|
|
| `items` | Array of content items in section |
|
|
|
|
### Content Item Fields (in `items`)
|
|
|
|
| Variable | Description |
|
|
| ------------------ | ------------------- |
|
|
| `item.title` | Content title |
|
|
| `item.description` | Content description |
|
|
| `item.date` | Publication date |
|
|
| `item.path` | URL path |
|
|
| `item.slug` | URL slug |
|
|
|
|
## Template Override
|
|
|
|
Set `template` in frontmatter to use a custom template:
|
|
|
|
```toml
|
|
+++
|
|
title = "Special Page"
|
|
template = "special"
|
|
+++
|
|
```
|
|
|
|
This uses `templates/content/special.html` instead of the default.
|