Publish the documentation on GitHub Pages

This page explains the GitHub Actions workflow provided to automatically publish the QForm Builder Community VitePress documentation on GitHub Pages.

Goal

The documentation should be published from the repository without a manual build step.

Target public URL:

https://vevedh.github.io/qform-builder-layer/

Added file

.github/workflows/docs.yml

GitHub Pages configuration

In the GitHub repository:

Settings → Pages → Build and deployment → Source: GitHub Actions

Automatic base handling

Local development uses:

base: /

The workflow injects:

VITEPRESS_BASE: '/${{ github.event.repository.name }}/'

For this repository, the generated base is:

/qform-builder-layer/

Provided workflow

The workflow:

1. runs on pushes to main that touch docs/**, scripts/**, .github/workflows/docs.yml, package.json, README.md or bun.lock;
2. checks out the repository;
3. installs Bun 1.3.6;
4. installs dependencies from the frozen lockfile;
5. builds VitePress with the repository name as VITEPRESS_BASE;
6. uploads the generated static site;
7. deploys it to GitHub Pages.

Node.js 24 compatibility

The workflow opts into the future JavaScript actions runtime with:

env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'

It also uses actions/checkout@v6 and actions/configure-pages@v6 to avoid the Node.js 20 deprecation warning. The workflow keeps the documentation build separate from the npm publication gate: GitHub Pages publishes only docs/.vitepress/dist.

Local test

bun run docs:build
bun run docs:preview

PowerShell simulation of the GitHub Pages base:

$env:VITEPRESS_BASE='/qform-builder-layer/'
bun run docs:build
Remove-Item Env:VITEPRESS_BASE

Custom domain case

If a custom domain is used later, set:

VITEPRESS_BASE=/

and add the expected CNAME configuration for GitHub Pages.

Best practices

• Run bun run docs:i18n:check before committing documentation changes.
• Keep French and English page trees synchronized.
• Do not commit docs/.vitepress/dist.
• Use workflow_dispatch to manually redeploy if necessary.