Skip to content

CONTRIBUTING.md: Explain using numbered reference-style links #37831

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.

Sign up for GitHub

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

Merged
joepeeples merged 1 commit into from
Jun 29, 2026
+2 −1
Merged

CONTRIBUTING.md: Explain using numbered reference-style links #37831

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
3 changes: 2 additions & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,8 +175,9 @@ See the documentation wiki to learn more about [image partials][6].

### Links

Format links using numbered [reference-style links][8], and use relative paths for other pages published on the documentation site.
Format links using numbered [reference-style links][8], and use relative paths for other pages published on the documentation site. Don't use word-based ID labels in reference-style links; numbered links are easier to maintain for localization.
- **Not recommended**: `read the [Getting Started with Azure](/getting_started/azure/)`
- **Not recommended**: `read the [Getting Started with Azure][azure-guide]`
- **Recommended**: `read the [Getting Started with Azure][1]` with a link reference at the bottom of the file: `[1]: /getting_started/azure/`.

Avoid vague link text; let readers know where you're sending them. This is particularly important for anyone using assistive technology to scroll through links; descriptive link text helps them find what they're looking for. Any sentence containing a link should read just as well if it didn't have the link.
Expand Down
Loading