You follow a Docs as Code approach. You are writing documentation with the same tools that are used to code. Even the docs are already hosted on GitHub, and the revision process happens through pull requests.
Nevertheless, every time you review new contributions, you have to download and build the documentation locally to make sure that the images and markup annotations did not break the page. If this is the case, let's see how to automate the build of your docs PR using Netlify CI! I'll be using Sphinx for building the docs, but you can follow the same approach with any other static site generator.
Create a Netlify account
If you haven't heard about Netlify before, the service automatically builds and publishes a website for every new commit in a Git repository.
Netlify works similarly to GitHub Pages. The main difference is that Netlify also deploys a website for every pull request, and not only when the
gh-pages branch is updated. Netlify is a paid service but they also offer a starter plan for experimentation that comes with monthly credits for free.
To create a new account, open app.netlify.com/signup, and complete the registration steps, preferably with your GitHub account.
Connect Netlify to the docs repository
Now that you have created an account, let's link Netlify and the docs repository.
1. From the Dashboard, click on the "New Site from Git" button in the upper right-hand corner.
2. Under "Continuous Deployment", select GitHub and authorize your account. You might need to grant permission to an organization if the repository is not under your account.
3. Select the docs repository you want to automate the previews.
4. Go to "Build Settings", write the command you use to build the docs and the name of the directory where the output is generated. In the case of my particular project, the build instruction is
make html and the folder that contains the generated HTML is
5. Click on the "Deploy Site" button.
To check that the integration is working, you will need to submit a new pull request or wait until you receive a new one.
Review a pull request
Within the pull requests view, you should see a new Netlify CI badge labeled as
Once the build passes (or fails), click on the "Details" link. If everything goes well, you should see the preview of the pull requests.
Putting all together
It's normal if the build does not pass the first time. Configuring a CI system takes some time in the beginning, but in exchange, you won't have to cope with repetitive tasks anymore. Check on Netlify why the build has failed, apply the fix, and try to build again!
I sincerely hope that the automation of pull requests previews ensures that your docs always look perfect and saves you and your team some precious time.