From 21058b8856f45fc1345012af7e95c05eff3d0664 Mon Sep 17 00:00:00 2001 From: dodexahedron Date: Mon, 23 Sep 2024 01:15:37 -0700 Subject: [PATCH] Expand Section Links documentation and add a section for Custom Anchors (#33531) Co-authored-by: Felicity Chapman Co-authored-by: Jan Brasna <1784648+janbrasna@users.noreply.github.com> --- .../basic-writing-and-formatting-syntax.md | 69 +++++++++++++++++++ .../about-readmes.md | 2 + data/reusables/repositories/section-links.md | 2 +- 3 files changed, 72 insertions(+), 1 deletion(-) diff --git a/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md b/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md index a982a49cc630..2824f66dedaa 100644 --- a/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md +++ b/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md @@ -124,10 +124,79 @@ You can also create a Markdown hyperlink by highlighting the text and using the {% data reusables.repositories.section-links %} +If you need to determine the anchor for a heading in a file you are editing, you can use the following basic rules: + +* Letters are converted to lower-case. +* Spaces are replaced by hyphens (`-`). Any other whitespace or punctuation characters are removed. +* Leading and trailing whitespace are removed. +* Markup formatting is removed, leaving only the contents (for example, `_italics_` becomes `italics`). +* If the automatically generated anchor for a heading is identical to an earlier anchor in the same document, a unique identifier is generated by appending a hyphen and an auto-incrementing integer. + +For more detailed information on the requirements of URI fragments, see [RFC 3986: Uniform Resource Identifier (URI): Generic Syntax, Section 3.5](https://www.rfc-editor.org/rfc/rfc3986#section-3.5). + +The code block below demonstrates the basic rules used to generate anchors from headings in rendered content. + +```markdown +# Example headings + +## Sample Section + +## This'll be a _Helpful_ Section About the Greek Letter Θ! +A heading containing characters not allowed in fragments, UTF-8 characters, two consecutive spaces between the first and second words, and formatting. + +## This heading is not unique in the file + +TEXT 1 + +## This heading is not unique in the file + +TEXT 2 + +# Links to the example headings above + +Link to the sample section: [Link Text](#sample-section). + +Link to the helpful section: [Link Text](#thisll--be-a-helpful-section-about-the-greek-letter-Θ). + +Link to the first non-unique section: [Link Text](#this-heading-is-not-unique-in-the-file). + +Link to the second non-unique section: [Link Text](#this-heading-is-not-unique-in-the-file-1). +``` + +> [!NOTE] +> If you edit a heading, or if you change the order of headings with "identical" anchors, you will also need to update any links to those headings as the anchors will change. + ## Relative links {% data reusables.repositories.relative-links %} +## Custom anchors + +You can use standard HTML anchor tags (``) to create navigation anchor points for any location in the document. To avoid ambiguous references, use a unique naming scheme for anchor tags, such as adding a prefix to the `name` attribute value. + +> [!NOTE] +> Custom anchors will not be included in the document outline/Table of Contents. + +You can link to a custom anchor using the value of the `name` attribute you gave the anchor. The syntax is exactly the same as when you link to an anchor that is automatically generated for a heading. + +For example: + +```markdown +# Section Heading + +Some body text of this section. + + +Some text I want to provide a direct link to, but which doesn't have its own heading. + +(… more content…) + +[A link to that custom anchor](#my-custom-anchor-point) +``` + +> [!TIP] +> Custom anchors are not considered by the automatic naming and numbering behavior of automatic heading links. + ## Images You can display an image by adding ! and wrapping the alt text in `[ ]`. Alt text is a short text equivalent of the information in the image. Then, wrap the link for the image in parentheses `()`. diff --git a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md b/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md index 956463e4f4a2..5e42f434f615 100644 --- a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md +++ b/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md @@ -45,6 +45,8 @@ For the rendered view of any Markdown file in a repository, including README fil {% data reusables.repositories.section-links %} +For more detailed information about section links, see "[Section links](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links)." + ## Relative links and image paths in README files {% data reusables.repositories.relative-links %} diff --git a/data/reusables/repositories/section-links.md b/data/reusables/repositories/section-links.md index da9756c0a14b..6da6716918c1 100644 --- a/data/reusables/repositories/section-links.md +++ b/data/reusables/repositories/section-links.md @@ -1,3 +1,3 @@ -You can link directly to a section in a rendered file by hovering over the section heading to expose {% octicon "link" aria-label="the link" %}. +You can link directly to any section that has a heading. To view the automatically generated anchor in a rendered file, hover over the section heading to expose the {% octicon "link" aria-label="the link" %} icon and click the icon to display the anchor in your browser. ![Screenshot of a README for a repository. To the left of a section heading, a link icon is outlined in dark orange.](/assets/images/help/repository/readme-links.png)