@primer/doctocat-nextjs 0.0.3-rc.4b671a6 → 0.0.4-rc.68fc11e

package/CHANGELOG.md

@@ -1,9 +1,47 @@
 # @primer/doctocat-nextjs
 
+## 0.0.4
+
+### Patch Changes
+
+- [#8](https://github.com/primer/doctocat-nextjs/pull/8) [`fd7f838`](https://github.com/primer/doctocat-nextjs/commit/fd7f83883152512b34dd7601346c03fe53e3ffb3) Thanks [@rezrah](https://github.com/rezrah)! - Added OpenGraph tags for improved social sharing experience.
+
+- [#8](https://github.com/primer/doctocat-nextjs/pull/8) [`0d0879b`](https://github.com/primer/doctocat-nextjs/commit/0d0879b8e732e74a50861e22a0ff534d0e191a45) Thanks [@rezrah](https://github.com/rezrah)! - Enabled related content navigation using `keywords` and `related` properties in Markdown frontmatter.
+
+  Example:
+
+  ```
+  ---
+  title: Page A
+  keywords: ['keyword', 'another keyword']
+  ---
+  ```
+
+  ```
+  ---
+  title: Page B
+  keywords: ['keyword', 'another keyword']
+  ---
+  ```
+
+  The matching keyword values above across both pages, will enable automatic related content navigation between the two pages.
+
+  or using the `related` property:
+
+  ```
+  ---
+  related: [{title: External link example, href: https://example.com}]
+  ---
+  ```
+
+- [#8](https://github.com/primer/doctocat-nextjs/pull/8) [`fd7f838`](https://github.com/primer/doctocat-nextjs/commit/fd7f83883152512b34dd7601346c03fe53e3ffb3) Thanks [@rezrah](https://github.com/rezrah)! - Fixed accessibility violations arising from duplicate landmarks and missing aria labels.
+
 ## 0.0.3
 
 ### Patch Changes
 
+- [`937f773`](https://github.com/primer/doctocat-nextjs/commit/937f77385bc6c4d2c6289d0a6f12122373789f73) Thanks [@rezrah](https://github.com/rezrah)! - Redesign index pages to match current Doctocat styles
+
 - [`7703a7b`](https://github.com/primer/doctocat-nextjs/commit/7703a7b86bc906ff981a7f864a9916c963a35087) Thanks [@rezrah](https://github.com/rezrah)! - Fixed code bg in dark mode and applied fixed width to toc to prevent layout shift
 
 ## 0.0.2

package/components/layout/header/Header.tsx

@@ -163,7 +163,11 @@ export function Header({pageMap, docsDirectories, siteTitle}: HeaderProps) {
   }, [])
 
   return (
-    <nav className={clsx(styles.Header, isSearchOpen && styles['Header--searchAreaOpen'])}>
+    <nav
+      className={clsx(styles.Header, isSearchOpen && styles['Header--searchAreaOpen'])}
+      role="navigation"
+      aria-label="Header Navigation"
+    >
       <Link href="/" className={styles.Header__siteTitle}>
         <MarkGithubIcon size={24} />
         <Text as="p" size="300" weight="semibold">

package/components/layout/index-cards/IndexCards.module.css

@@ -1,5 +1,12 @@
-.IndexCards {
-  --brand-Grid-spacing-margin: 0;
-  --brand-Card-maxWidth: 100%;
-  --brand-Grid-spacing-row: var(--brand-Grid-spacing-column-gap);
+.heading a {
+  color: var(--brand-InlineLink-color-rest);
+  text-decoration: none;
+}
+
+.heading a:hover {
+  text-decoration: underline;
+}
+
+.heading a:active {
+  color: var(--brand-InlineLink-color-pressed);
 }

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

@@ -1,9 +1,9 @@
 import React from 'react'
-import {Card, Grid} from '@primer/react-brand'
+import {Heading, Stack, Text} from '@primer/react-brand'
 import {Folder, MdxFile} from 'nextra'
 
-import styles from './IndexCards.module.css'
 import Link from 'next/link'
+import styles from './IndexCards.module.css'
 
 type IndexCardsProps = {
   route: string
@@ -25,22 +25,22 @@ export function IndexCards({route, folderData}: IndexCardsProps) {
   const filteredData = folderData.filter(item => item.kind === 'MdxPage' && item.route.includes(`${route}/`))
 
   return (
-    <Grid className={styles.IndexCards}>
+    <Stack direction="vertical" padding="none" gap="spacious">
       {filteredData.map((item: DocsItem) => {
-        if (item.kind !== 'MdxPage') return null
+        if (item.kind !== 'MdxPage' || !item.frontMatter) return null
+
         return (
-          <Grid.Column span={{medium: 6}} key={`cell-${item.route}`}>
-            <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>
+          <Stack direction="vertical" padding="none" gap="condensed" key={item.frontMatter.title}>
+            <Heading as="h2" size="6" className={styles.heading}>
+              <Link href={item.route} legacyBehavior passHref>
+                {item.frontMatter.title}
+              </Link>
+            </Heading>
+
+            {item.frontMatter.description && <Text as="p">{item.frontMatter.description}</Text>}
+          </Stack>
         )
       })}
-    </Grid>
+    </Stack>
   )
 }

package/components/layout/related-content-links/RelatedContentLinks.module.css

@@ -0,0 +1,4 @@
+.list {
+  margin-block: var(--base-size-24);
+  margin-inline-start: 0 !important;
+}

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

@@ -0,0 +1,34 @@
+import React from 'react'
+import {NavList} from '@primer/react'
+import {Text, 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 & {
+  title: string
+}
+
+export type RelatedContentLinksProps = {
+  links: RelatedContentLink[]
+}
+
+export function RelatedContentLinks({links}: RelatedContentLinksProps) {
+  if (!links.length) return null
+
+  return (
+    <div className="custom-component">
+      <Heading as="h2">Related content</Heading>
+      <UnorderedList className={styles.list}>
+        {links.map(page => (
+          <UnorderedList.Item key={page.route}>
+            <InlineLink href={page.route}>{page.title}</InlineLink>{' '}
+            {page.route.startsWith('http') ? <LinkExternalIcon /> : null}
+          </UnorderedList.Item>
+        ))}
+      </UnorderedList>
+    </div>
+  )
+}

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

@@ -36,6 +36,7 @@ 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'
 
 const {publicRuntimeConfig} = getConfig()
 
@@ -64,6 +65,55 @@ export function Theme({children, pageOpts}: NextraThemeLayoutProps) {
       ? ((data as Folder).children.filter(child => child.kind === 'MdxPage') as MdxFile[])
       : []
 
+  /**
+   * Uses a frontmatter 'keywords' value (as an array)
+   * to find adjacent pages that share the same values.
+   * @returns {RelatedContentLink[]}
+   */
+  const getRelatedPages = () => {
+    const currentPageKeywords = frontMatter.keywords || []
+    const relatedLinks = frontMatter['related'] || []
+    const matches: RelatedContentLink[] = []
+
+    // 1. Check keywords property and find local matches
+    for (const page of flatDocsDirectories) {
+      if (page.route === route) continue
+
+      if ('frontMatter' in page) {
+        const pageKeywords = page.frontMatter?.keywords || []
+        const intersection = pageKeywords.filter(keyword => currentPageKeywords.includes(keyword))
+
+        if (intersection.length) {
+          matches.push(page)
+        }
+      }
+    }
+
+    // 2. Check related property for internal and external links
+    for (const link of relatedLinks) {
+      if (!link.title || !link.href || link.href === route) continue
+
+      if (link.href.startsWith('/')) {
+        const page = flatDocsDirectories.find(localPage => localPage.route === link.href) as
+          | RelatedContentLink
+          | undefined
+
+        if (page) {
+          const entry = {
+            ...page,
+            title: link.title || page.title,
+            route: link.href || page.route,
+          }
+          matches.push(entry)
+        }
+      } else {
+        matches.push({...link, route: link.href})
+      }
+    }
+
+    return matches
+  }
+
   return (
     <>
       <BrandThemeProvider dir="ltr" colorMode={colorMode}>
@@ -71,7 +121,28 @@ export function Theme({children, pageOpts}: NextraThemeLayoutProps) {
           <BaseStyles>
             <Head>
               <title>{title}</title>
-              <meta name="og:image" content={frontMatter.image} />
+              {frontMatter.description && <meta name="description" content={frontMatter.description} />}
+              <meta property="og:type" content="website" />
+              <meta property="og:title" content={title} />
+              {frontMatter.description && <meta property="og:description" content={frontMatter.description} />}
+              <meta
+                property="og:image"
+                content={
+                  frontMatter.image ||
+                  'https://github.com/primer/brand/assets/19292210/8562a9a5-a1e4-4722-9ec7-47ebccd5901e'
+                }
+              />
+              {/* X (Twitter) OG */}
+              <meta name="twitter:card" content="summary_large_image" />
+              <meta name="twitter:title" content={title} />
+              {frontMatter.description && <meta name="twitter:description" content={frontMatter.description} />}
+              <meta
+                name="twitter:image"
+                content={
+                  frontMatter.image ||
+                  'https://github.com/primer/brand/assets/19292210/8562a9a5-a1e4-4722-9ec7-47ebccd5901e'
+                }
+              />
             </Head>
             <AnimationProvider runOnce visibilityOptions={1} autoStaggerChildren={false}>
               <Animate animate="fade-in">
@@ -92,7 +163,7 @@ export function Theme({children, pageOpts}: NextraThemeLayoutProps) {
                 </PRCBox>
                 <PageLayout rowGap="none" columnGap="none" padding="none" containerWidth="full">
                   <PageLayout.Content padding="normal">
-                    <main id="main">
+                    <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">
@@ -170,7 +241,14 @@ export function Theme({children, pageOpts}: NextraThemeLayoutProps) {
                               {isIndexPage ? (
                                 <IndexCards folderData={flatDocsDirectories} route={route} />
                               ) : (
-                                <MDXProvider components={getComponents()}>{children}</MDXProvider>
+                                <>
+                                  <MDXProvider components={getComponents()}>{children}</MDXProvider>
+                                  {getRelatedPages().length > 0 && (
+                                    <PRCBox sx={{pt: 5}}>
+                                      <RelatedContentLinks links={getRelatedPages()} />
+                                    </PRCBox>
+                                  )}
+                                </>
                               )}
                             </article>
                             <footer>
@@ -203,16 +281,22 @@ export function Theme({children, pageOpts}: NextraThemeLayoutProps) {
                             </footer>
                           </Stack>
                         </PRCBox>
-                        {!isHomePage && headings.length > 0 && (
-                          <PRCBox sx={{py: 2, pr: 3, display: ['none', null, null, null, 'block']}}>
-                            <TableOfContents headings={headings} />
+                        <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} />}
                           </PRCBox>
-                        )}
+                        </PRCBox>
                       </PRCBox>
-                    </main>
+                    </div>
                   </PageLayout.Content>
                   <PageLayout.Pane
-                    aria-label="Sticky pane"
+                    aria-label="Side navigation"
                     width="small"
                     sticky
                     padding="none"

package/components/layout/sidebar/Sidebar.tsx

@@ -55,7 +55,7 @@ export function Sidebar({pageMap}: SidebarProps) {
 
   return (
     <div className={styles.Sidebar}>
-      <NavList className={styles.NavList}>
+      <NavList className={styles.NavList} aria-label="Menu links">
         {reorderedPageMap.map(item => {
           if (item.kind === 'MdxPage' && item.route === '/') return null
 

package/components/layout/table-of-contents/TableOfContents.module.css

@@ -1,9 +1,3 @@
-.wrapper {
-  position: sticky;
-  top: var(--base-size-112);
-  width: 220px;
-}
-
 .heading {
   font-size: var(--base-size-12);
   padding-inline-start: var(--base-size-16);
@@ -15,6 +9,7 @@
   margin-block-end: var(--base-size-4);
   transition: transform var(--brand-animation-duration-fast) var(--brand-animation-easing-default);
 }
+
 .item[aria-current='location'] {
   transform: translateX(var(--base-size-4));
 }

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

@@ -61,7 +61,7 @@ export function TableOfContents({headings}: TableOfContentsProps) {
       <Text as="p" size="100" variant="muted" weight="normal" className={styles.heading}>
         On this page
       </Text>
-      <NavList>
+      <NavList aria-label="Table of contents">
         {depth2Headings.map(heading => (
           <NavList.Item
             className={styles.item}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primer/doctocat-nextjs",
-  "version": "0.0.3-rc.4b671a6",
+  "version": "0.0.4-rc.68fc11e",
   "description": "A Next.js theme for building Primer documentation sites",
   "main": "index.js",
   "scripts": {