setup-docs

name	setup-docs
description	Set up a documentation site using either a subdirectory or separate orphan branch with git worktree.

Set up a documentation site using either a subdirectory or separate orphan branch with git worktree.

$ARGUMENTS

Process

Step 0: Gather requirements

Ask the user which documentation setup approach they prefer:

• Subdirectory (docs/ folder): Documentation lives in docs/ subdirectory of the main repository. Easier to maintain and deploy alongside the main project. Documentation changes are part of the main project's git history. Recommended for simpler projects or when you want docs close to code.
• Separate worktree branch: Documentation lives in a separate git worktree with orphan branch. Completely isolated git history for documentation. Can be deployed independently of the main project. Recommended for complex documentation or separate deployment needs.

Then identify from the user context:

• Repository path (where the main project lives)
• Documentation framework (recommended: Docusaurus, Material for MkDocs, VitePress)
• Stack/tooling for the docs framework (infer from main project or ask)
• For worktree approach: Branch name for docs (default: docs) and worktree directory name (default: same as branch name)

Ask only if the details without a default are genuinely missing from the context.

Present the user's choice back to them and confirm before proceeding:

• "Based on your preference, I'll set up documentation using the [subdirectory/worktree branch] approach. Is that correct?"

Decision Point: Which setup approach should be used?

• If the user wants docs in the main repository -> Go to Path A: Subdirectory Setup
• If the user wants docs in a separate orphan branch -> Go to Path B: Separate Worktree Branch Setup

---

Path A: Subdirectory Setup (docs/ folder)

Step 1A: Create docs subdirectory

Create and navigate to the docs directory:

mkdir docs
cd docs

Step 2A: Initialize documentation project

Initialize the project using the appropriate tooling for the stack. Examples:

Material for MkDocs (Python):

uv init --no-readme

Docusaurus (Node.js):

npm init -y

VitePress (Node.js):

npm init -y

Note: If the base project is already using a package manager and the docs use the same language, reuse the same package manager for the documentation site.

Note: After Step A2, continue to Step 4: Add documentation framework dependencies.

---

Path B: Separate Worktree Branch Setup

Step 1B: Check for branch name conflicts

Check if there are existing branches that would conflict with creating the docs branch:

git branch -a | grep "^[[:space:]]*<branch-name>/"

If any branches like <branch-name>/* exist, they will prevent creating the branch. Delete conflicting branches with user confirmation.

Step 2B: Create git worktree with orphan branch

Create a detached worktree and checkout an orphan branch in it:

git worktree add -d ../<worktree-name>
cd ../<worktree-name>
git checkout --orphan <branch-name>

The orphan branch starts with a fresh history, separate from the main project.

Step 3B: Initialize documentation project

Clean the worktree and initialize the project using the appropriate tooling for the stack:

rm -rf * .gitignore

Then initialize based on the stack. Examples:

Material for MkDocs (Python):

uv init --no-readme

Docusaurus (Node.js):

npm init -y

VitePress (Node.js):

npm init -y

Note: If the base project is already using a package manager and the docs use the same language, reuse the same package manager for the documentation site.

Note: After Step B3, continue to Step 4: Add documentation framework dependencies.

Step 4: Add documentation framework dependencies

Add the documentation framework using the appropriate package manager. Examples:

Material for MkDocs (Python):

uv add mkdocs-material 'mkdocstrings[python]'

Docusaurus (Node.js):

npx create-docusaurus@latest . classic

VitePress (Node.js):

npm add -D vitepress

Step 5: Initialize documentation framework

Run the framework's initialization command to create the basic structure. Examples:

Material for MkDocs:

uv run mkdocs new .

Docusaurus:

# Already initialized by create-docusaurus in Step 4

VitePress:

npx vitepress init

Step 6: Set up commit hooks

For subdirectory approach: Reuse the existing commit hooks tooling from the main project if it exists. Check for existing hooks configuration in the main project directory.

For worktree approach: Set up commit hooks following the approach in /project/setup-pre-commit-hooks: use proper tooling with git-tracked config files (pre-commit for Python, husky + lint-staged for Node.js).

Include hooks for:

• Markdown/content formatting
• Documentation build validation (build with strict mode if available)
• If code files exist (Python plugins, custom components, etc.): formatting, linting, type-checking

Install the hooks and verify they work by running them manually.

Step 7: Verify the documentation site works

Test that the documentation site builds and serves correctly using the framework's dev server command. Examples:

Material for MkDocs:

uv run mkdocs serve

Docusaurus:

npm start

VitePress:

npm run docs:dev

Retrieve a page from the local server URL and verify the site renders correctly.

Step 8: Create .gitignore

Create .gitignore to exclude framework-specific build artifacts and dependencies. Examples:

Material for MkDocs:

site/
.cache/
__pycache__/
*.py[cod]
.venv/

Docusaurus:

.docusaurus/
build/
node_modules/
.cache/

VitePress:

.vitepress/dist/
.vitepress/cache/
node_modules/

Important: Before staging files, remove any unwanted boilerplate files generated by the documentation framework initialization process (e.g., main.py from uv init, Docusaurus sample blog posts, Docusaurus tutorial docs, sample VitePress pages, etc.). These are tracked source/content files created by the init template that are not needed for the real documentation site.

Do not treat ignored build/cache artifacts as "unwanted init files." Files and directories such as Docusaurus .docusaurus/, Docusaurus build/, MkDocs site/, VitePress .vitepress/dist/, dependency folders, and cache folders are generated by build/dev commands, not by the project init template. They should be covered by .gitignore and left alone unless the user explicitly asks to clean the working tree.

Run git status to confirm no unwanted files are staged.

Step 9: Commit the documentation setup

For both approaches: Stage all files in the current git working tree:

git add .

Commit with a descriptive message. If commit hooks modify files (e.g., formatting), stage the changes and commit again.

Use a commit message that describes:

• What documentation framework was set up
• Key features (theme, plugins, tooling)
• Dependency/package management approach

CRITICAL: Never disable or skip git hooks. If hooks are hanging or failing:

1. Kill the commit and debug the hooks separately (run the hook tool manually, e.g. lefthook run pre-commit, pre-commit run --all-files, npm run lint, etc.)
2. Fix the hook configuration or the underlying issue
3. Only then retry the commit with hooks enabled

Never use --no-verify, LEFTHOOK=0, HUSKY=0, PRE_COMMIT_ALLOW_NO_CONFIG=1, or any other mechanism to bypass hooks.

Notes:

• For subdirectory approach: This commits the docs/ directory and its contents as part of the main repository.
• For worktree approach: This creates the initial commit on the orphan docs branch. When you run git log --graph --all, you'll see both the main branch history and the docs branch. However, the docs branch itself is orphaned - run git rev-list --count HEAD to verify it has only 1 commit, or git log (without --all) to see only the docs branch history.

Step 10: Document the documentation setup in main project README

Switch back to the main project directory and update README.md to document where documentation lives:

cd <main-project-directory>

For subdirectory approach, add a Documentation section like:

## Documentation

Project documentation lives in the `docs/` directory.

To run the documentation site locally:

\`\`\`bash
cd docs
<framework-specific dev server command>
\`\`\`

For worktree approach, add a Documentation section like:

## Documentation

Project documentation lives in the `docs` branch, an orphan branch with separate history from the main codebase.

### Local Setup for Contributors

Set up the docs branch as a sibling worktree:

\`\`\`bash

# From the project root, add the docs branch as a sibling worktree

git worktree add ../docs docs
\`\`\`

This creates the following directory structure:

\`\`\`
parent-directory/
├── <project-name>/ # main branch (this repo)
└── docs/ # docs branch worktree
\`\`\`

Note: Documentation updates require coordinating branches in both worktrees when changes span code and docs.

Commit this README update to the main branch.

Key Principles

• Confirm the setup approach before creating files: The subdirectory and worktree flows diverge immediately, so restate the chosen path and wait for confirmation before creating anything.
• Reuse the project's existing tooling when possible: If the main project already has a package manager, hook runner, or documentation conventions that fit the docs stack, reuse them instead of introducing parallel tooling.
• Converge quickly after branch-specific setup: Keep Path A and Path B limited to the steps that truly differ, then return to shared steps so the workflow stays readable.