Mintlify compatibility

Mintlify compatibility

Tangly renders Mintlify projects unmodified. This page is the matrix of what and how: every component, field, and behavior, with notes on where Tangly and Mintlify differ.

If you’re starting from a working Mintlify project, the migration guide walks the swap. This page is the reference you’d want when something looks off.

docs.json fields

Every Mintlify-shipped top-level field is supported.

Mintlify field	Tangly	Notes
name	✅	Identical.
description	✅	Identical.
theme	✅	Mintlify themes (mint, maple, palm, willow, linden, almond, aspen, luma, sequoia) all alias to tang. See Aliases.
logo	✅	Identical. String + { light, dark, href } both supported.
favicon	✅	String + { light, dark }.
colors	✅	primary, light, dark, background, anchors all match.
navigation	⚠️	Tabs, groups, dropdowns, and anchors render with identical recursion. Top-level anchors-as-nav (a navigation.anchors[] entry that wraps whole tabs/groups) resolve too. versions / languages parse (schema-accepted) but aren’t rendered yet: their groups are flattened into one sidebar, so a migrated multi-version project shows every version’s groups at once instead of a switcher.
navbar	✅	links + primary (button + github variants).
footer	✅	socials, links. Tangly adds lastUpdated, editUrl, repo.
redirects	✅	[{ source, destination, permanent? }]. A { "$ref": "./redirects.json" } external file works too (see $ref below).
seo	✅	metatags, indexing (all / navigable).
analytics	✅	All twelve providers Mintlify supports + same shape.
api	✅	baseUrl, auth, playground, openapi, viewer. Tangly adds asyncapi, mdx.
appearance	✅	default, strict. Tangly adds readingTime, readingProgress.
fonts	✅	Heading + body.
styling	✅	eyebrows, codeblocks.
code	✅	copyButton, theme.
background	✅	image, color, decoration.
errors	✅	404.redirect.
banner	✅	content, dismissible, id, type.
contextual	✅	options (copy, view, chatgpt, claude).
metadata	✅	Identical.
icons	✅	library.
search	✅	prompt.
integrations	✅	Free-form bag (Mintlify and Tangly both treat this as passthrough).
thumbnails	⚠️	Schema accepted; auto-thumbnail generation on roadmap.

Unknown fields don’t fail validation. Zod’s passthrough() preserves them. Mintlify-extension fields you’ve added survive tangly migrate.

MDX components

Every component Mintlify ships, plus extras Tangly adds.

Cards & layout

Component	Tangly	Notes
<Card>	✅	image prop is aliased to Tangly’s img. Same shape.
<CardGroup>	✅	cols 1–4.
<Columns>	✅	cols 1–12.

Callouts

Component	Tangly	Notes
<Note>	✅	Identical.
<Tip>	✅	Identical.
<Warning>	✅	Identical.
<Info>	✅	Identical.
<Check>	✅	Identical.
<Danger>	✅	Identical.
<Update>	✅	label, description, tags. Identical.

Tabs & steps

Component	Tangly	Notes
<Tabs>	✅	name for cross-page sync.
<Tab>	✅	title, icon.
<Steps>	✅	Identical.
<Step>	✅	title, icon, titleSize, stepNumber.

Accordion

Component	Tangly	Notes
<Accordion>	✅	title, defaultOpen, icon, description.
<AccordionGroup>	✅	Identical.

Code

Component	Tangly	Notes
<CodeGroup>	✅	name for cross-page sync.
<Snippet>	⚠️	Placeholder. Disk resolution on v0.3 roadmap. Use <Embed> today.
<PackageManager>	✅	Tangly extra. Pre-built tabs for npm/yarn/pnpm/bun.

API

Component	Tangly	Notes
<ParamField>	✅	path/query/body/header, type, required, default, deprecated.
<ResponseField>	✅	Same shape.
<RequestExample>	✅	Identical.
<ResponseExample>	✅	Identical.
<OpenApiEndpoint>	✅	Tangly’s built-in viewer. A root openapi.{json,yaml,yml} is auto-discovered when no spec is configured, so openapi: "METHOD path" pages render with zero wiring.
<OpenApiRedoc>	✅	Tangly extra.
<OpenApiScalar>	✅	Tangly extra.
<OpenApiStoplight>	✅	Tangly extra.

Media

Component	Tangly	Notes
<Frame>	✅	caption.
<Video>	✅	YouTube, Vimeo, mp4 auto-detect. Tangly enriches: lazy-load, transcript link.
<LightboxImage>	✅	Auto-applied to every inline image.
<Embed>	✅	Tangly extra. Labeled-block embedding.
<FileTree>	✅	Tangly extra.

Text helpers

Component	Tangly	Notes
<Icon>	✅	Lucide. FA aliases for 100+ common Mintlify names, with a PascalCase fallback to any Lucide icon. See Icons.
<Tooltip>	✅	Identical.
<Link>	✅	href anchor; internal links get the base prefix, external open in a new tab.
<Badge>	✅	Tangly extra.
<Kbd>	✅	Tangly extra. Auto Cmd→Ctrl on non-mac.
<Expandable>	✅	Identical.
<GlossaryTerm>	✅	Tangly extra. Pairs with glossary auto-linking.

Frontmatter

Every Mintlify-shipped frontmatter field is supported.

Field	Tangly	Notes
title	✅	Identical.
description	✅	Identical.
sidebarTitle	✅	Identical.
icon	✅	Lucide / FA aliases.
tag	✅	Identical.
openapi	✅	METHOD path.
openapi-schema	✅	#/components/schemas/<Name>.
api	✅	Companion-MDX for hand-curated API pages.
keywords	✅	Identical.
noindex	✅	Identical.
mode	✅	default, wide, center, custom, frame, api. custom/frame are full-bleed (no sidebar, edge-to-edge); center drops the sidebar.
seo	✅	title, description, ogImage.

Tangly adds: draft, template, aiContext, lastUpdated, readingTime, editUrl, glossary. See Frontmatter.

Behavioral differences

Image optimization is off

Mintlify ships some image processing. Tangly disables @astrojs/mdx optimize and image.service: noop. Reason: Mintlify projects often reference absolute external URLs that bypass image pipelines anyway. If you need optimization, eject and turn it back on.

Relative image paths get rewritten

Mintlify resolves ![](../images/foo.png) at runtime. Tangly’s MDX preprocessor rewrites these to absolute (/images/foo.png) before Astro’s pipeline sees them. Reason: avoids cache misses on every relative path during HMR.

If you ship a Tangly-native project, use absolute paths from day one.

<latex> rewrite

Mintlify uses <latex>…</latex>. Tangly accepts both the latex tag (rewritten to $$…$$) and $$…$$ directly. KaTeX renders both identically.

Theme aliases collapse to tang

mint, maple, palm, willow, linden, almond, aspen, luma, sequoia all resolve to tang. Reproduce a specific Mintlify variant by setting theme: "tang" and overriding colors. See Aliases.

tangly migrate doesn’t auto-rewrite themes

Migration validates docs.json and updates $schema. It does not auto-pick a Tangly theme. Run it, see the notice, decide for yourself. If you want it auto-picked, that’s a one-line sed.

Reserved files and the home page

Tangly matches Mintlify here:

• A root index.mdx is the site home and renders at /. It doesn’t need to appear in navigation.
• README.md, LICENSE.md, CHANGELOG.md, and CONTRIBUTING.md are auto-ignored (never pages).
• AGENTS.md is rendered as a page, same as Mintlify.

See Page anatomy → Files that aren’t pages for the full list.

Config splitting with $ref

A docs.json can split across files via JSON $ref — { "$ref": "./redirects.json" }, per-language nav files, etc. Tangly resolves refs (relative to the referencing file, with #/pointer fragments and nested refs) before validation, so a multi-file config loads as one document.

Snippet imports

import { X } from "/snippets/foo.mdx" resolves to <project>/snippets/foo.mdx. Markdown/MDX snippets render as content.

An imported MDX snippet inherits the page’s global component set, so a snippet that uses <Note>, <Card>, or any other built-in renders those correctly (including snippets that import other snippets).

.jsx/.tsx snippets render as interactive Preact islands, so Mintlify-style React snippets work unmodified. Hooks (useState, useEffect, …) are injected as globals the way Mintlify exposes them, and a client:visible directive is auto-attached at each call site so the component hydrates when scrolled into view (write an explicit client:load/client:idle to override). react/react-dom alias to preact/compat, so most React components render as-is. A page with no JSX snippet ships zero extra client JS.

Search engine: Pagefind, not Mintlify’s

Tangly bundles Pagefind. Mintlify uses a different indexer. Behavior is similar (Cmd-K modal, fuzzy match) but the index file format and tuning knobs differ. Practical impact: zero for readers; for advanced search customization (boost rules, exact-match weighting), you’d configure Pagefind directly via custom build hooks.

No “API playground proxy”

Mintlify’s api.playground.proxy: true proxies try-it-out through their edge to bypass CORS. Tangly accepts the field but the proxy is a no-op; you need to fix CORS at your API. If your API can’t be CORS-permissive, the try-it-out form won’t work; use api.playground.mode: "hide" to remove it.

What’s not in Tangly yet

These are on the v0.3 roadmap:

• Snippet disk resolution. <Snippet file="..." /> reading from snippets/.
• Version / language switching. navigation.versions and navigation.languages parse but don’t render a switcher yet; their groups are flattened into one sidebar. Single-version projects are unaffected.
• OG thumbnail generation. Auto-render social previews.
• API playground proxy. Same shape as Mintlify’s, server-side.

For workarounds today, see FAQ.

Where to file gaps

If something doesn’t render the same as Mintlify and isn’t on the list above, open an issue with:

• A minimal reproduction.
• Mintlify’s render (screenshot).
• Tangly’s render (screenshot).

Compatibility regressions are a P1; we run a parity test against the Open Electricity docs corpus on every commit.