This version is out of date, covering development from v9.5.0 to v9.7.3. It is maintained here only for inbound reference links from elsewhere. It is no longer actively updated.

Jump to the current version of aTbRef

Tinderbox v9 Icon


Making an alias to a note allows a note to be placed (i.e. appear) in more than one location in a Tinderbox document, just like an alias in macOS. The original note can be in one place in the hierarchy whilst the alias can be somewhere else entirely. Both the original note and the alias give access to the content of the note: the same $Text, the same attributes, and so on; see notes below re intrinsic attributes. An original and its alias(es) can share the same container/map, though normally will be in different ones.

A note can have many aliases, or none. Aliases are a flexible way for organising notes in ways that a simple Outline-style hierarchy does not permit.

An alias will always have the same name as the original. Change the name of either the alias or the original, and both will change.

Creating an alias

If you are in a view window, first select the correct note with the arrow tool. The new alias is inserted immediately after ($OutlineOrder) the source item; noting both have the same title, it is the new alias that is now selected (the styling of the title should indicate this is the alias). There are several methods:

Drag from Find. A further method is to drag an item from a Find results pop-up/tear-off into the view pane. In this method the alias is placed at the drop point (Map) or closest insertion point in other view types.

Newly-created aliases in map view take their height and width from that of their original note, and are placed on the map to the right of their source item (assuming there is suitable free space, the alias is otherwise placed to avoid overlapping/compositing with another note).

Once created, the alias can be moved anywhere in the current document.

Agents. Another method of making aliases is to create an agent as that will create aliases for any notes matching the agent query. Aliases can then be dragged elsewhere, in which case the agent wiil spawn a new child alias as the source note still matches the query.


When exporting, aliases also behave as if their original note's children were their own children. Aliases are exported as separate pages in the appropriate location within the output. This makes it easier to use web links to alias content that point to the right place. It also helps when web output uses a hierarchical navigation system as with aTbRef.

When including children that are aliases such as when using ^children^ and ^descendants^, items that happen to be aliases are included as aliases (so reflecting intrinsic attribute values). Since for most purposes the alias and its original are interchangeable, this seldom affects export. However, intrinsic properties of the alias are exportable (and may differ from those of the original).

Reflecting the way aliases are treated as separate entities in an export context, basic links to or from aliases belong to those aliases and they support their own Roadmap view and Browse Links windows. However, the links() action code cannot currently address aliases as a destination object so analysis of links to/from an alias is best done visually or by means of Roadmap view. Originals and aliases export their own basic links (i.e. aliases can differ), but if an alias has no in/outbound basic links it will export those of the original. In the latter case the alias will show no basic links internally, e.g. in Roadmap view, but on export will inherit its original's basic links.

Text links as well as basic links are generated from exported aliases; the destination of the link is the same regardless of whether the source is the original or an alias. An alias can never have $Text/text links that differ from that of its original: that is fundamental of the point of it being an alias.

Copying aliases

Any alias can also be copied or aliased. However, do note that when copying/aliasing an existing alias the new alias is created as if being made from the alias's original though it uses the original's attributes rather than the source alias' intrinsic attributes. Likewise, the source alias' discrete basic links are not copied, i.e. the new alias will start with no basic links. In short you cannot make a copy of an alias that maintains the intrinsic differences of the source alias from the original. Aliases cannot be copied outside their current document, as another TBX will not hold the original of the (alias) note being copied. An alias needs to point to its original for many of its attribute values so the two must reside in the same document.

Identifying aliases in queries

The $IsAlias attribute can help with identifying whether a note is an alias or note. This is especially helpful within agents where all matches are aliases, regardless of the type of note being matched.

The $Container attribute is worthy of note as this means the 'parent' designator value of an alias does not equal that of the original note. This becomes important in agent actions where the acted-on note is an alias. It is thus often necessary to use syntax like $Name(parent(original), i.e. the name of the original note's parent container, rather than $Name(parent). In an agent action the latter code returns the name of the agent. Incidentally, in the last scenario $Name(parent) and $Name(agent) would both return the name of the Features needing more recent OS versions (more on the 'Link type honouring operators', 'original' and 'parent' designators).

Finding and counting aliases

Normally, the need it to reduce the number of matches but in some cases the opposite is needed: to find and/or count all the aliases of a note. The simplest method is to look at $Aliases for a given note. This is List of the paths of all aliases of the original note. Thus $Aliases.count gives the number of aliases of that note.

Another approach is using find(). An agent query de-duplicates matches, weeding duplicates and always taking an original over an alias. In contrast find() returns the (paths of) all matching objects, original and aliases. If there is no other scoping query term, find().count returns a count 1 larger than $Aliases.count, i.e. 1 original plus count of all aliases.

If the need is to find or count aliases within a defined part of the outline, or sharing some common attribute value(s), then find() is the best approach. Remember to add the query term '& $IsAlias' (i.e. $IsAlais is true, the item is an alias) to ensure any match to the original is filtered out. The returned find() list's size can then be checked for a count.

Aliases render in italics

In any major view aliases are always drawn with their title ($DisplayName) in italics. There is no way to make an alias be titled in normal type; this is by design, mirroring how the Mac's OSs have shown aliases. One result of this is that when older, pre-v6, TBXs are opened in v6+ they may not render aliases in italics: see more. There is a document setting to also underline alias titles, although they still render in italics (if possible).

Link counts and aliases

$InboundLinkCount and $OutboundLinkCount are intrinsic and report separate values for the alias and original note, those they may often be the same (outbound text links are always the same for original and alias).

Word counts

Word counts in Get Info/info pane do not include the $Text word counts of alias notes, just the count of the original $Text.