From 7af7fa34e4ba0ade232c9502439452bac1d792f3 Mon Sep 17 00:00:00 2001 From: Timothy DeHerrera Date: Wed, 4 Feb 2026 11:18:13 -0700 Subject: [PATCH] docs(architecture): add implementation notes on dependency trade-offs 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. --- docs/content/architecture.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/content/architecture.md b/docs/content/architecture.md index 6b8b4e6..d302220 100644 --- a/docs/content/architecture.md +++ b/docs/content/architecture.md @@ -105,3 +105,14 @@ The `SiteManifest` struct aggregates all content in one filesystem traversal: - Navigation tree (derived from structure + frontmatter weights) This avoids repeated directory scans during template rendering. + +## Implementation Notes + +Sukr prioritizes **output quality** over minimal build-time footprint. Current dependency choices reflect this: + +| Feature | Library | Trade-off | +| :------- | :--------- | :----------------------------------------------------------------------- | +| Math | KaTeX | Full LaTeX coverage; heavier than minimal alternatives like latex2mathml | +| Diagrams | mermaid-rs | High-fidelity SVG; uses headless rendering under the hood | + +Lighter alternatives exist and may be evaluated as they mature. The goal is browser-native output with zero client-side JavaScript—build-time weight is a secondary concern.