Field guide / Rule 15 — From Markdown
Paste a code block into most exporters and it arrives as a flat wall of grey monospace — legible, but lifeless. In a set document, code deserves the same care as prose. A fenced block that names its language comes across syntax-highlighted, in a theme you choose, and it looks identical whether you export a Word document or a PDF.
Open a fence and name its language — ```python, ```rust, ```sql — and the block is syntax-highlighted on the way out: keywords, strings and comments each in their own color, the way you see them in an editor. The point isn’t decoration; it’s that colored code is faster to read and harder to misread. A fence with no language still comes across as a clean, monospaced block — there’s simply no grammar to color it by.
The colors come from a theme you pick once, in the document’s frontmatter — code_theme: dracula for the dark default, code_theme: github for a light scheme that reads well on white paper, or code_theme: none to switch highlighting off and keep code in plain monospace. Whatever you choose sets the palette for every block in the document.
The two formats build code very differently under the hood, so it would be easy for their colors to drift apart. They don’t: both renderers are handed the same theme, so a highlighted block is the same block whether you hand someone a Word file or a PDF. The theme’s own background travels with it too, so highlighted code sits on the backdrop it was designed for.
Shared pages highlight your code too: a language-tagged fence lands in the same Dracula palette the
Word and PDF exports use by default — a dark, colored block that reads well on both the light and
dark reader themes. Written as ```python, here it is on the web:
def greet(name):
return "Hello, " + name In short
Code is content, not filler. A fence that names its language is syntax-highlighted wherever it lands — the Word and PDF exports honor the code_theme you pick, and shared pages paint the same Dracula default on screen. A fence with no language stays clean monospace.
Want to see it on your own snippets? Convert a document and the colors come across with them.