Use Docusaurus or Sphinx to build the docs site

Review by

2027-01-10

How to do it

Both pass the five tests. Docusaurus 1.0.0 came out on 9 June 2017, and 3.10.2 on 10 July 2026. @docusaurus/core had about 1.3 million weekly npm downloads in the week to 1 July 2026. Its last release is from July 2026, so it fails the six-month test after 10 January 2027 unless a new one ships. Sphinx 1.0 came out on 23 July 2010, and 9.2.0 on 21 October 2026, with about 4.8 million weekly PyPI downloads. Sphinx also builds API reference pages from Python docstrings. Both fail on broken links in strict mode, as Build the docs in CI and fail on every warning requires. MkDocs fails the release test, since its last release, 1.6.1, came out on 30 August 2024. Choose something else when the docs are a few pages. A folder of Markdown files on the code host is then enough.

Examples

JavaScript example

// docusaurus.config.js
export default {
  title: 'Harbour Bakery API',
  url: 'https://docs.example.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  presets: [['classic', { docs: { routeBasePath: '/' } }]],
};

Shell example

python -m sphinx -W --keep-going -b html docs docs/_build/html

How to check

The CI docs job runs docusaurus build with onBrokenLinks: 'throw', or sphinx-build -W. A link to a missing page makes the job fail.

Related rules

• DOC-8 Build and test the docs in CI and fail on every warning in Documentation