Do you turn your headings into anchor links?

Making headings linkable helps readers navigate directly to specific sections, share precise URLs, and maintain stable links even when heading text changes.

Anchor links improve user experience by enabling quick navigation within long pages and provide shareable URLs that point to exact content locations.

✅ Benefits

• Faster navigation - Users can jump directly to specific sections within long pages
• Easy sharing - Share precise URLs pointing to exact content locations
• Stable links - Custom IDs preserve links even when heading text changes
• SEO improvements - Search engines can link directly to relevant sections
• Better accessibility - Screen readers can navigate page structure more effectively

How anchor links work

When you create a heading, it can automatically generate an anchor link, or you can assign a custom ID.

Markdown heading:

## Getting started

This heading auto-generates an anchor: #getting-started

HTML heading with explicit ID:

<h2 id="getting-started">Getting started</h2>

Linking to the section:

https://example.com/docs#getting-started

Users can click the heading or its link icon to get a URL that navigates directly to that section.

✅ Figure: Good example - Good example - Click the heading (or its link icon) to get a URL that takes you straight to that section of the page

Implementation in MDX/React applications

For React applications using Markdown/MDX, use rehype plugins to automatically generate IDs and anchor links for headings.

Example configuration (Next.js with MDX):

// next.config.mjs
import createMDX from '@next/mdx';
import rehypeSlug from 'rehype-slug';
import rehypeAutolinkHeadings from 'rehype-autolink-headings';
import rehypeSanitize from 'rehype-sanitize';

const withMDX = createMDX({
  extension: /\.mdx?$/,
  options: {
    rehypePlugins: [
      rehypeSlug,  // Generates IDs for headings
      [rehypeAutolinkHeadings, { behavior: 'wrap' }],  // Adds clickable anchor links
      rehypeSanitize,  // Prevents XSS attacks from user-generated content
    ],
  },
});

export default withMDX({
  pageExtensions: ['ts', 'tsx', 'js', 'jsx', 'md', 'mdx'],
});

Security note: Always include rehype-sanitize when processing user-generated content to prevent XSS (cross-site scripting) attacks through DOM clobbering.