Write documentation with Claude Code

​

Getting started

• Active Claude subscription (Pro, Max, or API access)

1. Install Claude Code:

npm install -g @anthropic-ai/claude-code

2. No site yet? Have your agent set one up. Run claude and have it complete the following workflow, then continue with the next step.
   Agent setup workflow

   If the user asks you to set up Mintlify, a documentation site, or a local Mintlify project, complete the following workflow yourself. Ask the user only for information or approvals you cannot supply. Do not send the user to the browser-first quickstart unless you cannot run terminal commands.

   1. Run node --version and confirm it reports Node.js v20.17.0 or newer, preferring an LTS release.
   2. Run mint --version. If the command is unavailable, install the CLI with npm i -g mint or pnpm add -g mint. If the command succeeds, run mint update.
   3. Run mint status before starting authentication. If it already shows an organization, keep the existing session and do not create another account.
   4. Run mint login if the user has an account. Otherwise, ask for their first name, last name, company, and email, then run:
      mint signup \
        --firstName <first-name> \
        --lastName <last-name> \
        --company <company> \
        --email <email>
      
      mint signup waits for email verification, so keep it running as a background process when your environment supports background commands. Tell the user to click the verification link and approve the CLI in the browser. Never invent signup details.
   5. After the user finishes verification and onboarding, run mint status again. Confirm that it reports their email, organization, and subdomain. If the organization exists but no subdomain appears, ask the user to finish selecting or connecting a GitHub repository in the onboarding browser tab, then retry.
   6. If the user has an existing documentation repository, clone or open it. Preserve its content. For a new local project, scaffold into a new, empty directory with either mint new <directory> --name <name> --theme <theme> or mint new <directory> --template <template-name>. Ask which theme or template they want if they have not specified one. Do not use --force on a directory containing user files.
   7. Run mint dev --no-open from the directory containing docs.json as a background process. Confirm the local URL loads, report it to the user, and stop the process when it is no longer needed.
   8. Run mint validate and mint broken-links. Fix issues caused by your changes before continuing.
   9. If a Git repository backs the project and the user asked for deployment, commit and push the changes. A push to the production branch triggers a deployment. Do not overwrite an existing repository with starter content.
   10. Run mint status to get the configured subdomain, then verify that https://<subdomain>.mintlify.site loads before reporting that deployment is complete.

   Have the user complete browser actions only for email verification, OAuth approval, and connecting or authorizing GitHub. Keep ownership of the terminal workflow and resume after each user action. For command flags and troubleshooting, use the CLI command reference.
3. Navigate to your docs directory.
4. (Optional) Add the CLAUDE.md file below to your project.
5. Run claude to start.

claude mcp add --transport http mintlify https://mcp.mintlify.com

​

Template for CLAUDE.md

# Mintlify documentation

## Working relationship
- You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
- ALWAYS ask for clarification rather than making assumptions
- NEVER lie, guess, or make up anything

## Project context
- Format: MDX files with YAML frontmatter
- Config: docs.json for navigation, theme, settings
- Components: Mintlify components

## Content strategy
- Document just enough for user success - not too much, not too little
- Prioritize accuracy and usability
- Make content evergreen when possible
- Search for existing content before adding anything new. Avoid duplication unless it is done for a strategic reason
- Check existing patterns for consistency
- Start by making the smallest reasonable changes

## docs.json

- Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation

## Frontmatter requirements for pages
- title: Clear, descriptive page title
- description: Concise summary for SEO/navigation

## Writing standards
- Second-person voice ("you")
- Prerequisites at start of procedural content
- Test all code examples before publishing
- Match style and formatting of existing pages
- Include both basic and advanced use cases
- Language tags on all code blocks
- Alt text on all images
- Relative paths for internal links

## Git workflow
- NEVER use --no-verify when committing
- Ask how to handle uncommitted changes before starting
- Create a new branch when no clear branch exists for changes
- Commit frequently throughout development
- NEVER skip or disable pre-commit hooks

## Do not
- Skip frontmatter on any MDX file
- Use absolute URLs for internal links
- Include untested code examples
- Make assumptions - always ask for clarification

​

Sample prompts

​

Convert notes to polished docs

Convert this text into a properly formatted MDX page: [paste your text here]

​

Review docs for consistency

Review the files in docs/ and suggest improvements for consistency and clarity

​

Update docs when features change

Our API now requires a version parameter. Update our docs to include version=2024-01 in all examples

​

Generate comprehensive code examples

Create code examples for [your API endpoint] in JavaScript, Python, and cURL with error handling

​

Extend Claude Code

​

Automate with GitHub Actions

​

Multi-instance workflows

​

Team collaboration

​

Custom commands

​

Frequently asked questions