Architecture

How sukr transforms markdown into zero-JS static sites

Sukr is a 12-module static site compiler. Every feature that would typically require client-side JavaScript is moved to build-time.

Pipeline Overview

YesNoWalk content/Parse frontmatterStream markdownCode block?InterceptPass throughRender HTMLApply templateWrite public/

Module Responsibilities

Module Purpose
main.rs Pipeline orchestrator — wires everything together
config.rs Loads site.toml configuration
content.rs Discovers sections, pages, and navigation structure
render.rs Markdown→HTML with code block interception
highlight.rs Tree-sitter syntax highlighting (14 languages)
math.rs KaTeX rendering to MathML
mermaid.rs Mermaid diagrams to inline SVG
css.rs CSS minification via lightningcss
template_engine.rs Tera template loading and rendering
feed.rs Atom feed generation
sitemap.rs XML sitemap generation
error.rs Structured error types with source chaining

The Interception Pattern

The core innovation is event-based interception. Rather than parsing markdown into an AST and walking it twice, sukr streams pulldown-cmark events and intercepts specific patterns:

Start CodeBlockrust, python, etc.mermaidmath delimitersunknownOther eventspulldown-cmark eventstreamEvent type?Buffer contentLanguage tag?Tree-sitterhighlightingMermaid SVG renderingKaTeX MathMLHTML escape onlyEmit highlighted spansPass throughContinue stream

This pattern avoids buffering the entire document. Each code block is processed in isolation as it streams through.

Why Zero-JS

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

The result: zero bytes of JavaScript in the output. Pages load instantly, work without JS enabled, and avoid the complexity of client-side hydration.

Static Configuration Pattern

Tree-sitter grammars are expensive to initialize. Sukr uses LazyLock to create each language configuration exactly once:

static RUST_CONFIG: LazyLock<HighlightConfiguration> = LazyLock::new(|| {
    let mut config = HighlightConfiguration::new(
        tree_sitter_rust::LANGUAGE.into(),
        "rust",
        tree_sitter_rust::HIGHLIGHTS_QUERY,
        "",
    ).expect("query should be valid");
    config.configure(HIGHLIGHT_NAMES);
    config
});

This pattern ensures O(1) lookup per language regardless of how many code blocks exist in the site.

Single-Pass Content Discovery

The SiteManifest struct aggregates all content in one filesystem traversal:

  • Homepage (_index.md at root)
  • Sections (directories with _index.md)
  • Section items (posts, projects, pages)
  • Navigation tree (derived from structure + frontmatter weights)

This avoids repeated directory scans during template rendering.