Geographic Maps Extension

Relevant source files

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

• example/charts/geo.md
• src/markdown/index.ts
• README.md
• example/plugins/setup.md
• example/api.md
• example/package.json

The Geographic Maps Extension for vitepress-plugin-chartjs enables the rendering of spatial data through Choropleth and Bubble Map charts. This extension leverages the chartjs-chart-geo plugin to integrate geographic visualizations directly into VitePress documentation using markdown code blocks. It supports both inline GeoJSON definitions and build-time resolution of external topology files (e.g., TopoJSON).

Sources: example/charts/geo.md:1-5, README.md:144-146

Architecture and Integration

The extension functions as a client-side registration within the VitePress theme while benefiting from build-time data processing. The core plugin architecture is plugin-agnostic, meaning geographic capabilities are enabled by registering specific controllers and scales from the chartjs-chart-geo package.

Build-Time Resolution Flow

The following diagram illustrates how geographic data, often large in size, is resolved during the documentation build process rather than requested by the user's browser at runtime.

All chart data (YAML, JSON, JS modules) is resolved at build time, ensuring faster page loads and offline compatibility.
Sources: src/markdown/index.ts:167-175, README.md:15-18

Client-Side Registration

To use geographic charts, developers must register the necessary components in .vitepress/theme/index.ts. This registration must be wrapped in a check for the window object to ensure SSR compatibility.

Key components to register include:

• ChoroplethController & BubbleMapController
• GeoFeature
• ProjectionScale, ColorScale, and SizeScale

Sources: example/charts/geo.md:9-28, example/plugins/setup.md:65-73

Supported Chart Types

Chart Type	Description	Data Requirement
choropleth	Shaded areas representing values across geographic regions.	Requires GeoJSON features and corresponding values.
bubbleMap	Bubbles placed at specific coordinates (latitude/longitude).	Requires coordinate points and radius values.

Sources: example/charts/geo.md:115-132, example/api.md:103-104

Configuration and Scales

Geographic charts introduce specialized scale types to handle projections and data mapping.

Projection Types

Projections determine how the 3D earth is flattened into a 2D chart area.

Projection	Description
equirectangular	Simple cylindrical projection.
mercator	Standard web map projection.
albersUsa	Optimized specifically for USA maps.
equalEarth	Equal-area projection for global maps.
orthographic	A 3D globe-like view.

Sources: example/charts/geo.md:173-180

Scale Configuration Example

The following snippet demonstrates the configuration of projection and color scales for a choropleth map.

options:
  scales:
    projection:
      axis: x
      projection: equalEarth
    color:
      axis: x
      quantize: 5
      legend:
        position: bottom-right

Sources: example/charts/geo.md:88-92

Data Formats

Geographic data can be provided inline for simple shapes or loaded via external JavaScript modules for complex topologies.

JavaScript Configuration (Recommended)

Using JavaScript modules allows for fetching large datasets like the world-atlas or us-atlas during the build phase. This approach typically uses topojson-client to convert topology data into features usable by Chart.js.

import * as topojson from 'topojson-client';

export default async function () {
  const response = await fetch('https://unpkg.com/world-atlas/countries-50m.json');
  const world = await response.json();
  const countries = topojson.feature(world, world.objects.countries).features;

  return {
    type: 'choropleth',
    data: {
      labels: countries.map((d) => d.properties.name),
      datasets: [{
        outline: topojson.feature(world, world.objects.land).features[0],
        data: countries.map((d) => ({ feature: d, value: Math.random() }))
      }]
    }
  };
}

Sources: example/charts/geo.md:75-97

Inline GeoJSON

For small, custom maps, geometry can be defined directly in the markdown block using standard GeoJSON Polygon or Feature structures.
Sources: example/charts/geo.md:115-140

Dependencies

Implementation of geographic maps requires the following packages:

• chartjs-chart-geo: The primary rendering engine.
• topojson-client: Required if working with TopoJSON files (common for atlases).

Sources: example/package.json:19-20, example/plugins/setup.md:108

Summary

The Geographic Maps Extension provides a robust way to include interactive maps in VitePress documentation. By combining build-time resolution with the flexible chartjs-chart-geo plugin, it supports high-performance rendering of both global and regional spatial data without impacting client-side performance.

Sources: README.md:175-177, src/markdown/index.ts:167-175