The Typography of a Code Block Inside Your Notes

A fenced code block dropped into prose is a typographic island, and it should be sized on purpose. Match its visual size to the body — monospace runs large, so no fixed em number fits every pair. Give the panel real contrast, keep it on the body's rhythm, and let it preserve every space.

The block itself is a convention, not a mystery. A code fence is a sequence of at least three consecutive backtick characters or tildes, and the first word after the opening fence names the language for the renderer to color ¹. But the fence only sets the structure. Everything a reader actually sees is applied afterward, by whatever renders the note: the smaller monospace, the tinted panel, the syntax colors, the preserved indentation. Chris Coyier put the core tension plainly: how you want code "to look within a sentence is quite different from how you want it to look in a block" ². Inline code is a fragment mid-thought; a block is a place the reader stops. This post walks the four decisions that turn a jarring paste into a deliberate island.

How should a code block look inside your notes?

Treat it as a deliberate island, not a raw paste. Four decisions make the seam read cleanly: size the monospace to match the body's visual size, give the block enough contrast to separate without shouting, keep it on the body's vertical rhythm, and preserve its whitespace exactly. None of them is a single magic number.

Each decision is easy to get wrong by accident, because editors ship defaults that were never chosen for your notes. Equal point sizes that look unequal. A gray-on-gray theme that photographs well and reads poorly. A raw paste with no breathing room, or a tab that renders eight columns wide. The four sections below take them one at a time.

Size: why equal point sizes lie

Set a monospace block a hair smaller than your prose, but not by a fixed number. A monospace font at the same point size looks larger, because apparent size follows the height of its lowercase letters, not the point value. Typical is around 0.85 to 0.9em — but tune it to your specific pairing.

This is not aesthetic fussiness; it is how legibility works. MDN's note on font sizing states that legibility "is determined more by the size of lowercase letters than by the size of uppercase letters," and defines the aspect value as the "height of lowercase letters divided by font size" ³. Two fonts at the same points, different lowercase heights, look like two different sizes.

The fix resists a clean rule. Eric Meyer, tracing why the generic monospace keyword misbehaves across browsers, found you could end up with "a size smaller than you'd intended" ⁴ — his workaround was fiddly and browser-dependent, not a constant you can memorize. So the method is the answer, not a number: pick a step-down, then judge it by eye against the font your whole note is set in.

Match the visual size. Ignore the point size.

Contrast, not rainbow

A tinted panel separates the island from the prose, but the tint is not the point — legibility is. Every text and syntax color inside the block must clear a contrast ratio of at least 4.5:1 against its background. A pretty pastel theme that fails that ratio is harder to read, not easier.

The number is not arbitrary. WCAG Success Criterion 1.4.3 requires that "the visual presentation of text and images of text has a contrast ratio of at least 4.5:1," relaxing to 3:1 only for large-scale text ⁵. A syntax theme is dozens of small text-on-tint decisions; each one has to clear the bar, or the color that was meant to help instead hides.

Color does help, with a caveat worth stating plainly. Advait Sarkar's eye-tracking study found "syntax highlighting significantly improves task completion time, and that this effect becomes weaker with an increase in programming experience" ⁶. The measured gain was a median difference of 8.4 seconds on a code-comprehension task, significant at p = 0.047 — but the study ran with only ten subjects, and it measured how fast they finished, not how deeply they understood. Treat color as a speed aid for legible text, never as a substitute for contrast.

Contrast is the requirement. Color is the bonus.

Rhythm: keep the block on the body's baseline

Give the block room above and below, and keep its lines on the same vertical rhythm as your prose. This is craft consensus rather than a measured rule: a code island that floats without breathing space reads as a jarring interruption, while one spaced on the body's grid reads as a considered aside. Space before, space after.

Inside the block, the leading can run tighter than prose, because code lines are logical units, not sentences that flow. That is a different setting from the line-height you give your body text, and a different problem again from the measure your prose wraps at — a code line is a unit that should not wrap at all. The block should also respect the size hierarchy your headings already set, sitting below them without competing.

A block that breathes with the page reads as part of the note. One that does not reads as debris.

Whitespace and indentation: the block's whole job

The reason a code block exists is to preserve whitespace — the indentation is data, not decoration. Preformatted text is presented exactly as written, so every leading space and line break survives. Watch the tab, though: by default a tab character renders eight columns wide, which usually overpowers a note. Set it to two or four.

The semantics carry the intent. MDN describes the <pre> element as text "which is to be presented exactly as written" and "typically rendered using a non-proportional, or monospaced font" ⁷. Coyier makes the same point about why the tag matters: it "respects whitespace in the HTML. But semantically, it just means 'pre-formatted text'" ². The block is a promise that what you typed is what the reader gets.

The tab is the common trap. The CSS tab-size property "is used to customize the width of tab characters," and its initial value is eight ⁸, a width inherited from terminals, not chosen for a narrow note column. A setting of two or four keeps nested code from marching off the right edge.

Preserve the spaces. Tame the tabs.

The convention every reader already expects

Before any styling, the structure is a shared convention. A code fence is a sequence of at least three backticks or tildes, and the first word after the opening fence names the language. That label is what lets a renderer apply syntax colors at all — and it renders as a <pre><code> pair, monospaced by default.

The spec is explicit on both halves. CommonMark defines a code fence as "a sequence of at least three consecutive backtick characters" or tildes, and says "the first word of the info string is typically used to specify the language of the code sample" ¹. That info string, the python after your opening backticks, is the hook every highlighter reads.

The rendered result is equally conventional. MDN describes <code> as content "displayed using the user agent's default monospace font," marking "a short fragment of computer code" ⁹. Readers have seen ten thousand of these. Meeting the convention is why a block reads as code before a single color loads.

What your note actually stores

None of this lives in the file. A fenced block in Markdown is just text between backticks — the size, the panel, the colors, and the highlighting are a view applied by whatever renders it, never bytes you saved. So every decision here is reversible. Change the theme tomorrow and the note is untouched.

That is the quiet payoff of keeping notes in plain text. The typographic island you tuned is not encoded into the document; it is a rendering choice sitting on top of unchanged characters. Restyle it, move it to another reader, print it — the fenced text is identical every time. You never have to migrate the look, because the look was never in the file.

The file holds the code. The typography is a lens you can swap.

Frequently Asked Questions

The short version: a monospace block looks larger than prose at the same point size, so scale it down by eye; give it a panel that clears 4.5:1 contrast; keep it on the body's rhythm; and preserve its whitespace. These answers cover the questions people actually search for.

Why does my code font look bigger than the text?

Because apparent size follows letter height, not point size. A monospace font has taller, wider lowercase letters than the proportional font around it, so at an identical point size it looks larger. MDN notes that legibility "is determined more by the size of lowercase letters than by the size of uppercase letters" ³. Set the block slightly smaller to compensate.

Should code be smaller than body text?

Usually a little, but there is no universal number. Because monospace looks larger at the same point size, a step down of roughly 0.85 to 0.9em often matches the body's visual size. The right value depends on the two fonts you pair, so trust your eye over any fixed rule — set it, then read a real block.

How do I style code blocks in Markdown?

You write the content; the renderer applies the look. Fence the code with at least three backticks and add a language label for highlighting ¹. The rest is set by whatever displays the note: a monospace face, a tinted panel, comfortable spacing, applied through the <pre> and <code> elements the block becomes. Your Markdown stays plain text.

What background color should a Markdown code block use?

Any tint that separates the block while keeping its text legible. A subtle panel, a hair lighter or darker than the page, marks the island without shouting. The hard requirement is contrast: text and syntax colors must clear at least 4.5:1 against that background, the WCAG minimum ⁵. A low-contrast theme looks calm and reads badly.

What font size should code blocks be?

Match the body's visual size, not its point size. Since monospace appears larger, a block set at the same points looks oversized; a step to about 0.85 to 0.9em usually restores balance. Eric Meyer warned that even the browser's own monospace handling can leave you with "a size smaller than you'd intended" ⁴ — so verify by eye, per font-pair.

How do I make code blocks readable?

Contrast first, color second, space always. Ensure text and syntax colors clear 4.5:1 ⁵; syntax highlighting then speeds you up — Sarkar measured an 8.4-second median improvement in completion time on a comprehension task, though the effect shrank with programming experience ⁶. Keep the indentation intact and give the block room above and below. Readable beats colorful.

What should CSS tab-size be for code indentation?

Two or four, rarely the default. The CSS tab-size property sets how wide a tab character renders, and its initial value is eight columns ⁸, wide enough to push short code off the edge of a note. Setting it to two or four keeps nested indentation readable without wasting horizontal space the block does not have.

A code block is not a paste; it is a decision about where the reader should slow down. Size it, contrast it, space it, and preserve it — then remember the file kept none of that. The typography is a view, and the view is yours.

MNMNOTE keeps your notes in open Markdown on your own device, where the way a code block renders — size, panel, and color — is yours to set: mnmnote.com.