Skip to content

Commit c709725

Browse files
KarolaKirsanowmdroidiandevin-ai-integration[bot]
authored
Added obsidian use cases (#1179)
* scaffolding uses cases - obsidian * adding obsidian content01 * adding obsidian content02 * adding obsidian content03 * fix type errors * typos * figpanel update * Fix website docs CI failures * rm old roam tree * move images * update images * callout * nodetags * . * Update apps/website/content/obsidian/use-cases/track-your-projects-and-experiments.mdx Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com> --------- Co-authored-by: Michael Gartner <mclicks@gmail.com> Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com>
1 parent 7e058c1 commit c709725

84 files changed

Lines changed: 1050 additions & 95 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,8 @@ Flat legacy redirects, such as `/docs/obsidian/<slug>` to `/docs/obsidian/<secti
6161

6262
Use existing Nextra Markdown, MDX, and `nextra/components` features for styling and layout before proposing anything custom. For example, use Nextra callouts, cards, steps, tabs, tables, and file trees when those fit the content.
6363

64+
For discourse candidate tag pills, use the existing global MDX component: `<NodeTag type="clm" />`, `<NodeTag type="evd" />`, or `<NodeTag type="que" />`. Allowed `type` values are `que`, `clm`, `evd`, `src`, `hyp`, `res`, and `iss`. Use a `.mdx` file when a page needs `NodeTag`, and do not add one-off tag styling or CSS.
65+
6466
If the docs need a styling or presentation feature that Nextra does not currently provide, create a separate Linear ticket to add that Nextra functionality. Do not include theme, layout, route, component, or CSS changes in a content-only docs update.
6567

6668
Preferred: Use the `$update-user-docs` skill to update plugin docs. Detailed guidance for plugin docs lives next to the `$update-user-docs` skill:

‎apps/website/app/(nextra)/nextra-css.css‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,14 @@
44
--nextra-content-width: 90rem;
55
}
66

7+
.docs-bordered-image {
8+
display: block;
9+
max-width: 100%;
10+
height: auto;
11+
border: 1px solid rgb(203 213 225);
12+
margin-top: 1.25em;
13+
}
14+
715
.nextra-reset,
816
.nextra-search-results {
917
--nextra-primary-hue: 212deg;

‎apps/website/app/components/docs/NodeTag.tsx‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
import type { CSSProperties, ReactElement, ReactNode } from "react";
2+
3+
const NODE_TAG_COLORS = {
4+
que: "#99890E", // Question
5+
clm: "#7DA13E", // Claim
6+
evd: "#DB134A", // Evidence
7+
src: "#3B82F6", // Source
8+
hyp: "#8CE99A", // Hypothesis
9+
res: "#4DABF7", // Result
10+
iss: "#E599F7", // Issue
11+
} as const;
12+
13+
export type NodeTagType = keyof typeof NODE_TAG_COLORS;
14+
15+
const NODE_TAG_TYPES = Object.keys(NODE_TAG_COLORS) as NodeTagType[];
16+
17+
const isNodeTagType = (type: unknown): type is NodeTagType =>
18+
typeof type === "string" && type in NODE_TAG_COLORS;
19+
20+
const getTextColor = (backgroundColor: string): string => {
21+
const hex = backgroundColor.replace("#", "");
22+
const r = parseInt(hex.slice(0, 2), 16);
23+
const g = parseInt(hex.slice(2, 4), 16);
24+
const b = parseInt(hex.slice(4, 6), 16);
25+
26+
return (0.299 * r + 0.587 * g + 0.114 * b) / 255 > 0.5
27+
? "#000000"
28+
: "#FFFFFF";
29+
};
30+
31+
type NodeTagProps = {
32+
type: NodeTagType;
33+
children?: ReactNode;
34+
};
35+
36+
export const NodeTag = ({ type, children }: NodeTagProps): ReactElement => {
37+
if (!isNodeTagType(type)) {
38+
throw new Error(
39+
`Invalid NodeTag type "${String(type)}". Expected one of: ${NODE_TAG_TYPES.join(", ")}.`,
40+
);
41+
}
42+
43+
const backgroundColor = NODE_TAG_COLORS[type];
44+
45+
const style: CSSProperties = {
46+
backgroundColor,
47+
color: getTextColor(backgroundColor),
48+
padding: "1px 10px",
49+
borderRadius: "999px",
50+
fontSize: "0.85em",
51+
fontWeight: 500,
52+
display: "inline-block",
53+
whiteSpace: "nowrap",
54+
};
55+
56+
return <span style={style}>{children ?? `#${type}-candidate`}</span>;
57+
};

‎apps/website/content/obsidian/use-cases/_meta.ts‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,13 @@
11
import type { MetaRecord } from "nextra";
22

33
const meta: MetaRecord = {
4-
"literature-reviewing": "Literature review",
5-
"research-roadmapping": "Research notes",
6-
"reading-clubs": "Reading clubs and seminars",
7-
"lab-notebooks": "Lab notebooks",
4+
"build-utilize-personal-knowledge-base":
5+
"Build and Utilize a Personal Knowledge Base",
6+
"synthesize-insights-from-literature":
7+
"Synthesize Insights from the Literature",
8+
"share-your-ideas-and-research": "Share your ideas & research",
9+
"track-your-projects-and-experiments": "Track your Projects and Experiments",
10+
"experiment-tracking": "Experiment Tracking",
811
};
912

1013
export default meta;

‎apps/website/content/obsidian/use-cases/build-utilize-personal-knowledge-base.mdx‎

Lines changed: 258 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,258 @@
1+
---
2+
title: "Build and Utilize a Personal Knowledge Base"
3+
date: "2026-06-29"
4+
author: ""
5+
published: true
6+
---
7+
8+
import Image from "next/image";
9+
import { Callout } from "nextra/components";
10+
11+
## Turn your tsundoku pile into a knowledge base with discourse graphs
12+
13+
<Image
14+
src="/docs/obsidian/tsundoku.png"
15+
alt="tsundoku pile"
16+
width={195}
17+
height={302}
18+
className="docs-bordered-image"
19+
/>
20+
21+
_Candidate for saddest short poem_
22+
23+
Many researchers have established pipeline for accumulating potentially useful evidence and insights, but fewer ways of managing and exploiting these resources.
24+
25+
The [discourse graph protocol](/docs/obsidian/fundamentals/what-is-a-discourse-graph) can be used to drive more intentional note taking and to accentuate serendipitous discovery within existing knowledge bases.
26+
27+
## Startup
28+
29+
If you're already using Obsidian or Roam Research or another PKM platform, your first question might be _"Can I integrate discourse graphs into my existing knowledge base?"_
30+
31+
For Obsidian (& Roam), the answer is **yes**. Your discourse nodes can coexist with your existing graph: the two major considerations for a smooth integration are _organizational preferences_ and _vault size_.
32+
33+
### Vault organization
34+
35+
If you are a **"folder-centric"** Obsidian user, we recommend keeping your discourse graph an folder within your vault.
36+
37+
<Image
38+
src="/docs/obsidian/left-sidebar.png"
39+
alt="left sidebar"
40+
width={330}
41+
height={403}
42+
className="docs-bordered-image"
43+
/>
44+
45+
The Discourse Graph plugin lets you configure a default folder (or per-node-type folders) for discourse nodes in its settings, independent of Obsidian's own "Default location for new notes" setting.
46+
47+
So Obsidian's **"Default location for new notes"** setting (in `Settings → Files & Links`) can control where non-discourse notes go while the plugin routes new nodes to its own folder.
48+
49+
```
50+
vault/
51+
├── Discourse Graph/
52+
│ ├── Questions/
53+
│ ├── Claims/
54+
│ └── Evidence/
55+
└── Notes/ ← regular notes land here
56+
```
57+
58+
As you convert more of your existing notes to discourse nodes via the plugin's **"Convert note to discourse node"** command, move these notes to the configured discourse folder.
59+
60+
If you're a **"graph-centric"** vault user, following Obsidian wiki-linking and discourse graph [relation-creating](/docs/obsidian/core-features/creating-discourse-relationships) practices will allow you to navigate a vault of arbitrary size without getting lost in unrelated material.
61+
62+
As you build out your graph, your discourse nodes will begin to form "paths of desire" around the central Questions in your vault.
63+
64+
<Image
65+
src="/docs/obsidian/graph-view02.png"
66+
alt="graph view"
67+
width={971}
68+
height={924}
69+
className="docs-bordered-image"
70+
/>
71+
72+
<Callout type="info" emoji="💡">
73+
**Graph Gardening:** Add a random note picker to your vault to get in the
74+
habit of reviewing older notes for potential conversion to discourse nodes.
75+
</Callout>
76+
77+
### Managing a large vault
78+
79+
"Vanilla" Obsidian accommodates very large vaults with very few issues. Vault size usually only becomes a problem when you're running many script-heavy plugins at once.
80+
If you're an Obsidian power user you may already be using a plugin like [Dataview](https://blacksmithgu.github.io/obsidian-dataview/) to run queries over your vault. The discourse graph plugin uses [Datacore](https://github.com/blacksmithgu/datacore) to power its queries, which is even more performant in large vaults than Dataview. These two plugins can both be used in the same vault, but we recommend keeping an eye on your plugin count to optimize vault load time.
81+
82+
## Transforming existing notes into discourse nodes
83+
84+
You can transform a variety of file types into discourse nodes:
85+
86+
- [readwise](https://readwise.io/) snippets
87+
- [memex](https://memex.garden/) imports
88+
- screenshots
89+
- captures from the [Obsidian web clipper](https://obsidian.md/clipper).
90+
- articles from [Zotero](/docs/obsidian/use-cases/synthesize-insights-from-literature), etc.
91+
92+
As long as it can be referenced (`[filename]`) in a markdown file with the appropriate frontmatter, it can be part of your discourse graph.
93+
94+
<Image
95+
src="/docs/obsidian/clipping01.png"
96+
alt="Obsidian web clipper"
97+
width={853}
98+
height={713}
99+
className="docs-bordered-image"
100+
/>
101+
102+
_This web clipping has been converted into a Source_
103+
104+
<Image
105+
src="/docs/obsidian/img-clm02.png"
106+
alt="image to CLM"
107+
width={773}
108+
height={864}
109+
className="docs-bordered-image"
110+
/>
111+
112+
_This web screenshot has been converted into a Claim_
113+
114+
### Best practices for node conversion
115+
116+
The goal of transforming a **note** into a dg **node** is to preserve as much context and information as possible while orienting the content toward the questions animating your research -- or at least positioning it so that it suggests additional discourse nodes.
117+
118+
First, paraphrase the key insight of the note and record the source of the insight. This paraphrase is your new discourse node/filename. The rest of the note will become a **Source** node where the remaining note text can be retained as additional context for the insight. You might extract several discourse nodes or [candidate nodes](/docs/obsidian/core-features/node-tags) from a single web-clipped article, but breaking it out into a single DG node + SRC is enough to get started.
119+
120+
<Image
121+
src="/docs/obsidian/clm-clip02.png"
122+
alt="claim"
123+
width={744}
124+
height={832}
125+
className="docs-bordered-image"
126+
/>
127+
128+
_CLM node with SRC node attributing a blog_
129+
130+
In the above image, you can see the a second related Claim and its Source has already been extracted from the same web clipping. If you decide to pursue this topic further, you've already identified another Source node to investigate (Klein _et al._)
131+
132+
Adding `[[wiki-links]]` to key terms will keep your new node in conversation with the rest of your vault as you build your graph. This can help you to find appropriate [discourse relations](/docs/obsidian/core-features/creating-discourse-relationships) later.
133+
134+
<Image
135+
src="/docs/obsidian/src-node-clip.png"
136+
alt="source"
137+
width={517}
138+
height={759}
139+
className="docs-bordered-image"
140+
/>
141+
142+
_This SRC node from a web clipping is linked to the rest of the vault_
143+
144+
As you go through your vault, you might find that certain sources are accumulating multiple mentions in your graph. Identifying especially productive sources can help you to decide how to allocate your attention.
145+
146+
Of course you may be the author of many of the original notes in your vault -- in that case, we suggest retaining the relevant contextual information on the QUE/CLM/EVD node itself -- but remember to create a Source node for yourself!
147+
148+
<Image
149+
src="/docs/obsidian/drmanhattan.png"
150+
alt="self-cite"
151+
width={640}
152+
height={801}
153+
className="docs-bordered-image"
154+
sizes="350px"
155+
style={{ width: 350 }}
156+
/>
157+
158+
### Progressive formalization
159+
160+
The goal is to gradually convert most of your existing notes into a graph of interlinked CLM, QUE, or EVD nodes.
161+
162+
You can jumpstart the process by identifying [candidate nodes](/docs/obsidian/core-features/node-tags) in your existing notes, and revisiting these notes to decide which nodes should be promoted to full-fledged discourse nodes. The trigger for such a promotion is identifying their relevance to one of your research questions, or finding a potential [discourse relation](/docs/obsidian/core-features/creating-discourse-relationships) elsewhere in your graph.
163+
164+
<Image
165+
src="/docs/obsidian/graph-view01.png"
166+
alt="the graph"
167+
width={786}
168+
height={795}
169+
className="docs-bordered-image"
170+
/>
171+
172+
_So much room for activities!_
173+
174+
## Creating new discourse nodes
175+
176+
Build out your discourse graph by reading with an eye to capturing information relevant to your current questions or that inspires new questions.
177+
178+
<Image
179+
src="/docs/obsidian/new-node01.png"
180+
alt="web clipping"
181+
width={498}
182+
height={668}
183+
className="docs-bordered-image"
184+
/>
185+
186+
_Here's a [web clipping](https://obsidian.md/clipper) captured with an eye to turning it into a CLM node - the Obsidian web clipper helpfully captures the source in the frontmatter_
187+
188+
<Image
189+
src="/docs/obsidian/new-node02.png"
190+
alt="claim node"
191+
width={544}
192+
height={772}
193+
className="docs-bordered-image"
194+
/>
195+
196+
_... and here's the CLM node. Note that it's linked to 3 sources: one named after the article url where the full text is captured, one to the author, & one to the author's institution -- this reflects the organizational preferences of the vault owner; a single SRC node can contain all this information_
197+
198+
This habit of intentional reading is a great way to nudge yourself toward [contributing to the public conversation](/docs/obsidian/use-cases/share-your-ideas-and-research).
199+
200+
<Image
201+
src="/docs/obsidian/cat-meme.png"
202+
alt="you should start a blog"
203+
width={454}
204+
height={327}
205+
className="docs-bordered-image"
206+
/>
207+
208+
If you're using a highlighter like [memex](memex.garden) or the [Obsidian web clipper](https://obsidian.md/clipper), you can
209+
210+
1. highlight the relevant text
211+
2. bring it into your vault via the tool's import feature or copy-paste
212+
3. Select `Convert into` from the file window menu to turn it into a discourse node
213+
214+
<Image
215+
src="/docs/obsidian/convert-menu.png"
216+
alt="convert menu"
217+
width={1016}
218+
height={843}
219+
className="docs-bordered-image"
220+
/>
221+
222+
<Image
223+
src="/docs/obsidian/memex-res.png"
224+
alt="memex highlight"
225+
width={771}
226+
height={413}
227+
className="docs-bordered-image"
228+
/>
229+
230+
_Result node spotted in the wild_
231+
232+
Similarly, plugins like [Zotsidian](https://github.com/Qiwei-Zhao/zotsidian) enable you to import items from your reference manager pre-formatted as Sources.
233+
234+
<Image
235+
src="/docs/obsidian/zot-import.png"
236+
alt="readymade Source"
237+
width={776}
238+
height={889}
239+
className="docs-bordered-image"
240+
/>
241+
242+
After you've captured capture a few ideas, you can mark those that you might want to add to your graph later as [candidate nodes](/docs/obsidian/core-features/node-tags). The _progressive formalization_ ethos of the discourse graph protocol also applies to the process of deciding how to direct your attention: you can have a number of leads on potential projects active at once, and decide which ones to curate further later.
243+
244+
<Image
245+
src="/docs/obsidian/bullet-journal.png"
246+
alt="bullet journal"
247+
width={763}
248+
height={384}
249+
className="docs-bordered-image"
250+
/>
251+
252+
_Bullet Journal with candidate nodes in a [Daily Notes](https://obsidian.md/help/plugins/daily-notes) page_
253+
254+
## What else would you like to do?
255+
256+
- [Synthesize Insights from the Literature](/docs/obsidian/use-cases/synthesize-insights-from-literature)
257+
- [Track your Projects and Experiments](/docs/obsidian/use-cases/track-your-projects-and-experiments)
258+
- [Share your ideas & research](/docs/obsidian/use-cases/share-your-ideas-and-research)

0 commit comments

Comments
 (0)