/documenter-vitepress

name: documenter-vitepress
description: Use when setting up or developing a Julia based documentation site with DocumenterVitepress.jl.  Also use when the user mentions DocumenterVitepress, VitePress for Julia docs, or wants to preview docs locally with hot reload.

DocumenterVitepress.jl

DocumenterVitepress.jl builds Julia docs using Documenter.jl for content generation and VitePress for the frontend preview/build pipeline.

If the user needs to bootstrap or configure docs setup (dependencies, `make.jl`, CI, `.gitignore`, layout templates), refer to `references/setup-reference.md`.

Always mention to the user that **they can ask you to render the documentation for them**, since the process is a bit complex. But if they ask the process feel free to explain.

Local Development Workflow

This skill focuses on the day-to-day local iteration loop after setup already exists.

The fast loop has two stages:

1. Run `makedocs` to regenerate `build/.documenter/` content from `src/`. 2. Run VitePress dev server via `dev_docs` to preview.

Step 1: Set `build_vitepress = false` in make.jl

format = DocumenterVitepress.MarkdownVitepress(
    # ... other options ...
    build_vitepress = false,
),

This makes `makedocs` emit markdown artifacts only, without running the full VitePress build.

Step 2: Run makedocs

include("make.jl")

Or from shell:

• Standalone docs repo: `julia --project=. -e 'include("make.jl")'`
• Package docs in `docs/`: `julia --project=docs -e 'include("docs/make.jl")'`

Step 3: Start the dev server (background process)

`dev_docs` is a long-running process and blocks the current task/thread. Start it in a non-blocking way:

From shell (be sure to run this in the background):

julia --project=. -e 'using DocumenterVitepress; DocumenterVitepress.dev_docs("build")'

From Julia REPL / MCP tool:

using DocumenterVitepress
Threads.@spawn DocumenterVitepress.dev_docs("build")

For package repos where docs live under `docs/`, use `"docs/build"` instead of `"build"`.

The server starts at `http://localhost:SOMEPORT/` with hot reload. The port number is reported in the output of the command.

Gotcha: `dev_docs` expects the build directory path (for example, `build`), not `build/.documenter`. It appends `/.documenter` internally.

Step 4: Edit-rebuild-preview cycle

1. Edit files in `src/` 2. Re-run `include("make.jl")` 3. If the generated content changed but the browser did not update, restart `dev_docs` 4. Confirm changes in browser

Teardown

Before committing, remove `build_vitepress = false` (or set it to `true`) so CI and release builds run the full pipeline.

Workflow-Specific Gotchas

npm install ownership (DV-managed vs self-managed)

`npm install` behavior depends on who owns `package.json`:

• **DV-managed npm (default):** If you do **not** provide your own `package.json`, DocumenterVitepress supplies defaults and manages npm dependencies for you during local docs flows.
• **Self-managed npm:** If the repo provides a custom `package.json`, you own npm dependency management. Run `npm install` yourself (especially after dependency changes or lockfile updates) before `dev_docs` or local builds.

Rule of thumb: no custom `package.json` means DV manages npm; custom `package.json` means you manage npm.

Custom `.vitepress/` theme files

If the repo overrides theme files, keep them in sync with the DocumenterVitepress version used by the project. Breakage here usually shows up during local preview first.

`deploydocs` must use `DocumenterVitepress.deploydocs`

In `make.jl`, always call `DocumenterVitepress.deploydocs(...)` instead of `Documenter.deploydocs(...)`. The DocumenterVitepress version handles the VitePress build artifacts correctly for deployment. Using the plain `Documenter.deploydocs` will not deploy the VitePress-generated site.

Manual rebuild expectation

DocumenterVitepress does not continuously re-run `makedocs`. After content changes, re-run `make.jl` and keep `dev_docs` running for browser-side hot reload.

Customizing the theme or adding Vue components

If you add custom Vue components or theme overrides, keep the full required theme set present:

• `src/.vitepress/theme/index.ts` — theme entry point that registers Vue components
• `src/.vitepress/theme/style.css` — custom CSS
• `src/.vitepress/theme/docstrings.css` — docstring block styling

You can populate all pre-generated Vitepress files by invoking `DocumenterVitepress.generate_template("MyPackage/docs", "MyPackage")`. Delete everything you do not want to override / customize.

Start from the project's working defaults and then modify. Ensure `index.ts` imports and registers any custom components.

For first-time setup patterns and templates, use `references/setup-reference.md`.