@quartz-community/graph

The Graph View component for Quartz - visualize your digital garden as an interactive network graph.

This is a first-party community plugin for Quartz, demonstrating the new plugin system that allows components to be distributed as npm packages. It displays your content as an interactive force-directed graph, with both local (page-specific) and global (full site) views.

Features

• 🕸️ Interactive Network Graph - Visualize connections between your pages
• 🎨 Local & Global Views - See connections to current page or explore the entire graph
• ⚡ Smooth Animations - Built with D3 force simulation and PixiJS rendering
• 🏷️ Tag Support - Visualize tags as nodes in the graph
• 🖱️ Interactive Controls - Drag, zoom, and pan around the graph
• 💾 Visited Tracking - Highlights pages you've already visited
• ⌨️ Keyboard Shortcuts - Press Ctrl/Cmd + G to toggle the global graph

Installation

From GitHub (Recommended for now)

npm install github:quartz-community/graph --legacy-peer-deps

From NPM (when published)

npm install @quartz-community/graph

Usage

1. Configure in quartz.config.ts

Add the plugin to your externalPlugins array:

// quartz.config.ts
import { QuartzConfig } from "./quartz/cfg";

const config: QuartzConfig = {
  configuration: {
    // ... your configuration
  },
  plugins: {
    // ... your existing plugins
  },
  externalPlugins: ["@quartz-community/graph"],
};

export default config;

2. Import in your layout

// quartz.layout.ts
import { Graph } from "@quartz-community/graph/components";

// Create the Graph component once and reuse it across layouts
const graphComponent = Graph({
  localGraph: {
    drag: true,
    zoom: true,
    depth: 1,
  },
  globalGraph: {
    drag: true,
    zoom: true,
    depth: -1,
  },
});

export const defaultContentPageLayout: PageLayout = {
  // ... other layout config
  right: [
    // ... other components
    graphComponent,
  ],
};

export const defaultListPageLayout: PageLayout = {
  // ... other layout config
  right: [
    // ... other components
    graphComponent, // Reuse the same component instance
  ],
};

Configuration Options

interface D3Config {
  /** Enable node dragging */
  drag: boolean;
  /** Enable zooming */
  zoom: boolean;
  /** Depth of connections to show (-1 for all) */
  depth: number;
  /** Graph scale factor */
  scale: number;
  /** Force repelling strength */
  repelForce: number;
  /** Center force strength */
  centerForce: number;
  /** Distance between linked nodes */
  linkDistance: number;
  /** Label font size */
  fontSize: number;
  /** Opacity multiplier */
  opacityScale: number;
  /** Tags to exclude */
  removeTags: string[];
  /** Show tags as nodes */
  showTags: boolean;
  /** Dim non-hovered nodes on hover */
  focusOnHover?: boolean;
  /** Enable radial layout */
  enableRadial?: boolean;
}

interface GraphOptions {
  localGraph?: Partial<D3Config>; // Local page graph config
  globalGraph?: Partial<D3Config>; // Global graph config
}

Default Behavior

Local Graph

By default, the local graph:

• Shows 1 level of connections (direct links only)
• Dragging enabled
• Zoom enabled
• Tags shown as nodes
• 250px height
• Displays on the right side of pages

Global Graph

By default, the global graph:

• Shows all connections (depth: -1)
• Opens in fullscreen modal when clicking the graph icon
• Keyboard shortcut: Ctrl/Cmd + G
• Focus on hover enabled (dims non-connected nodes)
• Radial layout enabled
• Click outside or press Escape to close

How It Works

The Graph component fetches connection data from /static/contentIndex.json (generated by the ContentIndex emitter) and renders it using:

• D3 for physics simulation (force-directed layout)
• PixiJS for high-performance WebGL rendering

External libraries are loaded from CDN when the graph is first rendered.

[!info] Graph View requires the ContentIndex emitter plugin to be present in your Quartz configuration.

Development

This is a first-party Quartz community plugin. It serves as both:

1. A production-ready Graph View component
2. A reference implementation for building Quartz community plugins

To build locally:

npm install
npm run build

The prepare script automatically builds during installation.

License

MIT