Tangly — open-source documentation, self-hosted

introduction.mdx

docs.json

localhost:4322/introduction

---

title: "Introduction"

description: "What Tangly is"

---

# Self-host your docs.

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>

Get started

Self-host your docs.

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

curl tangly.dev/install.sh | sh

Init

tangly init

Build

tangly build

Status: stable

Components

34 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>

brew install tangly

curl tangly.dev/install.sh | sh

bunx tangly

<Tab>

Child of <Tabs>. One panel.

<Steps>

Install

curl tangly.dev/install.sh | sh
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>

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" }

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

Features

The rest is here.

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

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

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

---

Custom components

Drop a .tsx, use it.

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

// components/PriceTable.tsx

export default function PriceTable({ tiers }) {

return <table> ... </table>

}

// pricing.mdx

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/

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.

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

Themes

Six 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.

tangly init --theme tang

Pith

editorial

Open

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

tangly init --theme pith

Pip

minimal

Open

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

tangly init --theme pip

Readable

book-like

Open

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

tangly init --theme readable

Geist

developer

Open

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

tangly init --theme geist

Starter

scaffold

Open

Three sections, three pages, no opinions. The fastest way to start typing.

tangly init --theme starter

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: ...

GET

/v1/search-stream

Stream search results

Returns a server-sent event stream of search results as they're resolved.

Query parameters

q string required

Search query. May include wildcards.

limit integer default 50

Maximum results. Capped at 250.

Try it · 200 OK · 412 ms

data: {"id":"d_47","title":"Stream basics","score":0.92}

data: {"id":"d_91","title":"Try-it panels","score":0.81}

data: [stream] 47 results · complete

Open-source
documentation, self-hosted.

Self-host your docs.

Components

34 components, no imports.

v0.1.0

The rest is here.

Six themes. Same Markdown.

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

Stream search results

Static output. Ship anywhere.

Open-sourcedocumentation, self-hosted.

Self-host your docs.

Components

34 components, no imports.

The rest is here.

Six themes. Same Markdown.

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

Stream search results

Static output. Ship anywhere.

Open-source
documentation, self-hosted.