README.md

DocumenterVitepress.jl

Tip

Visit at https://luxdl.github.io/DocumenterVitepress.jl/dev/

This package provides a Markdown / MkDocs backend to Documenter.jl.

Installation

The package can be added using the Julia package manager. From the Julia REPL, type ] to enter the Pkg REPL mode and run

pkg> add DocumenterVitepress

Usage

To enable the backend:

1. Import the package in make.jl,
2. Pass format = DocumenterVitepress.MarkdownVitepress(...) to makedocs like so, replacing e.g. format = HTML(...):

using Documenter
using DocumenterVitepress
makedocs(;
    format=DocumenterVitepress.MarkdownVitepress(repo = "...", devbranch = "...", devurl = "dev"),
    )

and enjoy the fruits of your labour!

If you wish to fully customize your documentation with all of the capabilities of Vitepress, then you can use our template generator. But be warned that you may have to update that template to keep pace with DocumenterVitepress changes!

Tip

To get a fully customizable build, run

DocumenterVitepress.generate_template("/path/to/YourPackage/docs", "YourPackage")

to populate all of the files which Vitepress requires.

And keep an eye for custom domains.

Caution

If you are deploying from a custom URL, like geo.makie.org, please provide the entire URL to the deploy_url = "geo.makie.org" keyword argument of MarkdownVitepress!

Otherwise, the documentation will not render correctly.

Run locally

Because this is based on the Vitepress static site generator, you have to use NodeJS to view this site locally:

using DocumenterVitepress
DocumenterVitepress.dev_docs()

and edit your make.jl file to add build_vitepress = false as a keyword argument to the MarkdownVitepress config, to save time. If you keep this running, perhaps in a separate Terminal window, it will automatically rebuild whenever you run make.jl.

---

The documentation needs documentation.

-a Bellevue Linux Users Group member, 2005-