Overview
I spent the last two weeks of 2021 trying out a range of hosting and CI (continuous integration) providers for docs like code setups. This page sets out my requirements, and provides a quick comparison of some of the options. The section **MkDocs and Material on . . . ** contains practical guides on deploying MkDocs sites with the Material theme to Netlify, Vercel, Cloudflare Pages, and DigitalOcean App Platform. MkDocs with Material is a popular documentation toolset (and one I use for many of my own projects, including this site), making it a good test case. I've used GitHub for my tests.
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 textint, 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
Options
I've focused on the simplest possible setup and ease of use as my key requirements: for my own projects, I want to get stuff live, not endlessly wrangle environments. And for clients, I want to know I'm leaving them with something user-friendly. The trade-off is less power, especially around CI functionality.
I've ignored a few major options:
- Heroku with its GitHub integration: technically an all-in-one solution, and I did start to test it, but it proved such a faff that I immediately rejected it, at least for my own projects. However, I will revisit this option if I ever need more substantial CI functionality, as the combination of Heroku + GitHub integration + Heroku CI looks good, at least in theory.
- AWS Amplify: I don't want to get tangled up in AWS identity management and billing.
- Azure Static Web Apps: to use this with anything other than the limited default options (Gatsby, Hugo, Jekyll, VuePress, Next.js, and Nuxt.js), you have to configure GitHub Actions or Azure Pipeline. You can only use custom build commands for Node-based apps.
Quick comparison
This table shows the all-in-one options I've tested.
| Requirement | Cloudflare Pages | DigitalOcean App Platform | Netlify | Vercel |
|---|---|---|---|---|
| Automated build and deploy | Yes | Yes | Yes | Yes |
| Preview builds | Yes | No | Yes | Yes |
| Redirects | Yes (file based) | No | Yes (file based) | Yes (file based) |
| Encrypt build variables | No | Optional | No | Automatic |
| Free tier | Yes | Yes (three sites) | Yes | Yes (non-commercial) |
| Buy domains | Yes | No | Yes | Yes |
| Automatic or easily set up SSL | Yes | Yes (paid tiers only) | Yes | Yes |
| Access control | Yes for preview builds / No general login service | No | Yes (paid addon with free tier) | No (they do provide guidance) |
| Analytics | Yes (free) | No | Yes (paid addon) | No |
| Supported git providers | GitHub, GitLab | GitHub, GitLab, any public git repo | GitHub, GitLab, Bitbucket | GitHub, GitLab, Bitbucket |
I've not attempted to compare pricing here, as the offerings are too different: pricing can be affected by number of users (organisation seats), number of users (repo contributors), build minutes, bandwidth, and number of sites. Different providers use different metrics to calculate their pricing. Documentation projects also vary widely, from small teams with low usage requirements, to large teams deploying daily and seeing high traffic to their site.
Highly subjective short reviews
Although I've tried out a range of options, I've only done fairly quick tests, focusing on the features that matter for my projects. So these reviews are not comprehensive, and likley to be biased towards my personal preferences.
Cloudflare Pages
I am moving my personal projects to Cloudflare Pages, but it has some limitations and quirks:
- They don't fully support monorepos (multiple sites in one git repo). See known issues for details.
- You can't encrypt your environment variables, meaning when using Insiders your GitHub personal access token is exposed in the site dashboard.
- Their builds seem relatively slow. I've not done proper testing, but I've now tested out four platforms using the same two sites, and Cloudflare Pages is the only one with a "go make a cup of tea" build time.
However, I like Cloudflare's competitive pricing and generous free tier, as well as their free built-in analytics and preview access control. And according to comments in their Discord community, the issues I listed above are being worked on. If you are using the free Material theme (so no access token worries), and don't need monorepos, Cloudflare Pages could be a good choice now, and it sounds like it will become a really strong option in the future.
DigitalOcean App Platform
Having tried it out, I don't recommend DigitalOcean App Platform for hosting your docs projects:
- It presents as a simple deployment option, but has none of the convenience features you'd get from Vercel or Cloudflare Pages (such as automatic preview builds on pull request).
- The plans and pricing are weird. The starter plan allows for three sites, then $3 a site after that. But it comes with low build minutes (100) and outbound bandwidth (1GB) per month. It seems that DigitalOcean won't allow you to select a higher plan without adding a service or a worker:
My sense is that DigitalOcean App Platform isn't primarily targeted at static sites: it will support traditional fullstack apps, and its pricing seems designed around more complex fullstack usage.
Netlify
I have used Netlify for many years, and was a big fan. It offers hosting and basic CI/CD with a simple setup, and I love how easy it makes hosting my sites. However, I am now looking for alternatives, due to reports of pricing changes.
It seems they may be changing their pricing for some customers in a way that makes them unsuitable for projects with large numbers of contributors. Several tech writers have reported being informed by Netlify that in 2022 pricing will change from cost per Netlify organisation member to cost per GitHub contributor (it is unclear whether "contributor" is all members of the repo, or just those who contributed during a given month). As docs projects often have large numbers of contributors, this would be a massive price increase.
For solo projects this shouldn't matter, but I would prefer to be using something I could also recommend to clients, and it seems that is no longer possible with Netlify. I am also uneasy about the possibility of further changes, and how poorly this has been communicated: Netlify hasn't made any official updates to pricing (as of 24/12/2021), but there are enough people independently reporting the price increase that it's clear something is going on. The confusion is unsettling.
Vercel
Vercel is a strong option for deploying your static documentation site. If you want to avoid Netlify's pricing uncertainty, Vercel is the obvious choice (and the only one with full support for monorepos). If you want a free tier that isn't restricted to non-commercial use, Cloudflare Pages might be better.