Markdown block: Parsing issues and inconsistencies

[tyxla]

In testing how elements are recognized and parsed in our Jetpack Markdown block for Gutenberg, we've discovered several issues and inconsistencies so far.

This is a master issue for all of them, feel free to add any others that you find.

• Footnotes / reference links differences -- Markdown block: add support for footnotes. #30149
  • Reported by @mapk in Gutenberg: Try out the Markdown block #10133 (comment)
  • Reported by @jeherve in p1HpG7-5EW-p2 #comment-27928
• Images with alts and titles not supported
  • Reported by @jeherve in p1HpG7-5EW-p2 #comment-27928
• Single empty lines are omitted
  • Reported by @Stojdza in p1HpG7-5EW-p2 #comment-27911
  • Reported by @carladoria in p58i-7sR-p2 #comment-40539
  • Reported by @reginabally in p58i-7sR-p2 #comment-40610
• Alternative heading syntax parsed incorrectly on iPad Pro
  • Reported by @eliorivero in p1HpG7-5EW-p2 #comment-27968
• Code block not properly styled
  • Reported by @carladoria in p58i-7sR-p2 #comment-40539

[tyxla]

FWIW, some of those are already fixable:

• Empty lines omitted - fixable if we make breaks: true for the parser.
• Footnotes / reference links - there's a plugin for adding support

Anyway, fixing them is not so straightforward, because we'd also need to account for them in our WP.com implementation of Markdown.

[KnBrckr]

I was asked in https://wordpress.org/support/topic/definition-lists-not-working-in-markdown-gutenberg-block/#post-11127209 to add some notes here.

Also missing from the above list are definition lists and abbreviations. These are both part of Markdown Extra, which is what the Jetpack Markdown module is documented to use. WP.com also claims support for these features on its Markdown support page

There are markdown-it plugins available for the missing features:

• Footnotes (github) (npm)
• Abbreviations (github) (npm)
• Definition Lists (github) (npm)

[KokkieH]

Another report of this issue in https://wordpress.com/forums/topic/markdown-code-syntax-highlightyng-using-jetpack/

[DBJDBJ]

Guys, what is not being said here? 2+ years for NOT resolving something so important to many users. There must be a story behind this.

[jeherve]

@DBJDBJ We're not currently working on the Markdown block, but when we do come back and iterate on that block, we'll definitely be tackling some of the items on the list above.

Until then, we've marked this issue as "Good For Community". That means that we'll be happy to review any improvements and bug fixes suggested by community members like you.

[DBJDBJ]

@jeherve What is good for me I have now done: uninstalled Jet Pack. Actually I would very much like to move to HUGO but dbj.org is 500+ posts. It will be done.

[mxro]

Any chance on getting proper syntax highlighting for code blocks? As far as I can see, syntax highlighting still does not work even when specifying the correct language. All code in Markdown blocks is just rendered as plain text.

[jenxi]

Any chances of adding Markdown footnotes support in Markdown blocks?

[sophiegyo]

We had a question from someone who would like to create page anchors in Markdown:
https://wordpress.com/forums/topic/markdown-and-linkable-section-headers/

They referenced this .org style guide:
https://make.wordpress.org/docs/style-guide/linking/heading-targets/

I learned that the Markdown block uses CommonMark spec but this doesn't appear to allow page anchors, nor does it seem that the .org method of page anchors works in the Markdown block. I understand work's been done on the footnotes in the block; would it be viable to extend this to regular page anchors? (Or of course if there's something I'm missing about how to make those work, I'll gladly learn!)

[jeherve]

this doesn't appear to allow page anchors

That's correct. Header anchors are not supported at the moment. You can read more about it in this discussion: this doesn't appear to allow page anchors

They referenced this .org style guide:
make.wordpress.org/docs/style-guide/linking/heading-targets

This is about content published on make.wordpress.org, so it's a bit different. Instead, I would recommend using the option provided in the Heading block to add anchors to headings, like so:

That requires using a mix of Markdown blocks and heading blocks, which isn't ideal, but that's one way to work around the problem today.