The Graph Widget
The graph widget can be added to any page in two forms:
- Full graph view: place the
{{< quarto-graph-full >}}shortcode on any page you choose, this page for an example: Graph. This view shows every page by default. Drag nodes, scroll to zoom, click a node to open that page. Multiple instances on one page are fine, each with its own params. See Customizing the full graph widget. - Sidebar mini-panel: on every page, a small N-depth subgraph (the current page plus everything within N links of it; 1-depth by default) mounts at the top of the right-hand TOC sidebar. Clicking it opens a larger modal version of the same subgraph. Shows alongside the full graph view too, if a page has both.
What graph.json looks like
graph.json contains an array of nodes and edges. Here’s a minimal example with two nodes (Backlinks and The Graph Widget) and one edge between them:
{
"nodes": [
{"title": "Backlinks", "type": "concept", "url": "/backlinks/"},
{"title": "The Graph Widget", "type": "concept", "url": "/the-graph-widget/"}
],
"edges": [[0, 1]]
}Edges are pairs of node indices; [0, 1] connects the first and second nodes.
graph.json is assembled in two passes: pre-render builds the registry and backlink map from every page’s wikilinks and writes it to a side-channel file; then, at each page’s own render time, its Lua filter records that page’s real output URL to another side-channel file. Post-render joins the two and writes the final graph.json into the output directory. This late join is why a wikilink resolves to a real URL only after the whole project has rendered, not up front.
Node color
Each node’s color comes from its page’s type: frontmatter. The mapping is:
| Type | Color |
|---|---|
concept |
#3ba29f |
person |
#9177b6 |
reference |
#d65527 |
project |
#6b0021 |
experiment |
#c9a227 |
moc |
#8fa6d9 |
| (none/other) | #9aa0a6 |
Customizing the full graph widget
{{< quarto-graph-full >}} takes kwargs, all optional:
| Kwarg | Meaning |
|---|---|
width |
Any CSS length ("600px", "80%", "50vw") applied to the widget’s container. Default: fills its container. |
height |
Any CSS length. Default: max(420px, 65% of viewport height). |
depth |
Show only pages within N links of root (or the current page, if root is omitted), instead of the whole project graph. |
root |
The page to center depth on. Matched the same way a [[wikilink]] is: by title, alias, or filename stem first, falling back to a literal source path (e.g. posts/foo.qmd) if nothing matches. Ignored unless depth is also set. |
expandable |
"true" adds a button that expands the widget to a fullscreen overlay. Default: off. |
{{< quarto-graph-full width="700px" height="50vh" expandable="true" >}}
{{< quarto-graph-full root="Getting Started" depth="2" >}}Each {{< quarto-graph-full >}} call is independent. There’s no project-wide default for any of these, unlike the sidebar mini-panel below. A root that doesn’t match any page logs a warning at render time and that particular widget renders nothing, rather than silently falling back to the whole graph.