documenter-vitepress

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.