Close plan review: fix Decisions table 404 naming (content/404.md
→ content/_404.md), check off Verification items, log
collect_items() quadruple-call as technical debt, fill in
Retrospective.
Fix post-changeset staleness: AGENTS.md YAML→TOML reference,
add [nav]/[feed]/[sitemap] config tables to AGENTS.md example,
mark charter workstream 1 complete.
Thread tag names from collect_tags() through
generate_sitemap_file to generate_sitemap, appending
/tags/<tag>.html entries to sitemap.xml output.
Refactor: hoist collect_tags into run(), rename
generate_tag_pages to write_tag_pages.
Test suite: 83 → 84, phase 3 complete.
Detect content/_404.md as special page (underscore
prefix convention), store in SiteManifest.page_404,
render to 404.html in output root.
Add collect_tags() grouping all tagged content into
BTreeMap for deterministic output. render_tag_page()
renders through tags/default.html template.
Add 5 tests. Test suite: 78 → 83, all passing.
Add generate_aliases(), write_aliases(), and
redirect_html() to main.rs. For each content item
with aliases in frontmatter, writes a minimal HTML
redirect stub with meta refresh and canonical link.
Alias paths are normalized: bare paths get
/index.html appended, .html extensions preserved.
Add 2 tests. Test suite: 76 → 78, all passing.
Phase 2 complete — all plan items checked off.
Add draft filtering at discovery source functions:
collect_items(), discover_nav(), discover_pages().
Posts, feed, and sitemap inherit filtering
automatically via collect_items().
Items with frontmatter draft = true are excluded
from section listings, navigation, feed, and
sitemap. Default is false — no behavior change
for existing content.
Add 3 tests. Test suite: 73 → 76, all passing.
Wire config.feed.enabled and config.sitemap.enabled
into main.rs run() function. Both default to true,
so existing behavior is preserved.
Add 5 new tests: feed/sitemap config defaults,
independent disable, and ConfigContext nav structure
with base_url trailing-slash normalization.
Test suite: 69 → 73 tests, all passing.
Phase 1 complete — all plan items checked off.
Add FeedConfig and SitemapConfig structs to config.rs
with enabled: bool (default true) for opt-out control.
Refactor ConfigContext: flat nested_nav bool replaced
with nested nav: NavContext { nested, toc } to mirror
site.toml [nav] table structure.
Remove standalone base_url template variable; use
config.base_url as single source of truth with
trailing-slash trimming in ConfigContext::from().
Add section template fallback: try section/<type>.html,
fall back to section/default.html for unknown types.
Delete section/features.html (duplicate of default.html)
and homepage.html (dead code, never referenced).
Update base.html for new variable names.
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.
Replace hand-rolled YAML parser (70 lines) with serde-backed
toml::from_str<Frontmatter> (6 lines). Frontmatter delimiter
changes from --- to +++ (Hugo TOML convention).
New Frontmatter fields:
- draft: bool (#[serde(default)]) for draft filtering
- aliases: Vec<String> (#[serde(default)]) for URL redirects
Date field upgraded from Option<String> to Option<NaiveDate>
with custom deserializer for TOML native dates. Parse, don't
validate: invalid dates now fail at deserialization time.
Add chrono dependency with serde feature. Update cascade in
sitemap.rs (NaiveDate→String at boundary), template_engine.rs
(FrontmatterContext gains draft/aliases), and all 14 tests.
BREAKING CHANGE: Content files must use +++ TOML frontmatter
instead of --- YAML frontmatter.
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.
Manual Display and Error trait implementations replace derive macro.
Preserves source() chaining for all io::Error and tera::Error variants.
One less dependency, same behavior.
Two issues fixed:
1. Language-less code blocks (``` without lang) were not accumulating
text content. The guard `code_block_lang.is_some()` was false for
them, so content fell through to regular text rendering.
Fix: Add `in_code_block` flag to track code block state separately
from language presence.
2. Single quotes in code blocks were being HTML-escaped as ',
breaking CSP headers like 'self' in documentation.
Fix: Create code_escape/code_escape_into in escape.rs that only
escapes <, >, & (required to prevent HTML tag injection) but
preserves quotes (safe inside <pre><code> content).
Rationale for code_escape:
- < and > MUST be escaped to prevent browser interpreting code as HTML
- & MUST be escaped to prevent HTML entity interpretation
- Quotes are safe inside element content (no attribute context)
Also:
- Add test for unlabeled code block quote preservation
All 71 tests pass.
Apply html_escape to:
- Link href and title attributes (start_tag_to_html)
- Image src attribute (Event::End TagEnd::Image handler)
Add test cases for:
- Quote-breaking URL attacks
- Link title escaping
- Image src escaping
Addresses HIGH severity finding from security audit.
All 70 tests pass.
Add '\'' → ''' case to html_escape_into for complete XSS
protection in HTML attribute contexts. Update documentation
and add test case.
Addresses LOW severity finding from security audit.
- 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.
- content: DEFAULT_WEIGHT, DEFAULT_WEIGHT_HIGH → pub(crate)
- sitemap: SitemapEntry → pub(crate)
These items are implementation details not exposed to consumers.
- Create escape.rs with shared html_escape, html_escape_into, xml_escape
- Remove duplicate implementations from render.rs, highlight.rs, feed.rs, sitemap.rs
- Add DEFAULT_WEIGHT (50) and DEFAULT_WEIGHT_HIGH (99) constants to content.rs
- Replace all magic number weight defaults with named constants
No functional changes; all 67 tests pass.
- 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
Replace tree-sitter-highlight dep with tree-house crate from Helix
editor. Add ropey dependency required by tree-house.
Reorganize query files from Helix's runtime/queries/ for all 14
supported languages:
- bash, c, css, go, html, javascript, json, markdown, nix, python,
rust, toml, typescript, yaml
- Include ecma, _javascript, _typescript base dirs for JS/TS inheritance
- Copy highlights.scm, injections.scm, locals.scm where available
This commit establishes the foundation; highlight.rs implementation
will follow in subsequent commits.
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
