@primer/doctocat-nextjs 0.0.0-20250619155353 → 0.0.0-20250620095814

package/CHANGELOG.md

@@ -1,16 +1,18 @@
 # @primer/doctocat-nextjs
 
-## 0.0.0-20250619155353
+## 0.0.0-20250620095814
 
 ### Patch Changes
 
 - Fake entry to force publishing
 
-## 0.0.0-20250619155352
+## 0.0.0-20250620095812
 
 ### 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`.
+- [#43](https://github.com/primer/doctocat-nextjs/pull/43) [`c5542e9`](https://github.com/primer/doctocat-nextjs/commit/c5542e915dc0fbe6e054e8fde96f7136498b9cc7) 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) [`fea58bc`](https://github.com/primer/doctocat-nextjs/commit/fea58bc04c1cfb4897ef8f5921dbc9afd5b18dc8) 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
 

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,38 +1,42 @@
 .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 {
-  grid-area: main;
-  max-width: 100%;
-  overflow-x: hidden;
+  order: 1;
 }
 
 .aside {
-  grid-area: aside;
-  position: relative;
+  order: 0;
 }
 
-@media screen and (max-width: 1023px) {
+@media screen and (max-width: 48rem) {
   .Article--withToc {
-    grid-template-areas:
-      'aside'
-      'main';
-    grid-template-columns: 1fr;
+    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;
   }
 }
 
 @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

@@ -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 => {
@@ -92,8 +94,8 @@ export function IndexCards({route, folderData}: IndexCardsProps) {
         return (
           <Grid.Column span={{xsmall: 12, small: 12, medium: 12, large: 6, xlarge: 4}} key={item.frontMatter.title}>
             <Link legacyBehavior passHref href={item.route}>
-              <Card href="#" hasBorder fullWidth>
-                <Card.Image src={thumbnailUrl} alt="" aspectRatio="4:3" />
+              <Card href="#" hasBorder>
+                <Card.Image src={`${basePath ? basePath : ''}${thumbnailUrl}`} alt="" aspectRatio="4:3" />
                 <Card.Heading>{item.frontMatter.title}</Card.Heading>
                 {item.frontMatter.description && <Card.Description>{item.frontMatter.description}</Card.Description>}
               </Card>

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,6 +26,7 @@
     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,8 +18,7 @@ body {
   margin-block-start: 0 !important;
 }
 
-/* Pre styles are scoped to Nextra code blocks to prevent unintended styling of other code blocks (e.g., ReactCodeBlock previews). */
-.nextra-code pre {
+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.0.0-20250619155353",
+  "version": "0.0.0-20250620095814",
   "description": "A Next.js theme for building Primer documentation sites",
   "main": "index.js",
   "type": "module",