VitePress Configuration API

Relevant source files

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

• src/config.ts
• example/api.md
• src/index.ts
• src/markdown/index.ts
• src/markdown/resolver.ts
• README.md

The VitePress Configuration API for vitepress-plugin-chartjs provides a structured way to integrate Chart.js rendering into a VitePress site. It encompasses the high-level configuration options used during plugin initialization, the schemas for defining charts within Markdown, and the build-time mechanisms for resolving external data sources.

This API follows a Data-First architecture, where all parsing, validation, and file I/O occurs at build time. This ensures that the client-side Vue component receives pre-computed configurations, resulting in faster page loads and SSR compatibility without runtime fetching.
Sources: src/markdown/index.ts:133-145, README.md:129-137

Plugin Initialization

To enable the plugin, developers use the withChartjs() wrapper. This function augments the standard VitePress configuration by injecting markdown-it rules, Vite plugins, and dependency optimization settings.

The diagram shows how withChartjs integrates the plugin into the VitePress lifecycle.
Sources: src/index.ts:25-50, example/api.md:18-28

Plugin Options

Global settings are passed via the chartjs property in the VitePress configuration. These options define default behaviors and global styles for all charts rendered across the site.

Option	Type	Default	Description
defaultOptions	object	{}	Global Chart.js options applied to every chart instance.
defaultWidth	string | number	'100%'	The default width for chart containers.
defaultHeight	string | number	'400px'	The default height for chart containers.
enableZoom	boolean	false	Enables the chartjs-plugin-zoom globally.
enableDatalabels	boolean	false	Enables the chartjs-plugin-datalabels globally.
colorPalette	string[]	DEFAULT_COLORS	Custom array of colors for datasets.
darkColorPalette	string[]	DEFAULT_DARK_COLORS	Colors used when the site is in dark mode.
containerClass	string	undefined	Optional CSS class for the chart wrapper.
root	string	process.cwd()	The root directory used for resolving local file paths in url: directives.

Sources: src/config.ts:153-176, example/api.md:65-76

Markdown Configuration API

Charts are defined within Markdown using chart or chartjs code fences. The plugin supports two primary ways to provide configuration: inline YAML/JSON or external file references via the url directive.

Configuration Schema

The configuration follows a subset of the standard Chart.js structure, validated via Zod.

The class diagram represents the structure required for valid chart blocks.
Sources: src/config.ts:119-140, example/api.md:103-112

External Data Resolution

When a url: directive is used, the plugin invokes a build-time resolver to fetch and parse the data. This process is synchronous and happens entirely on the server.

The sequence diagram illustrates the build-time resolution logic for external files.
Sources: src/markdown/resolver.ts:25-63, src/markdown/index.ts:200-220

Validation and Processing Logic

Before rendering, every chart configuration undergoes a validation and enhancement phase. This ensures that even minimal configurations result in visually consistent charts.

Processing Workflow

1. Validation: Configurations are checked against ChartConfigSchema or UrlConfigSchema. If invalid, an error block is rendered in Markdown instead of a chart.
2. Option Merging: Global defaultOptions are merged with inline options, followed by the plugin's internal DEFAULT_OPTIONS (e.g., responsive: true).
3. Automatic Coloring: If a dataset lacks colors, the plugin automatically assigns colors from the colorPalette. For line and radar charts, it calculates border and background colors; for pie/doughnut charts, it generates a color array matching the data length.
4. Plugin Injection: If enableZoom or enableDatalabels are active in global settings, the corresponding plugin configurations are injected into the chart options if not already present.

Sources: src/markdown/index.ts:89-130, src/config.ts:187-211

Conclusion

The VitePress Configuration API provides a robust bridge between static Markdown documentation and dynamic data visualization. By centralizing logic in the build-time phase, it maintains the performance benefits of VitePress while offering flexible integration with the Chart.js ecosystem, including support for external JS modules and various data formats.
Sources: src/markdown/index.ts:133-145, README.md:10-18