From 6246120aebcc988efc85be67327a3aef6eb58fd2 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Mon, 29 Jun 2026 15:44:34 -0400 Subject: [PATCH] explain using numbered reference-style links --- CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4a9494f3fb8..04f09f4d4e9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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.