Sphinx to Hugo
Convert Sphinx documentation to Hugo Markdown with references and migration reports.
Sphinx to Hugo is a Python command-line tool for moving documentation into a Hugo website. It uses Sphinx to parse source documents and resolve references, then extends the upstream Markdown builder to produce Hugo content and supporting files.
The converter writes page metadata, preserves supported code, math, figures, tables, and downloads, and records toctree relationships in a separate navigation manifest. Graphviz diagrams become SVG files with their DOT source retained. The output includes a small Hugo site for checking the conversion.
A typical conversion uses the source project’s trusted Sphinx configuration and writes to a fresh output directory
sphinx-to-hugo convert \
--source docs/source \
--config-dir docs/source \
--out /tmp/documentation-conversion \
--prefix /teaching/
The tool was used to migrate this website’s 236-document teaching collection. It remains an early release with a documented supported subset. Conversion reports identify unsupported constructs and unresolved references for review. Original input files are preserved.
Python 3.10 or newer is required. Install Graphviz for diagram conversion and Hugo to build the output. The project uses the MIT license. Source, installation, and conversion limits · MIT license