docs: add cross-references and fix nav ordering
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).
This commit is contained in:
Timothy DeHerrera
@@ -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 → `<span class="hl-*">` |
|
||||
| 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 → `<span class="hl-*">` |
|
||||
| [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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user