Configuration

Tangly reads a single docs.json at your project root. The full reference is at docs.json — this guide covers the shape and the fields you’ll touch most.

Minimal example

{
  "$schema": "./node_modules/tangly/schema/docs.json",
  "name": "My Docs",
  "theme": "tang",
  "colors": { "primary": "#0ea5e9" },
  "navigation": {
    "groups": [{ "group": "Get Started", "pages": ["introduction"] }]
  }
}

That’s enough to render. Add fields as you need them.

Common fields

For the complete field-by-field reference (every nested object, every enum value), see docs.json reference.

Code blocks

code controls Shiki theming and the per-block copy button. See Code for the rendering surface.

{
  "code": {
    "copyButton": true,
    "theme": { "light": "github-light", "dark": "github-dark" }
  }
}

copyButton: false hides the button globally (per-block opt-out: add noCopy to the fence meta). theme accepts a string (same theme for both modes) or an object split.

Appearance

appearance toggles page chrome — color-scheme default plus the new reading-time stamp and reading-progress bar.

{
  "appearance": {
    "default": "system",
    "readingTime": true,
    "readingProgress": true
  }
}

readingTime: true shows estimated minutes in the page header (computed from word count). readingProgress: true paints a 2px progress bar across the top of every page as the reader scrolls.

Footer

Beyond the existing socials and links, the footer now drives last-updated stamps and edit-on-source links.

{
  "footer": {
    "lastUpdated": true,
    "repo": "https://github.com/owner/repo",
    "editUrl": "https://github.com/owner/repo/edit/main/{path}"
  }
}

lastUpdated: true reads each page’s last commit date from git and shows it in the footer. editUrl is a template — {path} is replaced with the page’s path relative to the project root. If editUrl is omitted but repo is set, Tangly derives editUrl from the repo URL. If neither is set, the link is hidden.

Banner

Top-of-page announcement strip. Add id to make dismissals stick across reloads (the id is the localStorage key — change it to re-show the banner). type controls tone.

{
  "banner": {
    "id": "v02-launch",
    "type": "info",
    "dismissible": true,
    "content": "Tangly v0.2 ships richer code blocks — <a href=\"/changelog\">see what's new</a>"
  }
}

type is one of info, warning, success. See Announcement banner for the full guide.

Section defaults

Cascade frontmatter through a directory subtree by dropping _section.mdx (or _meta.json) at the directory root:

---
# guides/wip/_section.mdx
draft: true
mode: wide
icon: pencil-line
---

Every page under guides/wip/ inherits these fields unless it overrides them in its own frontmatter. Section defaults bubble outward — closer overrides further.

Validation

Run tangly check to validate docs.json against the schema and resolve every page reference:

bun x tangly check --strict

--strict exits non-zero on any warning (use this in CI). See tangly check for the full surface.

Editor support

Add $schema for autocomplete + inline validation in VS Code, Cursor, JetBrains:

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

tangly migrate rewrites this for you when migrating from Mintlify.