Read the Docs quickstart with an AI coding agent

This is the AI-assisted version of the Docusaurus tutorial. Instead of clicking through templates and dashboards step by step, you delegate as much of the work as possible to an AI coding agent (Claude Code, Cursor, GitHub Copilot CLI, or any other tool that can run shell commands and call HTTP APIs).

By the end of this quickstart, you will have:

  • A Docusaurus documentation site scaffolded from scratch,

  • A public GitHub repository for it,

  • A Read the Docs project hosting the built documentation, and

  • Pull request builds enabled.

Note

The AI agent does the work that can be automated: scaffolding the site, writing the .readthedocs.yaml configuration, creating the GitHub repository, creating the Read the Docs project through the API, and triggering the first build.

A few steps still require you in a browser: creating a Read the Docs account (if you don’t have one), installing the Read the Docs GitHub App, and generating an API token. The agent will tell you when to do each, then resume.

Prerequisites

Before you start, make sure you have:

  • An AI coding agent installed locally (Claude Code, Cursor, Copilot CLI, etc.) that can read and write files and run shell commands in your project folder.

  • The GitHub CLI (gh) installed and authenticated (gh auth login).

  • Node.js 20 or newer for local testing (optional, but recommended).

  • A GitHub account.

You do not need a Read the Docs account yet — the agent will help you create one if needed.

Step 1: Scaffold the project

Create an empty folder, open your AI agent inside it, and send this prompt:

Set up a Docusaurus documentation site in this folder, ready to host on Read the Docs.

1. Scaffold a new Docusaurus site into a `docs/` subdirectory using
   `npx create-docusaurus@latest docs classic`.
2. Create a `.readthedocs.yaml` at the repository root that builds the site
   with Node.js 22 using `build.jobs`. The install step should run
   `npm install` inside `docs/`. The HTML build step should run `npm run build`
   inside `docs/`, then copy `docs/build/` into `$READTHEDOCS_OUTPUT/html/`.
3. Add a `.gitignore` covering `node_modules/` and `docs/build/`.
4. Initialize a git repository, commit everything on `main`, then create a
   public GitHub repository named `docusaurus-tutorial` with `gh repo create`
   and push.

The agent runs the scaffold, writes the configuration file, and pushes the repository. When it finishes, you will have a working Docusaurus project on GitHub and a .readthedocs.yaml like this:

.readthedocs.yaml
version: 2

build:
  os: "ubuntu-22.04"
  tools:
    nodejs: "22"
  jobs:
    install:
      - cd docs/ && npm install
    build:
      html:
        - cd docs/ && npm run build
        - mkdir --parents $READTHEDOCS_OUTPUT/html/
        - cp --recursive docs/build/* $READTHEDOCS_OUTPUT/html/

Tip

Read the agent’s plan before approving destructive commands. If you already have files in the folder, ask it to scaffold into a subfolder instead.

Step 2: Let the agent onboard you to Read the Docs

Now send this prompt to the same agent:

Help me get this project hosted on Read the Docs.

First, ask me whether I already have a Read the Docs account.

- If I don't, walk me through:
    a. Signing up at https://app.readthedocs.org/accounts/signup/ with GitHub.
    b. Installing the Read the Docs Community GitHub App at
       https://github.com/apps/read-the-docs-community for THIS repository only.
- If I do, confirm the GitHub App is installed for this repository.
  If not, walk me through installing it.

Then ask me to create a Read the Docs API token at
https://app.readthedocs.org/accounts/tokens/create/ and paste it.
Use that token with the Read the Docs API v3
(https://docs.readthedocs.com/platform/stable/api/v3.html) to:

1. POST /api/v3/projects/ to create the project, using the GitHub repository
   URL from `gh repo view --json url`. Prefix the project name with my
   GitHub username, e.g. `{username}-docusaurus-tutorial`.
2. PATCH /api/v3/projects/{slug}/ to enable pull request builds
   (`external_builds_enabled: true`) and to set a short description and
   a couple of tags like `docusaurus, documentation`.
3. POST /api/v3/projects/{slug}/versions/latest/builds/ to trigger the
   first build, then poll the build endpoint until it finishes and report
   the result.

When the build succeeds, give me the published documentation URL.
Treat the token as a secret — do not commit it or print it back to me.

The agent will pause and ask whether you already have an account. Answer honestly; if you don’t, follow the links it shares, come back, and confirm when you’re done so it can continue.

Important

Your API token is the equivalent of your password for the Read the Docs API. Paste it only into a local AI agent you trust. Tokens can be revoked any time at https://app.readthedocs.org/accounts/tokens/ if you suspect a leak.

What happens during this step

Behind the scenes, the agent calls these endpoints (all documented under API v3):

  • POST /api/v3/projects/ — creates the project linked to your GitHub repository.

  • PATCH /api/v3/projects/{slug}/ — turns on pull request builds and sets the description and tags.

  • POST /api/v3/projects/{slug}/versions/latest/builds/ — triggers the first build.

  • GET /api/v3/projects/{slug}/builds/{id}/ — polls until the build finishes.

If anything fails (for example the GitHub App is not installed, or the repository is not visible to your Read the Docs account), the API returns an explanatory error and the agent surfaces it back to you.

Step 3: Verify the result

When the build finishes, open the documentation URL the agent gave you. You should see a default Docusaurus site served from Read the Docs.

To confirm pull request builds work, ask the agent:

Create a new branch, change a heading in `docs/docs/intro.md`, push it,
and open a pull request. Then wait for the Read the Docs check and link me
to the preview build.

When the check turns green, you can review the preview the same way readers will see it.

Step 4: Configure features that need the dashboard

A handful of Read the Docs features are not yet available through the API. Ask your agent to open the right pages for you:

List the Read the Docs features I should enable from the dashboard, with
the exact URL for each, for project `{slug}`:

- Visual diff
- Link previews
- Automation rule to build only when files under `docs/` or `.readthedocs.yaml` change
- Email notifications for failed builds

For each one, the agent should point you at a URL like https://app.readthedocs.org/dashboard/{slug}/addons/ or https://app.readthedocs.org/dashboard/{slug}/rules/. Click through the link, flip the toggle or save the form, and you’re done.

See the related documentation pages if you want background: Visual diff, Link previews, Automation rules, Build notifications.

Step 5: Use the agent for ongoing maintenance

Once your project is on Read the Docs, the agent is still useful. Some prompts to keep handy:

Debug a failed build
My latest Read the Docs build failed. Fetch the build log via
`GET /api/v3/projects/{slug}/builds/{id}/` and tell me what to fix.
Change the Node.js version
Update `.readthedocs.yaml` to use Node.js 24, commit, and push.
Watch the next build and report whether it succeeded.
Add a new documentation version
Create a `1.0.x` branch from `main` on GitHub. Then use the Read the Docs
API to activate the `1.0.x` version and set `stable` as the default version
for the project.

Where to go from here

You’ve used an AI agent to scaffold a Docusaurus site, host it on Read the Docs, and wire up pull request builds — without clicking through most of the dashboard.

To keep going:

Happy documenting!