@primer/doctocat-nextjs 0.4.1-rc.afcbafc → 0.5.0-rc.6ee882c

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @primer/doctocat-nextjs
 
+## 0.5.0
+
+### Minor Changes
+
+- [#30](https://github.com/primer/doctocat-nextjs/pull/30) [`cdcb65e`](https://github.com/primer/doctocat-nextjs/commit/cdcb65e087d647a6d61c87d9122f105dcda64e35) Thanks [@joshfarrant](https://github.com/joshfarrant)! - - Aribitrary links can now be added to the sidebar and header using the `Theme` component's `headerLinks` and `sidebarLinks` props.
+  - Updated the header navigation to more closely visually align it with the existing Primer docs navigation.
+  - Removed `_meta.global.ts` and instead directly pass header and sidebar links into the doctocat `Theme` component.
+    ```diff
+    - // _meta.global.ts
+    - export default {
+    -   type: 'page',
+    -   href: 'https://github.com/primer/doctocat-nextjs',
+    -   title: 'Doctocat',
+    - }
+    ```
+    ```diff
+    + // app/layout.tsx
+    +
+    + const sidebarLinks: ThemeProps['sidebarLinks'] = [
+    +   {
+    +     href: 'https://github.com/',
+    +     title: 'GitHub',
+    +     isExternal: true,
+    +   },
+    + ]
+    +
+    + <Theme sidebarLinks={sidebarLinks} {...rest} />
+    ```
+
 ## 0.4.1
 
 ### Patch Changes

package/components/context/useConfig.tsx

@@ -0,0 +1,31 @@
+import React, {createContext, PropsWithChildren, useContext} from 'react'
+
+export type ConfigContextLink = {
+  title: string
+  href: string
+  isActive?: boolean
+  isExternal?: boolean
+}
+
+export type ConfigContextValue = {
+  headerLinks: ConfigContextLink[]
+  sidebarLinks: ConfigContextLink[]
+}
+
+export const ConfigContext = createContext<ConfigContextValue | null>(null)
+
+export const useConfig = (): ConfigContextValue => {
+  const context = useContext(ConfigContext)
+
+  if (!context) {
+    throw new Error('useConfig must be used within a ConfigContextProvider')
+  }
+
+  return context
+}
+
+type ConfigContextProviderProps = PropsWithChildren<{value: ConfigContextValue}>
+
+export const ConfigContextProvider = ({children, value}: ConfigContextProviderProps) => {
+  return <ConfigContext.Provider value={value}>{children}</ConfigContext.Provider>
+}

package/components/layout/global-search/GlobalSearch.module.css

@@ -3,6 +3,12 @@
   z-index: 1;
 }
 
+.GlobalSearch__searchIcon {
+  vertical-align: middle;
+  position: relative;
+  top: calc(var(--base-size-2) * -1);
+}
+
 .GlobalSearch__searchResultsContainer {
   display: none;
   margin-top: var(--base-size-4);

package/components/layout/global-search/GlobalSearch.tsx

@@ -9,7 +9,7 @@ import {useRouter} from 'next/navigation'
 
 import styles from './GlobalSearch.module.css'
 import type {DocsItem} from '../../../types'
-import {HighlightSearchTerm} from '../../highlight-search-term/HighlightSearchTerm'
+import {HighlightSearchTerm} from '../highlight-search-term/HighlightSearchTerm'
 
 type GlobalSearchProps = {
   flatDocsDirectories: DocsItem[]
@@ -173,7 +173,7 @@ export const GlobalSearch = forwardRef<HTMLInputElement, GlobalSearchProps>(
             contrast
             type="search"
             className={styles.GlobalSearch__searchInput}
-            leadingVisual={<SearchIcon />}
+            leadingVisual={<SearchIcon className={styles.GlobalSearch__searchIcon} />}
             placeholder={`Search ${siteTitle}`}
             ref={forwardedRef}
             value={searchTerm}

package/components/layout/header/Header.module.css

@@ -3,12 +3,31 @@
   display: flex;
   align-items: center;
   justify-content: space-between;
-  padding: var(--base-size-20) var(--base-size-12) var(--base-size-20) var(--base-size-16);
+  padding-block: var(--base-size-12);
+  padding-inline: var(--base-size-16) var(--base-size-16);
   border-bottom: var(--brand-borderWidth-thin) solid var(--brand-color-border-default);
   background: var(--brand-color-canvas-default);
   z-index: 20;
 }
 
+.Header__start {
+  display: flex;
+  align-items: center;
+}
+
+.Header__separator {
+  color: var(--borderColor-default);
+  font-weight: var(--base-text-weight-light);
+  margin-inline-start: var(--base-size-12);
+}
+
+.Header__end {
+  flex: 1;
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+}
+
 @media (max-width: 767px) {
   .Header__searchArea {
     display: none;
@@ -61,13 +80,12 @@
 
 @media (min-width: 768px) {
   .Header {
-    padding: var(--base-size-20) var(--base-size-12) var(--base-size-20) var(--base-size-24);
+    padding-inline: var(--base-size-24) var(--base-size-24);
   }
 
   .Header__searchArea {
     width: 100%;
     max-width: 350px;
-    margin-inline-start: auto;
     margin-inline-end: var(--base-size-16);
   }
 
@@ -82,10 +100,49 @@
   display: flex;
   gap: var(--base-size-8);
   align-items: center;
-  min-width: 230px;
+  margin-inline-end: auto;
   text-decoration: none;
 }
 
 .Header__siteTitle svg {
   fill: var(--brand-color-text-default);
 }
+
+.Header__siteTitleText {
+  @media (max-width: 25rem) {
+    display: none;
+  }
+}
+
+.Header__links {
+  display: none;
+  margin-inline: var(--base-size-24);
+}
+
+.Header__link {
+  text-decoration: none;
+  font-size: var(--base-font-size-16);
+  font-weight: var(--base-font-weight-500);
+}
+
+.Header__externalLinkIcon {
+  margin-block-end: var(--base-size-8);
+}
+
+@media (min-width: 72rem) {
+  .Header {
+    padding-block: var(--base-size-16);
+  }
+
+  .Header__separator {
+    display: none;
+  }
+
+  .Header__linksDropdown {
+    display: none;
+  }
+
+  .Header__links {
+    display: flex;
+  }
+}

package/components/layout/header/Header.tsx

@@ -1,31 +1,44 @@
 import React, {useEffect, useRef, useState} from 'react'
-import {MarkGithubIcon, MoonIcon, SearchIcon, SunIcon, ThreeBarsIcon, XIcon} from '@primer/octicons-react'
+import {
+  ArrowUpRightIcon,
+  MarkGithubIcon,
+  MoonIcon,
+  SearchIcon,
+  SunIcon,
+  ThreeBarsIcon,
+  XIcon,
+} from '@primer/octicons-react'
 import {IconButton} from '@primer/react'
 import {Stack, Text} from '@primer/react-brand'
 import {clsx} from 'clsx'
-import {PageMapItem} from 'nextra'
+import type {PageMapItem} from 'nextra'
 
 import Link from 'next/link'
 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 {DocsItem} from '../../../types'
+
+import type {DocsItem} from '../../../types'
+
 import {GlobalSearch} from '../global-search/GlobalSearch'
 import {FocusOn} from 'react-focus-on'
+import {LinksDropdown} from '../links-dropdown/LinksDropdown'
+import {useConfig} from '../../context/useConfig'
 
 type HeaderProps = {
-  pageMap: PageMapItem[]
   flatDocsDirectories: DocsItem[]
   siteTitle: string
+  pageMap: PageMapItem[]
 }
 
-export function Header({pageMap, siteTitle, flatDocsDirectories}: HeaderProps) {
+export function Header({siteTitle, flatDocsDirectories, pageMap}: HeaderProps) {
   const searchRef = useRef<HTMLInputElement | null>(null)
   const {colorMode, setColorMode} = useColorMode()
   const searchTriggerRef = useRef<HTMLButtonElement | null>(null)
   const [isNavDrawerOpen, setIsNavDrawerOpen] = useNavDrawerState('768')
   const [isSearchOpen, setIsSearchOpen] = useState(false)
+  const {headerLinks} = useConfig()
 
   useEffect(() => {
     document.documentElement.setAttribute('data-color-mode', colorMode)
@@ -44,57 +57,87 @@ export function Header({pageMap, siteTitle, flatDocsDirectories}: HeaderProps) {
       role="navigation"
       aria-label="Header Navigation"
     >
-      <Link href="/" className={styles.Header__siteTitle}>
-        <MarkGithubIcon size={24} />
-        <Text as="p" size="300" weight="semibold">
-          {siteTitle}
+      <div className={styles.Header__start}>
+        <Link href="/" className={styles.Header__siteTitle}>
+          <MarkGithubIcon size={24} />
+          <Text className={styles.Header__siteTitleText} as="p" size="300" weight="semibold">
+            {siteTitle}
+          </Text>
+        </Link>
+        <Text as="span" className={styles.Header__separator} weight="semibold" aria-hidden>
+          &#47;
         </Text>
-      </Link>
-      <div className={clsx(styles.Header__searchArea, isSearchOpen && styles['Header__searchArea--open'])}>
-        <FocusOn enabled={isSearchOpen} onEscapeKey={closeSearch} onClickOutside={closeSearch}>
-          <GlobalSearch
-            ref={searchRef}
-            siteTitle={siteTitle}
-            flatDocsDirectories={flatDocsDirectories}
-            onNavigate={() => closeSearch()}
-          />
-          <div className={styles.Header__searchHeaderBanner}>
-            <Stack direction="horizontal" padding="none" gap={4} alignItems="center" justifyContent="space-between">
-              <Text as="p" size="300" weight="semibold">
-                Search
-              </Text>
-              <IconButton icon={XIcon} variant="invisible" aria-label="Close search" onClick={closeSearch} />
-            </Stack>
-          </div>
-        </FocusOn>
+        {headerLinks.length > 0 && <LinksDropdown className={styles.Header__linksDropdown} items={headerLinks} />}
       </div>
-      <div>
-        <Stack direction="horizontal" padding="none" gap={4}>
-          <IconButton
-            icon={colorMode === 'light' ? SunIcon : MoonIcon}
-            variant="invisible"
-            aria-label={`Change color mode. Active mode is ${colorMode}.`}
-            onClick={() => setColorMode(colorMode === 'light' ? 'dark' : 'light')}
-          />
-          <IconButton
-            ref={searchTriggerRef}
-            className={styles.Header__searchButton}
-            icon={SearchIcon}
-            variant="invisible"
-            aria-label={`Open search`}
-            onClick={() => setIsSearchOpen(true)}
-          />
-          <div className={styles.Header__navDrawerContainer}>
+      <div className={styles.Header__end}>
+        <Stack className={styles.Header__links} direction="horizontal" padding="none" gap={24}>
+          {headerLinks.map(link => (
+            <Link
+              key={link.href}
+              className={styles.Header__link}
+              href={link.href}
+              aria-current={link.isActive ? 'page' : undefined}
+              {...(link.isExternal && {target: '_blank', rel: 'noopener noreferrer'})}
+            >
+              <Text
+                size="200"
+                variant={link.isActive ? 'default' : 'muted'}
+                weight={link.isActive ? 'semibold' : 'normal'}
+              >
+                {link.title}
+                {link.isExternal && (
+                  <ArrowUpRightIcon className={styles.Header__externalLinkIcon} size={10} aria-label="External link" />
+                )}
+              </Text>
+            </Link>
+          ))}
+        </Stack>
+        <div className={clsx(styles.Header__searchArea, isSearchOpen && styles['Header__searchArea--open'])}>
+          <FocusOn enabled={isSearchOpen} onEscapeKey={closeSearch} onClickOutside={closeSearch}>
+            <GlobalSearch
+              ref={searchRef}
+              siteTitle={siteTitle}
+              flatDocsDirectories={flatDocsDirectories}
+              onNavigate={() => closeSearch()}
+            />
+            <div className={styles.Header__searchHeaderBanner}>
+              <Stack direction="horizontal" padding="none" gap={4} alignItems="center" justifyContent="space-between">
+                <Text as="p" size="300" weight="semibold">
+                  Search
+                </Text>
+                <IconButton icon={XIcon} variant="invisible" aria-label="Close search" onClick={closeSearch} />
+              </Stack>
+            </div>
+          </FocusOn>
+        </div>
+        <div>
+          <Stack direction="horizontal" padding="none" gap={4}>
             <IconButton
-              icon={ThreeBarsIcon}
+              icon={colorMode === 'light' ? SunIcon : MoonIcon}
               variant="invisible"
-              aria-label="Menu"
-              aria-expanded={isNavDrawerOpen}
-              onClick={() => setIsNavDrawerOpen(true)}
+              aria-label={`Change color mode. Active mode is ${colorMode}.`}
+              onClick={() => setColorMode(colorMode === 'light' ? 'dark' : 'light')}
             />
-            <NavDrawer isOpen={isNavDrawerOpen} onDismiss={() => setIsNavDrawerOpen(false)} navItems={pageMap} />
-          </div>
-        </Stack>
+            <IconButton
+              ref={searchTriggerRef}
+              className={styles.Header__searchButton}
+              icon={SearchIcon}
+              variant="invisible"
+              aria-label={`Open search`}
+              onClick={() => setIsSearchOpen(true)}
+            />
+            <div className={styles.Header__navDrawerContainer}>
+              <IconButton
+                icon={ThreeBarsIcon}
+                variant="invisible"
+                aria-label="Menu"
+                aria-expanded={isNavDrawerOpen}
+                onClick={() => setIsNavDrawerOpen(true)}
+              />
+              <NavDrawer isOpen={isNavDrawerOpen} onDismiss={() => setIsNavDrawerOpen(false)} pageMap={pageMap} />
+            </div>
+          </Stack>
+        </div>
       </div>
     </nav>
   )

package/components/layout/links-dropdown/LinksDropdown.module.css

@@ -0,0 +1,121 @@
+.dropdown {
+  position: relative;
+  margin-inline-end: auto;
+}
+
+.dropdownButton {
+  display: flex;
+  align-items: center;
+  background: none;
+  border: none;
+  cursor: pointer;
+  font-size: var(--base-font-size-16);
+  font-weight: var(--base-font-weight-500);
+  padding: var(--base-size-8) var(--base-size-12);
+  border-radius: var(--brand-borderRadius-medium);
+  color: var(--brand-color-text-default);
+}
+
+.dropdownButton:focus-visible {
+  outline: var(--base-size-4) solid var(--brand-color-focus);
+  outline-radius: var(--base-size-8);
+  outline-offset: var(--base-size-2);
+}
+
+.buttonText {
+  margin-right: var(--base-size-8);
+}
+
+.chevron {
+  color: var(--brand-color-text-muted);
+  transition: transform 0.2s ease;
+}
+
+.dropdownButton[aria-expanded='true'] .chevron {
+  transform: rotate(180deg);
+}
+
+.dropdownMenu {
+  position: absolute;
+  top: 100%;
+  left: 0;
+  min-width: 200px;
+  z-index: 100;
+  background-color: var(--brand-color-canvas-default);
+  border-radius: var(--brand-borderRadius-medium);
+  box-shadow: var(--shadow-floating-small);
+  margin-top: var(--base-size-4);
+  opacity: 0;
+  visibility: hidden;
+  transform: translateY(-10px);
+  transition:
+    opacity 0.2s ease,
+    transform 0.2s ease,
+    visibility 0s linear 0.2s;
+}
+
+.dropdownMenu.open {
+  opacity: 1;
+  visibility: visible;
+  transform: translateY(0);
+  transition:
+    opacity 0.2s ease,
+    transform 0.2s ease,
+    visibility 0s linear 0s;
+}
+
+.dropdownMenu ul {
+  list-style: none;
+  margin: 0;
+  padding: var(--base-size-8) 0;
+}
+
+.menuItem {
+  margin-inline: var(--base-size-8);
+  padding: 0;
+  position: relative;
+}
+
+.menuItemActive {
+  background-color: var(--brand-color-border-subtle);
+  border-radius: var(--brand-borderRadius-medium);
+}
+
+.menuItemActive::after {
+  content: '';
+  position: absolute;
+  top: calc(50% - var(--base-size-12));
+  left: calc(var(--base-size-8) * -1);
+  width: var(--base-size-4);
+  height: var(--base-size-24);
+  background: var(--base-color-scale-blue-5);
+  border-radius: var(--brand-borderRadius-medium);
+}
+
+.link:focus-visible {
+  position: relative;
+  outline: var(--base-size-4) solid var(--brand-color-focus);
+  border-radius: var(--brand-borderRadius-small);
+  z-index: 1;
+}
+
+.link {
+  display: block;
+  padding: var(--base-size-6) var(--base-size-8);
+  text-decoration: none;
+  color: var(--brand-color-text-default);
+  cursor: pointer;
+}
+
+.link:hover {
+  background-color: var(--brand-color-canvas-subtle);
+}
+
+.linkText {
+  display: block;
+  line-height: var(--base-size-20);
+}
+
+.externalLinkIcon {
+  margin-block-end: var(--base-size-8);
+}

package/components/layout/links-dropdown/LinksDropdown.tsx

@@ -0,0 +1,135 @@
+import React, {useState, useRef, useEffect, type HTMLProps, useCallback} from 'react'
+import clsx from 'clsx'
+import Link from 'next/link'
+import {ArrowUpRightIcon, TriangleDownIcon} from '@primer/octicons-react'
+import {Text} from '@primer/react-brand'
+
+import styles from './LinksDropdown.module.css'
+import type {ConfigContextLink} from '../../context/useConfig'
+
+export type LinksDropdownProps = {
+  items: ConfigContextLink[]
+} & HTMLProps<HTMLDivElement>
+
+export const LinksDropdown = ({items, className, ...props}: LinksDropdownProps) => {
+  const [isOpen, setIsOpen] = useState(false)
+  const buttonRef = useRef<HTMLButtonElement>(null)
+  const menuRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const closeDropdown = (event: MouseEvent) => {
+      if (
+        menuRef.current &&
+        !menuRef.current.contains(event.target as Node) &&
+        buttonRef.current &&
+        !buttonRef.current.contains(event.target as Node)
+      ) {
+        setIsOpen(false)
+        buttonRef.current.focus()
+      }
+    }
+
+    document.addEventListener('mousedown', closeDropdown)
+    return () => {
+      document.removeEventListener('mousedown', closeDropdown)
+    }
+  }, [menuRef, buttonRef])
+
+  useEffect(() => {
+    const menu = menuRef.current
+
+    if (!menu) return
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      switch (e.key) {
+        case 'Escape':
+          e.preventDefault()
+          setIsOpen(false)
+          buttonRef.current?.focus()
+          break
+        case 'Tab':
+          setTimeout(() => {
+            if (!menu.contains(document.activeElement)) {
+              setIsOpen(false)
+            }
+          }, 0)
+          break
+      }
+    }
+
+    menu.addEventListener('keydown', handleKeyDown)
+    return () => {
+      menu.removeEventListener('keydown', handleKeyDown)
+    }
+  }, [menuRef])
+
+  const handleToggle = useCallback(() => {
+    const nextIsOpen = !isOpen
+    setIsOpen(nextIsOpen)
+
+    if (nextIsOpen) {
+      setTimeout(() => {
+        document.querySelector<HTMLAnchorElement>(`#dropdown-item-0 a`)?.focus()
+      }, 0)
+    } else {
+      buttonRef.current?.focus()
+    }
+  }, [isOpen])
+
+  const activeItem = items.find(item => item.isActive) || items[0]
+
+  return (
+    <div className={clsx(styles.dropdown, className)} {...props}>
+      <button
+        ref={buttonRef}
+        className={styles.dropdownButton}
+        aria-haspopup="true"
+        aria-expanded={isOpen}
+        aria-controls="links-dropdown-menu"
+        onClick={handleToggle}
+      >
+        <Text size="200" className={styles.buttonText} variant="muted">
+          {activeItem.title}
+        </Text>
+        <TriangleDownIcon className={styles.chevron} size={16} />
+      </button>
+
+      <div
+        ref={menuRef}
+        id="links-dropdown-menu"
+        className={`${styles.dropdownMenu} ${isOpen ? styles.open : ''}`}
+        role="menu"
+        aria-labelledby="links-dropdown-button"
+      >
+        <ul role="menu">
+          {items.map((link, index) => (
+            <li
+              key={link.href}
+              className={clsx(styles.menuItem, link.isActive && styles.menuItemActive)}
+              role="menuitem"
+              id={`dropdown-item-${index}`}
+            >
+              <Link
+                href={link.href}
+                className={clsx(styles.link, link.isActive && styles.linkActive)}
+                onClick={() => {
+                  setIsOpen(false)
+                }}
+                tabIndex={isOpen ? 0 : -1}
+                aria-current={link.isActive ? 'page' : undefined}
+                {...(link.isExternal && {target: '_blank', rel: 'noopener noreferrer'})}
+              >
+                <Text className={styles.linkText} size="100" weight={link.isActive ? 'semibold' : 'normal'}>
+                  {link.title}
+                  {link.isExternal && (
+                    <ArrowUpRightIcon className={styles.externalLinkIcon} size={10} aria-label="External link" />
+                  )}
+                </Text>
+              </Link>
+            </li>
+          ))}
+        </ul>
+      </div>
+    </div>
+  )
+}

package/components/layout/nav-drawer/NavDrawer.tsx

@@ -4,18 +4,18 @@ import {IconButton, Link, ThemeProvider} from '@primer/react'
 import {XIcon} from '@primer/octicons-react'
 
 import {Drawer} from './Drawer'
-import type {PageMapItem} from 'nextra'
 import {Sidebar} from '../sidebar/Sidebar'
 import {useColorMode} from '../../context/color-modes/useColorMode'
 import styles from './NavDrawer.module.css'
+import type {PageMapItem} from 'nextra'
 
 type NavDrawerProps = {
   isOpen: boolean
   onDismiss: () => void
-  navItems?: PageMapItem[]
+  pageMap: PageMapItem[]
 }
 
-export function NavDrawer({isOpen, onDismiss, navItems}: NavDrawerProps) {
+export function NavDrawer({isOpen, onDismiss, pageMap}: NavDrawerProps) {
   const {colorMode} = useColorMode()
   return (
     <Drawer isOpen={isOpen} onDismiss={onDismiss}>
@@ -31,13 +31,11 @@ export function NavDrawer({isOpen, onDismiss, navItems}: NavDrawerProps) {
           </div>
           <div className={styles.navContainer}>{/* <PrimerNavItems items={primerNavItems} /> */}</div>
         </div>
-        {navItems && navItems.length > 0 ? (
-          <ThemeProvider colorMode={colorMode}>
-            <div className={styles.sidebarWrapper}>
-              <Sidebar pageMap={navItems} />
-            </div>
-          </ThemeProvider>
-        ) : null}
+        <ThemeProvider colorMode={colorMode}>
+          <div className={styles.sidebarWrapper}>
+            <Sidebar pageMap={pageMap} />
+          </div>
+        </ThemeProvider>
       </div>
     </Drawer>
   )

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

@@ -51,7 +51,7 @@ export type ThemeProps = PropsWithChildren<{
   pageMap: PageMapItem[]
 }>
 
-export function Theme({children, pageMap}: ThemeProps) {
+export function Theme({pageMap, children}: ThemeProps) {
   const pathname = usePathname()
 
   const normalizedPages = normalizePages({
@@ -116,7 +116,7 @@ export function Theme({children, pageMap}: ThemeProps) {
                 }}
               >
                 <SkipToMainContent href="#main">Skip to main content</SkipToMainContent>
-                <Header pageMap={pageMap} flatDocsDirectories={flatDocsDirectories} siteTitle={siteTitle} />
+                <Header flatDocsDirectories={flatDocsDirectories} siteTitle={siteTitle} pageMap={pageMap} />
               </PRCBox>
               <PageLayout rowGap="none" columnGap="none" padding="none" containerWidth="full">
                 <PageLayout.Content padding="normal">

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

@@ -3,10 +3,13 @@ import React from 'react'
 
 import {ColorModeProvider} from '../../context/color-modes/ColorModeProvider'
 import {Theme, ThemeProps} from './Theme'
-import {PageMapItem} from 'nextra'
+import {type ConfigContextLink, ConfigContextProvider} from '../../context/useConfig'
+import type {PageMapItem} from 'nextra'
 
 type Props = {
   pageMap: PageMapItem[]
+  headerLinks?: ConfigContextLink[]
+  sidebarLinks?: ConfigContextLink[]
 } & ThemeProps
 
 /**
@@ -15,12 +18,17 @@ type Props = {
  * To add custom layouts, create a new file in `pages/_layouts`
  * and export a component with the same name as the layout file
  */
-export default function Shell({children, pageMap, ...rest}: Props) {
+export default function Shell({children, headerLinks = [], sidebarLinks = [], ...rest}: Props) {
   return (
     <ColorModeProvider>
-      <Theme {...rest} pageMap={pageMap}>
-        {children}
-      </Theme>
+      <ConfigContextProvider
+        value={{
+          headerLinks,
+          sidebarLinks,
+        }}
+      >
+        <Theme {...rest}>{children}</Theme>
+      </ConfigContextProvider>
     </ColorModeProvider>
   )
 }

package/components/layout/sidebar/Sidebar.tsx

@@ -1,32 +1,26 @@
 import React, {useMemo} from 'react'
 import NextLink from 'next/link'
 import {NavList} from '@primer/react'
-import {Folder, MdxFile, PageMapItem} from 'nextra'
+import type {Folder, MdxFile, PageMapItem} from 'nextra'
 
 import styles from './Sidebar.module.css'
 import {LinkExternalIcon} from '@primer/octicons-react'
 import type {DocsItem, ExtendedPageItem} from '../../../index'
 import {hasChildren} from '../../../helpers/hasChildren'
 import {usePathname} from 'next/navigation'
-
-type SidebarProps = {
-  pageMap: PageMapItem[]
-}
+import {useConfig} from '../../context/useConfig'
 
 const hasShowTabs = (child: ExtendedPageItem): boolean => {
   return child.name === 'index' && (child as MdxFile).frontMatter?.['show-tabs'] === true
 }
 
-export function Sidebar({pageMap: pageMapIn}: SidebarProps) {
-  const pageMap = pageMapIn as ExtendedPageItem[]
+type SidebarProps = {
+  pageMap: PageMapItem[]
+}
 
+export function Sidebar({pageMap}: SidebarProps) {
   const pathname = usePathname()
-
-  const externalLinks = pageMap.filter(page => {
-    if (page.href && page.href.startsWith('http')) {
-      return page
-    }
-  })
+  const {sidebarLinks} = useConfig()
 
   /**
    * Sorts the incoming data so that folders with a menu-position frontmatter value
@@ -112,15 +106,23 @@ export function Sidebar({pageMap: pageMapIn}: SidebarProps) {
             </NavList.Group>
           )
         })}
-        {externalLinks.length > 0 && (
+        {sidebarLinks.length > 0 && (
           <NavList.Group title="" sx={{mb: 24}}>
-            {externalLinks.map(link => {
+            {sidebarLinks.map(link => {
               return (
-                <NavList.Item as={NextLink} key={link.title} href={link.href}>
+                <NavList.Item
+                  as={NextLink}
+                  key={link.title}
+                  href={link.href}
+                  {...(link.isExternal && {target: '_blank', rel: 'noopener noreferrer'})}
+                  aria-current={link.isActive ? 'page' : undefined}
+                >
                   {link.title}
-                  <NavList.TrailingVisual>
-                    <LinkExternalIcon />
-                  </NavList.TrailingVisual>
+                  {link.isExternal && (
+                    <NavList.TrailingVisual>
+                      <LinkExternalIcon />
+                    </NavList.TrailingVisual>
+                  )}
                 </NavList.Item>
               )
             })}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primer/doctocat-nextjs",
-  "version": "0.4.1-rc.afcbafc",
+  "version": "0.5.0-rc.6ee882c",
   "description": "A Next.js theme for building Primer documentation sites",
   "main": "index.js",
   "type": "module",

package/types.ts

@@ -12,6 +12,8 @@ export type ExtendedPageItem = PageMapItem & {
   name: string
   title: string
   href: string
+  type?: string
+  active?: boolean
 }
 
 export type FolderWithoutChildren = Omit<Folder, 'children'>