Create Mintlify documentation

How to use the create-docs command in Cursor, what to tell the agent, local Mint CLI preview, and how to publish via git and the Mintlify dashboard.

Run the docs locally

To use the Mintlify CLI (mint dev, mint validate, mint broken-links, and so on), install the mint package globally once on your machine. As in the documentation repository README, use either:

npm i -g mint

or

pnpm add -g mint

The README also lists Node.js requirements (v20.17.0 or higher).

From the documentation project root (the folder that contains docs.json), start the local preview:

mint dev

The site is served at http://localhost:3000 (see the README for details).

Overview

This guide explains how to generate MDX pages for the documentation site (Mintlify) using the Cursor agent. The agent follows the workflow in .cursor/commands/create-docs.md and applies patterns from the .cursor/skills/mintlify.md skill.

In a local clone, paths are docs/.cursor/commands/create-docs.md and docs/.cursor/skills/mintlify.md (the .cursor folder sits under docs/).

When to use

Use this flow when you need to document a feature (API, worker, activity, internal flow) and want the agent to create or update .mdx files with Mintlify structure and components that match the project.

How to run in Cursor

1. Open Cursor chat

   Open the chat panel (Composer or Chat) in the workspace that contains the docs/ folder of the documentation repository.

2. Invoke the command

   In the message field, reference the agent file with @ and choose create-docs.md (full path: docs/.cursor/commands/create-docs.md). That loads the agent instructions into the conversation context.

3. Send your request

   Describe what you want documented. The agent will ask for required information before writing files; answer with as much detail and as many references as you can.

You can attach files to the chat with @ (for example source code, TypeScript types, or OpenAPI) so the agent can use them as factual references.

What the agent asks before writing

The official flow requires all of the following. Without them, the agent should collect the details first, then plan and generate the .mdx files.

Information	What to provide
Feature name(s)	What you are documenting (endpoint, activity, module, and so on). You can list more than one.
Description	Behavior, audience, when to use it, and anything another developer must know.
Reference files	Code, types, schemas, specs; paste into chat or use @file.
Where to save	A folder under docs/, for example docs/worker/activities/. If unsure, ask for a suggestion based on navigation in docs.json.

After that, the agent lists the .mdx files it plans to create and should confirm with you before writing everything.

What the agent uses under the hood

• Mintlify skill — Voice, docs.json, components (ParamField, CodeGroup, Steps, and so on), internal links, and frontmatter conventions. Path in the repo: docs/.cursor/skills/mintlify.md.
• create-docs command — Agent steps: read the skill, collect inputs, plan pages, align with existing pages, generate MDX, and remind you about navigation. Path: docs/.cursor/commands/create-docs.md.

After the files are created

1. Add each new page to the navigation section of docs.json (under the correct tab and group). Pages not listed in navigation do not appear in the sidebar.
2. Review titles, frontmatter descriptions, and code examples.
3. Optionally run mint validate and mint broken-links from the docs project folder.
4. Commit and push your changes to the documentation repository so the remote has the updated .mdx files and docs.json.
5. Deploy manually in the Mintlify dashboard. Pushing to the repo does not publish the site by itself; open the dashboard and trigger a deploy after your push.

Always use docs.json for configuration and navigation. The mint.json file is deprecated in current Mintlify.

Where this page lives in the repository

On GitHub: the ai-workflows folder in the enhancedai-com/docs repository — this guide sits alongside other AI-related workflows, per team organization.