feat: Added a default stylesheet for extensions.

AGENTS.md

@@ -53,10 +53,10 @@ thor/
 
 | File | Responsibility |
 |---|---|
-| `main.odin` | Entry point. Sets `context.logger`, calls `init_site`, `build_vfs`, wires `treesitter.grammar_dir`/`query_dir` from config, `site_load_content`, `render_site`. Optional Spall profiling via `SPALL` config flag. |
-| `site.odin` | `Flags` (CLI), `Config_File` (thor.json), `Site_Context` (template-facing: `title`, `description`, `base_url`, `params`, `og`, `menus`), `Site` (runtime state + arena + VFS + pages + `og`). `Feature` enum. 5-step `init_site`. Config menu parsing in `site_apply_config`. |
-| `content.odin` | `Page` struct (includes `weight`, `menus: map[string]Menu_Entry`, `og`), `Pending_File` struct, `scan_content_files` (section-aware walk that handles leaf bundles), `collect_languages` (pre-scan for code fence languages), `load_page` (falls back to file mtime when no frontmatter date), `infer_layout`. Calls `md.process()` for the markdown pipeline. |
-| `render.odin` | Template rendering: `render_site`, `render_page_html`, `render_home_html`, `render_section`. `Template_Context` (unified render struct with `site: Site_Context`, `page: Page`, `menus`, `posts`, `pages`). 3-frame context stack via `[]any{ctx.site, ctx.page, ctx}`. `sort_pages` (weight primary, date secondary). `to_title_case` for section display names. VFS-based template loading with fallback chain (`get_template`). |
+| `main.odin` | Entry point. Parses CLI flags via `core:flags`, sets logger level from `-verbose`/`-quiet`, calls `init_site`, `build_vfs`, wires `treesitter.grammar_dir`/`query_dir` from config, `site_load_content`, `render_site`. Optional Spall profiling via `SPALL` config flag. |
+| `site.odin` | `Flags` (CLI, includes `-verbose`/`-quiet`), `Config_File` (thor.json), `Site_Context` (template-facing: `title`, `description`, `base_url`, `params`, `og`, `menus`), `Site` (runtime state + arena + VFS + pages + `og`). `Feature` enum. `init_site(site, flags)` — takes pre-parsed `Flags`. Config menu parsing in `site_apply_config`. |
+| `content.odin` | `Page` struct (includes `weight`, `menus`, `params: json.Value`, `toc: string`, `og`), `Pending_File` struct, `scan_content_files` (section-aware walk that handles leaf bundles), `collect_languages` (pre-scan for code fence languages), `load_page` (falls back to file mtime, generates TOC via `md.generate_toc` when frontmatter `"toc": true`), `infer_layout`. Calls `md.process()` for the markdown pipeline. |
+| `render.odin` | Template rendering: `render_site`, `render_page_html`, `render_home_html`, `render_section`. `Template_Context` (unified render struct with `site: Site_Context`, `page: Page`, `menus`, `params`, `posts`, `pages`). 3-frame context stack via `[]any{ctx.site, ctx.page, ctx}`. `merge_params(site, page)` — shallow merge of site + page params. Error deduplication via `seen: ^map[string]bool` passed through render chain. `sort_pages` (weight primary, date secondary). `to_title_case` for section display names. VFS-based template loading with fallback chain (`get_template`). |
 | `menus.odin` | Menu system: `Menu_Entry {name, url, weight: Maybe(int)}`, `DEFAULT_WEIGHT = 10`. `build_menus` (priority chain: config → auto + page frontmatter, then `warn_all_duplicate_weights`). `collect_auto_menus` (sections + root-level pages, skips pages with explicit `"menus": "main"` frontmatter). `merge_page_menus` (frontmatter entries with effective weight fallback via nil check). `parse_page_menus` (string/array/object forms). `parse_config_menus` (from thor.json). `sort_menu_entries` / `compare_menu_entries` (weight primary via `.? or_else DEFAULT_WEIGHT`, name secondary). `warn_duplicate_weights` / `warn_all_duplicate_weights` (log when two entries in same menu have same explicitly-set weight). |
 | `minify.odin` | HTML/CSS minification via tree-sitter. Imports `ts "treesitter"`. |
 | `feed.odin` | RSS feed + sitemap XML. Uses `page.url` for canonical URLs. |
@@ -64,7 +64,7 @@ thor/
 | `assets.odin` | `copy_assets_dir` — iterates VFS entries with `assets/` prefix, minifies CSS, copies verbatim or via `os.copy_file`. |
 | `html.odin` | `strip_html_tags`, `unescape_html`, `generate_summary` (word-count truncation, zero-alloc), `generate_description` (HTML→plain text: strip tags, decode entities, collapse whitespace). |
 | `opengraph.odin` | `Open_Graph` struct (fields ordered per OGP spec, `is_article: Maybe(bool)`). `og_for_site(site)` for site defaults (from config + derived), `og_for_page(site_og, page)` for page-specific (overlay page.og + derive from page data). Description falls back to `generate_description(generate_summary(body_html))`. |
-| `frontmatter.odin` | JSON frontmatter parser (`{ }` delimited). Supports `layout`, `lastmod`, `weight: Maybe(int)`, `menus`, and nested `og` object (via `json_get_open_graph`). Helpers: `json_get_string`, `json_get_bool`, `json_get_int` (returns `Maybe(int)`, nil for absent/invalid). |
+| `frontmatter.odin` | JSON frontmatter parser (`{ }` delimited). Supports `layout`, `lastmod`, `weight: Maybe(int)`, `menus`, `params: json.Value`, `toc: bool`, and nested `og` object (via `json_get_open_graph`). Helpers: `json_get_string`, `json_get_bool`, `json_get_int` (returns `Maybe(int)`, nil for absent/invalid). |
 | `defaults.odin` | `DEFAULTS_PATH` constant, resolved at compile time via `#directory` so bundled templates ship in the binary. |
 
 ### Subpackages
@@ -72,13 +72,15 @@ thor/
 | Package | Files | Responsibility |
 |---|---|---|
 | `treesitter/` | `treesitter.odin` | FFI types (`Parser`, `Node`, `Query`, etc.), `@(link_prefix="ts_")` foreign bindings, grammar management (`Grammar_Store` with persistent allocator, `load_language`/`compile_query` building blocks, `ensure_parser`/`load_grammar` lazy loading, `preload_grammar`/`preload_grammars` for parallel loading with `sync.Mutex` cache protection), statically-linked HTML/CSS grammars |
-| `markdown/` | `markdown.odin` | `Extension` enum, `DEFAULT_EXTENSIONS`, `process(body, ext, file_path)` — full pipeline, `parse_extension_list`, `apply_extension_config` |
-| | `footnotes.odin` | `strip_definitions` (pre-cmark), `inject_notes` (post-cmark) |
+| `markdown/` | `markdown.odin` | `Extension` enum, `DEFAULT_EXTENSIONS`, `process(body, ext, file_path, allocator)` — full pipeline (clones cmark output, frees original), `parse_extension_list`, `apply_extension_config` |
+| | `footnotes.odin` | `strip_definitions` (pre-cmark, shared by `.Sidenotes` + `.Footnotes`), `inject_notes` (post-cmark sidenote rendering), `inject_footnotes` (post-cmark standard footnote rendering — numbered `<sup>` links + `<section class="footnotes"><ol>` at bottom). `.Sidenotes` and `.Footnotes` are mutually exclusive; `resolve_extension_conflicts` in `markdown.odin` picks `.Footnotes` if both are set. |
 | | `alerts.odin` | `inject_alerts` — GitHub alert blocks (`> [!NOTE]`) → styled blockquotes with semantic class names (`alert-note` etc.) |
 | | `emoji.odin` | `expand_emoji` — `:shortcode:` → unicode emoji |
 | | `sectionate.odin` | `wrap_sections` — splits HTML at `<h2>` into `<section>` wrappers |
 | | `highlight.odin` | Syntax highlighting via tree-sitter. Imports `../treesitter`. |
 | | `heading_ids.odin` | `inject_heading_ids` — adds `id` attributes to `<h1>`-`<h6>` from heading text. Slug-based, deduplicated. |
+| | `deflists.odin` | `convert_deflists` — pre-cmark pass. Scans for definition list patterns (`term\n\n: definition`) and converts to `<dl><dt><dd>` HTML blocks. Terms and definitions rendered through cmark individually for inline markdown. Consecutive pairs grouped into single `<dl>`. |
+| | `toc.odin` | `generate_toc(html, allocator)` — page-level feature (not a pipeline extension). Scans `<h1>`-`<h6>` for IDs (after `inject_heading_ids`), builds nested `<ul>` with `<a href="#id">` links. Called from `load_page` when frontmatter `"toc": true`. Depends on `.HeadingIDs` being enabled. |
 | `mustache/` | See [Mustache engine](#mustache-engine) below | Template engine |
 | `bench/` | `bench.odin` + `templates/` | Standalone template rendering benchmark. Generates 500 posts + 100 comments, renders with indented partials + inheritance + pipes. `--dump <path>` for output validation, positional arg for iteration count (default 250). |
 
@@ -113,13 +115,15 @@ Page :: struct {
     weight:      Maybe(int),  // page ordering (nil = unset, defaults to DEFAULT_WEIGHT at comparison time)
     lastmod:     string,
     menus:       map[string]Menu_Entry,  // frontmatter menu assignments
+    params:      json.Value,  // per-page params (merged with site params at render time)
     content:     string,      // rendered HTML body
     og:          Open_Graph,
     draft:       bool,
-    starred:     bool,
+    toc:         string,      // generated table of contents HTML (empty if not requested)
     _is_index:   bool `private`,
 }
 ```
+```
 
 No `Page_Type` enum — page type is inferred from section + `_is_index`. Layout is inferred via `infer_layout(section, is_index)`:
 
@@ -168,13 +172,13 @@ All weight fields use `Maybe(int)` — nil means "unset," `some(v)` means explic
 
 Config is split into three structs with a clear 5-step initialization flow:
 
-- **`Flags`** — CLI args only. Parsed by `core:flags`. Includes path overrides (`--content`, `--assets`, `--output`, `--layouts`), build-mode toggles (`-drafts`, `-watch`, `-minify`), and `-ext`/`-no-ext` for markdown extension overrides.
+- **`Flags`** — CLI args only. Parsed once in `main.odin` via `core:flags`, passed to `init_site`. Includes path overrides (`--content`, `--assets`, `--output`, `--layouts`), build-mode toggles (`-drafts`, `-watch`, `-minify`), log level (`-verbose` → Debug, `-quiet` → Warning), and `-ext`/`-no-ext` for markdown extension overrides.
 - **`Config_File`** — parsed from `thor.json` via `json.unmarshal_string`. Holds title, paths, `markdown_extensions` (JSON), `params` (JSON), `modules` (JSON array of relative paths), `og` (`Open_Graph` struct for site-level OG defaults).
 - **`Site`** — runtime state: arena, pages, modules, VFS, `features: bit_set[Feature]`, `markdown_extensions: bit_set[md.Extension]`, `og: Open_Graph` (resolved site-level OG).
 
 **`Feature` enum** — `Drafts`, `Minify`, `Watch`. Checked with `.Minify in site.features`.
 
-**`markdown.Extension` enum** (in the `markdown` package, not main) — `Emoji`, `Sidenotes`, `Alerts`, `Highlight`, `Sections`, `HeadingIDs`. Default is `md.DEFAULT_EXTENSIONS` (currently `.Emoji, .Sidenotes, .Alerts, .HeadingIDs`). Configurable via:
+**`markdown.Extension` enum** (in the `markdown` package, not main) — `Emoji`, `Sidenotes`, `Alerts`, `Highlight`, `Sections`, `HeadingIDs`, `DefLists`, `Footnotes`. Default is `md.DEFAULT_EXTENSIONS` (currently `.Emoji, .Sidenotes, .Alerts, .HeadingIDs, .DefLists`). Configurable via:
 - `thor.json`: `"markdown_extensions": { "emoji": true, "highlight": false, ... }`
 - CLI: `-ext:highlight,sections` (enable) / `-no-ext:emoji` (disable). Comma-separated, case-insensitive.
 
@@ -254,10 +258,12 @@ Lives in the `markdown` package. Entry point: `md.process(body, ext, file_path)`
 
 ```
 raw markdown
-  → md.strip_definitions     (if .Sidenotes — pre-cmark)
+  → md.strip_definitions     (if .Sidenotes || .Footnotes — pre-cmark)
+  → md.convert_deflists      (if .DefLists — pre-cmark)
   → cmark markdown_to_html   (Unsafe mode for HTML passthrough)
   → md.expand_emoji          (if .Emoji — post-cmark)
-  → md.inject_notes          (if .Sidenotes — post-cmark)
+  → md.inject_notes          (if .Sidenotes — post-cmark, sidenote rendering)
+  → md.inject_footnotes      (if .Footnotes — post-cmark, standard footnote rendering)
   → md.inject_alerts         (if .Alerts — post-cmark)
   → md.highlight_code        (if .Highlight — post-cmark)
   → md.inject_heading_ids    (if .HeadingIDs — post-cmark, pre-sections)
@@ -289,17 +295,17 @@ Template_Context :: struct {
     site:        Site_Context,   // site-level data (title, description, base_url, params, og)
     menus:       map[string][]Menu_Entry,  // generated menu data (copied from site, resolves above Page.menus)
     now:         string,          // UTC ISO 8601 build timestamp
-    title:       string,          // computed browser title ("Page | Site")
     date_format: string,          // from site.date.format (thor.json)
     timezone:    ^datetime.TZ_Region,  // for format pipe
     og:          Open_Graph,      // computed per-page OG
+    params:      json.Value,      // merged site + page params (resolves above Page.params)
     page:        Page,            // current page
     pages:       [dynamic]Page,   // home page list
     posts:       [dynamic]Page,   // section post list
 }
 ```
 
-`Site_Context` is embedded in `Site` via `using site_context`. Fields like `site.title`, `site.menus`, `site.params` are accessed directly on `Site` through promotion. `Template_Context.menus` is copied from `site.menus` to resolve above `Page.menus` (frontmatter assignments) on the context stack.
+`Site_Context` is embedded in `Site` via `using site_context`. Fields like `site.title`, `site.menus`, `site.params` are accessed directly on `Site` through promotion. `Template_Context.menus` is copied from `site.menus` to resolve above `Page.menus` (frontmatter assignments) on the context stack. `Template_Context.params` is set per-page via `merge_params(site.params, page.params)` — site params overlaid with page params. Browser title is handled by the `{{> title}}` partial (not a computed field).
 
 `render_site` pre-parses all partials and the base layout once (via `mustache.parse`), then per-layout templates are cached in `get_template`. Year-based grouping on section index pages is done in the template via `{{#posts | group_by year}}` (see Pipes extension below).
 
@@ -412,7 +418,7 @@ Spec-compliant implementation at `mustache/`. See `mustache/SPEC.md` for the imp
 | `mustache.odin` | Public API (`parse`, `render`, `Template`), parser (`parse_section`), renderer (`render_nodes` with `Indent_State` for partial indentation), template inheritance (`merge_block_overrides`), `delete_template`/`delete_partials`. Pipe support in Variable/Unescaped/Section/Inverted tags. |
 | `tokenizer.odin` | Tokenizer (template string → `[]Token`), standalone whitespace detection |
 | `data.odin` | Reflection-based data model: `base_value` (peels union/any/nested-any layers), `lookup_in` (structs + maps, handles `Type_Info_Any` value kind in maps), `resolve_name`, `is_truthy`, `any_to_string`, `write_value`, `list_info`, `extract_list_element`, `collect_map_keys` |
-| `pipes.odin` | Pipes extension: `Pipe_Filter` AST, `parse_pipeline` (takes `pos`), `apply_pipeline`, `apply_filter` (switch dispatch: `group_by` + `format`), `apply_group_by`, `apply_format`. Stored on `Node.filters`; render-scoped results in temp allocator. |
+| `pipes.odin` | Pipes extension: `Pipe_Op` enum (`.Format`, `.Group_By`), `pipe_op_from_string`/`pipe_op_candidates` (reflection-based enum name lookup), `Pipe_Filter` AST (with `op_pos` for diagnostics), `parse_pipeline` (tracks byte offsets via `strings.index`), `apply_pipeline`, `apply_filter` (exhaustive enum switch), `apply_group_by`, `apply_format`. Misspelled pipe op suggestions via `suggest_correction`. Stored on `Node.filters`; render-scoped results in temp allocator. |
 | `diagnostic.odin` | Rust-style error formatter: `format_error` (multi-line context, ANSI colors via `core:terminal/ansi`, `colorize` param), `format_render_error` (formats `Error`), `line_col`, `line_text`, `context_extent`, `count_lines`, `digit_count`, `should_colorize`. |
 | `suggest.odin` | Strict-warning helpers: `validate_key_path` (walks dotted path, crosses maps silently), `suggest_correction` (Levenshtein via `core:strings/levenshtein_distance`), `collect_struct_keys` (via reflection, recurses into `using`), `struct_has_field` (distinguishes missing field from nil value — needed for `Maybe(bool)`), `collect_partial_names`, `collect_block_names`. |
 | `spec_test.odin` | JSON spec test runner — loads `spec/specs/*.json`, runs each test case. Uses `log.nil_logger()` to suppress expected warnings. |
@@ -443,7 +449,11 @@ render(tmpl, data, partials) → render_nodes (walks flat node array against con
 
 Rust-style error messages with multi-line source context, caret underlines, and Levenshtein suggestions. ANSI colors via `core:terminal/ansi`, gated on `should_colorize()` (TTY detection on stderr).
 
-**Error types**: `Error_Body{msg, pos, kind}` where `kind` is `Error_Kind.Syntax` (parse-time) or `Error_Kind.Data` (render-time). `Error` is a single-variant union wrapping `Error_Body` (nilable for `!= nil` / `or_return`).
+**Error types**: `Error_Body{msg, pos, kind, source, path, span, hint}` where `kind` is `Error_Kind.Syntax` (parse-time) or `Error_Kind.Data` (render-time). `source`/`path` carry the template the error originated in (set by `tag_error` — enables correct file/line for errors inside partials). `span` controls caret underline width (used by pipe op diagnostics). `hint` carries "did you mean?" suggestions. `Error` is a single-variant union wrapping `Error_Body` (nilable for `!= nil` / `or_return`).
+
+**Error deduplication**: `render_template` takes `seen: ^map[string]bool`. Duplicate errors (same formatted diagnostic) are suppressed across page renders within a single build.
+
+**Partial source tracking**: `tag_error(err, current)` stamps render-time errors with `current.source`/`current.path` at the 4 `apply_pipeline` call sites in `render_nodes`. Ensures errors inside partials point at the partial file, not the top-level template.
 
 **Strict-by-default warnings** — `render_nodes` emits `log.warnf` diagnostics for:
 - Unknown keys in `{{k}}`, `{{{k}}}`, `{{#k}}`, `{{^k}}` (via `validate_key_path` + `suggest_correction`)
@@ -475,12 +485,13 @@ See `mustache/EXTENSIONS.md`.
 
 ## Known limitations
 
-- cmark allocates via C malloc, not the arena. HTML output leaks until process exit (problematic in watch mode — see `TODOS.md`).
 - CSS/JS cache busting uses manual `?v=N` query params instead of content hashing.
 - Tree-sitter grammar/query paths must be configured manually via `thor.json` (`grammars`, `queries`) — no auto-discovery. HTML/CSS are statically linked.
 - `map[string]any` only works through `lookup_in`'s special-case handling; thor otherwise uses structs.
 - `format_f64` in mustache brute-forces shortest float representation.
 - Content directory not mounted in VFS (modules can ship templates/assets but not content packs yet).
+- Per-page params rendering is incomplete — `merge_params` produces correct data, but `base_value` may return nil for `json.Value` fields accessed through the `[]any` context stack via reflection in some cases. Warning suppression masks this; actual rendering may not work for all param values.
+- Lambda support removed. Mustache lambdas (`proc() -> string` in data context) are not supported. Pipes cover data transformation.
 
 ## Design decisions
 
@@ -488,6 +499,8 @@ You may never, *ever* remove `TODO:` or `FIXME:` comments. Those are for humans,
 See `HUGO.md` for analysis of why thor doesn't need Hugo's shortcode context isolation.
 See `mustache/SPEC.md` for the original implementation specification.
 See `mustache/EXTENSIONS.md` for non-standard extensions (pipes).
+See `DIAGNOSTICS.md` for the two-tier diagnostic system design.
+See `mustache/TOKENIZERS.md` for tokenizer architecture comparison (Go, Liquid, Thor).
 
 ## Odin language facts
 
@@ -502,6 +515,7 @@ These are things that are easy to get wrong:
 - **`Maybe(T)` unwrap syntax:** `value.? or_else default`. Not `value or_else default` — `or_else` works on the `?T` returned by `.?`, not on `Maybe(T)` directly.
 - **`Maybe(T)` equality:** `a == b` works directly between two `Maybe(T)` values (nil == nil → true, some(5) == some(5) → true, nil == some(5) → false). Also `a == 5` works (int coerces to `Maybe(int)`).
 - **File logger in tests:** `log.create_file_logger(&f)` + `context.logger = logger` captures log output. Must be set inline in the test proc (not via a helper proc) for context propagation. Clean up with `log.destroy_file_logger(logger)` then `os.read_entire_file_from_path` to verify output.
+- **`fmt.sbprintf` writes directly to a `strings.Builder`.** Prefer `fmt.sbprintf(&sb, fmt, args...)` over `fmt.aprintf(fmt, args...)` + `defer delete` + `strings.write_string`. The `aprintf` pattern allocates an intermediate string, requires manual cleanup, and queues a `defer delete` per loop iteration. `sbprintf` avoids all of this.
 
 ## TODO
 

TODOS.md

@@ -1,6 +1,7 @@
 ## High priority
 
 - Polish existing features before moving on to new ones.
+- [ ] Do mustache's whitespace rules actually suit us, or should we make our own? 
 - [x] `{{>title}}` default partial? `{{site.title}} | {{ page.title }}`
 - [ ] implicit titles (Set when missing?)
 - [ ] create a default `head.html`.
@@ -12,6 +13,8 @@
 - [ ] [aliases](https://gohugo.io/methods/page/aliases/#redirects)?
 - [ ] Improve diagnostics
   - [x] keep track of every error and don't report them more than once.
+  - [ ] show parsed arg when -extension is unrecognized 
+    - [ ] also do typo detection?
   - [ ] `*` make sure the frontmatter parser has good diagnostics.
   - [ ] fix the diagnostics in [DIAGNOSTIC TODOS](./DIAGNOSTIC_TODOS.yaml)
   - [ ] only report format errors once.
@@ -105,12 +108,19 @@
 
 ## Markdown
 - [ ] Add overloads for every extension - accept ^strings.Builder.
-- [ ] Add conventional (Hugo style) footnotes option.
-- [ ] Add opt-in deflist support.
+- [x] Add conventional (Hugo style) footnotes option.
+- [x] Add opt-in deflist support.
 - [x] Decide if lambdas actually provide any value.
 - [ ] add tables extension
+- [x] Table of contents support.
+  - [ ] enable template level rendering of TOCs
+  - [ ] Write css for toc sidebar and figure out where to put it.
+  - [ ] Add [hugo style configuration](https://gohugo.io/configuration/markup/#table-of-contents)
+- [ ] Link checker?
+  - Checks all links on each page to make sure they are valid.
 - [ ] Peruse [GitHub's](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)
       docs for any juicy nuggets we may have missed.
+- [ ] Avoid using `render_inline_md` if possible.
 
 ## Dates
 - [ ] display an error when no part of the date appears in the output.
@@ -193,7 +203,6 @@ main :: proc () {
 - [ ] include-code shortcode (`{{< include-code ... >}}`) — i-ported-fd-to-odin
 - [ ] follow symlinks in `scan_content`?
 - [ ] ensure sidenote numbers render in display order and not in declaration order.
-- [ ] Table of contents support.
 - [ ] Nav items should be active when the current page is selected.
 - [ ] Theme selector for syntax highlighting.
   - use http://github.com/helix-editor/helix/tree/master/runtime/themes) as a

content.odin

@@ -28,6 +28,7 @@ Page :: struct {
 	content:     string,
 	og:          Open_Graph,
 	draft:       bool,
+	toc:         string,
 	_is_index:   bool `private`,
 }
 
@@ -280,6 +281,10 @@ load_page :: proc(
 		page.content = md.process(body, ext, file_path, context.allocator)
 	}
 
+	if fm.toc {
+		page.toc = md.generate_toc(page.content, context.allocator)
+	}
+
 	ok = true
 	return
 }

defaults/layouts/base.html

@@ -6,7 +6,8 @@
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>{{> title}}</title>
   {{> opengraph}}
-  {{> styles }}
+  {{> styles}}
+  {{> scripts}}
 </head>
 
 <body>

defaults/layouts/page.html

@@ -3,8 +3,13 @@
 <main>
   <article>
     <h1>{{page.title}}</h1>
-    {{#date}} <time class="subtitle" datetime="{{date}}">{{ date | format}}</time>
-    {{/date}} {{&content}}
+    {{#date}}<time class="subtitle" datetime="{{date}}">{{ date | format}}</time>{{/date}}
+    {{#page.toc}}
+    <nav class="toc">
+    {{&page.toc}}
+    </nav>
+    {{/page.toc}}
+    {{&content}}
   </article>
 </main>
 {{/main}}

defaults/layouts/partials/scripts.html

@@ -0,0 +1 @@
+{{params.scripts}}

defaults/layouts/partials/styles.html

@@ -1 +1,223 @@
+<style>
+/* Base layout */
+body {
+  margin-left: auto;
+  margin-right: auto;
+}
+
+main {
+  max-width: 760px;
+  margin: 0 auto;
+}
+
+/* Sidenote layout — activates only when sidenote elements are present */
+body:has(.sidenote, .marginnote) {
+  counter-reset: sidenote-counter;
+  padding-left: 12.5%;
+  width: 87.5%;
+}
+
+body:has(.sidenote, .marginnote) main {
+  max-width: none;
+  width: 60%;
+  margin: 0;
+}
+
+/* Images */
+img {
+  max-width: 100%;
+  height: auto;
+}
+
+/* Superscript (footnote refs) */
+sup {
+  line-height: 0;
+}
+
+/* Code blocks */
+code,
+pre>code {
+  font-family: Consolas, "Liberation Mono", Menlo, Courier, monospace;
+  font-size: 1.0rem;
+  line-height: 1.42;
+  -webkit-text-size-adjust: 100%;
+}
+
+pre>code {
+  font-size: 0.9rem;
+  overflow-x: auto;
+  display: block;
+}
+
+/* Alerts (GitHub-style) */
+.alert {
+  border-left: 4px solid;
+  border-radius: 0 4px 4px 0;
+  padding: 0.5rem 1rem;
+  margin-inline-start: 0;
+}
+
+.alert-title {
+  font-weight: bold;
+  margin-bottom: 0.25rem;
+  margin-top: 0.25rem;
+}
+
+.alert-note {
+  border-left-color: #3b82f6;
+}
+
+.alert-tip {
+  border-left-color: #22c55e;
+}
+
+.alert-important {
+  border-left-color: #a855f7;
+}
+
+.alert-warning {
+  border-left-color: #eab308;
+}
+
+.alert-caution {
+  border-left-color: #ef4444;
+}
+
+/* Definition lists */
+dl,
+ol,
+ul {
+  font-size: 1.4rem;
+  line-height: 2rem;
+}
+
+dt:not(:first-child) {
+  margin-top: 0.25rem;
+}
+
+dd {
+  margin-left: 0;
+}
+
+/* Sidenotes, margin notes */
+.sidenote,
+.marginnote {
+  float: right;
+  clear: right;
+  margin-right: -45%;
+  width: 40%;
+  margin-top: 0.3rem;
+  margin-bottom: 0;
+  font-size: 0.85em;
+  line-height: 1.5;
+  vertical-align: baseline;
+  position: relative;
+}
+
+.sidenote-number {
+  counter-increment: sidenote-counter;
+}
+
+.sidenote-number:after,
+.sidenote:before {
+  position: relative;
+  vertical-align: baseline;
+  color: var(--color-accent, currentColor);
+}
+
+.sidenote-number:after {
+  content: counter(sidenote-counter);
+  font-size: 0.8rem;
+  top: -0.5rem;
+  left: 0.1rem;
+}
+
+.sidenote:before {
+  content: counter(sidenote-counter) " ";
+  font-size: 0.8rem;
+  top: -0.5rem;
+}
+
+blockquote .sidenote,
+blockquote .marginnote {
+  margin-right: -82%;
+  min-width: 59%;
+  text-align: left;
+}
+
+.marginnote>code,
+.sidenote>code {
+  font-size: 1rem;
+}
+
+input.margin-toggle {
+  display: none;
+}
+
+label.sidenote-number {
+  display: inline-block;
+  max-height: 2rem;
+}
+
+label.margin-toggle:not(.sidenote-number) {
+  display: none;
+}
+
+/* Responsive */
+@media (max-width: 1200px) {
+  body {
+    padding-left: 1rem;
+    padding-right: 1rem;
+  }
+
+  body:has(.sidenote, .marginnote) {
+    padding-left: 8%;
+    padding-right: 8%;
+    width: 84%;
+  }
+
+  body:has(.sidenote, .marginnote) main {
+    width: 100%;
+    max-width: 760px;
+    margin: 0 auto;
+  }
+
+  pre>code {
+    width: 97%;
+  }
+
+  img {
+    width: 100%;
+  }
+
+  label.margin-toggle:not(.sidenote-number) {
+    display: inline;
+  }
+
+  label.margin-toggle:not(.sidenote-number)::after {
+    content: "\2295";
+  }
+
+  .sidenote,
+  .marginnote {
+    display: none;
+  }
+
+  .margin-toggle:checked+.sidenote,
+  .margin-toggle:checked+.marginnote {
+    display: block;
+    float: left;
+    left: 1rem;
+    clear: both;
+    width: 95%;
+    margin: 1rem 2.5%;
+    vertical-align: baseline;
+    position: relative;
+  }
+
+  label {
+    cursor: pointer;
+  }
+}
+</style>
 {{#params.stylesheets}}<link rel="stylesheet" href="{{.}}">{{/params.stylesheets}}

feed.odin

@@ -7,10 +7,9 @@ import "core:time"
 generate_rss :: proc(site: ^Site) -> string {
 	sb := strings.builder_make()
 
-	strings.write_string(
+	fmt.sbprintf(
 		&sb,
-		fmt.aprintf(
-			`<?xml version="1.0" encoding="utf-8" standalone="yes"?>
+		`<?xml version="1.0" encoding="utf-8" standalone="yes"?>
 <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
 <channel>
 <title>%s</title>
@@ -18,11 +17,10 @@ generate_rss :: proc(site: ^Site) -> string {
 <description>%s</description>
 <language>en-us</language>
 <atom:link href="%s/index.xml" rel="self" type="application/rss+xml"/>`,
-			xml_escape(site.title),
-			site.base_url,
-			xml_escape(site.description),
-			site.base_url,
-		),
+		xml_escape(site.title),
+		site.base_url,
+		xml_escape(site.description),
+		site.base_url,
 	)
 
 	for page in site.pages {
@@ -35,10 +33,9 @@ generate_rss :: proc(site: ^Site) -> string {
 			pub_date = format_rfc822(page.date)
 		}
 
-		strings.write_string(
+		fmt.sbprintf(
 			&sb,
-			fmt.aprintf(
-				`<item>
+			`<item>
 <title>%s</title>
 <link>%s</link>
 <pubDate>%s</pubDate>
@@ -46,12 +43,11 @@ generate_rss :: proc(site: ^Site) -> string {
 <description>%s</description>
 </item>
 `,
-				xml_escape(page.title),
-				page.url,
-				pub_date,
-				page.url,
-				xml_escape(page.content),
-			),
+			xml_escape(page.title),
+			page.url,
+			pub_date,
+			page.url,
+			xml_escape(page.content),
 		)
 	}
 
@@ -70,11 +66,11 @@ generate_sitemap :: proc(site: ^Site) -> string {
 	)
 
 	for page in site.pages {
-		lastmod := ""
+		fmt.sbprintf(&sb, "<url><loc>%s</loc>", page.url)
 		if page.date != "" {
-			lastmod = fmt.aprintf("<lastmod>%s</lastmod>", page.date)
+			fmt.sbprintf(&sb, "<lastmod>%s</lastmod>", page.date)
 		}
-		strings.write_string(&sb, fmt.aprintf("<url><loc>%s</loc>%s</url>\n", page.url, lastmod))
+		fmt.sbprintf(&sb, "</url>\n")
 	}
 
 	// Section index pages (for sections without an index in content)
@@ -103,14 +99,11 @@ generate_sitemap :: proc(site: ^Site) -> string {
 				section_lastmod = page.date
 			}
 		}
-		lm := ""
+		fmt.sbprintf(&sb, "<url><loc>%s/%s/</loc>", site.base_url, section)
 		if section_lastmod != "" {
-			lm = fmt.aprintf("<lastmod>%s</lastmod>", section_lastmod)
+			fmt.sbprintf(&sb, "<lastmod>%s</lastmod>", section_lastmod)
 		}
-		strings.write_string(
-			&sb,
-			fmt.aprintf("<url><loc>%s/%s/</loc>%s</url>\n", site.base_url, section, lm),
-		)
+		fmt.sbprintf(&sb, "</url>\n")
 	}
 
 	strings.write_string(&sb, "</urlset>")

flake.nix

@@ -158,6 +158,7 @@
               tree-sitter
 
               gdb
+              perf
 
               # IDE
               unstable.helix

frontmatter.odin

@@ -16,6 +16,7 @@ Frontmatter :: struct {
 	layout:      string,
 	og:          Open_Graph,
 	draft:       bool,
+	toc:         bool,
 }
 
 // parse_frontmatter splits raw file content into a Frontmatter struct and the
@@ -56,6 +57,7 @@ parse_frontmatter :: proc(content: string) -> (fm: Frontmatter, body: string, ok
 	fm.publishDate = json_get_string(obj, "publishDate")
 	fm.weight = json_get_int(obj, "weight")
 	fm.draft = json_get_bool(obj, "draft")
+	fm.toc = json_get_bool(obj, "toc")
 	if v, ok := obj["menus"]; ok {
 		fm.menus = v
 	}

markdown/deflists.odin

@@ -0,0 +1,197 @@
+package markdown
+
+import cm "vendor:commonmark"
+
+import "core:strings"
+
+// DefList_Entry represents a single term-definition pair in a definition list.
+DefList_Entry :: struct {
+	term:       string,
+	definition: string,
+}
+
+// convert_deflists scans markdown text for definition list patterns and
+// converts them to <dl><dt><dd> HTML blocks before cmark processing.
+//
+// A definition line starts with optional whitespace followed by a colon and
+// a space. The term is the nearest preceding non-blank line (immediately or
+// within one blank line). Consecutive term+definition pairs are grouped into
+// a single <dl> block.
+//
+// Terms and definitions are rendered through cmark individually so that
+// inline markdown (code, links, emphasis) is processed.
+convert_deflists :: proc(body: string, allocator := context.allocator) -> string {
+	lines := strings.split(body, "\n", allocator = context.temp_allocator)
+
+	sb := strings.builder_make(context.temp_allocator)
+
+	first := true
+	need_blank := false
+
+	i := 0
+	for i < len(lines) {
+		entries, matched, next := try_match_deflist(lines, i)
+		if matched {
+			html := render_deflist(entries)
+			if !first {
+				strings.write_string(&sb, "\n\n")
+			}
+			strings.write_string(&sb, html)
+			first = false
+			need_blank = true
+			i = next
+			continue
+		}
+
+		if need_blank {
+			strings.write_string(&sb, "\n\n")
+			need_blank = false
+		} else if !first {
+			strings.write_string(&sb, "\n")
+		}
+		strings.write_string(&sb, lines[i])
+		first = false
+		i += 1
+	}
+
+	return strings.clone(strings.to_string(sb), allocator)
+}
+
+// try_match_deflist attempts to match a definition list group starting at
+// lines[start]. A group is one or more term+definition pairs. Returns the
+// matched entries, whether a match was found, and the index past the group.
+try_match_deflist :: proc(
+	lines: []string,
+	start: int,
+) -> (
+	entries: [dynamic]DefList_Entry,
+	ok: bool,
+	end: int,
+) {
+	entries = make([dynamic]DefList_Entry, 0, allocator = context.temp_allocator)
+	end = start
+
+	i := start
+	for i < len(lines) {
+		// A term must be non-blank and not itself a def line
+		if is_blank_line(lines[i]) || is_def_line(lines[i]) {
+			break
+		}
+
+		// Look for a def line: immediately after or with one blank line
+		def_idx := i + 1
+		if def_idx < len(lines) && is_blank_line(lines[def_idx]) {
+			def_idx += 1
+		}
+
+		if def_idx >= len(lines) || !is_def_line(lines[def_idx]) {
+			break
+		}
+
+		// Found a term + def pair
+		append(
+			&entries,
+			DefList_Entry {
+				term = strings.trim_space(lines[i]),
+				definition = def_content(lines[def_idx]),
+			},
+		)
+		i = def_idx + 1
+
+		// After a pair, check if another pair follows (optionally
+		// separated by one blank line). If so, continue the group.
+		// If not, break without consuming the blank line.
+		if i < len(lines) && is_blank_line(lines[i]) {
+			after_blank := i + 1
+			if after_blank < len(lines) &&
+			   !is_blank_line(lines[after_blank]) &&
+			   !is_def_line(lines[after_blank]) {
+				// Check whether a def follows this potential term
+				check_def := after_blank + 1
+				if check_def < len(lines) && is_blank_line(lines[check_def]) {
+					check_def += 1
+				}
+				if check_def < len(lines) && is_def_line(lines[check_def]) {
+					i = after_blank
+					continue
+				}
+			}
+			break
+		}
+	}
+
+	if len(entries) > 0 {
+		ok = true
+		end = i
+	}
+	return
+}
+
+// is_def_line returns true if the line is a definition line:
+// optional leading whitespace, a colon, then whitespace or end-of-line.
+is_def_line :: proc(line: string) -> bool {
+	trimmed := strings.trim_left(line, " \t")
+	if len(trimmed) < 1 || trimmed[0] != ':' {
+		return false
+	}
+	if len(trimmed) == 1 {
+		return true
+	}
+	return trimmed[1] == ' ' || trimmed[1] == '\t'
+}
+
+// def_content extracts the definition text from a definition line,
+// stripping the leading colon and surrounding whitespace.
+def_content :: proc(line: string) -> string {
+	trimmed := strings.trim_left(line, " \t")
+	content := trimmed[1:]
+	content = strings.trim_left(content, " \t")
+	return content
+}
+
+// is_blank_line returns true for empty or whitespace-only lines.
+is_blank_line :: proc(line: string) -> bool {
+	return strings.trim_space(line) == ""
+}
+
+// render_deflist builds the <dl> HTML block from a list of entries.
+// Each term and definition is rendered through cmark to process inline
+// markdown. Result lives in context.temp_allocator.
+render_deflist :: proc(entries: [dynamic]DefList_Entry) -> string {
+	sb := strings.builder_make(context.temp_allocator)
+
+	strings.write_string(&sb, "<dl>")
+	for entry in entries {
+		term_html := render_inline_md(entry.term)
+		def_html := render_inline_md(entry.definition)
+		strings.write_string(&sb, "<dt>")
+		strings.write_string(&sb, term_html)
+		strings.write_string(&sb, "</dt><dd>")
+		strings.write_string(&sb, def_html)
+		strings.write_string(&sb, "</dd>")
+	}
+	strings.write_string(&sb, "</dl>")
+
+	return strings.to_string(sb)
+}
+
+// render_inline_md renders a snippet of markdown through cmark and strips
+// the surrounding <p> tags. Result lives in context.temp_allocator.
+render_inline_md :: proc(text: string) -> string {
+	raw := cm.markdown_to_html_from_string(text, {.Unsafe})
+	defer cm.free_string(raw)
+	return strings.clone(strip_p_tags(raw), context.temp_allocator)
+}
+
+// strip_p_tags removes surrounding <p></p> if the HTML is a single paragraph.
+strip_p_tags :: proc(html: string) -> string {
+	s := html
+	if len(s) > 0 && s[len(s) - 1] == '\n' {
+		s = s[:len(s) - 1]
+	}
+	if strings.has_prefix(s, "<p>") && strings.has_suffix(s, "</p>") {
+		return s[3:len(s) - 4]
+	}
+	return s
+}
+

markdown/deflists_test.odin

@@ -0,0 +1,104 @@
+#+test
+package markdown
+
+import "core:strings"
+import "core:testing"
+
+@(test)
+test_single_entry :: proc(t: ^testing.T) {
+	input := "term\n\n: definition"
+	result := convert_deflists(input, context.temp_allocator)
+	expected := "<dl><dt>term</dt><dd>definition</dd></dl>"
+	testing.expect_value(t, result, expected)
+}
+
+@(test)
+test_single_entry_no_blank :: proc(t: ^testing.T) {
+	input := "term\n: definition"
+	result := convert_deflists(input, context.temp_allocator)
+	expected := "<dl><dt>term</dt><dd>definition</dd></dl>"
+	testing.expect_value(t, result, expected)
+}
+
+@(test)
+test_indented_variant :: proc(t: ^testing.T) {
+	input := " term\n : definition"
+	result := convert_deflists(input, context.temp_allocator)
+	expected := "<dl><dt>term</dt><dd>definition</dd></dl>"
+	testing.expect_value(t, result, expected)
+}
+
+@(test)
+test_multiple_entries :: proc(t: ^testing.T) {
+	input := "t1\n\n: d1\n\nt2\n\n: d2"
+	result := convert_deflists(input, context.temp_allocator)
+	expected := "<dl><dt>t1</dt><dd>d1</dd><dt>t2</dt><dd>d2</dd></dl>"
+	testing.expect_value(t, result, expected)
+}
+
+@(test)
+test_mixed_indented_and_non_indented :: proc(t: ^testing.T) {
+	input := "t1\n\n: d1\n\n t2\n : d2\n\nt3\n\n: d3"
+	result := convert_deflists(input, context.temp_allocator)
+	expected := "<dl><dt>t1</dt><dd>d1</dd><dt>t2</dt><dd>d2</dd><dt>t3</dt><dd>d3</dd></dl>"
+	testing.expect_value(t, result, expected)
+}
+
+@(test)
+test_inline_markdown_in_term :: proc(t: ^testing.T) {
+	input := "`code`\n\n: def"
+	result := convert_deflists(input, context.temp_allocator)
+	expected := "<dl><dt><code>code</code></dt><dd>def</dd></dl>"
+	testing.expect_value(t, result, expected)
+}
+
+@(test)
+test_inline_markdown_in_definition :: proc(t: ^testing.T) {
+	input := "term\n\n: see [Content](#content) here"
+	result := convert_deflists(input, context.temp_allocator)
+	testing.expect(t, strings.contains(result, `<a href="#content">Content</a>`))
+	testing.expect(t, strings.contains(result, "<dd>see "))
+	testing.expect(t, strings.contains(result, "</dd>"))
+}
+
+@(test)
+test_regular_text_passes_through :: proc(t: ^testing.T) {
+	input := "This is: not a deflist"
+	result := convert_deflists(input, context.temp_allocator)
+	testing.expect_value(t, result, input)
+}
+
+@(test)
+test_colon_inside_paragraph_no_false_positive :: proc(t: ^testing.T) {
+	input := "First paragraph.\n\nSecond paragraph."
+	result := convert_deflists(input, context.temp_allocator)
+	testing.expect_value(t, result, input)
+}
+
+@(test)
+test_deflist_between_paragraphs :: proc(t: ^testing.T) {
+	input := "Before.\n\nterm\n\n: def\n\nAfter."
+	result := convert_deflists(input, context.temp_allocator)
+	testing.expect(t, strings.has_prefix(result, "Before."))
+	testing.expect(t, strings.contains(result, "<dl><dt>term</dt><dd>def</dd></dl>"))
+	testing.expect(t, strings.has_suffix(result, "After."))
+}
+
+@(test)
+test_empty_body :: proc(t: ^testing.T) {
+	result := convert_deflists("", context.temp_allocator)
+	testing.expect_value(t, result, "")
+}
+
+@(test)
+test_docs_md_pattern :: proc(t: ^testing.T) {
+	input := "content\n\n: `content` holds your pages.\n\n assets\n : `assets` contains files."
+	result := convert_deflists(input, context.temp_allocator)
+	testing.expect(t, strings.contains(result, "<dl>"))
+	testing.expect(t, strings.contains(result, "<dt>content</dt>"))
+	testing.expect(t, strings.contains(result, "<dt>assets</dt>"))
+	testing.expect(t, strings.contains(result, "<code>content</code>"))
+	testing.expect(t, strings.contains(result, "<code>assets</code>"))
+	testing.expect(t, strings.contains(result, "</dl>"))
+}
+

markdown/emoji_test.odin

@@ -30,3 +30,4 @@ test_emoji_skips_invalid_shortcodes :: proc(t: ^testing.T) {
 	testing.expect_value(t, expand_emoji(":Smile:"), ":Smile:")
 	testing.expect_value(t, expand_emoji(": not real :"), ": not real :")
 }
+

markdown/footnotes.odin

@@ -1,7 +1,5 @@
 package markdown
 
-import cm "vendor:commonmark"
-
 import "core:fmt"
 import "core:strings"
 
@@ -171,28 +169,27 @@ inject_notes :: proc(html: string, sn_defs, mn_defs: map[string]string) -> strin
 		}
 
 		// Render definition through cmark for markdown support
-		raw_html := cm.markdown_to_html_from_string(def_text, {.Unsafe})
-		defer cm.free_string(raw_html)
-		def_html := strip_p_tags(raw_html)
+		def_html := render_inline_md(def_text)
 
 		note: string
 		defer delete(note)
 		if is_margin {
-			note = fmt.aprintf(
+			fmt.sbprintf(
+				&parts,
 				`<label for="mn-%s" class="margin-toggle"></label><input type="checkbox" id="mn-%s" class="margin-toggle"><span class="marginnote">%s</span>`,
 				id,
 				id,
 				def_html,
 			)
 		} else {
-			note = fmt.aprintf(
+			fmt.sbprintf(
+				&parts,
 				`<label for="fn-%s" class="margin-toggle sidenote-number"></label><input type="checkbox" id="fn-%s" class="margin-toggle"><span class="sidenote">%s</span>`,
 				id,
 				id,
 				def_html,
 			)
 		}
-		strings.write_string(&parts, note)
 
 		remaining = remaining[ref_end:]
 	}
@@ -200,15 +197,98 @@ inject_notes :: proc(html: string, sn_defs, mn_defs: map[string]string) -> strin
 	return strings.to_string(parts)
 }
 
-// strip_p_tags removes surrounding <p></p> if the HTML is a single paragraph.
-strip_p_tags :: proc(html: string) -> string {
-	s := html
-	if len(s) > 0 && s[len(s) - 1] == '\n' {
-		s = s[:len(s) - 1]
+// inject_footnotes finds [^id] and [*id] references in rendered HTML, numbers
+// them sequentially by order of appearance, and replaces them with <sup> links.
+// Appends a <section class="footnotes"><ol> at the end with definitions.
+// Both sidenote ([^id]) and marginnote ([*id]) references are treated equally.
+inject_footnotes :: proc(html: string, sn_defs, mn_defs: map[string]string) -> string {
+	if len(sn_defs) == 0 && len(mn_defs) == 0 {
+		return html
 	}
-	if strings.has_prefix(s, "<p>") && strings.has_suffix(s, "</p>") {
-		return s[3:len(s) - 4]
+
+	parts: strings.Builder
+	strings.builder_init_len(&parts, 0)
+	defer strings.builder_destroy(&parts)
+
+	number_of: map[string]int = make(map[string]int, allocator = context.temp_allocator)
+	ordered_ids: [dynamic]string = make([dynamic]string, 0, allocator = context.temp_allocator)
+	next_num := 1
+
+	remaining := html
+
+	for {
+		sn_pos := strings.index(remaining, "[^")
+		mn_pos := strings.index(remaining, "[*")
+
+		is_margin := mn_pos >= 0 && (sn_pos < 0 || mn_pos < sn_pos)
+		pos := sn_pos
+		if is_margin {
+			pos = mn_pos
+		}
+		if pos < 0 {
+			strings.write_string(&parts, remaining)
+			break
+		}
+
+		strings.write_string(&parts, remaining[:pos])
+
+		close := strings.index(remaining[pos + 2:], "]")
+		if close < 0 {
+			strings.write_string(&parts, remaining[pos:])
+			break
+		}
+
+		id := remaining[pos + 2:pos + 2 + close]
+		ref_end := pos + 2 + close + 1
+
+		defs := sn_defs
+		if is_margin {
+			defs = mn_defs
+		}
+		def_text, found := defs[id]
+		if !found {
+			strings.write_string(&parts, remaining[pos:ref_end])
+			remaining = remaining[ref_end:]
+			continue
+		}
+
+		num, seen := number_of[id]
+		if !seen {
+			num = next_num
+			number_of[id] = num
+			next_num += 1
+			append(&ordered_ids, id)
+		}
+
+		fmt.sbprintf(&parts, `<sup><a href="#fn-%d" id="fnref-%d">%d</a></sup>`, num, num, num)
+
+		remaining = remaining[ref_end:]
 	}
-	return s
+
+	if len(ordered_ids) > 0 {
+		strings.write_string(&parts, "\n<section class=\"footnotes\">\n<hr>\n<ol>\n")
+		for id in ordered_ids {
+			def_text, ok := sn_defs[id]
+			if !ok {
+				def_text, ok = mn_defs[id]
+			}
+			if !ok do continue
+
+			def_html := render_inline_md(def_text)
+			num := number_of[id]
+
+			fmt.sbprintf(
+				&parts,
+				`<li id="fn-%d">%s <a href="#fnref-%d" class="footnote-backref">↩︎</a></li>` +
+				"\n",
+				num,
+				def_html,
+				num,
+			)
+		}
+		strings.write_string(&parts, "</ol>\n</section>")
+	}
+
+	return strings.to_string(parts)
 }
 

markdown/footnotes_test.odin

@@ -119,3 +119,102 @@ test_inject_notes_missing_ref :: proc(t: ^testing.T) {
 	testing.expect(t, strings.contains(out, "[^missing]"))
 	testing.expect(t, strings.contains(out, "[*missing]"))
 }
+
+@(test)
+test_inject_footnotes_basic :: proc(t: ^testing.T) {
+	html := "Text[^a] end."
+	sn := map[string]string {
+		"a" = "a footnote",
+	}
+	defer delete_map(sn)
+	mn := make(map[string]string)
+	defer delete_map(mn)
+
+	out := inject_footnotes(html, sn, mn)
+
+	testing.expect(t, strings.contains(out, `<sup><a href="#fn-1" id="fnref-1">1</a></sup>`))
+	testing.expect(t, strings.contains(out, `<li id="fn-1">a footnote`))
+	testing.expect(t, strings.contains(out, `class="footnote-backref"`))
+	testing.expect(t, strings.contains(out, `<section class="footnotes">`))
+	testing.expect(t, strings.contains(out, "</section>"))
+}
+
+@(test)
+test_inject_footnotes_numbered_by_appearance :: proc(t: ^testing.T) {
+	html := "Second[^b] then first[^a]."
+	sn := map[string]string {
+		"a" = "def a",
+		"b" = "def b",
+	}
+	defer delete_map(sn)
+	mn := make(map[string]string)
+	defer delete_map(mn)
+
+	out := inject_footnotes(html, sn, mn)
+
+	// b appears first in the text → 1, a → 2
+	testing.expect(t, strings.contains(out, `id="fnref-1">1</a></sup>`))
+	testing.expect(t, strings.contains(out, `id="fnref-2">2</a></sup>`))
+	testing.expect(t, strings.contains(out, `<li id="fn-1">def b`))
+	testing.expect(t, strings.contains(out, `<li id="fn-2">def a`))
+}
+
+@(test)
+test_inject_footnotes_marginnote_treated_same :: proc(t: ^testing.T) {
+	html := "Sidenote[^a] and marginnote[*b]."
+	sn := map[string]string {
+		"a" = "sn def",
+	}
+	defer delete_map(sn)
+	mn := map[string]string {
+		"b" = "mn def",
+	}
+	defer delete_map(mn)
+
+	out := inject_footnotes(html, sn, mn)
+
+	// Both get numbered as regular footnotes
+	testing.expect(t, strings.contains(out, `id="fnref-1">1</a></sup>`))
+	testing.expect(t, strings.contains(out, `id="fnref-2">2</a></sup>`))
+	testing.expect(t, strings.contains(out, `<li id="fn-1">sn def`))
+	testing.expect(t, strings.contains(out, `<li id="fn-2">mn def`))
+}
+
+@(test)
+test_inject_footnotes_no_defs :: proc(t: ^testing.T) {
+	html := "No notes here."
+	sn := make(map[string]string)
+	mn := make(map[string]string)
+	testing.expect(t, inject_footnotes(html, sn, mn) == html)
+}
+
+@(test)
+test_inject_footnotes_missing_def :: proc(t: ^testing.T) {
+	html := "Ref[^missing] end."
+	sn := map[string]string {
+		"other" = "x",
+	}
+	defer delete_map(sn)
+	mn := make(map[string]string)
+	defer delete_map(mn)
+
+	out := inject_footnotes(html, sn, mn)
+
+	testing.expect(t, strings.contains(out, "[^missing]"))
+	testing.expect(t, !strings.contains(out, "<section"))
+}
+
+@(test)
+test_inject_footnotes_inline_markdown :: proc(t: ^testing.T) {
+	html := "Text[^a] end."
+	sn := map[string]string {
+		"a" = "see [link](http://example.com) here",
+	}
+	defer delete_map(sn)
+	mn := make(map[string]string)
+	defer delete_map(mn)
+
+	out := inject_footnotes(html, sn, mn)
+
+	testing.expect(t, strings.contains(out, `<a href="http://example.com">link</a>`))
+}

markdown/markdown.odin

@@ -3,6 +3,7 @@ package markdown
 import cm "vendor:commonmark"
 
 import "core:encoding/json"
+import "core:log"
 import "core:strings"
 
 Extension :: enum {
@@ -12,9 +13,11 @@ Extension :: enum {
 	Highlight,
 	Sections,
 	HeadingIDs,
+	DefLists,
+	Footnotes,
 }
 
-DEFAULT_EXTENSIONS :: bit_set[Extension]{.Emoji, .Sidenotes, .Alerts, .HeadingIDs}
+DEFAULT_EXTENSIONS :: bit_set[Extension]{.Emoji, .Sidenotes, .Alerts, .HeadingIDs, .DefLists}
 
 // Caller is responsible for freeing string
 process :: proc(
@@ -26,9 +29,12 @@ process :: proc(
 	side_notes := make(map[string]string)
 	margin_notes := make(map[string]string)
 	clean_body := body
-	if .Sidenotes in ext {
+	if .Sidenotes in ext || .Footnotes in ext {
 		clean_body, side_notes, margin_notes = strip_definitions(body)
 	}
+	if .DefLists in ext {
+		clean_body = convert_deflists(clean_body, allocator)
+	}
 	original_html := cm.markdown_to_html_from_string(clean_body, {.Unsafe})
 	html := strings.clone(original_html, allocator)
 	cm.free_string(original_html)
@@ -36,7 +42,9 @@ process :: proc(
 	if .Emoji in ext {
 		html = expand_emoji(html)
 	}
-	if .Sidenotes in ext {
+	if .Footnotes in ext {
+		html = inject_footnotes(html, side_notes, margin_notes)
+	} else if .Sidenotes in ext {
 		html = inject_notes(html, side_notes, margin_notes)
 	}
 	if .Alerts in ext {
@@ -58,20 +66,14 @@ process :: proc(
 parse_extension_list :: proc(s: string) -> (result: bit_set[Extension]) {
 	for part in strings.split(s, ",", allocator = context.temp_allocator) {
 		name := strings.to_lower(strings.trim_space(part), allocator = context.temp_allocator)
-		switch name {
-		case "emoji":
-			result += {.Emoji}
-		case "sidenotes":
-			result += {.Sidenotes}
-		case "alerts":
-			result += {.Alerts}
-		case "highlight":
-			result += {.Highlight}
-		case "sections":
-			result += {.Sections}
-		case "heading_ids":
-			result += {.HeadingIDs}
+		e, ok := extension_from_name(name)
+		if !ok {
+			if name != "" {
+				log.warnf("unknown extension '%s'", name)
+			}
+			continue
 		}
+		result += {e}
 	}
 	return result
 }
@@ -81,20 +83,48 @@ apply_extension_config :: proc(ext: ^bit_set[Extension], config: json.Object) {
 	for name, val in config {
 		// TODO: Silently discards invalid values.
 		enabled := val.(json.Boolean) or_continue
-		switch name {
-		case "emoji":
-			if enabled {ext^ += {.Emoji}} else {ext^ -= {.Emoji}}
-		case "sidenotes":
-			if enabled {ext^ += {.Sidenotes}} else {ext^ -= {.Sidenotes}}
-		case "alerts":
-			if enabled {ext^ += {.Alerts}} else {ext^ -= {.Alerts}}
-		case "highlight":
-			if enabled {ext^ += {.Highlight}} else {ext^ -= {.Highlight}}
-		case "sections":
-			if enabled {ext^ += {.Sections}} else {ext^ -= {.Sections}}
-		case "heading_ids":
-			if enabled {ext^ += {.HeadingIDs}} else {ext^ -= {.HeadingIDs}}
+		e := extension_from_name(name) or_continue
+
+		if enabled {
+			ext^ += {e}
+		} else {
+			ext^ -= {e}
 		}
 	}
 }
 
+extension_from_name :: proc(name: string) -> (e: Extension, ok: bool) {
+	switch name {
+	case "emoji":
+		e = .Emoji
+		ok = true
+	case "sidenotes":
+		e = .Sidenotes
+	case "alerts":
+		e = .Alerts
+	case "highlight":
+		e = .Highlight
+	case "sections":
+		e = .Sections
+	case "heading_ids":
+		e = .HeadingIDs
+	case "deflists":
+		e = .DefLists
+	case "footnotes":
+		e = .Footnotes
+	case:
+	// Do nothing
+	}
+
+	return e, ok || e != .Emoji
+}
+
+// resolve_extension_conflicts resolves mutually exclusive extensions.
+// Footnotes and Sidenotes share the same [^id] syntax but render differently;
+// if both are enabled (e.g. from defaults + CLI), Footnotes wins.
+resolve_extension_conflicts :: proc(ext: ^bit_set[Extension]) {
+	if .Footnotes in ext^ && .Sidenotes in ext^ {
+		ext^ -= {.Sidenotes}
+	}
+}
+

markdown/toc.odin

@@ -0,0 +1,163 @@
+package markdown
+
+import "core:strings"
+
+// generate_toc scans rendered HTML for <h1>-<h6> tags with id attributes and
+// builds a nested <ul> table of contents. Returns "" if no headings with IDs
+// are found. Must be called after inject_heading_ids.
+generate_toc :: proc(html: string, allocator := context.allocator) -> string {
+	b: strings.Builder
+	strings.builder_init(&b, allocator)
+
+	current_level := 0
+	min_level := 7
+	pos := 0
+
+	for {
+		idx, level, id, text, next_pos := next_heading(html, pos)
+		if level == 0 {
+			break
+		}
+		pos = next_pos
+
+		if level < min_level {
+			min_level = level
+		}
+
+		if current_level == 0 {
+			current_level = level
+			strings.write_string(&b, "<ul>\n")
+		} else if level > current_level {
+			for current_level < level {
+				strings.write_string(&b, "<ul>\n")
+				current_level += 1
+			}
+		} else if level < current_level {
+			strings.write_string(&b, "</li>\n")
+			for current_level > level {
+				strings.write_string(&b, "</ul>\n</li>\n")
+				current_level -= 1
+			}
+		} else {
+			strings.write_string(&b, "</li>\n")
+		}
+
+		strings.write_string(&b, `<li><a href="#`)
+		strings.write_string(&b, id)
+		strings.write_string(&b, `">`)
+		strings.write_string(&b, text)
+		strings.write_string(&b, `</a>`)
+	}
+
+	if current_level == 0 {
+		return ""
+	}
+
+	strings.write_string(&b, "</li>\n")
+	for current_level > min_level {
+		strings.write_string(&b, "</ul>\n</li>\n")
+		current_level -= 1
+	}
+	strings.write_string(&b, "</ul>\n")
+
+	return strings.to_string(b)
+}
+
+// next_heading finds the next <hN> tag with an id attribute starting from pos.
+// Returns level=0 if none found.
+next_heading :: proc(
+	html: string,
+	start: int,
+) -> (
+	idx: int,
+	level: int,
+	id: string,
+	text: string,
+	next_pos: int,
+) {
+	i := start
+	for i + 3 < len(html) {
+		if html[i] == '<' && html[i + 1] == 'h' {
+			d := html[i + 2]
+			if d >= '1' && d <= '6' {
+				level = int(d - '0')
+				idx = i
+				break
+			}
+		}
+		i += 1
+	}
+
+	if level == 0 {
+		return 0, 0, "", "", len(html)
+	}
+
+	// Find end of opening tag
+	tag_end := strings.index_byte(html[idx:], '>')
+	if tag_end < 0 {
+		return 0, 0, "", "", len(html)
+	}
+	tag_end += idx
+
+	// Find id="..." within the tag
+	tag := html[idx:tag_end + 1]
+	id_pos := strings.index(tag, `id="`)
+	if id_pos < 0 {
+		// No id — skip this heading, continue searching
+		return next_heading(html, tag_end + 1)
+	}
+
+	id_start := idx + id_pos + 4
+	id_end_rel := strings.index_byte(html[id_start:], '"')
+	if id_end_rel < 0 {
+		return 0, 0, "", "", len(html)
+	}
+	id = html[id_start:id_start + id_end_rel]
+
+	// Text between > and </hN>
+	text_start := tag_end + 1
+	close_idx := strings.index(html[text_start:], "</h")
+	if close_idx < 0 {
+		return 0, 0, "", "", len(html)
+	}
+	text_end := text_start + close_idx
+	text = strip_tags(html[text_start:text_end])
+
+	// Find end of closing tag
+	next_pos = text_end + close_tag_len(html, text_end)
+
+	return idx, level, id, text, next_pos
+}
+
+// close_tag_len returns the length of the </hN> tag at pos.
+close_tag_len :: proc(html: string, pos: int) -> int {
+	if pos + 4 > len(html) {
+		return 4
+	}
+	end := strings.index_byte(html[pos:], '>')
+	if end < 0 {
+		return 4
+	}
+	return end + 1
+}
+
+// strip_tags removes HTML tags from a string, leaving only text content.
+strip_tags :: proc(s: string) -> string {
+	b: strings.Builder
+	strings.builder_init(&b, context.temp_allocator)
+
+	i := 0
+	for i < len(s) {
+		if s[i] == '<' {
+			end := strings.index_byte(s[i:], '>')
+			if end >= 0 {
+				i += end + 1
+				continue
+			}
+		}
+		strings.write_byte(&b, s[i])
+		i += 1
+	}
+	return strings.to_string(b)
+}
+

mustache/diagnostic.odin

@@ -227,7 +227,7 @@ format_error :: proc(
 	}
 	strings.write_string(&sb, "--> ")
 	strings.write_string(&sb, reset)
-	strings.write_string(&sb, fmt.tprintf("%s:%d:%d\n", path, line, col))
+	fmt.sbprintf(&sb, "%s:%d:%d\n", path, line, col)
 
 	// Top gutter line.
 	write_gutter(&sb, width, faint, reset)

mustache/format.odin

@@ -129,12 +129,12 @@ match_token :: proc(b: ^strings.Builder, dt: Date_Components, s: string) -> int
 	if strings.has_prefix(
 		s,
 		"January",
-	) {strings.write_string(b, fmt.tprintf("%s", time.Month(dt.month))); return 7}
+	) {fmt.sbprintf(b, "%s", time.Month(dt.month)); return 7}
 	if strings.has_prefix(s, "Monday") {emit_weekday(b, dt, full = true); return 6}
 	if strings.has_prefix(
 		s,
 		"2006",
-	) {strings.write_string(b, fmt.tprintf("%04d", dt.year)); return 4}
+	) {fmt.sbprintf(b, "%04d", dt.year); return 4}
 	if strings.has_prefix(s, "MST") {
 		abbr := dt.tz_abbr
 		if len(abbr) == 0 do abbr = "UTC"
@@ -146,37 +146,37 @@ match_token :: proc(b: ^strings.Builder, dt: Date_Components, s: string) -> int
 	if strings.has_prefix(
 		s,
 		"06",
-	) {strings.write_string(b, fmt.tprintf("%02d", dt.year % 100)); return 2}
-	if strings.has_prefix(s, "02") {strings.write_string(b, fmt.tprintf("%02d", dt.day)); return 2}
+	) {fmt.sbprintf(b, "%02d", dt.year % 100); return 2}
+	if strings.has_prefix(s, "02") {fmt.sbprintf(b, "%02d", dt.day); return 2}
 	if strings.has_prefix(
 		s,
 		"15",
-	) {strings.write_string(b, fmt.tprintf("%02d", dt.hour)); return 2}
+	) {fmt.sbprintf(b, "%02d", dt.hour); return 2}
 	if strings.has_prefix(
 		s,
 		"04",
-	) {strings.write_string(b, fmt.tprintf("%02d", dt.minute)); return 2}
+	) {fmt.sbprintf(b, "%02d", dt.minute); return 2}
 	if strings.has_prefix(
 		s,
 		"05",
-	) {strings.write_string(b, fmt.tprintf("%02d", dt.second)); return 2}
+	) {fmt.sbprintf(b, "%02d", dt.second); return 2}
 	if strings.has_prefix(
 		s,
 		"01",
-	) {strings.write_string(b, fmt.tprintf("%02d", dt.month)); return 2}
+	) {fmt.sbprintf(b, "%02d", dt.month); return 2}
 	if strings.has_prefix(s, "03") {emit_hour_12(b, dt, pad = true); return 2}
 	if strings.has_prefix(s, "PM") {emit_am_pm(b, dt); return 2}
 	if strings.has_prefix(s, "pm") {emit_am_pm_lower(b, dt); return 2}
 	if len(s) >= 1 {
 		switch s[0] {
 		case '2':
-			strings.write_string(b, fmt.tprintf("%d", dt.day)); return 1
+			fmt.sbprintf(b, "%d", dt.day); return 1
 		case '1':
-			strings.write_string(b, fmt.tprintf("%d", dt.month)); return 1
+			fmt.sbprintf(b, "%d", dt.month); return 1
 		case '4':
-			strings.write_string(b, fmt.tprintf("%d", dt.minute)); return 1
+			fmt.sbprintf(b, "%d", dt.minute); return 1
 		case '5':
-			strings.write_string(b, fmt.tprintf("%d", dt.second)); return 1
+			fmt.sbprintf(b, "%d", dt.second); return 1
 		case '3':
 			emit_hour_12(b, dt, pad = false); return 1
 		case:

site.odin

@@ -243,6 +243,7 @@ site_apply_cli_flags :: proc(site: ^Site, flags: Flags) {
 
 	site.markdown_extensions += md.parse_extension_list(flags.md_enable)
 	site.markdown_extensions -= md.parse_extension_list(flags.md_disable)
+	md.resolve_extension_conflicts(&site.markdown_extensions)
 }
 
 site_allocator :: proc(site: ^Site) -> mem.Allocator {

site/content/docs.md

@@ -1,10 +1,9 @@
 {
   "title": "Docs",
-  "date": "2026-07-22T08:54:00-04:00"
+  "date": "2026-07-22T08:54:00-04:00",
+  "toc": true
 }
 
-[TOC]
-
 ## Introduction
 
 This guide assumes you have either read [The Guide](../guide), or have built a [Hugo](https://gohugo.io) site before. It also assumes you have a basic knowledge of HTML and CSS.
@@ -32,33 +31,37 @@ TODO: Do we minify inline css?
 - syntax highlighting
 - heading ids
 - TODO: Table Of Contents Generation
+- [GitHub style alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)
 
 
 ## Directories
-Like Hugo, a Thor project is a collection of specially named directories, plus a config file. 
+Like Hugo, a Thor project is a collection of specially named directories, plus an optional config file. All directories are optional, but it is recommended to at least have a `content` directory.
 
 content
 
-: `content` holds your pages and page bundles.
-
-layouts
-
-: `layouts` holds your templates and partials. 
+: `content` holds your pages and page bundles. See [Content](#content). If not found, thor will look for content files in the root of your current working directory.
 
  assets
  : `assets` contains any static files for your site (favicon.ico, etc.), as well as files you want to send through the asset pipeline (CSS or JS files). 
+ 
+layouts
+
+: `layouts` holds your templates and partials. See [Templates](#templates).
 
  public
  : `public` will contain your completed site.
 
-All of these names can be remapped in `thor.json`. 
+All of these names can be remapped in `thor.json`.[^remap] 
 
-> [!NOTE] While directories can be remapped at the site level, modules must (currently) adhere to the defaults.
+[^remap]: While directories can be remapped at the site level, modules must (currently) adhere to the defaults.
 
-### Asset pipeline
+### Assets
 
-Currently, there is only one asset processor, and that is [the minifier](#minify). 
+Currently, there is only one asset processor, and that is [the minifier](#minify), though more are planned (i.e. Image processing).
 
+TODO: Expand
+
+## Content
 ### Pages & Page Bundles
 
 Page content can either be defined in a single file (`contact.md`), or in a directory  (`contact/index.md` + `contact/our-team.jpg`). Single file pages are preferred to page bundles.[^1]
@@ -67,21 +70,37 @@ Page content can either be defined in a single file (`contact.md`), or in a dire
 
 Thor currently supports 2 formats for page files: MarkDown (`.md`),  and HTML (`.html`). 
 
-## Templates[^tempmod]
+TODO: Content
 
-[^tempmod]: Template modification is an "advanced" feature, and shoud probably be discussed later in the page. (or possibly in the guide.)
+### Frontmatter
+
+TODO: Frontmatter
+
+## Menus
+
+TODO: Describe
+
+TODO: Don't forget to highlight differences from Hugo.
+
+## Templates
 
 Sites are built using one or more template files written in an extended version of [mustache](https://mustache.github.io) templates. The [mustache manual](https://mustache.github.io/mustache.5.html) has great explainations and a lot of examples if you want to know more, but I'll summarize them for you here.
 
+The beauty of Mustache is that there is very little syntax; there are just 10 symbols you need learn: `{{`, `{{&`, `{{^`, `{{>`, `{{<`, `{{#`, `/}}`, `{{$`, `{{!`, and `|`.
+
+TODO: ^^ Badly worded sentence ^^
+
+TODOS: Gotta describe base templates somewhere. (the same way we describe the partials)
+
 ### Tags
 
 #### Variables
 
-In order do display a scalar (not-list) value in your template, simply wrap it in double curly braces. e.g. `{{ page.title }}`.
+In order to display a scalar (not-list) value in your template, simply wrap it in double curly braces. e.g. `{{ page.title }}`.
 
-This content will be HTML escaped (for safety), so if the value you're rendering contains html, you'll need to use the raw syntex instead `{{& page.title}}` which will output the value without stripping or re-writing content.
+This content will be HTML escaped (for safety), so if the value you're rendering contains HTML, you'll need to use the raw syntex instead `{{& page.title}}`[^raw] which will output the value without stripping or re-writing content.
 
-`{{{ raw }}}` syntax is supported for raw html output, but `{{& raw }}` is preferred, as it's easy to accidentily insert too many braces.
+[^raw]: Official Triple brace syntax (`{{{ raw }}}`) is also supported, but `{{& raw }}` is preferred, as it's easy to accidentily insert too many braces.
 
 In most[^most] cases, invalid keys will be silently ignored (nothing between the braces will appear), in keeping with the official mustache spec.
 
@@ -118,7 +137,7 @@ TODO:
 
 ### Section Names
 
-When building your own templates, you are of course free to pick whatever names you choose for your partials and content slots. However, sticking to conventions helps create consistency in the ecosystem, and reduces friction when relying on a built-in template.
+When building your own templates, you are of course free to pick whatever names you choose for your partials and content slots. However, sticking to conventions helps create consistency in the ecosystem, and reduces friction when relying on built-in templates.
 
 `{{$main}}...{{/main}}`
 
@@ -144,13 +163,6 @@ When building your page(s), the following keys are accessible to your template f
 
 : The Current `DateTime`. see [DateTime](#datetimes)
 
-`title`
-
-: The title of the current page. Unless overridden, it will be expand to
-  `{{ page.title }} | {{ site.title }}`. [^title]
-
-  [^title]: Is there actually a way to overwrite this?
-
 `date_format`
 
 : The default format to use for dates. Configured in `thor.json:date.format`. 
@@ -167,10 +179,16 @@ When building your page(s), the following keys are accessible to your template f
 
 : Returns all regular pages, sorted by `?`. Regular pages exclude index pages like home and section roots.
 
+`posts`
+: TODO: Section groupings
+
 `og`
 
 : Contains the [Open Graph](https://ogp.me/) metadata for the current page.
 
+`menus`
+
+: The site's constructed menus. See [menus](#menus).
 #### Page
 
 `page.content`
@@ -191,6 +209,11 @@ TODO: Write
 
 : The author of the current page or site. See [schema.org](https://schema.org/author) for the recommended format.
 
+`stylesheets`
+
+:  A list of paths to css files the users wants to include globally. These are rendered by the `{{> styles }}` partial, and can be omitted on sites that use custom templates. 
+
+TODO: ^^ Bad sentence? ^^
 
 #### The Context Stack 
 When building your page(s), each template is fed a Context[^ctx] stack that contains all the data should you need to build your page.
@@ -260,7 +283,7 @@ Because mustache is a logic-less language, (there are no `for` or `if` tags), Th
 
 Thor allows you to chain two or more pipes, to allow complex data manipulation. However for performance and stylistic reasons, you are limited to no more than **8 pipes**[^pipes] for any given tag. If you believe you need more than 8 pipes, please [open an issue](../issues) with a **concrete example** of the problem you are facing.
 
-[^pipes]: TODO: THis number must be kept in-sync with `MAX_PIPES`.
+[^pipes]: TODO: This number must be kept in-sync with `MAX_PIPES`.
 
 **Examples:**
 
@@ -275,16 +298,52 @@ Thor allows you to chain two or more pipes, to allow complex data manipulation.
 
 ### Partials
 
-Partials are templates that render a portion of a page. To include a partial, the standard [mustache syntax](https://mustache.github.io/mustache.5.html#Partials) is used. All partials are resolved relative to the root partials directory, so to include a partial at `layouts/partials/my_partial.html`, you would use `{{> my_partial}}`.
+Partials are templates that render a portion of a page. To include a partial, the standard [mustache syntax](https://mustache.github.io/mustache.5.html#Partials) is used. All partials are resolved relative to the root partial's directory, so to include a partial at `layouts/partials/my_partial.html`, you would use `{{> my_partial}}`.
 
 Users can create or override as many partials as they want; several are included for convienience:
 
-`{{> opengraph}}`
+`{{> title }}`
+
+: The title of the current page. It should be placed inside the `<title>` tag. By default, it will appear as `{{ page.title }} | {{ site.title }}`.
+
+`{{> nav }}`
+
+: Nav renders the main menu for the site (`menus.main`). It should be placed inside the `<body>` tag, just before the `<main>` block.
+
+`{{> home-link }}`
+
+: This partial is rendered inside the home anchor in `{{> nav }}`. By default, it wil display the  name of the site, or `Home` if no name is set.
+
+`{{> styles }}`
+
+: This partial renders any stylesheets specified either by the user (via `params.stylesheets`) or by the theme author (specified directly in the template). `params.stylesheets` is intended as an escape hatch for users that want to add CSS to their site, but don't want to customize any templates. Styles should be placed inside the `<head>` tags.
+
+`{{> scripts }}`
+
+: This partial renders any script tags specified either by the user (via `params.scripts`) or by the theme author (specified directly in the template). `params.scripts` is intended as an escape hatch for users that want to add javascript to their site, but don't want to customize any templates. Scripts should be placed at the end of the `<head>` block.
+
+TODO: Scripts must currently be given in raw form, whereas styles are just paths/urs.
+
+`{{> opengraph }}`
 
 : This partial willl render the Open Graph meta tags for your page. It should be placed inside the `<head>` tag. See the [Open Graph](#open-graph) section for more details.
 
+`{{> footer }}`
+
+: This partial will render content on every page after the main page content. It should be placed at the end of the `<body>` tag. By default, it displays a simple copyright line with the current year and author's name (configured in `params.author.name`).
+
+TODO: `styles`/`css`?
+
+TODO: `comments`?
+
+TODO: `toc`?
+
+TODO: We keep referring to blocks and tags, should probably use consistent language.
+
 ### DateTimes
 
+TODO: Should this be a subsection of a "Data Types" section?
+
 Dates are strings in one of the following formats:
 
 | Format                      | Time zone                    |
@@ -298,10 +357,6 @@ Dates are strings in one of the following formats:
 
 If you want to display a date in a different format, you can use the `| format` Filter. With no argument, it will default to formatting the date with `site.date_format`.
 
-## Menus
-
-TODO: Describe
-
 ## Open Graph
 
 TODO: default Template support

site/thor.json

@@ -1,4 +1,7 @@
 {
+  "markdown_extensions": {
+    // "footnotes": true
+  },
   "params": {
     "author": {
       "name": "Spencer Brower"