Dynamic static sites with Django and Sphinx
2021-06-03, 09:15–10:00 (Europe/Paris), Main Room

You're building a content site? Can't face a CMS? Well have the best of all worlds!

Write your site content in Markdown. Manage it on the file system with git.
Use all the power of Sphinx to build your site, but server it with Django.

Cross-referencing, content super-powers meet auth, forms, interactivity,
dynamic content and all the rest of it. .

You don't have to choose, and you don't have to roll your own either.

On a content site these days, especially on a personal project, or where the
team are technical, you often don't want the limitations and complexity of full
CMS. No, you want to use familiar tools: you want to write in Markdown and
manage your content in git.

That doesn't necessarily fit the traditional Django workflow. You end up
looking at a static site. This is fine but you loose the ability of Django to
serve dynamic pages. You have to decide which of the numerous generators
you're going to use, or whether indeed you'll roll your own. It's a bit of a

You can have the best of all worlds though. Sphinx, yes the
documentation builder, is a super capable static site builder. You can
use it to build your content. Yes it can handle Markdown. Then you can
use Django to serve that content, given auth, forms, interactivity,
custom content, and all the rest of it.

I'm going to show you how.

The talk has two parts: Sphinx and then Django.

  • First we'll introduce using Sphinx to manage and build your content.
  • We'll look at project setup so you can use Markdown for files.
  • We'll organise those on the file system, and use git to manage them, rather
    than a full-blown CMS.
  • We'll push to GitHub and use a GitHub Action to build on each commit.
  • Then we'll setup Django to serve our Sphinx built content.
  • We'll use the DTL to get control over our templates.
  • And we'll add auth, to provide dynamic per-user content.

From there, the sky's the limit. Content management never looked so rosy.

See also: Slides from the Talk

I'm one of your friendly Django Fellows, working on Django, and helping out on various packages in the ecosystem. When I'm not doing that, I co-host the DjangoChat podcast — I should probably get out more. I've got lots of kids, so they keep me busy.

I'm @carltongibson on Twitter and GitHub and I'm secretly building a simpler story for deployment at btn.dev