Markdown Syntax Guide

Relevant source files

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

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

The Markdown Syntax Guide provides a technical overview of how vitepress-plugin-chartjs enables rendering Chart.js visualizations directly within VitePress documents. The plugin uses a "Data-First" architecture where all parsing, validation, and file resolution occur at build time, ensuring the client-side receives only pre-computed configurations for optimized rendering.

This system allows developers to define charts using simple YAML or JSON syntax inside fenced code blocks or by referencing external configuration files. The plugin handles the transition from Markdown tokens to live Vue components (<VpChart />) that initialize when they enter the viewport.

Code Block Implementation

The primary interface for creating charts is the use of fenced code blocks with the language identifiers chart or chartjs.

Fenced Code Blocks

When the Markdown-it parser encounters a code block tagged with chart, the ChartjsMarkdown plugin intercepts the token. It parses the content—supporting both YAML and JSON—and validates the structure against predefined Zod schemas.

The flow above illustrates how the Markdown-it plugin processes code block tokens during the build process to transform them into pre-configured Vue components.
Sources: src/markdown/index.ts:161-200, README.md:104-123

Inline Configuration Structure

Inline configurations require a specific set of fields to be valid. The core requirements include a type and a data object containing datasets.

Field	Type	Required	Description
type	String	Yes	The chart type (e.g., line, bar, pie).
data	Object	Yes	Contains labels and datasets series.
options	Object	No	Chart.js specific configuration (plugins, scales).
height	String/Number	No	Overrides the global default height.
width	String/Number	No	Overrides the global default width.

Sources: src/config.ts:98-104, example/api.md:129-140

External Configuration Loading

The plugin supports loading configurations from external files located in the public folder using the url: directive. This is resolved strictly at build time.

Supported File Types

The resolveUrl function in the build-time resolver handles different extensions with specific logic:

• .yaml / .json: Parsed as static configuration objects.
• .js / .mjs: Executed as Node.js modules. They can export an object, a function, or an async function.
• http(s)://: Fetched via a child process during the build.

The diagram shows the build-time resolution of external files, ensuring no runtime fetches are performed by the browser.
Sources: src/markdown/resolver.ts:25-56, example/charts/external.md:1-12

JavaScript Module Exports

When using .js files, the plugin allows for dynamic data generation. The resolver executes these files and expects a default export.

// Example: Dynamic JS config
export default async function() {
  const data = await fetch('https://api.example.com/stats');
  return {
    type: 'bar',
    data: { /* ... */ }
  };
}

Sources: example/charts/external.md:46-75, src/markdown/resolver.ts:79-101

Configuration and Validation

All Markdown-provided configurations (inline or external) are processed through a validation layer before rendering.

Schema Validation

The plugin uses Zod to ensure the chart configuration adheres to the expected Chart.js structure. Key validation points include:

• Type Requirement: Every chart must have a type string.
• Dataset Presence: The data object must contain at least one dataset.
• URL vs Inline: The system differentiates between a UrlConfig (containing a url) and a ChartConfig (containing type and data).

Sources: src/config.ts:133-163, src/markdown/index.ts:221-236

Pre-processing and Color Application

Before the <VpChart /> tag is generated, the plugin applies global configurations and default colors if they are missing from the Markdown input.

• Deep Merge: User-defined options are merged with defaultOptions provided in the plugin setup.
• Color Palettes: If backgroundColor or borderColor is omitted in the Markdown, the plugin automatically assigns colors from the colorPalette (default or custom).
• Plugin Defaults: Features like zoom or datalabels are injected into the config if enabled globally via PluginConfig.

Sources: src/markdown/index.ts:78-154, example/api.md:46-65

Error Handling in Markdown

If a syntax error (YAML/JSON) or validation failure occurs, the plugin renders a descriptive error block in place of the chart. This block includes the error title and a list of specific validation issues.

function renderError(title: string, messages: string[]): string {
  // Returns HTML div with .chartjs-error class
}

Sources: src/markdown/index.ts:39-55, src/markdown/index.ts:210-218

Summary

The Markdown syntax for vitepress-plugin-chartjs enables a seamless integration of data visualizations within technical documentation. By leveraging build-time resolution for both inline and external files (YAML, JSON, and JS), it maintains high performance while providing a flexible, schema-validated interface for developers to define complex charts.