Automatically add id attribute to dt element

Assuming that markup.goldmark.extensions.definitionList = true (the default)…

This markdown:

: definition

is rendered to:


but what I really, really want is:

  <dt id="term">term</dt>

where the id attribute is automatically generated and, if necessary, incremented to prevent (or least mitigate) duplicate id’s on the page (the same way that we handle heading id attributes).

While you can apply a markdown attribute to the description list, you cannot apply a markdown attribute to the term or definition.

You can obviously work around this by using heading elements instead of a description list, but (a) the description list seems a semantically better choice, and (b) the additional heading elements may pollute the TOC depending on configuration (endLevel).

A couple of examples from our docs:

Description list:
Heading elements:

I am guessing that we used heading elements in the second example in order to provide link targets.


If you’re willing to be a bit unconventional…


: definition


{{- if eq .Destination "@" -}}
  <span id="{{ .PlainText | anchorize }}">{{ .Text | safeHTML }}</span>
{{- else -}}
{{- end -}}

renders to:

  <dt><span id="term">term</span></dt>

No, the prime motivation for that is the Algolia search indexer. I have gotten access to the Algolia account that does this now, and I have on my list to look at some other search related issues (mostly the case of double-indexing pages).

I’m not sure I follow your logic, though; what do you need those IDs for? It’s not like we include these dt elements in the TOC?

For example, let’s say I want to link to the “lineNoStart” dt element on

1 Like

Yes, that I understand. OK, so you mean manual linking, then. Yea, that would be useful…

1 Like