diff --git a/previews/PR109/404.html b/previews/PR109/404.html index e2a3f714..2409243f 100644 --- a/previews/PR109/404.html +++ b/previews/PR109/404.html @@ -15,7 +15,7 @@
DocumenterVitepress

Appearance

404

PAGE NOT FOUND

But if you don't change your direction, and if you keep looking, you may end up where you are heading.
Take me home
- + \ No newline at end of file diff --git a/previews/PR109/api.html b/previews/PR109/api.html index 9db96f2c..a8919150 100644 --- a/previews/PR109/api.html +++ b/previews/PR109/api.html @@ -4,7 +4,7 @@ DocumenterVitepress - + @@ -12,13 +12,13 @@ - + -
DocumenterVitepress

Appearance

Public API ​

# DocumenterVitepress.DocumenterVitepress — Module.
julia
DocumenterVitepress

Similar to DocumentationMarkdown.jl but designed to work with vitepress.

source


# DocumenterVitepress.MarkdownVitepress — Type.
julia
MarkdownVitepress(; repo, devbranch, devurl, kwargs...)

This is the main entry point for the Vitepress Markdown writer.

It is a config which can be passed to the format keyword argument in Documenter.makedocs, and causes it to emit a Vitepress site.

Quick start

When invoking Documenter.makedocs, replace the default format=Documenter.HTML(...) with:

julia
format=DocumenterVitepress.MarkdownVitepress(; repo = "...", devbranch = "...", devurl = "...")

Keyword arguments (config)

  • deploy_url: Required: The URL of the repository to which the documentation will be deployed. This must be the full URL, like rafaqz.github.io/Rasters.jl or geo.makie.jl.

  • repo: Required: The full URL of the repository to which the documentation will be deployed.

  • devbranch: Required: The name of the development branch, like master or main.

  • devurl: Required: The URL path to the development site, like dev or dev-branch.

  • description: A description of the website as a String.

  • build_vitepress: Determines whether to build the Vitepress site or only emit markdown files. Defaults to true, i.e., building the full Vitepress site.

  • install_npm: Determines whether to run npm install before building the Vitepress site. Defaults to true.

  • md_output_path: The path to which the Markdown files will be output. Defaults to $build/.documenter.

  • clean_md_output: Determines whether to clean up the Markdown assets after build, i.e., whether to remove the contents of md_output_path after the Vitepress site is built. Options are:

    • nothing: Default. Only remove the contents of md_output_path if the documentation will deploy, to save space.

    • true: Removes the contents of md_output_path after the Vitepress site is built.

    • false: Does not remove the contents of md_output_path after the Vitepress site is built.

  • deploy_decision: DeployDecision from Documenter.jl. This is used to determine whether to deploy the documentation or not. Options are:

    • nothing: Default. Automatically determine whether to deploy the documentation.

    • Documenter.DeployDecision: Override the automatic decision and deploy based on the passed config.

    It might be useful to use the latter if DocumenterVitepress fails to deploy automatically. You can pass a manually constructed Documenter.DeployDecision struct, or the output of Documenter.deploy_folder(Documenter.auto_detect_deploy_system(); repo, devbranch, devurl, push_preview).

Extended help

The repo kwarg is used to set the edit link for the documentation.

The devbranch and devurl kwargs are used to set the path of the static site, which Vitepress expects in advance.

source


See e.g. DocumenterVitepress.DocumenterVitepress

- +
DocumenterVitepress

Appearance

Public API ​

# DocumenterVitepress.DocumenterVitepress — Module.
julia
DocumenterVitepress

Similar to DocumentationMarkdown.jl but designed to work with vitepress.

source


# DocumenterVitepress.MarkdownVitepress — Type.
julia
MarkdownVitepress(; repo, devbranch, devurl, kwargs...)

This is the main entry point for the Vitepress Markdown writer.

It is a config which can be passed to the format keyword argument in Documenter.makedocs, and causes it to emit a Vitepress site.

Quick start

When invoking Documenter.makedocs, replace the default format=Documenter.HTML(...) with:

julia
format=DocumenterVitepress.MarkdownVitepress(; repo = "...", devbranch = "...", devurl = "...")

Keyword arguments (config)

  • deploy_url: Required: The URL of the repository to which the documentation will be deployed. This must be the full URL, like rafaqz.github.io/Rasters.jl or geo.makie.jl.

  • repo: Required: The full URL of the repository to which the documentation will be deployed.

  • devbranch: Required: The name of the development branch, like master or main.

  • devurl: Required: The URL path to the development site, like dev or dev-branch.

  • description: A description of the website as a String.

  • build_vitepress: Determines whether to build the Vitepress site or only emit markdown files. Defaults to true, i.e., building the full Vitepress site.

  • install_npm: Determines whether to run npm install before building the Vitepress site. Defaults to true.

  • md_output_path: The path to which the Markdown files will be output. Defaults to $build/.documenter.

  • clean_md_output: Determines whether to clean up the Markdown assets after build, i.e., whether to remove the contents of md_output_path after the Vitepress site is built. Options are:

    • nothing: Default. Only remove the contents of md_output_path if the documentation will deploy, to save space.

    • true: Removes the contents of md_output_path after the Vitepress site is built.

    • false: Does not remove the contents of md_output_path after the Vitepress site is built.

  • deploy_decision: DeployDecision from Documenter.jl. This is used to determine whether to deploy the documentation or not. Options are:

    • nothing: Default. Automatically determine whether to deploy the documentation.

    • Documenter.DeployDecision: Override the automatic decision and deploy based on the passed config.

    It might be useful to use the latter if DocumenterVitepress fails to deploy automatically. You can pass a manually constructed Documenter.DeployDecision struct, or the output of Documenter.deploy_folder(Documenter.auto_detect_deploy_system(); repo, devbranch, devurl, push_preview).

Extended help

The repo kwarg is used to set the edit link for the documentation.

The devbranch and devurl kwargs are used to set the path of the static site, which Vitepress expects in advance.

source


See e.g. DocumenterVitepress.DocumenterVitepress

+ \ No newline at end of file diff --git a/previews/PR109/assets/kiuvkkf.C-W3LInb.gif b/previews/PR109/assets/ahdpvsa.C-W3LInb.gif similarity index 100% rename from previews/PR109/assets/kiuvkkf.C-W3LInb.gif rename to previews/PR109/assets/ahdpvsa.C-W3LInb.gif diff --git a/previews/PR109/assets/api.md.BHP-yzXv.js b/previews/PR109/assets/api.md.CdSoUTuV.js similarity index 97% rename from previews/PR109/assets/api.md.BHP-yzXv.js rename to previews/PR109/assets/api.md.CdSoUTuV.js index 58ad0452..a9890bb9 100644 --- a/previews/PR109/assets/api.md.BHP-yzXv.js +++ b/previews/PR109/assets/api.md.CdSoUTuV.js @@ -1,7 +1,7 @@ import { _ as _export_sfc, c as createElementBlock, o as openBlock, a6 as createStaticVNode } from "./chunks/framework.C2uzFif8.js"; const __pageData = JSON.parse('{"title":"","description":"","frontmatter":{"outline":"deep"},"headers":[],"relativePath":"api.md","filePath":"api.md","lastUpdated":null}'); const _sfc_main = { name: "api.md" }; -const _hoisted_1 = /* @__PURE__ */ createStaticVNode('

Public API ​

# DocumenterVitepress.DocumenterVitepress — Module.
julia
DocumenterVitepress

Similar to DocumentationMarkdown.jl but designed to work with vitepress.

source


# DocumenterVitepress.MarkdownVitepress — Type.
julia
MarkdownVitepress(; repo, devbranch, devurl, kwargs...)

This is the main entry point for the Vitepress Markdown writer.

It is a config which can be passed to the format keyword argument in Documenter.makedocs, and causes it to emit a Vitepress site.

Quick start

When invoking Documenter.makedocs, replace the default format=Documenter.HTML(...) with:

julia
format=DocumenterVitepress.MarkdownVitepress(; repo = "...", devbranch = "...", devurl = "...")

Keyword arguments (config)

Extended help

The repo kwarg is used to set the edit link for the documentation.

The devbranch and devurl kwargs are used to set the path of the static site, which Vitepress expects in advance.

source


See e.g. DocumenterVitepress.DocumenterVitepress

', 6); +const _hoisted_1 = /* @__PURE__ */ createStaticVNode('

Public API ​

# DocumenterVitepress.DocumenterVitepress — Module.
julia
DocumenterVitepress

Similar to DocumentationMarkdown.jl but designed to work with vitepress.

source


# DocumenterVitepress.MarkdownVitepress — Type.
julia
MarkdownVitepress(; repo, devbranch, devurl, kwargs...)

This is the main entry point for the Vitepress Markdown writer.

It is a config which can be passed to the format keyword argument in Documenter.makedocs, and causes it to emit a Vitepress site.

Quick start

When invoking Documenter.makedocs, replace the default format=Documenter.HTML(...) with:

julia
format=DocumenterVitepress.MarkdownVitepress(; repo = "...", devbranch = "...", devurl = "...")

Keyword arguments (config)

Extended help

The repo kwarg is used to set the edit link for the documentation.

The devbranch and devurl kwargs are used to set the path of the static site, which Vitepress expects in advance.

source


See e.g. DocumenterVitepress.DocumenterVitepress

', 6); const _hoisted_7 = [ _hoisted_1 ]; diff --git a/previews/PR109/assets/api.md.BHP-yzXv.lean.js b/previews/PR109/assets/api.md.CdSoUTuV.lean.js similarity index 100% rename from previews/PR109/assets/api.md.BHP-yzXv.lean.js rename to previews/PR109/assets/api.md.CdSoUTuV.lean.js diff --git a/previews/PR109/assets/code_example.md.NW-nZBDo.js b/previews/PR109/assets/code_example.md.NW-nZBDo.js new file mode 100644 index 00000000..9a2eba9e --- /dev/null +++ b/previews/PR109/assets/code_example.md.NW-nZBDo.js @@ -0,0 +1,15 @@ +import { _ as _export_sfc, c as createElementBlock, o as openBlock, a6 as createStaticVNode } from "./chunks/framework.C2uzFif8.js"; +const __pageData = JSON.parse('{"title":"Julia code example","description":"","frontmatter":{},"headers":[],"relativePath":"code_example.md","filePath":"code_example.md","lastUpdated":null}'); +const _sfc_main = { name: "code_example.md" }; +const _hoisted_1 = /* @__PURE__ */ createStaticVNode('

Julia code example ​

The Julia code used here is done using the following packages versions:

julia
using Pkg\nPkg.status()
Status `~/work/DocumenterVitepress.jl/DocumenterVitepress.jl/docs/Project.toml`\n  [e30172f5] Documenter v1.3.0\n  [4710194d] DocumenterVitepress v0.0.17 `~/work/DocumenterVitepress.jl/DocumenterVitepress.jl`

And a simple task:

julia
2 + 2
4

ANSI example ​

julia
julia> printstyled("this is my color"; color = :red)
this is my color

A more colorful example from documenter:

julia
julia> for color in 0:15\n           print("\\e[38;5;$color;48;5;$(color)m  ")\n           print("\\e[49m", lpad(color, 3), " ")\n           color % 8 == 7 && println()\n       end
    0     1     2     3     4     5     6     7 \n    8     9    10    11    12    13    14    15

Font ​

This package uses the JuliaMono font by default, but you can override this in CSS.

This is what some common symbols look like:

julia
] [ = $ ; ( @ { " ) ? . } ⊽ ⊼ ⊻ ⊋ ⊊ ⊉ ⊈ ⊇ ⊆ ≥ ≤ ≢ ≡ ≠ ≉ ≈ ∪ ∩ ∜ ∛ √ ∘ ∌\n|> /> ^ % ` ∈

Eval example ​

From Julia's documentation landing page.

Julia 1.10 Documentation ​

Welcome to the documentation for Julia 1.10.

Work in progress!

This documentation is for an unreleased, in-development, version of Julia.

Note

The documentation is also available in PDF format: julia-1.10.2.pdf.

REPL example ​

```@repl\na = 1;\nb = 2; # hide\na + b\n```

produces

julia
julia> a = 1;\n\njulia> a + b\n3
```@repl\na = 1;\nb = 2;\na + b\n```

produces

julia
julia> a = 1;\n\njulia> b = 2;\n\njulia> a + b\n3
', 30); +const _hoisted_31 = [ + _hoisted_1 +]; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _hoisted_31); +} +const code_example = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + code_example as default +}; diff --git a/previews/PR109/assets/code_example.md.y99H8d3D.lean.js b/previews/PR109/assets/code_example.md.NW-nZBDo.lean.js similarity index 100% rename from previews/PR109/assets/code_example.md.y99H8d3D.lean.js rename to previews/PR109/assets/code_example.md.NW-nZBDo.lean.js diff --git a/previews/PR109/assets/code_example.md.y99H8d3D.js b/previews/PR109/assets/code_example.md.y99H8d3D.js deleted file mode 100644 index e273d378..00000000 --- a/previews/PR109/assets/code_example.md.y99H8d3D.js +++ /dev/null @@ -1,15 +0,0 @@ -import { _ as _export_sfc, c as createElementBlock, o as openBlock, a6 as createStaticVNode } from "./chunks/framework.C2uzFif8.js"; -const __pageData = JSON.parse('{"title":"Julia code example","description":"","frontmatter":{},"headers":[],"relativePath":"code_example.md","filePath":"code_example.md","lastUpdated":null}'); -const _sfc_main = { name: "code_example.md" }; -const _hoisted_1 = /* @__PURE__ */ createStaticVNode('

Julia code example ​

The Julia code used here is done using the following packages versions:

julia
using Pkg\nPkg.status()
Status `~/work/DocumenterVitepress.jl/DocumenterVitepress.jl/docs/Project.toml`\n  [e30172f5] Documenter v1.3.0\n  [4710194d] DocumenterVitepress v0.0.17 `~/work/DocumenterVitepress.jl/DocumenterVitepress.jl`

And a simple task:

julia
2 + 2
4

ANSI example ​

julia
julia> printstyled("this is my color"; color = :red)
this is my color

A more colorful example from documenter:

julia
julia> for color in 0:15\n           print("\\e[38;5;$color;48;5;$(color)m  ")\n           print("\\e[49m", lpad(color, 3), " ")\n           color % 8 == 7 && println()\n       end
    0     1     2     3     4     5     6     7 \n    8     9    10    11    12    13    14    15

Font ​

This package uses the JuliaMono font by default, but you can override this in CSS.

This is what some common symbols look like:

julia
] [ = $ ; ( @ { " ) ? . } ⊽ ⊼ ⊻ ⊋ ⊊ ⊉ ⊈ ⊇ ⊆ ≥ ≤ ≢ ≡ ≠ ≉ ≈ ∪ ∩ ∜ ∛ √ ∘ ∌\n|> /> ^ % ` ∈

Eval example ​

From Julia's documentation landing page.

Julia 1.10 Documentation ​

Welcome to the documentation for Julia 1.10.

Work in progress!

This documentation is for an unreleased, in-development, version of Julia.

Note

The documentation is also available in PDF format: julia-1.10.2.pdf.

REPL example ​

```@repl\na = 1;\nb = 2; # hide\na + b\n```

produces

julia
julia> a = 1;\n\njulia> a + b\n3
```@repl\na = 1;\nb = 2;\na + b\n```

produces

julia
julia> a = 1;\n\njulia> b = 2;\n\njulia> a + b\n3
', 30); -const _hoisted_31 = [ - _hoisted_1 -]; -function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { - return openBlock(), createElementBlock("div", null, _hoisted_31); -} -const code_example = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); -export { - __pageData, - code_example as default -}; diff --git a/previews/PR109/assets/getting_started.md.BVoEZw9W.js b/previews/PR109/assets/getting_started.md.DTI7Qe_J.js similarity index 96% rename from previews/PR109/assets/getting_started.md.BVoEZw9W.js rename to previews/PR109/assets/getting_started.md.DTI7Qe_J.js index 82d1f083..d5cef675 100644 --- a/previews/PR109/assets/getting_started.md.BVoEZw9W.js +++ b/previews/PR109/assets/getting_started.md.DTI7Qe_J.js @@ -1,7 +1,7 @@ import { _ as _export_sfc, c as createElementBlock, o as openBlock, a6 as createStaticVNode } from "./chunks/framework.C2uzFif8.js"; const __pageData = JSON.parse('{"title":"Getting started","description":"","frontmatter":{},"headers":[],"relativePath":"getting_started.md","filePath":"getting_started.md","lastUpdated":null}'); const _sfc_main = { name: "getting_started.md" }; -const _hoisted_1 = /* @__PURE__ */ createStaticVNode('

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\n├── Project.toml\n├── make.jl\n├── package-lock.json\n├── package.json\n└── src\n    ├── getting_started.md\n    ├── index.md\n    └── assets\n        └── favicon.ico\n        └── logo_dark.png\n    └── .vitepress\n        ├── config.mts\n        └── theme\n            └── index.ts\n            └── 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:

sh
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:

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

Build new docs from docs/src ​

To start working on your docs do the following steps:

shell
$ cd docs\ndocs $

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

shell
docs> julia\njulia> ]\npkg> activate .

Add packages as necessary. Here, we will need

shell
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/\n├── Project.toml\n├── make.jl\n├── package-lock.json\n├── package.json\n└── src\n    ├── getting_started.md\n    ├── index.md\n    └── assets\n        └── favicon.ico\n        └── logo_dark.png\n    └── .vitepress\n        ├── config.mts\n        └── theme\n            └── index.ts\n            └── style.css

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

shell
npm run docs:dev

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

', 31); +const _hoisted_1 = /* @__PURE__ */ createStaticVNode('

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\n├── Project.toml\n├── make.jl\n├── package-lock.json\n├── package.json\n└── src\n    ├── getting_started.md\n    ├── index.md\n    └── assets\n        └── favicon.ico\n        └── logo_dark.png\n    └── .vitepress\n        ├── config.mts\n        └── theme\n            └── index.ts\n            └── 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:

sh
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:

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

Build new docs from docs/src ​

To start working on your docs do the following steps:

shell
$ cd docs\ndocs $

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

shell
docs> julia\njulia> ]\npkg> activate .

Add packages as necessary. Here, we will need

shell
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/\n├── Project.toml\n├── make.jl\n├── package-lock.json\n├── package.json\n└── src\n    ├── getting_started.md\n    ├── index.md\n    └── assets\n        └── favicon.ico\n        └── logo_dark.png\n    └── .vitepress\n        ├── config.mts\n        └── theme\n            └── index.ts\n            └── style.css

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

shell
npm run docs:dev

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

', 31); const _hoisted_32 = [ _hoisted_1 ]; diff --git a/previews/PR109/assets/getting_started.md.BVoEZw9W.lean.js b/previews/PR109/assets/getting_started.md.DTI7Qe_J.lean.js similarity index 100% rename from previews/PR109/assets/getting_started.md.BVoEZw9W.lean.js rename to previews/PR109/assets/getting_started.md.DTI7Qe_J.lean.js diff --git a/previews/PR109/assets/markdown-examples.md.ChWAEo72.js b/previews/PR109/assets/markdown-examples.md.9joevAWD.js similarity index 99% rename from previews/PR109/assets/markdown-examples.md.ChWAEo72.js rename to previews/PR109/assets/markdown-examples.md.9joevAWD.js index e261d8cb..9fb97cb6 100644 --- a/previews/PR109/assets/markdown-examples.md.ChWAEo72.js +++ b/previews/PR109/assets/markdown-examples.md.9joevAWD.js @@ -1,7 +1,7 @@ import { _ as _export_sfc, E as resolveComponent, c as createElementBlock, J as createVNode, w as withCtx, m as createBaseVNode, a as createTextVNode, a6 as createStaticVNode, o as openBlock } from "./chunks/framework.C2uzFif8.js"; const __pageData = JSON.parse('{"title":"Markdown Extension Examples","description":"","frontmatter":{},"headers":[],"relativePath":"markdown-examples.md","filePath":"markdown-examples.md","lastUpdated":null}'); const _sfc_main = { name: "markdown-examples.md" }; -const _hoisted_1 = /* @__PURE__ */ createStaticVNode('

Markdown Extension Examples ​

This page demonstrates some of the built-in markdown extensions provided by VitePress.

Syntax Highlighting ​

VitePress provides Syntax Highlighting powered by Shiki, with additional features like line-highlighting:

Input

```js{4}\nexport default {\n  data () {\n    return {\n      msg: 'Highlighted!'\n    }\n  }\n}\n```

Output

js
export default {\n  data () {\n    return {\n      msg: 'Highlighted!'\n    }\n  }\n}

Code groups ​

js
/**\n * @type {import('vitepress').UserConfig}\n */\nconst config = {\n  // ...\n}\n\nexport default config
ts
import type { UserConfig } from 'vitepress'\n\nconst config: UserConfig = {\n  // ...\n}\n\nexport default config

Code focus ​

js
export default {\n  data () {\n    return {\n      msg: 'Focused!'\n    }\n  }\n}

Lists ​

  1. a

  2. b

  3. c 1. d

  4. e

Custom Containers ​

Input

md
::: info\n\nThis is an info box.\n\n:::\n\n::: tip\n\nThis is a tip.\n\n:::\n\n::: warning\n\nThis is a warning.\n\n:::\n\n::: danger\n\nThis is a dangerous warning.\n\n:::\n\n::: details\n\nThis is a details block.\n\n:::

Output

INFO

This is an info box.

TIP

This is a tip.

WARNING

This is a warning.

DANGER

This is a dangerous warning.

Details

This is a details block.

Tabs ​

', 24); +const _hoisted_1 = /* @__PURE__ */ createStaticVNode('

Markdown Extension Examples ​

This page demonstrates some of the built-in markdown extensions provided by VitePress.

Syntax Highlighting ​

VitePress provides Syntax Highlighting powered by Shiki, with additional features like line-highlighting:

Input

```js{4}\nexport default {\n  data () {\n    return {\n      msg: 'Highlighted!'\n    }\n  }\n}\n```

Output

js
export default {\n  data () {\n    return {\n      msg: 'Highlighted!'\n    }\n  }\n}

Code groups ​

js
/**\n * @type {import('vitepress').UserConfig}\n */\nconst config = {\n  // ...\n}\n\nexport default config
ts
import type { UserConfig } from 'vitepress'\n\nconst config: UserConfig = {\n  // ...\n}\n\nexport default config

Code focus ​

js
export default {\n  data () {\n    return {\n      msg: 'Focused!'\n    }\n  }\n}

Lists ​

  1. a

  2. b

  3. c 1. d

  4. e

Custom Containers ​

Input

md
::: info\n\nThis is an info box.\n\n:::\n\n::: tip\n\nThis is a tip.\n\n:::\n\n::: warning\n\nThis is a warning.\n\n:::\n\n::: danger\n\nThis is a dangerous warning.\n\n:::\n\n::: details\n\nThis is a details block.\n\n:::

Output

INFO

This is an info box.

TIP

This is a tip.

WARNING

This is a warning.

DANGER

This is a dangerous warning.

Details

This is a details block.

Tabs ​

', 24); const _hoisted_25 = /* @__PURE__ */ createBaseVNode("p", null, "a content", -1); const _hoisted_26 = /* @__PURE__ */ createBaseVNode("p", null, "b content", -1); const _hoisted_27 = /* @__PURE__ */ createBaseVNode("p", null, "a content 2", -1); diff --git a/previews/PR109/assets/markdown-examples.md.ChWAEo72.lean.js b/previews/PR109/assets/markdown-examples.md.9joevAWD.lean.js similarity index 100% rename from previews/PR109/assets/markdown-examples.md.ChWAEo72.lean.js rename to previews/PR109/assets/markdown-examples.md.9joevAWD.lean.js diff --git a/previews/PR109/assets/mime_examples.md.Cp_wLkGX.js b/previews/PR109/assets/mime_examples.md.DEPsRdsZ.js similarity index 99% rename from previews/PR109/assets/mime_examples.md.Cp_wLkGX.js rename to previews/PR109/assets/mime_examples.md.DEPsRdsZ.js index 8f4b12f5..a447028e 100644 --- a/previews/PR109/assets/mime_examples.md.Cp_wLkGX.js +++ b/previews/PR109/assets/mime_examples.md.DEPsRdsZ.js @@ -1,8 +1,8 @@ import { _ as _export_sfc, c as createElementBlock, o as openBlock, a6 as createStaticVNode } from "./chunks/framework.C2uzFif8.js"; -const _imports_0 = "/DocumenterVitepress.jl/previews/PR109/assets/hgtfizt.CGGmtknr.png"; -const _imports_1 = "/DocumenterVitepress.jl/previews/PR109/assets/xagmzsa.yDDNeA3I.jpeg"; -const _imports_2 = "/DocumenterVitepress.jl/previews/PR109/assets/kiuvkkf.C-W3LInb.gif"; -const _imports_3 = "/DocumenterVitepress.jl/previews/PR109/assets/kiuvkkf.C-W3LInb.gif"; +const _imports_0 = "/DocumenterVitepress.jl/previews/PR109/assets/yioldgr.CGGmtknr.png"; +const _imports_1 = "/DocumenterVitepress.jl/previews/PR109/assets/xjblyea.yDDNeA3I.jpeg"; +const _imports_2 = "/DocumenterVitepress.jl/previews/PR109/assets/ahdpvsa.C-W3LInb.gif"; +const _imports_3 = "/DocumenterVitepress.jl/previews/PR109/assets/ahdpvsa.C-W3LInb.gif"; const __pageData = JSON.parse('{"title":"MIME-type examples","description":"","frontmatter":{},"headers":[],"relativePath":"mime_examples.md","filePath":"mime_examples.md","lastUpdated":null}'); const _sfc_main = { name: "mime_examples.md" }; const _hoisted_1 = /* @__PURE__ */ createStaticVNode('

MIME-type examples ​

This file tests the output for all available MIME-types.

julia
"""\n    MediaOutput{MIME"..."}(contents::String)\n\nA struct representing media output with a specific MIME type.\n\n# Fields\n- `contents::String`: The contents of the media output.\n"""\nstruct MediaOutput{MimeType}\n    contents::Vector{UInt8}\nend\nMediaOutput{MimeType}(contents::String) where MimeType = MediaOutput{MimeType}(Vector{UInt8}(contents))\n# This defines the show method for the target MIME type only!\nBase.show(io, ::MimeType, media::MediaOutput{MimeType}) where MimeType = write(io, media.contents)\n# MediaOutput{MIME"text/plain"}("Hello there!")
julia
using DocumenterVitepress\nMediaOutput{MIME"image/png"}(read(joinpath(pathof(DocumenterVitepress) |> dirname |> dirname, "docs", "src", "assets", "logo.png")))

julia
MediaOutput{MIME"image/jpeg"}(read(download("https://upload.wikimedia.org/wikipedia/commons/thumb/0/0e/Felis_silvestris_silvestris.jpg/519px-Felis_silvestris_silvestris.jpg")))

julia
MediaOutput{MIME"image/svg+xml"}("https://upload.wikimedia.org/wikipedia/commons/6/6c/SVG_Simple_Icon.svg" |> download |> read)
julia
MediaOutput{MIME"image/gif"}(read(download("https://upload.wikimedia.org/wikipedia/commons/2/2c/Rotating_earth_%28large%29.gif")))

julia
MediaOutput{MIME"image/gif"}(read(download("https://upload.wikimedia.org/wikipedia/commons/2/2c/Rotating_earth_%28large%29.gif")))

', 13); diff --git a/previews/PR109/assets/mime_examples.md.Cp_wLkGX.lean.js b/previews/PR109/assets/mime_examples.md.DEPsRdsZ.lean.js similarity index 90% rename from previews/PR109/assets/mime_examples.md.Cp_wLkGX.lean.js rename to previews/PR109/assets/mime_examples.md.DEPsRdsZ.lean.js index c26f8707..62324d38 100644 --- a/previews/PR109/assets/mime_examples.md.Cp_wLkGX.lean.js +++ b/previews/PR109/assets/mime_examples.md.DEPsRdsZ.lean.js @@ -1,8 +1,8 @@ import { _ as _export_sfc, c as createElementBlock, o as openBlock, a6 as createStaticVNode } from "./chunks/framework.C2uzFif8.js"; -const _imports_0 = "/DocumenterVitepress.jl/previews/PR109/assets/hgtfizt.CGGmtknr.png"; -const _imports_1 = "/DocumenterVitepress.jl/previews/PR109/assets/xagmzsa.yDDNeA3I.jpeg"; -const _imports_2 = "/DocumenterVitepress.jl/previews/PR109/assets/kiuvkkf.C-W3LInb.gif"; -const _imports_3 = "/DocumenterVitepress.jl/previews/PR109/assets/kiuvkkf.C-W3LInb.gif"; +const _imports_0 = "/DocumenterVitepress.jl/previews/PR109/assets/yioldgr.CGGmtknr.png"; +const _imports_1 = "/DocumenterVitepress.jl/previews/PR109/assets/xjblyea.yDDNeA3I.jpeg"; +const _imports_2 = "/DocumenterVitepress.jl/previews/PR109/assets/ahdpvsa.C-W3LInb.gif"; +const _imports_3 = "/DocumenterVitepress.jl/previews/PR109/assets/ahdpvsa.C-W3LInb.gif"; const __pageData = JSON.parse('{"title":"MIME-type examples","description":"","frontmatter":{},"headers":[],"relativePath":"mime_examples.md","filePath":"mime_examples.md","lastUpdated":null}'); const _sfc_main = { name: "mime_examples.md" }; const _hoisted_1 = /* @__PURE__ */ createStaticVNode("", 13); diff --git a/previews/PR109/assets/xagmzsa.yDDNeA3I.jpeg b/previews/PR109/assets/xjblyea.yDDNeA3I.jpeg similarity index 100% rename from previews/PR109/assets/xagmzsa.yDDNeA3I.jpeg rename to previews/PR109/assets/xjblyea.yDDNeA3I.jpeg diff --git a/previews/PR109/assets/hgtfizt.CGGmtknr.png b/previews/PR109/assets/yioldgr.CGGmtknr.png similarity index 100% rename from previews/PR109/assets/hgtfizt.CGGmtknr.png rename to previews/PR109/assets/yioldgr.CGGmtknr.png diff --git a/previews/PR109/code_example.html b/previews/PR109/code_example.html index 22aeb6f2..895cc90e 100644 --- a/previews/PR109/code_example.html +++ b/previews/PR109/code_example.html @@ -4,7 +4,7 @@ Julia code example | DocumenterVitepress - + @@ -12,15 +12,15 @@ - + -
DocumenterVitepress

Appearance

Julia code example ​

The Julia code used here is done using the following packages versions:

julia
using Pkg
+    
DocumenterVitepress
Appearance
Julia code example ​
The Julia code used here is done using the following packages versions:
julia
using Pkg
 Pkg.status()
Status `~/work/DocumenterVitepress.jl/DocumenterVitepress.jl/docs/Project.toml`
   [e30172f5] Documenter v1.3.0
-  [4710194d] DocumenterVitepress v0.0.17 `~/work/DocumenterVitepress.jl/DocumenterVitepress.jl`
And a simple task:
julia
2 + 2
4
ANSI example ​
julia
julia> printstyled("this is my color"; color = :red)
this is my color
A more colorful example from documenter:
julia
julia> for color in 0:15
+  [4710194d] DocumenterVitepress v0.0.17 `~/work/DocumenterVitepress.jl/DocumenterVitepress.jl`
And a simple task:
julia
2 + 2
4
ANSI example ​
julia
julia> printstyled("this is my color"; color = :red)
this is my color
A more colorful example from documenter:
julia
julia> for color in 0:15
            print("\e[38;5;$color;48;5;$(color)m  ")
            print("\e[49m", lpad(color, 3), " ")
            color % 8 == 7 && println()
@@ -30,20 +30,20 @@
 a = 1;
 b = 2; # hide
 a + b
-```
produces
julia
julia> a = 1;
+```
produces
julia
julia> a = 1;
 
-julia> a + b
+julia> a + b
 3
```@repl
 a = 1;
 b = 2;
 a + b
-```
produces
julia
julia> a = 1;
+```
produces
julia
julia> a = 1;
 
-julia> b = 2;
+julia> b = 2;
 
-julia> a + b
-3

-    
+julia> a + b
+3
+ \ No newline at end of file diff --git a/previews/PR109/getting_started.html b/previews/PR109/getting_started.html index 1583a5e6..68dd4c3e 100644 --- a/previews/PR109/getting_started.html +++ b/previews/PR109/getting_started.html @@ -4,7 +4,7 @@ Getting started | DocumenterVitepress - + @@ -12,12 +12,12 @@ - + -
DocumenterVitepress

Appearance

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
+    
DocumenterVitepress
Appearance
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
@@ -32,7 +32,7 @@
         ├── 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:
sh
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:
sh
npm add -D vitepress
sh
pnpm add -D vitepress
sh
yarn add -D vitepress
sh
bun add -D vitepress
Build new docs from docs/src ​
To start working on your docs do the following steps:
shell
$ cd docs
+            └── 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:
sh
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:
sh
npm add -D vitepress
sh
pnpm add -D vitepress
sh
yarn add -D vitepress
sh
bun add -D vitepress
Build new docs from docs/src ​
To start working on your docs do the following steps:
shell
$ cd docs
 docs $
Then, in docs start a julia session and activate a new environment.
shell
docs> julia
 julia> ]
 pkg> activate .
Add packages as necessary. Here, we will need
shell
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/
@@ -50,8 +50,8 @@
         ├── config.mts
         └── theme
             └── index.ts
-            └── style.css
Then, run docs/make.jl, and in another terminal in the docs directory, run:
shell
npm run docs:dev
This will deploy your documentation locally on a webserver. See here to know more.

-    
+            └── style.css

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

shell
npm run docs:dev

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

+ \ No newline at end of file diff --git a/previews/PR109/hashmap.json b/previews/PR109/hashmap.json index 95a7530a..e40330ff 100644 --- a/previews/PR109/hashmap.json +++ b/previews/PR109/hashmap.json @@ -1 +1 @@ -{"api.md":"BHP-yzXv","getting_started.md":"BVoEZw9W","code_example.md":"y99H8d3D","mime_examples.md":"Cp_wLkGX","index.md":"BaOUAF67","render_pipeline.md":"dHqdVTHY","markdown-examples.md":"ChWAEo72"} +{"render_pipeline.md":"dHqdVTHY","api.md":"CdSoUTuV","code_example.md":"NW-nZBDo","markdown-examples.md":"9joevAWD","index.md":"BaOUAF67","mime_examples.md":"DEPsRdsZ","getting_started.md":"DTI7Qe_J"} diff --git a/previews/PR109/index.html b/previews/PR109/index.html index 85d212eb..b5191f63 100644 --- a/previews/PR109/index.html +++ b/previews/PR109/index.html @@ -4,7 +4,7 @@ DocumenterVitepress - + @@ -18,7 +18,7 @@
DocumenterVitepress

Appearance

DocumenterVitepress.jl

Document your code

A Markdown backend designed to work with VitePress and Documenter.jl

Getting Started
View on Github
API Examples
DocumenterVitepress
markdown

Markdown

Write in standard markdown syntax

Literate.jl

Parse scripts into markdown via Literate.jl

VUE components

Explore the possibilities with VUE components

What is DocumenterVitepress.jl?

DocumenterVitepress is a Markdown backend for Documenter.jl which is designed to work with the VitePress site generator, which is built off Vue.js.

It is meant to be used in conjunction with the vitepress Node.js package, which is why so much customization is required!

Basic usage

If you copy the contents of the template/ directory into your docs/ and the .github/Documenter.yml file to your repo, you should be good to go and edit docs as usual!

Just remember to edit the navbar in docs/src/.vitepress/config.mts, if you want it to be different from the sidebar.

To install a logo or favicon, you can put logo.png and favicon.ico in docs/src/assets, and they will be automatically detected.

- + \ No newline at end of file diff --git a/previews/PR109/markdown-examples.html b/previews/PR109/markdown-examples.html index 73fa8d37..3b954b62 100644 --- a/previews/PR109/markdown-examples.html +++ b/previews/PR109/markdown-examples.html @@ -4,7 +4,7 @@ Markdown Extension Examples | DocumenterVitepress - + @@ -12,12 +12,12 @@ - + -
DocumenterVitepress

Appearance

Markdown Extension Examples ​

This page demonstrates some of the built-in markdown extensions provided by VitePress.

Syntax Highlighting ​

VitePress provides Syntax Highlighting powered by Shiki, with additional features like line-highlighting:

Input

```js{4}
+    
DocumenterVitepress
Appearance
Markdown Extension Examples ​
This page demonstrates some of the built-in markdown extensions provided by VitePress.
Syntax Highlighting ​
VitePress provides Syntax Highlighting powered by Shiki, with additional features like line-highlighting:
Input
```js{4}
 export default {
   data () {
     return {
@@ -31,7 +31,7 @@
       msg: 'Highlighted!'
     }
   }
-}
Code groups ​
js
/**
+}
Code groups ​
js
/**
  * @type {import('vitepress').UserConfig}
  */
 const config = {
@@ -80,8 +80,8 @@
 
 :::
Output
INFO
This is an info box.
TIP
This is a tip.
WARNING
This is a warning.
DANGER
This is a dangerous warning.
Details
This is a details block.
Tabs ​
a content
a content 2
Nested Tabs ​
a content
GitHub-flavored Alerts ​
See: https://vitepress.dev/guide/markdown#github-flavored-alerts
Critical content.
Tables ​
See: https://vitepress.dev/guide/markdown#github-style-tables
TablesAreCool
col 3 isright-aligned$1600
col 2 iscentered$12
zebra stripesare neat$1
Equations ​
When a≠0, there are two solutions to ax2+bx+c=0 and they are
x=−b±b2−4ac2a
Don't type anything after the last double dollar sign, and make sure there are no spaces after the opening double dollar sign in the display math!
Footnotes (citation-style) ​
Here is the link for the paper of Babushka[1]
Escaping characters ​
The following example:
md
< `less` and `greater` > than, and the backtick \`.
outputs:
< less and greater > than, and the backtick `.
And also, this <was> an <issue> before.
Let's see if this one works:
```
 sshflags=`-i <keyfile>`
-```
it does,
sshflags=`-i <keyfile>`
but within inline text it does not. Ideas for the escaping sequence?
This is the expected sequence by vitepress:
<code> sshflags= `` `-i <keyfile> ` `` </code>
More ​
Check out the documentation for the full list of markdown extensions.
  1. This is Babushka's footnote! ↩︎

-    
+```

it does,

sshflags=`-i <keyfile>`

but within inline text it does not. Ideas for the escaping sequence?

This is the expected sequence by vitepress:

<code> sshflags= `` `-i <keyfile> ` `` </code>

More ​

Check out the documentation for the full list of markdown extensions.

  1. This is Babushka's footnote! ↩︎

+ \ No newline at end of file diff --git a/previews/PR109/mime_examples.html b/previews/PR109/mime_examples.html index 249c9eb9..703bf8ad 100644 --- a/previews/PR109/mime_examples.html +++ b/previews/PR109/mime_examples.html @@ -4,7 +4,7 @@ MIME-type examples | DocumenterVitepress - + @@ -12,12 +12,12 @@ - + -
DocumenterVitepress

Appearance

MIME-type examples ​

This file tests the output for all available MIME-types.

julia
"""
+    
DocumenterVitepress
Appearance
MIME-type examples ​
This file tests the output for all available MIME-types.
julia
"""
     MediaOutput{MIME"..."}(contents::String)
 
 A struct representing media output with a specific MIME type.
@@ -32,8 +32,8 @@
 # This defines the show method for the target MIME type only!
 Base.show(io, ::MimeType, media::MediaOutput{MimeType}) where MimeType = write(io, media.contents)
 # MediaOutput{MIME"text/plain"}("Hello there!")
julia
using DocumenterVitepress
-MediaOutput{MIME"image/png"}(read(joinpath(pathof(DocumenterVitepress) |> dirname |> dirname, "docs", "src", "assets", "logo.png")))
julia
MediaOutput{MIME"image/jpeg"}(read(download("https://upload.wikimedia.org/wikipedia/commons/thumb/0/0e/Felis_silvestris_silvestris.jpg/519px-Felis_silvestris_silvestris.jpg")))
julia
MediaOutput{MIME"image/svg+xml"}("https://upload.wikimedia.org/wikipedia/commons/6/6c/SVG_Simple_Icon.svg" |> download |> read)
julia
MediaOutput{MIME"image/gif"}(read(download("https://upload.wikimedia.org/wikipedia/commons/2/2c/Rotating_earth_%28large%29.gif")))
julia
MediaOutput{MIME"image/gif"}(read(download("https://upload.wikimedia.org/wikipedia/commons/2/2c/Rotating_earth_%28large%29.gif")))

-    
+MediaOutput{MIME"image/png"}(read(joinpath(pathof(DocumenterVitepress) |> dirname |> dirname, "docs", "src", "assets", "logo.png")))

julia
MediaOutput{MIME"image/jpeg"}(read(download("https://upload.wikimedia.org/wikipedia/commons/thumb/0/0e/Felis_silvestris_silvestris.jpg/519px-Felis_silvestris_silvestris.jpg")))

julia
MediaOutput{MIME"image/svg+xml"}("https://upload.wikimedia.org/wikipedia/commons/6/6c/SVG_Simple_Icon.svg" |> download |> read)
julia
MediaOutput{MIME"image/gif"}(read(download("https://upload.wikimedia.org/wikipedia/commons/2/2c/Rotating_earth_%28large%29.gif")))

julia
MediaOutput{MIME"image/gif"}(read(download("https://upload.wikimedia.org/wikipedia/commons/2/2c/Rotating_earth_%28large%29.gif")))

+ \ No newline at end of file diff --git a/previews/PR109/render_pipeline.html b/previews/PR109/render_pipeline.html index d985d912..85feb87a 100644 --- a/previews/PR109/render_pipeline.html +++ b/previews/PR109/render_pipeline.html @@ -4,7 +4,7 @@ The rendering process | DocumenterVitepress - + @@ -17,8 +17,8 @@ -
DocumenterVitepress

Appearance

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!

- +
DocumenterVitepress

Appearance

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!

+ \ No newline at end of file