Move Documentation components to theme (#3170)

* Move sidebar logic to theme

* Split sidebar normalization and utils and import via shadowing

* Fix usage of findChildWithSource

* Fix lint-ts errors

* Move comment normalized item definition to d.ts

* Update and export INormalizedSidebarItem and use it in SidebarMenu

* Add suppressable default gatsby-transformer-remark definition

* Remove resolve-sidebar since local remark plugins are dvc.org only

* Remove resolve-sidebar since local remark plugins are dvc.org only

* Return src/components to master

* Add alias for local theme

* Roughly move doc components to theme

* Revert to master package.json

* Remove unused normalize sidebar module

* Re-fix package.json and change test imports

* stylelint --fix

* Move Page and DocumentationLayout from theme to site

* Fix svg imports

* Remove unused layout components

* stylelint fix

* Extract github link function and repo constant to more easily overridable files

* Remove unnecessary shadowed files since webpack override is in place

* Remove unused constants file

* Revert "Remove unused constants file"

This reverts commit b07ca1b.

* Remove actual unused constants file

* Use theme-based Link component

* Move core part of Documentation layout into theme

* Rename sidebar test block to something more descriptive of its contents

* Break apart docs sidebar and move it into theme

* Add missing import

gatsby-config.js

@@ -37,7 +37,12 @@ const plugins = [
   'gatsby-plugin-react-helmet',
   'gatsby-plugin-sitemap',
   'gatsby-plugin-twitter',
-  'gatsby-theme-iterative-docs',
+  {
+    resolve: 'gatsby-theme-iterative-docs',
+    options: {
+      remark: false
+    }
+  },
   {
     resolve: 'gatsby-source-filesystem',
     options: {

gatsby-node.js

@@ -1,4 +1,5 @@
 require('dotenv').config()
+const path = require('path')
 global.__basedir = __dirname
 
 const { setPageContext } = require('./src/gatsby/common')
@@ -40,4 +41,14 @@ exports.onCreateWebpackConfig = ({ stage, actions, getConfig }) => {
     }
     actions.replaceWebpackConfig(config)
   }
+  actions.setWebpackConfig({
+    resolve: {
+      alias: {
+        'gatsby-theme-iterative-docs': path.resolve(
+          'plugins',
+          'gatsby-theme-iterative-docs'
+        )
+      }
+    }
+  })
 }

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

@@ -1,7 +1,9 @@
 /* eslint-env node */
 
 const { createLinkNode } = require('./helpers')
-const { getItemByPath } = require('../../src/utils/shared/sidebar')
+const {
+  getItemByPath
+} = require('../../plugins/gatsby-theme-iterative-docs/src/utils/shared/sidebar')
 
 const DVC_API_REGEXP = /dvc.api([a-z-._]*\(\)$)?/
 const METHOD_REGEXP = /^[a-z-._]*\(\)$/

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

@@ -1,7 +1,9 @@
 /* eslint-env node */
 
 const { createLinkNode } = require('./helpers')
-const { getItemByPath } = require('../../src/utils/shared/sidebar')
+const {
+  getItemByPath
+} = require('../../plugins/gatsby-theme-iterative-docs/src/utils/shared/sidebar')
 
 const DVC_REGEXP = /dvc\s+[a-z][a-z-.]*/
 const COMMAND_REGEXP = /^[a-z][a-z-]*$/

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

@@ -1,7 +1,9 @@
 /* eslint-env node */
 
 const { createLinkNode } = require('./helpers')
-const { getItemByPath } = require('../../src/utils/shared/sidebar')
+const {
+  getItemByPath
+} = require('../../plugins/gatsby-theme-iterative-docs/src/utils/shared/sidebar')
 
 const LIVE_API_REGEXP = /Live.([a-z-._]*\(\)$)?/
 const METHOD_REGEXP = /^[a-z-._]*\(\)$/

plugins/gatsby-theme-iterative-docs/gatsby-config.js

@@ -0,0 +1,57 @@
+module.exports = ({ remark }) => {
+  const plugins = []
+  if (remark) {
+    plugins.push({
+      resolve: 'gatsby-transformer-remark',
+      options: {
+        plugins: [
+          'gatsby-remark-embedder',
+          {
+            resolve: 'gatsby-remark-prismjs',
+            options: {
+              noInlineHighlight: true,
+              languageExtensions: [
+                {
+                  language: 'text',
+                  definition: {}
+                }
+              ]
+            }
+          },
+          {
+            resolve: 'gatsby-remark-smartypants',
+            options: {
+              quotes: false
+            }
+          },
+          {
+            resolve: 'gatsby-remark-embed-gist',
+            options: {
+              includeDefaultCss: true
+            }
+          },
+          'gatsby-remark-relative-images',
+          'gatsby-remark-copy-linked-files',
+          'gatsby-remark-external-links',
+          {
+            resolve: 'gatsby-remark-autolink-headers',
+            options: {
+              enableCustomId: true,
+              isIconAfterHeader: true
+            }
+          },
+          {
+            resolve: 'gatsby-remark-images',
+            options: {
+              withWebp: true
+            }
+          },
+          'gatsby-remark-responsive-iframe'
+        ]
+      }
+    })
+  }
+  return {
+    plugins
+  }
+}

plugins/gatsby-theme-iterative-docs/gatsby-node.js

@@ -10,8 +10,9 @@ exports.pluginOptionsSchema = ({ Joi }) => {
     disable: Joi.boolean().default(Boolean(process.env.SKIP_DOCS)),
     getTemplate: Joi.function().default(() => defaultGetTemplate),
     defaultTemplate: Joi.string().default(
-      path.resolve('src', 'templates', 'doc.tsx')
-    )
+      require.resolve('./src/templates/doc.tsx')
+    ),
+    remark: Joi.boolean().default(true)
   })
 }
 
@@ -33,6 +34,25 @@ exports.createSchemaCustomization = async api => {
   ])
 }
 
+exports.onCreateWebpackConfig = ({ actions }) => {
+  actions.setWebpackConfig({
+    resolve: {
+      alias: {
+        [path.resolve(__dirname, 'sidebar')]: path.resolve(
+          'src',
+          'gatsby-theme-iterative-docs',
+          'sidebar'
+        ),
+        [path.resolve(__dirname, 'redirects')]: path.resolve(
+          'src',
+          'gatsby-theme-iterative-docs',
+          'redirects'
+        )
+      }
+    }
+  })
+}
+
 exports.createPages = require('./createPages.js')
 
 exports.onCreateNode = require('./onCreateNode.js')

plugins/gatsby-theme-iterative-docs/index.js

@@ -0,0 +1 @@
+// noop

plugins/gatsby-theme-iterative-docs/pseudo-shadow.js

@@ -0,0 +1,3 @@
+const path = require('path')
+const pseudoShadow = modulePath => require(path.resolve(modulePath))
+module.exports = pseudoShadow

plugins/gatsby-theme-iterative-docs/redirects.js

@@ -0,0 +1,2 @@
+const pseudoShadow = require('./pseudo-shadow')
+module.exports = pseudoShadow('./src/gatsby-theme-iterative-docs/redirects')

plugins/gatsby-theme-iterative-docs/sidebar.js

@@ -0,0 +1,2 @@
+const pseudoShadow = require('./pseudo-shadow')
+module.exports = pseudoShadow('./src/gatsby-theme-iterative-docs/sidebar')

src/components/Documentation/Layout/SearchForm/index.tsx → plugins/gatsby-theme-iterative-docs/src/components/Documentation/Layout/SearchForm/index.tsx

@@ -1,6 +1,6 @@
 import React, { useEffect, useState } from 'react'
 import Promise from 'promise-polyfill'
-import { loadResource } from '../../../../utils/front/resources'
+import { loadResource } from 'gatsby-theme-iterative-docs/src/utils/front/resources'
 
 import * as styles from './styles.module.css'
 

plugins/gatsby-theme-iterative-docs/src/components/Documentation/Layout/SidebarMenu/InnerSidebar/index.tsx

@@ -0,0 +1,35 @@
+import React from 'react'
+import includes from 'lodash/includes'
+import * as styles from '../styles.module.css'
+import { structure } from '../../../../../utils/shared/sidebar'
+import SidebarMenuItem from '../Item'
+import { SidebarItemClickHandler } from '..'
+
+export interface IInnerSidebarProps {
+  activePaths: string[]
+  onClick: SidebarItemClickHandler
+}
+
+const SidebarSections: React.FC<IInnerSidebarProps> = ({
+  activePaths,
+  onClick
+}) => {
+  return (
+    <div className={styles.sections}>
+      <div className={styles.sectionLinks}>
+        {structure.map(item => (
+          <SidebarMenuItem
+            key={item.path}
+            activePaths={
+              includes(activePaths, item.path) ? activePaths : undefined
+            }
+            onClick={onClick}
+            {...item}
+          />
+        ))}
+      </div>
+    </div>
+  )
+}
+
+export default SidebarSections

src/components/Documentation/Layout/SidebarMenu/index.tsx → plugins/gatsby-theme-iterative-docs/src/components/Documentation/Layout/SidebarMenu/Item/index.tsx

@@ -1,34 +1,14 @@
-import React, { useEffect, useRef, useState, SyntheticEvent } from 'react'
-import { useLocation } from '@reach/router'
-import cn from 'classnames'
+import React, { SyntheticEvent, useEffect, useState } from 'react'
 import { Collapse } from 'react-collapse'
-import PerfectScrollbar from 'perfect-scrollbar'
+import cn from 'classnames'
 import includes from 'lodash/includes'
 
-import ShowOnly from '../../../ShowOnly'
-import DownloadButton from '../../../DownloadButton'
-import Link from '../../../Link'
+import Link from '../../../../Link'
 import { ReactComponent as ExternalLinkIcon } from './external-link-icon.svg'
-import { ReactComponent as HouseIcon } from './house.svg'
-import { ReactComponent as CMLIcon } from './cml_bw_logo.svg'
-import { ReactComponent as StudioIcon } from './studio_gray_icon.svg'
-
-import {
-  structure,
-  getParentsListFromPath,
-  getPathWithSource
-} from '../../../../utils/shared/sidebar'
-
-import 'perfect-scrollbar/css/perfect-scrollbar.css'
-import * as styles from './styles.module.css'
-
-// A map for optional special icons that can be used in menu items
-// Use the key string here as the "icon" field in sidebar.json
-const ICONS: { [key: string]: React.FC<{ className?: string }> } = {
-  house: HouseIcon,
-  cml: CMLIcon,
-  studio: StudioIcon
-}
+import * as styles from '../styles.module.css'
+
+import ICONS from '../icons'
+import { getPathWithSource } from '../../../../../utils/shared/sidebar'
 
 interface ISidebarMenuItemProps {
   children?: Array<{ label: string; path: string; source: boolean | string }>
@@ -160,87 +140,4 @@ const SidebarMenuItem: React.FC<ISidebarMenuItemProps> = ({
   )
 }
 
-interface ISidebarMenuProps {
-  currentPath: string
-  onClick: (isLeafItemClicked: boolean) => void
-}
-
-const SidebarMenu: React.FC<ISidebarMenuProps> = ({ currentPath, onClick }) => {
-  const location = useLocation()
-  const rootRef = useRef<HTMLDivElement>(null)
-  const psRef = useRef<PerfectScrollbar | undefined>(undefined)
-  const [isScrollHidden, setIsScrollHidden] = useState(false)
-  const activePaths = currentPath && getParentsListFromPath(currentPath)
-
-  const scrollToActiveItem = (): void => {
-    const node = document.getElementById(currentPath)
-    const parent = rootRef.current
-
-    setIsScrollHidden(true)
-    setTimeout(() => {
-      if (node && parent) {
-        psRef.current?.update()
-
-        const parentHeight = parent.clientHeight
-        const parentScroll = parent.scrollTop
-        const nodeOffset = node.offsetTop
-        const nodeHeight = node.clientHeight
-        const scrollOffset = nodeOffset - parentHeight + nodeHeight
-
-        if (
-          parentScroll > nodeOffset + nodeHeight ||
-          parentScroll + parentHeight < nodeOffset
-        ) {
-          parent.scrollTop = scrollOffset
-        }
-      }
-
-      setIsScrollHidden(false)
-    }, 400)
-  }
-
-  useEffect(() => {
-    if (!psRef.current && rootRef.current) {
-      psRef.current = new PerfectScrollbar(rootRef.current, {
-        wheelPropagation: true
-      })
-    }
-
-    scrollToActiveItem()
-
-    return (): void => {
-      psRef.current?.destroy()
-      psRef.current = undefined
-    }
-  }, [])
-  useEffect(scrollToActiveItem, [location.pathname])
-
-  return (
-    <div
-      className={cn(styles.menu, isScrollHidden && styles.isScrollHidden)}
-      ref={rootRef}
-    >
-      <div className={styles.sections}>
-        <div className={styles.sectionLinks}>
-          {structure.map(item => (
-            <SidebarMenuItem
-              key={item.path}
-              activePaths={
-                includes(activePaths, item.path) ? activePaths : undefined
-              }
-              onClick={onClick}
-              {...item}
-            />
-          ))}
-        </div>
-      </div>
-      <ShowOnly on="desktop">
-        <div className={styles.footer}>
-          <DownloadButton openTop />
-        </div>
-      </ShowOnly>
-    </div>
-  )
-}
-
-export default SidebarMenu
+export default SidebarMenuItem

plugins/gatsby-theme-iterative-docs/src/components/Documentation/Layout/SidebarMenu/icons/index.ts

@@ -0,0 +1,9 @@
+import { ReactComponent as HouseIcon } from './house.svg'
+
+export type SidebarIcons = { [key: string]: React.FC<{ className?: string }> }
+
+const ICONS: SidebarIcons = {
+  house: HouseIcon
+}
+
+export default ICONS