starred/markdownlint

Fork 0

mirror of https://github.com/DavidAnson/markdownlint.git synced 2026-04-25 01:05:55 +03:00

[GH-ISSUE #1670] MD011: false positive when cross ref bibliography when writting academic paper after () #2580

New issue

Open

opened 2026-03-07 20:09:03 +03:00 by kerem · 6 comments

kerem commented

2026-03-07 20:09:03 +03:00

Owner

Originally created by @singledoggy on GitHub (Jul 13, 2025).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1670

(somthing)[@citekey]

I’m currently using nvim-lint, and this will be autofixed to

[somthing](@citekey)

Though I’m not sure if it’s a feature of markdownlint. I’ve temporarily disabled this check.

In the syntax of rmarkdown:

Items can be cited directly within the documentation using the syntax @key where key is the citation key in the first line of the entry, e.g., @R-base. To put citations in parentheses, use [@key]. To cite multiple entries, separate the keys by semicolons, e.g., [@key-1; @key-2; @key-3]. To suppress the mention of the author, add a minus sign before @, e.g., [-@R-base].

Since these cited items may need to be referenced after certain parenthesis symbols (), especially when there are some abbreviations, I’m not sure whether this should be considered as MD011.

This issue was originally placed in the wrong repository. I have now moved it here.

markdownlint/markdownlint#525

Originally created by @singledoggy on GitHub (Jul 13, 2025). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1670 ``` (somthing)[@citekey] ``` I’m currently using [nvim-lint](https://github.com/mfussenegger/nvim-lint), and this will be autofixed to ``` [somthing](@citekey) ``` Though I’m not sure if it’s a feature of markdownlint. I’ve temporarily disabled this check. In the syntax of rmarkdown: [Items can be cited directly within the documentation using the syntax @key where key is the citation key in the first line of the entry, e.g., @R-base. To put citations in parentheses, use [@key]. To cite multiple entries, separate the keys by semicolons, e.g., [@key-1; @key-2; @key-3]. To suppress the mention of the author, add a minus sign before @, e.g., [-@R-base].](https://bookdown.org/yihui/rmarkdown-cookbook/bibliography.html#:~:text=Items%20can%20be,%5B%2D%40R%2Dbase%5D ) Since these cited items may need to be referenced after certain parenthesis symbols (), especially when there are some abbreviations, I’m not sure whether this should be considered as MD011. This issue was originally placed in the wrong repository. I have now moved it here. markdownlint/markdownlint#525

kerem added the

enhancement

label

2026-03-07 20:09:03 +03:00

kerem commented

2026-03-07 20:09:04 +03:00

Author

Owner

@singledoggy commented on GitHub (Jul 13, 2025):

Perhaps my previous description of the problem was not clear enough, but obviously this situation can be detected, because mentions always start with '@', and if the content inside the brackets is a link, it is unlikely to start with '@'.

@singledoggy commented on GitHub (Jul 13, 2025): Perhaps my previous description of the problem was not clear enough, but obviously this situation can be detected, because mentions always start with '@', and if the content inside the brackets is a link, it is unlikely to start with '@'.

kerem commented

2026-03-07 20:09:04 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jul 13, 2025):

The example in the original issue used "#", not "@" as here. I agree that "@" is more unique and less likely to appear in this context in normal Markdown.

@DavidAnson commented on GitHub (Jul 13, 2025): The example in the original issue used "#", not "@" as here. I agree that "@" is more unique and less likely to appear in this context in normal Markdown.

kerem commented

2026-03-07 20:09:04 +03:00

Author

Owner

@singledoggy commented on GitHub (Jul 14, 2025):

Sorry, that was a typo. I hadn’t noticed it before.

@singledoggy commented on GitHub (Jul 14, 2025): Sorry, that was a typo. I hadn’t noticed it before.

kerem commented

2026-03-07 20:09:04 +03:00

Author

Owner

@DavidAnson commented on GitHub (Aug 5, 2025):

@singledoggy, as I read the syntax you link to, the syntax of a citation is simply @key or [@key]. For this to get flagged by MD011, you'd need to use the bracket form and precede it with parenthesized text. Is that common? And why are brackets necessary? Wouldn't (text)(@key) have the same effect as using brackets which get replaced by parentheses?

@DavidAnson commented on GitHub (Aug 5, 2025): @singledoggy, as I read the syntax you link to, the syntax of a citation is simply `@key` or `[@key]`. For this to get flagged by MD011, you'd need to use the bracket form and precede it with parenthesized text. Is that common? And why are brackets necessary? Wouldn't `(text)(@key)` have the same effect as using brackets which get replaced by parentheses?

kerem commented

2026-03-07 20:09:04 +03:00

Author

Owner

@singledoggy commented on GitHub (Aug 5, 2025):

[@key] is a type of cross-referencing method that can be converted to other formats of cross-references, such as .docx and .tex, by software like pandoc. A few journals that directly accept markdown should also default to using [@key] references. In my use case, I use markdown to take notes and then convert them to other formats for publication in academic journals. I also don't know why everyone uses [@key].
As for (text)(@key), it's just a situation I encountered while writing.

@singledoggy commented on GitHub (Aug 5, 2025): [@key] is a type of cross-referencing method that can be converted to other formats of cross-references, such as .docx and .tex, by software like pandoc. A few journals that directly accept markdown should also default to using [@key] references. In my use case, I use markdown to take notes and then convert them to other formats for publication in academic journals. I also don't know why everyone uses [@key]. As for (text)(@key), it's just a situation I encountered while writing.

kerem commented

2026-03-07 20:09:04 +03:00

Author

Owner

@DavidAnson commented on GitHub (Aug 5, 2025):

I did some research and the (not part of CommonMark) syntax for citations is pretty variable: https://pandoc.org/demo/example33/8.20-citation-syntax.html

I'll leave this issue open for context, but am not currently thinking to make a fix for what sounds like a pretty isolated incident (parentheses immediately before a bracket-style citation).

@DavidAnson commented on GitHub (Aug 5, 2025): I did some research and the (not part of CommonMark) syntax for citations is pretty variable: https://pandoc.org/demo/example33/8.20-citation-syntax.html I'll leave this issue open for context, but am not currently thinking to make a fix for what sounds like a pretty isolated incident (parentheses immediately before a bracket-style citation).