Nodes and references

Last updated: September 3, 2024

Overview

The first thing you'll encounter in Tana is the node.

Nodes look like bullets, and are the basic building blocks of Tana: They are designed to be light, rearrangeable packets of information. Use it to store a piece of information: A note, an idea, a paragraph.

The atomicity of nodes is key for unlocking the power of Tana: Nodes are the indivisible parts of a living information system. Living, because a node can grow and change over time. The simplicity of the node allows it to be used as a plain bullet for taking notes, all the way to powering sophisticated daily dashboards of dynamic information driven by Commands and enhanced by AI.

A node is an object that can be reused anywhere in Tana: Imagine if every time you visited your friends, they would forget your name and all the memories you've had together in the past? It's not just very annoying, but this is what's happening in documents and folders everywhere: you as a person is mentioned by name, but none of these mentions connect to a single entity that represents you, so the info gets stale (unless you're one of those who, on your birthday, is "always" turning 25). In Tana, every time you mention a quote in different contexts, you can connect it to the actual quote in the book it came from. Let's say the quote had a mistake - changing the quote in one place changes it everywhere it has been mentioned. These mirror versions of nodes in Tana are called References.

References ensure that important information stays relevant and updated: In Tana, if you have entered the information once, it is easy to pull it into different contexts again and again just where you need it. In meeting notes, create tasks as they arise in conversation and use Supertags to make them magically appear on someone's task board an instant later. This powerful connectivity enables you to update information everywhere, on the fly, in one go. No more mission-critical information getting outdated, going stale and being forgotten.

Basics

• In Tana, everything is a node: The fields, the views, the commands, the settings, layouts, workspaces, the daily page... everything. The difference between these node types is the kind of information Tana stores in them. For more info, see Node types.
• Every node is unique: Nodes are not just bullets, they are sophisticated containers for information. Every node in Tana is given a unique ID upon creation. You can see the ID of the node in the URL bar when you copy a link of it. This means that even though two nodes may look the same and spell out the exact same thing, they are considered different if they have different IDs. There's also a dozen other pieces of metadata collected per node in Tana.
• Every node has an owner, a single source of truth: All nodes have a permanent address within Tana's outline hierarchy. This means that a node will always have a parent: a node that is one level higher than them in the hierarchy, essentially their owner (with some exceptions). Why nodes only have one owner each is explained in the next paragraph:
• Mirror copies of nodes are References: In Tana, you can have mirror copies of nodes. These copies reference the original node, hence their name Reference, and are one and the same for all intents and purposes. Editing one reference edits the original and thus every other reference of this node in Tana. There are some differences to keep in mind. For one, they are not owned by their parent: Parents of these mirrored nodes are just parents. Also, when you delete references, you're not deleting the original node, the single source of truth.
• Nodes do not accept line breaks: To maximize the reusability of nodes means upholding strong design principles that keep their atomicity and simplicity intact. Therefore, Tana does not accept soft line breaks within a node, as it would make the node less uniform and universal.

Documentation

About nodes

NodeID

Every node is given a unique nodeID

• The easiest way to find it is to use the command get html link to node and paste it somewhere. This yields a text that looks like this, where the link opens Tana at the specified node given you have access to it:
  • "Tana node aXvnZWOpXAsU: Every node is given a unique nodeID"
• You can use this code to find the node it refers to. Paste it into the global search bar and the node with that ID should show up. Note: You have to have access to the workspace that the node resides in, or it won't work.
• A node cannot be referenced more than once as a child. This is because we don't allow the same nodeID to appear twice in the same list.

Node properties

Every node carries the following properties

Nodes vs. references

• What is a node: A node is a container for information.
• What is a reference: A reference represents a mirror copy of a node.
• Node/reference relationship: Every reference has a direct connection to their original node. You can't have a reference without an original node that it refers to. If the original node is trashed, references won't be trashed but appear with a trashcan which you can click to bring out of the trash.
• The technical difference between nodes and references: They are carbon copies because they use the same ID to draw from the same data. The only difference is that one of the parents of the references matches the value in the Owner field, turning that reference into the "original" node.
• Changing a node's ownership:
  • Within the same workspace: you can change a node's ownership by swapping places between the original node and any of its references. On a reference, use the command Bring referenced node here and it'll change the owner to its parent, making this the original node.
  • Between workspaces: you have to use the command Move to, or cut-paste a node between workspaces.

Creating and editing nodes

Create and edit nodes

• Like any text document, click on the page and start writing.
• Hit Enter to make a new node
• Nodes are designed to contain a string of text, with no line breaks.
• Nodes can receive most images/audio/video formats from copy-paste or drag-drop. PDFs too.

Formatting text in a node

Here are all the formatting options that can be applied to text:

• Bold Cmd/Ctrl+B
• Italics Cmd/Ctrl+I
• Underline Cmd/Ctrl+U
• Strikethrough
• Code ` (back tick)
• Highlight Ctrl+H

Also see Text selection toolbar

Add a checkbox to a node

• Any plain node can be a checkbox: Cycle through each checkbox state by hitting Cmd/Ctrl+Enter
• Supertags have a setting to turn on checkbox by default: for more on that, see Supertags

Slash / on empty node

Use slash on an empty node to create the following:

• Search node
• Field
• Reference
• Image / file
• Heading
• Checkbox
• Start live transcription: Begins to transcribe using your microphone. Requires Tana Core.
• More commands (vertical ellipsis)

Add emojis 🙃

You can create emojis on the fly by hitting colon : and entering a word that describes your emoji.

There are also OS shortcuts for accessing emojis:

• MacOS: Ctrl + Cmd + Space
• Windows: Start key + period key

Lock nodes

• There's an option to lock nodes so they become non-editable.
• Nodes can be locked by using the command Lock node. If using Build Title on a Supertag, this will also lock parts of the node that are derived from field values.

Moving nodes within the outline hierarchy

• To indent a node, use Tab. This makes it a child of the node directly above it.
• To outdent a node, use Shift-Tab. This makes it a sibling relative to its old parent
• For more documentation regarding nodes in the outline structure, see Outline editor.

Creating and editing references

Create/edit a reference

To create a reference:

• On the node you want to reference elsewhere, put your caret in the node and copy it with Cmd/Ctrl+C.
• On an empty node, paste a reference of the node with Cmd/Ctrl+V.

If you don't want to paste a reference and instead just want its plain text content, use Cmd/Ctrl+Shift+V.

✨NEW References are treated as enclosed objects in Tana.

• To edit a reference, hit Enter or double-click it.
• To bring up the edit toolbar, hit Esc or right-click it
• To zoom into it, hit Spacebar or click on the node icon.

Create an inline reference

Option 1: Create inline reference using copy-paste

• Copy the node/reference with Cmd/Ctrl+C
• Paste with Cmd/Ctrl+V and hit Spacebar

Option 2: Create inline reference using @-mentions

• From inside a node, type @ and then the keywords for the node you're looking for. You can navigate to it using the Up/Down arrow buttons and hit Enter to select it.

Rename the inline reference using Alias

If you want the inline reference to be written out differently, select the inline reference , then use Set Alias on the Text selection toolbar and type out what you'd like it to be.

Reference section

• References: If a node has references, at the bottom of such a node will be a section with the title "References". Expanding this will show you the breadcrumbs of where these references exist in the workspaces it appears in.
• Unlinked mentions: Here you'll also find something called "unlinked mentions", which shows you all places where the name of the current node is found elsewhere in Tana but is not linked (as a reference or inline reference) to this node. From here, Tana gives you the opportunity to establish a link if you want using the button "Link" to the right.

Reference counter

• There is a floating reference counter that appears to the right of every node that is visible, and not in focus/zoomed into.
• The number shows you how many references a node has, similar to the Reference section in the footer of a node.
• Click on the number to see where else the node has been referenced.
• You can turn on Reference counter in Settings > Preferences > Show Reference Counter.

Deleting nodes and references

Nodes and references are made differently from regular bullets, so there are some things to keep in mind when wanting to delete them.

• To delete a node with no references:
  • Option 1: Use Cmd/Ctrl+Shift+Backspace on the node.
  • Option 2: Right-click on the node bullet and select "Delete node"
  • Option 3: Using Backspace on all the words and then finally the node itself will also work.
  • Note: If a node has content and your caret is at the beginning of it and you hit Backspace, it will delete the node and merge this node's content with the node above it.
• To delete a reference without editing its contents:
  • Option 1: Use Cmd/Ctrl+Shift+Backspace on the reference.
  • Option 2: Right-click on the node bullet and select "Delete reference"
• To delete a node and all its references:
  • Use the command Hard delete including references. This will remove the references in the current workspace, but make references in other workspaces show up with a Trash icon.

Text selection toolbar

When you interact with text using a mouse, Tana gives you options in a toolbar based on what is selected.

When selecting text

• @ Reference: Creates a new inline reference, or lets you pick an existing reference from the popup
• # Tag: Creates a node from the selection and creates/applies a tag of your choice.
• Formatting: Bold, Italics, Underline, Strikeout, Code, Highlight
• Remove formatting

When clicking an inline object

• Open: Opens node in panel
• @ Set alias: Change the text of the link
• # Tag: Apply tag to inline object
• 🔗: Copies the node URL to clipboard
• Open to new panel: Opens node in the right dock
• ···: Access all commands

Banners and Icons

You can add an icon and a banner to any node.

Add an icon to a node

✨NEW You can add an icon to a node, which will replace the bullet icon.

• When zoomed into a node, hover over the title and you'll see ☺︎Icon as an option. Click on it and the emoji picker will appear.

You can add a default icon to a supertag, which will replace the bullet icon on all instances.

• Click on the supertag to go to the supertag page, and set an icon here.

Add a banner to a node

✨NEW You can add a banner to a node, which will appear as part of the header.

• When zoomed into a node, hover over the title and you'll see Banner as an option. Click on it and follow the instructions to set a banner.

You can add a default banner to a supertag, which will replace the banner on all instances.

• Click on the supertag to go to the supertag page, and set a banner here.

To save a banner, right click on it and select Move banner image to node

To remove a banner, right click on it and select Remove banner image.

Node configuration

To get to the node configuration: with your caret on the node you want to configure, run the command Configure node

Child supertag

• A supertag can be set to apply to all child nodes.
• To configure the supertag to be applied to all children of a node, add a supertag definition in the field.

Banner image

• Nodes can have banners. Tana will make any format of image fit the landscape crop of the header.
• To give a node a banner, drag an image into the Banner image field.

Page size

• Nodes can trigger pagination on child nodes if they exceed a certain number.
• By default, when a list of child nodes is 100 or more, it automatically triggers pagination.
• To change this, specify in numbers how many child nodes can be visible before pagination gets triggered.

Commands

• Commands can be permanently attached to a node, so they appear as buttons appended to the node name.
• To add commands, go to the node config window > Commands and add them here. Read up on Commands for more on what they are and how to make them.

On child added/removed

• You can trigger custom commands to run when child nodes are added or removed from the target node.
• To configure: Use the command configure node and scroll down to the On child added/removed. Add the command nodes here.
• Use case examples:
  • When a child is added, give it a tag and run an AI prompt
  • When a child is removed, add the current time to a field of the child
• Limitation: If nodes are added/removed via API, it will not trigger as they are currently not recorded as a user action. This is a limitation with the way the API is implemented.

Contextual content

To add notes to a node without making it permanently part of that node, you can use something we call contextual content.

In List view: use the shortcut Cmd+Option+Arrow Down (Mac)

In Table view: It's available as a column via the Add+ button at the end of the columns

A node with contextual content will display as a diamond instead of a circle.

Contextual content tends to be most helpful when you write a live search (viewed as a table) and want to process all of the results in some way without adding new data directly to the nodes. It can be as simple as adding a contextual checkbox field that says "I already looked at this."

Node management

Merging duplicate nodes

If you have duplicate objects in Tana and you want to merge them to one, you can select them and use the command Merge node to choose which node you'd like to merge the other into. This works on nodes, supertags and fields. When a node is merged into another:

• All the children are combined (if they both have the same fields, children in that field are also combined)
• All tags are combined, and the original node is put into trash
• All references and inline references in the available workspaces are updated to point to the new node.
• If there are workspaces that had not been loaded during the merge with references to the merged node, these references will clearly point to the new node.