f38303b7e0
Add comprehensive documentation for recently implemented features: - [nav] config section (nested, toc toggles) - Complete frontmatter fields reference (10 fields) - Hierarchical navigation behavior with ASCII diagram - Template context: nested_nav, anchors array, page.toc - Nav item structure including children for nested menus
106 lines
3.3 KiB
Markdown
106 lines
3.3 KiB
Markdown
---
|
|
title: Tera Templates
|
|
description: Customizable templates without recompilation
|
|
weight: 1
|
|
---
|
|
|
|
sukr uses [Tera](https://tera.netlify.app/), a Jinja2-like templating engine. Templates are loaded at runtime, so you can modify them without recompiling sukr.
|
|
|
|
## 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:
|
|
|
|
```yaml
|
|
---
|
|
title: Special Page
|
|
template: special
|
|
---
|
|
```
|
|
|
|
This uses `templates/page/special.html` instead of the default.
|