DocumenterVitepress.jl

https://luxdl.github.io/DocumenterVitepress.jl/dev/
Admin
DocumenterVitepress.jl is a Markdown backend for Documenter.jl designed to generate static...
Tokens:15,418
Snippets:210
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Serve Documentation Locally

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/get_started

Commands to start a local server to view the generated documentation.

```julia
pkg> activate . # do this inside the docs folder
using LiveServer

LiveServer.serve(; dir = "build/1")
```

--------------------------------

### Install LiveServer

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/get_started

Add the LiveServer package to the docs environment for local previewing.

```julia
pkg> add LiveServer
```

--------------------------------

### Start Vitepress Development Server

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/get_started

Run the Vitepress development server with hot-reload capabilities.

```sh
docs $ npm run docs:dev # in a new terminal
```

--------------------------------

### Run development server

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/devs/internal_api

Starts the Vitepress dev server for documentation built from Markdown files.

```julia
dev_docs(builddir::String; md_output_path = ".documenter")
```

--------------------------------

### Render SVG and GIF images

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/mime_examples

Examples of rendering SVG and GIF media types.

```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")))
```

--------------------------------

### Render PNG images

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/mime_examples

Examples of rendering PNG images with and without DPI metadata.

```julia
using DocumenterVitepress
MediaOutput{MIME"image/png"}(read(joinpath(pathof(DocumenterVitepress) |> dirname |> dirname, "docs", "src", "assets", "plot_without_dpi.png")))
```

```julia
using DocumenterVitepress
MediaOutput{MIME"image/png"}(read(joinpath(pathof(DocumenterVitepress) |> dirname |> dirname, "docs", "src", "assets", "plot_with_dpi.png")))
```

--------------------------------

### Install DocumenterVitepress dependencies

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/documenter_to_vitepress_docs_example

Use the Julia package manager to add DocumenterVitepress to your documentation environment.

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

--------------------------------

### Get Vitepress dependencies

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/devs/internal_api

Retrieves a dictionary of dependencies contributed by a plugin.

```julia
vitepress_dependencies(plugin::Documenter.Plugin) -> Dict{String,String}
```

--------------------------------

### Run doctests with @doctest

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/code_example

Use @doctest blocks to verify code examples against expected output.

```julia
@doctest
julia> 1 + 1
2
```

--------------------------------

### Get Vitepress components

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/devs/internal_api

Defines Vue components to be registered globally in the Vitepress theme.

```julia
vitepress_components(plugin::Documenter.Plugin) -> Vector{@NamedTuple{name::String, import_path::String}}
```

--------------------------------

### Get Vitepress assets

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/devs/internal_api

Retrieves absolute directory paths for assets to be copied into the Vitepress public directory.

```julia
vitepress_assets(plugin::Documenter.Plugin) -> Vector{String}
```

--------------------------------

### NewCM Font Mathematical Notation

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Examples of complex mathematical notation using NewCM fonts.

```markdown
Display math for triple integrals:
```math
\oiiint_{\Omega} f(x,y,z) \, dx\,dy\,dz
```
```

```markdown
```math
\begin{equation}
R_{\mu\nu} - \frac{1}{2}Rg_{\mu\nu} + \Lambda g_{\mu\nu} = \frac{8\pi G}{c^4}T_{\mu\nu} \label{eq:einstein}
\end{equation}
```
```

--------------------------------

### Get MIME priority

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/devs/internal_api

Returns a priority value for a given MIME type to assist in rendering selection.

```julia
mime_priority(mime::MIME)::Float64
```

--------------------------------

### Build and serve documentation

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/documenter_to_vitepress_docs_example

Commands to build the documentation and serve it locally using LiveServer or Vitepress.

```julia
julia> include("make.jl")
```

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

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

--------------------------------

### Build Documentation

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/get_started

Execute the build process locally.

```julia
julia> include("make.jl")
```

--------------------------------

### Manual Rebuild and Serve

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/get_started

Manually rebuild documentation and serve the build directory using LiveServer.

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

--------------------------------

### Build documentation site

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/devs/internal_api

Builds the Vitepress site in the specified directory.

```julia
build_docs(builddir::String; md_output_path = ".documenter")
```

--------------------------------

### Define custom containers

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Use the ::: syntax to create styled containers like info, tip, warning, danger, and details blocks.

```markdown
::: 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.

:::
```

--------------------------------

### Configure Deployment

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/get_started

Replace the standard deploydocs call with the DocumenterVitepress version.

```julia
DocumenterVitepress.deploydocs(;
    repo = "github.com/YourName/YourPackage.jl",
    target = joinpath(@__DIR__, "build"),
    branch = "gh-pages",
    devbranch = "main",
    push_preview = true,
)
```

--------------------------------

### Initialize MarkdownVitepress Configuration

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/api

The main configuration type used to define the Vitepress output format.

```julia
MarkdownVitepress(; repo, devbranch, devurl, kwargs...)
```

--------------------------------

### Live Development with servedocs

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/get_started

Use servedocs to watch source files and trigger automatic rebuilds of the documentation.

```julia
using LiveServer

servedocs(; buildfoldername="build/1")
```

--------------------------------

### Project Dependencies and Scripts

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/repo_stars

Configuration for package dependencies and build scripts in package.json.

```json
{
  "devDependencies": {
    "@nolebase/vitepress-plugin-enhanced-readabilities": "^2.15.0",
    "@types/d3-format": "^3.0.4", 
    "@types/node": "^22.13.9", 
    "markdown-it": "^14.1.0",
    "markdown-it-mathjax3": "^4.3.2",
    "vitepress": "^1.5.0",
    "vitepress-plugin-tabs": "^0.5.0"
  },
  "scripts": {
    "docs:dev": "vitepress dev build/.documenter",
    "docs:build": "vitepress build build/.documenter",
    "docs:preview": "vitepress preview build/.documenter"
  },
  "dependencies": {
    "d3-format": "^3.1.0", 
    "markdown-it-footnote": "^4.0.0"
  }
}
```

--------------------------------

### Configure Full Screen Space

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/style_css

CSS settings to allow content to fill all available screen space.

```css
/* https://bddxg.top/article/note/vitepress优化/一些细节上的优化.html#文档页面调整-加宽 */

@media (min-width: 1440px) {
  .VPSidebar {
    padding-left: 20px !important;
    width: 250px !important;
  }
  .VPNavBar .title {
    padding-left: 15px !important;
    width: 230px !important;
  }
  .VPContent.has-sidebar {
    padding-left: 250px !important;
    padding-right: 5vw !important;
  }
  .VPNavBar .curtain {
    width: 100% !important;
  }
  .VPDoc {
    padding: 32px 0 0 !important;
  }
  .VPNavBar.has-sidebar .content {
    padding-left: 250px !important;
    padding-right: 20px !important;
  }
  
  .VPNavBar .divider {
    padding-left: 250px !important;
  }
}

@media (min-width: 960px) {
  .VPDoc {
    padding: 32px 32px 0 10 !important;
  }
  .VPContent.has-sidebar {
    padding-left: 255px !important;
  }
}

.VPNavBar {
  padding-right: 0px !important;
}

.VPDoc.has-aside .content-container {
  max-width: 100% !important;
}
.aside {
  max-width: 200px !important;
  padding-left: 0 !important;
}

/* This one does the right menu */

.VPDocOutlineItem li {
  text-overflow: ellipsis;
  overflow: hidden;
  white-space: nowrap;
  max-width: 200px;
}

.VPNavBar .title {
  text-overflow: ellipsis;
  overflow: hidden;
  white-space: nowrap;
}
```

--------------------------------

### Configure make.jl

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/get_started

Update the makedocs call to use the MarkdownVitepress format.

```julia
using Documenter
using DocumenterVitepress

makedocs(;
    # ... your other arguments ...
    format = DocumenterVitepress.MarkdownVitepress(
        repo = "github.com/YourName/YourPackage.jl",
        devbranch = "main", # or master, trunk, ...
        devurl = "dev",
    ),
)
```

--------------------------------

### Deploy documentation

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/devs/internal_api

Deploys documentation built with DocumenterVitepress, wrapping the standard Documenter.deploydocs to handle multiple base aliases.

```julia
deploydocs(; repo, target, branch, devbranch, push_preview, kwargs...)
```

--------------------------------

### Project Directory Structure

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/get_started

The optional directory structure for custom assets and Vitepress configuration.

```text
        ├── assets/            # Optional: custom assets
        │   ├── favicon.ico
        │   └── logo.png
        └── .vitepress/        # Optional: custom Vitepress config
            ├── config.mts
            └── theme/
                ├── index.ts
                └── style.css
```

--------------------------------

### Configure GitHub Actions for PR Preview Comments

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/get_started

Add this workflow file to .github/workflows/preview-comment.yml to automatically post documentation preview URLs on pull requests.

```yaml
name: Preview comment

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  pull-requests: write

jobs:
  comment:
    name: Post preview URL
    runs-on: ubuntu-latest
    # Only run on PRs from the same repo (not forks)
    if: github.event.pull_request.head.repo.full_name == github.repository

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Extract deploy repo from make.jl
        id: deploy
        run: |
          # Looks for: deploy_repo = "github.com/owner/repo.git"
          DEPLOY_REPO=$(grep -oP 'deploy_repo\s*=\s*"github\.com/\K[^"]+' docs/make.jl | sed 's/\.git$//' || true)

          if [ -n "$DEPLOY_REPO" ]; then
            echo "repo=$DEPLOY_REPO" >> "$GITHUB_OUTPUT"
          else
            # No cross-repo deployment found, fall back to the source repo
            echo "repo=${{ github.repository }}" >> "$GITHUB_OUTPUT"
          fi

      - name: Comment preview URL
        uses: actions/github-script@v7
        env:
          DEPLOY_REPO: ${{ steps.deploy.outputs.repo }}
        with:
          script: |
            const pr = context.issue.number;
            const [deployOwner, deployRepoName] = process.env.DEPLOY_REPO.split("/");

            const previewUrl = `https://${deployOwner}.github.io/${deployRepoName}/previews/PR${pr}/`;
            const marker = "<!-- documenter-preview-comment -->";
            const body = [
              marker,
              "### 📚 Documentation preview 🚀",
              "",
              `**Preview URL:** [${previewUrl}](${previewUrl})`,
              "",
              "> [!NOTE]",
              "> The preview will be available once the documentation build completes successfully, and will reflect the last successful build for this PR.",
            ].join("\n");

            const { data: comments } = await github.rest.issues.listComments({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: pr,
            });

            const existing = comments.find((c) => c.body?.includes(marker));

            if (!existing) {
              await github.rest.issues.createComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: pr,
                body,
              });
            }
```

--------------------------------

### Configure Documenter.makedocs for Vitepress

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/api

Replace the default HTML format with the MarkdownVitepress configuration in your makedocs call.

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

--------------------------------

### Generate documentation path

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/devs/internal_api

Returns a file path in the mdfolder directory that mirrors the src directory tree.

```julia
docpath(file, mdfolder)
```

--------------------------------

### Generate template files

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/devs/internal_api

Copies template files to a target directory and replaces the package name placeholder.

```julia
generate_template(target_directory::String, package = "YourPackage")
```

```julia
generate_template(".julia/dev/MyPackage/docs", "MyPackage")
```

--------------------------------

### Render document

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/devs/internal_api

Main entry point for rendering Documenter documents to Vitepress-flavored Markdown.

```julia
render(args...)
```

```julia
render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Node, element::Eltype, page, doc; kwargs...)
```

--------------------------------

### Configure DocumenterVitepress in make.jl

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev

Use the MarkdownVitepress format in makedocs and deploy using the package's deploydocs function.

```julia
using Documenter
using DocumenterVitepress
makedocs(;
    format=DocumenterVitepress.MarkdownVitepress(
      repo = "...",
      devbranch = "...",
      devurl = "dev"),
    )
# and for deploying use
DocumenterVitepress.deploydocs(;
    repo = "...",
    target = joinpath(@__DIR__, "build"),
    branch = "gh-pages",
    devbranch = "...",
    push_preview = true,
)
```

--------------------------------

### Project Directory Structure

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/style_css

Shows the location of CSS files within the project structure.

```text
MyPackage.jl
├── CHANGELOG.md
├── docs
│   ├── src
│   │   ├── .vitepress
│   │   │   └── theme
│   │   │       ├── style.css
│   │   │       ├── docstrings.css
│   │   │       └── overrides.css
│   │   └── ...
│   ├── make.jl
│   └── ...
└── ...
```

--------------------------------

### Create a DataFrame in Julia

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Initializes a new DataFrame with specified columns and values.

```julia
using DataFrames
DataFrame(A=1:3, B=5:7, fixed=1)
```

--------------------------------

### Configure Repository Data

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/repo_stars

Define the repository path for star tracking.

```typescript
const REPO = "LuxDL/DocumenterVitepress.jl"; # change to "u/repo"
```

--------------------------------

### Generate Vitepress Template

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/get_started

Create the necessary Vitepress configuration and theme files for advanced customization.

```julia
using DocumenterVitepress

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

--------------------------------

### Write Redirect Index Method

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/devs/internal_api

Writes an index.html file as a meta-refresh redirect to a specified target directory.

```julia
write_redirect_index!(root, target)
```

--------------------------------

### Check Package Status

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/code_example

Executes Pkg.status() to display the current project environment dependencies.

```julia
using Pkg
Pkg.status()
```

--------------------------------

### write_redirect_index!(root, target)

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/devs/internal_api

Writes a meta-refresh redirect index.html file to the specified root directory, pointing to the target path.

```APIDOC
## write_redirect_index!(root, target)

### Description
Write `root/index.html` as a meta-refresh redirect to `./target/`, mirroring what `Documenter.deploydocs` does for the standard `versions=` argument. No-op if `target` is `nothing`, or if `index.html` exists and wasn't generated by Documenter or DocumenterVitepress.

### Signature
`write_redirect_index!(root, target)`

### Parameters
- **root** (String) - The root directory where the index.html will be written.
- **target** (String|Nothing) - The target path for the redirect.
```

--------------------------------

### Simulate REPL sessions with @repl

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/code_example

Use @repl blocks to display interactive Julia sessions. Supports hiding lines using # hide and focusing lines with [!code focus].

```julia
@repl
a = 1;
b = 2;
a + b
```

```julia
@repl
a = 1;
b = 2; # [!code focus] # hide
a + b
```

```julia
@repl
using StyledStrings
styled"{red:red} {green:green} {blue:blue} {cyan,bold:cyan bold}"
```

--------------------------------

### Julia LaTeXStrings Usage

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Demonstrates how to use the LaTeXStrings package in Julia to define LaTeX-formatted strings.

```julia
using LaTeXStrings
L"an equation: $\alpha^2$"
```

--------------------------------

### GitHub-flavored Alerts

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Use blockquotes with the [!WARNING] syntax to create alert callouts.

```markdown
> [!WARNING]
> Critical content.
```

--------------------------------

### Configure Author Badges via Frontmatter

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/author_badge

Define a list of authors with optional platform, avatar, and link metadata in the document frontmatter.

```yaml
---
authors:
  - name: Jane Smith
  - name: John Doe
    platform: bluesky
  - name: Lazaro
    avatar: https://avatars.githubusercontent.com/u/19525261?v=4
    platform: github
    link: https://github.com/lazarusA

---

## Badges via the frontmatter

<Authors />
```

--------------------------------

### Single Equation Labeling

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Use the equation environment inside a math block to label and reference equations.

```markdown
This is a simple equation

```math
\begin{equation}
x=0 \label{eq:a}
\end{equation}
```
and now we can reference this as Eq. ``\eqref{eq:a}``.
```

--------------------------------

### MarkdownVitepress Constructor

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/api

The MarkdownVitepress constructor is the primary entry point for configuring the Vitepress Markdown writer within Documenter.jl.

```APIDOC
## MarkdownVitepress

### Description
Configures the Documenter.jl writer to emit a Vitepress site. This object should be passed to the `format` keyword argument in `Documenter.makedocs`.

### Signature
`MarkdownVitepress(; repo, devbranch, devurl, kwargs...)`

### Parameters
- **repo** (String) - Required - The repository URL.
- **devbranch** (String) - Required - The development branch name.
- **devurl** (String) - Required - The development URL path.
- **kwargs** (Any) - Optional - Additional keyword arguments for configuration.

### Usage Example
```julia
format=DocumenterVitepress.MarkdownVitepress(; 
    repo = "...", 
    devbranch = "...", 
    devurl = "..."
)
```
```

--------------------------------

### Tabbed Content Syntax

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Use the :::tabs container to create tabbed interfaces. Each tab is defined by the == syntax.

```markdown
:::tabs

== tab a

a content

== tab b

b content

:::

:::tabs

== tab a

a content 2

== tab b

b content 2

:::
```

--------------------------------

### Access the DocumenterVitepress Module

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/api

The primary module for the package.

```julia
DocumenterVitepress
```

--------------------------------

### Generate a Table of Contents with @contents

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/code_example

Define a list of pages and a depth level to automatically generate a hierarchical navigation list. Ensure all paths are relative to the documentation root.

```julia
```@contents
Pages = [
    "get_started.md",
    "documenter_to_vitepress_docs_example.md",
    "style_css.md",
    "code_example.md",
    "markdown-examples.md",
    "mime_examples.md",
    "citations.md",
    "style_css.md",
    "author_badge.md",
    "repo_stars.md",
    "../devs/render_pipeline.md",
    "../devs/internal_api.md",
    "../api.md"
    ]
Depth = 3
```
```

--------------------------------

### Update make.jl for DocumenterVitepress

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/documenter_to_vitepress_docs_example

Replace the standard Documenter.jl configuration with the DocumenterVitepress format in your make.jl file.

```julia
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",
)
```

--------------------------------

### Perform Simple Arithmetic

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/code_example

Executes a basic addition operation.

```julia
2 + 2
```

--------------------------------

### Generate dynamic documentation with @eval

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/code_example

Use @eval blocks to execute Julia code and render the resulting Markdown output dynamically.

```julia
@eval
io = IOBuffer()
release = isempty(VERSION.prerelease)
v = "$(VERSION.major).$(VERSION.minor)"
!release && (v = v*"-$(first(VERSION.prerelease))")
print(io, """
    # Julia $(v) Documentation

    Welcome to the documentation for Julia $(v).

    """)
if true # !release
    print(io,"""
        !!! warning "Work in progress!"
            This documentation is for an unreleased, in-development, version of Julia.
        """)
end
import Markdown
Markdown.parse(String(take!(io)))
```

```julia
@eval
file = "julia-1.10.2.pdf"
url = "https://raw.githubusercontent.com/JuliaLang/docs.julialang.org/assets/$(file)"
import Markdown
Markdown.parse("""
!!! note
    The documentation is also available in PDF format: [$file]($url).
""")
```

--------------------------------

### Comprehensive Mathematical Alignment

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

A collection of various mathematical notations including manifolds, direct sums, and action integrals.

```latex
\begin{align}
\mathcal{M} &: \text{Spacetime manifold} \label{eq:manifold} \\
\bigoplus_{i \in I} \mathcal{V}_i &\subseteq \prod_{j=1}^{\infty} \mathbb{K}_j \quad \text{(direct sum of vector spaces)} \label{eq:direct-sum} \\
\mathfrak{L}[\phi] &= \int_{\mathcal{M}} \mathscr{L}(\phi, \partial_\mu \phi) \sqrt{-g} \, d^4x \label{eq:action} \\
\boldsymbol{\nabla} \times \boldsymbol{B} &= \mu_0\left(\boldsymbol{J} + \varepsilon_0\frac{\partial \boldsymbol{E}}{\partial t}\right) \label{eq:ampere-maxwell} \\
\widehat{\mathbb{Q}}_p &\curvearrowright \mathfrak{gl}_n(\mathbb{C}) \rightrightarrows \text{Aut}(\mathcal{H}) \label{eq:group-action}
\end{align}
```

--------------------------------

### Video with Title Attribute

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/video_embedding

Include both an alt attribute and a title attribute for the video.

```markdown
![Click to play](./my_video.mp4 "Also my title")
```

--------------------------------

### Modify configuration file

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/devs/internal_api

Updates the Vitepress configuration file by replacing placeholder strings with runtime-determined values.

```julia
modify_config_file(doc, settings, deploy_decision)
```

--------------------------------

### Vite Configuration for Components

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/repo_stars

Configure path aliases and SSR exclusions in config.mts.

```typescript
import path from 'path'

export default defineConfig({
vite: {
    resolve: {
      alias: {
        '@': path.resolve(__dirname, '../components')
      }
    },
    build: {
      assetsInlineLimit: 0, // so we can tell whether we have created inlined images or not, we don't let vite inline them
    },
    optimizeDeps: {
      exclude: [ 
        '@nolebase/vitepress-plugin-enhanced-readabilities/client',
        'vitepress',
        '@nolebase/ui',
      ], 
    }, 
    ssr: { 
      noExternal: [ 
        // If there are other packages that need to be processed by Vite, you can add them here.
        '@nolebase/vitepress-plugin-enhanced-readabilities',
        '@nolebase/ui',
      ], 
    },
  },

})
```

--------------------------------

### Print ANSI Colored Text

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/code_example

Demonstrates printing text with specific ANSI color codes.

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

--------------------------------

### Multi-line Align with Labels

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Reference multiple labeled lines within an align environment using \eqref or \ref.

```markdown
```math
\begin{align}
\nabla\cdot\mathbf{E}  &= 4 \pi \rho \label{eq:c} \\
\nabla\cdot\mathbf{B}  &= 2 \\
\nabla\times\mathbf{E} &= - \frac{1}{c} \frac{\partial\mathbf{B}}{\partial t} \label{eq:d} \\
\nabla\times\mathbf{B} &= - \frac{1}{c}
\left(4 \pi \mathbf{J} + \frac{\partial\mathbf{E}}{\partial t}\right)
\end{align}
```

See $\eqref{eq:c}$? And what about $\ref{eq:d}$? Or simply typed as \eqref{eq:c} and \ref{eq:d}!

Also works using $$\ref{eq:c}$$ or without spaces: equation\eqref{eq:d}goes here!
```

--------------------------------

### Provide Icon Attribution

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/author_badge

Include the required attribution link when using default icons provided by icons8.

```markdown
Icons by [icons8](https://icons8.com).
```

--------------------------------

### Create code groups

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Use the code-group directive to present multiple code snippets in a tabbed interface.

```markdown
::: code-group

```julia [one line]
using Gnuplot
t = 0:0.001:1
@gp t sin.(10π*t) "w l tit 'sin' lc 'gray'"
```

```julia [two lines]
using Gnuplot
x = -2π:0.001:2π
@gp x sin.(x) "w l t 'sin' lw 2 lc '#56B4E9'" "set grid"
@gp :- xrange = (-2π - 0.3, 2π + 0.3) yrange = (-1.1,1.1)
@gp :- x cos.(x) "w l t 'cos' lw 2 lc rgb '#E69F00'"
```

:::
```

--------------------------------

### VitePress Theme Integration

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/repo_stars

Register components and layout overrides in the VitePress theme index file.

```typescript
// .vitepress/theme/index.ts
import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import type { Theme as ThemeConfig } from 'vitepress'

import { 
  NolebaseEnhancedReadabilitiesMenu, 
  NolebaseEnhancedReadabilitiesScreenMenu, 
} from '@nolebase/vitepress-plugin-enhanced-readabilities/client'

import VersionPicker from "@/components/VersionPicker.vue"
import StarUs from '@/components/StarUs.vue'
import AuthorBadge from '@/components/AuthorBadge.vue'
import Authors from '@/components/Authors.vue'
import { enhanceAppWithTabs } from 'vitepress-plugin-tabs/client'

import '@nolebase/vitepress-plugin-enhanced-readabilities/client/style.css'
import './style.css'
import './docstrings.css'

export const Theme: ThemeConfig = {
  extends: DefaultTheme,
  Layout() {
    return h(DefaultTheme.Layout, null, {
      'nav-bar-content-after': () => [
        h(StarUs), 
        h(NolebaseEnhancedReadabilitiesMenu), // Enhanced Readabilities menu
      ],
      // A enhanced readabilities menu for narrower screens (usually smaller than iPad Mini)
      'nav-screen-content-after': () => h(NolebaseEnhancedReadabilitiesScreenMenu),
    })
  },
  enhanceApp({ app, router, siteData }) {
    enhanceAppWithTabs(app);
    app.component('VersionPicker', VersionPicker);
    app.component('AuthorBadge', AuthorBadge)
    app.component('Authors', Authors)
  }
}
export default Theme
```

--------------------------------

### DocumenterVitepress Configuration

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/api

The configuration interface for DocumenterVitepress, used to define repository settings, deployment paths, and site behavior.

```APIDOC
## DocumenterVitepress Configuration

### Description
Configures the deployment and build settings for a Vitepress documentation site using Documenter.jl.

### Parameters
- **repo** (String) - Required - The full URL of the repository to which the documentation will be deployed.
- **devbranch** (String) - Optional - The name of the development branch (e.g., 'main').
- **devurl** (String) - Optional - The URL path to the development site.
- **deploy_url** (String) - Optional - The full URL of the repository to which the documentation will be deployed.
- **description** (String) - Optional - A description of the website.
- **build_vitepress** (Bool) - Optional - Determines whether to build the Vitepress site. Defaults to true.
- **install_npm** (Bool) - Optional - Determines whether to run npm install. Defaults to true.
- **md_output_path** (String) - Optional - The path to output Markdown files. Defaults to $build/.documenter.
- **deploy_decision** (Any) - Optional - Used to determine whether to deploy the documentation.
- **assets** (List) - Optional - A list of assets for the HTMLWriter.
- **inventory_version** (String) - Optional - Version string for the objects.inv file.
- **sidebar_drawer** (Bool) - Optional - Enables a sidebar drawer toggle button. Defaults to false.
- **write_inventory** (Bool) - Optional - Whether to write inventory files.
- **noindex_non_stable** (Bool) - Optional - Adds a noindex meta tag to non-stable deployments.
- **keep** (Symbol) - Optional - Sets the granularity of versions to keep (:patch, :minor, :breaking).
```

--------------------------------

### Video with Alt Attribute

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/video_embedding

Use the alt attribute in Markdown syntax to provide a title for the video.

```markdown
![Click to play](my_video.mp4)
```

--------------------------------

### Render interactive HTML

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/mime_examples

Displays an interactive HTML element with mouse event handling.

```julia
HTML(raw"""
<div style="width: 100px; height: 100px; background-color: black;"
     onmousemove="let r = Math.round(event.offsetX / 100 * 255);
                  let b = Math.round((100 - event.offsetY) / 100 * 255);
                  this.style.backgroundColor = `rgb(${r}, 0, ${b})`;">
</div>
""")
```

--------------------------------

### Highlight multiple lines in Julia

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Apply the [!code highlight] marker to multiple lines to draw attention to a block.

```julia
# ‎
# up to 3 in order to highlight the previous 2 lines
using Gnuplot
x = -2π:0.001:2π
@gp x sin.(x) "w l t 'sin' lw 2 lc '#56B4E9'" "set grid"
@gp :- xrange = (-2π - 0.3, 2π + 0.3) yrange = (-1.1,1.1)
@gp :- x cos.(x) "w l t 'cos' lw 2 lc rgb '#E69F00'" # ‎[!code highlight]
```

--------------------------------

### Display Julia Symbols

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/code_example

Shows common Julia syntax and mathematical symbols using the default JuliaMono font.

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

--------------------------------

### Align Environment Labeling

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Labels can be placed inside align environments to reference specific lines.

```markdown
This also works

```math
\begin{align}
\label{eq:b}
a = 1
\end{align}
```

see Eq. $\eqref{eq:b}$.
```

--------------------------------

### Customize Layout Space

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/style_css

CSS rules to adjust content and aside widths in overrides.css.

```css
.VPDoc.has-aside .content-container {
  max-width: 100% !important;
}
.aside {
  max-width: 200px !important;
  padding-left: 0 !important;
}
.VPDoc {
  padding-top: 15px !important;
  padding-left: 5px !important;

}
/* This one does the right menu */

.VPDocOutlineItem li {
  text-overflow: ellipsis;
  overflow: hidden;
  white-space: nowrap;
  max-width: 200px;
}

.VPNavBar .title {
  text-overflow: ellipsis;
  overflow: hidden;
  white-space: nowrap;
}

@media (max-width: 960px) {
  .VPDoc {
    padding-left: 25px !important;  
  }
}
```

--------------------------------

### Configure Vite asset inlining

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/mime_examples

Configuration to disable automatic inlining of small assets in VitePress.

```typescript
vite: {
    build: {
        assetsInlineLimit: 0, // so we can tell whether we have created inlined images or not, we don't let vite inline them
    }
},
```

--------------------------------

### Render JPEG image

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/mime_examples

Displays a JPEG image downloaded from a URL.

```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")))
```

--------------------------------

### Apply noindex meta tag

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/devs/internal_api

Injects a noindex, nofollow robots meta tag into the configuration for non-stable deployments.

```julia
apply_noindex(config::AbstractString, noindex_non_stable::Bool, base::AbstractString) -> String
```

--------------------------------

### Highlight a single line in Julia

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Use the [!code highlight] marker to emphasize a specific line of code.

```julia
using Gnuplot
x = -2π:0.001:2π
@gp x sin.(x) "w l t 'sin' lw 2 lc '#56B4E9'" "set grid"
@gp :- xrange = (-2π - 0.3, 2π + 0.3) yrange = (-1.1,1.1)
@gp :- x cos.(x) "w l t 'cos' lw 2 lc rgb '#E69F00'" # ‎[!code highlight]
```

--------------------------------

### Define MediaOutput struct

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/mime_examples

Defines a struct to represent media output with a specific MIME type and a show method for rendering.

```julia
"""
    MediaOutput{MIME"..."}(contents::String)

A struct representing media output with a specific MIME type.

# Fields
- `contents::String`: The contents of the media output.
"""
struct MediaOutput{MimeType}
    contents::Vector{UInt8}
end
MediaOutput{MimeType}(contents::String) where MimeType = MediaOutput{MimeType}(Vector{UInt8}(contents))
# 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!")
```

--------------------------------

### Focus multiple lines in Julia

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Combine [!code focus] and [!code highlight] to emphasize and isolate multiple lines.

```julia
# ‎
using Gnuplot
x = -2π:0.001:2π
@gp x sin.(x) "w l t 'sin' lw 2 lc '#56B4E9'" "set grid"
@gp :- xrange = (-2π - 0.3, 2π + 0.3) yrange = (-1.1,1.1)
@gp :- x cos.(x) "w l t 'cos' lw 2 lc rgb '#E69F00'" # ‎[!code focus] # ‎[!code highlight]
```

--------------------------------

### Define DecomposeInSidebar

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/devs/internal_api

Wraps a collection of pages to enable multi-sidebar configurations in Vitepress.

```julia
DecomposeInSidebar(path::String, pages)
```

--------------------------------

### Add Citation-style Footnotes

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Implements citation-style footnotes using the bracketed index syntax.

```markdown
Here is the link for the paper of Babushka[^1]
```

```markdown
[^1]: This is Babushka's footnote!
```

--------------------------------

### Transform Vitepress config

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/devs/internal_api

Allows plugins to perform custom transformations on the config.mts source file.

```julia
vitepress_config_transform(plugin::Documenter.Plugin, config::String) -> String
```

--------------------------------

### Basic Video Embedding

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/video_embedding

Embed a video using standard Markdown image syntax.

```markdown
![](./my_video.mp4)
```

--------------------------------

### Inject plugin components

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/devs/internal_api

Injects plugin-specific Vitepress components into the theme index file at designated markers.

```julia
inject_plugin_components!(theme_index_path::String, doc)
```

--------------------------------

### Configure Collapsed Docstrings with @meta

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/code_example

Use this block to enable or disable the collapsing of docstrings on a page. Setting CollapsedDocStrings to true mimics Documenter.jl behavior.

```julia
```@meta
CollapsedDocStrings = true
```
```

--------------------------------

### Change repository information

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/repo_stars

Configuration snippet for updating repository information in the project.

```typescript
ts
```

--------------------------------

### Mark added and removed lines in Julia

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Use [!code --] for removed lines and [!code ++] for added lines to show code changes.

```julia
using Gnuplot
x = -2π:0.001:2π
@gp x sin.(x) "w l t 'sin' lw 2 lc '#56B4E9'" "set grid" # ‎ [!code --]
@gp :- xrange = (-2π - 0.3, 2π + 0.3) yrange = (-1.1,1.1)
@gp :- x cos.(x) "w l t 'cos' lw 2 lc rgb '#E69F00'" # ‎[!code ++] # ‎[!code focus]
```

--------------------------------

### Markdown Tables

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Standard markdown table syntax with alignment indicators.

```markdown
| Tables        |      Are      |  Cool |
| ------------- | :-----------: | ----: |
| col 3 is      | right-aligned | \$1600 |
| col 2 is      |   centered    |   \$12 |
| zebra stripes |   are neat    |    \$1 |
```

--------------------------------

### Escape Special Characters

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Demonstrates how to escape markdown characters like backticks and angle brackets.

```markdown
< `less` and `greater` > than, and the backtick \`.
```

```markdown
sshflags=`-i <keyfile>`
```

```markdown
sshflags=`-i <keyfile>`
```

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

--------------------------------

### Mathematical Equations

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Supports inline math with double dollars and block math using the math tag in fenced code blocks.

```markdown
When ``a \ne 0``, there are two solutions to ``ax^2 + bx + c = 0`` and they are

$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}$$

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!

You can also use fenced code blocks with the `math` tag for equations!

!!! note
    Inline `$$` delimiters like `$$x=1+2$$` will render as inline math when written within a paragraph. For display/block math, place the `$$` delimiters on their own lines.

    $$f(x, y) = 2y$$

Alternatively, use fenced code blocks:

```math
\nabla^2 \Phi = \rho
```
```

--------------------------------

### Focus a single line in Julia

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Use the [!code focus] marker to dim surrounding code and focus on a specific line.

```julia
using Gnuplot
x = -2π:0.001:2π
@gp x sin.(x) "w l t 'sin' lw 2 lc '#56B4E9'" "set grid"
@gp :- xrange = (-2π - 0.3, 2π + 0.3) yrange = (-1.1,1.1)
@gp :- x cos.(x) "w l t 'cos' lw 2 lc rgb '#E69F00'" # ‎[!code focus]
```

--------------------------------

### Stop Vitepress Server

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/get_started

Terminate any running Vitepress processes before creating or updating files.

```julia
# you might need to stop the Vitepress server if it's running before
# updating or creating new files
try run(`pkill -f vitepress`) catch end
```

--------------------------------

### Implement AuthorBadge Component

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/author_badge

Use the AuthorBadge component directly in your markdown files to display an author.

```html
<AuthorBadge
  author="John Doe 2"
/>
```

--------------------------------

### Raw HTML Video Embedding

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/video_embedding

Use @raw html blocks to embed video tags with custom attributes like controls and autoplay.

```html
```@raw html
<video src="./my_video.mp4" controls="controls" title="Auto play video" autoplay="autoplay"></video>
```
```

--------------------------------

### StarUs Component Definition

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/repo_stars

Vue component to display repository star information.

```vue
# StarUs.vue
const props = defineProps({
  repoUrl: {
    type: String,
    default: "https://github.com/LuxDL/DocumenterVitepress.jl" # change to "url repo"
  }
});
```

--------------------------------

### Standard Model Gauge Group

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Displays the Standard Model gauge group as a product of Lie groups.

```latex
\begin{equation}
G_{\text{SM}} = \text{SU}(3)_C \times \text{SU}(2)_L \times \text{U}(1)_Y \quad \text{with algebra } \mathfrak{g}_{\text{SM}} = \mathfrak{su}(3) \oplus \mathfrak{su}(2) \oplus \mathfrak{u}(1) \label{eq:gauge-group}
\end{equation}
```

--------------------------------

### Mark code errors and warnings in Julia

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Use [!code error] and [!code warning] to annotate problematic lines.

```julia
using Gnuplot
x = -2π:0.001:2π
@gp x sin.(x) "w l t 'sin' lw 2 lc '#56B4E9'" "set gridss" # ‎ [!code error]
@gp :- xrange = (-2π - 0.3, 2π + 0.3) yrange = (-1.1,1.1)
@gp :- x cos.(x) "w l t 'cos' lw 2 lc rgba '#E69F00'" # ‎[!code warning]
```

--------------------------------

### Nested Tabbed Content

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Tabs can be nested by using the ::::tabs container for the outer level and :::tabs for the inner level.

```markdown
::::tabs

=== first one

:::tabs

== tab a

a content

== tab b

b content

:::

=== second one

:::tabs

== tab c

c content 2

== tab d

d content 2

:::

::::
```

--------------------------------

### Strip YAML frontmatter delimiters

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/devs/internal_api

Extracts inner YAML from a block, handling trailing newlines robustly.

```julia
_strip_frontmatter_delimiters(text) -> String
```

--------------------------------

### Hopf Fibration and Cardinality

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Mathematical expressions for fiber bundles and set theory cardinality.

```latex
\begin{equation}
\mathbb{S}^1 \hookrightarrow \mathbb{S}^3 \xrightarrow[\text{Hopf fibration}]{\pi} \mathbb{S}^2 \cong \mathbb{CP}^1 \label{eq:fiber-bundle}
\end{equation}
```

```latex
\begin{equation}
\wp(\aleph_0) \cong 2^{\aleph_0} = \mathfrak{c} \label{eq:cardinality}
\end{equation}
```

--------------------------------

### Merge plugin dependencies

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/devs/internal_api

Updates the package.json file by merging plugin-provided dependencies into the existing dependencies object.

```julia
merge_plugin_dependencies!(package_json_path::String, doc)
```

--------------------------------

### Display ANSI Color Palette

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/code_example

Iterates through a range of ANSI color codes to display a color grid.

```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() # ‎[!code highlight]
end
```

--------------------------------

### Feynman Amplitude Vertex

Source: https://luxdl.github.io/DocumenterVitepress.jl/dev/manual/markdown-examples

Represents the Feynman amplitude for an electron-photon vertex coupling.

```latex
\begin{equation}
\mathscr{A}_{\text{vertex}} = -ie\bar{u}(p')\gamma^\mu u(p) A_\mu(q) \label{eq:feynman-amplitude}
\end{equation}
```
Tokens:
Raw