Interactive synopsis Fix #2024

gatsby-config.js

@@ -4,7 +4,7 @@ require('dotenv').config()
 const path = require('path')
 
 require('./config/prismjs/dvc')
-require('./config/prismjs/usage')
+// require('./config/prismjs/usage')
 require('./config/prismjs/dvctable')
 
 const apiMiddleware = require('./src/server/middleware/api')
@@ -66,6 +66,7 @@ const plugins = [
       plugins: [
         'gatsby-remark-embedder',
         'gatsby-remark-dvc-linker',
+        'gatsby-remark-args-linker',
         {
           resolve: 'gatsby-remark-prismjs',
           options: {

plugins/gatsby-remark-args-linker/index.js

@@ -0,0 +1,92 @@
+const visit = require('unist-util-visit')
+
+const argsRegex = new RegExp(/\-{1,2}[a-zA-Z-]*/, 'ig')
+
+function patch(context, key, value) {
+  if (!context[key]) {
+    context[key] = value
+  }
+
+  return context[key]
+}
+const svgIcon = `<svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg>`
+
+const addIdAttrToNode = (node, id) => {
+  const data = patch(node, `data`, {})
+
+  patch(data, `id`, id)
+  patch(data, `htmlAttributes`, {})
+  patch(data, `hProperties`, {})
+  patch(data.htmlAttributes, `id`, id)
+  patch(data.hProperties, `id`, id)
+}
+
+module.exports = (
+  { markdownAST },
+  { className = 'anchor', isIconAfterHeader = false }
+) => {
+  visit(
+    markdownAST,
+    node =>
+      node.type === 'listItem' &&
+      node.children.some(
+        item =>
+          item.type === 'paragraph' &&
+          item.children[0]?.type === 'inlineCode' &&
+          String(item.children[0]?.value).startsWith('-')
+      ),
+    listItemNode => {
+      const isParagraphNode = listItemNode.children?.[0].type === 'paragraph'
+      if (!isParagraphNode) return
+      const paragraphNode = listItemNode.children[0]
+      const isFirstArgNode =
+        paragraphNode.children[0]?.type === 'inlineCode' &&
+        String(paragraphNode.children[0]?.value).startsWith('-')
+      if (isFirstArgNode) {
+        const firstArgNode = paragraphNode.children[0]
+        const value = firstArgNode.value
+        const id = value.match(argsRegex)[0]
+        addIdAttrToNode(listItemNode, id)
+
+        const data = patch(listItemNode, `data`, {})
+        patch(data, `htmlAttributes`, {})
+        patch(data, `hProperties`, {})
+        patch(data.hProperties, `style`, `position:relative;`)
+        const label = id.split(`-`).join(` `)
+        const method = isIconAfterHeader ? `push` : `unshift`
+        listItemNode.children[method]({
+          type: `link`,
+          url: `#${id}`,
+          title: null,
+          children: [],
+          data: {
+            hProperties: {
+              'aria-label': `option ${label.trim()} permalink`,
+              class: `${className} ${isIconAfterHeader ? `after` : `before`}`
+            },
+            hChildren: [
+              {
+                type: `raw`,
+                // The Octicon link icon is the default. But users can set their own icon via the "icon" option.
+                value: svgIcon
+              }
+            ]
+          }
+        })
+
+        const isSecondArgNode =
+          String(paragraphNode.children[1]?.value).trim() === ',' &&
+          paragraphNode.children[2]?.type === 'inlineCode' &&
+          String(paragraphNode.children[2].value).startsWith('-')
+        if (isSecondArgNode) {
+          const secondArgNode = paragraphNode.children[2]
+          const value = secondArgNode.value
+          const id = value.match(argsRegex)[0]
+          addIdAttrToNode(paragraphNode, id)
+        }
+      }
+    }
+  )
+  // Manipulate AST
+  return markdownAST
+}

plugins/gatsby-remark-args-linker/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "gatsby-remark-args-linker",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC"
+}

plugins/gatsby-remark-dvc-linker/commandLinker.js

@@ -5,31 +5,29 @@ const { getItemByPath } = require('../../src/utils/shared/sidebar')
 
 const DVC_REGEXP = /dvc\s+[a-z][a-z-.]*/
 const COMMAND_REGEXP = /^[a-z][a-z-]*$/
+const ARGS_REGEXP = new RegExp(/\-{1,2}[a-zA-Z-]*/, 'ig')
 const COMMAND_ROOT = '/doc/command-reference/'
 
 module.exports = astNode => {
   const node = astNode[0]
   const parent = astNode[2]
-
   if (parent.type !== 'link' && DVC_REGEXP.test(node.value)) {
     const parts = node.value.split(/\s+/)
+    const baseUrl = `${COMMAND_ROOT}${parts[1]}`
     let url
-
-    const hasThirdSegment = parts[2] && COMMAND_REGEXP.test(parts[2])
     const isCommandPageExists = getItemByPath(`${COMMAND_ROOT}${parts[1]}`)
-    const isSubcommandPageExists =
-      isCommandPageExists &&
-      hasThirdSegment &&
-      getItemByPath(`${COMMAND_ROOT}${parts[1]}/${parts[2]}`)
-
-    if (isSubcommandPageExists) {
-      url = `${COMMAND_ROOT}${parts[1]}/${parts[2]}`
-    } else if (isCommandPageExists && hasThirdSegment) {
-      url = `${COMMAND_ROOT}${parts[1]}#${parts[2]}`
-    } else if (isCommandPageExists) {
-      url = `${COMMAND_ROOT}${parts[1]}`
+    if (isCommandPageExists) {
+      url = baseUrl
+    }
+    for (const arg of parts.slice(2)) {
+      if (arg && COMMAND_REGEXP.test(arg) && getItemByPath(`${url}/${arg}`)) {
+        url = `${url}/${arg}`
+      } else if (arg && ARGS_REGEXP.test(arg)) {
+        const id = arg.match(ARGS_REGEXP)[0]
+        url = `${url}#${id}`
+        break
+      }
     }
-
     createLinkNode(url, astNode)
   }
 

src/components/Code/index.tsx

@@ -0,0 +1,78 @@
+import React from 'react'
+import cn from 'classnames'
+
+import dvc from '../../../config/prismjs/dvc-commands'
+
+const dvcRegex = new RegExp(`dvc (?:${dvc.join('|')})`, 'ig')
+const usageRegex = new RegExp(
+  `(^|\n)\s*(usage|positional arguments|optional arguments)`,
+  'ig'
+)
+const squareArgsRegex = new RegExp(
+  /(?<=\[)(?:[^\]\[]+|\[(?:[^\]\[]+|\[[^\]\[]*\])*\])*(?=\])/,
+  'ig'
+) // regex that matches a square bracketed argument that allows two levels of nested square brackets
+const argsRegex = new RegExp(/\-{1,2}[a-zA-Z-]*/, 'ig')
+
+const encodeChars = (rawText: string) => {
+  return rawText.replaceAll('<', '&lt;')
+}
+const pipe = (...args: any[]) => args.reduce((acc, el) => el(acc))
+const linkifyArgs = (args: string) => {
+  if (args.includes('|')) {
+    const argsArr = args.split('|')
+    const argsWrappedArr = argsArr.map(linkifyArg)
+    return argsWrappedArr.join('|')
+  }
+  return linkifyArg(args)
+}
+
+const linkifyArg = (arg: string) => {
+  const dashArgs = arg.match(argsRegex)
+  if (!dashArgs) return arg
+  if (dashArgs.length > 1) {
+    return linkify(arg)
+  }
+  return `<a class="token args" href='#${dashArgs[0]}'>${arg}</a>`
+}
+const linkify = (str: string) => {
+  return str.replace(argsRegex, linker)
+}
+const linker = (str: string) => {
+  return `<a class="token args" href='#${str.replaceAll(' ', '_')}'>${str}</a>`
+}
+
+const wrapUsage = (text: string) =>
+  text.replace(usageRegex, `<span class="token usage">$&</span>`)
+const wrapDvc = (text: string) =>
+  text.replace(dvcRegex, `<span class="token dvc">$&</span>`)
+const linkifyArgsSquared = (text: string) =>
+  text.replace(squareArgsRegex, linkifyArgs)
+
+export const wrapWithTags = (text: string) => {
+  text = encodeChars(text)
+  return pipe(text, wrapUsage, wrapDvc, linkifyArgsSquared)
+}
+
+const formatText = (text: string) => {
+  const wrapped = wrapWithTags(text)
+  return wrapped
+}
+
+const Code: React.FC<{ className: string }> = ({ className, children }) => {
+  if (className === 'language-usage') {
+    const codeText = Array.isArray(children)
+      ? children.join('')
+      : String(children) || ''
+    const ReactText = formatText(codeText)
+    return (
+      <code
+        className={cn(className)}
+        dangerouslySetInnerHTML={{ __html: ReactText }}
+      ></code>
+    )
+  }
+  return <code className={cn(className)}>{children}</code>
+}
+
+export default Code

src/components/Documentation/Markdown/Main/styles.module.css

@@ -70,10 +70,27 @@
       }
     }
 
+    a.token.args {
+      color: var(--color-light-blue);
+      outline-color: var(--color-light-blue-hover);
+    }
+
     :global(a.gatsby-resp-image-link)::after {
       content: unset;
     }
 
+    li .anchor svg {
+      visibility: hidden;
+    }
+
+    li:hover .anchor svg {
+      visibility: visible;
+    }
+
+    li .anchor:focus svg {
+      visibility: visible;
+    }
+
     .anchor {
       margin-left: -24px;
     }

src/components/Documentation/Markdown/index.tsx

@@ -14,6 +14,7 @@ import Collapsible from 'react-collapsible'
 
 import Main from './Main'
 import Link from '../../Link'
+import Code from '../../Code'
 import Tooltip from './Tooltip'
 
 import * as styles from './styles.module.css'
@@ -204,7 +205,8 @@ const renderAst = new (rehypeReact as any)({
     cards: Cards,
     details: Details,
     toggle: Toggle,
-    tab: Tab
+    tab: Tab,
+    code: Code
   }
 }).Compiler
 

tsconfig.json

@@ -3,7 +3,7 @@
     "target": "es5",
     "module": "commonjs",
     "resolveJsonModule": true,
-    "lib": ["dom", "es2015", "es2017"],
+    "lib": ["dom", "es2015", "es2017", "es2021"],
     "jsx": "react",
     "sourceMap": true,
     "strict": true,