Added custom code based slugger for making <details> blocks linkable

content/docs/start/data-and-model-versioning.md

@@ -145,7 +145,7 @@ $ dvc push
 Usually, we also want to `git commit` and `git push` the corresponding `.dvc`
 files.
 
-<details>
+<details code="storing and sharing" position="start">
 
 ### 💡 Expand to see what happens under the hood.
 

package.json

@@ -100,6 +100,7 @@
     "@babel/core": "^7.16.0",
     "@svgr/webpack": "^6.0.0",
     "@types/classnames": "^2.2.10",
+    "@types/github-slugger": "^1.3.0",
     "@types/isomorphic-fetch": "^0.0.35",
     "@types/promise-polyfill": "^6.0.3",
     "@types/react": "^17.0.37",

plugins/gatsby-theme-iterative-docs/src/components/Documentation/Markdown/Main/styles.module.css

@@ -79,22 +79,29 @@
       content: unset;
     }
 
-    li .anchor svg {
+    li,
+    .collapsableDiv .anchor svg {
       visibility: hidden;
     }
 
-    li:hover .anchor svg {
+    li,
+    .collapsableDiv:hover .anchor svg {
       visibility: visible;
     }
 
-    li .anchor:focus svg {
+    li,
+    .collapsableDiv .anchor:focus svg {
       visibility: visible;
     }
 
     li .anchor {
       line-height: unset;
     }
 
+    .collapsableDiv .anchor {
+      line-height: 2.5;
+    }
+
     .anchor {
       margin-left: -24px;
     }

plugins/gatsby-theme-iterative-docs/src/components/Documentation/Markdown/index.tsx

@@ -4,7 +4,8 @@ import React, {
   useRef,
   ReactNode,
   ReactElement,
-  useContext
+  useContext,
+  useMemo
 } from 'react'
 import cn from 'classnames'
 import { nanoid } from 'nanoid'
@@ -18,8 +19,19 @@ import Tooltip from './Tooltip'
 
 import * as styles from './styles.module.css'
 import { TogglesContext, TogglesProvider } from './ToggleProvider'
+import { linkIcon } from '../../../../../../static/icons'
+import { useLocation } from '@reach/router'
+
+import Slugger from '../../../utils/front/Slugger'
+
+const Details: React.FC<{
+  slugger: Slugger
+  code: string
+  position: string
+}> = ({ slugger, children, code, position }) => {
+  const [isOpen, setIsOpen] = useState(false)
+  const location = useLocation()
 
-const Details: React.FC<Record<string, never>> = ({ children }) => {
   const filteredChildren: ReactNode[] = (
     children as Array<{ props: { children: ReactNode } } | string>
   ).filter(child => child !== '\n')
@@ -38,18 +50,43 @@ const Details: React.FC<Record<string, never>> = ({ children }) => {
     0,
     firstChild.props.children.length - 1
   ) as ReactNode[]
+  const titleString = triggerChildren.toString()
+  const slug = useMemo(
+    () => slugger.slug(titleString, code, position),
+    [titleString]
+  )
+  const id = slug
+  useEffect(() => {
+    if (location.hash === `#${id}`) {
+      setIsOpen(true)
+    }
+
+    return () => {
+      setIsOpen(false)
+    }
+  }, [location.hash])
 
   /*
      Collapsible's trigger type wants ReactElement, so we force a TS cast from
      ReactNode here.
    */
   return (
-    <Collapsible
-      trigger={triggerChildren as unknown as ReactElement}
-      transitionTime={200}
-    >
-      {filteredChildren.slice(1)}
-    </Collapsible>
+    <div id={id} className="collapsableDiv">
+      <Link
+        href={`#${id}`}
+        aria-label={triggerChildren.toString()}
+        className="anchor after"
+      >
+        <span dangerouslySetInnerHTML={{ __html: linkIcon }}></span>
+      </Link>
+      <Collapsible
+        open={isOpen}
+        trigger={triggerChildren as unknown as ReactElement}
+        transitionTime={200}
+      >
+        {filteredChildren.slice(1)}
+      </Collapsible>
+    </div>
   )
 }
 
@@ -195,22 +232,27 @@ const Toggle: React.FC<{
     </div>
   )
 }
+const Tab: React.FC = ({ children }) => {
+  return <React.Fragment>{children}</React.Fragment>
+}
 
 // Rehype's typedefs don't allow for custom components, even though they work
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-const renderAst = new (rehypeReact as any)({
-  createElement: React.createElement,
-  Fragment: React.Fragment,
-  components: {
-    a: Link,
-    abbr: Abbr,
-    card: Card,
-    cards: Cards,
-    details: Details,
-    toggle: Toggle,
-    tab: React.Fragment
-  }
-}).Compiler
+const renderAst = (slugger: Slugger) => {
+  return new (rehypeReact as any)({
+    createElement: React.createElement,
+    Fragment: React.Fragment,
+    components: {
+      a: Link,
+      abbr: Abbr,
+      card: Card,
+      cards: Cards,
+      details: (props: any) => <Details slugger={slugger} {...props} />,
+      toggle: Toggle,
+      tab: Tab
+    }
+  }).Compiler
+}
 
 interface IMarkdownProps {
   htmlAst: Node
@@ -227,9 +269,10 @@ const Markdown: React.FC<IMarkdownProps> = ({
   tutorials,
   githubLink
 }) => {
+  const slugger = new Slugger({ lowercase: false })
   return (
     <Main prev={prev} next={next} tutorials={tutorials} githubLink={githubLink}>
-      <TogglesProvider>{renderAst(htmlAst)}</TogglesProvider>
+      <TogglesProvider>{renderAst(slugger)(htmlAst)}</TogglesProvider>
     </Main>
   )
 }

plugins/gatsby-theme-iterative-docs/src/utils/front/Slugger.ts

@@ -0,0 +1,49 @@
+class Slugger {
+  separator: string
+  lowercase: boolean
+  codePosition: string
+  slugs: Array<string>
+
+  constructor(options?: {
+    separator?: string
+    lowercase?: boolean
+    codePosition?: string
+  }) {
+    this.separator = options?.separator || '-'
+    this.lowercase = Boolean(options?.lowercase) && true
+    this.codePosition = options?.codePosition || 'end'
+    this.slugs = []
+  }
+
+  slug(str: string, code?: string, position = this.codePosition) {
+    str = typeof str === 'string' ? str : ''
+    let slug = this.slugify(str)
+
+    if (this.lowercase) {
+      slug = slug.toLowerCase()
+    }
+    if (code) {
+      const codeSlug = this.slugify(code)
+      slug =
+        position === 'start'
+          ? `${codeSlug}${this.separator}${slug}`
+          : `${slug}${this.separator}${codeSlug}`
+    }
+    if (this.slugs.includes(slug)) {
+      throw new Error(`Duplicate slug: ${slug} for title:${str}`)
+    }
+    this.slugs.push(slug)
+    return slug
+  }
+  slugify = (str: string) => {
+    return str
+      .replace(/[^\w\s-]/g, '')
+      .trim()
+      .replace(/[-\s]+/g, this.separator)
+      .replace(this.separator + this.separator, this.separator)
+  }
+  reset() {
+    this.slugs = []
+  }
+}
+export default Slugger

yarn.lock

@@ -3386,6 +3386,11 @@
   resolved "https://registry.npmjs.org/@types/get-port/-/get-port-3.2.0.tgz"
   integrity sha512-TiNg8R1kjDde5Pub9F9vCwZA/BNW9HeXP5b9j7Qucqncy/McfPZ6xze/EyBdXS5FhMIGN6Fx3vg75l5KHy3V1Q==
 
+"@types/github-slugger@^1.3.0":
+  version "1.3.0"
+  resolved "https://registry.yarnpkg.com/@types/github-slugger/-/github-slugger-1.3.0.tgz#16ab393b30d8ae2a111ac748a015ac05a1fc5524"
+  integrity sha512-J/rMZa7RqiH/rT29TEVZO4nBoDP9XJOjnbbIofg7GQKs4JIduEO3WLpte+6WeUz/TcrXKlY+bM7FYrp8yFB+3g==
+
 "@types/glob@*", "@types/glob@^7.1.1":
   version "7.1.4"
   resolved "https://registry.npmjs.org/@types/glob/-/glob-7.1.4.tgz"