-
Notifications
You must be signed in to change notification settings - Fork 59.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Expand Section Links documentation and add a section for Custom Anchors #33531
base: main
Are you sure you want to change the base?
Changes from 22 commits
00a99ca
deff51e
793614a
918dc44
334d6fe
23f6e59
a1d3e15
fd1133e
8d3fa36
e617a28
87aa991
c7186fa
afd0ebe
0eb2910
49d4159
08ad9d8
c6c2a56
b7dc34c
4a085ba
1096825
10d9399
9a691f1
09f5d48
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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) | ||
Check warning on line 24 in content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md GitHub Actions / lint-contentImages alternate text should be between 40-150 characters
|
||
|
||
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) | ||
Check warning on line 28 in content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md GitHub Actions / lint-contentImages alternate text should be between 40-150 characters
|
||
|
||
## 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) | ||
Check warning on line 56 in content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md GitHub Actions / lint-contentImages alternate text should be between 40-150 characters
|
||
|
||
> [!NOTE] | ||
> When viewing a conversation, you can automatically quote text in a comment by highlighting the text, then typing <kbd>R</kbd>. You can quote an entire comment by clicking {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %}, then **Quote reply**. For more information about keyboard shortcuts, see "[AUTOTITLE](/get-started/accessibility/keyboard-shortcuts)." | ||
|
@@ -66,7 +66,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) | ||
Check warning on line 69 in content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md GitHub Actions / lint-contentImages alternate text should be between 40-150 characters
|
||
|
||
To format code or text into its own distinct block, use triple backticks. | ||
|
||
|
@@ -79,7 +79,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) | ||
Check warning on line 82 in content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md GitHub Actions / lint-contentImages alternate text should be between 40-150 characters
|
||
|
||
For more information, see "[AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks)." | ||
|
||
|
@@ -93,7 +93,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) | ||
Check warning on line 96 in content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md GitHub Actions / lint-contentImages alternate text should be between 40-150 characters
|
||
|
||
Here are the currently supported color models. | ||
|
||
|
@@ -124,10 +124,80 @@ | |
|
||
{% 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 characters are removed. | ||
* Leading and trailing whitespace are removed. | ||
* Paired formatting markup characters are removed, leaving only their 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 invalid characters, 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: [Name](#this-heading-is-not-unique-in-the-file). | ||
|
||
Link to the second non-unique section: [Name](#this-heading-is-not-unique-in-the-file-1). | ||
felicitymay marked this conversation as resolved.
Show resolved
Hide resolved
|
||
``` | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I tried to reduce the amount of space given to these examples to avoid unbalancing the article. |
||
|
||
> [!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. | ||
felicitymay marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
> [!NOTE] | ||
> Custom anchors will not be included in the document outline/Table of Contents. | ||
|
||
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 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. | ||
felicitymay marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Since this is only used once, there is no need for a reusable. I moved the content directly into the article. |
||
## 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 `()`. | ||
|
@@ -205,7 +275,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) | ||
Check warning on line 278 in content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md GitHub Actions / lint-contentImages alternate text should be between 40-150 characters
|
||
|
||
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. | ||
|
||
|
@@ -226,7 +296,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) | ||
Check warning on line 299 in content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md GitHub Actions / lint-contentImages alternate text should be between 40-150 characters
|
||
|
||
For more examples, see the [GitHub Flavored Markdown Spec](https://github.github.com/gfm/#example-265). | ||
|
||
|
@@ -355,7 +425,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) | ||
Check warning on line 428 in content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md GitHub Actions / lint-contentImages alternate text should be between 40-150 characters
|
||
|
||
For more information on backslashes, see Daring Fireball's "[Markdown Syntax](https://daringfireball.net/projects/markdown/syntax#backslash)." | ||
|
||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -39,12 +39,14 @@ | |
|
||
For the rendered view of any Markdown file in a repository, including README files, {% data variables.product.product_name %} will automatically generate a table of contents based on section headings. You can view the table of contents for a README file by clicking the {% octicon "list-unordered" aria-label="Table of Contents" %} menu icon at the top left of the rendered page. | ||
|
||
![Screenshot of the README for a repository. In the upper-left corner, a dropdown menu, labeled with a list icon, is expanded to show a table of contents.](/assets/images/help/repository/readme-automatic-toc.png) | ||
Check warning on line 42 in content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md GitHub Actions / lint-contentImages alternate text should be between 40-150 characters
|
||
|
||
## Section links in README files and blob pages | ||
|
||
{% 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)." | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. As you can see from the |
||
|
||
## Relative links and image paths in README files | ||
|
||
{% data reusables.repositories.relative-links %} | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 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) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As discussed, this is a briefer, more basic summary with a link to the URI generic syntax for more information.