Build a Manual with MkDocs #4: Deploy on Cloudflare Pages and Connect a Domain

Framework MkDocs Documentation Static Site
3 min read

By the time you reach #3, you have docs that look good locally. But localhost is visible only to you. In this post we send those docs out so anyone can reach them by address.

This series, Build a Manual with MkDocs, runs in six parts.

  • #1: From Install to Your First Doc
  • #2: nav and Search — Shaping the Information Structure of Your Docs
  • #3: Writing Content — Code Blocks, Mermaid, and Admonitions
  • #4: Deploy on Cloudflare Pages and Connect a Domain ← this post
  • #5: Multilingual Docs and Versioning
  • #6: Maintenance — Search, Accessibility, and Documentation Culture

In this post we’ll cover pinning dependencies and pushing to GitHub, connecting to Cloudflare Pages and setting up the build, and attaching a custom domain.

Pin Dependencies — requirements.txt #

To have the build server produce the docs with the same versions as your own machine, you need to record the packages you use. That’s requirements.txt.

requirements.txt 
mkdocs-material

To pin the version more strictly, write it like mkdocs-material==9.5.0. With this file in place, the build server installs the same tools and produces the same result.

Pushing to GitHub #

So the build output doesn’t end up in the repository, start by creating a .gitignore. MkDocs’ build output is the site folder.

.gitignore 
site/

Then initialize the repository and push.

Pushing to GitHub 
git init
git add .
git commit -m "docs: first doc"
git branch -M main
git remote add origin https://github.com/your-account/my-docs.git
git push -u origin main

Connecting to Cloudflare Pages #

In the Cloudflare dashboard, go to Workers & Pages → Create → Pages → Connect to Git and select the repository. Since MkDocs is Python, the build command has to install the dependencies first.

SettingValue
Build commandpip install -r requirements.txt && mkdocs build
Build output directorysite
Environment variablePYTHON_VERSION = 3.12

Click Save and Deploy and the first deployment starts; when it finishes you get a project-name.pages.dev address. From then on, it automatically rebuilds every time you push to main.

A Simpler Path — gh-deploy #

If you’re using GitHub Pages, MkDocs handles deployment in a single command too. It pushes the build output to a gh-pages branch.

To GitHub Pages in one shot 
mkdocs gh-deploy

It takes the least effort, but unlike the Cloudflare integration it runs the build directly on your own machine before pushing. For team use, the Cloudflare approach — which rebuilds automatically on every push — is less prone to mishaps.

Connecting a Custom Domain #

Instead of the pages.dev address, attach a domain you bought yourself. In the Pages project, go to Custom domains → Set up a domain and enter the domain. If you manage DNS elsewhere, add the following record yourself.

DNS record (subdomain) 
Type    Name     Value
CNAME   docs     project-name.pages.dev

Once the connection is done, Cloudflare automatically issues and renews the HTTPS certificate.

Wrapping Up #

In this post we pinned dependencies with requirements.txt and pushed to GitHub, connected to Cloudflare Pages and set up the build, and attached a custom domain. Now the docs have a real address and live on the internet.

In the next post we’ll cover multilingual docs and versioning. We’ll go over serving one set of docs in multiple languages, and how to keep older docs around as product versions move up.

X