Obsidian Graph

Obsidian Graph view

Global graph configuration lives in .obsidian/graph.json. Local graph (Graph view opened from a single note) lives in .obsidian/workspace.json and does not inherit from global. This skill covers global graph unless explicitly noted.

For diagnosing what's wrong with a graph (over-connection, render-only edges, false categories), use the paired obsidian-graph-audit skill first.

Workflow when the user asks "configure my graph"

1. Ask or read intent first. What's bothering them, or what do they want to see? Color groups without a goal are pure aesthetics — skip them.
2. ⚠️ Have the user close Graph view (or quit Obsidian). This is mandatory — Obsidian rewrites graph.json when Graph view closes, wiping external edits. See Caveats.
3. Read the current .obsidian/graph.json. Don't reset settings the user has tuned (especially scale).
4. Measure vault size: find . -name '*.md' -not -path './.obsidian/*' -not -path './.trash/*' -not -path './.claude/*' | wc -l. Forces depend on this.
5. Apply minimum changes, explain each. 14 color groups on 600 notes is too many — 3-8 is the proven range.
6. Keep only what adds signal. Filter > group when you don't want to see something; group > filter when you want to differentiate.
7. Verify decimal RGB math. A wrong byte in a color value silently renders as a different color. Always round-trip HEX↔decimal (see below).
8. Have the user open Graph view after edits. Changes take effect on next open.

Full schema of graph.json

20 fields. Source: community gist on syncing graph settings, example repo. Obsidian has no official schema document.

Filters block

Color groups block

Display block

Forces block

Other

What creates a graph edge

Before configuring color groups or filters, understand which references in a note become edges in the graph. Obsidian renders an edge from any of the following:

• [[Wikilinks]] in the body of a note
• Wikilinks inside frontmatter list fields, including topics: and categories: (any list-of-wikilinks pattern)
• Wikilinks inside single-value frontmatter properties — e.g. author: "[[J. R. R. Tolkien]]", director: "[[Christopher Nolan]]", host: "[[Tim Ferriss]]". These generate graph edges identical to wikilinks in the body. This is often missed.
• Tag nodes when showTags: true (otherwise tags don't appear at all)

What does NOT create an edge:

• Plain string properties (role: "Senior Engineer")
• Tags (when showTags: false)
• Wikilinks inside fenced code blocks (```...```) or inline code (`)

This matters when you design color groups: a note with author: "[[J. R. R. Tolkien]]" is already linked to the J. R. R. Tolkien node, so an additional tag: tolkien adds nothing graph-wise. Similarly, a topics: entry is redundant if a property field already references the same target. See obsidian-graph-audit Pattern H.

Search syntax (for search filter and query in color groups)

Same syntax as core Search.

Operators

Logic

Caveats for color groups

• Order matters. First matching group wins. Tags first (semantic role), categories next (entity type), topics third (epic clusters), paths last (catch-all).
• ["property":"value"] is substring match, not strict. ["categories":"Recipe"] matches both Recipes and Recipe Drafts. Mitigation: use distinct strings as category/topic names. If strict match is needed, convert to a tag.
• Regex is supported — /^Daily/, /202\d-/, etc.

Color group format

{
  "query": "<search query>",
  "color": { "a": 1, "rgb": <decimal RGB> }
}

• a — alpha (transparency), 0 = invisible, 1 = solid. Almost always 1.
• rgb — 24-bit decimal: R*65536 + G*256 + B.

HEX → decimal conversion

python3 -c "h='E07B5A'; print(int(h, 16))"  # → 14711642

Or manually: 0xE07B5A = 224*65536 + 123*256 + 90 = 14,711,642.

One wrong byte renders as a different color. Always round-trip:

python3 -c "n=14711642; print(f'#{n:06X}')"  # → #E07B5A

Palette — pastel set

Soft, calm overall. Luminosity values are close, so 5+ groups in this set may visually merge.

Palette — high-contrast set

Use when 5+ pastel groups blur together. Luminosity ranges from bright (hubs) to dark (Daily) — the eye separates them.

Four coloring strategies

Color groups can target four different dimensions of a note. Different vaults call for different strategies; mature vaults usually mix them.

A. Folder-based (path:)

{"query": "path:\"Projects/Active\"", ...}

When to use: Project-organized vault where the folder is a meaningful unit. Each project lives in its own folder, the layout is stable.

Pros:

• Simple mental model — "everything in this folder"
• No frontmatter required
• New files inherit the color automatically

Cons:

• Doesn't capture cross-cutting concerns (hub-pages, status workflows) that span folders
• Reorganizing folders breaks the coloring
• Files in one folder may be of different types (an epic and a routine note get the same color)

B. Category-based (["categories":"X"])

{"query": "[\"categories\":\"Companies\"]", ...}

When to use: Kepano-style vault with frontmatter categories:. Category = entity type (company, contact, recipe, film). Files in one category are semantically homogeneous.

Pros:

• Color follows entity meaning, not accidental location
• A file can belong to multiple categories (multi-color via group order)
• Folder reorganization doesn't break it

Cons:

• Property-search is substring match. ["categories":"Recipe"] matches both Recipes and Recipe Drafts. Categories must be distinct strings (see Caveats)
• Requires disciplined frontmatter
• Files without categories (rough notes, drafts) are uncolored

C. Topic-based (["topics":"X"])

{"query": "[\"topics\":\"Active Initiative\"] OR file:\"Active Initiative\"", ...}

When to use: Kepano-style with topics: fields (wikilinks to epics or coordinating concepts). Useful for an active project with epic-coordinators and many files attached to each.

Pros:

• Color = semantic cluster (the epic and everything tied to it)
• Cross-folder: files from Reports/, Interview Prep/, BootCamp/ can land in one color if they share a topic
• Ghost nodes work — the query reads the topic from frontmatter; it doesn't need the epic file to exist
• Sharper than path catch-all for a large active project (splits work streams visually)

Cons:

• Same substring-match caveat as ["categories":...]
• Files without topics aren't colored
• OR file:"X" is needed to color the epic node itself (the epic doesn't list itself as its own topic)
• More groups means closer to the 14-group practical ceiling

D. Tag-based (tag:#name)

{"query": "tag:#hub", ...}

When to use: Tag taxonomy for cross-cutting concerns — hubs (#hub), statuses (#status/done), types (#moc, #evergreen). A tag describes "what role does this file play in the graph", not "what is this file".

Pros:

• Strict match (not substring, unlike property)
• Multi-dimensional — tags cross folders and categories
• Easy to add or remove ad hoc

Cons:

• Tag taxonomy can sprawl without discipline
• A bare tag with no file is an orphan node when showTags: true
• Bureaucratic for very large vaults

Mixed approach — typical for mature vaults

"colorGroups": [
  {"query": "tag:#hub", ...},                                                      // cross-cutting accent
  {"query": "[\"categories\":\"Companies\"]", ...},                                 // entity types
  {"query": "[\"categories\":\"Contacts\"]", ...},
  {"query": "[\"topics\":\"Active Initiative\"] OR file:\"Active Initiative\"", ...}, // epic clusters
  {"query": "[\"topics\":\"Other Initiative\"] OR file:\"Other Initiative\"", ...},
  {"query": "path:\"Daily\"", ...},                                                 // structural folder
  {"query": "path:\"Projects\"", ...}                                               // catch-all
]

Order matters — tags first (semantic role), categories second (entity type), topics third (epic clusters of the active project), paths last (catch-all). First match wins.

Choosing a strategy

Best practices

1. Color by meaning, not by folder. Folder is one dimension; see the four-strategy section above. Pick by structure, often combine.

2. 3-8 color groups, not 14. Each group is render overhead and visual noise. If 14 feels needed, the user probably wants 5 conceptual buckets, not 14 individual ones.

3. Order matters. Specific queries first, broad last. First match wins.

4. Filter only for active noise, not for periphery. Folders that are weakly connected (rough notes, drafts, scratch) form their own peripheral cluster and don't crowd the center. Filter is justified when nodes from a folder embed into the center and pollute important clusters — typical candidates: Templates (if not in userIgnoreFilters), archive tagged #archive. Before adding -path: or -tag:, ask: "are these nodes currently in the center, or on the edge?". On the edge — leave them, they give visual segregation.

5. Don't show tags on the graph unless they're cross-cutting. Tags isolated to a single note become satellite-nodes with no signal. Tags that duplicate folder names add tangle without meaning. Enable showTags: true only when tags form a real semantic network (#moc, #status/*, thematic concepts).

6. textFadeMultiplier 0 means labels never visible. If you want to read names at zoom-in, set ≥ 0.3 (0.5 is a good default).

7. Forces are vault-size dependent. Sane defaults for ~600 notes: centerStrength: 0.5, repelStrength: 15-25, linkStrength: 0.7-1, linkDistance: 150-250. Larger vault → more repel + shorter links.

8. Don't edit scale by hand. Obsidian overwrites it on every zoom. Manual edits are wiped.

9. Local graph is configured separately. Local graph config lives in .obsidian/workspace.json under workspace state; it doesn't inherit from global. For shared color groups locally, install the community plugin Sync Graph Settings.

10. CSS snippet for defaults, color groups for exceptions (community pattern). Set base node/tag/attachment/unresolved colors via a CSS snippet once, use color groups only for specific subsets. Less retina-burning than 8 path-based groups doing everything.

CSS classes (for snippets)

The graph renders to canvas/WebGL, but Obsidian reads CSS color rules and converts them. Use !important to override. Path: Settings → Appearance → CSS snippets.

#HEX, rgb(), and rgba() are all supported. For transparent edges in graph view, use rgba.

Recipes

Hide noise

"search": "-path:\"Templates\" -path:\"Rough Notes\" -tag:#archive"

Focus on one project

"search": "path:\"Projects/Active\""

Color by status (tag-based)

"colorGroups": [
  {"query": "tag:#status/done",  "color": {"a": 1, "rgb": 8110426}},
  {"query": "tag:#status/draft", "color": {"a": 1, "rgb": 14731610}},
  {"query": "tag:#status/seed",  "color": {"a": 1, "rgb": 9149865}}
]

Color by project (folder-based)

"colorGroups": [
  {"query": "path:\"Projects/A\"", "color": {"a": 1, "rgb": 14711642}},
  {"query": "path:\"Projects/B\"", "color": {"a": 1, "rgb": 10185699}},
  {"query": "path:\"Notes\"",       "color": {"a": 1, "rgb": 14272670}},
  {"query": "path:\"Daily\"",       "color": {"a": 1, "rgb": 7376808}}
]

Color by category (Kepano-style)

"colorGroups": [
  {"query": "[\"categories\":\"Companies\"]", "color": {"a": 1, "rgb": 12092447}},
  {"query": "[\"categories\":\"Contacts\"]",  "color": {"a": 1, "rgb": 11828425}},
  {"query": "[\"categories\":\"Recipes\"]",   "color": {"a": 1, "rgb": 7317077}},
  {"query": "[\"categories\":\"Reports\"]",   "color": {"a": 1, "rgb": 9149865}}
]

Color by topic (epic clusters of an active project)

"colorGroups": [
  {"query": "[\"topics\":\"Initiative A\"] OR file:\"Initiative A\"",
   "color": {"a": 1, "rgb": 14904219}},
  {"query": "[\"topics\":\"Initiative B\"] OR file:\"Initiative B\"",
   "color": {"a": 1, "rgb": 5943264}}
]

OR file:"X" is needed because the epic node's own topics: references upstream parents, not itself.

Highlight hubs / MOCs

Tag-based — strict, recommended:

{"query": "tag:#hub", "color": {"a": 1, "rgb": 15252785}}

Folder/file-based fallback (when tags aren't in use):

{"query": "file:\"Home\" OR file:\"About\" OR path:\"Categories\"",
 "color": {"a": 1, "rgb": 15781984}}

Hide infrastructure and archive via tag taxonomy

Establish: #dashboard for view pages (kanban, metrics, charts), #no-graph for logs / setup docs / configs (pure control tag), #archive for archived content.

"search": "-tag:#dashboard -tag:#no-graph -tag:#archive"

Combine with category-exclude to hide entity types not wanted on the conceptual graph:

"search": "-tag:#dashboard -tag:#no-graph -[\"categories\":\"Vacancies\"]"

Forces for a 600+ note vault

"centerStrength": 0.5,
"repelStrength": 22,
"linkStrength": 0.7,
"linkDistance": 220,
"textFadeMultiplier": 0.5,
"nodeSizeMultiplier": 1.4,
"lineSizeMultiplier": 0.8

Caveats and gotchas

• ⚠️ Obsidian rewrites graph.json when Graph view closes. When the graph tab closes (or the app quits), Obsidian flushes its in-memory state to the file, overwriting external edits. Symptom: just-made edits are gone, close: true, and colorGroups: [].

  Procedure: either (a) Cmd+Q quit Obsidian → edit graph.json → relaunch → open Graph view; or (b) close the Graph view tab → edit → Cmd+P → Reload app without saving → open Graph view. Never edit while Graph view is open.

• Property-search is substring, not strict. ["topic"] matches topic, parent_topic, and topic_alternative. Don't use property search for color groups when precision matters; use tags instead.

• Many color groups slow rendering. Each group is O(notes × groups) per repaint. Above 15 groups it's noticeable on large vaults.

• showOrphans: false hides early sessions of a new vault. In a fresh vault most notes are orphans; without showOrphans: true you see an empty screen.

• Filter cascading. Removing a note via filter also removes its edges, and its neighbors may become orphans on the graph.

• Extended Graph plugin (ElsaTam/obsidian-extended-graph, locally-installed) gives deeper config (per-tag colors, edge weights). Recommend it when core hits a ceiling — don't try to squeeze more from the core graph.

Multiple views / saved presets

Core Obsidian doesn't support saved graph presets — one global config, one local. To switch between multiple views, install a plugin:

Don't recommend a plugin preemptively. Have the user describe the views they want to switch between (e.g. "focused project view" vs "full vault"). If there's no concrete use case, one global config is enough.

Manual approach without a plugin: store variants of graph.json in .obsidian/graph-presets/ and swap with a script. Not recommended — no UI for switching, easy to forget to restore, and races with Obsidian's overwrite (see Caveats).

When NOT to touch the graph

• The graph is used for 5-10 minutes a day for serendipity, not as primary navigation. Don't optimize it as a dashboard.
• The user hasn't said what's bothering them. Don't propose edits unprompted.
• Aesthetic edits without a clear task = bikeshedding. Get the goal first ("I want to see X / I don't want to see Y"), then config.