[docs] Quick nav and base content styles (#804)

.eslintrc.js

@@ -43,6 +43,9 @@ module.exports = {
     'no-irregular-whitespace': [1, { skipJSXText: true, skipStrings: true }],
     'react/no-unescaped-entities': [1, { forbid: ['>', '}'] }],
     'material-ui/straight-quotes': 'off',
+    // This prevents us from creating components like `<h1 {...props} />`
+    'jsx-a11y/heading-has-content': 'off',
+    'jsx-a11y/anchor-has-content': 'off',
   },
   overrides: [
     ...baseline.overrides.filter(

docs/data/getting-started/support/support.mdx

@@ -79,7 +79,7 @@ You can join Discord to engage in lively discussions, share your projects, and i
 
 <Callout type="warning">
   How-to questions are not accepted on Discord, they should be asked on
-  [Stack Overflow](#stackoverflow).
+  [Stack Overflow](#stack-overflow).
 </Callout>
 
 ## Custom work

docs/next.config.mjs

@@ -6,8 +6,12 @@ import * as fs from 'fs';
 import withDocsInfra from '@mui/monorepo/docs/nextConfigDocsInfra.js';
 import nextMdx from '@next/mdx';
 import rehypePrettyCode from 'rehype-pretty-code';
+import rehypeExtractToc from '@stefanprobst/rehype-extract-toc';
 import { rehypeDemos } from './src/components/demo/rehypeDemos.mjs';
 import { highlighter } from './src/syntax-highlighting/index.mjs';
+import { rehypeInlineCode } from './src/syntax-highlighting/rehype-inline-code.mjs';
+import { rehypeQuickNav } from './src/components/quick-nav/rehype-quick-nav.mjs';
+import { rehypeSlug } from './src/components/quick-nav/rehype-slug.mjs';
 
 const currentDirectory = url.fileURLToPath(new URL('.', import.meta.url));
 const workspaceRoot = path.resolve(currentDirectory, '../');
@@ -17,6 +21,7 @@ const withMdx = nextMdx({
   options: {
     rehypePlugins: [
       rehypeDemos,
+      rehypeInlineCode,
       [
         rehypePrettyCode,
         {
@@ -26,6 +31,9 @@ const withMdx = nextMdx({
           grid: false,
         },
       ],
+      rehypeSlug,
+      rehypeExtractToc,
+      rehypeQuickNav,
     ],
   },
 });

docs/package.json

@@ -40,6 +40,9 @@
     "core-js": "^3.37.1",
     "cross-env": "^7.0.3",
     "fast-glob": "^3.3.2",
+    "hast": "^1.0.0",
+    "hast-util-heading-rank": "^3.0.0",
+    "hast-util-to-string": "^3.0.1",
     "lodash": "^4.17.21",
     "lz-string": "^1.5.0",
     "next": "15.0.2",
@@ -54,13 +57,13 @@
     "react-runner": "^1.0.5",
     "react-simple-code-editor": "^0.13.1",
     "rehype-pretty-code": "^0.14.0",
-    "rehype-slug": "^6.0.0",
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.0",
     "remark-mdx-frontmatter": "^5.0.0",
     "shiki": "^1.22.2",
     "to-vfile": "^8.0.0",
     "unist-util-visit": "^5.0.0",
+    "unist-util-visit-parents": "^6.0.1",
     "vfile-matter": "^5.0.0"
   },
   "devDependencies": {

docs/scripts/reportBrokenLinks.mts

@@ -6,9 +6,9 @@ import glob from 'fast-glob';
 
 import * as jsxRuntime from 'react/jsx-runtime';
 import { evaluate } from '@mdx-js/mdx';
-import rehypeSlug from 'rehype-slug';
 import extractToc, { Toc, TocEntry } from '@stefanprobst/rehype-extract-toc';
 import exportToc from '@stefanprobst/rehype-extract-toc/mdx';
+import { rehypeSlug } from 'docs/src/components/quick-nav/rehype-slug.mjs';
 import { rehypeExtractLinkUrls } from './rehypeExtractLinkUrls.mts';
 
 const currentDirectory = path.dirname(fileURLToPath(import.meta.url));

docs/src/app/(content)/getMarkdownPage.ts

@@ -7,12 +7,12 @@ import * as jsxRuntime from 'react/jsx-runtime';
 import remarkFrontmatter from 'remark-frontmatter';
 import remarkMdxFrontmatter from 'remark-mdx-frontmatter';
 import remarkGfm from 'remark-gfm';
-import rehypeSlug from 'rehype-slug';
 import extractToc, { type Toc } from '@stefanprobst/rehype-extract-toc';
 import exportToc from '@stefanprobst/rehype-extract-toc/mdx';
 import { read as readVFile } from 'to-vfile';
 import { matter } from 'vfile-matter';
 import { highlighter } from 'docs/src/syntax-highlighting';
+import { rehypeSlug } from 'docs/src/components/quick-nav/rehype-slug.mjs';
 
 export const DATA_PATH = path.join(process.cwd(), 'data');
 

docs/src/app/new/(content)/components/dialog/page.mdx

@@ -1,15 +1,63 @@
+# Dialog
+
+<Subtitle>A popup that opens on top of the entire page.</Subtitle>
+
 <Demo path="./UnstyledDialogIntroduction" />
 
+## Examples
+
+### State
+
+By default, Dialog is an uncontrolled component that manages its own state. Use `<Dialog.Trigger>` and `<Dialog.Close>` to open and close the dialog.
+
+```tsx title="Uncontrolled dialog"
+<Dialog.Root>
+  <Dialog.Trigger>Open</Dialog.Trigger>
+  <Dialog.Popup>
+    <Dialog.Title>Example dialog</Dialog.Title>
+    <Dialog.Close>Close</Dialog.Close>
+  </Dialog.Popup>
+</Dialog.Root>
+```
+
+Use `open` and `onOpenChange` props if you need to access or control the state of the dialog.
+
 ```tsx title="Controlled dialog"
 const [open, setOpen] = React.useState(false);
-
 return (
   <Dialog.Root open={open} onOpenChange={setOpen}>
     <Dialog.Trigger>Open</Dialog.Trigger>
     <Dialog.Popup>
-      <Dialog.Title>Demo dialog</Dialog.Title>
-      <Dialog.Close>Close</Dialog.Close>
+      <form
+        // Close the dialog once data is submitted
+        onSubmit={async () => {
+          await submitData();
+          setOpen(false);
+        }}
+      >
+        ...
+      </form>
     </Dialog.Popup>
   </Dialog.Root>
 );
 ```
+
+It’s also common to use `onOpenChange` if your app needs to do something when the dialog is closed or opened. This is recommended over `React.useEffect` when reacting to state changes.
+
+```tsx title="Running code when dialog state changes"
+<Dialog.Root
+  open={open}
+  onOpenChange={(open) => {
+    // Do stuff when the dialog is closed
+    if (!open) {
+      doStuff();
+    }
+    // Set the new state
+    setOpen(open);
+  }}
+>
+```
+
+### Syntax
+
+The `<Dialog.Trigger>` part renders a native `<button>` element. Don’t take this paragraph too seriously though, I’m just testing the inline syntax highlighting.

docs/src/app/new/(content)/layout.tsx

@@ -2,8 +2,8 @@ import * as React from 'react';
 
 export default function Layout({ children }: React.PropsWithChildren) {
   return (
-    <div className="px-8 pb-24 pt-8">
-      <div className="mx-auto max-w-[768px]">{children}</div>
+    <div className="px-8 pt-12 pb-20">
+      <div className="relative mx-auto max-w-[768px]">{children}</div>
     </div>
   );
 }