Build and Deploy Your Own mdBook Wiki with Cloudflare Workers

Deploying your own wiki with mdBook and Cloudflare Workers is simple and efficient. Here's how you can set it up, without changing much of the default configuration.

Install dependencies

To get started, you need to install mdbook, which is the tool that builds your documentation site. If you have Rust and Cargo installed, you can install mdbook with:

cargo install mdbook

Alternatively, you can download a pre-built binary from the mdBook releases page if you prefer not to use Cargo.

For deployment, you'll need a Cloudflare account and the Wrangler CLI. To install Wrangler, use npm:

npm install -g wrangler

After installing Wrangler, authenticate it with your Cloudflare account by running:

wrangler login

This will open a browser window for you to log in and authorize Wrangler. Once authenticated, you can use Wrangler to deploy your static site to Cloudflare Workers.

Get started more directly with Cloudflare's guide to serve static files on Workers.

Configuration

1. Set the Output Directory for `mdBook`

In your book.toml, set the output directory to public:

[build]
build-dir = "public"

This ensures that when you run mdbook build, all static files are generated in the public directory, instead of the default book directory that it generates.

2. Configure Wrangler for Cloudflare Workers

Double check that your wrangler.jsonc should point to the same public directory for static assets and files to serve from. This was the default, but just in case something doesn't work, make sure of this:

"assets": {
  "directory": "./public"
}

This tells Wrangler to serve files from the public folder when deploying to Cloudflare Workers.

A opposite route could also be taken where you tell Wrangler to deploy the book directory instead, however there could be the case that paths to some assets is messed up or some more configuration needs to be set, hence I instead asked mdbook to dump the build to public.

From then on, you can write the pages you need, build the folder with mdbook and then run wrangler to deploy.

I also like to develop or write the posts while looking at a local watch build and just to make sure with a local python server and locally with wrangler using wrangler dev.

3. Use a Makefile for Easy Workflow

Remembering the specifics for these commands everytime or after it's been a while can be troublesome, hence Makefile comes to the rescue.

A simple Makefile I wrote provides convenient commands:

make build - Builds the site with mdBook.
make staticserve - Builds and serves the site locally for testing.
make deploy - Builds and deploys the site to Cloudflare Workers.
make wrangler-local - Builds and starts local development server for Wrangler.

build:
	mdbook build

watch:
	mdbook serve --open

staticserve: build
	python3 -m http.server -d ./public

clean:
	rm -rf public

wrangler-local: build
	npx wrangler dev

deploy: build
	npx wrangler deploy

This setup means you don't have to remember complex commands - just use the Makefile targets for a smooth workflow.

Thus by configuring Wrangler to use the same directory, and leveraging the Makefile, you can easily build and deploy your mdBook wiki as a static site on Cloudflare Workers.

Keyboard shortcuts