@primer/doctocat-nextjs 0.0.2-rc.1da8f9a → 0.0.2-rc.60745e5

package/CHANGELOG.md

@@ -6,4 +6,12 @@
 
 - [#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/root-layout/Theme.tsx

@@ -2,9 +2,11 @@ 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,
@@ -32,6 +34,8 @@ 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()
 
@@ -78,6 +82,7 @@ export function Theme({children, pageOpts}: NextraThemeLayoutProps) {
                     zIndex: 99,
                   }}
                 >
+                  <SkipToMainContent href="#main">Skip to main content</SkipToMainContent>
                   <Header
                     pageMap={pageMap}
                     docsDirectories={docsDirectories}
@@ -87,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">
@@ -132,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>
@@ -162,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

@@ -6,17 +6,7 @@ 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 = {
@@ -36,29 +26,6 @@ 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()
 
@@ -167,9 +134,7 @@ 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
@@ -178,7 +143,6 @@ export function Sidebar({pageMap}: SidebarProps) {
                   href={link.href}
                   target={isExternalUrl ? '_blank' : undefined}
                 >
-                  <NavList.LeadingVisual>{LeadingIcon && <LeadingIcon />}</NavList.LeadingVisual>
                   {link.title}
                   {isExternalUrl && (
                     <NavList.TrailingVisual>

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

@@ -0,0 +1,14 @@
+.SkipToMainContent {
+  position: absolute;
+  top: 0;
+  z-index: 999;
+  padding: var(--base-size-16);
+  background-color: var(--base-color-scale-blue-5);
+  color: var(--base-color-scale-white-0);
+  opacity: 0;
+}
+.SkipToMainContent:focus {
+  left: 0;
+  opacity: 1;
+  opacity: 1;
+}

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.1da8f9a",
+  "version": "0.0.2-rc.60745e5",
   "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'
   }[]
 }