Org-mode anchors

Theme: hugo-dusk
hugo version: 0.46
canonifyurls: true

Links to content within the same post are being rendered relative to the web root rather than relative to the post that they belong to. This includes org foot-nets as well as standard org links to headings or other content within the same document.

I have read the article on Links and Cross References regarding anchors. It says that anchors should have a id appended to the end of them, but when I inspect the anchors on my post I can see that no id has been appended. Perhaps that is the issue? I am just running this locally at the moment, so maybe that is also part of the issue. I have not published to github yet.

How can I make the anchors in my post link relative to the post itself and not to the webroot using org-mode?

Can you share your post in Org mode so that I can better understand the issue?

What are you linking to? If it’s a subtitle ** post subtitle, you should be able to do [[* post subtitle]]. If you assigned a CUSTOM_ID property with value “foo” to that subtree, you should be able to do [[#foo]].

If either doesn’t work, open an issue on the goorgeous library repo (though I’m afraid that that project isn’t maintained any more).

I simply export my posts from Org mode to Markdown using ox-hugo (Disclaimer: my package), and Hugo handles just the Markdown via Blackfriday. The kind of internal links I mentioned above are supported.

Hi Kaushalmodi,

Thank you kindly for your time and response.

I can’t share the post since it is neither published nor ready for publishing, but I can share an example directly from my post in plain text here.

In the body of my post I have two links. One is a link to the footnote heading [[footnotes][footnote]], the other is a footnote link to the footnote itself [fn:1]

see [[Footnotes][footnote]]: grep [fn:1]

Then at the bottom of my post I have the footnonte heading and thee footnote which look like the following:

* Footnotes

[fn:1] QLA - [[][grep]]
searches input for a pattern.
- -i :: case insensitive.
- -E :: tells grep that the pattern should be interpreted as a regular expression

The see [[Footnotes][footnote]]: grep [fn:1] links output to the following html:

<p>see <a href="Footnotes" title="footnote">footnote</a>: grep <sup class="footnote-ref" id="fnref:1"><a href="#fn:1">1</a></sup></p>

which when clicked on navigate the browser to the following URIs respectively


Whereas I would like those links to navigate the browser to the following URIs instead:


You can see that the heading link to the the Footnotes heading is not rendered as an anchor link at all. It might be that org-mode heading links are simply not supported at this time. If they were supported, but just not linking relative to the post, then I would have expected the footnote heading link to render with a leading octothorpe (#). I would be happy enough at this point if I could at least get the footnote links to behave correctly. They are producing anchor links since they have the leading octothorpe so the only behaviour that I need to change about the output of the footnote links is that they are relative to the post rather than the webroot.

Thank you again for your time, it is appreciated.


So after writing my previous reply I realized that I created my heading links using only the text in the heading rather than a custom id as you had suggested. So I corrected the footnotes heading so that it now looks like this:

* Footnotes
:COLUMNS:  %CUSTOM_ID[(Custom Id)]
:CUSTOM_ID: footnoteid

I then updated the footnote link higher up in my post like this:

see [[#footnoteid][footnote]]: grep [fn:1]

Unexpectedly the footnote header is now being rendered like this:


As you can see it has an id of footnotes and not footnoteid, so already I have a problem. The footnote link is rendered like this:

<p>see <a href="#footnoteid" title="footnote">footnote</a>: grep <sup class="footnote-ref" id="fnref:1"><a href="#fn:1">1</a></sup></p>

This is much better. Now, both the header link and the footnote link have a leading octothorpe and are being treated as proper anchors. Clicking on them still navigates the browser to the webroot though. Also, the footnoteid does not match the actual id being rendered for the heading. I can of course change that, I am just not sure why it is not respecting the customid that I choose when setting the CUSTOM_ID property. At least I am one small step closer to a solution.

That means that Goorgeous does not parse the CUSTOM_ID property.

1 Like

After further inspection of the other headings it looks as though all headings are automatically being given an id that contains the text of the heading itself. If I set the custom_id property that allows the link to work within org-mode, but it does not cause the rendered heading to have the explicitly specified custom_id. So I guess I am forced to set the custom_id to exactly the same text as the heading text so that the links will work in both emacs org-mode and in theory the published blog post. That is fine, but the issue still remains that the links are relative to the webroot and not the post itself.

Difficult to tell the problem unless you share the site source. You just need to create a minimal git repo with the one test page you have (and everything else needed to build the site: theme, config.toml, etc).

I posted a repository containing an example draft post that exhibits the issue:

You may find the post here

Thank you for your time.

I forked your repo to my throwaway repo:

Unrelated to your issue, you need to add the theme as a git submodule and record it in .gitmodules: See

I cannot recreate that issue… For showing you what I see, I quickly deployed it on Netlify at

Page created using Goorgeous


  • Note that the links contain the post URL.

Goorgeous issues

  • You have to leave a blank line between post sub headings
  • The [[* heading]] type links don’t work.
  • CUSTOM_ID does not get parsed.
  • [[#custom-id]] type links “work”, but the heading text does not get auto-inserted as link descr.

Page created using Blackfriday which uses ox-hugo exported markdown

link | Org source

This has none of the above issues.

Someone needs to fork out Goorgeous and iron out the kinks.

1 Like

Thank you for pointing this out. I actually thought that I did add the theme as a submodule, but as it turns out it was only ever addded as a git-link. I have since fixed this so that hugo-dusk is a proper submodule now.

That is really interesting. I am wondering if the problem only happens when I brows from localhost. I am going to try to publish to my blog and see if the links work correctly there. I will post back with what I find out in a few minutes…

Okay, I published the test post and my links are not working on my published page either.

Just an FYI for others reading this. Once I sort this out I will be deleting the test page so if you arrive here in the future expect the link to my test page to be dead.

I am thinking that my issue might be how I am posting. I am not using goorgeous. I had read that org-mode was a first class citizen like markdown so I assumed that it should just work. Also, it appeared to just be working. I can write my content in org-mode and, render the page locally, and browse it. The only issue that I ran into so far is linking with anchors.

You mentioned previously that goorgeous is unmaintained now. It does look like the last commit was in November of last year. If goorgeous is required for proper org-mode support and it is not maintained then gohugo needs to state that org-mode support is not being maintained as a first class citizen.

Thank kaushalmodi for all of your help.

Because you have this in your HTML source:

<base href="" />

Are you using the exact same site source you shared? It doesn’t make sense why it would publish differently for you. One difference that’s easy to resolve is that I am using Hugo 0.47.1. Can you update to that?

Also I’m out of my breadth here.
@bep: Any help with what inserts the base href?

You are, by default, if you are directly publishing from Org source. Goorgeous library gets baked into the hugo binary. [quote=“BloggerBust, post:11, topic:13842”]
it appeared to just be working. I can write my content in org-mode and, render the page locally, and browse it.

Yes, Goorgeous works great for limited Org mode syntax. This is an open source project, but not an island. It relies on many other open source Go libraries. To fix this link issue, someone knowledgeable of both Go and Org mode has to just jump in, and start maintaining a fork. Hugo cannot take the responsibility of maintaining the Org parsing library (the same applies to all other libraries it uses).


I believe I changed base href to after you had pulled the branch. I have changed it back to / now. Otherwise, the source is the same as what is being published.

I will try upgrading to 0.47.1 to see if that helps.

No worries. You have helped me plenty and I do appreciate it, but you are certainly under no obligation to continue and I certainly will not be offended if you part at this point.

Thank you for explaining to me that it is actually using goorgeous under the hood for org-mode support. I might just switch to your ox-hugo package anyway since it is supposed to have more feature supported.

Thanks again kaushalmodi!

I think setting the base href will makes all the links relative to that base (but I could be wrong… I’ve read about that base thing just in passing).

That said, did removing that fix the issue?

If not, please commit all your changes so that we are debugging the same source files.

Also, what’s your exact site publishing command? Just hugo?


I set the baseref and pushed the latest to master. I also published the change to Changing the base href has not resolved the issue.

My exact publishing command is simply to run hugo with no arguments.

I have installed ox-hugo and am going to try it out. Just reading through your documentation now. I have to head to work in 30 min also.

A … template?

I have switched to ox-hugo for org-mode support. The change has been pushed to master and published to the site as well. The issue with local links rendering relative to the root directory still persists. This seems to be an issue with my environment and not an issue with goorgeous or ox-hugo. I have to head off to work now, but I will be investigating emacs / org-mode related variables to see if there is something I have set that is causing the links to be rendered this way.

Thank you for your help so far. Thank you especially for your time; I appreciate how valuable time is.

OK, I found the problem.

Your theme was the issue, specifically the piece about the href base that I suspected.

Why you saw the problem: You were using the theme from commit (that’s why sharing your site source with submodules etc is really important!)

Why I didn’t see the problem: I was using the latest version of that theme where that bug was already fixed in (see the removal of href base line in that commit).

1 Like

Thank you kaushalmodi,

You are correct. I was building against an old submodule which I had incorrectly created somehow. I had created it as a git-link instead of a proper submodule. On top of that, I had pulled the latest earlier this week before the fix had been pushed and did not think to check if a new commit had been merged to the theme’s master branch with a fix for my issue. Of course, I did not realize at the time that I was experiencing an issue with the theme; I am brand new to hugo and just thought that I was not doing something correctly.

I have learnt quite a few lessons this week :slight_smile:


FYI: for anyone visiting this page in the future, I will be removing my temporary example post that I linked above since I only created and published it for the purposes of helping to troubleshoot this issue. I also think that it no longer provides any value for anyone moving forward since the issue was resolved in the theme.