`+citations` should be enabled in GFM and better documented

[VladimirAlexiev]

Describe your proposed improvement and the problem it solves.

I think the citations extension should be available and enabled for gfm input, just like it's enabled in markdown and available in markdown_github (which is deprecated).

• In Github, @ is used to ping somebody, but such feature is not applicable to documents, so it's safe to repurpose @ for citations.
• GFM is very widely used by developers, so we have "muscle memory" for some extensions enabled with it, in particular +autolink_bare_uris+pipe_tables

Even if this suggestion is rejected, the documentation of citations should be much improved. Currently it only talks about org, so I ignored it. But it should describe in which formats it is available

Describe alternatives you've considered.

I figured this out after much searching in the discussion group (eg https://groups.google.com/g/pandoc-discuss/c/75WYwG0TrKI/m/yZ6NNCIfAwAJ)

I ended up using this --from:

pandoc README.md --standalone --embed-resources \
  --from=markdown+pipe_tables-smart+citations --to=html \
  --toc --number-sections --wrap=preserve \
  --citeproc --csl=acm-sig-proceedings-long-author-list.csl -o README.html

I did some comparison of these tree:

pandoc --list-extensions=gfm
pandoc --list-extensions=markdown_github
pandoc --list-extensions=markdown

I use pandoc 3.1.7

[jgm]

I agree that it would be nice to have the +citations option with commonmark and gfm, but this waits on
jgm/commonmark-hs#15

[VladimirAlexiev]

https://github.com/VladimirAlexiev/pandoc-list-extensions lists all extensions and formats, and can be used as a reference when documenting extensions.

In particular, https://github.com/VladimirAlexiev/pandoc-list-extensions#extensions-for-selected-formats shows why I had to use the deprecated markdown_github rather than gfm: many extensions are available in the former but not in the latter.

[LeaVerou]

+1 for this. I had to use markdown_github+citations so that pandoc would stop dropping my citations, then had to go on a mad hunt across docs to figure out what flags to add to markdown_github to make it equivalent to gfm. 😕

[jgm]

Re the documentation: you're looking in the wrong place. See
https://pandoc.org/MANUAL.html#extension-citations
https://pandoc.org/MANUAL.html#citations

But, agreed, there's something very wrong about the section https://pandoc.org/MANUAL.html#other-extensions which duplicates headings for Extension: citations and others... (@tarleb do you remember the intent of this?)

As for citation support for gfm/commonmark: this waits on jgm/commonmark-hs#15

[jgm]

I've added some disambiguation to those MANUAL.txt headings, so that in the next release this will be less confusing. (It will now say Extension: citations (org), etc.)

[tarleb]

@tarleb do you remember the intent of this?

No, sorry.

[jgm]

I think I remember now. Most of the extensions were orginally documented in the "Pandoc's Markdown" section, but some of them affect other formats, so we added an "Extensions" section. It's still a bit confusing.

[LeaVerou]

Thanks, though I’m pretty sure I looked at that page as well... I might be missing something obvious, but I wouldn't know which extensions to enable on github_markdown to make it as similar as possible to gfm from that page, since I don't know the ins and outs of GFM to that degree.