github · dodexahedron · Jun 17, 2024 · Jun 17, 2024 · Jun 17, 2024 · Jun 17, 2024
diff --git a/...ed-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md b/...ed-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md
@@ -21,11 +21,11 @@
 ### A third-level heading
 ```

 ![Screenshot of rendered GitHub Markdown showing sample h1, h2, and h3 headers, which descend in type size and visual weight to indicate descending hierarchy level.](/assets/images/help/writing/headings-rendered.png)

 When you use two or more headings, GitHub automatically generates a table of contents that you can access by clicking {% octicon "list-unordered" aria-label="The unordered list icon" %} within the file header. Each heading title is listed in the table of contents and you can click a title to navigate to the selected section.

 ![Screenshot of the README file in the GitHub Docs open source repository with the drop-down menu for the table of contents exposed. The table of contents icon is outlined in dark orange.](/assets/images/help/repository/headings-toc.png)

 ## Styling text

@@ -53,7 +53,7 @@

 Quoted text is indented, with a different type color.

 ![Screenshot of rendered GitHub Markdown showing sample quoted text. The quote is indented with a vertical line on the left, and its text is dark gray rather than black.](/assets/images/help/writing/quoted-text-rendered.png)

 {% note %}

@@ -69,7 +69,7 @@
 Use `git status` to list all new or modified files that haven't yet been committed.
 ```

 ![Screenshot of rendered GitHub Markdown showing the appearance of characters surrounded by backticks. The words "git status" appear in a fixed-width typeface, highlighted in light gray.](/assets/images/help/writing/inline-code-rendered.png)

 To format code or text into its own distinct block, use triple backticks.

@@ -82,7 +82,7 @@
 ```
 ````

 ![Screenshot of rendered GitHub Markdown showing a code block. The words "git status," "git add," and "git commit" appear in a fixed-width typeface, highlighted in light gray.](/assets/images/help/writing/code-block-rendered.png)

 For more information, see "[AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks)."

@@ -96,7 +96,7 @@
 The background color is `#ffffff` for light mode and `#000000` for dark mode.
 ```

 ![Screenshot of rendered GitHub Markdown showing how HEX values within backticks create small circles of color. #ffffff shows a white circle, and #000000 shows a black circle.](/assets/images/help/writing/supported-color-models-rendered.png)

 Here are the currently supported color models.

@@ -139,6 +139,10 @@
 
 {% data reusables.repositories.relative-links %}
 
+## Custom anchors
+
+{% data reusables.repositories.custom-anchors %}
+
 ## 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 `()`.
@@ -225,7 +229,7 @@

 ![Screenshot of Markdown in {% data variables.product.prodname_vscode %} showing how indented bullets align vertically with the first letter of the text lines above them.](/assets/images/help/writing/nested-list-alignment.png)

 ![Screenshot of rendered GitHub Markdown showing a numbered item followed by a bulleted item nested one level to the right, and another bulleted item nested yet further to the right.](/assets/images/help/writing/nested-list-example-1.png)

 To create a nested list in the comment editor on {% data variables.product.product_name %}, which doesn't use a monospaced font, you can look at the list item immediately above the nested list and count the number of characters that appear before the content of the item. Then type that number of space characters in front of the nested list item.

@@ -246,7 +250,7 @@
         - Second nested list item
 ```

 ![Screenshot of rendered GitHub Markdown showing a list item prefaced by the number 100 followed by a bulleted item nested one level to the right, and another bulleted item nested yet further to the right.](/assets/images/help/writing/nested-list-example-2.png)

 For more examples, see the [GitHub Flavored Markdown Spec](https://github.github.com/gfm/#example-265).

@@ -383,7 +387,7 @@

 `Let's rename \*our-new-project\* to \*our-old-project\*.`

 ![Screenshot of rendered GitHub Markdown showing how backslashes prevent the conversion of asterisks to italics. The text reads, "Let's rename our-new-project to our-old-project."](/assets/images/help/writing/escaped-character-rendered.png)

 For more information on backslashes, see Daring Fireball's "[Markdown Syntax](https://daringfireball.net/projects/markdown/syntax#backslash)."


diff --git a/data/reusables/repositories/custom-anchors.md b/data/reusables/repositories/custom-anchors.md
@@ -0,0 +1,25 @@
+Use HTML anchor tags (`<a id="unique-anchor-name"></a>`) to create navigation anchor points to any place in the document.
-Use HTML anchor tags (`<a id="unique-anchor-name"></a>`) to create navigation anchor points to any place in the document.
+You can use standard HTML anchor tags (`<a name="unique-anchor-name"></a>`) to create navigation anchor points for any location in the document.
-Use HTML anchor tags (`<a id="unique-anchor-name"></a>`) to create navigation anchor points to any place in the document.
+You can use standard HTML anchor tags (`<a name="unique-anchor-name"></a>`) to create navigation anchor points for any location in the document.
+
+> [!NOTE]
+> Custom anchors will not be included in the document outline/Table of Contents.
+
+Link to custom anchors by using the `id` given to the anchor.
-Link to custom anchors by using the `id` given to the anchor.
+You can link to a custom anchor with the name, `name`, you gave the anchor. The syntax is exactly the same as when you link to an anchor that is automatically generated for a heading.
-Link to custom anchors by using the `id` given to the anchor.
+You can link to a custom anchor with the name, `name`, 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 id="my-custom-anchor-point"></a>
-<a id="my-custom-anchor-point"></a>
+<a name="my-custom-anchor-point"></a>
-<a id="my-custom-anchor-point"></a>
+<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.\
+> To avoid ambiguous references, use a unique naming scheme for custom anchors, such as adding a prefix to the `id` attribute value of custom anchors.
diff --git a/data/reusables/repositories/section-links.md b/data/reusables/repositories/section-links.md
@@ -1,3 +1,58 @@
 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 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 then click the icon to display the anchor in your browser.
-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 then 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)
+
+[Headings](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#headings) automatically create anchors which have default names created from the text of the heading, with the following rules:
-[Headings](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#headings) automatically create anchors which have default names created from the text of the heading, with the following rules:
+If you need to determine the anchor for a heading in a file you are editing, you can use the following rules:
-[Headings](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#headings) automatically create anchors which have default names created from the text of the heading, with the following rules:
+If you need to determine the anchor for a heading in a file you are editing, you can use the following rules:
+
+ * Generated identifiers are UTF-8 URI fragments.
+    * See [RFC 3986: Uniform Resource Identifier (URI): Generic Syntax, Section 3.5](https://www.rfc-editor.org/rfc/rfc3986#section-3.5).
+ * All ASCII letters are converted to lower-case.
+ * Spaces (UTF-8 codepoint `0x20`) are replaced by hyphens (`-`).
+ * Leading and trailing whitespace is removed.
+ * All other whitespace characters are removed.
+ * Paired formatting markup characters are removed, leaving only their contents (e.g., `_italics_` becomes `italics`).
- * Paired formatting markup characters are removed, leaving only their contents (e.g., `_italics_` becomes `italics`).
+ * Paired formatting markup characters are removed, leaving only their contents (for example, `_italics_` becomes `italics`).
- * Paired formatting markup characters are removed, leaving only their contents (e.g., `_italics_` becomes `italics`).
+ * Paired formatting markup characters are removed, leaving only their contents (for example, `_italics_` becomes `italics`).
+ * Punctuation and other characters not allowed in a URI fragment are removed.
+ * Other multi-byte UTF-8 characters which are valid in URI fragments are not modified.
+ * Percent Encoding is not performed.
+    * See [RFC 3986: Uniform Resource Identifier (URI): Generic Syntax, Section 2.1](https://www.rfc-editor.org/rfc/rfc3986#section-2.1) for the definition of Percent Encoding.
- * Percent Encoding is not performed.
-    * See [RFC 3986: Uniform Resource Identifier (URI): Generic Syntax, Section 2.1](https://www.rfc-editor.org/rfc/rfc3986#section-2.1) for the definition of Percent Encoding.
- * Percent Encoding is not performed.
-    * See [RFC 3986: Uniform Resource Identifier (URI): Generic Syntax, Section 2.1](https://www.rfc-editor.org/rfc/rfc3986#section-2.1) for the definition of Percent Encoding.
+ * If more than one heading has content which would result in identical output by these rules, unique names for instances after the first identical name are generated by appending a hyphen and an auto-incrementing integer in the order they appear in the rendered document.
- * If more than one heading has content which would result in identical output by these rules, unique names for instances after the first identical name are generated by appending a hyphen and an auto-incrementing integer in the order they appear in the rendered document.
+ * 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.
- * If more than one heading has content which would result in identical output by these rules, unique names for instances after the first identical name are generated by appending a hyphen and an auto-incrementing integer in the order they appear in the rendered document.
+ * 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.
+
-
+
+> [!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.
-
+
+> [!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.
+**Examples**
-**Examples**
-**Examples**
+
+A simple heading and a section link pointing to it:
+
+```markdown
+# Sample Section
+
+TEXT
+
+A link to that section: [Link Text](#sample-section).
+```
+
+A heading containing invalid characters, UTF-8 characters, two consecutive spaces between the first and second words, and formatting markup:
+
+```markdown
+# This'll  be a _Helpful_ Section About the Greek Letter Θ!
+
+TEXT
+
+A link to that section: [Link Text](#thisll--be-a-helpful-section-about-the-greek-letter-Θ).
+```
+
+Multiple headings sharing the same text:
+
+```markdown
+### This text is the same
+...content of the first section...
+
+# This text is the same
+...content of the second section...
+
+Link to the first section: [Name](#this-text-is-the-same).
+
+Link to the second section: [Name](#this-text-is-the-same-1).
+```
+
+> [!CAUTION]
+> Changing the order of sections having headings with the same name will cause their generated identifiers to change, as well, resulting in links to those sections no longer pointing to the same locations they previously pointed to.\
+> Use [Custom anchors](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#custom-anchors) to create anchors that will not be automatically changed.
-
-> [!CAUTION]
-> Changing the order of sections having headings with the same name will cause their generated identifiers to change, as well, resulting in links to those sections no longer pointing to the same locations they previously pointed to.\
-> Use [Custom anchors](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#custom-anchors) to create anchors that will not be automatically changed.
-
-> [!CAUTION]
-> Changing the order of sections having headings with the same name will cause their generated identifiers to change, as well, resulting in links to those sections no longer pointing to the same locations they previously pointed to.\
-> Use [Custom anchors](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#custom-anchors) to create anchors that will not be automatically changed.