Goldmark includes a system for extensions, but the author is (understandably!) conservative about what is included in the main repository. This came up when I submitted a PR to enable labeled footnotes ([^name] instead of just [^1]), and only then realized that the goal of Goldmark’s footnote support was to mirror PHP Markdown Extra’s footnote feature, not BlackFriday’s.
Such a feature would be easy to craft as an extension, but it would have to be enabled at compile time and built into the Hugo executable, I believe. (If that is not the case, please let me know!)
I totally understand if we wouldn’t want to introduce another external dependency to Hugo just for the sake of this relatively minor point of feature parity with a deprecated library, but is there any interest in a feature like this? I’d be happy to create the Goldmark extension, but the author was clear that it wasn’t something that would be accepted in the main repository.
Would we perhaps be open to having a set of Goldmark extensions that are part of Hugo? It might be overkill or invite too much bikeshedding, but it feels like a useful question to ask going forward if Goldmark is going to be the default renderer; eventually I imagine there might be other Markdown rendering features that would benefit Hugo.
(Background: I rely on the unique anchor tags generated by labeling footnotes this way (when assembling several pages into a larger one) so for now I’m sticking with BlackFriday as my Markdown renderer, but I’d like to be ready for a future where that’s no longer an option.)
For the record, I can’t answer your question, I was wondering about Goldmark &updated this thread because I’m trying to assess how to tackle my own footnote “issue”/wish.
In conjunction with Hugo they would allow static pages without any JS dependencies to support mermaid and katex code blocks in Markdown content authoring (rendered to SVG by Goldmark/Hugo).
I suspect such features would be of interest for a lot of Hugo users and theme developers.
Any chance the officially acknowledged third-party goldmark extensions could be integrated in Hugo’s extended version and the markdown code block parsing of the respective format additions be made opt-in via global config? And perhaps, possibly existing codeblock render hooks could even have precedence over goldmark-rendering for maximum flexibility?
I also wonder whether Hugo’s GoAT support wouldn’t be better served as a Goldmark extension.
@jmooring The fact that goldmark-mermaid calls out to the MermaidJS CLI isn’t an inherent blocker for inclusion in Hugo, right? It just means users would have to npm i @mermaid-js/mermaid-cli to be able to use the feature, no?
I’d greatly love support for goldmark-fences to be added in, it’d make it easier for us to be able to hint that areas of documents should have a container with a specific id/ class for styling it nicely.
It would make it a lot easier to style output if we can easily put extra containers into the rendered document without resorting to rendering unsafe html in documents.
There’s already a couple of ways to do what you want in Hugo (e.g. shortcodes). Adding one more is not likely, especially considering that the “fences syntax” doesn’t look very standard.
I agree that it can be done using other ways as I have implemented it using shortcodes. I don’t know about “standard” given the variations in markdown dialects. I personally think the fences syntax is a lot cleaner. It aligns neatly in format with the markdown attributes described here which is supported, whereas the shortcode implementation looks a bit out of place.
I appreciate these things are going to come down to personal opinions and preferences. I feel having the option to enable it be incredibly helpful for those who need it. Having easy ways to nest <div> elements in documents makes styling a lot easier and more flexible. DOM matters!
I’ll include some examples with the shortcode solutions so other can find it if they need it.
Contrasting the fences style (unsupported):
:::{.troubleshooting}
## My H2
Some text
:::
vs. using the shortcodes method (supported):
{{< div class="troubleshooting" >}}
## My H2
Some text
{{< /div >}}
Here’s my shortcode based on jmooring’s post on github (layouts/shortcodes/div.html)
<div
{{- range $k, $v := .Params }}
{{- if $v }}
{{- printf " %s=%q" $k $v | safeHTMLAttr }}
{{- end }}
{{- end -}}
>
{{ .Inner | markdownify }}
</div>
When you say “enable it” you talk like it’s about just toggling a switch. Adding this to Hugo is a significant amount of work and future maintainance:
It needs to be implemented with some sensible configuration options.
It needs to be documented.
We need to handle questions and bug fixes coming (e.g. “my headers inside fences don’t show up in ToC”, “render hooks doesn’t work for headings inside fences”). Considering this is an upstream library makes this even more challenging/time consuming.
So, adding a feature to Hugo is almost never just “enable it”.
If you call the shortcode using the {{< >}} notation, pass .Inner through .Page.RenderString instead of markdownify to avoid the problems described in https://github.com/gohugoio/hugo/issues/9692.
My apologies for my poor wording bep. As a coder I should have more clearly articulated what I meant. I appreciate adding support for the optional extensions in goldmark would be non-trivial. I was replying to this thread with the sole purpose of indicating that another user would love this feature.
Given the shortcode method works and the “rightness” of how it looks is likely more personal taste, I appreciate this will be a very low priority.
