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.

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.