Skip to main content

Obsidian Setup and Workflow

Obsidian is an optional but highly recommended local editor for this repo. It turns the docs/ folder into a connected knowledge graph — every relates-to link becomes a visible graph edge, every YAML frontmatter field becomes a searchable property, and Dataview lets you query docs like a database.

This runbook covers setup for both developers (who work with git daily) and product owners (who mainly browse and annotate docs).

1. Install Obsidian​

Download from obsidian.md — available for macOS, Windows, and Linux.

2. Open the Repo as a Vault​

  1. Clone sv0-documentation locally if you haven't already: 
    git clone https://github.com/SecurityV0/sv0-documentation.git
  2. Open Obsidian → Open folder as vault
  3. Select the root of the cloned repo (the folder containing docs/, mkdocs.yml, etc.)
  4. When prompted about safe mode, choose Turn on community plugins — required for the plugins below.

Why the repo root, not docs/? Opening the root lets Obsidian Git commit from inside the app. If you open just docs/, wikilinks and graph edges still work, but Obsidian Git can't see the .git directory.

3. Required Plugins​

Install these from Settings → Community plugins → Browse:

PluginPurpose
Obsidian GitCommit, pull, and push without leaving the app
DataviewQuery docs by type, tags, status, priority
Properties viewSidebar panel showing YAML frontmatter fields on the active file

Obsidian Git setup​

After installing, configure in Settings → Obsidian Git:

  • Vault backup interval: 0 (disable auto-commit — commit manually to keep clean history)
  • Pull on startup: true
  • Author name / email: Match your GitHub identity

To commit from inside Obsidian: Cmd/Ctrl+P → Obsidian Git: Create backup (stages all changes and commits).

Developers: you can also just use terminal git — Obsidian Git is optional if you're comfortable with the CLI.

4. The Properties Panel (YAML Frontmatter)​

Every doc in this repo starts with a YAML frontmatter block:

---
date: 2026-03-08
type: runbook
status: active
source: sv0-delta
tags: [obsidian, documentation, workflow]
priority: medium
description: "One sentence summary shown in hover previews."
relates-to:
  - "[[other-document]]"
---

In Obsidian, open any doc and click the Properties icon (top-left of the editor, or Cmd/Ctrl+;). You'll see all fields as an editable panel — no YAML editing required.

Field reference​

FieldValuesPurpose
dateYYYY-MM-DDCreation date (set once, don't change)
updatedYYYY-MM-DDOptional: last significant revision
typearchitecture plan runbook research reference analysis adr integration productInferred from directory; set manually if wrong
statusdraft active approved archived deprecatedLifecycle state
tagskebab-case listUsed for graph clustering and filtering
sourcehuman sv0-echo sv0-delta sv0-blue sv0-charlie owenWho created the doc
priorityhigh medium lowOptional; used in Dataview filters
descriptionStringOne sentence; shown in hover previews
relates-to[[wikilinks]]Graph edges — the primary connection mechanism

5. Graph View​

Open Graph view (Cmd/Ctrl+G) to see the full doc graph. Every relates-to wikilink becomes a visible edge.

Useful graph filters (click the filter icon in graph view):

  • Filter by tag: tag:#architecture shows only architecture docs
  • Filter by path: path:docs/product shows only product docs
  • Filter by property: not directly supported in graph filters, but use the Groups panel to colour nodes by tag

Tips:

  • Cmd/Ctrl+click a node to open it
  • Use the depth slider (bottom of the panel) to show neighbours up to N hops away
  • The local graph (Cmd/Ctrl+Shift+G or the graph icon on a specific note) shows only the current doc and its direct connections — useful for navigating from a known starting point

6. Dataview Queries​

The Dataview plugin lets you query docs like a database. These are read-only views — useful for exploration, not editing.

All ADRs by date​

TABLE description, date, status
FROM "docs/architecture/decisions"
WHERE type = "adr"
SORT date DESC

Active plans​

TABLE description, date, source
FROM "docs/plans"
WHERE status = "active"
SORT date DESC

High-priority docs​

TABLE description, type, date
FROM "docs"
WHERE priority = "high" AND status = "active"
SORT date DESC

All docs with graph connections​

TABLE relates-to, type, date
FROM "docs"
WHERE relates-to
SORT date DESC

Product docs tagged for a specific wedge​

TABLE description, tags, date
FROM "docs/product"
WHERE status = "active" AND contains(tags, "wedge1")
SORT date DESC

To use a query: create a new note, add a code block with language dataview, paste the query inside. The block renders as a live table in Reading view (Cmd/Ctrl+E).

7. Creating a New Document​

When creating docs, follow the standard schema. Template:

---
date: YYYY-MM-DD
type: runbook
status: draft
source: human
tags: [relevant, kebab-case, tags]
priority: medium
description: "One sentence describing this document."
relates-to:
  - "[[related-document-stem]]"
---

# Title

Content here.

Checklist before committing a new doc:

  • YAML frontmatter present and complete (date, type, status, source, description)
  • relates-to links added for at least the most relevant 1-2 existing docs
  • File named in lowercase-with-hyphens.md
  • Added to mkdocs.yml nav (or ask a developer to add it)
  • File placed in the correct directory (see the Repo Guide)

8. Workflow: For Product Owners​

If you don't use git, this is the minimal flow to read, annotate, and contribute docs:

  1. Reading: Open Obsidian, use Graph view or the file explorer to navigate
  2. Searching: Cmd/Ctrl+Shift+F → full-text search across all docs
  3. Hover previews: Hover over any [[wikilink]] to see the description of the linked doc without leaving the current page
  4. Suggesting edits: Edit the file in Obsidian, then use Cmd/Ctrl+P → Obsidian Git: Create backup to commit and push. Open a PR on GitHub if you want review before it goes live.
  5. Exploring by topic: Use the Dataview queries in section 6, or filter by tag in Graph view

9. Workflow: For Developers​

Standard git-based flow with Obsidian as the editor:

git checkout main && git pull origin main
git checkout -b docs/my-topic
# edit in Obsidian or your editor
git add docs/...
git commit -m "docs: ..."
git push -u origin docs/my-topic
gh pr create

Obsidian is used for:

  • Writing and navigating docs
  • Checking graph connections before committing
  • Running Dataview queries to verify cross-references

10. MkDocs vs Obsidian​

This repo uses both MkDocs (for the deployed docs site) and Obsidian (for local navigation).

ConcernMkDocsObsidian
Deployed docs site✓
Navigation structureDefined in mkdocs.yml navFile system + wikilinks
Graph view✓
Dataview queries✓
Hover previews✓
PR preview✓ (Cloudflare Pages)
AI agent access✓ (YAML frontmatter)

The two tools are complementary. MkDocs is the source of truth for what's deployed and publicly navigable. Obsidian is the local knowledge graph for the team.