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

For all purposes in Urtext, bracket nodes’ identities are unique from their containing files, parent nodes, and child nodes.

The syntax is to wrap the content in curly braces:

{ Example node in brackets }

Nodes can be nested arbitrarily deep.

{ 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 are 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.

Node Titles

The title of a node is be default 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  bolds the preceding text on the line. If it is used more than once, only the first use in the node is observed.
In any node, the title metadata key, if present, overrides both 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

Every node must be uniquely identified in the project. When nodes with duplicate titles appear, Urtext resolves (disambiguates) them using, in order of preference:

  1. the newest timestamp in the node

  2. if the node is metadata, its metadata key

  3. the title of its parent

If none of the above is available, a new timestamp is inserted and the first option is taken.

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 node ID appears in links as:

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

Nodes with no text

Nodes with no text receive the default title (untitled). Untitled nodes are resolved as others (above).

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.