FAQ
Questions that come up often enough to deserve their own answer.
~ 5 min read
FAQ
Is X supported?
”Does Tangly render every Mintlify component?”
The 14 most common ones, yes — <Card>, <CardGroup>, <Note>, <Tip>, <Warning>, <Info>, <Check>, <Danger>, <Update>, <Tabs>, <Tab>, <Steps>, <Step>, <Accordion>, <AccordionGroup>, <Frame>, <CodeGroup>, <ParamField>, <ResponseField>, <Snippet> placeholder, <OpenApiEndpoint>. Plus extras Mintlify doesn’t have (<Embed>, <Video>, <PackageManager>, <Kbd>, <FileTree>, …).
For the full matrix, see Migration → Compatibility.
”Does Tangly support versions?”
Yes. navigation.versions lets you author multiple parallel doc trees. See Schema → Navigation → Versions.
”Does Tangly support i18n?”
Yes. Same shape as versions but with language instead. See Schema → Navigation → Languages.
”Does Tangly do PDF / EPUB output?”
No. Static HTML only. The output of tangly build is the deployable artifact.
”Does Tangly support search?”
Yes. Pagefind is wired in. Cmd-K modal, indexed at build time. Per-page exclusion via noindex frontmatter.
”Does Tangly support analytics?”
Twelve providers — PostHog, Plausible, Fathom, GA4, GTM, Amplitude, Hotjar, Mixpanel, Segment, Pirsch, LogRocket, Heap. See Schema → Analytics.
”Does Tangly support custom domains / subpath hosting?”
Yes. tangly build --base /docs for subpath. Custom domains are a deployment concern, not a Tangly concern — see your host’s docs.
Workflow
”Why two formats — mint.json and docs.json?”
Backward compatibility. Tangly accepts mint.json so existing Mintlify projects render unmodified. New projects should use docs.json. tangly migrate converts the legacy format. See Migration.
”Should I commit the dist/ directory?”
No. It’s the build output. .gitignore it. Most CI pipelines build fresh on every deploy.
”Should I check node_modules/ into git?”
Same answer — no. .gitignore it. Dependencies install via bun install / npm install.
”What’s the difference between tangly dev and tangly preview?”
tangly dev runs a live-reload server with HMR — used during authoring. tangly preview serves the production dist/ output — used to sanity-check builds before deploy. They look the same to a reader; the difference is dev recompiles on edit, preview doesn’t.
”When should I tangly eject?”
When you’ve outgrown Tangly’s customization layers and need full Astro project control. Most projects never need to. Before running it, work through the five layers in Customizing themes. If layer 4 (component shadowing) doesn’t cut it, eject is the answer. One-way operation. Commit before running.
Performance
”How big should my docs site be before I worry?”
Tangly handles a thousand pages. Builds scale roughly linearly — a hundred pages take ~30s, a thousand take ~5min on a modern Mac. If you’re seeing worse, open an issue.
”Why is the build slow / fast?”
Builds are dominated by:
- MDX compilation (per-page, parallelizable but limited by Node).
- Image processing — disabled by default, so this is usually 0.
- Pagefind indexing — runs at the end, scales with content size.
The biggest variable is your content’s MDX complexity. Pages with lots of components (especially OpenAPI viewers) compile slower than plain Markdown.
”Will Tangly do incremental builds?”
Astro 6 has incremental builds; Tangly inherits them. So yes, between full rebuilds, dev-server edits are sub-second. For CI builds, “incremental” depends on your CI provider’s caching — most pipelines cache node_modules but not .astro/. Caching .astro/ between CI runs gives a 5–10× speedup.
Authoring
”Can I write Markdown without MDX?”
Yes. .md files render through the same pipeline. You lose JSX expressions and components — Markdown only. Most projects mix .md (simple pages) and .mdx (component-heavy pages).
”Where do I put my OpenAPI spec?”
Anywhere reachable. Common: openapi.json at project root. Reference it via api.openapi: "./openapi.json" in docs.json. See tutorial 2.
”Can I write the docs in a separate repo?”
Yes. Tangly is a CLI — point it at the directory containing docs.json. The repo containing docs/ and the repo containing the product are independent.
”How do I share content across pages?”
Three options, increasing in scope:
- Repeated MDX inline — copy-paste. For one-line snippets.
<Embed>— author a labeled block once on one page, reference it from others. See Embed.- Custom component —
theme/Foo.astrofor genuinely structured shared content.
”How do I write a ‘not yet documented’ page?”
Use the draft frontmatter field:
---
title: Foo (coming soon)
draft: true
---Visible in dev with a “Draft” badge. Excluded from production builds and search. Override with --include-drafts (or TANGLY_INCLUDE_DRAFTS=1) for staging deploys.
Theming
”Can I write my own theme?”
Not as a separate npm package — yet. The supported path: pick a built-in theme, override at the project level via theme/styles/theme.css and shadowed components. See Customizing themes.
If your customizations end up looking like a coherent new theme, open a PR — that’s how the current five built-ins came to be.
”Why doesn’t my color override apply?”
Most likely: you set colors.primary but the surface you’re looking at uses colors.light or colors.dark. The three together cover hover/active states. Override all three for clean results.
If you’re targeting a CSS variable directly, make sure the override’s specificity beats the bundled theme. Project-level theme/styles/theme.css is concatenated after the bundled theme, so it wins automatically; if you’ve added an @import chain, order matters.
AI agents
”Does Tangly require an AI agent?”
No. The agent integrations are conveniences. Tangly works as a plain docs framework — no API keys, no LLM calls.
”Where do I get the Tangly skill?”
npx skills add tanglydocs/tangly/skills/tanglifySee AI agents → Skills.
”Will Tangly send my docs to an LLM?”
No. Tangly’s static-only. The contextual buttons (copy, view, chatgpt, claude) are reader-initiated — they only run when the reader clicks. Nothing in the build process talks to an LLM.
Still stuck
- Common errors for specific error messages.
- GitHub Discussions for open questions.
- Issues for bugs.