Docs Publish

Appearance

Setup Guide ​

Add docs publishing to any repo in one command.

Quick Start ​

bash
~/personal/docs-publish/setup.sh <repo-path> <project-name> <github-org/repo>

Example:

bash
~/personal/docs-publish/setup.sh ~/personal/newproject/platform newproject MyOrg/platform

This will:

  1. Install vitepress, vitepress-plugin-mermaid, wrangler
  2. Add docs:dev, docs:build, docs:preview scripts
  3. Copy template config, index page, ADR template, deploy workflow
  4. Build the docs site
  5. Create Cloudflare Pages project
  6. Deploy
  7. Set GitHub Secrets

Manual Setup ​

If you prefer to do it step by step:

1. Install dependencies ​

bash
pnpm add -Dw vitepress vitepress-plugin-mermaid wrangler

2. Add scripts to root package.json ​

json
{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}

3. Copy template files ​

bash
cp template/docs/.vitepress/config.mts docs/.vitepress/config.mts
cp template/docs/index.md docs/index.md
cp template/docs/getting-started.md docs/getting-started.md
cp template/docs/adr/000-template.md docs/adr/000-template.md
cp template/.github/workflows/deploy-docs.yml .github/workflows/deploy-docs.yml

Edit config.mts — change SITE_TITLE, SITE_DESCRIPTION, GITHUB_URL. Edit deploy-docs.yml — change --project-name.

4. Create Cloudflare Pages project ​

bash
pnpm exec wrangler pages project create <project>-docs --production-branch main

5. Set GitHub Secrets ​

bash
gh secret set CLOUDFLARE_ACCOUNT_ID -R <org>/<repo> --body "<account-id>"
gh secret set CLOUDFLARE_API_TOKEN -R <org>/<repo>
# paste token when prompted

6. Build and verify ​

bash
pnpm docs:build
pnpm docs:preview  # check at localhost:4173

7. Push ​

Auto-deploys on push to docs/** on main.

Assessing a Repo ​

bash
~/personal/docs-publish/assess.sh <repo-path>

Returns a score out of 20 and a maturity level (0-5).