Markdown for Documentation — Structuring Technical Docs with Markdown

Markdown has become the standard for technical documentation. Documentation sites like Docusaurus, MkDocs, and GitBook all use Markdown, adding specialized features for navigation, callouts, and versioning.

Use the Markdown Preview to preview documentation as you write.

Documentation site generators

Structuring documentation

File organization

docs/
  getting-started/
    installation.md
    quick-start.md
  api/
    authentication.md
    endpoints.md
    errors.md
  guides/
    deployment.md
    configuration.md
  reference/
    configuration.md
    cli.md

Heading hierarchy

# Page Title (H1 — one per page)

Introduction paragraph.

## Major Section (H2)

Section content.

### Subsection (H3)

Subsection content.

#### Deep Subsection (H4 — use sparingly)

Deep content.

One H1 per page. H2s become the primary navigation entries. H3s are sub-navigation.

Docusaurus-specific Markdown

Front matter

---
title: Installation Guide
description: How to install MyPackage
sidebar_position: 1
sidebar_label: Installation
---

# Installation

Admonitions (callout blocks)

:::note
Regular informational note.
:::

:::tip
A helpful tip for the reader.
:::

:::info
Important information.
:::

:::warning
Potential issue to be aware of.
:::

:::danger
Action that could cause data loss or breakage.
:::

:::note Custom Title
Override the title.
:::

Code blocks with titles

```javascript title="src/auth.js"
function login(username, password) {
  // ...
}
```

Tabs

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="npm" label="npm">
    ```bash
    npm install my-package
    ```
  </TabItem>
  <TabItem value="yarn" label="Yarn">
    ```bash
    yarn add my-package
    ```
  </TabItem>
  <TabItem value="pnpm" label="pnpm">
    ```bash
    pnpm add my-package
    ```
  </TabItem>
</Tabs>

MkDocs Material theme

Configuration (mkdocs.yml)

site_name: My Documentation
theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - content.code.annotate
    - content.tabs.link

nav:
  - Home: index.md
  - Getting Started:
    - Installation: getting-started/installation.md
    - Quick Start: getting-started/quick-start.md
  - API Reference:
    - Authentication: api/authentication.md
    - Endpoints: api/endpoints.md

Admonitions in MkDocs

!!! note
    This is a note.

!!! warning "Custom Title"
    This warning has a custom title.

??? info "Collapsed by default"
    Click to expand this content.

!!! tip inline end
    This tip appears to the right.

Writing good documentation

The DITA information types

# Concept Doc (What is it?)
An explanation of what something is and why it exists.
No code required.

## Task Doc (How to do it?)
Step-by-step instructions.

1. Open the configuration file
2. Add the following section
3. Save and restart

## Reference Doc (Complete specification)
| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| host   | string | localhost | Database host |
| port   | number | 5432 | Database port |

Code example best practices

## Install the package

```bash
npm install my-package

Basic usage

import { MyClass } from 'my-package';

const instance = new MyClass({
  apiKey: process.env.API_KEY,
});

const result = await instance.doSomething({ input: 'value' });
console.log(result);

Configuration options

## Documentation SEO

```markdown
---
title: Getting Started with MyPackage
description: Install MyPackage and build your first integration in 5 minutes.
---

• Unique, descriptive titles for every page
• Meta description under 160 characters
• Use keywords naturally in headings and first paragraph
• Canonical URLs for versioned documentation

Related tools

• Markdown Preview — preview Markdown rendering
• Markdown Cheatsheet — complete Markdown syntax
• Markdown Code Blocks — syntax highlighting in docs