Getting started

As a tutorial, we will go through and explain the folder and files structure used to generate this website. You could use this as a template for your project's documentation.

Quick start

In general, you can copy the template folder to your docs folder and the .github/Documenter.yml action file from DocumenterVitepress.jl to your repo, and be pretty much good to go and edit docs as usual!

Since we're concerned only with documentation, we'll specifically look at the docs folder of your Julia project or package here.

For more information on how to structure this, see the Documenter.jl guide! In this quick start, we will focus solely on how to set up DocumenterVitepress assuming you already have some basic docs (even just an index.md will do).

Project structure

In order to start as quickly as possible, we recommend you copy the Project.toml, make.jl, package.json, and src folders to your own documentation.

DocumenterVitepress/docs
├── Project.toml
├── make.jl
├── package-lock.json
├── package.json
└── src
    ├── getting_started.md
    ├── index.md
    └── assets
        └── favicon.ico
        └── logo_dark.png
    └── .vitepress
        ├── config.mts
        └── theme
            └── index.ts
            └── style.css

You can ignore the rest of the files which are actually in DocumenterVitepress/docs/src for now - those show how to use advanced APIs, like

VitePress Installation

Start at the docs level:

docs $

Prerequisites

DocumenterVitepress.jl is completely self-contained and installs all of its dependencies (including its own isolated version of npm) automatically.

However, to view your documentation live when developing locally, you will need to install npm and instantiate the

VitePress can be used on its own, or be installed into an existing project. In both cases, you can install it with:

::: code-group

npm add -D vitepress
pnpm add -D vitepress
yarn add -D vitepress
bun add -D vitepress

:::

Build new docs from docs/src

To start working on your docs do the following steps:

$ cd docs
docs $

Then, in docs start a julia session and activate a new environment.

docs> julia
julia> ]
pkg> activate .

Add packages as necessary. Here, we will need

pkg>  add DocumenterVitepress, Documenter

These packages will be used in the make.jl file.

Setting up the Folder Structure

The files for this page in the docs folder have the following structure:

docs/
├── Project.toml
├── make.jl
├── package-lock.json
├── package.json
└── src
    ├── getting_started.md
    ├── index.md
    └── assets
        └── favicon.ico
        └── logo_dark.png
    └── .vitepress
        ├── config.mts
        └── theme
            └── index.ts
            └── style.css

Then, run docs/make.jl, and in another terminal in the docs directory, run:

npm run docs:dev

This will deploy your documentation locally on a webserver. See here to know more.