sphinx-mintlify-output 0.1.0

Sphinx builder that emits Mintlify-compatible MDX and docs.json

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 <a id> 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 <table> HTML for rowspan / colspan / multi-line cells.
• Admonitions — note / tip / warning / ... → Mintlify <Note> / <Tip> / <Warning> / <Info> / <Danger>. Use the directive's :class: option to pick <Check>, <Steps> / <Step>, or <Callout>.
• sphinx-design — card → <Card>, tab-set → <Tabs> (or <CodeGroup> when every tab is a single code block), dropdown → <Accordion>, grids → <Columns cols={N}>.
• Cross-references — :doc: / :ref: become relative links; footnotes and citations become [^id] with matching definitions; abbreviations become <Tooltip>.
• Images and figures — copied to images/; sized images switch to <img>; figure becomes <Frame caption=…> (short caption) or <Frame> with a rendered caption.
• Autodoc — Python signatures as anchored heading + fenced code block; :param: → <ParamField>; :returns: / :yields: / :raises: → <ResponseField>. Classes group their attributes and methods into a styled block.
• CLI options — .. option:: / cmdoption render as a <dl> with backticked signature.
• Math — inline $…$ and block $$…$$.
• Raw HTML / MDX — passed through; inline <svg> 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-<name>/.

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).