Support GitHub Flavored Markdown or at least CommonMark

Problem Description

Given the proliferation and ubiquity of GitHub, I believe many unassuming developers (myself included) naively believed what Markdown syntax is supported on GH is part of the original 2004 Markdown spec. Even if developers knew the difference, that they would prefer GitHub as that’s what’s most common. https://github.com/mitmproxy/pdoc/issues/64 suggests this conflation is a problem.

I personally stumbled across then when I wanted a URL to automatically be hyperlinked with pdoc, not realizing the original spec requires the URLs to be wrapped in < and > characters. In a phrase: I’ve become spoiled by GFM.

Proposal

Support the GitHub Flavored Markdown spec.

This can take place in a few possible ways:

• via a new -d gfm or -d github-markdown flag, reserving the -d markdown flag for the original 2004 spec
• replace the Markdown support in pdoc with the GFM version by default, optionally exposing a -d original-markdown for the 2004 spec
• A “pick n choose” approach where the most popular/used parts of GFM are supported on top of the current Markdown implementation (I don’t really advocate for this one)

Alternatives

I guess not supporting GFM at all?

Independent of my proposal, pdoc should probably declare what version or flavour we colloquially know/call as “Markdown”. The original is from 2004 released as a Perl script and has remained largely unchanged, warts and all.

CommonMark appears to be the, well, common and well-defined and versioned specification of the original Markdown. Indeed, GFM is derived from CommonMark!

I would hope that pdoc would choose a version of the CommonMark spec and support that version explicitly.

Additional context

The Differences from original Markdown section of commonmark-spec’s README is enlightening.

[f3ndot]

Ok makes sense! Thanks for entertaining the request. I may submit a PR adding documentation or a section into the README describing that pdoc supports the original Markdown specification along with a discrete set of extensions/extras to disambiguate/reduce confusion for people in the future.

[mhils]

Done, thanks for the good suggestion! 😃