On newer versions of orgmode (i.e. anything 9.7 or newer) something upstream breaks the manner in which ox-hugo handles links for sub-tree exports1. The most robust workaround is to stop using native Org links and switch to a manual Hugo short-code via an Org macro.

The process has two parts. First, we need the relref macro in the Org file with #+macro: relref @@hugo:[$1]({< relref "$2" >})@@ 2.

Then every internal link needs to be refactored using the target file slug, optionally appending the anchor if required.

Before:

1As I mentioned in my [[On-boarding for Code in Place][last post]]...

After:

1As I mentioned in my {{{relref(last post,scp-onboarding)}}}, I'm leading a section...

I ended up starting with a manual conversion, which was very tedious, but does result in a more stable site with links that are properly managed by Hugo’s content engine, insulating the site from future Org mode changes.

Eventually I used a script to generate most of the relref changes, with the exception of titles with code snippets:

1pixi s
2python ./scripts/convert_links.py content-org/all-posts.org all-posts-converted.org

  1. xref this comment ↩︎

  2. Wrap that the link with another {} ↩︎