Writing pages

Folders become the menu #

Every .md file under docs/ is a page. Folders become sidebar groups, and nested folders become collapsible submenus. A typical site:

A folder’s index.md is the first item inside it. Two files that map to the same URL fail the build. Files and folders whose name starts with a dot (.obsidian/, .notes.md) are skipped.

Front matter #

---
title: Installation            # page title; else the first "# heading", else the file name
description: How to install.   # meta description; else the first paragraph
draft: true                    # skipped in builds, shown by dokk serve and --drafts
noindex: true                  # kept out of sitemap.xml and search engines
sidebar:
  label: Install               # menu text instead of the title
  order: 1                     # lower comes first; unordered pages follow by file name
  hidden: true                 # built, but not in the menu
  badge: New                   # or {text: New, variant: secondary}; variants as :badge
---

A folder takes its menu title and order from its index.md. A folder without one sorts after ordered entries and uses its name, title-cased.

Links and images #

Link to other pages by their file, relative to the current one. dokk turns them into the right URL, including the base path on GitHub Pages:

See [installation](../getting-started/index.md#install).
![Diagram](img/diagram.png)

Files next to your Markdown (images, PDFs, …) are copied to the site. Files in public/ are copied to the site root, for example favicon.svg or CNAME.

A public/logo.svg (or logo.png) is shown next to the site title. Add public/logo-dark.svg for a version that suits dark mode. A favicon.svg can follow the browser’s theme with a @media (prefers-color-scheme: dark) rule inside the SVG.

Markdown features #

Tables, strikethrough, footnotes^[1], task lists, definition lists, heading anchors and attributes like {#id .class} all work. A heading can set its own anchor, as MkDocs writes it: ## Install { #setup } links as #setup. Code blocks are highlighted at build time:

def hello(name: str) -> str:
    return f"Hello, {name}!"

Add a title and highlight lines after the language:

```python title="hello.py" {2}
def hello(name: str) -> str:
    return f"Hello, {name}!"
```

def hello(name: str) -> str:
    return f"Hello, {name}!"

Definition lists put a term on one line and : with its description below. They are handy for options and glossaries:

`--port PORT`
: Port to listen on. Default: `8002`.

--port PORT

Port to listen on. Default: 8002.