Code and math

Technical writing leans on two things a plain blog engine handles badly: code and math. Both usually mean shipping a big library to every reader, so that their browser can color a few lines of TypeScript or lay out one equation. Here both happen once, on the server, and the reader gets finished HTML.

Code

Code blocks are highlighted by Shiki, the same engine VS Code uses, so the colors match what you see in your editor. Each block is rendered with a light and a dark theme at once, and the page's theme picks one with CSS, so switching themes does not re-render anything.

Notion's language names are mapped to Shiki's, and a language Shiki does not know falls back to plain text instead of failing the page.

import { fetchBlockTree } from "@yokinist/notion-fetch";
import { NotionBlocks } from "@yokinist/notion-rsc";

export default async function Page({ params }) {
  const { id } = await params;
  const blocks = await fetchBlockTree(notion, id, { limit });
  return <NotionBlocks blocks={blocks} />;
}

.notion-callout {
  border-radius: 0.75rem;
}

npm install @yokinist/notion-fetch @yokinist/notion-rsc @notionhq/client

Long lines scroll inside the block rather than widening the page, which matters most on phones.

Math

Equations are rendered by KaTeX into HTML and MathML, so they are sharp at any zoom and readable by screen readers. A block equation gets its own line:

and inline, like $E = mc^2$ or $a^2 + b^2 = c^2$, in the middle of a sentence.

Inline code keeps its own style.

What reaches the browser

Neither Shiki nor KaTeX is sent to the reader. The page loads one stylesheet for KaTeX's fonts and nothing else, which is why a post full of code can still score 100 on performance.