Add new rule: `no-generic-link-name` #1459

khiga8 · 2025-01-06T22:23:49Z

Closes: #681

This PR introduces a new lint rule to discourage generic, unhelpful link names. More context in linked issue!

While this rule has a default set of "banned names", consumers have the option to override the default and set their own banned words through the link_texts config if they'd like.

lib/md039.mjs

khiga8 · 2025-01-06T22:38:41Z

I'm not sure how to interpret this failure:

 test › markdownlint-test › validateJsonUsingConfigSchemaStrict

  Rejected promise returned by test. Reason:

  SyntaxError {
    message: 'Unexpected token } in JSON at position 42',
  }

I'd appreciate pointers!

DavidAnson · 2025-01-07T02:39:50Z

Great! I'll make a first pass review later tonight. Regarding the test failure you ask about, I think it is due to the trailing commas added to the new configuration comment at the bottom of test/long-lines-long-reference-definitions.md. JSON does not allow trailing commas.

In general, I think this would be the first built-in rule which only works in a single language (English) in its default configuration. I'm not sure how I feel about that... Certainly, all the documentation is in English because that's all I know and it's fairly common as a default language in the industry for documentation and code. However, to have the linting tool itself start to "favor" one language over another feels a little weird?

I'm open to counter-arguments or examples of another built-in rule that behaves like this. At the same time, having this rule default to an empty list would make it less useful. (Though there is precedent for that, see MD044/proper-names.) I do not think I want to start maintaining multiple translations for the phrase list because there are a lot of languages out there and I can only validate English for correctness.

DavidAnson · 2025-01-07T02:49:25Z

I was curious how a similar-ish project handled this situation: get-alex/alex#202

Ugh, that is not really a road I went to start down. My current thinking is to do something similar to MD044/proper-names and default this rule to an empty list.

I'm still open to feedback, though!

DavidAnson

Okay, it may look like a lot, but most of the changes are pretty small. :) Thanks for starting this out - let's continue the conversation around naming and default value in the body of the PR.

README.md

doc/md059.md

helpers/helpers.cjs

test/markdown-in-html.md

test/no-generic-link-name-config-override.md

test/no-generic-link-name.md

test/table-content-with-issues.md

…d simplify slightly.

schema/markdownlint-config-schema-strict.json

Bumps [eslint](https://github.com/eslint/eslint) from 9.17.0 to 9.18.0. - [Release notes](https://github.com/eslint/eslint/releases) - [Changelog](https://github.com/eslint/eslint/blob/main/CHANGELOG.md) - [Commits](eslint/eslint@v9.17.0...v9.18.0) --- updated-dependencies: - dependency-name: eslint dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <[email protected]>

Bumps [@stylistic/eslint-plugin](https://github.com/eslint-stylistic/eslint-stylistic/tree/HEAD/packages/eslint-plugin) from 2.12.1 to 2.13.0. - [Release notes](https://github.com/eslint-stylistic/eslint-stylistic/releases) - [Changelog](https://github.com/eslint-stylistic/eslint-stylistic/blob/main/CHANGELOG.md) - [Commits](https://github.com/eslint-stylistic/eslint-stylistic/commits/v2.13.0/packages/eslint-plugin) --- updated-dependencies: - dependency-name: "@stylistic/eslint-plugin" dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <[email protected]>

Bumps [json-schema-to-typescript](https://github.com/bcherny/json-schema-to-typescript) from 15.0.3 to 15.0.4. - [Changelog](https://github.com/bcherny/json-schema-to-typescript/blob/master/CHANGELOG.md) - [Commits](https://github.com/bcherny/json-schema-to-typescript/commits) --- updated-dependencies: - dependency-name: json-schema-to-typescript dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <[email protected]>

…ate and export resolveModule helper from markdownlint-cli2.

khiga8 · 2025-01-18T04:42:50Z

lib/md059.mjs

+          addErrorContext(
+            onError,
+            labelText.startLine,
+            text,


- errorContext: `[click␍␊ + errorContext: `[click␊ here]`,

I can't figure out why Windows behaves differently and returns a different text for the link test case with a line break. Curious if you might have any ideas @DavidAnson.

This looks like a \r\n vs. \n line ending difference. If you're getting this error, it's reporting an error that spans multiple lines. I left a comment about preventing that by checking startLine and endLine of the span. (See my comment on the main chat before spending time on this.)

khiga8 · 2025-01-18T04:50:28Z

Hey @DavidAnson! I believe I've addressed all your comments now. I have one remaining issue I'd appreciate your eyes on - #1459 (comment).

DavidAnson · 2025-01-19T00:40:17Z

Thank you! I replied to that open issue above. (FYI, I may not get back to this for a couple of days.)

At this stage in the process, I'll make another/final pass over the entire change. It's likely I'll have more nitpicks. Are you okay with me applying them to your PR here? What I typically do is squash the author's comments into one (attributed to then) with a following commit by me titled something like "final tweaks for previous commit". Unless you enjoy my nitpicking, this is probably the most efficient option. :)

One thing I'll do is review every new violation in test-repos. Skimming that now, it looks like the vast majority are "here" and "link" which is expected (plus a couple of "more"s). However, there are about 20 like this in mdn which deserve better understanding. If you beat me to that, please reply here with your thoughts:

test-repos/mdn-content/files/en-us/web/html/attributes/rel/preload/index.md: 105: MD059/descriptive-link-text Link text should be descriptive [Context: "[\`<link>\`]"]

khiga8 · 2025-02-02T00:21:21Z

Hey @DavidAnson! Sorry for the delay here!

(See my comment on the main chat before spending time on this.)
At this stage in the process, I'll make another/final pass over the entire change. It's likely I'll have more nitpicks. Are you okay with me applying them to your PR here?

Yep, I'm totally fine with you applying changes here! I haven't addressed the failing test yet - let me know if you'd like me to follow-up there, or with anything else.

If you beat me to that, please reply here with your thoughts:

It looks like the linter is flagging link texts with <link>, which links to an this article about the link HTML flag. In this scenario, <link> actually describes the content of the linked page, and isn't used in a generic way, so we definitely don't want to flag this.

Right now, we're stripping all non-alphanumeric characters in order with the intent to flag texts like link! and click here., but I'm thinking we'd want to be more conservative in this method, and only strip specific punctuations like ,!.:.

DavidAnson · 2025-02-10T03:44:30Z

In the mdn scenario, it's [`<link>`](/en-US/docs/Web/HTML/Element/link) which means there's a code span inside the link text. I think that scenario should be exempt from this rule, so will look at filtering such things out at a token level vs. via character replacement. This PR is next on my list, so I expect to spend some time on it this week. I'll take care of the above as part of my final pass on this. :)

DavidAnson

Accepting PR into a dedicated branch for final review.

this addresses errors observed by dependabot when upgrading to the latest version of `markdownlint`. there is a new lint, added in DavidAnson/markdownlint#1459, that introduces forbidden link text to discourage generic `here` text in links. this fixes sentences that included a link labeled "here". * #3918 * https://github.com/linkerd/linkerd2-proxy/actions/runs/15043224730/job/42279610780?pr=3918 * https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md059.md * DavidAnson/markdownlint#1459 * DavidAnson/markdownlint#681 ``` Summary: 3 error(s) Error: docs/FUZZING.md:17:13 MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md059.md Error: docs/FUZZING.md:100:2 MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md059.md Error: README.md:90:2 MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md059.md Error: Failed with exit code: 1 ``` Signed-off-by: katelyn martin <[email protected]>

* chore(docs): address `no-generic-link-test` lint (#3923) this addresses errors observed by dependabot when upgrading to the latest version of `markdownlint`. there is a new lint, added in DavidAnson/markdownlint#1459, that introduces forbidden link text to discourage generic `here` text in links. this fixes sentences that included a link labeled "here". * #3918 * https://github.com/linkerd/linkerd2-proxy/actions/runs/15043224730/job/42279610780?pr=3918 * https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md059.md * DavidAnson/markdownlint#1459 * DavidAnson/markdownlint#681 ``` Summary: 3 error(s) Error: docs/FUZZING.md:17:13 MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md059.md Error: docs/FUZZING.md:100:2 MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md059.md Error: README.md:90:2 MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md059.md Error: Failed with exit code: 1 ``` Signed-off-by: katelyn martin <[email protected]> * build(deps): bump DavidAnson/markdownlint-cli2-action (#3923) Bumps [DavidAnson/markdownlint-cli2-action](https://github.com/davidanson/markdownlint-cli2-action) from 19.1.0 to 20.0.0. - [Release notes](https://github.com/davidanson/markdownlint-cli2-action/releases) - [Commits](DavidAnson/markdownlint-cli2-action@05f3221...992badc) --- updated-dependencies: - dependency-name: DavidAnson/markdownlint-cli2-action dependency-version: 20.0.0 dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <[email protected]> --------- Signed-off-by: katelyn martin <[email protected]> Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

SchroederSteffen · 2025-06-02T11:57:11Z

doc/md059.md

+
+Parameters:
+
+- `link_texts`: List of restricted link texts (`string[]`, default `[]`)


The default is documented as [] here, but the defaultBannedText array contains entries.
What's the intended behavior? Default or no default?

Sorry, this is an error in the documentation, I'll fix it soon.

Actually, this is correct as implemented in the current release - you were maybe looking at an early version.

https://github.com/DavidAnson/markdownlint/blob/main/doc/md059.md

oh perfect. sorry for the false alert!

khiga8 added 9 commits January 6, 2025 11:35

Start doc page for new rule

a1c000f

Add rule and test

ddf030e

Move validLink check to micromark helper

0a60d3d

Add documentation for new rule

b575b03

Add downcase and strip helper function

443b77c

Update all tests so they pass

9cee2db

Update tests

9fbf423

update rule description

47db690

update snapshots

2b93c7e

khiga8 commented Jan 6, 2025

View reviewed changes

lib/md039.mjs Show resolved Hide resolved

khiga8 changed the base branch from main to next January 6, 2025 22:33

khiga8 mentioned this pull request Jan 6, 2025

[Proposal] Rule to discourage generic link text #681

Closed

DavidAnson requested changes Jan 7, 2025

View reviewed changes

DavidAnson and others added 10 commits January 7, 2025 04:28

Update test repo snapshots.

d4352c7

Update MD039/no-space-in-links to remove outdated validLink helper an…

637975f

…d simplify slightly.

Rename no-generic-link-name to descriptive-link-text

e141567

Move and rename downcase method.

b93cfef

Remove validLink helper

bbac469

Address more stylistic comments

bfbcadd

Remove no longer used

7b0467b

Address more comments

6be4eea

Update schema and snapshots

6386afe

Auto-generate docs

3a5e27f

khiga8 commented Jan 7, 2025

View reviewed changes

schema/markdownlint-config-schema-strict.json Outdated Show resolved Hide resolved

khiga8 added 3 commits January 7, 2025 15:56

Merge branch 'next' into kh-add-new-rule

da24423

Fix test

52aa2c8

Update schema

163c50b

dependabot bot and others added 13 commits January 12, 2025 19:48

Stop using module.createRequire (problematic under webpack), incorpor…

53ff5c4

…ate and export resolveModule helper from markdownlint-cli2.

Update to version 0.37.4.

a4c553a

Surface error for multi-line links

e2413d4

update snapshots

3da8f5c

fix bracket

6237579

Merge branch 'next' into kh-add-new-rule

1db59f5

Update snapshots

c62e329

Run script again after pulling in latest

d062477

Update snapshots on test repos

d130017

remove whitespace

8f3d764

khiga8 commented Jan 18, 2025

View reviewed changes

khiga8 requested a review from DavidAnson January 18, 2025 04:50

khiga8 changed the title ~~[WIP] Add new rule: no-generic-link-name~~ Add new rule: no-generic-link-name Feb 2, 2025

DavidAnson changed the base branch from next to md059 February 10, 2025 03:49

DavidAnson marked this pull request as ready for review February 10, 2025 03:53

DavidAnson approved these changes Feb 10, 2025

View reviewed changes

DavidAnson merged commit 8f3d764 into DavidAnson:md059 Feb 10, 2025
14 of 18 checks passed

khiga8 deleted the kh-add-new-rule branch February 19, 2025 23:41

cratelyn mentioned this pull request May 16, 2025

chore(deps): bump DavidAnson/markdownlint-cli2-action linkerd/linkerd2-proxy#3923

Merged

SchroederSteffen reviewed Jun 2, 2025

View reviewed changes


		Parameters:

		- `link_texts`: List of restricted link texts (`string[]`, default `[]`)

Uh oh!

Add new rule: no-generic-link-name #1459

Add new rule: no-generic-link-name #1459

Uh oh!

Conversation

khiga8 commented Jan 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

khiga8 commented Jan 6, 2025

Uh oh!

DavidAnson commented Jan 7, 2025

Uh oh!

DavidAnson commented Jan 7, 2025

Uh oh!

DavidAnson left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

khiga8 Jan 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DavidAnson Jan 19, 2025

Choose a reason for hiding this comment

Uh oh!

khiga8 commented Jan 18, 2025

Uh oh!

DavidAnson commented Jan 19, 2025

Uh oh!

khiga8 commented Feb 2, 2025

Uh oh!

DavidAnson commented Feb 10, 2025

Uh oh!

DavidAnson left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

SchroederSteffen Jun 2, 2025

Choose a reason for hiding this comment

Uh oh!

DavidAnson Jun 2, 2025

Choose a reason for hiding this comment

Uh oh!

DavidAnson Jun 3, 2025

Choose a reason for hiding this comment

Uh oh!

SchroederSteffen Jun 3, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Add new rule: `no-generic-link-name` #1459

Add new rule: `no-generic-link-name` #1459

khiga8 commented Jan 6, 2025 •

edited

Loading

khiga8 Jan 18, 2025 •

edited

Loading