x/pkgsite: go package readme markdown broken #40203
What is the URL of the page with the issue?
What is your user agent?
Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:78.0) Gecko/20100101 Firefox/78.0
What did you do?
Update my README.md upon every release
What did you expect to see?
My README.md working like it is https://github.com/Delta456/box-cli-maker/blob/master/README.md
What did you see instead?
README Markdown broken
The text was updated successfully, but these errors were encountered:
I did some digging into this. It seems that the problem is that blackfriday (markdown rendering engine used by pkgsite) isn't fully compatible with Github-flavoured markdown (GFM).
I can confirm that I wasn't able to (fully) replicate Github's rendering using blackfriday by adding additional format-related flags to https://github.com/golang/pkgsite/blob/master/internal/frontend/overview.go#L143. This seems consistent with the findings in russross/blackfriday#91. In short, their solution to this problem was to create a custom wrapper around blackfriday that is capable of rendering GFM: https://github.com/shurcooL/github_flavored_markdown (note: based on v1 blackfriday, not v2).
Using github_flavored_markdown I was able to render the following readme.
The output seems fairly consistent with https://github.com/Delta456/box-cli-maker/blob/master/README.md. There is no code highlighting for snippets and images are missing (can probably be fixed by writing a custom Walk() function similar to the one for blackfriday - didn't try that at this time due to an incompatible blackfriday version).
I think there are a few options for rendering different markdown flavours on pkg.go.dev:
Between the two (three) alternatives, I think (2) is the most likely to yield desirable results. Using (1) as an override to (2) might also be an option, but it might cause problems with certain markdown flavours (vanilla markdown doesn't support comments, for example. https://daringfireball.net/projects/markdown/syntax). [EDIT: there's obviosuly another option; use GFM for all readmes].
Ignore my last message, false positive (github_flavored_markdown uses blackfriday/v1 which works fine). Markdown syntax has nothing to do with.
The issue is with the blackfriday's parser which can't handle CRLF line terminators. This has been reported several times [1, 2, 3, 4] and there's also a PR (WIP) open .
To demonstrate what happens on a simplified readme from the OP (with
Unless I'm mistaken, blackfriday isn't actively developed anymore, and many have moved onto goldmark. Hugo, gitea, and even
Perhaps it'd be better to move to a markdown library which is actively maintained.