From 27c1c5e8c759f30d74d5df65a15541ae806a3bc3 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Mon, 23 Sep 2024 09:57:11 +0100 Subject: [PATCH] [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 <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> --- .../style-guide/components/anchor-heading.mdx | 25 +++++++++++++------ 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/src/content/docs/style-guide/components/anchor-heading.mdx b/src/content/docs/style-guide/components/anchor-heading.mdx index ac1efdd7d8aafd8..12635a69327c5c3 100644 --- a/src/content/docs/style-guide/components/anchor-heading.mdx +++ b/src/content/docs/style-guide/components/anchor-heading.mdx @@ -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"; + + +``` + +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. - -``` \ No newline at end of file +::: \ No newline at end of file