ENG-1797 Add links to existing docs (#1078)

* Bump roamjs-components and add docs links to settings

* Update roamjs-components to version 0.88.1 and replace imports of Description component with SettingsDescription in settings components. Add missing periods to descriptions in ExportSettings for consistency.

Author: mdroidian

apps/roam/package.json

@@ -74,7 +74,7 @@
     "react-draggable": "4.4.5",
     "react-in-viewport": "1.0.0-alpha.20",
     "react-vertical-timeline-component": "3.5.2",
-    "roamjs-components": "0.87.0",
+    "roamjs-components": "0.88.1",
     "tldraw": "2.4.6",
     "use-sync-external-store": "1.5.0",
     "xregexp": "^5.0.0",

apps/roam/src/components/settings/CanvasShortcutSettings.tsx

@@ -1,6 +1,6 @@
 import React, { useState } from "react";
 import { Checkbox, InputGroup, Tabs, Tab } from "@blueprintjs/core";
-import Description from "roamjs-components/components/Description";
+import Description from "~/components/settings/SettingsDescription";
 import getDiscourseNodes, {
   excludeDefaultNodes,
 } from "~/utils/getDiscourseNodes";

apps/roam/src/components/settings/DiscourseNodeSuggestiveRules.tsx

@@ -17,6 +17,7 @@ import {
   TEMPLATE_SETTING_KEYS,
 } from "~/components/settings/utils/settingKeys";
 import { RenderRoamBlock } from "~/utils/roamReactComponents";
+import { ROAM_DOCS, withDocsLink } from "./utils/docs";
 
 const DiscourseNodeSuggestiveRules = ({
   node,
@@ -72,7 +73,10 @@ const DiscourseNodeSuggestiveRules = ({
       <DualWriteBlocksPanel
         nodeType={node.type}
         title="Template"
-        description={`The template that auto fills ${node.text} page when generated.`}
+        description={withDocsLink(
+          `The template that auto fills ${node.text} page when generated.`,
+          ROAM_DOCS.creatingNodes,
+        )}
         settingKeys={TEMPLATE_SETTING_KEYS}
         uid={templateUid}
         defaultValue={node.template}

apps/roam/src/components/settings/ExportSettings.tsx

@@ -11,6 +11,7 @@ import {
   EXPORT_KEYS,
 } from "~/components/settings/utils/settingKeys";
 import { type SettingsSnapshot } from "./utils/accessors";
+import { ROAM_DOCS, withDocsLink } from "./utils/docs";
 
 const DiscourseGraphExport = ({
   globalSettings,
@@ -27,7 +28,10 @@ const DiscourseGraphExport = ({
       <div>
         <GlobalFlagPanel
           title="remove special characters"
-          description="Whether or not to remove the special characters in a file name"
+          description={withDocsLink(
+            "Whether or not to remove the special characters in a file name.",
+            ROAM_DOCS.sharing,
+          )}
           settingKeys={[
             GLOBAL_KEYS.export,
             EXPORT_KEYS.removeSpecialCharacters,
@@ -40,7 +44,10 @@ const DiscourseGraphExport = ({
 
         <GlobalFlagPanel
           title="resolve block references"
-          description="Replaces block references in the markdown content with the block's content"
+          description={withDocsLink(
+            "Replaces block references in the markdown content with the block's content.",
+            ROAM_DOCS.sharing,
+          )}
           settingKeys={[GLOBAL_KEYS.export, EXPORT_KEYS.resolveBlockReferences]}
           initialValue={exportBlockProps[EXPORT_KEYS.resolveBlockReferences]}
           order={3}
@@ -49,7 +56,10 @@ const DiscourseGraphExport = ({
         />
         <GlobalFlagPanel
           title="resolve block embeds"
-          description="Replaces block embeds in the markdown content with the block's content tree"
+          description={withDocsLink(
+            "Replaces block embeds in the markdown content with the block's content tree.",
+            ROAM_DOCS.sharing,
+          )}
           settingKeys={[GLOBAL_KEYS.export, EXPORT_KEYS.resolveBlockEmbeds]}
           initialValue={exportBlockProps[EXPORT_KEYS.resolveBlockEmbeds]}
           order={4}
@@ -59,7 +69,10 @@ const DiscourseGraphExport = ({
 
         <GlobalFlagPanel
           title="append referenced node"
-          description="If a referenced node is defined in a node's format, it will be appended to the discourse context"
+          description={withDocsLink(
+            "If a referenced node is defined in a node's format, it will be appended to the discourse context.",
+            ROAM_DOCS.sharing,
+          )}
           settingKeys={[GLOBAL_KEYS.export, EXPORT_KEYS.appendReferencedNode]}
           initialValue={exportBlockProps[EXPORT_KEYS.appendReferencedNode]}
           order={6}
@@ -70,7 +83,10 @@ const DiscourseGraphExport = ({
       <div className="link-type-select-wrapper">
         <GlobalSelectPanel
           title="link type"
-          description="How to format links that appear in your export."
+          description={withDocsLink(
+            "How to format links that appear in your export.",
+            ROAM_DOCS.sharing,
+          )}
           settingKeys={[GLOBAL_KEYS.export, EXPORT_KEYS.linkType]}
           initialValue={exportBlockProps[EXPORT_KEYS.linkType]}
           order={5}
@@ -81,7 +97,10 @@ const DiscourseGraphExport = ({
       </div>
       <GlobalNumberPanel
         title="max filename length"
-        description="Set the maximum name length for markdown file exports"
+        description={withDocsLink(
+          "Set the maximum name length for markdown file exports.",
+          ROAM_DOCS.sharing,
+        )}
         settingKeys={[GLOBAL_KEYS.export, EXPORT_KEYS.maxFilenameLength]}
         initialValue={exportBlockProps[EXPORT_KEYS.maxFilenameLength]}
         order={0}
@@ -90,7 +109,10 @@ const DiscourseGraphExport = ({
       />
       <GlobalMultiTextPanel
         title="frontmatter"
-        description="Specify all the lines that should go to the Frontmatter of the markdown file"
+        description={withDocsLink(
+          "Specify all the lines that should go to the Frontmatter of the markdown file.",
+          ROAM_DOCS.sharing,
+        )}
         settingKeys={[GLOBAL_KEYS.export, EXPORT_KEYS.frontmatter]}
         initialValue={exportBlockProps[EXPORT_KEYS.frontmatter]}
         order={2}

apps/roam/src/components/settings/GeneralSettings.tsx

@@ -15,6 +15,7 @@ import {
   getUidAndStringSetting,
 } from "~/utils/getExportSettings";
 import { DISCOURSE_CONFIG_PAGE_TITLE } from "~/data/constants";
+import { ROAM_DOCS, withDocsLink } from "./utils/docs";
 
 const DiscourseGraphHome = ({
   globalSettings,
@@ -47,7 +48,10 @@ const DiscourseGraphHome = ({
           Update titles to Sentence case once read side is migrated to block props. */}
       <GlobalTextPanel
         title="trigger"
-        description="The trigger to create the node menu."
+        description={withDocsLink(
+          "The trigger to create the node menu.",
+          ROAM_DOCS.creatingNodes,
+        )}
         settingKeys={[GLOBAL_KEYS.trigger]}
         initialValue={globalSettings[GLOBAL_KEYS.trigger]}
         order={0}

apps/roam/src/components/settings/HomePersonalSettings.tsx

@@ -2,7 +2,7 @@ import React, { useState } from "react";
 import { OnloadArgs } from "roamjs-components/types";
 import { render as renderToast } from "roamjs-components/components/Toast";
 import { Label, Dialog, Button, Intent, Classes } from "@blueprintjs/core";
-import Description from "roamjs-components/components/Description";
+import Description from "~/components/settings/SettingsDescription";
 import { addStyle } from "roamjs-components/dom";
 import { NodeMenuTriggerComponent } from "~/components/DiscourseNodeMenu";
 import {
@@ -35,6 +35,7 @@ import posthog from "posthog-js";
 import internalError from "~/utils/internalError";
 import { setPersonalSetting, type SettingsSnapshot } from "./utils/accessors";
 import { getStoredRelationsEnabled } from "~/utils/storedRelations";
+import { ROAM_DOCS, withDocsLink } from "./utils/docs";
 
 const enum RelationMigrationDialog {
   "none",
@@ -119,7 +120,12 @@ const HomePersonalSettings = ({
     <div className="flex flex-col gap-4 p-1">
       <Label>
         Personal node menu trigger
-        <Description description="Override the global trigger for the discourse node menu." />
+        <Description
+          description={withDocsLink(
+            "Override the global trigger for the discourse node menu.",
+            ROAM_DOCS.creatingNodes,
+          )}
+        />
         <NodeMenuTriggerComponent
           extensionAPI={extensionAPI}
           initialValue={personalSettings[PERSONAL_KEYS.personalNodeMenuTrigger]}
@@ -138,13 +144,19 @@ const HomePersonalSettings = ({
         settingKey={DISCOURSE_TOOL_SHORTCUT_KEY}
         blockPropKey={PERSONAL_KEYS.discourseToolShortcut}
         label="Discourse tool keyboard shortcut"
-        description="Set a single key to activate the discourse tool in tldraw. Only single keys (no modifiers) are supported. Leave empty for no shortcut."
+        description={withDocsLink(
+          "Set a single key to activate the discourse tool in tldraw. Only single keys (no modifiers) are supported. Leave empty for no shortcut.",
+          ROAM_DOCS.creatingNodes,
+        )}
         placeholder="Click to set single key"
         initialValue={personalSettings[PERSONAL_KEYS.discourseToolShortcut]}
       />
       <PersonalFlagPanel
         title="Overlay"
-        description="Whether or not to overlay discourse context information over discourse node references."
+        description={withDocsLink(
+          "Whether or not to overlay discourse context information over discourse node references.",
+          ROAM_DOCS.discourseContextOverlay,
+        )}
         settingKeys={[PERSONAL_KEYS.discourseContextOverlay]}
         initialValue={personalSettings[PERSONAL_KEYS.discourseContextOverlay]}
         onChange={(checked) => {
@@ -157,7 +169,10 @@ const HomePersonalSettings = ({
       />
       <PersonalFlagPanel
         title="Enable stored relations"
-        description="Use stored relations instead of legacy pattern-based relations"
+        description={withDocsLink(
+          "Use stored relations instead of legacy pattern-based relations",
+          ROAM_DOCS.migrationToStoredRelations,
+        )}
         settingKeys={["Reified relation triples"]}
         initialValue={personalSettings["Reified relation triples"]}
         value={storedRelations}
@@ -179,7 +194,10 @@ const HomePersonalSettings = ({
 
       <PersonalFlagPanel
         title="Text selection popup"
-        description="Whether or not to show the discourse node menu when selecting text."
+        description={withDocsLink(
+          "Whether or not to show the discourse node menu when selecting text.",
+          ROAM_DOCS.creatingNodes,
+        )}
         settingKeys={[PERSONAL_KEYS.textSelectionPopup]}
         initialValue={personalSettings[PERSONAL_KEYS.textSelectionPopup]}
         onChange={(checked) => {
@@ -221,7 +239,10 @@ const HomePersonalSettings = ({
       />
       <PersonalFlagPanel
         title="Auto canvas relations"
-        description="Automatically add discourse relations to canvas when a node is added"
+        description={withDocsLink(
+          "Automatically add discourse relations to canvas when a node is added",
+          ROAM_DOCS.storedRelations,
+        )}
         settingKeys={[PERSONAL_KEYS.autoCanvasRelations]}
         initialValue={personalSettings[PERSONAL_KEYS.autoCanvasRelations]}
         onChange={(checked) => {
@@ -231,7 +252,10 @@ const HomePersonalSettings = ({
 
       <PersonalFlagPanel
         title="(BETA) Overlay in canvas"
-        description="Whether or not to overlay discourse context information over canvas nodes."
+        description={withDocsLink(
+          "Whether or not to overlay discourse context information over canvas nodes.",
+          ROAM_DOCS.discourseContextOverlay,
+        )}
         settingKeys={[PERSONAL_KEYS.overlayInCanvas]}
         initialValue={personalSettings[PERSONAL_KEYS.overlayInCanvas]}
         onChange={(checked) => {

apps/roam/src/components/settings/KeyboardShortcutInput.tsx

@@ -7,7 +7,7 @@ import {
   IKeyCombo,
   Label,
 } from "@blueprintjs/core";
-import Description from "roamjs-components/components/Description";
+import Description from "~/components/settings/SettingsDescription";
 import { DISCOURSE_TOOL_SHORTCUT_KEY } from "~/data/userSettings";
 import { setPersonalSetting } from "~/components/settings/utils/accessors";
 import { comboToString } from "~/components/DiscourseNodeMenu";
@@ -18,7 +18,7 @@ type KeyboardShortcutInputProps = {
   settingKey: string;
   blockPropKey: keyof PersonalSettings;
   label: string;
-  description: string;
+  description: React.ReactNode;
   initialValue: IKeyCombo;
   placeholder?: string;
 };

apps/roam/src/components/settings/NodeConfig.tsx

@@ -2,7 +2,7 @@ import React, { useState, useCallback, useEffect } from "react";
 import getDiscourseNodes, { DiscourseNode } from "~/utils/getDiscourseNodes";
 import DualWriteBlocksPanel from "./components/EphemeralBlocksPanel";
 import { getSubTree } from "roamjs-components/util";
-import Description from "roamjs-components/components/Description";
+import Description from "~/components/settings/SettingsDescription";
 import {
   Label,
   Tabs,
@@ -39,6 +39,7 @@ import {
   DiscourseNodeFlagPanel,
   DiscourseNodeSelectPanel,
 } from "./components/BlockPropSettingPanels";
+import { ROAM_DOCS, withDocsLink } from "./utils/docs";
 
 export const getCleanTagText = (tag: string): string => {
   return tag.replace(/^#+/, "").trim().toUpperCase();
@@ -209,7 +210,10 @@ const NodeConfig = ({
               <DiscourseNodeTextPanel
                 nodeType={node.type}
                 title="Description"
-                description={`Describing what the ${node.text} node represents in your graph.`}
+                description={withDocsLink(
+                  `Describing what the ${node.text} node represents in your graph.`,
+                  ROAM_DOCS.grammarNodes,
+                )}
                 settingKeys={[DISCOURSE_NODE_KEYS.description]}
                 initialValue={node.description}
                 multiline
@@ -220,7 +224,10 @@ const NodeConfig = ({
               <DiscourseNodeTextPanel
                 nodeType={node.type}
                 title="Shortcut"
-                description={`The trigger to quickly create a ${node.text} page from the node menu.`}
+                description={withDocsLink(
+                  `The trigger to quickly create a ${node.text} page from the node menu.`,
+                  ROAM_DOCS.creatingNodes,
+                )}
                 settingKeys={[DISCOURSE_NODE_KEYS.shortcut]}
                 initialValue={node.shortcut}
                 error={shortcutError}
@@ -233,7 +240,10 @@ const NodeConfig = ({
                 <DiscourseNodeTextPanel
                   nodeType={node.type}
                   title="Tag"
-                  description={`Designate a hashtag for marking potential ${node.text}.`}
+                  description={withDocsLink(
+                    `Designate a hashtag for marking potential ${node.text}.`,
+                    ROAM_DOCS.taggingCandidateNodes,
+                  )}
                   settingKeys={[DISCOURSE_NODE_KEYS.tag]}
                   initialValue={node.tag}
                   placeholder={generateTagPlaceholder(node)}
@@ -330,7 +340,10 @@ const NodeConfig = ({
               <DiscourseNodeTextPanel
                 nodeType={node.type}
                 title="Format"
-                description={`DEPRECATED - Use specification instead. The format ${node.text} pages should have.`}
+                description={withDocsLink(
+                  `DEPRECATED - Use specification instead. The format ${node.text} pages should have.`,
+                  ROAM_DOCS.grammarNodes,
+                )}
                 settingKeys={[DISCOURSE_NODE_KEYS.format]}
                 initialValue={node.format}
                 error={formatError}
@@ -342,9 +355,10 @@ const NodeConfig = ({
               <Label>
                 Specification
                 <Description
-                  description={
-                    "The conditions specified to identify a ${nodeText} node."
-                  }
+                  description={withDocsLink(
+                    `The conditions specified to identify a ${node.text} node.`,
+                    ROAM_DOCS.grammarNodes,
+                  )}
                 />
                 <DiscourseNodeSpecification
                   node={node}
@@ -369,7 +383,10 @@ const NodeConfig = ({
               <DualWriteBlocksPanel
                 nodeType={node.type}
                 title="Template"
-                description={`The template that auto fills ${node.text} page when generated.`}
+                description={withDocsLink(
+                  `The template that auto fills ${node.text} page when generated.`,
+                  ROAM_DOCS.creatingNodes,
+                )}
                 settingKeys={TEMPLATE_SETTING_KEYS}
                 uid={templateUid}
                 defaultValue={node.template}
@@ -393,7 +410,10 @@ const NodeConfig = ({
               <DiscourseNodeSelectPanel
                 nodeType={node.type}
                 title="Overlay"
-                description="Select which attribute is used for the discourse overlay"
+                description={withDocsLink(
+                  "Select which attribute is used for the discourse overlay",
+                  ROAM_DOCS.discourseAttributes,
+                )}
                 settingKeys={[DISCOURSE_NODE_KEYS.overlay]}
                 options={attributeNode.children.map((c) => c.text)}
                 initialValue={

apps/roam/src/components/settings/PageGroupPanel.tsx

@@ -1,6 +1,6 @@
 import React, { useState, useCallback } from "react";
 import { Label, Button, Intent, Tag, InputGroup } from "@blueprintjs/core";
-import Description from "roamjs-components/components/Description";
+import Description from "~/components/settings/SettingsDescription";
 import AutocompleteInput from "roamjs-components/components/AutocompleteInput";
 import createBlock from "roamjs-components/writes/createBlock";
 import deleteBlock from "roamjs-components/writes/deleteBlock";