docs-kitDocs
mindmeldingGitHub

Writing

Writing pages

Front matter, links, images and how pages get into the sidebar.

View as Markdown Edit this page

A page is a Markdown file in your docs folder. It shows up on the site once help.json lists it.

#Front matter

Start each page with a title and a one-line description:

markdown
---
title: Connect Slack
description: Send alerts to a channel your team already reads.
---

The title becomes the page heading and the sidebar label. The description shows under the heading, in search results, in llms.txt and in link previews. Leave out the # Heading line; docs-kit writes it from the title.

#Adding a page to the sidebar

List the file name without .md in a group in help.json. Pages in folders use the folder path.

json
{
  "label": "Guide",
  "groups": [
    { "group": "Get started", "pages": ["what-is", "quickstart"] },
    { "group": "Integrations", "pages": ["integrations/slack", "integrations/email"] }
  ]
}

The order in help.json is the order in the sidebar and in the previous and next links. A file that isn't listed doesn't get built.

#Headings

Use ## for sections and ### for subsections. Both appear in the table of contents on the right, and each gets a link you can share. Deeper headings still work but stay out of the table of contents.

Link to another page by its path from the docs root, starting with /:

markdown
See [Connect Slack](/integrations/slack) for the setup.

docs-kit adds the base path, so the same link works on your laptop and in production. Links to sections work with #: /quickstart#run-it. Relative links such as slack or ../quickstart work too.

#Images

Put images anywhere in the docs folder, such as help/images/, and link them from the root:

markdown
![The alerts settings screen](/images/alerts.png)

Write alt text that says what the image shows, for readers who can't see it and for agents.