Skip to content

Research: Obsidian Integration Patterns

Date: 2025-11-09 Researcher: Phase 5 Unit 1 Status: Complete Related: ADR-026

Overview

This research document explores Obsidian's core features and best practices for integration, focusing on wikilinks, tags, Dataview plugin capabilities, and Graph View requirements. The goal is to inform our Phase 5 implementation of deep Obsidian integration for Inkwell's podcast note generation.

Obsidian uses wikilinks (double square brackets) as the primary internal linking mechanism:

[[Note Name]]                    # Basic link
[[Note Name|Display Text]]       # Custom display text
[[Note Name#Heading]]            # Link to heading
[[Note Name#^block-id]]          # Link to specific block

Key Features

1. Autocomplete & Suggestions

  • Type [[ and Obsidian suggests existing notes
  • Type [[Note# to see headings in that note
  • Type [[Note#^ to see block references
  • Links automatically appear in both source and target notes
  • Backlinks panel shows all notes linking to current note
  • Creates automatic knowledge graph connections

3. Unlinked Mentions

  • Obsidian detects mentions of note names without explicit links
  • Shows potential connections for manual linking
  • Reduces over-linking fatigue

✅ DO:

  1. Use wikilinks for entities with potential reuse
  2. People: [[Cal Newport]]
  3. Books: [[Deep Work]]
  4. Tools: [[Obsidian]]

  5. Concepts that appear across episodes: [[Zone of Genius]]

  6. Provide custom display text when helpful

  7. [[Deep Work|Cal Newport's book on focus]]

  8. [[Tim Ferriss|Tim]] for readability in context

  9. Link to specific sections when relevant

  10. [[Episode 287#Key Takeaways]]

  11. Enables precise cross-episode references

  12. Use consistent naming conventions

  13. Books: [[Book - Deep Work]] or [[Deep Work]]
  14. People: [[Person - Cal Newport]] or [[Cal Newport]]
  15. Tools: [[Tool - Notion]] or [[Notion]]
  16. Consistency enables better graph connections

❌ DON'T:

  1. Over-link common words
  2. Avoid linking every mention of "work", "time", "productivity"

  3. Reserve links for specific references

  4. Create orphan links without context

  5. Every wikilink should have purpose

  6. Consider: will user click this link?

  7. Use markdown links when wikilinks are appropriate

  8. Wikilinks work better within Obsidian ecosystem
  9. Markdown links break backlinks and graph
Feature Wikilinks [[]] Markdown Links []()
Autocomplete ✅ Yes ❌ No
Backlinks ✅ Yes ❌ No
Graph View ✅ Yes ❌ No
Rename support ✅ Yes ❌ No
Plugin support ✅ Excellent ⚠️ Limited
Portability ⚠️ Obsidian-specific ✅ Universal
File paths ✅ Automatic ❌ Manual

Recommendation for Inkwell: Use wikilinks exclusively for Obsidian integration. Users who need portability can use community plugins to convert wikilinks to markdown links.

2. Tag System - Organization & Categorization

Tag Syntax

Obsidian supports three tag formats:

#tag                             # Inline tag
#parent/child                    # Nested/hierarchical tag
#parent/child/grandchild         # Multi-level hierarchy

---
tags: [tag1, tag2, parent/child] # YAML frontmatter
---

Hierarchical Tag Structure

Tags with forward slashes (/) create logical hierarchies:

#podcast/deep-questions
#podcast/huberman-lab
#topic/ai
#topic/productivity
#topic/ai/machine-learning
#topic/ai/llm
#person/cal-newport
#person/andrew-huberman

Tag Best Practices

✅ Effective Tag Strategies:

  1. Use hierarchies for scalability 

    #podcast/show-name              # Scales to many podcasts
#topic/parent/child             # Enables filtering at any level
#status/reviewed                # Action-based organization

  2. Balance specificity and utility

  3. Too broad: #interesting (meaningless)
  4. Too narrow: #episode-287-discussed-on-tuesday (too specific)

  5. Just right: #topic/deep-work, #theme/focus-strategies

  6. Use YAML frontmatter for metadata tags 

    ---
tags:
  - podcast/deep-questions
  - topic/productivity
  - person/cal-newport
  - status/reviewed
---
    Benefits: Cleaner markdown, easier to edit, Dataview-friendly

  7. Create tag naming conventions

  8. Lowercase only: #ai not #AI
  9. Hyphens for multi-word: #deep-work not #deep_work or #deepwork
  10. Namespace prefixes: #podcast/, #topic/, #person/

❌ Tag Anti-Patterns:

  1. Over-tagging
  2. Don't tag every possible concept
  3. More tags = more cognitive load

  4. Focus on 3-7 meaningful tags per note

  5. Inconsistent naming

  6. #AI, #ai, #artificial-intelligence all different

  7. Pick one convention and stick to it

  8. Meaningless tags

  9. #important, #todo, #interesting without context
  10. Use more specific tags

Tag Wrangler Plugin

Key capabilities: - Visual tag hierarchy browser - Rename tags across vault - Merge duplicate tags - Navigate tag relationships

Recommendation: Essential for managing large tag systems programmatically.

3. Dataview Plugin - Querying Metadata

What is Dataview?

Dataview treats your Obsidian vault as a queryable database, enabling SQL-like queries over markdown files and their metadata.

Repository: https://github.com/blacksmithgu/obsidian-dataview Adoption: One of the most popular Obsidian plugins (~1M downloads)

Metadata Sources

Dataview can query:

  1. YAML Frontmatter (explicit metadata) 

    ---
type: podcast-note
podcast: Deep Questions
episode: 287
date: 2025-11-09
duration: 3600
rating: 5
actionable: true
---

  2. Inline Fields (within content) 

    Rating:: 5
Status:: reviewed

  3. Implicit Fields (automatically available)

  4. file.name - File name
  5. file.path - File path
  6. file.link - File as link
  7. file.size - File size
  8. file.ctime - Creation time
  9. file.mtime - Modified time
  10. file.tags - All tags
  11. file.inlinks - Backlinks
  12. file.outlinks - Outgoing links

Query Language

LIST Query

LIST
FROM #podcast
WHERE rating >= 4
SORT date DESC

TABLE Query

TABLE podcast, episode, duration, rating
FROM #podcast
WHERE date >= date(2025-01-01)
SORT rating DESC, date DESC

TASK Query

TASK
FROM #podcast
WHERE !completed

CALENDAR Query

CALENDAR date
FROM #podcast

Frontmatter Best Practices for Dataview

✅ Dataview-Friendly Design:

  1. Use consistent field names 

    # Good - consistent across all notes
podcast: Deep Questions
episode: 287
date: 2025-11-09

# Bad - inconsistent
show: Deep Questions  # sometimes "podcast", sometimes "show"
ep: 287              # sometimes "episode", sometimes "ep"

  2. Use appropriate data types 

    # Dates
date: 2025-11-09                    # YYYY-MM-DD format

# Numbers
duration: 3600                      # Integer (seconds)
rating: 5                           # Integer (1-5)
cost_total: 0.45                    # Float

# Booleans
actionable: true                    # Boolean
interview_conducted: false          # Boolean

# Lists
topics: [ai, productivity, focus]   # List

# Links
guest: [[Cal Newport]]              # Wikilink in frontmatter

  3. Create queryable categories 

    type: podcast-note                  # Enables: WHERE type = "podcast-note"
status: reviewed                    # Enables: WHERE status = "reviewed"

  4. Add custom calculation fields 

    word_count: 8543                    # For tracking note length
action_items: 3                     # For tracking actionable insights
cost_transcription: 0.003           # For cost breakdowns
cost_extraction: 0.015
cost_interview: 0.15
cost_total: 0.168

Example Dataview Queries for Inkwell

Most Expensive Episodes

TABLE podcast, episode, cost_total
FROM #podcast
SORT cost_total DESC
LIMIT 10

Actionable Episodes Not Yet Reviewed

LIST
FROM #podcast
WHERE actionable = true AND status != "reviewed"

Episodes by Podcast, Grouped

TABLE episode, date, duration
FROM #podcast
GROUP BY podcast
SORT podcast ASC, date DESC

Interview Completion Rate

TABLE
  length(rows) AS "Total Episodes",
  length(filter(rows, (r) => r.interview_conducted = true)) AS "Interviewed",
  round(length(filter(rows, (r) => r.interview_conducted = true)) / length(rows) * 100) + "%" AS "Rate"
FROM #podcast
GROUP BY podcast

Episodes with High Ratings

TABLE file.link AS Episode, rating, date
FROM #podcast
WHERE rating >= 4
SORT date DESC

Multi-Value Fields & Complex Queries

Nested Frontmatter

---
speakers:
  - name: Cal Newport
    role: host
  - name: Jesse
    role: producer
---

Query nested fields: 

TABLE speakers.name
FROM #podcast
FLATTEN speakers AS speaker
WHERE speaker.role = "host"

List Containment

---
topics: [ai, productivity, deep-work]
---

Query lists: 

LIST
FROM #podcast
WHERE contains(topics, "ai")

4. Graph View - Visual Knowledge Networks

How Graph View Works

Obsidian's Graph View visualizes your vault as a network: - Nodes = Notes - Edges = Links (wikilinks only) - Color coding by tags, folders, or custom rules - Zoom, pan, filter capabilities

Requirements for Good Graph Visualization

  • Links should represent genuine relationships
  • Avoid linking every mention (creates noise)
  • Focus on cross-references that add value

2. Consistent Note Structure

  • Similar notes (e.g., all podcast episodes) should link consistently
  • Creates recognizable patterns in graph

3. Hub Notes

  • Central index notes that link to many related notes
  • Example: [[Podcast - Deep Questions - Index]] links to all episodes
  • Creates clear visual hierarchy

Inkwell Graph View Strategy

Episode-to-Episode Linking

## Related Episodes

This episode builds on ideas from:
- [[Episode 285 - On Deep Work]]
- [[Episode 280 - Managing Attention]]

See also discussions of similar themes in:
- [[Episode 250 - Zone of Genius]]

Topic-Based Clustering

## Key Topics

This episode covered:
- [[Topic - Artificial Intelligence]]
- [[Topic - Productivity Systems]]
- [[Topic - Knowledge Management]]

Entity Linking

## People Mentioned

- [[Cal Newport]] (host)
- [[Andrew Huberman]] (referenced)
- [[Tim Ferriss]] (mentioned book)

## Books Discussed

- [[Book - Deep Work]]
- [[Book - Slow Productivity]]

Result: Creates visual clusters in Graph View: - All episodes cluster around their podcast - Episodes discussing similar topics cluster together - Entity nodes (people, books) connect episodes across podcasts

Templater

Purpose: Advanced template system with JavaScript support Relevance: Could inspire our own template system enhancements

Dataview (covered above)

Purpose: Query engine for vault Relevance: Primary reason for our frontmatter design

Tag Wrangler

Purpose: Tag management and refactoring Relevance: Users will need this for large tag systems

Excalidraw

Purpose: Diagrams and sketches Relevance: Not directly relevant, but popular for visual thinkers

Tasks

Purpose: Task management with checkboxes Relevance: Could enhance our action items from interviews

Calendar

Purpose: Calendar view of daily notes Relevance: Could visualize podcast listening timeline

6. Key Findings & Recommendations

Findings

  1. Wikilinks are essential
  2. Core to Obsidian's value proposition
  3. Enable backlinks, graph view, and navigation

  4. Must use [[]] format, not markdown links

  5. Hierarchical tags scale better

  6. Flat tags become overwhelming at scale
  7. Use namespace prefixes: #podcast/, #topic/, #person/

  8. YAML frontmatter preferred over inline tags

  9. Dataview demands consistent frontmatter

  10. Field names must be consistent across notes
  11. Data types matter (dates, booleans, numbers)

  12. Lists and nested structures are supported

  13. Graph View requires intentional linking

  14. Too many links = noise
  15. Too few links = isolation
  16. Focus on meaningful cross-references

Recommendations for Inkwell

  • ✅ Auto-generate wikilinks for: people, books, tools, concepts
  • ✅ Use consistent naming: prefer simple [[Name]] over prefixes
  • ✅ Link cross-episode references
  • ✅ Provide custom display text when context demands

Tags

  • ✅ Use hierarchical structure: #podcast/show-name
  • ✅ Limit to 5-7 tags per note
  • ✅ Store in YAML frontmatter, not inline
  • ✅ Support custom tag rules per podcast feed

Dataview

  • ✅ Design frontmatter schema for queryability
  • ✅ Include: type, podcast, episode, date, duration, rating, status
  • ✅ Add cost fields for tracking
  • ✅ Use appropriate data types

Graph View

  • ✅ Link episodes to topics, people, books
  • ✅ Create episode-to-episode references
  • ✅ Consider hub notes for each podcast

7. Implementation Priority

High Priority (Must Have)

  1. Wikilink generation for entities
  2. Hierarchical tags in frontmatter
  3. Dataview-compatible frontmatter with consistent fields

Medium Priority (Should Have)

  1. Cross-episode references
  2. Custom display text for wikilinks
  3. Topic and concept linking

Low Priority (Nice to Have)

  1. Hub note generation
  2. Advanced graph view optimization
  3. Plugin-specific enhancements

8. References

Next Steps

  1. Design Obsidian integration architecture (see ADR-026)
  2. Implement wikilink extraction system (Phase 5 Unit 3)
  3. Implement tag generation system (Phase 5 Unit 4)
  4. Implement Dataview frontmatter (Phase 5 Unit 5)

Document Version: 1.0 Last Updated: 2025-11-09 Status: Complete