Skip to content

Overview

I've tested out a range of hosting and CI (continuous integration) providers for docs like code setups. This section includes deployment guides for my recommended options. I currently use Cloudflare Pages for my own sites.

Requirements

A docs like code setup usually involves:

  • Documents written in a markup language (such as Markdown or AsciiDoc)
  • A static site generator to build the website
  • Source files stored under version control
  • Ideally, automated testing and deployments

For any website project I have a few key requirements:

  • Automated deploys on merge to main
  • Automated preview builds on pull request
  • Simple setup ("simple" is subjective, of course)
  • A way to redirect pages to new URLs

For docs projects, I'd add:

  • Automated linting (running Vale or textlint, Alex, and a link checker on pull request).
  • Ability to encrypt build environment variables (using Material Insiders requires a GitHub access token, which I don't want to leave exposed in site settings).
  • Reasonable pricing for a large number of contributors.
  • Really simple setup: I want to be able to recommend this tooling to clients, without relying on them having devops resources available for their docs work.

And some nice-to-haves:

  • A free tier (for testing and hobby projects at least)
  • Easy domain and SSL setup

There are a few things I'm not looking for that you might want to consider:

  • Access control (if you need your docs and/or preview builds behind a login).
  • Analytics (I'm happy using Plausible, but some hosting providers offer built in options, which are convenient).
  • Support for git providers other than GitHub.

Your Product Needs Words