wb publish supports three targets: cloudflare-pages, gh-pages, and self-hosted. Set PUBLISH_TARGET in publish.org or site.org.

Deploys via wrangler pages deploy. This is the default target for workbooks.sh projects.

wrangler must be on PATH and authenticated:

npm i -g wrangler
wrangler login

wrangler login opens a browser to authenticate with your Cloudflare account.

:PUBLISH_TARGET:  cloudflare-pages
:PUBLISH_PROJECT: my-pages-project   ← the CF Pages project name
:PUBLISH_DOMAIN:  my-project.pages.dev

PUBLISH_PROJECT must match an existing Cloudflare Pages project. To create one:

wrangler pages project create my-pages-project --production-branch main

If you have multiple Cloudflare accounts, set CLOUDFLARE_ACCOUNT_ID in your environment. Do not put it in the org file:

export CLOUDFLARE_ACCOUNT_ID=<your-account-id>
wb publish apply my.org

wb publish passes this env var to wrangler automatically.

For wb publish apply: the rendered .html file in a temporary directory is passed to wrangler pages deploy. For wb publish site: the full dist/ directory is deployed.

Set PUBLISH_DOMAIN to your custom domain. The domain must be configured in Cloudflare Pages (Settings → Custom domains). The domain is only used for the printed URL after deploy; wrangler handles the actual routing.

Deploys by pushing to the gh-pages branch of a GitHub repository.

:PUBLISH_TARGET:  gh-pages
:PUBLISH_PROJECT: org/repo   ← GitHub repo in org/name format
:PUBLISH_DOMAIN:  docs.example.com

PUBLISH_PROJECT must be org/name — the repository must exist and have a gh-pages branch. To create one:

git clone https://github.com/org/repo /tmp/repo
cd /tmp/repo
git checkout --orphan gh-pages
git rm -rf .
echo "placeholder" > index.html
git add . && git commit -m "init gh-pages"
git push origin gh-pages

Push authentication uses whatever git credential helper is configured for https://github.com. On macOS the system keychain is used by default after git clone with HTTPS and a successful auth.

For CI: set GITHUB_TOKEN and configure git to use it:

git config --global credential.helper store
echo "https://x-access-token:${GITHUB_TOKEN}@github.com" > ~/.git-credentials

For wb publish apply: the rendered HTML is written as index.html in the gh-pages branch root. For wb publish site: all files from dist/ are copied into the branch root.

Posts the rendered HTML blob to a running workbooks.sh runtime instance.

:PUBLISH_TARGET: self-hosted
:PUBLISH_URL:    https://your-runtime.example.com
:PUBLISH_PROJECT: workbook-id

PUBLISH_URL is the base URL of the runtime. The runtime must be running and reachable. The rendered HTML is POSTed to /api/publish with a JSON body:

{"html": "<rendered html>", "id": "workbook-id"}

The runtime stores it and makes it available at the host that resolves to the workbook ID (via Workbooks.Domains).

Self-hosted site mode (wb publish site) is not yet implemented. Use wb publish apply for single-page deploys to self-hosted targets.