The rendering process

DocumenterVitepress combines two formidable packages - Documenter.jl, which consumes documentation from Markdown files and Julia packages, and VitePress, which generates websites from Markdown files.

Documentation is therefore generated in two "stages". These are both executed by the first and main render function, in src/writers.jl.

Documenter.jl

First, the Documenter.jl pipeline is run. It takes as input the concerned Julia modules and Markdown files, and excecutes all doctests and runnable blocks.

From there, Documenter uses a plugin provided to the format keyword of makedocs to render to some viewable form. This is where DocumenterVitepress.jl steps in, with the MarkdownVitepress plugin.

That plugin takes in the Documenter Document which is generated once Documenter has parsed, run and expanded all the input Markdown files, and converts it to VitePress-flavoured Markdown, which is saved in docs/build/.documenter by default.

This conversion is done by the sometimes-recursive multiple dispatch based render function.

VitePress

VitePress is a NodeJS package which takes in Markdown files and generates a static site.

The first step we take is to replace several options in VitePress's configuration file by our own, if the user has not explicitly specified them. Notable ones are:

• base: the base path of the website. This is required, because Vitepress cannot generate relocatable websites - so we must know the exact path to our index.html when building.

• sidebar: the sidebar of the page, autogenerated from pages in makedocs.

Then, we simply ensure that all Node packages are installed, and run npm run docs:build, which builds a website.

In order to locally develop, run npm run docs:dev in another terminal. This will create a server.

Finalization

Finally, if deploying, we move files around such that the only thing deployed is the rendered webpage.

This means that the contents of build/.documenter are deleted, and the contents of build/final_site are moved into build proper. This allows the complete site to be committed directly.

Warning

This will probably not work if using a custom, non-detectable deployment configuration!