@primer/doctocat-nextjs 0.5.2 → 0.5.3-rc.796691c

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @primer/doctocat-nextjs
 
+## 0.5.3
+
+### Patch Changes
+
+- [#43](https://github.com/primer/doctocat-nextjs/pull/43) [`1b15bdf`](https://github.com/primer/doctocat-nextjs/commit/1b15bdfcf4b54996f38d20f1da711def23c636bd) Thanks [@rezrah](https://github.com/rezrah)! - Fix lack of `basePath` support on index cards. `href` now prepends the `basePath`.
+
+- [#46](https://github.com/primer/doctocat-nextjs/pull/46) [`2b99ba6`](https://github.com/primer/doctocat-nextjs/commit/2b99ba614d1bfe8f1c478b10a61c52df479901c9) Thanks [@rezrah](https://github.com/rezrah)! - Prepend `basePath` from `next.config.js` to paths in Doctocat UI components, where it would previously not resolve correctly.
+
 ## 0.5.2
 
 ### Patch Changes

package/components/context/useConfig.tsx

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

package/components/layout/code-block/ReactCodeBlock.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>

package/components/layout/code-block/code-transformer.ts

@@ -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}`
+    },
+  )
+}

package/components/layout/index-cards/IndexCards.tsx

@@ -3,6 +3,7 @@ import {Card, Grid} from '@primer/react-brand'
 import {DocsItem} from '../../../types'
 import {useColorMode} from '../../context/color-modes/useColorMode'
 import type {StaticImageData} from 'next/image'
+import Link from 'next/link'
 import placeholderDarkOneThumb from './images/dark-1.png'
 import placeholderDarkTwoThumb from './images/dark-2.png'
 import placeholderDarkThreeThumb from './images/dark-3.png'
@@ -17,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
@@ -42,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 => {
@@ -85,16 +88,20 @@ 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}>
-            <Card href={item.route} hasBorder>
-              <Card.Image src={thumbnailUrl} alt="" aspectRatio="4:3" />
-              <Card.Heading>{item.frontMatter.title}</Card.Heading>
-              {item.frontMatter.description && <Card.Description>{item.frontMatter.description}</Card.Description>}
-            </Card>
+            <Link legacyBehavior passHref href={item.route}>
+              <Card href="#" hasBorder>
+                <Card.Image src={thumbnailUrl} alt="" aspectRatio="4:3" />
+                <Card.Heading>{item.frontMatter.title}</Card.Heading>
+                {item.frontMatter.description && <Card.Description>{item.frontMatter.description}</Card.Description>}
+              </Card>
+            </Link>
           </Grid.Column>
         )
       })}

package/components/layout/root-layout/index.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>

package/doctocat.config.js

@@ -10,7 +10,7 @@ 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,
@@ -18,6 +18,13 @@ function withDoctocat(config = {}) {
 
     ...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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primer/doctocat-nextjs",
-  "version": "0.5.2",
+  "version": "0.5.3-rc.796691c",
   "description": "A Next.js theme for building Primer documentation sites",
   "main": "index.js",
   "type": "module",