Static Sites with Sphinx and Markdown
summary
Sphinx now accepts Markdown via MyST and the myst-parser, so a Sphinx site can be authored in .md files while still using directives, YAML front matter, and autodoc to pull API docs from code. The system warns on broken links, resolves titles for link text, supports role targets and intersphinx cross‑site links, includes external files for code snippets, and produces HTML, PDF, man pages and other outputs — and it works out of the box.
AI-written summary · about
chapters (30)
- 0:00Intro
- 0:57Markdown and Python Easy to do headings, paragraphs, lists
- 1:18WAIT A SECOND !!!! That's not Markdown...
- 1:32Static Websites with Sphinx and Markdown
- 2:02Old Days
- 3:03Single Page App (SPA)
- 4:14Meanwhile, for docs
- 4:55What Does Sphinx Do?
- 5:27Sphinx Site
- 6:24Install MyST Spip install myst-parser
- 6:38Configure Sphinx for MyST extensions - "myst parser", ...
- 7:03index.rst - index.md
- 7:39How It Works
- 9:10Markdown Image ![Alt Text] static/logo.png
- 9:46Enhanced Markdown Image image static/logo.png :alt: Python Logo
- 10:05Basic Admonition
- 10:28Enhanced Admonition
- 10:54toctree With Options
- 11:56Markdown Link URL [link text]
- 12:26Without Link Text 014../path/to/doc
- 13:02Warning on Broken Link
- 13:23Linking to a Role Targets and Cross-Referencing
- 13:48Role & No Link Text
- 14:12Intersphinx
- 15:52Code Fence With Language
- 16:21Code Fence Options
- 16:33literal-include
- 18:11Lots More To Cover
- 19:29Plenty to Read
- 20:07What's the Future?
related talks
23mMkDocs: Documenting projects with Markdown
32mCustomizing Sphinx: Simple, Normal, and Hard
01h 06mDocument your code
26mBuild your static site with Python
36mSphinx autodoc: automated API documentation
05mCode Samples That Compile Even More Easily
36mBuilding Docs like Code: Continuous Integration for Documentation
18mThanks, I Made It with Quartodoc