Deploy a Docusaurus site

Publish a Docusaurus site on your own domain, from your computer or from GitHub Actions.

Build command	npm run build
Output folder	build
Settings you need	url, baseUrl: '/', trailingSlash: true
Routing	With trailingSlash: true, each page is docs/intro/index.html, linked as /docs/intro/

Before you begin

You need:

• A Docusaurus site that builds on your computer with npm run build.
• An Evolving Edge account that can deploy workloads. See Getting Started.
• A project in the portal, and its project ID (it starts with proj_).
• A deploy token from the portal, under Workload → Deploy Tokens, with workload:write. Scope it to the project. See Deploy tokens.
• The domain you want to serve the site on, for example docs.example.com, and access to its DNS settings.
• Node.js 22.12 or later, on Windows (x64), macOS, or Linux (x64 or arm64).

1. Configure Docusaurus

docusaurus.config.js

export default {
  url: 'https://docs.example.com',
  baseUrl: '/',
  trailingSlash: true,
  // ...
};

• url is used for canonical links and the sitemap.
• baseUrl: '/': the site is served from the root of the domain.
• trailingSlash: true makes Docusaurus link to /docs/intro/, which matches the docs/intro/index.html it writes. Evolving Edge serves a folder’s index.html for an address that ends in a slash. If you leave trailingSlash unset, the links have no slash and the sitemap lists addresses without one.

If you prefer trailingSlash: false, Docusaurus writes docs/intro.html instead. Deploy with --clean-urls so /docs/intro finds it.

2. Claim your domain

Only the project that claimed a domain can deploy to it, so claim it before your first deploy. In the portal, or from the command line:

export EE_CDN_TOKEN=<your deploy token>
npx -p @evolving-edge/ee-cdn-cli ee-domain claim docs.example.com --project proj_abc123 --wait

It prints a TXT record and a CNAME record to add at your DNS provider, then waits until the domain is active. See Custom domains for the portal steps, root domains and Cloudflare.

3. Deploy from your computer

npm run build
npx @evolving-edge/ee-cdn-cli build --domain docs.example.com --project proj_abc123 --trailing-slash

• --trailing-slash makes /docs/intro redirect to /docs/intro/, so links from elsewhere that leave the slash off still arrive.
• ee-deploy finds build by itself if you leave the folder out.
• Each deploy replaces the whole site on that domain. Allow up to about 90 seconds for a new deploy to reach every node.

4. Deploy from GitHub Actions

In your repository settings, add:

• a secret EE_CDN_TOKEN holding your deploy token
• variables EE_DOMAIN (for example docs.example.com) and EE_CDN_PROJECT_ID

Then create .github/workflows/deploy.yml:

name: Deploy to Evolving Edge

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: ee-deploy
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # for "last updated" dates

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - run: npm ci
      - run: npm run build

      - name: Deploy
        env:
          EE_CDN_TOKEN: ${{ secrets.EE_CDN_TOKEN }}
          EE_CDN_PROJECT_ID: ${{ vars.EE_CDN_PROJECT_ID }}
        run: npx --yes @evolving-edge/ee-cdn-cli build --domain ${{ vars.EE_DOMAIN }} --trailing-slash

Redirects, 404 page and caching

Docusaurus copies everything in static/ to the site root, so that’s where _redirects and _headers go.

Redirects. Add a _redirects file at static/_redirects:

/docs/old-page/   /docs/new-page/    301
/v1/*             /docs/:splat       301

Rules can be 301 or 302, and * and :splat wildcards work. Redirects apply to public (Level 0) sites. @docusaurus/plugin-client-redirects keeps working too.

404 page. Docusaurus builds build/404.html, and Evolving Edge serves it with a 404 status for any address that doesn’t exist. See Custom 404 pages.

Caching. HTML pages are checked on every request, so a new deploy shows as soon as it reaches the nodes. Other files are cached for an hour. Docusaurus names the files in /assets/ by content hash, so you can cache that folder for a year with static/_headers:

/assets/*
  Cache-Control: public, max-age=31536000, immutable

Check first that nothing in static/assets/ is copied in without a hash. See Caching hashed assets for a year.

What doesn’t carry over

• Subfolder deploys. A site owns its whole domain, so baseUrl stays /.
• Deploy previews for each pull request. To preview, deploy to a second domain.
• Very large sites. A deploy’s package can be up to 100 MiB, after compression. A site with many versions and locales should check the size ee-deploy reports.

Troubleshooting

What you see	Why	What to do
The home page works, but other pages are 404s when opened directly	trailingSlash isn’t true, so links have no slash	Set trailingSlash: true, or deploy with --trailing-slash
/docs/intro is a 404 and the file is intro.html	trailingSlash: false	Deploy with --clean-urls
Scripts and styles are 404s	baseUrl is set to a subfolder	Set baseUrl: '/'
Sitemap URLs point at the wrong host	url isn’t your domain	Set url
The deploy is refused for your domain	The domain isn’t claimed for this project	Claim it first
No deploy token	EE_CDN_TOKEN isn’t set	Export it, or add the repository secret
An authorisation error on upload	The token is scoped to a project and no project was given	Pass --project (or set EE_CDN_PROJECT_ID)

More in the command line troubleshooting.