From 46c00c77295f2ab1529979642ac0a49fd6f1b835 Mon Sep 17 00:00:00 2001 From: Timothy DeHerrera Date: Sat, 14 Feb 2026 06:57:55 -0700 Subject: [PATCH] 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. --- docs/content/_index.md | 8 +-- docs/content/architecture.md | 12 ++-- docs/content/comparison.md | 10 +-- docs/content/configuration.md | 65 +++++++++++--------- docs/content/content-organization.md | 22 +++---- docs/content/deployment.md | 10 +-- docs/content/features/_index.md | 12 ++-- docs/content/features/css.md | 10 +-- docs/content/features/feeds.md | 22 +++---- docs/content/features/math.md | 10 +-- docs/content/features/mermaid.md | 10 +-- docs/content/features/sections.md | 26 ++++---- docs/content/features/sitemap.md | 20 +++--- docs/content/features/syntax-highlighting.md | 10 +-- docs/content/features/templates.md | 20 +++--- docs/content/getting-started.md | 18 +++--- docs/content/security.md | 12 ++-- docs/plans/api-stabilization.md | 6 +- 18 files changed, 154 insertions(+), 149 deletions(-) diff --git a/docs/content/_index.md b/docs/content/_index.md index debfb62..6b78426 100644 --- a/docs/content/_index.md +++ b/docs/content/_index.md @@ -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 diff --git a/docs/content/architecture.md b/docs/content/architecture.md index 0681aca..e7ff99f 100644 --- a/docs/content/architecture.md +++ b/docs/content/architecture.md @@ -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. diff --git a/docs/content/comparison.md b/docs/content/comparison.md index 38036f8..8038ac3 100644 --- a/docs/content/comparison.md +++ b/docs/content/comparison.md @@ -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. diff --git a/docs/content/configuration.md b/docs/content/configuration.md index b3f9d8a..80bf780 100644 --- a/docs/content/configuration.md +++ b/docs/content/configuration.md @@ -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,36 +70,41 @@ 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) | -| `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") | -| `template` | string | _(none)_ | Custom template name | -| `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 | +| Field | Type | Default | Description | +| -------------- | ------- | -------------- | ----------------------------------------------- | +| `title` | string | _(required)_ | Page title | +| `description` | string | _(none)_ | Meta description | +| `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") | +| `template` | string | _(none)_ | Custom template name | +| `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 diff --git a/docs/content/content-organization.md b/docs/content/content-organization.md index 4023473..149b359 100644 --- a/docs/content/content-organization.md +++ b/docs/content/content-organization.md @@ -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 diff --git a/docs/content/deployment.md b/docs/content/deployment.md index 7e271d2..1272cd1 100644 --- a/docs/content/deployment.md +++ b/docs/content/deployment.md @@ -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. diff --git a/docs/content/features/_index.md b/docs/content/features/_index.md index bd5234f..c1e2b6f 100644 --- a/docs/content/features/_index.md +++ b/docs/content/features/_index.md @@ -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. diff --git a/docs/content/features/css.md b/docs/content/features/css.md index 24bc25a..c301b97 100644 --- a/docs/content/features/css.md +++ b/docs/content/features/css.md @@ -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. diff --git a/docs/content/features/feeds.md b/docs/content/features/feeds.md index 32cebe9..e101096 100644 --- a/docs/content/features/feeds.md +++ b/docs/content/features/feeds.md @@ -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. diff --git a/docs/content/features/math.md b/docs/content/features/math.md index a8a0660..478b90d 100644 --- a/docs/content/features/math.md +++ b/docs/content/features/math.md @@ -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. diff --git a/docs/content/features/mermaid.md b/docs/content/features/mermaid.md index 8d1071d..c946653 100644 --- a/docs/content/features/mermaid.md +++ b/docs/content/features/mermaid.md @@ -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. diff --git a/docs/content/features/sections.md b/docs/content/features/sections.md index 3654385..9b6ba4a 100644 --- a/docs/content/features/sections.md +++ b/docs/content/features/sections.md @@ -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 diff --git a/docs/content/features/sitemap.md b/docs/content/features/sitemap.md index 141dd29..57f1ebc 100644 --- a/docs/content/features/sitemap.md +++ b/docs/content/features/sitemap.md @@ -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 ``: -```yaml ---- -title: My Post -date: 2024-01-15 ---- +```toml ++++ +title = "My Post" +date = 2024-01-15 ++++ ``` Content without dates omits the `` element. diff --git a/docs/content/features/syntax-highlighting.md b/docs/content/features/syntax-highlighting.md index b2ed9f8..276ca7f 100644 --- a/docs/content/features/syntax-highlighting.md +++ b/docs/content/features/syntax-highlighting.md @@ -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. diff --git a/docs/content/features/templates.md b/docs/content/features/templates.md index 9dfbd3d..009eb1a 100644 --- a/docs/content/features/templates.md +++ b/docs/content/features/templates.md @@ -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. diff --git a/docs/content/getting-started.md b/docs/content/getting-started.md index 8db8127..3376339 100644 --- a/docs/content/getting-started.md +++ b/docs/content/getting-started.md @@ -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! diff --git a/docs/content/security.md b/docs/content/security.md index 040eed5..4c2bcb9 100644 --- a/docs/content/security.md +++ b/docs/content/security.md @@ -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 | diff --git a/docs/plans/api-stabilization.md b/docs/plans/api-stabilization.md index bea95f5..c0ff0d3 100644 --- a/docs/plans/api-stabilization.md +++ b/docs/plans/api-stabilization.md @@ -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/.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)