Introduction

Sphinx defaults to reStructuredText, but many teams prefer Markdown because contributors already use it across repositories. With MyST parser, you can keep Sphinx features such as directives, cross-references, and API docs while writing pages in Markdown. A practical migration is incremental, not a full rewrite in one commit.

Enable Markdown Support with MyST

Install MyST parser in your documentation environment.

python -m pip install sphinx myst-parser

Then update conf.py.

1extensions = [
2    "myst_parser",
3    "sphinx.ext.autodoc",
4    "sphinx.ext.napoleon",
5    "sphinx.ext.viewcode",
6]
7
8source_suffix = {
9    ".rst": "restructuredtext",
10    ".md": "markdown",
11}

This allows a mixed project where existing .rst files remain valid while new docs can be .md.

Keep Mixed Markup During Migration

You do not need to convert all pages immediately. A mixed structure keeps risk low.

1docs/
2  conf.py
3  index.rst
4  guides/
5    getting-started.md
6    deployment.md
7  api/
8    reference.rst

This pattern lets teams adopt Markdown where it helps most without destabilizing established docs.

Use Sphinx Directives in Markdown

MyST supports directive blocks using fenced syntax.

```{note}
This page uses MyST directive syntax.
```

Table of contents block:

1```{toctree}
2:maxdepth: 2
3:caption: Guides
4
5guides/getting-started
6guides/deployment
7api/reference
8```

This capability is the key reason to use Sphinx plus MyST rather than plain Markdown generators.

Cross-References and Labels in MyST

You can define labels and references in Markdown pages.

Label declaration:

(install-guide)=
## Installation

Reference from another page:

See {ref}`install-guide` for setup steps.

Page reference:

Read {doc}`guides/deployment` for rollout details.

Consistent labels are essential for large documentation sets.

API Docs and Markdown Guides Together

Sphinx remains strong for API extraction and type-aware docs. You can combine API pages and Markdown narratives in one build.

1def normalize_email(value: str) -> str:
2    """Normalize email before persistence.
3
4    Args:
5        value: Raw user input.
6
7    Returns:
8        Lower-cased and trimmed email.
9    """
10    return value.strip().lower()

With autodoc enabled, generated API pages can live beside Markdown guides under one site navigation tree.

Build Checks in CI

Treat docs like code by building on every pull request.

sphinx-build -b html docs docs/_build/html

Fail on warnings:

sphinx-build -b html -W docs docs/_build/html

This catches broken references and directive mistakes before merge.

Migration Strategy That Scales

A proven plan:

1. enable MyST and mixed suffixes
2. convert one section at a time
3. preserve existing labels where possible
4. run strict builds in CI
5. update contributor docs with Markdown conventions

Small migration steps produce cleaner reviews and easier rollback.

Team Authoring Practices

Define lightweight standards:

• heading depth rules
• label naming format
• code block language tagging
• toctree update checklist

When standards are clear, contributors can update docs without constant format debates. It also helps reviewers focus on technical accuracy instead of formatting disagreements. A shared authoring checklist makes onboarding easier for new documentation contributors.

Common Pitfalls

A common pitfall is using generic Markdown extensions instead of MyST and losing Sphinx directive compatibility.

Another pitfall is forgetting to declare both .md and .rst suffixes, causing pages to disappear from builds.

A third pitfall is attempting full-repo conversion in one change, which makes reviews brittle and error-prone.

Teams also skip warning-as-error builds, allowing broken references to accumulate.

Summary

• MyST parser enables Markdown authoring while preserving Sphinx capabilities.
• Mixed Markdown and reStructuredText projects are practical and low risk.
• Directives, toctrees, and cross-references work in Markdown with MyST syntax.
• CI docs builds with warnings as errors keep documentation quality stable.
• Incremental migration and clear team conventions produce the best long-term results.