Org-mode external links not working when exported to HTML

Question

I have 2 .org files:

// a.org contains the anchor
<<my_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.

What I get is `` in `a.html` and `My Link` in `b.html`, which is marginally better, but not functional. This org version 8.3.3. — Andrew Swann, Feb 23 '16 at 07: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 01 '16 at 07:31
Links to anchors within other org-files work (see my answer) but it is an experimental feature (see bottom of my answer). — Tobias, Mar 03 '16 at 14:32

score 9 · Accepted Answer · edited Apr 28 '16 at 14:28

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.

Org-mode external links not working when exported to HTML

1 Answers1