Investigate moving invenio.rtfd.io to MkDocs

[diegodelemos]

• Document what are the implications
  • Are there blockers?
  • What problems are we getting in exchange?
  • Do we have to put more work than needed to have the same content displayed? (i.e. imagine we need Sphinx autodoc and MkDocs doesn't provide it, we are not going to reimplement it)

If it makes sense to make the migration:

• Move docs
• Change look and feel to inveniosoftware's Framework style (https://inveniordm.docs.cern.ch/, https://invenioils.docs.cern.ch/)
• Manage redirects and broken links

[topless]

MkDocs for invenio

Sphinx	MkDocs
✔️	✔️	autodoc support
✔️	✔️	table of contents
✔️	✔️	theme support
✔️	✔️	extension support
➖	✔️	search (preview)
➖	✔️	shortcuts for navigation

for the comparison invenio (sphinx), invenio-rdm, invenio-ils and reana (mkdocs) docs were used.

pros

• consistent look and feel for invenio ecosystem
• replacing rst format with widely used md
• easier customization
• automatic translation rst -> md

cons

• will require some work for the migration
• possibly will need to re-organize the docs a bit

more

• introduce markdown lint for even higher quality
• dead link validation

observations

1. As far as I can tell there is no feature from Sphinx that does not already exist in MkDocs. There are no obvious blockers.
2. TOC of contents might need some extra work to be migrated automatically.
3. Possibly static files i.e. images might have to be moved and corrected manually.
4. We will have to decide how we will organize the content in the new layout & navigation.

[aigentic-net]

Updated assessment (March 2026)

@topless's comparison from August 2020 was thorough and found no blockers. Since then, the MkDocs ecosystem has matured significantly:

What's improved since 2020:

• Material for MkDocs is now the de facto standard theme, with built-in search, dark mode, versioning, code annotation, content tabs, and admonitions
• mkdocstrings provides autodoc-quality API documentation from Python docstrings (parity with Sphinx autodoc)
• mike handles documentation versioning (equivalent to ReadTheDocs version selectors)
• markdown-link-check and mkdocs-linkcheck handle dead link validation natively
• markdownlint-cli2 provides consistent Markdown linting

Ecosystem alignment:

The Invenio ecosystem has already migrated:

• invenio-rdm documentation uses MkDocs
• invenio-ils documentation uses MkDocs
• REANA documentation uses MkDocs

The invenio framework docs remain the only major holdout using Sphinx/RST.

Migration path:

1. rst2myst or pandoc can convert .rst to .md in bulk (the 2020 assessment noted this)
2. Static files (images, diagrams) may need path adjustments
3. Navigation structure would need to be defined in mkdocs.yml
4. API docs via mkdocstrings would need a configuration pass

Recommendation:

The investigation requested in this issue is complete -- @topless's 2020 analysis confirmed feasibility and the ecosystem has only strengthened the case since. This issue should either:

1. Be converted into a migration task (with a concrete plan and milestone), or
2. Be closed as "investigation complete" with a new issue opened for the actual migration when prioritized

The decision is a maintainer/governance call on timing, not a technical blocker.