Anchors

Hugo supports specifying custom ID’s for headings in a page using the {#some-id} syntax. See its documentation on Cross References: Heading IDs for reference.

If the heading ID’s are not specified using the above syntax, Hugo will generate them automatically. While that is OK in general, it becomes problematic when user generates TOC using Org, where the links to headings on the page need to be embedded, or uses Org internal or external links to reference other headings.

So in order to make the user experience smooth, anchors for all headings are always derived withing ox-hugo and exported using the {#some-id} syntax.

The functions used for deriving the anchors can be customized using the org-hugo-anchor-functions variable.

This variable is a list of functions which can return the anchor string for a given Org heading element. The first function in the list to return a non-nil value wins. So this scheme can be used to set a precedence order that the user desires.

This is the default precedence order:

org-hugo-get-page-or-bundle-name

Use the heading’s :EXPORT_FILE_NAME property if set, else return nil.

org-hugo-get-custom-id

Use the heading’s :CUSTOM_ID property if set, else return nil.

org-hugo-get-heading-slug

Derive anchor using the heading’s text. This could also return nil, if the heading has no alphanumeric characters or no text (empty string).

org-hugo-get-md5

Derive anchor using the few 6 characters of md5 based on the heading title text. It returns the md5 of an empty string if nothing else works. That way, this function guarantees to return some non-empty string.

Above precedence is set in the default value of org-hugo-anchor-functions — '(org-hugo-get-page-or-bundle-name org-hugo-get-custom-id org-hugo-get-heading-slug org-hugo-get-md5).

Other anchor functions #

org-hugo-get-id

This function returns the ID, if that property is set for a heading.

If a user prefers to give higher precedence to Org ID than the heading-derived-slug, they can customize org-hugo-anchor-functions to '(org-hugo-get-page-or-bundle-name org-hugo-get-custom-id org-hugo-get-id org-hugo-get-heading-slug org-hugo-get-md5).

Now if an Org heading looks like this:

** Heading in a post
:PROPERTIES:
:ID:       74283e7c-a20b-1c22-af88-e41ff8055d17
:END:

, it will be exported as below in Markdown:

### Heading in a post {#74283e7c-a20b-1c22-af88-e41ff8055d17}

Target Links #

Org mode specifies the <<target>> syntax in Org Info: Internal Links.

By default, a target named “foo” (<<foo>>) will create an HTML anchor with a prefix (like org-target--). See this link to that “foo” target.

But if the target name is prefixed with a “.”, like “.bar” (<<.bar>>), the HTML anchor with not have that prefix . See this link to that “.bar” target.

This special feature allows you to create an HTML anchor anywhere in your document which you might then refer from a different post by using something like the relref Org macro .