Bug: false `markdown/no-missing-link-fragments` positive

[adamlui]

Environment

Node version: v22.15.0
npm version: v11.6.2
Local ESLint version: v9.37.0 (Currently used)
Global ESLint version: Not found
Operating System: win32 10.0.19045

Which language are you using?

commonmark

What did you do?

Configuration

import js from '@eslint/js'
import globals from 'globals'
import importPlugin from 'eslint-plugin-import'
import json from '@eslint/json'
import markdown from '@eslint/markdown'
import regexp from 'eslint-plugin-regexp'
import stylisticJS from '@stylistic/eslint-plugin'
import yml from 'eslint-plugin-yml'

export default [
    { ignores: ['**/sandbox/', '**/package-lock.json', '**/*.min.js'] },
    {
        files: ['**/*.{js,mjs}'],
        languageOptions: { ecmaVersion: 'latest', sourceType: 'script', globals: { ...globals.node }},
        plugins: { 'import': importPlugin, 'js-styles': stylisticJS, regexp },
        rules: {
            ...js.configs.recommended.rules,
            ...importPlugin.flatConfigs.recommended.rules,
            ...regexp.configs['flat/recommended'].rules,
            'indent': 'off', 'no-unexpected-multiline': 'off', 'key-spacing': 'off', // allow whitespace anywhere
            'js-styles/no-trailing-spaces': 'error', // ...except at ends of lines
            'js-styles/max-len': ['error', { 'code': 120, // limit lines to 120 chars except if containing...
                'ignoreComments': true, 'ignoreStrings': true, // ...trailing/own-line comments, quoted strings...
                'ignoreTemplateLiterals': true, 'ignoreRegExpLiterals': true }], // ...or template/regex literals
            'js-styles/no-extra-semi': 'error', // disallow unnecessary semicolons
            'quotes': ['error', 'single', // enforce single quotes...
                { 'allowTemplateLiterals': true }], // ...except backticks to avoid escaping quotes
            'comma-dangle': ['error', 'never'], // enforce no trailing commas in arrays or objects
            'no-constant-condition': 'off', // allow constant conditions
            'no-empty': 'off', // allow empty blocks
            'no-inner-declarations': 'off', // allow function declarations anywhere
            'no-useless-escape': 'off', // allow all escape chars cause ESLint sucks at detecting truly useless ones
            'no-unused-vars': ['error', { 'caughtErrors': 'none' }] // allow unused named args in catch blocks
        }
    },
    { files: ['**/*.json'], language: 'json/json', ...json.configs.recommended },
    {
        files: ['**/*.md'], language: 'markdown/commonmark', plugins: { markdown },
        rules: {
            ...markdown.configs.recommended[0].rules,
            'markdown/heading-increment': 'off', // allow headings to skip levels
            'markdown/fenced-code-language': 'off', // allow code blocks w/ no language specified
            'markdown/no-missing-label-refs': 'off', // allow missing label references
            'markdown/no-multiple-h1': 'off', // allow multi H1s
            'markdown/require-alt-text': 'off' // allow missing img alts
        }
    },
    { files: ['**/*.mjs'], languageOptions: { sourceType: 'module' }},
    { files: ['**/*.{yaml,yml}'], ...yml.configs['flat/standard'][1] }
]

...
<h1>{ } scss-to-css</h1>
...
[**More JavaScript utilities**][link-js-utils] • [Discuss][link-discuss] • [Back to top ↑](#--scss-to-css)
...

What did you expect to happen?

No err

What actually happened?

Error: 353:76 error Link fragment '#--scss-to-css' does not reference a heading or anchor in this document markdown/no-missing-link-fragments

Link to Minimal Reproducible Example

https://github.com/adamlui/scss-to-css/actions/runs/19284245065/job/55141495883

Participation

• I am willing to submit a pull request for this issue.

Additional comments

GitHub doesn't include or url encode symbols like emojis and curly braces but deletes them from heading urls for some reason, so plugin has to ignore them (and whatever else is deleted)

[lumirlumir]

Hi, @adamlui

GitHub doesn't include or url encode symbols like emojis and curly braces

I'm not sure I fully understood your bug report, but I can reproduce an error with the following minimal Markdown example:

<h1>{ } scss-to-css</h1>

[Back to top ↑](#--scss-to-css)

Also, I can see an error in the following Markdown:

<h1>👍 scss-to-css</h1>

[Back to top ↑](#--scss-to-css)

Also, even if there are no emojis or curly braces in the h1 tag, it still causes errors:

<!-- eslint markdown/no-missing-link-fragments: "error" -->

<h1>scss-to-css</h1>

[Back to top ↑](#scss-to-css)

---

Could you confirm whether the examples I mentioned above would be false positives for your use case? That would be helpful.

[adamlui]

Sup @lumirlumir when it's like this:

<h1>{ } scss-to-css</h1>

...the human expected fragment is this: #{-}-scss-to-css

But then GH strips to this #--scss-to-css

So in last example, it is true positive because you deleted the leading spaces from heading, so fragment is truly missing and click won't work

But the other examples are false because clicking works, so the plugin needs to take this account when validating, like i think all Shift + num symbols and emojis will false positive like this

[adamlui]

Wait @lumirlumir i'm wrong last example is false positive too so something else is the cause sorry (confirmed squiggly for me too)

[adamlui]

@lumirlumir someone edited my doc today and it is now all one line like

[**More JavaScript utilities**][link-js-utils] • [Discuss][link-discuss] • [Back to top ↑](#--scss-to-css)

before it is like this

<a href="https://github.com/adamlui/scss-to-css/discussions">Discuss</a> /
<a href="#--scss-to-css">Back to top ↑</a>

[lumirlumir]

Thanks for confirming!

I was able to reproduce the bug in my GitHub README.md example: https://github.com/lumirlumir/test-markdown-repro-582

When I click the button above, it works correctly, and I can verify that the fragments (slug) for scss-to-css are generated correctly.

---

This behavior is surely a bug, since the current logic doesn't handle the text inside an <h1> tag (e.g. <h1>scss-to-css</h1>) and only inspects the id attribute.

markdown/src/rules/no-missing-link-fragments.js

Lines 118 to 126 in dc4267d

	for (const match of htmlTextWithoutComments.matchAll(
	htmlIdNamePattern,
	)) {
	const extractedId = match.groups.id;
	const finalId = slugger.slug(extractedId);
	fragmentIds.add(
	ignoreCase ? finalId.toLowerCase() : finalId,
	);
	}

So, when there is no id attribute, it produces false positives even though that's valid GitHub Markdown.

---

I'm marking this issue as accepted and will start working on it.