@ () path/to/list_name { Header for this link (optional) }
The starting @ character tells the parser that this is a markup tag line of type list link. This must be followed by ( ), which may or may not contain an optional link limiter (more on this below). The line ends with a relative path in relation to the user home folder where all lists are stored.
The text of the linked list can be added into the parent list in the following ways:
1. Seamless linking will blend into the parent's text in the final generated output without indentation, where it will look as if it were all written together as a whole. To do this, simply have the opening and closing brackets without a header line between them.
Template syntax
Contents of equipment/tools list
⇒ Generated Output
1 2 3 4 5
Pack bag @ () equipment/tools { } Drive
1 2 3
Wrench Pliers Screwdriver
1 2 3 4 5
Pack bag Wrench Pliers Screwdriver Drive
2. If the optional { header line } is provided, then the linked list content will be included as a section of lines indented by 2 spaces. This header line is only included if generated output is produced by the linked list. If the linked result is empty (e.g. due to user prompts not selecting any output), then the header line will not appear.
1 2 3 4 5 6
Pack bag @ () equipment/tools { Bring tools } Drive
1
# Empty list
1 2
Pack bag Drive
3. An optional header character ^ in the header line area will create an auto-generated header based on the list path.
1 2 3 4 5 6
Pack bag @ () equipment/tools { ^ } Drive
1 2 3
Wrench Pliers Screwdriver
1 2 3 4 5 6
Pack bag tools (equipment/) Wrench Pliers Screwdriver Drive
There are a few options for how the resulting contents of a linked-to list(s) can be treated. The keywords inside the parentheses define this behavior, and are discussed in this section.
¶ Limiting how often a particular list can be linked-to
If provided, the limiting type in parentheses can restrict how often the link happens when generating the final output. If no limit is provided, then the link may be included an unlimited number of times in a session. If one of the following limits is provided, then the link might not be included as described. Only one of these keywords can be used.
@ (global) list Linked only once when generating final output. In this case, the link will be ignored if it has already been encountered in the current list or any of the previous lists.
@ (local) list Linked only once from a particular list. If a reference of this type is encountered, then the reference will be ignored if it has already been link previously in the current list. If it was only linked from another list, then it will be linked from this list.
Using a link limit can prevent redundancy, which can happen because lists often include a single resource that is included multiple times due to various linked lists or different possible conditional paths. Using a global limit on a reference for a camera bag, for example, will make sure that the bag is only included once in the final generated checklist.
Note that future links can not be affected. If a link is encountered later without a limit, then it will be included even if previous links were locally or globally restricted.
Without a collating keyword inside the parentheses, the contents of the linked-to list(s) will be treated in the normal fashion. Adding one of the following collating keywords (only one allowed) will change how the contents of the linked list are presented in the final result.
sorted
Sort the results in alphabetical / numerical order
unique
Eliminate any repeated lines which are exactly the same, and only display one instance for each line. The results are not sorted, but instead handled in the order that they appear.
quantity
Add a quantity number to each line
Collation is only recommended for certain list types. It is intended for (but not limited to) items or objects rather than tasks.
One important note about a collated list: indentation is not preserved the same way it is everywhere else. Any indented lines will lose their additional spacing; all lines are treated as being at the same level.
The quantity modifier is useful with a list containing tasks or items that only need to be performed once, or included in an inventory once. Every line from the linked-to list is prefaced with "(n) ", containing the quantity number.
Template syntax
Contents of equipment/tools list
⇒ Generated Output
1 2 3 4 5 6
Pack bag @ (quantity) equipment/tools { What to pack: } Drive
1 2 3 4 5 6
Wrench Pliers Pliers Screwdriver Pliers Wrench
1 2 3 4 5 6
Pack bag What to pack: (2) Wrench (3) Pliers (1) Screwdriver Drive
When the parser encounters a list link, it “jumps” into the list. That list may itself contain a link to yet another list, which contains another link, and so on. This link-within-link-within-link pattern is allowed up to a limit of being 50 links deep, at which point an error message will be shown when trying to generate the output checklist. Otherwise, there is no limit to the total number links encountered while parsing.