Open-source
documentation, self-hosted.

Tangly turns a folder of Markdown into a fast, themed, deployable docs site. No proprietary backend, no monthly bill — just a static binary and your repo.

$ npm i -g tangly

Read the docs

introduction.mdx

rendered with tangly dev

---

title: "Introduction"

description: "What Tangly is"

---

Tangly turns Markdown into a fast,

themed, deployable docs site.

<Note>

Already have Mintlify? `tangly dev`

renders your project as-is.

</Note>

## Components

<Card title="Install"

icon="terminal">

One-line install via curl.

</Card>

<Steps>

</Steps>

Status: <Badge>stable</Badge>

Documentation › Introduction

Introduction

What Tangly is

Tangly turns Markdown into a fast, themed, deployable docs site.

Already have Mintlify? tangly dev renders your project as-is.

Components

Install

→

One-line install via curl.

Install

npm i -g tangly

Init

tangly init

Build

tangly build

Status: stable

Components

38 components, no imports.

Drop a tag in MDX. Every theme ships every component. Render here uses the real @tanglydocs/theme-ui package, not screenshots.

Callouts

<Note>

<Tip>

<Info>

<Check>

v0.1.0

May 2026

feat

Open-source release.

Layout

<Card>

<Frame>

Hero illustration

Navigation

<Tabs>

npm i -g tangly

bun add -g tangly

curl tangly.dev/install.sh | sh

<Tab>

Child of <Tabs>. One panel.

<Steps>

Install

npm i -g tangly
Init

tangly init
Build

tangly build

<Step>

Child of <Steps>. One step.

Why Tangly?

Self-host. No vendor lock-in.

Free?

Apache-2.0.

Mintlify compat?

Drop-in.

Code & content

bun add tangly

npm i tangly

pnpm add tangly

Directorymy-docs
- docs.json
- intro.mdx
- Directoryapi/
  - openapi.yaml

$ tangly init my-docs

<Embed>

codepen.io / · 240×80

<Video>

demo.mp4

API

q string path required

Search query.

id uuid

Domain ID.

Request example

curl api.tangly.dev/v1
  -H "Auth: $TOKEN"

Response example

{ "id": "d_47" }

OpenAPI

GET /v1/domains

Endpoint page, generated from your spec.

Try it

POST Redoc

/v1/orders

GET Scalar

/v1/usage

DELETE Stoplight

/v1/keys/{id}

Inline & misc

<Badge>

v0.1 new beta

<Icon>

<Kbd>

Press Cmd+K

SSE stream

An MDX file is markdown plus JSX.

advanced opts

Three optional fields.

npm install tangly

yarn add tangly

pnpm add tangly

bun add tangly

Rendering

code · math · diagrams

Not components. Markdown syntax, wired by default. Shiki highlighting with line highlights, diffs, and titles. KaTeX math. Mermaid diagrams. Every page, every theme.

Code · Shiki

search.ts

export async function search(q: string) {
  const index = await load("/pagefind");
  return index.search(q);
}

Diagrams · Mermaid

Math · KaTeX

∑ ∞ n=1

1 n²

π² 6

Features

The rest is here.

Every feature you'd reach for. Each does what it says.

Built for agents

Every page, also raw Markdown.

Append .md to any URL or send Accept: text/markdown. About 10× fewer tokens. /llms.txt and /llms-full.txt ship by default.

$ curl docs.tangly.dev/quickstart.md

↳ # Quickstart

↳ raw markdown · ~10× fewer tokens

↳ /llms.txt · /llms-full.txt by default

Built-in, instant, ⌘K.

Static index built at tangly build. No Algolia key, no third-party request, no per-month cost.

openapi

⌘K

OpenAPI rendered references, schemas, try-it

/api

Migrating from Mintlify · OpenAPI compat notes

/migrate

docs.json reference · openapi field

/reference/docs-json

Social cards

Every page unfurls.

A branded 1200×630 Open Graph image per page, generated from its title, theme, and your colors. Links unfurl in Slack, iMessage, and X instead of rendering blank. Previews self-reference and stay out of search.

Documentation

Streaming responses

docs.tangly.dev

Custom components

Drop an .astro, use it.

Put a component into components/. Use it from MDX. Hot reloads. No registration.

// components/Pricing.astro
---
const { tiers } = Astro.props;
---
<ul>{tiers.map((t) => <li>{t.name}</li>)}</ul>

// pricing.mdx
<Pricing tiers={tiers} />

Drafts

Frontmatter is the CMS.

Mark a page draft: true. Hidden in production, visible in tangly dev. Ship preview builds with --include-drafts.

---

title: "New billing flow"

description: "Stripe + per-seat metering"

draft: true # hidden in prod

---

Readable errors

Config errors you can read.

When docs.json is wrong, tangly check names the key, the line, the reason, and the fix. Did-you-mean for typos, rename hints for Mintlify fields.

$ tangly check

✗ docs.json: 2 problems

theme · line 3

"mintlify" is not a known theme

→ did you mean "mint"?

navigation.tabs[1].pages · line 24

expected array, got string

Migrate

From Mintlify, in a minute.

tangly migrate reads mint.json and emits a Tangly-shaped docs.json. MDX stays untouched.

$ tangly migrate

↳ found mint.json (v2.4)

↳ mapped 14 fields → docs.json

↳ done. 0 MDX files modified.

Subpath hosting

Mount under any path.

Build with --base /docs/. All asset paths rewrite. Works behind Caddy, nginx, or a Cloudflare Worker.

$ tangly build --out ./dist --base /docs/

↳ rewrote 247 asset paths

↳ ./dist/index.html → /docs/

↳ ./dist/api/ → /docs/api/

Eject

Ejects to a raw Astro project.

Outgrown the magic? tangly eject materializes the synthesized Astro project into your repo. astro.config.mjs is yours to edit. One-way, no Tangly required after.

$ tangly eject

↳ wrote .tangly/ (47 files)

↳ rewrote package.json scripts → astro

↳ added astro, @astrojs/mdx, tailwindcss

↳ done. astro.config.mjs is yours.

Deploy from CI

Drop a workflow. Done.

A 14-line GitHub Actions workflow ships your docs to GitHub Pages on every push. Bun caches resolve in seconds. The Tangly monorepo deploys itself this way.

# .github/workflows/pages.yml

name: deploy

on: [push]

permissions: { pages: write, id-token: write }

jobs:

build:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v4

- uses: oven-sh/setup-bun@v2

- run: bun install --frozen-lockfile

- run: bunx tangly build --base /$REPO

- uses: actions/upload-pages-artifact@v3

- uses: actions/deploy-pages@v4

Fast dev

Astro 6 + Vite. HMR under 250ms.

Cold start under 2s on a hundred pages. tangly dev boots fast and stays out of the way.

$ tangly dev

↳ Tangly · 58 pages · theme: tang

↳ Local: http://localhost:4321

↳ ready in 1.7s

# edit any .mdx

↳ HMR 187ms

Themes

Five themes. Same Markdown.

Swap a one-line value in docs.json. Same content, new register. Each tile is a real Tangly site. Click through to examples.tangly.dev.

Mintlify-Mint inspired. Sidebar nav, on-page TOC, monospace headings.

Serif headings, cream surface, generous measure. For long-form writing.

No sidebar. Single-column reading mode. Headings as the only navigation.

Narrow column, large body type, drop caps. Reads like a manual.

Vercel/Linear register. Ink ground, thin rules, dense type scale.

The default `tangly init` scaffold. Three sections, three pages, on the tang theme. The fastest way to start typing.

tangly init

OpenAPI

Point at an OpenAPI spec. Get a real API reference.

Drop a 3.0 or 3.1 spec into docs.json. Tangly generates browseable endpoint pages with schemas, examples, and a try-it panel — no third-party explorer required.

openapi.yaml

v3.1 47 endpoints · 28 schemas

openapi: 3.1.0
info:
  title: Search Stream
  version: 2026.05.01
paths:
  /v1/search-stream:
    get:
      summary: Stream search results
      parameters:
        - in: query
          name: q
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            text/event-stream: ...