Docusaurus
Docusaurus is a static-site generator that builds a single-page application with fast client-side navigation and out-of-the-box documentation features.
Minimal configuration required to build a Docusaurus project on Read the Docs looks like this, specifying a Node.js toolchain on Ubuntu, using multiple build jobs to install the requirements, build the site, and copy the output to $READTHEDOCS_OUTPUT:
version: 2
build:
os: "ubuntu-22.04"
tools:
nodejs: "18"
jobs:
# "docs/" was created following the Docusaurus tutorial:
# npx create-docusaurus@latest docs classic
# but you can just use your existing Docusaurus site
install:
# Install Docusaurus dependencies
- cd docs/ && npm install
build:
html:
# Build the site
- cd docs/ && npm run build
# Copy generated files into Read the Docs directory
- mkdir --parents $READTHEDOCS_OUTPUT/html/
- cp --recursive docs/build/* $READTHEDOCS_OUTPUT/html/
Limitations
Feature |
Description |
Supported |
|---|---|---|
Search |
Provides full-text search capabilities. |
Not supported |
Files changed |
Ability to see what HTML files change in pull request previews. |
Not supported |
Quick start
If you have an existing Docusaurus project you want to host on Read the Docs, check out our Adding a documentation project guide.
If you’re new to Docusaurus, check out the official Fast Track guide.
Configuring Docusaurus and Read the Docs Addons
For optimal integration with Read the Docs, make the following optional configuration changes to your Docusaurus config.
Set the canonical URL
A canonical URL allows you to specify the preferred version of a web page to prevent duplicated content.
Set your Docusaurus url to your Read the Docs canonical URL using dotenv and a Read the Docs environment variable:
import 'dotenv/config';
export default {
url: process.env.READTHEDOCS_CANONICAL_URL,
};