Headings

Markdown gives you six heading levels. Use one # for the biggest, six for the smallest. The top two keep the same serif as the body text. From level three down, headings switch to a plainer typeface, and the two smallest use capital letters so they read as labels rather than titles. The space above each heading shrinks as the levels descend:

Heading one: the article title

Heading two: a major section

Heading three: a subsection

Heading four: a topic within it

Heading five: a small label

Heading six: the smallest label

Notice the pair above: when one heading follows another with no text between them, the gap closes so they read as a unit, the way a title and subtitle should.

Paragraphs

Paragraphs do most of the work on a reading page. Each line holds about sixty-five characters, a width your eye can scan and return from without losing its place. Here is Thoreau, from Walden:

I went to the woods because I wished to live deliberately, to front only the essential facts of life, and see if I could not learn what it had to teach, and not, when I came to die, discover that I had not lived. I did not wish to live what was not life, living is so dear; nor did I wish to practise resignation, unless it was quite necessary.

A second paragraph follows the first after a small gap: close enough to keep the text flowing, distinct enough to show where one paragraph ends and the next begins. End a Markdown line with two spaces and you get a hard line break instead of a new paragraph:
like this, with no gap at all.

Emphasis

Wrap a word in single asterisks for italic, double for bold, and triple for bold italic. Backticks mark inline code, which steps into a different typeface with a soft tinted background. Weight, slant, and texture do the differentiating, never color alone.

Small inline touches

Strikethrough: wrap text in double tildes and it reads as crossed out revised.

Highlight: the <mark> element puts a gentle tint behind the words that matter.

Subscript and superscript: chemistry gets CO₂; geometry gets a² + b² = c². Neither one knocks the line spacing off its rhythm.

Abbreviations: hover the W3C and its full name appears; the dotted underline hints that there is more to see.

Keyboard keys: press Ctrl + S to save, or Ctrl + Shift + P for the command palette. Each key sits in its own little cap.

Try selecting any sentence on this page. The selection tint comes from the theme, so it stays readable in light, sepia, and dark alike.

Inline SVG: a hand-drawn star sits inline like a character, sized in the markup rather than stretched to fill the column the way a standalone image would.

Links

A link looks like this: colored, with a quiet underline that darkens when you hover. Markdown also turns bare addresses into links automatically: design@example.com or example.com. Code can live inside a link too: npm install. And when a whole image is a link, the framework adds feedback of its own. Hover the image below and it lifts with a soft shadow; that is the only reason it is here:

Footnotes

Write [^1] in Markdown and a small numbered reference appears in the text¹. The notes themselves gather at the very end of the article, far below, and each one links back to where you left off².

Blockquotes

Start a line with > and Markdown sets the quote apart, in a quieter color with a rule along its edge:

The details are not the details. They make the design.

Quotes nest when someone quotes a quote:

The outer voice says something.

An inner voice replies.

And a third voice, deepest of all, still keeps its spacing.

Then the outer voice returns.

Alerts

GitHub extends the blockquote into five labelled callouts. Plain GitHub Flavored Markdown leaves them as ordinary quotes; add the alerts plugin to your pipeline and the framework colors each type in every theme:

Horizontal rules

Type three hyphens on their own line and Markdown draws a thematic break, a short centered rule that says the subject is changing:

And the prose picks up again on the other side.

Bulleted lists

Start lines with a hyphen and you get a bulleted list. A tight list keeps its items close:

• Set the type first
• Then the spacing
• Then the color

A loose list, where each item holds a full paragraph, gets a little more room:

• The first item carries a complete thought, written as a paragraph, and keeps the same comfortable line spacing as the essay around it.

• The second item does the same, so the list reads as prose that happens to have bullets.

Indent items and lists nest three levels deep, each level keeping its own indent:

• Level one
  • Level two
    • Level three
    • Level three again
  • Back to level two
• And back to level one

Numbered lists

Start lines with numbers and Markdown counts for you:

1. Establish the baseline
2. Define the structure
3. Refine the typography

Lists can start wherever you like:

42. Item forty-two
43. Item forty-three

Numbered and bulleted lists mix freely, even with checkboxes inside:

1. First, review the checklist
   • Audit the typography
   • Verify the spacing
2. Then, work through the sequence
   1. Draft
   2. Revise

Task lists

Write - [ ] and - [x] and Markdown produces checkboxes. The framework draws its own: a rounded square that fills with a check when done:

• Publish the stylesheet
• Review the pull request
• This one is live. Click it and watch the check draw in

Definition lists

Some Markdown flavors support term-and-definition pairs:

Voice

The personality of the writing, steady across everything you publish.

Tone

The mood of the moment; it flexes with the reader's situation.

Measure

The length of a line of text. This page holds it near sixty-five characters.

Code blocks

Fence code with three backticks and it sits in its own bordered panel, in a fixed-width typeface:

/* A code block keeps every space exactly where you typed it */
:root {
  --primary-font: "Source Serif 4", serif;
  --code-font: "Source Code Pro", monospace;
}

Long lines never break the page. The block scrolls sideways instead, and you can scroll it from the keyboard too (click or tab into it, then use the arrow keys):

const result = bootstrapApplicationFramework(globalSettings, userPreferences, networkConfiguration, offlineFallbackStrategy);

Tables

Draw a table with pipes and hyphens. Headers get a strong rule beneath them, rows get light ones, and the digits line up in tidy columns:

A table too wide for the page scrolls sideways instead of breaking the layout. Try it on a phone:

Images and figures

An image on its own line becomes a centered block with soft corners. In dark mode it dims slightly so it never glows against the page:

Give an image a caption and it becomes a figure. The caption sits beneath in a smaller, quieter typeface:

Disclosures

The <details> element folds content away behind a clickable summary line, no scripts involved:

Forms and buttons

Reading pages sometimes ask for something back: a newsletter signup, a comment, a search. Every control sits in the plainer typeface, keeps a visible border, and shows a clear ring when you reach it from the keyboard:

Press and hold the Subscribe button; it dips slightly under your finger. The disabled one fades and refuses the cursor. Type something that isn't an email address into the email field, then click away: the border only turns to the error color once you've actually interacted with it, not simply because it started out empty.

Progress, meter, and dialog

Three more native elements read the same theme colors:

70%
60%

Mixed content and hard cases

A heading holding code and bold

Inline styling inside a heading inherits the heading's size and keeps the line steady.

Code inside a quote

Sometimes a quotation includes the code it discusses:

table {
  display: block;
  overflow-x: auto;
}

A list inside a quote

• The first quoted point keeps its indent.
• The second keeps the rhythm.

Code inside a list

• Run npm run build to compile the stylesheet.
• Then ship it:

  $ scp dist/style.css server:/var/www/

A table inside a disclosure