# Give agents your team's conventions Source: https://learn.mintlify.com/courses/agent-friendly-content/agent-instructions Write instruction files that tell AI writing tools who your readers are, which terms to use, and how your pages are structured, and put them where each tool looks. The previous lesson covered agents that read your published docs on a user's behalf. This lesson covers agents that help your team write them. Mintlify's agent, the editor's agent, and coding tools like Claude Code and Cursor can all draft and edit pages. Without guidance, they write for a generic reader, pick whichever term they saw last, and mix content types. An instruction file gives them the context your pages don't contain: who you write for and how your team works. ## What to include A useful instruction file for a documentation project covers four things. **Audience.** Who your readers are and what they already know, so the tool pitches content at the right level. The [Understand your readers first](/courses/structure-docs/understand-your-readers) lesson covers how to write a reader definition. **Terminology.** The canonical name for each concept, and the variants to avoid. This is the most effective way to stop terminology drift. **Content types.** What each kind of page should and shouldn't do, so a how-to guide doesn't turn into an essay. **What not to do.** The mistakes your team keeps correcting, like "don't add introductory paragraphs that restate the title." ```markdown .mintlify/AGENTS.md theme={null} ## Audience Our primary readers are backend developers integrating our API for the first time. They understand REST and JSON. They do not need explanations of basic concepts. Write at this level unless a page explicitly specifies otherwise. ## Terminology - "workspace," not "organization" or "team" - "publish," not "deploy" or "push" - "API key," not "token" or "secret" ## Content types Each page is one of: tutorial, how-to, reference, or explanation. Do not mix types. Identify the type before writing or editing. If a how-to needs to explain a concept, link to an explanation page instead of explaining inline. ## Style - Don't restate the title in the first sentence - Lead with what the reader needs, not background - Use active voice ``` Keep instructions short and specific. Tools follow them on every request, so vague or contradictory rules make results worse, not better. ## Put instructions where each tool looks Each tool reads its own file, and none of them read each other's. Write the instructions once, then copy them to each place your team needs. | Tool | Where it reads instructions | | - | - | | Mintlify's agent, in Slack, automations, and the API | `.mintlify/AGENTS.md` in your docs repository | | The editor's agent | **AI instructions** in your [editor settings](https://mintlify.com/docs/editor/settings#ai-instructions), set by each teammate | | Claude Code | `CLAUDE.md`, such as `.claude/CLAUDE.md` in your repository | | Other coding agents, such as Codex and Cursor | `AGENTS.md` at the root of your repository | > [!WARNING] > > Mintlify publishes Markdown files in your project, so a root `AGENTS.md` is readable by anyone at `/agents.md`. Keep Mintlify's copy in `.mintlify/AGENTS.md`, which is never published. If your coding tools need a root `AGENTS.md`, add it to your [`.mintignore`](https://mintlify.com/docs/organize/mintignore) file so it stays private. ## Keep instructions current Instruction files go stale like any other content. When your team renames a feature, add the new term and the old one to avoid. When you notice yourself correcting the same mistake in several drafts, add a rule for it. Review the files when you review your style guide, and remove rules that no longer apply. Quiz Your team uses Mintlify's agent through automations. You added terminology rules to CLAUDE.md, but the agent's pull requests keep using the old terms. Why? Next up: [Test whether agents can use your content](/courses/agent-friendly-content/test-agent-readiness)—build a repeatable question set and catch regressions. # Help agents find and read your content Source: https://learn.mintlify.com/courses/agent-friendly-content/help-agents-find-your-content Configure llms.txt, Markdown output, your MCP server, skill.md, and agent-only content so AI tools can discover and use your documentation. [Control what agents see](https://www.youtube.com/embed/mZ24DBYI9xI) Good pages are only part of the job. Agents also need a way to find the right pages, read them efficiently, and understand what your product does before they start. Mintlify generates most of this for you. This lesson covers what each piece does, what you can tune, and when it's worth overriding the defaults. ## `llms.txt`: a map of your site `llms.txt` is a Markdown file at the root of your site that lists your pages with a short description of each. It works like a sitemap for AI tools: an agent can read it to see what your site covers and pick which pages to fetch, without crawling your navigation. Mintlify generates `llms.txt` automatically and keeps it up to date as you publish. The generated file includes: * Your site name as a heading * A summary of your site, taken from the `description` field in `docs.json` * Every page in navigation order, with the `description` from its frontmatter * Links to the Markdown version of each page You can see yours by adding `/llms.txt` to your site's URL. ### Improve the generated file Because the file is built from your content, you improve it by improving the sources: * **Write a specific site description in `docs.json`.** This is the first thing an agent reads. "Acme docs" tells it nothing. "Documentation for Acme, a payment processing API that handles charges, refunds, and webhook notifications" tells it whether it's in the right place. * **Give every page a specific description.** Pages without one appear in `llms.txt` with only a title, and the [previous lesson](/courses/agent-friendly-content/write-for-agents#write-specific-titles-and-descriptions) covered why titles alone aren't enough. * **Order your navigation deliberately.** The file follows your navigation, so put your most important content first. * **Leave out pages agents shouldn't use.** Pages marked `hidden: true` or `noindex: true` in their frontmatter are excluded from `llms.txt`, along with search and AI context. Use this for deprecated pages you haven't deleted yet, internal notes, and pre-release content. Here's the difference a site description and page descriptions make: ```markdown Weak llms.txt theme={null} # Acme Docs ## Docs - [Getting Started](https://docs.acme.com/getting-started.md) - [Advanced configuration](https://docs.acme.com/advanced.md) - [Webhooks](https://docs.acme.com/webhooks.md) ``` ```markdown Strong llms.txt theme={null} # Acme > Documentation for Acme, a payment processing API for e-commerce platforms that handles charges, refunds, and webhook notifications. ## Docs - [Quickstart](https://docs.acme.com/quickstart.md): Make your first API call and create a test charge - [Configure rate limits](https://docs.acme.com/rate-limits.md): Set request limits per API key and handle 429 responses - [Receive webhooks](https://docs.acme.com/webhooks.md): Register an endpoint and verify webhook signatures ``` Large sites don't lose pages to size limits. If the file would exceed 100,000 characters, Mintlify splits it into linked index files that agents follow. ### When to write a custom file You can replace the generated file by adding your own `llms.txt` to the root of your project. A custom file gives you full control over grouping and wording, but you take on its maintenance: it won't update when you add, move, or remove pages. Most sites are better served by improving the generated file. If you do write one, it must follow the [llms.txt format](https://llmstxt.org/#format), starting with your site name as a heading. ### `llms-full.txt` Mintlify also generates `llms-full.txt`, which contains the full Markdown content of every page in one file. Agents that want everything at once can read it instead of fetching pages one by one. It follows the same rules for hidden and `noindex` pages. A custom `llms.txt` doesn't change it. ## Markdown pages As the first lesson covered, Mintlify serves a Markdown version of every page to agents automatically. Links in the Markdown point to other Markdown pages, so an agent that follows them keeps getting clean content. Two features let you shape what agents see in that Markdown. **Agent-only and human-only content.** The `Visibility` component shows content to one audience and hides it from the other. Use it when the best instructions differ: a person clicks a button, while an agent calls an API. ```mdx theme={null} Click **Create account** in the top-right corner. To create an account, call `POST /v1/accounts` with a valid email address. ``` **Site-wide agent instructions.** Set `markdown.instructions` in `docs.json` to add a block of guidance to every Markdown page and to `llms.txt`. Use it for rules that apply everywhere, like "Always cite the API version" or "Prefer the TypeScript SDK in examples." ```json docs.json theme={null} "markdown": { "instructions": "Always cite the API version. Prefer the TypeScript SDK in examples." } ``` ## Your MCP server Mintlify generates a search MCP server for your site. When a user connects it to an AI tool like Claude, Cursor, or ChatGPT, the agent can search your content and read full pages directly, instead of relying on web search or what it remembers from training. Your MCP server also gives agents a way to report problems. If an agent finds a page that's wrong or outdated, it can submit feedback, which shows up in your analytics alongside feedback from readers. Make it easy for users to connect. The [contextual menu](https://mintlify.com/docs/ai/contextual-menu) adds options to every page for copying the page as Markdown, opening it in an AI tool, and installing your MCP server in Cursor or VS Code. ## `skill.md`: what agents can do with your product `llms.txt` tells agents where your content is. `skill.md` tells them what they can accomplish with your product: its capabilities, the inputs they need, and the constraints that apply. Mintlify generates a `skill.md` for public sites by analyzing your documentation, and keeps it current as your content changes. Agents connected to your MCP server can use it automatically. Developers can also add it to their own agents with `npx skills add` and your site's URL. Write custom skills when developers commonly ask agents to complete specific workflows with your product, like "create a charge" or "set up webhooks." Put each skill in its own folder under `.mintlify/skills/`, with a `SKILL.md` file that has a `name`, a `description`, and step-by-step instructions: ```markdown .mintlify/skills/create-charge/SKILL.md theme={null} --- name: create-charge description: Create a payment charge using the Acme API. Use when a user needs to process a payment. --- ## Instructions 1. Retrieve the customer's payment method with `GET /customers/{id}`. 2. Create a charge with `POST /charges`, passing the payment method ID and amount. 3. Return the charge ID to the user. ``` Mintlify lists custom skills at a discovery endpoint so agents can find them. If your primary goal is helping agents answer questions, the generated `skill.md` may be all you need. See the [Mintlify skill.md guide](https://mintlify.com/docs/ai/skillmd) before you override it. ## Structured sources If your product has an API, keep its OpenAPI specification accurate. A specification gives agents exact parameter types, required fields, allowed values, and response shapes that prose can leave out. Treat the specification as the source of truth for API structure. Use written pages for concepts, workflows, examples, and decisions the specification can't explain, and avoid defining the same field by hand in several places. ## `robots.txt` and AI crawlers Mintlify's default `robots.txt` allows AI crawlers and includes a Content-Signal line that opts your content in to search indexing, AI answers, and AI model training. If you don't want your docs used for training, add a custom `robots.txt` with `ai-train=no`. Be careful about blocking AI crawlers entirely: if they can't read your docs, AI tools can't cite them in answers. ## Check your setup Run `mint score` from the Mintlify CLI to check how ready your site is for agents. It checks your `llms.txt` and `llms-full.txt`, Markdown responses, `skill.md`, MCP server, `robots.txt`, and more, then reports a score with each check passed or failed. Quiz Your llms.txt lists a deprecated API guide near the top, and agents keep recommending it. What's the best fix? Next up: [Give agents your team's conventions](/courses/agent-friendly-content/agent-instructions)—tell AI writing tools who you write for and which terms to use. # How agents read your content Source: https://learn.mintlify.com/courses/agent-friendly-content/how-agents-read-your-content Learn how AI agents find, fetch, and read your content, and the technical problems that make them fail without anyone noticing. [How agents read your documentation](https://www.youtube.com/embed/PtfE2Nk-9c0) People arrive with context. They have a goal, know what they were doing, and may remember the page they came from. They can skim, follow links, and build a mental model of your product over time. Agents work differently. They start from the user's prompt and pull in whatever content they can find for that one request, often a few chunks at a time, without seeing the rest of your site. > [!NOTE] > > This course focuses on agents that read your content in real time to answer questions or complete tasks. Optimizing content for model training is a related but separate concern. ## How agents find your content Depending on the tool, an agent reaches your content in one or more of these ways: * **Web search.** The agent searches the web, reads the result snippets, and fetches a few of the pages that look relevant. Your page titles and descriptions decide whether yours are among them. * **Direct fetch.** The agent requests a URL it already knows, from training data, a user's message, or a link on another page. * **An index file.** The agent reads `llms.txt`, a Markdown list of your pages with descriptions, to decide which pages to fetch. * **An MCP server.** A user connects your documentation's MCP server to their AI tool. The agent can then search your content and read full pages directly, without going through a web search. Each path ends the same way: the agent has a handful of pages, or parts of pages, and has to answer from those alone. ## What agents receive When a person visits your site, the browser renders HTML with navigation, scripts, and styling. Agents don't need any of that, and it costs them context space they could spend on your content. Mintlify serves agents a Markdown version of each page instead. An agent gets Markdown when it requests a URL ending in `.md`, asks for Markdown in its request headers, or identifies itself as a known AI agent, like the ones ChatGPT and Claude use to fetch pages. You don't need to configure anything for this to work. Components become plain Markdown too. Callouts become labeled blocks, steps become numbered titles, and components without a Markdown equivalent, like tabs, keep their text. That means agents see the content of every tab, not just the first one. ## Agents work from fragments Because an agent may read only one page, or only part of one, it can't rely on context the way a person can. A sentence like "once you've completed the setup above" points to text the agent may never have seen. A page titled "Advanced configuration" gives it little reason to fetch the page in the first place. The next lesson covers how to write pages that hold up under these conditions. The short version: every page should make sense on its own, say clearly what it covers, and use the same terms your users do. ## Technical problems cause silent failures Some agent failures have nothing to do with how well you've written your content. Technical issues can stop agents from getting it at all: * **Very long pages.** Agent tools limit how much of a page they'll read. Some cut off around 50,000 characters, and the limit varies by tool. The agent gets part of the page and doesn't know the rest exists. Focused, single-topic pages are much less likely to hit a limit. * **Lots of tabbed content.** Because agents see every tab, a page with many large tabs can balloon in size. Put content that applies to everyone before the tabs, and keep each tab focused. * **Content rendered in the browser.** Most agent fetch tools don't run JavaScript, so content that only appears after scripts run may be invisible to them. Mintlify renders pages on the server, so this mainly affects custom interactive components. * **Moved content.** Agents often have old URLs from training data or earlier conversations. Add redirects whenever you move a page. Moving to a new domain is riskier, because many agent tools don't follow redirects to a different host, so keep old URLs working on the original domain when you can. For humans, these problems are visible: a page looks broken or a link 404s. For agents, the information is just missing, and the user gets a wrong or incomplete answer with no sign that anything went wrong. Quiz A user asks an AI tool how to configure SSO for your product. The answer is on a 70,000-character page that covers every authentication method, and SSO is near the bottom. What's the most likely outcome? Next up: [Write content agents can use](/courses/agent-friendly-content/write-for-agents)—the writing habits that make each page reliable context for agents. # Keep content agent-friendly over time Source: https://learn.mintlify.com/courses/agent-friendly-content/ongoing-maintenance Agent-friendly content degrades without attention, just like any other content quality. Here's what to watch and when. [Keep content agent-friendly over time](https://www.youtube.com/embed/bShYBXXl36Q) Agent-friendly content needs maintenance. As your product changes and pages accumulate, yesterday's clear context can become today's stale answer. A few checks can fit into the maintenance routine you already have. ## Watch what agents tell you Your [question set](/courses/agent-friendly-content/test-agent-readiness) catches regressions you can predict. Mintlify's analytics show you the ones you can't: * **Assistant analytics** group the questions readers ask your site's assistant into topics, with ratings for each answer. Topics with poor ratings point to missing, unclear, or outdated pages. * **Agent feedback** comes from AI agents connected to your MCP server. When an agent finds a page that's wrong or confusing, it can report the problem, and you'll see it in your feedback analytics next to reader feedback. * **Traffic analytics** show how many page views come from AI agents rather than people, so you can see which pages agents rely on most. When an answer is wrong, trace it to the content. A vague title, a mixed-topic page, inconsistent terms, or a page that wasn't updated after a release are the usual causes. ## When the product changes Documentation stops being agent-friendly the same way it stops being accurate: it was right once and then wasn't updated. Agents don't know when content is stale, so they present it with the same confidence as current information. When a product changes or you release a new feature: * Update the relevant pages before or alongside the release, not after * Check whether terminology has changed. If a feature was renamed, find every page that uses the old name and update it * Update your agent instruction files if a term changed * Mark pages for removed features `hidden: true` or delete them, so they drop out of `llms.txt` and AI context ## Audit for terminology drift Terminology consistency is hard to maintain as a team grows and different people contribute to content. Run a periodic audit: 1. List the canonical terms for your most important concepts in a shared style guide 2. Search your content for synonyms and variants 3. Update any pages using non-canonical terms An agent can help: give it your list of terminology and ask it to scan your content for inconsistencies. Add new terms to your [agent instruction files](/courses/agent-friendly-content/agent-instructions) as your product grows. Define the name before contributors start writing about a new feature. ## Check new pages are self-contained Self-containment is hard to keep up because missing context is hard to spot while you're writing. You know the subject, so you may not notice that a page depends on information found elsewhere. Add these questions to your review checklist for new pages: * Does this page assume the reader has read any other page? * Does it use terms that are only defined elsewhere? * If a reader arrived here from an agent's answer, would they have enough context to act? ## Keep `llms.txt` accurate Mintlify's generated `llms.txt` updates itself whenever you publish, so you don't need to maintain the file. You do need to maintain what it's built from: page descriptions, navigation order, and which pages are hidden. When you review a section, check that its descriptions still match its pages. If you wrote a custom `llms.txt`, it won't update on its own. Review it whenever you add, move, or remove pages, or switch back to the generated file. ## A maintenance rhythm * **With every product release**: Update affected pages, check for terminology changes, and update agent instruction files if a term changed * **Monthly**: Review assistant analytics and agent feedback for unanswered questions, wrong answers, or outdated information * **Quarterly**: Audit for terminology drift, check page descriptions, and check that high-traffic pages are self-contained * **After major content or access changes**: Re-run your evaluation set and verify that each audience can retrieve only the intended sources Quiz An agent starts giving wrong answers about a feature that was recently renamed in your product. What's the most likely cause, and what should you fix? That's the end of the course. You've covered how agents read, which writing and configuration choices give them reliable context, how to evaluate their answers, how to protect sensitive information, and how to keep the whole system accurate as your product evolves. The same discipline makes the content more dependable for people too. ## Go deeper * [Why agent-friendliness matters](https://afdocs.dev/why-agent-friendliness-matters.html)—An overview of how agents access documentation and why the highest-impact fixes are often configuration changes, not rewrites. * [The Agent-Friendly Documentation Spec](https://agentdocsspec.com/)—A spec that defines 28 checks for evaluating the agent-friendliness of your documentation. ## Continue learning * [Structure docs that scale](/courses/structure-docs/overview)—Content types, navigation design, and keeping documentation accurate as your product grows * [Git and GitHub for Mintlify](/courses/git-github/overview)—Version control, branching, and collaboration workflows for documentation * [How to use Mintlify components](/courses/components/overview)—How to use Mintlify's components to structure and format documentation effectively # Create agent-friendly content Source: https://learn.mintlify.com/courses/agent-friendly-content/overview Make your documentation work for AI agents as well as people: what to write, what to configure, and how to test and maintain it. Your content has two audiences: humans and AI. Not long ago, someone who needed help with your product would start with your docs. If they couldn't find an answer, they might open a support ticket or try another product. That pattern has changed. People now ask tools such as ChatGPT, Claude, Perplexity, and your Mintlify assistant for answers grounded in your content. Developers also use coding agents such as Claude Code and Cursor to understand and build with your product. Your content must still work well for humans. But you also need to consider the AI that mediates between your content and your users. The good news is that agent-friendly content is usually better for people too. Clear pages, explicit context, consistent terms, and a tight focus help every reader. This course also covers the few considerations that are specific to agents. ## Who this is for Developers, technical writers, and product teams who maintain content. Some lessons focus on Mintlify, but the principles apply to any platform. You don't need a background in AI or machine learning, just an interest in making your content work well for anyone (or anything) that reads it. ## Lessons in this course 1. [How agents read your content](/courses/agent-friendly-content/how-agents-read-your-content)—How agents find and fetch your pages, and the technical problems that make them fail silently. 2. [Write content agents can use](/courses/agent-friendly-content/write-for-agents)—Writing habits that make each page reliable context for agents. 3. [Help agents find and read your content](/courses/agent-friendly-content/help-agents-find-your-content)—Configure `llms.txt`, Markdown output, your MCP server, and `skill.md`. 4. [Give agents your team's conventions](/courses/agent-friendly-content/agent-instructions)—Write instruction files for the AI tools that help your team write docs. 5. [Test whether agents can use your content](/courses/agent-friendly-content/test-agent-readiness)—Build a repeatable question set and check your technical setup. 6. [Protect private and sensitive information](/courses/agent-friendly-content/security-and-access)—Separate discovery from access control and test what each audience can retrieve. 7. [Keep content agent-friendly over time](/courses/agent-friendly-content/ongoing-maintenance)—Use analytics and agent feedback to keep content accurate as your product changes. ## Agent-friendly content checklist Use this as a quick reference. ### Content * [ ] Every page makes sense without reading adjacent pages * [ ] Page titles are specific enough to match user questions ("Configure rate limits for API requests" instead of "Advanced configuration") * [ ] Every page has a description that names the task and topics it covers * [ ] Headings make sense without surrounding context * [ ] Each page covers one topic or task * [ ] Terminology is consistent, with one name per concept ### Examples and references * [ ] Code examples are complete and runnable * [ ] Placeholder values are clear and explain what to substitute * [ ] Cross-references name what they link to. No "click here," "the above," or similar ### Configuration * [ ] The `description` in `docs.json` explains what your product does * [ ] Deprecated, internal, and pre-release pages are marked `hidden: true` or `noindex: true` * [ ] Your MCP server is easy for users to connect, for example through the contextual menu * [ ] `.mintlify/AGENTS.md` defines audience, terminology, and content type rules for Mintlify's agent * [ ] Private content is protected by authentication, not just hidden * [ ] `mint score` passes the checks that matter for your site ### Evaluation * [ ] A saved set of user questions covers lookup, tasks, troubleshooting, ambiguity, and unsupported requests * [ ] Expected facts and supporting sources are recorded for each question * [ ] Each run records which agent was tested and how it accessed your content * [ ] The question set runs after major content, terminology, configuration, or access changes ### Ongoing maintenance * [ ] Assistant analytics and agent feedback are reviewed regularly * [ ] Content is updated alongside product changes * [ ] Agent instruction files are updated when terminology changes Next up: [How agents read your content](/courses/agent-friendly-content/how-agents-read-your-content)—how agents find and fetch your pages. # Protect private and sensitive information Source: https://learn.mintlify.com/courses/agent-friendly-content/security-and-access Separate content discovery from access control, keep secrets out of examples, and test what each audience can retrieve. Agent-friendly content should be easy for the right agent to find and use. That doesn't mean every agent should receive every page. Discovery and authorization solve different problems. Files such as `llms.txt` help agents find content, but they can't control access to private pages or protect a sensitive value. ## Use access controls If content is private, protect the page or site with authentication and authorization. Test access with the same roles and groups your users have. Removing a link from navigation or `llms.txt` only makes a page less visible. Anyone, or any agent, with the URL can still fetch it. On Mintlify, `hidden: true` removes a page from navigation, `llms.txt`, search, and AI context, but the page is still public at its URL. Before publishing, classify content: * **Public**: Safe for anyone to read and reuse * **User-only**: Available to authenticated users * **Role-restricted**: Available only to specific groups * **Internal**: Not part of the user documentation site * **Secret**: Must not appear in documentation, source control, examples, or agent context For internal files that shouldn't be on your site at all, like drafts or team notes, add them to `.mintignore`. Mintlify won't publish them, and nobody can reach them by URL. If you need to control who can read pages, set up [authentication](https://mintlify.com/docs/deploy/authentication-setup) for your site. Mintlify's agent features follow the same rules: * On a partly protected site, `llms.txt` and `llms-full.txt` list only public pages. * Markdown pages, search, and the assistant only return pages the reader's user groups can see. * Your MCP server returns public pages to anyone and protected pages only to signed-in users. * Custom skills can be limited to specific user groups with a `groups` field in their frontmatter. Check one more file: if your project has an `AGENTS.md` at its root, Mintlify publishes it at `/agents.md`. Move it to `.mintlify/AGENTS.md` or add it to `.mintignore`. Store secrets in a secret manager, never in a documentation page. ## Keep examples safe to copy Use unmistakable placeholders such as `YOUR_API_KEY` and explain where readers should supply the real value. Never paste a working credential, private hostname, customer identifier, or production response into an example. Check screenshots too. Browser tabs, account names, email addresses, tokens, and internal URLs can appear outside the area you meant to document. Add automated secret scanning to the repository when possible, but don't rely on automation alone. Reviewers should ask whether every example is safe to publish and copy. ## Separate public and private sources When an agent that helps maintain your documentation has access to both public and private repositories, make the boundaries between them explicit. * State which source is canonical for each audience * Avoid publishing internal instructions that contradict public guidance * Keep pre-release terminology out of public answers until the feature ships ## Test access by audience Add access cases to your evaluation set. * Can a signed-out reader, or an agent with no credentials, retrieve only public content? * Can a signed-in user reach the private guide their group should see, and nothing beyond it? * Does an agent connected to your MCP server with a user's credentials see only that user's pages? * Does an unsupported request cause the agent to guess from internal context? Run these checks whenever permissions, connected repositories, or publication settings change. ## Respond to accidental exposure If a secret reaches the repository or published site, removing the page is not enough. The secret was compromised the moment it became public. Revoke or rotate the value, remove it from the page, and follow your organization's incident process. Git history, caches, and copied agent context may keep the old value long after you edit the page. Quiz You set hidden: true on an internal page. It no longer appears in navigation or llms.txt. Is it protected from agents? Next up: [Keep content agent-friendly over time](/courses/agent-friendly-content/ongoing-maintenance)—maintain accuracy, terminology, evaluations, and access boundaries as the product changes. # Test whether agents can use your content Source: https://learn.mintlify.com/courses/agent-friendly-content/test-agent-readiness Create a small set of questions you can rerun to catch answers that are wrong, incomplete, or unsupported before your users do. The only way to know whether agents can use your content is to ask them. A few questions now and then catch obvious gaps, but they won't tell you whether last month's restructure made answers better or worse. For that, you need a small, saved set of questions that you ask the same way every time and compare over time. ## Start with real user questions Pull questions from support tickets, search queries, assistant conversations, onboarding calls, and common product tasks. Keep the original wording when you can. Users rarely describe a problem with the exact terms you use to describe your product, so it's helpful to test their phrasing. Include several kinds of questions. Some types of questions and examples include: * **Direct lookup**: "What is the maximum request size?" * **Task-based**: "How do I rotate an API key without downtime?" * **Troubleshooting**: "Why does my webhook return 401?" * **Cross-page**: "Which authentication method should I use for a browser app?" * **Unsupported**: "Can I deploy this product on a game console?" * **Ambiguous**: "How do I change the limit?" It might seem counterintuitive to test questions that aren't answered in your documentation. But you want to know whether an agent asks for context or states that your documentation doesn't have an answer. A confident guess is a bad answer. ## Choose which agents to test Answers depend on the tool and how it reaches your content. The same question can get different answers from: * Your site's Mintlify assistant, which searches your docs directly * A general AI tool like ChatGPT or Claude using web search * A coding agent connected to your MCP server Test the tools your users actually use. For each run, record which tool you used and how it accessed your content. Otherwise you can't tell whether an answer changed because of your content or because you switched tools. ## Define what a good answer contains For each question, write down: * The facts the answer must include * The page or pages that support those facts * Any important warning or prerequisite * What the answer must not claim * Whether the agent should answer, ask a follow-up question, or say the docs don't cover it Don't require the agent to answer the question exactly. You aren't writing a script for it to recite. Focus on the substance of the answer. Would it help your users succeed with the task they're trying to accomplish? ```yaml Example evaluation case theme={null} question: How do I rotate an API key without downtime? expected: - Create a second key before revoking the first - Update the application to use the second key - Verify requests succeed before revoking the old key sources: - /security/rotate-api-keys must_not: - Tell the user to revoke the active key first ``` ## Look beyond correct or incorrect An answer can get the main fact right and still leave someone stuck. Check for: * **Correctness**: Are the claims accurate? * **Completeness**: Does it include the steps, prerequisites, and risks needed to act? * **Grounding**: Do the cited pages support the claims? * **Restraint**: Does the agent avoid inventing an answer when the content is missing? * **Usefulness**: Can the reader take the next step without guessing? Phrasing isn't part of this test unless the prose makes the answer hard to understand. ## Run the same questions before and after changes Before a major content or configuration change, save the current answers as a baseline. Run the same questions afterward and compare them. If an answer gets worse, trace the problem back to its source: 1. Did the agent find the right page? 2. Did the page contain the answer in a focused section? 3. Did titles, descriptions, or terminology make the page hard to match? 4. Did outdated or duplicate content compete with the canonical source? Fix the content or configuration that caused the failure. Don't contort one sentence to make a single test pass. Your pages still need to work for questions you haven't anticipated. ## Keep the question set manageable Start with 5-10 questions that cover the tasks your users care about most. Add questions if you discover a new gap in your content and want to test for it. Remove questions that no longer reflect your product. Run the set after major releases, navigation or terminology changes, and updates to `llms.txt` or agent instructions. Keep reviewing a sample of live questions too. A fixed set helps you catch regressions, but it won't tell you about every new need. Assistant analytics are a good source: look for topics that come up often or get poor ratings. ## Check the technical setup too Content quality and technical setup fail in different ways. Your question set tests the content. To test the setup, run `mint score` from the Mintlify CLI. It checks whether agents can reach your `llms.txt`, get Markdown versions of your pages, find your MCP server and `skill.md`, and get past your `robots.txt`. Run it when you change any of those settings. Quiz An agent answers all but one question correctly. It invents an answer to one question that your documentation doesn't cover. How should you treat that result? Next up: [Protect private and sensitive information](/courses/agent-friendly-content/security-and-access)—make sure agents only access the content they should. # Write content agents can use Source: https://learn.mintlify.com/courses/agent-friendly-content/write-for-agents The specific writing and structural habits that make your content reliable context for agents. [Write content agents can use](https://www.youtube.com/embed/uoXz3K8lx8U) Agents often read one page, or part of one, with no surrounding context. The habits in this lesson make each page hold up on its own. They help people too: readers who land on a page from a search result or an agent's citation are in the same position. ## Make every page self-contained Write every page as if the reader has never seen any other page on your site. That means: * Define terms and acronyms the first time they appear on each page * Include prerequisites and information about who can access features * Document all the steps required to complete a task * Don't write "as mentioned in the overview" or "once you've completed the previous step" without making it clear what that refers to * If a page depends on something being set up first, say so explicitly at the top: "This guide assumes you've already authenticated. If you haven't, see [Authentication](https://docs.example.com/authentication)." Treat each page as a document, not a chapter. ## Write specific titles and descriptions Every page must have a title and a description. These are the primary signal an agent uses to decide whether a page is relevant to a user's question. **Titles** should be specific enough that their content is unambiguous: | Vague title | Specific title | | - | - | | Advanced configuration | Configure rate limits for API requests | | Authentication | Authenticate API requests with API keys | | Troubleshooting | Fix common webhook delivery failures | **Descriptions** should answer "Why would someone read this page?" in one concrete sentence. Name the task it supports and the specific topics it covers. A weak description: > "Learn about our authentication system and how to use it in your application." A strong description: > "Authenticate API requests using API keys. Covers generating keys, passing them in request headers, and handling 401 errors." The second version tells an agent exactly what the page contains. When a user asks, "Why is my API call returning a 401?", the agent can pick this page because the description mentions 401 errors explicitly. On Mintlify, descriptions also appear next to each page in your `llms.txt` file, so agents see them before they fetch anything. A useful test: if you covered the title and showed only the description to someone unfamiliar with your product, could they tell what the page is about? ## Use headings that stand alone Headings serve as navigation aids for both humans and agents. A heading like "Part three" or "More options" tells an agent nothing about what's in the section. A heading like "Set a retry policy for failed requests" is specific enough to match against a user's question. Apply the same principle as titles: specific enough to stand alone. ## Keep pages focused on one thing A page that covers installation, configuration, and troubleshooting in one place asks an agent to extract a specific answer from a mixed-topic document. Sometimes it succeeds. Often it doesn't. If users frequently need multiple topics together, link between them rather than combining them. A focused page is easier for an agent to match to a question, and easier to quote accurately. If your site has many mixed-topic pages, start revising your highest-traffic pages and the ones most often surfaced in support tickets. You can improve your content over time, starting with the pages that are most important to your users. ## Use consistent terminology Pick one name for each concept and use it everywhere. If some pages say "workspace" and others say "organization" for the same thing, a person can usually work it out. An agent may treat them as two different concepts, or give an answer that mixes them. This is especially important for: * Product features and UI elements * Role names and permissions * Core concepts your users must understand to succeed with your product If you've used multiple terms for the same thing in the past, write down the canonical terms where AI writing tools will see them, so they don't reintroduce the old ones. For Mintlify's agent, that's `.mintlify/AGENTS.md`. [Give agents your team's conventions](/courses/agent-friendly-content/agent-instructions) covers where other tools look. ```markdown .mintlify/AGENTS.md theme={null} ## Terminology - Use "workspace" not "organization" or "team"—these are the same thing; workspace is correct - Use "API key" not "token" or "secret" when referring to authentication credentials - Use "publish" not "deploy" or "push" when describing sending changes live ``` You'll still need to check edits, but the tools start from the right terms instead of whichever one they saw last. ## Write complete examples When you include a code example, make it runnable. Agents surface examples to answer user questions, and coding agents like Claude Code or Cursor use them to generate code. An example with unexplained placeholder values, or that's missing an import or initialization step, might produce errors when users try to use it. A complete example: * Can be run as-is, or includes clear placeholders that explain what to substitute * Includes all necessary imports and initialization * Shows the expected output or result where it isn't obvious If a full working example would be very long, break it up and make each section self-contained. ## Avoid implicit references Phrases like "the above," "as mentioned," "this value," and "it" create ambiguity that humans resolve through context but agents often can't. Be explicit: | Implicit reference | Explicit reference | | - | - | | Pass this value to the next function | Pass the `session_token` from the login response to `createSession()` | | As mentioned in the previous section | As explained in [Authentication](https://docs.example.com/authentication) | | It will return an error | The API returns a `401 Unauthorized` error | This precision also makes content easier for humans to read. They don't have to hold information in their memory across pages to understand a sentence. Quiz A user asks an agent how to set rate limits. Your site has a page called 'Advanced configuration' that covers rate limits, among other topics. What's most likely to go wrong? Next up: [Help agents find and read your content](/courses/agent-friendly-content/help-agents-find-your-content)—configure the files and features agents use to discover and read your site. # Progressive disclosure with accordions Source: https://learn.mintlify.com/courses/components/accordions Use accordions to hide optional details until readers need them. A rule to remember: readers should be able to complete the task without opening an accordion. If skipping the content could make the task fail, keep it visible. Say you're writing a setup guide with fixes for three uncommon errors. Putting every fix in the main content makes everyone read information most of them don't need. Moving the fixes to another page makes the readers who do need them go looking. Accordions solve this. They only reveal content when readers click on them, so the fixes stay on the page and readers decide when to read them. This approach is called progressive disclosure: show the essentials first and let readers reveal details as needed. ## What belongs in an accordion Use accordions for details that help some readers but are safe for everyone else to skip. * A fix for a specific error message * Customizing settings that don't affect the standard setup * Diagnostic information for investigating an unexpected result * Background that explains why a step works without changing what the reader should do ```mdx Example of an accordion for a troubleshooting step theme={null} Confirm that your firewall allows outbound traffic on port 443, then retry the request. ``` > **Fix a connection timeout** > > Confirm that your firewall allows outbound traffic on port 443, then retry the request. The title identifies who needs the content. Readers who don't have a connection timeout can keep moving. Opening an accordion updates the page URL, so you can link straight to it. That's useful for support: send someone a link to the exact fix instead of the whole page. ## Keep required steps visible Prerequisites, required actions, warnings, and expected results should always be visible. Do not hide them within an accordion. Suppose every reader must do a task, like restart the development server after changing an environment variable. Hiding that instruction makes the procedure look shorter, but it also makes it harder to complete since someone may not click into the accordion and see the required task. ```mdx Example of a required action inside an accordion - don't do this theme={null} Add `API_KEY` to your `.env` file. Restart your development server to load the new value. ``` **1. Add the environment variable** Add `API_KEY` to your `.env` file. > **Additional details** > > Restart your development server to load the new value. Keep the restart instruction visible in the step. Save the accordion for information that only some readers need. ```mdx Example of a better use of an accordion theme={null} 1. Add `API_KEY` to your `.env` file. 2. Restart your development server. Confirm that the file is named `.env` and is in the project root. ``` **1. Add the environment variable** 1. Add `API_KEY` to your `.env` file. 2. Restart your development server. > **The new value isn't loading** > > Confirm that the file is named `.env` and is in the project root. Don't use accordions simply to make a long page look shorter. If the hidden sections have separate goals or must be read in order, split the page or use visible sections. ## Group independent details Use `` when several related items can be read independently. ```mdx Example of an accordion group theme={null} Restart your terminal or run the command with `npx mint`. Run `mint dev --port 3333` to choose another port. ``` > **The CLI command isn't available** > > Restart your terminal or run the command with `npx mint`. > **Port 3000 is already in use** > > Run `mint dev --port 3333` to choose another port. A reader can open either accordion without reading the other. If one accordion depends on another, the content isn't independent and should probably be a procedure. Be careful with long accordion groups. A stack of ten vague titles forces readers to open each one just to find out what the page contains. Break up the group, improve the titles, or move substantial topics to their own sections. ## Choose the component by what readers need Several components hide or emphasize content, but they solve different problems. * Optional detail → **accordion** * A version for the reader's operating system, framework, or other context → **tabs** * Nested fields in API reference content → **expandable** * Information readers must notice → **callout** or **main content** Choose what components to use based on the decision readers need to make. Don't use components just for visual design. ## Give readers a reason to open accordions Accordion titles must describe what is inside. "More," "Details," and "Learn more" force readers to guess. "Fix a 401 response" and "Configure a proxy" make the choice clear. If the title alone isn't enough, add a `description` to show a short line of detail under it. Quiz A deployment guide includes a required command, an optional proxy configuration, and a warning that deploying a new version replaces the current production version. Which content belongs in an accordion? Next up: [Code block essentials](/courses/components/code-blocks)—make examples easier to understand and use. # Components for API documentation Source: https://learn.mintlify.com/courses/components/api-components Document parameters, response fields, nested objects, and request examples with components designed for API reference. Someone reading an API reference usually arrives with a specific question like "Is this parameter required?" or "What type does this field return?" or "What does a successful response look like?" Mintlify's API components put those answers in predictable places. Readers can scan the page instead of digging through paragraphs or decoding a hand-built table. ## Document request parameters Use `` for path, query, body, and header parameters. The prop identifies where the parameter belongs. Add its type and whether it is required, then describe any limits a reader could otherwise miss. ```mdx Example of request parameters theme={null} Maximum number of users to return. Accepts values from 1 to 100. Bearer token in the format `Bearer YOUR_API_KEY`. ``` Don't make readers guess about allowed values, formats, units, or limits. "The number of results" leaves questions. "Maximum results per page, from 1 to 100" answers them. Adding a `` to a page also adds an API playground, where readers can fill in the parameters and send a real request. If a parameter is being phased out, add `deprecated` so readers see it before they build on it. ## Describe response fields Use `` for values returned by the API: ```mdx Example of a response field theme={null} ISO 8601 timestamp for when the user was created. ``` For a nested object, put an `` inside its parent field. Readers can see that `id` and `email` belong to `user` without having every child property open by default. ```mdx Example of nested response fields theme={null} The newly created user. Unique identifier for the user. Primary email address for the user. ``` Use expandables for this kind of nested reference data. If you're hiding optional explanation rather than child properties, use an accordion. ## Pair requests with responses `` and `` show the complete exchange in the page's side panel. Start with a successful request, then add the error responses readers are likely to encounter. ````mdx Example of request and response examples theme={null} ```bash cURL curl https://api.example.com/users \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```json 200 OK { "id": "usr_123", "email": "ada@example.com" } ``` ```` Check examples against the field documentation whenever the API changes. A field marked as required shouldn't be missing from the example, and a renamed field shouldn't survive in an old response block. ## Generated reference versus hand-written reference If you have an OpenAPI document, let it [generate your API reference](https://mintlify.com/docs/api-playground/openapi-setup) and define the endpoint structure. Use these components for hand-written guidance on the parts a schema can't explain well: why someone would choose an option, how a workflow fits together, or what to do when a request fails. Try not to define the same field by hand in several places. When its type or behavior changes, one of those copies will eventually be missed. Quiz An API response contains an address object with six child properties. Which components represent that structure best? Next up: [Images, frames, and diagrams](/courses/components/visual-content)—add visual context that explains a task or relationship. # Site-wide, page-level, and inline signals Source: https://learn.mintlify.com/courses/components/banner-tag-badge Use banners for site-wide announcements, tags for page status in the sidebar, and badges for inline labels. Callouts sit in the main content and interrupt the reading flow. Some signals work better elsewhere: across the whole site, in the sidebar before a reader opens a page, or as a small label next to the thing it describes. Banners, tags, and badges handle those three cases. ## Banner: site-wide announcements A banner appears at the top of every page. It isn't a component you add to a page. You configure it once with the `banner` property in `docs.json` and choose whether readers can dismiss it. Use a banner when: * You're announcing a deprecation that affects a significant portion of your users. * A feature is in maintenance mode or temporarily unavailable. * There's a breaking change in an upcoming release that everyone needs to know about before they continue reading. Set `type` to match the urgency: `info` for general announcements, `warning` for maintenance or upcoming changes, and `critical` when readers need to act. ```json Example of a banner in docs.json theme={null} { "banner": { "content": "API v1 is deprecated and will be removed on March 31. [Migrate to v2](/guides/migrate-v2) before that date.", "type": "warning", "dismissible": true } } ``` If a reader dismisses a banner, it stays hidden for them until you change its content. ### When not to use a banner If an announcement is only applicable to a small portion of your users, don't use a banner. Don't use a banner for: * A new feature announcement that isn't urgent or widely relevant (write a changelog entry instead). * Page-specific notes or warnings (use a callout instead). * Content that applies to only some users (the banner appears to everyone). The cost of a banner is high: it takes up space on every page and if it's not relevant to people, it trains them to dismiss banners without reading them. Use banners thoughtfully, and retire them promptly. ## Tag: sidebar labels for pages The `tag` frontmatter property adds a short label next to your page title in the sidebar. Use it to signal the status of a page to readers before they open it. ```yaml Example of a tag theme={null} --- title: "Streaming responses" tag: "New" --- ``` Tags are useful for: * Marking new pages or recently updated content so returning users notice them. * Labeling preview or beta features that aren't yet stable. For deprecated pages, Mintlify has a specific frontmatter property: `deprecated: true`. ```yaml Example of a deprecated page theme={null} --- title: "Legacy authentication" deprecated: true --- ``` This displays a "Deprecated" label next to the page title. ## Badge: inline labels and status indicators Use `` components to communicate status, version, or category inline with your content. ```mdx Example of a badge theme={null} ## Streaming responses New Streaming is now available for all API tiers. ``` Common uses for badges include: * Versions and availability: Available in v2.3+ * Status indicators: Beta, Deprecated, Enterprise * Requirements and defaults: Required, Optional, Default ## Tags versus badges Both tags and badges are labels, but they appear in different places and serve different readers. A tag is a sidebar signal. It's visible before the reader opens a page and useful for readers scanning navigation. A badge appears inside the content and labels something at the point where the reader encounters it. The right choice depends on when the reader needs the information: in the sidebar while navigating or in the content while reading. Quiz You've released a new page documenting a beta feature. You want readers to know it's in beta before they open the page. Which approach fits best? Next up: [Steps or numbered lists](/courses/components/steps-or-lists)—choose the right structure for instructions readers must follow. # Describe branching procedures Source: https://learn.mintlify.com/courses/components/branching-procedures When a procedure splits by platform, role, or preference, how you handle the fork determines whether users find their path or get lost. Many setup procedures branch. Install on macOS or Windows, configure for cloud or on-premises, authenticate with an API key or OAuth. Your job is to help readers find their path without wading through instructions that don't apply to them. ## Three approaches to branching procedures ### Tabs inside a step When the differences are short—a few lines each or a single code block—and part of a procedure, put the options inside a tab within the step that diverges. ````mdx Example of tabs inside a step theme={null} ```bash brew install acme-cli ``` ```powershell winget install Acme.CLI ``` Run `acme --version` to confirm the installation succeeded. ```` This keeps the procedure together and makes it clear the variation applies specifically to that one step. The steps before and after are the same for everyone. Not every reader notices tabs, so use them carefully. Keep information that applies to every path outside the tabs. Use tabs inside steps when: * Only one or two steps in the procedure vary by platform. * Each variation is short and fits within a single step, not an entirely separate procedure. * The reader doesn't need to make a meaningful decision about which path to take or the selection criteria are obvious like picking their operating system. ### Separate how-to guides When the differences between branching procedures are more in depth, or the choice affects more than just a few steps, write separate guides and link to them from a decision point. ```mdx Example of a decision point theme={null} Choose the authentication method that fits your setup: Best for server-to-server requests and scripts. Simpler to set up. Required for accessing user data. More setup, but more control. ``` This approach is easier to read and easier to maintain when the procedures diverge significantly. Readers self-select into their path and follow that guide from start to finish. Make sure people are finding the right guide for their path. Review feedback and search results related to the guides to identify gaps and areas for improvement. Use separate guides when: * The differences between procedures involve more than 3-4 steps each. * The procedures require different prerequisites. * A user who takes one path will never need the other. ### A prerequisite step that routes the reader For longer procedures where the initial steps are identical but the later steps diverge, make the branching point clear before the user begins the shared steps. This avoids frustration from having readers discover halfway through that they need to take a different path. ```mdx Example of routing before a procedure theme={null} Before you begin, decide where you'll deploy. Everyone completes steps 1-4. Then: - **If you're deploying to the cloud**, continue to [Deploy to the cloud](#deploy-to-the-cloud). - **If you're self-hosting**, continue to [Deploy on your own servers](#deploy-on-your-own-servers). ``` This way, readers know up front how the procedure branches out, and can follow the correct path without having to backtrack. This is a lightweight version of the separate-guides approach. It's appropriate when most of the procedure is shared and only the last few steps differ, so two parallel guides would mostly duplicate each other. ## What to avoid A common mistake is embedding a branch mid-procedure without clearly signaling it. ```mdx Example of an unclear branching point theme={null} Add your key to the config file if you're using API key auth. For OAuth, you'll need to register a client application first. ``` This forces every reader to understand both paths to figure out which applies. Even users who know exactly which auth method they're using have to read carefully to make sure they're not missing something. The fix is to make the decision explicit before the step begins, or use tabs so the paths are visually separated. Quiz A setup guide has 8 steps total. Steps 1 and 2 are identical for everyone, but the rest of the procedure is completely different for free and paid plans. What's the best approach? Next up: [When a procedure outgrows a page](/courses/components/complex-procedures)—how to recognize when a procedure is too long for one page, and how to restructure it. # When callouts stop working Source: https://learn.mintlify.com/courses/components/callout-fatigue Callouts lose their impact if readers skip them. Learn when that happens and how to fix it. Callouts should tell readers to pay attention. If you overuse them, they become visual noise that readers skip. This is callout fatigue. The fix isn't simply to use fewer callouts. First, decide whether the content belongs in a callout at all. If readers need information to complete the task, put it in the main content. Use callouts for exceptional context, optional advice, or genuine risk. ## When callout fatigue happens Callout fatigue builds gradually. Each callout may make sense on its own, but together they form a wall of styled text that's hard to scan. It also happens across a site. As more people write pages, the same callout type starts to mean different things in different places. Readers stop knowing what to expect from a callout and start ignoring them. That creates two problems: * When something is actually dangerous, people might ignore a warning because it looks like every other callout with less important information. * Content outside of the callouts becomes hard to read because callouts create too much distraction. ## How many callouts to use There's no useful universal limit. A page with one unnecessary callout has a problem; a reference page with several focused caveats may not. When a page has several callouts, ask these questions about each one: * Would a reader encounter a problem if they didn't see this? * Does this need to be visually separated from the main content, or should it be part of another section? * Is this callout compensating for prose that could be clearer? Callouts are sometimes used to fix problems introduced by other content. Instead of rewriting a paragraph, someone adds a `` explaining a caveat. Over time these callouts accumulate. Often, the fix is to revise the main text of a page instead of adding another callout. ## Main ideas should be in the main content Putting important information in a callout feels like it makes the information stand out. It can do the opposite: readers who have learned to skip callouts skip that information too. If users need to know something to complete the task, that information belongs in the procedure. Reserve callouts for things that apply to a subset of users, edge cases, or genuine risks. When readers skip past callouts and miss something important, that's a writing problem, not a reader problem. This is especially common in setup guides: ```mdx Example of a poorly used callout theme={null} {/* Users need to know where to save their environment variables earlier in the procedure. */} 1. Copy your API key from your Mintlify dashboard. 2. Replace `your-key` with your actual key: `API_KEY=your-key` 3. Restart your development server so that the new environment variable loads. Set your environment variables in your `.env` file. ``` Move the required detail into the procedure: ```mdx Better: required information stays in the main path theme={null} 1. Copy your API key from your Mintlify dashboard. 2. In your `.env` file, replace `your-key` with your key: `API_KEY=your-key`. 3. Restart your development server so the new environment variable loads. ``` ## Multiple callouts on the same page If you find yourself writing several `` callouts on a single page, stop and examine the content itself. Multiple warnings on one page can indicate: * The feature has too many dangerous edge cases and the documentation is papering over a product problem. * The procedure is too long and should be split into smaller pages. * Some of the warnings aren't actually `` level and should be downgraded or removed. This applies to every callout type. If a page has many callouts, step back and look at the content itself. Ask two questions: What are readers trying to do, and what do they need to do it correctly? Quiz A setup guide puts the required configuration file, supported runtime version, and restart command in three separate notes. What should you change? Next up: [Site-wide, page-level, and inline signals](/courses/components/banner-tag-badge)—how banners, tags, and badges help emphasize information site-wide, at the page-level, and inline. # Choose the right callout Source: https://learn.mintlify.com/courses/components/callout-types Mintlify gives you a variety of callout types. Use them to send different signals to your readers. Callouts interrupt the reading flow so people stop and pay attention. Each type sets a different expectation: optional advice, useful context, a risk, or confirmation that something worked. Use those signals consistently. When callout styling is just decoration, readers can't tell which information deserves their attention. ## The types of callouts Each callout type has its own icon and color, and readers learn what they mean from how you use them. Choose a consistent meaning for each one. Here are some general guidelines: | Component | Signal | Use when | | - | - | - | | `` | Neutral addition | There's something useful to know that doesn't fit in the main flow. | | `` | Context worth noticing | A fact or caveat changes how the reader understands the surrounding content. | | `` | Optional improvement | There's a best practice or shortcut the reader might not discover on their own. | | `` | Caution required | Something could break or cause data loss if the reader misses this. | | `` | Serious harm possible | Ignoring this information or doing this action incorrectly is destructive, irreversible, or security-critical. | | `` | Confirmation | The reader has completed something correctly, or a requirement has been satisfied. | ## How to choose Ask yourself, "What happens if the reader skips this callout?" * Nothing bad, they just miss something useful → `` or `` * They might misunderstand how something behaves → `` * Something breaks or data gets corrupted → `` * Data gets lost, accounts get compromised, or something irreversible happens → `` The `` callout is different. Use it to give users confirmation after they complete a task. Use the other callout types to guide users before they take an action or make a decision. If skipping the content makes the procedure impossible to complete, it doesn't belong in a callout. The [next lesson](/courses/components/callout-fatigue) covers what to do instead. ```mdx Example of a callout theme={null} Your API key is now active. Verify this by checking the **Keys** section of your dashboard. ``` ## The note versus info distinction These two are easy to conflate, and readers often can't tell them apart. If you want to use both, draw the line this way: * `` is a side thought: "By the way, you might want to know this." * `` is context that changes how the reader understands something: "This feature behaves differently on the free plan." If that distinction is more than your team will apply consistently, pick one and use it for both. Readers won't miss the difference. They will notice if warnings stop meaning risk. ## Don't escalate to sound important The most common callout mistake is using a warning because the content feels significant, but there's no actual risk for the user. If you're using `` to emphasize a default setting or note an API behavior, you're training readers to ignore your warnings. Reserve warning and danger callouts for potentially destructive actions or situations where data could be lost or compromised. If you can describe the worst-case outcome and it's "your request fails with a 400 error," that's not worthy of a warning or danger callout. If the worst-case is "all data in this environment is permanently deleted," that's danger. ## When none of the types fit If you need a callout with a meaning the built-in types don't cover, like a recurring "Enterprise only" note, use the generic `` component with your own icon and color. Use it the same way every time so readers learn what it means. ```mdx Example of a custom callout theme={null} This feature is available on Enterprise plans. ``` Quiz You want to mention that users can prefix any CLI command with DEBUG=true to see detailed log output. It's not required for normal use, but useful when something isn't working as expected. Which callout type fits best? Next up: [When callouts stop working](/courses/components/callout-fatigue)—what happens when you use too many callouts and how to fix it. # Cards and links for navigation Source: https://learn.mintlify.com/courses/components/cards-navigation Choose between an inline link and a card based on how much attention the destination deserves, and put cards where readers make decisions. Inline links and cards both send readers somewhere else, but they send different signals. An inline link says "this is here if you want it." A card says "this is where you should go next." Choose based on how much attention the destination deserves. ## Inline links are the default Use an inline link when: * The reference fits within a sentence. * The destination is supplementary. Readers can keep going without it. * The link is one of several possible paths forward. ```mdx Example of an inline link theme={null} Mintlify's content types are based on the [Diátaxis framework](https://diataxis.fr). ``` Most readers keep reading. Some open the link for context. The inline format signals that it's optional. ## Cards are a call to action A linked card is a navigation element that's hard to miss, even for readers who skim. Use one when: * There's a clear next step and you want to make it prominent. * Readers need to choose between two to four paths. * An overview page points to the pages beneath it. Before adding a card, ask whether you want the reader to go somewhere. If you only want visual polish, a list or plain text does the job with less noise. ## Where cards belong Cards work best at the boundaries of content: the beginning or end of a page, an overview that points to child pages, or a section that exits into a different part of the docs. On overview pages, a grid of cards gives readers a visual menu of what's inside: ```mdx Example of an overview page theme={null} Get your first page live. Link your documentation to a Git repository. Colors, fonts, logo, and layout settings. Publish your docs to a custom domain. ``` At decision points, cards with a short description let readers choose their path: ```mdx Example of a decision point theme={null} Create a new project from scratch. Import existing content and configure your new site. ``` Icon names depend on your site's icon library, which is set in `docs.json`. Check that each name exists in the library you use. ## Card variations Image cards work for course indexes, product listings, or anywhere an image helps readers tell options apart. Use them when the image communicates something the title alone doesn't. ```mdx Example of an image card theme={null} Learn the foundations of a docs-as-code workflow. ``` Horizontal cards create a more compact, list-like layout. To make the action explicit, add `cta` to show a button with your own text. ```mdx Example of a horizontal card with a call to action theme={null} Full endpoint documentation with request and response schemas. ``` ## When not to use cards Don't use cards as styled bullet lists. If a card has a title but no link, it's probably a list item. Don't use cards for supplementary links in the middle of a section. A card interrupts reading and implies the reader should stop and go there. If they can safely keep reading, use an inline link. Don't use cards to navigate within a page. Mintlify builds a table of contents from your headings, and anchor links handle the rest. Quiz Partway through a setup guide, you want to point to a security best practices page. Most users don't need to read it now, but it's useful context. Which fits best? Next up: [End-of-page navigation patterns](/courses/components/end-of-page)—what to put at the bottom of a page to help readers continue. # Code block essentials Source: https://learn.mintlify.com/courses/components/code-blocks A few small choices in how you write code blocks determine whether users can actually follow along. Many code blocks are harder to use than they need to be: no language, no filename, and no indication of which part matters. These details are small, but fixing them makes examples much easier to follow. ## Why specify a language? Mintlify uses the language identifier after the opening backticks to apply syntax highlighting. Without it, the code renders as plain monospace text. ````mdx Example with and without a language tag theme={null} {/* No highlighting. Harder to scan */} ``` npm install @acme/sdk ``` {/* Highlighted correctly */} ```bash npm install @acme/sdk ``` ```` ```text Not highlighted theme={null} npm install @acme/sdk ``` ```bash Highlighted correctly theme={null} npm install @acme/sdk ``` Syntax highlighting reduces the cognitive load of reading code. Readers can see at a glance where strings end, where keywords are, and what's a variable versus a value. Include a language on every fenced block. Common identifiers include: * Shell and commands: `bash`, `sh`, `powershell` * Languages: `python`, `javascript`, `typescript`, `go`, `ruby`, `java`, `sql` * Data and config: `json`, `yaml`, `toml` * Markup and styles: `mdx`, `html`, `css` * Plain output: `text` ## Filenames and titles A filename tells readers where this code lives in their project. A title tells them what it does if a filename doesn't apply. ````mdx Example code block with a filename theme={null} ```json docs.json { "theme": "sequoia", "name": "My Docs" } ``` ```` The filename `docs.json` appears as a label on the code block. Readers know immediately that this is what goes in the `docs.json` file. Use a filename when the code belongs in a specific file. Use a descriptive title when the code is a command or snippet without a natural filename. ````mdx Example code block with a descriptive title theme={null} ```bash Install dependencies npm install ``` ```` ## Draw attention to the lines that matter When a code block is long and you want to emphasize a few lines, use `highlight` with the line numbers or ranges. ````mdx Example line highlighting theme={null} ```python highlight={3} import os API_KEY = os.environ.get("API_KEY") # This line is highlighted client = Client(api_key=API_KEY) ``` ```` ```python highlight={3} theme={null} import os API_KEY = os.environ.get("API_KEY") # This line is highlighted client = Client(api_key=API_KEY) ``` Use highlighting sparingly. If you highlight most of a code block, nothing stands out. Two related options help in specific cases: * **`focus`** dims every line except the ones you name. Use it when the surrounding lines are context the reader needs to see but not study. * **Diff markers** show lines as added or removed. Add `[!code ++]` or `[!code --]` in a comment at the end of a line. Use them when you're showing a change to existing code, like an upgrade guide. ```javascript Example diff theme={null} const client = new Acme({ apiKey: "YOUR_API_KEY" }); // [!code --] const client = new Acme({ apiKey: process.env.ACME_API_KEY }); // [!code ++] ``` ## The copy button Mintlify adds a copy button to code blocks automatically. Users running commands from documentation expect to paste them directly. If the code has a trailing space, a curly quote instead of a straight quote, or wraps in a way that introduces a line break, the command won't run and users won't know why. Write commands exactly as they should be typed without extra spaces or decorative characters. Test them before publishing. Some code blocks aren't meant to be copied, like terminal output or an ASCII diagram. Add `nocopy` to hide the copy button so readers don't paste output as if it were a command. ## Keep examples short Code blocks that contain more than the reader needs force them to figure out which parts apply and which are setup they already did. When showing a configuration change, show only the relevant section, and tell readers where it goes. ````mdx Example of only part of a config file theme={null} Add `primary` inside the `colors` object in your `docs.json`: ```json docs.json "colors": { "primary": "#166E3F" } ``` ```` When a complete example really is long, like a full configuration file, add `expandable` so the block starts collapsed and readers can open it if they need the whole thing. Quiz A code block shows a Python function with 20 lines. Three lines configure an environment variable. The rest is standard SDK setup the user completed two steps ago. What should you do? Next up: [When to explain code and when to just show it](/courses/components/code-in-context)—how to place code blocks within explanations so readers understand what to do and why. # When to explain code and when to just show it Source: https://learn.mintlify.com/courses/components/code-in-context How much prose to put around a code block depends on what the reader is trying to do. Over-explaining slows down experts. Under-explaining loses beginners. Code needs the right amount of context. Too little leaves beginners guessing; too much slows down experienced readers. The balance depends on the page and its audience. ## How does the content type affect explanation? Reference pages are looked up, not read top-to-bottom. Someone reading an API reference page already knows what they want. They are after the parameters, the types, and a quick example. Long prose explanations slow them down. ````mdx Reference page example theme={null} ## Create user Creates a new user and returns the user object. Full name. Email address. ```json Response { "id": "usr_01J...", "name": "Ada Lovelace", "email": "ada@example.com", "created_at": "2025-01-01T00:00:00Z" } ``` ```` No prose about what a user is, why you'd create one, or what happens after. The reference page trusts the reader knows what they want to do, they just need the details. How-to guides explain the steps, not the concepts. Readers need the path forward. Brief prose before code blocks identifying what's about to happen is helpful. Paragraphs explaining why the API was designed this way are not. Tutorials explain reasoning alongside steps. Beginners need to understand not just what to do but why, so they can troubleshoot when things go wrong. Code blocks in tutorials often warrant a brief explanation of what the code does and what to expect from it. ## Inline comments versus prose When only part of a code block needs explanation, inline comments are often clearer than a paragraph after the block. Keep them short, because readers who copy the code copy the comments too. ```python Inline comments theme={null} client = acme.Client( api_key=os.environ["API_KEY"], # Never hardcode your key timeout=30 # Increase if you're uploading large files ) ``` Use inline comments for: * Non-obvious choices ("why 30 seconds for a timeout?") * Things that are commonly misconfigured ("should I use `api_key` or `API_KEY`?") * Variables the reader will need to replace ("replace `YOUR_API_KEY` with your actual API key") Avoid inline comments for things that are obvious from the code, or for adding step numbers like `# Step 1: Initialize the client`. If the comment restates what the code says, you probably don't need it. ## Explain before, confirm after For how-to guides and tutorials, one sentence before the code block identifies what's about to happen and gives readers context for what they're reading. ````mdx Explain-then-show pattern theme={null} Create a client instance with your API key. You'll reuse this client throughout your application. ```python client = acme.Client(api_key=os.environ["API_KEY"]) ``` ```` The sentence creates context then the code demonstrates. The reader who already knows Python sees the sentence and can predict the code. The reader who's less comfortable reads the sentence and then has a frame for the code. Don't save the explanation for after the code. If readers hit code they don't understand, they might stop or leave the page rather than keep reading in hopes of an explanation. After the code, say what should happen when it works, if that isn't obvious: "The request returns `201 Created` and the new user's ID." That's not an explanation of the code. It's how readers know they can move on. ## What counts as obvious depends on the reader Content for beginners needs more explanation than content for experienced users. A step that's obvious to someone who's written API integrations before might not be obvious to someone setting up their first integration. Before deciding how much to explain, consider your audience for the specific page where the code block appears. If you've defined your readers as developers with API experience, trust that experience. If you're writing for people who are new to using your product and APIs, explain the parts that experienced users take for granted. Quiz You're writing a reference page for a webhook event object. Should you include a paragraph explaining what webhooks are and why they're useful? Next up: [Tabs and code groups](/courses/components/tabs)—let readers switch to the version of the content that applies to them. # Columns and cards for visual comparisons Source: https://learn.mintlify.com/courses/components/columns-and-cards Use columns and cards when a table is too rigid or your comparison items need richer content than a cell can hold. Tables work for compact, attribute-heavy comparisons. When each option needs a description, link, or visual cue, combine `` and `` for a roomier side-by-side layout. ## Columns for side-by-side content `` arranges its children side by side, in one to four columns that collapse to a vertical stack on smaller screens. To put text, lists, or code side by side, wrap each column's content in ``. ```mdx Side-by-side comparison with columns theme={null} **API key authentication** Simple to set up. Best for server-to-server requests where user identity doesn't matter. Not suitable for client-side code because the key would be exposed. **OAuth 2.0** More setup required. Required when you need to act on behalf of a user. Tokens are short-lived and scoped, which limits the damage from a token leak. ``` This layout works when you're presenting two or three alternatives that need more information than a table cell can hold, but not so much that they each need their own page. ## Cards in a comparison context `` components add a title, and optional icons, images, or links. In a comparison, cards with links let readers go straight from the comparison to the guide for the option they chose. The example below adds a recommendation before the cards. Side-by-side layouts imply the options are equally valid, so if one option is right for most readers, say so first. ```mdx Comparison with cards and a recommendation theme={null} For most users, API key authentication is the right choice. Use OAuth if your app needs to access resources on behalf of individual users. Server-to-server requests. Simpler setup. Not for client-side use. User-delegated access. Required for acting on behalf of users. More setup. ``` ## When are columns and cards the right choice? Use columns with cards when: * You have two to four options and each needs a short description. * Each option links to a separate page where users can get the full details. * The options are parallel. They are the same kind of thing, but with different tradeoffs. * A table would be too rigid because the options don't have a neat attribute/value structure. Quiz You're comparing two pricing plans with eight attributes each: storage, API calls, support level, and five more. Which component is most appropriate? Next up: [Components for API documentation](/courses/components/api-components)—document parameters, responses, nested objects, and examples. # When a procedure outgrows a page Source: https://learn.mintlify.com/courses/components/complex-procedures Split a complex procedure at meaningful task boundaries so readers can make progress without losing context. A long page isn't automatically a bad page. A twenty-step procedure with one clear outcome can be easier to follow than five short pages that make readers jump back and forth. Don't end pages at arbitrary lengths. Split up procedures when readers reach a meaningful task or stage boundary. ## Keep one outcome on one page Keep a procedure together when: * Every reader follows roughly the same path * The steps lead to one clear outcome * Readers are likely to complete the work in one sitting * Splitting the page would make them carry details from one page to the next A page can scroll and still be easy to follow. Clear step titles, useful headings, and visible success criteria matter more than the raw number of steps. ## Split at a meaningful boundary A page break should mark real progress. Strong reasons to split a procedure include: * Readers complete a distinct milestone before moving on * The next stage has different prerequisites or applies to a different audience * There's a natural pause where readers may stop and return later * One stage needs enough explanation or troubleshooting to distract from the main procedure Name each page for what the reader accomplishes: * Connect your repository * Configure deployments * Publish your site Avoid labels such as "Setup, part 1" and "Setup, part 2." They describe the document's structure, not the reader's progress. If only some readers need the next stage, say who should continue and who is finished. For procedures with substantially different paths, create separate guides and route readers before the paths diverge. ## Connect the pages Guide users forward at the end of each page. ```mdx Example of a card component used for a next step link theme={null} You've connected your repository. Next, configure your deployment settings. Set your build command, output directory, and environment variables. ``` Next steps can be simple, like a single sentence with a link. The [end-of-page lesson](/courses/components/end-of-page) covers when to use a card and when a sentence is enough. Users who complete a page shouldn't have to return to an index to find out what comes next. Tell them what they accomplished, what the next page helps them do, and whether continuing is optional. ## Update the navigation When a procedure spans multiple pages, make sure the navigation reflects the sequence. In `docs.json`, list the pages in order within a group: ```json Example group theme={null} { "group": "Set up your account", "pages": [ "guides/create-account", "guides/connect-repository", "guides/configure-deployments", "guides/publish" ] } ``` The sidebar order communicates the sequence. A user who gets lost can look at the sidebar and see where they are in the overall flow. ## Don't hide required stages Accordions can keep optional explanations and troubleshooting close to a step. They shouldn't contain an entire required stage of a procedure. Collapsing required work makes it look optional and makes the overall process harder to scan. If the stage is required and substantial, keep it visible or give it a focused page. If it's optional help, an accordion may be the right fit. Quiz A deployment guide covers connecting a repository, configuring a build, and publishing a site. Readers often pause after connecting the repository, and build configuration has its own prerequisites and troubleshooting. What's the best structure? Next up: [Progressive disclosure with accordions](/courses/components/accordions)—keep optional details nearby without hiding the main path through a procedure. # Conditional content Source: https://learn.mintlify.com/courses/components/conditional-content Use views when a reader's choice changes an entire page, and visibility to show different content to people, AI agents, or user groups. Sometimes changing the programming language or framework changes more than the code. The headings, explanations, and procedure may all follow a different path. The `` component lets readers make that choice once and see the version of the page that applies to them. Use views for page-level variation. If only one section or code sample changes, a smaller component will be easier to follow. ## How views work Each `` block has a `title` that appears in a dropdown on the page. When a reader chooses a title, the page shows the matching view and updates the table of contents. Use one view per option on a page. ````mdx Example of views theme={null} ## Send an asynchronous request ```javascript const response = await client.messages.create(options); ``` ## Send an asynchronous request ```python response = await client.messages.create(**options) ``` ```` Try the selector on this page. Switching between JavaScript and Python changes the example below. ### JavaScript example ```javascript theme={null} console.log("Hello from JavaScript!"); ``` ### Python example ```python theme={null} print("Hello from Python!") ``` ## Choose the smallest component that fits Views, tabs, and code groups all show variations, but at different scales: * Use `` when the explanation stays the same and only the code changes. * Use `` when one section changes based on the reader's platform, role, or another known context. * Use `` when the selection changes headings, explanations, or several examples across the page. For example, an SDK guide may use views when its JavaScript version explains promises while its Python version explains synchronous and asynchronous clients. Those differences affect the page's structure, not just a code block. ## Keep shared information visible Put introductions, prerequisites, and warnings that apply to every reader outside the view blocks. Duplicating them creates extra maintenance, while placing them in only one view hides them from everyone else. Views are also a poor fit when readers need to compare the options before choosing. The selector shows one version at a time, so use a table or visible sections for a comparison. Don't use views simply to shorten a page. The hidden content should be an alternative version, not required information that every reader needs. ## Show different content to different audiences Views let readers choose. The `` component chooses for them, based on who's reading. **People and AI agents.** Content wrapped in `` appears on your site but not in the Markdown version that agents read. Content in `` does the opposite. Use it when the best instructions differ: a person clicks a button, while an agent calls an API. ```mdx Example of agent-only content theme={null} Click **Create account** in the top-right corner. To create an account, call `POST /v1/accounts` with a valid email address. ``` **Signed-in readers and user groups.** If your site uses authentication, `` can also show content only to signed-in or signed-out readers, or to specific user groups. For example, show a "Sign in to see your API keys" prompt to signed-out readers and the keys page link to everyone else. Like views, visibility works best for alternatives. Keep information everyone needs outside the component. Quiz Your quickstart tells readers to click through three dashboard screens to create an API key. AI agents helping users can't click, but they can call your API. What should you do? Next up: [Tables for structured comparisons](/courses/components/tables)—when a grid communicates relationships better than prose or cards. # End-of-page navigation patterns Source: https://learn.mintlify.com/courses/components/end-of-page The bottom of a page can be a navigation decision point. What you put there determines whether readers continue naturally or have to figure out what comes next. Documentation often assumes readers will follow a set order. In reality, people skip around and take unexpected paths. You can still give them useful signposts. At the end of a page, tell readers whether they're done or should continue somewhere else. ## Link to the next page The lightest option is a single sentence that names the next page, says what it covers, and links to it. You've probably noticed these at the end of lessons in this course. ```mdx Example of a next page link theme={null} Next up: [Configure your deployment settings](/guides/configure-deployments)—set your build command, output directory, and environment variables. ``` Link to the next page when: * The flow is linear. There's one obvious next step. * The content is part of a sequential course or tutorial. * You want to maintain reading momentum. Include a description. A bare link doesn't tell the reader why they should go there. Help your readers understand why they should read the next page and what they'll learn. ## Use a card at the end of a page When readers have a choice of next steps, cards make the options easy to compare. ```mdx Cards at the end of a guide theme={null} You've set up authentication. Choose your next step: Send a request and see a real response. Full endpoint documentation with request and response schemas. ``` Use cards at the end when: * You want to make the next step prominent and scannable. * The destination is important enough to stand out even for readers who skim to the bottom. * You want to guide readers between a choice of next steps. ## Let the sidebar do the work For reference pages like API endpoints, configuration options, or component documentation, readers usually navigate with the sidebar or search rather than following a set path. Explicit next steps at the bottom of every reference page don't help much, because you can't predict where each reader goes next. That's fine. Mintlify adds previous and next links to the bottom of each page automatically, following your navigation order. You only need to add your own navigation when the navigation order doesn't match the reading order, or when you want to send readers outside the current section. On standalone pages where previous and next don't make sense, like a landing page, set `hideFooterPagination: true` in the page's frontmatter. ## Suggest related topics For pages without one obvious next step, a list of related pages helps readers who want to keep exploring. Turn on **Related topics** in your dashboard settings, and Mintlify adds suggested pages to the bottom of each page automatically. To choose the suggestions yourself, list them in the page's `related` frontmatter: ```yaml Example of related topics theme={null} --- title: "Rotate an API key" related: - /guides/create-api-key - /reference/api-keys --- ``` Set `related: false` to hide the section on a page where it doesn't help. ## What not to do Don't add next steps just to have next steps. Sometimes a single page is enough, and your reader is ready to get back to their work. Don't add several competing next steps. If you can't pick the most useful one or two, readers can't either. Quiz You're finishing a step-by-step tutorial, and the next page in the sequence is a reference page with no obvious connection to the tutorial. What's the best end-of-page navigation? Next up: [Small components with specific jobs](/courses/components/supporting-components)—decide when a narrow component earns its place on the page. # How to use Mintlify components Source: https://learn.mintlify.com/courses/components/overview Learn which components to use and when, so your documentation stays clear and consistent. Mintlify includes callouts, cards, tabs, steps, code blocks, and more. Used well, these components help readers find what they need and follow complex instructions. Used poorly, they get in the way. This course will help you choose the right component for the job and use it well. Each lesson pairs a component (or a group of related components) with concrete guidance on how to use it to support your users. > [!TIP] > > Don't have a Mintlify account yet? [Create one](https://mintlify.com/start) so you can try each component in your own docs as you go. ## What you'll learn * How to choose between components that look similar but signal different things to readers * When plain prose or a list is better than a component * How to guide readers through procedures, including ones that branch by platform or role * How to present code, variations, comparisons, API details, and visuals * How to point readers to their next step without cluttering the page ## Who this is for Anyone who contributes to documentation on Mintlify and wants to use components more deliberately. It's especially helpful if you're new to technical writing or writing for the web. ## Lessons in this course ### Call out important information * [Choose the right callout](/courses/components/callout-types)—What each callout type tells readers. * [When callouts stop working](/courses/components/callout-fatigue)—How to recognize and fix callout fatigue. * [Site-wide, page-level, and inline signals](/courses/components/banner-tag-badge)—When to use banners, tags, and badges. ### Guide users through a process * [Steps or numbered lists](/courses/components/steps-or-lists)—Choose the right structure for a sequence. * [Describe branching procedures](/courses/components/branching-procedures)—Help readers follow the path that applies to them. * [When a procedure outgrows a page](/courses/components/complex-procedures)—Split a long procedure without losing the thread. * [Progressive disclosure with accordions](/courses/components/accordions)—Keep optional details nearby without hiding the main path. ### Share sample code * [Code block essentials](/courses/components/code-blocks)—Make examples easier to understand and use. * [When to explain code and when to just show it](/courses/components/code-in-context)—Match the explanation to the reader and page. ### Present content that varies by environment or stack * [Tabs and code groups](/courses/components/tabs)—Let readers pick their language, platform, or role. * [Conditional content](/courses/components/conditional-content)—Change a whole page with views, or show different content to people and agents. ### Show a comparison of options * [Tables for structured comparisons](/courses/components/tables)—Use rows and columns when the content is genuinely tabular. * [Columns and cards for visual comparisons](/courses/components/columns-and-cards)—Give richer options more room. ### Document APIs * [Components for API documentation](/courses/components/api-components)—Document parameters, responses, nested objects, and examples. ### Add visual context * [Images, frames, and diagrams](/courses/components/visual-content)—Choose visuals that explain something prose cannot. ### Direct users to related content * [Cards and links for navigation](/courses/components/cards-navigation)—Match the visual weight of a link to the importance of the destination. * [End-of-page navigation patterns](/courses/components/end-of-page)—Help readers decide what to do next. ### Use supporting components * [Small components with specific jobs](/courses/components/supporting-components)—Decide when tooltips, updates, panels, prompts, file trees, tiles, icons, and colors belong on the page. Next up: [Choose the right callout](/courses/components/callout-types)—what each callout type tells readers. # Steps or numbered lists Source: https://learn.mintlify.com/courses/components/steps-or-lists Both guide users through procedures. This lesson explains when to use each. Numbered lists and the `` component both show a sequence, but they set different expectations. Use `` when the reader performs a sequence and each action needs explanation. Use a numbered list when the sequence is simple or describes what the system does. ## When to use the steps component Use `` when: * The reader performs each step. * Each step needs code, substeps, decisions, or more context than a single list item can hold. ````mdx Example steps theme={null} Go to [mintlify.com/start](https://mintlify.com/start) and sign up. Connect your Git provider during onboarding if you want to work locally. ```bash npm i -g mint ``` Run `mint dev` from your docs directory. The preview opens at `localhost:3000`. ```` The title of each step describes what the user accomplishes. If someone only reads the step titles, and not the content of every step, they should be able to understand the overall procedure. Don't use vague titles like "Step 2" or "Installation." And don't just describe what happens mechanically in a step title, like "Click **Enable**." ## When a numbered list is better Use a numbered list when: * Each item fits in one or two lines. * You're listing things in a logical order, not guiding someone through a task. * The content doesn't need sub-elements like code blocks, images, or multiple lines of context. ```mdx Example descriptive numbered list theme={null} Your changes are deployed in this order: 1. Mintlify validates the `docs.json` structure. 2. Your MDX files compile. 3. The site publishes to your subdomain. ``` This is a sequence of things that happen, not a sequence of things the user does. Using a `` component doesn't help communicate the sequence. ```mdx Example procedural numbered list theme={null} 1. Navigate to your dashboard. 2. Click the **Deploy** button. ``` This is a simple process that doesn't require any decisions or complex actions. A numbered list is a good fit. ## The one-line step problem A common misuse of the steps component is wrapping content without using the component's full capabilities. ```mdx Not the best use of steps theme={null} ``` These one-liners mostly just add whitespace. A numbered list would communicate the same thing. ```mdx Better as a numbered list theme={null} 1. Open your terminal. 2. Run `mint dev`. 3. Open the preview URL. ``` If your steps have no child content—no code blocks, prose, or decisions—they can probably be list items instead. ## Step titles matter Readers scan step titles to understand the overall procedure. If you set `titleSize` to `h2` or `h3` on ``, the titles also become headings on the page. A title like "Configure" is less helpful than "Configure your webhook endpoint." The latter tells you exactly what the step is about. Generally, start step titles with a verb and end with the specific thing being acted on. * "Installation" → "Install project dependencies" * "Analytics script" → "Add the analytics script to your layout" * "Test" → "Test the connection" Quiz You're documenting a feature that activates in three stages automatically after signup. Which should you use? Next up: [Describe branching procedures](/courses/components/branching-procedures)—how to handle when a procedure forks based on platform, role, preference, or other factors. # Small components with specific jobs Source: https://learn.mintlify.com/courses/components/supporting-components Know when a tooltip, update, panel, prompt, file tree, tile, icon, or color swatch earns its place on the page. Some components solve one narrow problem, like defining a term, formatting a changelog entry, pinning an example beside the content, showing a folder structure, or giving readers a prompt they can copy. Before adding one of these components, identify what problem it solves. If the only reason you're about to use a component is because "the page looks plain," text is probably a better choice than a component. ## Define a term without sending readers away A tooltip works for a short definition that helps in the moment: ```mdx Example of a tooltip theme={null} The commit is now on your branch. ``` The sentence still makes sense if someone doesn't open the tooltip. That's important because hover interactions are easy to miss and work differently on touch devices. Keep instructions and required context in the page itself. A tooltip should save a quick detour, not conceal part of the task. Tooltips can include a link with `cta` and `href`, which is useful for pointing to a full definition, but anything readers must follow belongs in the text. ## Give release notes a consistent shape The `` component is built for dated changelog entries: ```mdx Example of a changelog entry theme={null} The local preview now reports broken links before startup completes. ``` Its label creates an anchor, and its tags help readers filter the changelog. That behavior is useful on a release-notes page but unnecessary inside an ordinary guide. When a product change affects the current instructions, update the guide rather than inserting a permanent release announcement into it. ## Trade the table of contents for a side panel `` replaces the page's table of contents with content you choose, like a reference table or a note that applies to the whole page. Request and response examples already appear in the side panel on their own, so you don't need a panel just for those. If you do add a panel to an API page, put the examples inside it. That tradeoff is less attractive on a long guide. If readers rely on the table of contents to move between sections, replacing it with a tip or promotional card makes the page harder to navigate. Use a panel when its content supports the entire page and is more useful than section links, not simply because the space is available. ## Give readers prompts they can actually run Use `` when the content is meant to be copied into an AI tool: ```mdx Example of a prompt theme={null} Read this documentation page and list every prerequisite it assumes. For each one, quote the heading where it should be introduced. ``` A useful prompt says what to inspect and what to return. "Improve this page" leaves both decisions to the tool and gives readers little idea what result to expect. If the text is a shell command or code sample, keep it in a code block. The Prompt component is for instructions to an AI tool, not anything that happens to be copyable. ## Show folder structures as a tree When readers need to know where files go, a file tree is clearer than a sentence or a code block of indented names. Write a nested list inside ``, with a trailing slash on folder names: ```mdx Example of a file tree theme={null} - docs/ - docs.json - quickstart.mdx - guides/ - authentication.mdx ``` Readers can expand and collapse folders, and the tree supports keyboard navigation. ## Use visual helpers only when they add information Tiles combine navigation with a visual preview. They work well for a gallery where the preview helps readers choose, such as themes or component examples. If the image adds nothing beyond the title, use a card or a normal link. Icons help distinguish repeated items, but always pair them with a label. A symbol that feels obvious to your team may mean something different to a reader. Color swatches belong in brand and design-system references where the color value is itself the subject. They aren't a substitute for explaining status or meaning in text. Quiz You want readers to copy a detailed instruction into an AI coding tool. The instruction specifies which file to review and the format of the response. Which component fits best? That's the end of How to use Mintlify components. When you're unsure about a component, write the content in plain Markdown first. Add the component only if it makes the result easier to find, follow, or understand. Ready for more? [Structure docs that scale](/courses/structure-docs/overview) zooms out from individual components to how your whole site is organized. # Tables for structured comparisons Source: https://learn.mintlify.com/courses/components/tables Use tables when you're comparing multiple items against a consistent set of attributes. Tables show relationships between items and attributes. Readers can scan a column to compare one attribute or a row to understand one option. This works only when the content is genuinely tabular. Forcing other content into a table makes it harder to read. It's even harder with a screen reader, which moves through a table cell by cell and relies on the headers to explain each one. ## When are tables the right choice? Tables work well when: * You have multiple items (rows) with the same set of attributes (columns) * Each cell has a short, scannable value. Don't put paragraphs of prose in table cells. * The comparison is the point, not the individual items. Examples of when to use tables: * Feature comparison by plan tier * Supported SDK languages by feature * API parameters with name, type, default, and description columns * Operating system requirements ```mdx Environment requirements table theme={null} | Environment | Minimum version | Notes | |-------------|----------------|-------| | Node.js | 18.0 | LTS recommended | | Python | 3.9 | | | Ruby | 3.1 | | | Go | 1.21 | | ``` ## When are tables the wrong choice? Trying to force non-tabular information into a table is the most common problem. There must be a relationship between the table rows, headers, and cells. If there isn't, don't use a table. Uneven cell content can be difficult to read. If some cells are two words and others are two paragraphs, the table stops being scannable. Pull the long content into a separate section and use the table for the short summary. Tables with more than five or six columns start to break on mobile screens. Consider whether some columns could be collapsed, removed, or moved to a detail section. Tables aren't good for narrative content. If you expect someone to read every word in a table in a particular order, it isn't actually a table. Similarly, don't try to put complex conditional logic in a table cell. If your table cell says "See note 3 below," reconsider how you're structuring the information. If cells need bullet lists, code blocks, or multiple paragraphs, use a different structure. ## Alternatives to tables When a table is almost right but doesn't quite fit, consider these alternatives: * Two or three items with many attributes: consider cards organized with ``. * Many items, few attributes: a bulleted list may be simpler. * Comparison where one option is clearly recommended: state the recommendation in prose and use a table only to show the key differences. Quiz You're documenting three authentication methods. Each requires a four-step setup process, has a different security model, and suits different use cases. Should this be a table? Next up: [Columns and cards for visual comparisons](/courses/components/columns-and-cards)—when you need layout flexibility that tables don't provide. # Tabs and code groups Source: https://learn.mintlify.com/courses/components/tabs Use code groups when only the code changes between versions, and tabs when instructions or explanations change too. Tabs and code groups both let readers switch between versions of the same content. They work best when readers arrive knowing which version they need: their programming language, package manager, operating system, or role. The difference is what changes: * **Code groups** are for code. Use them when the explanation is the same for everyone and only the code changes, like the same API call in Python, JavaScript, and cURL. * **Tabs** are for everything else. Use them when the instructions, explanation, or mix of content changes, like setup steps that differ on macOS and Windows. ## Code groups: same explanation, different code Wrap two or more code blocks in ``. Each block needs a title, which becomes its label in the group. ````mdx Example of a code group theme={null} Install the SDK with your package manager. ```bash npm npm install @acme/sdk ``` ```bash yarn yarn add @acme/sdk ``` ```bash pnpm pnpm add @acme/sdk ``` ```` ```bash npm theme={null} npm install @acme/sdk ``` ```bash yarn theme={null} yarn add @acme/sdk ``` ```bash pnpm theme={null} pnpm add @acme/sdk ``` The sentence above the group applies to everyone, so it's written once. Readers pick their package manager and copy one command. The same pattern works for SDK examples: ```python Python theme={null} client = acme.Client(api_key="YOUR_API_KEY") user = client.users.create( name="Ada Lovelace", email="ada@example.com" ) ``` ```javascript JavaScript theme={null} const client = new Acme({ apiKey: "YOUR_API_KEY" }); const user = await client.users.create({ name: "Ada Lovelace", email: "ada@example.com", }); ``` ```bash cURL theme={null} curl -X POST https://api.example.com/v1/users \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{"name": "Ada Lovelace", "email": "ada@example.com"}' ``` For many languages, add the `dropdown` prop to `` to show a menu instead of a crowded row of labels. ## Tabs: when more than the code changes Use tabs when a section of the page changes based on the reader's context, and the change includes instructions or explanation, not just code. ````mdx Example of tabs theme={null} Install the CLI with Homebrew: ```bash brew install acme-cli ``` If macOS blocks the binary, open **System Settings** > **Privacy & Security** and click **Allow Anyway**. Install the CLI with winget: ```powershell winget install Acme.CLI ``` Restart your terminal so the `acme` command is on your `PATH`. ```` Each tab carries its own instructions, so a code group wouldn't be enough. Tabs also work well for: * Authentication methods chosen earlier in a setup flow * A short section that differs for administrators and members * A procedure step that differs by platform The difference should stay local. If most of the page changes, use [views](/courses/components/conditional-content) or separate pages instead. ## Keep choices in sync Tabs and code groups on the same page sync by label. If a reader selects `Python` in one, every other tab group or code group with a `Python` label switches too, so they only choose once. Labels must match exactly. `Python`, `python`, and `Python 3` are three different choices. For code groups, the label is the code block's title, so a block titled `create_user.py` won't sync with a tab titled `Python`. If you want syncing, title your code blocks by language. ````mdx Tab groups that sync theme={null} ... ... ```python Python ... ``` ```javascript JavaScript ... ``` ```` Use the same labels and order throughout the page. If two tab groups share labels but represent unrelated choices, turn off syncing with `sync={false}` on ``. ## When tabs get in the way Don't use tabs or code groups for options readers need to compare. Switching back and forth makes differences harder to see. Use a table, columns, or short sections instead. Don't bury a recommendation in tabs. If one option is right for most readers, recommend it before showing the alternatives. Don't use tabs to make a page look shorter. Required instructions should stay visible, and a procedure with substantially different paths is usually easier to follow as separate guides. Don't repeat a distinction the site navigation already makes. If administrators and members have separate sections, role-based tabs inside those pages are a sign that the content may be in the wrong place. Quiz A page explains how to configure a webhook. The steps and explanation are the same for every language, but you want to show the handler code in Python, Node.js, and Go. What should you use? Next up: [Conditional content](/courses/components/conditional-content)—change a whole page based on the reader's language, or show different content to people and AI agents. # Images, frames, and diagrams Source: https://learn.mintlify.com/courses/components/visual-content Choose visuals that clarify a task, then make them accessible and easy to maintain. Adding a screenshot can feel like the quickest way to make a page more helpful. Sometimes it is. Other times, the screenshot repeats the instructions, goes stale after the next product update, and makes the important part harder to find. Start with the question the visual needs to answer. If there isn't one, you probably don't need the visual. ## Use screenshots to show location or state A screenshot is useful when readers need to recognize something they can see: * Where a setting lives in a crowded interface * Which status confirms that a deployment worked * What a correctly configured screen looks like Crop to the part that matters. A full-screen capture with one tiny button circled in red makes readers search the image before they can continue. Skip the screenshot when the interface is simple enough to describe in a sentence, such as "Select **Settings**, then **API keys**." Text is faster to scan, easier to update, and searchable. ## Use frames to give visuals context `` separates an image or video from the surrounding page and can add a caption: ```mdx Example of a framed image theme={null} GitHub App settings showing the documentation repository as connected ``` The alt text and caption have different jobs. Alt text conveys what a reader needs from the image. The caption explains why the image is here or points out something worth noticing. Repeating the same sentence in both doesn't help. "Screenshot of dashboard" is weak alt text because it leaves out the useful part. "Deployment dashboard showing a successful production build" tells the reader which state the image demonstrates. Use `alt=""` for a purely decorative image. For an instructional image, describe the information, not every color, border, and menu visible on the screen. Readers can click images to zoom in by default. Add `noZoom` to an image when zooming doesn't help, like a small icon or a logo that links somewhere. ## Use diagrams to explain relationships When the hard part is understanding how several things connect, a diagram is usually more helpful than a screenshot. Request flows, system boundaries, state changes, and branching processes are good candidates. Mintlify renders Mermaid diagrams from a text definition, so you can review changes to the diagram alongside the rest of your content: ````mdx Example of a Mermaid diagram theme={null} ```mermaid flowchart LR Edit[Edit a page] --> PR[Open a pull request] PR --> Preview[Review the preview] Preview --> Merge[Merge to main] Merge --> Live[Publish the live site] ``` ```` This diagram is useful because the order and relationship between stages are the point. A screenshot of GitHub would show the interface, but not the workflow as clearly. Introduce a diagram in the text and summarize its takeaway. That context helps everyone, including readers who use a screen reader or can't comfortably inspect a large diagram. Mintlify adds zoom and pan controls to larger diagrams, but a diagram that needs them may be trying to show too much at once. ## Plan for the next product update Before publishing a visual, ask what will make it stale. Screenshots often contain button labels, navigation, account data, dates, and feature states that change independently of the instructions. Remove personal or internal information, and keep the source file for diagrams your team may need to update. During product reviews, check the visuals on every affected page, not only the prose around them. If your site supports light and dark mode, a screenshot taken in one mode can look out of place in the other. Take a screenshot in each mode and show the right one with the `dark:hidden` and `hidden dark:block` classes: ```mdx Example of light and dark mode screenshots theme={null} API keys settings page API keys settings page ``` Quiz You need to explain how a request passes through an API gateway, an authentication service, and your application. Readers also need to understand what happens when authentication fails. What should you use? Next up: [Cards and links for navigation](/courses/components/cards-navigation)—use visual weight to guide readers to another page. # Access and permissions Source: https://learn.mintlify.com/courses/git-github/access-and-permissions Identify the GitHub or Mintlify permission someone needs to do their work. When you deploy documentation on Mintlify from a GitHub repository, access is split between two systems. GitHub controls who can change the repository. Mintlify controls what someone can do in the dashboard and editor. When someone gets stuck, the first question is which system is blocking them. ## GitHub controls the repository For most documentation teams, you only need to know these GitHub repository permissions: * **Read**: View and clone a repository. A contributor with read access can also propose changes through a fork if the organization allows that workflow. * **Write**: Push branches to the repository, open pull requests from those branches, review changes, and merge when branch rules allow it. This is the usual role for regular internal contributors. * **Admin**: Manage repository access, settings, and branch protection. Reserve it for people responsible for the repository itself. GitHub also offers Triage and Maintain permissions. They can be useful for teams with more specialized responsibilities, but they aren't relevant to the everyday branch workflow. Organization repositories often grant access through teams. If a contributor can clone the repository but can't push a branch, ask a repository or organization administrator whether they should receive write access or use a fork-based workflow. ## Mintlify controls the dashboard and editor Mintlify uses viewer, editor, and admin roles. * **Viewer**: View content, the dashboard, and analytics. In the editor, viewers can leave comments and suggest changes, but can't edit or publish. * **Editor**: Create and edit pages, update navigation, publish changes, and trigger deployments. * **Admin**: Everything an editor can do, plus manage roles, billing, SSO, the custom domain, and the Git source. Most people on your team need an editor role. Limit admin roles to the people who handle account-level settings. If your organization doesn't use role-based access control, every member has full access and new members join as editors. See [Roles](https://mintlify.com/docs/dashboard/roles) for the full list of permissions. ## Repository access can bypass dashboard roles The two systems don't check each other. Anyone with write access to the repository can push to the deployment branch, and that push deploys, whatever their Mintlify role. A viewer in Mintlify with write access in GitHub can still publish. If publishing should require review, enforce it in GitHub with branch protection on the deployment branch. Mintlify roles only control what people can do in the dashboard and editor. ## The GitHub App has separate access The Mintlify GitHub App acts with the permissions approved during installation. Someone on your team can have the correct GitHub and Mintlify roles while deployments still fail because the app no longer has access to the repository. Check the app connection when any of the following occur: * New commits on the deployment branch don't trigger builds * Pull requests stop receiving preview deployments * The repository was renamed, transferred, or replaced * An organization administrator recently changed GitHub App access If deployments stop, first confirm the commit actually reached the deployment branch and check the latest deployment's status in the dashboard. If both look fine, check the app. Open your GitHub organization's **Settings** > **GitHub Apps**, select the Mintlify app, and confirm the documentation repository is in its list. Then confirm the repository and deployment branch in Mintlify's **Git Settings**. Quiz Your team wants every change to the docs reviewed before it goes live. A contractor has the Mintlify viewer role and GitHub write access. Can they publish without review? Next up: [Set up your local environment](/courses/git-github/local-setup)—clone the repository and run a local documentation preview. # Best practices for branches Source: https://learn.mintlify.com/courses/git-github/branches Scope and name branches so teammates can understand, review, and merge them. A useful branch represents one reviewable outcome. Someone looking at its name and pull request should be able to answer, "What will this change accomplish?" Your team's workflow determines when a branch is required. Repositories with protected deployment branches require pull requests; teams with a direct-publishing workflow may handle small fixes differently. ## Give the branch one job Good branch scopes include: * Add an authentication quickstart * Correct the webhook examples * Reorganize the API navigation Avoid mixing unrelated cleanup into the same branch. If you notice a typo while restructuring the API navigation, record it for a separate fix unless it must change for the restructuring to work. Focused branches produce focused pull requests. They're easier to describe, review, revise, and revert if something goes wrong. ## Name it for the outcome Use a short, specific name with lowercase letters and hyphens: * `add-auth-quickstart` * `fix-webhook-examples` * `reorganize-api-navigation` Names such as `updates`, `ethan-edits`, and `docs-fixes` don't tell a teammate what is in the branch. Two to five meaningful words is often enough, but clarity matters more than a fixed length. Follow an existing team convention if the repository uses issue numbers or prefixes such as `docs/`. In the web editor, you give a branch a title instead, like "Add authentication quickstart." The same advice applies: describe the outcome. If you leave the title blank, the editor names the branch after the date, which tells your teammates nothing. You can rename the branch later, but that only changes the title shown in the editor and on the pull request, not the underlying Git branch name. ## Start from the current deployment branch Before creating a local branch, update the branch your site deploys from, as shown in the [workflow lesson](/courses/git-github/workflow#work-locally). Starting from a current base reduces the chance that your pull request includes old changes or runs into avoidable conflicts. In the web editor, switch to the deployment branch before creating the new branch. ## Keep the branch understandable Commit coherent checkpoints and push the branch when you want to share or back up the work. If the branch's purpose grows from "fix one example" into "rewrite the entire API section," stop and decide whether the new work deserves another branch. Long-running work isn't automatically wrong. A migration or product launch may take time. Keep it manageable by merging independent groundwork separately and syncing the remaining branch with the deployment branch when needed. ## Merge and clean up Before merging, confirm that: * The pull request still matches the branch's stated purpose * The preview renders the intended pages and navigation * Required reviews and configured checks have passed * No unrelated files slipped into the diff After merging, delete the feature branch unless your team has a reason to keep it. Deleting a merged branch doesn't remove the merged work or its commit history. It does remove the branch's preview deployment the next time Mintlify syncs. Be careful deleting a branch that isn't merged. In the web editor, deleting a branch closes its pull request and permanently removes the branch along with any unpublished changes. Quiz While adding an authentication guide, you notice that several unrelated API pages need link cleanup. What should you do? Next up: [Preview deployments](/courses/git-github/mintlify-previews)—review the rendered result, not just the changed lines. # Collaborating with your team Source: https://learn.mintlify.com/courses/git-github/collaborating-with-your-team Get useful pull request reviews, coordinate overlapping work, and resolve conflicts safely. Git gives everyone a place to work. It doesn't decide who should review a change, whether two projects overlap, or what the final wording should be. Those parts still need a team. ## Make the pull request easy to review A useful pull request tells reviewers: * What changed * Why it changed * Which pages or flows deserve close attention * What is deliberately outside the scope The diff should support that story. Separate unrelated work, remove temporary files, and explain changes that aren't obvious from the rendered page. Ask people for the feedback they are equipped to give. An engineer may verify technical behavior, a writer may focus on clarity and structure, and a product manager may confirm scope or terminology. For a small correction, one reviewer may cover everything. When a docs change goes with a product change, link the two pull requests so reviewers can check the docs against what actually shipped. ## Review in the web editor Not everyone on your team needs to use GitHub. In the web editor, teammates can: * **Comment** on specific text or a whole page. Every role can comment, including viewers. * **Suggest** changes that an editor or admin accepts or rejects. Viewers are always in suggesting mode. * **Edit together** on the same branch in real time, in visual or source mode. Changes merge automatically as you type, with no conflicts to resolve. Comments stay in the editor and never reach your repository. If the branch has an open pull request on GitHub, Mintlify adds a summary of unresolved comment threads to the pull request description, so reviewers on both sides see the same open questions. ## Coordinate before branches overlap Two branches can change the same files without causing a conflict. A conflict occurs only when Git can't combine overlapping edits automatically. Still, Git resolving the files doesn't guarantee that the combined writing makes sense. Two writers can add contradictory explanations in different paragraphs and produce a clean merge. Tell teammates when you're changing a shared page or navigation group, and review the combined result after syncing. Keep branches focused and start them from a current deployment branch. For longer work, agree on checkpoints where you'll bring in the latest changes, rather than doing it on an arbitrary schedule. If someone pushes to the repository while you have a page open in the web editor, the editor merges their changes into your page and tells you. When both of you changed the same part of the page, it keeps both versions and highlights them so you can choose. ## Resolve a merge conflict locally Before bringing `main` into your feature branch, confirm where you are and that your own work is committed or safely set aside: ```bash theme={null} git status git branch --show-current git fetch origin git merge origin/main ``` Replace `main` if your site uses another deployment branch. If Git finds a conflict, it marks the affected section: ```text theme={null} <<<<<<< HEAD This is the text on your feature branch. ======= This is the text from the deployment branch. >>>>>>> origin/main ``` Edit the section into the final version you want and remove all three marker lines. Then preview the page and finish the merge: ```bash theme={null} git add guides/resolved-page.mdx git commit -m "Merge main into feature branch" git push ``` Don't choose a side based only on which version is newer. Read the surrounding page and preserve the intent of both changes when appropriate. ## Use branch protection as a team rule Branch protection can require pull requests, approvals, or passing checks before changes reach the deployment branch. Configure the rules around the risks your team wants to manage. Mintlify follows those rules. When the deployment branch is protected, the web editor won't publish to it directly. It offers **Create branch** instead, so every change goes through a pull request. If your repository requires pull requests, use the same path for urgent fixes but keep the review focused and quick. If it permits direct publishing, decide as a team which changes still deserve a branch and preview. ## Protect work before trying to undo it Start with `git status` and `git diff`. These commands inspect the working copy without changing it. If you need to switch tasks, commit a sensible checkpoint or stash the work temporarily: ```bash theme={null} git stash push -u -m "Work in progress on authentication guide" ``` Return to the branch later and run `git stash pop`. Review the result because applying a stash can also produce conflicts. `git restore path/to/file.mdx` discards uncommitted changes to that file. Use it only when you have inspected the diff and are certain those edits are unwanted. It isn't a recovery command. If a mistake is already in shared history, prefer a new commit that corrects or reverts it. Avoid rewriting a branch other people may be using unless your team has agreed to it. Quiz Git merges two writers' branches without reporting a conflict. Do you still need to review the combined page? That's the end of the Git and GitHub for Mintlify course. You can now connect the repository, make a focused change, review the rendered result, and recover when work overlaps. Next, [Structure docs that scale](/courses/structure-docs/overview) covers how to organize that content as the documentation grows. # Core Git concepts Source: https://learn.mintlify.com/courses/git-github/concepts-you-need Learn the small set of Git concepts behind the everyday documentation workflow. You don't need to master Git before editing documentation. Start with six ideas: repository, branch, working copy, commit, pull request, and merge. ## Repository A repository, usually shortened to "repo," contains your documentation files and the history your team has committed. Mintlify builds your site from a configured branch in that repository. Teams often use `main`, but the deployment branch can have another name. ## Branch and working copy A branch is a line of work with its own version of the repository. A feature branch lets you prepare a change without updating the deployment branch. Your working copy is the repository on your computer. Edits in your working copy aren't part of Git's history yet. You can inspect them, preview them, and decide what belongs in the next commit. This distinction helps when Git reports a "modified" or "untracked" file: the file exists in your working copy, but you haven't committed its current state. ## Commit A commit saves a selected set of changes to the branch's history. Its message should say what the change accomplishes, such as `Add authentication quickstart` or `Fix broken API reference link`. Before committing, review the affected files with `git status` and the exact edits with `git diff`. Then stage only the files that belong together: ```bash theme={null} git status git diff git add guides/authentication.mdx git commit -m "Clarify authentication setup" ``` A commit is more useful when it represents one coherent change. It doesn't need to capture every edit you made during a work session. ## Pull request A pull request, or PR, asks to merge one branch into another. It gives reviewers a focused diff and a place to discuss the change. For a repository connected to Mintlify, a PR can also get a preview deployment, a temporary copy of your site with the changes applied. Your team may also turn on checks for broken links or writing style. Approval requirements depend on the repository's branch protection rules. Some teams require reviews; others allow the author to merge after checking the preview. ## Merge Merging applies the accepted changes to the target branch. When that target is your Mintlify deployment branch, the merge triggers a new deployment. After the work is merged, the feature branch can usually be deleted. Its commits remain in the repository's history. You don't need to memorize commands yet. The [workflow lesson](/courses/git-github/workflow) puts them in order and explains when to use each one. If you use the web editor, it runs these steps for you. Quiz You edited two files and committed them on a feature branch on your computer. Your teammate says they can't see your branch on GitHub. Why not? Next up: [Get connected](/courses/git-github/get-connected)—connect a documentation repository so Mintlify can deploy it. # Get connected Source: https://learn.mintlify.com/courses/git-github/get-connected Connect a GitHub repository so Mintlify can build and deploy your documentation. Mintlify needs two things from GitHub: a repository containing your documentation and permission to read and deploy it. The Mintlify GitHub App provides that connection. If your team uses GitLab or Bitbucket, see [GitLab](https://mintlify.com/docs/deploy/gitlab) or [Bitbucket](https://mintlify.com/docs/deploy/bitbucket) for the equivalent setup. The rest of this course still applies. By the end of this lesson, your site will be live and Mintlify will redeploy it whenever a change reaches your deployment branch. ## Start with a repository Go to [mintlify.com/start](https://mintlify.com/start) and follow the onboarding flow. You can connect your GitHub account and choose a repository, or skip that step to get started faster. If you skip it, Mintlify creates a private repository for you in its own GitHub organization. You can use the web editor right away, but you can't clone that repository or work locally until you copy it to your own account. Use the [one-click clone](https://mintlify.com/docs/deploy/github#clone-to-your-own-repository) in **Git Settings** when you're ready. If you connect an existing repository, make sure it contains—or will contain—your Mintlify project. At minimum, the project needs a `docs.json` configuration file and a page included in its navigation. The GitHub account completing this setup must be allowed to install or request the Mintlify GitHub App for the repository. In an organization, an owner may need to approve the installation. ## Choose the repository Mintlify can access During installation, GitHub asks which repositories the Mintlify app can access. Choose **Only select repositories** and select your documentation repository. You can update that selection later in the GitHub App settings if the repository changes. Mintlify uses the connection to: * Read the documentation source * Deploy changes pushed to the configured deployment branch * Create preview deployments for pull requests * Create branches and pull requests from the web editor * Report configured checks in GitHub Granting access only to the repositories Mintlify needs follows the principle of least privilege: if something goes wrong, the app can't touch anything else. ## Confirm the source and deployment In your Mintlify dashboard, open **Git Settings** and confirm the organization, repository, and deployment branch. The deployment branch is often `main`, but use whatever branch your team has configured. After the first successful build, open the site URL from the dashboard. To confirm the connection works end to end, make a small change, like fixing a typo, and merge it to your deployment branch. A new deployment should appear in the dashboard within a minute or two. If it doesn't, the next lesson covers what to check. You can find the full installation and permission details in the [GitHub deployment guide](https://mintlify.com/docs/deploy/github). Quiz You skipped connecting GitHub during onboarding and have been editing in the web editor. Now a teammate wants to clone the repository and work locally. What do they need to do first? Next up: [Access and permissions](/courses/git-github/access-and-permissions)—identify whether a GitHub or Mintlify role is blocking the work. # Set up your local environment Source: https://learn.mintlify.com/courses/git-github/local-setup Install the tools you need, clone your documentation repository, and run your first local preview. The web editor lets you work without installing anything. If you prefer your own editor or want to test changes locally, you'll need Git, Node.js, the Mintlify CLI, and a local copy of the repository. By the end of this lesson, you'll have your docs running at `localhost:3000`. ## Before you begin Make sure you have: * Access to your documentation repository on GitHub. If Mintlify created the repository for you during onboarding, [clone it to your own account](/courses/git-github/get-connected#start-with-a-repository) first. * Git installed on your computer * Node.js v20.17.0 or later * A terminal and a code editor You can confirm that Git and Node.js are available by running: ```bash Check your installed versions theme={null} git --version node --version ``` If either command fails, or Node.js is older than v20.17.0, install or update that tool before continuing. See the [Mintlify CLI installation guide](https://mintlify.com/docs/cli/install) for details. ## Clone your repository Cloning downloads the repository and connects your local copy to GitHub. On your repository's GitHub page, select **Code** and copy the HTTPS URL. Then run: ```bash theme={null} git clone https://github.com/your-org/your-docs.git cd your-docs ``` Replace the example URL and directory with your own. Run `ls` to check that you're in the right place. You should see `docs.json` and your documentation files. > [!NOTE] > > If GitHub asks you to authenticate, follow its prompt. Depending on your organization, you may use a browser sign-in, a personal access token, or SSH. ## Install the Mintlify CLI Install the CLI globally so the `mint` command is available from any documentation project: ```bash theme={null} npm i -g mint ``` Then confirm the installation: ```bash theme={null} mint --version ``` You can also run the CLI without a global installation by using `npx mint` in place of `mint`. ## Start a local preview From the directory that contains `docs.json`, run: ```bash theme={null} mint dev ``` The preview opens in your browser at `http://localhost:3000`. Leave the command running while you work. When you save a file, the preview reloads with your changes. > [!TIP] > > If you use VS Code or Cursor, the [Mintlify MDX extension](https://mintlify.com/docs/cli/mdx-extension) can show the preview in a panel beside your editor. If port 3000 is already in use, the CLI chooses another available port and prints its address in the terminal. ## Make a test edit Open an MDX page and change a sentence. Save the file, then check the local preview. Before committing anything, inspect what changed: ```bash theme={null} git status git diff ``` `git status` lists changed and untracked files. `git diff` shows the exact line-by-line edits that you haven't staged yet. Together, they help you catch an accidental change before it reaches a commit. You can now restore the sentence or keep it for the workflow lesson. ## Common setup problems **`mint: command not found`** Restart your terminal after installing the CLI. If the command still isn't available, use `npx mint dev` or check where npm installs global packages. **The preview shows a site you don't recognize, or a new `docs.json` appears** If you run `mint dev` in a directory without a `docs.json` file, the CLI generates one from the folder structure. Stop the preview, delete the generated file if you don't want it, and run `pwd` and `ls` to find the directory that contains your real `docs.json`. **The local preview looks different from your live site** Run `mint update` to get the latest version of the CLI, then restart the preview. **GitHub rejects your clone or push** Confirm that you have access to the repository and that GitHub authentication is working. If you can clone but can't push, you may have read access instead of write access. Quiz You cloned your docs repository into a folder called company-site. The docs live in a docs subfolder that contains docs.json. Where should you run mint dev? Next up: [Workflow overview](/courses/git-github/workflow)—turn your local edit into a branch, commit, pull request, preview, and published update. # Preview deployments Source: https://learn.mintlify.com/courses/git-github/mintlify-previews Use a rendered preview to review changes that a Git diff cannot show. [Preview deployments](https://www.youtube.com/embed/GYzXpmN_--8) A Git diff shows which lines changed. A preview shows what those changes do to the documentation site. When the Mintlify GitHub App has access to your repository, pull requests to your deployment branch get a preview deployment: a temporary copy of your site with the changes applied. New commits update the preview, so reviewers can follow the same link throughout the pull request. ## Find the preview Open the pull request and look for the Mintlify bot's comment with the preview link. The deployment may still be building when the pull request first opens, so check its status if the link isn't ready yet. If no preview appears: 1. Confirm that the pull request targets the configured deployment branch. 2. If the pull request comes from a fork, look for a **Mintlify Preview (fork)** check that says **Action required**. Fork previews need approval before they build, because they run the contributor's code. 3. Check that the Mintlify GitHub App can access the repository. 4. Open the **Previews** page in your Mintlify dashboard to see the build status. You can also create a preview for any branch, with or without a pull request, from the **Previews** page. ## Review what readers will experience Start with every page changed by the pull request. The preview widget, a floating button in the bottom-right corner of the preview, lists every added, modified, and removed page and links straight to each one. For each page, check: * The page renders without broken MDX or missing media * The edited section makes sense with the paragraphs around it * Links and interactive components behave as expected * Headings and the table of contents describe the page clearly Then check the effects beyond those pages. A small `docs.json` edit can move several pages, change a label, or remove something from navigation. Follow the relevant path through the sidebar instead of checking only the URL you were given. For layout-heavy changes, resize the browser or check a mobile viewport. You don't need to test every screen size on every copy edit; focus the review on what the change could plausibly affect. ## Give reviewers a specific task Share the preview with a short review request. For example: > Please check the new authentication flow from **Create a token** through **Test the request**. In particular, does the choice between service and user tokens make sense before step one? That is more useful than "Thoughts?" Reviewers know where to start and what kind of feedback you need. Preview URLs are publicly accessible by default, even though they show unpublished content. Some organizations require a Mintlify login to view previews. If yours does and you need a review from someone outside your organization, you can password-protect an individual preview and share the password with them instead. ## Treat the preview and diff as a pair The preview shows what readers will see. It won't show things that never render, like a comment in the MDX source, a leftover debug note in a snippet that no page uses, or an API key pasted into a file. Review the Git diff for source changes and the preview for the reader experience. Quiz A pull request changes one page and reorganizes its navigation group. What should you inspect in the preview? Next up: [Collaborating with your team](/courses/git-github/collaborating-with-your-team)—make reviews useful and handle overlapping work without losing changes. # Git and GitHub for Mintlify Source: https://learn.mintlify.com/courses/git-github/overview Learn how to use Git and GitHub to write, review, and publish documentation with Mintlify. Mintlify documentation lives in a Git repository. You can let the web editor handle Git for you, with branches, commits, and pull requests created as you work, or you can work locally in your preferred editor. If Git is new to you, expect a short adjustment period. This course covers only what you need to work on Mintlify docs: the core concepts, everyday tasks, and habits that keep a team moving. You can leave the rest of Git for later. The course starts with the few Git ideas you need, then walks through setup, publishing, review, and team collaboration. ## What you'll learn * Why documentation teams use Git and what problems it solves * Core Git concepts that help you understand Mintlify's docs-as-code workflow * How Mintlify connects to your repository and publishes changes * How to manage branches, use preview deployments, and collaborate with your team ## Who this is for Anyone who contributes to documentation on Mintlify and wants to understand the Git-based workflow. It's especially useful if you're used to tools such as Notion, Confluence, or Google Docs. ## Lessons in this course 1. [Why docs teams use Git](/courses/git-github/why-docs-teams-use-git)—What problems Git solves for documentation teams, and why it's worth learning. 2. [Core Git concepts](/courses/git-github/concepts-you-need)—Concepts and commands that cover nearly everything you'll do with your documentation repository. 3. [Get connected](/courses/git-github/get-connected)—How to create your documentation repository, install the Mintlify GitHub App, and get your site live. 4. [Access and permissions](/courses/git-github/access-and-permissions)—The two permission systems that control who can do what: GitHub for repository access and Mintlify for site configuration. 5. [Set up your local environment](/courses/git-github/local-setup)—Install the tools you need, clone your repository, and run a local preview. 6. [Workflow overview](/courses/git-github/workflow)—The primary Mintlify workflow from making a change to seeing it live, using both the web editor and the CLI. 7. [Best practices for branches](/courses/git-github/branches)—When to create a branch, how to name it, and how to manage it through to a merged change. 8. [Preview deployments](/courses/git-github/mintlify-previews)—How to review the rendered site before merging a pull request. 9. [Collaborating with your team](/courses/git-github/collaborating-with-your-team)—How to work alongside writers, engineers, and product managers without stepping on each other's toes. This course uses GitHub for its examples. Mintlify also supports GitLab and Bitbucket. The Git concepts are the same, though some setup steps and integrations differ. Next up: [Why docs teams use Git](/courses/git-github/why-docs-teams-use-git)—what a Git-based workflow adds to documentation review and publishing. # Why docs teams use Git Source: https://learn.mintlify.com/courses/git-github/why-docs-teams-use-git Understand what a Git-based workflow adds to documentation review and publishing. Git records changes to files. GitHub gives teams a place to share those changes, review them, and decide when to publish them. That may sound like extra machinery if you're used to Google Docs, Notion, or Confluence. Those tools already support collaboration and revision history. Git becomes especially useful when documentation lives beside software, engineers contribute directly, or publishing needs a deliberate review step. ## See what changed Each commit records a set of changes with an author, time, and message. If a guide becomes inaccurate, you can inspect its history to see how it changed and often recover an earlier version. That history is useful only when the team commits its work and writes meaningful messages. Git tracks committed changes; it isn't an automatic record of every keystroke. For a Mintlify site connected to GitHub, the repository is the source that Mintlify builds from. The deployed site reflects the files on the configured deployment branch, which is often `main`. ## Work on changes without publishing them A branch gives you a place to edit files without changing the deployed version. Other contributors can work on their own branches at the same time. When branches change different parts of the repository, Git can usually combine them. When two branches change the same lines, Git stops and asks a person to decide what the final version should say. The conflict is visible instead of being silently resolved in favor of one writer. ## Review the rendered result before it goes live A pull request shows the difference between a branch and the deployment branch. Reviewers can comment on specific lines, suggest edits, and check the rendered preview before merging. This is the main benefit of the workflow: writing, review, and publishing are separate decisions. A team can keep lightweight rules for small fixes and require more review for a new API guide or a navigation redesign. You don't need to adopt Git because engineers use it. Adopt it when history, branches, and review solve a collaboration problem your team actually has. For most teams that publish docs alongside a product, they do. Next up: [Core Git concepts](/courses/git-github/concepts-you-need)—the terms you'll see while making and reviewing documentation changes. # Workflow overview Source: https://learn.mintlify.com/courses/git-github/workflow Follow a documentation change from a fresh branch through review and deployment. [Workflow overview](https://www.youtube.com/embed/WrK6AX8gcrQ) The web editor and a local editor lead to the same place: a branch with a focused change, a pull request for review, and a merge into your deployment branch. This lesson follows that review-based workflow. If your deployment branch isn't protected, you can also publish straight from it, so match the steps to your team's branch rules. ## Work in the web editor The editor handles the Git steps for you: it creates the branch, commits as you type, and opens the pull request. **1. Create a branch** Click the branch name in the editor toolbar. Your deployment branch has a **Live** badge. Type a title that describes the change, such as "Update authentication guide," then click **New branch**. If you don't see a branch name in the toolbar, open **More options** in the top bar and turn on **Branches**. **2. Make your changes** Edit pages in visual mode, or switch to source mode to edit the MDX directly. The editor commits your work to the branch automatically, about 15 seconds after you stop typing. The first commit opens a pull request, as a draft if your team has that setting on. Before you ask for review, look over the changed files in the pull request for anything you didn't mean to change. **3. Request review** Click **Publish**, then **Request review**. This marks the pull request ready for review. Make sure its description explains what changed and why, so reviewers know where to focus. **4. Merge and publish** Check the preview deployment and get any review your team requires. When the pull request is approved, click **Publish**, then **Merge and publish**. The editor merges the pull request, deploys your change, and switches you back to the deployment branch. > [!NOTE] > > If you don't see a **Publish** button, your project has **auto publish** turned on. Edits commit straight to the deployment branch shortly after you stop typing, with no review step. ## Work locally **1. Update the deployment branch** Switch to the branch your site deploys from, then update it. This example uses `main`: ```bash theme={null} git switch main git pull --ff-only ``` Starting from an up-to-date deployment branch means your new branch includes your teammates' latest work, which avoids conflicts later. **2. Create a feature branch** Create the branch from the updated deployment branch: ```bash theme={null} git switch -c update-auth-guide ``` **3. Preview and edit** From the directory containing `docs.json`, start the local preview: ```bash theme={null} mint dev ``` Edit your MDX files and check the rendered result as you work. **4. Review the change** Inspect both the affected files and their exact edits: ```bash theme={null} git status git diff ``` Look for temporary notes, secrets, generated files, and unrelated edits before staging anything. Then check for problems the preview might not show: ```bash theme={null} mint broken-links mint validate ``` `mint broken-links` finds internal links that point nowhere. `mint validate` checks that the site builds. **5. Commit the files that belong together** Stage the files you reviewed, then commit them: ```bash theme={null} git add guides/authentication.mdx git commit -m "Clarify authentication setup" ``` Add more paths when they belong to the same change. Avoid staging the whole repository by habit. **6. Push and open a pull request** Push the new branch and set its upstream connection: ```bash theme={null} git push -u origin update-auth-guide ``` Follow GitHub's link or open the repository to create a pull request. Explain the purpose of the change and point reviewers to anything that needs special attention. **7. Check the preview and merge** Open the Mintlify preview from the pull request. After the change passes your team's review and checks, merge it into the deployment branch. ## Respond to review feedback Keep using the same branch and pull request. Make the requested edit, review it, and push another commit: ```bash theme={null} git add guides/authentication.mdx git commit -m "Clarify authentication prerequisites" git push ``` GitHub adds the commit to the open pull request, and Mintlify updates its preview. You don't need to start the workflow again. Your team may also have Mintlify's CI checks turned on, which check every pull request for broken links or writing style. Treat them as a safety net, not a replacement for reading the changed page. Quiz You've been editing on a branch in the Mintlify web editor and are ready for team review. What should you do? Next up: [Best practices for branches](/courses/git-github/branches)—keep each branch focused enough to review and merge confidently. # Choose the right content type Source: https://learn.mintlify.com/courses/structure-docs/content-types Give every page one job. Mixing tutorials, how-to guides, reference, and explanation on one page makes documentation hard to use and hard to navigate. A page that tries to teach a concept while also explaining how to complete a task and listing configuration options is harder to understand than three separate pages that each serve a single purpose. Users who want to do the task have to wade through the explanation. Users who need the configuration details have to read through the steps. Nobody gets what they came for quickly. Choosing the content type before you write prevents this. It also gives AI writing tools a clear target. ## Four content types The [Diátaxis framework](https://diataxis.fr) defines four types of documentation based on what the reader needs: | Type | Reader's goal | Examples | | - | - | - | | **Tutorial** | Learn by doing | "Build your first integration" | | **How-to guide** | Complete a specific task | "Set up webhooks" | | **Reference** | Look up specific information | API endpoint parameters | | **Explanation** | Understand a concept | "How our authentication model works" | Use these categories as strictly or loosely as your team needs. What matters is that you can say what each page helps its reader accomplish. ## Why mixing types causes problems Each content type has a different structure, a different level of assumed knowledge, and a different relationship to other pages. Tutorials are sequential and assume nothing. How-to guides assume the reader knows what they're doing and just need the steps. Reference material is scannable, not readable. Explanations are the only type where depth and context are the point. When you mix them, the page stops matching what the reader came for. Someone who came to do something ends up reading an essay. Someone who came to understand something gets a list of parameters. Mixed pages also cause navigation problems. They're hard to place in a hierarchy because they don't clearly belong anywhere. ## The AI problem with content types AI writing tools don't default to any particular content type. Given a prompt like "write documentation for our webhook feature," most AI tools will produce a hybrid: some explanation, some steps, some reference material, blended together. It reads fine, but it serves no reader particularly well and creates navigation headaches down the line. The fix is to be explicit. AI tools respond well to content type instructions: > "Write a how-to guide for setting up webhooks. Assume the reader already knows what webhooks are and has already authenticated. Focus only on the steps. No background explanation." That prompt gives the tool a type, a reader, and a boundary, so the draft has one job. ### Make content types a standing instruction Instead of repeating content type rules in every prompt, add them to the same places as your [reader definition](/courses/structure-docs/understand-your-readers#use-your-audience-as-ai-context): `.mintlify/AGENTS.md` for Mintlify's agent, AI instructions for the editor's agent, and the instruction files your local tools read. ```markdown .mintlify/AGENTS.md theme={null} ## Content types Every page is one of four types: tutorial, how-to, reference, or explanation. - **Tutorials**: Sequential, assumes no prior knowledge, focused on learning by doing - **How-to guides**: Goal-driven, assumes prior knowledge, focused on completing a task - **Reference**: Scannable and complete, no explanatory prose - **Explanations**: Conceptual, provides background and context, not task-oriented Identify the content type before writing or editing any page. Do not mix types on a single page. If a how-to guide needs to explain a concept, link to an explanation page instead of including the explanation inline. ``` With this in place, AI tools ask "which type is this page?" before they draft, and you can point to the rule when a draft drifts. ## Categorize what you already have If you're working with an existing Mintlify site, start with an audit. Go through your highest-traffic pages and assign each one a content type. You'll likely find: * Pages doing multiple jobs that need to be split * How-to guides buried inside reference pages * Tutorials that assume too much prior knowledge * Explanations that never get read because they're positioned as onboarding content Don't try to fix everything at once. Start with the pages that get the most traffic and generate the most support questions—these have the most impact when improved. Keep the list. You'll use it when you design navigation in a later lesson. Quiz You're reviewing a page called 'Webhooks.' It opens with two paragraphs on why webhooks beat polling, then walks through registering an endpoint, then lists every event type and its payload fields. What should you do? Next up: [Structure individual pages for scanning](/courses/structure-docs/page-structure)—turn a page goal into clear prerequisites, headings, examples, and verification. # Keep docs accurate as your product grows Source: https://learn.mintlify.com/courses/structure-docs/keeping-docs-current Documentation goes stale by default. Here's how to keep it close enough to the truth that users can rely on it. [Keep docs accurate as your product grows](https://www.youtube.com/embed/A7j3kLIwJrw) Documentation goes stale by default. Product changes accumulate, screenshots drift, features get renamed, and old workflows stop working. Without deliberate maintenance, the gap between your docs and your product widens until users notice, usually through support tickets. Keeping docs accurate is mostly a process problem, not a writing problem. Mintlify can take on a lot of the mechanical work, like spotting what changed, drafting updates, and catching broken links. That leaves your team to decide what's accurate and what ships. ## Give every section an owner Docs without an owner drift first. When everyone is responsible for a page, nobody notices it's wrong. Assign an owner to each section of your docs, usually the person or team closest to that part of the product. Owners don't write every change. They review changes to their section, answer accuracy questions, and notice when the product moves ahead of the docs. Write the ownership down somewhere your team already looks, like a `CODEOWNERS` file in your docs repository. GitHub then requests a review from the owner automatically when someone changes their pages. ## Ship docs with the product The foundation of maintainable documentation is treating docs the same way you treat code: version-controlled, reviewed, and deployed through a pipeline. If your Mintlify project is connected to a Git repository, documentation changes go through pull requests, and reviewers can check a preview before anything goes live. The key habit to build: **update the docs as part of shipping the feature.** When a feature ships, the docs ship with it. When a feature changes, the docs change in the same release. A separate docs-update process that runs after the fact always falls behind. ## Let Mintlify's agent draft the updates Even with good habits, product changes can outpace the docs team. Mintlify's [agent](https://mintlify.com/docs/agent) can close the gap by drafting updates for you. There are two ways to put it to work. **Autopilot** is the low-setup option. Once you [turn it on](https://mintlify.com/docs/autopilot) and give it access to your code repositories, it watches for merged code changes, opens pull requests with suggested documentation updates, and runs a daily quality check. It decides what to work on, so you don't write prompts or configure triggers. **Automations** give you more control. Each [automation](https://mintlify.com/docs/automations) pairs a prompt with a trigger, like a schedule or a merged pull request. The predefined **Update from code changes** automation reads merged pull requests in your product repositories and opens a pull request in your docs repository for changes that affect users. By default it runs twice a week, and you can switch it to run on every merged pull request instead. Either way, the workflow looks like this: **1. Turn on Autopilot or an automation** Connect the code repositories the agent should watch, then enable Autopilot or the **Update from code changes** automation from your dashboard. **2. Review the pull request** The agent opens a pull request in your docs repository with proposed changes and cites the code changes it used. Review for accuracy, tone, and whether the content type is right for the page being updated. **3. Merge or revise** Merge the changes if they're accurate, or use the draft as a starting point for a more thorough update. This doesn't replace human review. AI-drafted docs need to be checked for accuracy and tone before they ship. But it removes the blank-page problem: instead of starting from scratch after a feature lands, a writer reviews and edits a draft. > [!NOTE] > > Automations open pull requests by default. Some, like **Translate content**, merge directly. Check each automation's update mode so you know which changes get a review. ## Set up automated checks Some problems can be caught before anyone reads the page. Mintlify's [CI checks](https://mintlify.com/docs/deploy/ci) run on every pull request against your deployment branch: * **Broken links** catches internal links that lead nowhere, a common side effect of reorganizing navigation or renaming pages. * **Vale** checks writing style against rules you define. Enforce consistent terminology, flag passive voice, or catch product names written incorrectly. Turn them on in your dashboard settings, and set each one to **Warning** or **Blocking**. Start with warnings, then switch to blocking once your existing pages pass. Predefined maintenance automations cover problems that CI can't block on. **Fix broken links**, **Fix SEO issues** (such as missing titles and descriptions), **Fix grammar & typos**, and **Enforce your style guide** run when content changes and open pull requests with fixes. When pages move, test redirects as part of the change. A navigation update can look correct while old bookmarks and external links still lead to a 404. ## Know when to update, rewrite, or delete Not all maintenance is equal. Most changes need a targeted update: fix the thing that changed and move on. But some pages accumulate so many caveats and workarounds that they become harder to follow than a fresh rewrite would be. A page is a candidate for rewriting when: * It has more warnings, notes, and "as of version X" qualifiers than actual content * The underlying workflow it describes has fundamentally changed * Users are frequently confused by it even after incremental improvements A page is a candidate for deletion when: * It documents a feature or workflow that no longer exists * The information exists in better form elsewhere * It's receiving very low traffic that can't be explained by it being a niche reference Wrong documentation is worse than no documentation. A page that describes a workflow that no longer works costs users more time than a missing page would. If you can't fix it soon, remove it and add a redirect to the closest useful page. You can always bring it back. ## A maintenance rhythm that works The goal isn't perfection. It's documentation readers can trust. A lightweight rhythm helps: * **With every release**: Update docs alongside the feature, and review agent-drafted pull requests * **Monthly**: Review search, feedback, and assistant analytics for gaps * **Quarterly**: Have section owners check their highest-traffic pages for accuracy * **Annually**: Assess whether your overall structure still reflects how users actually use your product Quiz You turn on the Update from code changes automation with its default settings. An engineer merges a pull request that renames an API parameter. What happens? That's the end of this course. You've worked through who you're writing for, how to choose content types and structure pages, how to design and test navigation around user goals, and how to keep it all accurate as your product changes. Ready for more? [Create agent-friendly content](/courses/agent-friendly-content/overview) covers how to make the same docs work for AI tools that read them on your users' behalf. # Measure and improve findability Source: https://learn.mintlify.com/courses/structure-docs/measure-and-improve Use search, analytics, support questions, and task testing to find where your documentation structure fails readers. Documentation structure is a hypothesis. You believe readers will recognize a label, choose a section, and find the page that helps. Seeing what users do on your site tells you whether that hypothesis is right. No single metric captures documentation quality, so combine several signals and look for patterns. ## Start with questions, not page views High traffic can mean a page is valuable, confusing, or simply linked from the product. Low traffic can mean a page is unnecessary—or impossible to find. Begin with questions such as: * Can new users find the quickstart? * Do people search for a term your navigation doesn't use? * Which tasks still generate support tickets after you document them? * Where do readers leave a multi-page procedure? Choose signals that help answer a question rather than collecting numbers without a decision in mind. ## Where to find the signals Mintlify collects most of these signals for you on the [analytics](https://mintlify.com/docs/analytics) page: * **Search** shows what readers search for, which queries return no results, and how often readers click a result. * **Feedback** shows page ratings and written comments from readers, and feedback that AI agents submit. * **User engagements** includes a user flow chart that shows the paths readers take between pages and where they drop off, which answers "where do readers leave a multi-page procedure?" * **Assistant** groups the questions readers ask the AI assistant into categories and topics, with ratings for each answer. The sections below cover what to look for in each. ## Review search behavior Search terms show readers' language and intent. Look for: * Frequent queries with no useful result * Queries that use a different term from your docs * Repeated searches that become more specific * Searches for content that exists but ranks poorly If readers search for "team permissions" while your docs say "workspace roles," add the reader's language to the page's `keywords` frontmatter. Search matches keywords without showing them on the page, so readers find the right page while the product term stays consistent. If the mismatch is common, mention the reader's term in the introduction too. ## Connect support questions to content Tag support tickets by task or topic. When the same question repeats, ask: 1. Is the answer missing? 2. Does it exist under a label readers won't recognize? 3. Is it on the right page but buried in the wrong section? 4. Is the documentation accurate but the product workflow still confusing? Documentation cannot fix every product problem. Treat repeated confusion as evidence, not automatically as a request for more prose. ## Test real tasks Give a colleague who doesn't know the structure a realistic task. Ask them to think aloud while they find the answer using only the site. Watch where they look first, which labels they misunderstand, and when they backtrack. Don't guide them. A five-minute task test often reveals more than a discussion among people who already know where everything lives. You can run a lighter version before you build anything: share only the navigation labels, with no content, and ask where they'd go for each task. Test the highest-value tasks first: * Reach a first successful result * Configure authentication * Recover from a common error * Find a specific reference value ## Use assistant conversations carefully Questions sent to the AI assistant are another source of user intent, often phrased in more detail than a search query. In assistant analytics, filter for topics that come up repeatedly and conversations users rated poorly. When readers ask questions that existing content should answer, the problem is usually structural: the information exists, but readers can't find it or don't recognize it as relevant. An assistant can sometimes compensate for poor navigation, so don't treat a correct answer as proof that the underlying page is easy for humans to find. ## Turn evidence into a small change For each pattern, choose the smallest change likely to help: * Rename a heading or navigation group * Improve a page title or description * Add a missing cross-link * Split a mixed-topic page * Create a new page for a recurring task * Remove outdated content that competes with the right answer Define what you expect to improve, make the change, and check the same signal again. Documentation gets better through small, testable iterations. Mintlify's agent can draft some of these changes for you. The **Fill gaps from assistant conversations** and **Improve docs from user feedback** [automations](https://mintlify.com/docs/automations/reference) review those signals on a schedule and open pull requests with proposed fixes. You still decide which ones to merge. Quiz A troubleshooting page has low traffic, but its topic generates many support tickets. What should you investigate first? Next up: [Keep docs accurate as your product grows](/courses/structure-docs/keeping-docs-current)—build the maintenance rhythm that keeps improvements from drifting out of date. # Design navigation for your users (not your product) Source: https://learn.mintlify.com/courses/structure-docs/navigation-design The most common navigation mistake is organizing around how your product is built rather than what users are trying to accomplish. [Design navigation for your users](https://www.youtube.com/embed/tISBTAlRcRQ) Documentation often mirrors the product: features become sections, and the internal architecture becomes the docs hierarchy. That feels logical because it matches the team's mental model. It rarely works well for users. Users don't navigate docs by feature. They navigate by goal. They arrive asking "how do I do X?" If your navigation requires them to first understand your product's architecture to know where to look, you've already made their job harder. ## Feature-based vs. goal-based navigation Here's a concrete example. A company that builds a data pipeline tool might organize their docs like this: ```text Feature-based navigation theme={null} Sources Destinations Transformations Connectors Settings ``` This mirrors the product's architecture. But a user who wants to "get data from Postgres into our data warehouse" has to infer which sections are relevant before they can even start reading. A goal-based alternative: ```text Goal-based navigation theme={null} Get started Connect your data Transform and model Reference ``` The underlying content is often identical. The organization reflects what users are trying to accomplish, not how the product is built. ## The AI navigation trap AI tools are particularly prone to generating feature-based navigation. Ask an AI to "suggest a navigation structure for our documentation" and it will usually mirror your product, because the most obvious input you give it is a list of features. If you're using AI to help structure your Mintlify docs, be explicit about organizing by user goal: > "Suggest a navigation structure for our documentation organized around what users are trying to accomplish, not our product's feature list. Our users are typically trying to: \[list 3–5 key jobs to be done]." That extra context usually produces a more useful structure. ## Mintlify's navigation primitives Mintlify gives you several ways to organize navigation. Each one fits a different structural need. Pick one primary pattern for the top level of your site, then nest the others inside it. ### Groups Groups are the basic building block: a labeled section with pages inside. Use them when the pages inside share a clear purpose and a user who wants one is likely to want the others. ```json docs.json theme={null} { "group": "Get started", "pages": ["quickstart", "authentication", "first-api-call"] } ``` Keep group names short and goal-oriented. "Get started" works. "Introduction to the product" is too long and too vague. ### Tabs Tabs create distinct sections of your site with separate URL paths, shown as a navigation bar across the top. Use them for parallel sections that serve the same audience in different modes. Completing a single task should only require content from a single tab. The most common good use of tabs is separating guides from API reference for one product. The same developer reads both, but they're doing different things: following steps in one, looking up parameters in the other. A common misuse of tabs is creating a tab for every product area because the sidebar is getting long. A long sidebar usually means your groups are poorly defined, not that you need more tabs. ### Dropdowns Dropdowns do the same job as tabs, but as a menu at the top of the sidebar instead of a bar across the page. Choose them when you have more sections than fit comfortably in a tab bar, or when you want the top of the page to stay clean. ### Products Products are for separate products that each need their own full documentation site under one project. If a user who works with Product A rarely needs Product B's documentation, products make sense. If users regularly move between sections, tabs or groups will serve them better. ### Anchors Anchors add persistent items to the top of your sidebar. They can section your content like tabs, but they're most useful as **global anchors**: links that appear on every page, regardless of section. Use global anchors for resources readers need from anywhere, like a changelog, a status page, or a community forum. Don't use anchors to promote content that's already easy to reach through your main navigation. ## Patterns that hold up **Make the quickstart easy to reach.** The most important page on most documentation sites is the one that gets a new user to a working state as fast as possible. Put it at or near the top of your primary navigation, and link to it from your introduction page so new users don't have to read through an overview to find it. **Separate doing from looking up.** Tutorials and how-to guides are about doing. Reference material is about looking up. Users move between these modes constantly, and they're easier to navigate when they live in distinct areas of your Mintlify site. **Name sections for what users will accomplish, not what the section contains.** "Webhooks" describes what's inside. "Receive real-time events" describes why a user would go there. The second version attracts the right reader without requiring them to already know what webhooks are. ## Check your section names Look at each section name without reading the content. Can a new user tell from the name alone whether the section will help with their task? If the answer is often no, the problem is usually one of two things: section names that are too product-centric, or sections that are too broad and need to be broken up. The next lesson covers how to test navigation with real readers and real data. ## Inventory content before reorganizing it Before changing a large navigation tree, list the existing pages with their purpose, audience, content type, traffic, and owner. If you audited content types in the [content types lesson](/courses/structure-docs/content-types#categorize-what-you-already-have), start from that list. Mark duplicates, gaps, and pages that no longer deserve a place in the new structure. Designing from an inventory prevents two common mistakes: preserving every old page because it already exists, and moving pages without noticing that several cover the same task. When you rename or move a published page, add a [redirect](https://mintlify.com/docs/create/redirects) from the old URL to the new one. Existing bookmarks, search results, support messages, and agent citations may continue using the old address long after the navigation changes. Quiz Your sidebar has grown to 40+ pages and a teammate suggests adding more tabs to manage the length. What should you consider first? Next up: [Measure and improve findability](/courses/structure-docs/measure-and-improve)—use behavior and feedback to test whether the structure works. # Structure docs that scale Source: https://learn.mintlify.com/courses/structure-docs/overview Learn how to build documentation that stays useful as your product and team grow. Most documentation problems are structural. You don't fix them by having better prose or nicer screenshots. You need to structure content around user goals and tasks. A ten-page site is easy to scan even if you don't know what you're looking for. At fifty pages, it gets harder. At a hundred, readers who can't find an answer quickly may open a support ticket or just leave. This course covers the decisions that determine whether your docs hold up over time: who you're writing for, what type of content each page should be, how to design navigation around user goals rather than product features, and how to keep everything accurate as things change. The examples use Mintlify, and you'll also see how to guide AI writing tools, because clear structure helps those tools produce better work. ## What you'll learn * How to define your audience clearly enough to use as context for AI writing tools * How to categorize content by type, and why mixing types makes docs more difficult to navigate * How to structure individual pages for scanning and successful task completion * How to design navigation that reflects what users are trying to accomplish * How to use behavior and feedback to find structural problems * How to keep documentation accurate at scale, with automation handling the mechanical work ## Who this is for Developers, technical writers, and product teams who own documentation at a company using Mintlify. You don't need a writing background. You just need to care about creating documentation that works for your users. ## Lessons in this course 1. [Understand your readers first](/courses/structure-docs/understand-your-readers)—Why audience clarity is the foundation of every structural decision, and how to use it as context for AI writing tools. 2. [Choose the right content type](/courses/structure-docs/content-types)—Different types of documentation and why mixing them makes it harder to navigate. 3. [Structure individual pages for scanning](/courses/structure-docs/page-structure)—How to organize prerequisites, headings, examples, troubleshooting, and verification. 4. [Design navigation for your users (not your product)](/courses/structure-docs/navigation-design)—How to organize content around what users are trying to accomplish, and when to use groups, tabs, dropdowns, products, and anchors. 5. [Measure and improve findability](/courses/structure-docs/measure-and-improve)—How to use search, analytics, support questions, and task testing to find structural problems. 6. [Keep docs accurate as your product grows](/courses/structure-docs/keeping-docs-current)—Ownership, agent-drafted updates, and automated checks that keep docs from going stale. Next up: [Understand your readers first](/courses/structure-docs/understand-your-readers)—define who each section is for before you decide how to organize it. # Structure individual pages for scanning Source: https://learn.mintlify.com/courses/structure-docs/page-structure Turn a page goal into headings, prerequisites, examples, and verification that help readers move quickly. A good navigation structure gets readers to the right page. The page still has to help them finish the job. Readers rarely start at the top and study every sentence. They scan headings, code blocks, lists, and visual cues until they find the section that matches their immediate question. Build pages for that behavior. ## Give each page one clear goal Before writing, finish this sentence: "After reading this page, the reader can \_\_\_." If the answer contains several unrelated verbs, split the page. "Install the SDK, understand our architecture, and troubleshoot webhooks" is at least three goals. Match the page structure to its content type: * A tutorial guides a learner through a complete experience. * A how-to guide starts with a known goal and provides the shortest reliable path. * Reference content makes facts easy to locate and compare. * An explanation builds understanding through context and relationships. ## Put prerequisites before instructions Tell readers what they need before they start working on a task. * Required accounts, roles, or permissions * Software and supported versions * Values they need to collect * Setup they should have completed elsewhere Link directly to prerequisite instructions. Don't make readers discover halfway through a procedure that they lack access or need another tool. ## Write headings that tell the story A reader should understand the page's shape by scanning its headings alone. Use headings that name a task, decision, or question: * "Generate an API key" instead of "API keys" * "Choose a deployment region" instead of "Options" * "Fix a 401 response" instead of "Troubleshooting" Keep the hierarchy meaningful. Use `##` for the main sections and `###` for subsections within them. Don't skip levels only to change the visual size. ## Introduce examples before showing them Before a code block, tell readers what it does, where it belongs, and what they may need to replace. Afterward, state the expected result when it isn't obvious. Here's what that looks like in practice: > To confirm your API key works, request your account details. Replace `YOUR_API_KEY` with the key from **Settings** > **API keys**. > > ```bash theme={null} > curl https://api.example.com/me \ > -H "Authorization: Bearer YOUR_API_KEY" > ``` > > A successful request returns `200 OK` with your account name and ID. The code shows the request. The sentences before and after tell readers why to run it, what to change, and how to know it worked. ## Put help near the failure point Don't collect every warning and troubleshooting note at the bottom of a long guide. If step three commonly fails because of permissions, mention the required permission before step three and link to the relevant fix there. Keep broad troubleshooting pages for symptoms that can occur in many workflows. Keep task-specific recovery close to the task. ## End with proof and direction Tell readers how to confirm that they succeeded. A useful verification is observable. * A command returns a specific value * A new status appears in the dashboard * An API request returns `200 OK` * The published page appears at a known URL Then tell them what comes next—if there is a meaningful next step. Don't add navigation only to fill the bottom of the page. ## Review the page as a stranger Before publishing, check: * Can someone understand the goal from the title and description? * Are all prerequisites visible before the first action? * Do the headings make sense without the paragraphs beneath them? * Can a reader tell what to copy, change, and expect from each example? * Is help placed near the step that can fail? * Does the page say how to verify success? Quiz A reader needs administrator access for step four of a guide. Where should the guide first mention that requirement? Next up: [Design navigation for your users (not your product)](/courses/structure-docs/navigation-design)—connect well-structured pages into paths that match user goals. # Understand your readers first Source: https://learn.mintlify.com/courses/structure-docs/understand-your-readers Audience clarity is the foundation of good documentation structure. Without it, every other decision is guesswork. [Understand your readers first](https://www.youtube.com/embed/6r5fRlj6nIU) Before you design navigation or decide how to organize content, you need to answer one question: who is this for? Most teams think they know their audience. But "developers" isn't specific enough. Neither is "our users." When your audience is everyone, your docs end up structured around the product rather than what people are trying to accomplish. ## Why audience clarity comes first Your audience shapes your structure. The same information needs a different organization depending on who's reading and what they want to do. A developer integrating your API for the first time needs a path that starts with authentication and gets to a working example as fast as possible. A developer returning to look up a specific parameter needs something they can scan in five seconds. A technical lead evaluating your product needs to understand the architecture before they care about implementation details. These are three different readers with three different needs. A single structure can't put all three first, so you have to decide who comes first. ## Define your primary reader For each section of your documentation, define one primary reader: a person with a specific goal and a specific level of prior knowledge, not a demographic. A useful reader definition answers three questions: * **Who are they?** Their role, experience level, and relationship to your product. * **What are they trying to do?** The specific task or goal that brought them to the docs. * **What do they already know?** What you can assume, and where you'll need to fill gaps. A good reader definition is concrete enough to write for. *Backend engineers* is not. *A backend engineer who signed up yesterday and needs to make their first authenticated API call* is. ## Use your audience as AI context If you use AI tools to write or maintain documentation, a clear audience definition matters even more. Without one, AI tools write for a vague, generic reader who doesn't represent anyone. Make your reader definition part of the context your AI tools receive every time they touch your docs. Where it goes depends on the tool: * **Mintlify's agent** (in Slack, automations, and the API) reads `.mintlify/AGENTS.md` in your docs repository. It doesn't read `CLAUDE.md`, Cursor rules, or other instruction files. * **The editor's agent** reads the **AI instructions** in your [editor settings](https://mintlify.com/docs/editor/settings#ai-instructions). Each teammate sets their own. * **Local tools** like Claude Code or Cursor read their own instruction files. Copy the same definition into them so every tool writes for the same reader. A minimal version looks like this: ```markdown .mintlify/AGENTS.md theme={null} ## Audience Our primary readers are backend developers integrating a B2B API for the first time. They are comfortable with REST and JSON but may not have used our product before. They want working examples, not explanations of concepts they already understand. Write for this reader unless a page explicitly specifies otherwise. ``` > [!WARNING] > > Keep `AGENTS.md` inside the `.mintlify/` directory. If you put it at the root of your project, Mintlify publishes it at `/agents.md` where anyone can read it. ## A practical starting point Before moving to the next lesson, write a one-paragraph reader definition for the section of your docs you're most responsible for. Name the role, the goal, and the level of prior knowledge you can assume. Add it to `.mintlify/AGENTS.md` and your editor AI instructions. Your AI tools will write for that reader, and you'll have something concrete to check drafts against. Quiz Your team's reader definition says 'developers.' A new page about webhooks keeps getting feedback that it's too basic for some readers and too advanced for others. What's the most likely fix? Next up: [Choose the right content type](/courses/structure-docs/content-types)—how to categorize each page before you write it, and why mixing content types is one of the most common reasons docs become hard to navigate. # Mintlify Learn Source: https://learn.mintlify.com/index Learn how to write great docs your users will love. # Mintlify Learn Learn how to write great docs your users will love. > **[Structure docs that scale](/courses/structure-docs/overview)** > > ![](https://mintcdn.com/learn/bGCRYioItrCK_NAk/assets/lessons/structure-docs-that-scale-light.jpg?fit=max\&auto=format\&n=bGCRYioItrCK_NAk\&q=85\&s=7f7491aa62cbe9fe3fe3ef1dfca6554b) > > 7 Lessons > > Learn how to organize, design, and maintain documentation as your > product and team grow. > **[Git and GitHub for Mintlify](/courses/git-github/overview)** > > ![](https://mintcdn.com/learn/bGCRYioItrCK_NAk/assets/lessons/git-and-github-for-mintlify-light.jpg?fit=max\&auto=format\&n=bGCRYioItrCK_NAk\&q=85\&s=0e4d9d99c2e5355855b261981e9833c6) > > 10 Lessons > > Learn how version control works, how to set up your docs repo, and how > to use Mintlify's review-driven workflow. > **[How to use Mintlify components](/courses/components/overview)** > > ![](https://mintcdn.com/learn/bGCRYioItrCK_NAk/assets/lessons/how-to-use-mintlify-components-light.jpg?fit=max\&auto=format\&n=bGCRYioItrCK_NAk\&q=85\&s=6358b29952da50c54d3cde538e6183a5) > > 19 Lessons > > Learn which components to use and when, so your documentation stays > clear and consistent. > **[Create agent-friendly content](/courses/agent-friendly-content/overview)** > > ![](https://mintcdn.com/learn/bGCRYioItrCK_NAk/assets/lessons/create-agent-friendly-docs-light.jpg?fit=max\&auto=format\&n=bGCRYioItrCK_NAk\&q=85\&s=85dbfef4008857e94d72a4e41c4c0284) > > 8 Lessons > > Learn how to write, structure, and configure your documentation so AI > tools can use it reliably. ### Your first day on Mintlify > **[Write content agents can use](/courses/agent-friendly-content/write-for-agents)** > > Write pages that agents can find, understand, and use as context. > **[Keep docs up to date](/courses/structure-docs/keeping-docs-current)** > > Make a plan from the beginning to keep your documentation up to date. > **[Learn the workflow](/courses/git-github/workflow)** > > Best practices for updating, reviewing, and publishing content.