Document duplicate heading ids and how to avoid them (#779)

Co-authored-by: Isabel Matwawana <[email protected]> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Christopher Moyer <[email protected]>
grafana · Jul 16, 2024 · ddecbd4 · ddecbd4
1 parent b530a8e
commit ddecbd4
Show file tree

Hide file tree

Showing 2 changed files with 20 additions and 0 deletions.
diff --git a/docs/sources/write/markdown-guide/index.md b/docs/sources/write/markdown-guide/index.md
@@ -42,6 +42,18 @@ For the title of the page, use one `#`. For each child heading, use two `##` sym
 <!-- vale Grafana.Gerunds = NO -->
 <!-- A false positive because the noun heading looks like a gerund. -->
 
+### Identifiers
+
+Each heading has an auto-generated identifier that you can use to link to the heading within the page.
+To derive the generated identifier from a heading, refer to [Link to page headings](https://grafana.com/docs/writers-toolkit/write/links/#link-to-page-headings).
+
+You can also explicitly set the heading identifier.
+The following Markdown example sets the heading identifier to be `alternative-heading-id`:
+
+```markdown
+# Heading {#alternative-heading-id}
+```
+
 ### Heading don'ts
 
 <!-- vale Grafana.Gerunds = YES -->

diff --git a/docs/sources/write/shortcodes/index.md b/docs/sources/write/shortcodes/index.md
@@ -566,6 +566,14 @@ Hugo doesn't rebuild the destination file when a source file changes on disk.
 To trigger a rebuild after changes to a source file, perform a trivial change to the destination file and save that, too.
 {{< /admonition >}}
 
+### Shared files and headings
+
+Hugo renders the shortcode separately to the page. As a result, if the same heading exists in a shared file and the page that includes it, they'll have the same heading identifier. This duplication of heading identifiers breaks the ability to link to the headings properly.
+
+To work around this, set a heading identifier in the shared file.
+If there are two shared files with the same heading, you only need to set a heading identifier in one of them.
+To set a heading identifier, refer to the [Markdown guide](https://grafana.com/docs/writers-toolkit/write/markdown-guide/#identifiers).
+
 ### Guidance
 
 When the page with the `docs/shared` shortcode includes a shared page from the same project, you should use version substitution syntax for the `version` parameter.