@primer/doctocat-nextjs 0.0.4 → 0.1.0

package/{.eslintrc.js → .eslintrc.cjs}

@@ -1,7 +1,8 @@
-const base = require('../../.eslintrc')
+const base = require('../../.eslintrc.cjs')
 
 module.exports = {
   ...base,
+  plugins: ['react-hooks'],
   parserOptions: {
     tsconfigRootDir: __dirname,
   },

package/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "eslint.options": {
+    "configFile": ".eslintrc.cjs"
+  }
+}

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @primer/doctocat-nextjs
 
+## 0.1.0
+
+### Minor Changes
+
+- [#18](https://github.com/primer/doctocat-nextjs/pull/18) [`bfe68b1`](https://github.com/primer/doctocat-nextjs/commit/bfe68b14e8e3b4383ea41dcbf47373df8a130567) Thanks [@rezrah](https://github.com/rezrah)! - Upgraded internal framework to [Nextra v3](https://the-guild.dev/blog/nextra-3).
+
+  To migrate Doctocat to this release, follow these steps:
+
+  1. Install the latest version `npm i @primer/doctocat-nextjs@0.1.0`
+  2. Rename your `next.config.js` to be `next.config.mjs`. Add `type="module"` to your `package.json` and update the file contents to match the following:
+
+  ```diff
+  -  const withDoctocat = require('@primer/doctocat-nextjs/doctocat.config.js')
+
+  -  module.exports = {
+  -  ...withDoctocat({
+
+  -  }),
+  -  }
+
+  +  import withDoctocat from '@primer/doctocat-nextjs/doctocat.config.js'
+
+  +  export default {
+  +  ...withDoctocat({
+
+  +  }),
+  +  }
+
+  ```
+
 ## 0.0.4
 
 ### Patch Changes

package/components/context/color-modes/context.ts

@@ -1,4 +1,4 @@
-import React from 'react'
+import {createContext} from 'react'
 
 export type ColorMode = 'light' | 'dark'
 
@@ -12,4 +12,4 @@ const defaultValues: ColorModeContextProps = {
   setColorMode: () => {},
 }
 
-export const ColorModeContext = React.createContext<ColorModeContextProps>(defaultValues)
+export const ColorModeContext = createContext<ColorModeContextProps>(defaultValues)

package/components/layout/header/Header.tsx

@@ -1,10 +1,10 @@
 import {MarkGithubIcon, MoonIcon, SearchIcon, SunIcon, ThreeBarsIcon, XIcon} from '@primer/octicons-react'
 import {Box, FormControl, IconButton, TextInput} from '@primer/react'
 import {Heading, Stack, Text} from '@primer/react-brand'
-import clsx from 'clsx'
-import {MdxFile, PageMapItem} from 'nextra'
+import {clsx} from 'clsx'
+import {MdxFile, Folder, PageMapItem} from 'nextra'
 import type {PageItem} from 'nextra/normalize-pages'
-import React, {useCallback, useEffect, useMemo} from 'react'
+import React, {useCallback, useEffect, useMemo, useRef, useState} from 'react'
 import {debounce} from 'lodash'
 
 import Link from 'next/link'
@@ -12,6 +12,8 @@ import styles from './Header.module.css'
 import {NavDrawer} from '../nav-drawer/NavDrawer'
 import {useNavDrawerState} from '../nav-drawer/useNavDrawerState'
 import {useColorMode} from '../../context/color-modes/useColorMode'
+import {hasChildren} from '../../../helpers/hasChildren'
+import {DocsItem} from '../../../types'
 
 type HeaderProps = {
   pageMap: PageMapItem[]
@@ -28,14 +30,14 @@ type SearchResults = {
 
 export function Header({pageMap, docsDirectories, siteTitle}: HeaderProps) {
   const {colorMode, setColorMode} = useColorMode()
-  const inputRef = React.useRef<HTMLInputElement | null>(null)
-  const searchResultsRef = React.useRef<HTMLElement | null>(null)
+  const inputRef = useRef<HTMLInputElement | null>(null)
+  const searchResultsRef = useRef<HTMLElement | null>(null)
   const [isNavDrawerOpen, setIsNavDrawerOpen] = useNavDrawerState('768')
-  const [isSearchOpen, setIsSearchOpen] = React.useState(false)
-  const [isSearchResultOpen, setIsSearchResultOpen] = React.useState(false)
-  const [searchResults, setSearchResults] = React.useState<SearchResults[] | undefined>()
-  const [searchTerm, setSearchTerm] = React.useState<string | undefined>('')
-  const [activeDescendant] = React.useState<number>(-1)
+  const [isSearchOpen, setIsSearchOpen] = useState(false)
+  const [isSearchResultOpen, setIsSearchResultOpen] = useState(false)
+  const [searchResults, setSearchResults] = useState<SearchResults[] | undefined>()
+  const [searchTerm, setSearchTerm] = useState<string | undefined>('')
+  const [activeDescendant] = useState<number>(-1)
 
   useEffect(() => {
     if (isSearchOpen && inputRef.current) {
@@ -80,10 +82,10 @@ export function Header({pageMap, docsDirectories, siteTitle}: HeaderProps) {
     () =>
       pageMap
         .map(item => {
-          if (item.kind === 'Folder') {
-            return item.children.filter(child => child.kind === 'MdxPage')
+          if (hasChildren(item)) {
+            return (item as Folder).children.filter(child => !hasChildren(child))
           }
-          if (item.kind === 'MdxPage') {
+          if ((item as DocsItem).type === 'doc') {
             return item
           }
         })

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

@@ -1,33 +1,21 @@
 import React from 'react'
 import {Heading, Stack, Text} from '@primer/react-brand'
-import {Folder, MdxFile} from 'nextra'
 
 import Link from 'next/link'
 import styles from './IndexCards.module.css'
+import {DocsItem} from '../../../types'
 
 type IndexCardsProps = {
   route: string
   folderData: DocsItem[]
 }
 
-type FolderWithoutChildren = Omit<Folder, 'children'>
-
-type DocsItem = (MdxFile | FolderWithoutChildren) & {
-  title: string
-  type: string
-  children?: DocsItem[]
-  firstChildRoute?: string
-  withIndexPage?: boolean
-  isUnderCurrentDocsTree?: boolean
-}
-
 export function IndexCards({route, folderData}: IndexCardsProps) {
-  const filteredData = folderData.filter(item => item.kind === 'MdxPage' && item.route.includes(`${route}/`))
-
+  const filteredData = folderData.filter(item => item.type === 'doc' && item.route.includes(`${route}/`))
   return (
     <Stack direction="vertical" padding="none" gap="spacious">
       {filteredData.map((item: DocsItem) => {
-        if (item.kind !== 'MdxPage' || !item.frontMatter) return null
+        if (item.type !== 'doc' || !item.frontMatter) return null
 
         return (
           <Stack direction="vertical" padding="none" gap="condensed" key={item.frontMatter.title}>

package/components/layout/nav-drawer/useNavDrawerState.ts

@@ -1,28 +1,28 @@
-import React from 'react'
+import {useCallback, useEffect, useMemo, useState} from 'react'
 import debounce from 'lodash.debounce'
 
 export function useNavDrawerState(breakpoint): [boolean, (value: boolean) => void] {
   if (typeof breakpoint === 'string') {
     breakpoint = parseInt(breakpoint, 10)
   }
-  const [isOpen, setOpen] = React.useState<boolean>(false)
+  const [isOpen, setOpen] = useState<boolean>(false)
 
-  const onResize = React.useCallback(() => {
+  const onResize = useCallback(() => {
     if (window.innerWidth >= breakpoint) {
       setOpen(false)
     }
   }, [setOpen, breakpoint])
 
-  const handleSetOpen = React.useCallback(
+  const handleSetOpen = useCallback(
     (value: boolean) => {
       setOpen(value)
     },
     [setOpen],
   )
 
-  const debouncedOnResize = React.useMemo(() => debounce(onResize, 250), [onResize])
+  const debouncedOnResize = useMemo(() => debounce(onResize, 250), [onResize])
 
-  React.useEffect(() => {
+  useEffect(() => {
     if (isOpen) {
       // eslint-disable-next-line github/prefer-observers
       window.addEventListener('resize', debouncedOnResize)

package/components/layout/related-content-links/RelatedContentLinks.tsx

@@ -1,10 +1,8 @@
 import React from 'react'
-import {NavList} from '@primer/react'
-import {Text, Heading, UnorderedList, InlineLink} from '@primer/react-brand'
+import {Heading, UnorderedList, InlineLink} from '@primer/react-brand'
 import {MdxFile} from 'nextra'
 
 import styles from './RelatedContentLinks.module.css'
-import Link from 'next/link'
 import {LinkExternalIcon} from '@primer/octicons-react'
 
 export type RelatedContentLink = MdxFile & {

package/components/layout/root-layout/Theme.tsx

@@ -1,4 +1,5 @@
-import React, {useMemo} from 'react'
+import React, {useMemo, useRef} from 'react'
+import {createPortal} from 'react-dom'
 import NextLink from 'next/link'
 import Head from 'next/head'
 import type {Folder, MdxFile, NextraThemeLayoutProps} from 'nextra'
@@ -34,36 +35,33 @@ import {TableOfContents} from '../table-of-contents/TableOfContents'
 import bodyStyles from '../../../css/prose.module.css'
 import {IndexCards} from '../index-cards/IndexCards'
 import {useColorMode} from '../../context/color-modes/useColorMode'
-import {getComponents} from '../../mdx-components/mdx-components'
 import {SkipToMainContent} from '../skip-to-main-content/SkipToMainContent'
 import {RelatedContentLink, RelatedContentLinks} from '../related-content-links/RelatedContentLinks'
+import {hasChildren} from '../../../helpers/hasChildren'
 
 const {publicRuntimeConfig} = getConfig()
 
 export function Theme({children, pageOpts}: NextraThemeLayoutProps) {
-  const {title, frontMatter, headings, filePath, pageMap, route} = pageOpts
-  const {locale = 'en-US', defaultLocale} = useRouter()
+  const tocPortalRef = useRef<HTMLDivElement | null>(null)
+  const {title, frontMatter, filePath, pageMap} = pageOpts
+
+  const {asPath: route} = useRouter()
   const fsPath = useFSRoute()
   const {colorMode} = useColorMode()
   const {activePath, topLevelNavbarItems, docsDirectories, flatDocsDirectories} = useMemo(
     () =>
       normalizePages({
         list: pageMap,
-        locale,
-        defaultLocale,
         route: fsPath,
       }),
-    [pageMap, locale, defaultLocale, fsPath],
+    [pageMap, fsPath],
   )
 
   const {siteTitle} = publicRuntimeConfig
   const isHomePage = route === '/'
   const isIndexPage = /index\.mdx?$/.test(filePath) && !isHomePage && !frontMatter['show-tabs']
   const data = !isHomePage && activePath[activePath.length - 2]
-  const filteredTabData: MdxFile[] =
-    data && data.kind === 'Folder'
-      ? ((data as Folder).children.filter(child => child.kind === 'MdxPage') as MdxFile[])
-      : []
+  const filteredTabData: MdxFile[] = data && hasChildren(data) ? ((data as Folder).children as MdxFile[]) : []
 
   /**
    * Uses a frontmatter 'keywords' value (as an array)
@@ -165,133 +163,152 @@ export function Theme({children, pageOpts}: NextraThemeLayoutProps) {
                   <PageLayout.Content padding="normal">
                     <div id="main">
                       <PRCBox sx={!isHomePage && {display: 'flex', maxWidth: 1600, margin: '0 auto'}}>
-                        <PRCBox sx={!isHomePage && {maxWidth: 800, width: '100%', margin: '0 auto'}}>
-                          <Stack direction="vertical" padding="none" gap="spacious">
-                            {!isHomePage && (
-                              <>
-                                {activePath.length && (
-                                  <Breadcrumbs>
-                                    {siteTitle && (
-                                      <Breadcrumbs.Item
-                                        as={NextLink}
-                                        href="/"
-                                        sx={{
-                                          color: 'var(--brand-InlineLink-color-rest)',
-                                        }}
-                                      >
-                                        {siteTitle}
-                                      </Breadcrumbs.Item>
+                        <MDXProvider
+                          components={{
+                            wrapper: ({children: mdxChildren, toc}) => {
+                              return (
+                                <>
+                                  {tocPortalRef.current &&
+                                    createPortal(
+                                      <PRCBox sx={{py: 2, pr: 3, display: ['none', null, null, null, 'block']}}>
+                                        <PRCBox
+                                          sx={{
+                                            position: 'sticky',
+                                            top: 112,
+                                            width: 220,
+                                          }}
+                                        >
+                                          {toc.length > 0 && <TableOfContents headings={toc} />}
+                                        </PRCBox>
+                                      </PRCBox>,
+
+                                      tocPortalRef.current,
                                     )}
-                                    {activePath.map((item, index) => {
-                                      return (
+
+                                  <div>{mdxChildren}</div>
+                                </>
+                              )
+                            },
+                          }}
+                        >
+                          <PRCBox sx={!isHomePage && {maxWidth: 800, width: '100%', margin: '0 auto'}}>
+                            <Stack direction="vertical" padding="none" gap="spacious">
+                              {!isHomePage && (
+                                <>
+                                  {activePath.length && (
+                                    <Breadcrumbs>
+                                      {siteTitle && (
                                         <Breadcrumbs.Item
                                           as={NextLink}
-                                          key={item.name}
-                                          href={item.route}
-                                          selected={index === activePath.length - 1}
+                                          href="/"
                                           sx={{
-                                            textTransform: 'capitalize',
                                             color: 'var(--brand-InlineLink-color-rest)',
                                           }}
                                         >
-                                          {item.title.replace(/-/g, ' ')}
+                                          {siteTitle}
                                         </Breadcrumbs.Item>
-                                      )
-                                    })}
-                                  </Breadcrumbs>
-                                )}
+                                      )}
+                                      {activePath.map((item, index) => {
+                                        return (
+                                          <Breadcrumbs.Item
+                                            as={NextLink}
+                                            key={item.name}
+                                            href={item.route}
+                                            selected={index === activePath.length - 1}
+                                            sx={{
+                                              textTransform: 'capitalize',
+                                              color: 'var(--brand-InlineLink-color-rest)',
+                                            }}
+                                          >
+                                            {item.title.replace(/-/g, ' ')}
+                                          </Breadcrumbs.Item>
+                                        )
+                                      })}
+                                    </Breadcrumbs>
+                                  )}
 
-                                <Box>
-                                  <Stack direction="vertical" padding="none" gap={12} alignItems="flex-start">
-                                    {frontMatter.title && (
-                                      <Heading as="h1" size="3">
-                                        {frontMatter.title}
-                                      </Heading>
-                                    )}
-                                    {frontMatter.description && (
-                                      <Text as="p" variant="muted" size="300">
-                                        {frontMatter.description}
-                                      </Text>
-                                    )}
-                                    {frontMatter.image && (
-                                      <Box paddingBlockStart={16}>
-                                        <Hero.Image src={frontMatter.image} alt={frontMatter['image-alt']} />
-                                      </Box>
-                                    )}
-                                    {frontMatter['action-1-text'] && (
-                                      <Box paddingBlockStart={16}>
-                                        <ButtonGroup>
-                                          <Button as="a" href={frontMatter['action-1-link']}>
-                                            {frontMatter['action-1-text']}
-                                          </Button>
-                                          {frontMatter['action-2-text'] && (
-                                            <Button as="a" variant="secondary" href={frontMatter['action-2-link']}>
-                                              {frontMatter['action-2-text']}
+                                  <Box>
+                                    <Stack direction="vertical" padding="none" gap={12} alignItems="flex-start">
+                                      {frontMatter.title && (
+                                        <Heading as="h1" size="3">
+                                          {frontMatter.title}
+                                        </Heading>
+                                      )}
+                                      {frontMatter.description && (
+                                        <Text as="p" variant="muted" size="300">
+                                          {frontMatter.description}
+                                        </Text>
+                                      )}
+                                      {frontMatter.image && (
+                                        <Box paddingBlockStart={16}>
+                                          <Hero.Image src={frontMatter.image} alt={frontMatter['image-alt']} />
+                                        </Box>
+                                      )}
+                                      {frontMatter['action-1-text'] && (
+                                        <Box paddingBlockStart={16}>
+                                          <ButtonGroup>
+                                            <Button as="a" href={frontMatter['action-1-link']}>
+                                              {frontMatter['action-1-text']}
                                             </Button>
-                                          )}
-                                        </ButtonGroup>
-                                      </Box>
-                                    )}
-                                  </Stack>
-                                </Box>
-                                {Boolean(frontMatter['show-tabs']) && <UnderlineNav tabData={filteredTabData} />}
-                              </>
-                            )}
-                            <article className={route !== '/' && !isIndexPage ? bodyStyles.Prose : ''}>
-                              {isIndexPage ? (
-                                <IndexCards folderData={flatDocsDirectories} route={route} />
-                              ) : (
-                                <>
-                                  <MDXProvider components={getComponents()}>{children}</MDXProvider>
-                                  {getRelatedPages().length > 0 && (
-                                    <PRCBox sx={{pt: 5}}>
-                                      <RelatedContentLinks links={getRelatedPages()} />
-                                    </PRCBox>
-                                  )}
+                                            {frontMatter['action-2-text'] && (
+                                              <Button as="a" variant="secondary" href={frontMatter['action-2-link']}>
+                                                {frontMatter['action-2-text']}
+                                              </Button>
+                                            )}
+                                          </ButtonGroup>
+                                        </Box>
+                                      )}
+                                    </Stack>
+                                  </Box>
+                                  {Boolean(frontMatter['show-tabs']) && <UnderlineNav tabData={filteredTabData} />}
                                 </>
                               )}
-                            </article>
-                            <footer>
-                              <Box marginBlockStart={64}>
-                                <Stack direction="vertical" padding="none" gap={16}>
-                                  <Stack direction="horizontal" padding="none" alignItems="center" gap={8}>
-                                    <PencilIcon size={16} fill="var(--brand-InlineLink-color-rest)" />
+                              <article className={route !== '/' && !isIndexPage ? bodyStyles.Prose : ''}>
+                                {isIndexPage ? (
+                                  <IndexCards folderData={flatDocsDirectories} route={route} />
+                                ) : (
+                                  <>
+                                    <>{children}</>
+                                    {getRelatedPages().length > 0 && (
+                                      <PRCBox sx={{pt: 5}}>
+                                        <RelatedContentLinks links={getRelatedPages()} />
+                                      </PRCBox>
+                                    )}
+                                  </>
+                                )}
+                              </article>
+                              <footer>
+                                <Box marginBlockStart={64}>
+                                  <Stack direction="vertical" padding="none" gap={16}>
+                                    <Stack direction="horizontal" padding="none" alignItems="center" gap={8}>
+                                      <PencilIcon size={16} fill="var(--brand-InlineLink-color-rest)" />
 
-                                    <InlineLink
-                                      href={`${publicRuntimeConfig.repo}/blob/main/${
-                                        publicRuntimeConfig.repoSrcPath ? `${publicRuntimeConfig.repoSrcPath}/` : ''
-                                      }${filePath}`}
+                                      <InlineLink
+                                        href={`${publicRuntimeConfig.repo}/blob/main/${
+                                          publicRuntimeConfig.repoSrcPath ? `${publicRuntimeConfig.repoSrcPath}/` : ''
+                                        }${filePath}`}
+                                      >
+                                        Edit this page
+                                      </InlineLink>
+                                    </Stack>
+                                    <Box
+                                      marginBlockStart={8}
+                                      paddingBlockStart={24}
+                                      borderStyle="solid"
+                                      borderBlockStartWidth="thin"
+                                      borderColor="default"
                                     >
-                                      Edit this page
-                                    </InlineLink>
+                                      <Text as="p" variant="muted" size="100">
+                                        &copy; {new Date().getFullYear()} GitHub, Inc. All rights reserved.
+                                      </Text>
+                                    </Box>
                                   </Stack>
-                                  <Box
-                                    marginBlockStart={8}
-                                    paddingBlockStart={24}
-                                    borderStyle="solid"
-                                    borderBlockStartWidth="thin"
-                                    borderColor="default"
-                                  >
-                                    <Text as="p" variant="muted" size="100">
-                                      &copy; {new Date().getFullYear()} GitHub, Inc. All rights reserved.
-                                    </Text>
-                                  </Box>
-                                </Stack>
-                              </Box>
-                            </footer>
-                          </Stack>
-                        </PRCBox>
-                        <PRCBox sx={{py: 2, pr: 3, display: ['none', null, null, null, 'block']}}>
-                          <PRCBox
-                            sx={{
-                              position: 'sticky',
-                              top: 112,
-                              width: 220,
-                            }}
-                          >
-                            {!isHomePage && headings.length > 0 && <TableOfContents headings={headings} />}
+                                </Box>
+                              </footer>
+                            </Stack>
                           </PRCBox>
-                        </PRCBox>
+                        </MDXProvider>
+                        <div ref={tocPortalRef} />
                       </PRCBox>
                     </div>
                   </PageLayout.Content>
@@ -315,3 +332,22 @@ export function Theme({children, pageOpts}: NextraThemeLayoutProps) {
     </>
   )
 }
+
+export function MdxWrapper({children, toc}) {
+  return (
+    <>
+      <PRCBox sx={{py: 2, pr: 3, display: ['none', null, null, null, 'block']}}>
+        <PRCBox
+          sx={{
+            position: 'sticky',
+            top: 112,
+            width: 220,
+          }}
+        >
+          {toc.length > 0 && <TableOfContents headings={toc} />}
+        </PRCBox>
+      </PRCBox>
+      <div>{children}</div>
+    </>
+  )
+}

package/components/layout/sidebar/Sidebar.tsx

@@ -1,31 +1,25 @@
 import React, {useMemo} from 'react'
 import NextLink from 'next/link'
 import {NavList} from '@primer/react'
-import {Folder, MdxFile, PageMapItem} from 'nextra'
+import {Folder, MdxFile} from 'nextra'
 import {useRouter} from 'next/router'
 import getConfig from 'next/config'
 
 import styles from './Sidebar.module.css'
 import {LinkExternalIcon} from '@primer/octicons-react'
-import type {ThemeConfig} from '../../../index'
+import type {DocsItem, ThemeConfig} from '../../../index'
+import {hasChildren} from '../../../helpers/hasChildren'
 
 type SidebarProps = {
   pageMap: DocsItem[]
 }
 
-type FolderWithoutChildren = Omit<Folder, 'children'>
+const {publicRuntimeConfig} = getConfig()
 
-type DocsItem = (MdxFile | FolderWithoutChildren) & {
-  title: string
-  type: string
-  children?: DocsItem[]
-  firstChildRoute?: string
-  withIndexPage?: boolean
-  isUnderCurrentDocsTree?: boolean
+const hasShowTabs = (child: DocsItem): boolean => {
+  return child.name === 'index' && (child as MdxFile).frontMatter?.['show-tabs'] === true
 }
 
-const {publicRuntimeConfig} = getConfig()
-
 export function Sidebar({pageMap}: SidebarProps) {
   const router = useRouter()
 
@@ -39,11 +33,11 @@ export function Sidebar({pageMap}: SidebarProps) {
   const reorderedPageMap = useMemo(
     () =>
       [...pageMap].sort((a, b) => {
-        if (a.kind === 'Folder' && a.children) {
-          const aIndex = a.children.find(child => child.name === 'index' && child.kind === 'MdxPage')
+        if (hasChildren(a) && a.children) {
+          const aIndex = a.children.find(child => child.name === 'index' && child.type === 'doc')
           const aPosition = (aIndex as MdxFile | undefined)?.frontMatter?.['menu-position'] ?? Infinity
-          if (b.kind === 'Folder' && b.children) {
-            const bIndex = b.children.find(child => child.name === 'index' && child.kind === 'MdxPage')
+          if (hasChildren(b) && b.children) {
+            const bIndex = b.children.find(child => child.name === 'index' && child.type === 'doc')
             const bPosition = (bIndex as MdxFile | undefined)?.frontMatter?.['menu-position'] ?? Infinity
             return aPosition - bPosition
           }
@@ -57,21 +51,19 @@ export function Sidebar({pageMap}: SidebarProps) {
     <div className={styles.Sidebar}>
       <NavList className={styles.NavList} aria-label="Menu links">
         {reorderedPageMap.map(item => {
-          if (item.kind === 'MdxPage' && item.route === '/') return null
+          if (item.type === 'doc' && item.route === '/') return null
 
-          if (item.kind === 'MdxPage') {
+          if (!hasChildren(item) && item.type === 'doc') {
             return (
               <NavList.Item as={NextLink} key={item.name} href={item.route} sx={{textTransform: 'capitalize'}}>
-                {item.frontMatter?.title ?? item.name}
+                {(item as MdxFile).frontMatter?.title ?? item.name}
               </NavList.Item>
             )
           }
 
           // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-          if (item.kind === 'Folder') {
-            const indexPage = (item as Folder).children.find(
-              child => child.kind === 'MdxPage' && child.name === 'index',
-            ) as MdxFile
+          if (hasChildren(item)) {
+            const indexPage = (item as Folder).children.find(child => (child as MdxFile).name === 'index') as MdxFile
             const subNavName = indexPage.frontMatter?.title ?? ''
             const shouldShowTabs = indexPage.frontMatter?.['show-tabs'] ?? false
             if (shouldShowTabs) {
@@ -87,28 +79,27 @@ export function Sidebar({pageMap}: SidebarProps) {
                 {item.children &&
                   item.children
                     .sort((a, b) => (a.name === 'index' ? -1 : b.name === 'index' ? 1 : 0)) // puts index page first
-                    .filter(
-                      child =>
-                        (child as DocsItem).name !== 'index' ||
-                        ((child.name === 'index' && (child as MdxFile).frontMatter?.['show-tabs']) ?? false),
-                    ) // only show index page if it has show-tabs
+                    // only show index page if it has show-tabs
+                    .filter(child => child.name !== 'index' || hasShowTabs(child))
                     .map((child: DocsItem) => {
-                      if (child.kind === 'MdxPage') {
+                      if (child.type === 'doc') {
                         return (
                           <NavList.Item
                             as={NextLink}
                             key={child.name}
                             href={child.route}
+                            sx={{textTransform: 'capitalize'}}
                             aria-current={child.route === router.pathname ? 'page' : undefined}
                           >
-                            {(child as MdxFile).frontMatter?.title || item.name}
+                            {child.title}
                           </NavList.Item>
                         )
                       }
 
-                      if ((child as DocsItem).kind === 'Folder') {
-                        const landingPageItem: PageMapItem | undefined = (child as Folder).children.find(
-                          innerChild => innerChild.kind === 'MdxPage' && innerChild.name === 'index',
+                      if (hasChildren(child)) {
+                        const landingPageItem = (child as Folder).children.find(
+                          innerChild =>
+                            (innerChild as DocsItem).type === 'doc' && (innerChild as DocsItem).name === 'index',
                         )
                         return (
                           <NavList.Item

package/css/global.css

@@ -14,100 +14,6 @@ body {
   margin-block-start: 0 !important;
 }
 
-/**
- * Code block overrides
- */
-
-:root {
-  --shiki-color-text: #414141;
-  --shiki-color-background: transparent;
-  --shiki-token-constant: #1976d2;
-  --shiki-token-string: #22863a;
-  --shiki-token-comment: #aaa;
-  --shiki-token-keyword: #d32f2f;
-  --shiki-token-parameter: #ff9801;
-  --shiki-token-function: #6f42c1;
-  --shiki-token-string-expression: var(--shiki-token-string);
-  --shiki-token-punctuation: #212121;
-  --shiki-token-link: var(--shiki-token-string);
-  --shiki-color-ansi-black: #24292e;
-  --shiki-color-ansi-black-dim: rgba(36, 41, 46, 0.5);
-  --shiki-color-ansi-red: #d73a49;
-  --shiki-color-ansi-red-dim: rgba(215, 58, 73, 0.5);
-  --shiki-color-ansi-green: #28a745;
-  --shiki-color-ansi-green-dim: rgba(40, 167, 69, 0.5);
-  --shiki-color-ansi-yellow: #dbab09;
-  --shiki-color-ansi-yellow-dim: rgba(219, 171, 9, 0.5);
-  --shiki-color-ansi-blue: #0366d6;
-  --shiki-color-ansi-blue-dim: rgba(3, 102, 214, 0.5);
-  --shiki-color-ansi-magenta: #5a32a3;
-  --shiki-color-ansi-magenta-dim: rgba(90, 50, 163, 0.5);
-  --shiki-color-ansi-cyan: #1b7c83;
-  --shiki-color-ansi-cyan-dim: rgba(27, 124, 131, 0.5);
-  --shiki-color-ansi-white: #6a737d;
-  --shiki-color-ansi-white-dim: rgba(106, 115, 125, 0.5);
-  --shiki-color-ansi-bright-black: #959da5;
-  --shiki-color-ansi-bright-black-dim: rgba(149, 157, 165, 0.5);
-  --shiki-color-ansi-bright-red: #cb2431;
-  --shiki-color-ansi-bright-red-dim: rgba(203, 36, 49, 0.5);
-  --shiki-color-ansi-bright-green: #22863a;
-  --shiki-color-ansi-bright-green-dim: rgba(34, 134, 58, 0.5);
-  --shiki-color-ansi-bright-yellow: #b08800;
-  --shiki-color-ansi-bright-yellow-dim: rgba(176, 136, 0, 0.5);
-  --shiki-color-ansi-bright-blue: #005cc5;
-  --shiki-color-ansi-bright-blue-dim: rgba(0, 92, 197, 0.5);
-  --shiki-color-ansi-bright-magenta: #5a32a3;
-  --shiki-color-ansi-bright-magenta-dim: rgba(90, 50, 163, 0.5);
-  --shiki-color-ansi-bright-cyan: #3192aa;
-  --shiki-color-ansi-bright-cyan-dim: rgba(49, 146, 170, 0.5);
-  --shiki-color-ansi-bright-white: #d1d5da;
-  --shiki-color-ansi-bright-white-dim: rgba(209, 213, 218, 0.5);
-}
-
-[data-color-mode='dark'] {
-  --shiki-color-text: #d1d1d1;
-  --shiki-token-constant: #79b8ff;
-  --shiki-token-string: #ffab70;
-  --shiki-token-comment: #6b737c;
-  --shiki-token-keyword: #f97583;
-  --shiki-token-function: #b392f0;
-  --shiki-token-string-expression: #4bb74a;
-  --shiki-token-punctuation: #bbb;
-  --shiki-token-link: var(--shiki-token-string);
-  --shiki-color-ansi-black: #586069;
-  --shiki-color-ansi-black-dim: rgba(88, 96, 105, 0.5);
-  --shiki-color-ansi-red: #ea4a5a;
-  --shiki-color-ansi-red-dim: rgba(234, 74, 90, 0.5);
-  --shiki-color-ansi-green: #34d058;
-  --shiki-color-ansi-green-dim: rgba(52, 208, 88, 0.5);
-  --shiki-color-ansi-yellow: #ffea7f;
-  --shiki-color-ansi-yellow-dim: rgba(255, 234, 127, 0.5);
-  --shiki-color-ansi-blue: #2188ff;
-  --shiki-color-ansi-blue-dim: rgba(33, 136, 255, 0.5);
-  --shiki-color-ansi-magenta: #b392f0;
-  --shiki-color-ansi-magenta-dim: rgba(179, 146, 240, 0.5);
-  --shiki-color-ansi-cyan: #39c5cf;
-  --shiki-color-ansi-cyan-dim: rgba(57, 197, 207, 0.5);
-  --shiki-color-ansi-white: #d1d5da;
-  --shiki-color-ansi-white-dim: rgba(209, 213, 218, 0.5);
-  --shiki-color-ansi-bright-black: #959da5;
-  --shiki-color-ansi-bright-black-dim: rgba(149, 157, 165, 0.5);
-  --shiki-color-ansi-bright-red: #f97583;
-  --shiki-color-ansi-bright-red-dim: rgba(249, 117, 131, 0.5);
-  --shiki-color-ansi-bright-green: #85e89d;
-  --shiki-color-ansi-bright-green-dim: rgba(133, 232, 157, 0.5);
-  --shiki-color-ansi-bright-yellow: #ffea7f;
-  --shiki-color-ansi-bright-yellow-dim: rgba(255, 234, 127, 0.5);
-  --shiki-color-ansi-bright-blue: #79b8ff;
-  --shiki-color-ansi-bright-blue-dim: rgba(121, 184, 255, 0.5);
-  --shiki-color-ansi-bright-magenta: #b392f0;
-  --shiki-color-ansi-bright-magenta-dim: rgba(179, 146, 240, 0.5);
-  --shiki-color-ansi-bright-cyan: #56d4dd;
-  --shiki-color-ansi-bright-cyan-dim: rgba(86, 212, 221, 0.5);
-  --shiki-color-ansi-bright-white: #fafbfc;
-  --shiki-color-ansi-bright-white-dim: rgba(250, 251, 252, 0.5);
-}
-
 pre {
   background-color: var(--brand-color-canvas-subtle);
   border-radius: var(--brand-borderRadius-large);
@@ -123,6 +29,15 @@ code {
     'calt' 1,
     'ss01' 1;
 }
+
+code span {
+  color: var(--shiki-light);
+}
+
+[data-color-mode='dark'] code span {
+  color: var(--shiki-dark);
+}
+
 code[data-line-numbers] > .line {
   padding-left: 0.5rem;
 }

package/doctocat.config.js

@@ -1,9 +1,12 @@
-const withNextra = require('nextra')({
+import nextra from 'nextra'
+import transpiler from 'next-transpile-modules'
+
+const withNextra = nextra({
   theme: '@primer/doctocat-nextjs',
   staticImage: true,
 })
 
-const withTM = require('next-transpile-modules')(['@primer/doctocat-nextjs'])
+const withTM = transpiler(['@primer/doctocat-nextjs'])
 
 /*
  * Wrapper for next config, that allows us to do some shared configuration
@@ -23,4 +26,4 @@ function withDoctocat(config = {}) {
   })
 }
 
-module.exports = withDoctocat
+export default withDoctocat

package/helpers/hasChildren.ts

@@ -0,0 +1,5 @@
+import {PageMapItem, Folder} from 'nextra'
+import {DocsItem} from '../types'
+
+export const hasChildren = (item: DocsItem | PageMapItem): boolean =>
+  'children' in item && Array.isArray((item as Folder).children) && (item as Folder).children.length > 0

package/package.json

@@ -1,37 +1,45 @@
 {
   "name": "@primer/doctocat-nextjs",
-  "version": "0.0.4",
+  "version": "0.1.0",
   "description": "A Next.js theme for building Primer documentation sites",
   "main": "index.js",
+  "type": "module",
   "scripts": {
-    "lint": "eslint '**/*.{js,ts,tsx,md,mdx}' --max-warnings=0 --config ./.eslintrc.js",
+    "check": "tsc --noEmit",
+    "lint": "eslint '**/*.{js,ts,tsx,md,mdx}' --max-warnings=0 --config ./.eslintrc.cjs",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "author": "GitHub, Inc.",
   "license": "MIT",
   "peerDependencies": {
-    "next": "^14.0.3",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0"
+    "next": "15.1.6",
+    "react": "18.3.1",
+    "react-dom": "18.3.1"
   },
   "dependencies": {
-    "@primer/octicons-react": "^19.8.0",
-    "@primer/react": "^36.2.0",
-    "@primer/react-brand": "^0.29.1",
+    "@primer/octicons-react": "19.14.0",
+    "@primer/react": "36.27.0",
+    "@primer/react-brand": "0.46.0",
     "next-transpile-modules": "^10.0.1",
-    "framer-motion": "^10.16.12",
+    "framer-motion": "12.0.1",
     "lodash.debounce": "^4.0.8",
-    "react-focus-on": "^3.9.1",
-    "nextra": "^2.13.2"
+    "react-focus-on": "3.9.4",
+    "nextra": "3.3.1",
+    "react": "18.3.1",
+    "react-dom": "18.3.1"
   },
   "devDependencies": {
     "@github/prettier-config": "^0.0.6",
     "@types/node": "18.11.10",
-    "@types/react": "^18.2.39",
-    "@types/react-dom": "^18.2.17",
-    "clsx": "^2.0.0",
-    "next": "^14.0.3",
-    "styled-components": "^6.1.1",
-    "typescript": "^5.3.2"
+    "@types/react": "18.3.12",
+    "@types/react-dom": "18.3.1",
+    "clsx": "2.1.1",
+    "next": "15.1.6",
+    "styled-components": "6.1.13",
+    "typescript": "5.7.3"
+  },
+  "overrides": {
+    "@types/react": "18.3.12",
+    "@types/react-dom": "18.3.1"
   }
 }

package/types.ts

@@ -1,3 +1,5 @@
+import {Folder, MdxFile} from 'nextra'
+
 export type ThemeConfig = {
   docsRepositoryBase: string
   sidebarLinks?: {
@@ -5,3 +7,14 @@ export type ThemeConfig = {
     href: string
   }[]
 }
+
+export type FolderWithoutChildren = Omit<Folder, 'children'>
+
+export type DocsItem = MdxFile & {
+  title: string
+  type: string
+  children?: DocsItem[]
+  firstChildRoute?: string
+  withIndexPage?: boolean
+  isUnderCurrentDocsTree?: boolean
+}

package/components/mdx-components/mdx-components.module.css

@@ -1,14 +0,0 @@
-.Heading__anchor {
-  color: var(--brand-color-text-default) !important;
-  text-decoration: none !important;
-}
-
-.Heading__anchorIcon {
-  visibility: hidden;
-  margin-left: var(--base-size-8);
-  vertical-align: middle !important;
-}
-
-.Heading__anchor:hover .Heading__anchorIcon {
-  visibility: visible;
-}

package/components/mdx-components/mdx-components.tsx

@@ -1,43 +0,0 @@
-import React from 'react'
-import type {ComponentProps, ReactElement} from 'react'
-import clsx from 'clsx'
-import type {Components} from 'nextra/mdx'
-
-import {LinkIcon} from '@primer/octicons-react'
-import NextLink from 'next/link'
-
-import styles from './mdx-components.module.css'
-
-// Anchor links for Headings
-function HeadingLink({
-  tag: Tag,
-  context,
-  children,
-  id,
-  className,
-  ...props
-}: ComponentProps<'h2'> & {
-  tag: `h${2 | 3 | 4 | 5 | 6}`
-  context: {index: number}
-}): ReactElement {
-  return (
-    <Tag {...props} id={id} className={clsx(className)}>
-      <NextLink href={`#${id}`} className={styles.Heading__anchor}>
-        {children} <LinkIcon className={styles.Heading__anchorIcon} size={16} />
-      </NextLink>
-    </Tag>
-  )
-}
-
-export const Link = ({href = '', className, ...props}) => <NextLink href={href} {...props} />
-export const getComponents = (): Components => {
-  const context = {index: 0}
-  return {
-    h2: props => <HeadingLink tag="h2" context={context} {...props} />,
-    h3: props => <HeadingLink tag="h3" context={context} {...props} />,
-    h4: props => <HeadingLink tag="h4" context={context} {...props} />,
-    h5: props => <HeadingLink tag="h5" context={context} {...props} />,
-    h6: props => <HeadingLink tag="h6" context={context} {...props} />,
-    a: Link,
-  }
-}