Installation

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 globally

The fastest path. One command, tangly on your PATH everywhere:

npm i -g tangly

Then tangly init, tangly dev, tangly build work from any directory.

Install per project

If you’d rather pin Tangly to a single project’s package.json:

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.

Curl one-liner (alternative)

A POSIX/PowerShell installer that does the same thing as npm i -g tangly (uses npm under the hood, writes a tangly wrapper to your PATH):

# Linux / macOS
curl -fsSL https://tangly.dev/install.sh | bash

# Windows (PowerShell)
iwr -useb https://tangly.dev/install.ps1 | iex

Useful when you don’t want to add to your global npm scope, or want a version-pinned cache directory.

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 agent skills you can install into any project that uses a skill-aware agent (Claude Code, Codex, …):

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

Install both skills globally with one command:

npx skills add tanglydocs/tangly -g

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