Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Style Guide] Adding more explanation to the AnchorHeading component style guide. #16986

Merged
merged 4 commits into from
Sep 23, 2024
Merged

[Style Guide] Adding more explanation to the AnchorHeading component style guide. #16986

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c2e426a
Adding more explanation to the AnchorHeading component style guide.
Oxyjun Sep 20, 2024
93132db
Update src/content/docs/style-guide/components/anchor-heading.mdx
Oxyjun Sep 23, 2024
65881be
Update src/content/docs/style-guide/components/anchor-heading.mdx
Oxyjun Sep 23, 2024
341f156
Update src/content/docs/style-guide/components/anchor-heading.mdx
Oxyjun Sep 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 18 additions & 7 deletions src/content/docs/style-guide/components/anchor-heading.mdx
View file
Open in desktop
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 headers.
Oxyjun marked this conversation as resolved.
Show resolved Hide resolved
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} />
```

By default, markdown files (including partials) have this behavior 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.
Oxyjun marked this conversation as resolved.
Show resolved Hide resolved

Additionally, `AnchorHeading`s are useful when rendering partial files into one location where there are duplicate headings (for example, when there are multiple H3 "`create`" headings in one page). `AnchorHeading`'s ability to explicitly define a fragment allows you to ensure each heading can be linked correctly with unique fragments.
Oxyjun marked this conversation as resolved.
Show resolved Hide resolved

:::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.
Oxyjun marked this conversation as resolved.
Show resolved Hide resolved

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