Expand Section Links documentation and add a section for Custom Ancho…

…rs (#33531)

Co-authored-by: Felicity Chapman <[email protected]>
Co-authored-by: Jan Brasna <[email protected]>

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 (`<a name="unique-anchor-name"></a>`) 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.
+
+<a name="my-custom-anchor-point"></a>
+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 <kbd>!</kbd> 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 `()`.

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 %}

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)