hide On This Page TOC's title themeConfig.toc.title when there is…

… no toc links (#3954) * fix and take docs update from git stash * prettier
shuding · Jan 16, 2025 · 865e2ab · 865e2ab
1 parent 22c44bd
commit 865e2ab
Show file tree

Hide file tree

Showing 37 changed files with 537 additions and 464 deletions.
diff --git a/.changeset/wild-planes-collect.md b/.changeset/wild-planes-collect.md
@@ -0,0 +1,5 @@
+---
+"nextra-theme-docs": patch
+---
+
+hide `On This Page` TOC's title `themeConfig.toc.title` when there is no toc links
diff --git a/docs/app/_meta.global.ts → docs/app/_meta.global.tsx b/docs/app/_meta.global.ts → docs/app/_meta.global.tsx
@@ -1,3 +1,23 @@
+import { LinkArrowIcon } from 'nextra/icons'
+import type { FC, ReactNode } from 'react'
+import { useMDXComponents } from '../mdx-components'
+
+// eslint-disable-next-line react-hooks/rules-of-hooks -- isn't react hook
+const { code: Code } = useMDXComponents()
+
+const ExternalLink: FC<{ children: ReactNode }> = ({ children }) => {
+  return (
+    <>
+      <Code>{children}</Code>&thinsp;
+      <LinkArrowIcon
+        // based on font-size
+        height="1em"
+        className="x:inline x:align-baseline x:shrink-0"
+      />
+    </>
+  )
+}
+
 export default {
   index: {
     type: 'page',
@@ -8,9 +28,41 @@ export default {
     title: 'Documentation',
     items: {
       index: '',
+      'file-conventions': {
+        items: {
+          _: {
+            type: 'separator',
+            title: 'Files'
+          },
+          'page-file': <Code>page.mdx</Code>,
+          'meta-file': <Code>_meta.js</Code>,
+          'mdx-components-file': <Code>mdx-components.js</Code>,
+          _2: {
+            href: 'https://nextjs.org/docs/app/api-reference/file-conventions/page',
+            title: <ExternalLink>page.jsx</ExternalLink>
+          },
+          _3: {
+            href: 'https://nextjs.org/docs/app/api-reference/file-conventions/layout',
+            title: <ExternalLink>layout.jsx</ExternalLink>
+          },
+          _4: {
+            type: 'separator',
+            title: 'Top-Level Folders'
+          },
+          'content-directory': <Code>content</Code>,
+          'src-directory': <Code>src</Code>,
+          _5: {
+            href: 'https://nextjs.org/docs/app/building-your-application/routing',
+            title: <ExternalLink>app</ExternalLink>
+          },
+          _6: {
+            href: 'https://nextjs.org/docs/app/building-your-application/optimizing/static-assets',
+            title: <ExternalLink>public</ExternalLink>
+          }
+        }
+      },
       guide: {
         items: {
-          'organize-files': '',
           markdown: '',
           'syntax-highlighting': '',
           link: '',
@@ -21,11 +73,7 @@ export default {
           'static-exports': '',
           search: '',
           'github-alert-syntax': '',
-          turbopack: '',
-          _: {
-            type: 'separator',
-            title: 'File Conventions'
-          }
+          turbopack: ''
         }
       },
       advanced: {
@@ -66,7 +114,6 @@ export default {
       'docs-theme': {
         items: {
           start: '',
-          'page-configuration': '',
           'built-ins': {
             items: {
               layout: ''

diff --git a/docs/app/about/page.mdx b/docs/app/about/page.mdx
@@ -55,7 +55,7 @@ product.
 
 |    Name     |                   Description                    |                Preview                |
 | :---------: | :----------------------------------------------: | :-----------------------------------: |
-|    Icon     | Useful for favicons, app icons, link icons, etc. |     ![Nextra icon](/favicon.svg)      |
+|    Icon     | Useful for favicons, app icons, link icons, etc. |      ![Nextra icon](../icon.svg)      |
 |    Logo     |                 Full Nextra logo                 |       ![Nextra logo](/logo.svg)       |
 | Social Card |              The Nextra social card              | ![Nextra card](/opengraph-image.jpeg) |
 

diff --git a/docs/app/docs/advanced/latex/page.mdx b/docs/app/docs/advanced/latex/page.mdx
@@ -58,7 +58,7 @@ x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}
 
 will be rendered as:
 
-<div className="mt-6 rounded-xl border border-gray-200 p-4 dark:border-gray-900">
+<div className="mt-6 rounded-xl border p-4 nextra-border">
   The **Pythagorean equation** is $a=\sqrt{b^2 + c^2}$ and the quadratic formula:
 
   ```math

diff --git a/docs/app/docs/advanced/table/page.mdx b/docs/app/docs/advanced/table/page.mdx
@@ -66,4 +66,4 @@ In this example, the tags `<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, and
 `<td>` will be replaced with corresponding MDX components, allowing for
 customized styling.
 
-[^1]: https://mdxjs.com/packages/vue/#usemdxcomponentscomponents
+[^1]: https://mdxjs.com/packages/react/#usemdxcomponentscomponents
diff --git a/docs/app/docs/custom-theme/page.mdx b/docs/app/docs/custom-theme/page.mdx
@@ -143,13 +143,6 @@ export default function Layout({ children, pageOpts }: NextraThemeLayoutProps) {
 ```
 
 There are other item kinds such as `Folder` (for directories) and `Meta` (for
-`_meta.js` files). All the items are typed so you can easily know the
-properties.
+`_meta` files). All the items are typed so you can easily know the properties.
 
 </Steps>
-
-## Advanced Usage
-
-> [!WARNING]
->
-> Docs for advanced usage are under construction.
diff --git a/docs/app/docs/docs-theme/built-ins/layout/page.mdx b/docs/app/docs/docs-theme/built-ins/layout/page.mdx
@@ -252,7 +252,7 @@ sidebarTitle: Getting Started 🚀
 
 The priority of the sidebar title is as follows:
 
-1. `title` property from `_meta.js` file
+1. `title` property from `_meta` file
 1. Front matter `sidebarTitle`
 1. Front matter `title`
 1. Filename of the page formatted with [Title](https://title.sh)

diff --git a/docs/app/docs/docs-theme/built-ins/navbar/page.mdx b/docs/app/docs/docs-theme/built-ins/navbar/page.mdx
@@ -22,12 +22,12 @@ import { ToggleVisibilitySection } from 'components/toggle-visibility-section'
 
 The logo of the website rendered on the navbar.
 
-<Screenshot>![Customized Logo](/assets/docs/logo.png)</Screenshot>
-
-<div className="mt-8 text-center text-sm">
-  [Live example on
-  StackBlitz](https://stackblitz.com/edit/nextra-2-docs-yrlccm?file=theme.config.jsx)
-</div>
+<figure>
+  <Screenshot>![Customized Logo](/assets/docs/logo.png)</Screenshot>
+  <br />
+  {/* prettier-ignore */}
+  <figcaption>[Live example on StackBlitz](https://stackblitz.com/edit/nextra-2-docs-yrlccm?file=theme.config.jsx)</figcaption>
+</figure>
 
 ```jsx filename="app/layout.jsx"
 <Navbar

diff --git a/docs/app/docs/docs-theme/page.mdx b/docs/app/docs/docs-theme/page.mdx
@@ -5,7 +5,7 @@ sidebarTitle: Docs Theme
 
 # Nextra Docs Theme
 
-import { BoxIcon, ChevronRightIcon, RowsIcon } from '@components/icons'
+import { BoxIcon, ChevronRightIcon } from '@components/icons'
 import { Cards } from 'nextra/components'
 import { MDXRemote } from 'nextra/mdx-remote'
 import { createIndexPage, getPageMap } from 'nextra/page-map'
@@ -15,7 +15,6 @@ import { createIndexPage, getPageMap } from 'nextra/page-map'
   components={{
     Cards,
     ChevronRightIcon,
-    RowsIcon,
     BoxIcon
   }}
 />
diff --git a/...app/docs/guide/content-directory/page.mdx → ...le-conventions/content-directory/page.mdx b/...app/docs/guide/content-directory/page.mdx → ...le-conventions/content-directory/page.mdx
@@ -1,5 +1,6 @@
 ---
 icon: FolderIcon
+sidebarTitle: content
 ---
 
 import fs from 'node:fs/promises'

diff --git a/...p/docs/guide/mdx-components-file/page.mdx → ...-conventions/mdx-components-file/page.mdx b/...p/docs/guide/mdx-components-file/page.mdx → ...-conventions/mdx-components-file/page.mdx
@@ -1,5 +1,6 @@
 ---
 icon: MdxIcon
+sidebarTitle: mdx-components.js
 ---
 
 # `mdx-components.js` File
@@ -14,15 +15,15 @@ The `mdx-components` file is **required**, you use it to customize styles via
 The file must export a single function named `useMDXComponents`.
 
 ```ts filename="mdx-components.js"
-import { useMDXComponents as mdxComponents } from 'nextra-theme-docs' // nextra-theme-blog or your-custom-theme
+import { useMDXComponents as getThemeComponents } from 'nextra-theme-docs' // nextra-theme-blog or your custom theme
 
 // Get the default MDX components
-const myComponents = mdxComponents()
+const themeComponents = getThemeComponents()
 
 // Merge components
 export function useMDXComponents(components) {
   return {
-    ...myComponents,
+    ...themeComponents,
     ...components
   }
 }
@@ -43,4 +44,5 @@ When defining MDX Components, the export function accepts a single parameter
 > You can keep `mdx-components` file in root of your project, or in
 > [`src` directory](./src-directory).
 >
-> The `.js`, `.jsx`, or `.tsx` file extensions can be used for `mdx-components`.
+> The `.js`, `.jsx`, or `.tsx` file extensions can be used for `mdx-components`
+> file.