TypeScript API Reference

Relevant source files

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

• src/index.ts
• src/config.ts
• src/markdown/index.ts
• src/markdown/resolver.ts
• src/chartjs-plugin.ts
• example/api.md

Introduction

The vitepress-plugin-chartjs library provides a robust TypeScript API designed to integrate Chart.js into VitePress documentation sites. It enables developers to define charts using YAML or JSON within Markdown code blocks, which are then processed at build time to ensure high performance and zero runtime data fetching.

The API architecture is divided into three primary layers: the VitePress configuration wrapper, the Markdown-it parser extension, and the Build-time resolver. These layers work together to validate chart configurations via Zod schemas, resolve external data sources (YAML, JSON, or JavaScript modules), and inject the necessary Vue components into the VitePress client app.

Sources: src/index.ts, src/markdown/index.ts, example/api.md

Core Configuration API

withChartjs

The primary entry point for the plugin is the withChartjs function. This high-order function wraps the standard VitePress UserConfig to automatically inject Markdown-it rules and Vite plugins required for chart rendering.

The diagram shows how withChartjs modifies the standard VitePress configuration object to include the plugin's internal logic.

Key functions and types:

• withChartjs(config: UserConfig): Enhances the configuration with markdown rules and Vite plugins.
• PluginConfig: Interface for defining global plugin behavior (colors, dimensions, zoom).

Sources: src/index.ts:25-51, src/config.ts:133-156

Global Plugin Options

Configuration options passed via the chartjs key in defineConfig.

Option	Type	Default	Description
defaultOptions	ChartOptions	{}	Base options applied to every chart instance.
defaultWidth	string | number	'100%'	Default width for the chart container.
defaultHeight	string | number	'400px'	Default height for the chart container.
colorPalette	string[]	DEFAULT_COLORS	Custom array of colors for datasets.
enableZoom	boolean	false	Automatically enables the zoom plugin for all charts.
enableDatalabels	boolean	false	Automatically enables the datalabels plugin.
root	string	process.cwd()	Base directory for resolving relative url: paths.

Sources: src/config.ts:133-156, example/api.md:55-68

Data Models and Validation

The plugin utilizes Zod for strict runtime and build-time validation of chart data. This ensures that errors are caught during the build process rather than failing in the user's browser.

Chart Configuration Schema

The ChartConfig represents the full structure of a chart definition, including its type, data, and options.

This diagram represents the hierarchical structure of the chart configuration as defined in the source schemas.

Validation Functions:

• validateChartData(parsed: unknown): Validates a pre-parsed object against the ChartConfigSchema.
• validateChartInput(raw: string): Parses raw YAML string and validates the resulting object.

Sources: src/config.ts:98-124, src/config.ts:167-219

Build-Time Resolution API

One of the core features of the plugin is the ability to resolve external data sources at build time. This is handled by the resolveUrl utility.

resolveUrl

This function resolves url: directives synchronously during the VitePress build process.

The sequence shows the synchronous resolution flow for different file types during the build.

Supported File Types and Logic:

• YAML/JSON: Loaded via fs.readFileSync and parsed.
• JavaScript (.js/.mjs): Executed in a Node.js child process via execSync. This allows the use of fs, path, or even fetch inside the external JS file to generate data.
• HTTP(S): Fetched synchronously using a Node.js helper.

Sources: src/markdown/resolver.ts:25-58, src/markdown/index.ts:182-205

Markdown and Vite Integration

ChartjsMarkdown

This function implements the markdown-it fence rule. It intercepts code blocks with the chart or chartjs language identifiers and transforms them into a custom Vue component: <VpChart />.

Transformation Logic:

1. Parse: Converts YAML/JSON content to a JavaScript object.
2. Resolve: If a url property exists, it invokes resolveUrl.
3. Process: Applies default options, merges global plugin settings, and assigns default color palettes.
4. Encode: The final configuration is JSON-stringified and escaped into the :data attribute of the component.

Sources: src/markdown/index.ts:135-231

ChartjsPlugin

A Vite plugin that handles the registration of the client-side chart component. It uses a virtual module approach to ensure the VpChart component is globally available in the VitePress application without manual user registration.

Sources: src/chartjs-plugin.ts:10-53

Summary

The vitepress-plugin-chartjs API provides a comprehensive bridge between static Markdown documentation and dynamic data visualization. By leveraging build-time resolution and Zod-based validation, it ensures that charts are both performant and type-safe. Developers can interact with the API via the withChartjs configuration wrapper or by utilizing the exported TypeScript types for custom chart generation.