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

.