Thally

Build and publish Git-owned docs for people and AI tools with Thally's MIT-licensed documentation engine and public toolchain. One MDX source can serve HTML, Markdown, structured JSON, JSON-LD, llms.txt, RSS, and a live MCP endpoint. Self-host it or connect the site to Thally Cloud.

Start a docs site

npx create-thally-docs my-docs
cd my-docs
npm run dev

create-thally-docs installs dependencies by default (pass --no-install to skip) and prints the exact preview command. The default site runs Next.js directly; npm run check and npm run starter:update explicitly invoke the current official CLI without freezing it into your site's dependency graph.

Or clone the dedicated starter directly:

npx degit thallylabs/starter my-docs
cd my-docs
npm install
npm run dev

The server starts at http://localhost:3040. If that port is occupied, run npm run dev -- --port 3041.

Keep product knowledge aligned

The product knowledge layer for software teams.

Your product changed. Did your docs, website, and help center? Connect the repositories that define your product and the places customers learn about it. When a pull request merges, Thally Track gathers the evidence, traces the impact, and opens evidence-backed pull requests for your team to review. A no-change result is valid. Nothing publishes without human approval.

Features

• MDX content — write docs in Markdown with React components
• Unified content engine — each page is parsed once into a typed content graph; HTML, JSON, JSON-LD, Markdown, search, and embeddings are all projections of that one model
• Auto-generated API reference — drop in an OpenAPI spec and get interactive docs with a "Try It" console
• Sidebar & tabs — configured from a single docs.json file
• Hybrid search — instant client-side command palette plus a server-side full-text + vector /api/search
• Retrieval-grounded AI chat — Q&A with retrieval over your docs and inline citations, available when the site is linked to Thally Cloud; the widget stays hidden otherwise
• Agent endpoints — /llms.txt, /ai.txt, /api/docs-index, /api/docs/{slug}, and an Agent Readiness Score at /api/agent-readiness
• Native WebMCP — supported browsers expose all eight deployed-site tools plus get_current_page and navigate_to_page through document.modelContext; reader sessions and MCP rate limits apply automatically
• HTML tool discovery: the server-rendered <head> includes an inert <script type="application/webmcp+json"> with all ten tools' names, descriptions, and input schemas from the same registry. This versioned Thally discovery extension is not a standardized WebMCP registration mechanism. Native execution still requires JavaScript and a compatible browser. The metadata identifies the eight HTTP-callable tools at /api/mcp and links to /.well-known/mcp.json; the two browser-session tools cannot be called over HTTP.
• Remote MCP server — every deployed site is an MCP endpoint at /api/mcp with read-only tools (search_docs, search_sections, read_page, list_pages, list_api_operations, get_api_operation, list_changes, agent_readiness) and pages as resources; attach with claude mcp add --transport http <site>/api/mcp
• Docs agent — thally agent "…" (or @thally on a product PR) drafts docs as a reviewed pull request, self-checked with thally check; it never merges
• Provenance & drift — machine-legible lastVerified dates + thally check --drift to catch pages stale against the code they document
• Team accounts & roles — Google/Microsoft OIDC sign-in + Owner/Editor/Viewer from a git-committed roster in docs.json (no database, no per-seat)
• Unified thally CLI + @thallylabs/mcp — one toolchain to scaffold, develop, deploy, check, and drive your docs from any MCP client
• TOC, dark mode, responsive — built-in with zero config; persistent sidebar, mobile drawer, command palette
• Syntax highlighting — Shiki with CSS variables for theme-aware code blocks

Project Structure

docs.json              # Navigation config — tabs, groups, page order, API reference
openapi.yaml           # Your OpenAPI spec (auto-generates the API Reference tab)
src/
  content/             # MDX documentation pages (flat folder)
    introduction.mdx
    quickstart.mdx
    ...
  app/                 # Next.js App Router
  components/          # Layout, navigation, MDX, and UI primitives
  data/
    docs.ts            # Reads docs.json + frontmatter to build navigation
    site.ts            # Site name, description, links, brand colors
  config/
    api-reference.ts   # Reads API config from docs.json

Adding a Page

1. Create src/content/my-page.mdx:

   ---
   title: My Page
   description: A short description for search and meta tags.
   ---
   
   Your content here. Use any MDX — headings, code blocks, callouts, etc.
   

2. Add "my-page" to a group in docs.json:

   {
     "group": "Getting Started",
     "pages": ["introduction", "quickstart", "my-page"]
   }
   

3. Done. Sidebar, search, and navigation update automatically.

Configuring Navigation (docs.json)

{
  "tabs": [
    {
      "tab": "Overview",
      "groups": [
        { "group": "Getting Started", "pages": ["introduction", "quickstart"] },
        { "group": "Core Concepts", "pages": ["authentication", "pagination"] }
      ]
    },
    {
      "tab": "API Reference",
      "api": {
        "source": "openapi.yaml",
        "tagsOrder": ["Pets", "Store"],
        "defaultGroup": "General"
      }
    },
    {
      "tab": "Changelog",
      "href": "/changelog"
    }
  ]
}

• tab — label shown in the top navigation bar
• groups — sidebar sections, each with a title and ordered page list
• api — auto-generates API reference from an OpenAPI spec
• href — links to an internal route or external URL

Large navigation trees load separately after the article appears, while small sidebars remain inline. Sidebars with up to 1,000 visible entries render in full; larger ones get earlier/later controls that replace windows of 1,000 visible entries across the collection, retaining authored groups and active-page context. Loading failures leave the article available and offer a navigation retry. Reader-restricted navigation remains private and is never publicly cached. If no introduction page exists, the homepage redirects to the first available internal document in navigation order, respecting the reader and current locale.

Markdown page URLs

Public .md versions of documentation pages are available as an opt-in delivery surface for readers and AI tools. Enable them in docs.json:

{
  "markdown": { "enabled": true },
  "tabs": []
}

After enabling the setting, append .md to a page path: /quickstart.md. For the homepage, use /.md. Thally Cloud sites can manage the same setting from Site settings without editing the repository. The feature is disabled by default, and access protection still applies to Markdown page URLs.

API Reference

Drop your OpenAPI 3.x spec as openapi.yaml in the project root and configure it in docs.json:

{
  "tab": "API Reference",
  "api": {
    "source": "openapi.yaml",
    "tagsOrder": ["Pets", "Store"],
    "defaultGroup": "General",
    "overrides": {
      "GET /pets": { "title": "List pets", "badge": "Stable" }
    }
  }
}

The template includes an example Pet Store spec. Replace it with your own.

Customization

Brand Colors

Edit src/data/site.ts to change the site name, description, links, and brand palette. Two presets are included (primary green, secondary purple) — switch between them or define your own.

Layout

Edit src/config/layout.ts for padding, column widths, and panel styles.

Environment Variables

Copy .env.example to .env.local:

cp .env.example .env.local

Legacy DOX_* names are still read as a fallback for every THALLY_* variable, so existing deployments keep working without renaming anything.

Managed builds prepare canonical search text in protected content assets. Search still applies current reader access, locale, version, and listing metadata; each prepared record must match its current source SHA. Changed or legacy pages use the ordinary canonical parser until the next full build. Transfers and decoded shard caches are bounded; this does not change the Worker's CPU or memory limits.

Production

npm run build
npm start

Deploy anywhere that supports Next.js — Vercel, Netlify, Cloudflare, Docker, etc.

Stack

• Next.js 16 / TypeScript / App Router
• Tailwind CSS 3.4 + @tailwindcss/typography
• Radix UI (dialog, scroll-area, accordion, slot)
• MDX via next-mdx-remote + Shiki syntax highlighting
• next-themes for dark mode, nuqs for URL state, zustand for sidebar state
• yaml for inert frontmatter and OpenAPI parsing

Contributing

Pull requests target main. Before opening one, run:

npm test
npm run lint
npm run build

Runtime, rendering, search, and package changes belong in this repository. thallylabs/starter is the standalone site template that create-thally-docs, thally init, and MCP project creation scaffold from; its runtime files are generated from here, so please do not patch them in the starter repository. Known warnings that are pinned to upstream toolchains are tracked in BUILD-WARNINGS.md.

License

MIT