docs: migrate content files to TOML frontmatter
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
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: sukr
|
||||
description: Minimal static site compiler — suckless, Rust, zero JS
|
||||
---
|
||||
+++
|
||||
title = "sukr"
|
||||
description = "Minimal static site compiler — suckless, Rust, zero JS"
|
||||
+++
|
||||
|
||||
# sukr
|
||||
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
title: "Architecture"
|
||||
description: "How sukr transforms markdown into zero-JS static sites"
|
||||
weight: 5
|
||||
toc: true
|
||||
---
|
||||
+++
|
||||
title = "Architecture"
|
||||
description = "How sukr transforms markdown into zero-JS static sites"
|
||||
weight = 5
|
||||
toc = true
|
||||
+++
|
||||
|
||||
sukr is a 13-module static site compiler. Every feature that would typically require client-side JavaScript is moved to build-time.
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
title: "Comparison"
|
||||
description: "How sukr compares to other static site generators"
|
||||
weight: 10
|
||||
---
|
||||
+++
|
||||
title = "Comparison"
|
||||
description = "How sukr compares to other static site generators"
|
||||
weight = 10
|
||||
+++
|
||||
|
||||
This page provides a factual comparison of sukr with other popular static site generators.
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
title: Configuration
|
||||
description: Complete reference for site.toml configuration
|
||||
weight: 3
|
||||
---
|
||||
+++
|
||||
title = "Configuration"
|
||||
description = "Complete reference for site.toml configuration"
|
||||
weight = 3
|
||||
+++
|
||||
|
||||
sukr is configured via `site.toml`. All settings have sensible defaults.
|
||||
|
||||
@@ -70,29 +70,32 @@ sukr -h, --help # Show help
|
||||
|
||||
## Frontmatter
|
||||
|
||||
Each Markdown file can have YAML frontmatter:
|
||||
Each Markdown file can have TOML frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: Page Title
|
||||
description: Optional description
|
||||
date: 2024-01-15 # For blog posts
|
||||
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)
|
||||
---
|
||||
```toml
|
||||
+++
|
||||
title = "Page Title"
|
||||
description = "Optional description"
|
||||
date = 2024-01-15 # For blog posts (native TOML date)
|
||||
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)
|
||||
tags = ["rust", "tutorial"] # Tags for categorization
|
||||
draft = true # Exclude from output
|
||||
aliases = ["/old/path"] # Redirect old URLs here
|
||||
+++
|
||||
```
|
||||
|
||||
### Frontmatter Fields
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
| -------------- | ------- | -------------- | ---------------------------------------------- |
|
||||
| -------------- | ------- | -------------- | ----------------------------------------------- |
|
||||
| `title` | string | _(required)_ | Page title |
|
||||
| `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) |
|
||||
| `nav_label` | string | title | Override navigation label |
|
||||
| `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 |
|
||||
| `link_to` | string | _(none)_ | External URL (renders as link instead of page) |
|
||||
| `tags` | list | `[]` | Tags for categorization |
|
||||
| `draft` | boolean | `false` | Exclude content from output |
|
||||
| `aliases` | list | `[]` | Old URL paths that redirect here |
|
||||
|
||||
### Section Types
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
title: Content Organization
|
||||
description: How the filesystem maps to your site structure
|
||||
weight: 2
|
||||
---
|
||||
+++
|
||||
title = "Content Organization"
|
||||
description = "How the filesystem maps to your site structure"
|
||||
weight = 2
|
||||
+++
|
||||
|
||||
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:
|
||||
|
||||
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`
|
||||
|
||||
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.
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: Blog
|
||||
weight: 10 # Appears before items with weight > 10
|
||||
---
|
||||
```toml
|
||||
+++
|
||||
title = "Blog"
|
||||
weight = 10 # Appears before items with weight > 10
|
||||
+++
|
||||
```
|
||||
|
||||
### Hierarchical Navigation
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
title: Deployment
|
||||
description: Deploy your sukr site to any static hosting platform
|
||||
weight: 1
|
||||
---
|
||||
+++
|
||||
title = "Deployment"
|
||||
description = "Deploy your sukr site to any static hosting platform"
|
||||
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.
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
title: Features
|
||||
description: Explore sukr's capabilities
|
||||
section_type: features
|
||||
weight: 3
|
||||
---
|
||||
+++
|
||||
title = "Features"
|
||||
description = "Explore sukr's capabilities"
|
||||
section_type = "features"
|
||||
weight = 3
|
||||
+++
|
||||
|
||||
sukr provides a focused set of features for building fast, minimal static sites.
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
title: CSS Minification
|
||||
description: Automatic CSS optimization at build time
|
||||
weight: 7
|
||||
---
|
||||
+++
|
||||
title = "CSS Minification"
|
||||
description = "Automatic CSS optimization at build time"
|
||||
weight = 7
|
||||
+++
|
||||
|
||||
sukr automatically minifies CSS files in your static directory during the build.
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
title: Atom Feeds
|
||||
description: Build-time feed generation for blog posts
|
||||
weight: 6
|
||||
---
|
||||
+++
|
||||
title = "Atom Feeds"
|
||||
description = "Build-time feed generation for blog posts"
|
||||
weight = 6
|
||||
+++
|
||||
|
||||
sukr generates an Atom 1.0 feed for blog posts at build time.
|
||||
|
||||
@@ -29,7 +29,7 @@ The feed includes:
|
||||
|
||||
## 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.
|
||||
|
||||
@@ -50,11 +50,11 @@ Add a link in your `base.html` template:
|
||||
|
||||
Post dates in frontmatter should use `YYYY-MM-DD` format:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: My Post
|
||||
date: 2024-01-15
|
||||
---
|
||||
```toml
|
||||
+++
|
||||
title = "My Post"
|
||||
date = 2024-01-15
|
||||
+++
|
||||
```
|
||||
|
||||
The feed converts this to RFC 3339 format required by Atom.
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
title: Math Rendering
|
||||
description: Build-time LaTeX math with KaTeX
|
||||
weight: 5
|
||||
---
|
||||
+++
|
||||
title = "Math Rendering"
|
||||
description = "Build-time LaTeX math with KaTeX"
|
||||
weight = 5
|
||||
+++
|
||||
|
||||
sukr renders LaTeX math expressions at build time using KaTeX, producing static HTML and CSS. No client-side JavaScript required.
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
title: Mermaid Diagrams
|
||||
description: Build-time diagram rendering with Mermaid
|
||||
weight: 4
|
||||
---
|
||||
+++
|
||||
title = "Mermaid Diagrams"
|
||||
description = "Build-time diagram rendering with Mermaid"
|
||||
weight = 4
|
||||
+++
|
||||
|
||||
sukr renders Mermaid diagrams at build time, producing inline SVG. No client-side JavaScript required.
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
title: Sections
|
||||
description: Section types, frontmatter, and template dispatch reference
|
||||
weight: 2
|
||||
---
|
||||
+++
|
||||
title = "Sections"
|
||||
description = "Section types, frontmatter, and template dispatch reference"
|
||||
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).
|
||||
|
||||
@@ -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:
|
||||
|
||||
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`
|
||||
|
||||
### Built-in Section Types
|
||||
@@ -25,13 +25,13 @@ The section type determines which template is used. It resolves in order:
|
||||
|
||||
In `_index.md`:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: My Blog
|
||||
description: Thoughts and tutorials
|
||||
section_type: blog # Optional, defaults to directory name
|
||||
weight: 1 # Nav order
|
||||
---
|
||||
```toml
|
||||
+++
|
||||
title = "My Blog"
|
||||
description = "Thoughts and tutorials"
|
||||
section_type = "blog" # Optional, defaults to directory name
|
||||
weight = 1 # Nav order
|
||||
+++
|
||||
```
|
||||
|
||||
## Adding a New Section
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
title: Sitemap
|
||||
description: Automatic XML sitemap generation for SEO
|
||||
weight: 7
|
||||
---
|
||||
+++
|
||||
title = "Sitemap"
|
||||
description = "Automatic XML sitemap generation for SEO"
|
||||
weight = 7
|
||||
+++
|
||||
|
||||
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>`:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: My Post
|
||||
date: 2024-01-15
|
||||
---
|
||||
```toml
|
||||
+++
|
||||
title = "My Post"
|
||||
date = 2024-01-15
|
||||
+++
|
||||
```
|
||||
|
||||
Content without dates omits the `<lastmod>` element.
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
title: Syntax Highlighting
|
||||
description: Build-time code highlighting with Tree-sitter and tree-house
|
||||
weight: 3
|
||||
---
|
||||
+++
|
||||
title = "Syntax Highlighting"
|
||||
description = "Build-time code highlighting with Tree-sitter and tree-house"
|
||||
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.
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
title: Tera Templates
|
||||
description: Customizable templates without recompilation
|
||||
weight: 1
|
||||
---
|
||||
+++
|
||||
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).
|
||||
|
||||
@@ -95,11 +95,11 @@ Each anchor in `anchors` has:
|
||||
|
||||
Set `template` in frontmatter to use a custom template:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: Special Page
|
||||
template: special
|
||||
---
|
||||
```toml
|
||||
+++
|
||||
title = "Special Page"
|
||||
template = "special"
|
||||
+++
|
||||
```
|
||||
|
||||
This uses `templates/content/special.html` instead of the default.
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
title: Getting Started
|
||||
description: Install sukr and build your first site
|
||||
weight: 0
|
||||
---
|
||||
+++
|
||||
title = "Getting Started"
|
||||
description = "Install sukr and build your first site"
|
||||
weight = 0
|
||||
+++
|
||||
|
||||
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`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: Welcome
|
||||
description: My awesome site
|
||||
---
|
||||
+++
|
||||
title = "Welcome"
|
||||
description = "My awesome site"
|
||||
+++
|
||||
|
||||
# Hello, World!
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
title: Security
|
||||
description: Content trust model and deployment security guidance
|
||||
weight: 90
|
||||
---
|
||||
+++
|
||||
title = "Security"
|
||||
description = "Content trust model and deployment security guidance"
|
||||
weight = 90
|
||||
+++
|
||||
|
||||
# Security
|
||||
|
||||
@@ -13,7 +13,7 @@ sukr is a **build-time only** compiler with no runtime attack surface. Security
|
||||
| Source | Trust Level | Rationale |
|
||||
| :------------------- | :--------------- | :--------------------------------------------------- |
|
||||
| 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 |
|
||||
| sukr binary | **Trusted** | Compiled from audited Rust code |
|
||||
| Tree-sitter grammars | **Trusted** | Compiled into the binary |
|
||||
|
||||
@@ -100,8 +100,8 @@ Items validated by codebase investigation:
|
||||
- [x] Update `extract_frontmatter()` to detect `+++` delimiters instead of `---`
|
||||
- [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)
|
||||
- [ ] Migrate all 17 content files from YAML (`---`) to TOML (`+++`) frontmatter
|
||||
- [ ] Update embedded frontmatter examples in documentation pages (7 files)
|
||||
- [x] Migrate all 17 content files from YAML (`---`) to TOML (`+++`) frontmatter
|
||||
- [x] Update embedded frontmatter examples in documentation pages (7 files)
|
||||
- [ ] Add `FeedConfig` and `SitemapConfig` structs to `config.rs` with `enabled: bool` (default `true`)
|
||||
- [ ] Wire feed/sitemap config into `SiteConfig` deserialization
|
||||
- [ ] 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`
|
||||
- [ ] 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`
|
||||
- [ ] 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
|
||||
- [ ] Verify all 69 existing tests pass (updated for TOML)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user