Skip to content

Commit dbe87d1

Browse files
[Style Guide] Adding more explanation to the AnchorHeading component style guide. (#16986)
* Adding more explanation to the AnchorHeading component style guide. * Update src/content/docs/style-guide/components/anchor-heading.mdx Co-authored-by: Rebecca Tamachiro <[email protected]> * Update src/content/docs/style-guide/components/anchor-heading.mdx Co-authored-by: Rebecca Tamachiro <[email protected]> * Update src/content/docs/style-guide/components/anchor-heading.mdx Co-authored-by: Rebecca Tamachiro <[email protected]> --------- Co-authored-by: Rebecca Tamachiro <[email protected]>
1 parent a162133 commit dbe87d1

File tree

1 file changed

+18
-7
lines changed

1 file changed

+18
-7
lines changed

src/content/docs/style-guide/components/anchor-heading.mdx

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,25 @@
22
title: Anchor heading
33
---
44

5-
The `AnchorHeading` component emulates the behaviour of the [`rehype-slug`](https://github.com/rehypejs/rehype-slug) and [`rehype-autolink-headings`](https://github.com/rehypejs/rehype-autolink-headings) plugins.
5+
The `AnchorHeading` component defines headings. Specifically, `AnchorHeading` performs the following:
66

7-
It adds an `id` based on the output of [`github-slugger`](https://github.com/Flet/github-slugger/) to the heading, as well as adding a button to copy a link to that particular heading.
8-
9-
This is only required when writing headings yourself inside components, Markdown (including partials) will have this applied via the aforementioned rehype plugins.
7+
1. Generates URL fragments corresponding to headings.
8+
2. Formats URL fragments into compatible syntax. For example, a `&` is replaced with a `-`.
9+
3. Creates a button to copy the URL at each fragment.
10+
4. Allows heading fragments to be defined separately from the text of the heading itself.
1011

1112
```mdx live
12-
import { AnchorHeading } from "~/components"
13+
import { AnchorHeading } from "~/components";
14+
15+
<AnchorHeading title="How to use AnchorHeading" slug="use-anchorheading" depth={2} />
16+
```
17+
18+
Markdown files (including partials) have this behavior by default, applied via rehype plugins. Therefore, the `AnchorHeading` component is usually only required when writing headings yourself inside components, or when working on non-markdown files.
19+
20+
Additionally, `AnchorHeading` is useful when rendering partial files into one location where there are duplicate headings (for example, when there are multiple H3 corresponding to `/#create` in one page). `AnchorHeading` allows you to explicitly define fragments, ensuring that each heading can be referred correctly with unique anchors.
21+
22+
:::note
23+
24+
The `AnchorHeading` component emulates the behavior of the [`rehype-slug`](https://github.com/rehypejs/rehype-slug) and the [`rehype-autolink-headings`](https://github.com/rehypejs/rehype-autolink-headings). It adds an `id` based on the output of [`github-slugger`](https://github.com/Flet/github-slugger/) to the heading, as well as adding a button to copy a link to that particular heading.
1325

14-
<AnchorHeading title="Foo & Bar & Baz" depth={2} />
15-
```
26+
:::

0 commit comments

Comments
 (0)