Architecture

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

Pipeline Overview¶

The compiler runs in two phases:

1. Discover — walk the filesystem, parse frontmatter and markdown, extract typed content blocks and link references, build the navigation tree
2. Render — dispatch each content block to its renderer, apply templates, write output files

The discover phase also validates internal links — any [link](../page.md) pointing to a nonexistent page is reported as an error before rendering begins.

Module Responsibilities¶

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 into typed content blocks:

Each content block carries its own data — language, math expression, diagram source, heading level + slug, or pre-rendered HTML prose. During the render phase, each block type is dispatched to its renderer independently.

Non-intercepted content (paragraphs, lists, emphasis, inline code) is rendered to HTML during parsing and emitted as prose blocks. Link URLs are extracted as a side-channel for reference validation.

Why Zero-JS¶

Traditional SSGs ship JavaScript for:

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 tree-house (Helix editor's Tree-sitter integration) with LazyLock to create language configurations exactly once:

/// Create a LanguageConfig for a language with embedded queries.
fn make_config(
    grammar: Grammar,
    highlights: &str,
    injections: &str,
    locals: &str,
) -> Option<LanguageConfig> {
    LanguageConfig::new(grammar, highlights, injections, locals).ok()
}

// Register Rust with embedded Helix queries
if let Ok(grammar) = Grammar::try_from(tree_sitter_rust::LANGUAGE)
    && let Some(config) = make_config(
        grammar,
        include_str!("../queries/rust/highlights.scm"),
        include_str!("../queries/rust/injections.scm"),
        include_str!("../queries/rust/locals.scm"),
    )
{
    config.configure(resolve_scope);
    configs.insert(Language::Rust, config);
}

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

Content Discovery¶

The SiteManifest struct aggregates all content in one filesystem traversal:

• Homepage (_index.md at root)
• Sections (directories with _index.md) — items sorted at discovery time
• Standalone pages (top-level .md files)
• Navigation tree (derived from sections and pages, ordered by weight)
• Internal link references (validated against known output paths)

This avoids repeated directory scans during template rendering. Broken internal links are caught before any rendering begins.

Implementation Notes¶

sukr prioritizes output quality over minimal build-time footprint. Current dependency choices reflect this:

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.