I have a very large orgmode document that has internal links to many different parts of the document.

If I try to export a subtree that has an internal link that points to a part of the document outside of the subtree exported, I get an error

Unable to resolve the link: "Determinism"

to get around this, I've written

#+OPTIONS: broken-links:auto

which makes it so that when I export the subtree, it can export but in the export the link's title isn't exported, it's simply a blank spot.

Basically in the original document's subtree I'll have this internal link that points to outside of the subtree like this

Philosophers love [[determinism]]

but upon export It becomes

Philosophers love

and what I want in the export is

Philosophers love determinism

I'm wondering if this is achievable.

I'm using spacemacs on MacOS, Mojave.

  • 3
    I see the same behaviour with broken-links:t. This is not consistent with the documentation, which says the broken links are clearly marked in the output. You should report this as a bug. Apr 4, 2019 at 18:13
  • 1
    This seems to still be the case even with what I believe is the latest version of org-mode unfortunately.
    – avv
    Jun 4, 2020 at 6:55

1 Answer 1


As of org version 9.5-dev in 2021 (and possibly earlier), the option

#+OPTIONS: broken-links:mark

Produces nearly the desired behaviour:

#+OPTIONS: broken-links:mark

* Test

Philosophers love [[determinism]]

enter image description here

The documentation for the customization option org-export-with-broken-links is:

org-export-with-broken-links is a variable defined in ‘ox.el’.

Its value is nil

  You can customize this variable.
  This variable was introduced, or its default value was changed, in
  version 26.1 of Emacs.

Non-nil means do not raise an error on broken links.

When this variable is non-nil, broken links are ignored, without
stopping the export process.  If it is set to ‘mark’, broken
links are marked as such in the output, with a string like

  [BROKEN LINK: path]

where PATH is the un-resolvable reference.

This option can also be set with the OPTIONS keyword, e.g.,

There is no option to customize the appearance of the broken link. However, the function involved is org-export-data in the file ox.el, and it would be relatively straightforward to over-write the function if you want to tweak things.

Your Answer

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

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