Aller au contenu principal

Content Authoring and Daily Usage

This chapter explains how to write and organize docs content.

Creating a New Doc Page​

Add a Markdown file under docs/, for example:

  • docs/getting-started.md
  • docs/docusaurus/installation.md

Docusaurus automatically adds routes and sidebar entries when using autogenerated sidebar mode.

Frontmatter Basics​

Use frontmatter at the top of each file:

---
title: Getting Started
sidebar_position: 2
slug: /getting-started
---

Key fields:

  • title: page title
  • sidebar_position: order in sidebar
  • slug: custom route segment

Markdown and MDX​

  • Use .md for pure markdown docs
  • Use .mdx when embedding React components

Use MDX sparingly. Prefer plain markdown for maintainability.

Images and Static Assets​

  • Store shared images in static/img
  • Reference with /img/... path in markdown

Example:

![Architecture Diagram](/img/architecture.png)

Cross-Linking Pages​

Use relative links between docs for easy navigation.

Example:

See [Installation](./4-installation.md) to set up the project.

Writing Quality Tips​

  • Keep one main topic per page
  • Use short sections and actionable headings
  • Include copy-paste command blocks
  • Add troubleshooting near complex steps