Markdown Documentation: How to Write Docs in Markdown

Markdown documentation is a set of plain-text .md files, kept in version control next to the code, that a tool renders into a website, PDF, or Word file. This guide shows how to structure a multi-page docs folder and gives you a copy-paste page template plus an API endpoint template. It also helps you pick between a README, MkDocs, Docusaurus, and Pandoc.

What Is Markdown Documentation?

The term means writing your project's guides, references, and changelogs as Markdown files instead of in a wiki editor or a Word document. Each page is a text file with headings, lists, links, and fenced code blocks. A renderer turns those files into HTML.

Teams choose Markdown for documentation because the files live in the same repository as the software, an approach usually called docs-as-code. The .md documentation files get branches, pull requests, code review, and history for free. Microsoft Learn and Adobe Experience League both author their public docs this way, and each publishes a contributor guide describing their Markdown conventions.

The main trade-off is layout control. Markdown gives you structure, not design, so anything beyond headings, tables, and callouts depends on the site generator you choose. We think that's a fair deal for technical docs, where consistency matters more than custom layouts.

How to Structure a Markdown Docs Folder

Most projects start with a single README and outgrow it. The README Markdown guide covers that first file; this section is about what happens when one page isn't enough.

One convention works with GitHub, MkDocs, and Docusaurus alike. Put a docs/ folder at the repository root, one Markdown document per topic, and an index.md as the landing page:

docs/
  index.md            # what the project is, where to start
  getting-started.md  # install and first run
  guides/
    configuration.md
    deployment.md
  reference/
    cli.md
    api.md
  faq.md
  changelog.md

GitHub renders every one of those files when you browse the repository, and GitHub Pages can publish straight from the folder. Per GitHub's Pages documentation, the publishing source can be either the repository root or a /docs folder on the source branch. That single sentence is why so many projects use this exact name.

Link between pages with relative paths, not full URLs. GitHub's writing guide recommends relative links because they keep working in clones and on every branch. [Configuration](./guides/configuration.md) resolves on GitHub, in MkDocs, and in Docusaurus; a full https:// URL only works in one of those places.

Three habits keep a docs folder readable as it grows:

• One H1 per file, matching the page title, then H2s for sections. Skipping from H1 to H3 breaks generated sidebars and screen readers.
• Language tags on every fenced code block (bash, json, yaml) so highlighting works. The Markdown code block guide lists the common tags.
• A table of contents on any page longer than a screen. The Markdown table of contents post shows manual and generated options.

Markdown Documentation Page Template

Here's the page skeleton we use for a guide page. It fits GitHub, MkDocs, and Docusaurus without changes. Edit it live, then copy it into your docs/ folder.

Every element in that template renders the same way across the three tools. That covers headings, an ordered list of steps, a GFM table for settings, bold lead-ins for troubleshooting, and relative links. That's the point of a template. If you stick to CommonMark plus GFM tables, your docs are portable.

How Do You Write API Documentation in Markdown?

Markdown for API documentation follows one pattern per endpoint. Start with a heading that holds the method and path, then a sentence on what it does, a parameters table, and request and response code blocks. Repeat it for every endpoint and the reference stays scannable.

### GET /users/:id

Returns a single user by ID.

#### Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| id | string | yes | The user ID, for example u_123 |

#### Example request

```bash
curl https://api.example.com/users/u_123 \
  -H "Authorization: Bearer TOKEN"
```

#### Example response

```json
{ "id": "u_123", "name": "Ada", "created_at": "2026-01-15T09:30:00Z" }
```

Two things make API docs Markdown files easier to maintain. First, keep API documentation Markdown files to one resource each (users.md, orders.md) rather than one giant api.md, so pull requests touch only the endpoints that changed. Second, generate what you can. If you already have an OpenAPI file, tools such as widdershins produce a Markdown API documentation set from it, and you hand-write only the guides around it.

One caveat: Markdown has no way to mark a parameter as deprecated or to link a response schema to a definitions page beyond a plain link. For large APIs, a rendered OpenAPI page usually wins for the reference section, with Markdown docs for tutorials alongside it.

Callouts, Tables, and Other Docs Markdown Features

Documentation leans on a handful of GFM extensions that basic Markdown doesn't have. The three that matter most:

Alerts and admonitions. On GitHub, a blockquote that starts with > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], or > [!CAUTION] renders as a coloured callout. MkDocs and Docusaurus use different syntax (!!! note and :::note respectively), which is the most common thing to fix when moving docs between tools. The Markdown callout post compares them.

Tables. Parameter tables, option tables, and comparison tables are all GFM pipe tables. Keep them narrow; a table with more than five columns is unreadable on a phone and better expressed as a list of definitions.

Task lists. - [ ] and - [x] render as checkboxes on GitHub and are handy in release checklists inside a RELEASING.md file.

Changelogs. A changelog.md with one H2 per version and bullet lists under Added, Changed, and Fixed is the most-read documentation Markdown file in many repositories. Keep the newest version at the top and link each entry to its pull request so readers can trace a change to its code.

If your team is weighing Markdown against reStructuredText, the Markdown vs reStructuredText comparison covers where RST's directives pull ahead and where Markdown's simplicity wins. For most projects, Markdown docs are the default and RST is the exception for Sphinx-based Python projects.

README, MkDocs, Docusaurus, or Pandoc?

The same Markdown documents can be published four ways. GitHub renders them in place, MkDocs and Docusaurus convert Markdown to documentation websites, and Pandoc turns them into files. Pick by output, not by fashion.

Need	Use	Why
A few pages read on GitHub	README plus a docs/ folder	Zero build step; GitHub renders the files
A searchable docs website	MkDocs	Python-based, docs/ folder plus a mkdocs.yml nav
A docs site inside a React project, with versioning	Docusaurus	Docs in docs/, ordering via sidebar_position front matter
A PDF or Word handoff	Pandoc or an online converter	One command turns Markdown into DOCX or PDF

MkDocs reads a docs directory by default, renders it with Python-Markdown, and takes its sidebar from a nav: list in mkdocs.yml. An index.md (or README.md) becomes the home page. Docusaurus also reads a docs folder and can build the sidebar automatically, ordering pages with a sidebar_position: 2 line in each file's front matter. Both are covered in depth in our MkDocs Markdown guide and Docusaurus Markdown guide.

For a handoff to someone who wants a file, not a site, use Pandoc: pandoc guide.md -o guide.docx produces Word, and pandoc guide.md -o guide.pdf produces PDF. The manual notes that PDF output uses LaTeX by default, so you need a LaTeX engine installed or a --pdf-engine such as weasyprint or typst. If installing that is more than you want, the Markdown to PDF converter does the same job in the browser with no setup.

Common Markdown Documentation Mistakes

Absolute links between pages. https://github.com/org/repo/blob/main/docs/x.md breaks in MkDocs and in forks. Use ./x.md.

Untagged code blocks. A fence without a language renders as grey text with no highlighting, and some generators can't distinguish shell input from output. Tag every block.

One 4,000-word page. Long pages are hard to link into and slow to review. Split at each H2 that could stand alone, and add a landing page that links the pieces.

Markdown Documentation FAQ

Good markdown documentation comes down to a predictable docs/ folder, one H1 per page, tagged code blocks, relative links, and a template you reuse. Choose the publishing tool last, since the same files work on GitHub, in MkDocs and Docusaurus, and through Pandoc. Draft your next page in the editor, check the preview, and commit it alongside the code.