Static Sites With Sphinx and Markdown

Sphinx is great for docs. But it's also great for information-rich websites. With MyST, you can use Markdown with Sphinx.

Edit this page

Everybody knows Sphinx for documenting projects, Python and otherwise. But few think of Sphinx for the rest of a website. Why? Because Sphinx traditionally means authoring with reStructuredText (RST) instead of Markdown. While RST is very powerful, it's a bit quirky, and nowhere near the popularity of Markdown.

But with the arrival of full Markdown support via MyST, and with static site generators having a renaissance, it's time to give Sphinx a second look. Sphinx is an "information-rich" static site generator, with rich linking and many other features for authoring.

This tutorial shows authoring Sphinx sites using Markdown and what it has to offer versus other approaches.

Audience

  • Existing Sphinx users that aren't yet using Markdown via MyST

  • Sphinx documentation writers interesting in site building beyond just docs

  • Static site users who aren't using Sphinx and don't know what they're missing

Goals

  • Quickly get oriented with Sphinx for static sites, beyond just documentation

  • Show how easy it is to switch to Markdown, and what kind of power you then get

  • Cover Sphinx's "special sauce": the data model of doctrees and references that change "pile of pages" into an interconnected site

Start learning »
Sphinx Setup
Sphinx Setup
Make a project and virtual environment with dependencies, then make a simple Sphinx website.
Linking
Linking
Sphinx turns links into structure, which turns out to be very valuable.