Skip to content

Commit

Permalink
[Style Guide] Adding more explanation to the AnchorHeading component …
Browse files Browse the repository at this point in the history
…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 <62246989+RebeccaTamachiro@users.noreply.github.com>

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

Co-authored-by: Rebecca Tamachiro <62246989+RebeccaTamachiro@users.noreply.github.com>

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

Co-authored-by: Rebecca Tamachiro <62246989+RebeccaTamachiro@users.noreply.github.com>

---------

Co-authored-by: Rebecca Tamachiro <62246989+RebeccaTamachiro@users.noreply.github.com>
  • Loading branch information
2 people authored and maheshwarip committed Dec 2, 2024
1 parent 4ec6b80 commit 27c1c5e
Showing 1 changed file with 18 additions and 7 deletions.
25 changes: 18 additions & 7 deletions src/content/docs/style-guide/components/anchor-heading.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,25 @@
title: Anchor heading
---

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.
The `AnchorHeading` component defines headings. Specifically, `AnchorHeading` performs the following:

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.

This is only required when writing headings yourself inside components, Markdown (including partials) will have this applied via the aforementioned rehype plugins.
1. Generates URL fragments corresponding to headings.
2. Formats URL fragments into compatible syntax. For example, a `&` is replaced with a `-`.
3. Creates a button to copy the URL at each fragment.
4. Allows heading fragments to be defined separately from the text of the heading itself.

```mdx live
import { AnchorHeading } from "~/components"
import { AnchorHeading } from "~/components";

<AnchorHeading title="How to use AnchorHeading" slug="use-anchorheading" depth={2} />
```

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.

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.

:::note

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.

<AnchorHeading title="Foo & Bar & Baz" depth={2} />
```
:::

0 comments on commit 27c1c5e

Please sign in to comment.