Fix basePath issues in Doctocat UI components (#46)

* prepend basePath to index card hrefs

* fix basePath resolution inside Doctocat UI

* remove filtered element and apply to all elements with src

* apply index card basePaths only to frontmatter, not default placeholder ones that are impoted through webpack instead

Author: rezrah

.changeset/warm-teachers-repeat.md

@@ -0,0 +1,5 @@
+---
+'@primer/doctocat-nextjs': patch
+---
+
+Prepend `basePath` from `next.config.js` to paths in Doctocat UI components, where it would previously not resolve correctly.

packages/site/content/content-example/tabbed-component/react.mdx

@@ -98,6 +98,15 @@ You can place an icon inside the Button in either the leading or the trailing po
 </AnimationProvider>
 ```
 
+### Images
+
+```
+<>
+  <img src="/images/avatar-mona.png" />
+  <Avatar src="/images/avatar-mona.png" />
+</>
+```
+
 ### Polymorphism
 
 The `Button` component can render as a `button` or `a` HTML element. By default, it will render as a `button`.

packages/site/public/images/avatar-mona.png

@@ -10,6 +10,7 @@ export type ConfigContextLink = {
 export type ConfigContextValue = {
   headerLinks: ConfigContextLink[]
   sidebarLinks: ConfigContextLink[]
+  basePath: string
 }
 
 export const ConfigContext = createContext<ConfigContextValue | null>(null)

packages/theme/components/context/useConfig.tsx

@@ -3,12 +3,14 @@ import React, {PropsWithChildren, useCallback, useState} from 'react'
 import clsx from 'clsx'
 import {LiveProvider, LiveEditor, LiveError, LivePreview} from 'react-live'
 import {useColorMode} from '../../context/color-modes/useColorMode'
+import {useConfig} from '../../context/useConfig'
 import styles from './ReactCodeBlock.module.css'
 import {ActionBar, Button, ThemeProvider} from '@primer/react'
 import {CopyIcon, MoonIcon, SunIcon, UndoIcon} from '@primer/octicons-react'
 import {colorModes} from '../../context/color-modes/context'
 
 import {lightTheme, darkTheme} from './syntax-highlighting-themes'
+import {codeTransformer} from './code-transformer'
 
 type ReactCodeBlockProps = {
   'data-language': string
@@ -18,10 +20,19 @@ type ReactCodeBlockProps = {
 
 export function ReactCodeBlock(props: ReactCodeBlockProps) {
   const {colorMode, setColorMode} = useColorMode()
+  const {basePath} = useConfig()
   const initialCode = getCodeFromChildren(props.children)
   const [code, setCode] = useState(initialCode)
   const shouldShowPreview = ['tsx', 'jsx'].includes(props['data-language'])
 
+  /**
+   * Transforms code to prepend basePath to img src attributes
+   */
+  const transformCodeWithBasePath = useCallback(
+    (sourceCode: string) => codeTransformer(sourceCode, basePath),
+    [basePath],
+  )
+
   const handleReset = useCallback(() => {
     setCode(initialCode)
   }, [initialCode, setCode])
@@ -34,7 +45,7 @@ export function ReactCodeBlock(props: ReactCodeBlockProps) {
 
   return (
     <>
-      <LiveProvider code={code} scope={props.jsxScope} noInline={noInline}>
+      <LiveProvider transformCode={transformCodeWithBasePath} code={code} scope={props.jsxScope} noInline={noInline}>
         <div className={clsx(styles.CodeBlock, 'custom-component')}>
           {shouldShowPreview && (
             <div>

packages/theme/components/layout/code-block/ReactCodeBlock.tsx

@@ -0,0 +1,19 @@
+export const codeTransformer = (sourceCode: string, basePath: string): string => {
+  if (!basePath) return sourceCode
+
+  // to skip external URLs and other irrelevant paths
+  const shouldTransform = (src: string) => !src.startsWith('http') && !src.startsWith('//') && !src.startsWith(basePath)
+
+  // normalise for absolute (/path) and relative (path) values
+  const transformSrc = (src: string) => (src.startsWith('/') ? `${basePath}${src}` : `${basePath}/${src}`)
+
+  // Assumes all elements with a src attribute are trying to point at Next.js public folder
+  return sourceCode.replace(
+    /<(\w+)\s+([^>]*\s+)?src=["']([^"']+)["']([^>]*)/g,
+    (match, tagName, before = '', src, after) => {
+      if (!shouldTransform(src)) return match
+
+      return `<${tagName} ${before}src="${transformSrc(src)}"${after}`
+    },
+  )
+}

packages/theme/components/layout/code-block/code-transformer.ts

@@ -18,6 +18,7 @@ import placeholderLightFiveThumb from './images/light-5.png'
 import placeholderLightSixThumb from './images/light-6.png'
 
 import styles from './IndexCards.module.css'
+import {useConfig} from '../../context/useConfig'
 
 type IndexCardsProps = {
   route: string
@@ -43,6 +44,7 @@ const lightModePlaceholderThumbs = [
 ] as unknown as StaticImageData[]
 
 export function IndexCards({route, folderData}: IndexCardsProps) {
+  const {basePath} = useConfig()
   const lastPlaceholderIndexRef = useRef<number>(-1)
   // We don't want to show children of these pages. E.g. tabbed pages
   const onlyDirectChildren = folderData.filter(item => {
@@ -86,8 +88,10 @@ export function IndexCards({route, folderData}: IndexCardsProps) {
 
         const thumbnailUrl =
           colorMode === 'dark'
-            ? item.frontMatter.thumbnail_darkMode || getNextPlaceholderIndex(darkModePlaceholderThumbs).src
-            : item.frontMatter.thumbnail || getNextPlaceholderIndex(lightModePlaceholderThumbs).src
+            ? `${basePath ? basePath : ''}${item.frontMatter.thumbnail_darkMode}` ||
+              getNextPlaceholderIndex(darkModePlaceholderThumbs).src
+            : `${basePath ? basePath : ''}${item.frontMatter.thumbnail}` ||
+              getNextPlaceholderIndex(lightModePlaceholderThumbs).src
 
         return (
           <Grid.Column span={{xsmall: 12, small: 12, medium: 12, large: 6, xlarge: 4}} key={item.frontMatter.title}>

packages/theme/components/layout/index-cards/IndexCards.tsx

@@ -25,6 +25,7 @@ export default function Shell({children, headerLinks = [], sidebarLinks = [], ..
         value={{
           headerLinks,
           sidebarLinks,
+          basePath: process.env.NEXT_PUBLIC_DOCTOCAT_BASE_PATH || '',
         }}
       >
         <Theme {...rest}>{children}</Theme>

packages/theme/components/layout/root-layout/index.tsx

@@ -10,14 +10,21 @@ const withNextra = nextra({
  * Relies on `transpilePackages: ['@primer/doctocat-nextjs'],` being set in the next.config
  */
 function withDoctocat(config = {}) {
-  return {
+  const finalConfig = {
     ...withNextra(),
     images: {
       unoptimized: true,
     },
 
     ...config,
   }
+
+  // Enables basePath in next.config.js to be used inside Doctocat
+  if (finalConfig.basePath) {
+    process.env.NEXT_PUBLIC_DOCTOCAT_BASE_PATH = finalConfig.basePath
+  }
+
+  return finalConfig
 }
 
 export default withDoctocat