← Blog

Using Markdown for Technical Documentation

·7 min read
markdowndocumentationtechnical-writingdevelopment

Why Markdown for Documentation?

Technical documentation has a unique set of requirements. It needs to be easy to write, easy to maintain, version-controlled, and publishable in multiple formats. Markdown meets all of these requirements while remaining simple enough that anyone on the team can contribute, not just dedicated technical writers.

Before Markdown became the standard, teams wrote documentation in wikis, Word documents, or bespoke content management systems. Each approach had friction. Wikis required a running server. Word documents created merge conflicts in version control. Custom CMS platforms locked content into proprietary formats.

Markdown changed the equation. Documentation lives in the same repository as the code. Changes go through the same pull request process. Anyone with a text editor can contribute. And the output can be a static website, a PDF manual, or both.

Setting Up Your Documentation Structure

Folder Organization

A well-organized folder structure is the foundation of maintainable documentation. Here is a pattern that scales from small projects to large ones:

docs/
  index.md
  getting-started/
    installation.md
    quick-start.md
    configuration.md
  guides/
    basic-usage.md
    advanced-features.md
    troubleshooting.md
  api/
    overview.md
    endpoints.md
    authentication.md
  reference/
    configuration-options.md
    environment-variables.md
    cli-commands.md
  contributing/
    development-setup.md
    code-style.md
    pull-requests.md

Each folder represents a section, and each file is a page. The index.md in the root serves as the landing page. This structure maps naturally to a documentation website’s navigation.

Naming Conventions

Use lowercase, hyphen-separated filenames: getting-started.md, not Getting Started.md or getting_started.md. This convention avoids URL encoding issues and works consistently across operating systems.

The Landing Page

Your index.md should answer three questions immediately:

  1. What is this project?
  2. Who is it for?
  3. How do I get started?
# Project Name

Project Name is a [brief description]. It helps [target audience]
to [key benefit].

## Quick Links

- [Installation Guide](getting-started/installation.md)
- [Quick Start Tutorial](getting-started/quick-start.md)
- [API Reference](api/overview.md)
- [FAQ](guides/troubleshooting.md)

Writing Effective Documentation

The Four Types of Documentation

The Diataxis framework identifies four types of documentation, each serving a different purpose:

  1. Tutorials: Learning-oriented, step-by-step lessons for beginners. “Follow these steps to build your first project.”
  2. How-to Guides: Task-oriented instructions for specific goals. “How to configure SSL certificates.”
  3. Reference: Information-oriented, precise descriptions of the API or configuration. “The --verbose flag enables detailed logging.”
  4. Explanation: Understanding-oriented, discussions of concepts and design decisions. “Why we chose event-driven architecture.”

Most documentation fails because it mixes these types. A tutorial should not stop to explain architecture. A reference page should not include step-by-step instructions. Keep them separate.

Cross-Referencing

Link between documents liberally. Readers rarely start at the beginning and read sequentially. They land on a page from a search engine and need links to related content:

For more details on authentication, see the
[Authentication Guide](../api/authentication.md).

This feature requires the `advanced` plan.
See [Pricing](../reference/pricing.md) for details.

Use relative paths for internal links. This ensures links work both in the documentation site and when browsing files directly on GitHub.

Code Examples

Technical documentation lives or dies by its code examples. Every concept should have a working example:

### Creating a Client

```python
from mylib import Client

# Initialize with your API key
client = Client(api_key="your-api-key")

# Make a request
response = client.get("/users")
print(response.json())
```

> **Note**: Never commit real API keys. Use environment
> variables in production.

Make code examples:

  • Complete: Include imports, initialization, and cleanup.
  • Correct: Test every example. Broken code examples destroy trust.
  • Copy-pasteable: A reader should be able to copy the example into their editor and run it with minimal changes.

Versioning Documentation

When your software has multiple active versions, your documentation needs versioning too. There are several approaches:

Git branches: Maintain a documentation branch for each major version.

main          -> docs for latest version
v2.x          -> docs for version 2
v1.x          -> docs for version 1

Folder-based versioning: Keep version-specific docs in separate folders.

docs/
  latest/
  v2/
  v1/

Tool-based versioning: Many documentation platforms have built-in versioning support, which we will cover in the next section.

Documentation Site Generators

MkDocs

MkDocs is a Python-based static site generator designed specifically for documentation. It is simple, fast, and produces clean output.

# mkdocs.yml
site_name: My Project
theme:
  name: material
nav:
  - Home: index.md
  - Getting Started:
    - Installation: getting-started/installation.md
    - Quick Start: getting-started/quick-start.md
  - API Reference: api/overview.md

# Install
pip install mkdocs mkdocs-material

# Serve locally
mkdocs serve

# Build static site
mkdocs build

The Material for MkDocs theme is particularly popular. It provides search, dark mode, versioning support, and a responsive layout out of the box.

Docusaurus

Docusaurus, built by Meta, is a React-based documentation framework. It is more feature-rich than MkDocs but has a steeper learning curve:

npx create-docusaurus@latest my-docs classic
cd my-docs
npm start

Docusaurus supports MDX (Markdown with JSX), which lets you embed interactive React components directly in your documentation:

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>
</Tabs>

Other Options

  • GitBook: Commercial platform with a generous free tier. Excellent for teams that want a hosted solution.
  • VitePress: Vue-powered, fast, and lightweight. Great for Vue ecosystem projects.
  • Sphinx: The standard for Python project documentation. Supports reStructuredText and Markdown.
  • Astro Starlight: A newer option built on Astro, gaining popularity for its performance and flexibility.

Best Practices

Write for Your Audience

Know who reads your documentation. If your audience is experienced developers, you can assume familiarity with common tools and concepts. If it includes beginners, explain prerequisites explicitly.

Keep a Changelog

Maintain a CHANGELOG.md that tracks notable changes in each release:

# Changelog

## [2.1.0] - 2025-02-10

### Added
- Support for custom themes
- PDF export with table of contents

### Fixed
- Table alignment issue in dark mode
- Memory leak when processing large files

### Changed
- Default font changed from Arial to Inter

Follow the Keep a Changelog convention for consistency.

Use Admonitions

Most documentation tools support admonition blocks for warnings, tips, and notes:

:::warning
This action cannot be undone. Make sure to back up
your data before proceeding.
:::

:::tip
You can speed up builds by enabling caching in
your configuration file.
:::

Include a Search Function

For any documentation site with more than ten pages, search is essential. Both MkDocs (with the Material theme) and Docusaurus include search functionality. For static sites without built-in search, consider Algolia DocSearch.

Automate Documentation Updates

Use CI/CD pipelines to build and deploy documentation automatically when changes are merged:

# .github/workflows/docs.yml
name: Deploy Docs
on:
  push:
    branches: [main]
    paths: ['docs/**']
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

Generating PDF Documentation

Sometimes you need documentation in PDF format, for offline access, compliance requirements, or distribution to clients who prefer printed material.

You can convert your Markdown documentation to PDF using tools like printmd, which handles the layout, page breaks, and typography automatically. This is especially useful for:

  • User manuals that ship with a product
  • API documentation provided to enterprise clients
  • Compliance documentation that requires a dated, versioned PDF
  • Training materials distributed as printed handouts

The key is to write your Markdown with dual output in mind. Use standard Markdown features, avoid tool-specific extensions when possible, and test your documentation in both the web and PDF formats.

Conclusion

Markdown has become the standard for technical documentation because it removes friction from every part of the process: writing, reviewing, versioning, and publishing. Start with a clear folder structure, use the right tool for your needs, and follow the Diataxis framework to ensure your documentation serves every type of reader.

The best documentation is the documentation that gets written. Markdown’s low barrier to entry means more team members will contribute, and that is the biggest win of all.

Convert your Markdown to PDF with printmd

Try printmd