An example of how to use Sphinx to create a beautiful documentation site with markdown.
- Write documentation in markdown
- Automatically rebuild the site in local development when files is saved
- Table of contents with sub-header anchor links
- Auto-generated search functionality
- Easy to serve the docs on ReadTheDocs
- Fork https://github.com/adamghill/sphinx-markdown-docs
git clone https://github.com/GITHUB_USER/sphinx-markdown-docs
curl -sSL https://install.python-poetry.org | python3 -
poetry install
- Update
docs/source/conf.py
for your project
poetry run sphinx-autobuild -W -b dirhtml docs/source docs/build
- Go to http://localhost:8000
- Edit/add markdown files in
docs/source/
directory - Update the
toctree
indocs/source/index.md
poetry run sphinx-build -W -b dirhtml docs/source docs/build
- Sphinx: awesomely powerful documentation tooling
- MyST: markdown parser for
Sphinx
- furo: beautiful theme built by pradyunsg
- sphinx-autobuild: automatically re-generates documentation when the markdown is updated
- poetry: sane Python dependency management
- mkdocs: fast, simple and downright gorgeous static site generator that's geared towards building project documentation.
- mdBook: Create book from markdown files. Like Gitbook but implemented in Rust.
- Docusaurus: Easy to maintain open source documentation websites.
- Retype: an ✨ ultra-high-performance ✨ generator that builds a website based on simple text files.