Build a Manual with Docusaurus #4: Deploy to Cloudflare Pages and Connect a Domain

Framework Docusaurus Documentation Static Site
3 min read

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

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

  • #1 From Install to Your First Doc
  • #2 Sidebar and Search — Structuring Your Documentation
  • #3 Writing Content — Code Blocks, Mermaid, Admonitions
  • #4 Deploy to Cloudflare Pages and Connect a Domain ← this post
  • #5 Multilingual and Versioning
  • #6 Maintenance — Search, Accessibility, and Documentation Culture

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

Pushing to GitHub #

So the build output and dependencies don’t end up in the repository, start with .gitignore. create-docusaurus creates a default .gitignore for you, but the key three are these.

.gitignore 
/build/
/node_modules/
/.docusaurus/

Then initialize the repository and push.

Push 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 Docusaurus is a Node project, the build settings are simple.

ItemValue
Framework presetDocusaurus
Build commandnpm run build
Build output directorybuild
Environment variableNODE_VERSION = 20

It’s safest to match the Node version to your local setup. Click Save and Deploy and the first deployment begins; when it finishes you get a project-name.pages.dev address. From then on, it rebuilds automatically every time you push to main.

A Simpler Path — the deploy Command #

If you use GitHub Pages, Docusaurus provides a deploy command. First fill in url, baseUrl, organizationName, and projectName in docusaurus.config.js, then run it.

To GitHub Pages in one shot 
npm run deploy

This builds on your own machine and pushes to the gh-pages branch. If a team works on it together, the Cloudflare side, which builds automatically on push, has fewer mishaps.

Connecting a Custom Domain #

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

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

Once connected, Cloudflare automatically issues and renews the HTTPS certificate. When using a custom domain, also align url and baseUrl in docusaurus.config.js to that domain.

Wrapping Up #

In this post we pushed the docs to GitHub, connected to Cloudflare Pages and set up the Node build, and even attached a custom domain. The docs now have a real address and live on the internet.

In the next post we’ll cover multilingual and versioning. This is the area where Docusaurus is strongest, with both available as built-in features.

X