nebius/sphinx-mintlify-output

nebius/sphinx-mintlify-output

Language: Python

License: Apache-2.0

Stars: 1

Forks: 0

Open issues: 0

Created: 2026-06-10T15:00:24Z

Pushed: 2026-06-19T07:55:13Z

Default branch: master

Fork: no

Archived: no

README:

sphinx-mintlify-output

Sphinx builder that turns reST / MyST sources into a deploy-ready Mintlify project: .mdx pages with YAML frontmatter, copied static assets, and a docs.json navigation manifest.

Useful when your source of truth is reST/MyST (autodoc, intersphinx, sphinx-design) and you want to ship it through Mintlify without rewriting in MDX.

Install

pip install sphinx-mintlify-output
# or
uv add --dev sphinx-mintlify-output

Quickstart

In conf.py:

extensions = ["sphinx_mintlify_output"]

mintlify_docs_json = {
"name": "My Docs",
"theme": "mint",
"colors": {"primary": "#0d9373"},
}

Build:

sphinx-build -b mintlify docs out/mintlify

Point Mintlify at out/mintlify. Done.

Configuration

| Key | Default | Purpose | |-----|---------|---------| | mintlify_docs_json | {} | Merged into the generated docs.json | | mintlify_static_path | [] | Directories copied into out/static/ | | mintlify_image_dir | "images" | Where images land relative to outdir | | mintlify_frontmatter | {} | Default frontmatter merged into every page | | mintlify_component_map | {} | Override admonition → component mappings | | mintlify_emit_anchors | True | Emit ` anchors for autodoc entries and explicit targets (not section headings — Mintlify derives those from markdown) | | mintlify_externalize_assets | True | Pull inline SVG / base64 image URIs into images/ and reference them by path | | mintlify_base_path | "" | URL mount-point. Empty (default) → Sphinx-style **relative** links (../intro, images/foo.png) that work under any deployment prefix. Set to e.g. "/sandboxes/sdk"` to force absolute links rooted at that prefix when embedding into a larger Mintlify site that uses absolute paths everywhere |

What's translated

• reST / MyST core — headings, paragraphs, lists, code blocks, block

quotes, transitions.

• Tables — GFM by default; falls back to `` HTML for

rowspan / colspan / multi-line cells.

• Admonitions — note / tip / warning / ... → Mintlify

/ / / / . Use the directive's :class: option to pick , / , or `.

• sphinx-design — card → `, tab-set → ` (or

when every tab is a single code block), dropdown → , grids → `.

• Cross-references — :doc: / :ref: become relative links;

footnotes and citations become [^id] with matching definitions; abbreviations become ``.

• Images and figures — copied to images/; sized images switch to

; figure becomes (short caption) or ` with a rendered caption.

• Autodoc — Python signatures as anchored heading + fenced code

block; :param: → `; :returns: / :yields: / :raises: → `. Classes group their attributes and methods into a styled block.

• CLI options — .. option:: / cmdoption render as a `` with

backticked signature.

• Math — inline $…$ and block $$…$$.
• Raw HTML / MDX — passed through; inline `` and base64 data

URIs optionally externalised as files.

• Navigation — docs.json built from the toctree; mixed top-level

captioned + uncaptioned toctrees are handled. Override the result via mintlify_docs_json["navigation"].

Unknown nodes are skipped with a Sphinx warning rather than silently dropped.

Development

Requires Python 3.10+ and uv.

uv sync
uv run pytest
uv run mypy sphinx_mintlify_output
uv run ruff check .

tests/golden/ is a byte-exact corpus that pins the rendered output; uv run python tests/capture_golden.py refreshes it after an intentional change.

To add support for a new docutils node: write a TranslationNode subclass under sphinx_mintlify_output/nodes/, register it in the NODE_REGISTRY dict in nodes/__init__.py, and drop a fixture under tests/roots/test-/.

Status

Alpha. Feature-complete for the use cases above; API and config keys may shift before 1.0 — pin a version if you depend on the output layout.

Copyright

Nebius B.V. 2026, licensed under the Apache License, Version 2.0 (see [LICENSE](LICENSE)).