feat: flag bad descriptive text

styles/Canonical/027-non-descriptive-link-text.yml

@@ -0,0 +1,16 @@
+# 027 - Flag non-descriptive link text
+
+# Copilot assisted.
+
+extends: existence
+message: "Use descriptive link text instead of '%s' to improve accessibility."
+link: https://docs.ubuntu.com/styleguide/en
+scope: raw
+nonword: true
+ignorecase: true
+level: warning
+tokens:
+  - '\[[^\]]*\b(here|these|this|more|link)\b[^\]]*\]\([^\)]+\)'
+  - '`[^`<]*\b(here|these|this|more|link)\b[^`<]*<[^>]+>`_'
+  - ':([^\s\n:]+:)*(doc|ref|any|download|reftype|class|func):`[^`]*\b(here|these|this|more|link)\b[^`]*`'
+  - '\{([^\}\s\n]+:)*(doc|ref|any|download|reftype|class|func)\}`[^`]*\b(here|these|this|more|link)\b[^`]*`' 

tests/data/manifest.yml

@@ -549,6 +549,176 @@ rules:
           As shown by Smith and colleagues in their paper.
         expect:
           triggers: []
+  026-hints-tips:
+    cases:
+      - id: valid
+        filetypes: [md, rst]
+        content: |
+          .. hint::
+              This is a reST hint.
+          .. tip::
+              This is a reST tip.
+          ```{hint}
+          This is a MyST hint.
+          ```
+          ```{tip}
+          This is a MyST tip.
+          ```
+          ````{hint}
+          This is a deeper MyST hint.
+          ````
+          ````{tip}
+          This is a deeper MyST tip.
+          ````
+          :::{hint}
+          This is a colon-fenced MyST hint.
+          :::
+          :::{tip}
+          This is a colon-fenced MyST tip.
+          :::
+          ::::{hint}
+          This is a deeper colon-fenced MyST hint.
+          ::::
+          ::::{tip}
+          This is a deeper colon-fenced MyST tip.
+          ::::
+        expect:
+          triggers:
+            - '.. hint::'
+            - '.. tip::'
+            - '```{hint}'
+            - '```{tip}'
+            - '````{hint}'
+            - '````{tip}'
+            - ':::{hint}'
+            - ':::{tip}'
+            - '::::{hint}'
+            - '::::{tip}'
+          severity: suggestion
+  027-non-descriptive-link-text:
+    cases:
+      - id: bad-link-text-md
+        filetypes: [md]
+        content: |
+          See [here](https://example.com) for details.
+          Go to [click here](https://example.com) to learn.
+          Read [this](https://example.com/doc) for more.
+          Check [these](https://example.com/list) items.
+          For details, [read more](https://example.com).
+          To get started, [learn more](https://example.com).
+          See [more](https://example.com) about the topic.
+          Follow this [link](https://example.com).
+          Visit [this link](https://example.com) for help.
+          See [this page](https://example.com) for info.
+          Read [this document](https://example.com) now.
+          See [this article](https://example.com/blog) too.
+          See [more information](https://example.com) below.
+          See [more info](https://example.com/faq) here.
+          Try [clicking here](https://example.com/try) for setup.
+          See [the link to docs](https://example.com/docs) now.
+          See [see more details](https://example.com/info) below.
+          See {doc}`here <target>` for details.
+          See {ref}`this <label>` for setup.
+          See {any}`these <something>` for examples.
+          Get {download}`this <file.tar.gz>` archive.
+          See {ref}`try this <label>` for more.
+          See {external+sphinxcontrib-mermaid:doc}`this link <target>` for details.
+          See {external+sphinxcontrib-mermaid:py:class}`this link <target>` for details.
+        expect:
+          triggers:
+            - '[here](https://example.com)'
+            - '[click here](https://example.com)'
+            - '[this](https://example.com/doc)'
+            - '[these](https://example.com/list)'
+            - '[read more](https://example.com)'
+            - '[learn more](https://example.com)'
+            - '[more](https://example.com)'
+            - '[link](https://example.com)'
+            - '[this link](https://example.com)'
+            - '[this page](https://example.com)'
+            - '[this document](https://example.com)'
+            - '[this article](https://example.com/blog)'
+            - '[more information](https://example.com)'
+            - '[more info](https://example.com/faq)'
+            - '[clicking here](https://example.com/try)'
+            - '[the link to docs](https://example.com/docs)'
+            - '[see more details](https://example.com/info)'
+            - '{doc}`here <target>`'
+            - '{ref}`this <label>`'
+            - '{any}`these <something>`'
+            - '{download}`this <file.tar.gz>`'
+            - '{ref}`try this <label>`'
+            - '{external+sphinxcontrib-mermaid:doc}`this link <target>`'
+            - '{external+sphinxcontrib-mermaid:py:class}`this link <target>`'
+          severity: warning
+      - id: bad-link-text-rst
+        filetypes: [rst]
+        content: |
+          See `here <https://example.com>`_ for details.
+          Go to `click here <https://example.com>`_ to learn.
+          Read `this <https://example.com>`_ for more.
+          See `these <https://example.com>`_ items.
+          For more, `read more <https://example.com>`_.
+          See `learn more <https://example.com>`_ to begin.
+          See `more <https://example.com>`_ about it.
+          Follow this `link <https://example.com>`_.
+          See `this page <https://example.com>`_ for info.
+          Try `clicking here <https://example.com>`_ for setup.
+          See `the link to docs <https://example.com>`_ now.
+          See :doc:`here <target>` for the guide.
+          See :ref:`this <label>` for setup.
+          See :ref:`these <label>` for examples.
+          See :doc:`read more <target>` for details.
+          See :any:`learn more <target>` too.
+          Get :download:`this <file.tar.gz>` archive.
+          See :ref:`try this <label>` for more.
+          See :external+invname:ref:`this <some.address>`
+          See :external+invname:py:class:`this link <some.address>`
+        expect:
+          triggers:
+            - '`here <https://example.com>`_'
+            - '`click here <https://example.com>`_'
+            - '`this <https://example.com>`_'
+            - '`these <https://example.com>`_'
+            - '`read more <https://example.com>`_'
+            - '`learn more <https://example.com>`_'
+            - '`more <https://example.com>`_'
+            - '`link <https://example.com>`_'
+            - '`this page <https://example.com>`_'
+            - '`clicking here <https://example.com>`_'
+            - '`the link to docs <https://example.com>`_'
+            - ':doc:`here <target>`'
+            - ':ref:`this <label>`'
+            - ':ref:`these <label>`'
+            - ':doc:`read more <target>`'
+            - ':any:`learn more <target>`'
+            - ':download:`this <file.tar.gz>`'
+            - ':ref:`try this <label>`'
+            - ':external+invname:ref:`this <some.address>`'
+            - ':external+invname:py:class:`this link <some.address>`'
+          severity: warning
+      - id: clean-link-text
+        filetypes: [md, rst]
+        content: |
+          See [the installation guide](https://example.com/install) for details.
+          Read [Ubuntu documentation](https://example.com/docs) for more.
+          Follow the [getting started tutorial](https://example.com/start).
+          Download [the latest release](https://example.com/releases).
+          Visit `Ubuntu documentation <https://example.com>`_ for help.
+          See `the contributor guide <https://example.com>`_ for details.
+          See :doc:`security overview <security>` for details.
+          See :ref:`configuration options <config-opts>` for help.
+          See {ref}`configuration options <config-opts>` for help.
+          See {doc}`security overview <security>` for details.
+          You can find more information about this here in the prose.
+          Use this command to install these packages.
+          See [the linked resources](https://example.com/resources) page.
+          Visit `linked resources <https://example.com>`_ for help.
+          See :doc:`furthermore <target>` for details.
+          See {ref}`linking guide <label>` for help.
+        expect:
+          triggers: []
+          severity: suggestion
   # 400-Enforce-inclusive-terms:
   #   cases:
   #     - id: valid
@@ -2106,49 +2276,4 @@ rules:
                  Line 35
                  Line 36
           severity: warning
-  026-hints-tips:
-    cases:
-      - id: valid
-        filetypes: [md, rst]
-        content: |
-          .. hint::
-              This is a reST hint.
-          .. tip::
-              This is a reST tip.
-          ```{hint}
-          This is a MyST hint.
-          ```
-          ```{tip}
-          This is a MyST tip.
-          ```
-          ````{hint}
-          This is a deeper MyST hint.
-          ````
-          ````{tip}
-          This is a deeper MyST tip.
-          ````
-          :::{hint}
-          This is a colon-fenced MyST hint.
-          :::
-          :::{tip}
-          This is a colon-fenced MyST tip.
-          :::
-          ::::{hint}
-          This is a deeper colon-fenced MyST hint.
-          ::::
-          ::::{tip}
-          This is a deeper colon-fenced MyST tip.
-          ::::
-        expect:
-          triggers:
-            - '.. hint::'
-            - '.. tip::'
-            - '```{hint}'
-            - '```{tip}'
-            - '````{hint}'
-            - '````{tip}'
-            - ':::{hint}'
-            - ':::{tip}'
-            - '::::{hint}'
-            - '::::{tip}'
-          severity: suggestion
+

vale.ini

@@ -30,6 +30,7 @@ Canonical.025a-latinisms-with-english-equivalents = suggestion
 Canonical.025b-latinisms-to-reconsider = suggestion
 Canonical.025c-latinisms-to-avoid = suggestion
 Canonical.026-hints-tips = suggestion
+Canonical.027-bad-descriptive-links = warning
 Canonical.400-Enforce-inclusive-terms = error
 Canonical.500-Repeated-words = warning