From da0747ada8db141edc8932b8613ca6b54498735b Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Mon, 30 Mar 2026 15:28:23 -0600 Subject: [PATCH 01/14] Add documentation routing and layout for Roam and Obsidian (#928) - Introduced a new `docsRouteMap.ts` file to manage documentation sections and redirects for Roam and Obsidian platforms. - Updated `next.config.ts` to include dynamic redirects based on the new route map. - Refactored the layout components for documentation pages to utilize a consistent theme layout. - Removed outdated `page.tsx` files for Roam and Obsidian, replacing them with new landing pages that leverage Nextra for content rendering. - Added new metadata and content files for various documentation sections, enhancing the overall documentation structure and accessibility. --- .../app/(docs)/docs/(landing)/layout.tsx | 18 +++ .../app/(docs)/docs/(landing)/page.tsx | 47 ++++++ .../docs/_components/DocsThemeLayout.tsx | 44 +++++ .../docs/obsidian/[[...mdxPath]]/page.tsx | 76 +++++++++ .../app/(docs)/docs/obsidian/[slug]/page.tsx | 32 ---- .../app/(docs)/docs/obsidian/layout.tsx | 24 ++- .../website/app/(docs)/docs/obsidian/page.tsx | 6 - apps/website/app/(docs)/docs/page.tsx | 39 ----- .../(docs)/docs/roam/[[...mdxPath]]/page.tsx | 76 +++++++++ .../app/(docs)/docs/roam/[slug]/page.tsx | 33 ---- apps/website/app/(docs)/docs/roam/layout.tsx | 24 ++- apps/website/app/(docs)/docs/roam/page.tsx | 13 -- apps/website/app/(docs)/layout.tsx | 15 +- apps/website/app/components/Logo.tsx | 48 ++++-- apps/website/content/_meta.ts | 13 ++ apps/website/content/index.mdx | 29 ++++ apps/website/content/obsidian/_meta.ts | 16 ++ .../obsidian/advanced-features/_meta.ts | 8 + .../advanced-features/command-palette.md | 24 +++ .../advanced-features/sync-and-import.md | 151 ++++++++++++++++++ .../content/obsidian/configuration/_meta.ts | 9 ++ .../configuration/general-settings.md | 28 ++++ .../configuration/node-types-templates.md | 53 ++++++ .../configuration/relationship-types.md | 55 +++++++ .../content/obsidian/core-features/_meta.ts | 11 ++ .../content/obsidian/core-features/canvas.md | 150 +++++++++++++++++ .../core-features/creating-discourse-nodes.md | 58 +++++++ .../creating-discourse-relationships.md | 36 +++++ .../core-features/discourse-context.md | 44 +++++ .../obsidian/core-features/node-tags.md | 67 ++++++++ .../content/obsidian/fundamentals/_meta.ts | 8 + .../obsidian/fundamentals/base-grammar.md | 28 ++++ .../fundamentals/what-is-a-discourse-graph.md | 21 +++ apps/website/content/obsidian/index.mdx | 23 +++ .../content/obsidian/use-cases/_meta.ts | 10 ++ .../obsidian/use-cases/lab-notebooks.md | 9 ++ .../use-cases/literature-reviewing.md | 15 ++ .../obsidian/use-cases/reading-clubs.md | 11 ++ .../use-cases/research-roadmapping.md | 9 ++ .../website/content/obsidian/welcome/_meta.ts | 8 + .../obsidian/welcome/getting-started.md | 43 +++++ .../content/obsidian/welcome/installation.md | 45 ++++++ apps/website/content/roam/_meta.ts | 15 ++ .../content/roam/fundamentals/_meta.ts | 14 ++ .../content/roam/fundamentals/base-grammar.md | 28 ++++ .../content/roam/fundamentals/grammar.md | 16 ++ .../migration-to-stored-relations.md | 91 +++++++++++ .../content/roam/fundamentals/nodes.md | 23 +++ .../roam/fundamentals/operators-relations.md | 71 ++++++++ .../roam/fundamentals/relations-patterns.md | 54 +++++++ .../roam/fundamentals/stored-relations.md | 79 +++++++++ .../fundamentals/what-is-a-discourse-graph.md | 21 +++ apps/website/content/roam/guides/_meta.ts | 13 ++ .../roam/guides/creating-discourse-nodes.md | 25 +++ .../creating-discourse-relationships.md | 27 ++++ .../roam/guides/exploring-discourse-graph.md | 14 ++ .../guides/extending-personalizing-graph.md | 34 ++++ .../roam/guides/querying-discourse-graph.md | 67 ++++++++ .../roam/guides/sharing-discourse-graph.md | 61 +++++++ .../roam/guides/tagging-candidate-nodes.md | 42 +++++ apps/website/content/roam/index.mdx | 23 +++ apps/website/content/roam/use-cases/_meta.ts | 11 ++ .../roam/use-cases/enhanced-zettelkasten.md | 13 ++ .../content/roam/use-cases/lab-notebooks.md | 9 ++ .../roam/use-cases/literature-reviewing.md | 15 ++ .../content/roam/use-cases/reading-clubs.md | 11 ++ .../roam/use-cases/research-roadmapping.md | 9 ++ .../content/roam/views-and-tools/_meta.ts | 10 ++ .../views-and-tools/discourse-attributes.md | 66 ++++++++ .../discourse-context-overlay.md | 43 +++++ .../roam/views-and-tools/discourse-context.md | 26 +++ .../roam/views-and-tools/node-index.md | 18 +++ apps/website/content/roam/welcome/_meta.ts | 9 ++ .../content/roam/welcome/getting-started.md | 33 ++++ .../roam/welcome/installation-roam-depot.md | 15 ++ .../content/roam/welcome/installation.md | 15 ++ apps/website/docsRouteMap.ts | 82 ++++++++++ apps/website/next.config.ts | 8 +- 78 files changed, 2419 insertions(+), 169 deletions(-) create mode 100644 apps/website/app/(docs)/docs/(landing)/layout.tsx create mode 100644 apps/website/app/(docs)/docs/(landing)/page.tsx create mode 100644 apps/website/app/(docs)/docs/_components/DocsThemeLayout.tsx create mode 100644 apps/website/app/(docs)/docs/obsidian/[[...mdxPath]]/page.tsx delete mode 100644 apps/website/app/(docs)/docs/obsidian/[slug]/page.tsx delete mode 100644 apps/website/app/(docs)/docs/obsidian/page.tsx delete mode 100644 apps/website/app/(docs)/docs/page.tsx create mode 100644 apps/website/app/(docs)/docs/roam/[[...mdxPath]]/page.tsx delete mode 100644 apps/website/app/(docs)/docs/roam/[slug]/page.tsx delete mode 100644 apps/website/app/(docs)/docs/roam/page.tsx create mode 100644 apps/website/content/_meta.ts create mode 100644 apps/website/content/index.mdx create mode 100644 apps/website/content/obsidian/_meta.ts create mode 100644 apps/website/content/obsidian/advanced-features/_meta.ts create mode 100644 apps/website/content/obsidian/advanced-features/command-palette.md create mode 100644 apps/website/content/obsidian/advanced-features/sync-and-import.md create mode 100644 apps/website/content/obsidian/configuration/_meta.ts create mode 100644 apps/website/content/obsidian/configuration/general-settings.md create mode 100644 apps/website/content/obsidian/configuration/node-types-templates.md create mode 100644 apps/website/content/obsidian/configuration/relationship-types.md create mode 100644 apps/website/content/obsidian/core-features/_meta.ts create mode 100644 apps/website/content/obsidian/core-features/canvas.md create mode 100644 apps/website/content/obsidian/core-features/creating-discourse-nodes.md create mode 100644 apps/website/content/obsidian/core-features/creating-discourse-relationships.md create mode 100644 apps/website/content/obsidian/core-features/discourse-context.md create mode 100644 apps/website/content/obsidian/core-features/node-tags.md create mode 100644 apps/website/content/obsidian/fundamentals/_meta.ts create mode 100644 apps/website/content/obsidian/fundamentals/base-grammar.md create mode 100644 apps/website/content/obsidian/fundamentals/what-is-a-discourse-graph.md create mode 100644 apps/website/content/obsidian/index.mdx create mode 100644 apps/website/content/obsidian/use-cases/_meta.ts create mode 100644 apps/website/content/obsidian/use-cases/lab-notebooks.md create mode 100644 apps/website/content/obsidian/use-cases/literature-reviewing.md create mode 100644 apps/website/content/obsidian/use-cases/reading-clubs.md create mode 100644 apps/website/content/obsidian/use-cases/research-roadmapping.md create mode 100644 apps/website/content/obsidian/welcome/_meta.ts create mode 100644 apps/website/content/obsidian/welcome/getting-started.md create mode 100644 apps/website/content/obsidian/welcome/installation.md create mode 100644 apps/website/content/roam/_meta.ts create mode 100644 apps/website/content/roam/fundamentals/_meta.ts create mode 100644 apps/website/content/roam/fundamentals/base-grammar.md create mode 100644 apps/website/content/roam/fundamentals/grammar.md create mode 100644 apps/website/content/roam/fundamentals/migration-to-stored-relations.md create mode 100644 apps/website/content/roam/fundamentals/nodes.md create mode 100644 apps/website/content/roam/fundamentals/operators-relations.md create mode 100644 apps/website/content/roam/fundamentals/relations-patterns.md create mode 100644 apps/website/content/roam/fundamentals/stored-relations.md create mode 100644 apps/website/content/roam/fundamentals/what-is-a-discourse-graph.md create mode 100644 apps/website/content/roam/guides/_meta.ts create mode 100644 apps/website/content/roam/guides/creating-discourse-nodes.md create mode 100644 apps/website/content/roam/guides/creating-discourse-relationships.md create mode 100644 apps/website/content/roam/guides/exploring-discourse-graph.md create mode 100644 apps/website/content/roam/guides/extending-personalizing-graph.md create mode 100644 apps/website/content/roam/guides/querying-discourse-graph.md create mode 100644 apps/website/content/roam/guides/sharing-discourse-graph.md create mode 100644 apps/website/content/roam/guides/tagging-candidate-nodes.md create mode 100644 apps/website/content/roam/index.mdx create mode 100644 apps/website/content/roam/use-cases/_meta.ts create mode 100644 apps/website/content/roam/use-cases/enhanced-zettelkasten.md create mode 100644 apps/website/content/roam/use-cases/lab-notebooks.md create mode 100644 apps/website/content/roam/use-cases/literature-reviewing.md create mode 100644 apps/website/content/roam/use-cases/reading-clubs.md create mode 100644 apps/website/content/roam/use-cases/research-roadmapping.md create mode 100644 apps/website/content/roam/views-and-tools/_meta.ts create mode 100644 apps/website/content/roam/views-and-tools/discourse-attributes.md create mode 100644 apps/website/content/roam/views-and-tools/discourse-context-overlay.md create mode 100644 apps/website/content/roam/views-and-tools/discourse-context.md create mode 100644 apps/website/content/roam/views-and-tools/node-index.md create mode 100644 apps/website/content/roam/welcome/_meta.ts create mode 100644 apps/website/content/roam/welcome/getting-started.md create mode 100644 apps/website/content/roam/welcome/installation-roam-depot.md create mode 100644 apps/website/content/roam/welcome/installation.md create mode 100644 apps/website/docsRouteMap.ts diff --git a/apps/website/app/(docs)/docs/(landing)/layout.tsx b/apps/website/app/(docs)/docs/(landing)/layout.tsx new file mode 100644 index 000000000..2c0bb05e2 --- /dev/null +++ b/apps/website/app/(docs)/docs/(landing)/layout.tsx @@ -0,0 +1,18 @@ +import { getPageMap } from "nextra/page-map"; +import DocsThemeLayout from "../_components/DocsThemeLayout"; +import "../../../(nextra)/nextra-css.css"; +import "nextra-theme-docs/style-prefixed.css"; + +type DocsLandingLayoutProps = { + children: React.ReactNode; +}; + +const DocsLandingLayout = async ({ + children, +}: DocsLandingLayoutProps): Promise => { + const pageMap = await getPageMap("/docs"); + + return {children}; +}; + +export default DocsLandingLayout; diff --git a/apps/website/app/(docs)/docs/(landing)/page.tsx b/apps/website/app/(docs)/docs/(landing)/page.tsx new file mode 100644 index 000000000..da60503a5 --- /dev/null +++ b/apps/website/app/(docs)/docs/(landing)/page.tsx @@ -0,0 +1,47 @@ +import type { Metadata } from "next"; +import { notFound } from "next/navigation"; +import { importPage } from "nextra/pages"; +import { useMDXComponents } from "../../../../mdx-components"; + +type ImportedPage = Awaited>; + +const { wrapper } = useMDXComponents(); + +const Wrapper = wrapper as React.ComponentType<{ + children: React.ReactNode; + metadata: ImportedPage["metadata"]; + toc: ImportedPage["toc"]; +}>; + +const loadPage = async (): Promise => importPage([]); + +const Page = async (): Promise => { + try { + const { default: MDXContent, metadata, toc } = await loadPage(); + + return ( + + + + ); + } catch (error) { + console.error("Error rendering docs landing page:", error); + notFound(); + } +}; + +export const generateMetadata = async (): Promise => { + try { + const { metadata } = await loadPage(); + + return metadata; + } catch (error) { + console.error("Error generating docs landing metadata:", error); + + return { + title: "Docs", + }; + } +}; + +export default Page; diff --git a/apps/website/app/(docs)/docs/_components/DocsThemeLayout.tsx b/apps/website/app/(docs)/docs/_components/DocsThemeLayout.tsx new file mode 100644 index 000000000..1eae7a897 --- /dev/null +++ b/apps/website/app/(docs)/docs/_components/DocsThemeLayout.tsx @@ -0,0 +1,44 @@ +import type { PageMapItem } from "nextra"; +import { Footer, Layout, Navbar } from "nextra-theme-docs"; +import { Logo } from "~/components/Logo"; + +type DocsThemeLayoutProps = { + children: React.ReactNode; + pageMap: PageMapItem[]; +}; + +const DocsThemeLayout = ({ + children, + pageMap, +}: DocsThemeLayoutProps): React.ReactElement => { + return ( +
+ + Apache 2.0 {new Date().getFullYear()} (c) Discourse Graphs. + + } + navbar={ + } + projectLink="https://github.com/DiscourseGraphs/discourse-graph" + /> + } + pageMap={pageMap} + sidebar={{ + defaultMenuCollapseLevel: 1, + }} + toc={{ + backToTop: "Back to top", + }} + > + {children} + +
+ ); +}; + +export default DocsThemeLayout; diff --git a/apps/website/app/(docs)/docs/obsidian/[[...mdxPath]]/page.tsx b/apps/website/app/(docs)/docs/obsidian/[[...mdxPath]]/page.tsx new file mode 100644 index 000000000..b9155694d --- /dev/null +++ b/apps/website/app/(docs)/docs/obsidian/[[...mdxPath]]/page.tsx @@ -0,0 +1,76 @@ +import type { Metadata } from "next"; +import { notFound } from "next/navigation"; +import { generateStaticParamsFor, importPage } from "nextra/pages"; +import { useMDXComponents } from "../../../../../mdx-components"; + +type DocsPageProps = { + params: Promise<{ + mdxPath?: string[]; + }>; +}; + +type ImportedPage = Awaited>; + +const { wrapper } = useMDXComponents(); + +const Wrapper = wrapper as React.ComponentType<{ + children: React.ReactNode; + metadata: ImportedPage["metadata"]; + toc: ImportedPage["toc"]; +}>; + +const generateAllStaticParams = generateStaticParamsFor("mdxPath"); + +const loadPage = async (mdxPath?: string[]): Promise => + importPage(["obsidian", ...(mdxPath ?? [])]); + +export const generateStaticParams = async (): Promise< + Array<{ mdxPath?: string[] }> +> => { + const staticParams = await generateAllStaticParams(); + + return staticParams.flatMap(({ mdxPath }) => { + if (!Array.isArray(mdxPath) || mdxPath[0] !== "obsidian") { + return []; + } + + const platformPath = mdxPath.slice(1); + + return platformPath.length ? [{ mdxPath: platformPath }] : [{}]; + }); +}; + +const Page = async ({ params }: DocsPageProps): Promise => { + try { + const { mdxPath } = await params; + const { default: MDXContent, metadata, toc } = await loadPage(mdxPath); + + return ( + + + + ); + } catch (error) { + console.error("Error rendering Obsidian docs page:", error); + notFound(); + } +}; + +export const generateMetadata = async ({ + params, +}: DocsPageProps): Promise => { + try { + const { mdxPath } = await params; + const { metadata } = await loadPage(mdxPath); + + return metadata; + } catch (error) { + console.error("Error generating Obsidian docs metadata:", error); + + return { + title: "Obsidian docs", + }; + } +}; + +export default Page; diff --git a/apps/website/app/(docs)/docs/obsidian/[slug]/page.tsx b/apps/website/app/(docs)/docs/obsidian/[slug]/page.tsx deleted file mode 100644 index 81ef7c912..000000000 --- a/apps/website/app/(docs)/docs/obsidian/[slug]/page.tsx +++ /dev/null @@ -1,32 +0,0 @@ -import { docMap } from "~/(docs)/docs/obsidian/docMap"; -import { Metadata } from "next"; -import { - generateDocsStaticParams, - generateDocsMetadata, - DocsPage, -} from "~/components/DocsPage"; - -const Page = async ({ params }: { params: Promise<{ slug: string }> }) => { - const { slug } = await params; - const directory = docMap[slug] ?? docMap.default; - - return await DocsPage({ params: Promise.resolve({ slug }), directory }); -}; - -export default Page; - -export const generateStaticParams = () => - generateDocsStaticParams([...new Set(Object.values(docMap))]); - -export const generateMetadata = async ({ - params, -}: { - params: Promise<{ slug: string }>; -}): Promise => { - const { slug } = await params; - const directory = docMap[slug] ?? docMap.default; - return generateDocsMetadata({ - params: Promise.resolve({ slug }), - directory, - }); -}; diff --git a/apps/website/app/(docs)/docs/obsidian/layout.tsx b/apps/website/app/(docs)/docs/obsidian/layout.tsx index f71434c71..85aa0e8c3 100644 --- a/apps/website/app/(docs)/docs/obsidian/layout.tsx +++ b/apps/website/app/(docs)/docs/obsidian/layout.tsx @@ -1,10 +1,18 @@ -import { navigation } from "./navigation"; -import { Layout } from "~/components/DocsLayout"; +import { getPageMap } from "nextra/page-map"; +import DocsThemeLayout from "../_components/DocsThemeLayout"; +import "../../../(nextra)/nextra-css.css"; +import "nextra-theme-docs/style-prefixed.css"; -export default function RootLayout({ - children, -}: { +type ObsidianDocsLayoutProps = { children: React.ReactNode; -}) { - return {children}; -} +}; + +const ObsidianDocsLayout = async ({ + children, +}: ObsidianDocsLayoutProps): Promise => { + const pageMap = await getPageMap("/docs/obsidian"); + + return {children}; +}; + +export default ObsidianDocsLayout; diff --git a/apps/website/app/(docs)/docs/obsidian/page.tsx b/apps/website/app/(docs)/docs/obsidian/page.tsx deleted file mode 100644 index 80871f146..000000000 --- a/apps/website/app/(docs)/docs/obsidian/page.tsx +++ /dev/null @@ -1,6 +0,0 @@ -import { DocsRedirect } from "~/components/DocsRedirect"; -import { navigation } from "./navigation"; - -export default function Page() { - return ; -} diff --git a/apps/website/app/(docs)/docs/page.tsx b/apps/website/app/(docs)/docs/page.tsx deleted file mode 100644 index e87c18134..000000000 --- a/apps/website/app/(docs)/docs/page.tsx +++ /dev/null @@ -1,39 +0,0 @@ -import Link from "next/link"; -import Image from "next/image"; - -const DocsPage = () => { - return ( -
-
-

- Future Home of All the Docs -

-

- For now, here are the{" "} - - Roam Docs{" "} - - and the{" "} - - Obsidian Docs{" "} - -

-
- -
-
-
- ); -}; - -export default DocsPage; diff --git a/apps/website/app/(docs)/docs/roam/[[...mdxPath]]/page.tsx b/apps/website/app/(docs)/docs/roam/[[...mdxPath]]/page.tsx new file mode 100644 index 000000000..734ab2e6a --- /dev/null +++ b/apps/website/app/(docs)/docs/roam/[[...mdxPath]]/page.tsx @@ -0,0 +1,76 @@ +import type { Metadata } from "next"; +import { notFound } from "next/navigation"; +import { generateStaticParamsFor, importPage } from "nextra/pages"; +import { useMDXComponents } from "../../../../../mdx-components"; + +type DocsPageProps = { + params: Promise<{ + mdxPath?: string[]; + }>; +}; + +type ImportedPage = Awaited>; + +const { wrapper } = useMDXComponents(); + +const Wrapper = wrapper as React.ComponentType<{ + children: React.ReactNode; + metadata: ImportedPage["metadata"]; + toc: ImportedPage["toc"]; +}>; + +const generateAllStaticParams = generateStaticParamsFor("mdxPath"); + +const loadPage = async (mdxPath?: string[]): Promise => + importPage(["roam", ...(mdxPath ?? [])]); + +export const generateStaticParams = async (): Promise< + Array<{ mdxPath?: string[] }> +> => { + const staticParams = await generateAllStaticParams(); + + return staticParams.flatMap(({ mdxPath }) => { + if (!Array.isArray(mdxPath) || mdxPath[0] !== "roam") { + return []; + } + + const platformPath = mdxPath.slice(1); + + return platformPath.length ? [{ mdxPath: platformPath }] : [{}]; + }); +}; + +const Page = async ({ params }: DocsPageProps): Promise => { + try { + const { mdxPath } = await params; + const { default: MDXContent, metadata, toc } = await loadPage(mdxPath); + + return ( + + + + ); + } catch (error) { + console.error("Error rendering Roam docs page:", error); + notFound(); + } +}; + +export const generateMetadata = async ({ + params, +}: DocsPageProps): Promise => { + try { + const { mdxPath } = await params; + const { metadata } = await loadPage(mdxPath); + + return metadata; + } catch (error) { + console.error("Error generating Roam docs metadata:", error); + + return { + title: "Roam docs", + }; + } +}; + +export default Page; diff --git a/apps/website/app/(docs)/docs/roam/[slug]/page.tsx b/apps/website/app/(docs)/docs/roam/[slug]/page.tsx deleted file mode 100644 index 9617b5560..000000000 --- a/apps/website/app/(docs)/docs/roam/[slug]/page.tsx +++ /dev/null @@ -1,33 +0,0 @@ -import { docMap } from "~/(docs)/docs/roam/docMap"; -import { Metadata } from "next"; -import { - generateDocsStaticParams, - generateDocsMetadata, - DocsPage, -} from "~/components/DocsPage"; - -type Params = { - params: Promise<{ - slug: string; - }>; -}; - -const Page = async ({ params }: Params) => { - const { slug } = await params; - const directory = docMap[slug] ?? docMap.default; - - return await DocsPage({ params: Promise.resolve({ slug }), directory }); -}; - -export default Page; - -export const generateStaticParams = () => - generateDocsStaticParams([...new Set(Object.values(docMap))]); - -export const generateMetadata = async ({ - params, -}: Params): Promise => { - const { slug } = await params; - const directory = docMap[slug] ?? docMap.default; - return generateDocsMetadata({ params: Promise.resolve({ slug }), directory }); -}; diff --git a/apps/website/app/(docs)/docs/roam/layout.tsx b/apps/website/app/(docs)/docs/roam/layout.tsx index 18096f77c..38570535f 100644 --- a/apps/website/app/(docs)/docs/roam/layout.tsx +++ b/apps/website/app/(docs)/docs/roam/layout.tsx @@ -1,10 +1,18 @@ -import { Layout } from "~/components/DocsLayout"; -import { navigation } from "./navigation"; +import { getPageMap } from "nextra/page-map"; +import DocsThemeLayout from "../_components/DocsThemeLayout"; +import "../../../(nextra)/nextra-css.css"; +import "nextra-theme-docs/style-prefixed.css"; -export default function RootLayout({ - children, -}: { +type RoamDocsLayoutProps = { children: React.ReactNode; -}) { - return {children}; -} +}; + +const RoamDocsLayout = async ({ + children, +}: RoamDocsLayoutProps): Promise => { + const pageMap = await getPageMap("/docs/roam"); + + return {children}; +}; + +export default RoamDocsLayout; diff --git a/apps/website/app/(docs)/docs/roam/page.tsx b/apps/website/app/(docs)/docs/roam/page.tsx deleted file mode 100644 index 4496ed7bf..000000000 --- a/apps/website/app/(docs)/docs/roam/page.tsx +++ /dev/null @@ -1,13 +0,0 @@ -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)/layout.tsx b/apps/website/app/(docs)/layout.tsx index d2181de4d..5ebae9beb 100644 --- a/apps/website/app/(docs)/layout.tsx +++ b/apps/website/app/(docs)/layout.tsx @@ -1,9 +1,6 @@ import { type Metadata } from "next"; import { Inter } from "next/font/google"; -import clsx from "clsx"; -import { customScrollbar } from "~/components/DocsLayout"; import { DESCRIPTION } from "~/data/constants"; -import "~/globals.css"; const inter = Inter({ subsets: ["latin"], @@ -20,17 +17,7 @@ export const metadata: Metadata = { }; const DocsLayout = ({ children }: { children: React.ReactNode }) => { - return ( -
- {children} -
- ); + return
{children}
; }; export default DocsLayout; diff --git a/apps/website/app/components/Logo.tsx b/apps/website/app/components/Logo.tsx index 0dec46a94..134b30277 100644 --- a/apps/website/app/components/Logo.tsx +++ b/apps/website/app/components/Logo.tsx @@ -6,31 +6,49 @@ import { usePathname } from "next/navigation"; import { PlatformBadge } from "./PlatformBadge"; const DOCS_PLATFORMS = { - "/docs/obsidian/": "obsidian", - "/docs/roam/": "roam", + "/docs/obsidian": "obsidian", + "/docs/roam": "roam", } as const; -export const Logo = () => { +type LogoProps = { + linked?: boolean; + textClassName?: string; +}; + +export const Logo = ({ + linked = true, + textClassName = "text-neutral-dark", +}: LogoProps) => { const pathname = usePathname(); const platform = Object.entries(DOCS_PLATFORMS).find(([path]) => pathname.includes(path), )?.[1]; + const brand = ( + <> + Discourse Graphs Logo + + + Discourse Graphs + + + ); + return (
- - Discourse Graphs Logo - - - Discourse Graphs - - + {linked ? ( + + {brand} + + ) : ( +
{brand}
+ )} {platform && (
diff --git a/apps/website/content/_meta.ts b/apps/website/content/_meta.ts new file mode 100644 index 000000000..d35fd540f --- /dev/null +++ b/apps/website/content/_meta.ts @@ -0,0 +1,13 @@ +import type { MetaRecord } from "nextra"; + +const meta: MetaRecord = { + index: "Overview", + roam: { + title: "Roam", + }, + obsidian: { + title: "Obsidian", + }, +}; + +export default meta; diff --git a/apps/website/content/index.mdx b/apps/website/content/index.mdx new file mode 100644 index 000000000..feb94c181 --- /dev/null +++ b/apps/website/content/index.mdx @@ -0,0 +1,29 @@ +--- +title: Documentation +description: Discourse Graphs documentation for the Roam extension and Obsidian plugin. +--- + +import { Callout, Cards } from "nextra/components"; + +# Documentation + +Choose the product documentation you need. All `/docs` routes now render through Nextra, while the `/nextra` sandbox remains available for experimentation. + + + Shared conceptual docs, like What is a discourse graph? and + Base grammar, are available from both product sections so + URLs stay stable. + + + + + + diff --git a/apps/website/content/obsidian/_meta.ts b/apps/website/content/obsidian/_meta.ts new file mode 100644 index 000000000..3cd87c634 --- /dev/null +++ b/apps/website/content/obsidian/_meta.ts @@ -0,0 +1,16 @@ +import type { MetaRecord } from "nextra"; + +const meta: MetaRecord = { + index: { + title: "Overview", + display: "hidden", + }, + welcome: "Welcome", + fundamentals: "Fundamentals", + configuration: "Configuration", + "core-features": "Core features", + "advanced-features": "Advanced features", + "use-cases": "Use cases", +}; + +export default meta; diff --git a/apps/website/content/obsidian/advanced-features/_meta.ts b/apps/website/content/obsidian/advanced-features/_meta.ts new file mode 100644 index 000000000..ca1e99ccb --- /dev/null +++ b/apps/website/content/obsidian/advanced-features/_meta.ts @@ -0,0 +1,8 @@ +import type { MetaRecord } from "nextra"; + +const meta: MetaRecord = { + "command-palette": "Command palette", + "sync-and-import": "Sync and import", +}; + +export default meta; diff --git a/apps/website/content/obsidian/advanced-features/command-palette.md b/apps/website/content/obsidian/advanced-features/command-palette.md new file mode 100644 index 000000000..77b2d4636 --- /dev/null +++ b/apps/website/content/obsidian/advanced-features/command-palette.md @@ -0,0 +1,24 @@ +--- +title: "Command palette integration" +date: "2025-01-01" +author: "" +published: true +--- + +## Using the Command Palette + +The Command Palette is a powerful way to access all Discourse Graph features without memorizing keyboard shortcuts. To open it: + +1. Press `Cmd/Ctrl + P` +2. Type "Discourse" to see all available commands + ![command palette](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2F5ybScaQISO.png?alt=media&token=2b36f0e7-4247-47b7-a53d-c784dfd4609b) + +## Customizing Commands + +You can customize how commands appear in the Command Palette: + +1. Open Obsidian Settings +2. Go to "Hotkeys" +3. Search for "Discourse" +4. Modify the commands or add hotkeys + diff --git a/apps/website/content/obsidian/advanced-features/sync-and-import.md b/apps/website/content/obsidian/advanced-features/sync-and-import.md new file mode 100644 index 000000000..c7ada41c1 --- /dev/null +++ b/apps/website/content/obsidian/advanced-features/sync-and-import.md @@ -0,0 +1,151 @@ +--- +title: "Sync and Import" +date: "2026-02-16" +author: "" +published: true +--- + +The Sync and Import feature allows you to synchronize your discourse nodes with the Discourse Graph database and share them with collaborators. Once enabled, you can publish nodes to a shared group space and import nodes published by others. + +> **Note:** This feature is currently in **beta**. The sync functionality requires an active connection to the Discourse Graph database. + +> **Warning:** When using sync and import: +> +> - Don't edit the things you imported +> - Don't click to create new files (from imported nodes) +> - Don't delete imported node types + +## Enabling sync mode + +### Step 1: Open settings + +Open the Discourse Graph plugin settings: + +1. Open **Obsidian settings** (click the gear icon in the bottom-left corner, or press `Cmd/Ctrl + ,`) +2. Scroll down in the left sidebar to **community plugins** +3. Find **Discourse Graph** + +### Step 2: Reveal the admin panel + +The sync feature is located in a hidden **admin panel** tab that is not visible by default. + +1. While on the Discourse Graph settings page, press `Cmd + Shift + A` (Mac) or `Ctrl + Shift + A` (Windows/Linux) +2. A new **admin panel** tab will appear in the settings tab bar + +![Admin panel tab revealed](/docs/obsidian/sync-setting.png) + +### Step 3: Enable sync mode + +1. In the **admin panel** tab, find the **(BETA) Sync mode enable** toggle +2. Click the toggle to enable sync mode +3. Click **Save changes** +4. A confirmation notice will appear: "Admin panel settings saved" +5. The sync mode will initialize automatically, and you will see a notice: "Sync mode initialized successfully" + +Once enabled, your discourse nodes will begin syncing automatically to the Discourse Graph database. The plugin monitors file changes in your vault (with a short delay) and syncs them in the background. + +--- + +## Publishing a discourse node + +Publishing makes a synced discourse node available to other members of your group. This is how you share your work with collaborators. + +### Prerequisites + +Before publishing, make sure: + +- **Sync mode is enabled** (see above) +- **You are a member of a group.** Group membership is managed by your team administrator. The Discourse Graph team will ensure you are added to the appropriate group before you can publish. +- The discourse node you want to publish has a `nodeTypeId` in its frontmatter +- The discourse node has been **synced at least once** (it must have a `nodeInstanceId` in its frontmatter — this is assigned automatically after the first sync) + +### Steps to publish + +1. **Open the discourse node** you want to publish in the editor + +2. **Open the command palette** by pressing `Cmd/Ctrl + P` + +3. **Search for the publish command** by typing "Publish" and select **"Discourse Graph: Publish current node to lab space"** + ![Publish command in palette](/docs/obsidian/publish-command.png) + +4. The plugin will: + - Publish the node to your group + - **Automatically publish any relations** connected to this node where the other endpoint has already been published to the same group + - Sync any embedded assets (images, attachments) to the shared storage + - Update the node's frontmatter with a `publishedToGroups` field + +5. A confirmation notice will appear: **"Published"** + ![Node published successfully](/docs/obsidian/publish-success.png) + +**Note on publishing relations:** Relations between nodes are published **automatically** — you do not need to publish them separately. When you publish a node, the plugin checks all its relations and publishes any where: + +- Both the source and destination nodes are published to the same group, **and** +- The relation type is defined in your discourse relation settings + +--- + +## Importing discourse nodes from another space + +Importing allows you to bring published discourse nodes from other group members into your vault. + +### Steps to import + +1. **Open the command palette** by pressing `Cmd/Ctrl + P` + +2. **Search for the import command** by typing "Import" and select **"Discourse Graph: Import nodes from another space"** + +![Import command in palette](/docs/obsidian/import-command.png) + +3. The **import nodes** modal will open and begin loading available nodes from your groups. Once loaded, you will see a list of importable nodes **grouped by space**. Each space section shows the space name and available nodes. + +![Selecting nodes to import](/docs/obsidian/import-modal.png) + +4. Before importing, the modal shows an **import preview** summarizing everything that will be created: + - Number of nodes and relations to be imported + - Any new node types that will be added to your vault + - Any new relation types that will be added + - Any new discourse relation triplets (source → relation → destination) that will be established + +5. The plugin will import each selected node **and their associated relations**, then display a progress bar. Once complete, you will see a confirmation notice. + +Imported nodes are saved in an `import/{spaceName}/` folder in your vault, preserving the original space organization. + +![Import location](/docs/obsidian/import-location.png) + +> **Note:** Relations are only imported when **both** the source and destination nodes are present in your local vault (either as previously imported nodes or nodes you already have locally). Relations whose endpoints are missing will be skipped. + +--- + +## Refreshing imported nodes + +After importing, you can fetch the latest content from the original sources to keep your imported nodes up to date. + +1. **Open the command palette** by pressing `Cmd/Ctrl + P` +2. Search for "Fetch" and select **"Discourse Graph: Fetch latest content from imported nodes"** +3. The plugin will check each imported node for updates and refresh any that have changed + +![Refreshing imported nodes](/docs/obsidian/refresh-imported.png) + +Alternatively, you can click the "Refresh" button in the Discourse Context panel. + +![Refresh button](/docs/obsidian/refresh-button.png) + +## Summary of commands + +- **Sync discourse nodes to Supabase**: Manually sync all discourse nodes to the database +- **Publish current node to lab space**: Publish the active discourse node to your group, including any relations whose other endpoint is already published to the same group +- **Import nodes from another space**: Open the import modal to browse and import shared nodes along with their relations +- **Fetch latest content from imported nodes**: Refresh all imported nodes with the latest content + +## Troubleshooting + +- **"Sync mode is not enabled"** — You need to enable sync mode in the admin panel first (see [Enabling sync mode](#enabling-sync-mode) above) +- **"Please sync the node first"** — The node hasn't been synced yet. Wait for automatic sync or trigger a manual sync via the command palette using **"Discourse Graph: Sync discourse nodes to Supabase"**. + +![Sync command](/docs/obsidian/sync-command.png) + +- **"You are not a member of any groups"** — You need to be added to a group before you can import nodes. Contact your team administrator +- **No importable nodes found** — Either no nodes have been published to your groups, or you have already imported all available nodes +- The frontmatter fields related to sync are normally hidden. You can choose to display them in the setting panel + ![Show frontmatter](/docs/obsidian/show-frontmatter.png) + diff --git a/apps/website/content/obsidian/configuration/_meta.ts b/apps/website/content/obsidian/configuration/_meta.ts new file mode 100644 index 000000000..5f037a041 --- /dev/null +++ b/apps/website/content/obsidian/configuration/_meta.ts @@ -0,0 +1,9 @@ +import type { MetaRecord } from "nextra"; + +const meta: MetaRecord = { + "node-types-templates": "Node types and templates", + "relationship-types": "Relationship types", + "general-settings": "General settings", +}; + +export default meta; diff --git a/apps/website/content/obsidian/configuration/general-settings.md b/apps/website/content/obsidian/configuration/general-settings.md new file mode 100644 index 000000000..f67fdc640 --- /dev/null +++ b/apps/website/content/obsidian/configuration/general-settings.md @@ -0,0 +1,28 @@ +--- +title: "General settings" +date: "2025-06-27" +author: "" +published: true +--- + +The General settings page in the Discourse Graph plugin provides fundamental configuration options that affect how the plugin operates. Here are the available settings: + +## Show IDs in frontmatter + +This setting controls the visibility of identifiers in your note's frontmatter section. + +- When enabled, node type IDs and relation type IDs will be visible in the frontmatter of your notes +- When disabled, these IDs will be hidden from view +- This can be useful if you prefer a cleaner frontmatter appearance while still maintaining the underlying structure + +## Discourse nodes folder path + +This setting determines where new discourse nodes will be created in your vault. + +- Specify a folder path where you want all new discourse nodes to be stored +- Leave the field empty to create nodes in the root folder of your vault +- You can use the folder suggester to easily navigate and select existing folders +- Example format: `folder1/folder2` + +Changes to these settings will only take effect after clicking the "Save Changes" button. The interface will indicate when you have unsaved changes pending. + diff --git a/apps/website/content/obsidian/configuration/node-types-templates.md b/apps/website/content/obsidian/configuration/node-types-templates.md new file mode 100644 index 000000000..b029f6f7b --- /dev/null +++ b/apps/website/content/obsidian/configuration/node-types-templates.md @@ -0,0 +1,53 @@ +--- +title: "Node types & templates" +date: "2025-01-01" +author: "" +published: true +--- + +## Configuring Node Types + +Node types are the building blocks of your discourse graph. Each node type represents a different kind of content or concept in your notes. + +### Adding a Node Type + +1. Under "Node Types," click "Add Node Type" +2. Enter a name for your node type (e.g., "Claim", "Evidence", "Question") +3. Add the format for your node type. eg a claim node will have page title "CLM - {content}" +4. **Template (Optional)**: Select a template from the dropdown to automatically apply template content when creating nodes of this type + - Templates are sourced from Obsidian's core Templates plugin + - Ensure you have the Templates plugin enabled and configured with a template folder + - The dropdown will show all available template files from your configured template folder + + ![add node types with template](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FHMg_Tq6qiR.png?alt=media&token=69828bfc-c939-41b0-abd4-2cc8931c5a38) + + - Click "Save Changes" + +## Working with Templates + +Templates allow you to automatically add predefined content when creating new nodes. They're especially useful for maintaining consistent structure across similar types of notes. + +### Setting Up Templates + +1. Create a new folder for templates + ![new folder](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FyTtJ1a0iI2.png?alt=media&token=b5d09b10-f170-47cd-a239-ee5f7acd89dc) + +2. Configure the template folder location in settings + ![template](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FhzZg_GJXY9.png?alt=media&token=508c8d19-1f13-4fb3-adf1-898dcf694f08) + +3. Create template files + ![create template file](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FtTr9vOnXnX.png?alt=media&token=dda1fe25-3ccf-42b4-8f3c-1cd29f82c3f7) + +## Template Requirements + +- Templates must be stored in your designated template folder +- The Templates core plugin must be enabled +- Template files should use Markdown format +- Templates can include any valid Markdown content + +## Next Steps + +- [Configure relationship types](/docs/obsidian/configuration/relationship-types) +- [Learn about creating nodes](/docs/obsidian/core-features/creating-discourse-nodes) +- [Explore advanced template usage](/docs/obsidian/configuration/node-types-templates#working-with-templates) + diff --git a/apps/website/content/obsidian/configuration/relationship-types.md b/apps/website/content/obsidian/configuration/relationship-types.md new file mode 100644 index 000000000..73a5abfbd --- /dev/null +++ b/apps/website/content/obsidian/configuration/relationship-types.md @@ -0,0 +1,55 @@ +--- +title: "Relationship types" +date: "2025-01-01" +author: "" +published: true +--- + +## Understanding relationship types + +Relationship types define how different nodes in your discourse graph can connect to each other. Each relationship type has: +- A primary label (e.g., "supports") +- A complement label (e.g., "is supported by") +- Rules about which node types can be connected + +## Adding relationship types + +1. Open Obsidian Settings +2. Navigate to the "Discourse Graphs" settings tab +3. Under "Relation Types," click "Add Relationship Type" +4. Configure the relationship: + - Enter the primary label (e.g., "supports", "contradicts") + - Enter the complement label (e.g., "is supported by", "is contradicted by") + ![add relation type](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2Fjk367dcO_K.png?alt=media&token=22d74e9f-882c-434b-8b50-afd7a754fb2b) +5. Click "Save Changes" + +## Configuring valid relationships + +After creating relationship types, you need to define which node types can be connected by each relationship. + +1. Open the Discourse Relations tab in settings +![discourse relation](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FNgm7Ha4Ul5.png?alt=media&token=a933bd3a-d9a6-42c1-9c6e-d779d41c7ebf) + +2. Choose the components: + - Source Node Type (e.g., Claim) + - Relationship Type (e.g., supports) + - Target Node Type (e.g., Question) +![choose relation](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FlflJBkfdaK.png?alt=media&token=5de9617c-6099-46e8-931f-feafc604cabb) + +3. Review and confirm the configuration +![final relations](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FycPW-N-rY8.png?alt=media&token=54867be2-9030-4c6c-82d2-b96069e52d81) + +## Example relationships + +Here are some common relationship types: +- Claim → supports → Question +- Evidence → supports → Claim +- Evidence → contradicts → Claim +- Source → informs → Question + +## Next steps + +- [Create your first relationship](/docs/obsidian/core-features/creating-discourse-relationships) +- [Learn about the discourse context](/docs/obsidian/core-features/discourse-context) +- [Explore your graph](/docs/obsidian/core-features/canvas) + diff --git a/apps/website/content/obsidian/core-features/_meta.ts b/apps/website/content/obsidian/core-features/_meta.ts new file mode 100644 index 000000000..ef63f1b80 --- /dev/null +++ b/apps/website/content/obsidian/core-features/_meta.ts @@ -0,0 +1,11 @@ +import type { MetaRecord } from "nextra"; + +const meta: MetaRecord = { + "creating-discourse-nodes": "Creating nodes", + "creating-discourse-relationships": "Creating relationships", + "discourse-context": "Discourse context", + canvas: "Canvas", + "node-tags": "Node tags", +}; + +export default meta; diff --git a/apps/website/content/obsidian/core-features/canvas.md b/apps/website/content/obsidian/core-features/canvas.md new file mode 100644 index 000000000..dd3e95cef --- /dev/null +++ b/apps/website/content/obsidian/core-features/canvas.md @@ -0,0 +1,150 @@ +--- +title: "Canvas" +date: "2025-01-01" +author: "" +published: true +--- + +The canvas feature in Discourse Graph provides an interactive visual workspace for creating and connecting discourse nodes and relations. Built on top of tldraw, it allows you to visually map out discourse structures with drag-and-drop functionality, adding other visual elements like texts, scribbles, embeddings, and images. + +## Creating a new canvas + +### Using the command palette + +1. Open the command palette (`Cmd/Ctrl + P`) +2. Search for "Create new Discourse Graph canvas" +3. Press Enter to create a new canvas + +![Create canvas command](/docs/obsidian/create-canvas-command.png) +The canvas will be created in your configured canvas folder (default: `Discourse Canvas/`) with a timestamp-based filename like `Canvas-2025-01-15-1430.md`. + +## Opening and viewing canvas + +### Opening a canvas + +1. Open the file of the canvas +2. In case the file is still in markdown format, you can open the canvas mode by either + +Using the command palette + +![Open canvas command](/docs/obsidian/open-canvas-command.png) +Or click on the canvas icon at the top right corner +![Canvas icon button](/docs/obsidian/canvas-icon-button.png) + +**WARNING: DO NOT MODIFY MARKDOWN CONTENT OF FILE** + +## Discourse nodes + +### Creating new discourse nodes + +**Using the discourse node tool** + +- Click the discourse node icon in the toolbar +- Select a node type from the right side panel +- Click anywhere on the canvas to place a new node +- Or drag the selected node type to the canvas +- Enter the node title in the modal that appears + +![Create discourse node](/docs/obsidian/create-discourse-node.gif) + +### Adding existing nodes + +**Using node search** + +- Use the search bar in the top-right of the canvas +- Type to search for existing discourse Nodes +- Click on a node from the search results to add it to the canvas + +![Node search](/docs/obsidian/node-search.gif) + +**Search filtering** + +- When a specific node type is selected, search results are filtered to that type + +![Search filtering](/docs/obsidian/search-filtering.gif) + +## Discourse relations + +### Create new relations between nodes + +- Click the discourse node icon in the toolbar +- Click the type of relations you want to create between two nodes +- Click and drag the arrow from the source node to target node + +![Create relations](/docs/obsidian/create-relations.gif) + +_Note_: The relation type selected must be compatible between the source and target nodes. Otherwise, you will receive a relation tool error. To update the setting on what relation types are possible between two kinds of discourse nodes, you can change the setting [Relation types setting](/docs/obsidian/configuration/relationship-types#configuring-valid-relationships) + +![Relation error](/docs/obsidian/relation-error.png) + +### Adding existing relations + +- Click on the discourse node you're trying to add existing relations of +- Click on the "Relations" button that pops up. You'll see a panel showing all the relations that this node has +- Click on the '+' or '-' to add these relations to the canvas + - For relations whose target discourse node isn't on canvas yet, it will be added to the canvas along with the relation + +![Adding existing relations](/docs/obsidian/adding-existing-relations.gif) + +## Canvas Features + +### Key figures + +You can choose to show the first image of discourse nodes of certain type. To change the setting on whether this first image show up, you can edit it in the Node Type Setting + +![Key figure](/docs/obsidian/key-figure.png) + +Then you will see the image show up if any is present in the file. + +![Key figure example](/docs/obsidian/key-figure-example.png) + +### Open discourse node files + +- To open a discourse node to the side panel, you can press Shift + Click, or click on the sidebar icon when hover on discourse node. +- To open file to a new tab, you can press Cmd + click on the file + +### Auto-save + +- Changes are automatically saved to the markdown file +- No manual save required +- File updates preserve the markdown structure and block references + +### Export Options + +- **Markdown View**: Switch to see the underlying markdown structure +- **SVG Export**: Export canvas as SVG image (via tldraw) +- **PNG Export**: Export canvas as PNG image (via tldraw) + +![Export options](/docs/obsidian/export-options.png) + +## Troubleshooting + +### Common Issues + +**Canvas Won't Load**: + +- Check that the file has proper frontmatter with `tldr-dg: true` +- Verify the JSON data block is properly formatted +- Try switching to markdown view and back to canvas view + +**Relations Won't Connect**: + +- Ensure the node types allow the relation type you're trying to create +- Check your discourse relation configuration in settings +- Verify both nodes are valid discourse nodes + +**Performance Issues**: + +- Consider splitting large canvases into multiple smaller ones +- Close other resource-intensive applications + +**Search Not Working**: + +- Verify nodes have proper frontmatter with `nodeTypeId` +- Check that the Obsidian metadata cache is up to date +- Try restarting Obsidian to refresh the cache + +### Getting Help + +If you encounter issues with the canvas feature, reach out to our dev team via [Slack](https://join.slack.com/t/discoursegraphs/shared_invite/zt-37xklatti-cpEjgPQC0YyKYQWPNgAkEg) + diff --git a/apps/website/content/obsidian/core-features/creating-discourse-nodes.md b/apps/website/content/obsidian/core-features/creating-discourse-nodes.md new file mode 100644 index 000000000..0238d7e29 --- /dev/null +++ b/apps/website/content/obsidian/core-features/creating-discourse-nodes.md @@ -0,0 +1,58 @@ +--- +title: "Creating discourse nodes" +date: "2025-01-01" +author: "" +published: true +--- + +## Creating a node + +To create a discourse node, first select the text you want to turn into a node: + +![select text](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FInIer-iPGs.png?alt=media&token=fad214f6-f426-4249-8b0a-d5a403894600) + +There are two ways you can create a node: + +### 1. Using command keys (recommended) +#### 1.1 Turn selected text into discourse node + +1. Press `Cmd + \` (or your configured hotkey) +2. The Node Menu will open as a popup +![node menu](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FS6eU6y70eX.png?alt=media&token=00e61ddf-877b-4752-a65b-272e80a0a19c) +3. Select the node type you want to turn the text into +4. A new discourse node will be created +![node created](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2F1VNkJC0aH8.png?alt=media&token=df9a26aa-997b-4b56-a307-87a80e350b28) + +#### 1.2 Creating new node from scratch +1. Press `Cmd + \` (or your configured hotkey) +2. Enter the title and node type +![](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FyYxtLKkx6B.png?alt=media&token=7f4f02df-d1fe-4529-8530-90acb0dc74b8) + +### 2. Using the right-click menu + +1. Right-click on the selected text +Alternatively, you can right-click on the selected text + +![right click menu](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2F4UqeVkqLz7.png?alt=media&token=d2373152-d251-45fe-afb6-56373d6092aa) +2. Choose a node type from the "Turn into discourse node" menu + +### 3. Turn existing page into discourse node + +If a page is not a discourse node, you can turn it into one by clicking on the file menu, and chosing "Convert into" option +![](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FCAGcQrCONJ.png?alt=media&token=fba6a6c9-038c-4a63-a46f-920bb8b37df1) + +After choosing a node type, you can edit the title and node type in the menu +![](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FVZ-jWbffHY.png?alt=media&token=6d7e5861-1df6-4148-8c11-4767a6e130f0) +## Node templates + +When creating a node, if you've configured a [template for that node type](/docs/obsidian/configuration/node-types-templates#working-with-templates), the template content will be automatically applied to the new node. + + +The new node will be saved in the designated folder that you created in the [General settings](/docs/obsidian/configuration/general-settings) + +## Next Steps + +After creating nodes: +- [Create relationships between nodes](/docs/obsidian/core-features/creating-discourse-relationships) +- [Learn how to explore your graph](/docs/obsidian/core-features/canvas) + diff --git a/apps/website/content/obsidian/core-features/creating-discourse-relationships.md b/apps/website/content/obsidian/core-features/creating-discourse-relationships.md new file mode 100644 index 000000000..f09de7dd5 --- /dev/null +++ b/apps/website/content/obsidian/core-features/creating-discourse-relationships.md @@ -0,0 +1,36 @@ +--- +title: "Creating discourse relationships" +date: "2025-01-01" +author: "" +published: true +--- + +## Creating a relationship + +To create a relationship between discourse nodes: + +1. Open a note that you want to create a relationship from +2. Open the discourse context by clicking the telescope icon on the left bar +![open discourse context](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FE10krHZcDM.png?alt=media&token=c1796a9f-7e51-437f-913d-91f5433d9bab) + + Alternatively, you can: + - Set a hotkey to toggle the discourse context view + - Access it via the Command Palette + ![command palette](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2F5ybScaQISO.png?alt=media&token=2b36f0e7-4247-47b7-a53d-c784dfd4609b) + +3. Click "Add a new relation" + +4. Choose a relationship type from the dropdown. The dropdown shows all available relations that you have defined in the settings, and indicates what node types you can link with. +![add relation](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FXQsgznWuV2.png?alt=media&token=9442b9fa-0904-4847-8eb8-a5791705c4c5) + +5. Search for the target node by its title +![search](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2F4NW4UjYDrC.png?alt=media&token=bae307d0-ebec-4e6b-a03d-0943d9d03754) + +6. Click "Confirm" to create the relationship +![relationship created](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FK8XAhCqrUL.png?alt=media&token=a559c477-c7f6-4b3e-8b00-ece7da5d4fec) + +## Next steps + +After creating relationships: +- [Learn how to explore your graph](/docs/obsidian/core-features/canvas) + diff --git a/apps/website/content/obsidian/core-features/discourse-context.md b/apps/website/content/obsidian/core-features/discourse-context.md new file mode 100644 index 000000000..b7649e9f5 --- /dev/null +++ b/apps/website/content/obsidian/core-features/discourse-context.md @@ -0,0 +1,44 @@ +--- +title: "Exploring your discourse graph" +date: "2025-01-01" +author: "" +published: true +--- + +## Opening the discourse context + +The discourse context view is your main tool for exploring relationships between nodes in your graph. There are several ways to open it: + +### Method 1: Using the sidebar icon + +Click the telescope icon on the left sidebar to toggle the discourse context view. +![open discourse context](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FE10krHZcDM.png?alt=media&token=c1796a9f-7e51-437f-913d-91f5433d9bab) + +### Method 2: Using the command palette + +1. Open the Command Palette (`Cmd/Ctrl + P`) +2. Search for "discourse context" + ![command palette](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2F5ybScaQISO.png?alt=media&token=2b36f0e7-4247-47b7-a53d-c784dfd4609b) + +### Method 3: Using hotkeys + +You can configure a custom hotkey in the Obsidian settings to quickly toggle the discourse context view. + +3. Configure a custom hotkey in settings + +## Using the discourse context + +The discourse context view shows you: + +- All relationships the current node has with other nodes +- Types of relationships (supports, contradicts, etc.) +- Quick access to related nodes +- Tools for creating new relationships + +You can use this view to: + +- Navigate between related nodes +- Understand how nodes connect to each other +- Add new relationships +- Get a quick overview of your graph structure + diff --git a/apps/website/content/obsidian/core-features/node-tags.md b/apps/website/content/obsidian/core-features/node-tags.md new file mode 100644 index 000000000..7eab9a20b --- /dev/null +++ b/apps/website/content/obsidian/core-features/node-tags.md @@ -0,0 +1,67 @@ +--- +title: "Node tags" +date: "2025-10-15" +author: "" +published: true +--- + +## Overview + +Node tags allow you to quickly create discourse nodes from tagged lines in your notes. When you assign a tag to a node type, any line containing that tag becomes a clickable element that can be converted into a discourse node. + +This feature streamlines your workflow by letting you mark potential discourse nodes with tags as you write, then easily convert them to full discourse nodes later. + +## Setting up node tags + +### Configuring tags in settings + +1. Open the Discourse Graph settings +2. Navigate to the **Node Types** section +3. Select an existing node type or create a new one +4. In the **Node tag** field, enter a tag identifier + +![Node tags setting](/docs/obsidian/node-tags-setting.png) + +### Tag naming rules + +Tags must follow these rules: +- **No spaces**: Tags cannot contain whitespace +- **Allowed characters**: Only letters (a-z, A-Z), numbers (0-9), and dashes (-) +- **No special characters**: Characters like #, @, /, \, etc. are not allowed +- **Case-sensitive**: Tags are case-sensitive in the editor + +#### Tag examples + +**Valid tags:** +- `clm-candidate` +- `question-idea` +- `evidence2024` +- `my-argument` + +**Invalid tags:** +- `clm candidate` (contains space) +- `#clm-candidate` (contains #) +- `clm/candidate` (contains /) + +## Using node tags in your notes + +### Adding tags to your notes + +Once you've configured a node tag for a node type, simply add the tag (prefixed with `#`) to any line in your notes: + +![Node tags example](/docs/obsidian/node-tags-example.png) + +### Creating discourse nodes from tags + +When you hover over a tagged line, a button appears above the tag: + +1. **Hover** over the tag you want to convert +2. Wait for the **"Create [Node Type]"** button to appear +![On hover](/docs/obsidian/on-hover-node-tag.png) +3. **Click** the button to open the node creation dialog +![Node creation dialog](/docs/obsidian/create-node-dialog-node-tag.png) +4. Click "Confirm" to create node + +You'll see that the candidate node is now replaced with a formalized node +![node created from tag](/docs/obsidian/node-tag-created.png) + diff --git a/apps/website/content/obsidian/fundamentals/_meta.ts b/apps/website/content/obsidian/fundamentals/_meta.ts new file mode 100644 index 000000000..a5730652c --- /dev/null +++ b/apps/website/content/obsidian/fundamentals/_meta.ts @@ -0,0 +1,8 @@ +import type { MetaRecord } from "nextra"; + +const meta: MetaRecord = { + "what-is-a-discourse-graph": "What is a discourse graph?", + "base-grammar": "Base grammar", +}; + +export default meta; diff --git a/apps/website/content/obsidian/fundamentals/base-grammar.md b/apps/website/content/obsidian/fundamentals/base-grammar.md new file mode 100644 index 000000000..fb298cc0d --- /dev/null +++ b/apps/website/content/obsidian/fundamentals/base-grammar.md @@ -0,0 +1,28 @@ +--- +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/content/obsidian/fundamentals/what-is-a-discourse-graph.md b/apps/website/content/obsidian/fundamentals/what-is-a-discourse-graph.md new file mode 100644 index 000000000..b998a19f6 --- /dev/null +++ b/apps/website/content/obsidian/fundamentals/what-is-a-discourse-graph.md @@ -0,0 +1,21 @@ +--- +title: "What is a 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. + +![](/docs/roam/argument-map.png) + +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! + +![](/docs/roam/bans-hate-speech.png) + +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/content/obsidian/index.mdx b/apps/website/content/obsidian/index.mdx new file mode 100644 index 000000000..b9d4256b9 --- /dev/null +++ b/apps/website/content/obsidian/index.mdx @@ -0,0 +1,23 @@ +--- +title: Obsidian documentation +description: Learn how to install, configure, and use the Discourse Graph plugin for Obsidian. +--- + +import { Callout, Cards } from "nextra/components"; + +# Obsidian documentation + +Use these docs to install the Discourse Graph plugin for Obsidian, configure node and relationship types, and work with discourse structures directly in your vault. + + + Start with Getting started if you want the fastest path to a + working vault. + + + + + + + + + diff --git a/apps/website/content/obsidian/use-cases/_meta.ts b/apps/website/content/obsidian/use-cases/_meta.ts new file mode 100644 index 000000000..c193a603e --- /dev/null +++ b/apps/website/content/obsidian/use-cases/_meta.ts @@ -0,0 +1,10 @@ +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", +}; + +export default meta; diff --git a/apps/website/content/obsidian/use-cases/lab-notebooks.md b/apps/website/content/obsidian/use-cases/lab-notebooks.md new file mode 100644 index 000000000..d29aca7c2 --- /dev/null +++ b/apps/website/content/obsidian/use-cases/lab-notebooks.md @@ -0,0 +1,9 @@ +--- +title: "Lab notebooks" +date: "2025-01-01" +author: "" +published: true +--- + +Description coming soon! + diff --git a/apps/website/content/obsidian/use-cases/literature-reviewing.md b/apps/website/content/obsidian/use-cases/literature-reviewing.md new file mode 100644 index 000000000..4202485e2 --- /dev/null +++ b/apps/website/content/obsidian/use-cases/literature-reviewing.md @@ -0,0 +1,15 @@ +--- +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 new file mode 100644 index 000000000..8739b9a7c --- /dev/null +++ b/apps/website/content/obsidian/use-cases/reading-clubs.md @@ -0,0 +1,11 @@ +--- +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 new file mode 100644 index 000000000..f2edf06b1 --- /dev/null +++ b/apps/website/content/obsidian/use-cases/research-roadmapping.md @@ -0,0 +1,9 @@ +--- +title: "Research roadmapping" +date: "2025-01-01" +author: "" +published: true +--- + +Description coming soon! + diff --git a/apps/website/content/obsidian/welcome/_meta.ts b/apps/website/content/obsidian/welcome/_meta.ts new file mode 100644 index 000000000..ac6fd187f --- /dev/null +++ b/apps/website/content/obsidian/welcome/_meta.ts @@ -0,0 +1,8 @@ +import type { MetaRecord } from "nextra"; + +const meta: MetaRecord = { + "getting-started": "Getting started", + installation: "Installation", +}; + +export default meta; diff --git a/apps/website/content/obsidian/welcome/getting-started.md b/apps/website/content/obsidian/welcome/getting-started.md new file mode 100644 index 000000000..ed6419d9c --- /dev/null +++ b/apps/website/content/obsidian/welcome/getting-started.md @@ -0,0 +1,43 @@ +--- +title: "Getting started" +date: "2025-01-01" +author: "" +published: true +--- + +The Discourse Graph plugin enables [Obsidian](https://obsidian.md/) users to seamlessly add additional semantic structure to their notes, including specified page types and link types that [model scientific discourse](/docs/obsidian/fundamentals/what-is-a-discourse-graph), to enable more complex and structured knowledge synthesis work, such as a complex interdisciplinary literature review, and enhanced collaboration with others on this work. + +For more information about Discourse Graphs, check out our website at [https://discoursegraphs.com](https://discoursegraphs.com) + +## Quick Start Guide + +1. [Install the plugin](/docs/obsidian/welcome/installation) +2. [Configure node and relationship types](/docs/obsidian/configuration/node-types-templates) +3. [Create your first discourse node](/docs/obsidian/core-features/creating-discourse-nodes) +4. [Create relationships between nodes](/docs/obsidian/core-features/creating-discourse-relationships) +5. [Explore your discourse graph](/docs/obsidian/core-features/canvas) + +## 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 +- Join our community to share your experience and get help + +## Guides: Jump right in + +Follow our handy guides to get started on the basics as quickly as possible: + +- [Creating discourse nodes](/docs/obsidian/core-features/creating-discourse-nodes) +- [Creating discourse relationships](/docs/obsidian/core-features/creating-discourse-relationships) +- [Exploring your Discourse Graph](/docs/obsidian/core-features/canvas) +- [Running advanced commands](/docs/obsidian/advanced-features/command-palette) +- [Extending and personalizing your Discourse Graph](/docs/obsidian/configuration/general-settings) + +## Fundamentals: Dive a little deeper + +Learn the fundamentals of the Discourse Graph plugin to get a deeper understanding of our main features: + +- [What is a Discourse Graph?](/docs/obsidian/fundamentals/what-is-a-discourse-graph) +- [Relationship types](/docs/obsidian/configuration/relationship-types) +- [The Base Grammar: questions, claims, and evidence](/docs/obsidian/fundamentals/base-grammar) + diff --git a/apps/website/content/obsidian/welcome/installation.md b/apps/website/content/obsidian/welcome/installation.md new file mode 100644 index 000000000..a2936985e --- /dev/null +++ b/apps/website/content/obsidian/welcome/installation.md @@ -0,0 +1,45 @@ +--- +title: "Installation" +date: "2025-01-01" +author: "" +published: true +--- + +## Prerequisites + +### Install BRAT (Beta Reviewer's Auto-update Tester) + +1. Open Obsidian Settings +2. Go to Community Plugins and disable Restricted Mode +3. Click "Browse" and search for "BRAT" +![BRAT](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2Faar5LKpLOk.png?alt=media&token=6f51ac48-19d3-4bb5-9a07-7b32cfa6afe6) +4. Install BRAT and enable it + +### Install DataCore via BRAT + +1. Open Obsidian Settings +2. Go to "Community Plugins" → "BRAT" +3. Click "Add Beta Plugin" +![Add plugin](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FdMtstUHPXe.png?alt=media&token=3f139ab9-9802-404d-9554-4a63bac080c5) +4. Enter the repository URL: `https://github.com/blacksmithgu/datacore` and choose "Latest version" +![Add datacore](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FEY3vNGt1Rf.png?alt=media&token=32c60ff1-5272-4cde-8b5f-8f049fb2cf50) +5. Check the box for "Enable after installing the plugin" +6. Click "Add plugin" + +## Install Discourse Graphs + +1. Open Obsidian Settings +2. Go to "Community Plugins" → "BRAT" +3. Click "Add Beta Plugin" +![Add plugin](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FdMtstUHPXe.png?alt=media&token=3f139ab9-9802-404d-9554-4a63bac080c5) +4. Enter the repository URL: `https://github.com/DiscourseGraphs/discourse-graph-obsidian` and choose "Latest version" +![Add discourse graph](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FSBCK-2lkcu.png?alt=media&token=0375c828-da4d-43b4-8f2c-e691692cb019) +5. Check the box for "Enable after installing the plugin" +6. Click "Add Plugin" + +## Next Steps + +After installation, you'll want to: +1. [Configure your node types](/docs/obsidian/configuration/node-types-templates) +2. [Set up relationship types](/docs/obsidian/configuration/relationship-types) +3. [Create your first node](/docs/obsidian/core-features/creating-discourse-nodes) diff --git a/apps/website/content/roam/_meta.ts b/apps/website/content/roam/_meta.ts new file mode 100644 index 000000000..428463021 --- /dev/null +++ b/apps/website/content/roam/_meta.ts @@ -0,0 +1,15 @@ +import type { MetaRecord } from "nextra"; + +const meta: MetaRecord = { + index: { + title: "Overview", + display: "hidden", + }, + welcome: "Welcome", + guides: "Guides", + fundamentals: "Fundamentals", + "views-and-tools": "Views and tools", + "use-cases": "Use cases", +}; + +export default meta; diff --git a/apps/website/content/roam/fundamentals/_meta.ts b/apps/website/content/roam/fundamentals/_meta.ts new file mode 100644 index 000000000..b661cddd1 --- /dev/null +++ b/apps/website/content/roam/fundamentals/_meta.ts @@ -0,0 +1,14 @@ +import type { MetaRecord } from "nextra"; + +const meta: MetaRecord = { + "what-is-a-discourse-graph": "What is a discourse graph?", + grammar: "Grammar", + nodes: "Nodes", + "operators-relations": "Operators and relations", + "base-grammar": "Base grammar", + "stored-relations": "Stored relations", + "migration-to-stored-relations": "Migration to stored relations", + "relations-patterns": "Relations and patterns", +}; + +export default meta; diff --git a/apps/website/content/roam/fundamentals/base-grammar.md b/apps/website/content/roam/fundamentals/base-grammar.md new file mode 100644 index 000000000..fb298cc0d --- /dev/null +++ b/apps/website/content/roam/fundamentals/base-grammar.md @@ -0,0 +1,28 @@ +--- +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/content/roam/fundamentals/grammar.md b/apps/website/content/roam/fundamentals/grammar.md new file mode 100644 index 000000000..af7735c71 --- /dev/null +++ b/apps/website/content/roam/fundamentals/grammar.md @@ -0,0 +1,16 @@ +--- +title: "Extension grammar" +date: "2025-01-01" +author: "" +published: true +--- + +- [Nodes](/docs/roam/fundamentals/nodes) +- [Operators and relations](/docs/roam/fundamentals/operators-relations) +- [Stored relations](/docs/roam/fundamentals/stored-relations) +- [Base grammar](/docs/roam/fundamentals/base-grammar) + +## Relation grammar building blocks + +- [Nodes](/docs/roam/fundamentals/nodes) + diff --git a/apps/website/content/roam/fundamentals/migration-to-stored-relations.md b/apps/website/content/roam/fundamentals/migration-to-stored-relations.md new file mode 100644 index 000000000..efb6038e1 --- /dev/null +++ b/apps/website/content/roam/fundamentals/migration-to-stored-relations.md @@ -0,0 +1,91 @@ +--- +title: "Migration to stored relations" +date: "2025-01-01" +author: "" +published: true +--- + +## Overview + +Stored relations make relations load faster and more reliably. Discourse Graph installs as of v0.18.0 use them by default. Older installs need a one-time migration that copies existing pattern-based relations into the new format. + +This guide covers the migration flow from **Personal Settings** for older installs. If you're new to stored relations, start with the [stored relations overview](/docs/roam/fundamentals/stored-relations). + +## Turn on stored relations for an existing install + +1. Open **Personal Settings** +2. Go to the **Home** panel +3. Find **Enable stored relations** +4. Turn the toggle **On** + +When you turn this on for an older install, you'll be shown a migration step for your graph. + +## Migrate your existing relations + +After enabling the toggle, click: + +`Migrate all relations` + +What to expect: + +- It may take a few minutes +- Roam may feel frozen while it runs (this is expected) +- You **can** work in **another Roam window** during the migration +- When it finishes, you can continue working normally + +## When should I run migration again? + +You only need to run migration again if: + +- Relations were created while stored relations were turned off +- Your team is transitioning gradually and some people are still using the older relation method + +## Multi-user graphs + +Migration runs **per graph**, but the stored relations toggle is **per user**. During rollout, it's possible for teammates to be in different modes. + +If some users are still using the older relation method, running migration again later helps ensure you see the most up-to-date relations. + +### What each user sees + +#### If you do NOT opt in + +- You can keep using **patterns** to create relations +- The overlay will search **only pattern-based** relations +- You **will not** see stored relations + +#### If you DO opt in + +- You will see **only stored** relations +- You **will not** see pattern-based relations + +### Re-running migration (multi-user / mixed mode) + +You can run migration **multiple times**. + +This matters if: + +- Some users are still creating **pattern-based** relations +- Other users are already using **stored** relations + +In that case, stored-relations users must re-run migration to "catch up," otherwise: + +- They won't see new pattern-based relations created since the last migration + +#### Important edge case + +If you: + +1. Delete a **stored** relation that originally came from a pattern, and then +2. Re-run migration + +... it will be **re-created** from the still-existing pattern. + +### For the technically inclined + +Stored relations are implemented as: + +- `roam/js/discourse-graph/relations` + +Each relation is a **block**, with relation data stored in the block's **hidden properties**. + diff --git a/apps/website/content/roam/fundamentals/nodes.md b/apps/website/content/roam/fundamentals/nodes.md new file mode 100644 index 000000000..4f50cd3cf --- /dev/null +++ b/apps/website/content/roam/fundamentals/nodes.md @@ -0,0 +1,23 @@ +--- +title: "Nodes" +date: "2025-01-01" +author: "" +published: true +--- + +- `discourse node` + - as defined in your grammar (e.g., base grammar will include CLM or EVD, for example) + +- `block` +- `page` + +It is not possible to directly specify that a source or target node in a relation pattern is a `block` or `page`. These are variables that are defined implicitly at the moment, by what incoming and/or outgoing relations it connects to. + +For example, if a node's incoming relation is `references`, that implies it is a page. Similarly, if the node's incoming relation is `has child` or `has ancestor`, that implies the node is a block. + +When in doubt, check the preview of your relation pattern to ensure you're correctly expressing your intentions! + +## Next + +- [Operators and relations](/docs/roam/fundamentals/operators-relations) + diff --git a/apps/website/content/roam/fundamentals/operators-relations.md b/apps/website/content/roam/fundamentals/operators-relations.md new file mode 100644 index 000000000..2600109bd --- /dev/null +++ b/apps/website/content/roam/fundamentals/operators-relations.md @@ -0,0 +1,71 @@ +--- +title: "Operators and relations" +date: "2025-01-01" +author: "" +published: true +--- + +## Roam-native + +### `references` + +- **description**: a block references some page. NOTE: you'll need to then chain that with something like `has title` or `with text` to identify the page. +- **source**: a `block` +- **target**: a `page` +- example: + - this block references \[\[some page\]\] + +### `is in page` + +- **description**: source is in some page. NOTE: you'll need to then chain that with something like `has title` or `with text` to identify the page. +- **source**: a `block` +- **target**: a `page` + +### `has ancestor` + +- **description**: a block has some ancestor (i.e., the block is in the indentation path of some target, whether directly or indirectly) +- **source**: a `block` +- **target**: a `block` or `page` + +### `has child` + +- **description**: a block or page has some direct child (directly indented underneath) +- **source**: a `block` or `page` +- **target**: a `block` + +### `has descendant` + +- **description**: a block has some descendant (i.e., the target block is in the indentation path of the source, whether directly or indirectly). NOTE: you'll need to then chain that with something like `has title` or `with text` to identify the block. +- **source**: a `block` or `page` +- **target**: a `block` + +### `has title` + +- **description**: source text exactly matches some text +- **source**: a `page`, `block`, or `discourse node` +- **target**: a `string` that specifies the target title to match + +### `with text` + +- **description**: node content contains some text +- **source:** a `page`, `block`, or `discourse node` +- **target**: a `string` that specifies the target text to find in the node content + +### `has attribute` + +- **description**: has a child block with some attribute +- **source**: a `page` or `discourse node` +- **target**: a `string` that specifies the target attribute to be matched + +## Discourse-graph only + +### `is a` + +- **description**: exact match to user-defined `discourse nodes` only (ALTHOUGH the autocomplete will allow you to specify other stuff that don't make sense) +- **source**: a `page` (since all discourse nodes must be pages) +- **target**: a `discourse node` (defined in your grammar) + +## Next + +- [Stored relations](/docs/roam/fundamentals/stored-relations) + diff --git a/apps/website/content/roam/fundamentals/relations-patterns.md b/apps/website/content/roam/fundamentals/relations-patterns.md new file mode 100644 index 000000000..e8a63e6db --- /dev/null +++ b/apps/website/content/roam/fundamentals/relations-patterns.md @@ -0,0 +1,54 @@ +--- +title: "Relations and patterns" +date: "2025-01-01" +author: "" +published: true +--- + +Pattern-based relations are a **legacy workflow**. New graphs use [**stored relations**](/docs/roam/fundamentals/stored-relations) by default. If you're still using patterns or you're not sure which system your graph is on, see [**Migration to stored relations**](/docs/roam/fundamentals/migration-to-stored-relations). + +The legacy pattern workflow recognizes a few common writing and outlining structures and converts them into discourse relations. + +- [Informed](#question-informed-by-evidence) +- [Supported](#claim-supported-by-evidence) +- [Opposed](#claim-opposed-by-evidence) + +## Question Informed by Evidence + +- Go into a Question page. +- Create a block and reference an evidence page. + +Like this: + +![](/docs/roam/relation-informs.png) + +The system recognizes that this piece of evidence **informs** the 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: + +![](/docs/roam/relation-supports.png) + +The system recognizes that this piece of evidence **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: + +![](/docs/roam/relation-opposes.png) + +The system recognizes that this piece of evidence **opposes** that claim. + diff --git a/apps/website/content/roam/fundamentals/stored-relations.md b/apps/website/content/roam/fundamentals/stored-relations.md new file mode 100644 index 000000000..8d0c733aa --- /dev/null +++ b/apps/website/content/roam/fundamentals/stored-relations.md @@ -0,0 +1,79 @@ +--- +title: "Stored relations" +date: "2025-01-01" +author: "" +published: true +--- + +## Overview + +Stored relations are explicit relationships between discourse nodes. They are created directly in the graph and saved as data, so they can be used consistently across overlays, queries, and canvases. + +## What is a stored relation? + +A stored relation connects two discourse nodes with a named relation type, such as a claim supporting another claim or a source informing a question. + +Stored relations are: + +- Created directly in the [**Discourse context overlay**](/docs/roam/views-and-tools/discourse-context-overlay) +- Persisted in your graph as structured data +- Available anywhere Discourse Graph reads relationships + +## Why use stored relations? + +Stored relations give you a more direct and predictable way to work with relationships in your graph. + +- **Fast to read** + - Relations are loaded directly from stored data + - The Discourse context overlay can resolve them quickly +- **Stable over time** + - Relations do not depend on formatting or page structure + - Editing nearby text does not change the relation itself +- **Easy to understand** + - A relation exists because you created it + - Deleting a relation removes it explicitly + +## Creating stored relations + +Typical flow: + +1. Open the Discourse context overlay for a node. +2. Click **Add relation**. +3. Select the relation type. +4. Select the source and destination nodes. +5. Save the relation. + +The relation is stored immediately. + +## Viewing stored relations + +Stored relations appear throughout Discourse Graph: + +- The [**Discourse context overlay**](/docs/roam/views-and-tools/discourse-context-overlay) shows relations for the current node +- Queries can resolve relations from stored data +- Canvases can use the same stored relationships + +## Editing and deleting stored relations + +- Stored relations can be deleted directly from the Discourse context overlay +- If you want to change a relation, the usual flow is to delete the old one and create the new one +- Relation labels are referenced by node identity, so renaming a relation label updates the associated relations automatically + +## Multi-user behavior + +Stored relations are shared across the graph. + +- Teammates working in the same graph see the same stored relations +- Changes to stored relations are available to other users in that graph + +## For the technically inclined + +Stored relations are implemented as: + +- One block per relation +- Located at: `roam/js/discourse-graph/relations` +- Relation data stored in the block's hidden properties +- Source and destination nodes referenced by UID + +This structure allows fast lookup, consistent rendering, and future extensions such as metadata, provenance, and annotations. + diff --git a/apps/website/content/roam/fundamentals/what-is-a-discourse-graph.md b/apps/website/content/roam/fundamentals/what-is-a-discourse-graph.md new file mode 100644 index 000000000..b998a19f6 --- /dev/null +++ b/apps/website/content/roam/fundamentals/what-is-a-discourse-graph.md @@ -0,0 +1,21 @@ +--- +title: "What is a 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. + +![](/docs/roam/argument-map.png) + +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! + +![](/docs/roam/bans-hate-speech.png) + +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/content/roam/guides/_meta.ts b/apps/website/content/roam/guides/_meta.ts new file mode 100644 index 000000000..f5bf2d1e3 --- /dev/null +++ b/apps/website/content/roam/guides/_meta.ts @@ -0,0 +1,13 @@ +import type { MetaRecord } from "nextra"; + +const meta: MetaRecord = { + "creating-discourse-nodes": "Creating nodes", + "tagging-candidate-nodes": "Tagging candidate nodes", + "creating-discourse-relationships": "Creating relationships", + "exploring-discourse-graph": "Exploring", + "querying-discourse-graph": "Querying", + "extending-personalizing-graph": "Extending", + "sharing-discourse-graph": "Sharing", +}; + +export default meta; diff --git a/apps/website/content/roam/guides/creating-discourse-nodes.md b/apps/website/content/roam/guides/creating-discourse-nodes.md new file mode 100644 index 000000000..d58d00b5a --- /dev/null +++ b/apps/website/content/roam/guides/creating-discourse-nodes.md @@ -0,0 +1,25 @@ +--- +title: "Creating discourse nodes" +date: "2025-01-01" +author: "" +published: true +--- + +The extension makes it easy to factor parts of your notes into formal nodes of a discourse graph (claims, evidence, etc.). + +Steps to create a discourse graph node: + +1. Select the text you want to turn into a formal discourse graph node +2. Press the trigger hotkey (default is `\`) to open up the Node Menu +3. Press the appropriate shortcut key (e.g., E for Evidence) + +The system will create a new page with the text as title, appropriate metadata, and template you have defined. + +## Demo + +https://www.loom.com/share/471fcf7dc13246439cb35feedb110470 + +You can customize the template for specific nodes in the Settings Panel. + +![](/docs/roam/node-template.png) + diff --git a/apps/website/content/roam/guides/creating-discourse-relationships.md b/apps/website/content/roam/guides/creating-discourse-relationships.md new file mode 100644 index 000000000..b86836985 --- /dev/null +++ b/apps/website/content/roam/guides/creating-discourse-relationships.md @@ -0,0 +1,27 @@ +--- +title: "Creating discourse relationships" +date: "2025-01-01" +author: "" +published: true +--- + +Creating relationships in Discourse Graph means creating **stored relations**. Stored relations are the default way to connect discourse nodes. + +> Note: If you're still using pattern relations, or if you're not sure which system your graph is using, start with [**Migration to stored relations**](/docs/roam/fundamentals/migration-to-stored-relations). + +## Quick start + +1. Open the [**Discourse context overlay**](/docs/roam/views-and-tools/discourse-context-overlay) for a node. +2. Click **Add relation**. +3. Choose the relation type. +4. Choose the source and destination nodes. +5. Save the relation. + +The relation is stored immediately and becomes available throughout your graph. + +## Read next + +- Learn how stored relations work in [**Stored relations**](/docs/roam/fundamentals/stored-relations) +- Explore relationships from the [**Discourse context overlay**](/docs/roam/views-and-tools/discourse-context-overlay) +- If you're still using the legacy workflow, see [**Relations and patterns**](/docs/roam/fundamentals/relations-patterns) + diff --git a/apps/website/content/roam/guides/exploring-discourse-graph.md b/apps/website/content/roam/guides/exploring-discourse-graph.md new file mode 100644 index 000000000..a92073b0f --- /dev/null +++ b/apps/website/content/roam/guides/exploring-discourse-graph.md @@ -0,0 +1,14 @@ +--- +title: "Exploring Your 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. + +- [Discourse context](/docs/roam/views-and-tools/discourse-context) +- [Discourse context overlay](/docs/roam/views-and-tools/discourse-context-overlay) +- [Discourse attributes](/docs/roam/views-and-tools/discourse-attributes) +- [Node index](/docs/roam/views-and-tools/node-index) + diff --git a/apps/website/content/roam/guides/extending-personalizing-graph.md b/apps/website/content/roam/guides/extending-personalizing-graph.md new file mode 100644 index 000000000..ada7c7c83 --- /dev/null +++ b/apps/website/content/roam/guides/extending-personalizing-graph.md @@ -0,0 +1,34 @@ +--- +title: "Extending and personalizing your Discourse Graph" +date: "2025-01-01" +author: "" +published: true +--- + +This page covers ways to extend and personalize Discourse Graph beyond the default setup. + +## Stored relations + +Coming soon. + +## Pattern relation legacy + +Discourse Graph used to rely much more heavily on query-based pattern relations. The videos below are older examples of that legacy workflow. + +Note: + +- They use the legacy query-based pattern-relations workflow +- They show an older UI that does not match the current product + +Some users extended the grammar quite extensively. For example, here is a video from a user who extended the grammar to cover structured international law research: + +[https://www.youtube.com/watch?v=rST7cKMO_Ds](https://www.youtube.com/watch?v=rST7cKMO_Ds) + +Others also extended the grammar to integrate results from their own experiments and contextualize each new result against earlier research. + +For example, here is a demo of creating a "consistent with" relation pattern that recognizes when two pieces of evidence both support the same thing: + +[https://www.loom.com/share/cb9e526a98764e95a459a6db2b66e46a](https://www.loom.com/share/cb9e526a98764e95a459a6db2b66e46a) + +If you want to explore or understand that legacy workflow, it will be useful to [learn more about the extension grammar](/docs/roam/fundamentals/grammar). + diff --git a/apps/website/content/roam/guides/querying-discourse-graph.md b/apps/website/content/roam/guides/querying-discourse-graph.md new file mode 100644 index 000000000..0fc850200 --- /dev/null +++ b/apps/website/content/roam/guides/querying-discourse-graph.md @@ -0,0 +1,67 @@ +--- +title: "Querying Your Discourse Graph" +date: "2025-01-01" +author: "" +published: true +--- + +## Query Drawer + +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"). + +### Making a query + +Use Command Palette (⌘+`P` on Mac,`CTRL`\+ `P` otherwise) to access the query drawer. + +![](/docs/roam/command-palette-query-drawer.png) + +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. + +![](/docs/roam/query-drawer.png) + +## Common Query Examples + +### Evidence that Informs a Question + +![](/docs/roam/query-drawer-informs.png) + +### Evidence that Supports a Claim + +![](/docs/roam/query-drawer-supports.png) + +## Advanced Query Examples + +### 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) + +![](/docs/roam/query-drawer-advanced.png) + +### 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) + +![](/docs/roam/query-drawer-advanced2.png) + +### Select discourse attributes to display as attributes of results + +If you have defined [Discourse Attributes](/docs/roam/views-and-tools/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. + +![](/docs/roam/query-drawer-advanced3.png) + +## Naming a query + +You can name a query if you like! + +![](/docs/roam/query-drawer-naming.gif) + +## 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. + +![](/docs/roam/query-drawer-save-to-page.png) + +It will be saved to the namespace `discourse-graph/queries/` by default. + diff --git a/apps/website/content/roam/guides/sharing-discourse-graph.md b/apps/website/content/roam/guides/sharing-discourse-graph.md new file mode 100644 index 000000000..57740ef23 --- /dev/null +++ b/apps/website/content/roam/guides/sharing-discourse-graph.md @@ -0,0 +1,61 @@ +--- +title: "Sharing Your 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 a number of formats, select an export option to see the options available. + +![](/docs/roam/command-palette-export.png) + +Demo: + +[https://www.loom.com/share/ca222cb93efb4ed890b4c9e91f05db52](https://www.loom.com/share/ca222cb93efb4ed890b4c9e91f05db52) + +## Export Options + +We have a range of options for customizing the markdown export. These can be found on the `Export` tab of the discourse graph configuration. + +![](/docs/roam/settings-export.png) + +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: + - ![](/docs/roam/settings-export-frontmatter.png) + +`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)`) + +## Example + +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/content/roam/guides/tagging-candidate-nodes.md b/apps/website/content/roam/guides/tagging-candidate-nodes.md new file mode 100644 index 000000000..55865c13b --- /dev/null +++ b/apps/website/content/roam/guides/tagging-candidate-nodes.md @@ -0,0 +1,42 @@ +--- +title: "Tagging candidate nodes" +date: "2025-09-16" +author: "" +published: true +--- + +## Purpose - quickly bookmark notes that could later become formal discourse nodes + +While you're taking notes, often you'll write down something that could later become a formal discourse node like a Claim, Evidence, or Result. But sometimes you don't want to break your flow to formalize it in the moment, or you may want to clarify/revisit it later to be sure that you want to turn it into a Claim/Evidence/Result. +It's helpful to quickly tag these. Later, you can search for them and formalize them in one click. + +## Setup - define candidate nodes + +In the discourse graphs settings, for each node type, list a "candidate node" tag label: + +![Tagging candidate nodes demo](/docs/roam/tagging-config.gif) + +⚠️ _Important: A tag cannot use text that is already part of its associated node's format. For example, if the "Claim" node format is CLM, you cannot use #CLM as its tag. You'll get an error message if you attempt to do this._ + +## Tag candidate nodes + +Tag candidate nodes with the keyboard shortcut: `\` + +![Tagging candidate nodes keyboard shortcut](/docs/roam/tagging-demo.gif) + +Click or use the down arrow key to select a candidate node type. + +💡 _If you've customized the keyboard shortcut for creating nodes, this keyboard shortcut will change too_ + +## Formalize candidate nodes + +Hover your mouse over the node tag, and click "Create Evidence" + + + +![Formalizing candidate nodes](/docs/roam/tagging-formalization.gif) + +## Candidate node styling + +Candidate node styling is currently controlled in roam/css. You can borrow our node styling here: [template-lab CSS page](https://roamresearch.com/#/app/template-lab/page/X8V4gy32s) + diff --git a/apps/website/content/roam/index.mdx b/apps/website/content/roam/index.mdx new file mode 100644 index 000000000..3c0f1dfa8 --- /dev/null +++ b/apps/website/content/roam/index.mdx @@ -0,0 +1,23 @@ +--- +title: Roam documentation +description: Learn how to install, configure, and use the Discourse Graph extension for Roam. +--- + +import { Callout, Cards } from "nextra/components"; + +# Roam documentation + +Use these docs to install the Discourse Graph extension for Roam, learn the core workflows, and understand the underlying graph model. + + + New to the extension? Start with Getting started and + Installation, then move into the guides. + + + + + + + + + diff --git a/apps/website/content/roam/use-cases/_meta.ts b/apps/website/content/roam/use-cases/_meta.ts new file mode 100644 index 000000000..18e66e72c --- /dev/null +++ b/apps/website/content/roam/use-cases/_meta.ts @@ -0,0 +1,11 @@ +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", +}; + +export default meta; diff --git a/apps/website/content/roam/use-cases/enhanced-zettelkasten.md b/apps/website/content/roam/use-cases/enhanced-zettelkasten.md new file mode 100644 index 000000000..aa37ec08b --- /dev/null +++ b/apps/website/content/roam/use-cases/enhanced-zettelkasten.md @@ -0,0 +1,13 @@ +--- +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/lab-notebooks.md b/apps/website/content/roam/use-cases/lab-notebooks.md new file mode 100644 index 000000000..d29aca7c2 --- /dev/null +++ b/apps/website/content/roam/use-cases/lab-notebooks.md @@ -0,0 +1,9 @@ +--- +title: "Lab notebooks" +date: "2025-01-01" +author: "" +published: true +--- + +Description coming soon! + diff --git a/apps/website/content/roam/use-cases/literature-reviewing.md b/apps/website/content/roam/use-cases/literature-reviewing.md new file mode 100644 index 000000000..4202485e2 --- /dev/null +++ b/apps/website/content/roam/use-cases/literature-reviewing.md @@ -0,0 +1,15 @@ +--- +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 new file mode 100644 index 000000000..8739b9a7c --- /dev/null +++ b/apps/website/content/roam/use-cases/reading-clubs.md @@ -0,0 +1,11 @@ +--- +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 new file mode 100644 index 000000000..f2edf06b1 --- /dev/null +++ b/apps/website/content/roam/use-cases/research-roadmapping.md @@ -0,0 +1,9 @@ +--- +title: "Research roadmapping" +date: "2025-01-01" +author: "" +published: true +--- + +Description coming soon! + diff --git a/apps/website/content/roam/views-and-tools/_meta.ts b/apps/website/content/roam/views-and-tools/_meta.ts new file mode 100644 index 000000000..97ae9e3e3 --- /dev/null +++ b/apps/website/content/roam/views-and-tools/_meta.ts @@ -0,0 +1,10 @@ +import type { MetaRecord } from "nextra"; + +const meta: MetaRecord = { + "discourse-context": "Discourse context", + "discourse-context-overlay": "Discourse context overlay", + "discourse-attributes": "Discourse attributes", + "node-index": "Node index", +}; + +export default meta; diff --git a/apps/website/content/roam/views-and-tools/discourse-attributes.md b/apps/website/content/roam/views-and-tools/discourse-attributes.md new file mode 100644 index 000000000..1a28b8070 --- /dev/null +++ b/apps/website/content/roam/views-and-tools/discourse-attributes.md @@ -0,0 +1,66 @@ +--- +title: "Discourse attributes" +date: "2025-01-01" +author: "" +published: true +--- + +- [Discourse context](/docs/roam/views-and-tools/discourse-context) +- [Discourse context overlay](/docs/roam/views-and-tools/discourse-context-overlay) +- [Discourse attributes](/docs/roam/views-and-tools/discourse-attributes) +- [Node index](/docs/roam/views-and-tools/node-index) + +## Define Discourse Attributes + +You can define discourse attributes that for each discourse node, which compute a numerical "score" for each instance of the node based on its discourse relations to other nodes. In the extension, we call these **discourse attributes**. + +These attributes can be handy for sorting/querying nodes. For instance, if you create a discourse attribute for Claim nodes that is a function of the number of Evidence nodes that Support the Claim, like this: + +![](/docs/roam/settings-discourse-attributes.png) + +You can add discourse attributes as a column to display and sort/filter by when [Querying your discourse graph](./querying-discourse-graph.md) by adding a `discourse:{label}` selection. + +For example, in the index for Claims, you can return the Evidence attribute as a column (Select), and then sort in descending order by that attribute. + +## Basic Discourse Relation Functions + +A discourse attribute consists of one or more **discourse functions**, joined by one or more math operations. You can think of the discourse functions as variables that get their value from some discourse relations the node participates in. + +Here is the template for each discourse function: `{count:relationName:targetType}` + +- `count` is the operation. Atm, this is the only supported operation for basic discourse functions. We also have experimental discourse functions that operate over the discourse attributes of related nodes (see below), which allow for other operations such as `sum` and `average` +- `relationName` is the name of the relation you want to use for the function, such as `Supported By` or `Informed By` +- `targetType` is the name of the type of target of the relation you want to use for the function (since nodes can have relationships of the same name with multiple other nodes, such as `Supported By:Claim` or `Supported By:Evidence`) + +Here are some examples: + +- `{count:Supported By:Evidence}` +- `{count:Informed By:Source}` +- `{count:Opposed By:Claim}` + +You can use basic math operations to combine multiple discourse functions. For example, you might want to combine information across the supporting and opposing relationships to gauge how "robust" a Claim is, and give different weights to support from evidence vs. claims. You could express it like this: + +`{count:Supported By:Evidence} + {count:Supported By:Claim}*0.5 - {count:Opposed By:Evidence} - {count:Opposed By:Claim}*0.5` + +This function sums up the number of supporting relations and subtracts the number of opposing relations, but gives only half weight (`*0.5`) to supporting/opposing relations from Claims. + +## Compound Discourse Functions + +We have an experimental feature that allows us to access discourse attributes from related nodes to compute a discourse attribute. This allows us to experiment with more sophisticated ways to reason over our discourse nodes. + +For example, if a Claim that only gets direct support from other Claims (e.g., because it is quite general), we might care to distinguish if its supporting Claims are themselves also supported by Evidence. + +If each Claim node has a discourse attribute called Evidence that looks like this: + +`{count:Supported By:Evidence} - {count:Opposed By:Evidence}` + +We can define a compound discourse function that _averages_ over the Evidence attribute of Claims that support the Claim. Like this: + +`{average:Supported By:Claim:Evidence}` + +The syntax for these compound discourse functions is: + +`{operation:relationName:targetType:targetDiscourseAttribute}` + +This generalizes the syntax for the basic discourse functions by adding a discourse attribute to access from the targets, and the option of using additional operations than `count` (for now, we only support `sum` and `average`) for the function. + diff --git a/apps/website/content/roam/views-and-tools/discourse-context-overlay.md b/apps/website/content/roam/views-and-tools/discourse-context-overlay.md new file mode 100644 index 000000000..41c1a2de4 --- /dev/null +++ b/apps/website/content/roam/views-and-tools/discourse-context-overlay.md @@ -0,0 +1,43 @@ +--- +title: "Discourse context overlay" +date: "2025-01-01" +author: "" +published: true +--- + +- [Discourse context](/docs/roam/views-and-tools/discourse-context) +- [Discourse context overlay](/docs/roam/views-and-tools/discourse-context-overlay) +- [Discourse attributes](/docs/roam/views-and-tools/discourse-attributes) +- [Node index](/docs/roam/views-and-tools/node-index) + +The discourse context overlay adds an icon next to each discourse node wherever it is referenced. This icon provides access to two key features: + +1. a popover to view the [Discourse context](/docs/roam/views-and-tools/discourse-context) of the node inline, and +2. a "Discourse score" component that displays a customizable score for the node that is some function of its relations to other nodes in the discourse graph. + +The overlay is an optional feature that is turned off by default. To turn it on, go to the grammar tab in the config page and check the box for overlay. + +![](/docs/roam/settings-discourse-context-overlay.png) + +## Popover + +The popover is simple to operate. Simply click on the icon to bring up the [discourse context](/docs/roam/views-and-tools/discourse-context) component in-line for quick reference. + +![](/docs/roam/discourse-context-overlay.gif) + +## Discourse score + +By default, the discourse score displays the count of the total number of discourse relations for that node (the number on the left), as well as a count of the total number of references to that node in the graph. + +For example, the following score display denotes that the node participates in 5 discourse relations with other nodes, which can be seen in detail in the discourse context popover (1 informs, 1 supports, 2 consistent with, and 1 sourced by; note that 2 of these relations are [custom relations](/docs/roam/guides/extending-personalizing-graph)). + +![](/docs/roam/discourse-context-overlay-score.png) + +You can think of this default discourse score as a rough sense of how "robust" a given node is (discourse relations are more structured, high-signal relationships) relative to how "important" it is (raw references are often noisy). If you'd like, you can also experiment with different functions of discourse relations to a node by defining your own [Discourse attributes](/docs/roam/views-and-tools/discourse-attributes), and have them show up in the overlay! + +## Demo + +(old video demo) + +https://www.loom.com/share/b3d6094cd14a466081b8aa8495eb6542 + diff --git a/apps/website/content/roam/views-and-tools/discourse-context.md b/apps/website/content/roam/views-and-tools/discourse-context.md new file mode 100644 index 000000000..f54d87fae --- /dev/null +++ b/apps/website/content/roam/views-and-tools/discourse-context.md @@ -0,0 +1,26 @@ +--- +title: "Discourse context" +date: "2025-01-01" +author: "" +published: true +--- + +- [Discourse context](/docs/roam/views-and-tools/discourse-context) +- [Discourse context overlay](/docs/roam/views-and-tools/discourse-context-overlay) +- [Discourse attributes](/docs/roam/views-and-tools/discourse-attributes) +- [Node index](/docs/roam/views-and-tools/node-index) + +The discourse context component adds a "higher-signal" linked references section to each discourse node, that allows you to explore _discourse_ relations (e.g., inform, support, etc.) between this node and other nodes in your discourse graph. + +## Group by target node + +![](/docs/roam/discourse-context-group-by-target.gif) + +## Filter results + +![](/docs/roam/discourse-context-filter.gif) + +## Demo + +https://www.loom.com/share/0c66e95d0c71426e8090a8bc1cbf8544 + diff --git a/apps/website/content/roam/views-and-tools/node-index.md b/apps/website/content/roam/views-and-tools/node-index.md new file mode 100644 index 000000000..49d6a2ea7 --- /dev/null +++ b/apps/website/content/roam/views-and-tools/node-index.md @@ -0,0 +1,18 @@ +--- +title: "Node index" +date: "2025-01-01" +author: "" +published: true +--- + +- [Discourse context](/docs/roam/views-and-tools/discourse-context) +- [Discourse context overlay](/docs/roam/views-and-tools/discourse-context-overlay) +- [Discourse attributes](/docs/roam/views-and-tools/discourse-attributes) +- [Node index](/docs/roam/views-and-tools/node-index) + +The extension has node settings tabs for each node you define, which provides a query over all of your nodes of that type. For example, you can go to the Claim tab to see all the Claim nodes in your graph. + +![](/docs/roam/settings-node-index.png) + +This can be quite handy in multiplayer settings, for example, to quickly view the latest question nodes that have been added to the graph, or who authored them, by modifying the default index query, just like a [regular query](/docs/roam/guides/querying-discourse-graph). + diff --git a/apps/website/content/roam/welcome/_meta.ts b/apps/website/content/roam/welcome/_meta.ts new file mode 100644 index 000000000..1f0b15743 --- /dev/null +++ b/apps/website/content/roam/welcome/_meta.ts @@ -0,0 +1,9 @@ +import type { MetaRecord } from "nextra"; + +const meta: MetaRecord = { + "getting-started": "Getting started", + installation: "Installation", + "installation-roam-depot": "Installation from Roam Depot", +}; + +export default meta; diff --git a/apps/website/content/roam/welcome/getting-started.md b/apps/website/content/roam/welcome/getting-started.md new file mode 100644 index 000000000..0e8672c35 --- /dev/null +++ b/apps/website/content/roam/welcome/getting-started.md @@ -0,0 +1,33 @@ +--- +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](/docs/roam/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](/docs/roam/guides/exploring-discourse-graph), [querying](/docs/roam/guides/querying-discourse-graph), and [sharing](/docs/roam/guides/sharing-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](/docs/roam/guides/creating-discourse-nodes) +- [Creating discourse relationships](/docs/roam/guides/creating-discourse-relationships) +- [Exploring your Discourse Graph](/docs/roam/guides/exploring-discourse-graph) +- [Querying your Discourse Graph](/docs/roam/guides/querying-discourse-graph) +- [Extending and Personalizing your Discourse Graph](/docs/roam/guides/extending-personalizing-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?](/docs/roam/fundamentals/what-is-a-discourse-graph) +- [The Discourse Graph extension grammar](/docs/roam/fundamentals/grammar) +- [The base grammar: questions, claims, and evidence](/docs/roam/fundamentals/base-grammar) + diff --git a/apps/website/content/roam/welcome/installation-roam-depot.md b/apps/website/content/roam/welcome/installation-roam-depot.md new file mode 100644 index 000000000..2d8d03902 --- /dev/null +++ b/apps/website/content/roam/welcome/installation-roam-depot.md @@ -0,0 +1,15 @@ +--- +title: "Installation" +date: "2025-01-01" +author: "" +published: false +--- + +The Discourse Graphs extension can be installed via Roam Depot: + +![](/docs/roam/roam-depot-sidebar.png) + +![](/docs/roam/roam-depot-settings.png) + +Then type in "Discourse Graphs" in the search bar and click install. + diff --git a/apps/website/content/roam/welcome/installation.md b/apps/website/content/roam/welcome/installation.md new file mode 100644 index 000000000..13bd7c302 --- /dev/null +++ b/apps/website/content/roam/welcome/installation.md @@ -0,0 +1,15 @@ +--- +title: "Installation" +date: "2025-01-01" +author: "" +published: true +--- + +The Discourse Graphs extension is now available for installation via Roam Depot. + +Search for Discourse Graph in Roam Depot + +![](/docs/roam/browse-roam-depot.png) +![](/docs/roam/find-in-roam-depot.png) +![](/docs/roam/install-instruction-roam-depot.png) + diff --git a/apps/website/docsRouteMap.ts b/apps/website/docsRouteMap.ts new file mode 100644 index 000000000..77cd8c2dd --- /dev/null +++ b/apps/website/docsRouteMap.ts @@ -0,0 +1,82 @@ +export const ROAM_DOC_SECTIONS = { + welcome: ["getting-started", "installation", "installation-roam-depot"], + guides: [ + "creating-discourse-nodes", + "tagging-candidate-nodes", + "creating-discourse-relationships", + "exploring-discourse-graph", + "querying-discourse-graph", + "extending-personalizing-graph", + "sharing-discourse-graph", + ], + fundamentals: [ + "what-is-a-discourse-graph", + "grammar", + "nodes", + "operators-relations", + "base-grammar", + "stored-relations", + "migration-to-stored-relations", + "relations-patterns", + ], + "views-and-tools": [ + "discourse-context", + "discourse-context-overlay", + "discourse-attributes", + "node-index", + ], + "use-cases": [ + "literature-reviewing", + "enhanced-zettelkasten", + "reading-clubs", + "lab-notebooks", + "research-roadmapping", + ], +} as const; + +export const OBSIDIAN_DOC_SECTIONS = { + welcome: ["getting-started", "installation"], + fundamentals: ["what-is-a-discourse-graph", "base-grammar"], + configuration: [ + "node-types-templates", + "relationship-types", + "general-settings", + ], + "core-features": [ + "creating-discourse-nodes", + "creating-discourse-relationships", + "discourse-context", + "canvas", + "node-tags", + ], + "advanced-features": ["command-palette", "sync-and-import"], + "use-cases": [ + "literature-reviewing", + "research-roadmapping", + "reading-clubs", + "lab-notebooks", + ], +} as const; + +type Redirect = { + source: string; + destination: string; + permanent: boolean; +}; + +const buildPlatformRedirects = ( + platform: "roam" | "obsidian", + sections: Record, +): Redirect[] => + Object.entries(sections).flatMap(([section, slugs]) => + slugs.map((slug) => ({ + source: `/docs/${platform}/${slug}`, + destination: `/docs/${platform}/${section}/${slug}`, + permanent: true, + })), + ); + +export const DOCS_REDIRECTS: Redirect[] = [ + ...buildPlatformRedirects("roam", ROAM_DOC_SECTIONS), + ...buildPlatformRedirects("obsidian", OBSIDIAN_DOC_SECTIONS), +]; diff --git a/apps/website/next.config.ts b/apps/website/next.config.ts index 498e5acea..167835927 100644 --- a/apps/website/next.config.ts +++ b/apps/website/next.config.ts @@ -1,16 +1,22 @@ import nextra from "nextra"; import type { NextConfig } from "next"; import { config } from "@repo/database/dbDotEnv"; +import { DOCS_REDIRECTS } from "./docsRouteMap"; config(); -const withNextra = nextra({}); +const withNextra = nextra({ + contentDirBasePath: "/docs", +}); const nextConfig: NextConfig = { reactStrictMode: true, serverRuntimeConfig: { maxDuration: 300, }, + async redirects() { + return DOCS_REDIRECTS; + }, turbopack: { resolveAlias: { "next-mdx-import-source-file": "./mdx-components.tsx", From b9b9ddb99fff0a9c2a8a2923671f92e4a398f632 Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Tue, 31 Mar 2026 13:02:23 -0600 Subject: [PATCH 02/14] Update ESLint configuration, package scripts, and add documentation indexing script - Modified ESLint configuration to include new file patterns and global variables. - Updated package.json to change the postbuild script to a new documentation indexing script. - Added a new script for building a search index from documentation markdown files. - Introduced tests for the new indexing script to ensure correct functionality. --- apps/website/eslint.config.mjs | 11 +- apps/website/package.json | 2 +- .../scripts/build-docs-search-index.mjs | 212 ++++++++++++++++++ .../scripts/build-docs-search-index.test.mjs | 46 ++++ apps/website/tsconfig.json | 2 +- 5 files changed, 270 insertions(+), 3 deletions(-) create mode 100644 apps/website/scripts/build-docs-search-index.mjs create mode 100644 apps/website/scripts/build-docs-search-index.test.mjs diff --git a/apps/website/eslint.config.mjs b/apps/website/eslint.config.mjs index f8db82476..9a7035ee9 100644 --- a/apps/website/eslint.config.mjs +++ b/apps/website/eslint.config.mjs @@ -15,6 +15,15 @@ export default [ }, }, { - ignores: [".next/**"], + files: ["scripts/**/*.mjs"], + languageOptions: { + globals: { + console: "readonly", + process: "readonly", + }, + }, + }, + { + ignores: [".next/**", "public/_pagefind/**"], }, ]; diff --git a/apps/website/package.json b/apps/website/package.json index a55b05a0c..2de7cc75b 100644 --- a/apps/website/package.json +++ b/apps/website/package.json @@ -7,7 +7,7 @@ "scripts": { "dev": "next dev", "build": "next build --no-lint", - "postbuild": "pagefind --site .next/server/app --output-path public/_pagefind", + "postbuild": "node ./scripts/build-docs-search-index.mjs", "start": "next start", "lint": "eslint .", "lint:fix": "eslint . --fix", diff --git a/apps/website/scripts/build-docs-search-index.mjs b/apps/website/scripts/build-docs-search-index.mjs new file mode 100644 index 000000000..f29931443 --- /dev/null +++ b/apps/website/scripts/build-docs-search-index.mjs @@ -0,0 +1,212 @@ +import fs from "node:fs/promises"; +import path from "node:path"; +import { pathToFileURL } from "node:url"; +import matter from "gray-matter"; +import { createIndex, close } from "pagefind"; + +/** + * @typedef {{ + * url: string; + * content: string; + * meta: { + * title: string; + * }; + * }} SearchRecord + */ + +const CONTENT_ROOT = path.join(process.cwd(), "content"); +const OUTPUT_PATH = path.join(process.cwd(), "public", "_pagefind"); +const DOCS_PREFIX = "/docs"; +const MARKDOWN_EXTENSIONS = new Set([".md", ".mdx"]); +const DOC_DIRECTORIES = ["roam", "obsidian"]; + +/** + * @param {string} value + * @returns {string} + */ +const collapseWhitespace = (value) => value.replace(/\s+/g, " ").trim(); + +/** + * @param {string} source + * @returns {string} + */ +export const markdownToSearchText = (source) => { + const withoutImports = source.replace(/^\s*(import|export)\s.+$/gm, " "); + const withoutFences = withoutImports.replace(/```[\s\S]*?```/g, " "); + const withoutImages = withoutFences.replace(/!\[([^\]]*)\]\([^)]+\)/g, " $1 "); + const withoutLinks = withoutImages.replace(/\[([^\]]+)\]\([^)]+\)/g, " $1 "); + const withoutHtml = withoutLinks.replace(/<[^>]+>/g, " "); + const withoutInlineCode = withoutHtml.replace(/`([^`]+)`/g, " $1 "); + const withoutMarkdownTokens = withoutInlineCode + .replace(/^#{1,6}\s*/gm, " ") + .replace(/^\s*>+\s?/gm, " ") + .replace(/^\s*[-*+]\s+/gm, " ") + .replace(/^\s*\d+\.\s+/gm, " ") + .replace(/\|/g, " ") + .replace(/[*_~]/g, " "); + + return collapseWhitespace(withoutMarkdownTokens); +}; + +/** + * @param {string} absoluteFilePath + * @returns {string} + */ +export const routePathFromContentFile = (absoluteFilePath) => { + const relativePath = path.relative(CONTENT_ROOT, absoluteFilePath); + const normalizedPath = relativePath.replace(/\\/g, "/"); + const withoutExtension = normalizedPath.replace(/\.(md|mdx)$/u, ""); + const segments = withoutExtension.split("/"); + + if (withoutExtension === "index") { + return DOCS_PREFIX; + } + + if (segments.at(-1) === "index") { + segments.pop(); + } + + return `${DOCS_PREFIX}/${segments.join("/")}`; +}; + +/** + * @param {string} absoluteFilePath + * @returns {string} + */ +const titleFromFilePath = (absoluteFilePath) => + path + .basename(absoluteFilePath, path.extname(absoluteFilePath)) + .split("-") + .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1)) + .join(" "); + +/** + * @param {string} absoluteFilePath + * @returns {boolean} + */ +const isMarkdownFile = (absoluteFilePath) => + MARKDOWN_EXTENSIONS.has(path.extname(absoluteFilePath)); + +/** + * @param {string} directory + * @returns {Promise} + */ +const collectMarkdownFiles = async (directory) => { + const entries = await fs.readdir(directory, { withFileTypes: true }); + const nestedFiles = await Promise.all( + entries.map(async (entry) => { + const absolutePath = path.join(directory, entry.name); + + if (entry.isDirectory()) { + return collectMarkdownFiles(absolutePath); + } + + return isMarkdownFile(absolutePath) ? [absolutePath] : []; + }), + ); + + return nestedFiles.flat(); +}; + +/** + * @param {string} absoluteFilePath + * @returns {Promise} + */ +const readDocRecord = async (absoluteFilePath) => { + const rawFile = await fs.readFile(absoluteFilePath, "utf8"); + const { content, data } = matter(rawFile); + + if (data.published === false) { + return null; + } + + const title = + typeof data.title === "string" && data.title.trim().length + ? data.title.trim() + : titleFromFilePath(absoluteFilePath); + const searchText = markdownToSearchText(content); + + if (!searchText.length) { + return null; + } + + return { + url: routePathFromContentFile(absoluteFilePath), + content: `${title}\n${searchText}`, + meta: { + title, + }, + }; +}; + +/** + * @returns {Promise} + */ +const collectDocRecords = async () => { + const docFiles = await Promise.all( + DOC_DIRECTORIES.map((directory) => + collectMarkdownFiles(path.join(CONTENT_ROOT, directory)), + ), + ); + const topLevelDocs = [path.join(CONTENT_ROOT, "index.mdx")]; + const allFiles = [...topLevelDocs, ...docFiles.flat()]; + const records = await Promise.all(allFiles.map(readDocRecord)); + + return records.filter(Boolean); +}; + +/** + * @returns {Promise} + */ +const buildDocsSearchIndex = async () => { + await fs.rm(OUTPUT_PATH, { recursive: true, force: true }); + + const records = await collectDocRecords(); + const { index, errors } = await createIndex({ + forceLanguage: "en", + }); + + if (errors.length) { + throw new Error(errors.join("\n")); + } + + if (!index) { + throw new Error("Pagefind did not return an index instance."); + } + + for (const record of records) { + const { errors: recordErrors } = await index.addCustomRecord({ + ...record, + language: "en", + }); + + if (recordErrors.length) { + throw new Error(recordErrors.join("\n")); + } + } + + const { errors: writeErrors } = await index.writeFiles({ + outputPath: OUTPUT_PATH, + }); + + if (writeErrors.length) { + throw new Error(writeErrors.join("\n")); + } + + console.log(`Indexed ${records.length} docs pages into ${OUTPUT_PATH}`); +}; + +const isDirectExecution = + process.argv[1] && + import.meta.url === pathToFileURL(process.argv[1]).href; + +if (isDirectExecution) { + void buildDocsSearchIndex() + .catch((error) => { + console.error(error); + process.exitCode = 1; + }) + .finally(() => { + void close(); + }); +} diff --git a/apps/website/scripts/build-docs-search-index.test.mjs b/apps/website/scripts/build-docs-search-index.test.mjs new file mode 100644 index 000000000..db186cb11 --- /dev/null +++ b/apps/website/scripts/build-docs-search-index.test.mjs @@ -0,0 +1,46 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import path from "node:path"; +import { + markdownToSearchText, + routePathFromContentFile, +} from "./build-docs-search-index.mjs"; + +void test("routePathFromContentFile maps content files to canonical docs routes", () => { + assert.equal( + routePathFromContentFile( + path.join(process.cwd(), "content", "roam", "welcome", "getting-started.md"), + ), + "/docs/roam/welcome/getting-started", + ); + assert.equal( + routePathFromContentFile( + path.join(process.cwd(), "content", "obsidian", "index.mdx"), + ), + "/docs/obsidian", + ); + assert.equal( + routePathFromContentFile(path.join(process.cwd(), "content", "index.mdx")), + "/docs", + ); +}); + +void test("markdownToSearchText strips MDX component markup but keeps readable text", () => { + const source = `import { Callout } from "nextra/components" + +# Documentation + +Choose the \`/docs\` routes. + + + Shared conceptual docs stay stable. + + +- [Roam docs](/docs/roam) +`; + + assert.equal( + markdownToSearchText(source), + 'Documentation Choose the /docs routes. Shared conceptual docs stay stable. Roam docs', + ); +}); diff --git a/apps/website/tsconfig.json b/apps/website/tsconfig.json index d7bf5c41c..a32535e2c 100644 --- a/apps/website/tsconfig.json +++ b/apps/website/tsconfig.json @@ -12,7 +12,7 @@ "next.config.ts", "**/*.ts", "**/*.tsx", - "scripts/*tx", + "scripts/**/*.mjs", ".next/types/**/*.ts", "postcss.config.mjs" ] From 0110a5b831657c52b5160af38696c7c28a4a2293 Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Tue, 31 Mar 2026 13:43:51 -0600 Subject: [PATCH 03/14] Refactor Logo component to use SVG instead of Image component - Replaced the Image component with a span that utilizes an SVG mask for the logo rendering. - Added a new SVG file for the logo to enhance scalability and styling flexibility. --- apps/website/app/components/Logo.tsx | 19 +++++++++++++------ apps/website/public/logo-light-48.svg | 6 ++++++ 2 files changed, 19 insertions(+), 6 deletions(-) create mode 100644 apps/website/public/logo-light-48.svg diff --git a/apps/website/app/components/Logo.tsx b/apps/website/app/components/Logo.tsx index 134b30277..e7eef8ae8 100644 --- a/apps/website/app/components/Logo.tsx +++ b/apps/website/app/components/Logo.tsx @@ -1,7 +1,6 @@ "use client"; import Link from "next/link"; -import Image from "next/image"; import { usePathname } from "next/navigation"; import { PlatformBadge } from "./PlatformBadge"; @@ -27,11 +26,19 @@ export const Logo = ({ const brand = ( <> - diff --git a/apps/website/public/logo-light-48.svg b/apps/website/public/logo-light-48.svg new file mode 100644 index 000000000..693b77557 --- /dev/null +++ b/apps/website/public/logo-light-48.svg @@ -0,0 +1,6 @@ + + + + \ No newline at end of file From 3fdad2b5ef9a9e23c8fb1b5032141975ac7be01a Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Tue, 31 Mar 2026 13:58:06 -0600 Subject: [PATCH 04/14] Add Nextra CSS reset class for content width - Introduced a new `.nextra-reset` class in `nextra-css.css` to set the content width to 90rem, enhancing layout consistency across the website. --- apps/website/app/(nextra)/nextra-css.css | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/apps/website/app/(nextra)/nextra-css.css b/apps/website/app/(nextra)/nextra-css.css index 65dd5f63a..8d62f2633 100644 --- a/apps/website/app/(nextra)/nextra-css.css +++ b/apps/website/app/(nextra)/nextra-css.css @@ -1 +1,5 @@ @tailwind utilities; + +.nextra-reset { + --nextra-content-width: 90rem; +} From 73484357fbd7369d60d29d8bbbff68aa465b1bc8 Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Tue, 31 Mar 2026 17:19:29 -0600 Subject: [PATCH 05/14] separate search --- .../app/(docs)/docs/(landing)/layout.tsx | 13 ++---- .../docs/_components/DocsThemeLayout.tsx | 42 +++++++++++++++++++ .../app/(docs)/docs/obsidian/layout.tsx | 6 ++- apps/website/app/(docs)/docs/roam/layout.tsx | 6 ++- .../scripts/build-docs-search-index.mjs | 32 ++++++++++++-- .../scripts/build-docs-search-index.test.mjs | 20 +++++++++ 6 files changed, 103 insertions(+), 16 deletions(-) diff --git a/apps/website/app/(docs)/docs/(landing)/layout.tsx b/apps/website/app/(docs)/docs/(landing)/layout.tsx index 2c0bb05e2..0c9eee5c2 100644 --- a/apps/website/app/(docs)/docs/(landing)/layout.tsx +++ b/apps/website/app/(docs)/docs/(landing)/layout.tsx @@ -1,18 +1,11 @@ -import { getPageMap } from "nextra/page-map"; -import DocsThemeLayout from "../_components/DocsThemeLayout"; -import "../../../(nextra)/nextra-css.css"; -import "nextra-theme-docs/style-prefixed.css"; +import "~/globals.css"; type DocsLandingLayoutProps = { children: React.ReactNode; }; -const DocsLandingLayout = async ({ +const DocsLandingLayout = ({ children, -}: DocsLandingLayoutProps): Promise => { - const pageMap = await getPageMap("/docs"); - - return {children}; -}; +}: DocsLandingLayoutProps): React.ReactElement => <>{children}; export default DocsLandingLayout; diff --git a/apps/website/app/(docs)/docs/_components/DocsThemeLayout.tsx b/apps/website/app/(docs)/docs/_components/DocsThemeLayout.tsx index 1eae7a897..c2d96ebdc 100644 --- a/apps/website/app/(docs)/docs/_components/DocsThemeLayout.tsx +++ b/apps/website/app/(docs)/docs/_components/DocsThemeLayout.tsx @@ -1,16 +1,57 @@ import type { PageMapItem } from "nextra"; +import { Search } from "nextra/components"; import { Footer, Layout, Navbar } from "nextra-theme-docs"; import { Logo } from "~/components/Logo"; +type DocsSearchScope = "roam" | "obsidian"; + type DocsThemeLayoutProps = { children: React.ReactNode; + hideSearch?: boolean; pageMap: PageMapItem[]; + searchScope?: DocsSearchScope; +}; + +const SEARCH_PLACEHOLDERS: Record = { + obsidian: "Search Obsidian docs...", + roam: "Search Roam docs...", +}; + +const renderSearch = ({ + hideSearch, + searchScope, +}: Pick): + | React.ReactElement + | null + | undefined => { + if (hideSearch) { + return null; + } + + if (!searchScope) { + return undefined; + } + + return ( + + ); }; const DocsThemeLayout = ({ children, + hideSearch, pageMap, + searchScope, }: DocsThemeLayoutProps): React.ReactElement => { + const search = renderSearch({ hideSearch, searchScope }); + return (
} pageMap={pageMap} + search={search} sidebar={{ defaultMenuCollapseLevel: 1, }} diff --git a/apps/website/app/(docs)/docs/obsidian/layout.tsx b/apps/website/app/(docs)/docs/obsidian/layout.tsx index 85aa0e8c3..9c136cbc6 100644 --- a/apps/website/app/(docs)/docs/obsidian/layout.tsx +++ b/apps/website/app/(docs)/docs/obsidian/layout.tsx @@ -12,7 +12,11 @@ const ObsidianDocsLayout = async ({ }: ObsidianDocsLayoutProps): Promise => { const pageMap = await getPageMap("/docs/obsidian"); - return {children}; + return ( + + {children} + + ); }; export default ObsidianDocsLayout; diff --git a/apps/website/app/(docs)/docs/roam/layout.tsx b/apps/website/app/(docs)/docs/roam/layout.tsx index 38570535f..9a82c0eb4 100644 --- a/apps/website/app/(docs)/docs/roam/layout.tsx +++ b/apps/website/app/(docs)/docs/roam/layout.tsx @@ -12,7 +12,11 @@ const RoamDocsLayout = async ({ }: RoamDocsLayoutProps): Promise => { const pageMap = await getPageMap("/docs/roam"); - return {children}; + return ( + + {children} + + ); }; export default RoamDocsLayout; diff --git a/apps/website/scripts/build-docs-search-index.mjs b/apps/website/scripts/build-docs-search-index.mjs index f29931443..d4e0766e7 100644 --- a/apps/website/scripts/build-docs-search-index.mjs +++ b/apps/website/scripts/build-docs-search-index.mjs @@ -4,6 +4,10 @@ import { pathToFileURL } from "node:url"; import matter from "gray-matter"; import { createIndex, close } from "pagefind"; +/** + * @typedef {Record} SearchFilters + */ + /** * @typedef {{ * url: string; @@ -11,6 +15,7 @@ import { createIndex, close } from "pagefind"; * meta: { * title: string; * }; + * filters?: SearchFilters; * }} SearchRecord */ @@ -69,6 +74,24 @@ export const routePathFromContentFile = (absoluteFilePath) => { return `${DOCS_PREFIX}/${segments.join("/")}`; }; +/** + * @param {string} absoluteFilePath + * @returns {SearchFilters | undefined} + */ +export const searchFiltersFromContentFile = (absoluteFilePath) => { + const relativePath = path.relative(CONTENT_ROOT, absoluteFilePath); + const normalizedPath = relativePath.replace(/\\/g, "/"); + const [topLevelDirectory] = normalizedPath.split("/"); + + if (DOC_DIRECTORIES.includes(topLevelDirectory)) { + return { + platform: [topLevelDirectory], + }; + } + + return undefined; +}; + /** * @param {string} absoluteFilePath * @returns {string} @@ -125,6 +148,7 @@ const readDocRecord = async (absoluteFilePath) => { ? data.title.trim() : titleFromFilePath(absoluteFilePath); const searchText = markdownToSearchText(content); + const filters = searchFiltersFromContentFile(absoluteFilePath); if (!searchText.length) { return null; @@ -136,6 +160,7 @@ const readDocRecord = async (absoluteFilePath) => { meta: { title, }, + ...(filters ? { filters } : {}), }; }; @@ -148,11 +173,10 @@ const collectDocRecords = async () => { collectMarkdownFiles(path.join(CONTENT_ROOT, directory)), ), ); - const topLevelDocs = [path.join(CONTENT_ROOT, "index.mdx")]; - const allFiles = [...topLevelDocs, ...docFiles.flat()]; + const allFiles = docFiles.flat(); const records = await Promise.all(allFiles.map(readDocRecord)); - return records.filter(Boolean); + return records.filter((record) => record !== null); }; /** @@ -198,7 +222,7 @@ const buildDocsSearchIndex = async () => { const isDirectExecution = process.argv[1] && - import.meta.url === pathToFileURL(process.argv[1]).href; + import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href; if (isDirectExecution) { void buildDocsSearchIndex() diff --git a/apps/website/scripts/build-docs-search-index.test.mjs b/apps/website/scripts/build-docs-search-index.test.mjs index db186cb11..7313837b3 100644 --- a/apps/website/scripts/build-docs-search-index.test.mjs +++ b/apps/website/scripts/build-docs-search-index.test.mjs @@ -4,6 +4,7 @@ import path from "node:path"; import { markdownToSearchText, routePathFromContentFile, + searchFiltersFromContentFile, } from "./build-docs-search-index.mjs"; void test("routePathFromContentFile maps content files to canonical docs routes", () => { @@ -44,3 +45,22 @@ Choose the \`/docs\` routes. 'Documentation Choose the /docs routes. Shared conceptual docs stay stable. Roam docs', ); }); + +void test("searchFiltersFromContentFile scopes docs records by platform", () => { + assert.deepEqual( + searchFiltersFromContentFile( + path.join(process.cwd(), "content", "roam", "welcome", "getting-started.md"), + ), + { platform: ["roam"] }, + ); + assert.deepEqual( + searchFiltersFromContentFile( + path.join(process.cwd(), "content", "obsidian", "index.mdx"), + ), + { platform: ["obsidian"] }, + ); + assert.equal( + searchFiltersFromContentFile(path.join(process.cwd(), "content", "index.mdx")), + undefined, + ); +}); From 625921b380180379be40b119fe4b324d8c2f189d Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Tue, 31 Mar 2026 17:21:09 -0600 Subject: [PATCH 06/14] docs landing page --- .../app/(docs)/docs/(landing)/page.tsx | 128 ++++++++++++------ 1 file changed, 88 insertions(+), 40 deletions(-) diff --git a/apps/website/app/(docs)/docs/(landing)/page.tsx b/apps/website/app/(docs)/docs/(landing)/page.tsx index da60503a5..b590014b2 100644 --- a/apps/website/app/(docs)/docs/(landing)/page.tsx +++ b/apps/website/app/(docs)/docs/(landing)/page.tsx @@ -1,47 +1,95 @@ import type { Metadata } from "next"; -import { notFound } from "next/navigation"; -import { importPage } from "nextra/pages"; -import { useMDXComponents } from "../../../../mdx-components"; - -type ImportedPage = Awaited>; - -const { wrapper } = useMDXComponents(); - -const Wrapper = wrapper as React.ComponentType<{ - children: React.ReactNode; - metadata: ImportedPage["metadata"]; - toc: ImportedPage["toc"]; -}>; - -const loadPage = async (): Promise => importPage([]); - -const Page = async (): Promise => { - try { - const { default: MDXContent, metadata, toc } = await loadPage(); - - return ( - - - - ); - } catch (error) { - console.error("Error rendering docs landing page:", error); - notFound(); - } +import Link from "next/link"; +import { ArrowRight } from "lucide-react"; +import { Card, CardContent } from "@repo/ui/components/ui/card"; +import { PlatformBadge } from "~/components/PlatformBadge"; +import { Logo } from "~/components/Logo"; + +export const metadata: Metadata = { + title: "Documentation", + description: + "Choose the Discourse Graphs documentation for Roam Research or Obsidian.", }; -export const generateMetadata = async (): Promise => { - try { - const { metadata } = await loadPage(); +const DOCS_DESTINATIONS = [ + { + description: + "Installation, graph building, querying, and advanced workflows for the Roam Research plugin.", + href: "/docs/roam", + platform: "roam", + title: "Roam docs", + }, + { + description: + "Setup, node and relation authoring, sync, and workspace configuration for the Obsidian plugin.", + href: "/docs/obsidian", + platform: "obsidian", + title: "Obsidian docs", + }, +] as const; + +const DocsLandingPage = (): React.ReactElement => { + return ( +
+
+
+ + + Back to site + +
+
+ +
+
+
+

+ Documentation +

+

+ Choose your docs +

+

+ Discourse Graphs has separate documentation for each client. Pick + the one you are using to get the right setup instructions, + workflows, and reference pages. +

+
+ +
+ {DOCS_DESTINATIONS.map(({ description, href, platform, title }) => ( + + + +
+ + +
- return metadata; - } catch (error) { - console.error("Error generating docs landing metadata:", error); +
+

+ {title} +

+

+ {description} +

+
- return { - title: "Docs", - }; - } +

+ Open documentation +

+ + + + ))} +
+
+
+
+ ); }; -export default Page; +export default DocsLandingPage; From ac0eb7187e3a7391285d29bdb3bc240b99c90bc1 Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Tue, 31 Mar 2026 17:40:12 -0600 Subject: [PATCH 07/14] Add DocsPageTemplate component and refactor documentation page rendering - Introduced a new `DocsPageTemplate` component to standardize the layout for documentation pages. - Updated the Obsidian and Roam documentation page files to utilize the new `DocsPageTemplate`, improving code consistency and maintainability. - Removed direct usage of `useMDXComponents` in favor of the new template for better structure. --- .../docs/_components/DocsPageTemplate.tsx | 34 +++++++++++++++++++ .../docs/obsidian/[[...mdxPath]]/page.tsx | 17 +++------- .../(docs)/docs/roam/[[...mdxPath]]/page.tsx | 17 +++------- 3 files changed, 44 insertions(+), 24 deletions(-) create mode 100644 apps/website/app/(docs)/docs/_components/DocsPageTemplate.tsx diff --git a/apps/website/app/(docs)/docs/_components/DocsPageTemplate.tsx b/apps/website/app/(docs)/docs/_components/DocsPageTemplate.tsx new file mode 100644 index 000000000..ccd8d6506 --- /dev/null +++ b/apps/website/app/(docs)/docs/_components/DocsPageTemplate.tsx @@ -0,0 +1,34 @@ +import type { EvaluateResult } from "nextra"; +import { useMDXComponents } from "mdx-components"; + +type DocsPageTemplateProps = Omit & { + children: React.ReactNode; +}; + +const hasPrimaryHeading = (sourceCode: string): boolean => + /(^|\n)#\s+\S/m.test(sourceCode); + +const DocsPageTemplate = ({ + children, + metadata, + sourceCode, + ...wrapperProps +}: DocsPageTemplateProps): React.ReactElement => { + const { h1, wrapper } = useMDXComponents(); + // eslint-disable-next-line @typescript-eslint/naming-convention + const Wrapper = wrapper as React.ComponentType; + const H1 = h1 as React.ComponentType< + React.HTMLAttributes & { + children: React.ReactNode; + } + >; + + return ( + + {!hasPrimaryHeading(sourceCode) &&

{metadata.title}

} + {children} + + ); +}; + +export default DocsPageTemplate; diff --git a/apps/website/app/(docs)/docs/obsidian/[[...mdxPath]]/page.tsx b/apps/website/app/(docs)/docs/obsidian/[[...mdxPath]]/page.tsx index b9155694d..f4600feb1 100644 --- a/apps/website/app/(docs)/docs/obsidian/[[...mdxPath]]/page.tsx +++ b/apps/website/app/(docs)/docs/obsidian/[[...mdxPath]]/page.tsx @@ -1,7 +1,7 @@ import type { Metadata } from "next"; import { notFound } from "next/navigation"; import { generateStaticParamsFor, importPage } from "nextra/pages"; -import { useMDXComponents } from "../../../../../mdx-components"; +import DocsPageTemplate from "../../_components/DocsPageTemplate"; type DocsPageProps = { params: Promise<{ @@ -11,14 +11,6 @@ type DocsPageProps = { type ImportedPage = Awaited>; -const { wrapper } = useMDXComponents(); - -const Wrapper = wrapper as React.ComponentType<{ - children: React.ReactNode; - metadata: ImportedPage["metadata"]; - toc: ImportedPage["toc"]; -}>; - const generateAllStaticParams = generateStaticParamsFor("mdxPath"); const loadPage = async (mdxPath?: string[]): Promise => @@ -43,12 +35,13 @@ export const generateStaticParams = async (): Promise< const Page = async ({ params }: DocsPageProps): Promise => { try { const { mdxPath } = await params; - const { default: MDXContent, metadata, toc } = await loadPage(mdxPath); + const result = await loadPage(mdxPath); + const { default: MDXContent, ...wrapperProps } = result; return ( - + - + ); } catch (error) { console.error("Error rendering Obsidian docs page:", error); diff --git a/apps/website/app/(docs)/docs/roam/[[...mdxPath]]/page.tsx b/apps/website/app/(docs)/docs/roam/[[...mdxPath]]/page.tsx index 734ab2e6a..42180f867 100644 --- a/apps/website/app/(docs)/docs/roam/[[...mdxPath]]/page.tsx +++ b/apps/website/app/(docs)/docs/roam/[[...mdxPath]]/page.tsx @@ -1,7 +1,7 @@ import type { Metadata } from "next"; import { notFound } from "next/navigation"; import { generateStaticParamsFor, importPage } from "nextra/pages"; -import { useMDXComponents } from "../../../../../mdx-components"; +import DocsPageTemplate from "../../_components/DocsPageTemplate"; type DocsPageProps = { params: Promise<{ @@ -11,14 +11,6 @@ type DocsPageProps = { type ImportedPage = Awaited>; -const { wrapper } = useMDXComponents(); - -const Wrapper = wrapper as React.ComponentType<{ - children: React.ReactNode; - metadata: ImportedPage["metadata"]; - toc: ImportedPage["toc"]; -}>; - const generateAllStaticParams = generateStaticParamsFor("mdxPath"); const loadPage = async (mdxPath?: string[]): Promise => @@ -43,12 +35,13 @@ export const generateStaticParams = async (): Promise< const Page = async ({ params }: DocsPageProps): Promise => { try { const { mdxPath } = await params; - const { default: MDXContent, metadata, toc } = await loadPage(mdxPath); + const result = await loadPage(mdxPath); + const { default: MDXContent, ...wrapperProps } = result; return ( - + - + ); } catch (error) { console.error("Error rendering Roam docs page:", error); From e984a0d3f927b2cecd24b2b7af58f7d138f80ba7 Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Tue, 31 Mar 2026 20:49:15 -0600 Subject: [PATCH 08/14] format --- .../app/(docs)/docs/(landing)/page.tsx | 2 +- apps/website/content/index.mdx | 12 ++------- .../advanced-features/command-palette.md | 1 - .../advanced-features/sync-and-import.md | 1 - .../configuration/general-settings.md | 1 - .../configuration/node-types-templates.md | 1 - .../configuration/relationship-types.md | 13 +++++----- .../content/obsidian/core-features/canvas.md | 1 - .../core-features/creating-discourse-nodes.md | 17 +++++++------ .../creating-discourse-relationships.md | 12 ++++----- .../core-features/discourse-context.md | 1 - .../obsidian/core-features/node-tags.md | 8 +++--- .../obsidian/fundamentals/base-grammar.md | 1 - .../fundamentals/what-is-a-discourse-graph.md | 1 - apps/website/content/obsidian/index.mdx | 25 +++++++++++++++---- .../obsidian/use-cases/lab-notebooks.md | 1 - .../use-cases/literature-reviewing.md | 1 - .../obsidian/use-cases/reading-clubs.md | 1 - .../use-cases/research-roadmapping.md | 1 - .../obsidian/welcome/getting-started.md | 1 - .../content/obsidian/welcome/installation.md | 13 +++++----- .../content/roam/fundamentals/base-grammar.md | 1 - .../content/roam/fundamentals/grammar.md | 1 - .../migration-to-stored-relations.md | 1 - .../content/roam/fundamentals/nodes.md | 1 - .../roam/fundamentals/operators-relations.md | 1 - .../roam/fundamentals/relations-patterns.md | 1 - .../roam/fundamentals/stored-relations.md | 1 - .../fundamentals/what-is-a-discourse-graph.md | 1 - .../roam/guides/creating-discourse-nodes.md | 1 - .../creating-discourse-relationships.md | 1 - .../roam/guides/exploring-discourse-graph.md | 1 - .../guides/extending-personalizing-graph.md | 1 - .../roam/guides/querying-discourse-graph.md | 1 - .../roam/guides/sharing-discourse-graph.md | 1 - .../roam/guides/tagging-candidate-nodes.md | 1 - apps/website/content/roam/index.mdx | 25 +++++++++++++++---- .../roam/use-cases/enhanced-zettelkasten.md | 1 - .../content/roam/use-cases/lab-notebooks.md | 1 - .../roam/use-cases/literature-reviewing.md | 1 - .../content/roam/use-cases/reading-clubs.md | 1 - .../roam/use-cases/research-roadmapping.md | 1 - .../views-and-tools/discourse-attributes.md | 1 - .../discourse-context-overlay.md | 1 - .../roam/views-and-tools/discourse-context.md | 1 - .../roam/views-and-tools/node-index.md | 1 - .../content/roam/welcome/getting-started.md | 1 - .../roam/welcome/installation-roam-depot.md | 1 - .../content/roam/welcome/installation.md | 1 - .../scripts/build-docs-search-index.mjs | 5 +++- .../scripts/build-docs-search-index.test.mjs | 22 +++++++++++++--- package.json | 4 +-- 52 files changed, 101 insertions(+), 97 deletions(-) diff --git a/apps/website/app/(docs)/docs/(landing)/page.tsx b/apps/website/app/(docs)/docs/(landing)/page.tsx index b590014b2..43c929aca 100644 --- a/apps/website/app/(docs)/docs/(landing)/page.tsx +++ b/apps/website/app/(docs)/docs/(landing)/page.tsx @@ -30,7 +30,7 @@ const DOCS_DESTINATIONS = [ const DocsLandingPage = (): React.ReactElement => { return ( -
+
diff --git a/apps/website/content/index.mdx b/apps/website/content/index.mdx index feb94c181..3a4378e9a 100644 --- a/apps/website/content/index.mdx +++ b/apps/website/content/index.mdx @@ -16,14 +16,6 @@ Choose the product documentation you need. All `/docs` routes now render through - - + + diff --git a/apps/website/content/obsidian/advanced-features/command-palette.md b/apps/website/content/obsidian/advanced-features/command-palette.md index 77b2d4636..620368949 100644 --- a/apps/website/content/obsidian/advanced-features/command-palette.md +++ b/apps/website/content/obsidian/advanced-features/command-palette.md @@ -21,4 +21,3 @@ You can customize how commands appear in the Command Palette: 2. Go to "Hotkeys" 3. Search for "Discourse" 4. Modify the commands or add hotkeys - diff --git a/apps/website/content/obsidian/advanced-features/sync-and-import.md b/apps/website/content/obsidian/advanced-features/sync-and-import.md index c7ada41c1..a2fede972 100644 --- a/apps/website/content/obsidian/advanced-features/sync-and-import.md +++ b/apps/website/content/obsidian/advanced-features/sync-and-import.md @@ -148,4 +148,3 @@ Alternatively, you can click the "Refresh" button in the Discourse Context panel - **No importable nodes found** — Either no nodes have been published to your groups, or you have already imported all available nodes - The frontmatter fields related to sync are normally hidden. You can choose to display them in the setting panel ![Show frontmatter](/docs/obsidian/show-frontmatter.png) - diff --git a/apps/website/content/obsidian/configuration/general-settings.md b/apps/website/content/obsidian/configuration/general-settings.md index f67fdc640..a7f2b13e7 100644 --- a/apps/website/content/obsidian/configuration/general-settings.md +++ b/apps/website/content/obsidian/configuration/general-settings.md @@ -25,4 +25,3 @@ This setting determines where new discourse nodes will be created in your vault. - Example format: `folder1/folder2` Changes to these settings will only take effect after clicking the "Save Changes" button. The interface will indicate when you have unsaved changes pending. - diff --git a/apps/website/content/obsidian/configuration/node-types-templates.md b/apps/website/content/obsidian/configuration/node-types-templates.md index b029f6f7b..df8db92b0 100644 --- a/apps/website/content/obsidian/configuration/node-types-templates.md +++ b/apps/website/content/obsidian/configuration/node-types-templates.md @@ -50,4 +50,3 @@ Templates allow you to automatically add predefined content when creating new no - [Configure relationship types](/docs/obsidian/configuration/relationship-types) - [Learn about creating nodes](/docs/obsidian/core-features/creating-discourse-nodes) - [Explore advanced template usage](/docs/obsidian/configuration/node-types-templates#working-with-templates) - diff --git a/apps/website/content/obsidian/configuration/relationship-types.md b/apps/website/content/obsidian/configuration/relationship-types.md index 73a5abfbd..ce6344d17 100644 --- a/apps/website/content/obsidian/configuration/relationship-types.md +++ b/apps/website/content/obsidian/configuration/relationship-types.md @@ -8,6 +8,7 @@ published: true ## Understanding relationship types Relationship types define how different nodes in your discourse graph can connect to each other. Each relationship type has: + - A primary label (e.g., "supports") - A complement label (e.g., "is supported by") - Rules about which node types can be connected @@ -20,7 +21,7 @@ Relationship types define how different nodes in your discourse graph can connec 4. Configure the relationship: - Enter the primary label (e.g., "supports", "contradicts") - Enter the complement label (e.g., "is supported by", "is contradicted by") - ![add relation type](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2Fjk367dcO_K.png?alt=media&token=22d74e9f-882c-434b-8b50-afd7a754fb2b) + ![add relation type](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2Fjk367dcO_K.png?alt=media&token=22d74e9f-882c-434b-8b50-afd7a754fb2b) 5. Click "Save Changes" ## Configuring valid relationships @@ -28,20 +29,21 @@ Relationship types define how different nodes in your discourse graph can connec After creating relationship types, you need to define which node types can be connected by each relationship. 1. Open the Discourse Relations tab in settings -![discourse relation](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FNgm7Ha4Ul5.png?alt=media&token=a933bd3a-d9a6-42c1-9c6e-d779d41c7ebf) + ![discourse relation](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FNgm7Ha4Ul5.png?alt=media&token=a933bd3a-d9a6-42c1-9c6e-d779d41c7ebf) 2. Choose the components: - Source Node Type (e.g., Claim) - Relationship Type (e.g., supports) - Target Node Type (e.g., Question) -![choose relation](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FlflJBkfdaK.png?alt=media&token=5de9617c-6099-46e8-931f-feafc604cabb) + ![choose relation](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FlflJBkfdaK.png?alt=media&token=5de9617c-6099-46e8-931f-feafc604cabb) 3. Review and confirm the configuration -![final relations](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FycPW-N-rY8.png?alt=media&token=54867be2-9030-4c6c-82d2-b96069e52d81) + ![final relations](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FycPW-N-rY8.png?alt=media&token=54867be2-9030-4c6c-82d2-b96069e52d81) ## Example relationships Here are some common relationship types: + - Claim → supports → Question - Evidence → supports → Claim - Evidence → contradicts → Claim @@ -51,5 +53,4 @@ Here are some common relationship types: - [Create your first relationship](/docs/obsidian/core-features/creating-discourse-relationships) - [Learn about the discourse context](/docs/obsidian/core-features/discourse-context) -- [Explore your graph](/docs/obsidian/core-features/canvas) - +- [Explore your graph](/docs/obsidian/core-features/canvas) diff --git a/apps/website/content/obsidian/core-features/canvas.md b/apps/website/content/obsidian/core-features/canvas.md index dd3e95cef..9334e9295 100644 --- a/apps/website/content/obsidian/core-features/canvas.md +++ b/apps/website/content/obsidian/core-features/canvas.md @@ -147,4 +147,3 @@ Then you will see the image show up if any is present in the file. ### Getting Help If you encounter issues with the canvas feature, reach out to our dev team via [Slack](https://join.slack.com/t/discoursegraphs/shared_invite/zt-37xklatti-cpEjgPQC0YyKYQWPNgAkEg) - diff --git a/apps/website/content/obsidian/core-features/creating-discourse-nodes.md b/apps/website/content/obsidian/core-features/creating-discourse-nodes.md index 0238d7e29..66ff68fdd 100644 --- a/apps/website/content/obsidian/core-features/creating-discourse-nodes.md +++ b/apps/website/content/obsidian/core-features/creating-discourse-nodes.md @@ -14,27 +14,28 @@ To create a discourse node, first select the text you want to turn into a node: There are two ways you can create a node: ### 1. Using command keys (recommended) + #### 1.1 Turn selected text into discourse node 1. Press `Cmd + \` (or your configured hotkey) 2. The Node Menu will open as a popup -![node menu](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FS6eU6y70eX.png?alt=media&token=00e61ddf-877b-4752-a65b-272e80a0a19c) + ![node menu](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FS6eU6y70eX.png?alt=media&token=00e61ddf-877b-4752-a65b-272e80a0a19c) 3. Select the node type you want to turn the text into 4. A new discourse node will be created -![node created](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2F1VNkJC0aH8.png?alt=media&token=df9a26aa-997b-4b56-a307-87a80e350b28) + ![node created](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2F1VNkJC0aH8.png?alt=media&token=df9a26aa-997b-4b56-a307-87a80e350b28) #### 1.2 Creating new node from scratch + 1. Press `Cmd + \` (or your configured hotkey) 2. Enter the title and node type -![](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FyYxtLKkx6B.png?alt=media&token=7f4f02df-d1fe-4529-8530-90acb0dc74b8) + ![](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FyYxtLKkx6B.png?alt=media&token=7f4f02df-d1fe-4529-8530-90acb0dc74b8) ### 2. Using the right-click menu 1. Right-click on the selected text -Alternatively, you can right-click on the selected text + Alternatively, you can right-click on the selected text -![right click menu](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2F4UqeVkqLz7.png?alt=media&token=d2373152-d251-45fe-afb6-56373d6092aa) -2. Choose a node type from the "Turn into discourse node" menu +![right click menu](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2F4UqeVkqLz7.png?alt=media&token=d2373152-d251-45fe-afb6-56373d6092aa) 2. Choose a node type from the "Turn into discourse node" menu ### 3. Turn existing page into discourse node @@ -43,16 +44,16 @@ If a page is not a discourse node, you can turn it into one by clicking on the f After choosing a node type, you can edit the title and node type in the menu ![](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FVZ-jWbffHY.png?alt=media&token=6d7e5861-1df6-4148-8c11-4767a6e130f0) + ## Node templates When creating a node, if you've configured a [template for that node type](/docs/obsidian/configuration/node-types-templates#working-with-templates), the template content will be automatically applied to the new node. - The new node will be saved in the designated folder that you created in the [General settings](/docs/obsidian/configuration/general-settings) ## Next Steps After creating nodes: + - [Create relationships between nodes](/docs/obsidian/core-features/creating-discourse-relationships) - [Learn how to explore your graph](/docs/obsidian/core-features/canvas) - diff --git a/apps/website/content/obsidian/core-features/creating-discourse-relationships.md b/apps/website/content/obsidian/core-features/creating-discourse-relationships.md index f09de7dd5..7eae520bf 100644 --- a/apps/website/content/obsidian/core-features/creating-discourse-relationships.md +++ b/apps/website/content/obsidian/core-features/creating-discourse-relationships.md @@ -11,26 +11,26 @@ To create a relationship between discourse nodes: 1. Open a note that you want to create a relationship from 2. Open the discourse context by clicking the telescope icon on the left bar -![open discourse context](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FE10krHZcDM.png?alt=media&token=c1796a9f-7e51-437f-913d-91f5433d9bab) + ![open discourse context](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FE10krHZcDM.png?alt=media&token=c1796a9f-7e51-437f-913d-91f5433d9bab) Alternatively, you can: - Set a hotkey to toggle the discourse context view - Access it via the Command Palette - ![command palette](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2F5ybScaQISO.png?alt=media&token=2b36f0e7-4247-47b7-a53d-c784dfd4609b) + ![command palette](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2F5ybScaQISO.png?alt=media&token=2b36f0e7-4247-47b7-a53d-c784dfd4609b) 3. Click "Add a new relation" 4. Choose a relationship type from the dropdown. The dropdown shows all available relations that you have defined in the settings, and indicates what node types you can link with. -![add relation](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FXQsgznWuV2.png?alt=media&token=9442b9fa-0904-4847-8eb8-a5791705c4c5) + ![add relation](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FXQsgznWuV2.png?alt=media&token=9442b9fa-0904-4847-8eb8-a5791705c4c5) 5. Search for the target node by its title -![search](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2F4NW4UjYDrC.png?alt=media&token=bae307d0-ebec-4e6b-a03d-0943d9d03754) + ![search](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2F4NW4UjYDrC.png?alt=media&token=bae307d0-ebec-4e6b-a03d-0943d9d03754) 6. Click "Confirm" to create the relationship -![relationship created](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FK8XAhCqrUL.png?alt=media&token=a559c477-c7f6-4b3e-8b00-ece7da5d4fec) + ![relationship created](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FK8XAhCqrUL.png?alt=media&token=a559c477-c7f6-4b3e-8b00-ece7da5d4fec) ## Next steps After creating relationships: -- [Learn how to explore your graph](/docs/obsidian/core-features/canvas) +- [Learn how to explore your graph](/docs/obsidian/core-features/canvas) diff --git a/apps/website/content/obsidian/core-features/discourse-context.md b/apps/website/content/obsidian/core-features/discourse-context.md index b7649e9f5..6251122c2 100644 --- a/apps/website/content/obsidian/core-features/discourse-context.md +++ b/apps/website/content/obsidian/core-features/discourse-context.md @@ -41,4 +41,3 @@ You can use this view to: - Understand how nodes connect to each other - Add new relationships - Get a quick overview of your graph structure - diff --git a/apps/website/content/obsidian/core-features/node-tags.md b/apps/website/content/obsidian/core-features/node-tags.md index 7eab9a20b..090c6f450 100644 --- a/apps/website/content/obsidian/core-features/node-tags.md +++ b/apps/website/content/obsidian/core-features/node-tags.md @@ -25,6 +25,7 @@ This feature streamlines your workflow by letting you mark potential discourse n ### Tag naming rules Tags must follow these rules: + - **No spaces**: Tags cannot contain whitespace - **Allowed characters**: Only letters (a-z, A-Z), numbers (0-9), and dashes (-) - **No special characters**: Characters like #, @, /, \, etc. are not allowed @@ -33,12 +34,14 @@ Tags must follow these rules: #### Tag examples **Valid tags:** + - `clm-candidate` - `question-idea` - `evidence2024` - `my-argument` **Invalid tags:** + - `clm candidate` (contains space) - `#clm-candidate` (contains #) - `clm/candidate` (contains /) @@ -57,11 +60,10 @@ When you hover over a tagged line, a button appears above the tag: 1. **Hover** over the tag you want to convert 2. Wait for the **"Create [Node Type]"** button to appear -![On hover](/docs/obsidian/on-hover-node-tag.png) + ![On hover](/docs/obsidian/on-hover-node-tag.png) 3. **Click** the button to open the node creation dialog -![Node creation dialog](/docs/obsidian/create-node-dialog-node-tag.png) + ![Node creation dialog](/docs/obsidian/create-node-dialog-node-tag.png) 4. Click "Confirm" to create node You'll see that the candidate node is now replaced with a formalized node ![node created from tag](/docs/obsidian/node-tag-created.png) - diff --git a/apps/website/content/obsidian/fundamentals/base-grammar.md b/apps/website/content/obsidian/fundamentals/base-grammar.md index fb298cc0d..126b6d0d7 100644 --- a/apps/website/content/obsidian/fundamentals/base-grammar.md +++ b/apps/website/content/obsidian/fundamentals/base-grammar.md @@ -25,4 +25,3 @@ This is what ships with the extension. 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/content/obsidian/fundamentals/what-is-a-discourse-graph.md b/apps/website/content/obsidian/fundamentals/what-is-a-discourse-graph.md index b998a19f6..e3a1a998e 100644 --- a/apps/website/content/obsidian/fundamentals/what-is-a-discourse-graph.md +++ b/apps/website/content/obsidian/fundamentals/what-is-a-discourse-graph.md @@ -18,4 +18,3 @@ Consider how that information model foregrounds the conceptual building blocks a 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/content/obsidian/index.mdx b/apps/website/content/obsidian/index.mdx index b9d4256b9..683912bba 100644 --- a/apps/website/content/obsidian/index.mdx +++ b/apps/website/content/obsidian/index.mdx @@ -15,9 +15,24 @@ Use these docs to install the Discourse Graph plugin for Obsidian, configure nod - - - - + + + + - diff --git a/apps/website/content/obsidian/use-cases/lab-notebooks.md b/apps/website/content/obsidian/use-cases/lab-notebooks.md index d29aca7c2..9bdfa548c 100644 --- a/apps/website/content/obsidian/use-cases/lab-notebooks.md +++ b/apps/website/content/obsidian/use-cases/lab-notebooks.md @@ -6,4 +6,3 @@ published: true --- Description coming soon! - diff --git a/apps/website/content/obsidian/use-cases/literature-reviewing.md b/apps/website/content/obsidian/use-cases/literature-reviewing.md index 4202485e2..3aded41b9 100644 --- a/apps/website/content/obsidian/use-cases/literature-reviewing.md +++ b/apps/website/content/obsidian/use-cases/literature-reviewing.md @@ -12,4 +12,3 @@ Lukas Kawerau (aka Cortex Futura) has a course that integrates the extension int 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 index 8739b9a7c..51c94d6e5 100644 --- a/apps/website/content/obsidian/use-cases/reading-clubs.md +++ b/apps/website/content/obsidian/use-cases/reading-clubs.md @@ -8,4 +8,3 @@ 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 index f2edf06b1..01d12fc3d 100644 --- a/apps/website/content/obsidian/use-cases/research-roadmapping.md +++ b/apps/website/content/obsidian/use-cases/research-roadmapping.md @@ -6,4 +6,3 @@ published: true --- Description coming soon! - diff --git a/apps/website/content/obsidian/welcome/getting-started.md b/apps/website/content/obsidian/welcome/getting-started.md index ed6419d9c..92dcb437a 100644 --- a/apps/website/content/obsidian/welcome/getting-started.md +++ b/apps/website/content/obsidian/welcome/getting-started.md @@ -40,4 +40,3 @@ Learn the fundamentals of the Discourse Graph plugin to get a deeper understandi - [What is a Discourse Graph?](/docs/obsidian/fundamentals/what-is-a-discourse-graph) - [Relationship types](/docs/obsidian/configuration/relationship-types) - [The Base Grammar: questions, claims, and evidence](/docs/obsidian/fundamentals/base-grammar) - diff --git a/apps/website/content/obsidian/welcome/installation.md b/apps/website/content/obsidian/welcome/installation.md index a2936985e..4a591c6da 100644 --- a/apps/website/content/obsidian/welcome/installation.md +++ b/apps/website/content/obsidian/welcome/installation.md @@ -12,7 +12,7 @@ published: true 1. Open Obsidian Settings 2. Go to Community Plugins and disable Restricted Mode 3. Click "Browse" and search for "BRAT" -![BRAT](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2Faar5LKpLOk.png?alt=media&token=6f51ac48-19d3-4bb5-9a07-7b32cfa6afe6) + ![BRAT](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2Faar5LKpLOk.png?alt=media&token=6f51ac48-19d3-4bb5-9a07-7b32cfa6afe6) 4. Install BRAT and enable it ### Install DataCore via BRAT @@ -20,9 +20,9 @@ published: true 1. Open Obsidian Settings 2. Go to "Community Plugins" → "BRAT" 3. Click "Add Beta Plugin" -![Add plugin](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FdMtstUHPXe.png?alt=media&token=3f139ab9-9802-404d-9554-4a63bac080c5) + ![Add plugin](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FdMtstUHPXe.png?alt=media&token=3f139ab9-9802-404d-9554-4a63bac080c5) 4. Enter the repository URL: `https://github.com/blacksmithgu/datacore` and choose "Latest version" -![Add datacore](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FEY3vNGt1Rf.png?alt=media&token=32c60ff1-5272-4cde-8b5f-8f049fb2cf50) + ![Add datacore](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FEY3vNGt1Rf.png?alt=media&token=32c60ff1-5272-4cde-8b5f-8f049fb2cf50) 5. Check the box for "Enable after installing the plugin" 6. Click "Add plugin" @@ -31,15 +31,16 @@ published: true 1. Open Obsidian Settings 2. Go to "Community Plugins" → "BRAT" 3. Click "Add Beta Plugin" -![Add plugin](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FdMtstUHPXe.png?alt=media&token=3f139ab9-9802-404d-9554-4a63bac080c5) + ![Add plugin](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FdMtstUHPXe.png?alt=media&token=3f139ab9-9802-404d-9554-4a63bac080c5) 4. Enter the repository URL: `https://github.com/DiscourseGraphs/discourse-graph-obsidian` and choose "Latest version" -![Add discourse graph](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FSBCK-2lkcu.png?alt=media&token=0375c828-da4d-43b4-8f2c-e691692cb019) + ![Add discourse graph](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FSBCK-2lkcu.png?alt=media&token=0375c828-da4d-43b4-8f2c-e691692cb019) 5. Check the box for "Enable after installing the plugin" 6. Click "Add Plugin" ## Next Steps After installation, you'll want to: + 1. [Configure your node types](/docs/obsidian/configuration/node-types-templates) 2. [Set up relationship types](/docs/obsidian/configuration/relationship-types) -3. [Create your first node](/docs/obsidian/core-features/creating-discourse-nodes) +3. [Create your first node](/docs/obsidian/core-features/creating-discourse-nodes) diff --git a/apps/website/content/roam/fundamentals/base-grammar.md b/apps/website/content/roam/fundamentals/base-grammar.md index fb298cc0d..126b6d0d7 100644 --- a/apps/website/content/roam/fundamentals/base-grammar.md +++ b/apps/website/content/roam/fundamentals/base-grammar.md @@ -25,4 +25,3 @@ This is what ships with the extension. 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/content/roam/fundamentals/grammar.md b/apps/website/content/roam/fundamentals/grammar.md index af7735c71..29d5ee845 100644 --- a/apps/website/content/roam/fundamentals/grammar.md +++ b/apps/website/content/roam/fundamentals/grammar.md @@ -13,4 +13,3 @@ published: true ## Relation grammar building blocks - [Nodes](/docs/roam/fundamentals/nodes) - diff --git a/apps/website/content/roam/fundamentals/migration-to-stored-relations.md b/apps/website/content/roam/fundamentals/migration-to-stored-relations.md index efb6038e1..9e5a9dcbd 100644 --- a/apps/website/content/roam/fundamentals/migration-to-stored-relations.md +++ b/apps/website/content/roam/fundamentals/migration-to-stored-relations.md @@ -88,4 +88,3 @@ Stored relations are implemented as: - `roam/js/discourse-graph/relations` Each relation is a **block**, with relation data stored in the block's **hidden properties**. - diff --git a/apps/website/content/roam/fundamentals/nodes.md b/apps/website/content/roam/fundamentals/nodes.md index 4f50cd3cf..62c72502f 100644 --- a/apps/website/content/roam/fundamentals/nodes.md +++ b/apps/website/content/roam/fundamentals/nodes.md @@ -20,4 +20,3 @@ When in doubt, check the preview of your relation pattern to ensure you're corre ## Next - [Operators and relations](/docs/roam/fundamentals/operators-relations) - diff --git a/apps/website/content/roam/fundamentals/operators-relations.md b/apps/website/content/roam/fundamentals/operators-relations.md index 2600109bd..45cead933 100644 --- a/apps/website/content/roam/fundamentals/operators-relations.md +++ b/apps/website/content/roam/fundamentals/operators-relations.md @@ -68,4 +68,3 @@ published: true ## Next - [Stored relations](/docs/roam/fundamentals/stored-relations) - diff --git a/apps/website/content/roam/fundamentals/relations-patterns.md b/apps/website/content/roam/fundamentals/relations-patterns.md index e8a63e6db..433b16f32 100644 --- a/apps/website/content/roam/fundamentals/relations-patterns.md +++ b/apps/website/content/roam/fundamentals/relations-patterns.md @@ -51,4 +51,3 @@ Like this: ![](/docs/roam/relation-opposes.png) The system recognizes that this piece of evidence **opposes** that claim. - diff --git a/apps/website/content/roam/fundamentals/stored-relations.md b/apps/website/content/roam/fundamentals/stored-relations.md index 8d0c733aa..869e10414 100644 --- a/apps/website/content/roam/fundamentals/stored-relations.md +++ b/apps/website/content/roam/fundamentals/stored-relations.md @@ -76,4 +76,3 @@ Stored relations are implemented as: - Source and destination nodes referenced by UID This structure allows fast lookup, consistent rendering, and future extensions such as metadata, provenance, and annotations. - diff --git a/apps/website/content/roam/fundamentals/what-is-a-discourse-graph.md b/apps/website/content/roam/fundamentals/what-is-a-discourse-graph.md index b998a19f6..e3a1a998e 100644 --- a/apps/website/content/roam/fundamentals/what-is-a-discourse-graph.md +++ b/apps/website/content/roam/fundamentals/what-is-a-discourse-graph.md @@ -18,4 +18,3 @@ Consider how that information model foregrounds the conceptual building blocks a 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/content/roam/guides/creating-discourse-nodes.md b/apps/website/content/roam/guides/creating-discourse-nodes.md index d58d00b5a..d4f002001 100644 --- a/apps/website/content/roam/guides/creating-discourse-nodes.md +++ b/apps/website/content/roam/guides/creating-discourse-nodes.md @@ -22,4 +22,3 @@ https://www.loom.com/share/471fcf7dc13246439cb35feedb110470 You can customize the template for specific nodes in the Settings Panel. ![](/docs/roam/node-template.png) - diff --git a/apps/website/content/roam/guides/creating-discourse-relationships.md b/apps/website/content/roam/guides/creating-discourse-relationships.md index b86836985..b7eabb6bd 100644 --- a/apps/website/content/roam/guides/creating-discourse-relationships.md +++ b/apps/website/content/roam/guides/creating-discourse-relationships.md @@ -24,4 +24,3 @@ The relation is stored immediately and becomes available throughout your graph. - Learn how stored relations work in [**Stored relations**](/docs/roam/fundamentals/stored-relations) - Explore relationships from the [**Discourse context overlay**](/docs/roam/views-and-tools/discourse-context-overlay) - If you're still using the legacy workflow, see [**Relations and patterns**](/docs/roam/fundamentals/relations-patterns) - diff --git a/apps/website/content/roam/guides/exploring-discourse-graph.md b/apps/website/content/roam/guides/exploring-discourse-graph.md index a92073b0f..42748ae71 100644 --- a/apps/website/content/roam/guides/exploring-discourse-graph.md +++ b/apps/website/content/roam/guides/exploring-discourse-graph.md @@ -11,4 +11,3 @@ The extension adds features to enable you to seamlessly explore your discourse g - [Discourse context overlay](/docs/roam/views-and-tools/discourse-context-overlay) - [Discourse attributes](/docs/roam/views-and-tools/discourse-attributes) - [Node index](/docs/roam/views-and-tools/node-index) - diff --git a/apps/website/content/roam/guides/extending-personalizing-graph.md b/apps/website/content/roam/guides/extending-personalizing-graph.md index ada7c7c83..458bb3fb1 100644 --- a/apps/website/content/roam/guides/extending-personalizing-graph.md +++ b/apps/website/content/roam/guides/extending-personalizing-graph.md @@ -31,4 +31,3 @@ For example, here is a demo of creating a "consistent with" relation pattern tha [https://www.loom.com/share/cb9e526a98764e95a459a6db2b66e46a](https://www.loom.com/share/cb9e526a98764e95a459a6db2b66e46a) If you want to explore or understand that legacy workflow, it will be useful to [learn more about the extension grammar](/docs/roam/fundamentals/grammar). - diff --git a/apps/website/content/roam/guides/querying-discourse-graph.md b/apps/website/content/roam/guides/querying-discourse-graph.md index 0fc850200..71486b9c4 100644 --- a/apps/website/content/roam/guides/querying-discourse-graph.md +++ b/apps/website/content/roam/guides/querying-discourse-graph.md @@ -64,4 +64,3 @@ You can save a query to its own page if you want to keep it around for easier ac ![](/docs/roam/query-drawer-save-to-page.png) It will be saved to the namespace `discourse-graph/queries/` by default. - diff --git a/apps/website/content/roam/guides/sharing-discourse-graph.md b/apps/website/content/roam/guides/sharing-discourse-graph.md index 57740ef23..be5d44b17 100644 --- a/apps/website/content/roam/guides/sharing-discourse-graph.md +++ b/apps/website/content/roam/guides/sharing-discourse-graph.md @@ -58,4 +58,3 @@ Here is a brief explanation of each option: ## Example 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/content/roam/guides/tagging-candidate-nodes.md b/apps/website/content/roam/guides/tagging-candidate-nodes.md index 55865c13b..5259c67fc 100644 --- a/apps/website/content/roam/guides/tagging-candidate-nodes.md +++ b/apps/website/content/roam/guides/tagging-candidate-nodes.md @@ -39,4 +39,3 @@ Hover your mouse over the node tag, and click "Create Evidence" ## Candidate node styling Candidate node styling is currently controlled in roam/css. You can borrow our node styling here: [template-lab CSS page](https://roamresearch.com/#/app/template-lab/page/X8V4gy32s) - diff --git a/apps/website/content/roam/index.mdx b/apps/website/content/roam/index.mdx index 3c0f1dfa8..3aa0309ee 100644 --- a/apps/website/content/roam/index.mdx +++ b/apps/website/content/roam/index.mdx @@ -15,9 +15,24 @@ Use these docs to install the Discourse Graph extension for Roam, learn the core - - - - + + + + - diff --git a/apps/website/content/roam/use-cases/enhanced-zettelkasten.md b/apps/website/content/roam/use-cases/enhanced-zettelkasten.md index aa37ec08b..36ba3e2c9 100644 --- a/apps/website/content/roam/use-cases/enhanced-zettelkasten.md +++ b/apps/website/content/roam/use-cases/enhanced-zettelkasten.md @@ -10,4 +10,3 @@ Maarten Van Doorn has integrated the discourse graph into his take on applying t 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/lab-notebooks.md b/apps/website/content/roam/use-cases/lab-notebooks.md index d29aca7c2..9bdfa548c 100644 --- a/apps/website/content/roam/use-cases/lab-notebooks.md +++ b/apps/website/content/roam/use-cases/lab-notebooks.md @@ -6,4 +6,3 @@ published: true --- Description coming soon! - diff --git a/apps/website/content/roam/use-cases/literature-reviewing.md b/apps/website/content/roam/use-cases/literature-reviewing.md index 4202485e2..3aded41b9 100644 --- a/apps/website/content/roam/use-cases/literature-reviewing.md +++ b/apps/website/content/roam/use-cases/literature-reviewing.md @@ -12,4 +12,3 @@ Lukas Kawerau (aka Cortex Futura) has a course that integrates the extension int 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 index 8739b9a7c..51c94d6e5 100644 --- a/apps/website/content/roam/use-cases/reading-clubs.md +++ b/apps/website/content/roam/use-cases/reading-clubs.md @@ -8,4 +8,3 @@ 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 index f2edf06b1..01d12fc3d 100644 --- a/apps/website/content/roam/use-cases/research-roadmapping.md +++ b/apps/website/content/roam/use-cases/research-roadmapping.md @@ -6,4 +6,3 @@ published: true --- Description coming soon! - diff --git a/apps/website/content/roam/views-and-tools/discourse-attributes.md b/apps/website/content/roam/views-and-tools/discourse-attributes.md index 1a28b8070..6bada99d8 100644 --- a/apps/website/content/roam/views-and-tools/discourse-attributes.md +++ b/apps/website/content/roam/views-and-tools/discourse-attributes.md @@ -63,4 +63,3 @@ The syntax for these compound discourse functions is: `{operation:relationName:targetType:targetDiscourseAttribute}` This generalizes the syntax for the basic discourse functions by adding a discourse attribute to access from the targets, and the option of using additional operations than `count` (for now, we only support `sum` and `average`) for the function. - diff --git a/apps/website/content/roam/views-and-tools/discourse-context-overlay.md b/apps/website/content/roam/views-and-tools/discourse-context-overlay.md index 41c1a2de4..86d6a6d95 100644 --- a/apps/website/content/roam/views-and-tools/discourse-context-overlay.md +++ b/apps/website/content/roam/views-and-tools/discourse-context-overlay.md @@ -40,4 +40,3 @@ You can think of this default discourse score as a rough sense of how "robust" a (old video demo) https://www.loom.com/share/b3d6094cd14a466081b8aa8495eb6542 - diff --git a/apps/website/content/roam/views-and-tools/discourse-context.md b/apps/website/content/roam/views-and-tools/discourse-context.md index f54d87fae..247e58405 100644 --- a/apps/website/content/roam/views-and-tools/discourse-context.md +++ b/apps/website/content/roam/views-and-tools/discourse-context.md @@ -23,4 +23,3 @@ The discourse context component adds a "higher-signal" linked references section ## Demo https://www.loom.com/share/0c66e95d0c71426e8090a8bc1cbf8544 - diff --git a/apps/website/content/roam/views-and-tools/node-index.md b/apps/website/content/roam/views-and-tools/node-index.md index 49d6a2ea7..adb101cdc 100644 --- a/apps/website/content/roam/views-and-tools/node-index.md +++ b/apps/website/content/roam/views-and-tools/node-index.md @@ -15,4 +15,3 @@ The extension has node settings tabs for each node you define, which provides a ![](/docs/roam/settings-node-index.png) This can be quite handy in multiplayer settings, for example, to quickly view the latest question nodes that have been added to the graph, or who authored them, by modifying the default index query, just like a [regular query](/docs/roam/guides/querying-discourse-graph). - diff --git a/apps/website/content/roam/welcome/getting-started.md b/apps/website/content/roam/welcome/getting-started.md index 0e8672c35..a0f022009 100644 --- a/apps/website/content/roam/welcome/getting-started.md +++ b/apps/website/content/roam/welcome/getting-started.md @@ -30,4 +30,3 @@ Learn the fundamentals of the Discourse Graph extension to get a deeper understa - [What is a Discourse Graph?](/docs/roam/fundamentals/what-is-a-discourse-graph) - [The Discourse Graph extension grammar](/docs/roam/fundamentals/grammar) - [The base grammar: questions, claims, and evidence](/docs/roam/fundamentals/base-grammar) - diff --git a/apps/website/content/roam/welcome/installation-roam-depot.md b/apps/website/content/roam/welcome/installation-roam-depot.md index 2d8d03902..237aa6cb6 100644 --- a/apps/website/content/roam/welcome/installation-roam-depot.md +++ b/apps/website/content/roam/welcome/installation-roam-depot.md @@ -12,4 +12,3 @@ The Discourse Graphs extension can be installed via Roam Depot: ![](/docs/roam/roam-depot-settings.png) Then type in "Discourse Graphs" in the search bar and click install. - diff --git a/apps/website/content/roam/welcome/installation.md b/apps/website/content/roam/welcome/installation.md index 13bd7c302..44e738d09 100644 --- a/apps/website/content/roam/welcome/installation.md +++ b/apps/website/content/roam/welcome/installation.md @@ -12,4 +12,3 @@ Search for Discourse Graph in Roam Depot ![](/docs/roam/browse-roam-depot.png) ![](/docs/roam/find-in-roam-depot.png) ![](/docs/roam/install-instruction-roam-depot.png) - diff --git a/apps/website/scripts/build-docs-search-index.mjs b/apps/website/scripts/build-docs-search-index.mjs index d4e0766e7..d956ef7db 100644 --- a/apps/website/scripts/build-docs-search-index.mjs +++ b/apps/website/scripts/build-docs-search-index.mjs @@ -38,7 +38,10 @@ const collapseWhitespace = (value) => value.replace(/\s+/g, " ").trim(); export const markdownToSearchText = (source) => { const withoutImports = source.replace(/^\s*(import|export)\s.+$/gm, " "); const withoutFences = withoutImports.replace(/```[\s\S]*?```/g, " "); - const withoutImages = withoutFences.replace(/!\[([^\]]*)\]\([^)]+\)/g, " $1 "); + const withoutImages = withoutFences.replace( + /!\[([^\]]*)\]\([^)]+\)/g, + " $1 ", + ); const withoutLinks = withoutImages.replace(/\[([^\]]+)\]\([^)]+\)/g, " $1 "); const withoutHtml = withoutLinks.replace(/<[^>]+>/g, " "); const withoutInlineCode = withoutHtml.replace(/`([^`]+)`/g, " $1 "); diff --git a/apps/website/scripts/build-docs-search-index.test.mjs b/apps/website/scripts/build-docs-search-index.test.mjs index 7313837b3..a4d17e645 100644 --- a/apps/website/scripts/build-docs-search-index.test.mjs +++ b/apps/website/scripts/build-docs-search-index.test.mjs @@ -10,7 +10,13 @@ import { void test("routePathFromContentFile maps content files to canonical docs routes", () => { assert.equal( routePathFromContentFile( - path.join(process.cwd(), "content", "roam", "welcome", "getting-started.md"), + path.join( + process.cwd(), + "content", + "roam", + "welcome", + "getting-started.md", + ), ), "/docs/roam/welcome/getting-started", ); @@ -42,14 +48,20 @@ Choose the \`/docs\` routes. assert.equal( markdownToSearchText(source), - 'Documentation Choose the /docs routes. Shared conceptual docs stay stable. Roam docs', + "Documentation Choose the /docs routes. Shared conceptual docs stay stable. Roam docs", ); }); void test("searchFiltersFromContentFile scopes docs records by platform", () => { assert.deepEqual( searchFiltersFromContentFile( - path.join(process.cwd(), "content", "roam", "welcome", "getting-started.md"), + path.join( + process.cwd(), + "content", + "roam", + "welcome", + "getting-started.md", + ), ), { platform: ["roam"] }, ); @@ -60,7 +72,9 @@ void test("searchFiltersFromContentFile scopes docs records by platform", () => { platform: ["obsidian"] }, ); assert.equal( - searchFiltersFromContentFile(path.join(process.cwd(), "content", "index.mdx")), + searchFiltersFromContentFile( + path.join(process.cwd(), "content", "index.mdx"), + ), undefined, ); }); diff --git a/package.json b/package.json index 318b0f778..10c565ff3 100644 --- a/package.json +++ b/package.json @@ -7,7 +7,7 @@ "dev": "turbo dev", "lint": "turbo lint", "deploy": "turbo deploy", - "format": "prettier --write \"**/*.{ts,tsx,md}\"", + "format": "prettier --write \"**/*.{js,mjs,ts,tsx,md,mdx}\"", "prepare": "husky" }, "devDependencies": { @@ -34,7 +34,7 @@ "tailwindConfig": "./packages/tailwind-config/tailwind.config.ts" }, "lint-staged": { - "*.{ts|tsx|md}": "prettier -w" + "*.{ts,mjs,ts,tsx,md,mdx}": "prettier -w" }, "dependencies": { "posthog-js": "catalog:" From a3ddfccc412033f565ea35ced936194ce39250b1 Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Tue, 31 Mar 2026 22:09:26 -0600 Subject: [PATCH 09/14] Update documentation by removing redundant overview sections and enhancing clarity in node and relation descriptions - Removed the "Overview" section from multiple documentation files to streamline content. - Improved formatting and clarity in the node and relation documentation across various files. - Ensured consistency in the presentation of tag rules and examples in the node-tags documentation. --- apps/website/app/(docs)/docs/obsidian/pages/node-tags.md | 9 +++++---- .../docs/roam/pages/migration-to-stored-relations.md | 2 -- apps/website/app/(docs)/docs/roam/pages/nodes.md | 4 ---- .../app/(docs)/docs/roam/pages/operators-relations.md | 4 ---- .../app/(docs)/docs/roam/pages/stored-relations.md | 2 -- apps/website/content/obsidian/core-features/node-tags.md | 2 -- apps/website/content/roam/fundamentals/base-grammar.md | 6 ++---- .../roam/fundamentals/migration-to-stored-relations.md | 2 -- apps/website/content/roam/fundamentals/nodes.md | 4 ---- .../content/roam/fundamentals/operators-relations.md | 4 ---- .../content/roam/fundamentals/stored-relations.md | 2 -- 11 files changed, 7 insertions(+), 34 deletions(-) diff --git a/apps/website/app/(docs)/docs/obsidian/pages/node-tags.md b/apps/website/app/(docs)/docs/obsidian/pages/node-tags.md index a72fa3c6e..1155a8490 100644 --- a/apps/website/app/(docs)/docs/obsidian/pages/node-tags.md +++ b/apps/website/app/(docs)/docs/obsidian/pages/node-tags.md @@ -5,8 +5,6 @@ author: "" published: true --- -## Overview - Node tags allow you to quickly create discourse nodes from tagged lines in your notes. When you assign a tag to a node type, any line containing that tag becomes a clickable element that can be converted into a discourse node. This feature streamlines your workflow by letting you mark potential discourse nodes with tags as you write, then easily convert them to full discourse nodes later. @@ -25,6 +23,7 @@ This feature streamlines your workflow by letting you mark potential discourse n ### Tag naming rules Tags must follow these rules: + - **No spaces**: Tags cannot contain whitespace - **Allowed characters**: Only letters (a-z, A-Z), numbers (0-9), and dashes (-) - **No special characters**: Characters like #, @, /, \, etc. are not allowed @@ -33,12 +32,14 @@ Tags must follow these rules: #### Tag examples **Valid tags:** + - `clm-candidate` - `question-idea` - `evidence2024` - `my-argument` **Invalid tags:** + - `clm candidate` (contains space) - `#clm-candidate` (contains #) - `clm/candidate` (contains /) @@ -57,9 +58,9 @@ When you hover over a tagged line, a button appears above the tag: 1. **Hover** over the tag you want to convert 2. Wait for the **"Create [Node Type]"** button to appear -![On hover](/docs/obsidian/on-hover-node-tag.png) + ![On hover](/docs/obsidian/on-hover-node-tag.png) 3. **Click** the button to open the node creation dialog -![Node creation dialog](/docs/obsidian/create-node-dialog-node-tag.png) + ![Node creation dialog](/docs/obsidian/create-node-dialog-node-tag.png) 4. Click "Confirm" to create node You'll see that the candidate node is now replaced with a formalized node diff --git a/apps/website/app/(docs)/docs/roam/pages/migration-to-stored-relations.md b/apps/website/app/(docs)/docs/roam/pages/migration-to-stored-relations.md index e79d02059..b09d38256 100644 --- a/apps/website/app/(docs)/docs/roam/pages/migration-to-stored-relations.md +++ b/apps/website/app/(docs)/docs/roam/pages/migration-to-stored-relations.md @@ -5,8 +5,6 @@ author: "" published: true --- -## Overview - Stored relations make relations load faster and more reliably. Discourse Graph installs as of v0.18.0 use them by default. Older installs need a one-time migration that copies existing pattern-based relations into the new format. This guide covers the migration flow from **Personal Settings** for older installs. If you're new to stored relations, start with the [stored relations overview](./stored-relations). diff --git a/apps/website/app/(docs)/docs/roam/pages/nodes.md b/apps/website/app/(docs)/docs/roam/pages/nodes.md index 145e199c8..8483e572e 100644 --- a/apps/website/app/(docs)/docs/roam/pages/nodes.md +++ b/apps/website/app/(docs)/docs/roam/pages/nodes.md @@ -16,7 +16,3 @@ It is not possible to directly specify that a source or target node in a relatio For example, if a node's incoming relation is `references`, that implies it is a page. Similarly, if the node's incoming relation is `has child` or `has ancestor`, that implies the node is a block. When in doubt, check the preview of your relation pattern to ensure you're correctly expressing your intentions! - -## Next - -- [Operators and relations](./operators-relations) diff --git a/apps/website/app/(docs)/docs/roam/pages/operators-relations.md b/apps/website/app/(docs)/docs/roam/pages/operators-relations.md index 766974d36..c738ef5e6 100644 --- a/apps/website/app/(docs)/docs/roam/pages/operators-relations.md +++ b/apps/website/app/(docs)/docs/roam/pages/operators-relations.md @@ -64,7 +64,3 @@ published: true - **description**: exact match to user-defined `discourse nodes` only (ALTHOUGH the autocomplete will allow you to specify other stuff that don't make sense) - **source**: a `page` (since all discourse nodes must be pages) - **target**: a `discourse node` (defined in your grammar) - -## Next - -- [Stored relations](./stored-relations) diff --git a/apps/website/app/(docs)/docs/roam/pages/stored-relations.md b/apps/website/app/(docs)/docs/roam/pages/stored-relations.md index 6b6abfd86..4c623eb08 100644 --- a/apps/website/app/(docs)/docs/roam/pages/stored-relations.md +++ b/apps/website/app/(docs)/docs/roam/pages/stored-relations.md @@ -5,8 +5,6 @@ author: "" published: true --- -## Overview - Stored relations are explicit relationships between discourse nodes. They are created directly in the graph and saved as data, so they can be used consistently across overlays, queries, and canvases. ## What is a stored relation? diff --git a/apps/website/content/obsidian/core-features/node-tags.md b/apps/website/content/obsidian/core-features/node-tags.md index 090c6f450..1155a8490 100644 --- a/apps/website/content/obsidian/core-features/node-tags.md +++ b/apps/website/content/obsidian/core-features/node-tags.md @@ -5,8 +5,6 @@ author: "" published: true --- -## Overview - Node tags allow you to quickly create discourse nodes from tagged lines in your notes. When you assign a tag to a node type, any line containing that tag becomes a clickable element that can be converted into a discourse node. This feature streamlines your workflow by letting you mark potential discourse nodes with tags as you write, then easily convert them to full discourse nodes later. diff --git a/apps/website/content/roam/fundamentals/base-grammar.md b/apps/website/content/roam/fundamentals/base-grammar.md index 126b6d0d7..f6f5ea289 100644 --- a/apps/website/content/roam/fundamentals/base-grammar.md +++ b/apps/website/content/roam/fundamentals/base-grammar.md @@ -5,18 +5,16 @@ author: "" published: true --- -## Base grammar - This is what ships with the extension. -### Nodes +## Nodes - QUE - Question - CLM - Claim - EVD - Evidence - Source -### Relations +## Relations - EVD Informs QUE - EVD Supports CLM diff --git a/apps/website/content/roam/fundamentals/migration-to-stored-relations.md b/apps/website/content/roam/fundamentals/migration-to-stored-relations.md index 9e5a9dcbd..715d40a6f 100644 --- a/apps/website/content/roam/fundamentals/migration-to-stored-relations.md +++ b/apps/website/content/roam/fundamentals/migration-to-stored-relations.md @@ -5,8 +5,6 @@ author: "" published: true --- -## Overview - Stored relations make relations load faster and more reliably. Discourse Graph installs as of v0.18.0 use them by default. Older installs need a one-time migration that copies existing pattern-based relations into the new format. This guide covers the migration flow from **Personal Settings** for older installs. If you're new to stored relations, start with the [stored relations overview](/docs/roam/fundamentals/stored-relations). diff --git a/apps/website/content/roam/fundamentals/nodes.md b/apps/website/content/roam/fundamentals/nodes.md index 62c72502f..8483e572e 100644 --- a/apps/website/content/roam/fundamentals/nodes.md +++ b/apps/website/content/roam/fundamentals/nodes.md @@ -16,7 +16,3 @@ It is not possible to directly specify that a source or target node in a relatio For example, if a node's incoming relation is `references`, that implies it is a page. Similarly, if the node's incoming relation is `has child` or `has ancestor`, that implies the node is a block. When in doubt, check the preview of your relation pattern to ensure you're correctly expressing your intentions! - -## Next - -- [Operators and relations](/docs/roam/fundamentals/operators-relations) diff --git a/apps/website/content/roam/fundamentals/operators-relations.md b/apps/website/content/roam/fundamentals/operators-relations.md index 45cead933..c738ef5e6 100644 --- a/apps/website/content/roam/fundamentals/operators-relations.md +++ b/apps/website/content/roam/fundamentals/operators-relations.md @@ -64,7 +64,3 @@ published: true - **description**: exact match to user-defined `discourse nodes` only (ALTHOUGH the autocomplete will allow you to specify other stuff that don't make sense) - **source**: a `page` (since all discourse nodes must be pages) - **target**: a `discourse node` (defined in your grammar) - -## Next - -- [Stored relations](/docs/roam/fundamentals/stored-relations) diff --git a/apps/website/content/roam/fundamentals/stored-relations.md b/apps/website/content/roam/fundamentals/stored-relations.md index 869e10414..29ca70dd6 100644 --- a/apps/website/content/roam/fundamentals/stored-relations.md +++ b/apps/website/content/roam/fundamentals/stored-relations.md @@ -5,8 +5,6 @@ author: "" published: true --- -## Overview - Stored relations are explicit relationships between discourse nodes. They are created directly in the graph and saved as data, so they can be used consistently across overlays, queries, and canvases. ## What is a stored relation? From db72006bc2cca7a680db4c795c173ee346aeee91 Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Tue, 31 Mar 2026 22:25:32 -0600 Subject: [PATCH 10/14] exploring your discourse graph --- apps/website/content/roam/_meta.ts | 1 - .../content/roam/fundamentals/stored-relations.md | 4 ++-- apps/website/content/roam/guides/_meta.ts | 2 +- .../guides/creating-discourse-relationships.md | 4 ++-- .../roam/guides/exploring-discourse-graph.md | 13 ------------- .../exploring-discourse-graph}/_meta.ts | 4 ++++ .../discourse-attributes.md | 10 +++++----- .../discourse-context-overlay.md | 14 +++++++------- .../discourse-context.md | 8 ++++---- .../roam/guides/exploring-discourse-graph/index.md | 13 +++++++++++++ .../exploring-discourse-graph}/node-index.md | 8 ++++---- .../roam/guides/extending-personalizing-graph.md | 3 ++- .../roam/guides/querying-discourse-graph.md | 2 +- 13 files changed, 45 insertions(+), 41 deletions(-) delete mode 100644 apps/website/content/roam/guides/exploring-discourse-graph.md rename apps/website/content/roam/{views-and-tools => guides/exploring-discourse-graph}/_meta.ts (81%) rename apps/website/content/roam/{views-and-tools => guides/exploring-discourse-graph}/discourse-attributes.md (88%) rename apps/website/content/roam/{views-and-tools => guides/exploring-discourse-graph}/discourse-context-overlay.md (72%) rename apps/website/content/roam/{views-and-tools => guides/exploring-discourse-graph}/discourse-context.md (60%) create mode 100644 apps/website/content/roam/guides/exploring-discourse-graph/index.md rename apps/website/content/roam/{views-and-tools => guides/exploring-discourse-graph}/node-index.md (63%) diff --git a/apps/website/content/roam/_meta.ts b/apps/website/content/roam/_meta.ts index 428463021..3ce033f3c 100644 --- a/apps/website/content/roam/_meta.ts +++ b/apps/website/content/roam/_meta.ts @@ -8,7 +8,6 @@ const meta: MetaRecord = { welcome: "Welcome", guides: "Guides", fundamentals: "Fundamentals", - "views-and-tools": "Views and tools", "use-cases": "Use cases", }; diff --git a/apps/website/content/roam/fundamentals/stored-relations.md b/apps/website/content/roam/fundamentals/stored-relations.md index 29ca70dd6..2fb28fc52 100644 --- a/apps/website/content/roam/fundamentals/stored-relations.md +++ b/apps/website/content/roam/fundamentals/stored-relations.md @@ -13,7 +13,7 @@ A stored relation connects two discourse nodes with a named relation type, such Stored relations are: -- Created directly in the [**Discourse context overlay**](/docs/roam/views-and-tools/discourse-context-overlay) +- Created directly in the [**Discourse context overlay**](/docs/roam/guides/exploring-discourse-graph/discourse-context-overlay) - Persisted in your graph as structured data - Available anywhere Discourse Graph reads relationships @@ -47,7 +47,7 @@ The relation is stored immediately. Stored relations appear throughout Discourse Graph: -- The [**Discourse context overlay**](/docs/roam/views-and-tools/discourse-context-overlay) shows relations for the current node +- The [**Discourse context overlay**](/docs/roam/guides/exploring-discourse-graph/discourse-context-overlay) shows relations for the current node - Queries can resolve relations from stored data - Canvases can use the same stored relationships diff --git a/apps/website/content/roam/guides/_meta.ts b/apps/website/content/roam/guides/_meta.ts index f5bf2d1e3..c98c9bf15 100644 --- a/apps/website/content/roam/guides/_meta.ts +++ b/apps/website/content/roam/guides/_meta.ts @@ -4,7 +4,7 @@ const meta: MetaRecord = { "creating-discourse-nodes": "Creating nodes", "tagging-candidate-nodes": "Tagging candidate nodes", "creating-discourse-relationships": "Creating relationships", - "exploring-discourse-graph": "Exploring", + "exploring-discourse-graph": "Exploring your discourse graph", "querying-discourse-graph": "Querying", "extending-personalizing-graph": "Extending", "sharing-discourse-graph": "Sharing", diff --git a/apps/website/content/roam/guides/creating-discourse-relationships.md b/apps/website/content/roam/guides/creating-discourse-relationships.md index b7eabb6bd..57f01090e 100644 --- a/apps/website/content/roam/guides/creating-discourse-relationships.md +++ b/apps/website/content/roam/guides/creating-discourse-relationships.md @@ -11,7 +11,7 @@ Creating relationships in Discourse Graph means creating **stored relations**. S ## Quick start -1. Open the [**Discourse context overlay**](/docs/roam/views-and-tools/discourse-context-overlay) for a node. +1. Open the [**Discourse context overlay**](/docs/roam/guides/exploring-discourse-graph/discourse-context-overlay) for a node. 2. Click **Add relation**. 3. Choose the relation type. 4. Choose the source and destination nodes. @@ -22,5 +22,5 @@ The relation is stored immediately and becomes available throughout your graph. ## Read next - Learn how stored relations work in [**Stored relations**](/docs/roam/fundamentals/stored-relations) -- Explore relationships from the [**Discourse context overlay**](/docs/roam/views-and-tools/discourse-context-overlay) +- Explore relationships from the [**Discourse context overlay**](/docs/roam/guides/exploring-discourse-graph/discourse-context-overlay) - If you're still using the legacy workflow, see [**Relations and patterns**](/docs/roam/fundamentals/relations-patterns) diff --git a/apps/website/content/roam/guides/exploring-discourse-graph.md b/apps/website/content/roam/guides/exploring-discourse-graph.md deleted file mode 100644 index 42748ae71..000000000 --- a/apps/website/content/roam/guides/exploring-discourse-graph.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "Exploring Your 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. - -- [Discourse context](/docs/roam/views-and-tools/discourse-context) -- [Discourse context overlay](/docs/roam/views-and-tools/discourse-context-overlay) -- [Discourse attributes](/docs/roam/views-and-tools/discourse-attributes) -- [Node index](/docs/roam/views-and-tools/node-index) diff --git a/apps/website/content/roam/views-and-tools/_meta.ts b/apps/website/content/roam/guides/exploring-discourse-graph/_meta.ts similarity index 81% rename from apps/website/content/roam/views-and-tools/_meta.ts rename to apps/website/content/roam/guides/exploring-discourse-graph/_meta.ts index 97ae9e3e3..e2f57a9f4 100644 --- a/apps/website/content/roam/views-and-tools/_meta.ts +++ b/apps/website/content/roam/guides/exploring-discourse-graph/_meta.ts @@ -1,6 +1,10 @@ import type { MetaRecord } from "nextra"; const meta: MetaRecord = { + index: { + title: "Overview", + display: "hidden", + }, "discourse-context": "Discourse context", "discourse-context-overlay": "Discourse context overlay", "discourse-attributes": "Discourse attributes", diff --git a/apps/website/content/roam/views-and-tools/discourse-attributes.md b/apps/website/content/roam/guides/exploring-discourse-graph/discourse-attributes.md similarity index 88% rename from apps/website/content/roam/views-and-tools/discourse-attributes.md rename to apps/website/content/roam/guides/exploring-discourse-graph/discourse-attributes.md index 6bada99d8..cdb6329eb 100644 --- a/apps/website/content/roam/views-and-tools/discourse-attributes.md +++ b/apps/website/content/roam/guides/exploring-discourse-graph/discourse-attributes.md @@ -5,10 +5,10 @@ author: "" published: true --- -- [Discourse context](/docs/roam/views-and-tools/discourse-context) -- [Discourse context overlay](/docs/roam/views-and-tools/discourse-context-overlay) -- [Discourse attributes](/docs/roam/views-and-tools/discourse-attributes) -- [Node index](/docs/roam/views-and-tools/node-index) +- [Discourse context](/docs/roam/guides/exploring-discourse-graph/discourse-context) +- [Discourse context overlay](/docs/roam/guides/exploring-discourse-graph/discourse-context-overlay) +- [Discourse attributes](/docs/roam/guides/exploring-discourse-graph/discourse-attributes) +- [Node index](/docs/roam/guides/exploring-discourse-graph/node-index) ## Define Discourse Attributes @@ -18,7 +18,7 @@ These attributes can be handy for sorting/querying nodes. For instance, if you c ![](/docs/roam/settings-discourse-attributes.png) -You can add discourse attributes as a column to display and sort/filter by when [Querying your discourse graph](./querying-discourse-graph.md) by adding a `discourse:{label}` selection. +You can add discourse attributes as a column to display and sort/filter by when [Querying your discourse graph](/docs/roam/guides/querying-discourse-graph) by adding a `discourse:{label}` selection. For example, in the index for Claims, you can return the Evidence attribute as a column (Select), and then sort in descending order by that attribute. diff --git a/apps/website/content/roam/views-and-tools/discourse-context-overlay.md b/apps/website/content/roam/guides/exploring-discourse-graph/discourse-context-overlay.md similarity index 72% rename from apps/website/content/roam/views-and-tools/discourse-context-overlay.md rename to apps/website/content/roam/guides/exploring-discourse-graph/discourse-context-overlay.md index 86d6a6d95..4e3bf44fb 100644 --- a/apps/website/content/roam/views-and-tools/discourse-context-overlay.md +++ b/apps/website/content/roam/guides/exploring-discourse-graph/discourse-context-overlay.md @@ -5,14 +5,14 @@ author: "" published: true --- -- [Discourse context](/docs/roam/views-and-tools/discourse-context) -- [Discourse context overlay](/docs/roam/views-and-tools/discourse-context-overlay) -- [Discourse attributes](/docs/roam/views-and-tools/discourse-attributes) -- [Node index](/docs/roam/views-and-tools/node-index) +- [Discourse context](/docs/roam/guides/exploring-discourse-graph/discourse-context) +- [Discourse context overlay](/docs/roam/guides/exploring-discourse-graph/discourse-context-overlay) +- [Discourse attributes](/docs/roam/guides/exploring-discourse-graph/discourse-attributes) +- [Node index](/docs/roam/guides/exploring-discourse-graph/node-index) The discourse context overlay adds an icon next to each discourse node wherever it is referenced. This icon provides access to two key features: -1. a popover to view the [Discourse context](/docs/roam/views-and-tools/discourse-context) of the node inline, and +1. a popover to view the [Discourse context](/docs/roam/guides/exploring-discourse-graph/discourse-context) of the node inline, and 2. a "Discourse score" component that displays a customizable score for the node that is some function of its relations to other nodes in the discourse graph. The overlay is an optional feature that is turned off by default. To turn it on, go to the grammar tab in the config page and check the box for overlay. @@ -21,7 +21,7 @@ The overlay is an optional feature that is turned off by default. To turn it on, ## Popover -The popover is simple to operate. Simply click on the icon to bring up the [discourse context](/docs/roam/views-and-tools/discourse-context) component in-line for quick reference. +The popover is simple to operate. Simply click on the icon to bring up the [discourse context](/docs/roam/guides/exploring-discourse-graph/discourse-context) component in-line for quick reference. ![](/docs/roam/discourse-context-overlay.gif) @@ -33,7 +33,7 @@ For example, the following score display denotes that the node participates in 5 ![](/docs/roam/discourse-context-overlay-score.png) -You can think of this default discourse score as a rough sense of how "robust" a given node is (discourse relations are more structured, high-signal relationships) relative to how "important" it is (raw references are often noisy). If you'd like, you can also experiment with different functions of discourse relations to a node by defining your own [Discourse attributes](/docs/roam/views-and-tools/discourse-attributes), and have them show up in the overlay! +You can think of this default discourse score as a rough sense of how "robust" a given node is (discourse relations are more structured, high-signal relationships) relative to how "important" it is (raw references are often noisy). If you'd like, you can also experiment with different functions of discourse relations to a node by defining your own [Discourse attributes](/docs/roam/guides/exploring-discourse-graph/discourse-attributes), and have them show up in the overlay! ## Demo diff --git a/apps/website/content/roam/views-and-tools/discourse-context.md b/apps/website/content/roam/guides/exploring-discourse-graph/discourse-context.md similarity index 60% rename from apps/website/content/roam/views-and-tools/discourse-context.md rename to apps/website/content/roam/guides/exploring-discourse-graph/discourse-context.md index 247e58405..e97ed9b04 100644 --- a/apps/website/content/roam/views-and-tools/discourse-context.md +++ b/apps/website/content/roam/guides/exploring-discourse-graph/discourse-context.md @@ -5,10 +5,10 @@ author: "" published: true --- -- [Discourse context](/docs/roam/views-and-tools/discourse-context) -- [Discourse context overlay](/docs/roam/views-and-tools/discourse-context-overlay) -- [Discourse attributes](/docs/roam/views-and-tools/discourse-attributes) -- [Node index](/docs/roam/views-and-tools/node-index) +- [Discourse context](/docs/roam/guides/exploring-discourse-graph/discourse-context) +- [Discourse context overlay](/docs/roam/guides/exploring-discourse-graph/discourse-context-overlay) +- [Discourse attributes](/docs/roam/guides/exploring-discourse-graph/discourse-attributes) +- [Node index](/docs/roam/guides/exploring-discourse-graph/node-index) The discourse context component adds a "higher-signal" linked references section to each discourse node, that allows you to explore _discourse_ relations (e.g., inform, support, etc.) between this node and other nodes in your discourse graph. diff --git a/apps/website/content/roam/guides/exploring-discourse-graph/index.md b/apps/website/content/roam/guides/exploring-discourse-graph/index.md new file mode 100644 index 000000000..e627aaa4b --- /dev/null +++ b/apps/website/content/roam/guides/exploring-discourse-graph/index.md @@ -0,0 +1,13 @@ +--- +title: "Exploring Your 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. + +- [Discourse context](/docs/roam/guides/exploring-discourse-graph/discourse-context) +- [Discourse context overlay](/docs/roam/guides/exploring-discourse-graph/discourse-context-overlay) +- [Discourse attributes](/docs/roam/guides/exploring-discourse-graph/discourse-attributes) +- [Node index](/docs/roam/guides/exploring-discourse-graph/node-index) diff --git a/apps/website/content/roam/views-and-tools/node-index.md b/apps/website/content/roam/guides/exploring-discourse-graph/node-index.md similarity index 63% rename from apps/website/content/roam/views-and-tools/node-index.md rename to apps/website/content/roam/guides/exploring-discourse-graph/node-index.md index adb101cdc..ede969fc1 100644 --- a/apps/website/content/roam/views-and-tools/node-index.md +++ b/apps/website/content/roam/guides/exploring-discourse-graph/node-index.md @@ -5,10 +5,10 @@ author: "" published: true --- -- [Discourse context](/docs/roam/views-and-tools/discourse-context) -- [Discourse context overlay](/docs/roam/views-and-tools/discourse-context-overlay) -- [Discourse attributes](/docs/roam/views-and-tools/discourse-attributes) -- [Node index](/docs/roam/views-and-tools/node-index) +- [Discourse context](/docs/roam/guides/exploring-discourse-graph/discourse-context) +- [Discourse context overlay](/docs/roam/guides/exploring-discourse-graph/discourse-context-overlay) +- [Discourse attributes](/docs/roam/guides/exploring-discourse-graph/discourse-attributes) +- [Node index](/docs/roam/guides/exploring-discourse-graph/node-index) The extension has node settings tabs for each node you define, which provides a query over all of your nodes of that type. For example, you can go to the Claim tab to see all the Claim nodes in your graph. diff --git a/apps/website/content/roam/guides/extending-personalizing-graph.md b/apps/website/content/roam/guides/extending-personalizing-graph.md index 458bb3fb1..088132281 100644 --- a/apps/website/content/roam/guides/extending-personalizing-graph.md +++ b/apps/website/content/roam/guides/extending-personalizing-graph.md @@ -9,7 +9,8 @@ This page covers ways to extend and personalize Discourse Graph beyond the defau ## Stored relations -Coming soon. +If you want to use the current relation workflow, start with the +[Stored relations](/docs/roam/fundamentals/stored-relations) guide. ## Pattern relation legacy diff --git a/apps/website/content/roam/guides/querying-discourse-graph.md b/apps/website/content/roam/guides/querying-discourse-graph.md index 71486b9c4..04baa1d5c 100644 --- a/apps/website/content/roam/guides/querying-discourse-graph.md +++ b/apps/website/content/roam/guides/querying-discourse-graph.md @@ -45,7 +45,7 @@ Example: find all evidence that informs a question, and select a methods attribu ### Select discourse attributes to display as attributes of results -If you have defined [Discourse Attributes](/docs/roam/views-and-tools/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`. +If you have defined [Discourse Attributes](/docs/roam/guides/exploring-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. From ca1428ce9542efe69866efa766d0b42dd2631bd6 Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Tue, 31 Mar 2026 22:41:26 -0600 Subject: [PATCH 11/14] Refactor and update documentation for relations and grammar - Renamed "Relations and patterns" to "Legacy relations patterns" for clarity. - Removed outdated sections and improved links to the new stored relations documentation. - Added new files for grammar components, including base grammar, nodes, and operators-relations. - Introduced a migration guide for transitioning to stored relations, enhancing user experience and clarity. --- .../(docs)/docs/roam/pages/relations-patterns.md | 2 +- apps/website/content/roam/fundamentals/_meta.ts | 5 ----- apps/website/content/roam/fundamentals/grammar.md | 15 --------------- .../content/roam/fundamentals/grammar/_meta.ts | 14 ++++++++++++++ .../fundamentals/{ => grammar}/base-grammar.md | 0 .../content/roam/fundamentals/grammar/index.md | 15 +++++++++++++++ .../roam/fundamentals/{ => grammar}/nodes.md | 0 .../{ => grammar}/operators-relations.md | 0 .../{ => grammar}/stored-relations.md | 0 .../roam/fundamentals/relations-patterns.md | 2 +- apps/website/content/roam/guides/_meta.ts | 1 + .../guides/creating-discourse-relationships.md | 4 ++-- .../roam/guides/extending-personalizing-graph.md | 2 +- .../migration-to-stored-relations.md | 2 +- .../content/roam/welcome/getting-started.md | 2 +- 15 files changed, 37 insertions(+), 27 deletions(-) delete mode 100644 apps/website/content/roam/fundamentals/grammar.md create mode 100644 apps/website/content/roam/fundamentals/grammar/_meta.ts rename apps/website/content/roam/fundamentals/{ => grammar}/base-grammar.md (100%) create mode 100644 apps/website/content/roam/fundamentals/grammar/index.md rename apps/website/content/roam/fundamentals/{ => grammar}/nodes.md (100%) rename apps/website/content/roam/fundamentals/{ => grammar}/operators-relations.md (100%) rename apps/website/content/roam/fundamentals/{ => grammar}/stored-relations.md (100%) rename apps/website/content/roam/{fundamentals => guides}/migration-to-stored-relations.md (96%) diff --git a/apps/website/app/(docs)/docs/roam/pages/relations-patterns.md b/apps/website/app/(docs)/docs/roam/pages/relations-patterns.md index 628c0fb59..f7b50398c 100644 --- a/apps/website/app/(docs)/docs/roam/pages/relations-patterns.md +++ b/apps/website/app/(docs)/docs/roam/pages/relations-patterns.md @@ -1,5 +1,5 @@ --- -title: "Relations and patterns" +title: "Legacy relations patterns" date: "2025-01-01" author: "" published: true diff --git a/apps/website/content/roam/fundamentals/_meta.ts b/apps/website/content/roam/fundamentals/_meta.ts index b661cddd1..c41e3335d 100644 --- a/apps/website/content/roam/fundamentals/_meta.ts +++ b/apps/website/content/roam/fundamentals/_meta.ts @@ -3,11 +3,6 @@ import type { MetaRecord } from "nextra"; const meta: MetaRecord = { "what-is-a-discourse-graph": "What is a discourse graph?", grammar: "Grammar", - nodes: "Nodes", - "operators-relations": "Operators and relations", - "base-grammar": "Base grammar", - "stored-relations": "Stored relations", - "migration-to-stored-relations": "Migration to stored relations", "relations-patterns": "Relations and patterns", }; diff --git a/apps/website/content/roam/fundamentals/grammar.md b/apps/website/content/roam/fundamentals/grammar.md deleted file mode 100644 index 29d5ee845..000000000 --- a/apps/website/content/roam/fundamentals/grammar.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: "Extension grammar" -date: "2025-01-01" -author: "" -published: true ---- - -- [Nodes](/docs/roam/fundamentals/nodes) -- [Operators and relations](/docs/roam/fundamentals/operators-relations) -- [Stored relations](/docs/roam/fundamentals/stored-relations) -- [Base grammar](/docs/roam/fundamentals/base-grammar) - -## Relation grammar building blocks - -- [Nodes](/docs/roam/fundamentals/nodes) diff --git a/apps/website/content/roam/fundamentals/grammar/_meta.ts b/apps/website/content/roam/fundamentals/grammar/_meta.ts new file mode 100644 index 000000000..7d337e68d --- /dev/null +++ b/apps/website/content/roam/fundamentals/grammar/_meta.ts @@ -0,0 +1,14 @@ +import type { MetaRecord } from "nextra"; + +const meta: MetaRecord = { + index: { + title: "Overview", + display: "hidden", + }, + nodes: "Nodes", + "operators-relations": "Operators and relations", + "base-grammar": "Base grammar", + "stored-relations": "Stored relations", +}; + +export default meta; diff --git a/apps/website/content/roam/fundamentals/base-grammar.md b/apps/website/content/roam/fundamentals/grammar/base-grammar.md similarity index 100% rename from apps/website/content/roam/fundamentals/base-grammar.md rename to apps/website/content/roam/fundamentals/grammar/base-grammar.md diff --git a/apps/website/content/roam/fundamentals/grammar/index.md b/apps/website/content/roam/fundamentals/grammar/index.md new file mode 100644 index 000000000..3008ef0ac --- /dev/null +++ b/apps/website/content/roam/fundamentals/grammar/index.md @@ -0,0 +1,15 @@ +--- +title: "Extension grammar" +date: "2025-01-01" +author: "" +published: true +--- + +- [Nodes](/docs/roam/fundamentals/grammar/nodes) +- [Operators and relations](/docs/roam/fundamentals/grammar/operators-relations) +- [Stored relations](/docs/roam/fundamentals/grammar/stored-relations) +- [Base grammar](/docs/roam/fundamentals/grammar/base-grammar) + +## Relation grammar building blocks + +- [Nodes](/docs/roam/fundamentals/grammar/nodes) diff --git a/apps/website/content/roam/fundamentals/nodes.md b/apps/website/content/roam/fundamentals/grammar/nodes.md similarity index 100% rename from apps/website/content/roam/fundamentals/nodes.md rename to apps/website/content/roam/fundamentals/grammar/nodes.md diff --git a/apps/website/content/roam/fundamentals/operators-relations.md b/apps/website/content/roam/fundamentals/grammar/operators-relations.md similarity index 100% rename from apps/website/content/roam/fundamentals/operators-relations.md rename to apps/website/content/roam/fundamentals/grammar/operators-relations.md diff --git a/apps/website/content/roam/fundamentals/stored-relations.md b/apps/website/content/roam/fundamentals/grammar/stored-relations.md similarity index 100% rename from apps/website/content/roam/fundamentals/stored-relations.md rename to apps/website/content/roam/fundamentals/grammar/stored-relations.md diff --git a/apps/website/content/roam/fundamentals/relations-patterns.md b/apps/website/content/roam/fundamentals/relations-patterns.md index 433b16f32..00188bf2a 100644 --- a/apps/website/content/roam/fundamentals/relations-patterns.md +++ b/apps/website/content/roam/fundamentals/relations-patterns.md @@ -5,7 +5,7 @@ author: "" published: true --- -Pattern-based relations are a **legacy workflow**. New graphs use [**stored relations**](/docs/roam/fundamentals/stored-relations) by default. If you're still using patterns or you're not sure which system your graph is on, see [**Migration to stored relations**](/docs/roam/fundamentals/migration-to-stored-relations). +Pattern-based relations are a **legacy workflow**. New graphs use [**stored relations**](/docs/roam/fundamentals/grammar/stored-relations) by default. If you're still using patterns or you're not sure which system your graph is on, see [**Migration to stored relations**](/docs/roam/guides/migration-to-stored-relations). The legacy pattern workflow recognizes a few common writing and outlining structures and converts them into discourse relations. diff --git a/apps/website/content/roam/guides/_meta.ts b/apps/website/content/roam/guides/_meta.ts index c98c9bf15..071fab45c 100644 --- a/apps/website/content/roam/guides/_meta.ts +++ b/apps/website/content/roam/guides/_meta.ts @@ -4,6 +4,7 @@ const meta: MetaRecord = { "creating-discourse-nodes": "Creating nodes", "tagging-candidate-nodes": "Tagging candidate nodes", "creating-discourse-relationships": "Creating relationships", + "migration-to-stored-relations": "Migration to stored relations", "exploring-discourse-graph": "Exploring your discourse graph", "querying-discourse-graph": "Querying", "extending-personalizing-graph": "Extending", diff --git a/apps/website/content/roam/guides/creating-discourse-relationships.md b/apps/website/content/roam/guides/creating-discourse-relationships.md index 57f01090e..c01d01ae2 100644 --- a/apps/website/content/roam/guides/creating-discourse-relationships.md +++ b/apps/website/content/roam/guides/creating-discourse-relationships.md @@ -7,7 +7,7 @@ published: true Creating relationships in Discourse Graph means creating **stored relations**. Stored relations are the default way to connect discourse nodes. -> Note: If you're still using pattern relations, or if you're not sure which system your graph is using, start with [**Migration to stored relations**](/docs/roam/fundamentals/migration-to-stored-relations). +> Note: If you're still using pattern relations, or if you're not sure which system your graph is using, start with [**Migration to stored relations**](/docs/roam/guides/migration-to-stored-relations). ## Quick start @@ -21,6 +21,6 @@ The relation is stored immediately and becomes available throughout your graph. ## Read next -- Learn how stored relations work in [**Stored relations**](/docs/roam/fundamentals/stored-relations) +- Learn how stored relations work in [**Stored relations**](/docs/roam/fundamentals/grammar/stored-relations) - Explore relationships from the [**Discourse context overlay**](/docs/roam/guides/exploring-discourse-graph/discourse-context-overlay) - If you're still using the legacy workflow, see [**Relations and patterns**](/docs/roam/fundamentals/relations-patterns) diff --git a/apps/website/content/roam/guides/extending-personalizing-graph.md b/apps/website/content/roam/guides/extending-personalizing-graph.md index 088132281..e4cf2277d 100644 --- a/apps/website/content/roam/guides/extending-personalizing-graph.md +++ b/apps/website/content/roam/guides/extending-personalizing-graph.md @@ -10,7 +10,7 @@ This page covers ways to extend and personalize Discourse Graph beyond the defau ## Stored relations If you want to use the current relation workflow, start with the -[Stored relations](/docs/roam/fundamentals/stored-relations) guide. +[Stored relations](/docs/roam/fundamentals/grammar/stored-relations) guide. ## Pattern relation legacy diff --git a/apps/website/content/roam/fundamentals/migration-to-stored-relations.md b/apps/website/content/roam/guides/migration-to-stored-relations.md similarity index 96% rename from apps/website/content/roam/fundamentals/migration-to-stored-relations.md rename to apps/website/content/roam/guides/migration-to-stored-relations.md index 715d40a6f..282ea9344 100644 --- a/apps/website/content/roam/fundamentals/migration-to-stored-relations.md +++ b/apps/website/content/roam/guides/migration-to-stored-relations.md @@ -7,7 +7,7 @@ published: true Stored relations make relations load faster and more reliably. Discourse Graph installs as of v0.18.0 use them by default. Older installs need a one-time migration that copies existing pattern-based relations into the new format. -This guide covers the migration flow from **Personal Settings** for older installs. If you're new to stored relations, start with the [stored relations overview](/docs/roam/fundamentals/stored-relations). +This guide covers the migration flow from **Personal Settings** for older installs. If you're new to stored relations, start with the [stored relations overview](/docs/roam/fundamentals/grammar/stored-relations). ## Turn on stored relations for an existing install diff --git a/apps/website/content/roam/welcome/getting-started.md b/apps/website/content/roam/welcome/getting-started.md index a0f022009..cacd269c9 100644 --- a/apps/website/content/roam/welcome/getting-started.md +++ b/apps/website/content/roam/welcome/getting-started.md @@ -29,4 +29,4 @@ Learn the fundamentals of the Discourse Graph extension to get a deeper understa - [What is a Discourse Graph?](/docs/roam/fundamentals/what-is-a-discourse-graph) - [The Discourse Graph extension grammar](/docs/roam/fundamentals/grammar) -- [The base grammar: questions, claims, and evidence](/docs/roam/fundamentals/base-grammar) +- [The base grammar: questions, claims, and evidence](/docs/roam/fundamentals/grammar/base-grammar) From ed29a8fe35d7e23c4b7a5048639f2b5b0a289de9 Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Tue, 31 Mar 2026 22:48:53 -0600 Subject: [PATCH 12/14] Enhance documentation routing and redirects - Added new custom redirects for Roam documentation to improve navigation. - Simplified the fundamentals section by removing outdated entries. - Introduced a utility function for creating redirects, enhancing code maintainability. --- apps/website/docsRouteMap.ts | 93 +++++++++++++++++++++++++++++------- 1 file changed, 77 insertions(+), 16 deletions(-) diff --git a/apps/website/docsRouteMap.ts b/apps/website/docsRouteMap.ts index 77cd8c2dd..d16d8a425 100644 --- a/apps/website/docsRouteMap.ts +++ b/apps/website/docsRouteMap.ts @@ -4,27 +4,13 @@ export const ROAM_DOC_SECTIONS = { "creating-discourse-nodes", "tagging-candidate-nodes", "creating-discourse-relationships", + "migration-to-stored-relations", "exploring-discourse-graph", "querying-discourse-graph", "extending-personalizing-graph", "sharing-discourse-graph", ], - fundamentals: [ - "what-is-a-discourse-graph", - "grammar", - "nodes", - "operators-relations", - "base-grammar", - "stored-relations", - "migration-to-stored-relations", - "relations-patterns", - ], - "views-and-tools": [ - "discourse-context", - "discourse-context-overlay", - "discourse-attributes", - "node-index", - ], + fundamentals: ["what-is-a-discourse-graph", "grammar", "relations-patterns"], "use-cases": [ "literature-reviewing", "enhanced-zettelkasten", @@ -64,6 +50,12 @@ type Redirect = { permanent: boolean; }; +const createRedirect = (source: string, destination: string): Redirect => ({ + source, + destination, + permanent: true, +}); + const buildPlatformRedirects = ( platform: "roam" | "obsidian", sections: Record, @@ -76,7 +68,76 @@ const buildPlatformRedirects = ( })), ); +const ROAM_CUSTOM_REDIRECTS: Redirect[] = [ + createRedirect( + "/docs/roam/discourse-context", + "/docs/roam/guides/exploring-discourse-graph/discourse-context", + ), + createRedirect( + "/docs/roam/discourse-context-overlay", + "/docs/roam/guides/exploring-discourse-graph/discourse-context-overlay", + ), + createRedirect( + "/docs/roam/discourse-attributes", + "/docs/roam/guides/exploring-discourse-graph/discourse-attributes", + ), + createRedirect( + "/docs/roam/node-index", + "/docs/roam/guides/exploring-discourse-graph/node-index", + ), + createRedirect( + "/docs/roam/views-and-tools/discourse-context", + "/docs/roam/guides/exploring-discourse-graph/discourse-context", + ), + createRedirect( + "/docs/roam/views-and-tools/discourse-context-overlay", + "/docs/roam/guides/exploring-discourse-graph/discourse-context-overlay", + ), + createRedirect( + "/docs/roam/views-and-tools/discourse-attributes", + "/docs/roam/guides/exploring-discourse-graph/discourse-attributes", + ), + createRedirect( + "/docs/roam/views-and-tools/node-index", + "/docs/roam/guides/exploring-discourse-graph/node-index", + ), + createRedirect("/docs/roam/nodes", "/docs/roam/fundamentals/grammar/nodes"), + createRedirect( + "/docs/roam/operators-relations", + "/docs/roam/fundamentals/grammar/operators-relations", + ), + createRedirect( + "/docs/roam/base-grammar", + "/docs/roam/fundamentals/grammar/base-grammar", + ), + createRedirect( + "/docs/roam/stored-relations", + "/docs/roam/fundamentals/grammar/stored-relations", + ), + createRedirect( + "/docs/roam/fundamentals/nodes", + "/docs/roam/fundamentals/grammar/nodes", + ), + createRedirect( + "/docs/roam/fundamentals/operators-relations", + "/docs/roam/fundamentals/grammar/operators-relations", + ), + createRedirect( + "/docs/roam/fundamentals/base-grammar", + "/docs/roam/fundamentals/grammar/base-grammar", + ), + createRedirect( + "/docs/roam/fundamentals/stored-relations", + "/docs/roam/fundamentals/grammar/stored-relations", + ), + createRedirect( + "/docs/roam/fundamentals/migration-to-stored-relations", + "/docs/roam/guides/migration-to-stored-relations", + ), +]; + export const DOCS_REDIRECTS: Redirect[] = [ + ...ROAM_CUSTOM_REDIRECTS, ...buildPlatformRedirects("roam", ROAM_DOC_SECTIONS), ...buildPlatformRedirects("obsidian", OBSIDIAN_DOC_SECTIONS), ]; From 311123d539a87ce6b17841cd64441f828fcb3b01 Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Tue, 31 Mar 2026 22:50:52 -0600 Subject: [PATCH 13/14] Remove outdated installation instructions for Roam Depot and update related documentation for clarity. The "Installation from Roam Depot" entry has been deleted, and the main installation page has been revised for improved readability. --- apps/website/content/roam/welcome/_meta.ts | 1 - .../roam/welcome/installation-roam-depot.md | 14 -------------- apps/website/content/roam/welcome/installation.md | 2 +- 3 files changed, 1 insertion(+), 16 deletions(-) delete mode 100644 apps/website/content/roam/welcome/installation-roam-depot.md diff --git a/apps/website/content/roam/welcome/_meta.ts b/apps/website/content/roam/welcome/_meta.ts index 1f0b15743..ac6fd187f 100644 --- a/apps/website/content/roam/welcome/_meta.ts +++ b/apps/website/content/roam/welcome/_meta.ts @@ -3,7 +3,6 @@ import type { MetaRecord } from "nextra"; const meta: MetaRecord = { "getting-started": "Getting started", installation: "Installation", - "installation-roam-depot": "Installation from Roam Depot", }; export default meta; diff --git a/apps/website/content/roam/welcome/installation-roam-depot.md b/apps/website/content/roam/welcome/installation-roam-depot.md deleted file mode 100644 index 237aa6cb6..000000000 --- a/apps/website/content/roam/welcome/installation-roam-depot.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Installation" -date: "2025-01-01" -author: "" -published: false ---- - -The Discourse Graphs extension can be installed via Roam Depot: - -![](/docs/roam/roam-depot-sidebar.png) - -![](/docs/roam/roam-depot-settings.png) - -Then type in "Discourse Graphs" in the search bar and click install. diff --git a/apps/website/content/roam/welcome/installation.md b/apps/website/content/roam/welcome/installation.md index 44e738d09..41a481e33 100644 --- a/apps/website/content/roam/welcome/installation.md +++ b/apps/website/content/roam/welcome/installation.md @@ -5,7 +5,7 @@ author: "" published: true --- -The Discourse Graphs extension is now available for installation via Roam Depot. +The Discourse Graphs extension available for installation via Roam Depot. Search for Discourse Graph in Roam Depot From b0093cdfa9f728fef45251d43c664093267c8e32 Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Tue, 31 Mar 2026 23:03:31 -0600 Subject: [PATCH 14/14] Refactor documentation for consistency and clarity - Removed unnecessary sections and improved formatting across multiple files. - Standardized headings and titles for better readability. - Updated related links and streamlined content to enhance user navigation. --- .../obsidian/advanced-features/sync-and-import.md | 4 ---- .../obsidian/configuration/node-types-templates.md | 12 ++++++------ .../obsidian/configuration/relationship-types.md | 2 +- .../core-features/creating-discourse-nodes.md | 12 ++++++------ .../creating-discourse-relationships.md | 6 +----- .../content/obsidian/fundamentals/base-grammar.md | 2 -- .../fundamentals/what-is-a-discourse-graph.md | 2 +- .../website/content/obsidian/welcome/installation.md | 8 -------- .../roam/fundamentals/what-is-a-discourse-graph.md | 2 +- 9 files changed, 16 insertions(+), 34 deletions(-) diff --git a/apps/website/content/obsidian/advanced-features/sync-and-import.md b/apps/website/content/obsidian/advanced-features/sync-and-import.md index a2fede972..aa1801aa0 100644 --- a/apps/website/content/obsidian/advanced-features/sync-and-import.md +++ b/apps/website/content/obsidian/advanced-features/sync-and-import.md @@ -44,8 +44,6 @@ The sync feature is located in a hidden **admin panel** tab that is not visible Once enabled, your discourse nodes will begin syncing automatically to the Discourse Graph database. The plugin monitors file changes in your vault (with a short delay) and syncs them in the background. ---- - ## Publishing a discourse node Publishing makes a synced discourse node available to other members of your group. This is how you share your work with collaborators. @@ -82,8 +80,6 @@ Before publishing, make sure: - Both the source and destination nodes are published to the same group, **and** - The relation type is defined in your discourse relation settings ---- - ## Importing discourse nodes from another space Importing allows you to bring published discourse nodes from other group members into your vault. diff --git a/apps/website/content/obsidian/configuration/node-types-templates.md b/apps/website/content/obsidian/configuration/node-types-templates.md index df8db92b0..c8fa32139 100644 --- a/apps/website/content/obsidian/configuration/node-types-templates.md +++ b/apps/website/content/obsidian/configuration/node-types-templates.md @@ -5,11 +5,11 @@ author: "" published: true --- -## Configuring Node Types +## Configuring node types Node types are the building blocks of your discourse graph. Each node type represents a different kind of content or concept in your notes. -### Adding a Node Type +### Adding a node type 1. Under "Node Types," click "Add Node Type" 2. Enter a name for your node type (e.g., "Claim", "Evidence", "Question") @@ -23,11 +23,11 @@ Node types are the building blocks of your discourse graph. Each node type repre - Click "Save Changes" -## Working with Templates +## Working with templates Templates allow you to automatically add predefined content when creating new nodes. They're especially useful for maintaining consistent structure across similar types of notes. -### Setting Up Templates +### Setting up templates 1. Create a new folder for templates ![new folder](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FyTtJ1a0iI2.png?alt=media&token=b5d09b10-f170-47cd-a239-ee5f7acd89dc) @@ -38,14 +38,14 @@ Templates allow you to automatically add predefined content when creating new no 3. Create template files ![create template file](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FtTr9vOnXnX.png?alt=media&token=dda1fe25-3ccf-42b4-8f3c-1cd29f82c3f7) -## Template Requirements +## Template requirements - Templates must be stored in your designated template folder - The Templates core plugin must be enabled - Template files should use Markdown format - Templates can include any valid Markdown content -## Next Steps +## Related - [Configure relationship types](/docs/obsidian/configuration/relationship-types) - [Learn about creating nodes](/docs/obsidian/core-features/creating-discourse-nodes) diff --git a/apps/website/content/obsidian/configuration/relationship-types.md b/apps/website/content/obsidian/configuration/relationship-types.md index ce6344d17..80dfad8f2 100644 --- a/apps/website/content/obsidian/configuration/relationship-types.md +++ b/apps/website/content/obsidian/configuration/relationship-types.md @@ -49,7 +49,7 @@ Here are some common relationship types: - Evidence → contradicts → Claim - Source → informs → Question -## Next steps +## Related - [Create your first relationship](/docs/obsidian/core-features/creating-discourse-relationships) - [Learn about the discourse context](/docs/obsidian/core-features/discourse-context) diff --git a/apps/website/content/obsidian/core-features/creating-discourse-nodes.md b/apps/website/content/obsidian/core-features/creating-discourse-nodes.md index 66ff68fdd..62f739084 100644 --- a/apps/website/content/obsidian/core-features/creating-discourse-nodes.md +++ b/apps/website/content/obsidian/core-features/creating-discourse-nodes.md @@ -13,9 +13,9 @@ To create a discourse node, first select the text you want to turn into a node: There are two ways you can create a node: -### 1. Using command keys (recommended) +### Using command keys (recommended) -#### 1.1 Turn selected text into discourse node +#### Turn selected text into discourse node 1. Press `Cmd + \` (or your configured hotkey) 2. The Node Menu will open as a popup @@ -24,20 +24,20 @@ There are two ways you can create a node: 4. A new discourse node will be created ![node created](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2F1VNkJC0aH8.png?alt=media&token=df9a26aa-997b-4b56-a307-87a80e350b28) -#### 1.2 Creating new node from scratch +#### Creating new node from scratch 1. Press `Cmd + \` (or your configured hotkey) 2. Enter the title and node type ![](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FyYxtLKkx6B.png?alt=media&token=7f4f02df-d1fe-4529-8530-90acb0dc74b8) -### 2. Using the right-click menu +### Using the right-click menu 1. Right-click on the selected text Alternatively, you can right-click on the selected text ![right click menu](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2F4UqeVkqLz7.png?alt=media&token=d2373152-d251-45fe-afb6-56373d6092aa) 2. Choose a node type from the "Turn into discourse node" menu -### 3. Turn existing page into discourse node +### Turn existing page into discourse node If a page is not a discourse node, you can turn it into one by clicking on the file menu, and chosing "Convert into" option ![](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FCAGcQrCONJ.png?alt=media&token=fba6a6c9-038c-4a63-a46f-920bb8b37df1) @@ -51,7 +51,7 @@ When creating a node, if you've configured a [template for that node type](/docs The new node will be saved in the designated folder that you created in the [General settings](/docs/obsidian/configuration/general-settings) -## Next Steps +## Related After creating nodes: diff --git a/apps/website/content/obsidian/core-features/creating-discourse-relationships.md b/apps/website/content/obsidian/core-features/creating-discourse-relationships.md index 7eae520bf..8fb765ad2 100644 --- a/apps/website/content/obsidian/core-features/creating-discourse-relationships.md +++ b/apps/website/content/obsidian/core-features/creating-discourse-relationships.md @@ -5,8 +5,6 @@ author: "" published: true --- -## Creating a relationship - To create a relationship between discourse nodes: 1. Open a note that you want to create a relationship from @@ -29,8 +27,6 @@ To create a relationship between discourse nodes: 6. Click "Confirm" to create the relationship ![relationship created](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FK8XAhCqrUL.png?alt=media&token=a559c477-c7f6-4b3e-8b00-ece7da5d4fec) -## Next steps - -After creating relationships: +## Related - [Learn how to explore your graph](/docs/obsidian/core-features/canvas) diff --git a/apps/website/content/obsidian/fundamentals/base-grammar.md b/apps/website/content/obsidian/fundamentals/base-grammar.md index 126b6d0d7..e15419541 100644 --- a/apps/website/content/obsidian/fundamentals/base-grammar.md +++ b/apps/website/content/obsidian/fundamentals/base-grammar.md @@ -5,8 +5,6 @@ author: "" published: true --- -## Base grammar - This is what ships with the extension. ### Nodes diff --git a/apps/website/content/obsidian/fundamentals/what-is-a-discourse-graph.md b/apps/website/content/obsidian/fundamentals/what-is-a-discourse-graph.md index e3a1a998e..ebde4ad4e 100644 --- a/apps/website/content/obsidian/fundamentals/what-is-a-discourse-graph.md +++ b/apps/website/content/obsidian/fundamentals/what-is-a-discourse-graph.md @@ -1,5 +1,5 @@ --- -title: "What is a Discourse Graph" +title: "What is a discourse graph" date: "2025-01-01" author: "" published: true diff --git a/apps/website/content/obsidian/welcome/installation.md b/apps/website/content/obsidian/welcome/installation.md index 4a591c6da..ece1d6525 100644 --- a/apps/website/content/obsidian/welcome/installation.md +++ b/apps/website/content/obsidian/welcome/installation.md @@ -36,11 +36,3 @@ published: true ![Add discourse graph](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdiscourse-graphs%2FSBCK-2lkcu.png?alt=media&token=0375c828-da4d-43b4-8f2c-e691692cb019) 5. Check the box for "Enable after installing the plugin" 6. Click "Add Plugin" - -## Next Steps - -After installation, you'll want to: - -1. [Configure your node types](/docs/obsidian/configuration/node-types-templates) -2. [Set up relationship types](/docs/obsidian/configuration/relationship-types) -3. [Create your first node](/docs/obsidian/core-features/creating-discourse-nodes) diff --git a/apps/website/content/roam/fundamentals/what-is-a-discourse-graph.md b/apps/website/content/roam/fundamentals/what-is-a-discourse-graph.md index e3a1a998e..ebde4ad4e 100644 --- a/apps/website/content/roam/fundamentals/what-is-a-discourse-graph.md +++ b/apps/website/content/roam/fundamentals/what-is-a-discourse-graph.md @@ -1,5 +1,5 @@ --- -title: "What is a Discourse Graph" +title: "What is a discourse graph" date: "2025-01-01" author: "" published: true