Three-phase plan to stabilize sukr's public API surfaces before 1.0:
- Phase 1: Replace hand-rolled YAML frontmatter with TOML (+++ delimiters,
serde Deserialize), normalize template variable naming, add feed/sitemap
config toggles, template section fallback, remove dead templates
- Phase 2: Draft filtering and alias redirect stub generation
- Phase 3: 404 page support and tag listing page generation
Key decisions: TOML frontmatter (eliminates fragile parser), config.nav
nesting to mirror site.toml structure, flat tags array, date validation
via chrono::NaiveDate.
Ref: .sketches/2026-02-13-api-stabilization.md
Frame the strategic intent for reaching a 1.0 release.
Four workstreams in priority order:
- API Stabilization (feature evaluation + dependency health audit)
- Error Quality (actionable messages, no panics outside main)
- Test Coverage (protect the stabilized surface)
- Distribution (CI/CD, cargo install, nix build, changelog)
Strategic non-goals: plugin system, incremental builds,
additional output formats, dev server, migration tooling.
Check off all 7 plan verification items with results.
Write retrospective covering what went well (phased approach,
source verification, CHALLENGE decisions), surprises (sketch
false positives, extra Sukr instances, existing Tera link),
process observations (CORE granularity, cross-phase deps,
tech debt tracking), and intentional deferrals (G2, G5,
security.md mixed quadrants).
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).
Remove duplicated comparison table, inline config reference,
and content structure diagram from README — link to docs site
instead. Trim themes/README.md to attribution and theme list,
link to syntax-highlighting docs for usage and customization.
Create deployment.md how-to page covering local preview,
GitHub Pages, Netlify, Cloudflare Pages, and generic static
hosts. Add cross-links from homepage and getting-started
Next Steps. Reference security.md for CSP headers.
Update Tera link to canonical URL, add authoring syntax
pointer. Add Default column to frontmatter fields table
with source-verified values. Enrich Theme System section
with core CSS variables table and customization pattern.
Rewrite _index.md as explanation-only — remove inline Quick
Start, add Learn More links. Move section discovery explanation
from features/sections.md into content-organization.md. Slim
sections.md to reference-only with cross-reference.
Normalize "Sukr" to "sukr" in architecture.md (4 instances).
Change site.toml title to lowercase. Fix template override
path from page/special.html to content/special.html. Update
copyright year to 2026.
Replace stale `cargo install sukr` with install-from-source.
Replace Step 4 dead-end with inline base.html, page.html,
and content/default.html templates. Add "View your site"
completion step. Improve Next Steps with reading-order context.
- Fix module count: 12 → 13 (add escape.rs)
- Add escape.rs to module responsibilities table
- Update code example from old HighlightConfiguration API
to current tree-house LanguageConfig pattern
Reflects tree-house migration and API coherence audit findings.
- Add 6 syntax highlighting themes (dracula, gruvbox, nord, github)
- Rewrite css.rs to use lightningcss bundler for @import resolution
- Theme CSS is inlined at build time, producing single bundled output
Use CSS Overflow Level 5 properties (scroll-target-group, :target-current)
to highlight the current section in the sidebar TOC as the user scrolls.
Progressive enhancement: gracefully degrades in unsupported browsers
(Firefox, Safari) — they retain existing hover/click behavior.
Browser support: Chrome 140+, Edge 140+, Opera 124+ (~65% global).
Document that sukr prioritizes output quality over minimal build-time
weight. Acknowledges KaTeX and mermaid-rs are heavier than alternatives,
leaving door open for future evaluation without committing to redesign.
Rename "Zero JS Output" to "JS-Free Rich Content" with footnote
explaining that all generators can produce JS-free basic HTML—sukr's
distinction is built-in build-time math and diagram rendering.
Override mermaid's default white backgrounds to blend with dark theme:
- Transparent SVG background
- Node fills use --bg-sidebar
- Labels use --fg color
- Edges use --fg-muted
Add scrollable container rules for .mermaid-diagram in mobile
media query. SVG diagrams now scroll horizontally within their
container instead of extending the page width and obscuring
the hamburger menu.
- Highlight heading with accent border-left when targeted via URL hash
- Show pilcrow anchor visibly on targeted headings
- Add scroll-margin-top for better scroll positioning
- Add pilcrow (¶) anchor link after heading text for deep-linking
- CSS: hidden by default, visible on heading hover, user-overridable
- Add strip_parens Tera filter for cleaner nav anchor labels
- Update test expectations for new heading format
- Add toc: bool to [nav] config section (default: false)
- Frontmatter toc: true/false overrides global config
- If frontmatter toc is not specified, falls back to config.nav.toc
- Enable nav.toc = true in docs/site.toml for global TOC
- Pass extracted anchors through template context
- Render anchor links under active page when page.toc is true
- Hierarchical indentation by heading level (h2-h6)
- CSS styling: smaller font, muted color, border-left indicator
- Add toc: true to templates.md as example
Add responsive table rules: horizontal scroll within container,
word-break for inline code, and constrained max-width. Fixes
hamburger menu being pushed off-screen on pages with wide tables.
Implement pure CSS mobile navigation with the following features:
- Collapsible sidebar nav hidden behind hamburger toggle on mobile
- Animated hamburger → X icon morph using CSS transforms
- Smooth slide-down transition for nav reveal (max-height/opacity)
- Hamburger positioned on right side of header via absolute positioning
- Uses :has() selector to detect checkbox state without JavaScript
- Overflow fixes to prevent horizontal scroll on mobile devices
The implementation follows suckless principles with zero JavaScript.
Add docs/content/features/sitemap.md documenting the automatic
XML sitemap generation feature:
- Output location and contents
- Auto-generation behavior
- lastmod date handling
- Linking and validation tips
Follows established pattern from feeds.md.
- Add sidebar footer with GitHub repo link and MIT copyright
- Generate geometric logo for project branding
- Add logo as favicon in browser tab
- Add logo to sidebar header (32x32) next to "sukr" text
- Add centered logo (128px) at top of README
- Add sidebar footer with GitHub repo link and MIT copyright
- Position footer at bottom of sidebar using flexbox
- Generate geometric logo and add as favicon
- Update base.html template with footer and favicon link
KaTeX renders square roots using a 400em-wide SVG that relies on CSS
`overflow: hidden` to clip to the correct length. Without the KaTeX
stylesheet, this SVG extends across the entire page.
Changes:
- Add KaTeX CDN stylesheet link to base.html for fonts and layout
- Add .katex-display local margin/overflow overrides
- Add .hide-tail svg max-width fallback for file:// CORS blocking
The CDN provides full KaTeX styling when accessible. The SVG constraint
serves as a fallback when CDN is blocked (e.g., local file:// access).
Fix markdown code block highlighting to properly support both markdown
structure (headings, frontmatter) and language injection (rust, bash).
The key fix uses `#set! injection.include-children` in the injection
query to override tree-sitter-md's internal tokenization, enabling
proper highlighting of embedded languages within code fences.
Changes:
- Use crate's HIGHLIGHT_QUERY_BLOCK for base markdown highlighting
- Add custom injection query with include-children directive
- Add YAML/TOML frontmatter and HTML block injection rules
- Add text.* highlight names (title, literal, uri, reference)
- Add string.escape highlight name
- Add CSS styles for new highlight classes
- Remove unused custom md-highlights.scm
- Add Atom feed generation docs (feeds.md)
- Add CSS minification docs (css.md)
- Fix em dash usage in css.md for natural prose
Completes AI audit (4 layers passed) and documentation gap analysis.
All 39 tests pass, docs site builds successfully.
