[Intermediate] — Every option, what it does at 855 notes rather than at 50, and the colour mechanic that makes links look broken when they aren’t.
Local vs global
Two graphs, configured separately:
- Local — the panel in the right sidebar. Shows the current note and everything within
depthhops. - Global — every note in the vault. Opens as a modal via the small network icon at the top-right of the local panel. It has no URL of its own; see Layout and Components for what a real
/graphpage would require.
Node radius is proportional to total links in + out, so hubs are visibly bigger. Visited notes render in a different colour, like browser link history.
The graph requires the content-index emitter — it needs the whole link map, which only exists after every file is parsed.
Options
options:
localGraph:
depth: 2 # hops from the current note; -1 = everything
scale: 1.1 # initial zoom (higher = closer)
repelForce: 0.6 # how hard nodes push each other apart
centerForce: 0.3 # how hard they're pulled to the middle
linkDistance: 35 # target edge length
fontSize: 0.5 # label size
opacityScale: 1.2 # how fast labels fade with zoom
showTags: false
focusOnHover: true # dim everything not connected to the hovered node
enableRadial: false
drag: true
zoom: true
removeTags: []Tuning for a large vault
The defaults are built for a ~100-note garden. At 855 densely cross-linked notes they collapse into an unreadable blob. What actually mattered here:
enableRadial: false — the single biggest change. Radial layout forces every node into a ring, which destroys the domain clustering that makes a large graph legible in the first place. Force-directed layout lets git/, devops/, ai-ml/ settle into visible clusters. The default is true for the global graph; turning it off is what makes the global view worth opening.
repelForce up (0.9 global, 0.6 local) — at scale, default repulsion leaves nodes overlapping.
linkDistance up (45 global, 35 local) — more room between connected nodes, fewer crossing edges.
fontSize down (0.45 global, 0.5 local) — 855 labels at the default 0.6 is a solid mat of overlapping text.
showTags: false — no note in this vault uses frontmatter tags, so tag nodes would be pure noise. If you never tag, turn this off everywhere.
scale down for global (0.65) — start zoomed out enough to see the shape.
focusOnHover: true earns its place at this size: hovering dims everything not connected, which is the only practical way to trace one note’s neighbourhood in a dense graph.
The link-colour mechanic
The thing that looks like a bug and isn’t — or rather, is a palette bug that looks like a graph bug.
Reading the shipped source:
// @quartz-community/graph — link rendering
function Ve() {
for (...) { l.alpha = 1; l.color = l.active ? ee : te }
}
// ee = --gray (hovered)
// te = --lightgray (normal)Links are drawn at full opacity all the time. Hovering changes only the colour. So if --lightgray is close to --light (the page background), every edge is invisible until hovered, and it reads as “the graph only shows paths on hover.”
That was exactly this vault’s symptom: lightgray: #2f2d33 against light: #17161a is roughly 1.3:1 contrast. The fix was lifting --lightgray, not touching any graph option.
Two things follow:
opacityScaleis not the knob. It governs how labels fade with zoom, not link visibility.- CSS cannot fix it. The graph paints to a PIXI canvas and reads the variables off
document.documentElementat draw time. There is no DOM element per link to style. The only lever is the variable — see Theming and Styling for the compensating trick.
The node-dimming path is separate and does respect focusOnHover:
function Ke() { ... _u !== null && Oe && (F = l.active ? 1 : .2); l.gfx.alpha = F }
// ^^ Oe = focusOnHoverNote the link function has no focusOnHover guard — links dim on hover regardless of that setting. Only nodes respect it.
Sizing the panel
Neither the panel height nor the modal size is configurable in YAML. Both are CSS:
.graph .graph-outer { height: 320px; } // default 250px
.graph > .global-graph-outer > .global-graph-container {
width: 92vw; // default 80vw
height: 90vh; // default 80vh
}Worth raising the panel height whenever localGraph.depth is above 1 — depth 2 pulls in far more nodes than 250px can show.
Debugging it
The rendered config is inlined into the HTML as a data-cfg attribute, which is the fastest way to confirm your YAML actually took effect:
grep -o 'class="graph-container" data-cfg="[^"]*"' public/git/index.htmlIf those values are the plugin defaults rather than yours, the likely cause is a stale build — public/ isn’t regenerated until you run a build, and an old public/ will happily show you settings from weeks ago.
Related
- Theming and Styling — why
--lightgrayis the load-bearing variable - Layout and Components — what a dedicated graph page would take
- How Quartz Works — why the graph must be an emitter, not a transformer
- Quartz notes
Software engineering
Infrastructure & security
Computer science
Hardware & engineering