@primer/doctocat-nextjs 0.0.2-rc.cdbd6bf → 0.0.2-rc.de031ea

package/CHANGELOG.md

@@ -4,4 +4,14 @@
 
 ### Patch Changes
 
+- [#4](https://github.com/primer/doctocat-nextjs/pull/4) [`4f28982`](https://github.com/primer/doctocat-nextjs/commit/4f28982e327e75f199f28fad987f1e827deafeb2) Thanks [@joseph-lozano](https://github.com/joseph-lozano)! - Wrap links with Next's Link component
+
+- [`6f21970`](https://github.com/primer/doctocat-nextjs/commit/6f21970c74f7635be89fc4cd20376d7fe5ca35e7) Thanks [@rezrah](https://github.com/rezrah)! - Switch hero image order with description and reduce `h2` block start margin
+
+- [#6](https://github.com/primer/doctocat-nextjs/pull/6) [`afd4e17`](https://github.com/primer/doctocat-nextjs/commit/afd4e1762f6294a14942d415c693319a874cd3fb) Thanks [@rezrah](https://github.com/rezrah)! - - Add MDX to HTML overrides mechanism and apply to headings and anchors
+
+  - Added anchor links to headings to match current functionality on primer.style
+
+- [`b49f218`](https://github.com/primer/doctocat-nextjs/commit/b49f218e9bbc2de720476e21888956bee6081967) Thanks [@rezrah](https://github.com/rezrah)! - Removed sidebar links and added skip to main content a11y link
+
 - [#2](https://github.com/primer/doctocat-nextjs/pull/2) [`2742b32`](https://github.com/primer/doctocat-nextjs/commit/2742b3214e7a53416d23f0459dc389f7c22cf5a1) Thanks [@rezrah](https://github.com/rezrah)! - Remove code blocks stylesheet, now merged into global.css

package/components/layout/header/Header.tsx

@@ -4,7 +4,7 @@ import {Heading, Stack, Text} from '@primer/react-brand'
 import clsx from 'clsx'
 import {MdxFile, PageMapItem} from 'nextra'
 import type {PageItem} from 'nextra/normalize-pages'
-import React, {useEffect, useMemo} from 'react'
+import React, {useCallback, useEffect, useMemo} from 'react'
 import {debounce} from 'lodash'
 
 import Link from 'next/link'
@@ -37,6 +37,12 @@ export function Header({pageMap, docsDirectories, siteTitle}: HeaderProps) {
   const [searchTerm, setSearchTerm] = React.useState<string | undefined>('')
   const [activeDescendant] = React.useState<number>(-1)
 
+  useEffect(() => {
+    if (isSearchOpen && inputRef.current) {
+      inputRef.current.focus()
+    }
+  }, [isSearchOpen])
+
   useEffect(() => {
     const handleKeyDown = (event: KeyboardEvent) => {
       if (event.key === 'Escape') {
@@ -152,6 +158,10 @@ export function Header({pageMap, docsDirectories, siteTitle}: HeaderProps) {
     alert(`Name: ${inputRef.current.value}`)
   }
 
+  const handleSearchButtonOpenClick = useCallback(() => {
+    setIsSearchOpen(true)
+  }, [])
+
   return (
     <nav className={clsx(styles.Header, isSearchOpen && styles['Header--searchAreaOpen'])}>
       <Link href="/" className={styles.Header__siteTitle}>
@@ -292,7 +302,7 @@ export function Header({pageMap, docsDirectories, siteTitle}: HeaderProps) {
             variant="invisible"
             aria-label={`Open search`}
             sx={{display: ['flex', null, 'none']}}
-            onClick={() => setIsSearchOpen(true)}
+            onClick={handleSearchButtonOpenClick}
           />
           <Box sx={{display: ['flex', null, 'none']}}>
             <IconButton

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

@@ -1,9 +1,9 @@
 import React from 'react'
 import {Card, Grid} from '@primer/react-brand'
 import {Folder, MdxFile} from 'nextra'
-import {useRouter} from 'next/router'
 
 import styles from './IndexCards.module.css'
+import Link from 'next/link'
 
 type IndexCardsProps = {
   route: string
@@ -22,7 +22,6 @@ type DocsItem = (MdxFile | FolderWithoutChildren) & {
 }
 
 export function IndexCards({route, folderData}: IndexCardsProps) {
-  const {basePath} = useRouter()
   const filteredData = folderData.filter(item => item.kind === 'MdxPage' && item.route.includes(`${route}/`))
 
   return (
@@ -31,12 +30,14 @@ export function IndexCards({route, folderData}: IndexCardsProps) {
         if (item.kind !== 'MdxPage') return null
         return (
           <Grid.Column span={{medium: 6}} key={`cell-${item.route}`}>
-            <Card href={`${basePath}${item.route}`} hasBorder style={{width: '100%'}}>
-              {item.frontMatter && <Card.Heading>{item.frontMatter.title}</Card.Heading>}
-              {item.frontMatter && item.frontMatter.description && (
-                <Card.Description>{item.frontMatter.description}</Card.Description>
-              )}
-            </Card>
+            <Link href={item.route} legacyBehavior passHref>
+              <Card href="#" hasBorder style={{width: '100%'}}>
+                {item.frontMatter && <Card.Heading>{item.frontMatter.title}</Card.Heading>}
+                {item.frontMatter && item.frontMatter.description && (
+                  <Card.Description>{item.frontMatter.description}</Card.Description>
+                )}
+              </Card>
+            </Link>
           </Grid.Column>
         )
       })}

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

@@ -1,4 +1,5 @@
 import React from 'react'
+import NextLink from 'next/link'
 import {Box, IconButton, Link, ThemeProvider} from '@primer/react'
 import {XIcon} from '@primer/octicons-react'
 
@@ -34,7 +35,7 @@ export function NavDrawer({isOpen, onDismiss, navItems}: NavDrawerProps) {
             }}
           >
             <Box sx={{py: 20, pl: 4, pr: 3, alignItems: 'center', justifyContent: 'space-between', display: 'flex'}}>
-              <Link href="https://primer.style" sx={{fontWeight: 'bold', color: 'inherit'}}>
+              <Link as={NextLink} href="https://primer.style" sx={{fontWeight: 'bold', color: 'inherit'}}>
                 Explore
               </Link>
               <IconButton icon={XIcon} aria-label="Close" onClick={onDismiss} variant="invisible" />

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

@@ -1,9 +1,12 @@
 import React, {useMemo} from 'react'
+import NextLink from 'next/link'
 import Head from 'next/head'
 import type {Folder, MdxFile, NextraThemeLayoutProps} from 'nextra'
+import {MDXProvider} from 'nextra/mdx'
 import {useFSRoute} from 'nextra/hooks'
 import {PencilIcon} from '@primer/octicons-react'
 import {BaseStyles, Box as PRCBox, Breadcrumbs, PageLayout, ThemeProvider} from '@primer/react'
+
 import {
   Animate,
   AnimationProvider,
@@ -31,12 +34,14 @@ 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'
 
 const {publicRuntimeConfig} = getConfig()
 
 export function Theme({children, pageOpts}: NextraThemeLayoutProps) {
   const {title, frontMatter, headings, filePath, pageMap, route} = pageOpts
-  const {locale = 'en-US', defaultLocale, basePath} = useRouter()
+  const {locale = 'en-US', defaultLocale} = useRouter()
   const fsPath = useFSRoute()
   const {colorMode} = useColorMode()
   const {activePath, topLevelNavbarItems, docsDirectories, flatDocsDirectories} = useMemo(
@@ -77,6 +82,7 @@ export function Theme({children, pageOpts}: NextraThemeLayoutProps) {
                     zIndex: 99,
                   }}
                 >
+                  <SkipToMainContent href="#main">Skip to main content</SkipToMainContent>
                   <Header
                     pageMap={pageMap}
                     docsDirectories={docsDirectories}
@@ -86,7 +92,7 @@ export function Theme({children, pageOpts}: NextraThemeLayoutProps) {
                 </PRCBox>
                 <PageLayout rowGap="none" columnGap="none" padding="none" containerWidth="full">
                   <PageLayout.Content padding="normal">
-                    <main>
+                    <main 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">
@@ -96,7 +102,8 @@ export function Theme({children, pageOpts}: NextraThemeLayoutProps) {
                                   <Breadcrumbs>
                                     {siteTitle && (
                                       <Breadcrumbs.Item
-                                        href={basePath || '/'}
+                                        as={NextLink}
+                                        href="/"
                                         sx={{
                                           color: 'var(--brand-InlineLink-color-rest)',
                                         }}
@@ -107,8 +114,9 @@ export function Theme({children, pageOpts}: NextraThemeLayoutProps) {
                                     {activePath.map((item, index) => {
                                       return (
                                         <Breadcrumbs.Item
+                                          as={NextLink}
                                           key={item.name}
-                                          href={`${basePath}${item.route}`}
+                                          href={item.route}
                                           selected={index === activePath.length - 1}
                                           sx={{
                                             textTransform: 'capitalize',
@@ -129,16 +137,16 @@ export function Theme({children, pageOpts}: NextraThemeLayoutProps) {
                                         {frontMatter.title}
                                       </Heading>
                                     )}
-                                    {frontMatter.image && (
-                                      <Box paddingBlockEnd={16}>
-                                        <Hero.Image src={frontMatter.image} alt={frontMatter['image-alt']} />
-                                      </Box>
-                                    )}
                                     {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>
@@ -159,7 +167,11 @@ export function Theme({children, pageOpts}: NextraThemeLayoutProps) {
                               </>
                             )}
                             <article className={route !== '/' && !isIndexPage ? bodyStyles.Prose : ''}>
-                              {isIndexPage ? <IndexCards folderData={flatDocsDirectories} route={route} /> : children}
+                              {isIndexPage ? (
+                                <IndexCards folderData={flatDocsDirectories} route={route} />
+                              ) : (
+                                <MDXProvider components={getComponents()}>{children}</MDXProvider>
+                              )}
                             </article>
                             <footer>
                               <Box marginBlockStart={64}>

package/components/layout/sidebar/Sidebar.tsx

@@ -1,21 +1,12 @@
 import React, {useMemo} from 'react'
+import NextLink from 'next/link'
 import {NavList} from '@primer/react'
 import {Folder, MdxFile, PageMapItem} from 'nextra'
 import {useRouter} from 'next/router'
 import getConfig from 'next/config'
 
 import styles from './Sidebar.module.css'
-import {
-  BookmarkIcon,
-  BrowserIcon,
-  Icon,
-  ImageIcon,
-  LinkExternalIcon,
-  OrganizationIcon,
-  RepoIcon,
-  StackIcon,
-  StarIcon,
-} from '@primer/octicons-react'
+import {LinkExternalIcon} from '@primer/octicons-react'
 import type {ThemeConfig} from '../../../index'
 
 type SidebarProps = {
@@ -35,32 +26,8 @@ type DocsItem = (MdxFile | FolderWithoutChildren) & {
 
 const {publicRuntimeConfig} = getConfig()
 
-function getOcticonForType(type?: string): Icon | undefined {
-  if (!type) return undefined
-
-  switch (type) {
-    case 'repo':
-      return RepoIcon
-    case 'org':
-      return OrganizationIcon
-    case 'bookmark':
-      return BookmarkIcon
-    case 'star':
-      return StarIcon
-    case 'browser':
-      return BrowserIcon
-    case 'stack':
-      return StackIcon
-    case 'img':
-      return ImageIcon
-    default:
-      return StarIcon
-  }
-}
-
 export function Sidebar({pageMap}: SidebarProps) {
   const router = useRouter()
-  const basePath = router.basePath
 
   const {sidebarLinks}: ThemeConfig = publicRuntimeConfig
 
@@ -94,7 +61,7 @@ export function Sidebar({pageMap}: SidebarProps) {
 
           if (item.kind === 'MdxPage') {
             return (
-              <NavList.Item key={item.name} href={`${basePath}${item.route}`} sx={{textTransform: 'capitalize'}}>
+              <NavList.Item as={NextLink} key={item.name} href={item.route} sx={{textTransform: 'capitalize'}}>
                 {item.frontMatter?.title ?? item.name}
               </NavList.Item>
             )
@@ -109,7 +76,7 @@ export function Sidebar({pageMap}: SidebarProps) {
             const shouldShowTabs = indexPage.frontMatter?.['show-tabs'] ?? false
             if (shouldShowTabs) {
               return (
-                <NavList.Item key={indexPage.name} href={`${basePath}${indexPage.route}`}>
+                <NavList.Item as={NextLink} key={indexPage.name} href={indexPage.route}>
                   {(indexPage as MdxFile).frontMatter?.title || item.name}
                 </NavList.Item>
               )
@@ -129,8 +96,9 @@ export function Sidebar({pageMap}: SidebarProps) {
                       if (child.kind === 'MdxPage') {
                         return (
                           <NavList.Item
+                            as={NextLink}
                             key={child.name}
-                            href={`${basePath}${child.route}`}
+                            href={child.route}
                             aria-current={child.route === router.pathname ? 'page' : undefined}
                           >
                             {(child as MdxFile).frontMatter?.title || item.name}
@@ -144,8 +112,9 @@ export function Sidebar({pageMap}: SidebarProps) {
                         )
                         return (
                           <NavList.Item
-                            key={`${(landingPageItem as MdxFile).route}`}
-                            href={`${basePath}${(landingPageItem as MdxFile).route}`}
+                            as={NextLink}
+                            key={(landingPageItem as MdxFile).route}
+                            href={(landingPageItem as MdxFile).route}
                             sx={{textTransform: 'capitalize'}}
                             aria-current={(landingPageItem as MdxFile).route === router.pathname ? 'page' : undefined}
                           >
@@ -165,13 +134,15 @@ export function Sidebar({pageMap}: SidebarProps) {
         {sidebarLinks && sidebarLinks.length > 0 && (
           <NavList.Group title="" sx={{mb: 24}}>
             {sidebarLinks.map(link => {
-              const {leadingIcon} = link
               const isExternalUrl = link.href.startsWith('http')
-              const LeadingIcon = getOcticonForType(leadingIcon)
 
               return (
-                <NavList.Item key={link.title} href={link.href} target={isExternalUrl ? '_blank' : undefined}>
-                  <NavList.LeadingVisual>{LeadingIcon && <LeadingIcon />}</NavList.LeadingVisual>
+                <NavList.Item
+                  as={NextLink}
+                  key={link.title}
+                  href={link.href}
+                  target={isExternalUrl ? '_blank' : undefined}
+                >
                   {link.title}
                   {isExternalUrl && (
                     <NavList.TrailingVisual>

package/components/layout/skip-to-main-content/SkipToMainContent.module.css

@@ -0,0 +1,17 @@
+.SkipToMainContent {
+  position: absolute;
+  top: 0;
+  left: 0;
+  z-index: 999;
+  padding: var(--base-size-16);
+  background-color: var(--base-color-scale-blue-5);
+  color: var(--base-color-scale-white-0);
+}
+.SkipToMainContent:not(:focus) {
+  clip: rect(1px, 1px, 1px, 1px);
+  clip-path: inset(50%);
+  height: 1px;
+  width: 1px;
+  margin: -1px;
+  padding: 0px;
+}

package/components/layout/skip-to-main-content/SkipToMainContent.tsx

@@ -0,0 +1,14 @@
+import React, {HTMLAttributes, PropsWithChildren} from 'react'
+import styles from './SkipToMainContent.module.css'
+
+type SkipToMainContentProps = {
+  href: string
+} & HTMLAttributes<HTMLAnchorElement>
+
+export function SkipToMainContent({children, href, ...rest}: PropsWithChildren<SkipToMainContentProps>) {
+  return (
+    <a href={href} className={styles.SkipToMainContent} {...rest}>
+      {children}
+    </a>
+  )
+}

package/components/layout/table-of-contents/TableOfContents.tsx

@@ -1,4 +1,4 @@
-import React, {useEffect} from 'react'
+import React, {useEffect, useMemo} from 'react'
 import {NavList} from '@primer/react'
 import {Text} from '@primer/react-brand'
 import {Heading as HeadingType} from 'nextra'
@@ -10,6 +10,8 @@ type TableOfContentsProps = {
 }
 
 export function TableOfContents({headings}: TableOfContentsProps) {
+  const depth2Headings = useMemo(() => headings.filter(heading => heading.depth === 2), [headings])
+
   useEffect(() => {
     const observer = new IntersectionObserver(
       entries => {
@@ -40,7 +42,7 @@ export function TableOfContents({headings}: TableOfContentsProps) {
       },
     )
 
-    for (const heading of headings) {
+    for (const heading of depth2Headings) {
       const el = document.getElementById(heading.id)
       if (el) {
         observer.observe(el)
@@ -50,7 +52,7 @@ export function TableOfContents({headings}: TableOfContentsProps) {
     return () => {
       observer.disconnect()
     }
-  }, [headings])
+  }, [depth2Headings])
 
   return (
     <aside className={styles.wrapper}>
@@ -58,7 +60,7 @@ export function TableOfContents({headings}: TableOfContentsProps) {
         On this page
       </Text>
       <NavList>
-        {headings.map(heading => (
+        {depth2Headings.map(heading => (
           <NavList.Item
             className={styles.item}
             key={heading.id}

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

@@ -0,0 +1,14 @@
+.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

@@ -0,0 +1,43 @@
+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,
+  }
+}

package/css/prose.module.css

@@ -129,15 +129,12 @@
   letter-spacing: var(--brand-heading-letterSpacing-300);
 }
 
-.Prose :is(h1, h2, h3) {
-  --spacing: var(--base-size-64);
-}
-
 .Prose :is(h1) {
+  --spacing: var(--base-size-64);
   margin-block-end: var(--spacing);
 }
 
-.Prose :is(h1, h2, h3) + * {
+.Prose :is(h2, h3) + * {
   --spacing: var(--base-size-40);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primer/doctocat-nextjs",
-  "version": "0.0.2-rc.cdbd6bf",
+  "version": "0.0.2-rc.de031ea",
   "description": "A Next.js theme for building Primer documentation sites",
   "main": "index.js",
   "scripts": {

package/types.ts

@@ -3,6 +3,5 @@ export type ThemeConfig = {
   sidebarLinks?: {
     title: string
     href: string
-    leadingIcon?: 'repo' | 'org' | 'bookmark' | 'star' | 'img' | 'browser' | 'stack'
   }[]
 }