Nodes

Urtext’s basic unit is a node, a range or set of ranges of text, up to and including an entire file. A file is itself a node, and nodes can contain other nodes.

File Nodes

The most basic node is a single file. It may or may not contain other nodes nested inside it.

To create a new file-level node, press ctrl + shift+ ;

A new file is created and named automatically. It contains by default a creation timestamp.

The template for new file nodes can be changed with the new_file_node_format key in project_settings.

Bracket Nodes

Nodes can be nested arbitrarily deep. For all purposes in Urtext, bracket nodes’ identities are unique from their containing files, parent nodes, and child nodes.

The syntax for bracket nodes is to wrap the content in curly braces:

{ Example node in brackets }

Bracket nodes use syntax highlighting to showing nesting level:

{ Parent Node

  { Child node

    { another child node

      { yet another child node

        { This can go on as deep as you wish }

      }

    }

  }

}

Every opening curly bracket must be closed in the same file. Stray closing brackets are highlighted in an error color:

{ }

}

Urtext is self-correcting, however. On file save, stray brackets will be removed and missing ones added to balance the bracket syntax.

Nodes at the file level do not use curly-braces, as their region boundaries are the file itself.

Escaping Curly Braces

If you need to use curly brackets in your text, escape the Urtext syntax by preceding the bracket with a backward slash; this will prevent them from being parsed.

This brace will not be parsed as a node wrapper:

\{

To ignore syntax elements more globally, and/or to embed other syntaxes that use Urtext characters, such as JSON, PHP, and JavaScript, see Escaping and Embedding.

Bullet Nodes

For nodes that can fit on a single line, such as items in a list, short phrases, word definitions, and so on, a bullet syntax is available. Begin the line with the bullet character, inserted with ctrl+shift+^

The closing wrapper is the next newline (the end of the same line). Bullet nodes:

can contain metadata
can contain bracket nodes, including nested ones, as long as they are all on a single line.

• Example of a bullet node { example a bracket node within a bullet node }

Node Titles

By default, the title of a node is its first non-whitespace line. This can be overridden with the title_marker syntax, which is to follow any text with whitespace and a single underscore character:

Even though this text begins the node . . .
This line will be the title _

The title marker also bolds the preceding text on the line. If it is used more than once, only the first use in the node will be observed.

In any node, the title metadata key, if present, overrides both of the above.

This text begins the node . . .
This line will still not be the title _
title::The title will be this, since the title key overrides both

Node IDs

Node IDs are often, but not always, identical to their title. Node IDs will be different from their title under two conditions:

Duplicate titled nodes in the project

When there is a duplicate node in the project, Urtext attempts to resolve, or disambiguate, the node, using first the title of its parent, then the oldest timestamp in the node, then the oldest timestamp in any ancestor node. The resulting ID is the node’s title followed by the node_resolution_marker, a caret surrounded by spaces, followed by the resolution point. The resulting ID appears in links as follows:

| A node with a duplicate title ^ The Parent Node’s Title >

If no resolution point can be found, the node is dropped from the project.

Nodes with no text

Nodes with no text receive the default title (untitled). Untitled nodes are resolved as above; if no resolution point is available, the node is dropped from the project.

Resolving Nodes

If a duplicate or untitled node cannot be resolved, the easiest solution is to give it a unique timestamp, usually the current time, by pressing ctrl + shift + t.