Components

Small content patterns that keep long pages easy to scan.

Callouts

Use a GitHub-style Markdown callout for a note readers should see before continuing. Put the marker on the first line of a blockquote.

Note

Keep callouts short. If a note needs several paragraphs, give it a section of its own.

markdown
markdown
> [!NOTE]
> Keep callouts short. If a note needs several paragraphs, give it a section of its own.

Use [!TIP] for optional advice, [!IMPORTANT] for information readers need to succeed, [!WARNING] for a risk, and [!CAUTION] for serious consequences.

Quotations and captions

Use a blockquote for quoted material and a figure caption for its attribution. Keep distinct paragraphs when the quotation contains more than one thought.

Write the instruction where the reader needs it.

Give each section one job, and each example enough context to be useful.

Example editorial guideline

Figures also support images: use an <img> with descriptive alt text and explicit width and height, followed by a <figcaption>. Images shrink to fit the reading column and inherit the appearance’s corner radius.

Headings and keyboard keys

The page title is its only level-one heading. Use ## for sections and ### for topics within a section; both appear in the page outline. Keep heading levels in sequence.

Use <kbd> for actual keys: press Ctrl + K (or Command + K on macOS) to open search. Use inline code for identifiers such as themeVariant.

Code blocks

Code examples follow your light or dark appearance. Copy a complete example with the button in its header, or select just the lines you need.

eleventy.config.js
eleventy.config.js
export default function (eleventyConfig) {
  eleventyConfig.addCollection("docs", (api) =>
    api.getFilteredByTag("docs")
  );
}

Package managers

Choose your package manager once. Matching groups on this site remember your selection.

npm
npm install zod
pnpm
pnpm add zod
yarn
yarn add zod
bun
bun add zod

The selection also applies to this second group:

npm
npm run dev
pnpm
pnpm dev
yarn
yarn dev
bun
bun run dev

Different languages

Use independent tabs for alternative implementations. These examples read a local JSON file.

JavaScript
import { readFile } from "node:fs/promises";

const content = await readFile("settings.json", "utf8");
const settings = JSON.parse(content);
console.log(settings.theme);
Python
import json
from pathlib import Path

content = Path("settings.json").read_text(encoding="utf-8")
settings = json.loads(content)
print(settings["theme"])

Line numbers and changes

Add line numbers when the surrounding explanation refers to specific lines. Here, line 3 sets the public path.

settings.json
settings.json
{
  "name": "Documentation",
  "basePath": "/docs/",
  "search": true
}

Mark changes to make a migration easier to follow:

settings.js
settings.js
export const settings = {
  theme: "light", 
  theme: "system", 
};

Here’s the finished example ready to copy. It comes from src/examples/settings.js. See how to include a file.

settings.js
settings.js
export const settings = {
  theme: "system",
};

Literal template examples

Template syntax is displayed exactly as written, including braces and tags:

welcome.liquid
welcome.liquid
{% if user %}
  <h1>Hello, {{ user.name }}!</h1>
{% endif %}

Long text

Code scrolls horizontally by default. Opt into wrapping for logs or long text that should fit the page.

build.log
build.log
Build complete: generated documentation, search index, stylesheets, and local fonts. The output is ready to serve from any static web host, with all code examples highlighted ahead of time.

Tables

Element Best use
Heading Name a topic or task
List Show a sequence or related choices
Table Compare the same fields across items
Callout Highlight a useful exception

Use links to move between pages. Use buttons for actions such as opening search or switching themes. Keeping those roles separate makes the interface easier to understand with a keyboard or screen reader.

Disclosure

Use native disclosure for optional detail. It works without JavaScript.

When should I use this?

For supporting information that most readers can safely skip. Keep essential instructions visible.

Release timeline

The release-notes page demonstrates a reusable, responsive timeline. Its dates and versions are sample content, not the template’s release history.

Use a .njk page to call the timeline macro. Keep entries newest first, give each an individual anchor, and use an ISO date for the machine-readable value. Each entry can contain paragraphs, lists, links, and headings. Write breaking changes and migration instructions explicitly when they apply.

src/pages/docs/release-notes.njk
src/pages/docs/release-notes.njk
{% import "macros/timeline.njk" as timeline %}
<ol class="release-timeline" role="list">
  {% call timeline.entry("version-1-0", "v1.0.0", "2026-04-16", "16 April 2026", "The first chapter") %}
    <p>Describe what changed and what readers need to do.</p>
  {% endcall %}
</ol>