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
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.
