Problem with GitHub's Markdown Rendering Library

I’ve stumbled upon a problem with GitHub’s markdown renderer for repositories’ previews. Since the GitHub preview library hosts multiple rendering packages for the various supported syntaxes I’m not quite sure where I should report this — i.e. which is the repository of the GFM rendering tool, or whether this is issue should instead be reported to GitHub Flavored specification project.

Problem Description

Yesterday, after pushing a commit on master I realized that the README.md contained some broken referenced-link. The problem was due to a single reference label in which I omitted the separating space between the URL and the alt-text:

Link to [`somefile.sh`][somefile.sh]

[somefile.sh]: ./somefile.sh"View source file"
                             ^ missing space!

The missing space did not only affect that specific reference link — which was rendered raw in the preview: [`somefile.sh`][somefile.sh] — but every other reference link in the document, which made it quite hard for me to find the source of the problem.

Also, the local previewer of my editor rendered the document without problems, which further made it hard for me to spot the problem.

Expected Behaviour

Although the separating space in that context is good practice, and omitting it is bad syntax, I believe that GitHub’s markdown renderer shouldn’t break like it did — especially since that single label affected the rendering of all others.

Most markdown previewers are able to parse and render that document without problems, and when you come to think about it the context isn’t ambiguous since the double quotes character can’t possibly be part of a URL, and the parser should be able to detect that a " encountered while parsing a URL should be interpreted as the beginning of the alt-text string — which is what many markdown rendering libraries and tools actually do in this case.

Help Request

I would like to submit an Issue for this, asking to make the markdown previewer library more fault-tolerant for this typo. Where should I submit an issue? In the GFM specification repo? or is there a specific rendering tool repository?

2 Likes

The github/markup project is the place to start whenever you’re looking at how we render markup files in a repository. Given that you’re asking about Markdown, you can see that gjtorikian/commonmarker is used to perform the actual rendering, which is a wrapper for github/cmark-gfm and itself is a fork of commonmark/cmark. If I was in your shoes, I suspect the most helpful thing would be to determine if it is a bug in the GitHub-specific Markdown rendering (in other words, in github/cmark-gfm) or if it exists in the underlying commonmark/cmark library. Once I made that determination, I would file the appropriate issue with my findings, how I tested to make the determination, etc in either github/cmark-gfm or commonmark/cmark.

I hope that helps!

2 Likes

Indeed, it’s exactly the disentanglement of repository dependencies I was looking for.

1 Like