Installation and Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• example/api.md
• example/index.md
• example/plugins/setup.md
• src/index.ts
• src/config.ts
• src/markdown/index.ts
• src/chartjs-plugin.ts

vitepress-plugin-chartjs is a zero-config plugin for VitePress that enables the rendering of Chart.js charts directly from Markdown code blocks. It employs a data-first architecture where data resolution, validation, and file I/O occur at build time, ensuring the client only receives pre-computed configurations.

The installation and setup process involves three main phases: dependency installation, VitePress configuration wrapping, and theme enhancement for client-side rendering.

Sources: README.md:12-25, src/markdown/index.ts:133-145

1. Installation

The plugin requires chart.js as a peer dependency. Use a package manager to add both to your project.

# pnpm
pnpm add vitepress-plugin-chartjs chart.js

# npm
npm install vitepress-plugin-chartjs chart.js

Sources: example/api.md:7-9, README.md:27-35

2. VitePress Configuration

To initialize the plugin, you must wrap your VitePress configuration with the withChartjs function. This function automatically injects the necessary Markdown-it rules and Vite plugins into the VitePress lifecycle.

Configuration Wrapper Logic

The withChartjs function performs several internal steps:

1. Markdown Config: Injects ChartjsMarkdown to parse ```chart blocks.
2. Vite Plugins: Registers the ChartjsPlugin to handle component registration.
3. Dependency Optimization: Adds chart.js, yaml, and zod to optimizeDeps.
4. SSR Handling: Ensures the plugin is not externalized during Server-Side Rendering.

Sources: src/index.ts:24-52

Implementation Example

In .vitepress/config.mts:

import { defineConfig } from 'vitepress'
import { withChartjs } from 'vitepress-plugin-chartjs'

export default withChartjs(defineConfig({
  title: "My Site",
  chartjs: {
    defaultHeight: '400px',
    enableZoom: true
  },
}))

Sources: example/api.md:13-22, example/index.md:58-70

Global Plugin Options

Options are passed via the chartjs key in the configuration:

Option	Type	Default	Description
defaultOptions	object	{}	Base Chart.js options for all charts
defaultWidth	string | number	'100%'	Default width of the chart container
defaultHeight	string | number	'400px'	Default height of the chart container
enableZoom	boolean	false	Globally enables chartjs-plugin-zoom
enableDatalabels	boolean	false	Globally enables chartjs-plugin-datalabels
colorPalette	string[]	Built-in	Custom array of colors for datasets
root	string	process.cwd()	Root directory for resolving url: paths

Sources: example/api.md:41-52, src/config.ts:161-180

3. Theme and Client Setup

The plugin requires a dedicated CSS file for correct rendering and a theme setup to register the Vue component and any optional Chart.js extensions.

Basic Theme Setup

In .vitepress/theme/index.ts:

import DefaultTheme from 'vitepress/theme'
import 'vitepress-plugin-chartjs/style.css'

export default DefaultTheme

Sources: example/api.md:26-30, example/index.md:46-52

Setup with External Plugins

If utilizing extended chart types (e.g., boxplot, matrix) or plugins (e.g., zoom, annotation), they must be registered within the enhanceApp hook. This must be wrapped in a check for window to remain SSR-safe.

4. System Architecture

The plugin architecture splits responsibilities between the build process and the browser to optimize performance and static site compatibility.

Data Flow

1. Build Time: The Markdown-it plugin parses code blocks. If a url: is present, it is resolved (reading local files or executing JS modules). All configurations are validated via Zod schemas.
2. Client Time: The VpChart component receives a JSON-encoded configuration. It remains idle until the IntersectionObserver detects it is within the viewport, at which point it initializes Chart.js.

Sources: src/markdown/index.ts:133-151, src/config.ts:192-210, README.md:143-150

Summary

Setting up vitepress-plugin-chartjs requires wrapping the main configuration to enable build-time processing and importing styles into the theme. By resolving data (including dynamic JavaScript-generated data) during the build, the plugin ensures that documentation sites remain high-performance and compatible with static hosting, only initializing heavy Chart.js logic when charts are actually visible to the user.

Sources: README.md:14-25, example/api.md:120-125