Add a Markdown file
Create a file under src/pages/docs/. The directory data file automatically applies the documentation layout and adds the page to the docs collection.
---
title: Your page title
description: A short summary for readers and search.
permalink: /guides/your-page/
eleventyNavigation:
key: Your page title
parent: Guides
order: 4
---
---
title: Your page title
description: A short summary for readers and search.
permalink: /guides/your-page/
eleventyNavigation:
key: Your page title
parent: Guides
order: 4
---
The key must be unique. parent points to another page’s key. order controls the position among siblings. Leave out parent to make a top-level item.
Write content
Use headings, lists, links, tables, and fenced code blocks. Second- and third-level headings receive stable IDs and appear in the page outline.
Add code examples
Use a language name after the opening fence. Optional metadata adds a filename, highlighted lines, line numbers, or wrapping:
```js title="settings.js" {2} line-numbers
export const settings = {
theme: "system",
};
```
```js title="settings.js" {2} line-numbers
export const settings = {
theme: "system",
};
```
Use wrap for long text and logs. Leave it out for horizontally scrollable source code. Languages without a supported grammar remain readable as plain text and produce a build warning. Fences without a language use plain text.
For alternatives, put labelled fences in a code group:
::: code-group sync="package-manager"
```sh [npm]
npm install zod
```
```sh [pnpm]
pnpm add zod
```
:::
::: code-group sync="package-manager"
```sh [npm]
npm install zod
```
```sh [pnpm]
pnpm add zod
```
:::
Add yarn and bun tabs in the same way. Supply each command explicitly. Only groups with the same sync value share a saved selection; omit it for independent examples. Each group must contain only fenced blocks with distinct labels. Without JavaScript, every example remains visible under its label.
Use // [!code ++] and // [!code --] to mark added or removed lines. Copy preserves the original fence content, including annotation comments and its final newline. Use a separate final example when readers should copy only the completed change.
Markdown content is not evaluated as Nunjucks, so {{ expressions }} and {% tags %} are preserved in examples. Nunjucks still renders the surrounding layouts. Use a .njk page when the page itself needs template logic.
See Components for rendered examples.
Write internal links from the site root, as in that link. The build rewrites them as relative paths, so the finished site works from any folder.
Include code from a file
Put the source under src/examples/. In an empty fence, write the language followed by file="path". The path is relative to src/examples/.
```js file="settings.js" line-numbers
```
```js file="settings.js" line-numbers
```
Eleventy reads the file when building the site. The usual fence options still work, and the filename is shown by default. Include files you intend to publish in full.
Use trusted HTML sparingly
Raw HTML is enabled for small components in trusted, repository-authored docs. For a complex component, create a Nunjucks page or include under src/_includes/. Do not use untrusted Markdown as a template source.
Keep links clear
Prefer descriptive link text. For example, write “Read the theme guide” instead of “click here.”