diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e297abeda..3e077b51c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -61,6 +61,8 @@ Flat legacy redirects, such as `/docs/obsidian/` to `/docs/obsidian/`, ``, or ``. 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. + 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. Preferred: Use the `$update-user-docs` skill to update plugin docs. Detailed guidance for plugin docs lives next to the `$update-user-docs` skill: diff --git a/apps/website/app/(nextra)/nextra-css.css b/apps/website/app/(nextra)/nextra-css.css index 330c3dcd3..bb4cdaa4f 100644 --- a/apps/website/app/(nextra)/nextra-css.css +++ b/apps/website/app/(nextra)/nextra-css.css @@ -4,6 +4,14 @@ --nextra-content-width: 90rem; } +.docs-bordered-image { + display: block; + max-width: 100%; + height: auto; + border: 1px solid rgb(203 213 225); + margin-top: 1.25em; +} + .nextra-reset, .nextra-search-results { --nextra-primary-hue: 212deg; diff --git a/apps/website/app/components/docs/NodeTag.tsx b/apps/website/app/components/docs/NodeTag.tsx new file mode 100644 index 000000000..18a69397b --- /dev/null +++ b/apps/website/app/components/docs/NodeTag.tsx @@ -0,0 +1,57 @@ +import type { CSSProperties, ReactElement, ReactNode } from "react"; + +const NODE_TAG_COLORS = { + que: "#99890E", // Question + clm: "#7DA13E", // Claim + evd: "#DB134A", // Evidence + src: "#3B82F6", // Source + hyp: "#8CE99A", // Hypothesis + res: "#4DABF7", // Result + iss: "#E599F7", // Issue +} as const; + +export type NodeTagType = keyof typeof NODE_TAG_COLORS; + +const NODE_TAG_TYPES = Object.keys(NODE_TAG_COLORS) as NodeTagType[]; + +const isNodeTagType = (type: unknown): type is NodeTagType => + typeof type === "string" && type in NODE_TAG_COLORS; + +const getTextColor = (backgroundColor: string): string => { + const hex = backgroundColor.replace("#", ""); + const r = parseInt(hex.slice(0, 2), 16); + const g = parseInt(hex.slice(2, 4), 16); + const b = parseInt(hex.slice(4, 6), 16); + + return (0.299 * r + 0.587 * g + 0.114 * b) / 255 > 0.5 + ? "#000000" + : "#FFFFFF"; +}; + +type NodeTagProps = { + type: NodeTagType; + children?: ReactNode; +}; + +export const NodeTag = ({ type, children }: NodeTagProps): ReactElement => { + if (!isNodeTagType(type)) { + throw new Error( + `Invalid NodeTag type "${String(type)}". Expected one of: ${NODE_TAG_TYPES.join(", ")}.`, + ); + } + + const backgroundColor = NODE_TAG_COLORS[type]; + + const style: CSSProperties = { + backgroundColor, + color: getTextColor(backgroundColor), + padding: "1px 10px", + borderRadius: "999px", + fontSize: "0.85em", + fontWeight: 500, + display: "inline-block", + whiteSpace: "nowrap", + }; + + return {children ?? `#${type}-candidate`}; +}; diff --git a/apps/website/content/obsidian/use-cases/_meta.ts b/apps/website/content/obsidian/use-cases/_meta.ts index c193a603e..a05edbcf1 100644 --- a/apps/website/content/obsidian/use-cases/_meta.ts +++ b/apps/website/content/obsidian/use-cases/_meta.ts @@ -1,10 +1,13 @@ import type { MetaRecord } from "nextra"; const meta: MetaRecord = { - "literature-reviewing": "Literature review", - "research-roadmapping": "Research notes", - "reading-clubs": "Reading clubs and seminars", - "lab-notebooks": "Lab notebooks", + "build-utilize-personal-knowledge-base": + "Build and Utilize a Personal Knowledge Base", + "synthesize-insights-from-literature": + "Synthesize Insights from the Literature", + "share-your-ideas-and-research": "Share your ideas & research", + "track-your-projects-and-experiments": "Track your Projects and Experiments", + "experiment-tracking": "Experiment Tracking", }; export default meta; diff --git a/apps/website/content/obsidian/use-cases/build-utilize-personal-knowledge-base.mdx b/apps/website/content/obsidian/use-cases/build-utilize-personal-knowledge-base.mdx new file mode 100644 index 000000000..57d1a0a20 --- /dev/null +++ b/apps/website/content/obsidian/use-cases/build-utilize-personal-knowledge-base.mdx @@ -0,0 +1,258 @@ +--- +title: "Build and Utilize a Personal Knowledge Base" +date: "2026-06-29" +author: "" +published: true +--- + +import Image from "next/image"; +import { Callout } from "nextra/components"; + +## Turn your tsundoku pile into a knowledge base with discourse graphs + +tsundoku pile + +_Candidate for saddest short poem_ + +Many researchers have established pipeline for accumulating potentially useful evidence and insights, but fewer ways of managing and exploiting these resources. + +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. + +## Startup + +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?"_ + +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_. + +### Vault organization + +If you are a **"folder-centric"** Obsidian user, we recommend keeping your discourse graph an folder within your vault. + +left sidebar + +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. + +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. + +``` +vault/ +├── Discourse Graph/ +│ ├── Questions/ +│ ├── Claims/ +│ └── Evidence/ +└── Notes/ ← regular notes land here +``` + +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. + +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. + +As you build out your graph, your discourse nodes will begin to form "paths of desire" around the central Questions in your vault. + +graph view + + + **Graph Gardening:** Add a random note picker to your vault to get in the + habit of reviewing older notes for potential conversion to discourse nodes. + + +### Managing a large vault + +"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. +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. + +## Transforming existing notes into discourse nodes + +You can transform a variety of file types into discourse nodes: + +- [readwise](https://readwise.io/) snippets +- [memex](https://memex.garden/) imports +- screenshots +- captures from the [Obsidian web clipper](https://obsidian.md/clipper). +- articles from [Zotero](/docs/obsidian/use-cases/synthesize-insights-from-literature), etc. + +As long as it can be referenced (`[filename]`) in a markdown file with the appropriate frontmatter, it can be part of your discourse graph. + +Obsidian web clipper + +_This web clipping has been converted into a Source_ + +image to CLM + +_This web screenshot has been converted into a Claim_ + +### Best practices for node conversion + +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. + +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. + +claim + +_CLM node with SRC node attributing a blog_ + +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._) + +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. + +source + +_This SRC node from a web clipping is linked to the rest of the vault_ + +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. + +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! + +self-cite + +### Progressive formalization + +The goal is to gradually convert most of your existing notes into a graph of interlinked CLM, QUE, or EVD nodes. + +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. + +the graph + +_So much room for activities!_ + +## Creating new discourse nodes + +Build out your discourse graph by reading with an eye to capturing information relevant to your current questions or that inspires new questions. + +web clipping + +_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_ + +claim node + +_... 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_ + +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). + +you should start a blog + +If you're using a highlighter like [memex](memex.garden) or the [Obsidian web clipper](https://obsidian.md/clipper), you can + +1. highlight the relevant text +2. bring it into your vault via the tool's import feature or copy-paste +3. Select `Convert into` from the file window menu to turn it into a discourse node + +convert menu + +memex highlight + +_Result node spotted in the wild_ + +Similarly, plugins like [Zotsidian](https://github.com/Qiwei-Zhao/zotsidian) enable you to import items from your reference manager pre-formatted as Sources. + +readymade Source + +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. + +bullet journal + +_Bullet Journal with candidate nodes in a [Daily Notes](https://obsidian.md/help/plugins/daily-notes) page_ + +## What else would you like to do? + +- [Synthesize Insights from the Literature](/docs/obsidian/use-cases/synthesize-insights-from-literature) +- [Track your Projects and Experiments](/docs/obsidian/use-cases/track-your-projects-and-experiments) +- [Share your ideas & research](/docs/obsidian/use-cases/share-your-ideas-and-research) diff --git a/apps/website/content/obsidian/use-cases/experiment-tracking.mdx b/apps/website/content/obsidian/use-cases/experiment-tracking.mdx new file mode 100644 index 000000000..a99c28c4e --- /dev/null +++ b/apps/website/content/obsidian/use-cases/experiment-tracking.mdx @@ -0,0 +1,83 @@ +--- +title: "Experiment Tracking" +date: "2026-06-29" +author: "" +published: true +--- + +import Image from "next/image"; + +# How to use Experiments + +The **Experiment** is a container for your day-to-day work exploring a **Hypothesis.** It consists of an **intervention** and a **metric** used to track the result of that intervention. The **Result** is a statement of your observations regarding that intervention in terms of the appropriate metric. + +Making an experiment page helps you track multiple days' work and reflect on your progress towards your experiment target. +Ideally the target is a **Hypothesis** you are testing, and the experiment page is a space to document and reflect on **candidate results** for that hypothesis. + +### A quick word on candidate nodes + +**Candidate Results** are preliminary observations attached to a particular experiment. They might be first impressions formed from a certain data artefact. Use this tag to mark candidate results: #res-candidate + +**Candidate Issues** surface potential problems or future experiments. Use this tag to mark candidate issues: #iss-candidate + +When you're more confident in the observation, you can use the "Create Discourse Node" popup to convert the candidate result into a proper Result. This will affect where the Result appears in queries and its appearance on your Project Canvas. It will also give you a warm sense of accomplishment (this can be done to mature all candidate node types). + +## Creating experiments + +You can create a new experiment by + +1. Creating a new note and applying the Experiment Template from the Templater menu in the left sidebar + +templater flow + +2. Navigating to your "Experiments" base in the "Bases" folder and selecting "+ New" + +bases flow + +3. Using any of the methods to create nodes (Remember, an Experiment is a type of **Source**) + +## Experiment relations + +As a **Source** node, the **Experiment** has a special relationship to **Result** nodes: the **Experiment** _produces_ **Results**. + +Conversely, each Result in your graph should reference an Experiment. + +The Experiment also has a relationship with the **Issue** node, as Experiments _suggest/produce_ **Issues** that may later be developed into Experiments. + +iss-exp relations + +## Transforming an Issue into an Experiment + +If you decide an Issue captures something worth doing, you can easily change it into an Experiment: the **Issue** template is identical to the **Experiment** template, so you can either duplicate the node and change the name and metadata to use your preferred EXP syntax (e.g. "@measurement -") or simply edit the title of the Issue in place. + +issue example + +## What else would you like to do? + +- [Synthesize Insights from the Literature](/docs/obsidian/use-cases/synthesize-insights-from-literature) +- [Build and Utilize a Personal Knowledge Base](/docs/obsidian/use-cases/build-utilize-personal-knowledge-base) +- [Share your ideas & research](/docs/obsidian/use-cases/share-your-ideas-and-research) diff --git a/apps/website/content/obsidian/use-cases/literature-reviewing.md b/apps/website/content/obsidian/use-cases/literature-reviewing.md deleted file mode 100644 index 3aded41b9..000000000 --- a/apps/website/content/obsidian/use-cases/literature-reviewing.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Literature reviewing" -date: "2025-01-01" -author: "" -published: true ---- - -This is currently the most common use case. - -Lukas Kawerau (aka Cortex Futura) has a course that integrates the extension into a complete system for academic literature reviewing and writing: [https://learn.cortexfutura.com/p/cite-to-write-v2](https://learn.cortexfutura.com/p/cite-to-write-v2) - -Lukas gives a short overview of how in this tweet thread: - -[https://x.com/cortexfutura/status/1441795897680011276](https://x.com/cortexfutura/status/1441795897680011276) diff --git a/apps/website/content/obsidian/use-cases/reading-clubs.md b/apps/website/content/obsidian/use-cases/reading-clubs.md deleted file mode 100644 index 51c94d6e5..000000000 --- a/apps/website/content/obsidian/use-cases/reading-clubs.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Reading clubs" -date: "2025-01-01" -author: "" -published: true ---- - -Description coming soon! - -[Get in touch](mailto:joechan@umd.edu) if you're interested in joining a Reading Club! diff --git a/apps/website/content/obsidian/use-cases/research-roadmapping.md b/apps/website/content/obsidian/use-cases/research-roadmapping.md deleted file mode 100644 index 01d12fc3d..000000000 --- a/apps/website/content/obsidian/use-cases/research-roadmapping.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "Research roadmapping" -date: "2025-01-01" -author: "" -published: true ---- - -Description coming soon! diff --git a/apps/website/content/obsidian/use-cases/share-your-ideas-and-research.mdx b/apps/website/content/obsidian/use-cases/share-your-ideas-and-research.mdx new file mode 100644 index 000000000..ab49111f9 --- /dev/null +++ b/apps/website/content/obsidian/use-cases/share-your-ideas-and-research.mdx @@ -0,0 +1,193 @@ +--- +title: "Share your ideas & research" +date: "2026-06-29" +author: "" +published: true +--- + +import Image from "next/image"; +import { Callout } from "nextra/components"; + +You've built your graph, it's a work of beauty and insight -- now you're ready to share what you've learned. + +sharing your graph + +_Getting eyes on the prize_ + +- [Share individual nodes](#sharing-your-discourse-nodes) +- [Share your canvas](#sharing-your-discourse-canvas) +- [Use your graph as a springboard for drafting a manuscript](#drafting-a-manuscript-from-your-discourse-graph) + +## Sharing your discourse nodes + +We've just added a feature to allow you to share "live" nodes with your collaborators by publishing them to a shared group space: The **sync and import** feature, currently hidden behind an admin panel. + + + +_Opening the admin panel_ + + + For further information on the sync mode feature, visit [the website + docs](/docs/obsidian/advanced-features/sync-and-import). To request access, + please email discoursegraphs@gmail.com + + +## Sharing your discourse canvas + +### Presenting your Canvas + +Your [canvas](/docs/obsidian/core-features/canvas) can be used to give a PowerPoint- or Figma-like visual overview of your work. + +You can start at your motivating Question and move through your hypothesis to your experiments and their results, opening each node in the sidebar to show your audience relevant details. + +canvas walkthrough + +_Example Canvas walkthrough_ + +You can create a "presentation view" for your discourse nodes by adding the material/images you wish to highlight at the top of the page -- the first image on the page is automatically selected as the image that displays on the discourse canvas. + + + You can [modify your discourse + templates](/docs/obsidian/configuration/node-types-templates) to customize + your presentation view. + + +### Exporting your Canvas + +You can export a static .png or .svg image of your discourse canvas from the menu. + +export a png or svg + +_Canvas export menu_ + + + It is not possible at present to export a "live" discourse canvas to another + graph. + + +## Drafting a manuscript from your discourse graph + +### Using the canvas as a storyboard + +You can use the discourse canvas to organize your ideas for a paper. Your canvas allows you to follow your train of thought from hypothesis formation to hypothesis testing -- including the dead ends. You can see at a glance which sources (references) were crucial to the formulation of certain claims, and which informed the design of your experiments. + +If you are targeting a particular journal, you might find it helpful to spatially arrange your discourse nodes according to their ms submission format. This can give you a head start on the drafting stage. + + + +_Using canvas layers to organize article sections_ + +The Canvas layout can also be used to spot "gaps" in your argument at a glance, before Reviewer #2 rushes in to fill them with part of their œuvre. + + + +_Spotting unsupported Claims before Reviewer # 2_ + +The Canvas is also useful for designing figure panels -- particularly for deciding which figures should be composed into figure panels, and which visual evidence is crucial enough to highlight in the main body of the text vs. the supplementary information. + +figure design + +_Experimental setup in one panel for greatest impact ..._ + +figure design + +_While the data speaks for itself_ + +### Arguing with your graph + +Your discourse nodes should be formulated as concisely as possible (remember node = filename). But the rest of the page can be used to construct and elaborate your broader point. The example below links both **Evidence** and **Caveats** related to a **Claim**. In this discourse context, a _Caveat_ is an observation that weakens the claim without necessarily opposing it. Some caveats may be promoted to Evidence that _opposes_ a Claim after further investigation, others may become **Issues**: requests for additional analyses to clarify a point. Anticipating the most salient caveats to each of your claims is a useful preparation for the review stage of your ms submission. + + + +_An example of a claim with caveats_ + +You can [modify your discourse graph templates](/docs/obsidian/configuration/node-types-templates) to structure key information in a way that facilitates article writing later. + + + +_An example of an Evidence node with methods context_ + +Discourse nodes are modular and composable and can be re-used in multiple projects. One strategy to maximize composability is to capture "evergreen" information in the node template and add additional project-specific context in the "log" section. + + + +_In the [Obsidian example vault](https://github.com/DiscourseGraphs/obsidian-lab-example) CLM, HYP, ISS, EXP, & QUE node templates have a "log" section_ + +## Exporting your graph + +Your discourse nodes are markdown notes, and they can be copied, printed, & exported in different formats. + +While the **Discourse Node Sync** feature mentioned above is the only fully-supported way of sharing functional discourse nodes, you can get a quick-and-dirty approximation using copy/paste. Importing a "foreign" discourse node into your graph strips it of its relation data, but it can still be recognized as a discourse node if its NodeTypeId exists in your graph. Open the 3-dot menu in the file pane: if the option "Convert Into" exists, it is not recognized as a node, and you can select the type of node you'd like to turn it into. + +## What else would you like to do? + +- [Build and Utilize a Personal Knowledge Base](/docs/obsidian/use-cases/build-utilize-personal-knowledge-base) +- [Synthesize Insights from the Literature](/docs/obsidian/use-cases/synthesize-insights-from-literature) +- [Track your Projects and Experiments](/docs/obsidian/use-cases/track-your-projects-and-experiments) diff --git a/apps/website/content/obsidian/use-cases/synthesize-insights-from-literature.mdx b/apps/website/content/obsidian/use-cases/synthesize-insights-from-literature.mdx new file mode 100644 index 000000000..13c5b4b2a --- /dev/null +++ b/apps/website/content/obsidian/use-cases/synthesize-insights-from-literature.mdx @@ -0,0 +1,283 @@ +--- +title: "Synthesize Insights from the Literature" +date: "2026-06-29" +author: "" +published: true +--- + +import Image from "next/image"; +import { Callout } from "nextra/components"; + + + This guide makes reference to templates available in an example vault that you + can find [here](https://github.com/DiscourseGraphs/obsidian-lab-example) + + +## Literature Synthesis with discourse graphs + +Discourse graphs turn literature synthesis into a **question-directed activity**: instead of merely absorbing disconnected insights from different sources, the discourse graph workflow orients your reading around a central guiding question of your own devising. + +- + This purpose-driven reading increases engagement with the text and retention + of salient data. +- + It also incentivizes reading widely and strategically, as papers from many + different authors/fields may have made small but significant contributions to + your question. + +There's a bit of a chicken-and-egg problem here, as engaging in question-driven analysis of the literature first requires the development of a question, which usually involves at least some loosely-directed exploration. Discourse graphs accommodate both phases of the explore/exploit curve. + +explore/exploit curve + +## Building your library of sources + +Let's assume that your exploration phase is influenced by the items in your reference manager/personal library. Obsidian offers a variety of plugins for interacting with reference management software. + +ref manager + +The [example vault](https://github.com/DiscourseGraphs/obsidian-lab-example) uses [Zotsidian](https://github.com/Qiwei-Zhao/zotsidian), a Zotero integration plugin with built-in discourse graph support. 🥰 + + + **If you like your reference manager, you can keep your reference manager** -- + they all play well with discourse graphs + + a note from a former president + + +### Managing literature sources with Zotsidian + +- Make sure you have Zotero Desktop ≥ 8 installed and running + - In Zotero, go to `Settings / Preferences -> Advanced` and make sure `Allow other applications on this computer to communicate with Zotero` is enabled. +- Make sure you have citekeys for the Zotero items you want to work with + - Install the Better BibTeX (BBT) plugin from https://retorque.re/zotero-better-bibtex/ to automatically generate citekeys +- [Install Zotsidian](https://github.com/Qiwei-Zhao/zotsidian#install-from-github-release) and enable the plugin +- check your plugin settings: + +settings + +These settings control: + +- how to format citations (use `[[double brackets]]` if you want sources to be wiki- linked immediately ) +- where to store newly-created source nodes +- which template to use +- whether to show a hover-over infobox when a citation is imported + +hover card + + + The hovercard is useful when you're creating a lot of Source pages at once but + can interfere with other mouse-over operations. + + +In the example vault the hotkey `Ctrl-Shift-Y` opens a search panel that you can use to search for references in your Zotero library. + +zotsidian search + +You can also search inline by typing "@..." which will autocomplete with your zotero references after 2 letters. + +inline search + +## Using Obsidian Bases to organize your reading + +You can also navigate and manage your Sources via Obsidian's built-in **Base** feature. This vault contains an example `Sources.base` where you can organize your Sources by citekey, tags, reading status, target Question, or any other frontmatter property. + +Sources Base + +## Synthesis workflows + +starting out + +At the outset of the _exploration_ phase, you probably have a topic in mind, or an assertion vaguely in the shape of a question/hypothesis that needs further refinement. You may be reading the literature to understand prior art on the topic. At this point, before a Question or Project has coalesced, some users like to take notes on their **Daily Notes Page**, in the **Media Log**: + +a question + + + **As long as you use wikilink syntax** + +(`[[mertonMatthewEffectScience1968]]`) the notes you make here will be +referenced at the bottom of the appropriate Source page so that you can find +them later. + + alt text + + +The **Media Log** provides a low-overhead way of taking quick notes that can later be converted to structured note-taking. + +Reflecting on your reading might inspire you to develop a few candidate questions of your own: + +que-candidate + +After further reading, you're ready to formalize one of these candidates as the Question driving your literature review: + +formalize q + +Now you can read and revisit articles in light of your guiding question, and search for **Claims** _addressing_ the **Question** and **Evidence** _supporting_ those **Claims**. + +new question + +### EVD and CLM mining + +As you read the literature, capture claims and evidence relevant to your Question. You can track them on the Question page itself, on the relevant Source page, or anywhere else in your graph -- as long as you tag relevant items with `QUE - {your question}`, these mentions will be linked at the bottom of your Question page. + +media log + +linked mentions + +## Integrating findings from the literature with your research + +The [Discourse Canvas](/docs/obsidian/core-features/canvas) can be used to assemble your claims and evidence into an overview of the state of the field in relation to your target question. + +lit review + +As you collect and assimilate claims and evidence sourced directly from the literature, you will probably develop a few claims of your own that derive from your reading but aren't directly stated in any of the articles. This is your **Synthesis Claim**: an initial position on the question that you'd like to test further. + +lit review + +This synthesis claim can be used as a springboard for more directed reading and the development of an experiment, simulation, or other test. + +Once you've metabolized the claim to find testable components, you can add those components to your graph as **Hypotheses** and begin developing **Experiments**. + +The multiple layers of the tldraw discourse canvas facilitate organizing your research campaign into _literature review_ and _project planning phases_. + +lit synthesis + +In the discourse graph workflow, these phases are largely simultaneous and mutually informative. + +moving along the curve + + + We're developing an LLM-assisted workflow for extracting claims & evidence + from the literature. Join us on + [Slack](https://join.slack.com/t/discoursegraphs/shared_invite/zt-37xklatti-cpEjgPQC0YyKYQWPNgAkEg) + to learn more. + + +## What else would you like to do? + +- [Build and Utilize a Personal Knowledge Base](/docs/obsidian/use-cases/build-utilize-personal-knowledge-base) +- [Track your Projects and Experiments](/docs/obsidian/use-cases/track-your-projects-and-experiments) +- [Share your ideas & research](/docs/obsidian/use-cases/share-your-ideas-and-research) diff --git a/apps/website/content/obsidian/use-cases/track-your-projects-and-experiments.mdx b/apps/website/content/obsidian/use-cases/track-your-projects-and-experiments.mdx new file mode 100644 index 000000000..b7b433e7a --- /dev/null +++ b/apps/website/content/obsidian/use-cases/track-your-projects-and-experiments.mdx @@ -0,0 +1,104 @@ +--- +title: "Track your Projects and Experiments" +date: "2026-06-29" +author: "" +published: true +--- + +import Image from "next/image"; +import { Callout } from "nextra/components"; + + + This guide makes reference to templates available in an example vault that you + can find [here](https://github.com/DiscourseGraphs/obsidian-lab-example) + + +## How to use Projects + +The **Project** acts as a container for multiple activities exploring a particular research question. You can think of it as a conceptual framework to structure a set of Discourse nodes related to a certain research goal. + +Use Project pages to + +- Prioritize experiments +- Stay oriented toward and reflect on your progress toward your project target/question +- Keep relevant resources at hand (links, etc) + +The Project structure facilitates the creation of a traditional research narrative and aids in keeping track of all the moving parts that go into a scientific ms. + +### Examples + +The [discourse graph example vault](https://github.com/DiscourseGraphs/obsidian-lab-example) contains an example project page, `PRJ - Passarine Songbird Cargo Capacity`, that demonstrates a project structure appropriate to experimental research. + +Project Page + +- The **Resources** section can be used to organize protocols, references, datasets, reagent lists, etc. It's also a convenient spot to pre-register your working **Hypothesis** + +- The **Create Discourse Graph Canvas** button will automatically spin up a discourse canvas named after the project for visual organization of your ideas. + +- The **Experiments, Issues, & Results** Bases can be used to keep track of multiple active experiments and filter by status, observations made from those experiments (Results), and ideas for future experiments (Issues). + +- The **ToDo** list collects tasks tagged `PRJ - Passarine Songbird Cargo Capacity` + +- The **Project Log** can be used to keep track of project updates and link project-relevant information from other parts of your graph. Like your **Daily Notes Page**, it has a button function for regular entries. + +- the **Project Meeting Notes** log will collect references to this project made in meeting notes throughout this graph. + +## How to Create a Project + +Create a new project by + +1. Creating a new note in the "Projects" Folder and applying the Project Template from the Templater menu in the left sidebar + +templater flow + +2. Navigating to your "Projects" base in the "Bases" folder and selecting "+ New" + +bases flow + +## The relationship between your Projects and your Discourse Graph + +In the example vault, the **Project** is not treated as a discourse node but rather an organizational background for other nodes. You can see how this works in the `Canvas - PRJ - Passarine Songbird Cargo Capacity`: the Project contains 3 **Questions:** + +- the original motivating question: `QUE - Can a 5 ounce bird carry a one-pound coconut?` +- a question that arose during the course of the initial investigation: `QUE - what is the airspeed velocity of an unladen swallow?` +- and a sub-question informing that second question: `QUE - African or European?` + +These three Questions are all part of the same work package, and while their respective edges may eventually meet, we're not going to force it. + +## The relationship between your Projects and your Experiments + +The Project is also the natural container for the **Experiment** node, which is a flavor of the **Source** node for laboratory work. Your Project will probably contain several experiments -- you can see from the `Experiments.base` that each Experiment is associated with a Project via its frontmatter for easier queryability. + +Project-as-container + +Learn more about creating and tracking experiments [here](/docs/obsidian/use-cases/experiment-tracking). + +## What else would you like to do? + +- [Build and Utilize a Personal Knowledge Base](/docs/obsidian/use-cases/build-utilize-personal-knowledge-base) +- [Synthesize Insights from the Literature](/docs/obsidian/use-cases/synthesize-insights-from-literature) +- [Share your ideas & research](/docs/obsidian/use-cases/share-your-ideas-and-research) diff --git a/apps/website/content/obsidian/welcome/getting-started.md b/apps/website/content/obsidian/welcome/getting-started.md index 92dcb437a..8b10b5663 100644 --- a/apps/website/content/obsidian/welcome/getting-started.md +++ b/apps/website/content/obsidian/welcome/getting-started.md @@ -20,7 +20,7 @@ For more information about Discourse Graphs, check out our website at [https://d ## What's Next? - Learn about [what makes a discourse graph](/docs/obsidian/fundamentals/what-is-a-discourse-graph) -- Explore [use cases](/docs/obsidian/use-cases/literature-reviewing) for discourse graphs +- Explore [use cases](/docs/obsidian/use-cases/synthesize-insights-from-literature) for discourse graphs - Join our community to share your experience and get help ## Guides: Jump right in diff --git a/apps/website/content/roam/guides/_meta.ts b/apps/website/content/roam/guides/_meta.ts index 071fab45c..05c102fae 100644 --- a/apps/website/content/roam/guides/_meta.ts +++ b/apps/website/content/roam/guides/_meta.ts @@ -9,6 +9,7 @@ const meta: MetaRecord = { "querying-discourse-graph": "Querying", "extending-personalizing-graph": "Extending", "sharing-discourse-graph": "Sharing", + "experiment-tracking": "Experiment tracking", }; export default meta; diff --git a/apps/website/content/obsidian/use-cases/lab-notebooks.md b/apps/website/content/roam/guides/experiment-tracking.md similarity index 55% rename from apps/website/content/obsidian/use-cases/lab-notebooks.md rename to apps/website/content/roam/guides/experiment-tracking.md index 9bdfa548c..436b9e8d7 100644 --- a/apps/website/content/obsidian/use-cases/lab-notebooks.md +++ b/apps/website/content/roam/guides/experiment-tracking.md @@ -1,6 +1,6 @@ --- -title: "Lab notebooks" -date: "2025-01-01" +title: "Experiment Tracking" +date: "2026-06-29" author: "" published: true --- diff --git a/apps/website/content/roam/use-cases/_meta.ts b/apps/website/content/roam/use-cases/_meta.ts index 18e66e72c..3d232508d 100644 --- a/apps/website/content/roam/use-cases/_meta.ts +++ b/apps/website/content/roam/use-cases/_meta.ts @@ -1,11 +1,12 @@ import type { MetaRecord } from "nextra"; const meta: MetaRecord = { - "literature-reviewing": "Literature reviewing", - "enhanced-zettelkasten": "Zettelkasten", - "reading-clubs": "Reading clubs and seminars", - "lab-notebooks": "Lab notebooks", - "research-roadmapping": "Product and research roadmapping", + "build-utilize-personal-knowledge-base": + "Build and Utilize a Personal Knowledge Base", + "synthesize-insights-from-literature": + "Synthesize Insights from the Literature", + "share-your-ideas-and-research": "Share your ideas & research", + "track-your-projects-and-experiments": "Track your Projects and Experiments", }; export default meta; diff --git a/apps/website/content/roam/use-cases/build-utilize-personal-knowledge-base.md b/apps/website/content/roam/use-cases/build-utilize-personal-knowledge-base.md new file mode 100644 index 000000000..f6ded4019 --- /dev/null +++ b/apps/website/content/roam/use-cases/build-utilize-personal-knowledge-base.md @@ -0,0 +1,8 @@ +--- +title: "Build and Utilize a Personal Knowledge Base" +date: "2026-06-29" +author: "" +published: true +--- + +Description coming soon! diff --git a/apps/website/content/roam/use-cases/enhanced-zettelkasten.md b/apps/website/content/roam/use-cases/enhanced-zettelkasten.md deleted file mode 100644 index 36ba3e2c9..000000000 --- a/apps/website/content/roam/use-cases/enhanced-zettelkasten.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Enhanced Zettelkasten" -date: "2025-01-01" -author: "" -published: true ---- - -Maarten Van Doorn has integrated the discourse graph into his take on applying the zettelkasten to his research. - -Here is a video overview: - -[https://www.youtube.com/watch?v=mNzUAICf4Rk](https://www.youtube.com/watch?v=mNzUAICf4Rk) diff --git a/apps/website/content/roam/use-cases/literature-reviewing.md b/apps/website/content/roam/use-cases/literature-reviewing.md deleted file mode 100644 index 3aded41b9..000000000 --- a/apps/website/content/roam/use-cases/literature-reviewing.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Literature reviewing" -date: "2025-01-01" -author: "" -published: true ---- - -This is currently the most common use case. - -Lukas Kawerau (aka Cortex Futura) has a course that integrates the extension into a complete system for academic literature reviewing and writing: [https://learn.cortexfutura.com/p/cite-to-write-v2](https://learn.cortexfutura.com/p/cite-to-write-v2) - -Lukas gives a short overview of how in this tweet thread: - -[https://x.com/cortexfutura/status/1441795897680011276](https://x.com/cortexfutura/status/1441795897680011276) diff --git a/apps/website/content/roam/use-cases/reading-clubs.md b/apps/website/content/roam/use-cases/reading-clubs.md deleted file mode 100644 index 51c94d6e5..000000000 --- a/apps/website/content/roam/use-cases/reading-clubs.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Reading clubs" -date: "2025-01-01" -author: "" -published: true ---- - -Description coming soon! - -[Get in touch](mailto:joechan@umd.edu) if you're interested in joining a Reading Club! diff --git a/apps/website/content/roam/use-cases/research-roadmapping.md b/apps/website/content/roam/use-cases/research-roadmapping.md deleted file mode 100644 index 01d12fc3d..000000000 --- a/apps/website/content/roam/use-cases/research-roadmapping.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "Research roadmapping" -date: "2025-01-01" -author: "" -published: true ---- - -Description coming soon! diff --git a/apps/website/content/roam/use-cases/lab-notebooks.md b/apps/website/content/roam/use-cases/share-your-ideas-and-research.md similarity index 52% rename from apps/website/content/roam/use-cases/lab-notebooks.md rename to apps/website/content/roam/use-cases/share-your-ideas-and-research.md index 9bdfa548c..a66aa276a 100644 --- a/apps/website/content/roam/use-cases/lab-notebooks.md +++ b/apps/website/content/roam/use-cases/share-your-ideas-and-research.md @@ -1,6 +1,6 @@ --- -title: "Lab notebooks" -date: "2025-01-01" +title: "Share your ideas & research" +date: "2026-06-29" author: "" published: true --- diff --git a/apps/website/content/roam/use-cases/synthesize-insights-from-literature.md b/apps/website/content/roam/use-cases/synthesize-insights-from-literature.md new file mode 100644 index 000000000..da844d5f4 --- /dev/null +++ b/apps/website/content/roam/use-cases/synthesize-insights-from-literature.md @@ -0,0 +1,8 @@ +--- +title: "Synthesize Insights from the Literature" +date: "2026-06-29" +author: "" +published: true +--- + +Description coming soon! diff --git a/apps/website/content/roam/use-cases/track-your-projects-and-experiments.md b/apps/website/content/roam/use-cases/track-your-projects-and-experiments.md new file mode 100644 index 000000000..7de0006ba --- /dev/null +++ b/apps/website/content/roam/use-cases/track-your-projects-and-experiments.md @@ -0,0 +1,8 @@ +--- +title: "Track your Projects and Experiments" +date: "2026-06-29" +author: "" +published: true +--- + +Description coming soon! diff --git a/apps/website/mdx-components.tsx b/apps/website/mdx-components.tsx index 333e60126..f5ab2fb61 100644 --- a/apps/website/mdx-components.tsx +++ b/apps/website/mdx-components.tsx @@ -1,12 +1,18 @@ +import { NodeTag } from "~/components/docs/NodeTag"; import { useMDXComponents as getThemeComponents } from "nextra-theme-docs"; type MdxComponentMap = Record; export const useMDXComponents = ( components: MdxComponentMap = {}, -): MdxComponentMap => ({ - ...getThemeComponents(), - ...components, -}); +): MdxComponentMap => { + const themeComponents = getThemeComponents(); + + return { + ...themeComponents, + NodeTag, + ...components, + }; +}; export default useMDXComponents; diff --git a/apps/website/public/docs/obsidian/backrooms.jpg b/apps/website/public/docs/obsidian/backrooms.jpg new file mode 100644 index 000000000..555c946e5 Binary files /dev/null and b/apps/website/public/docs/obsidian/backrooms.jpg differ diff --git a/apps/website/public/docs/obsidian/biblio.png b/apps/website/public/docs/obsidian/biblio.png new file mode 100644 index 000000000..b5591e82e Binary files /dev/null and b/apps/website/public/docs/obsidian/biblio.png differ diff --git a/apps/website/public/docs/obsidian/bullet-journal.png b/apps/website/public/docs/obsidian/bullet-journal.png new file mode 100644 index 000000000..fa9c1db5b Binary files /dev/null and b/apps/website/public/docs/obsidian/bullet-journal.png differ diff --git a/apps/website/public/docs/obsidian/canvas-export-1.png b/apps/website/public/docs/obsidian/canvas-export-1.png new file mode 100644 index 000000000..4959abb4b Binary files /dev/null and b/apps/website/public/docs/obsidian/canvas-export-1.png differ diff --git a/apps/website/public/docs/obsidian/canvas-walkthru01.gif b/apps/website/public/docs/obsidian/canvas-walkthru01.gif new file mode 100644 index 000000000..d1270d349 Binary files /dev/null and b/apps/website/public/docs/obsidian/canvas-walkthru01.gif differ diff --git a/apps/website/public/docs/obsidian/cat-meme.png b/apps/website/public/docs/obsidian/cat-meme.png new file mode 100644 index 000000000..f6a3a8fd3 Binary files /dev/null and b/apps/website/public/docs/obsidian/cat-meme.png differ diff --git a/apps/website/public/docs/obsidian/clipping01.png b/apps/website/public/docs/obsidian/clipping01.png new file mode 100644 index 000000000..e35e4ec00 Binary files /dev/null and b/apps/website/public/docs/obsidian/clipping01.png differ diff --git a/apps/website/public/docs/obsidian/clm-clip02.png b/apps/website/public/docs/obsidian/clm-clip02.png new file mode 100644 index 000000000..36ce80c57 Binary files /dev/null and b/apps/website/public/docs/obsidian/clm-clip02.png differ diff --git a/apps/website/public/docs/obsidian/convert-menu.png b/apps/website/public/docs/obsidian/convert-menu.png new file mode 100644 index 000000000..5755ba308 Binary files /dev/null and b/apps/website/public/docs/obsidian/convert-menu.png differ diff --git a/apps/website/public/docs/obsidian/convert-menub.png b/apps/website/public/docs/obsidian/convert-menub.png new file mode 100644 index 000000000..10ce1d9b1 Binary files /dev/null and b/apps/website/public/docs/obsidian/convert-menub.png differ diff --git a/apps/website/public/docs/obsidian/create-exp01.png b/apps/website/public/docs/obsidian/create-exp01.png new file mode 100644 index 000000000..dd96a9755 Binary files /dev/null and b/apps/website/public/docs/obsidian/create-exp01.png differ diff --git a/apps/website/public/docs/obsidian/create-exp02.png b/apps/website/public/docs/obsidian/create-exp02.png new file mode 100644 index 000000000..427c83cad Binary files /dev/null and b/apps/website/public/docs/obsidian/create-exp02.png differ diff --git a/apps/website/public/docs/obsidian/create-prj01.png b/apps/website/public/docs/obsidian/create-prj01.png new file mode 100644 index 000000000..917a0c794 Binary files /dev/null and b/apps/website/public/docs/obsidian/create-prj01.png differ diff --git a/apps/website/public/docs/obsidian/create-prj02.png b/apps/website/public/docs/obsidian/create-prj02.png new file mode 100644 index 000000000..aeee0edc6 Binary files /dev/null and b/apps/website/public/docs/obsidian/create-prj02.png differ diff --git a/apps/website/public/docs/obsidian/dgraph-share.png b/apps/website/public/docs/obsidian/dgraph-share.png new file mode 100644 index 000000000..c8a972daf Binary files /dev/null and b/apps/website/public/docs/obsidian/dgraph-share.png differ diff --git a/apps/website/public/docs/obsidian/drmanhattan.png b/apps/website/public/docs/obsidian/drmanhattan.png new file mode 100644 index 000000000..bac2b0813 Binary files /dev/null and b/apps/website/public/docs/obsidian/drmanhattan.png differ diff --git a/apps/website/public/docs/obsidian/exp-exp.png b/apps/website/public/docs/obsidian/exp-exp.png new file mode 100644 index 000000000..a3be6be81 Binary files /dev/null and b/apps/website/public/docs/obsidian/exp-exp.png differ diff --git a/apps/website/public/docs/obsidian/exp-exp01.png b/apps/website/public/docs/obsidian/exp-exp01.png new file mode 100644 index 000000000..484050e79 Binary files /dev/null and b/apps/website/public/docs/obsidian/exp-exp01.png differ diff --git a/apps/website/public/docs/obsidian/exp-exp02.png b/apps/website/public/docs/obsidian/exp-exp02.png new file mode 100644 index 000000000..a67fc7409 Binary files /dev/null and b/apps/website/public/docs/obsidian/exp-exp02.png differ diff --git a/apps/website/public/docs/obsidian/figdesign01.png b/apps/website/public/docs/obsidian/figdesign01.png new file mode 100644 index 000000000..901ad96b0 Binary files /dev/null and b/apps/website/public/docs/obsidian/figdesign01.png differ diff --git a/apps/website/public/docs/obsidian/figdesign02.png b/apps/website/public/docs/obsidian/figdesign02.png new file mode 100644 index 000000000..b2cf8cca1 Binary files /dev/null and b/apps/website/public/docs/obsidian/figdesign02.png differ diff --git a/apps/website/public/docs/obsidian/gap-spotting.png b/apps/website/public/docs/obsidian/gap-spotting.png new file mode 100644 index 000000000..9a84394ac Binary files /dev/null and b/apps/website/public/docs/obsidian/gap-spotting.png differ diff --git a/apps/website/public/docs/obsidian/graph-argument-evd.png b/apps/website/public/docs/obsidian/graph-argument-evd.png new file mode 100644 index 000000000..79c026d46 Binary files /dev/null and b/apps/website/public/docs/obsidian/graph-argument-evd.png differ diff --git a/apps/website/public/docs/obsidian/graph-argument.png b/apps/website/public/docs/obsidian/graph-argument.png new file mode 100644 index 000000000..5e5937db6 Binary files /dev/null and b/apps/website/public/docs/obsidian/graph-argument.png differ diff --git a/apps/website/public/docs/obsidian/graph-view01.png b/apps/website/public/docs/obsidian/graph-view01.png new file mode 100644 index 000000000..b0c4d1865 Binary files /dev/null and b/apps/website/public/docs/obsidian/graph-view01.png differ diff --git a/apps/website/public/docs/obsidian/graph-view02.png b/apps/website/public/docs/obsidian/graph-view02.png new file mode 100644 index 000000000..a5a4245ff Binary files /dev/null and b/apps/website/public/docs/obsidian/graph-view02.png differ diff --git a/apps/website/public/docs/obsidian/hover.png b/apps/website/public/docs/obsidian/hover.png new file mode 100644 index 000000000..14fdc6e3f Binary files /dev/null and b/apps/website/public/docs/obsidian/hover.png differ diff --git a/apps/website/public/docs/obsidian/img-clm02.png b/apps/website/public/docs/obsidian/img-clm02.png new file mode 100644 index 000000000..fe1d5db04 Binary files /dev/null and b/apps/website/public/docs/obsidian/img-clm02.png differ diff --git a/apps/website/public/docs/obsidian/iss-ex.png b/apps/website/public/docs/obsidian/iss-ex.png new file mode 100644 index 000000000..8a6806597 Binary files /dev/null and b/apps/website/public/docs/obsidian/iss-ex.png differ diff --git a/apps/website/public/docs/obsidian/iss-exp.png b/apps/website/public/docs/obsidian/iss-exp.png new file mode 100644 index 000000000..13bb633d9 Binary files /dev/null and b/apps/website/public/docs/obsidian/iss-exp.png differ diff --git a/apps/website/public/docs/obsidian/left-sidebar.png b/apps/website/public/docs/obsidian/left-sidebar.png new file mode 100644 index 000000000..b3da2a6d7 Binary files /dev/null and b/apps/website/public/docs/obsidian/left-sidebar.png differ diff --git a/apps/website/public/docs/obsidian/linked-men.png b/apps/website/public/docs/obsidian/linked-men.png new file mode 100644 index 000000000..faf09ce27 Binary files /dev/null and b/apps/website/public/docs/obsidian/linked-men.png differ diff --git a/apps/website/public/docs/obsidian/lit-rev.png b/apps/website/public/docs/obsidian/lit-rev.png new file mode 100644 index 000000000..37fe06b76 Binary files /dev/null and b/apps/website/public/docs/obsidian/lit-rev.png differ diff --git a/apps/website/public/docs/obsidian/lit-rev02.png b/apps/website/public/docs/obsidian/lit-rev02.png new file mode 100644 index 000000000..559475109 Binary files /dev/null and b/apps/website/public/docs/obsidian/lit-rev02.png differ diff --git a/apps/website/public/docs/obsidian/lit-synth-canvas.png b/apps/website/public/docs/obsidian/lit-synth-canvas.png new file mode 100644 index 000000000..4a192dcd8 Binary files /dev/null and b/apps/website/public/docs/obsidian/lit-synth-canvas.png differ diff --git a/apps/website/public/docs/obsidian/med-log-ex.png b/apps/website/public/docs/obsidian/med-log-ex.png new file mode 100644 index 000000000..71b098eec Binary files /dev/null and b/apps/website/public/docs/obsidian/med-log-ex.png differ diff --git a/apps/website/public/docs/obsidian/memex-res.png b/apps/website/public/docs/obsidian/memex-res.png new file mode 100644 index 000000000..1ebf38ec0 Binary files /dev/null and b/apps/website/public/docs/obsidian/memex-res.png differ diff --git a/apps/website/public/docs/obsidian/merton-mentions.png b/apps/website/public/docs/obsidian/merton-mentions.png new file mode 100644 index 000000000..794adc7dc Binary files /dev/null and b/apps/website/public/docs/obsidian/merton-mentions.png differ diff --git a/apps/website/public/docs/obsidian/merton-que.png b/apps/website/public/docs/obsidian/merton-que.png new file mode 100644 index 000000000..cf21fca4a Binary files /dev/null and b/apps/website/public/docs/obsidian/merton-que.png differ diff --git a/apps/website/public/docs/obsidian/ms-canvas.png b/apps/website/public/docs/obsidian/ms-canvas.png new file mode 100644 index 000000000..f8c0b0207 Binary files /dev/null and b/apps/website/public/docs/obsidian/ms-canvas.png differ diff --git a/apps/website/public/docs/obsidian/new-node01.png b/apps/website/public/docs/obsidian/new-node01.png new file mode 100644 index 000000000..5ff6a441a Binary files /dev/null and b/apps/website/public/docs/obsidian/new-node01.png differ diff --git a/apps/website/public/docs/obsidian/new-node02.png b/apps/website/public/docs/obsidian/new-node02.png new file mode 100644 index 000000000..41cf28eb7 Binary files /dev/null and b/apps/website/public/docs/obsidian/new-node02.png differ diff --git a/apps/website/public/docs/obsidian/new-q.png b/apps/website/public/docs/obsidian/new-q.png new file mode 100644 index 000000000..2e35ceb3d Binary files /dev/null and b/apps/website/public/docs/obsidian/new-q.png differ diff --git a/apps/website/public/docs/obsidian/node-log.png b/apps/website/public/docs/obsidian/node-log.png new file mode 100644 index 000000000..513e1a422 Binary files /dev/null and b/apps/website/public/docs/obsidian/node-log.png differ diff --git a/apps/website/public/docs/obsidian/obama.png b/apps/website/public/docs/obsidian/obama.png new file mode 100644 index 000000000..69ae46038 Binary files /dev/null and b/apps/website/public/docs/obsidian/obama.png differ diff --git a/apps/website/public/docs/obsidian/prj-container.png b/apps/website/public/docs/obsidian/prj-container.png new file mode 100644 index 000000000..acda60938 Binary files /dev/null and b/apps/website/public/docs/obsidian/prj-container.png differ diff --git a/apps/website/public/docs/obsidian/prj-page.png b/apps/website/public/docs/obsidian/prj-page.png new file mode 100644 index 000000000..ba5189742 Binary files /dev/null and b/apps/website/public/docs/obsidian/prj-page.png differ diff --git a/apps/website/public/docs/obsidian/reader-que.png b/apps/website/public/docs/obsidian/reader-que.png new file mode 100644 index 000000000..40d452754 Binary files /dev/null and b/apps/website/public/docs/obsidian/reader-que.png differ diff --git a/apps/website/public/docs/obsidian/reader-que02.png b/apps/website/public/docs/obsidian/reader-que02.png new file mode 100644 index 000000000..6b8d76b40 Binary files /dev/null and b/apps/website/public/docs/obsidian/reader-que02.png differ diff --git a/apps/website/public/docs/obsidian/source-base01.png b/apps/website/public/docs/obsidian/source-base01.png new file mode 100644 index 000000000..1eeb3d21b Binary files /dev/null and b/apps/website/public/docs/obsidian/source-base01.png differ diff --git a/apps/website/public/docs/obsidian/src-node-clip.png b/apps/website/public/docs/obsidian/src-node-clip.png new file mode 100644 index 000000000..aa29fae55 Binary files /dev/null and b/apps/website/public/docs/obsidian/src-node-clip.png differ diff --git a/apps/website/public/docs/obsidian/tsundoku.png b/apps/website/public/docs/obsidian/tsundoku.png new file mode 100644 index 000000000..a19284dc6 Binary files /dev/null and b/apps/website/public/docs/obsidian/tsundoku.png differ diff --git a/apps/website/public/docs/obsidian/zot-import.png b/apps/website/public/docs/obsidian/zot-import.png new file mode 100644 index 000000000..06c36ce7a Binary files /dev/null and b/apps/website/public/docs/obsidian/zot-import.png differ diff --git a/apps/website/public/docs/obsidian/zot-search.png b/apps/website/public/docs/obsidian/zot-search.png new file mode 100644 index 000000000..592d1cc3b Binary files /dev/null and b/apps/website/public/docs/obsidian/zot-search.png differ diff --git a/apps/website/public/docs/obsidian/zot-search2.png b/apps/website/public/docs/obsidian/zot-search2.png new file mode 100644 index 000000000..d3f0be385 Binary files /dev/null and b/apps/website/public/docs/obsidian/zot-search2.png differ diff --git a/apps/website/public/docs/obsidian/zotsidian-settings.png b/apps/website/public/docs/obsidian/zotsidian-settings.png new file mode 100644 index 000000000..8275c938b Binary files /dev/null and b/apps/website/public/docs/obsidian/zotsidian-settings.png differ diff --git a/skills/update-user-docs/SKILL.md b/skills/update-user-docs/SKILL.md index e682f7b7f..830c54c3d 100644 --- a/skills/update-user-docs/SKILL.md +++ b/skills/update-user-docs/SKILL.md @@ -20,6 +20,7 @@ If no argument is provided, use the current branch's diff against main, commit m - Do not edit legacy docs route shells or deleted legacy docs paths such as `apps/website/app/(docs)/docs/*/pages`, `docMap.ts`, `navigation.ts`, or `sharedPages`. - Do not update runtime code, app routes, or package interfaces unless the dev explicitly asks for that separately. - Use existing Nextra Markdown, MDX, and `nextra/components` features before proposing custom styling or layout. +- Use the existing global `NodeTag` MDX component for discourse candidate tag pills, such as ``. Allowed `type` values are `que`, `clm`, `evd`, `src`, `hyp`, `res`, and `iss`. Do not create one-off tag styling or CSS in docs content. - Do not add or change theme, layout, route, component, or CSS code while adding documentation content. If existing Nextra features are not enough, flag the author to create a separate Linear ticket for new Nextra functionality. ## When to Run diff --git a/skills/update-user-docs/references/doc-conventions.md b/skills/update-user-docs/references/doc-conventions.md index d8210df2d..d39c666c0 100644 --- a/skills/update-user-docs/references/doc-conventions.md +++ b/skills/update-user-docs/references/doc-conventions.md @@ -43,6 +43,9 @@ Good first choices include: - Nextra `Steps` for ordered setup or workflow instructions - Nextra `Tabs` for compact platform or mode variants - Nextra `Table` and `FileTree` when structured data or file paths need clearer presentation +- The global `NodeTag` MDX component for discourse candidate tag pills, such as ``, ``, or ``. Allowed `type` values are `que`, `clm`, `evd`, `src`, `hyp`, `res`, and `iss`. + +Use `.mdx` when a page needs MDX components like `Callout`, `Image`, or `NodeTag`. `NodeTag` renders `#-candidate` by default and uses the approved node colors. Do not import `NodeTag` in individual docs pages; it is registered globally through `mdx-components.tsx`. Do not change docs structural code, theme files, route shells, app layouts, shared components, or CSS as part of adding content. If the content needs a styling or presentation feature that existing Nextra features cannot support, stop and flag the author to create a separate Linear ticket for adding that Nextra functionality. diff --git a/skills/update-user-docs/references/llm-authoring-guide.md b/skills/update-user-docs/references/llm-authoring-guide.md index 4d7de62a9..b9a72addd 100644 --- a/skills/update-user-docs/references/llm-authoring-guide.md +++ b/skills/update-user-docs/references/llm-authoring-guide.md @@ -17,6 +17,8 @@ Use these paths: Use existing Nextra Markdown, MDX, and nextra/components features first for styling and layout, such as Callout, Cards, Steps, Tabs, Table, and FileTree when appropriate. +For discourse candidate tag pills, use the existing global MDX component, such as ``, ``, or ``. Allowed `type` values are `que`, `clm`, `evd`, `src`, `hyp`, `res`, and `iss`. It renders `#-candidate` with approved node colors. Do not import it in individual pages and do not add custom tag CSS. + Do not edit route shells, theme/layout code, shared components, CSS, or legacy docs paths. Do not use app/(docs)/docs/*/pages, docMap.ts, navigation.ts, or sharedPages. If adding a page, choose the right platform section, create a kebab-case .md or .mdx file, update the nearest _meta.ts, and update docsRouteMap.ts only when a flat /docs// redirect should exist. @@ -55,6 +57,8 @@ Before finishing, verify links, sidebar registration, route redirects, and stale 5. Add the slug to the nearest `_meta.ts` file. 6. Update `apps/website/docsRouteMap.ts` only if a flat legacy route should redirect to the sectioned route. +Use `.mdx` instead of `.md` when a page needs MDX components such as `Callout`, `Image`, or `NodeTag`. + ## Screenshot handling Use screenshots only when the file exists or the dev provides it. @@ -70,7 +74,7 @@ If the screenshot is not available yet, add a comment like: - Docs edits are under `apps/website/content/**`. - New pages are registered in the nearest `_meta.ts`. - Needed flat redirects are in `apps/website/docsRouteMap.ts`. -- Styling uses existing Nextra features and does not change structural code. +- Styling uses existing Nextra features or the existing `NodeTag` MDX component and does not change structural code. - New links resolve to existing routes or files. - Screenshot TODOs are comments, not broken images. - No positive instructions point to legacy docs paths.