Skip to main content

How to create and edit docs

This guide is for the documentation team. If you have never worked with a code repository before, that is fine—there are only a few fixed steps, listed below in order.

Where do the docs live?​

  • All documentation pages live in the docs folder at the project root.
  • Each page is usually one file with a .md (Markdown) extension.
  • After you save the file and the site is published, that same content appears as a web page.

Create a new page​

Step 1: Add a file​

  1. Open the docs folder.
  2. Create a new file—for example my-page.md.
    • Use an English file name with no spaces (for example backup-guide.md).
  3. Start the file with these first lines (this block is called front matter):
---
title: Your page title
sidebar_position: 10
---

Page content starts here.
  • title: The title shown in the sidebar and at the top of the page.
  • sidebar_position: A smaller number appears higher in the sidebar (for example 1, 2, 10).

Step 2: Write content in Markdown​

Common patterns:

You want to writeIn your .md file
Large heading# Title
Medium heading## Subtitle
Bullet listLines starting with - or *
Numbered list1. , 2., and so on
Bold**word**
Link[link text](https://example.com)
Inline code`command`
Multi-line code blockThree backticks above and below the code

For more detail, see the Markdown Guide (optional).

Add images​

  1. Copy the image into static/img (for example static/img/screenshot.png).
  2. Reference it in your doc like this:
![Short description for accessibility](/img/screenshot.png)

Paths always start from the site root with /img/....

Put a page under a category (like VPS)​

If you want several pages grouped together:

  1. Create a folder under docs, for example docs/my-section/.
  2. Add a _category_.json file in that folder so the group label appears in the sidebar:
{
  "label": "Category name",
  "position": 5
}
  1. Add your .md files inside that folder (for example docs/my-section/page-one.md).

A real example in this project is the docs/vps/ folder.

Preview before you publish​

If you run the project on your machine (requires Node.js installed):

npm install
npm start

Your browser should open; find the new page in the sidebar and check that everything looks correct.

If you only hand off files through Git and another team builds the site, make sure you commit the .md file in the correct path.

Quick recap​

  1. Create a .md file under docs (or a subfolder).
  2. Fill in title and, if needed, sidebar_position at the top of the file.
  3. Write the body in Markdown; put images in static/img.
  4. Use a folder + _category_.json when you need a sidebar group.
Pro tip

You do not have to write Markdown from day one inside a .md file. Draft your text in whatever editor you prefer—Word, Google Docs, Notion, or a phone notes app—then copy the full text into ChatGPT, DeepSeek, or a similar tool and ask it to convert the content to Markdown.

Sample prompt (click to expand)
Convert the text below into clean Markdown; use ## and ### for headings and format lists properly.

Shorter version: “Turn this into Markdown.” Then review the output once, add front matter (title, and so on) at the top of the file, and save it under docs.

Before you save for good

Always read the AI output yourself. It sometimes formats links, tables, or code blocks incorrectly.

If anything is unclear, ask your repository owner or tech lead for the right file path and branch name.