# Org-mode external links not working when exported to HTML

I have 2 .org files:

// a.org contains the anchor
<<my_anchor>>

// b.org contains the link to my_anchor


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


What I got is:

// b.html


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

• 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. – Andrew Swann Feb 23 '16 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 Feb 24 '16 at 16:23
• It looks more like a bug to me - have you tried reporting it? – Andrew Swann Feb 24 '16 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 Feb 26 '16 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 Mar 1 '16 at 7:31

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



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.