System Architecture Overview

Relevant source files

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

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

The vitepress-plugin-chartjs is a build-time integrated toolset designed to render Chart.js visualizations within a VitePress environment. It utilizes a "data-first" architecture where complex parsing, external data fetching, and configuration merging occur during the static site generation (SSG) phase, ensuring the client-side bundle remains lightweight and performant.

The system is primarily composed of a Markdown-it extension for processing code blocks, a build-time data resolver for external assets, and a Vite plugin to inject necessary Vue components and styles into the client application.

Sources: README.md:162-170, src/markdown/index.ts:162-175

Core Plugin Integration

The entry point of the system is the withChartjs function. This utility wraps the standard VitePress configuration to inject three critical components: a Markdown-it plugin, a Vite plugin, and specific dependency optimizations.

Orchestration Flow

The following diagram illustrates how withChartjs modifies the VitePress build pipeline:

The orchestration ensures that chart.js, yaml, and zod are pre-bundled by Vite while the VpChart component is globally registered for use in generated Markdown files.
Sources: src/index.ts:24-52

Markdown Processing Pipeline

The ChartjsMarkdown plugin intercepts standard Markdown fences with the language identifiers chart or chartjs. It performs build-time transformations to convert YAML/JSON configurations into a specialized Vue component call.

Data Processing Steps

1. Parsing: Converts the raw string content of the code block into a JavaScript object using YAML or JSON parsers.
2. Validation: Uses Zod-based schemas to ensure the configuration contains required fields like type and data.
3. Resolution: If a url: key is present, the system triggers the resolveUrl logic to fetch data from local files or remote APIs.
4. Enrichment: Applies default options (e.g., responsiveness), merges global plugin configurations, and injects default color palettes.
5. Serialization: Encodes the final configuration object into a JSON string passed as a prop to the <VpChart /> component.

Sources: src/markdown/index.ts:188-250, src/config.ts:182-205

Build-Time Data Resolver

The resolver is a critical architectural component that enables "Build-Time Resolution." It ensures that no network requests for chart data are made by the end-user's browser.

The resolver supports multiple input types, including local YAML/JSON, ES modules (via dynamic import), and remote HTTP(S) resources.
Sources: src/markdown/resolver.ts:22-52, README.md:165-166

Configuration and Schema

The system uses zod to enforce strict data structures for charts while allowing flexibility for Chart.js plugins.

Plugin Configuration Options

Option	Type	Default	Description
defaultOptions	Object	{}	Global Chart.js defaults
defaultHeight	String/Number	'400px'	Default container height
colorPalette	String[]	DEFAULT_COLORS	Global color theme
enableZoom	Boolean	false	Global toggle for zoom plugin
root	String	process.cwd()	Base directory for path resolution

Sources: src/config.ts:145-167, src/markdown/index.ts:114-118

Dataset Schema

The DatasetSchema is designed to be "loose," allowing standard Chart.js properties to pass through to the client while validating core requirements.
Sources: src/config.ts:17-43

Client-Side Integration

The ChartjsPlugin (Vite Plugin) handles the registration of the <VpChart /> component. It intercepts the VitePress client entry point and injects the component registration logic.

The plugin also handles resolveId mapping for the vitepress-plugin-chartjs/client module, ensuring it points to the correct build artifact (TypeScript source in dev, or .mjs/.js in production).
Sources: src/chartjs-plugin.ts:14-38

Summary of Data Flow

1. Markdown Source: Developer writes a code block.
2. Markdown-it Plugin: Parses the block and resolves any external url:.
3. VpChart Component: Replaces the code block in the HTML output, carrying the pre-computed config in its :data prop.
4. Client-Side Initialization: The VpChart component (using an IntersectionObserver) initializes Chart.js only when the element is visible in the viewport.

Sources: README.md:162-170, src/markdown/index.ts:162-175