Knowledge Graph View
Build a graph block that maps the pages, headings, and links in an Orbix workspace.
This example builds an interactive graph view of a workspace. Larger nodes represent pages, smaller nodes represent headings inside those pages, and lines show how pages and sections link to one another.
The live graph below is generated from the pages and headings in this SDK documentation. Drag any node to rearrange it, scroll to zoom, or click a node to open that page or section.
How it works
You don't need an external charting library to build a graph block in Orbix. The block combines three hooks from @orbixdocs/sdk:
useOrbixWorkspace()—ws.getWorkspaceGraph()returns all pages and the links between them (wikilink,subpage, andreference), whilews.getAllHeadings()returns the headings (H1,H2,H3) across every page.useOrbixCanvas()anduseOrbixAnimationLoop()— sets up a<canvas>that automatically resizes with the block and runs the layout loop while the block is visible on screen.- Navigation (
ws.navigateToPage) — clicking a page node opens that page (ws.navigateToPage(node.pageId)), and clicking a heading node opens the page and scrolls straight to that heading (ws.navigateToPage(node.pageId, node.blockId)).
Full block code
Copy this file into Block Studio or your local project. Because the block reads workspace pages and navigates between documents, declare workspace: ['read:all_pages'] and document: ['read', 'navigate'] in the manifest.
import { useEffect, useMemo, useRef, useState } from 'react';
import {
defineBlock,
useOrbixAnimationLoop,
useOrbixCanvas,
useOrbixWorkspace,
type BlockRenderProps,
} from '@orbixdocs/sdk';
interface GraphNode {
id: string;
label: string;
kind: 'page' | 'heading';
pageId: string;
blockId?: string;
degree: number;
x: number;
y: number;
vx: number;
vy: number;
fx: number | null;
fy: number | null;
}
interface GraphEdge {
sourceIndex: number;
targetIndex: number;
kind: 'heading' | 'link';
}
export default defineBlock({
manifest: {
id: 'acme.knowledge-graph',
name: 'Knowledge Graph',
version: '1.0.0',
sdk: '^3.0.0',
capabilities: {
document: ['read', 'navigate'],
workspace: ['read:all_pages'],
},
},
component(_props: BlockRenderProps) {
const ws = useOrbixWorkspace();
const [hoveredId, setHoveredId] = useState<string | null>(null);
const { canvasRef, width, height, ready } = useOrbixCanvas({
contextType: '2d',
pixelRatio: true,
});
// Build nodes and links from workspace pages and headings
const graph = useMemo(() => {
const { nodes: pageNodes, edges: pageEdges } = ws.getWorkspaceGraph();
const headings = ws.getAllHeadings().filter((h) => h.level <= 2);
const nodes: GraphNode[] = [];
const indexById = new Map<string, number>();
pageNodes.forEach((p, idx) => {
const angle = idx * 2.4;
const radius = 60 * Math.sqrt(idx + 1);
indexById.set(p.id, nodes.length);
nodes.push({
id: p.id,
label: p.title || 'Untitled',
kind: 'page',
pageId: p.id,
degree: p.degree,
x: Math.cos(angle) * radius,
y: Math.sin(angle) * radius,
vx: 0,
vy: 0,
fx: null,
fy: null,
});
});
const edges: GraphEdge[] = [];
const neighbors = new Map<string, Set<string>>();
const addEdge = (aId: string, bId: string, kind: 'heading' | 'link') => {
const aIdx = indexById.get(aId);
const bIdx = indexById.get(bId);
if (aIdx === undefined || bIdx === undefined || aIdx === bIdx) return;
edges.push({ sourceIndex: aIdx, targetIndex: bIdx, kind });
if (!neighbors.has(aId)) neighbors.set(aId, new Set());
if (!neighbors.has(bId)) neighbors.set(bId, new Set());
neighbors.get(aId)!.add(bId);
neighbors.get(bId)!.add(aId);
};
for (const e of pageEdges) {
addEdge(e.source, e.target, 'link');
}
headings.forEach((h, idx) => {
const parentIdx = indexById.get(h.pageId);
if (parentIdx === undefined) return;
const parent = nodes[parentIdx];
const hId = `${h.pageId}#${h.blockId}`;
const angle = idx * 1.25;
indexById.set(hId, nodes.length);
nodes.push({
id: hId,
label: h.text,
kind: 'heading',
pageId: h.pageId,
blockId: h.blockId,
degree: 1,
x: parent.x + Math.cos(angle) * 48,
y: parent.y + Math.sin(angle) * 48,
vx: 0,
vy: 0,
fx: null,
fy: null,
});
addEdge(h.pageId, hId, 'heading');
});
return { nodes, edges, neighbors };
}, [ws]);
const nodesRef = useRef<GraphNode[]>([]);
const edgesRef = useRef<GraphEdge[]>([]);
const neighborsRef = useRef<Map<string, Set<string>>>(new Map());
const cameraRef = useRef({ x: 0, y: 0, k: 0.8 });
const targetCameraRef = useRef({ x: 0, y: 0, k: 0.8 });
const draggedRef = useRef<GraphNode | null>(null);
useEffect(() => {
nodesRef.current = graph.nodes;
edgesRef.current = graph.edges;
neighborsRef.current = graph.neighbors;
}, [graph]);
useOrbixAnimationLoop(
() => {
if (!ready) return;
const ctx = canvasRef.current?.getContext('2d');
if (!ctx) return;
const nodes = nodesRef.current;
const edges = edgesRef.current;
const cam = cameraRef.current;
const targetCam = targetCameraRef.current;
// Smooth camera interpolation for wheel zoom
cam.x += (targetCam.x - cam.x) * 0.2;
cam.y += (targetCam.y - cam.y) * 0.2;
cam.k += (targetCam.k - cam.k) * 0.2;
// Update node positions
for (let i = 0; i < nodes.length; i++) {
const a = nodes[i];
if (a.fx === null) {
a.vx -= a.x * 0.003;
a.vy -= a.y * 0.003;
}
for (let j = i + 1; j < nodes.length; j++) {
const b = nodes[j];
const dx = b.x - a.x;
const dy = b.y - a.y;
const d2 = Math.max(25, dx * dx + dy * dy);
if (d2 > 220000) continue;
const f = (a.kind === 'page' && b.kind === 'page' ? 750 : 280) / d2;
if (a.fx === null) {
a.vx -= dx * f;
a.vy -= dy * f;
}
if (b.fx === null) {
b.vx += dx * f;
b.vy += dy * f;
}
}
}
for (const e of edges) {
const s = nodes[e.sourceIndex];
const t = nodes[e.targetIndex];
if (!s || !t) continue;
const dx = t.x - s.x;
const dy = t.y - s.y;
const dist = Math.sqrt(dx * dx + dy * dy) || 1;
const rest = e.kind === 'heading' ? 52 : 135;
const pull = ((dist - rest) / dist) * (e.kind === 'heading' ? 0.08 : 0.03);
if (s.fx === null) {
s.vx += dx * pull * 0.5;
s.vy += dy * pull * 0.5;
}
if (t.fx === null) {
t.vx -= dx * pull * 0.5;
t.vy -= dy * pull * 0.5;
}
}
for (const n of nodes) {
if (n.fx !== null && n.fy !== null) {
n.x = n.fx;
n.y = n.fy;
n.vx = 0;
n.vy = 0;
} else {
n.vx *= 0.76;
n.vy *= 0.76;
n.x += n.vx;
n.y += n.vy;
}
}
// Draw frame
ctx.clearRect(0, 0, width, height);
ctx.fillStyle = '#09090b';
ctx.fillRect(0, 0, width, height);
ctx.save();
ctx.translate(width / 2 + cam.x, height / 2 + cam.y);
ctx.scale(cam.k, cam.k);
const activeNeighbors = hoveredId
? neighborsRef.current.get(hoveredId)
: null;
for (const e of edges) {
const s = nodes[e.sourceIndex];
const t = nodes[e.targetIndex];
if (!s || !t) continue;
const connected =
hoveredId !== null && (s.id === hoveredId || t.id === hoveredId);
const alpha = hoveredId === null ? 0.11 : connected ? 0.65 : 0.02;
ctx.beginPath();
ctx.moveTo(s.x, s.y);
ctx.lineTo(t.x, t.y);
ctx.strokeStyle = `rgba(255, 255, 255, ${alpha})`;
ctx.lineWidth = connected ? 1.15 : 0.8;
ctx.stroke();
}
ctx.font = '450 11px Inter, sans-serif';
ctx.textAlign = 'center';
ctx.textBaseline = 'top';
for (const n of nodes) {
const isHovered = n.id === hoveredId;
const isNeighbor = activeNeighbors ? activeNeighbors.has(n.id) : false;
const r = n.kind === 'page' ? 4.2 + Math.min(4, Math.sqrt(n.degree)) : 2.3;
const alpha =
hoveredId === null
? n.kind === 'page'
? 0.94
: 0.45
: isHovered || isNeighbor
? 1.0
: 0.1;
ctx.beginPath();
ctx.arc(n.x, n.y, isHovered ? r * 1.2 : r, 0, Math.PI * 2);
ctx.fillStyle = `rgba(255, 255, 255, ${alpha})`;
ctx.fill();
const showLabel =
isHovered ||
(isNeighbor && n.kind === 'page') ||
(hoveredId === null && n.kind === 'page');
if (showLabel) {
ctx.fillStyle = `rgba(244, 244, 245, ${isHovered ? 1 : 0.78})`;
ctx.fillText(n.label, n.x, n.y + r + 5);
}
}
ctx.restore();
},
{ fps: 60, pauseWhenHidden: true, visibilityTarget: canvasRef }
);
const handleCanvasClick = (e: React.MouseEvent<HTMLCanvasElement>) => {
const rect = e.currentTarget.getBoundingClientRect();
const cam = cameraRef.current;
const wx = (e.clientX - rect.left - rect.width / 2 - cam.x) / cam.k;
const wy = (e.clientY - rect.top - rect.height / 2 - cam.y) / cam.k;
for (const n of nodesRef.current) {
const dx = wx - n.x;
const dy = wy - n.y;
if (dx * dx + dy * dy <= 64) {
ws.navigateToPage(n.pageId, n.blockId);
return;
}
}
};
const handleCanvasMove = (e: React.MouseEvent<HTMLCanvasElement>) => {
const rect = e.currentTarget.getBoundingClientRect();
const cam = cameraRef.current;
const wx = (e.clientX - rect.left - rect.width / 2 - cam.x) / cam.k;
const wy = (e.clientY - rect.top - rect.height / 2 - cam.y) / cam.k;
if (draggedRef.current) {
draggedRef.current.fx = wx;
draggedRef.current.fy = wy;
return;
}
let hitId: string | null = null;
for (const n of nodesRef.current) {
const dx = wx - n.x;
const dy = wy - n.y;
if (dx * dx + dy * dy <= 64) {
hitId = n.id;
break;
}
}
if (hitId !== hoveredId) setHoveredId(hitId);
};
const handleWheel = (e: React.WheelEvent<HTMLCanvasElement>) => {
e.preventDefault();
const targetCam = targetCameraRef.current;
const zoomFactor = Math.exp(-e.deltaY * 0.0015);
targetCam.k = Math.max(0.35, Math.min(3, targetCam.k * zoomFactor));
};
return (
<div
style={{
height: 440,
borderRadius: 12,
overflow: 'hidden',
background: '#09090b',
border: '1px solid rgba(255, 255, 255, 0.08)',
}}
>
<canvas
ref={canvasRef}
onClick={handleCanvasClick}
onMouseMove={handleCanvasMove}
onWheel={handleWheel}
style={{ display: 'block', width: '100%', height: '100%', cursor: 'grab' }}
/>
</div>
);
},
});