From ef173ec092c774c22e2075bb41a8253b00d5c0be Mon Sep 17 00:00:00 2001 From: Timothy DeHerrera Date: Thu, 12 Feb 2026 13:27:23 -0700 Subject: [PATCH] docs: add cross-references and fix nav ordering MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Link feature names in architecture.md to feature docs pages. Add See Also section to configuration.md with related pages. Add getting-started prerequisite link to deployment.md. Adjust page weights for user journey sidebar order: Getting Started (0) → Deployment (1) → Content Organization (2) → Config (3). --- docs/content/architecture.md | 12 ++++++------ docs/content/configuration.md | 8 +++++++- docs/content/content-organization.md | 2 +- docs/content/deployment.md | 2 +- docs/plans/documentation-overhaul.md | 4 ++-- 5 files changed, 17 insertions(+), 11 deletions(-) diff --git a/docs/content/architecture.md b/docs/content/architecture.md index 21676ce..0681aca 100644 --- a/docs/content/architecture.md +++ b/docs/content/architecture.md @@ -68,12 +68,12 @@ This pattern avoids buffering the entire document. Each code block is processed Traditional SSGs ship JavaScript for: -| Feature | Typical Approach | sukr Approach | -| :------------------ | :--------------------- | :------------------------------------------------ | -| Syntax highlighting | Prism.js, Highlight.js | Tree-sitter at build-time → `` | -| Math rendering | MathJax, KaTeX.js | KaTeX at build-time → MathML (browser-native) | -| Diagrams | Mermaid.js | mermaid-rs at build-time → inline SVG | -| Mobile nav | JavaScript toggle | CSS `:has()` + checkbox hack | +| Feature | Typical Approach | sukr Approach | +| :------------------------------------------------------- | :--------------------- | :------------------------------------------------ | +| [Syntax highlighting](features/syntax-highlighting.html) | Prism.js, Highlight.js | Tree-sitter at build-time → `` | +| [Math rendering](features/math.html) | MathJax, KaTeX.js | KaTeX at build-time → MathML (browser-native) | +| [Diagrams](features/mermaid.html) | Mermaid.js | mermaid-rs at build-time → inline SVG | +| Mobile nav | JavaScript toggle | CSS `:has()` + checkbox hack | The result: **zero bytes of JavaScript** in the output. Pages load instantly, work without JS enabled, and avoid the complexity of client-side hydration. diff --git a/docs/content/configuration.md b/docs/content/configuration.md index 4202e25..b3f9d8a 100644 --- a/docs/content/configuration.md +++ b/docs/content/configuration.md @@ -1,7 +1,7 @@ --- title: Configuration description: Complete reference for site.toml configuration -weight: 2 +weight: 3 --- sukr is configured via `site.toml`. All settings have sensible defaults. @@ -110,3 +110,9 @@ The `section_type` field determines which template is used for section indexes: - _(any other)_ → `templates/section/default.html` If not specified, sukr uses the directory name as the section type. + +## See Also + +- [Getting Started](getting-started.html) — install sukr and build your first site +- [Content Organization](content-organization.html) — how directories map to site structure +- [Templates](features/templates.html) — template directory structure and customization diff --git a/docs/content/content-organization.md b/docs/content/content-organization.md index 2b57f02..4023473 100644 --- a/docs/content/content-organization.md +++ b/docs/content/content-organization.md @@ -1,7 +1,7 @@ --- title: Content Organization description: How the filesystem maps to your site structure -weight: 1 +weight: 2 --- sukr builds your site structure from your `content/` directory. No routing config needed — the filesystem _is_ the config. diff --git a/docs/content/deployment.md b/docs/content/deployment.md index e8e0c00..7e271d2 100644 --- a/docs/content/deployment.md +++ b/docs/content/deployment.md @@ -4,7 +4,7 @@ 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. +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. ## Local Preview diff --git a/docs/plans/documentation-overhaul.md b/docs/plans/documentation-overhaul.md index 6417cf0..b53c75b 100644 --- a/docs/plans/documentation-overhaul.md +++ b/docs/plans/documentation-overhaul.md @@ -88,7 +88,7 @@ None. All CHALLENGE questions resolved. - [x] Remove inline config reference (link to docs site `configuration.md`) - [x] Keep security overview (short, relevant for trust evaluation) - [x] Trim `themes/README.md` to attribution + structure + link to docs site (targeted exception) - - [ ] Add cross-references between docs pages where missing + - [x] Add cross-references between docs pages where missing ## Verification @@ -104,7 +104,7 @@ None. All CHALLENGE questions resolved. | Item | Severity | Why Introduced | Follow-Up | Resolved | | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :------------------------------------------------------ | :--------------------------------------------------------------- | :------: | -| `deployment.md` and `content-organization.md` both have weight 1 — alphabetical sort puts Content Org before Deployment in sidebar, suboptimal for user journey | Low | Changing other page weights was scope creep for Phase 3 | Adjust weights to match Install → Deploy → Organize user journey | ☐ | +| `deployment.md` and `content-organization.md` both have weight 1 — alphabetical sort puts Content Org before Deployment in sidebar, suboptimal for user journey | Low | Changing other page weights was scope creep for Phase 3 | Adjust weights to match Install → Deploy → Organize user journey | ☑ | ## Retrospective