Knowledge Graph

Turn concepts scattered across documents into a graph you can explore. Feed it Markdown and # headings become document nodes, ## headings become concepts, [[wiki links]] connect them and #tags form their own group — or pass structured nodes and links directly. On the dark constellation canvas, node size follows degree and color follows type; drag to pan, scroll to zoom around the cursor and search as you type. Selecting a node pans the camera to center it and opens a source panel with its summary, every citation's source file and location, and neighbor chips you can jump to. The force simulation is self-written, with no d3 dependency.

Playground

Tune the props live — the code snippet updates as you go, so you can dial in the look you want before copying it.

import * as React from "react";

export default function Example() {
  return (
    <div className="flex min-h-[320px] w-full items-center justify-center p-6">

<KnowledgeGraph/>

    </div>
  );
}

Installation

Usage

import { KnowledgeGraph, parseMarkdownGraph } from "@/components/ui/knowledge-graph";

const notes = `# Release Process
The standard steps from merge to production; every step must support a [[Rollback]]. #operations

## Rollback
Keep build artifacts for the last three versions and purge the [[Caching Strategy]] in one step. #operations
`;

// Pass Markdown directly
<KnowledgeGraph markdown={notes} onCitationClick={(c) => console.log(c.source, c.location)} />;

// Or convert first, then add structured records such as people
const graph = parseMarkdownGraph(notes);
<KnowledgeGraph
  nodes={[...graph.nodes, { id: "Jo", label: "Jo", type: "person" }]}
  links={[...graph.links, { source: "Jo", target: "Rollback", weight: 2 }]}
  defaultSelectedId="Rollback"
/>;

Props

KnowledgeGraphNode

KnowledgeCitation

KnowledgeGraphLink

Also exports parseMarkdownGraph(md: string): KnowledgeGraphData plus the KnowledgeGraphProps, KnowledgeGraphData and KnowledgeNodeType types.

CSS variables

How it works

• Markdown rules: # headings → document nodes; ## headings → concept nodes linked to their document, and ### and deeper hang under the nearest ##; [[Name]] (or [[Name|shown text]]) links to the node with the same name, creating a concept if missing; a #tag must follow line start, whitespace or CJK punctuation, so a#b inside a URL is not a tag. Each paragraph becomes a citation whose location reads "Document › Heading · line N", and the concepts and tags it links to receive the same citation; repeated pairs add up their weight
• Self-written force simulation: initial positions are placed in a disc from a hash of each id (identical on SSR and client); every tick applies O(n²) repulsion (strength -120), link springs (ideal length linkDistance, shorter for heavier links), gravity of 0.02 toward the center and 0.85 velocity damping. Alpha decays from 1 by 0.97 and requestAnimationFrame stops below 0.005. Up to about 300 nodes is recommended
• Re-layout only on structural changes: as long as node ids and links stay the same, passing fresh arrays every render does not restart the layout; when nodes are added, existing ones keep their positions
• Camera: panning and zooming use a spring (stiffness 300, damping 35) within a 0.3–3 zoom range; until the user moves the camera, it keeps framing the whole graph while the layout settles. The simulation pauses while the canvas is offscreen
• Dragging and pinning: a dragged node follows the pointer and reheats the graph to alpha 0.3, then is released on pointer up; double-click a node to pin it (drawn with a dashed ring) and again to unpin; "Re-run layout" clears every pin and restarts from the initial positions
• Search: matching nodes stay lit while the rest fade to 0.2; Enter selects and centers the first match, and an Enter pressed during IME composition is ignored

Accessibility

• The root is role="application" with aria-describedby pointing at sr-only instructions, plus an sr-only list of every node and its connections, so screen reader users get the whole graph without operating the canvas
• Each node is a focusable role="button" with an aria-label such as "Concept: Caching Strategy, 6 connections" and aria-pressed while selected; Tab visits nodes from most to least connected, and focus highlights neighbors like hover does and brings the node into view
• With the canvas focused, arrow keys pan and + / - zoom; Enter or Space selects a node and Esc clears the selection, which is announced through aria-live
• Toolbar buttons all have an aria-label, type filter chips expose their state with aria-pressed, and every control has a focus-visible ring
• When the system "reduce motion" setting is on, the simulation pre-runs 300 ticks synchronously and renders statically, the flowing dots along links are skipped, camera moves jump instead of animating, the source panel fades without sliding, and dragging moves only that node without reheating the graph