MD011: false positive when cross ref bibliography when writting academic paper after ()

[singledoggy]

(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

[singledoggy]

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 '@'.

[DavidAnson]

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.

[singledoggy]

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

[DavidAnson]

@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?

[singledoggy]

[@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.

[DavidAnson]

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).