Skip to content

Deploy Docs ​

This docs site uses VitePress + VitePress Theme Teek. All content lives inside doc/, and the build output is a static site suitable for Cloudflare Pages.

Local development ​

bash
cd doc
npm install
npm run dev

Build static files ​

bash
cd doc
npm run build

The output directory is:

text
doc/.vitepress/dist

Publish that directory to any static hosting service.

Option A: set Cloudflare Root directory to doc ​

This is the preferred setup.

SettingRecommended value
Framework presetVitePress
Root directorydoc
Build commandnpm run build
Build output directory.vitepress/dist
Environment variableDOCS_BASE=/
Node.jsNODE_VERSION=22.16.0 or a newer 22/24 LTS version

Steps:

  1. Open Cloudflare Dashboard and go to Workers & Pages / Pages.
  2. Choose Create application, then Pages.
  3. Connect the Git repository: https://github.com/fantasy-ke/FkeMark.
  4. Choose the production branch based on your release strategy: main for stable docs, dev for preview docs.
  5. Fill in the build settings above.
  6. Save and deploy. Cloudflare will install dependencies, build the docs, and publish .vitepress/dist.

Option B: keep Root directory at repository root ​

If the Cloudflare project must keep the repository root, use explicit doc commands:

SettingValue
Framework presetNone or VitePress
Root directoryempty or repository root
Build commandnpm --prefix doc ci && npm --prefix doc run build
Build output directorydoc/.vitepress/dist
Environment variableDOCS_BASE=/

Cloudflare headers ​

doc/public/_headers is copied to the build output root. It configures:

  • Basic security headers for all pages.
  • Long cache for VitePress static assets.
  • Shorter cache for the reusable theme CSS so visual updates can ship safely.

GitHub Pages ​

The repository URL is:

text
https://github.com/fantasy-ke/FkeMark

For GitHub Pages, the expected URL is:

text
https://fantasy-ke.github.io/FkeMark/

The config automatically uses /FkeMark/ as base in GitHub Actions. For root-domain deployment, set:

bash
DOCS_BASE=/ npm run build

Why VitePress ​

FrameworkBest forDecision
VitePressMarkdown-first, lightweight static docsBest fit for this Vite/npm project
DocusaurusLarge docs and versioningPowerful but heavier
Astro StarlightContent sites, built-in nav/search/i18nGood, but introduces Astro ecosystem
NextraNext.js + MDX docsBetter for existing Next.js projects

For this project’s home page, guide, theme docs, and deployment notes, VitePress is the smallest maintainable choice, with Teek as the theme enhancement layer.

Troubleshooting ​

Styles or icons return 404 ​

Check DOCS_BASE:

  • Cloudflare Pages root domain: DOCS_BASE=/
  • GitHub Pages repository page: DOCS_BASE=/FkeMark/
  • Custom subpath: set the real subpath, for example DOCS_BASE=/docs/

Cloudflare build fails ​

The VitePress/Teek dependency chain needs a recent Node.js runtime. Set:

text
NODE_VERSION=22.16.0

A validated 24 LTS version can also be used later.

Cloudflare cannot find the output directory ​

Make sure Root directory and Build output directory match:

  • Root directory is doc: output directory should be .vitepress/dist.
  • Root directory is repository root: output directory should be doc/.vitepress/dist.

Released under AGPL-3.0-only.