Adding class to heading not working while attribute adds just fine

support
1

I read the docs as well as several other support topics before adding a class and an attribute to a heading and a paragraph. The outcome is as follows:

  • Adding a class to a paragraph works
  • Adding an attribute to a paragraph works
  • Adding a class to a heading does not work
  • Adding an attribute to a heading works

Hugo environment:

hugo v0.139.3+extended+withdeploy linux/amd64 BuildDate=2024-11-29T15:36:56Z VendorInfo=brew
GOOS="linux"
GOARCH="amd64"
GOVERSION="go1.23.3"
github.com/sass/libsass="3.6.6"
github.com/webmproject/libwebp="v1.3.2"

My config file:

markup:
  goldmark:
    parser:
      attribute:
        block: true
        title: true
    renderer:
      unsafe: true

My markdown page:

## User Manual {class="foo bar" id="bax"}

Lorem ipsum.
{class="fooo" id="baz"}

I also tried with H1 and H2, as well as with all kinds of full and shorthand syntax for the HTML with no luck.

This configuration renders this:

<h3 id="bax">User Manual<a class="td-heading-self-link" href="#bax" aria-label="Heading self-link"></a></h3>
<p class="fooo" id="baz">Lorem ipsum.</p>

Why is Hugo ignoring classes added to a title?

2

It looks like either you or your theme has implemented a heading render hook. Look for a file named render-heading.html and post its contents here.

3

Thanks jmooring.

I’m using Docsy. Indeed there’s a render-heading.html file, reading the following:

{{ template "_default/_markup/td-render-heading.html" . }}

The template it points to contains the following:

h{{ .Level }} id="{{- .Anchor | safeURL -}}">
  {{- .Text | safeHTML -}}
  {{ template "_default/_markup/_td-heading-self-link.html" . -}}
</h{{ .Level }}>

{{- define "_default/_markup/_td-heading-self-link.html" -}}
<a class="td-heading-self-link" href="#{{ .Anchor | safeURL }}" aria-label="Heading self-link"></a>
{{- end -}}
4

Please raise an issue with the theme maintainers.

Until they change the template, you can override it based on these examples:
https://gohugo.io/render-hooks/headings/#examples

5

Edited to make the information suitable for marking as a solution

Thanks for all the help!

For other Docsy users, this is how I changed the code. Place the following in layouts/_default/_markup/render-heading.html (create it if you don’t have it; thanks, jmooring!):

<h{{ .Level }} id="{{- .Anchor | safeURL -}}" {{- with .Attributes.class }} class="{{ . }}" {{- end }}>
  {{- .Text | safeHTML -}}
  {{ template "_default/_markup/_td-heading-self-link.html" . -}}
</h{{ .Level }}>

{{- define "_default/_markup/_td-heading-self-link.html" -}}
<a class="td-heading-self-link" href="#{{ .Anchor | safeURL }}" aria-label="Heading self-link"></a>
{{- end -}}
6

The contents of the Hugo’s cache directory are temporary. You will lose the changes when you upgrade the module, clear the cache, etc.

Never modify a theme or module file. Override it instead.

mkdir -p layouts/_default/_markup
touch layouts/_default/_markup/render-heading.html

Then place the revised code in the file you just created.

7

The Docsy maintainers were extremely quick. The fix is already merged. I assume it will appear in 0.12.0.