Enable descriptive-link-text markdown lint rule (#39495)

* Enable descriptive-link-text markdown lint rule

* Address reviews

Author: Josh-Cena

.markdownlint.jsonc

@@ -170,8 +170,24 @@
   },
   // Disabled, as yari generates link fragments by replacing spaces with underscores, not dashes.
   "link-fragments": false,
-  // TODO: enable
-  "descriptive-link-text": false,
+  "descriptive-link-text": {
+    "prohibited_texts": [
+      "here",
+      "link",
+      "more",
+      "this",
+      "this link",
+      "this page",
+      "this site",
+      "this article",
+      "click here",
+      "click this link",
+      "see here",
+      "see this page",
+      "see this site",
+      "see this article",
+    ],
+  },
 
   // https://github.com/OnkarRuikar/markdownlint-rule-search-replace
   "search-replace": {

files/en-us/learn_web_development/core/css_layout/fundamental_layout_comprehension/index.md

@@ -12,7 +12,7 @@ If you have worked through this module then you will have already covered the ba
 
 ## Starting point
 
-You can download the HTML, CSS, and a set of six images [here](https://github.com/mdn/learning-area/tree/main/css/css-layout/fundamental-layout-comprehension).
+You can download the HTML, CSS, and a set of six images [in our learning-area repo](https://github.com/mdn/learning-area/tree/main/css/css-layout/fundamental-layout-comprehension).
 
 Save the HTML document and stylesheet into a directory on your computer, and add the images into a folder named `images`. Opening the `index.html` file in a browser should give you a page with basic styling but no layout, which should look something like the image below.
 

files/en-us/learn_web_development/core/scripting/debugging_javascript/index.md

@@ -50,7 +50,7 @@ There are a number of common JavaScript problems that you will want to be mindfu
 
 - Basic syntax and logic problems (again, check out [Troubleshooting JavaScript](/en-US/docs/Learn_web_development/Core/Scripting/What_went_wrong)).
 - Making sure variables, etc. are defined in the correct scope, and you are not running into conflicts between items declared in different places (see [Function scope and conflicts](/en-US/docs/Learn_web_development/Core/Scripting/Functions#function_scope_and_conflicts)).
-- Confusion about [this](/en-US/docs/Web/JavaScript/Reference/Operators/this), in terms of what scope it applies to, and therefore if its value is what you intended. You can read [What is "this"?](/en-US/docs/Learn_web_development/Core/Scripting/Object_basics#what_is_this) for a light introduction; you should also study examples like [this one](https://github.com/mdn/learning-area/blob/7ed039d17e820c93cafaff541aa65d874dde8323/javascript/oojs/assessment/main.js#L143), which shows a typical pattern of saving a `this` scope to a separate variable, then using that variable in nested functions so you can be sure you are applying functionality to the correct `this` scope.
+- Confusion about [`this`](/en-US/docs/Web/JavaScript/Reference/Operators/this), in terms of what scope it applies to, and therefore if its value is what you intended. You can read [What is "this"?](/en-US/docs/Learn_web_development/Core/Scripting/Object_basics#what_is_this) for a light introduction; you should also study examples like [this one](https://github.com/mdn/learning-area/blob/7ed039d17e820c93cafaff541aa65d874dde8323/javascript/oojs/assessment/main.js#L143), which shows a typical pattern of saving a `this` scope to a separate variable, then using that variable in nested functions so you can be sure you are applying functionality to the correct `this` scope.
 - Incorrectly using functions inside loops that iterate with a global variable (more generally "getting the scope wrong").
 
 > [!CALLOUT]

files/en-us/learn_web_development/core/scripting/functions/index.md

@@ -87,7 +87,7 @@ Bear in mind that some built-in browser functions are not part of the core JavaS
 
 **Functions** that are part of objects are called **methods**; you'll learn about objects later in the module. For now, we just wanted to clear up any possible confusion about method versus function — you are likely to meet both terms as you look at the available related resources across the Web.
 
-The built-in code we've made use of so far comes in both forms: **functions** and **methods.** You can check the full list of the built-in functions, as well as the built-in objects and their corresponding methods [here](/en-US/docs/Web/JavaScript/Reference/Global_Objects).
+The built-in code we've made use of so far comes in both forms: **functions** and **methods.** You can check the full list of the built-in functions, as well as the built-in objects and their corresponding methods [in our JavaScript reference](/en-US/docs/Web/JavaScript/Reference/Global_Objects).
 
 You've also seen a lot of **custom functions** in the course so far — functions defined in your code, not inside the browser. Anytime you saw a custom name with parentheses straight after it, you were using a custom function. In our [random-canvas-circles.html](https://mdn.github.io/learning-area/javascript/building-blocks/loops/random-canvas-circles.html) example (see also the full [source code](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/loops/random-canvas-circles.html)) from our [loops article](/en-US/docs/Learn_web_development/Core/Scripting/Loops), we included a custom `draw()` function that looked like this:
 

files/en-us/learn_web_development/core/structuring_content/creating_links/index.md

@@ -251,6 +251,8 @@ Let's look at a specific example:
 <p><a href="https://www.mozilla.org/en-US/firefox/new/">Download Firefox</a></p>
 ```
 
+<!-- markdownlint-disable descriptive-link-text -->
+
 **Bad** link text: [Click here](https://www.mozilla.org/en-US/firefox/new/) to download Firefox
 
 ```html example-bad
@@ -260,6 +262,8 @@ Let's look at a specific example:
 </p>
 ```
 
+<!-- markdownlint-enable descriptive-link-text -->
+
 Other tips:
 
 - Don't repeat the URL as part of the link text — URLs look ugly, and sound even uglier when a screen reader reads them out letter by letter.

files/en-us/learn_web_development/core/styling_basics/box_model/index.md

@@ -290,7 +290,7 @@ Can you change the size of the second box (by adding CSS to the `.alternate` cla
 {{EmbedLiveSample("box-models", "", "400px")}}
 
 > [!NOTE]
-> You can find a solution for this task [here](https://github.com/mdn/css-examples/blob/main/learn/solutions.md#the-box-model).
+> You can find a solution for this task [in our css-examples repo](https://github.com/mdn/css-examples/blob/main/learn/solutions.md#the-box-model).
 
 ### Use browser DevTools to view the box model
 

files/en-us/learn_web_development/extensions/performance/multimedia/index.md

@@ -103,7 +103,7 @@ Finally, should you want to include animated images on your page, then know that
 
 #### Serving the optimal size
 
-In image delivery the "one size fits all" approach will not yield the best results, meaning that for smaller screens you would want to serve images with smaller resolution and vice versa for larger screens. On top of that, you'd also want to serve higher resolution images to those devices that boast a high DPI screen (e.g., "Retina"). So apart from creating plenty of intermediate image variants you also need a way to serve the right file to the right browser. That's where you would need to upgrade your `<picture>` and `<source>` elements with [media](/en-US/docs/Web/HTML/Reference/Elements/source#media) and/or [sizes](/en-US/docs/Web/HTML/Reference/Elements/source#sizes) attributes. A detailed article on how to combine all of these attributes can be found [here](https://www.smashingmagazine.com/2014/05/responsive-images-done-right-guide-picture-srcset/).
+In image delivery the "one size fits all" approach will not yield the best results, meaning that for smaller screens you would want to serve images with smaller resolution and vice versa for larger screens. On top of that, you'd also want to serve higher resolution images to those devices that boast a high DPI screen (e.g., "Retina"). So apart from creating plenty of intermediate image variants you also need a way to serve the right file to the right browser. That's where you would need to upgrade your `<picture>` and `<source>` elements with [`media`](/en-US/docs/Web/HTML/Reference/Elements/source#media) and/or [`sizes`](/en-US/docs/Web/HTML/Reference/Elements/source#sizes) attributes. [Responsive images done right: A guide to `<picture>` and `srcset`](https://www.smashingmagazine.com/2014/05/responsive-images-done-right-guide-picture-srcset/) explains in detail how to combine all of these attributes.
 
 Two interesting effects to keep in mind regarding high dpi screens is that:
 

files/en-us/learn_web_development/extensions/server-side/django/development_environment/index.md

@@ -224,7 +224,7 @@ The libraries we'll use for creating our virtual environments are [virtualenvwra
 
 #### Ubuntu virtual environment setup
 
-After installing Python and pip you can install _virtualenvwrapper_ (which includes _virtualenv_). The official installation guide can be found [here](https://virtualenvwrapper.readthedocs.io/en/latest/install.html), or follow the instructions below.
+After installing Python and pip you can install _virtualenvwrapper_ (which includes _virtualenv_). You can check [the official installation guide](https://virtualenvwrapper.readthedocs.io/en/latest/install.html), or follow the instructions below.
 
 Install the tool using _pip3_:
 
@@ -463,7 +463,7 @@ Now that the repository ("repo") is created on GitHub we are going to want to cl
    In the "Clone" section, select the "HTTPS" tab, and copy the URL.
    If you used the repository name "django_local_library", the URL should be something like: `https://github.com/<your_git_user_id>/django_local_library.git`.
 
-2. Install _git_ for your local computer (you can find versions for different platforms [here](https://git-scm.com/downloads)).
+2. Install _git_ for your local computer ([official Git download guide](https://git-scm.com/downloads)).
 3. Open a command prompt/terminal and clone your repo using the URL you copied above:
 
    ```bash

files/en-us/learn_web_development/extensions/server-side/django/models/index.md

@@ -490,7 +490,7 @@ Some things to consider:
 - Should "language" be associated with a `Book`, `BookInstance`, or some other object?
 - Should the different languages be represented using model, a free text field, or a hard-coded selection list?
 
-After you've decided, add the field. You can see what we decided on GitHub [here](https://github.com/mdn/django-locallibrary-tutorial/blob/main/catalog/models.py).
+After you've decided, add the field. You can see what we decided [for our project on GitHub](https://github.com/mdn/django-locallibrary-tutorial/blob/main/catalog/models.py).
 
 Don't forget that after a change to your model, you should again re-run your database migrations to add the changes.
 

files/en-us/learn_web_development/extensions/server-side/express_nodejs/deployment/index.md

@@ -378,7 +378,7 @@ The steps are:
 
 Now that the repository ("repo") is created on GitHub we are going to want to clone (copy) it to our local computer:
 
-1. Install _git_ for your local computer (you can find versions for different platforms [here](https://git-scm.com/downloads)).
+1. Install _git_ for your local computer ([official Git download guide](https://git-scm.com/downloads)).
 2. Open a command prompt/terminal and clone your repo using the URL you copied above:
 
    ```bash

files/en-us/learn_web_development/howto/tools_and_setup/how_much_does_it_cost/index.md

@@ -77,7 +77,7 @@ Because FTP is inherently insecure, you should make sure to use SFTP — the sec
 
 ## Browsers
 
-You either already have a browser or can get one for free. If necessary, download Firefox [here](https://www.mozilla.org/en-US/firefox/all/) or Google Chrome [here](https://www.google.com/chrome/).
+You either already have a browser or can get one for free. If necessary, download [Firefox](https://www.mozilla.org/en-US/firefox/all/) or [Google Chrome](https://www.google.com/chrome/).
 
 ## Web access
 

files/en-us/learn_web_development/howto/web_mechanics/what_is_a_domain_name/index.md

@@ -171,4 +171,4 @@ Okay, we talked a lot about processes and architecture. Time to move on.
 - If you want to get hands-on, it's a good time to start digging into design and explore [the anatomy of a web page](/en-US/docs/Learn_web_development/Howto/Design_and_accessibility/Common_web_layouts).
 - It's also worth noting that some aspects of building a website cost money. Please refer to [how much it costs to build a website](/en-US/docs/Learn_web_development/Howto/Tools_and_setup/How_much_does_it_cost).
 - Or read more about [Domain Names](https://en.wikipedia.org/wiki/Domain_name) on Wikipedia.
-- You can also find [here](https://howdns.works/) a fun and colorful explanation of how DNS works.
+- The [How DNS works](https://howdns.works/) tutorial has a fun and colorful explanation.

files/en-us/mdn/writing_guidelines/howto/document_an_http_header/index.md

@@ -18,7 +18,7 @@ This article explains how to create a new reference page for an HTTP header.
 
 ## Step 2 – Check the existing HTTP header pages
 
-- Existing HTTP headers are documented [here](/en-US/docs/Web/HTTP/Reference/Headers).
+- Existing HTTP headers are documented [in the HTTP reference](/en-US/docs/Web/HTTP/Reference/Headers).
 - There are different header categories: {{Glossary("Request header")}}, {{Glossary("Response header")}}, and {{Glossary("Representation header")}}.
 - Find the category of the header you are about to document (note that some headers can be both request and response headers, depending on the context).
 - Go to an existing header reference page that has the same category.

files/en-us/mdn/writing_guidelines/howto/json_structured_data/index.md

@@ -83,12 +83,10 @@ There are two other keys, `"dictionaries"` and `"callbacks"`, operating on the s
 
 ### Update process for GroupData
 
-This file should be updated in the same PR where changes affecting the sidebar happens. That way, the sidebar is always up-to-date. Reviewers shouldn't merge PRs that don't adopt it.
+This file, located at [`files/jsondata/GroupData.json`](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json), should be updated in the same PR where changes affecting the sidebar happens. That way, the sidebar is always up-to-date. Reviewers shouldn't merge PRs that don't adopt it.
 
 To test your changes, check that the sidebar in the files in your PR displays all entries correctly.
 
-The `GroupData.json` file is located [here](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json) on GitHub.
-
 ## InterfaceData: recording interface inheritance
 
 > [!NOTE]
@@ -116,12 +114,10 @@ The value of `"Name_of_the_parent_interface"` is not a list but a single entry,
 
 ### Update process for InterfaceData
 
-The same PR adding a new interface that inherits from another one must update this file. Reviewers shouldn't merge PRs that don't do so.
+The same PR adding a new interface that inherits from another one must update this file, located at [`files/jsondata/InterfaceData.json`](https://github.com/mdn/content/blob/main/files/jsondata/InterfaceData.json). Reviewers shouldn't merge PRs that don't do so.
 
 To test your changes, check that the sidebars of each interface you edited in your PR display inheritance correctly.
 
-The `InterfaceData.json` file is located [here](https://github.com/mdn/content/blob/main/files/jsondata/InterfaceData.json) on GitHub.
-
 ## SpecData: Specification information
 
 > [!WARNING]

files/en-us/mdn/writing_guidelines/writing_style_guide/index.md

@@ -144,10 +144,14 @@ For example:
 
 Additionally, avoid using vague link text like "Click here" or "Read this article". Descriptive link text provides better context for all readers and improves the experience for users of assistive technologies.
 
+<!-- markdownlint-disable descriptive-link-text -->
+
 - **Correct**: "Learn more about [how to order flex items](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Ordering_flex_items)."
 - **Incorrect**: "Click [here](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Ordering_flex_items) to learn more."
 - **Incorrect**: "Read [this article](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Ordering_flex_items) to learn more."
 
+<!-- markdownlint-enable descriptive-link-text -->
+
 By following these guidelines, you help make MDN documentation accessible, clear, and usable by everyone, regardless of how they access the page.
 
 ### Write with SEO in mind

files/en-us/mozilla/add-ons/webextensions/api/runtime/getbackgroundpage/index.md

@@ -22,7 +22,7 @@ This is an asynchronous function that returns a {{JSxRef("Promise")}}.
 > [!NOTE]
 > In Firefox, this method cannot be used in Private Browsing mode — it always returns `null`. For more info see [Firefox bug 1329304](https://bugzil.la/1329304).
 >
-> In Chrome, this method is available only with persistent background pages, which are not available in Manifest V3, so consider using Manifest V2. See the [this](https://developer.chrome.com/docs/extensions/develop/migrate/to-service-workers) for details.
+> In Chrome, this method is available only with persistent background pages, which are not available in Manifest V3, so consider using Manifest V2. See [Migrate to a service worker](https://developer.chrome.com/docs/extensions/develop/migrate/to-service-workers) for details.
 >
 > Consider using {{WebExtAPIRef("runtime.sendMessage","runtime.sendMessage()")}} or {{WebExtAPIRef("runtime.connect","runtime.connect()")}}, which work correctly in both scenarios above.
 

files/en-us/mozilla/add-ons/webextensions/native_messaging/index.md

@@ -396,7 +396,7 @@ If you haven't managed to run the application, you should see an error message g
 
 - Check that the name passed to `runtime.connectNative()` matches the name in the app manifest
 - macOS/Linux: check that name of the app manifest is `<name>.json`.
-- macOS/Linux: check the native application's manifest file location as mentioned [here](/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_manifests#macos).
+- macOS/Linux: check the native application's manifest file location as mentioned [in the native manifests reference](/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_manifests#macos).
 - Windows: check that the registry key is in the correct place, and that its name matches the name in the app manifest.
 - Windows: check that the path given in the registry key points to the app manifest.
 

files/en-us/mozilla/firefox/releases/17/index.md

@@ -36,7 +36,7 @@ Firefox 17 shipped on November 20, 2012. This article lists key changes that are
 ### JavaScript
 
 - [`String`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) object now offers Harmony [`startsWith`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith), [`endsWith`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith), and [`contains`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes) methods ([Firefox bug 772733](https://bugzil.la/772733)).
-- The String methods [link](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/link) and [anchor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/anchor) now escape the `'"'` (quotation mark) ([Firefox bug 352437](https://bugzil.la/352437)).
+- The String methods [`link()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/link) and [`anchor()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/anchor) now escape the `'"'` (quotation mark) ([Firefox bug 352437](https://bugzil.la/352437)).
 - Experimental support for strawman `ParallelArray` object has been implemented ([Firefox bug 778559](https://bugzil.la/778559)).
 - Support to iterate [`Map`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)/[`Set`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) ([Firefox bug 725909](https://bugzil.la/725909)).
 - Disabled ECMAScript for XML (E4X), an abandoned JavaScript extension, for web content by default ([Firefox bug 778851](https://bugzil.la/778851)).

files/en-us/mozilla/firefox/releases/22/index.md

@@ -54,7 +54,7 @@ page-type: firefox-release-notes
 
 - The `properties` parameter has been removed from the `nsITreeView.getCellProperties()`, `nsITreeView.getColumnProperties()` and `nsITreeView.getRowProperties()` methods of `nsITreeView`. These methods should now return a string of space-separated property names ([Firefox bug 407956](https://bugzil.la/407956)).
 - The `inIDOMUtils.getCSSPropertyNames()` method has been implemented and will return all supported [CSS property](/en-US/docs/Web/CSS/Reference) names.
-- See [here](https://blog.mozilla.org/addons/2013/06/03/compatibility-for-firefox-22/) for more changes.
+- See [the Mozilla blog](https://blog.mozilla.org/addons/2013/06/03/compatibility-for-firefox-22/) for more changes.
 
 ### Firefox Developer Tools