Installation

Requirements

• Node 20+ (or Bun 1.2+).
• A package manager — bun (recommended), pnpm, npm, or yarn all work.
• A directory you want to render. Tangly does not impose a folder structure beyond docs.json at the root.

Install

bun add -D tangly

pnpm add -D tangly

npm install --save-dev tangly

yarn add -D tangly

The tangly binary becomes available via bun x tangly, pnpm exec tangly, npx tangly, etc.

Project layout

A minimal Tangly project is two files:

A typical project grows like this:

Tangly does not require src/, pages/, or any framework files. The MDX files at any depth are the source of truth; docs.json decides which ones appear in navigation. Files prefixed with _ (e.g. _section.mdx) and the snippets/ folder are skipped.

Editor support

Add this to the top of docs.json for autocomplete + inline validation:

{
  "$schema": "./node_modules/tangly/schema/docs.json",
  "name": "My docs"
}

VS Code, Cursor, JetBrains, and any editor with a JSON-Schema language server pick this up automatically. You’ll get IntelliSense for every nav field, color token, and analytics provider.

Optional: scripts

Wire dev/build into your package.json:

{
  "scripts": {
    "dev": "tangly dev",
    "build": "tangly build",
    "preview": "tangly preview",
    "check": "tangly check --strict"
  }
}

Agent skills

Tangly ships two Claude Code skills you can install into any project that uses Claude Code:

• tanglify — drives the Tangly CLI, scaffolds docs.json, ports from Mintlify, picks deploy adapters.
• tech-documentation — Diátaxis-grounded principles for writing the actual content.

Install via the npm skills convention:

npx skills add tanglify
npx skills add tech-documentation

Or point at the repo directly:

npx skills add github:tanglydocs/tangly/skills/tanglify
npx skills add github:tanglydocs/tangly/skills/tech-documentation

The skills live under skills/ and are versioned alongside the framework — when CLI flags or schema fields change, the skill content moves with them.

What’s next