@primer/doctocat-nextjs 0.0.0-20250625111807 → 0.0.0-20250626090518

package/CHANGELOG.md

@@ -1,16 +1,16 @@
 # @primer/doctocat-nextjs
 
-## 0.0.0-20250625111807
+## 0.0.0-20250626090518
 
 ### Patch Changes
 
 - Fake entry to force publishing
 
-## 0.0.0-20250625111805
+## 0.5.4
 
 ### Patch Changes
 
-- [#51](https://github.com/primer/doctocat-nextjs/pull/51) [`b0e2e2a`](https://github.com/primer/doctocat-nextjs/commit/b0e2e2ae3b6c5f61f3de8e40eecb789e577fb8a3) Thanks [@rezrah](https://github.com/rezrah)! - Add auto-collapsed React code blocks for large code snippets. This feature only applies to code fences with the `jsx live` language identifiers.
+- [#51](https://github.com/primer/doctocat-nextjs/pull/51) [`4c76c4f`](https://github.com/primer/doctocat-nextjs/commit/4c76c4f5ccd248ec7d1f448c054808287a3ff51d) Thanks [@rezrah](https://github.com/rezrah)! - Add auto-collapsed React code blocks for large code snippets. This feature only applies to code fences with the `jsx live` language identifiers.
 
   E.g.
 
@@ -19,8 +19,11 @@
   ```
 
 - [#48](https://github.com/primer/doctocat-nextjs/pull/48) [`ce73c24`](https://github.com/primer/doctocat-nextjs/commit/ce73c24b2e4e924667bf7446a504bd88d8f2ccf0) Thanks [@rezrah](https://github.com/rezrah)! - - Fix inline code font-size in markdown headings. Now inherits size used in the heading.
+
   - Increased spacing below React code blocks, which was previously too small.
 
+- [#50](https://github.com/primer/doctocat-nextjs/pull/50) [`5d67989`](https://github.com/primer/doctocat-nextjs/commit/5d679895408c1a58342419692db4234dfddefd80) Thanks [@rezrah](https://github.com/rezrah)! - Add `menu-position` frontmatter support for custom sidebar navigation ordering
+
 ## 0.5.3
 
 ### Patch Changes

package/components/layout/code-block/ReactCodeBlock.tsx

@@ -1,5 +1,5 @@
 'use client'
-import React, {PropsWithChildren, useCallback, useState, useRef, useEffect, useId} from 'react'
+import React, {type PropsWithChildren, useCallback, useState, useRef, useEffect, useId} from 'react'
 import clsx from 'clsx'
 import {LiveProvider, LiveEditor, LiveError, LivePreview} from 'react-live'
 import {useColorMode} from '../../context/color-modes/useColorMode'
@@ -21,6 +21,15 @@ type ReactCodeBlockProps = {
   jsxScope: Record<string, unknown>
 } & PropsWithChildren<HTMLElement>
 
+const getFocusableElements = () => {
+  const focusableElementsQuery = 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+
+  return Array.from(document.querySelectorAll<HTMLElement>(focusableElementsQuery)).filter(el => {
+    const style = window.getComputedStyle(el)
+    return style.display !== 'none' && style.visibility !== 'hidden' && !el.hasAttribute('disabled')
+  })
+}
+
 export function ReactCodeBlock(props: ReactCodeBlockProps) {
   const uniqueId = useId()
   const {colorMode, setColorMode} = useColorMode()
@@ -31,6 +40,7 @@ export function ReactCodeBlock(props: ReactCodeBlockProps) {
   const [isCodePaneCollapsed, setIsCodePaneCollapsed] = useState<boolean | null>(null)
   const [initialPosition, setInitialPosition] = useState<number | null>(null)
   const editorRef = useRef<HTMLDivElement>(null)
+  const resetButtonRef = useRef<HTMLButtonElement>(null)
   const shouldShowPreview = ['tsx', 'jsx'].includes(props['data-language'])
 
   // scroll back to the initial y pos on collapse state change
@@ -84,6 +94,41 @@ export function ReactCodeBlock(props: ReactCodeBlockProps) {
 
   const noInline = props['data-filename'] === 'noinline' || false
 
+  useEffect(() => {
+    const editor = editorRef.current
+
+    if (!editor) return
+
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== 'Tab') {
+        return
+      }
+
+      if (e.shiftKey) {
+        e.preventDefault()
+        // We know that the previous focusable element is always the reset button
+        resetButtonRef.current?.focus()
+        return
+      }
+
+      const focusableElements = getFocusableElements()
+
+      const currentIndex = focusableElements.findIndex(el => el === resetButtonRef.current)
+
+      if (currentIndex !== -1) {
+        e.preventDefault()
+        const nextIndex = currentIndex + 1
+        focusableElements[nextIndex]?.focus()
+      }
+    }
+
+    editor.addEventListener('keydown', onKeyDown)
+
+    return () => {
+      editor.removeEventListener('keydown', onKeyDown)
+    }
+  }, [])
+
   return (
     <>
       <LiveProvider transformCode={transformCodeWithBasePath} code={code} scope={props.jsxScope} noInline={noInline}>
@@ -117,7 +162,7 @@ export function ReactCodeBlock(props: ReactCodeBlockProps) {
             <Button size="small" leadingVisual={CopyIcon} onClick={handleCopy}>
               Copy
             </Button>
-            <Button size="small" leadingVisual={UndoIcon} onClick={handleReset}>
+            <Button size="small" leadingVisual={UndoIcon} onClick={handleReset} ref={resetButtonRef}>
               Reset
             </Button>
           </div>

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

@@ -149,22 +149,40 @@ export function Theme({pageMap, children}: ThemeProps) {
                                     {activeHeaderLink ? activeHeaderLink.title : siteTitle}
                                   </Breadcrumbs.Item>
                                 )}
-                                {activePath.map((item, index) => {
-                                  return (
+                                {activePath.reduce((acc, item, index, items) => {
+                                  // Skip duplicate item for index pages without tab-label
+                                  if (
+                                    index > 0 &&
+                                    item.route === items[index - 1].route &&
+                                    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+                                    !item.frontMatter?.['tab-label']
+                                  ) {
+                                    return acc
+                                  }
+
+                                  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+                                  const itemTitle = item.frontMatter?.['tab-label'] || item.title
+                                  const isLastItem = index === items.length - 1
+
+                                  acc.push(
                                     <Breadcrumbs.Item
                                       as={NextLink}
-                                      key={item.name}
+                                      key={`${item.name}-${index}`}
                                       href={item.route}
-                                      selected={index === activePath.length - 1}
+                                      selected={isLastItem}
                                       sx={{
                                         textTransform: 'capitalize',
                                         color: 'var(--brand-InlineLink-color-rest)',
+                                        pointerEvents: isLastItem ? 'none' : undefined,
+                                        cursor: isLastItem ? 'default' : undefined,
                                       }}
                                     >
-                                      {item.title.replace(/-/g, ' ')}
-                                    </Breadcrumbs.Item>
+                                      {itemTitle.replace(/-/g, ' ')}
+                                    </Breadcrumbs.Item>,
                                   )
-                                })}
+
+                                  return acc
+                                }, [] as React.ReactNode[])}
                               </Breadcrumbs>
                             )}
 

package/components/layout/sidebar/Sidebar.tsx

@@ -82,7 +82,29 @@ export function Sidebar({pageMap}: SidebarProps) {
                 <NextLink href={item.route}>{subNavName}</NextLink>
               </NavList.GroupHeading>
               {item.children
-                .sort((a, b) => ((a as MdxFile).name === 'index' ? -1 : (b as MdxFile).name === 'index' ? 1 : 0)) // puts index page first
+                .sort((a, b) => {
+                  // make sure index page is first
+                  if ((a as MdxFile).name === 'index') return -1
+                  if ((b as MdxFile).name === 'index') return 1
+
+                  // Check for menu-position property in frontmatter
+                  const aPos = (a as MdxFile).frontMatter?.['menu-position']
+                  const bPos = (b as MdxFile).frontMatter?.['menu-position']
+
+                  // If both have menu-position, sort by menu-position
+                  if (typeof aPos === 'number' && typeof bPos === 'number') {
+                    return aPos - bPos
+                  }
+
+                  // If only one has menu-position, it comes first
+                  if (typeof aPos === 'number') return -1
+                  if (typeof bPos === 'number') return 1
+
+                  // Neither has menu-position, sort alphabetically by title or name
+                  const aTitle = (a as MdxFile).frontMatter?.title || (a as MdxFile).name
+                  const bTitle = (b as MdxFile).frontMatter?.title || (b as MdxFile).name
+                  return aTitle.localeCompare(bTitle)
+                })
                 // only show index page if it has show-tabs
                 .filter(child => (child as MdxFile).name !== 'index' || hasShowTabs(child as ExtendedPageItem))
                 .map(child => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primer/doctocat-nextjs",
-  "version": "0.0.0-20250625111807",
+  "version": "0.0.0-20250626090518",
   "description": "A Next.js theme for building Primer documentation sites",
   "main": "index.js",
   "type": "module",

package/types.ts

@@ -31,6 +31,7 @@ export type FrontMatter = {
   description?: string
   filePath?: string
   keywords?: string[]
+  menu_position?: number
   related?: {
     title: string
     href: string