Markdown-It Parser Implementation

Relevant source files

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

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

The Markdown-It parser implementation in vitepress-plugin-chartjs follows a Data-First architecture. Its primary purpose is to intercept specific code blocks (labeled chart or chartjs) during the VitePress build process and transform them into specialized Vue components. By performing all heavy lifting—such as YAML/JSON parsing, remote data fetching, and JavaScript module execution—at build time, the plugin ensures that the client-side bundle contains only pre-computed, static configuration data.

This implementation bridges the gap between raw Markdown text and dynamic Chart.js visualizations. It handles the resolution of external assets via a synchronous resolver and applies global theme defaults (colors, zoom settings, and responsiveness) before the data ever reaches the browser.

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

Core Architecture and Data Flow

The parser operates as a Markdown-it plugin that overrides the default fence renderer. When the parser encounters a fenced code block, it determines if the language tag matches the supported chart identifiers. If so, it processes the content through a pipeline of validation, resolution, and transformation.

The diagram above illustrates the build-time pipeline where raw markdown is converted into a <VpChart /> component.
Sources: src/markdown/index.ts:182-255, src/index.ts:24-30

Parsing and Validation Logic

The parser utilizes YAML.parse and JSON.parse to ingest the content of the markdown code block. Once parsed, the resulting object is validated using Zod schemas to ensure it adheres to the expected structure.

Validation Tiers

1. Schema Validation: Ensures required fields like type are present and that data structures (labels, datasets) are correctly typed.
2. URL Validation: If a url is provided, it must be a non-empty string.
3. Resolved Data Validation: If data is fetched from an external source, the resulting object is re-validated against the chart schema.

Component	Responsibility	Source File
validateChartData	Validates parsed objects against ChartConfigSchema or UrlConfigSchema.	src/config.ts:192-214
ChartjsMarkdown	Main entry point for the Markdown-it plugin; manages the fence rule override.	src/markdown/index.ts:172-177
processConfig	Merges user options with DEFAULT_OPTIONS and applies global plugin settings.	src/markdown/index.ts:133-158

Sources: src/markdown/index.ts:197-216, src/config.ts:192-214

Build-Time Resolver

The resolveUrl function is a critical component that handles external configuration files. It is strictly synchronous because it runs during the Markdown-it transformation phase.

Resolution Methods

• Local Files: Uses fs.readFileSync for .yaml and .json files.
• JavaScript Modules: Executes a child process using node -e to import .js or .mjs files, allowing the use of Node.js APIs like fs or path during the build.
• Remote URLs: Fetches data from HTTP(S) endpoints via a child process.

The sequence diagram shows how the resolver manages different file types synchronously during the build.
Sources: src/markdown/resolver.ts:25-58, src/markdown/resolver.ts:91-115

Transformation and Rendering

After the configuration data is validated and resolved, the parser performs a "Deep Merge" with global defaults. This includes applying color palettes and enabling plugins like zoom or datalabels if configured in the VitePress project settings.

Component Output

The final output of the parser is a string containing the <VpChart /> Vue component. The pre-processed configuration is stringified, HTML-escaped, and passed to the component via the :data attribute.

function buildTag(dataAttr: string, height: string, chartId: string): string {
  return `<VpChart id="${chartId}" ${dataAttr} height="${height}" />`;
}

Sources: src/markdown/index.ts:178-181, src/markdown/index.ts:80-108

Configuration Schemas

The system uses Zod to define strict interfaces for chart configurations. This ensures that only valid Chart.js structures are passed to the client.

Field	Type	Description
type	string	The Chart.js chart type (e.g., 'line', 'bar', 'treemap').
data	object	Contains labels and datasets.
options	object	Chart.js specific display options and plugin settings.
url	string	Optional path to an external configuration file.
height	string | number	Optional override for the chart container height.

Sources: src/config.ts:117-133, src/config.ts:20-40

Conclusion

The Markdown-it parser implementation serves as the backbone of the vitepress-plugin-chartjs ecosystem. By centralizing data resolution and validation at build time, it provides a seamless developer experience where complex data visualizations can be declared simply within Markdown files while maintaining high performance and security for the end user.