Pandoc-style footnotes should not be flagged by "no-shortcut-reference-link" or"no-undefined-references"

[McGlear]

Subject of the feature

Pandoc-style footnotes work either inline or as reference-style blocks:

This is a text with an inline footnote ^[This is an inline footnote].
Longer block footnotes are also possible [^longnote].

[^longnote]: I am a longer footnote

While this feature has been implemented in Remark using remark-footnotes, I have not found a way to make the remark-linter honor that syntax while no-shortcut-reference-link and no-undefined-references are active.

no-shortcut-reference-link flags both inline and block footnoes.
no-undefined-references flags only inline footnotes.

Expected behaviour

no-shortcut-reference-link and no-undefined-references should ignore references when they are actually footnotes (as indicated by ^) while still flagging regular references without a definition or "lazy" references not using the trailing [].

Info

I am using remark-lint within the Atom editor through the linter-markdown package. The .remarkrc contains

{
  "plugins": [
    "preset-lint-recommended",
    "preset-lint-consistent"
  ],
  "settings": {
    "commonmark": true
  }
}

[wooorm]

I believe that if you add remark-footnotes before the linting presets (and install it), it should work?

  "plugins": [
+   "footnotes",
    "preset-lint-recommended",
    "preset-lint-consistent"

[McGlear]

You are right. When using the linter through remark-cli together with --use footnotes it works fine.

I haven't figured out a way to actually use remark-footnotes within atom/linter-markdown yet, so the references still get flagged inside atom, but I suppose that's more of an npm/windows/atom/linter-markdown/personal-incompetence issue, and not related to remark-lint per se.

[wooorm]

I use linter-remark in atom: it loads remark config files, so if you move the cli options to a config file, it should work!

[McGlear]

I played around with linter-remark yesterday, too.

To be honest, I am not particularly happy with either linter-markdown or linter-remark in atom at the moment. I find the mere fact that - "just" for linting markdown - I need to add non-atom packages through npm quite tedious. And judging from some of the github issues in the linter-markdown repo I am not the only one. In those issues, other people mention all the problems that arise (especially with maintaining those external packages) and it also seems like many people can't really extract the necessary information from the current documentation (yet those of us running into those problems also obviously aren't able to improve the docs and submit them via PRs - if we were, we wouldn't need to ask ;) ).

Concerning this particular issue (footnotes getting flagged), I wonder what adding the footnotes plugin does exactly to circumvent the flagging. Does it filter the footnote style links before the linter is run, thus eliminating those footnote-references that remark-lint would normally flag? Or does it actually add anything to the internal pattern matching scheme of the linter? It seems counterintuitive to run a remark-plugin just for the sake of changing what the linter does or does not flag (and requiring the user to do so then creates problems when atom packages like linter-markdown that try to make isolated use of the remarklint linter without ever intending to make use of the remark functionality beyond the linting). Again, I have no idea how remark or remark-lint work. But wouldn't it make sense to keep linting as seperate from the rest of the processing part as possible?

[wooorm]

Sorry, that it’s so confusing.

remark-lint is part of the remark ecosystem: lots of tools for working with Markdown. Linting it is one thing. Another is converting to HTML. To man pages. Generating tables of contents and other sections. remark is part of the unified collective. hundreds of projects for dealing with content. HTML, XML, markdown, prose, and more. That’s why, every plugin does exactly one thing. Linting plugins lint. Footnote plugins footnote. They integrate with each other: they’re separate but can be combined. Not everyone uses footnotes, so parsing something as footnotes if it should’ve been a link, is a bad idea in my opinion.

More information about unified is on its website: https://unifiedjs.com.

Does that help? Anything else I can help with?

[McGlear]

Well, I think I understand what remark could do for a user. Personally, I rely on pandoc for conversion, so I don't require any of the conversion features that remark could provide. As far as I know, there (currently) aren't any linters for pandoc. And no non-remark options for linting markdown within atom.

What I don't entirely understand is this:

Obviously, this statement is true: "Not everyone uses footnotes". But why should the linter flag syntactically correct footnotes [^footnote] or ^[footnote] for not conforming to reference syntax? From what I understand, a linter checks whether something might be a reference ("Hey, I detect square brackets!") and then compares what the user has written to what markdown specifications say a reference should look like ("Hey! He is using a reference-link but doesn't define it later in the document. I should flag that, so he can find his error." or "Hey, he is being lazy! Markdown specifications clearly state that references should have two sets of square brackets! Better flag that to help him write consistent code"). And that's awesome. But the remark linter flags things that weren't intended to be references to begin with. And the user clearly marked them as not being references by adding the ^ character, following markdown syntax standards.
I could make the same argument saying:
"Not everyone uses references. Parsing something as a reference even though it could have been meant as an external link is a bad idea." and have my linter flag this [I am a reference link][link id] with an error code like ("Markdown links use parantheses. Correct your format to [linkname](url)" - which of course would not be useful linting, because the user clearly wrote a reference-style link in compliance with markdown style guides and never intended that reference link to comply with standards for external links.

It's possible that this discussion comes down to "What standards should markdown linters currently adhere to, considering that markdown is not (yet) standardized across all and any converters / use cases" - I would argue that footnotes [^footnote] are already common enough to consider them "standard" - just like references using [ref text][1] are. But opinions might differ on that.

[wooorm]

What Markdown is, is mostly accepted to be, or at least moving towards, CM or GFM. Reference links are a part of Markdown in its original form, in CM, and in GFM. Other parsers, such as Pandoc have unstandardized features (note: CM is maintained by the author of Pandoc). Footnotes are a popular feature indeed. Several parsers support different syntaxes for footnotes. If you want to support a different syntax for footnotes, fork remark-footnotes, and remark-lint will still work.

[McGlear]

As I said, it therefore comes down to which parts are "standard enough" to be included without loading extra plugins into remark. Just linting with recommended presets will currently not flag references but will flag footnotes. That's fair.
When looking at using remark-lint through atom packages, things get tricky. It's not a problem when the user of the linter-remark or the linter-markdown packages is willing and able to install non-atom packages through npm and keep them updated. (Even though I'm still not sure whether it's even possible to use non-linting plugins in conjunction with linter-markdown or whether that then requires linter-remark). That's also why I closed this issue, because in the end I'm having trouble with the atom packages, not with remark-lint. My comments here were mainly for clarification and understanding the reasoning behind what parts of markdown syntax remark takes "for granted" even without extra plugins.

[wooorm]

Good! Glad I could clarify that.

I haven’t worked on linter-markdown in years. I think linter-remark is a better idea, that’s why I maintain it. linter-markdown seems abandoned, unfortunately.

The reason for preferring linter-remark, and local plugins/configurations, is exactly because things like footnotes aren’t the same for every file you may work on. Leading to mistakes if they’re toggled on globally in linter-markdown, but not in the project you’re currently working on.
I do get that it’s annoying to use, if you don’t already have a package.json / node_modules. you could try to put your config file in your home folder (~)? And install the packages there? That would ensure all files that are checked, will use that configuration.

[McGlear]

I will give that another try, thanks a lot!

[SwuduSusuwu]

I believe that if you add remark-footnotes before the linting presets (and install it), it should work?

  "plugins": [
+   "footnotes",
    "preset-lint-recommended",
    "preset-lint-consistent"

Do not understand how to do this in the context of https://github.com/orgs/remarkjs/discussions/1392 .

It sounds as if (4 years ago) the maintainers had issues to include support for footnotes. Is it still too difficult to fix Remark-lint's defaults (such as to allow footnotes) or was this just forgot?

[SwuduSusuwu]

Several parsers support different syntaxes for footnotes.

Am just aware of the "Pandoc" style of footnotes.
Asked Assistant about other versions of footnotes, but all it gave was the [^<number>] version of footnotes.
Which version of footnotes does Remark-lint allow you to use?

[wooorm]

GFM has footnotes. remark-gfm does that. GH is big.