Link h2 and h3 in docs

docs/src/app/not-found.tsx

@@ -21,7 +21,7 @@ export default function NotFound() {
               className="-m-1 inline-flex items-center gap-1 p-1"
               href="/react/overview/quick-start"
             >
-              Documentation <ArrowRightIcon />
+              Documentation <ArrowRightIcon aria-hidden />
             </Link>
 
             <Link className="-m-1 p-1" href="https://github.com/mui/base-ui">

docs/src/components/HeadingLink.css

@@ -0,0 +1,24 @@
+.HeadingLink {
+  &:focus-visible {
+    outline: 2px solid var(--color-blue);
+    outline-offset: -2px;
+    border-radius: var(--radius-sm);
+  }
+
+  & svg {
+    visibility: hidden;
+  }
+
+  @media (hover: hover) {
+    &:hover {
+      text-decoration: underline;
+      text-underline-offset: 2px;
+      text-decoration-thickness: 1px;
+      text-decoration-color: color-mix(in oklab, var(--color-gray), transparent);
+    }
+
+    &:hover svg {
+      visibility: visible;
+    }
+  }
+}

docs/src/components/HeadingLink.tsx

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import clsx from 'clsx';
+import { LinkIcon } from 'docs/src/icons/LinkIcon';
+
+export function HeadingLink({
+  children,
+  className,
+  id,
+  ...otherProps
+}: React.ComponentPropsWithoutRef<'a'>) {
+  return (
+    <a
+      className={clsx('HeadingLink mr-[0.5em] inline-flex items-center gap-[0.5em]', className)}
+      href={`#${id}`}
+      {...otherProps}
+    >
+      {children}
+      <LinkIcon aria-hidden />
+    </a>
+  );
+}

docs/src/components/Link.tsx

@@ -19,7 +19,7 @@ export function Link({ href, className, ...props }: React.ComponentProps<typeof
         className={clsx('Link mr-[0.125em] inline-flex items-center gap-[0.25em]', className)}
       >
         {props.children}
-        <ExternalLinkIcon />
+        <ExternalLinkIcon aria-hidden />
       </NextLink>
     );
   }

docs/src/icons/LinkIcon.tsx

@@ -0,0 +1,16 @@
+import * as React from 'react';
+
+export function LinkIcon(props: React.ComponentProps<'svg'>) {
+  return (
+    <svg
+      width="12"
+      height="6"
+      viewBox="0 0 12 6"
+      fill="currentcolor"
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <path d="M8.9176 0.083252H7.1676C6.84677 0.083252 6.58427 0.345752 6.58427 0.666585C6.58427 0.987419 6.84677 1.24992 7.1676 1.24992H8.9176C9.8801 1.24992 10.6676 2.03742 10.6676 2.99992C10.6676 3.96242 9.8801 4.74992 8.9176 4.74992H7.1676C6.84677 4.74992 6.58427 5.01242 6.58427 5.33325C6.58427 5.65409 6.84677 5.91659 7.1676 5.91659H8.9176C10.5276 5.91659 11.8343 4.60992 11.8343 2.99992C11.8343 1.38992 10.5276 0.083252 8.9176 0.083252ZM3.6676 2.99992C3.6676 3.32075 3.9301 3.58325 4.25094 3.58325H7.75094C8.07177 3.58325 8.33427 3.32075 8.33427 2.99992C8.33427 2.67909 8.07177 2.41659 7.75094 2.41659H4.25094C3.9301 2.41659 3.6676 2.67909 3.6676 2.99992ZM4.83427 4.74992H3.08427C2.12177 4.74992 1.33427 3.96242 1.33427 2.99992C1.33427 2.03742 2.12177 1.24992 3.08427 1.24992H4.83427C5.1551 1.24992 5.4176 0.987419 5.4176 0.666585C5.4176 0.345752 5.1551 0.083252 4.83427 0.083252H3.08427C1.47427 0.083252 0.167603 1.38992 0.167603 2.99992C0.167603 4.60992 1.47427 5.91659 3.08427 5.91659H4.83427C5.1551 5.91659 5.4176 5.65409 5.4176 5.33325C5.4176 5.01242 5.1551 4.74992 4.83427 4.74992Z" />
+    </svg>
+  );
+}

docs/src/mdx-components.tsx

@@ -9,6 +9,7 @@ import { AttributesReferenceTable } from './components/ReferenceTable/Attributes
 import { CssVariablesReferenceTable } from './components/ReferenceTable/CssVariablesReferenceTable';
 import { getChildrenText } from './utils/getChildrenText';
 import { Link } from './components/Link';
+import { HeadingLink } from './components/HeadingLink';
 import { Subtitle } from './components/Subtitle/Subtitle';
 import { Kbd } from './components/Kbd/Kbd';
 
@@ -26,16 +27,32 @@ export const mdxComponents: MDXComponents = {
       <title>{`${getChildrenText(props.children)} · Base UI`}</title>
     </React.Fragment>
   ),
-  h2: (props) => (
-    // Do not wrap heading tags in divs, that confuses Safari Reader
-    <React.Fragment>
-      <h2 className="mt-10 mb-4 scroll-mt-6 text-xl font-medium text-balance" {...props} />
-      <div className="mb-5 border-t border-gray-200" />
-    </React.Fragment>
-  ),
-  h3: (props) => (
-    <h3 className="mt-8 mb-1.5 scroll-mt-6 text-lg font-medium text-balance" {...props} />
-  ),
+  h2: ({ children, id, ...otherProps }) => {
+    return (
+      // Do not wrap heading tags in divs, that confuses Safari Reader
+      <React.Fragment>
+        <h2
+          className="mt-10 mb-4 scroll-mt-6 text-xl font-medium text-balance"
+          id={id}
+          {...otherProps}
+        >
+          <HeadingLink id={id}>{children}</HeadingLink>
+        </h2>
+        <div className="mb-5 border-t border-gray-200" />
+      </React.Fragment>
+    );
+  },
+  h3: ({ children, id, ...otherProps }) => {
+    return (
+      <h3
+        className="mt-8 mb-1.5 scroll-mt-6 text-lg font-medium text-balance"
+        id={id}
+        {...otherProps}
+      >
+        <HeadingLink id={id}>{children}</HeadingLink>
+      </h3>
+    );
+  },
   h4: (props) => <h4 className="mt-8 mb-1.5 scroll-mt-6 font-medium text-balance" {...props} />,
   h5: (props) => <h5 className="mt-8 mb-1.5 scroll-mt-6 font-medium text-balance" {...props} />,
   h6: (props) => <h6 className="mt-8 mb-1.5 scroll-mt-6 font-medium text-balance" {...props} />,

docs/src/styles.css

@@ -32,6 +32,7 @@
 @import './components/Demo/Demo.css';
 @import './components/GhostButton.css';
 @import './components/Header.css';
+@import './components/HeadingLink.css';
 @import './components/Kbd/Kbd.css';
 @import './components/Link.css';
 @import './components/MobileNav.css';