Introduction

Tangly

Tangly turns a folder of Markdown into a self-hosted docs site. It’s open source, runs on Astro, MDX, and Tailwind v4, and emits a static folder you drop on any host. No proprietary runtime, no monthly bill.

It’s small, it’s fast, and it works the way coding agents already want to work.

What you get

• Self-hosted and open source. A static site you own, hosted anywhere: Vercel, Cloudflare, Netlify, AWS, GitHub Pages, S3, nginx. No proprietary backend, no monthly bill.
• Drop-in Mintlify compat. Point Tangly at an existing docs.json + MDX project and it renders unchanged. tangly migrate converts a mint.json in one command. No source edits.
• Auto-generated API docs. Point at an OpenAPI 3.0 / 3.1 spec and get browseable endpoint pages with an interactive try-it panel. Redoc, Scalar, and Stoplight viewers too.
• 38 MDX components, no imports. Cards, Tabs, Steps, Accordions, callouts, ParamFields, CodeGroups, and more. Every theme ships every one.
• Code, math, and diagrams. Shiki syntax highlighting with line highlights, diffs, focus, and titles. Mermaid diagrams. KaTeX math. Multi-language CodeGroups and package-manager tabs.
• Built for AI agents. Every page is also served as raw Markdown (.md URL or Accept: text/markdown). ~10× token reduction. /llms.txt and /llms-full.txt ship by default.
• Five themes, or your own. tang, pith, pip, readable, geist via one theme field. Build custom themes from @tanglydocs/theme-ui. See live demos.
• Search built in. Pagefind, instant, ⌘K. No Algolia key, no third-party request.
• Social cards, generated. Every page renders a branded 1200×630 Open Graph image at build, so shared links unfurl with the page title and your theme. On by default once siteUrl is set, with per-environment URLs so previews never leak into search.
• Custom components. Drop an .astro component into components/ and use it from MDX. Hot-reloads, no registration.
• Drafts. Mark a page draft: true. Hidden in production, visible in tangly dev, shippable with --include-drafts.
• Readable config errors. tangly check reports problems key-by-key with line numbers, plain-English reasons, and did-you-mean fixes.
• Fast dev, ejectable. Astro 6 + Vite under the hood: HMR under 250ms, cold start under 2s on a hundred pages. tangly eject to a raw Astro project whenever you outgrow the magic.

What you write

Two things: a config file and pages.

docs.json declares navigation and configures everything that isn’t content. Each .mdx file becomes a page. Frontmatter handles per-page metadata (title, description, icon, draft, noindex). Embedded blocks let you reuse content across pages without copy-paste drift.

Built for agents

Coding agents work better when the surface they’re acting on is predictable. Claude Code, Cursor, Copilot, Aider all benefit. Tangly leans into that:

• Strict frontmatter schema. Agents fill it correctly because the rules are unambiguous.
• JSON Schema for docs.json. Editor autocomplete in Cursor, VS Code, Zed, JetBrains.
• Auto-generated llms.txt and llms-full.txt. The standard way to expose docs to LLMs.
• Per-page Markdown for agents. Append .md to any URL, or send Accept: text/markdown, and you get the raw source. About 10× token reduction vs. HTML.
• A bundled agent skill (tanglify) version-locked to the CLI. Works with Claude Code, Codex, and other skill-aware agents. Knows every flag, every config field, every migration path.

See AI agents for the full picture.

Mintlify-compatible

Existing Mintlify projects render unchanged. Same components, same docs.json schema, same frontmatter. Run tangly migrate to clean up, then tangly dev. No source edits.

For the full compatibility matrix, see Migration → Compatibility.

What’s next

Two paths forward:

• First time? Quickstart gets you to a running dev server in 60 seconds. Tutorial takes you from empty directory to deployed site in ten minutes.
• Migrating from Mintlify? Migration guide handles the swap.

For everything else, the Components and Schema references cover what you’d want to look up.