You follow a Docs as Code approach. You're writing documentation with the same tools that you use to code. The docs are 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 ensure 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!
Step 1 - 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.
Step 2 - 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 project, the build instruction is make html and the folder that contains the generated HTML is _build/html.
5. Click on the "Deploy Site" button.
To check that the integration is working, submit a new pull request or wait until you receive a new one.
Step 3 - Review a pull request
Within the pull requests view, you should see a new Netlify CI badge labeled as netlify/deploy-preview.
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 initially, but in exchange, you won't have to deal 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.