External Static Data

Relevant source files

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

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

The "External Static Data" feature in vitepress-plugin-chartjs allows developers to decouple chart configurations from Markdown files by loading them from external files or remote URLs. This system supports a variety of formats including YAML, JSON, and JavaScript/ES modules.

A critical architectural aspect of this feature is that all data resolution occurs at build time. The client-side application never performs runtime fetches for chart configurations; instead, the VpChart component receives pre-computed data embedded directly into the static site. This ensures faster page loads, offline compatibility, and the ability to use Node.js-specific APIs during the data generation phase.

Sources: example/charts/external.md:3-9, README.md:16-17, src/markdown/index.ts:182-192

Data Resolution Architecture

The system utilizes a "Data-First" architecture where the Markdown-it plugin intercepts chart or chartjs code blocks and processes url: directives. The resolution logic is centralized in the resolveUrl function, which determines the file type and applies the appropriate loading strategy.

Build-Time Sequence

The following diagram illustrates how the plugin resolves an external URL during the VitePress build process.

Supported File Formats

The resolver supports different loading mechanisms based on the file extension and URL protocol.

Extension	Loading Mechanism	Execution Environment	Use Case
.yaml	Synchronous File Read	Node.js (Build-time)	Static, human-readable configs
.json	Synchronous File Read	Node.js (Build-time)	Standard static configurations
.js / .mjs	Dynamic import() in child process	Node.js (Build-time)	Programmatic or async data generation
http(s)://	fetch() in child process	Node.js (Build-time)	Loading data from external APIs at build

Sources: example/charts/external.md:143-150, src/markdown/resolver.ts:25-58

JavaScript Module Resolution

JavaScript and ES Module files (.js, .mjs) offer the most flexibility. They are executed in a separate Node.js process using execSync to maintain synchronous compatibility with the Markdown-it rendering pipeline.

Export Patterns

External JavaScript files must provide a default export. The plugin handles three specific return types from these modules:

1. Object Export: A direct Chart.js configuration object.
2. Function Export: A function that returns a configuration object (useful for generating random data).
3. Async Function Export: A function that returns a Promise, allowing for data fetching via fs or fetch during the build.

// Example: Async data fetching at build time
export default async function() {
  const response = await fetch('https://api.example.com/data');
  const data = await response.json();
  return {
    type: 'line',
    data: data
  };
}

Sources: example/charts/external.md:38-42, README.md:104-121, src/markdown/resolver.ts:84-100

Configuration and Validation

When an external file is resolved, it undergoes the same validation and processing as inline configurations. This ensures consistency and prevents runtime errors.

Processing Pipeline

1. Resolution: The resolveUrl function locates and reads the content.
2. Normalization: The normalizeData function ensures the resulting object contains a required type field.
3. Validation: The validateChartData function uses Zod schemas to verify the structure (e.g., ensuring at least one dataset is present).
4. Transformation: The processConfig function merges global default options and applies the configured color palette.

Implementation Details

URL Resolution Logic

The plugin searches for local files in a specific order:

1. If the path starts with /, it checks rootDir/public/ followed by rootDir/.
2. Relative paths are checked against the provided rootDir.

Sources: src/markdown/resolver.ts:31-41

Zod Validation Schema

The UrlConfigSchema specifically validates the syntax used in Markdown blocks for external data:

export const UrlConfigSchema = z.object({
  url: z.string().min(1, '"url" must be a non-empty string.'),
  height: z.union([z.number(), z.string()]).nullish(),
}).loose();

Sources: src/config.ts:153-156

Conclusion

External Static Data resolution provides a robust mechanism for managing complex data visualizations without cluttering Markdown files. By shifting the data fetching and computation to the build phase, the plugin maintains high performance and reliability for the end user while granting developers access to the full power of the Node.js ecosystem for data preparation.