From e01fc77faf6aadd6791b631eb992be379287a6f0 Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Wed, 1 Jan 2025 16:15:34 -0600 Subject: [PATCH 01/15] WIP init --- apps/website/app/(docs)/docs/page.tsx | 14 +++ .../app/(docs)/docs/roam/[slug]/page.tsx | 116 +++++++++++++++++ apps/website/app/(docs)/docs/roam/layout.tsx | 10 ++ .../app/(docs)/docs/roam/navigation.ts | 84 +++++++++++++ apps/website/app/(docs)/docs/roam/page.tsx | 13 ++ .../(docs)/docs/roam/pages/base-grammar.md | 27 ++++ .../roam/pages/creating-discourse-nodes.md | 16 +++ .../pages/creating-discourse-relationships.md | 70 +++++++++++ .../docs/roam/pages/enhanced-zettelkasten.md | 10 ++ .../roam/pages/exploring-discourse-graph.md | 8 ++ .../pages/extending-personalizing-graph.md | 20 +++ .../docs/roam/pages/extension-grammar.md | 27 ++++ .../(docs)/docs/roam/pages/getting-started.md | 26 ++++ .../(docs)/docs/roam/pages/installation.md | 30 +++++ .../(docs)/docs/roam/pages/lab-notebooks.md | 8 ++ .../docs/roam/pages/literature-reviewing.md | 14 +++ .../roam/pages/querying-discourse-graph.md | 100 +++++++++++++++ .../(docs)/docs/roam/pages/reading-clubs.md | 10 ++ .../docs/roam/pages/research-roadmapping.md | 8 ++ .../roam/pages/sharing-discourse-graph.md | 40 ++++++ .../roam/pages/what-is-discourse-graph.md | 20 +++ apps/website/app/(docs)/layout.tsx | 39 ++++++ .../app/{ => (home)}/blog/[slug]/page.tsx | 0 apps/website/app/{ => (home)}/blog/page.tsx | 0 .../app/(home)/blog/posts/EXAMPLE copy.md | 33 +++++ .../app/{ => (home)}/blog/posts/EXAMPLE.md | 0 apps/website/app/(home)/blog/posts/welcome.md | 26 ++++ .../app/{ => (home)}/blog/readBlogs.tsx | 47 ++++++- apps/website/app/{ => (home)}/blog/schema.tsx | 0 apps/website/app/{ => (home)}/layout.tsx | 32 ++--- apps/website/app/{ => (home)}/page.tsx | 0 apps/website/app/components/DocsHeader.tsx | 36 ++++++ apps/website/app/components/Layout.tsx | 100 +++++++++++++++ apps/website/app/components/Logo.tsx | 19 +++ apps/website/app/components/Navigation.tsx | 62 +++++++++ apps/website/app/components/Prose.tsx | 31 +++++ .../app/components/TableOfContents.tsx | 118 ++++++++++++++++++ apps/website/app/globals.css | 2 +- apps/website/app/utils/getNodes.ts | 29 +++++ apps/website/app/utils/sections.ts | 92 ++++++++++++++ apps/website/package.json | 11 +- apps/website/tsconfig.json | 3 + package-lock.json | 94 ++++++++++++++ 43 files changed, 1418 insertions(+), 27 deletions(-) create mode 100644 apps/website/app/(docs)/docs/page.tsx create mode 100644 apps/website/app/(docs)/docs/roam/[slug]/page.tsx create mode 100644 apps/website/app/(docs)/docs/roam/layout.tsx create mode 100644 apps/website/app/(docs)/docs/roam/navigation.ts create mode 100644 apps/website/app/(docs)/docs/roam/page.tsx create mode 100644 apps/website/app/(docs)/docs/roam/pages/base-grammar.md create mode 100644 apps/website/app/(docs)/docs/roam/pages/creating-discourse-nodes.md create mode 100644 apps/website/app/(docs)/docs/roam/pages/creating-discourse-relationships.md create mode 100644 apps/website/app/(docs)/docs/roam/pages/enhanced-zettelkasten.md create mode 100644 apps/website/app/(docs)/docs/roam/pages/exploring-discourse-graph.md create mode 100644 apps/website/app/(docs)/docs/roam/pages/extending-personalizing-graph.md create mode 100644 apps/website/app/(docs)/docs/roam/pages/extension-grammar.md create mode 100644 apps/website/app/(docs)/docs/roam/pages/getting-started.md create mode 100644 apps/website/app/(docs)/docs/roam/pages/installation.md create mode 100644 apps/website/app/(docs)/docs/roam/pages/lab-notebooks.md create mode 100644 apps/website/app/(docs)/docs/roam/pages/literature-reviewing.md create mode 100644 apps/website/app/(docs)/docs/roam/pages/querying-discourse-graph.md create mode 100644 apps/website/app/(docs)/docs/roam/pages/reading-clubs.md create mode 100644 apps/website/app/(docs)/docs/roam/pages/research-roadmapping.md create mode 100644 apps/website/app/(docs)/docs/roam/pages/sharing-discourse-graph.md create mode 100644 apps/website/app/(docs)/docs/roam/pages/what-is-discourse-graph.md create mode 100644 apps/website/app/(docs)/layout.tsx rename apps/website/app/{ => (home)}/blog/[slug]/page.tsx (100%) rename apps/website/app/{ => (home)}/blog/page.tsx (100%) create mode 100644 apps/website/app/(home)/blog/posts/EXAMPLE copy.md rename apps/website/app/{ => (home)}/blog/posts/EXAMPLE.md (100%) create mode 100644 apps/website/app/(home)/blog/posts/welcome.md rename apps/website/app/{ => (home)}/blog/readBlogs.tsx (66%) rename apps/website/app/{ => (home)}/blog/schema.tsx (100%) rename apps/website/app/{ => (home)}/layout.tsx (70%) rename apps/website/app/{ => (home)}/page.tsx (100%) create mode 100644 apps/website/app/components/DocsHeader.tsx create mode 100644 apps/website/app/components/Layout.tsx create mode 100644 apps/website/app/components/Logo.tsx create mode 100644 apps/website/app/components/Navigation.tsx create mode 100644 apps/website/app/components/Prose.tsx create mode 100644 apps/website/app/components/TableOfContents.tsx create mode 100644 apps/website/app/utils/getNodes.ts create mode 100644 apps/website/app/utils/sections.ts diff --git a/apps/website/app/(docs)/docs/page.tsx b/apps/website/app/(docs)/docs/page.tsx new file mode 100644 index 000000000..d0ddd8f00 --- /dev/null +++ b/apps/website/app/(docs)/docs/page.tsx @@ -0,0 +1,14 @@ +export default function DocsPage() { + return ( +
+
+

+ Documentation +

+
+

Welcome to the documentation.

+
+
+
+ ); +} diff --git a/apps/website/app/(docs)/docs/roam/[slug]/page.tsx b/apps/website/app/(docs)/docs/roam/[slug]/page.tsx new file mode 100644 index 000000000..f582e4120 --- /dev/null +++ b/apps/website/app/(docs)/docs/roam/[slug]/page.tsx @@ -0,0 +1,116 @@ +import fs from "fs/promises"; +import path from "path"; +import { notFound } from "next/navigation"; +import { Metadata } from "next"; +import { getBlog, getFileContent } from "~/(home)/blog/readBlogs"; +import { DocsHeader } from "~/components/DocsHeader"; +import { Prose } from "~/components/Prose"; +import { collectSections } from "~/utils/sections"; +import { extractHeadings } from "~/utils/getNodes"; +import { TableOfContents } from "~/components/TableOfContents"; + +type Params = { + params: Promise<{ + slug: string; + }>; +}; + +const PATH = "app/(docs)/docs/roam/pages"; +const DIRECTORY = path.join(process.cwd(), PATH); + +// export default async function Page({ params }: Params) { +// try { +// const { slug } = await params; +// const { data, contentHtml } = await getBlog(slug, DIRECTORY); + +// return ( +//
+//
+//
+//

+// {data.title} +//

+//
+//
+//
+//
+// ); +// } catch (error) { +// console.error("Error rendering docs page:", error); +// return notFound(); +// } +// } + +// import { DocsHeader } from '@/components/DocsHeader' +// import { PrevNextLinks } from '@/components/PrevNextLinks' +// import { Prose } from '@/components/Prose' +// import { TableOfContents } from '@/components/TableOfContents' +// import { collectSections } from '@/lib/sections' + +export default async function Page({ params }: Params) { + const { slug } = await params; + const fileContent = await getFileContent(`${slug}.md`, DIRECTORY); + const { data, contentHtml } = await getBlog(slug, DIRECTORY); + const nodes = await extractHeadings(fileContent); + const tableOfContents = collectSections(nodes); + + return ( + <> +
+
+ + +
+ +
+ {/* */} +
+ + + ); +} + +export async function generateStaticParams() { + try { + const directoryExists = await fs + .stat(DIRECTORY) + .then((stats) => stats.isDirectory()) + .catch(() => false); + + if (!directoryExists) { + console.log("No docs directory found"); + return []; + } + + const files = await fs.readdir(DIRECTORY); + + return files + .filter((filename) => filename.endsWith(".md")) + .map((filename) => ({ + slug: filename.replace(/\.md$/, ""), + })); + } catch (error) { + console.error("Error generating static params:", error); + return []; + } +} + +export async function generateMetadata({ params }: Params): Promise { + try { + const { slug } = await params; + const { data } = await getBlog(slug, DIRECTORY); + + return { + title: data.title, + authors: [{ name: data.author }], + }; + } catch (error) { + console.error("Error generating metadata:", error); + return { + title: "Docs", + }; + } +} diff --git a/apps/website/app/(docs)/docs/roam/layout.tsx b/apps/website/app/(docs)/docs/roam/layout.tsx new file mode 100644 index 000000000..14fbc70f5 --- /dev/null +++ b/apps/website/app/(docs)/docs/roam/layout.tsx @@ -0,0 +1,10 @@ +import { Layout } from "~/components/Layout"; +import { navigation } from "./navigation"; + +export default function RootLayout({ + children, +}: { + children: React.ReactNode; +}) { + return {children}; +} diff --git a/apps/website/app/(docs)/docs/roam/navigation.ts b/apps/website/app/(docs)/docs/roam/navigation.ts new file mode 100644 index 000000000..3c7af6073 --- /dev/null +++ b/apps/website/app/(docs)/docs/roam/navigation.ts @@ -0,0 +1,84 @@ +import { NavigationList } from "~/components/Navigation"; + +const root = "/docs/roam"; + +export const navigation: NavigationList = [ + { + title: "🏠 Welcome!", + links: [ + { title: "Getting Started", href: `${root}/getting-started` }, + { title: "Installation", href: `${root}/installation` }, + ], + }, + { + title: "πŸ—ΊοΈ GUIDES", + links: [ + { + title: "Creating Nodes", + href: `${root}/creating-discourse-nodes`, + }, + { + title: "Creating Relationships", + href: `${root}/creating-discourse-relationships`, + }, + { + title: "Exploring", + href: `${root}/exploring-discourse-graph`, + }, + { + title: "Querying", + href: `${root}/querying-discourse-graph`, + }, + { + title: "Extending", + href: `${root}/extending-personalizing-graph`, + }, + { + title: "Sharing", + href: `${root}/sharing-discourse-graph`, + }, + ], + }, + { + title: "🧱 FUNDAMENTALS", + links: [ + { + title: "What is a Discourse Graph?", + href: `${root}/what-is-discourse-graph`, + }, + { + title: "Grammar", + href: `${root}/extension-grammar`, + }, + { + title: "The Base Grammar", + href: `${root}/base-grammar`, + }, + ], + }, + { + title: "🚒 USE CASES", + links: [ + { + title: "Literature Reviewing", + href: `${root}/literature-reviewing`, + }, + { + title: "Zettelkasten", + href: `${root}/enhanced-zettelkasten`, + }, + { + title: "Reading Clubs / Seminars", + href: `${root}/reading-clubs`, + }, + { + title: "Lab notebooks", + href: `${root}/lab-notebooks`, + }, + { + title: "Product / Research Roadmapping", + href: `${root}/research-roadmapping`, + }, + ], + }, +]; diff --git a/apps/website/app/(docs)/docs/roam/page.tsx b/apps/website/app/(docs)/docs/roam/page.tsx new file mode 100644 index 000000000..4496ed7bf --- /dev/null +++ b/apps/website/app/(docs)/docs/roam/page.tsx @@ -0,0 +1,13 @@ +import { redirect, notFound } from "next/navigation"; +import { navigation } from "./navigation"; + +export default function Page() { + const firstSection = navigation[0]; + const firstLink = firstSection?.links[0]; + + if (!firstLink?.href) { + notFound(); + } + + redirect(firstLink.href); +} diff --git a/apps/website/app/(docs)/docs/roam/pages/base-grammar.md b/apps/website/app/(docs)/docs/roam/pages/base-grammar.md new file mode 100644 index 000000000..d27acdddb --- /dev/null +++ b/apps/website/app/(docs)/docs/roam/pages/base-grammar.md @@ -0,0 +1,27 @@ +--- +title: "Base Grammar" +date: "2025-01-01" +author: "" +published: true +--- + +## Base grammar + +This is what ships with the extension. + +### Nodes + +- QUE - Question +- CLM - Claim +- EVD - Evidence +- Source + +### Relations + +- EVD Informs QUE +- EVD Supports CLM +- EVD Opposes CLM + +Motivation for this base grammar is described in this [article](https://oasislab.pubpub.org/pub/54t0y9mk/release/3). + +This base grammar may be most useful for projects that interact with empirical evidence where you want to clearly distinguish between theory and evidence, and retain provenance to the source citations if you want to get more context. diff --git a/apps/website/app/(docs)/docs/roam/pages/creating-discourse-nodes.md b/apps/website/app/(docs)/docs/roam/pages/creating-discourse-nodes.md new file mode 100644 index 000000000..9a7665740 --- /dev/null +++ b/apps/website/app/(docs)/docs/roam/pages/creating-discourse-nodes.md @@ -0,0 +1,16 @@ +--- +title: "Creating Discourse Nodes" +date: "2025-01-01" +author: "" +published: true +--- + +The extension makes it easy to factor parts of your notes into formal of a discourse graph (claims, evidence, etc.). + +Simply select the text you want to turn into a formal discourse graph node (e.g., QUE, CLM, EVD), then press hotkey (default is `\`, but you can edit this in the extension config page) to open up the refactor menu, and press appropriate shortcut key (e.g., E for evidence); system will create new page with the text as title and appropriate metadata and boilerplate sections. + +Demo: + +You can customize templates for nodes in the config page for the node. It is in the name space `discourse-graph/nodes/NameOfNode`. For example, here is the config page for the stock evidence node, and its template: + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252FVtjFJyQV46XaLExTCoU9%252FCleanShot%25202022-03-09%2520at%252023.40.33.png%3Falt%3Dmedia%26token%3D51697e02-3334-4661-9cec-5c2ab50dd1ac&width=300&dpr=4&quality=100&sign=a6b14d76&sv=2) diff --git a/apps/website/app/(docs)/docs/roam/pages/creating-discourse-relationships.md b/apps/website/app/(docs)/docs/roam/pages/creating-discourse-relationships.md new file mode 100644 index 000000000..c86b6d0ca --- /dev/null +++ b/apps/website/app/(docs)/docs/roam/pages/creating-discourse-relationships.md @@ -0,0 +1,70 @@ +--- +title: "Creating Discourse Relationships" +date: "2025-01-01" +author: "" +published: true +--- + +**You can create formal discourse relations between nodes by writing and outlining!** + +The extension has an in-built [grammar](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/fundamentals/the-discourse-graph-extension-grammar) that enables it to recognize when certain patterns of writing and outlining are meant to express particular discourse relations (e.g., support, oppose, inform) between discourse nodes. When it recognizes these patterns, it "writes" them to a formal discourse graph data structure, that you can then use to explore or query your discourse graph. + +## Basic "stock" patterns + +The extension ships with the ability to recognize three such writing/outlining patterns. Give them a try! + +### Question informed by Evidence + +Go into a question page. + +Create a block, and reference an evidence page. + +Like this: + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252FH9gwHdsH7oYG8Qm2fe93%252FCleanShot%25202022-03-26%2520at%252021.57.06.png%3Falt%3Dmedia%26token%3D474cf30c-7948-4edc-900d-31538d8b4a14&width=768&dpr=4&quality=100&sign=f79abb8f&sv=2) + +The system now formally recognizes that this piece of evidence **informs** the question (and equivalently, the question is **informed by** that evidence)! + +You can verify this by checking the [discourse context](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/exploring-your-discourse-graph/discourse-context) of the question or the evidence page. + +Or by running a [query](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/querying-your-discourse-graph) for evidence that informs that question. + +### Claim supported by Evidence + +Create a block anywhere, and reference a claim page. We'll call this the claim block. + +Indent a block underneath the claim block. And reference the page `[[SupportedBy]]`. We'll call this the connecting block. + +Indent a block underneath the connecting block. And reference an evidence page. + +Like this: + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252FnoU9ZujGFPHYMuuaNTJt%252FCleanShot%25202022-03-26%2520at%252021.57.25.png%3Falt%3Dmedia%26token%3Db25c32a8-5371-4b6b-b283-17c5247db532&width=768&dpr=4&quality=100&sign=24d67ba2&sv=2) + +The system now formally recognizes that this piece of evidence **supports** that claim (and equivalently, the claim is **supported by** that evidence)! + +You can verify this by checking the [discourse context](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/exploring-your-discourse-graph/discourse-context) of the claim or the evidence page. + +Or by running a [query](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/querying-your-discourse-graph) for evidence that supports that claim. + +### Claim opposed by Evidence + +Create a block anywhere, and reference a claim page. We'll call this the claim block. + +Indent a block underneath the claim block. And reference the page `[[OpposedBy]]`. We'll call this the connecting block. + +Indent a block underneath the connecting block. And reference an evidence page. + +Like this: + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252Fl31B28XNlmjDwPamERlE%252FCleanShot%25202022-03-26%2520at%252021.57.49.png%3Falt%3Dmedia%26token%3De7737f12-27b3-4ff8-aa67-93b682f88f05&width=768&dpr=4&quality=100&sign=c0d24cae&sv=2) + +The system now formally recognizes that this piece of evidence **opposes** that claim (and equivalently, the claim is **opposed by** that evidence)! + +You can verify this by checking the [discourse context](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/exploring-your-discourse-graph/discourse-context) of the claim or the evidence page. + +Or by running a [query](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/querying-your-discourse-graph) for evidence that supports that claim + +## Digging deeper + +Want to recognize other patterns that aren't listed here? Or don't like these? You can [change them](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/extending-and-personalizing-your-discourse-graph)! But you might first want to [understand how the grammar works](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/fundamentals/the-discourse-graph-extension-grammar). diff --git a/apps/website/app/(docs)/docs/roam/pages/enhanced-zettelkasten.md b/apps/website/app/(docs)/docs/roam/pages/enhanced-zettelkasten.md new file mode 100644 index 000000000..9b5a7317a --- /dev/null +++ b/apps/website/app/(docs)/docs/roam/pages/enhanced-zettelkasten.md @@ -0,0 +1,10 @@ +--- +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. The process is explained in great detail in his course: [https://www.academicmasterywithroam.com/](https://www.academicmasterywithroam.com/) + +Here is a video overview: diff --git a/apps/website/app/(docs)/docs/roam/pages/exploring-discourse-graph.md b/apps/website/app/(docs)/docs/roam/pages/exploring-discourse-graph.md new file mode 100644 index 000000000..01e31e0fc --- /dev/null +++ b/apps/website/app/(docs)/docs/roam/pages/exploring-discourse-graph.md @@ -0,0 +1,8 @@ +--- +title: "Exploring Discourse Graph" +date: "2025-01-01" +author: "" +published: true +--- + +The extension adds features to enable you to seamlessly explore your discourse graph to enhance your thinking. diff --git a/apps/website/app/(docs)/docs/roam/pages/extending-personalizing-graph.md b/apps/website/app/(docs)/docs/roam/pages/extending-personalizing-graph.md new file mode 100644 index 000000000..78ecf2f3c --- /dev/null +++ b/apps/website/app/(docs)/docs/roam/pages/extending-personalizing-graph.md @@ -0,0 +1,20 @@ +--- +title: "Extending and Personalizing Discourse Graph" +date: "2025-01-01" +author: "" +published: true +--- + +You can define new nodes and relation patterns to fit your own needs! + +Some users have extended the grammar quite extensively! + +For example, here is a video from a user who extended the grammar to cover structured international law research: + +Others have also extended the grammar to integrate with their primary results from their own experiments, to richly contextualize each new result and experiment with questions shared with past research. + +Detailed instructions coming soon! + +For now, here is a quick demo video of creating an incredibly useful "consistent with" relation pattern that recognizes when any pair of evidence both supports the same thing, implying that they are consistent with each other. + +To extend the grammar, it will likely be useful to [learn more about the fundamentals of the extension's grammar and how it works](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/fundamentals/the-discourse-graph-extension-grammar). diff --git a/apps/website/app/(docs)/docs/roam/pages/extension-grammar.md b/apps/website/app/(docs)/docs/roam/pages/extension-grammar.md new file mode 100644 index 000000000..f90630982 --- /dev/null +++ b/apps/website/app/(docs)/docs/roam/pages/extension-grammar.md @@ -0,0 +1,27 @@ +--- +title: "Extension Grammar" +date: "2025-01-01" +author: "" +published: true +--- + +The basic technical intuition behind the extension is that it creates a mapping between the following two elements: + +- **Human-readable, natural writing patterns in Roam**, such as pages, blocks, page/block references, and indentation +- **Discourse graph nodes and relations**, such as questions, claims, evidence, and relations like support/oppose/inform + +This works because writing in Roam is instantiated as transactions on an underlying [Datomic](https://docs.datomic.com/cloud/whatis/data-model.html) database, queryable via [the Datomic dialect of Datalog](http://www.learndatalogtoday.org/). At it's most basic level, the extension's discourse graph grammar is defined in terms of higher-order combinations of Datalog queries. + +The purpose of this mapping is to make it possible to write and outline as naturally as possible, to help your own thinking, and then have the extension [_recognize_](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/creating-discourse-relationships) (and "make real") the important relationships in your thinking that you have specified, so you and others can build on it in the near or later future as you continue your work. + +For this reason, if you want to better understand how the extension works, and especially if you want to [extend or customize its grammar](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/extending-and-personalizing-your-discourse-graph), it is very useful to get a robust intuition for how Datomic and Datalog work. + +Here are two helpful entry points for this: + +## Relation grammar building blocks + +[Nodes](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/fundamentals/the-discourse-graph-extension-grammar/nodes) + +### Operators/relations + +## Examples diff --git a/apps/website/app/(docs)/docs/roam/pages/getting-started.md b/apps/website/app/(docs)/docs/roam/pages/getting-started.md new file mode 100644 index 000000000..4592fdfea --- /dev/null +++ b/apps/website/app/(docs)/docs/roam/pages/getting-started.md @@ -0,0 +1,26 @@ +--- +title: "Getting Started" +date: "2025-01-01" +author: "" +published: true +--- + +The Discourse Graph extension enables [Roam](https://roamresearch.com/) users to seamlessly add additional semantic structure to their notes, including specified page types and link types that [model scientific discourse](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/fundamentals/what-is-a-discourse-graph), to enable more complex and structured [knowledge synthesis work](https://oasislab.pubpub.org/pub/54t0y9mk/release/3), such as a complex interdisciplinary literature review, and enhanced collaboration with others on this work. + +## Overview + +Here is a relatively brief walkthrough of some of the main features of the extension, including creating discourse nodes and relations, and [using](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/exploring-your-discourse-graph), [querying](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/querying-your-discourse-graph), and [sharing](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/sharing-your-discourse-graph) the discourse graph. This is done in the context of an actual ongoing literature review. + +[https://www.loom.com/share/2ec80422301c451b888b65ee1d283b40](https://www.loom.com/share/2ec80422301c451b888b65ee1d283b40) + +## Guides: Jump right in + +Follow our handy guides to get started on the basics as quickly as possible: + +[Creating discourse nodes](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/creating-discourse-nodes)[Creating discourse relationships](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/creating-discourse-relationships)[Exploring your discourse graph](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/exploring-your-discourse-graph)[Querying your discourse graph](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/querying-your-discourse-graph)[Extending and personalizing your discourse graph](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/extending-and-personalizing-your-discourse-graph) + +## Fundamentals: Dive a little deeper + +Learn the fundamentals of the Discourse Graph extension to get a deeper understanding of our main features: + +[What is a Discourse Graph?](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/fundamentals/what-is-a-discourse-graph)[The Base Grammar: Questions, Claims, and Evidence](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/fundamentals/the-base-grammar-questions-claims-and-evidence)[The Discourse Graph Extension Grammar](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/fundamentals/the-discourse-graph-extension-grammar)[Graph Querying](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/fundamentals/graph-querying) diff --git a/apps/website/app/(docs)/docs/roam/pages/installation.md b/apps/website/app/(docs)/docs/roam/pages/installation.md new file mode 100644 index 000000000..167f62a4e --- /dev/null +++ b/apps/website/app/(docs)/docs/roam/pages/installation.md @@ -0,0 +1,30 @@ +--- +title: "Installation" +date: "2025-01-01" +author: "" +published: true +--- + +Discourse Graphs is part of the Query Builder extension. + +## Install Query Builder + +The Query Builder extension can be installed via Roam Depot: + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252FAzY9vJSZTuGvcvel0keH%252Fimage.png%3Falt%3Dmedia%26token%3Dbaa295ae-c81f-4510-b7d1-a3488788bdc5&width=768&dpr=4&quality=100&sign=b11ce2d2&sv=2) + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252FmmmTzLMWGTgDJOJgtT1u%252Fimage.png%3Falt%3Dmedia%26token%3D4ebcaefc-2abf-4ec9-8eb6-d65fa5d0f8a2&width=768&dpr=4&quality=100&sign=160f39d4&sv=2) + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252FDjxPKeZjQvEvcpwqyY26%252Fimage.png%3Falt%3Dmedia%26token%3D2935e5ae-074c-4ff5-be7e-c52f7d2e0fe1&width=768&dpr=4&quality=100&sign=17dbe2fd&sv=2) + +### Toggle Discourse Graphs + +After you have installed the Query Builder extension, scroll down to the `Discourse Graphs` toggle and switch it to `on`: + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252FeIvW0Cm3pvjg3Mc3xCLY%252Fimage.png%3Falt%3Dmedia%26token%3D21de463b-6b2f-4c2b-8934-24a8e85cc7c8&width=768&dpr=4&quality=100&sign=e28e052f&sv=2) + +### Verify + +You can verify that it was successful by navigating to `roam/js/discourse-graph` and you should see a configuration panel like this: + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252FohBj0cjCyYHZydSi6fB2%252Fimage.png%3Falt%3Dmedia%26token%3Dad15ee6d-eb7d-4f7c-9f82-d658bfa6f0e4&width=768&dpr=4&quality=100&sign=37bbc344&sv=2) diff --git a/apps/website/app/(docs)/docs/roam/pages/lab-notebooks.md b/apps/website/app/(docs)/docs/roam/pages/lab-notebooks.md new file mode 100644 index 000000000..892fd78c5 --- /dev/null +++ b/apps/website/app/(docs)/docs/roam/pages/lab-notebooks.md @@ -0,0 +1,8 @@ +--- +title: "Lab Notebooks" +date: "2025-01-01" +author: "" +published: true +--- + +Description coming soon! diff --git a/apps/website/app/(docs)/docs/roam/pages/literature-reviewing.md b/apps/website/app/(docs)/docs/roam/pages/literature-reviewing.md new file mode 100644 index 000000000..7e50c3a55 --- /dev/null +++ b/apps/website/app/(docs)/docs/roam/pages/literature-reviewing.md @@ -0,0 +1,14 @@ +--- +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 diff --git a/apps/website/app/(docs)/docs/roam/pages/querying-discourse-graph.md b/apps/website/app/(docs)/docs/roam/pages/querying-discourse-graph.md new file mode 100644 index 000000000..cbcceac1c --- /dev/null +++ b/apps/website/app/(docs)/docs/roam/pages/querying-discourse-graph.md @@ -0,0 +1,100 @@ +--- +title: "Querying Discourse Graph" +date: "2025-01-01" +author: "" +published: true +--- + +**Note: a lot of the querying functionality overlaps with the RoamJS query-builder extension, which was spun off from this extension. You might find the documentation for the query-builder helpful for learning how to run queries:** [**https://roamjs.com/extensions/query-builder**](https://roamjs.com/extensions/query-builder) + +The query drawer component allows you to construct structured queries over your discourse graph, based on discourse relations (e.g., "find all evidence that supports/opposes a claim"), and reason over the results in a structured, tabular format (e.g., "find all evidence that supports a claim, and allow me to filter/sort by methodological details"). + +## Quick demo + +Demo of query drawer (\*slightly\* different version from latest version, so some details of the results table are different) + +## Making a query + +Use Command Palette (⌘+`P` on Mac,`CTRL`\+ `P` otherwise) to access the query drawer. + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252FucIbbRPFNErjWmvUWsuT%252FCleanShot%25202022-04-01%2520at%252021.40.17.png%3Falt%3Dmedia%26token%3D2081a074-7427-4f64-b16c-4698a7eb9d6b&width=768&dpr=4&quality=100&sign=359890e5&sv=2) + +A query drawer component will open from the left. From there, you can construct structured queries of your discourse graph and explore their results in a tabular format. + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252F0ftjk5RTY8KpVYbns7rr%252FCleanShot%25202022-04-01%2520at%252021.41.02%25402x.png%3Falt%3Dmedia%26token%3D2ae6c4a2-17bd-4462-a9ae-bf8ff92f5e14&width=768&dpr=4&quality=100&sign=7f5d3bfc&sv=2) + +## Some common queries + +### Find all evidence that informs a question + +Example query: + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252FMWPf303ozAs41sTKodVa%252FCleanShot%25202022-04-01%2520at%252023.47.35%25402x.png%3Falt%3Dmedia%26token%3Dec9f20f3-e52d-449a-80e7-89fd7df4b1d9&width=768&dpr=4&quality=100&sign=ce3c3b67&sv=2) + +The results: + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252FyIqwgNmXBxP3aAo25S27%252FCleanShot%25202022-04-01%2520at%252023.47.58%25402x.png%3Falt%3Dmedia%26token%3Ddd3d81c0-45dd-4616-8eff-9e054c341048&width=768&dpr=4&quality=100&sign=ecdda401&sv=2) + +### Find all evidence that supports a claim + +Example query: + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252Fw1xCMcFkXYbE1odWP9j9%252FCleanShot%25202022-04-01%2520at%252023.52.11%25402x.png%3Falt%3Dmedia%26token%3D52753a1f-6438-4a09-9843-a885416cc7f2&width=768&dpr=4&quality=100&sign=ee71f061&sv=2) + +The results: + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252FrFnJ4GSZeVZkSfi8DDrK%252FCleanShot%25202022-04-01%2520at%252023.51.39%25402x.png%3Falt%3Dmedia%26token%3D8a060fbb-f01a-40ab-90a5-d996121df562&width=768&dpr=4&quality=100&sign=c0d223d9&sv=2) + +## More advanced queries + +### Mix discourse and Roam queries + +Example: find all evidence that informs a question, but only if it was collected in a specific location (this example assumes at least some evidence pages have an attribute `Location::` in them) + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252FPu1P09mHjDgubm8nWWpa%252FCleanShot%25202022-04-01%2520at%252023.57.43%25402x.png%3Falt%3Dmedia%26token%3D8bf2b34e-bd79-4b94-8580-18e853ca4e14&width=768&dpr=4&quality=100&sign=9038a27d&sv=2) + +Results: + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252F3vnWb4zgfB7NrFZ3AYep%252FCleanShot%25202022-04-01%2520at%252023.58.22%25402x.png%3Falt%3Dmedia%26token%3D89a352ad-962d-42e5-8e54-0f0bb5b2975e&width=768&dpr=4&quality=100&sign=37530e8a&sv=2) + +### Select node attributes to display as attributes of results + +Example: find all evidence that informs a question, and select a methods attribute to display so we can sort/filter on it (this example assumes at least some evidence pages have an attribute `testingRegime::` in them) + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252F7ERzj7j5oAMulB17cxlk%252FCleanShot%25202022-04-02%2520at%252000.01.04%25402x.png%3Falt%3Dmedia%26token%3Da2fc92ab-5b23-4edd-b5df-b2d9377fab29&width=768&dpr=4&quality=100&sign=ee53e213&sv=2) + +Results (note: will display "blank" for nodes that lack values for the selected attribute): + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252FPU6YbIdMzPXDfnaFej2o%252FCleanShot%25202022-04-02%2520at%252000.01.22%25402x.png%3Falt%3Dmedia%26token%3Db65b7d96-350b-47e9-8a16-4d790eda34b6&width=768&dpr=4&quality=100&sign=2e5f1335&sv=2) + +### Select discourse attributes to display as attributes of results + +If you have defined [Discourse attributes](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/exploring-your-discourse-graph/discourse-attributes) for the node you want to query, you can select it as a column in your query. The syntax for accessing a node's discourse attribute as a select is`discourse:discourseAttributeName`. + +Example: find all claims and display their "Evidence" discourse attributes (number of supporting evidence relations) as a column. + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252FUzAz2CnYbSbci32YaBHA%252FCleanShot%25202022-08-10%2520at%252009.33.43%25402x.png%3Falt%3Dmedia%26token%3D05d362c1-6552-4b3d-9ab6-d1f8bf18db99&width=768&dpr=4&quality=100&sign=778f57f7&sv=2) + +Results: + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252FzIeU4A2XkolPEFvMfacU%252FCleanShot%25202022-08-10%2520at%252009.34.36%25402x.png%3Falt%3Dmedia%26token%3Dc5207e94-958d-4418-8d86-a0bcc0097a06&width=768&dpr=4&quality=100&sign=9009f1e5&sv=2) + +## Sorting/filtering a query's results + +You can filter and sort each column in the results table. + +## Naming a query + +You can name a query if you like! + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252FEoHEpmInyUdsPgSm3bxE%252Frename-query.gif%3Falt%3Dmedia%26token%3Db28406d0-2bc7-456e-a220-cfd644903874&width=768&dpr=4&quality=100&sign=9e54fc7a&sv=2) + +## Saving a query to its own page + +You can save a query to its own page if you want to keep it around for easier access. + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252F45Ncnv88iwpyAGPXnFbl%252FCleanShot%25202022-04-02%2520at%252000.14.15%25402x.png%3Falt%3Dmedia%26token%3D9fc84685-d724-4c87-92c5-7e2810ccf66a&width=300&dpr=4&quality=100&sign=2d2a2f45&sv=2) + +It will be saved to the namespace `discourse-graph/queries/` + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252FIMylaMmqdnLkkD0BKC93%252FCleanShot%25202022-04-02%2520at%252000.16.26%25402x.png%3Falt%3Dmedia%26token%3D52119802-c613-419b-8f1f-de5896d08f29&width=768&dpr=4&quality=100&sign=5d13a33a&sv=2) diff --git a/apps/website/app/(docs)/docs/roam/pages/reading-clubs.md b/apps/website/app/(docs)/docs/roam/pages/reading-clubs.md new file mode 100644 index 000000000..22f945120 --- /dev/null +++ b/apps/website/app/(docs)/docs/roam/pages/reading-clubs.md @@ -0,0 +1,10 @@ +--- +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/app/(docs)/docs/roam/pages/research-roadmapping.md b/apps/website/app/(docs)/docs/roam/pages/research-roadmapping.md new file mode 100644 index 000000000..293bbeafc --- /dev/null +++ b/apps/website/app/(docs)/docs/roam/pages/research-roadmapping.md @@ -0,0 +1,8 @@ +--- +title: "Research Roadmapping" +date: "2025-01-01" +author: "" +published: true +--- + +Description coming soon! diff --git a/apps/website/app/(docs)/docs/roam/pages/sharing-discourse-graph.md b/apps/website/app/(docs)/docs/roam/pages/sharing-discourse-graph.md new file mode 100644 index 000000000..2bf7e48b3 --- /dev/null +++ b/apps/website/app/(docs)/docs/roam/pages/sharing-discourse-graph.md @@ -0,0 +1,40 @@ +--- +title: "Sharing Discourse Graph" +date: "2025-01-01" +author: "" +published: true +--- + +You can export your discourse graph as a whole, or from queries of your graph, to archive your most important notes, or share them with others. + +The extension exports to 1) markdown, 2) csv (neo4j-compatible [labeled property graph](https://neo4j.com/blog/rdf-triple-store-vs-labeled-property-graph-difference/)), and 3) `json` + +Demo: + +## Markdown export options + +Since markdown has different flavors, and different tools you might want to export/archive your notes to handle links differently (e.g., wikilinks vs. markdown links) and different operating systems have different filename limitations, we have a range of options for customizing the markdown export. These can be found on the `Export` tab of the discourse graph configuration in `roam/js/discourse-graph`. + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252FwN1ubNMnOFHwHMP9Oskb%252FCleanShot%25202022-08-10%2520at%252010.03.33%25402x.png%3Falt%3Dmedia%26token%3Df77df57e-519f-498e-9294-b478fb8990bc&width=768&dpr=4&quality=100&sign=5978d0a8&sv=2) + +Here is a brief explanation of each option: + +- `Max Filename Length` sets the maximum length of the filenames; this is important if you have page names that are quite long and may run afoul of, say, Windows' filename length limit of 250-260 characters. +- `Remove Special Characters` removes all "special characters" that may lead to trouble for filenames in different operating systems, such as `?` (not allowed on Windows) or `/` (denotes file/folder boundaries). +- `Simplified Filename` strips away all "template" characters (i.e., everything except the `{content}` in the node format: for example, if you define a Claim node as `[[CLM]] - {content}`, and have a Claim node `[[[[CLM]] - people are lazy]]`, the exported filename will be `people are lazy` +- `Frontmatter` specifies what properties to add to the YAML. + + - By default, the properties are: + + - `title: {text}` + - `author: {author}` + - `date: {date}` + + - You can add properties as key-value pairs in the same format: + + - ![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252FOnl6Zd8Ej0Z3DLnwI66H%252FCleanShot%25202022-08-10%2520at%252010.11.22.gif%3Falt%3Dmedia%26token%3D313669a2-77cc-4c57-b5aa-5b202c237d90&width=300&dpr=4&quality=100&sign=4cf91&sv=2) + +- `Resolve Block References` and `Resolve Block Embeds` control whether you want to resolve block references/embeds in your export. You can keep this turned off if you are unsure of the privacy implications of references/embeds. +- Link Type controls whether inline page references are wikilinks (`[[like this]]`) or alias (`[like this](pageName.md)`) + +Here is an example of a discourse graph exported to Obsidian-compatible markdown: [https://publish.obsidian.md/joelchan-notes](https://publish.obsidian.md/joelchan-notes) diff --git a/apps/website/app/(docs)/docs/roam/pages/what-is-discourse-graph.md b/apps/website/app/(docs)/docs/roam/pages/what-is-discourse-graph.md new file mode 100644 index 000000000..83932635f --- /dev/null +++ b/apps/website/app/(docs)/docs/roam/pages/what-is-discourse-graph.md @@ -0,0 +1,20 @@ +--- +title: "What is Discourse Graph" +date: "2025-01-01" +author: "" +published: true +--- + +**Discourse graphs** are an information model for bodies of knowledge that emphasize discourse moves (such as questions, claims, and evidence), and relations (such as support or opposition), rather than papers or sources as the main units. + +To give an intuition for what it is, here is a figure of a visual representation of a simple discourse graph for a body of literature on bans and antisocial behavior in online forums. You may recognize similarities to things like argument maps. + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252FYK0h2xFxWruVPgyYj9bb%252FCleanShot%25202022-03-10%2520at%252010.28.22.png%3Falt%3Dmedia%26token%3D8a1e6a71-f99c-43b3-82a4-1130f0150988&width=768&dpr=4&quality=100&sign=52a73624&sv=2) + +Consider how that information model foregrounds the conceptual building blocks and relationships that are important for synthesis, compared to a typical "[iTunes for papers](http://joelchan.me/assets/pdf/2019-cscw-beyond-itunes-for-papers.pdf)" model that foregrounds documents in a way that forces us to drudge through [tedious extraction work](https://dl.acm.org/doi/abs/10.1145/3295750.3298937) before we can do the thinking we want to do! + +![](https://oasis-lab.gitbook.io/~gitbook/image?url=https%3A%2F%2F3894211722-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FVpoqQNZpk4qG2nMcQUaw%252Fuploads%252FypWrTlPQrMw961IPBiAM%252FCleanShot%25202022-03-10%2520at%252010.30.21.png%3Falt%3Dmedia%26token%3D2df9644a-9e4c-4764-b5a1-7c69a597aa37&width=768&dpr=4&quality=100&sign=c0668245&sv=2) + +This information model (theoretically!) has high potential for augmenting individual and collective "research-grade" synthesis (e.g., lit reviews for a dissertation or grant proposal). + +Discourse graphs are not a new idea (you can read more about it in [this short (academic-focused) write-up](http://joelchan.me/assets/pdf/Discourse_Graphs_for_Augmented_Knowledge_Synthesis_What_and_Why.pdf) or this more [practically-oriented article](https://oasislab.pubpub.org/pub/54t0y9mk/release/3)), but the potential to use it for everyday research work is! diff --git a/apps/website/app/(docs)/layout.tsx b/apps/website/app/(docs)/layout.tsx new file mode 100644 index 000000000..727b878ff --- /dev/null +++ b/apps/website/app/(docs)/layout.tsx @@ -0,0 +1,39 @@ +import { type Metadata } from "next"; +import { Inter } from "next/font/google"; + +import clsx from "clsx"; + +import { DESCRIPTION } from "~/(home)/layout"; +import { customScrollbar } from "~/components/Layout"; + +const inter = Inter({ + subsets: ["latin"], + display: "swap", + variable: "--font-inter", +}); + +export const metadata: Metadata = { + title: { + template: "%s - Docs", + default: "Discourse Graphs - Documentation", + }, + description: DESCRIPTION, +}; + +export default function RootLayout({ + children, +}: { + children: React.ReactNode; +}) { + return ( + + + {children} + + + ); +} diff --git a/apps/website/app/blog/[slug]/page.tsx b/apps/website/app/(home)/blog/[slug]/page.tsx similarity index 100% rename from apps/website/app/blog/[slug]/page.tsx rename to apps/website/app/(home)/blog/[slug]/page.tsx diff --git a/apps/website/app/blog/page.tsx b/apps/website/app/(home)/blog/page.tsx similarity index 100% rename from apps/website/app/blog/page.tsx rename to apps/website/app/(home)/blog/page.tsx diff --git a/apps/website/app/(home)/blog/posts/EXAMPLE copy.md b/apps/website/app/(home)/blog/posts/EXAMPLE copy.md new file mode 100644 index 000000000..196676e3e --- /dev/null +++ b/apps/website/app/(home)/blog/posts/EXAMPLE copy.md @@ -0,0 +1,33 @@ +--- +title: "Example Post - How to Create Blog Posts" +date: "2024-01-01" +author: "Devs" +published: true # Set to true to make this post visible +--- + +# How to Create Blog Posts + +This is a template post that shows how to create new blog posts. Keep this file as a reference and create new posts by following these instructions. + +### Creating Blog Posts + +1. [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) and [clone](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) the repository. +2. [Create a new branch](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/managing-branches) for your update. +3. Copy this file (`EXAMPLE.md`) to create a new post +4. Rename the file to your desired URL slug (e.g., `my-new-post.md`) +5. Update the frontmatter and content +6. Set `published: true` when ready +7. Push your branch and open a pull request. πŸš€ + +### Required Frontmatter + +Every post must start with frontmatter in YAML format: + +```yaml +--- +title: "Your Post Title" +date: "YYYY-MM-DD" +author: "Author's name" +published: true # Set to true to make the post visible +--- +``` diff --git a/apps/website/app/blog/posts/EXAMPLE.md b/apps/website/app/(home)/blog/posts/EXAMPLE.md similarity index 100% rename from apps/website/app/blog/posts/EXAMPLE.md rename to apps/website/app/(home)/blog/posts/EXAMPLE.md diff --git a/apps/website/app/(home)/blog/posts/welcome.md b/apps/website/app/(home)/blog/posts/welcome.md new file mode 100644 index 000000000..40d344a2f --- /dev/null +++ b/apps/website/app/(home)/blog/posts/welcome.md @@ -0,0 +1,26 @@ +--- +title: "Welcome to the Discourse Graphs Documentation" +date: "2024-01-01" +author: "" +published: true +--- + +The Discourse Graph extension enables [Roam](https://roamresearch.com/) users to seamlessly add additional semantic structure to their notes, including specified page types and link types that [model scientific discourse](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/fundamentals/what-is-a-discourse-graph), to enable more complex and structured [knowledge synthesis work](https://oasislab.pubpub.org/pub/54t0y9mk/release/3), such as a complex interdisciplinary literature review, and enhanced collaboration with others on this work. + +## Overview + +Here is a relatively brief walkthrough of some of the main features of the extension, including creating discourse nodes and relations, and [using](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/exploring-your-discourse-graph), [querying](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/querying-your-discourse-graph), and [sharing](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/sharing-your-discourse-graph) the discourse graph. This is done in the context of an actual ongoing literature review. + +[https://www.loom.com/share/2ec80422301c451b888b65ee1d283b40](https://www.loom.com/share/2ec80422301c451b888b65ee1d283b40) + +## Guides: Jump right in + +Follow our handy guides to get started on the basics as quickly as possible: + +[Creating discourse nodes](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/creating-discourse-nodes)[Creating discourse relationships](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/creating-discourse-relationships)[Exploring your discourse graph](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/exploring-your-discourse-graph)[Querying your discourse graph](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/querying-your-discourse-graph)[Extending and personalizing your discourse graph](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/guides/extending-and-personalizing-your-discourse-graph) + +## Fundamentals: Dive a little deeper + +Learn the fundamentals of the Discourse Graph extension to get a deeper understanding of our main features: + +[What is a Discourse Graph?](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/fundamentals/what-is-a-discourse-graph)[The Base Grammar: Questions, Claims, and Evidence](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/fundamentals/the-base-grammar-questions-claims-and-evidence)[The Discourse Graph Extension Grammar](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/fundamentals/the-discourse-graph-extension-grammar)[Graph Querying](https://oasis-lab.gitbook.io/roamresearch-discourse-graph-extension/fundamentals/graph-querying) diff --git a/apps/website/app/blog/readBlogs.tsx b/apps/website/app/(home)/blog/readBlogs.tsx similarity index 66% rename from apps/website/app/blog/readBlogs.tsx rename to apps/website/app/(home)/blog/readBlogs.tsx index bfaeb3bae..6ea5660c9 100644 --- a/apps/website/app/blog/readBlogs.tsx +++ b/apps/website/app/(home)/blog/readBlogs.tsx @@ -1,12 +1,16 @@ -import { remark } from "remark"; -import html from "remark-html"; +import { unified } from "unified"; +import remarkParse from "remark-parse"; +import remarkRehype from "remark-rehype"; +import rehypeStringify from "rehype-stringify"; +import { toString } from "mdast-util-to-string"; +import { visit } from "unist-util-visit"; import { notFound } from "next/navigation"; import path from "path"; import fs from "fs/promises"; import matter from "gray-matter"; import { BlogSchema, type Blog, BlogFrontmatter } from "./schema"; -const BLOG_DIRECTORY = path.join(process.cwd(), "app/blog/posts"); +const BLOG_DIRECTORY = path.join(process.cwd(), "app/(home)/blog/posts"); async function validateBlogDirectory(): Promise { try { @@ -35,8 +39,31 @@ async function processBlogFile(filename: string): Promise { } } +function remarkHeadingId() { + return (tree: any) => { + visit(tree, "heading", (node) => { + const text = toString(node); + const id = text + .toLowerCase() + .replace(/[^a-z0-9]+/g, "-") + .replace(/(^-|-$)/g, ""); + + node.data = { + hName: `h${node.depth}`, + hProperties: { id }, + }; + }); + }; +} + async function getMarkdownContent(content: string): Promise { - const processedContent = await remark().use(html).process(content); + const processedContent = await unified() + .use(remarkParse) + .use(remarkHeadingId) + .use(remarkRehype) + .use(rehypeStringify) + .process(content); + console.log(processedContent.toString()); return processedContent.toString(); } @@ -57,11 +84,21 @@ export async function getAllBlogs(): Promise { } } +export async function getFileContent( + filename: string, + directory: string, +): Promise { + const filePath = path.join(directory, filename); + const fileContent = await fs.readFile(filePath, "utf-8"); + return fileContent; +} + export async function getBlog( slug: string, + directory: string = BLOG_DIRECTORY, ): Promise<{ data: BlogFrontmatter; contentHtml: string }> { try { - const filePath = path.join(BLOG_DIRECTORY, `${slug}.md`); + const filePath = path.join(directory, `${slug}.md`); await fs.access(filePath); const fileContent = await fs.readFile(filePath, "utf-8"); diff --git a/apps/website/app/blog/schema.tsx b/apps/website/app/(home)/blog/schema.tsx similarity index 100% rename from apps/website/app/blog/schema.tsx rename to apps/website/app/(home)/blog/schema.tsx diff --git a/apps/website/app/layout.tsx b/apps/website/app/(home)/layout.tsx similarity index 70% rename from apps/website/app/layout.tsx rename to apps/website/app/(home)/layout.tsx index 1a3b8db02..5a27f34b1 100644 --- a/apps/website/app/layout.tsx +++ b/apps/website/app/(home)/layout.tsx @@ -1,24 +1,29 @@ import type { Metadata } from "next"; -import "./globals.css"; -import { PostHogProvider } from "./providers"; +import "~/globals.css"; +import { PostHogProvider } from "~/providers"; import Link from "next/link"; -import Image from "next/image"; import { Inter } from "next/font/google"; import { getAllBlogs } from "./blog/readBlogs"; +import { Logo } from "~/components/Logo"; + +export const DESCRIPTION = + "Discourse Graphs are a tool and ecosystem for collaborative knowledge synthesis, enabling researchers to map ideas and arguments in a modular, composable graph format."; +export const SHORT_DESCRIPTION = + "A tool and ecosystem for collaborative knowledge synthesis"; export const metadata: Metadata = { title: "Discourse Graphs | A Tool for Collaborative Knowledge Synthesis", - description: - "Discourse Graphs are a tool and ecosystem for collaborative knowledge synthesis, enabling researchers to map ideas and arguments in a modular, composable graph format.", + description: DESCRIPTION, + openGraph: { title: "Discourse Graphs", - description: "A tool and ecosystem for collaborative knowledge synthesis", + description: SHORT_DESCRIPTION, type: "website", }, twitter: { card: "summary_large_image", title: "Discourse Graphs", - description: "A tool and ecosystem for collaborative knowledge synthesis", + description: SHORT_DESCRIPTION, }, }; @@ -38,18 +43,7 @@ export default async function RootLayout({ className={`flex min-h-screen flex-col bg-neutral-light ${inter.className}`} >
- - Discourse Graphs Logo - - - Discourse Graphs - - +