URL: /introduction

---
title: Introduction
description: Tangly is an open-source documentation framework that turns a folder of markdown into a fast, themed site you self-host.
icon: "sparkles"
---

# Tangly

Tangly is an open-source documentation framework that turns a folder of markdown into a fast, themed site you self-host. Built on Astro, MDX, and Tailwind v4 — no proprietary runtime, no vendor lock-in, no monthly bill.

It's small. It's fast. It works the way coding agents already want to work.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="zap" href="/quickstart">
    Scaffold a project and see it render in under a minute.
  </Card>
  <Card title="Tutorial" icon="rocket" href="/tutorials/first-docs-site">
    Empty directory to deployed site in ten minutes.
  </Card>
  <Card title="Components" icon="puzzle" href="/reference/components">
    35+ MDX components — Card, Tabs, Steps, OpenAPI, callouts, and more.
  </Card>
  <Card title="docs.json schema" icon="file-json" href="/reference/schema/docs-json">
    Every configuration field, with editor-driven validation.
  </Card>
</CardGroup>

## What you get

- **A typed schema** for `docs.json` with JSON Schema autocomplete in any LSP-aware editor.
- **Five themes** out of the box — tang, pith, pip, readable, geist. Switch with one config field.
- **35+ MDX components** auto-injected. No imports, no setup.
- **OpenAPI auto-routing** — drop a spec, get pages with try-it-out.
- **Pagefind search** indexed at build time. Cmd-K modal included.
- **Static-site fast** — cold dev under 2s, builds under 30s for a hundred pages.
- **Adapters** for Vercel, Cloudflare Pages, Node, or plain static hosts.
- **Skills for Claude Code** + JSON Schema for Cursor — the agent integrations you'd build yourself, already done.

## What you write

Two things — a config file and pages:

<FileTree>
- my-docs/
  - docs.json
  - introduction.mdx
  - guides/
    - getting-started.mdx
  - images/
    - hero.png
</FileTree>

`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](/guides/authoring/embedded-blocks) let you reuse content across pages without copy-paste drift.

## Built for agents

Coding agents — Claude Code, Cursor, Copilot, Aider — work better when the surface they're acting on is predictable. 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 — ~10× token reduction vs. HTML.
- **A bundled Claude Code skill (`tanglify`)** version-locked to the CLI. Knows every flag, every config field, every migration path.

See [AI agents](/guides/ai-agents) for the full picture.

## Mintlify-compatible

Existing Mintlify projects render unmodified. 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](/guides/migration/compatibility).

## What's next

Two paths forward:

- **First time?** [Quickstart](/quickstart) gets you to a running dev server in 60 seconds. [Tutorial](/tutorials/first-docs-site) takes you from empty directory to deployed site in ten minutes.
- **Migrating from Mintlify?** [Migration guide](/guides/migration/from-mintlify) handles the swap.

For everything else, the [Components](/reference/components) and [Schema](/reference/schema/docs-json) references cover what you'd want to look up.