Skip to main content

Create New Documentation Article

After you have created a documentation group or category, you can add new articles or pages inside it. Each article is a markdown file. If you are new to Markdown, do not worry - it is just plain text with a few simple symbols for formatting.

Step 1: Go to Your Group Folder​

Open the docs group folder where you want to add an article.

For example, if you have a group called getting-started:

docs/getting-started/

You already have _category_.json inside. Now you will add markdown files here.

Step 2: Create a New Markdown File​

Create a new file with a .md extension. The file name becomes the URL.

Naming rules:

  • Use lowercase and dashes: how-to-install.md → URL: /docs/getting-started/how-to-install
  • Do not use spaces: Use installation.md not installation guide.md
  • Keep it short and descriptive

Examples:

  • download.md
  • installation.md
  • configuration.md
  • deployment.md

For this example, create: docs/getting-started/installation.md

Step 3: Add Frontmatter​

Every doc article must have frontmatter at the top. Frontmatter is metadata that tells Docusaurus how to display the article in the sidebar and in search results.

Basic Template:

---
title: Your Article Title Here
description: Short SEO description about this article (150 chars) - shows in Google and doc header
image: img/docusaurus.png
sidebar_position: 3
---

# Your Title Here

Write your content here with markdown...

Frontmatter Fields Explained:

  • title: Article title shown in the browser tab, sidebar, and Google. Keep it clear.
  • description: SEO description. Important for Google ranking. 120-160 characters is ideal.
  • image: Cover image for social sharing (Open Graph). Use img/docusaurus.png or your own img/your-image.png. The image must be in the static/img/ folder.
  • sidebar_position: Order inside the group. 1 = first article, 2 = second, etc.

Real Implementation Example​

File: docs/getting-started/installation.md

---
title: Installation
description: Complete guide to install the Docusar Docusaurus Themes template - npm install and yarn install with common error fixes.
image: img/docusaurus.png
sidebar_position: 3
---

# Installation

This guide shows how to install Docusar template dependencies.

## Step 1: Open Project Folder

Open terminal and go to your project folder. For example, your project is on the Desktop named `docusar`:

Windows:

cd C:\Users\pcname\Desktop\docusar


Replace `pcname` with your PC name.

## Step 2: Install Dependencies

Run the installation:

**With npm:**

npm install


**With yarn:**

yarn install


Wait until it finishes. You will see a `node_modules` folder created.

Step 4: Write Content with Markdown​

After the frontmatter, write your article using Markdown:

# Heading 1
## Heading 2
### Heading 3

**Bold text**
*Italic text*

- List item 1
- List item 2

1. Numbered list
2. Second

[Link Text](https://example.com)

![Image Alt](img/your-image.png)

```bash
npm run start

Code block


## Step 5: Save and Check

1. Save the file
2. Run `npm run start` if it is not running
3. Go to http://localhost:3000/docs/getting-started/installation
4. Check the sidebar - your new article should appear at the position you set
5. Check if the title and description show correctly

**Tips:**

- `sidebar_position` must be a number, no quotes
- Always start the content with an `#` H1 that matches your title
- Image path in markdown: if the image is in `static/img/`, use `/img/image.png` or `img/image.png`
- You can create subfolders inside a group too: `docs/getting-started/advanced/config.md`

Now you know how to add unlimited documentation articles.