Merge pull request #6 from primer/rezrah/add-mdx-overrides

add mdx overrides and heading anchors

.changeset/beige-points-worry.md

@@ -1,6 +1,5 @@
 ---
 '@primer/doctocat-nextjs': patch
-'doctocat-nextjs-site': patch
 ---
 
 Wrap links with Next's Link component

.changeset/points-worry-beige.md

@@ -0,0 +1,6 @@
+---
+'@primer/doctocat-nextjs': patch
+---
+
+- Add MDX to HTML overrides mechanism and apply to headings and anchors
+- Added anchor links to headings to match current functionality on primer.style

.github/workflows/deploy.yml

@@ -9,7 +9,7 @@ on:
   workflow_dispatch:
 
 env:
-  IS_PROD: true
+  IS_PROD: 'true'
 
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:

.github/workflows/deploy_preview.yml

@@ -4,23 +4,51 @@ on:
   pull_request:
 
 env:
-  IS_PROD: false
+  IS_PROD: 'false'
 
 permissions:
-  checks: write
   contents: read
-  deployments: write
   pages: write
   id-token: write
 
 jobs:
+  build:
+    if: ${{ github.repository == 'primer/doctocat-nextjs' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          cache: ${{ steps.detect-package-manager.outputs.manager }}
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build with Next.js
+        run: IS_PROD='false' npm run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: packages/site/out
+
   deploy:
     if: ${{ github.repository == 'primer/doctocat-nextjs' }}
-    name: Preview
-    # SHA for security hardening. Points at last verified HEAD of main branch.
-    uses: primer/.github/.github/workflows/deploy_preview.yml@0cec9b9914f358846163f2428663b58da41028c9
-    with:
-      node_version: 18
-      install: npm ci
-      build: npm run build
-      output_dir: packages/site/out
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v3
+        with:
+          preview: true

packages/site/next.config.js

@@ -3,7 +3,7 @@ const withDoctocat = require('@primer/doctocat-nextjs/doctocat.config')
 module.exports = {
   ...withDoctocat({
     output: 'export',
-    basePath: process.env.GITHUB_ACTIONS === 'true' && process.env.IS_PROD ? '/doctocat-nextjs' : '',
+    basePath: process.env.GITHUB_ACTIONS === 'true' && process.env.IS_PROD === 'false' ? '/doctocat-nextjs' : '',
     publicRuntimeConfig: {
       siteTitle: 'Doctocat',
       repo: 'https://github.com/primer/doctocat-nextjs',

packages/theme/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,7 @@ 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'
 
 const {publicRuntimeConfig} = getConfig()
 
@@ -162,7 +165,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}>

packages/theme/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;
+}

packages/theme/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,
+  }
+}