Override the build process completely with
We are happy to announce a new beta feature that allows users to override the Read the Docs build process completely. We previously talked about executing custom commands in-between the Read the Docs build process. That approach is not sufficient for projects with a heavily customized build process, or those that want to use a different documentation tool like Pelican, Docsify and Docusaurus for their documentation. Some of which were not able to use our platform at all. Until now! We have good news for them!
The new configuration file option
build.commands allows projects to only execute exactly the commands they want.
No more. No less.
This means that Read the Docs won’t execute any of the default commands behind the scenes.
You have 100% control over the build process.
How does it work?¶
To use the new beta feature,
you can specify all the commands the build process requires under the
build.commands config key.
Finally, move the resulting documentation artifacts into the
Read the Docs will upload and host all the content of that folder ✨
Here is simple example that builds the Docusaurus tutorial:
version: 2 build: os: ubuntu-22.04 tools: nodejs: "18" commands: # "docs/" directory was created using the command to create the site: # npx create-docusaurus@latest docs classic # # Install Docusaurus dependencies - cd docs/ && npm install # Build the site - cd docs/ && npm run build # Copy generated files into Read the Docs directory - mkdir --parents _readthedocs/html/ - cp --recursive docs/build/* _readthedocs/html/
The resulting documentation lives at https://test-builds.readthedocs.io/en/docusaurus/.
If you want to read more about
read the full documentation.
This feature is still in beta and has some limitation currently.
We are working to make
build.commands more integrated into our platform.
One major missing feature is the flyout, which gives access to downloads, versions and other functionality.
We are actively working on improving this feature,
and we will publishing more content about this in the next months.
Try it out and give us feedback!¶
We want to continue improving this beta feature. It has lot of potential and we want to develop it in a way that’s useful for our users. Please, give it a try and let us know how are you using it and if it’s missing something for your use case.