Upgrading from Documenter.jl to DocumenterVitepress.jl

Migrate your existing Documenter.jl documentation to DocumenterVitepress.jl in a few steps.

Assuming you're working on a package named Example.jl in the ExampleOrg organization:

1. Update make.jl

The make.jl file with Documenter.jl should look like this:

using Example
using Documenter

DocMeta.setdocmeta!(Example, :DocTestSetup, :(using Example); recursive=true)

makedocs(;
    modules = [Example],
    authors = "Author Name",
    sitename = "Example.jl",
    format = Documenter.HTML(;
        canonical = "https://github.com/ExampleOrg/Example.jl",
        edit_link = "main",
    ),
    pages = [
        "Home" => "index.md",
        "API" => "api.md",
    ],
)

deploydocs(;
    repo = "github.com/ExampleOrg/Example.jl",
    devbranch = "main",
)

2. Install DocumenterVitepress

$ cd docs
docs $ julia
julia> ]
pkg> activate .
pkg> add DocumenterVitepress Documenter

3. Build and View

Build your documentation:

julia> include("make.jl")

View locally with LiveServer:

using LiveServer
LiveServer.serve(dir = "build/1")

Open your browser typically at http://localhost:8000/, your should see the address in the terminal.

Using Vitepress dev server instead

If you prefer Vitepress's hot-reload server:

1. Add a package.json to your docs folder (example here)

2. Install dependencies: npm install

3. Run: npm run docs:dev

Stop the server when needed:

try run(`pkill -f vitepress`) catch end

4. Remove Symlinks from gh-pages

Before deploying, delete any symlinks on your `gh-pages` branch (e.g., `stable`, `v1`). DocumenterVitepress cannot write to symlinks.

Delete them via GitHub's web interface at https://github.com/ExampleOrg/Example.jl/tree/gh-pages

5. Deploy

Push your changes. Your CI will now deploy using DocumenterVitepress.

For more details, see Get Started.