From c0a650f40992a0ec45c1f274f94c214f4b5d42f0 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Fri, 8 May 2026 11:56:36 +0200 Subject: [PATCH 1/7] Docs: Docusaurus tutorial --- docs/user/index.rst | 10 +- docs/user/tutorial/docusaurus.rst | 423 ++++++++++++++++++++++++++++++ docs/user/tutorial/index.rst | 4 +- 3 files changed, 432 insertions(+), 5 deletions(-) create mode 100644 docs/user/tutorial/docusaurus.rst diff --git a/docs/user/index.rst b/docs/user/index.rst index a73744b0e2d..c35b5b851f4 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -6,7 +6,8 @@ Read the Docs: documentation simplified :hidden: :caption: Getting started - Tutorial + Sphinx tutorial + Docusaurus tutorial /intro/add-project /intro/doctools /examples @@ -165,11 +166,14 @@ We have a few places for you to get started: .. descriptions here are active +:doc:`/tutorial/docusaurus` + Follow the Read the Docs tutorial for Docusaurus. + :doc:`/tutorial/index` - Follow the Read the Docs tutorial. + Follow the Read the Docs tutorial for Sphinx. :doc:`/intro/doctools` - Quick start for MkDocs and Docusaurus. + Quick start for MkDocs and other tools. :doc:`/examples` Start your journey with an example project to learn how to use Read the Docs. diff --git a/docs/user/tutorial/docusaurus.rst b/docs/user/tutorial/docusaurus.rst new file mode 100644 index 00000000000..55e59be8c3a --- /dev/null +++ b/docs/user/tutorial/docusaurus.rst @@ -0,0 +1,423 @@ +Read the Docs tutorial for Docusaurus +===================================== + +In this tutorial you will learn how to host a public `Docusaurus`_ documentation project on Read the Docs Community. +No prior experience with Docusaurus is required. + +.. _Docusaurus: https://docusaurus.io/ + +.. note:: + + Find out the `differences between Read the Docs Community and Read the Docs for Business `_. + +In the tutorial we will: + +1. Import a Docusaurus project from a GitHub repository. +2. Tailor the project's configuration. +3. Explore pull request previews, the build summary comment, visual diff, and link previews. + +If you don't have a GitHub account, you'll need to `register for a free account `_ before you start. + +Preparing your repository on GitHub +----------------------------------- + +#. `Sign in to GitHub `_ and navigate to the `Docusaurus tutorial GitHub template `_. + +#. Click the green :guilabel:`Use this template` button, then click :guilabel:`Create a new Repository`. On the new page: + + Owner + Leave the default, or change it to something suitable for a tutorial project. + Repository name + Something memorable and appropriate, for example ``docusaurus-tutorial``. + Visibility + Make sure the project is "Public", rather than "Private". + +#. Click the green :guilabel:`Create repository` button to create a public repository that you will use in this Read the Docs tutorial, containing the following files: + + ``.readthedocs.yaml`` + Read the Docs configuration file. Required. + + ``README.md`` + Description of the repository. + + ``package.json`` + Node.js project metadata, including the Docusaurus dependencies. + + ``docusaurus.config.js`` + Docusaurus site configuration. + + ``sidebars.js`` + Defines the sidebar structure for the documentation. + + ``docs/`` + Directory holding the Markdown source files of the documentation. + +Creating a Read the Docs account +-------------------------------- + +To create a Read the Docs account: +navigate to the `Sign Up page `_ +and choose the option :guilabel:`Sign up with GitHub`. +On the authorization page, click the green :guilabel:`Authorize readthedocs` button. + +.. figure:: /_static/images/tutorial/github-authorization.png + :width: 60% + :align: center + :alt: GitHub authorization page + + GitHub authorization page + +.. note:: + + Read the Docs needs elevated permissions to perform certain operations + that ensure that the workflow is as smooth as possible, + like installing :term:`webhooks `. + If you want to learn more, + check out :ref:`reference/git-integration:permissions for connected accounts`. + +After that, you will be redirected to Read the Docs to confirm your e-mail and username. Click the :guilabel:`Sign Up »` button to create your account and +open your :term:`dashboard`. + +When you have clicked the link in your email from Read the Docs to "verify your email address" and finalize the process, your Read the Docs account will be ready to create your first project. + +Importing the project to Read the Docs +-------------------------------------- + +To import your GitHub project to Read the Docs: + +#. Click the :guilabel:`Import a Project` button on your `dashboard `_. + +#. Click the |:heavy_plus_sign:| button to the right of your ``docusaurus-tutorial`` project. If the list of repositories is empty, click the |:arrows_counterclockwise:| button. + +#. Enter some details about your Read the Docs project: + + Name + The name of the project, used to create a unique subdomain for each project. + so it is better if you prepend your username, + for example ``{username}-docusaurus-tutorial``. + + Repository URL + The URL that contains the documentation source. Leave the automatically filled value. + + Default branch + Name of the default branch of the project, leave it as ``main``. + + Then click the :guilabel:`Next` button to create the project and open the :term:`project home`. + +You just created your first Docusaurus project on Read the Docs! |:tada:| + +Checking the first build +------------------------ + +Read the Docs will build your project documentation right after you create it. + +To see the build logs: + +#. Click the :guilabel:`Your documentation is building` link on the :term:`project home`. + + - If the build has not finished by the time you open it, you will see a spinner next to a "Installing" or "Building" indicator, meaning that it is still in progress. + - If the build has finished, you'll see a green "Build completed" indicator, the completion date, the elapsed time, and a link to the generated documentation. + +#. Click on :guilabel:`View docs` to see your documentation live! + +.. note:: + + Advertisement is one of our main sources of revenue. + If you want to learn more about how do we fund our operations + and explore options to go ad-free, + check out our `Sustainability page `_. + + If you don't see the ad, you might be using an ad blocker. + Our EthicalAds network respects your privacy, doesn't target you, + and tries to be as unobtrusive as possible, + so we would like to kindly ask you to :doc:`not block us ` |:heart:| + +Configuring the project +----------------------- + +To update the project description and configure the notification settings: + +#. Navigate back to the :term:`project page` and click the :guilabel:`⚙ Admin` button, to open the Settings page. + +#. Update the project description with a short summary of what the documentation is about. + +#. Set a project homepage and add a couple of public project tags such as ``docusaurus, documentation``. + +#. To get a notification if the build fails, click the :guilabel:`Email Notifications` link on the left, add your email address, and click the :guilabel:`Add` button. + +Triggering builds from pull requests +------------------------------------ + +Read the Docs can :doc:`trigger builds from GitHub pull requests ` +and show you a preview of the documentation with those changes. + +To trigger builds from pull requests: + +#. Click the :guilabel:`Settings` link on the left under the :guilabel:`⚙ Admin` menu, check the "Build pull requests for this project" checkbox, and click the :guilabel:`Save` button at the bottom of the page. + +#. Make some changes to your documentation: + + #. Navigate to your GitHub repository, locating the file ``docs/intro.md``, and clicking on the |:pencil2:| icon on the top-right with the tooltip "Edit this file" to open a web editor. + + #. In the editor, add the following sentence to the file: + + .. code-block:: markdown + :caption: docs/intro.md + + This documentation is hosted on Read the Docs. + + #. Write an appropriate commit message, choose the "Create a **new branch** for this commit and start a pull request" option. + + #. Click the green :guilabel:`Propose changes` button to open the new pull request page, then click the :guilabel:`Create pull request` button below the description. + +After opening the pull request, a Read the Docs check will appear +indicating that it is building the documentation for that pull request. +If you click the :guilabel:`Details` link while your project is building +the build log will be opened. After building, this link opens the documentation directly. + +Reviewing the pull request preview +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once the pull request build finishes, Read the Docs adds a comment to the pull request with a build overview that includes: + +- A link to the documentation preview. +- The list of files that changed between the pull request and the latest version of the documentation. + +This summary saves you from clicking through the build log to find the preview, and helps you confirm at a glance that the changes you expected are the ones being deployed. + +.. note:: + + The build overview comment is only available for projects connected to a :ref:`reference/git-integration:GitHub App`. + See :doc:`/pull-requests` for details on each of the pull request features. + +Comparing changes with visual diff +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Reading a Markdown diff is fine for prose, +but it doesn't always tell you what the page will *look* like once rendered. +:doc:`Visual diff ` highlights the changes directly on the rendered documentation pages, +so you can review pull requests the same way readers will see them. + +To enable visual diff: + +#. Go to the :guilabel:`Settings` tab of your project. +#. Click :guilabel:`Addons`, then :guilabel:`Visual diff`. +#. Check :guilabel:`Enable visual diff` and click :guilabel:`Save`. + +Open the pull request preview again. A new dropdown appears at the top right of the page listing every file that changed in the pull request. Pick a file to jump to it, then click :guilabel:`Show diff` (or press the ``d`` hotkey) to highlight the additions and deletions inline. Use the up/down arrows to step through each chunk. + +Adding a configuration file +--------------------------- + +The Admin tab of the :term:`project home` has some *global* configuration settings for your project. + +Build process configuration settings live in the ``.readthedocs.yaml`` :doc:`configuration file `, in your Git repository, which means it can be different for every version or branch of your project. + +Docusaurus is a Node.js application, so Read the Docs builds it by running a sequence of commands defined under :ref:`build.jobs `. The template repository ships with this file: + +.. code-block:: yaml + :caption: .readthedocs.yaml + + version: 2 + + build: + os: "ubuntu-22.04" + tools: + nodejs: "18" + jobs: + install: + - npm install + build: + html: + - npm run build + - mkdir --parents $READTHEDOCS_OUTPUT/html/ + - cp --recursive build/* $READTHEDOCS_OUTPUT/html/ + +The :doc:`purpose of each key ` is: + +``version`` + Required, specifies :doc:`version 2 of the configuration file `. + +``build.os`` + Required, specifies the Docker image used to build the documentation. + +``build.tools.nodejs`` + Specifies the :ref:`Node.js version ` used during the build. + +``build.jobs.install`` + Commands run during the install step. Here we install Docusaurus and its dependencies with ``npm install``. + +``build.jobs.build.html`` + Commands run to produce the HTML output. We run ``npm run build`` to invoke Docusaurus, then copy the generated ``build/`` directory into ``$READTHEDOCS_OUTPUT/html/``, where Read the Docs picks it up. + +.. tip:: + + ``build.jobs`` is the recommended way to override the build process for tools that do not have first-class Read the Docs support. + Each step (``install``, ``build.html``, ``post_build``, etc.) can be overridden independently, + which keeps the rest of Read the Docs' build pipeline intact. + +Using a different Node.js version +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To build your project with Node.js 20 instead of 18, edit the ``.readthedocs.yaml`` file and change the Node.js version like this: + +.. code-block:: yaml + :caption: .readthedocs.yaml + :emphasize-lines: 6 + + version: 2 + + build: + os: "ubuntu-22.04" + tools: + nodejs: "20" + jobs: + install: + - npm install + build: + html: + - npm run build + - mkdir --parents $READTHEDOCS_OUTPUT/html/ + - cp --recursive build/* $READTHEDOCS_OUTPUT/html/ + +After you commit these changes, go back to your project home, navigate to the "Builds" page, and open the new build that just started. You will see in the build logs that the new toolchain version was used to install the dependencies and build the site. + +Versioning documentation +------------------------ + +Read the Docs supports having :doc:`several versions of your documentation `, +in the same way that you have several versions of your code. +By default, it creates a ``latest`` version +that points to the default branch of your version control system +(``main`` in the case of this tutorial), +and that's why the URLs of your HTML documentation contain the string ``/latest/``. + +Creating a new version of your documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Read the Docs automatically creates documentation versions from GitHub branches and tags that :ref:`follow some rules ` about looking like version numbers, such as ``1.0``, ``2.0.3`` or ``4.x``. + +To create version ``1.0`` of your code, and consequently of your documentation: + +#. Navigate to your GitHub repository, click the branch selector, type ``1.0.x``, and click "Create branch: 1.0.x from 'main'". + +#. Check that you now have version ``1.0.x`` in your :term:`project home`, click on the :guilabel:`Versions` button, and under "Active Versions" you will see two entries: + + - The ``latest`` version, pointing to the ``main`` branch. + - A new ``stable`` version, pointing to the ``origin/1.0.x`` branch. + +When you created your branch, Read the Docs created a new special version called ``stable`` pointing to it. Once it builds, it appears in the :term:`flyout menu`. + +Setting stable as the default +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To set ``stable`` as the *default version*, rather than ``latest``, so that users see the ``stable`` documentation when they visit the :term:`root URL` of your documentation: + +#. In the :guilabel:`⚙ Admin` menu of your project home, go to the :guilabel:`Settings` link, choose ``stable`` in the "Default version" dropdown, and hit :guilabel:`Save` at the bottom. + +Modifying versions +~~~~~~~~~~~~~~~~~~ + +Both ``latest`` and ``stable`` are now *active*, which means that they are visible to readers and new builds can be triggered for them. +In addition to these, Read the Docs also created an *inactive* ``1.0.x`` version, which always points to the ``1.0.x`` branch of your repository. + +To activate the ``1.0.x`` version: + +#. On your :term:`project home`, go to "Versions", locate ``1.0.x`` under "Activate a version", and click the :guilabel:`Activate` button. + +#. On the "Activate" page with "Active" and "Hidden" checkboxes, check only "Active" and click :guilabel:`Save`. + +.. note:: + + Read more about :ref:`hidden versions ` + in our documentation. + +Enabling link previews for your readers +--------------------------------------- + +:doc:`Link previews ` show readers the content of an internal link when they hover over it, +so they can decide whether to follow the link without losing their place. + +To enable link previews: + +#. Go to your project's :term:`dashboard` and click the project name. +#. Go to :guilabel:`Settings`, then in the left bar, go to :guilabel:`Addons`. +#. Open :guilabel:`Link previews` and check :guilabel:`Enabled`. +#. Save your settings -- a rebuild of your project isn't required. + +Open your published documentation and hover over any internal link. A small popup appears with the target page's content. Link previews only render for internal links inside the main documentation content, so navigation bars and external links are unaffected. + +Getting project insights +------------------------ + +Once your project is up and running, you will probably want to understand +how readers are using your documentation, addressing some common questions like: + +- What are the most visited pages? +- What are the most frequently used search terms? +- Are readers finding what they are looking for? + +Read the Docs has traffic and search analytics tools to help you find answers to these questions. + +Understanding traffic analytics +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Traffic Analytics view gives you a simple overview of how your readers browse your documentation. +It respects visitors' privacy by not storing identifying information about them. + +This page shows the most viewed documentation pages of the past 30 days, +plus a visualization of the daily views during that period. + +To see the Traffic Analytics view, go back to the :term:`project page`, +click the :guilabel:`⚙ Admin` button, and then click the :guilabel:`Traffic Analytics` section. +You will see the list of pages in descending order of visits, alongside a daily-views chart. + +You can also download this data in :abbr:`CSV (Comma-Separated Values)` format for closer inspection +by scrolling to the bottom of the page and clicking the :guilabel:`Download all data` button. + +Understanding search analytics +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Read the Docs also shows :doc:`what terms your readers are searching for `. +This can inform decisions about what areas to focus on, +or what parts of your project are less understood or harder to find. + +To view search analytics, go to the :guilabel:`⚙ Admin` section of your project page +and click the :guilabel:`Search Analytics` section. +You will see a table with the most searched queries, +how many results each query returned, and how many times it was searched, +plus a visualization of the daily number of search queries during the past 30 days. + +Like Traffic Analytics, you can download the whole dataset in CSV format +by clicking the :guilabel:`Download all data` button. + +Where to go from here +--------------------- + +This is the end of the tutorial. You have accomplished a lot: + +#. Created a Docusaurus project from a GitHub template. +#. Connected it to Read the Docs. +#. Built its HTML documentation. +#. Customized the build process with ``build.jobs``. +#. Reviewed pull requests with the build summary comment and visual diff. +#. Enabled link previews for your readers. +#. Added new documentation versions. +#. Browsed the project analytics. + +Nice work! + +Here are some resources to help you continue learning about documentation +and Read the Docs: + +- Learn more about the platform :doc:`features `. +- Read the :doc:`Docusaurus deployment guide ` for more advanced configuration tips. +- See a list of Read the Docs :doc:`/examples`. +- Learn how to do specific tasks in the :doc:`/guides/index`. +- Learn about private project support and other enterprise features + in :doc:`our commercial service guide `. +- Join a global community of fellow `documentarians ` in `Write the Docs `_ and + :doc:`its Slack workspace `. +- Contribute to Read the Docs in :doc:`rtd-dev:contribute`, we appreciate it! + +Happy documenting! diff --git a/docs/user/tutorial/index.rst b/docs/user/tutorial/index.rst index 88d6d0413eb..917f5f792b2 100644 --- a/docs/user/tutorial/index.rst +++ b/docs/user/tutorial/index.rst @@ -1,5 +1,5 @@ -Read the Docs tutorial -====================== +Read the Docs tutorial for Sphinx +================================= In this tutorial you will learn how to host a public documentation project on Read the Docs Community. From 3fbcdb310a533afb551e121932f9b34ed8abf182 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Fri, 8 May 2026 12:09:40 +0200 Subject: [PATCH 2/7] Switch OAuth for GitHub App --- docs/user/tutorial/docusaurus.rst | 28 ++++++++++++---------------- 1 file changed, 12 insertions(+), 16 deletions(-) diff --git a/docs/user/tutorial/docusaurus.rst b/docs/user/tutorial/docusaurus.rst index 55e59be8c3a..b25c579d1db 100644 --- a/docs/user/tutorial/docusaurus.rst +++ b/docs/user/tutorial/docusaurus.rst @@ -55,30 +55,26 @@ Preparing your repository on GitHub Creating a Read the Docs account -------------------------------- -To create a Read the Docs account: +To create a Read the Docs account, navigate to the `Sign Up page `_ and choose the option :guilabel:`Sign up with GitHub`. -On the authorization page, click the green :guilabel:`Authorize readthedocs` button. -.. figure:: /_static/images/tutorial/github-authorization.png - :width: 60% - :align: center - :alt: GitHub authorization page +Confirm your e-mail and username on Read the Docs, then click the :guilabel:`Sign Up »` button to create your account and open your :term:`dashboard`. - GitHub authorization page +When you click the link in the verification email from Read the Docs, your account will be ready to create your first project. -.. note:: +Installing the Read the Docs GitHub App +--------------------------------------- - Read the Docs needs elevated permissions to perform certain operations - that ensure that the workflow is as smooth as possible, - like installing :term:`webhooks `. - If you want to learn more, - check out :ref:`reference/git-integration:permissions for connected accounts`. +For Read the Docs to access your ``docusaurus-tutorial`` repository, +install the `Read the Docs Community GitHub App `_: -After that, you will be redirected to Read the Docs to confirm your e-mail and username. Click the :guilabel:`Sign Up »` button to create your account and -open your :term:`dashboard`. +#. Open the GitHub App page and click :guilabel:`Install`. +#. Choose the GitHub account or organization that owns your ``docusaurus-tutorial`` repository. +#. Select :guilabel:`Only select repositories` and pick ``docusaurus-tutorial``. You can grant access to additional repositories at any time from your GitHub settings. +#. Click :guilabel:`Install` to complete the setup. -When you have clicked the link in your email from Read the Docs to "verify your email address" and finalize the process, your Read the Docs account will be ready to create your first project. +See :ref:`reference/git-integration:GitHub App` for more details on what the GitHub App can do and the permissions it requests. Importing the project to Read the Docs -------------------------------------- From 340aef5f8636f75f46ebdab6cfe7fae74768c659 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Fri, 8 May 2026 12:40:59 +0200 Subject: [PATCH 3/7] Updates --- docs/user/tutorial/docusaurus.rst | 38 +++++++++++++------------------ 1 file changed, 16 insertions(+), 22 deletions(-) diff --git a/docs/user/tutorial/docusaurus.rst b/docs/user/tutorial/docusaurus.rst index b25c579d1db..c9949d0dc46 100644 --- a/docs/user/tutorial/docusaurus.rst +++ b/docs/user/tutorial/docusaurus.rst @@ -57,11 +57,9 @@ Creating a Read the Docs account To create a Read the Docs account, navigate to the `Sign Up page `_ -and choose the option :guilabel:`Sign up with GitHub`. +and choose the option :guilabel:`Sign up with GitHub` and then :guilabel:`Sign up using GitHub App`. -Confirm your e-mail and username on Read the Docs, then click the :guilabel:`Sign Up »` button to create your account and open your :term:`dashboard`. - -When you click the link in the verification email from Read the Docs, your account will be ready to create your first project. +.. TODO: we need a way to install the GitHub App upfront before adding a project Installing the Read the Docs GitHub App --------------------------------------- @@ -74,16 +72,19 @@ install the `Read the Docs Community GitHub App `_. +#. Click the :guilabel:`Add project` button on your `dashboard `_. -#. Click the |:heavy_plus_sign:| button to the right of your ``docusaurus-tutorial`` project. If the list of repositories is empty, click the |:arrows_counterclockwise:| button. +#. Search for your ``docusaurus-tutorial`` repository, select it, and click :guilabel:`Continue`. #. Enter some details about your Read the Docs project: @@ -100,6 +101,8 @@ To import your GitHub project to Read the Docs: Then click the :guilabel:`Next` button to create the project and open the :term:`project home`. + #. Click :guilabel:`This file exists` to trigger the first build of your documentation. + You just created your first Docusaurus project on Read the Docs! |:tada:| Checking the first build @@ -107,6 +110,9 @@ Checking the first build Read the Docs will build your project documentation right after you create it. +.. TODO: update this since the UI has changed +.. 1. click on the version +.. 2. click on the build that just started To see the build logs: #. Click the :guilabel:`Your documentation is building` link on the :term:`project home`. @@ -116,18 +122,6 @@ To see the build logs: #. Click on :guilabel:`View docs` to see your documentation live! -.. note:: - - Advertisement is one of our main sources of revenue. - If you want to learn more about how do we fund our operations - and explore options to go ad-free, - check out our `Sustainability page `_. - - If you don't see the ad, you might be using an ad blocker. - Our EthicalAds network respects your privacy, doesn't target you, - and tries to be as unobtrusive as possible, - so we would like to kindly ask you to :doc:`not block us ` |:heart:| - Configuring the project ----------------------- From 563db011ab298e0dbaf8cb978a274925a29036ee Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Fri, 8 May 2026 13:31:01 +0200 Subject: [PATCH 4/7] More updates to Docusaurus tutorial --- docs/user/tutorial/docusaurus.rst | 42 ++++++++++++++----------------- 1 file changed, 19 insertions(+), 23 deletions(-) diff --git a/docs/user/tutorial/docusaurus.rst b/docs/user/tutorial/docusaurus.rst index c9949d0dc46..9270254e3da 100644 --- a/docs/user/tutorial/docusaurus.rst +++ b/docs/user/tutorial/docusaurus.rst @@ -40,17 +40,10 @@ Preparing your repository on GitHub ``README.md`` Description of the repository. - ``package.json`` - Node.js project metadata, including the Docusaurus dependencies. - - ``docusaurus.config.js`` - Docusaurus site configuration. - - ``sidebars.js`` - Defines the sidebar structure for the documentation. - ``docs/`` - Directory holding the Markdown source files of the documentation. + Directory holding the Docusaurus project, including + ``package.json``, ``docusaurus.config.js``, ``sidebars.js``, + and the Markdown source files under ``docs/pages/``. Creating a Read the Docs account -------------------------------- @@ -147,12 +140,12 @@ To trigger builds from pull requests: #. Make some changes to your documentation: - #. Navigate to your GitHub repository, locating the file ``docs/intro.md``, and clicking on the |:pencil2:| icon on the top-right with the tooltip "Edit this file" to open a web editor. + #. Navigate to your GitHub repository, locating the file ``docs/pages/intro.mdx``, and clicking on the |:pencil2:| icon on the top-right with the tooltip "Edit this file" to open a web editor. #. In the editor, add the following sentence to the file: .. code-block:: markdown - :caption: docs/intro.md + :caption: docs/pages/intro.mdx This documentation is hosted on Read the Docs. @@ -213,15 +206,15 @@ Docusaurus is a Node.js application, so Read the Docs builds it by running a seq build: os: "ubuntu-22.04" tools: - nodejs: "18" + nodejs: "20" jobs: install: - - npm install + - cd docs/ && npm install build: html: - - npm run build + - cd docs/ && npm run build - mkdir --parents $READTHEDOCS_OUTPUT/html/ - - cp --recursive build/* $READTHEDOCS_OUTPUT/html/ + - cp --recursive docs/build/* $READTHEDOCS_OUTPUT/html/ The :doc:`purpose of each key ` is: @@ -235,10 +228,13 @@ The :doc:`purpose of each key ` is: Specifies the :ref:`Node.js version ` used during the build. ``build.jobs.install`` - Commands run during the install step. Here we install Docusaurus and its dependencies with ``npm install``. + Commands run during the install step. The Docusaurus project lives under ``docs/``, + so we ``cd`` into it and run ``npm install`` to install Docusaurus and its dependencies. ``build.jobs.build.html`` - Commands run to produce the HTML output. We run ``npm run build`` to invoke Docusaurus, then copy the generated ``build/`` directory into ``$READTHEDOCS_OUTPUT/html/``, where Read the Docs picks it up. + Commands run to produce the HTML output. We ``cd docs/`` and run ``npm run build`` + to invoke Docusaurus, then copy the generated ``docs/build/`` directory into + ``$READTHEDOCS_OUTPUT/html/``, where Read the Docs picks it up. .. tip:: @@ -249,7 +245,7 @@ The :doc:`purpose of each key ` is: Using a different Node.js version ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To build your project with Node.js 20 instead of 18, edit the ``.readthedocs.yaml`` file and change the Node.js version like this: +To build your project with Node.js 22 instead of 20, edit the ``.readthedocs.yaml`` file and change the Node.js version like this: .. code-block:: yaml :caption: .readthedocs.yaml @@ -260,15 +256,15 @@ To build your project with Node.js 20 instead of 18, edit the ``.readthedocs.yam build: os: "ubuntu-22.04" tools: - nodejs: "20" + nodejs: "22" jobs: install: - - npm install + - cd docs/ && npm install build: html: - - npm run build + - cd docs/ && npm run build - mkdir --parents $READTHEDOCS_OUTPUT/html/ - - cp --recursive build/* $READTHEDOCS_OUTPUT/html/ + - cp --recursive docs/build/* $READTHEDOCS_OUTPUT/html/ After you commit these changes, go back to your project home, navigate to the "Builds" page, and open the new build that just started. You will see in the build logs that the new toolchain version was used to install the dependencies and build the site. From 1059893447d9c535e4077bb0ab505d0cd0c187d6 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Fri, 8 May 2026 13:38:15 +0200 Subject: [PATCH 5/7] Add blank line --- docs/user/tutorial/docusaurus.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/user/tutorial/docusaurus.rst b/docs/user/tutorial/docusaurus.rst index 9270254e3da..ddde5098ab3 100644 --- a/docs/user/tutorial/docusaurus.rst +++ b/docs/user/tutorial/docusaurus.rst @@ -106,6 +106,7 @@ Read the Docs will build your project documentation right after you create it. .. TODO: update this since the UI has changed .. 1. click on the version .. 2. click on the build that just started + To see the build logs: #. Click the :guilabel:`Your documentation is building` link on the :term:`project home`. From 641b1f5acc95fa6aca6d630e297343150b512107 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Fri, 8 May 2026 13:48:24 +0200 Subject: [PATCH 6/7] Promote Automation rules more --- docs/user/tutorial/docusaurus.rst | 83 +++++++++++++++++++------------ 1 file changed, 51 insertions(+), 32 deletions(-) diff --git a/docs/user/tutorial/docusaurus.rst b/docs/user/tutorial/docusaurus.rst index ddde5098ab3..4463fc7705a 100644 --- a/docs/user/tutorial/docusaurus.rst +++ b/docs/user/tutorial/docusaurus.rst @@ -334,49 +334,68 @@ To enable link previews: Open your published documentation and hover over any internal link. A small popup appears with the target page's content. Link previews only render for internal links inside the main documentation content, so navigation bars and external links are unaffected. -Getting project insights ------------------------- +Building only when documentation changes +---------------------------------------- + +If your repository hosts both your application code and its documentation, +Read the Docs rebuilds your docs on every push by default — even when the +change doesn't touch any documentation files. +:doc:`Automation rules ` can gate builds on the contents +of the webhook event from GitHub, so you only spend build time on commits and +pull requests that actually affect the documentation. + +To create a rule that builds your project only when documentation files change: + +#. From the :term:`project home`, open the :guilabel:`⚙ Admin` menu and select + :guilabel:`Automation Rules`, then click :guilabel:`Add Rule`. + +#. Configure the rule: -Once your project is up and running, you will probably want to understand -how readers are using your documentation, addressing some common questions like: + Description + Something memorable, for example ``Build only on documentation changes``. -- What are the most visited pages? -- What are the most frequently used search terms? -- Are readers finding what they are looking for? + Match + ``Any version``. -Read the Docs has traffic and search analytics tools to help you find answers to these questions. + Version types + Check :guilabel:`Tag`, :guilabel:`Branch`, and :guilabel:`Pull request` + so the rule applies to every kind of build. -Understanding traffic analytics -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Changed files + One pattern per line: -The Traffic Analytics view gives you a simple overview of how your readers browse your documentation. -It respects visitors' privacy by not storing identifying information about them. + .. code-block:: text -This page shows the most viewed documentation pages of the past 30 days, -plus a visualization of the daily views during that period. + docs/* + .readthedocs.yaml -To see the Traffic Analytics view, go back to the :term:`project page`, -click the :guilabel:`⚙ Admin` button, and then click the :guilabel:`Traffic Analytics` section. -You will see the list of pages in descending order of visits, alongside a daily-views chart. + Action + ``Trigger build for version``. -You can also download this data in :abbr:`CSV (Comma-Separated Values)` format for closer inspection -by scrolling to the bottom of the page and clicking the :guilabel:`Download all data` button. +#. Click :guilabel:`Save` to create the rule. -Understanding search analytics -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +From now on, Read the Docs only triggers a build when the push or pull request +modifies a file under ``docs/`` or the ``.readthedocs.yaml`` configuration. +Pushes that only touch application code, tests, or unrelated files no longer +trigger a documentation build. -Read the Docs also shows :doc:`what terms your readers are searching for `. -This can inform decisions about what areas to focus on, -or what parts of your project are less understood or harder to find. +.. important:: -To view search analytics, go to the :guilabel:`⚙ Admin` section of your project page -and click the :guilabel:`Search Analytics` section. -You will see a table with the most searched queries, -how many results each query returned, and how many times it was searched, -plus a visualization of the daily number of search queries during the past 30 days. + Once a rule with the :guilabel:`Trigger build for version` action exists, + builds are **gated** by automation rules: if no rule matches the incoming + webhook event, no build runs. Make sure your patterns cover every path + that should rebuild the docs before relying on this in production. + +.. note:: + + Webhook-filter automation rules are only available for projects connected + through the :ref:`reference/git-integration:GitHub App`. + +.. seealso:: -Like Traffic Analytics, you can download the whole dataset in CSV format -by clicking the :guilabel:`Download all data` button. + :doc:`/automation-rules` + Full reference for automation rules, including filters by commit message + and pull request label. Where to go from here --------------------- @@ -390,7 +409,7 @@ This is the end of the tutorial. You have accomplished a lot: #. Reviewed pull requests with the build summary comment and visual diff. #. Enabled link previews for your readers. #. Added new documentation versions. -#. Browsed the project analytics. +#. Configured an automation rule to build only when documentation changes. Nice work! From bfa5c5a81f0368f00adc22e244573e9a32f51724 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Wed, 13 May 2026 23:31:55 +0200 Subject: [PATCH 7/7] Getting started with AI --- docs/user/index.rst | 4 + docs/user/tutorial/docusaurus-with-ai.rst | 236 ++++++++++++++++++++++ 2 files changed, 240 insertions(+) create mode 100644 docs/user/tutorial/docusaurus-with-ai.rst diff --git a/docs/user/index.rst b/docs/user/index.rst index c35b5b851f4..1b2608d49e1 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -8,6 +8,7 @@ Read the Docs: documentation simplified Sphinx tutorial Docusaurus tutorial + Quickstart with an AI agent /intro/add-project /intro/doctools /examples @@ -166,6 +167,9 @@ We have a few places for you to get started: .. descriptions here are active +:doc:`/tutorial/docusaurus-with-ai` + Use an AI coding agent (Claude Code, Cursor, etc.) to scaffold and host your docs. + :doc:`/tutorial/docusaurus` Follow the Read the Docs tutorial for Docusaurus. diff --git a/docs/user/tutorial/docusaurus-with-ai.rst b/docs/user/tutorial/docusaurus-with-ai.rst new file mode 100644 index 00000000000..2852b415362 --- /dev/null +++ b/docs/user/tutorial/docusaurus-with-ai.rst @@ -0,0 +1,236 @@ +Read the Docs quickstart with an AI coding agent +================================================ + +This is the AI-assisted version of the :doc:`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. + +.. _Docusaurus: https://docusaurus.io/ + +.. 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 :doc:`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: + +.. code-block:: text + + 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: + +.. code-block:: yaml + :caption: .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: + +.. code-block:: text + + 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 :doc:`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: + +.. code-block:: text + + 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 :doc:`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: + +.. code-block:: text + + 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: +:doc:`Visual diff `, :doc:`Link previews `, +:doc:`Automation rules `, +:doc:`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 + .. code-block:: text + + 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 + .. code-block:: text + + 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 + .. code-block:: text + + 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: + +- Compare what the agent did with the manual :doc:`Docusaurus tutorial ` + so you understand the pieces it touched. +- Read the :doc:`API v3 reference ` to see what else the agent can automate. +- Skim :doc:`/intro/doctools` if you want to try the same pattern with a different + documentation generator. +- Browse :doc:`/guides/index` for deeper how-to guides on specific features. + +Happy documenting!