x/pkgsite: consider moving to goldmark to handle issues in READMEs

[hhrutter]

What is the URL of the page with the issue?

https://pkg.go.dev/mod/github.com/pdfcpu/pdfcpu

What is your user agent?

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/81.0.4044.138 Safari/537.36

Some images don't show up and there is also a markdown table that's screwed up.

[julieqiu]

Thanks for the feedback @hhrutter - we'll work on a fix! This is also related to #37194

[josh-newman]

In case it's helpful, I ran into another case of incorrect table rendering, this time with no images in the table: correct on Github (snapshot), incorrect on pkg.go.dev (snapshot).

[shaqque]

The broken markdown tables for both packages (pdfcpu and parquet-go) seem to be caused by incorrectly formatted markdown, at least according to blackfriday (the external markdown parser pkg.go.dev uses). Note that Github-flavored-markdown (GFM), which Github uses, is not the same as regular markdown.

Specifically,

1. pdfcpu's table does not does not have a space/newline before the start of the table, causing blackfriday to not detect it as a table. Adding that space allows blackfriday to detect and render the table correctly.
   • Reproduction: https://play.golang.org/p/lraQZ-OlRcp
2. parquet-go's table uses 1 hyphen per column in the header row instead of 3, which blackfriday requires (see russross/blackfriday#351). This also appears to violate Github's documentation for tables, though the official Github-flavored-markdown spec doesn't say anything about this despite the examples all having 3 hyphens per column. Changing the table to use 3 hyphens per column in the header row allows blackfriday to detect and render the table correctly.
   • Reproduction: https://play.golang.org/p/0EhSP25SY31

There is a related discussion on #40203 about blackfriday and GFM. In particular, @zikaeroh suggested

Unless I'm mistaken, blackfriday isn't actively developed anymore, and many have moved onto goldmark. Hugo, gitea, and even x/tools/present and x/website use goldmark for their markdown support.

Perhaps it'd be better to move to a markdown library which is actively maintained.

I tried the above cases using goldmark, and in both cases, the table was identified and rendered properly by goldmark.

• Reproduction: https://play.golang.org/p/CiJmIbnu6RV. This won't actually run on the playground since the build takes too long.

I think this, along with active maintenance (last commit was 6 days ago) and broader use among other Go projects, makes moving to goldmark a good idea.

[gopherbot]

Change https://golang.org/cl/266579 mentions this issue: content/static: copy readme.css into legacy_readme.css

[gopherbot]

Change https://golang.org/cl/267117 mentions this issue: internal/frontend: separate goldmark readme code from legacy overview code

[jamalc]

@hhrutter - this should be fixed. We made the switch to goldmark 😊