CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This is the Kit Developer Documentation site at https://developers.kit.com/, built with Mintlify. Content is written in MDX (Markdown + JSX). Changes merged to main are automatically deployed by Mintlify.

Git Workflow

Always create a new branch for changes — never commit directly to main. Merging to main triggers an automatic deployment to https://developers.kit.com/.

Mintlify Reference

Mintlify provides LLM-friendly documentation:

Summary: https://www.mintlify.com/docs/llms.txt
Full: https://www.mintlify.com/docs/llms-full.txt

Local Development

The CLI package is mint. The older mintlify package name is deprecated. The CLI requires an LTS version of Node and refuses to run on Node 25.

# Install the CLI
npm i -g mint

# Run the local dev server
mint dev

# Check for broken links
mint broken-links

# Validate the build in strict mode (fails on warnings)
mint validate

# Check for accessibility issues
mint a11y

# Rewrite MDX files to Mintlify's canonical style
mint format

mint score runs Mintlify’s agent-readiness checks against the deployed site. It needs an authenticated session, so run mint login first.

mint login
mint score

Architecture

docs.json — The central config file controlling all navigation, theming, fonts, API settings, and metadata. All new pages must be registered here under navigation.tabs to appear in the sidebar. Content areas:

welcome.mdx — Landing page
kit-app-store/ — Kit App Store integration docs (OAuth, app config, versioning, best practices)
plugins/ — Plugin development docs including component library, content blocks, media sources, automation nodes
api-reference/ — API v4 (current, powered by api-reference/v4.json OpenAPI spec) and v3 (legacy, individual MDX files)
changelog.mdx — Public developer changelog using Mintlify <Update> components

api-reference/v4.json — OpenAPI 3.0 spec for current API. API reference pages are auto-generated from this file; endpoint pages don’t need hand-authored MDX.

Changelog Entries

The changelog uses Mintlify’s <Update> component format. Follow this structure:

<Update label="February 2026" tags={["API"]}>
## 🚀 Feature title
One or two sentences describing what developers can now do.
</Update>

Emoji conventions: 🚀 Added, 🔧 Changed, 🐛 Fixed, ⚠️ Breaking Changes Valid tags: "API", "Kit App Store", "Plugins", "Webhooks", "SDK", "Authentication", "Documentation", "Forms", "Automation", "Commerce", "Analytics" Changelog entries are written by hand. An earlier Slack-to-changelog pipeline (.github/workflows/process-shipped-message.yml) no longer exists.

Adding New Pages

Create the .mdx file in the appropriate directory.
Register the page path in docs.json under the correct tab/group in navigation.tabs.

API Documentation

API v4 is spec-driven — update api-reference/v4.json to add/modify endpoints. API v3 pages are hand-authored MDX in api-reference/v3/.

Per-operation prose in v4.json

Add per-endpoint prose via the description field on each operation (sibling of summary). Reference example: paths./v4/broadcasts.post.description. Mintlify’s OpenAPI description renderer is markdown-flavoured but stripped down — only inline elements survive:

Works: paragraphs (\n\n or <br/><br/>), backticked code, **bold**, [links](/path)
Stripped silently: markdown bullet lists (\n- item), blockquotes (> ...), headings, <ul> / <li>, Mintlify components (<Note>, <Tip>, <Warning>)
Renders but unstyled: <aside class='notice'> — passes through as a bare <aside> element with no callout CSS

Reshape lists into prose; for callouts use a bold lead-in (**Note:** …) rather than a component. npx mint dev does not hot-reload v4.json — restart the dev server after spec edits.

​CLAUDE.md

​Overview

​Git Workflow

​Mintlify Reference

​Local Development

​Architecture

​Changelog Entries

​Adding New Pages

​API Documentation

​Per-operation prose in v4.json