Examples Gallery

Relevant source files

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

• example/examples.md
• example/charts/external.md
• example/charts/line.md
• example/charts/boxplot.md
• example/charts/treemap.md
• example/charts/matrix.md
• example/charts/geo.md
• example/charts/graph.md
• example/plugins/datalabels.md
• example/plugins/colorschemes.md
• src/markdown/index.ts
• src/config.ts
• README.md

The Examples Gallery serves as a comprehensive demonstration of the capabilities provided by vitepress-plugin-chartjs. It showcases how developers can render a wide variety of Chart.js visualizations—ranging from standard statistical plots to complex geographic and hierarchical diagrams—directly within VitePress documentation using simple Markdown code blocks.

This gallery highlights the two primary methods of chart definition: inline YAML/JSON configuration and build-time resolution of external files (YAML, JSON, or JavaScript). It also demonstrates the seamless integration of third-party Chart.js plugins for enhanced features like data labeling, custom color schemes, and specialized chart types.

Sources: README.md:9-25, example/index.md:7-40

Standard Chart Types

The plugin supports all native Chart.js types. These can be defined using simple YAML syntax within a chart or chartjs code block.

Basic Visualization

The most common charts include Line, Bar, Pie, and Doughnut. These utilize standard labels and datasets.

The diagram above shows the data flow from a Markdown block to the final rendered canvas element.
Sources: src/markdown/index.ts:210-245, src/config.ts:161-190

Chart Type	Description	Key Configuration Fields
line	Displays data points connected by lines.	tension, fill, pointStyle
bar	Vertical or horizontal bars for comparison.	indexAxis: y (for horizontal)
pie / doughnut	Circular charts showing proportions.	cutout (for doughnut)
radar	2D chart for multivariate data.	scales.r.beginAtZero
polarArea	Similar to pie but segments have different radii.	data.datasets.data

Sources: example/examples.md:5-180, example/charts/line.md:144-165

Advanced Statistical Plots

Through the @sgratzl/chartjs-chart-boxplot plugin, the gallery demonstrates boxplot and violin charts for displaying data distributions.

• Box Plot: Automatically calculates min, max, median, and quartiles from an array of raw numbers.
• Violin Plot: Visualizes the density of the data at different values.

Sources: example/charts/boxplot.md:30-100, example/charts/boxplot.md:144-155

Specialized and Hierarchical Charts

The plugin's architecture allows for the registration of extended controllers to support complex data structures like matrices, trees, and graphs.

Matrix and Heatmaps

The matrix chart type allows for grid-based visualizations. Each data point requires x and y coordinates, often with a value v used to determine background color intensity.
Sources: example/charts/matrix.md:200-240

Hierarchical Data (Treemaps and Graphs)

• Treemaps: Use nested rectangles to show hierarchies. Data can be a simple array of numbers or an array of objects grouped by keys.
• Graphs: Support for forceDirectedGraph, tree, and dendrogram. These require either an edges array (source/target) or parent references within the data points.

The diagram shows how hierarchical data structures are mapped to different specialized rendering strategies.
Sources: example/charts/treemap.md:155-180, example/charts/graph.md:215-255

External Configuration and Build-Time Logic

One of the most powerful features demonstrated in the examples is the use of the url: directive. This allows fetching configuration from external files in the public/ directory.

Build-Time Resolution Process

The plugin resolves external files during the build process, ensuring no runtime fetching is required on the client side.

Dynamic JavaScript Modules

JavaScript modules (.js, .mjs) can export a static object, a function, or an async function. Since they run in Node.js at build time, they can utilize:

• fs and path for reading local data files.
• fetch for pulling data from remote APIs during the build.
• Random generators for dynamic sample data.

Sources: example/charts/external.md:40-100, README.md:110-130

Plugin-Enhanced Features

The gallery includes examples of how global and per-chart options interact with Chart.js plugins.

Data Labels and Formatting

The chartjs-plugin-datalabels allows placing text directly on chart elements. Configuration can be set at three levels:

1. Per Dataset: dataset.datalabels (highest priority).
2. Per Chart: options.plugins.datalabels.
3. Globally: Via VitePress config chartjs: { enableDatalabels: true }.

Sources: example/plugins/datalabels.md:160-200, src/markdown/index.ts:185-200

Color Schemes and Custom Palettes

Developers can use hw-chartjs-plugin-colorschemes to apply predefined palettes (e.g., brewer.Paired12, office.Excel16). Alternatively, the plugin supports a global colorPalette in the VitePress config, which is automatically applied to datasets if no specific colors are provided.

Sources: example/plugins/colorschemes.md:180-210, src/markdown/index.ts:125-160

Conclusion

The Examples Gallery demonstrates that vitepress-plugin-chartjs is not merely a wrapper for basic charts, but a robust data visualization bridge. By shifting data resolution and complex logic to build-time, it maintains high performance and compatibility with VitePress's static nature while supporting the full breadth of the Chart.js ecosystem.