Annotations & Data Labels
Relevant source files
The following files were used as context for generating this wiki page:
Annotations and Data Labels are two critical visual enhancement features supported by the vitepress-plugin-chartjs ecosystem. Annotations allow for the addition of decorative or informative shapes—such as lines, boxes, and points—onto the chart canvas, while Data Labels enable the display of textual information directly on data elements. Both features are implemented through official Chart.js plugins (chartjs-plugin-annotation and chartjs-plugin-datalabels) and are integrated into the build-time resolution pipeline of the project.
Sources: example/plugins/annotations.md, example/plugins/datalabels.md, README.md:144-158
Plugin Architecture and Registration
The project follows a plugin-agnostic core architecture. While the markdown parser handles the configuration for these features, the actual rendering logic must be registered on the client side. This ensures that the heavy Chart.js plugin code is only loaded in the browser environment.
Client-Side Registration Flow
Because VitePress uses Server-Side Rendering (SSR), plugins like Annotations and Data Labels must be registered within the enhanceApp hook of the theme configuration, guarded by a check for the window object.
Build-Time Processing
The vitepress-plugin-chartjs markdown engine processes annotation and datalabel configurations during the build. The processConfig function in the markdown renderer merges user-provided plugin settings with global defaults.
Sources: src/markdown/index.ts:140-170
Data Labels Plugin
The Data Labels plugin allows for the display of values, percentages, or labels directly on chart elements like bars, points, or pie slices.
Configuration Levels
The plugin supports a hierarchical configuration strategy where settings can be applied at three different levels of priority:
| Priority | Level | Description |
|---|---|---|
| 1 (Highest) | Per Dataset | Defined within dataset.datalabels |
| 2 | Per Chart | Defined within options.plugins.datalabels |
| 3 (Lowest) | Global | Defined in VitePress chartjs config |
Sources: example/plugins/datalabels.md:213-228, src/markdown/index.ts:167-169
Global Activation
In the VitePress configuration, Data Labels can be enabled globally for all charts using the enableDatalabels flag.
// .vitepress/config.mts
export default withChartjs(
defineConfig({
chartjs: {
enableDatalabels: true,
},
})
)
Sources: example/plugins/datalabels.md:255-263, src/config.ts:133
Positioning Logic
Data Label positioning is determined by the anchor (the reference point on the element) and align (the relative direction from the anchor).
Annotations Plugin
The Annotations plugin provides tools to draw non-data-driven visual cues on the chart. These are defined under the options.plugins.annotation.annotations object.
Supported Annotation Types
| Type | Key Properties | Use Case |
|---|---|---|
line | yMin, yMax, xMin, xMax, borderDash | Drawing targets, thresholds, or trend lines. |
box | xMin, xMax, yMin, yMax, backgroundColor | Highlighting specific regions (e.g., "Target Zones"). |
point | xValue, yValue, radius, pointStyle | Marking specific coordinate points of interest. |
label | content, font, padding, borderRadius | Adding descriptive text boxes at specific coordinates. |
Sources: example/plugins/annotations.md:129-178
Annotation Structure Example
Annotations are identified by unique keys within the configuration, allowing multiple overlays on a single chart.
options:
plugins:
annotation:
annotations:
threshold_line:
type: line
yMin: 70
yMax: 70
borderColor: red
highlight_zone:
type: box
xMin: 3
xMax: 7
backgroundColor: rgba(255, 99, 132, 0.2)
Sources: example/plugins/annotations.md:26-50, example/plugins/annotations.md:65-90
Integration with Markdown Engine
The ChartjsMarkdown engine ensures that these configurations are validated before being passed to the client. It uses Zod schemas to verify that the options.plugins object structure matches expected types.
Configuration Data Flow
Validation Schemas
The PluginsSchema and OptionsSchema in the core configuration allow for "loose" object definitions, ensuring that third-party plugin options (like annotation or datalabels) are preserved during the build-time processing without being stripped by the validator.
Sources: src/config.ts:79-85, src/config.ts:110-112
Summary
Annotations and Data Labels are implemented as opt-in extensions to the vitepress-plugin-chartjs core. By leveraging build-time configuration merging and client-side plugin registration, the system provides a flexible way to add complex visual overlays and labels to charts without compromising the static nature of VitePress documentation. These features are highly configurable through standard YAML syntax in markdown, supporting per-dataset, per-chart, and global settings.