I have 2 .org files:

// a.org contains the anchor

// b.org contains the link to my_anchor
[[file:a.org::my_anchor][My Link]]

When I click on the link in org-mode, it links correctly to the position of my_anchor in a.org. But when I export these 2 files to HTML, what I expect is:

// b.html
<a href="a.html#my_anchor">My Link</a>

What I got is:

// b.html
<a href="a.html">My Link</a>

I wonder how to correctly write an external link so that it works both in org-mode and in exported HTML.

  • 1
    What I get is <a id="orgtarget1"></a> in a.html and <a href="a.html#MissingReference">My Link</a> in b.html, which is marginally better, but not functional. This org version 8.3.3. Commented Feb 23, 2016 at 7:47
  • @AndrewSwann Thanks for the info, mine is 8.2.5. This looks promising, possibly it requires a special way to write the link in org mode, I wonder how.
    – vicch
    Commented Feb 24, 2016 at 16:23
  • It looks more like a bug to me - have you tried reporting it? Commented Feb 24, 2016 at 17:07
  • @AndrewSwann No, I haven't learnt how to report a bug. Actually I don't feel like investing more time on it for the moment. It seems not an important issue anyways.
    – vicch
    Commented Feb 26, 2016 at 14:34
  • @AndrewSwann It is a documentation bug. You find more details about that at the end of my answer below. I've filed a bug report.
    – Tobias
    Commented Mar 1, 2016 at 7:31

1 Answer 1


The string behind :: is actually a search. In this context one understands the relevant comment in the source code of the function org-html-link in the library file ox-html.el (org 8.2.5). It says:

  ;; Add search option, if any.  A search option can be
  ;; relative to a custom-id or a headline title.  Any other
  ;; option is ignored.

So, you can either replace my_anchor by #my_anchor to form a custom-id or use a headline title starting with the character *. In the second case don't include spaces after the *-character!

Linking section headers in other files only works when you publish org-mode projects. Org-mode projects are defined as members of the variable org-publish-project-alist. See the documentation of this variable and Section 13 Publishing of the org-mode manual for the details.

Example: file a.org:

* This is file a.org
  Some important notes.

* Second Section

* Section with a custom-id

  Some text before the custom-id

  <<#my-anchor>> Here we have the custom-id

  Some text behind the custom-id.

Text in file b.org:

* This is file b.org
  Some text.

* b.org contains the link to my_anchor
  [[file:a.org::#my_anchor][My Link to the custom-id]]

  [[file:a.org::*Second Section][My Link to the headline of the second section]]

Remark: The reason that links to headers in other files only work with publishing is that they are fetched from org-publish-cache in org-publish-resolve-external-fuzzy-link which is used in org-html-link.

Section header links are actually numbered links, such as sec-1, sec-2 and the section headers are translated to the numbers 1,2,... via an association list in the variable org-publish-cache.

I consider this a documentation bug. The html-export of links of section headers in other files is not mentioned in Section 13.1.6 Links between published files of the org-mode manual. I can also not find any remark of the html-export of links to custom-id's across files in the manual.

I've just discovered these things through reading the source code.

This is what I got as an answer to my bug-report:

Thank you for the report.

Unfortunately, this feature is very experimental, and actually quite
buggy. It's not ready for prime time, and therefore not documented.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.