Add built-in heading anchor link support (#3033)

Co-authored-by: HiDeoo <[email protected]>

Author: delucis

.changeset/late-onions-sparkle.md

@@ -0,0 +1,26 @@
+---
+'@astrojs/starlight': minor
+---
+
+Adds support for generating clickable anchor links for headings.
+
+By default, Starlight now renders an anchor link beside headings in Markdown and MDX content. A new `<AnchorHeading>` component is available to achieve the same thing in custom pages built using `<StarlightPage>`.
+
+If you want to disable this new Markdown processing set the `markdown.headingLinks` option in your Starlight config to `false`:
+
+```js
+starlight({
+  title: 'My docs',
+  markdown: {
+    headingLinks: false,
+  },
+}),
+```
+
+⚠️ **BREAKING CHANGE:** The minimum supported version of Astro is now v5.5.0.
+
+Please update Starlight and Astro together:
+
+```sh
+npx @astrojs/upgrade
+```

.changeset/quick-items-dream.md

@@ -0,0 +1,24 @@
+---
+'@astrojs/starlight-markdoc': minor
+---
+
+Adds support for generating clickable anchor links for headings.
+
+By default, the Starlight Markdoc preset now includes a default `heading` node, which renders an anchor link beside headings in your Markdoc content.
+
+If you want to disable this new feature, pass `headingLinks: false` in your Markdoc config:
+
+```js
+export default defineMarkdocConfig({
+  // Disable the default heading anchor link support
+  extends: [starlightMarkdoc({ headingLinks: false })],
+});
+```
+
+⚠️ **BREAKING CHANGE:** The minimum supported peer version of Starlight is now v0.34.0.
+
+Please update Starlight and the Starlight Markdoc preset together:
+
+```sh
+npx @astrojs/upgrade
+```

.prettierignore

@@ -18,5 +18,8 @@ pnpm-lock.yaml
 # https://github.com/withastro/prettier-plugin-astro/issues/337
 packages/starlight/user-components/Tabs.astro
 
+# Prettier forces whitespace between elements we want to avoid for consistency with the rehype version
+packages/starlight/components/AnchorHeading.astro
+
 # Malformed YAML file used for testing
 packages/starlight/__tests__/i18n/malformed-yaml-src/content/i18n/*.yml

docs/src/content/docs/guides/authoring-content.mdx

@@ -650,3 +650,22 @@ If you already have a Starlight site and want to add Markdoc, follow these steps
 </Steps>
 
 To learn more about the Markdoc syntax and features, see the [Markdoc documentation](https://markdoc.dev/docs/syntax) or the [Astro Markdoc integration guide](https://docs.astro.build/en/guides/integrations-guide/markdoc/).
+
+### Configuring the Markdoc preset
+
+The `starlightMarkdoc()` preset accepts the following configuration options:
+
+#### `headingLinks`
+
+**type:** `boolean`  
+**default:** `true`
+
+Controls whether or not headings are rendered with a clickable anchor link.
+Equivalent to the [`markdown.headingLinks`](/reference/configuration/#markdown) option, which applies to Markdown and MDX files.
+
+```js "headingLinks: false"
+export default defineMarkdocConfig({
+	// Disable the default heading anchor link support
+	extends: [starlightMarkdoc({ headingLinks: false })],
+});
+```

docs/src/content/docs/guides/pages.mdx

@@ -3,6 +3,8 @@ title: Pages
 description: Learn how to create and manage your documentation site’s pages with Starlight.
 sidebar:
   order: 1
+tableOfContents:
+  maxHeadingLevel: 4
 ---
 
 Starlight generates your site’s HTML pages based on your content, with flexible options provided via Markdown frontmatter.
@@ -73,28 +75,49 @@ Read more in the [“Pages” guide in the Astro docs](https://docs.astro.build/
 
 ### Using Starlight’s design in custom pages
 
-To use the Starlight layout in custom pages, wrap your page content with the `<StarlightPage />` component.
+To use the Starlight layout in custom pages, wrap your page content with the [`<StarlightPage>` component](#starlightpage-component).
 This can be helpful if you are generating content dynamically but still want to use Starlight’s design.
 
+To add anchor links to headings that match Starlight’s Markdown anchor link styles, you can use the [`<AnchorHeading>` component](#anchorheading-component) in your custom pages.
+
 ```astro
 ---
 // src/pages/custom-page/example.astro
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
+import AnchorHeading from '@astrojs/starlight/components/AnchorHeading.astro';
 import CustomComponent from './CustomComponent.astro';
 ---
 
 <StarlightPage frontmatter={{ title: 'My custom page' }}>
 	<p>This is a custom page with a custom component:</p>
 	<CustomComponent />
+
+	<AnchorHeading level="2" id="learn-more">Learn more</AnchorHeading>
+	<p>
+		<a href="https://starlight.astro.build/">Read more in the Starlight docs</a>
+	</p>
 </StarlightPage>
 ```
 
-#### Props
+#### `<StarlightPage>` component
+
+The `<StarlightPage />` component renders a full page of content using Starlight’s layout and styles.
+
+```astro
+---
+import StarlightPage from '@astrojs/starlight/components/AnchorHeading.astro';
+---
+
+<StarlightPage frontmatter={{ title: 'My custom page' }}>
+	<!-- Custom page content -->
+</StarlightPage>
+```
 
 The `<StarlightPage />` component accepts the following props.
 
-##### `frontmatter` (required)
+##### `frontmatter`
 
+**required**  
 **type:** `StarlightPageFrontmatter`
 
 Set the [frontmatter properties](/reference/frontmatter/) for this page, similar to frontmatter in Markdown pages.
@@ -173,3 +196,33 @@ Set the BCP-47 language tag for this page’s content, e.g. `en`, `zh-CN`, or `p
 **default:** `false`
 
 Indicate if this page is using [fallback content](/guides/i18n/#fallback-content) because there is no translation for the current language.
+
+#### `<AnchorHeading>` component
+
+The `<AnchorHeading />` component renders an HTML heading element with a clickable anchor link that matches Starlight’s Markdown styles.
+
+```astro
+---
+import AnchorHeading from '@astrojs/starlight/components/AnchorHeading.astro';
+---
+
+<AnchorHeading level="2" id="sub-heading">Sub heading</AnchorHeading>
+```
+
+It accepts the following props as well as any other valid [global HTML attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes).
+
+##### `level`
+
+**required**  
+**type:** `1 | 2 | 3 | 4 | 5 | 6`
+
+The heading level to render.
+For example, `level="1"` would render an `<h1>` element.
+
+##### `id`
+
+**required**  
+**type:** `string`
+
+The unique ID for this heading.
+This will be used as the `id` attribute of the rendered heading and the anchor icon will link to it.

docs/src/content/docs/reference/configuration.mdx

@@ -372,6 +372,29 @@ starlight({
 });
 ```
 
+### `markdown`
+
+**type:** `{ headingLinks?: boolean }`  
+**default:** `{ headingLinks: true }`
+
+Configure Starlight’s Markdown processing.
+
+#### `headingLinks`
+
+**type:** `boolean`  
+**default:** `true`
+
+Controls whether or not headings are rendered with a clickable anchor link.
+
+```js
+starlight({
+	markdown: {
+		// Disable Starlight’s clickable heading anchor links.
+		headingLinks: false,
+	},
+}),
+```
+
 ### `expressiveCode`
 
 **type:** `StarlightExpressiveCodeOptions | boolean`  

package.json

@@ -42,7 +42,7 @@
         "examples/basics/dist/_astro/*.css",
         "!examples/basics/dist/_astro/print.*.css"
       ],
-      "limit": "14.5 kB",
+      "limit": "14.75 kB",
       "gzip": true
     }
   ],

packages/markdoc/components.ts

@@ -1 +1,2 @@
 export { default as Code } from './Code.astro';
+export { default as Heading } from '@astrojs/starlight/components/AnchorHeading.astro';

packages/markdoc/index.mjs

@@ -1,4 +1,4 @@
-import { component } from '@astrojs/markdoc/config';
+import { component, nodes } from '@astrojs/markdoc/config';
 import { WellKnownElementAttributes, WellKnownAnchorAttributes } from './html.mjs';
 
 /**
@@ -287,7 +287,23 @@ export const StarlightMarkdocPreset = {
 	},
 };
 
-/** @return {import('@astrojs/markdoc/config').AstroMarkdocConfig} */
-export default function starlightMarkdoc() {
-	return StarlightMarkdocPreset;
+/**
+ * Markdoc preset that configures Starlight’s built-in components.
+ * @return {import('@astrojs/markdoc/config').AstroMarkdocConfig}
+ */
+export default function starlightMarkdoc({ headingLinks = true } = {}) {
+	return {
+		...StarlightMarkdocPreset,
+		nodes: {
+			...StarlightMarkdocPreset.nodes,
+			...(headingLinks
+				? {
+						heading: {
+							...nodes.heading,
+							render: component('@astrojs/starlight-markdoc/components', 'Heading'),
+						},
+					}
+				: {}),
+		},
+	};
 }

packages/markdoc/package.json

@@ -23,7 +23,7 @@
   },
   "peerDependencies": {
     "@astrojs/markdoc": ">=0.12.1",
-    "@astrojs/starlight": ">=0.30.0"
+    "@astrojs/starlight": ">=0.34.0"
   },
   "publishConfig": {
     "provenance": true