Graph & Tree Networks Extension

Relevant source files

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

• example/charts/graph.md
• example/plugins/setup.md
• example/api.md
• README.md
• src/config.ts
• example/package.json

The Graph & Tree Networks Extension for vitepress-plugin-chartjs enables the visualization of complex relational data, hierarchical structures, and network topologies within VitePress documentation. By leveraging the chartjs-chart-graph package, the plugin supports specialized chart types such as force-directed graphs, dendrograms, and tidy tree layouts.

These chart types are not part of the core Chart.js library and require explicit registration within the VitePress theme. Once configured, they allow developers to represent data using either explicit edge connections (for networks) or parent-child relationships (for trees), rendered with physics-based simulations or structured layouts.
Sources: example/charts/graph.md:1-5, README.md:144-150, example/plugins/setup.md:1-5

Architectural Overview and Registration

The extension operates on a plugin-agnostic core. While vitepress-plugin-chartjs handles the markdown parsing and build-time resolution, the specific rendering logic for graphs and trees is provided by the chartjs-chart-graph extension.

Component Registration Flow

To use these features, the controllers and elements must be registered in the .vitepress/theme/index.ts file. This process must be SSR-safe, occurring only on the client side when the window object is available.

The diagram above illustrates the client-side enhancement process required to enable graph rendering capabilities.
Sources: example/charts/graph.md:7-25, example/plugins/setup.md:76-81

Required Dependencies

The following packages are necessary for the extension to function:

Package	Role
chart.js	Core rendering engine (Peer Dependency)
chartjs-chart-graph	Provides graph/tree controllers and edge elements
vitepress-plugin-chartjs	Markdown integration and build-time data resolution
Sources: example/package.json:17-21, example/plugins/setup.md:112-126

Supported Network & Tree Types

The extension provides three primary visualization modes, each suited for different data structures.

1. Force-Directed Graphs

Used for general network topologies. It employs a physics simulation (via D3-force) to position nodes dynamically based on their connections.

• Data Structure: Requires an array of nodes (data) and an array of edges defining source and target indices.
• Styling: Supports lineBorderColor and lineBorderWidth for connections, and standard point properties for nodes.
  Sources: example/charts/graph.md:31-45, example/charts/graph.md:162-171

2. Dendrograms

Ideal for hierarchical clustering or organizational charts. They can be rendered in horizontal, vertical, or radial orientations.

• Data Structure: Uses parent-child relationships where nodes specify a parent index.
• Key Options: Controlled via options.tree.orientation.
  Sources: example/charts/graph.md:79-85, example/charts/graph.md:191-195

3. Tree Layouts

A "Tidy Tree" layout that provides proper spacing for hierarchical data, ensuring leaves and branches do not overlap.
Sources: example/charts/graph.md:141-145, example/charts/graph.md:155-159

Data Models and Configuration

Data for graphs and trees can be defined inline within markdown or loaded from external YAML/JSON files.

Dataset Schema

The extension utilizes a loose schema that passes through specific fields required by the graph controllers.

Field	Type	Description
data	Array	Objects containing node properties (e.g., { x, y } or { parent })
edges	Array	(Graph only) Objects defining { source, target } relationships
pointRadius	Number/Array	Size of the nodes
lineBorderWidth	Number	Thickness of the connecting edges
Sources: src/config.ts:32-55, example/charts/graph.md:173-189

Configuration Logic Flow

The plugin processes graph configurations at build time, merging default options before passing pre-computed data to the client.

This flow ensures that complex graph data is validated and pre-processed before reaching the browser.
Sources: src/markdown/index.ts:167-210, src/config.ts:192-212

Tree-Specific Options

When using tree or dendrogram types, a specialized tree object is available in the chart options.

Option	Values	Description
orientation	horizontal, vertical, radial	The direction in which the tree grows
mode	dendrogram, tree	Specific layout algorithm to use
Sources: example/charts/graph.md:191-195, example/api.md:120-125

Implementation Example: Hierarchical Data

Hierarchical structures are defined by linking nodes to their parents via index references.

type: tree
data:
  labels: [Root, Child1, Child2]
  datasets:
    - data:
        - {}             # Index 0: Root
        - { parent: 0 }  # Index 1: Child of 0
        - { parent: 0 }  # Index 2: Child of 0

Sources: example/charts/graph.md:182-189, example/api.md:139-145

Conclusion

The Graph & Tree Networks Extension expands the utility of vitepress-plugin-chartjs by integrating specialized relational visualizations. By combining build-time data resolution with the flexible chartjs-chart-graph extension, it provides a performant way to document network architectures, file structures, and complex hierarchies with minimal runtime overhead.
Sources: README.md:14-25, src/markdown/index.ts:145-155