Switching from Sphinx to Markdown
summary
Argues Markdown is deliverable not just desirable: conversion uses Pandoc plus custom regex scripts, MkDocs (and forks like Proper Docs/Zenscroll), mkdocstrings, PyMdown Extensions, Weblate and the translate-toolkit, tox for build wrappers. Migration timeline and scope are concrete: 9 months, 37 PRs, ~3,000 files, ~700k lines touched (net +83k); tutorial 2 weeks, Toga ~2.5 months, Briefcase 3 days, Rubicon ~2 weeks, website >3 months. Live-preview speed, type alias support, and automated translation builds are the actual wins demonstrated.
AI-written summary · about
chapters (18)
- 0:00Introduction to switching documentation formats
- 1:28What is reStructuredText
- 3:58Markdown as alternative
- 6:25Comparing strengths of both formats
- 7:26BeeWare migration journey
- 9:09Preparing for Markdown migration
- 12:00Handling translations
- 14:50Automating RST to Markdown
- 18:01Migrating tutorial docs
- 18:42Converting Toga API docs
- 20:29Briefcase docs in days
- 21:11Rubicon Objective-C challenges
- 21:52Rebuilding site in Markdown
- 23:14Human side of migration
- 25:40Migration timeline and scale
- 26:44Was migration worth it?
- 27:27MkDocs ecosystem
- 28:36Q&A
related talks
32mSwitching from Sphinx to Markdown
42mTwo years of Markdoc: what we’ve learned about balancing developer and author experience
27mGoing from Publican to Read the Docs
40mFrom resistance to adoption: navigating the challenges of docs-like-code
27mPractical Sphinx
44mPushing documentation (so it doesn't hurt anymore)
41mEmbracing the Kraken : How to build a docs-toolchain monster and why it’s OK
28mBeyond Skeuomorphic Markdown