This is a good thing. I’m going to cut a release some time next week. If you can build from source and want to take it for a spin, please read https://github.com/gohugoio/hugo/issues/6490 first – and esp. note the reference to the updated docs (yes, I have done the work properly this time, I think). And note:
While this will fix many reported formatting issues, being CommonMark compliant also means “stricter” in some areas (there are 17 rules about how a heading should look like), so there may also be some markup that you need to adjust.
I fully expect some “Hugo 0.60 broke my site” issues when I release this, which is the utlimate irony of open source. Read the documentation, especially the Goldmark config section, to see if there are some options you can set to get what you want. You can also set blackfriday to be the default for md/markdown if you for some reason want to stick with the old.
A general remark: Goldmark is one of the most impressing one-man-projects I’ve seen. But even if it’s > 1.0 and it passes all CommmonMark tests and have done some extensive fuzz testing, there will be bugs. I found a crash in one of the sites I tested it with (the Kubernetes site), that got fixed in an hour … And as every software projects have bugs, there will be more once we let the internet lose … But it’s fixable.
Testing it out on my relatively simple site right now and I wouldn’t have even noticed the switch. Great work @bep
I like how extendable Goldmark looks but I’m a bit confused how to get started doing so. The Goldmark docs on extensions seem simple enough but in terms of getting those changes into Hugo, would I need to fork Goldmark? Or in Hugo directly in markup/goldmark? I’m guessing allowing users to put their own Goldmark extensions directly in their own individual projects would get messy quickly…
(I’m also assuming extensions are even the best way to go about adding a feature, like opening external links in new windows (hrefTargetBlank in Blackfriday) for example, so please correct me if that’s wrong. It looks like that’s how you added the ToC functionality but I’ve only skimmed the commit you made.)
In other words, I’m mainly just curious what the best way is for us to help bring its features back up to parity with Blackfriday as you start getting “@bep broke my site” issues coming in. Thanks as always
We need to do some thinking about this, which isn’t something I’m doing … today. As in your following example, it would probably be too fine grained to implement a href target blank extension. There are issues on GitHub discussing link/image markdown “hooks”. But there are a fair amount of things to consider.
I have tested Goldmark in a complex project that I maintain. This is a big improvement for Hugo. It makes pure Markdown syntax work as intended in content files. That was not the case with Blackfriday.
I would suggest to also include a linter, and generate error messages such as “this bit of markdown is not compatible with strict commonmark and may cease working when we put in goldmark” for a few releases, and only then switch the default.
Adding unsafe=true reduced the diffs for my blog from 299,592 lines to 247,381; a quick skim suggests that most of the difference from 0.59.1 is that Goldmark’s typographer feature doesn’t “smarten” apostrophes in contractions. It also generates a lot less blank lines, which is nice.