servius/sukr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: document navigation, TOC, and template context

Browse Source 
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
This commit is contained in:
Timothy DeHerrera
2026-02-01 11:00:20 -07:00
parent 3d5682c59f
commit f38303b7e0
3 changed files with 82 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
docs/content/configuration.md
View File

@@ -40,6 +40,25 @@ sukr -c sites/blog/site.toml
# Paths resolve relative to sites/blog/
```
## Navigation Configuration
Control how navigation menus are generated:
```toml
[nav]
nested = false # Show child pages under sections
toc = false # Enable table of contents globally
```
| Field | Default | Description |
| -------- | ------- | --------------------------------------------------- |
| `nested` | `false` | Display section children as nested sub-menus |
| `toc` | `false` | Show heading anchors in sidebar (table of contents) |
When `nested = true`, section pages appear as indented sub-items under their parent section. When `toc = true`, h2-h6 headings are extracted and displayed as anchor links in the sidebar.
Both settings can be overridden per-page via frontmatter.
## CLI Options
```bash
@@ -62,9 +81,26 @@ weight: 10 # Sort order (lower = first)
nav_label: Short Name # Override nav display
section_type: blog # Override section template
template: custom # Override page template
toc: true # Override global TOC setting
link_to: https://... # External link (for project cards)
---
```
### Frontmatter Fields
| Field | Type | Description |
| -------------- | ------- | ---------------------------------------------- |
| `title` | string | Page title (required) |
| `description` | string | Meta description |
| `date` | string | Publication date (YYYY-MM-DD) |
| `weight` | integer | Sort order (lower = first, default 50) |
| `nav_label` | string | Override navigation label (defaults to title) |
| `section_type` | string | Template dispatch (e.g., "blog", "projects") |
| `template` | string | Custom template path |
| `toc` | boolean | Enable/disable table of contents for this page |
| `link_to` | string | External URL (renders as link instead of page) |
| `tags` | list | Tags for categorization |
### Section Types
The `section_type` field determines which template is used for section indexes:

16
docs/content/content-organization.md
View File

@@ -58,6 +58,22 @@ weight: 10 # Appears before items with weight > 10
---
```
### Hierarchical Navigation
When `nav.nested = true` in your config, section children appear as nested sub-items:
```text
Features ← Section link
├─ Templates ← Child page
├─ Sections ← Child page
└─ Highlighting ← Child page
Getting Started ← Top-level page
```
Child pages inherit their parent section's position in the nav tree. Within a section, children sort by weight then alphabetically.
Without nested navigation (the default), only top-level items appear in the nav.
## URL Examples
| Source Path | Output Path | URL |

44
docs/content/features/templates.md
View File

@@ -39,23 +39,39 @@ All templates extend `base.html`:
### All Templates
| Variable | Description |
| --------------- | ------------------------------- |
| `config.title` | Site title |
| `config.author` | Site author |
| `nav` | Navigation items |
| `page_path` | Current page path |
| `prefix` | Relative path prefix for assets |
| `base_url` | Canonical base URL |
| `title` | Current page title |
| 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 |
| `content` | Rendered HTML content |
| 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