Block Reference: Every Block You Can Use

This post is the master reference for everything you can drop into a blog body. Every block, every mark, every annotation. Read it once, keep the slug bookmarked, and copy patterns from here when you build a real article.

Sections below are organised by feature. Each demonstration is followed by a one-line note in italics telling you when to use it.

Headings (H2 → H5)

There are four heading levels in the editor. H1 is reserved for the post title — never use it inside the body. The article's section headings should always be H2; sub-sections nest down from there.

Heading 2 — major section

Heading 3 — sub-section under an H2

Heading 4 — supporting label inside an H3

Heading 5 — rarely used, reserve for fine-grained labels

Paragraph text and inline formatting

A paragraph is the default block. Inside any paragraph you can layer strong (bold), emphasis (italic), underline, strikethrough, and inline code. Mix freely — each mark is just a toggle in the toolbar.

Use strong for terms the reader must not miss, em for tone or quoted phrasing, and code for filenames, commands, env vars, or any literal string the reader will paste somewhere.

Lead paragraph

The very first paragraph above this whole post is a lead paragraph. It renders larger than a normal paragraph and sets the article's hook. Use exactly one lead, and put it first.

↑ That paragraph is the demo. Style: Lead paragraph. When to use: the opening sentence(s) of an article, never anywhere else.

Blockquote

Use a blockquote to call out a quote from a source, a customer, or a published study. It renders with a distinct visual treatment so the reader knows it is not your voice.

When to use: direct quotation only. Don't use it for emphasis — that's what bold and callouts are for.

Bullet and numbered lists (with nesting)

Bullets — for unordered items where order is not meaningful:

• First item at level 1.
• Second item at level 1.
  • Nested item at level 2 — Tab in the editor to nest.
  • Another nested item at level 2.
• Back to level 1.

Numbered — for ordered steps, ranked rules, or anything where sequence matters:

1. Step one.
2. Step two.
   1. A nested sub-step.
3. Step three.

Links (annotations)

Linking is an annotation, not a mark. Highlight the text, click the link icon, paste the URL. Use relative paths for internal pages — for example: our case studies page. For external sources, use the full URL and tick "Open in new tab" — for example: Sanity's docs.

Highlight and text colour

Highlight wraps text in a coloured background — yellow, pink, green, blue, orange. Text colour changes the type colour itself — brand maroon, brand red, brand navy, gray, green.

When to use: sparingly. Highlight one phrase per section at most. Never highlight or recolour an entire paragraph — it screams.

Inline images

Drop an inline image anywhere in the body. Each image has a width (full / wide / inset) and an alignment (centre / left / right). Always add alt text — it is required for accessibility and SEO.

Width: full — image breaks out edge-to-edge.

Width: wide — sits inside the article column at maximum width.

Width: inset — narrower than the column, centred.

Code block

A code block is a fenced, syntax-highlighted snippet with an optional filename. Pick the language from the dropdown — TypeScript, JavaScript, Python, SQL, HTML, CSS, JSON, Bash, and more are supported.

// Example: a tiny Sanity client
import {createClient} from '@sanity/client'

export const sanity = createClient({
  projectId: 'ptywia1y',
  dataset: 'production',
  apiVersion: '2024-01-01',
  useCdn: true,
})

When to use: any time you show actual code. Do not use a code block for fake "code" or pseudo-syntax — readers expect to be able to copy-paste from it.

Callouts (info / tip / warning / danger / note)

A callout is a coloured box that pulls something out of the flow. Five tones, each with a different visual treatment. Pick the tone that matches the message:

Tables

Tables render with a header row by default. The first row is the header. Add a caption underneath the table — it is shown to readers and to screen readers.

Embed (generic URL)

The embed block takes any URL and renders it inline. Use this for YouTube videos, Vimeo, CodePen, generic iframes, or anywhere the live page itself is the content.

Social post embeds

Social post is a separate, branded embed for X, LinkedIn, YouTube, Facebook, Instagram, TikTok, Threads, and Bluesky. Pick the platform from the dropdown and paste the post URL. The block renders with the platform's style.

Dividers (line / dots / asterisk)

Three divider styles. Use them to mark a strong topic break — not after every section. The post you are reading uses line dividers throughout to separate block demos.

Line:

Dots:

Asterisk — heaviest break:

* * *

House rules

A short checklist before you publish:

1. Exactly one Lead paragraph at the top.
2. Exactly one H1 — that is the title field, never inside the body.
3. Every image has alt text.
4. External links open in a new tab; internal links do not.
5. Callouts and dividers exist to help the reader skim — do not overuse.
6. Code blocks are real, copy-pastable code. Pseudo-code goes in a paragraph with inline `code` marks.

* * *

Mermaid diagrams

A Mermaid code block renders as a live diagram on the site instead of as code. Insert a Code block and choose "Mermaid diagram" as the language, then write Mermaid syntax. Use it for flows, sequences, and architecture sketches.