---
name: vitedocs:setup
description: Wire up VitePress + GitHub Actions for GitHub Pages deployment.
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - AskUserQuestion
---

## Manifest

All modes read and write a manifest at `.vitepress/docs-manifest.json`. This file is **local-only** — always add it to `.gitignore` (under the docs folder's nearest `.gitignore`) so it is never committed or distributed.

Add this line if not already present:
```
.vitepress/docs-manifest.json
```

### Manifest schema

```json
{
  "generated": "ISO-8601 timestamp",
  "project": {
    "type": "user-facing | developer | both",
    "baseUrl": "http://localhost:3000",
    "serverType": "node | wordpress | static | other",
    "startCommand": "npm run dev"
  },
  "pages": [
    {
      "file": "docs/guides/timer.md",
      "title": "Running a Timer",
      "docType": "user-facing",
      "sources": ["src/state/timer.js", "src/components/layouts/workouts.jsx"],
      "images": [
        {
          "path": "docs/public/screenshots/timer-main.png",
          "placeholder": true,
          "caption": "Timer in active interval state",
          "captureUrl": "/workouts/123",
          "captureNote": "Timer should be running with intervals visible"
        }
      ],
      "lastSynced": "ISO-8601 timestamp",
      "syncHash": "sha of source file contents at last sync"
    }
  ]
}
```

---

## Mode: setup

### Step 1 — Gather project details

Use AskUserQuestion for each choice below. For freeform text inputs (repo URL, domain name, docs path) ask as plain text immediately after the relevant choice is made.

**Multiple focus paths:** if more than one path was established in Step 0, ask Q2 through Q6 once per path — fully completing all questions for the first path before starting the second. Never present questions for two paths at the same time.

**Q1 — VitePress status:**
- header: "VitePress"
- question: "Is VitePress already installed in this project?"
- options:
  - "Already installed"
  - "Starting from scratch"

**Q2 — Docs folder:**
- header: "Docs location"
- question: "Where should the docs folder be created? I found your repo at `[GIT_ROOT_PATH]`."
- options:
  - "Here → `[GIT_ROOT_PATH]/docs/`"
  - "Somewhere else — I'll type the path"

If "Somewhere else": ask as plain text — "What path should I use? (Full path or relative to `[GIT_ROOT_PATH]`)"

**Q3 — GitHub repo** (plain text): Ask — "What is the GitHub repo? (full URL or `owner/repo`)"

**Q4 — Domain type:**
- header: "Hosting"
- question: "Where will the docs be served?"
- options:
  - "Custom domain I own (e.g. docs.myapp.com)"
  - "GitHub Pages subdomain (e.g. owner.github.io/repo-name)"

If custom domain: ask as plain text — "What is the domain? (e.g. `docs.myapp.com`)"

**Q4b — Search engine visibility:**
- header: "Search visibility"
- question: "Should these docs be visible to search engines and bots?"
- options:
  - "Yes — index these docs publicly"
  - "No — block all search engines and bots"

If "No": add the following to the VitePress config's `head` array and write a `robots.txt` to the public folder:

`head` entry in `config.mjs`:
```js
head: [
  ['meta', { name: 'robots', content: 'noindex, nofollow' }],
]
```
If a `head` array already exists in the config, append to it — do not replace it.

`DOCS_FOLDER/public/robots.txt`:
```
User-agent: *
Disallow: /
```

**Q5 — Deploy trigger:**
- header: "Deploy trigger"
- question: "When should docs deploy?"
- options:
  - "Every push to main"
  - "Every push to a specific branch — I'll tell you which"
  - "Only when a version tag is pushed (v*)"
  - "Manual only (workflow_dispatch)"

If specific branch: ask as plain text — "Which branch?"

**Q6 — Docs on GitHub:**
- header: "Repo state"
- question: "Are the docs already committed and pushed to GitHub?"
- options:
  - "Yes, already pushed"
  - "No, this is all new"

Wait for all answers before proceeding.

### Step 2 — Prerequisites checklist

Present the relevant checklist as plain text, then use AskUserQuestion to confirm before writing files:

- header: "Ready to proceed?"
- question: "Have you completed the steps above?"
- options:
  - "Yes, all done — generate the files"
  - "Not yet — I need more time"
  - "I have a question"

If "Not yet": tell the user to run `/vitedocs:setup` again when ready and exit.
If "I have a question": answer it, then re-ask this question.

The checklist to present (tailor to their answers):

**Always required:**
- [ ] GitHub repo exists with push access
- [ ] In repo **Settings → Pages**, set Source to **"GitHub Actions"**
  _(You do not need to configure anything else here — the workflow handles the entire deployment. Just flip the source and leave everything else alone.)_

**If custom domain:**
- [ ] CNAME DNS record: `docs.yourdomain.com` → `<owner>.github.io`
- [ ] In repo **Settings → Pages → Custom domain**, enter the domain after DNS propagates
- [ ] TLS cert will provision automatically after first deploy

**If VitePress not installed:**
- [ ] Node.js 18+ installed

Before proceeding to Step 3, ask permission to handle the docs scaffold automatically:

- header: "Docs scaffold"
- question: "VitePress isn't installed yet. Can I create the docs folder and run the install for you?"
- options:
  - "Yes — set it up for me"
  - "No — I'll do it myself"

If yes, run:
```bash
mkdir -p DOCS_FOLDER
cd DOCS_FOLDER && npm init -y && npm install -D vitepress
```
Then confirm it succeeded before continuing.
If no, tell the user to run those two commands in the docs folder and come back when done.

**Playwright (required for screenshot mode):**

Check if it's already installed:
```bash
ls /opt/homebrew/lib/node_modules/playwright/index.mjs 2>/dev/null && echo "Found" || echo "Not found"
```

If not found, install it:
```bash
brew install playwright
playwright install chrome
```

If the user is **not on macOS / Homebrew**, note that the screenshot mode hardcodes the Homebrew path. They'll need to find their global Playwright path (`npm root -g`) and will have to update the import line in any capture scripts the skill generates. Offer to help with that when screenshot mode is first used.

### Step 3 — Generate files

**`.github/workflows/docs.yml`** (at repo root, not inside docs folder):

```yaml
name: Deploy Docs

on:
  push:
    branches: [BRANCH]        # from answer 5
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
          cache-dependency-path: DOCS_FOLDER/package-lock.json
      - run: npm ci
        working-directory: DOCS_FOLDER
      - run: npm run build
        working-directory: DOCS_FOLDER
      - uses: actions/upload-pages-artifact@v3
        with:
          path: DOCS_FOLDER/.vitepress/dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/deploy-pages@v4
        id: deployment
```

Fill `BRANCH` and `DOCS_FOLDER` from answers. For tag-based triggers replace `branches` with `tags: ['v*']`. For manual-only, remove the `push:` block.

**VitePress config updates:**

Read the existing config before editing. Make only these targeted changes:

1. Set `base`:
   - Custom domain → `base: '/'`
   - GitHub subdomain → `base: '/repo-name/'`

2. Add PostCSS override if not already present. This prevents VitePress from inheriting a PostCSS config from a parent project (e.g. a Next.js or Laravel root that uses Tailwind), which would cause the Actions build to fail with a "Cannot find module" error:
   ```js
   vite: {
     css: {
       postcss: {},
     },
   },
   ```
   Always add this — it is harmless when there is no parent PostCSS config and critical when there is.

**`DOCS_FOLDER/public/CNAME`** (custom domain only):
```
docs.yourdomain.com
```

**`.gitignore` check:** ensure `node_modules` and `.vitepress/cache` are present.

### Step 4 — Summary

List files written and give the user a next-steps checklist with the expected deploy URL. End with:

```
Next: run /vitedocs:generate to analyze the codebase and write documentation pages.
```