spencer/thor

Fork 0

mirror of https://github.com/sbrow/thor.git synced 2026-08-26 11:23:32 -04:00

Files

T

Spencer Brower 3898925228 chore: Updated AGENTS.md.

2026-07-16 14:48:31 -04:00

11 KiB

Raw Blame History

Thor — Odin Static Site Generator

Thor is a static site generator written in Odin, replacing Hugo for the sbrow.github.io blog. It lives at ./thor/ as a git subtree with its own flake.nix.

Architecture

thor.json          ← site config (title, base_url, author, params)
content/           ← markdown and HTML content files
layouts/           ← Mustache templates + partials (including icons)
assets/            ← CSS (Tufte-based), JS, fonts, images — copied/processed to public/
public/            ← build output (generated)

Source files

File	Responsibility
`main.odin`	Entry point. Sets `context.logger`, calls `init_site`, `walk_content`, `render_site`. Optional Spall profiling via `SPALL` config flag.
`site.odin`	`Flags` (parsed config), `Site` (runtime state + arena), `Feature` bit_set enum, `init_site`, `load_site_config`, `merge_flags`, `site_apply_flags`, `find_config` (walks up dir tree for `thor.json`)
`frontmatter.odin`	JSON frontmatter parser (`{ }` delimited)
`content.odin`	`Page` struct, content walker, page loader, cmark integration, full markdown pipeline, `copy_assets_dir` (recursive copy with CSS minification)
`footnotes.odin`	Note definition stripping (pre-cmark) + sidenote/marginnote injection (post-cmark)
`alerts.odin`	GitHub alert post-processor (`> [!CAUTION]` → styled blockquote)
`emoji.odin`	Emoji shortcode expander (`:shrug:` → `¯\_(ツ)_/¯`), post-cmark
`highlight.odin`	Post-cmark Tree-sitter syntax highlighter; statically links HTML/CSS grammars, dlopen for others; caches loaded grammars, reports syntax errors
`tree_sitter.odin`	C FFI bindings for Tree-sitter (TSParser, TSQuery, TSQueryCursor, node traversal, dlopen/dlsym). Statically links `tree-sitter-html` and `tree-sitter-css` via Nix.
`sectionate.odin`	`wrap_sections` proc — splits HTML at `<h2` into `<section>` wrappers
`render.odin`	Template rendering pipeline: pre-parses templates/partials once, struct-based data model (`Base_Data`/`Page_Data`/`Home_Data`/`Posts_Data`), `mustache.render()`, minification gate, RSS, sitemap, robots.txt
`minify.odin`	Tree-sitter-based HTML and CSS minification (`minify_html`, `minify_css`). Strips comments, collapses whitespace, removes inter-tag spaces. Preserves `<pre>`/`<code>`/`<script>`/`<style>` content.
`feed.odin`	RSS feed + sitemap XML generation. Uses `strings.Builder`. `format_rfc822` uses `core:time` for date parsing.
`mustache/`	Mustache template engine (spec-compliant, custom implementation)

Icon SVGs live as HTML partials in layouts/partials/icons/ (home, github, rss, chevron_up, star).

Data flow

thor.json → find_config → init_site → Flags → merge_flags → site_apply_flags → Site (config + Dynamic_Arena + features: bit_set)
                                                                                              ↓
content/ → walk_content → []Page (with body_html from pipeline)
                                                                                              ↓
layouts/*.html → parse() → mustache.Template (parsed once)
                                   ↓
render_site → mustache.render(Page_Data, partials) → optional minify_html → public/

Config system

Config is split into Flags (parsed from CLI args + JSON) and Site (runtime state):

Flags — pure parsed config struct. CLI args via core:flags, JSON via json.unmarshal_string.
Site — runtime state: arena, resolved config values, features: bit_set[Feature].
Feature enum — Sections, Drafts, Minify, Watch. Checked with .Minify in site.features.
find_config — walks up from CWD looking for thor.json. Falls back to ./thor.json.

Config precedence: CLI flags > thor.json values > hardcoded defaults.

{
  "title": "...",
  "base_url": "...",
  "author": "...",
  "sectionate": true,
  "params": {
    "social": [
      { "name": "github", "url": "...", "icon": "icons/github" }
    ]
  }
}

Template system

Templates use Mustache with template inheritance ({{<base}} / {{$block}}):

<!-- base.html -->
<body>{{> nav}}{{$content}}{{/content}}{{> footer}}</body>

<!-- post.html -->
{{<base}}
{{$content}}
<main><article><h1>{{page_title}}</h1>{{&body}}</article></main>
{{/content}}
{{/base}}

Data is passed as typed structs (not map[string]any). Mustache resolves struct fields via Odin reflection, including using-embedded fields:

Base_Data :: struct {
    now:  datetime.DateTime,
    body: string,
    title: string,
    // ...
}
Page_Data :: struct {
    using base: Base_Data,  // fields promoted via struct_get fallback
    page_title: string,
    // ...
}

render_site pre-parses all templates and partials once (via mustache.parse), then reuses them for every page render.

Markdown pipeline (in content.odin `load_page`)

raw markdown
  → strip_definitions     (pre-cmark: extract [^id]: definitions)
  → cmark markdown_to_html (Unsafe mode for HTML passthrough)
  → expand_emoji          (post-cmark: :shortcode: → unicode, avoids cmark escape issues)
  → inject_notes          (post-cmark: [^id] → <label><input><span> markup)
  → inject_alerts         (post-cmark: [!TYPE] blockquotes → styled alerts)
  → highlight_code        (post-cmark: tree-sitter per code block, with error reporting)
  → wrap_sections         (post-cmark: if .Sections in features, wraps content in <section> at <h2>)

.html content files skip cmark entirely — body is used as-is.

Syntax highlighting

Build-time highlighting via Tree-sitter C FFI. No client-side JavaScript.

HTML and CSS grammars statically linked via Nix (mkGrammarStaticLib in thor/flake.nix). Always available, no dlopen.
Other grammars (bash, odin, nu, etc.) loaded via dlopen from Helix's compiled .so files.
Highlight queries (.scm) loaded from Helix's runtime directory.
Paths hardcoded in tree_sitter.odin (Nix store paths, Helix-version-dependent).
Grammar loading split: ensure_parser (parser only, used by minify) vs load_grammar (parser + query, used by highlight).
Capture names mapped to CSS classes: keyword → .hl-keyword, etc.
Atom-one-dark color theme in main.css.

Minification

Optional, enabled with -minify flag (.Minify in Feature bit_set).

HTML — tree-sitter parses output, strips comments, removes inter-tag whitespace, preserves <pre>/<code>/<textarea>/<script>/<style> content. Applied after template rendering.
CSS — tree-sitter parses .css files in assets/, strips comments, collapses whitespace, trims around {};:,. Applied during copy_assets_dir.
Non-CSS files in assets/ copied verbatim.

Memory management

Site owns a mem.Dynamic_Arena
init_site calls mem.dynamic_arena_init(&site.arena, alignment = 64) — the 64-byte alignment is required by Odin's map runtime (MAP_CACHE_LINE_SIZE)
Config loading (flags + JSON) uses the arena allocator explicitly
site_allocator(site) returns the arena allocator for callers
destroy_site frees the arena
main.odin sets context.logger = log.create_console_logger() — without this, all log.* calls are silently dropped
context.allocator is set to site_allocator(&site) in the main loop

Spall profiling

Optional, compiled out by default. Enabled with -define:SPALL=true:

odin build . -define:SPALL=true -o:speed -out:thor-prof
./thor-prof -drafts  # generates thor.spall

Uses core:prof/spall with @(instrumentation_enter)/@(instrumentation_exit) hooks — every function auto-instrumented, no manual annotation needed.

Building

Local development

nix develop
# From blog root:
odin run ./thor -- -drafts
# Assets (CSS/JS/fonts) are copied/minified automatically by thor
caddy run  # serves public/ on blog.localhost

No CSS build step — main.css is static Tufte-based CSS, no preprocessor or compiler needed.

Production build

nix build  # runs thor, outputs to ./result/

Tests

cd thor
odin test .              # site tests (config, frontmatter, footnotes)
odin test . -all-packages  # includes mustache spec tests

Mustache engine

Spec-compliant Mustache implementation at mustache/. See mustache/SPEC.md for the implementation specification.

Files

File	Responsibility
`mustache.odin`	Public API (`parse`, `render`, `Template`), parser (`parse_section`), renderer (`render_nodes`), template inheritance (`merge_block_overrides`)
`tokenizer.odin`	Tokenizer (template string → `[]Token`), standalone whitespace detection
`data.odin`	Reflection-based data model: `effective` (union/distinct peeling), `lookup_in`, `resolve_name`, `is_truthy`, `any_to_string`, `list_info`, `write_value`
`spec_test.odin`	JSON spec test runner — loads `spec/specs/*.json`, runs each test case

Architecture

parse(source) → tokenize → trim_standalone_whitespace → parse_section → Template
render(tmpl, data, partials) → render_nodes (walks flat node array against context stack) → string

Two-phase API: parse() produces a reusable Template, render() walks it against data. Templates parsed once, rendered many times.
Flat [dynamic]Node array with first_child/child_count indices — pre-order layout.
Context stack: ^[dynamic]any with append/pop for section push/pop.
effective(a) peels Named/Distinct/Union layers (including json.Value).
lookup_in resolves keys on structs (via reflect.struct_field_value_by_name with allow_using = true) and maps (via runtime map internals).
Template inheritance: {{<parent}} loads parent from partials, {{$block}} defines overridable sections. merge_block_overrides propagates overrides through multi-level chains.
Dynamic partial names: {{>*key}} resolves partial name from data context at render time.

Not implemented

Lambdas (~lambdas.json)
Set delimiters ({{= =}}, delimiters.json)

Known limitations

cmark allocates via C malloc, not the arena. HTML output leaks until process exit.
CSS/JS cache busting uses manual ?v=N query params instead of content hashing.
Tree-sitter grammar/query paths for dynamic grammars hardcoded in tree_sitter.odin (Nix store hashes, Helix-version-dependent). HTML/CSS are statically linked.
map[string]any not fully supported by mustache lookup_in — thor uses structs instead.
format_f64 in mustache brute-forces shortest float representation.

Design decisions

See HUGO.md for analysis of why thor doesn't need Hugo's shortcode context isolation. See mustache/PARTIAL_INDENT.md for whitespace handling analysis. See mustache/SPEC.md for the original implementation specification.

TODO

See TODOS.md for the full list.

11 KiB Raw Blame History

Thor — Odin Static Site Generator

Architecture

Source files

Data flow

Config system

Template system

Markdown pipeline (in content.odin load_page)

Syntax highlighting

Minification

Memory management

Spall profiling

Building

Local development

Production build

Tests

Mustache engine

Files

Architecture

Not implemented

Known limitations

Design decisions

TODO

11 KiB

Raw Blame History

Markdown pipeline (in content.odin `load_page`)