Goldmark (CommonMark compliant) is now merged and the new default

Announcements
1

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.
25 Likes
5

Right.

So in a project of mine with complex HTML in the config I entered

[markup]
unsafe = true

I have a shortcode called wrap.html that simply contains {{ .Inner }} and then in content files it is used like so:

{{< wrap >}}<div class="specifics">{{</ wrap >}}
# Some title
<span class="duration">12 Nov – 7 Dec 2019</span>
{{< wrap >}}</div>{{</ wrap >}}

All HTML elements are not rendered despite enabling the unsafe parameter.

I suppose that I will have to stick with Blackfriday for this project or refactor when time permits.

EDIT

Also one of the content files in the hugoBasicExample contains an SVG.

Again this is ignored despite enabling the unsafe parameter.

So it seems that mixing HTML in Markdown is no longer possible.

7

Your config is wrong. Please read the documentation carefully.

8

Right.

So it is.

[markup.goldmark.renderer]
unsafe= true

The attribute syntax needs to be used even for the new default.
Anyway the above renders the HTML again in the markdown as it was with Blackfriday.

There is one gotcha however. If a shortcode contains both Markdown and HTML like below:

{{< wrap >}}<div class="specifics">{{</ wrap >}}
# Some title
<span class="duration">12 Nov – 7 Dec 2019</span>
{{< wrap >}}</div>{{</ wrap >}}

Then the HTML will still be omitted despite setting the unsafe parameter.

If I stick just with HTML elements in the above like so:

{{< wrap >}}<div class="specifics">{{</ wrap >}}
<h1>Some title</h1>
<span class="duration">12 Nov – 7 Dec 2019</span>
{{< wrap >}}</div>{{</ wrap >}}

Then everything is rendered as it should.

Anyway good to know.

Thanks.

1 Like
9

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.

6 Likes
10

Testing it out on my relatively simple site right now and I wouldn’t have even noticed the switch. Great work @bep :+1:

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 :slight_smile:

11

Nice name

1 Like
12

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.

1 Like
13

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.

Thank you for merging Goldmark into Hugo.

3 Likes
14

This is a great step forward for Hugo. Great work and thanks.

1 Like
15

Awesome

16

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.

17

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.

-j

2 Likes
18

UPDATE : created a proper post on this broken shortcode in markdown here

19

@bep can we have some suggestions on how to use partials / shortcodes with goldmark (so that we don’t have to be “unsafe” :wink:)

1 Like
20

Is it possible to re-activate the apostrophes “smartification”? Really important to me :frowning:

NB: Goldmark should… GitHub - yuin/goldmark: 🏆 A markdown parser written in Go. Easy to extend, standard(CommonMark) compliant, well structured.

21

There’s an issue already open for this: Apostrophes in contractions are not converted to right single quote · Issue #39 · yuin/goldmark · GitHub

Doesn’t hurt thumbs-up -ing it … at least the Goldmark dev knows that there’s a high demand to fix that issue.

1 Like