Can this Replicate Features from Sphinx ReadTheDocs?

[wesleyboar]

Background

Some potential clients —

• life_sciences_ml_at_tacc
• containers_at_tacc

— use reStructuredText.

Question

What is required to support porting those clients to Markdown with MkDocs?

[wesleyboar]

I researched all the reST and Sphinx syntax used by those clients.

Legend & Summary

Symbol	Meaning	Instances 1
✅	simple to convert	8
ℹ️	can convert, with caveat	2
⚠️	not simple to convert	4
💡	maybe a way to convert	0
❌	can not convert	0
❓	unknown	0

Roles

:ref:

Details

• Links to entire documents
• Uses document's first title if no link text provided
• Breaks if file moves/renames
• Has build-time verification
• Updates if document title changes
• Can reference special names (genindex, modindex, search that Sphinx auto-generates

ℹ️ Convert

• ℹ️ try mkdocs-autorefs
• 💡 consider custom index generation via mkdocs-macros-plugin

:doc:

Details

• Links to specific sections using labels
• Labels are defined with .. _label-name:
• Works even if file moves/renames
• Has build-time verification
• Updates if section title changes
• Can be used for both document and section references

✅ Convert

mkdocs-autorefs

Special Names

genindex

Details

• Automatically generated general index
• Contains all index entries from :index: roles
• Referenced using :ref: role

⚠️ Convert

• ❌ No direct equivalent in MkDocs
• 💡 Consider using mkdocs-macros-plugin for custom index generation

modindex

Details

• Automatically generated module index
• Contains all Python module entries
• Referenced using :ref: role

⚠️ Convert

• ❌ No direct equivalent in MkDocs
• 💡 Consider using mkdocstrings for Python module documentation

search

Details

• Automatically generated search page
• Provides full-text search functionality
• Referenced using :ref: role

✅ Convert

• ✅ Built-in search functionality in MkDocs
• ✅ Enhanced by mkdocs-material with better search experience
• ✅ Can be customized with mkdocs-search

:math:

✅ Convert

pymdown-extensions arithmatex

1. ✅ python-markdown attr_list
2. ✅ python-markdown attr_list
3. ✅ python-markdown attr_list
4. ❓ Use \begin{align}...\end{align} for aligned equations

:align:

✅ Convert

python-markdown attr_list

• ✅ add style via python-markdown attr_list
• ✅ add class via python-markdown attr_list

HTML Attributes e.g. :class:, :width:

✅ Convert

python-markdown attr_list

Directives

.. toctree::

Details

0. Name for ToC Link
1. :maxdepth:
2. :name:
3. :caption:
4. :numbered:
5. :titlesonly:
6. :glob:
7. :reversed:
8. :hidden:
9. :includehidden:

⚠️ Convert

[TOC]
0. ❌

1. ⚠️ options: CSS or custom plugin for [TOC:_] or manual list
2. ❌ — [TOC]{ #name } fails
3. ✅ add ### Caption above [TOC]`
4. ℹ️ global CSS
5. ❌
6. ❌
7. ℹ️ global CSS
8. ❓
9. ❓

.. code-block::, sourcecode, code

Details

1. lineos
2. lineno-start
3. emphasize-lines
4. force
5. caption
6. name
7. class
8. dedent

⚠️ Convert

python-markdown fenced_code and pymdown-extensions superfences

1. ✅ linenums
2. ✅ linenums
3. ✅ hl_lines
4. ❓ pymdown-extensions highlight
5. ✅ title
6. ✅ add id via python-markdown attr_list
7. ✅ add class via python-markdown attr_list
8. ⚠️ deindent manually

.. math::

Details

0. :class:
1. :name:
2. :label:
3. :no-wrap:

ℹ️ Convert

pymdown-extensions arithmatex

1. ✅ add class via python-markdown attr_list
2. ✅ add id via python-markdown attr_list
3. ❓
4. ❓ maybe \begin{align}...\end{align}

.. image::

Details

1. :alt:
2. :width:
3. :align:
4. :target:
5. :scale:
6. :height:

✅ Convert

• Markdown image (![](…)) syntax
• python-markdown attr_list

.. figure::

Details

1. :alt:
2. :width:
3. :align:
4. :target:
5. :scale:
6. :height:
7. :figclass:
8. :name:

✅ Convert

• Markdown image (![](…)) syntax
• pymdown-extensions blocks.caption
• python-markdown attr_list

.. note::, .. warning::

Details

1. :class:
2. :name:

✅ Convert

pymdown-extensions blocks.admonition

• python-markdown attr_list

References

Some popular plugins may assist in converting other features.

💡 Convert

• mkdocs-awesome-nav
  ^{(f.k.a mkdocs-awesome-pages-plugin)}

Footnotes

1. Instances in overall evaluations. Evaluation details may have instances that are aggregated into a different overall evaluation. ↩

[wesleyboar]

Important

Answer: Yes, with some effort.

Tip

Regex and A.I. can help.