|
4 | 4 | <img alt="Shows project promo image in light and dark mode"> |
5 | 5 | </picture> |
6 | 6 |
|
7 | | -# Discourse Graphs for Obsidian |
| 7 | +# Overview |
8 | 8 |
|
9 | | -The Discourse Graph extension enables Obsidian users to seamlessly add additional semantic structure to their notes, including specified page types and link types that model scientific discourse, to enable more complex and structured knowledge synthesis work, such as a complex interdisciplinary literature review, and enhanced collaboration with others on this work. |
| 9 | +Break down the research process into atomic units to augment the knowledge synthesis process. Create distinct objects for questions, claims, evidence, hypotheses or choose your own to suit your specific needs. These objects can then be related, resurfaced, and reused throughout your research journey to help you efficiently build arguments and create new knowledge. |
10 | 10 |
|
11 | | -For more information about Discourse Graphs, check out our website at [https://discoursegraphs.com](https://discoursegraphs.com) |
| 11 | +# Installation |
12 | 12 |
|
13 | | -## Installation |
| 13 | +Follow the instructions below to install the plugin: |
14 | 14 |
|
15 | | -### Prerequisites |
| 15 | +## Install BRAT |
16 | 16 |
|
17 | | -#### Install BRAT (Beta Reviewer's Auto-update Tester) |
| 17 | +To use the plugin prior to its public release on Obsidian's community plugin browser, install BRAT (Beta Reviewer's Auto-update Tester). |
18 | 18 |
|
19 | 19 | 1. Open Obsidian Settings |
20 | 20 | 2. Go to Community Plugins and disable Restricted Mode |
21 | 21 | 3. Click "Browse" and search for "BRAT" |
22 | | -  |
23 | 22 | 4. Install BRAT and enable it |
24 | 23 |
|
25 | | -#### Install DataCore via BRAT |
| 24 | +## Install DataCore via BRAT |
26 | 25 |
|
27 | | -1. Open Obsidian Settings |
28 | | -2. Go to "Community Plugins" → "BRAT" |
29 | | -3. Click "Add Beta Plugin" |
30 | | -  |
31 | | -4. Enter the repository URL: `https://github.com/blacksmithgu/datacore` and choose "Latest version" |
32 | | -  |
33 | | -5. Check the box for "Enable after installing the plugin" |
34 | | -6. Click "Add plugin" |
| 26 | +1. Add the DataCore plugin from the BRAT settings menu or run command "Add a beta plugin for testing" |
| 27 | +2. Enter the repository URL: `https://github.com/blacksmithgu/datacore` and choose "Latest version" |
| 28 | +3. Check the box for "Enable after installing the plugin" |
| 29 | +4. Click `Add plugin` |
35 | 30 |
|
36 | | -### Install Discourse Graphs |
| 31 | +## Install Discourse Graphs |
37 | 32 |
|
38 | | -1. Open Obsidian Settings |
39 | | -2. Go to "Community Plugins" → "BRAT" |
40 | | -3. Click "Add Beta Plugin" |
41 | | -  |
| 33 | +1. Add the Discourse Graphs plugin from the BRAT settings menu or run command `Add a beta plugin for testing` |
| 34 | +2. Enter the repository URL: `https://github.com/DiscourseGraphs/discourse-graph-obsidian` and choose "Latest version" |
| 35 | +3. Check the box for "Enable after installing the plugin" |
| 36 | +4. Click `Add plugin` |
42 | 37 |
|
43 | | -4. Enter the repository URL: `https://github.com/DiscourseGraphs/discourse-graph-obsidian` and choose "Latest version" |
44 | | -  |
45 | | -5. Check the box for "Enable after installing the plugin" |
46 | | -6. Click "Add Plugin" |
| 38 | +# Getting started |
47 | 39 |
|
48 | | -## Creating Nodes and Relationships |
| 40 | +The Discourse Graphs plugin gives you the ability to add additional semantic structure to your notes via specified page types (nodes) and relation types that model scientific discourse and enable more complex and structured [knowledge synthesis work](https://oasislab.pubpub.org/pub/54t0y9mk/release/3). |
49 | 41 |
|
50 | | -### Configure Node and Relationship Types |
| 42 | +The plugin ships with several node types to provide a foundation for your scientific argumentation: Question, Claim, Evidence, and Source, as well as complementary relation types that can be used between them. |
51 | 43 |
|
52 | | -1. Open Obsidian Settings |
53 | | -2. Navigate to the "Discourse Graphs" settings tab |
54 | | - |
55 | | -#### Edit Node Types |
56 | | - |
57 | | -- Under "Node Types," click "Add Node Type" |
58 | | -- Enter a name for your node type (e.g., "Claim", "Evidence", "Question") |
59 | | -- Add the format for your node type. eg a claim node will have page title "CLM - {content}" |
60 | | -- **Template (Optional)**: Select a template from the dropdown to automatically apply template content when creating nodes of this type |
61 | | - - Templates are sourced from Obsidian's core Templates plugin |
62 | | - - Ensure you have the Templates plugin enabled and configured with a template folder |
63 | | - - The dropdown will show all available template files from your configured template folder |
64 | | - |
65 | | -  |
66 | | - - Click "Save Changes" |
67 | | - |
68 | | -- To create a new template: |
69 | | - - Create new folder to store templates |
70 | | -  |
71 | | - |
72 | | - - Specify template folder location in plugin settings menu |
73 | | -  |
74 | | - |
75 | | - - Create new file in template folder (A) and add text to file (B) |
76 | | -  |
77 | | - |
78 | | -  |
79 | | - - Click "Save Changes" |
80 | | - |
81 | | -#### Edit Relation Types |
82 | | - |
83 | | -- Under "Relation Types," click "Add Relationship Type" |
84 | | -- A relation type is a kind of relationship that can exist between any two node types |
85 | | -- Enter a name for your relationship (e.g., "supports", "contradicts") |
86 | | -- Enter the complement label (e.g., "is supported by", "is contradicted by") |
87 | | -  |
88 | | -- Click "Save Changes" |
89 | | - |
90 | | -#### Define possible relations between nodes |
91 | | - |
92 | | -- Open the Discourse Relations tab in the Discourse Graph settings |
93 | | -  |
94 | | -- Choose Source Node Type, Relation Type, and Target Node Type |
95 | | -  |
96 | | -- Once you see the source, relation, and target selected: |
97 | | -  |
98 | | - E.g: this means that _Claim_ nodes can supports _Questions_ nodes |
99 | | -- Click "Save changes" |
100 | | - |
101 | | -## Using Discourse Graphs |
102 | | - |
103 | | -### Instantiate a Node |
104 | | - |
105 | | -- Select the text you want to turn into a Discourse Node |
106 | | -  |
107 | | -- There are two ways you can create a node from here: |
108 | | - 1. Using command keys: Cmd + \ |
109 | | - <br> |
110 | | - - As you press these keys, the Node Menu will open up as a popup |
111 | | - |
112 | | -  |
113 | | - - Select the node type you want to turn the text into |
114 | | - - Voila, you've created a new discourse node |
115 | | -  |
116 | | - 2. Right-click menu: |
117 | | - - Alternatively, you can right-click on the selected text |
118 | | -  |
119 | | - - Then choose a node type from the "Turn into discourse node" menu |
120 | | - |
121 | | -### Open Discourse Context |
122 | | - |
123 | | -- Click on the telescope icon on the left bar |
124 | | -  |
125 | | -- Alternatively, you can set a hotkey to toggle the Discourse Context view or access it via the Command Palette |
126 | | -  |
127 | | - |
128 | | -### Instantiate a Relationship |
129 | | - |
130 | | -1. Open a note that you want to create a relationship from |
131 | | -2. Open the Discourse Context |
132 | | -  |
133 | | -3. Click "Add a new relation" |
134 | | -4. The dropdown that shows Relationship Types will be all available relations that you have defined in the setings. |
135 | | - <br> It will also show you what node type you can link with |
136 | | -  |
137 | | -5. Search the nodes you want to link with by the title |
138 | | -  |
139 | | -6. Click "Confirm", now a new relationship has been created |
140 | | -  |
| 44 | +To see the default settings or begin adding your own node and relation types, open the Discourse Graphs plugin settings menu by navigating to it in Obsidian's settings menu or using the command: "Open Discourse Graphs settings" |
| 45 | + |
| 46 | +## Defining node types |
| 47 | + |
| 48 | +To define a new node type for use in your vault navigate to the Node Types menu and click `Add Node Type`. Doing so will take you to an editing menu where you can choose the details of your new node type including its title, a description, a template to use, a color to represent that type in your vault, and more. |
| 49 | + |
| 50 | +## Defining relation types |
| 51 | + |
| 52 | +The Discourse Graphs plugin ships with four default relation types: `supports`, `opposes`, `informs`, and `derivedFrom`. You can add your own in the Relation Types menu by clicking the `Add relation type` button and filling out the text fields that define your new type. |
| 53 | + |
| 54 | +## Defining relations |
| 55 | + |
| 56 | +With nodes and relation types ready, the last step is to connect them in the Discourse Relations menu. Click `Add Relation` then choose a source node, relation type, target node, and then click `Save Changes`. These relations are now ready to use in your notes and canvases. |
| 57 | + |
| 58 | +# Usage |
| 59 | + |
| 60 | +## In notes |
| 61 | + |
| 62 | +<picture> |
| 63 | + <source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/85bfcced-5627-4e38-ac54-588bf37df2d4"> |
| 64 | + <source media="(prefers-color-scheme: light)" srcset="https://github.com/user-attachments/assets/f3e27e4a-d50e-4634-905c-32fbca6b4eac"> |
| 65 | + <img alt="Shows project promo image in light and dark mode"> |
| 66 | +</picture> |
| 67 | + |
| 68 | +### Creating nodes |
| 69 | + |
| 70 | +There are three ways to create nodes in a note: |
| 71 | + |
| 72 | +_Turn text into a node with the node type selection menu_ |
| 73 | + |
| 74 | +1. Highlight the text that you want to turn into a node |
| 75 | +2. Use the hotkey `⌘ + \` to open the node type selection menu |
| 76 | +3. Choose your node type |
| 77 | + |
| 78 | +_Turn text into a node from the right click menu_ |
| 79 | + |
| 80 | +1. Highlight the text that you want to turn into a node |
| 81 | +2. Right-click on the highlighted text and navigate to the menu option "Turn into discourse node" |
| 82 | +3. Choose your node type |
| 83 | + |
| 84 | +_Create discourse node command_ |
| 85 | + |
| 86 | +1. Search for and select "Create discourse node" from the command palette |
| 87 | +2. In the node creation dialog, choose your node type and the title of your new node then click confirm |
| 88 | +3. Your new node is created and a link to it is added to the location of your cursor |
| 89 | + |
| 90 | +### Creating relations |
| 91 | + |
| 92 | +To create a relation between nodes: |
| 93 | + |
| 94 | +1. Open the page of the node that you want to create the relation for |
| 95 | +2. Run the command "Toggle discourse context" which will open a widget in the right sidebar |
| 96 | +3. From there, click `Add a new relation`, choose the desired relation type and the node to link with, then click `Confirm` |
| 97 | +4. The relation is now created and can be viewed or removed from this Discourse Context panel |
| 98 | + |
| 99 | +## On a canvas |
| 100 | + |
| 101 | +<picture> |
| 102 | + <source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/48a3a4ae-ac47-4f8b-8288-1d1ba3377ef2"> |
| 103 | + <source media="(prefers-color-scheme: light)" srcset="https://github.com/user-attachments/assets/6234a38f-be4e-4a83-bfe6-2d22ea1293e1"> |
| 104 | + <img alt="Shows project promo image in light and dark mode"> |
| 105 | +</picture> |
| 106 | + |
| 107 | +The Discourse Graphs plugin uses [tldraw](https://tldraw.dev/) to create canvases in Obsidian. To create a new canvas, run the command "Create new Discourse Graph Canvas". |
| 108 | + |
| 109 | +### Creating nodes |
| 110 | + |
| 111 | +1. Click on the Discourse Graphs icon-button located in the bottom toolbar of the canvas |
| 112 | +2. Drag the desired node type from the menu that appears in the top-right corner of the interface onto the canvas |
| 113 | +3. Search for or create a new node with the input field in the node creation modal |
| 114 | +4. Click `Confirm` to add this node to the canvas |
| 115 | + |
| 116 | +### Creating relations |
| 117 | + |
| 118 | +1. Click on the Discourse Graphs icon-button located in the bottom toolbar of the canvas to show a menu in the top right of the interface |
| 119 | +2. From the menu, select the desired relation type that you would like to draw between nodes |
| 120 | +3. With the relation type selected, click and drag from one node card to another to create a relation between those nodes |
| 121 | + |
| 122 | +# Commands |
| 123 | + |
| 124 | +| Name | Description | |
| 125 | +| ------------------------------------- | ------------------------------------------------------------------------------------------ | |
| 126 | +| Bulk identify discourse nodes | Scan vault to identify notes that follow the title pattern to be a node | |
| 127 | +| Create discourse node | Opens the node creation dialog modal | |
| 128 | +| Create new Discourse Graph canvas | Creates a tldraw canvas | |
| 129 | +| Open Discourse Graphs settings | Takes you to the plugin settings menu | |
| 130 | +| Open node type menu | Opens menu that allows you to choose the node type that you wish to apply to selected text | |
| 131 | +| Switch to Discourse Graph canvas view | Renders tldraw canvas if markdown is displayed | |
| 132 | +| Switch to discourse markdown edit | Displays markdown of a rendered tldraw canvas | |
| 133 | +| Toggle discourse context | Opens a widget in the sidebar which displays relations of the active node | |
| 134 | + |
| 135 | +# Documentation |
| 136 | + |
| 137 | +For more information about Discourse Graphs, check out [our website](https://discoursegraphs.com) and [documentation](https://discoursegraphs.com/docs/obsidian/getting-started). |
| 138 | + |
| 139 | +# Get involved |
| 140 | + |
| 141 | +1. Join our growing community of academics, researchers, and thinkers on [Slack 💬](https://join.slack.com/t/discoursegraphs/shared_invite/zt-37xklatti-cpEjgPQC0YyKYQWPNgAkEg) |
| 142 | +2. Are you a lab or researcher interested in piloting the plugin with some guidance from the team? Send us [an email](mailto:discoursegraphs@homeworld.bio) or DM on Slack! |
| 143 | +3. Discourse Graphs is [open source](https://en.wikipedia.org/wiki/Open_source) and open to contributions. If you have an idea for an improvement or identify a bug open an issue here on the repo to start the conversation. |
![graphite-app[bot]](https://avatars.githubusercontent.com/in/158384?v=4&size=40){kind=avatar}
0 commit comments