Writing documentation

Maintain .md files in the document source repository’s docs/ directory. The template discovers pages automatically, leaves the originals unchanged, and writes build content only to temporary and generated directories.

Organize pages

This example has the following structure:

docs/
├── README.md
├── getting-started.md
├── writing-docs.md
├── sidebar-order.md
├── site-config.md
├── deployment.md
├── deployment/
│   ├── configuration.md
│   ├── private-repository.md
│   ├── deploy-hook.md
│   ├── template-update.md
│   └── template-update-agent.md
├── markdown-test.md
├── markdown-test/
│   └── markdown-display-test.md
├── site.json
└── assets/
    └── nimbus-mark.svg

A subdirectory can also contain README.md or index.md as its landing page. Keep only one of these in each directory to avoid competing for the same route. Regular files generate lowercase slugs from their paths.

See Markdown display test for rendered examples of common syntax.

Titles and sidebar

Plain Markdown can begin with an H1, as on this example’s home page. The template extracts the page title from the first heading.

To set a description, sidebar label, or order, add frontmatter at the start of the file:

---
title: Writing documentation
description: Maintain documentation pages with Markdown.
sidebar:
  label: Writing documentation
  order: 20
---

Start writing the page here.

## Add content

Use ordinary Markdown headings, lists, tables, and code blocks.

The page displays title as its main heading, so you do not need to repeat it in the body. The sidebar includes pages automatically; smaller sidebar.order values appear first.

This example uses 10, 20, 30… to order siblings, leaving space to insert new pages. A category’s position is controlled by a Markdown file beside the directory with the same name. For example, deployment.md positions the entire Deployment guide category, while each page’s sidebar.order inside deployment/ controls its position within that category.

See Sidebar order for step-by-step instructions, complete examples, and the current document order.

Non-index pages can set slug to customize their route, such as slug: writing-docs. Do not add leading or trailing / characters. Directory landing pages keep their automatic mapping and should not set a custom slug.

Relative links

Write links using paths between document files:

[Quick start](./getting-started.md)
[Site configuration](./site-config.md)
[Home](./README.md)

The build rewrites these links to their corresponding site pages and preserves heading anchors after #. For example: Site theme.

Target files must exist. Markdown outside the selected document directory does not become a page on this site. Use full GitHub URLs when linking to the repository README or the separate Chinese documentation.

Images and assets

Image paths are relative to the Markdown file that references them. This example’s home page uses docs/assets/nimbus-mark.svg:

![Official Nimbus logo](./assets/nimbus-mark.svg)

The template copies referenced local assets and rewrites their URLs. Images can live in other ordinary directories in the source repository, but paths cannot escape the repository. Hidden files, hidden directories, and symbolic links are not published.

You can also set the logo and favicon through the optional ordinary build variables SITE_LOGO and SITE_FAVICON. These are absent from the initial deployment form; add them later only to customize branding. They accept HTTP(S) image URLs or paths relative to the DOCS_REPO repository root, such as docs/assets/nimbus-mark.svg, regardless of the site JSON location. Local brand.logo and brand.favicon paths in JSON remain relative to the JSON file. Unset variables inherit the corresponding JSON field, falling back to the built-in official Nimbus logo (/nimbus-logo.svg) if that field is absent. Existing default and empty values behave the same way. Explicit image URLs and repository paths override JSON. Save the variables in Cloudflare Builds and rebuild to apply them. See Branding.

Publish updates

Commit and push document changes, then trigger a site build. The build regenerates pages and the sidebar; deleted files disappear from the next output. If the top navigation explicitly references a deleted page, also update docs/site.json.

A separate document source can use a Deploy hook to rebuild automatically after a push.

The current document input handles .md files and ignores .mdx. It does not execute JavaScript or MDX components from the document source. To change template code, edit the template project itself and consult the repository maintenance instructions.