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

docs: migrate content files to TOML frontmatter

Browse Source 
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.
This commit is contained in:
Timothy DeHerrera
2026-02-14 06:57:55 -07:00
parent 16fed12273
commit 46c00c7729
18 changed files with 154 additions and 149 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/content/_index.md
View File

@@ -1,7 +1,7 @@
--- +++
title: sukr title = "sukr"
description: Minimal static site compiler — suckless, Rust, zero JS description = "Minimal static site compiler — suckless, Rust, zero JS"
--- +++
# sukr # sukr

12
docs/content/architecture.md
View File

@@ -1,9 +1,9 @@
--- +++
title: "Architecture" title = "Architecture"
description: "How sukr transforms markdown into zero-JS static sites" description = "How sukr transforms markdown into zero-JS static sites"
weight: 5 weight = 5
toc: true toc = true
--- +++
sukr is a 13-module static site compiler. Every feature that would typically require client-side JavaScript is moved to build-time. sukr is a 13-module static site compiler. Every feature that would typically require client-side JavaScript is moved to build-time.

10
docs/content/comparison.md
View File

@@ -1,8 +1,8 @@
--- +++
title: "Comparison" title = "Comparison"
description: "How sukr compares to other static site generators" description = "How sukr compares to other static site generators"
weight: 10 weight = 10
--- +++
This page provides a factual comparison of sukr with other popular static site generators. This page provides a factual comparison of sukr with other popular static site generators.

45
docs/content/configuration.md
View File

@@ -1,8 +1,8 @@
--- +++
title: Configuration title = "Configuration"
description: Complete reference for site.toml configuration description = "Complete reference for site.toml configuration"
weight: 3 weight = 3
--- +++
sukr is configured via `site.toml`. All settings have sensible defaults. sukr is configured via `site.toml`. All settings have sensible defaults.
@@ -70,29 +70,32 @@ sukr -h, --help # Show help
## Frontmatter ## Frontmatter
Each Markdown file can have YAML frontmatter: Each Markdown file can have TOML frontmatter:
```yaml ```toml
--- +++
title: Page Title title = "Page Title"
description: Optional description description = "Optional description"
date: 2024-01-15 # For blog posts date = 2024-01-15 # For blog posts (native TOML date)
weight: 10 # Sort order (lower = first) weight = 10 # Sort order (lower = first)
nav_label: Short Name # Override nav display nav_label = "Short Name" # Override nav display
section_type: blog # Override section template section_type = "blog" # Override section template
template: custom # Override page template template = "custom" # Override page template
toc: true # Override global TOC setting toc = true # Override global TOC setting
link_to: https://... # External link (for project cards) link_to = "https://..." # External link (for project cards)
--- tags = ["rust", "tutorial"] # Tags for categorization
draft = true # Exclude from output
aliases = ["/old/path"] # Redirect old URLs here
+++
``` ```
### Frontmatter Fields ### Frontmatter Fields
| Field | Type | Default | Description | | Field | Type | Default | Description |
| -------------- | ------- | -------------- | ---------------------------------------------- | | -------------- | ------- | -------------- | ----------------------------------------------- |
| `title` | string | _(required)_ | Page title | | `title` | string | _(required)_ | Page title |
| `description` | string | _(none)_ | Meta description | | `description` | string | _(none)_ | Meta description |
| `date` | string | _(none)_ | Publication date (YYYY-MM-DD) | | `date` | date | _(none)_ | Publication date (YYYY-MM-DD, native TOML date) |
| `weight` | integer | `50` | Sort order (lower = first) | | `weight` | integer | `50` | Sort order (lower = first) |
| `nav_label` | string | title | Override navigation label | | `nav_label` | string | title | Override navigation label |
| `section_type` | string | directory name | Template dispatch (e.g., "blog", "projects") | | `section_type` | string | directory name | Template dispatch (e.g., "blog", "projects") |
@@ -100,6 +103,8 @@ link_to: https://... # External link (for project cards)
| `toc` | boolean | global setting | Enable/disable table of contents for this page | | `toc` | boolean | global setting | Enable/disable table of contents for this page |
| `link_to` | string | _(none)_ | External URL (renders as link instead of page) | | `link_to` | string | _(none)_ | External URL (renders as link instead of page) |
| `tags` | list | `[]` | Tags for categorization | | `tags` | list | `[]` | Tags for categorization |
| `draft` | boolean | `false` | Exclude content from output |
| `aliases` | list | `[]` | Old URL paths that redirect here |
### Section Types ### Section Types

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

@@ -1,8 +1,8 @@
--- +++
title: Content Organization title = "Content Organization"
description: How the filesystem maps to your site structure description = "How the filesystem maps to your site structure"
weight: 2 weight = 2
--- +++
sukr builds your site structure from your `content/` directory. No routing config needed — the filesystem _is_ the config. sukr builds your site structure from your `content/` directory. No routing config needed — the filesystem _is_ the config.
@@ -53,7 +53,7 @@ sukr automatically discovers sections during the build:
The **section type** determines which template renders the index. It resolves in order: The **section type** determines which template renders the index. It resolves in order:
1. **Frontmatter override** — `section_type: blog` in the section's `_index.md` 1. **Frontmatter override** — `section_type = "blog"` in the section's `_index.md`
2. **Directory name** — `content/blog/` becomes type `blog` 2. **Directory name** — `content/blog/` becomes type `blog`
For the full section type reference (built-in types, frontmatter fields, and template dispatch), see [Sections](features/sections.html). For the full section type reference (built-in types, frontmatter fields, and template dispatch), see [Sections](features/sections.html).
@@ -67,11 +67,11 @@ Navigation builds automatically from:
Items sort by `weight` in frontmatter (lower first), then alphabetically. Items sort by `weight` in frontmatter (lower first), then alphabetically.
```yaml ```toml
--- +++
title: Blog title = "Blog"
weight: 10 # Appears before items with weight > 10 weight = 10 # Appears before items with weight > 10
--- +++
``` ```
### Hierarchical Navigation ### Hierarchical Navigation

10
docs/content/deployment.md
View File

@@ -1,8 +1,8 @@
--- +++
title: Deployment title = "Deployment"
description: Deploy your sukr site to any static hosting platform description = "Deploy your sukr site to any static hosting platform"
weight: 1 weight = 1
--- +++
sukr builds your site to `public/`. This directory contains self-contained static HTML, CSS, and assets — no server-side runtime needed. Upload it anywhere that serves static files. If you haven't built a site yet, start with the [Getting Started](getting-started.html) guide. sukr builds your site to `public/`. This directory contains self-contained static HTML, CSS, and assets — no server-side runtime needed. Upload it anywhere that serves static files. If you haven't built a site yet, start with the [Getting Started](getting-started.html) guide.

12
docs/content/features/_index.md
View File

@@ -1,8 +1,8 @@
--- +++
title: Features title = "Features"
description: Explore sukr's capabilities description = "Explore sukr's capabilities"
section_type: features section_type = "features"
weight: 3 weight = 3
--- +++
sukr provides a focused set of features for building fast, minimal static sites. sukr provides a focused set of features for building fast, minimal static sites.

10
docs/content/features/css.md
View File

@@ -1,8 +1,8 @@
--- +++
title: CSS Minification title = "CSS Minification"
description: Automatic CSS optimization at build time description = "Automatic CSS optimization at build time"
weight: 7 weight = 7
--- +++
sukr automatically minifies CSS files in your static directory during the build. sukr automatically minifies CSS files in your static directory during the build.

22
docs/content/features/feeds.md
View File

@@ -1,8 +1,8 @@
--- +++
title: Atom Feeds title = "Atom Feeds"
description: Build-time feed generation for blog posts description = "Build-time feed generation for blog posts"
weight: 6 weight = 6
--- +++
sukr generates an Atom 1.0 feed for blog posts at build time. sukr generates an Atom 1.0 feed for blog posts at build time.
@@ -29,7 +29,7 @@ The feed includes:
## Auto-generation ## Auto-generation
Feed generation happens automatically when any content exists in a section with `section_type: blog`. No configuration required. Feed generation happens automatically when any content exists in a section with `section_type = "blog"`. No configuration required.
Posts are sorted by date (newest first), matching the blog section ordering. Posts are sorted by date (newest first), matching the blog section ordering.
@@ -50,11 +50,11 @@ Add a link in your `base.html` template:
Post dates in frontmatter should use `YYYY-MM-DD` format: Post dates in frontmatter should use `YYYY-MM-DD` format:
```yaml ```toml
--- +++
title: My Post title = "My Post"
date: 2024-01-15 date = 2024-01-15
--- +++
``` ```
The feed converts this to RFC 3339 format required by Atom. The feed converts this to RFC 3339 format required by Atom.

10
docs/content/features/math.md
View File

@@ -1,8 +1,8 @@
--- +++
title: Math Rendering title = "Math Rendering"
description: Build-time LaTeX math with KaTeX description = "Build-time LaTeX math with KaTeX"
weight: 5 weight = 5
--- +++
sukr renders LaTeX math expressions at build time using KaTeX, producing static HTML and CSS. No client-side JavaScript required. sukr renders LaTeX math expressions at build time using KaTeX, producing static HTML and CSS. No client-side JavaScript required.

10
docs/content/features/mermaid.md
View File

@@ -1,8 +1,8 @@
--- +++
title: Mermaid Diagrams title = "Mermaid Diagrams"
description: Build-time diagram rendering with Mermaid description = "Build-time diagram rendering with Mermaid"
weight: 4 weight = 4
--- +++
sukr renders Mermaid diagrams at build time, producing inline SVG. No client-side JavaScript required. sukr renders Mermaid diagrams at build time, producing inline SVG. No client-side JavaScript required.

26
docs/content/features/sections.md
View File

@@ -1,8 +1,8 @@
--- +++
title: Sections title = "Sections"
description: Section types, frontmatter, and template dispatch reference description = "Section types, frontmatter, and template dispatch reference"
weight: 2 weight = 2
--- +++
sukr discovers sections from your content directory structure. For an explanation of how sections work and how directories map to site structure, see [Content Organization](../content-organization.html). sukr discovers sections from your content directory structure. For an explanation of how sections work and how directories map to site structure, see [Content Organization](../content-organization.html).
@@ -10,7 +10,7 @@ sukr discovers sections from your content directory structure. For an explanatio
The section type determines which template is used. It resolves in order: The section type determines which template is used. It resolves in order:
1. **Frontmatter override**: `section_type: blog` in `_index.md` 1. **Frontmatter override**: `section_type = "blog"` in `_index.md`
2. **Directory name**: `content/blog/` → type `blog` 2. **Directory name**: `content/blog/` → type `blog`
### Built-in Section Types ### Built-in Section Types
@@ -25,13 +25,13 @@ The section type determines which template is used. It resolves in order:
In `_index.md`: In `_index.md`:
```yaml ```toml
--- +++
title: My Blog title = "My Blog"
description: Thoughts and tutorials description = "Thoughts and tutorials"
section_type: blog # Optional, defaults to directory name section_type = "blog" # Optional, defaults to directory name
weight: 1 # Nav order weight = 1 # Nav order
--- +++
``` ```
## Adding a New Section ## Adding a New Section

20
docs/content/features/sitemap.md
View File

@@ -1,8 +1,8 @@
--- +++
title: Sitemap title = "Sitemap"
description: Automatic XML sitemap generation for SEO description = "Automatic XML sitemap generation for SEO"
weight: 7 weight = 7
--- +++
sukr generates an XML sitemap at build time for search engine optimization. sukr generates an XML sitemap at build time for search engine optimization.
@@ -38,11 +38,11 @@ URLs use the `base_url` from `site.toml` to construct absolute URLs as required
If content has a `date` field in frontmatter, it's included as `<lastmod>`: If content has a `date` field in frontmatter, it's included as `<lastmod>`:
```yaml ```toml
--- +++
title: My Post title = "My Post"
date: 2024-01-15 date = 2024-01-15
--- +++
``` ```
Content without dates omits the `<lastmod>` element. Content without dates omits the `<lastmod>` element.

10
docs/content/features/syntax-highlighting.md
View File

@@ -1,8 +1,8 @@
--- +++
title: Syntax Highlighting title = "Syntax Highlighting"
description: Build-time code highlighting with Tree-sitter and tree-house description = "Build-time code highlighting with Tree-sitter and tree-house"
weight: 3 weight = 3
--- +++
sukr highlights code blocks at build time using [tree-house](https://github.com/helix-editor/tree-house) (Helix editor's Tree-sitter integration). No client-side JavaScript required. sukr highlights code blocks at build time using [tree-house](https://github.com/helix-editor/tree-house) (Helix editor's Tree-sitter integration). No client-side JavaScript required.

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

@@ -1,8 +1,8 @@
--- +++
title: Tera Templates title = "Tera Templates"
description: Customizable templates without recompilation description = "Customizable templates without recompilation"
weight: 1 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). 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).
@@ -95,11 +95,11 @@ Each anchor in `anchors` has:
Set `template` in frontmatter to use a custom template: Set `template` in frontmatter to use a custom template:
```yaml ```toml
--- +++
title: Special Page title = "Special Page"
template: special template = "special"
--- +++
``` ```
This uses `templates/content/special.html` instead of the default. This uses `templates/content/special.html` instead of the default.

18
docs/content/getting-started.md
View File

@@ -1,8 +1,8 @@
--- +++
title: Getting Started title = "Getting Started"
description: Install sukr and build your first site description = "Install sukr and build your first site"
weight: 0 weight = 0
--- +++
This guide walks you through installing sukr and creating your first static site. This guide walks you through installing sukr and creating your first static site.
@@ -47,10 +47,10 @@ base_url = "https://example.com"
Create `content/_index.md`: Create `content/_index.md`:
```markdown ```markdown
--- +++
title: Welcome title = "Welcome"
description: My awesome site description = "My awesome site"
--- +++
# Hello, World! # Hello, World!

12
docs/content/security.md
View File

@@ -1,8 +1,8 @@
--- +++
title: Security title = "Security"
description: Content trust model and deployment security guidance description = "Content trust model and deployment security guidance"
weight: 90 weight = 90
--- +++
# Security # Security
@@ -13,7 +13,7 @@ sukr is a **build-time only** compiler with no runtime attack surface. Security
| Source | Trust Level | Rationale | | Source | Trust Level | Rationale |
| :------------------- | :--------------- | :--------------------------------------------------- | | :------------------- | :--------------- | :--------------------------------------------------- |
| Markdown content | **Untrusted** | May come from contributors, CMS, or external sources | | Markdown content | **Untrusted** | May come from contributors, CMS, or external sources |
| YAML frontmatter | **Untrusted** | Parsed from content files | | TOML frontmatter | **Untrusted** | Parsed from content files |
| Templates | **Semi-trusted** | User-controlled but typically from known sources | | Templates | **Semi-trusted** | User-controlled but typically from known sources |
| sukr binary | **Trusted** | Compiled from audited Rust code | | sukr binary | **Trusted** | Compiled from audited Rust code |
| Tree-sitter grammars | **Trusted** | Compiled into the binary | | Tree-sitter grammars | **Trusted** | Compiled into the binary |

6
docs/plans/api-stabilization.md
View File

@@ -100,8 +100,8 @@ Items validated by codebase investigation:
- [x] Update `extract_frontmatter()` to detect `+++` delimiters instead of `---` - [x] Update `extract_frontmatter()` to detect `+++` delimiters instead of `---`
- [x] Add date validation: custom `deserialize_date` fn for TOML native dates → `chrono::NaiveDate` - [x] Add date validation: custom `deserialize_date` fn for TOML native dates → `chrono::NaiveDate`
- [x] Change `tags` from `taxonomies.tags` nesting to flat `tags = ["..."]` (direct TOML array) - [x] Change `tags` from `taxonomies.tags` nesting to flat `tags = ["..."]` (direct TOML array)
- [ ] Migrate all 17 content files from YAML (`---`) to TOML (`+++`) frontmatter - [x] Migrate all 17 content files from YAML (`---`) to TOML (`+++`) frontmatter
- [ ] Update embedded frontmatter examples in documentation pages (7 files) - [x] Update embedded frontmatter examples in documentation pages (7 files)
- [ ] Add `FeedConfig` and `SitemapConfig` structs to `config.rs` with `enabled: bool` (default `true`) - [ ] Add `FeedConfig` and `SitemapConfig` structs to `config.rs` with `enabled: bool` (default `true`)
- [ ] Wire feed/sitemap config into `SiteConfig` deserialization - [ ] Wire feed/sitemap config into `SiteConfig` deserialization
- [ ] Gate feed generation in `main.rs` on `config.feed.enabled` - [ ] Gate feed generation in `main.rs` on `config.feed.enabled`
@@ -111,7 +111,7 @@ Items validated by codebase investigation:
- [ ] Update `docs/templates/base.html`: `config.nested_nav` → `config.nav.nested`, `base_url` → `config.base_url` - [ ] Update `docs/templates/base.html`: `config.nested_nav` → `config.nav.nested`, `base_url` → `config.base_url`
- [ ] Delete `docs/templates/section/features.html` and `docs/templates/homepage.html` - [ ] Delete `docs/templates/section/features.html` and `docs/templates/homepage.html`
- [ ] Add template section fallback in `render_section`: try `section/<type>.html`, fall back to `section/default.html` - [ ] Add template section fallback in `render_section`: try `section/<type>.html`, fall back to `section/default.html`
- [ ] Update/fix all existing tests to use TOML frontmatter - [x] Update/fix all existing tests to use TOML frontmatter
- [ ] Add new tests: TOML parsing, date validation (valid + invalid), feed/sitemap config gating - [ ] Add new tests: TOML parsing, date validation (valid + invalid), feed/sitemap config gating
- [ ] Verify all 69 existing tests pass (updated for TOML) - [ ] Verify all 69 existing tests pass (updated for TOML)