Skip to content
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

Merged
Changes from 1 commit
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
00a99ca
Add more details, rules, behavior, and examples to section links reus…
dodexahedron Jun 17, 2024
deff51e
Add section for custom anchors
dodexahedron Jun 17, 2024
793614a
Added additional line breaks suggested by the linter
dodexahedron Jun 17, 2024
918dc44
Add line break at the end of the file, requested by linter
dodexahedron Jun 17, 2024
334d6fe
Changed list style to use * instead of -
dodexahedron Jun 17, 2024
23f6e59
Minor tweaks to the tip text for easier reading.
dodexahedron Jun 17, 2024
a1d3e15
Modified language to more closely align with the style guide
dodexahedron Jun 17, 2024
fd1133e
Style and content changes
dodexahedron Jun 17, 2024
8d3fa36
Clarification, re-ordering, language tweaks, and linking to resources
dodexahedron Jun 17, 2024
e617a28
Add a tip to use custom anchors to address the called-out issue
dodexahedron Jun 17, 2024
87aa991
Apparently footnotes aren't allowed there
dodexahedron Jun 17, 2024
c7186fa
Included the links that were previously added as footnotes to the bul…
dodexahedron Jun 17, 2024
afd0ebe
Shortened these to make the linter a little happier
dodexahedron Jun 17, 2024
0eb2910
Caution feels more appropriate here.
dodexahedron Jun 17, 2024
49d4159
Make these links relative
dodexahedron Jun 17, 2024
08ad9d8
Fix URI fragment for link to headers section.
dodexahedron Jun 17, 2024
c6c2a56
Apply suggestions from code review
felicitymay Sep 16, 2024
b7dc34c
Merge branch 'main' into dodexahedron-section-links-and-custom-links-…
felicitymay Sep 16, 2024
4a085ba
Updates to address comments part 1
felicitymay Sep 16, 2024
1096825
Delete data/reusables/repositories/custom-anchors.md
felicitymay Sep 16, 2024
10d9399
Update to move the detailed content into the basic writing article
felicitymay Sep 16, 2024
9a691f1
Add link to README file for more info
felicitymay Sep 16, 2024
09f5d48
A few minor updates from self-review
felicitymay Sep 16, 2024
f535f75
Merge branch 'main' into dodexahedron-section-links-and-custom-links-…
felicitymay Sep 20, 2024
db47583
Apply suggestions from code review
felicitymay Sep 23, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
A few minor updates from self-review
  • Loading branch information
felicitymay authored Sep 16, 2024
commit 09f5d489003ba9c1766458a8bc3f79bb062a5ba4
Original file line number Diff line number Diff line change
Expand Up @@ -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

View workflow job for this annotation

GitHub Actions / lint-content

Images alternate text should be between 40-150 characters

Image alternate text is 162 characters long.

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

View workflow job for this annotation

GitHub Actions / lint-content

Images alternate text should be between 40-150 characters

Image alternate text is 185 characters long.

## Styling text

Expand Down Expand Up @@ -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

View workflow job for this annotation

GitHub Actions / lint-content

Images alternate text should be between 40-150 characters

Image alternate text is 167 characters long.

> [!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)."
Expand All @@ -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

View workflow job for this annotation

GitHub Actions / lint-content

Images alternate text should be between 40-150 characters

Image alternate text is 184 characters long.

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

Expand All @@ -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

View workflow job for this annotation

GitHub Actions / lint-content

Images alternate text should be between 40-150 characters

Image alternate text is 173 characters long.

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

Expand All @@ -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

View workflow job for this annotation

GitHub Actions / lint-content

Images alternate text should be between 40-150 characters

Image alternate text is 173 characters long.

Here are the currently supported color models.

Expand Down Expand Up @@ -158,9 +158,9 @@

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 first non-unique section: [Link Text](#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).
Link to the second non-unique section: [Link Text](#this-heading-is-not-unique-in-the-file-1).
```

> [!NOTE]
Expand All @@ -172,7 +172,7 @@

## 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.
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.
Expand All @@ -195,8 +195,7 @@
```

> [!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.
> Custom anchors are not considered by the automatic naming and numbering behavior of automatic heading links.

## Images

Expand Down Expand Up @@ -275,7 +274,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 277 in content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md

View workflow job for this annotation

GitHub Actions / lint-content

Images alternate text should be between 40-150 characters

Image alternate text is 180 characters long.

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.

Expand All @@ -296,7 +295,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 298 in content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md

View workflow job for this annotation

GitHub Actions / lint-content

Images alternate text should be between 40-150 characters

Image alternate text is 203 characters long.

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

Expand Down Expand Up @@ -425,7 +424,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 427 in content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md

View workflow job for this annotation

GitHub Actions / lint-content

Images alternate text should be between 40-150 characters

Image alternate text is 177 characters long.

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

Expand Down
Loading