Anchor Syntax
en's anchor syntax can be very flexible, but some situations lead to ambiguity.
In short, following these two rules should keep you out of trouble:
- Avoid characters with special meanings in your node IDs: TOML allows you to use a wide range of characters in identifiers, but when writing your graph it's better keep your IDs free of some characters. Accents and ideograms are fine, but characters such as
#,&,:and/are not because they are interpreted differently by en and URL parsers, which might lead to unexpected results - Know you can be explicit to force proper evaluation: When needed, use full three-pipe anchors, as in
|text|destination|, to make your anchors fully unambiguous
Basic anchor
See the Anchors section in the Syntax page for the basic anchor syntax. The following sections go into more detail on some edge cases.
Trailing characters in anchors
For internal anchors, most punctuation is automatically separated from the anchor destination so you can simply write:
This gem|PreciousStone, though green, was not an emerald.
This gem, though green, was not an emerald.
This is one of the reasons to avoid punctuation in your node IDs.
The punctuation symbols that are ignored at the trailing boundary of anchors are:
, . : ; ? ! ( ) ' " ` | _ *
For external anchors, you often must add a third | to explicitly set the end because external URLs can have all sorts of arbitrary characters. This is not necessary for spaces, but it is for other characters.
Plural node anchors
Something similar applies to the lowercase letter s:
We found three |boat|s at the marina.
This conveniently lets you write plural words as anchors to their singular form without having to write:
We found three boats|Boat at the marina.
Which is annoying to write and makes the text a lot less fluid.
Unlike with punctuation, this doesn't mean you can't have a node with the ID s. You can, but you'll have to write your anchors to it always with a trailing pipe:
The |letter s|s| is important so we dedicated a whole page to it: |s|!
Spaced node anchors
If you write a node anchor with spaces, it will be collapsed:
This |Node Anchor| will work as if it were |NodeAnchor|.
Accordingly, node IDs should not have spaces because, among other things, this feature makes it impossible to create an anchor to them.
Case-insensitive fallbacks
Because node ID resolution redirects to a lowercase match if it can't find an exact match, you can write:
The next |precious stone| was stolen in 1973.
And the visible text will still display as "precious stone" but point to an ID such as PreciousStone.
This is not a problem if you want to refer to a specific ID that differs only in case because the case-sensitive match takes priority.
URL detection
en must differentiate node anchors from outgoing URLs:
|internal|Internal| |external|https://external.example.com|
It does this by looking at the destination and checking if it contains a / or :. That's one more reason to avoid these characters in your node IDs.