Broken Link Checker

Your API documentation is one of the first places developers go to learn how your product works. 
It shapes their first impression and plays a big role in whether they decide to build with your API. 
Clear, consistent, and accurate documentation is essential for a developer experience that helps developers hit 200. 
But keeping docs that way can be challenging, especially when many people are contributing.

At ReadMe, we treat documentation as a team sport. 
Designers, engineers, support teams, and go-to-market teams all play a part in keeping our docs up-to-date. 
Whether people write directly in ReadMe’s editor or review content in GitHub, multiple voices often mean a range of writing styles. 

That’s where ReadMe’s Linter comes in. The AI Linter helps your team keep API docs cohesive and error-free by catching issues early, 
before your customers find them. With the Linter, you can:

- __Define a custom style guide__ in plain language that matches your company’s tone and standards
- Set rules to __detect objective errors__ before publishing
- __Surface subjective warnings__ for content that might need a second look
- __Automatically fix issues__ with [Agent Owlbert](https://docs.readme.com/main/docs/aiagent), ReadMe’s AI writing assistant

The AI Linter acts as a built-in quality check for your API documentation. 
It helps your team write, edit, and publish faster while maintaining accuracy and consistency across every page.

## How ReadMe's Linter Works

1. You define rules for your style guide, errors, and warnings.

- A style guide sets clear, plain-language rules for your documentation, along with guidelines for identifying errors and warnings.
Think of a style guide as documentation for your documentation. 
- In software development, an error is something that breaks the code. If you apply this to docs, an error is anything that should never be published.
- A warning is less critical. It points out a potential issue that you may want to look over to make sure it fits your style.

2. You can run the AI Linter on a page while editing, before you save.
3. Agent Owlbert can help fix all the issues that are flagged. 

Here are some examples of how style guide rules, errors, and warnings look in plain language—and how our AI Linter interprets them:

__Style Guide__: 
- Use an active voice and maintain a friendly, helpful tone. 
- Write for beginners, intermediate, and advanced users, but assume that everyone has a baseline understanding of the product. 
- Keep sentences brief, between 50-75 words.

<img 
src="/static/blog/2025-10-30-linter/StyleGuideDarkbg.png" 
alt="Style Guide results" 
className="full" 
style={{ display: 'block', maxWidth: '50%', height: 'auto', margin: '0 auto', }} 
/>

__Errors__:
- Capitalize ReadMe correctly. Always use "ReadMe". Never use “readme” or “Readme." 
- Avoid placeholder text including lorem ipsum or TODO.
- Use backticks for code elements.

<img 
src="/static/blog/2025-10-30-linter/ErrorsDarkbg.png" 
alt="Style Guide results" 
className="full" 
style={{ display: 'block', maxWidth: '50%', height: 'auto', margin: '0 auto', }} 
/>

__Warnings__: 
- Avoid using unexplained, internal jargon.
- Avoid using uncertain language.
- Use inclusive language.

<img 
src="/static/blog/2025-10-30-linter/WarningsDarkbg.png" 
alt="Warnings results" 
className="full" 
style={{ display: 'block', maxWidth: '50%', height: 'auto', margin: '0 auto', }} 
/>

## Why Linters Matter for API Documentation

For many teams, documentation quality is a key part of the overall developer experience. 
When your docs stay up to date, developers can build with your API faster. 
ReadMe’s Linter automates much of the manual review process and makes it easy for your entire documentation site to stay unified and polished. 
Check out [our docs](https://docs.readme.com/main/docs/linter) and try our linter!

## For Teams Looking to Get More From ReadMe AI

We're introducing the [AI Booster Pack](https://readme.com/pricing) which gives your team more ways to get value from ReadMe AI, with features including:

- [Ask AI](https://docs.readme.com/main/docs/ask-ai): A conversational AI search tool that surfaces contextually relevant answers trained on your documentation.
- [Ask AI Analytics](https://docs.readme.com/main/docs/ask-ai#analytics): Dig into user questions, responses, and feedback to understand how Ask AI is performing. 
- Unlimited [AI Agent](https://docs.readme.com/main/docs/aiagent) usage: A writing assistant that helps create and edit your docs.
- Unlimited [Docs Audits](https://docs.readme.com/main/docs/docs-audit): An overview report and score of your documentation site. 

You can add AI Booster Pack to any plan for $150/month. If you're already using Owlbot, you’ve automatically been upgraded 
to the AI Booster Pack, which now includes [Ask AI](https://docs.readme.com/main/docs/ask-ai).

 <Slack>
 Need help getting started with the linter?
 </Slack>


Find & Fix API Documentation Errors with ReadMe's AI Linter

Find & Fix API Documentation Errors Early with | ReadMe's AI Linter

Paul Cox

For the past 10 years, ReadMe has helped API teams create great developer experiences. But today, those
experiences need to support not just developers, but also the AI tools they use every day. As development moves
faster, documentation has become core to the workflow. That’s why we’re excited to introduce a new set of AI
features that make creating and maintaining documentation easier than ever.

## Agent Owlbert: Your AI Writing Assistant

Meet [Agent Owlbert](https://docs.readme.com/main/docs/aiagent), your AI writing assistant that accelerates how you write and improve documentation.
Owlbert can help rewrite your docs for clarity, build more interactive pages by suggesting and implementing ReadMe’s [built-in MDX components](https://readme.com/blog/component-marketplace),
and combine research with content creation.

<Frame>
  <video
    src="/static/blog/2025-10-07-team-up-with-ai-to-build-docs/AgentOwlbert-MDX.mp4"
    loop
    muted
    autoPlay
  >
  </video>
</Frame>

## Linter: Review Pages with Custom Rules

The [Linter](https://docs.readme.com/main/docs/linter) works in real-time as you write, catching issues you might miss.
The Linter automates the time-consuming work of checking content against your style guide and automated tooling that writers traditionally use.
While there are a ton of grammar checks out there, this isn’t just another generic spell check tool.
You write in natural language what makes for good documentation and the linter surfaces errors and warnings. Any
issues that the linter surfaces can be fixed by Agent Owlbert!

<Frame gradient="poppy">
  <video
    src="/static/blog/2025-10-07-team-up-with-ai-to-build-docs/Linter-Rules.mp4"
    loop
    muted
    autoPlay
  >
  </video>
</Frame>

## Docs Audit: Score Your Docs Against Your Own Style Guide

While the Linter makes sure every page is perfect, [Docs Audit](https://docs.readme.com/main/docs/docs-audit) gives
you a complete overview of your documentation. It helps you identify gaps and inconsistencies so
you can improve your entire documentation site. You customize a style guide that reflects what your company values,
whether that means using more playful language or writing straightforward, step-by-step instructions.

Together, the Linter and Docs Audit create a powerful system for evaluating, scoring, and elevating your documentation,
from the tiniest details to the overall developer experience.

<Frame gradient="bluebird" attachToBottom={true}>
  <img
    src="/static/blog/2025-10-07-team-up-with-ai-to-build-docs/DocsAuditReport.png?"
    alt="Docs Audit Report"
    style={{
      display: 'block',
      maxWidth: '100%',
      height: 'auto',
      margin: '0 auto',
    }}
  />
</Frame>

## New AI Search

We've completely reimagined how developers interact with your documentation. Owlbot has evolved from a simple
search bar to a sidebar experience that makes it easy for developers to learn about your API. Now,
[Ask AI](https://docs.readme.com/main/docs/ask-ai) is a conversational interface that understands context, remembers previous questions, and can guide
developers through complex implementation scenarios.

<Frame gradient="twilight">
  <video
    src="/static/blog/2025-10-07-team-up-with-ai-to-build-docs/AskAI-Features.mp4"
    loop
    muted
    autoPlay
  >
  </video>
</Frame>

## AI Booster Pack: A New Way to Build with ReadMe

While these features are available on most plans, the AI Booster Pack unlocks advanced capabilities for teams
looking to do more with AI, including:

- Custom AI models tailored to your API and documentation

- Ask AI analytics to understand and improve AI interactions

- Unlimited usage across all AI features

The [AI Booster Pack](https://readme.com/pricing) is available for $150/month and can be added to any plan.

Already using Owlbot? You’ve automatically been upgraded to the AI Booster Pack, which now includes [AI Search](https://docs.readme.com/main/docs/ask-ai).

## Start Building with AI
The way software gets built is changing, and documentation has become a central part of that process.
With our new [AI features](https://docs.readme.com/main/docs/ai-overview), ReadMe makes it simple to create documentation that keeps pace with modern development.
Try them out for yourself and let us know what you think!

 <Slack>
 Need help building with AI?
 </Slack>


Team Up with AI to Build Docs

Team Up with AI | to Build Docs

Great API documentation is more than just a static reference. Developers want clear guides, accurate details, and 
fast answers to their questions. ReadMe's AI tools make your job easier so that you can spend time on what matters most - 
building APIs that developers love to build with.

This guide walks through how you can use ReadMe’s AI features to write, review, and improve your 
documentation so it’s easier for your developers to get started with your API.

## Write and Edit Documentation

__Meet Agent Owlbert, Your AI Writing Assistant__ 

[Agent Owlbert](https://docs.readme.com/main/docs/aiagent) reviews your documentation, suggests edits for clarity, and flags inconsistencies. 
Because it’s connected to your documentation and knowledge sources, Owlbert also helps keep everything in sync 
as your API evolves.

<video
  src="/static/blog/2025-09-12-ai-tools-for-api-documentation/ai-agent.mp4"
  loop
  muted
  autoPlay
  className="full"
>
</video>

__Tip__: Use Owlbert as a second set of eyes when writing new content. It’s especially helpful for keeping your endpoint 
descriptions and guides aligned.

## Review and Improve Your Docs

__Polish Your API Docs with Built-In Linting__

The [Linter](https://docs.readme.com/main/docs/linter) helps keep your documentation clear and consistent. It automatically checks for issues like missing details, 
unclear phrasing, or formatting problems. Instead of reviewing every page by hand, you’ll get quick feedback that 
makes your docs easier to follow. This is especially helpful when multiple people are contributing.

<img 
src="/static/blog/2025-09-12-ai-tools-for-api-documentation/linter.png" 
alt="Linter configuration" 
className="full" 
style={{ display: 'block', maxWidth: '50%', height: 'auto', margin: '0 auto', }} 
/>

<br></br>

__Tip__: The Linter works best when you use it regularly while updating your docs. Catching small issues early makes your
guides and API reference more easier to navigate.

## Help Your Developers Use Your Docs More Easily

__Add AI Search to Your Docs__

Once you’ve published your API reference and guides in ReadMe, you can [enable an Ask AI dropdown menu](https://docs.readme.com/main/docs/AskAI) to your docs. 
This gives developers the option to ask AI tools, like ChatGPT or Claude, questions about your docs. 
Instead of scrolling through pages to find what they need, your developers can ask questions in conversational 
language and receive accurate, contextual answers pulled directly from your guides and API reference.

<video
  src="/static/blog/2025-09-12-ai-tools-for-api-documentation/ask-ai.mp4"
  loop
  muted
  autoPlay
  className="full"
>
</video>

__Tip__: The clearer your guides and references, the more helpful the answers will be.

__Connect Your Docs to AI with LLMs.txt__

You can also [generate an llms.txt file](https://docs.readme.com/main/docs/LLMstxt) of your docs, which is a file that 
tells large language models like ChatGPT or Claude how to find and use your docs. By making your documentation 
discoverable to AI tools, you help developers get accurate, up-to-date answers when they ask questions in natural 
language.

__Tip__: The better your informational architecture and structure, the more likely AI tools will surface the 
right information for your developers.

__Generate Your MCP Server__

Finally, [generate an MCP (Model Context Protocol) server](https://docs.readme.com/main/docs/mcp-servers) from your docs. This feature automatically creates a way for AI tools to access your documentation. With MCP servers, developers can stay in their AI-powered code editor and still rely on your documentation.

<img
  src="/static/blog/2025-07-30-mcp/MCP-server.png"
  alt="ReadMe MCP Server Generation Configuration"
  className="full"
  style={{
    display: 'block',
    maxWidth: '50%',
    height: 'auto',
    margin: '0 auto',
  }}
/>

<br></br>

__Tip__: MCP server generation runs in the background and you don’t need to configure anything manually. 
Just keep your docs updated in ReadMe, and the server stays in sync.

## Bringing It All Together

With all of these built-in AI tools, your documentation becomes an evolving, interactive resource:

- Your writing stays clear and consistent.
- Developers can ask questions about your API, directly in your hub.
- AI assistants have access the latest version of your docs.

ReadMe’s AI tools work together to handle what AI does best so that you can spend more time on what you’re good at! 
Check out our [AI Overview docs](https://docs.readme.com/main/docs/ai-overview) that walk through each feature so you 
could learn more about them and start building.

 <Slack>
 Need help getting started with ReadMe's AI features? 
 </Slack>

Use ReadMe’s AI Tools to Write Great Documentation


## Why Interactive API Documentation Matters

In 2025, documentation doesn’t have to be pages of walls of text. It’s table stakes to learn about APIs through clearly written 
technical documentation, but now there are tools available to make docs engaging and actually…fun. 

## How MDX Changes Developer Docs

Traditional content management systems relied on plain text or Markdown. The introduction of MDX changed that by extending 
Markdown with the ability to embed React components. You’ve probably interacted with a React component today without realizing it. 
Whether you submitted a form, clicked a button, or even fired off celebratory confetti after completing a task, you interacted 
with some components on a web page. That same kind of delight can live inside your API docs, giving developers not just instructions 
but a hands-on experience.

## Two Ways to Add Components in ReadMe

With ReadMe’s editor, you can add components to your documentation in two ways:
1. **Use built-in components** like Cards or Accordions, easily accessible from the slash menu.
2. **Build your own components** and bring them directly into your docs.

## Examples of Components 

Here are some of my favorite components:

**Accordion**: Expand and collapse sections of content to organize and display large amounts of information 
in a compact, interactive way.

<Accordion 
title="Specs & Details" 
icon="fa-info-circle" 
iconColor="green">
  A great way to collapse information, but ensure essential headers are still visible.
</Accordion>

<Accordion 
title="FAQ" 
icon="fa-question-circle" 
iconColor="blue">
  Use accordions in FAQs to break down content in a way that's easy to find and digestible.
</Accordion>

<br></br>

**Page Banners**: Visually highlight important information, announcements, or calls to action directly inside a page. 
Customize the message, text, and colors, as well as the position whether it's inline (inside the content body) 
or at the top of the page header.

<Banner
  isInline={true}
  message="This banner is displayed inline."
  color="yellow-500"
  textColor="white"
  fontSize="14px"
  fontWeight="bold"
/>

<br></br>

<br></br>
**Quiz Game**: Display a question with multiple-choice answers, let the user select an option, and check if the answer is correct.
<QuizGame
  question="What is a group of owls called?"
  options={[
    { text: 'A flock', isCorrect: false },
    { text: 'A parliament', isCorrect: true},
    { text: 'A council', isCorrect: false },
    { text: 'A murder', isCorrect: false }
  ]}
/>

<br></br>

Here's the code you would paste into your component editor in ReadMe:

<CodeBlock 
  language="jsx"
  code={`
  import { useState } from 'react';

  export const QuizGame = ({ question, options }) => {
    const [selectedIndex, setSelectedIndex] = useState(null);
    const [submitted, setSubmitted] = useState(false);

    const handleOptionClick = (index) => {
      if (submitted) return;
      setSelectedIndex(index);
    };

    const handleSubmit = () => {
      if (selectedIndex !== null) {
        setSubmitted(true);
      }
    };

    const handleReset = () => {
      setSelectedIndex(null);
      setSubmitted(false);
    };

    return (
      <div className="max-w-md mx-auto p-6 bg-inherit rounded-lg shadow-sm border border-gray-200 dark:border-gray-400">
        <h3 className="mb-6! mt-0! text-center">{question}</h3>
        <div className="flex flex-col gap-2">
          {options.map((option, idx) => (
            <button
              key={idx}
              onClick={() => handleOptionClick(idx)}
              className={\`
                text-sm text-left border-0 rounded-md p-[10px] bg-gray-100 text-gray-600 dark:bg-gray-700 dark:text-white
                \${!submitted && 'cursor-pointer hover:bg-gray-200 dark:hover:bg-gray-700'}
                \${!submitted && selectedIndex === idx && 'border! border-blue-300 bg-blue-200! dark:bg-blue-900!'}
                \${submitted && option.isCorrect && 'border! border-green-300 bg-green-100 dark:bg-green-900'}
                \${submitted && selectedIndex === idx && !option.isCorrect && 'border! border-red-300 bg-red-100 dark:bg-red-900'}
              \`}
            >
              {option.text}
            </button>
          ))}
        </div>
        <div className="flex justify-end">
          {!submitted ? (
            <button
              onClick={handleSubmit}
              disabled={selectedIndex === null}
              className={\`
                mt-3 border-none p-3 font-semibold rounded-md cursor-pointer
                \${submitted || selectedIndex === null ? 'bg-gray-300 text-gray-400 cursor-not-allowed!' : 'bg-blue-500 text-white hover:bg-blue-600'}
              \`}
            >
              Check Answer
            </button>
          ) : (
              <button
                onClick={handleReset}
                className="mt-3 border-none py-3 px-7 font-semibold rounded-md cursor-pointer text-white bg-gray-500 hover:bg-gray-400"
              >
                <i className="fa-solid fa-refresh" /> Reset
              </button>
            )}
          </div>
        </div>
      );
    };
  
  <QuizGame
    question="What is a group of owls called?"
    options={[
      { text: 'A flock', isCorrect: false },
      { text: 'A parliament', isCorrect: true},
      { text: 'A council', isCorrect: false },
      { text: 'A murder', isCorrect: false }
    ]}
  />
`}
/>

<br></br>

## How to Add a Component to Your Documentation

1. In your Admin Dashboard, go to **Settings** > **Custom Components**.

2. From the Marketplace, choose a component to customize. Or, you can build your own component from scratch with JSX!

3. Add the component to your docs using the `<` menu.

<video
  src="/static/blog/2025-08-28-component-marketplace/Marketplace.mp4"
  loop
  muted
  autoPlay
  className="full"
>
</video>

## Share Your Component with ReadMe's Community

If you've built a component and want to contribute it to our [Component Marketplace on GitHub](https://github.com/readmeio/marketplace), 
open up a PR with your new MDX component and we'll review it! Here are our [Contribution Guidelines](https://github.com/readmeio/marketplace/blob/main/CONTRIBUTING.md)
if you're interested in contributing to ReadMe's Component Marketplace. If you have any questions, just open an issue. 

 <Slack>
 Need help building components, or want to contribute a component to our marketplace? 
 </Slack>

Interactive API Documentation: How to Use Custom Components in ReadMe


A few weeks ago, we launched [Branching](https://readme.com/blog/branches), giving you 
the ability to manage documentation in the same way you your manage code. With Branching, 
teams can edit, preview, and publish updates with confidence. Now, we’re building on that 
foundation with [Branch Reviews](https://docs.readme.com/main/docs/branches#/).

Branch Reviews provide a simple, structured way to see exactly what's changed on a branch, 
review in context, and approve edits before they go live. The result is a 
faster, safer, and more collaborative process for maintaining your API documentation.

<div style={{ display: 'flex', justifyContent: 'center' }}>
  <img
    src="/static/blog/2025-08-26-branch-reviews/review-changes.jpg"
    alt="Granular merge permissions for Enterprise plans"
    style={{
      maxWidth: '150%',
      height: 'auto'
    }}
  />
</div>


## Why Branch Reviews Matter 

When you’re rolling out new features and products all the time, 
your API docs need to keep up. That’s how customers discover and adopt what you’ve built. 
The problem is, with multiple teammates editing docs from different places, it’s easy 
to lose track of changes or accidentally publish something that isn’t quite right. 

Branch Reviews solve this by:

- Showing **line-by-line diffs** of every change across your docs
- Making it **easy to preview** updates before merging
- Letting teams **share review links** for quick feedback
- Supporting **role-based merge permissions** for governance (Enterprise feature)


<video
  src="/static/blog/2025-08-26-branch-reviews/review-branch.mp4"
  loop
  muted
  autoPlay
  className="full"
>
</video>

---

## How Branch Reviews Work

1. **Create a Branch**<br></br>
Start from the Versions & Branches menu in your Admin Dashboard. Your changes live safely in a branch until you’re ready to merge. 
If you’re [syncing with GitHub](https://docs.readme.com/main/docs/bi-directional-sync), branches created in the ReadMe UI will 
automatically show up in your GitHub repository too!

2. **Make Your Edits**<br></br>
Update pages, restructure content, or reorganize docs without affecting the live version.

3. **Open the Review Tab**<br></br>
See exactly what’s changed including content updates and documentation reordering.

4. **Share your Branch for Feedback**<br></br>
Share a preview link with teammates to review edits.

5. **Merge Only What's Ready**<br></br>
Once approved, merge your branch into production. If conflicts come up, resolve them in GitHub or choose which branch to keep.

6. **Control Who Merges**<br></br>
For Enterprise plans, you can restrict merging to Admins or Editors to ensure quality control.

---
## Traditional Staging vs. Branching

Staging environments are slow, siloed, and often limited to one preview at a time. 
Branch Reviews are built for today’s collaborative teams:

<div className="overflow-x-auto">
  <table className="min-w-full border border-gray-300 divide-y divide-gray-200 rounded-lg shadow-sm">
    <thead className="bg-gray-100">
      <tr>
        <th className="px-4 py-2 text-left text-sm font-semibold text-gray-700">Staging</th>
        <th className="px-4 py-2 text-left text-sm font-semibold text-gray-700">Branches</th>
      </tr>
    </thead>
    <tbody className="divide-y divide-gray-200">
      <tr>
        <td className="px-4 py-2 text-sm text-gray-600">All project-level pending changes must be promoted together.</td>
        <td className="px-4 py-2 text-sm text-gray-600">Individual branches can be merged when ready.</td>
      </tr>
      <tr>
        <td className="px-4 py-2 text-sm text-gray-600">All teammates beholden to the same promotion cycle.</td>
        <td className="px-4 py-2 text-sm text-gray-600">Each branch has its own preview, enabling targeted reviews and cleaner feedback workflows.</td>
      </tr>
      <tr>
        <td className="px-4 py-2 text-sm text-gray-600">Only group Admins can promote content.</td>
        <td className="px-4 py-2 text-sm text-gray-600">Flexible permissions so branches can be created, reviewed, and merged by different roles with granular control.</td>
      </tr>
      <tr>
        <td className="px-4 py-2 text-sm text-gray-600">Limited team collaboration.</td>
        <td className="px-4 py-2 text-sm text-gray-600">With GitHub sync, branches mirror seamlessly across ReadMe and GitHub.</td>
      </tr>
    </tbody>
  </table>
</div>




---

## Getting Started with Branching

If your team wants to improve overall developer experience to drive API adoption, you 
need a documentation workflow that is collaborative, transparent, and safe.

Learn more about [Branches in ReadMe](https://docs.readme.com/main/docs/branches) and start reviewing and merging branches in your 
own workflow today.




Review & Approve API Documentation Changes with Branch Reviews


Branching is here! Now, you can edit, preview, and publish different versions of your documentation without impacting 
what’s live. You have full version control over your docs workflow, right from within ReadMe.
Building branching is part of our bigger effort to make ReadMe work the same way you do with your code. 
This means offering things like version control, Git workflows, and writing where your team chooses.

<video
  src="/static/blog/2025-08-07-branches/branching.mp4"
  loop
  muted
  autoPlay
  className="full"
>
</video>

---

## Skip Staging, `Git Branch`

Traditional staging environments can slow teams down. They’re rigid, limited to just one preview at a time, and make 
collaboration harder than it needs to be. With ReadMe’s branches, you get the flexibility and control of Git, 
directly in your docs workflow.
If you've used Suggested Edits, you've been limited to editing one page a time. Branches enable you to group multiple 
changes across multiple pages into a branch to make it easy to manage big updates and reviews.


Here’s what you can do with [branches](https://docs.readme.com/main/docs/branches):
- **Edit in isolation**: Make selected changes to your documentation without affecting what’s live.
- **Preview before you publish**: See exactly what your readers will experience, before merging.
- **Collaborate better**: Share preview links with teammates for faster reviews and approvals.
- **Merge with control**: Only push what’s ready, and keep in-progress work in a branch.

<img
  src="/static/blog/2025-08-07-branches/create-branch.png"
  alt="Create a branch in ReadMe"
  style={{
    display: 'block',
    maxWidth: '100%',
    height: 'auto',
    margin: '0 auto'
  }}
/>

<br></br>

You can do all of this from ReadMe’s editor, or by syncing your docs to a Git repo with bi-directional sync.

---

## Bi-Directional Sync with GitHub

If you're using [bi-directional sync with GitHub](https://docs.readme.com/main/docs/bi-directional-sync), 
your ReadMe branches automatically mirror what’s in your repo. Your team can work on docs in ReadMe's editor or 
their IDE. Whether they want to use a docs-as-code workflow or our WYSIWYG editor, your docs will always be 
up-to-date.

## Built for Teams & Enterprise

For our Enterprise customers, branching comes with [granular merge permissions](https://docs.readme.com/main/docs/branches#/restricting-merge-to-admins) and governance tools, so teams 
can move fast without compromising quality or control. You can restrict merge access per project to only 
Admins or Editors. 

<img
  src="/static/blog/2025-08-07-branches/merge-branch.png"
  alt="Granular merge permissions for Enterprise plans"
  style={{
    display: 'block',
    maxWidth: '50%',
    height: 'auto',
    margin: '0 auto'
  }}
/>

<br></br>

---

## Getting Started

A lot of teams want to write [docs-as-code](https://readme.com/blog/docs-as-code). That might mean reviewing changes in a pull request, writing alongside 
code in the same branch, or lining up a docs update with a product release. 
Branching makes all of this possible. You don’t have to wait until something is final, and you don’t have to manually 
track what’s been changed. 

Check out [our docs](https://docs.readme.com/main/docs/branches) to start editing in branches.





Ship Docs Like Features with Branching


Docs-as-code is the philosophy that your technical documentation should be produced and managed using the same
tools and process as your code. This includes writing in your local dev environment, using Git for version control,
and deploying through the same workflow.

There’s a number of benefits:

- **All in one place**: This makes it harder to skip the documentation, if the creation of the docs happens the same place the code does.
- **Shared deploys**: You can set it up so that your docs can go out the same time the feature does, so your launch is coordinated.
- **Automation**: Not all docs are written by humans… sometimes the best documentation is automated from your code!

You also get to take advantage of the rich ecosystem built around code: version control, automated tests, linting,
pull requests and more.

## Limitations
When I started ReadMe 10 years ago, ironically the most beloved value prop was that the docs weren’t locked up in Git.
Back then, most documentation was tangled together with the presentation layer (the HTML and CSS for the docs site),
and even a small typo fix required a herculean effort to deploy. Documentation sat stale, waiting for a developer
who knew how to get it published.

Since then, a lot has changed. Developer tools have gotten better. Everyone’s gotten more technical.
And the content and presentation layer are now separate, meaning the content is more accessible.

Our editor is still a solid way to write and manage your docs. The WYSIWYG editor is easy to use, but also
gives you room to customize and build interactive docs. If you want to work in a visual way while still taking
advantage of all the bells and whistles ReadMe provides, there’s a lot of great reasons to fire up the web editor.

## Best of Both Worlds
We built ReadMe in a way where your team doesn’t have to choose where you write – everyone can write where they feel
most comfortable. For people who prefer to write in their local dev environment, they can check the docs out via
[bi-directional](https://docs.readme.com/main/docs/bi-directional-sync) sync and edit there. Or, for people who
prefer a more rich, visual experience, our editor is always an option. You don’t need Git to use ReadMe,
but now it’s there if your teams want it.

The best part is different people can seamlessly work together in different places. Git is the source of truth,
and our editor is just a client on top of it. All our tooling (and all GitHub’s tooling)
can be used, so you can write wherever and whenever inspiration strikes!

## Why Now
We’ve rebuilt ReadMe on top of Git so your team can work with docs the same way you work with code.
With features like [branching](https://docs.readme.com/main/docs/branches), it’s easier to collaborate, review changes, and ship docs alongside your
product. Whether you’re writing in your IDE or in ReadMe’s editor, everything stays in sync so that your docs will
keep up with your code.

<Slack>
Need help with your docs, or want to chat about how to incorporate Git into your docs workflow?
</Slack>


Where Docs-as-Code Goes Next


ReadMe powers APIs, and APIs power AI, so of course we're psyched about Model Context Protocol (MCP), a new standard that bridges AI agents and developer tools.
It's right in line with our mission to make APIs easier to use with an intuitive developer experience.

We’ve launched our own MCP server and made it possible for API creators to do the same. Now, ReadMe customers
can edit docs directly from AI code editors. Customers can also launch their own MCP servers,
making APIs instantly more accessible and understandable to AI tools to meet developers where they are.

---

## What Is MCP and Why it Matters for APIs

Model Context Protocol ([MCP](https://modelcontextprotocol.io/overview)), introduced by Anthropic in late 2023, standardizes how tools and data sources connect to AI models.

It enables:

- Large-language modles (LLMs) to understand and use data from APIs and documentation
- Function calling, not just text generation
- AI agents to act on information, not just understand it

In short, MCP gives models both the knowledge and the ability to complete tasks.

---

## One Way to Think About MCP: A Well-Organized Toolbox

I've been covered in sheetrock dust from our home improvement projects lately, which might explain why all I can think
about when I hear ''tooling'' is the screwdriver on my desk from hanging shelves over the weekend.

MCP servers are APIs or services that expose their data in an MCP-compatible format, making it easier for AI to access and use APIs. I think of them as a toolbox you
hand to an AI agent, filled with power drills, screws, and instructions (APIs, data sources, and docs).
The toolbox tells the AI how each drill works and remembers which screws need a flathead and which need a Phillips.

Now, the AI doesn't just _know_ which bit to use. It can pick up the power drill, slot in the right bit, and screw it in.
It uses the right tool for the right job and actually gets the task done.

## Generating MCP Servers for Your Developers

Developers can use MCP servers to not only learn about APIs, but also to take action and build
even faster. With ReadMe, an [MCP server](https://docs.readme.com/main/docs/generate-your-own-mcp-server) is automatically provided out of the box for every project. All you
have to do is enable MCP to connect your documentation and API to AI tools. You can share your [MCP URL](https://docs.readme.com/main/docs/generate-your-own-mcp-server) with your developers,
and they can connect their AI assistants and tools directly to your API.

<img
  src="/static/blog/2025-07-30-mcp/MCP-server.png"
  alt="ReadMe MCP Server Generation Configuration"
  className="full"
  style={{
    display: 'block',
    maxWidth: '50%',
    height: 'auto',
    margin: '0 auto',
  }}
/>

<br></br>

This means that API creators can enable developers to build outside of docs with confidence
that docs and APIs remain the source of truth. Rather than context-switching between documentation, IDEs,
and testing tools, developers can work directly within their AI code editor while having
instant access to API documentation.

## Use ReadMe's MCP Server to Improve API Docs with AI

With [ReadMe's MCP server](https://docs.readme.com/main/docs/readmes-mcp-server), you can do everything you normally would in ReadMe, like adding and editing pages, directly through our API.

Our favorite workflow is:

1. Ask to find underperforming pages by using the [Metrics API](https://docs.readme.com/main/reference/metrics-api-introduction#/) to identify docs with low page views.
2. Ask for suggestions on how to improve each page's content, using your best performing docs as a reference.
3. Edit those pages directly from IDEs like VS Code or Cursor, with ReadMe's MCP server.

To get started, you'll need your ReadMe API key. Once you have that, you can
[plug it into Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=readmeAPI&config=eyJ1cmwiOiJodHRwczovL2RvY3MucmVhZG1lLmNvbS9tY3AifQ==) and start improving your docs.

<iframe
  width="560"
  height="315"
  src="https://www.youtube.com/embed/ZoTq0BrFoGA"
  frameborder="0"
  allowfullscreen
></iframe>

In addition to Cursor, we also support IDE integrations with VS Code, Claude, Windsurf, and Gemini CLI.

---

## Getting Started with MCP

Choose how you’d like to start working with MCP:

1. [Auto-Generate Your Own MCP Server](https://docs.readme.com/main/docs/generate-your-own-mcp-server): Simply enable MCP to connect your API documentation to AI tools.

2. [Use ReadMe's MCP Server](https://docs.readme.com/main/docs/readmes-mcp-server): You can do everything you normally would in ReadMe, 
like adding and editing pages, directly through our API.

<Slack>
Have questions about MCP, or need help with your docs?
</Slack>

From IDE to AI: How ReadMe bridges APIs to LLMs with MCP


So, everyone’s been talking about LLMs. Many companies are trying to figure out how to incorporate AI into their product suite or even encourage their employees to use AI to build. We’ve been thinking about how this new wave of innovation could make it easier for developers to use APIs so we started with llms.txt.

You can now publish an llms.txt file to help AI assistants understand your API documentation to provide your customers with the answers they need to build with your API. While AI is trending, ReadMe's mission remains the same: helping developers use APIs, with documentation at the core of the experience.

# What is /llms.txt?

<a href="https://llmstxt.org/" target="_blank" rel="noopener noreferrer">llms.txt</a> is a file that LLMs can use to better understand your content. By now, you’ve probably heard of an LLM, short for Large Language Model. LLMs like OpenAI’s ChatGPT and Anthropic’s Claude use natural language processing techniques to advance the way we interact with data and information. In the context of ReadMe, a llms.txt file of your docs is a page that lists all of your docs pages with links to each page in markdown format. Let’s take a look at what that looks like.

This is what your docs in ReadMe look like:

<img
  src="/static/blog/2025-04-30-ask-ai/ReadMe-sidebar.png"
  alt="ReadMe Sidebar"
  style={{
    display: 'block',
    maxWidth: '50%',
    height: 'auto',
    margin: '0 auto'
  }}
/>

This is your docs as an llms.txt file:

<div style={{
  backgroundColor: '#1e1e1e',
  color: '#d4d4d4',
  padding: '1rem',
  borderRadius: '8px',
  fontFamily: 'monospace',
  fontSize: '1rem',
  lineHeight: '1.6',
  overflowX: 'auto',
  maxWidth: '800px',
  margin: '1rem auto',
  boxShadow: '0 4px 10px rgba(0, 0, 0, 0.5)'
}}>
  <pre style={{
    backgroundColor: 'transparent',
    color: '#d4d4d4',
    margin: 0,
    whiteSpace: 'break-spaces',
    textWrap: 'nowrap',
    fontSize: '14px',
    letterSpacing: '-0.5px',
  }}>
{`# Getting Started

[👋 Welcome to ReadMe!](https://docs.readme.com/main/docs/about-readme.md)

[🚀 Quickstart Guide](https://docs.readme.com/main/docs/quickstart.md)

[📦 Moving Your Docs to Their New Home](https://docs.readme.com/main/docs/migration-moving-your-docs-to-their-new-home.md)`}
  </pre>
</div>

# Why You Want an llms.txt file Of Your Docs
When you make docs accessible to LLMs, you're not only keeping up with the latest trends, but also you're adding context and richness to your developer experience. At ReadMe, we believe docs shouldn’t just be paragraphs of text. By enabling AI features, you meet developers where they are: exploring, learning, and debugging through conversational tools. Giving developers a way to interact with your API via LLMs adds a powerful new touchpoint in your developer experience. By publishing a llms.txt file that LLMs can read for your docs, you’re able to streamline workflows and get your customers to “hello world” faster.

# Getting Started: Using AI Features

<img
    src="/static/blog/2025-04-30-ask-ai/AskAI.gif"
    alt="Ask AI Dropdown"
    className='full'/>

Now, let’s walk through setting this up. In the top menu bar of the editor, go to ​​✨ AI Settings where you can toggle to publish your <a href="https://docs.readme.com/main/docs/LLMstxt/" target="_blank" rel="noopener noreferrer">docs as an llms.txt file</a>.

You can also add an <a href="https://docs.readme.com/main/docs/AskAI/" target="_blank" rel="noopener noreferrer">Ask AI dropdown</a> across all of your Guides, allowing users to select their preferred LLM to interact with (ChatGPT or Claude). They can also copy your docs as markdown to paste into their LLM of choice.

 <img
    src="/static/blog/2025-04-30-ask-ai/ask-ai-dropdown-settings.png"
    alt="AskAI Dropdown Settings"
    style={{
      display: 'block',
      maxWidth: '50%',
      height: 'auto',
      margin: '0 auto 1.5rem auto' }}
    />


When your users click “Ask ChatGPT,” the current page is sent as a markdown file to ChatGPT for users to ask questions about. Markdown is the ideal format for LLMs to read data, so we host a markdown version for all your guides. Simply add <code>.md</code> to the end of the url. Give it a quick try with your own docs.

Docs on ReadMe: [https://docs.readme.com/main/docs/quickstart](https://docs.readme.com/main/docs/quickstart)

Markdown file of ReadMe docs: [https://docs.readme.com/main/docs/quickstart.md](https://docs.readme.com/main/docs/quickstart.md)

# What's Next

While there is a lot of buzz around AI, we’ve always been building with developers in mind. We’re excited to help API creators create a developer-first experience where documentation stands at the core of onboarding. Give this a try and let us know any feedback you might have at <a href="mailto:support@readme.io?subject=AI Feature Request&body=Hi ReadMe team,">support@readme.io</a>! If there are any AI features you’d like to see on ReadMe, let us know!

For more details, check out our <a href="https://docs.readme.com/main/docs/AskAI/" target="_blank" rel="noopener noreferrer">docs on Ask AI</a>.



AI Meets API Docs: The Why Behind /llms.txt

Build Customizable, Reusable Components | for Your Docs and Developers

How to Build a Stepper Component | with MDX & Tailwind

ReadMe's Bi-Directional Sync with GitHub

ReadMe Refactored

API Workflow Automations with Josue Negron of OneTrust

Meet the Personalities Behind Your Docs’ Personalization

How to Do Developer Marketing | That Doesn't Suck

ReadMe in Review: January 2024

API Documentation 101: Everything You Need to Get Started

ReadMe in Review: December 2023

DriveWealth's Justin Jenkins on DX & Improving Your Docs

Edit Once, Update Everywhere: Reusable Content Comes to ReadMe

ReadMe in Review: November 2023

Customize Your DX With Developer Dashboard

Take Your Docs to the Next Level With Owlbot AI

ReadMe Micro: Because Microservices Deserve Big Solutions

Take a Tour of the New Editor, Sidebar, and Page Controls 🗺️

AMA Webinar Transcript: Greg Koberger (ReadMe) and Josh Nickerson (AWS)

Webinar Recap 🎤 Developer Experience, API Performance, and More with AWS

Authenticating Into ReadMe’s CLI With 1Password and Your Fingerprint ☝️

Helping Your Users Write Succinct API Calls With "api" ✍️

Behind The Docs Q&A with Beth Favini

Give Thanks to Your Developers 🦃 Personalized API Onboarding Pages & Dark Mode

Field Notes

Find & Fix API Documentation Errors Early with ReadMe's AI Linter

Team Up with AI to Build Docs

Use ReadMe’s AI Tools to Write Great Documentation

Broken Link Checker

Improvements

Bugs Eaten by Owlbert

Older Posts

Ready for a developer hub developers love?