Statistical Charts Extension

Relevant source files

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

• example/charts/boxplot.md
• example/plugins/setup.md
• example/api.md
• src/markdown/index.ts
• src/config.ts
• README.md

The Statistical Charts Extension for vitepress-plugin-chartjs provides specialized visualizations for data distribution analysis, specifically supporting Box Plot and Violin chart types. These charts are not part of the core Chart.js library and are enabled through the integration of the @sgratzl/chartjs-chart-boxplot plugin. Within the VitePress ecosystem, these charts allow developers to render complex statistical summaries directly from Markdown code blocks using YAML or JSON configurations.

Sources: example/charts/boxplot.md:1-5, README.md:104-106, example/plugins/setup.md:58-64

Architecture and Integration

The extension operates on a "plugin-agnostic" core. While the markdown parser recognizes any chart type string, the actual rendering of statistical charts requires client-side registration of the specific controllers and elements provided by the boxplot extension.

Data Flow for Statistical Rendering

The following diagram illustrates how statistical data flows from a Markdown block to a rendered chart:

The plugin-agnostic core handles parsing and validation, while the extension handles the specific logic for calculating medians, quartiles, and outliers.
Sources: src/markdown/index.ts:166-175, example/api.md:131-137, README.md:118-124

Supported Chart Types

The extension introduces two primary statistical visualizations:

Type	Description	Key Components
boxplot	Displays a summary of a set of data (minimum, first quartile, median, third quartile, and maximum).	BoxPlotController, BoxAndWiskers
violin	Similar to box plots but includes a rotated kernel density plot on each side to show the probability density of the data.	ViolinController, Violin

Sources: example/charts/boxplot.md:19-21, example/plugins/setup.md:58-64, example/api.md:86-93

Configuration and Setup

Extension Registration

To enable statistical charts, the developer must register the third-party extension in the VitePress theme configuration (.vitepress/theme/index.ts). This registration must be SSR-safe, occurring only when window is defined.

// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'

export default {
  extends: DefaultTheme,
  async enhanceApp({ app }) {
    if (typeof window !== 'undefined') {
      const { Chart } = await import('chart.js')
      const boxplot = await import('@sgratzl/chartjs-chart-boxplot')
      
      Chart.register(
        boxplot.BoxPlotController,
        boxplot.BoxAndWiskers,
        boxplot.ViolinController,
        boxplot.Violin
      )
    }
  }
}

Sources: example/charts/boxplot.md:7-17, example/plugins/setup.md:58-64

Data Format

Unlike standard line or bar charts that take single values, statistical charts accept arrays of raw numbers. The plugin automatically calculates the statistical markers from these arrays.

• Labels: An array of strings representing the categories on the X-axis.
• Data: An array of arrays, where each inner array contains the raw numerical values for that category.

type: boxplot
data:
  labels: [Group A, Group B]
  datasets:
    - label: Dataset 1
      data:
        - [10, 15, 20, 25, 30] # Raw data for Group A
        - [5, 10, 15, 20, 25]  # Raw data for Group B

Sources: example/charts/boxplot.md:120-131, src/config.ts:35-38

Technical Implementation Details

The core plugin facilitates these charts through a specialized validation and processing pipeline:

1. Validation: ChartConfigSchema in src/config.ts uses Zod to ensure the type is present and datasets contain data, but it remains "loose" to allow extension-specific fields (like outline or custom dataset properties) to pass through to the client.
2. Color Application: The applyDefaultColors function in src/markdown/index.ts provides automatic coloring even for extended types. While it has specific logic for line or bar, it defaults to passing the dataset through for extended types like boxplot, allowing the extension's default styles or user-defined colors to take precedence.
3. Build-time Resolution: If the statistical data is large, it can be loaded from external .yaml, .json, or .js files using the url: directive. This is resolved at build time, ensuring the heavy raw data arrays are handled before the page reaches the client.

Sources: src/config.ts:107-113, src/markdown/index.ts:98-129, example/api.md:98-106

Summary

The Statistical Charts Extension significantly expands the analytical capabilities of VitePress documentation by integrating advanced distribution visualizations. By leveraging build-time data resolution and a flexible plugin architecture, it allows for the display of complex raw data sets as clean, professional Box Plot and Violin charts without sacrificing runtime performance.

Sources: README.md:10-15, example/charts/boxplot.md:1-5