@primer/doctocat-nextjs 0.5.2 → 0.5.3-rc.1ab2f8f

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/article/Article.module.css

@@ -1,42 +1,38 @@
 .Article {
   display: grid;
+  grid-template-areas: 'main';
+  grid-template-columns: 1fr;
 }
 
 .Article--withToc {
   gap: var(--base-size-48);
+  grid-template-areas: 'main aside';
+  grid-template-columns: 1fr 200px;
 }
 
 .main {
-  order: 1;
+  grid-area: main;
+  max-width: 100%;
+  overflow-x: hidden;
 }
 
 .aside {
-  order: 0;
+  grid-area: aside;
+  position: relative;
 }
 
-@media screen and (max-width: 48rem) {
+@media screen and (max-width: 1023px) {
   .Article--withToc {
-    display: flex; /* Prevents column overflow */
-    flex-direction: column;
-  }
-}
-
-@media screen and (min-width: 1023px) {
-  .main {
-    order: 0;
-  }
-
-  .aside {
-    order: 1;
-  }
-
-  .Article--withToc {
-    grid-template-columns: 1fr 200px;
+    grid-template-areas:
+      'aside'
+      'main';
+    grid-template-columns: 1fr;
   }
 }
 
 @media screen and (min-width: 2048px) {
   .Article--withToc {
+    grid-template-areas: 'main';
     grid-template-columns: 1fr;
   }
 }

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,21 @@ export function IndexCards({route, folderData}: IndexCardsProps) {
 
         const thumbnailUrl =
           colorMode === 'dark'
-            ? item.frontMatter.thumbnail_darkMode || getNextPlaceholderIndex(darkModePlaceholderThumbs).src
-            : item.frontMatter.thumbnail || getNextPlaceholderIndex(lightModePlaceholderThumbs).src
+            ? (item.frontMatter.thumbnail_darkMode
+                ? `${basePath || ''}${item.frontMatter.thumbnail_darkMode}`
+                : null) || getNextPlaceholderIndex(darkModePlaceholderThumbs).src
+            : (item.frontMatter.thumbnail ? `${basePath || ''}${item.frontMatter.thumbnail}` : null) ||
+              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 fullWidth>
+                <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/components/layout/table-of-contents/TableOfContents.module.css

@@ -26,7 +26,6 @@
     display: flex;
     flex-direction: column;
     min-width: 280px;
-    right: 0;
     overflow: auto;
     padding: var(--base-size-40) var(--base-size-40) var(--base-size-40) 0;
     top: 65px;

package/css/global.css

@@ -18,7 +18,8 @@ body {
   margin-block-start: 0 !important;
 }
 
-pre {
+/* Pre styles are scoped to Nextra code blocks to prevent unintended styling of other code blocks (e.g., ReactCodeBlock previews). */
+.nextra-code pre {
   background-color: var(--brand-color-canvas-subtle);
   border-radius: var(--brand-borderRadius-large);
   padding-top: 1rem;

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.1ab2f8f",
   "description": "A Next.js theme for building Primer documentation sites",
   "main": "index.js",
   "type": "module",