Blog feature reference

2026-04-23T00:00:00.000Z

A single post that exercises every feature the blog pipeline supports. Everything below renders at build time via marked plus the custom extensions in app/vite/plugins/md-frontmatter.ts. Use this as a cheat sheet when writing future posts — if something on this page renders wrong on the deployed site, the renderer regressed, not the content.

The {{ toc }} token expands to a bullet list of the post's h2–h6 headings:

Headings

Post titles come from frontmatter (title), so the body starts at h2. Use h3/h4 for subsections — anything deeper probably means the section should be split into its own post.

This is an h3

And this an h4

Text formatting

Standard emphasis: bold, italic, both, ~~strikethrough~~. Inline code uses backticks.

Raw inline HTML passes through for semantic extras: highlight, HTML, — Mark Otto, ~~deleted~~, inserted, H₂O, E = mc².

Site variables

Post content references central data through {{ path.to.key }} — expanded against content/site.yml at build. Keeps URLs, handles, and identity strings out of prose.

Name: {{ name }}
Site URL: {{ url }}
Repository: {{ repo }}
Contact: {{ socials.email }}
GitHub: {{ socials.github }}
Built on: {{ now }}

Router paths are derived from app/routes.ts and exposed as {{ urls.<route-file-basename> }} — e.g. {{ urls.home }} → {{ urls.home }}, {{ urls.blog }} → {{ urls.blog }}. Anything under the urls: section of site.yml (static artifacts like feed and not_found) wins over the router-derived map.

Lists

Unordered:

first item
second item
- nested once
- also nested
third item

Ordered:

one
two
three

Blockquote

The best code is no code at all. Every new line of code you willingly bring into the world is code that has to be debugged, code that has to be read and understood, code that has to be supported.

— Jeff Atwood

Horizontal rule

Three or more hyphens on their own line render as a dashed divider:

Code

Inline snippets use backticks: marked.use() registers an extension.

Fenced without a language — plain preformatted:

$ pnpm run build
$ pnpm run preview

Fenced with a language — shiki highlights at build time using real TextMate grammars, with dual light/dark themes that follow the site's theme toggle:

export function slugify(text: string): string {
  return text
    .toLowerCase()
    .replace(/[^\w\s-]/g, '')
    .replace(/\s+/g, '-');
}

Append linenos to the info string for a two-column render with a line-number gutter:

1
2
3
4
5
6
7
8
9
export function expandTemplate(md: string, vars: Record<string, unknown>): string {
  return md.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (match, raw) => {
    const inner = raw.trim();
    if (inner === 'toc') return buildTocList(md);
    if (inner === 'now') return formatNow();
    if (inner.startsWith('gist:')) return gistEmbed(inner.slice(5));
    return lookup(inner, vars) ?? match;
  });
}

Tables

GFM table syntax:

Feature	Source	Handler
Footnotes	`[^id]` / `[^id]: body`	`marked-footnote`
TOC	`{{ toc }}`	`md-frontmatter.ts`
Line numbers	`linenos` fence flag	`md-frontmatter.ts`
Gists	`{{ gist:ID }}`	`md-frontmatter.ts`
Route URLs	`{{ urls.<name> }}`	`app/routes.ts`
Site vars	`{{ path.to.key }}`	`content/site.yml`

Definition list

Raw HTML — marked doesn't parse the Kramdown term\n: def shorthand, so write <dl> directly:

HTML: HyperText Markup Language. Structure.
CSS: Cascading Style Sheets. Presentation.
JS: JavaScript. Behavior.

Images

External placeholders via placehold.co:

Local images go under app/assets/ and are imported by the route component, not referenced from markdown.

Footnotes

Reference a footnote inline with [^id]¹ and define the body anywhere in the document. On render, marked-footnote collects all definitions into a <section class="footnotes"> at the bottom and wires up back-links automatically.

Multiple references to the same id collapse to a single footnote with multiple back-arrows¹.

Gist embed

{{ gist:ID }} expands to an iframe pointing at the gist's pibb URL (GitHub's iframe-safe render) — drops the embed inline without blocking on a <script> tag:

Frontmatter

Every post needs frontmatter at the top:

---
title: Post title
date: 2026-04-23
---

title drives the page <title> and the rendered h1. date can come from the filename prefix (YYYY-MM-DD-slug.md) or the frontmatter field — frontmatter wins when both are present. Slug is derived from the filename with any leading YYYY-MM-DD- stripped.

That's the full surface. To add a new feature, extend expandTemplate (build-time tokens), register a marked.use({ renderer }) override (HTML shape), or add styles under app/styles/terminal-content.scss (appearance).

Footnote body. Marked-footnote moves this to the bottom and links back to the reference via the return arrow. ↩ ↩²

Manuele