Nodes and references

Nodes are the fundamental building blocks of Tana, each representing a piece of information that exists in the hierarchy of the outline structure. A node is atomic in format, making it infinitely malleable and rearrangeable. Nodes can exist in many places at once, as References. Everything in Tana is a type of node, which is part of the design philosophy that makes Tana so powerful.
Last updated: October 28, 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:
  • 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

SYSTEM FIELD NAMESYSTEM FIELD DESCRIPTIONEXPRESSION (title/prompt)
Node nameThe written contents of the node${name}
Node descriptionThe description of a node. Add a description in the node config or by hitting Ctrl+i (Mac) or Alt+i (PC)${sys:description}
Created timeThe time the node was created${sys:createdAt}
Last edited timeThe time of the last edit${sys:lastEditedAt}
Last edited byWho the node has been edited by${sys:lastEditedBy}
Edited byAll users who have edited the node${sys:editedBy}
Owner nodeThe owner of the node. A node can have many parents, but only one owner.${sys:owner}
TagsSupertags applied to the nodeOnly works in Prompts/Commands: ${sys:tags}
WorkspaceThe workspace this node belongs to
Number of referencesNumber of times the node is referenced across all available workspaces (calculated)
Date from calendar nodeDate based on ancestor calendar node (if any)${sys:dateFromCalendarNode} *used to be "dateFromDayNode"
DoneBased on node's checkbox state "Yes"
Done timeWhat time a checkbox was checked by a user. Is not triggered by done-state mapping.${sys:doneTime}
PathWhere the node lives in Tana
IDThe ID of the node.Only works in Prompts/Commands: ${sys:nodeId}
(Content)The indented content of a node: its child nodes and references with their context expanded.Only works in Prompts/Commands: ${sys:content}
(Context)The whole node: its name, fields, field values, child nodes and references.Only works in Prompts/Commands: ${sys:context}

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. See Storing files on nodes

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

Keeping track of tasks in the form of checkboxes are a fundamental part of a node. It is baked into the metadata of every node through the Done and Done time system fields. There are some very simple and powerful things you can do with checkboxes in Tana to track your tasks:

  • Any plain node can be a checkbox: Cycle through each checkbox state by hitting Cmd/Ctrl+Enter.
  • Checkboxes have three "done states": no checkbox, not done, and done.
  • You can find all checkbox nodes that is a descendant of a node by running the command Find todos within →. This is handy when you've been creating tasks on the fly and want to gather them all.
  • Special search terms exist for finding nodes with checkboxes:
    • TODO - finds all nodes with checkboxes, no matter their done state
    • NOT DONE - finds all nodes that are unchecked
    • DONE - finds all nodes that are checked
    • DONE LAST <X> DAYS - finds all nodes that were done the past X days. Write it out like this: DONE LAST 7 DAYS
    • For more, see Search nodes
  • Supertags have a setting to turn on checkbox by default: for more on that, see Supertags
  • Supertags can have their done state mapped to the values of a field: 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.

See edit history

Every node has a record of its creation time, and edit log. To see it:

1. Hover over the node bullet, then 2. click on the Edited by line to show the edit log
Nodes in focus do not have the bullet visible because they're displayed as headings. To check the edit log of the node in focus: 1. open the ellipsis menu, then 2. click on Show edit log.

Creating and editing references

Create/edit a reference

To create a reference:

  • Option 1: @-mentions. On an empty node, type @ and select a reference with Enter
  • Option 2: Copy/paste. Copy any node with Cmd/Ctrl+C, then on an empty node, paste the reference with Cmd/Ctrl+V.
    • If you didn't want to paste a reference but rather its plain text content, hit Cmd/Ctrl+Shift+V.

Edit a reference

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

To create an inline reference:

  • Option 1a: @-mention on empty node. Type @ and then the keywords for the node you're looking for. Hit Shift+Enter to select it.
  • Option 1b: @-mention in the middle of a node. Type @ and then the keywords for the node you're looking for. Hit Enter to select it.
  • Option 1c: @-mention in the middle of node to make a new node in Library. Type @ and then the keywords for the node you're looking for. Use Cmd/Ctrl+Enter which will create a new node in Library and make an inline reference to it here.
  • Option 1d: @-mention with text selected. With text selected, type @ and then find the node you're looking for. Hit Enter to create an inline link using the selected text as alias.
  • Option 2: Copy/paste, then type. Create inline reference by first copying the node/reference with Cmd/Ctrl+C, then paste into empty node with Cmd/Ctrl+V . Hit Spacebar or any other key to make it inline.
  • Option 3: Type, then paste. Start typing in an empty node, and if you have a reference already copied, you can paste it anywhere in the node to make an inline reference.

Edit an inline reference

For a quick look at what's inside the inline reference, you can expand it in context without navigating to it:

  • Shift+click on an inline reference
  • Focus on an inline reference and press Cmd/Ctrl+Arrow down

(This section is greatly improved thanks to Navigator Maciej for writing an excellent post on all the ways to create references and inline references back in early 2023! 🙏)

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

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

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.

Right-click on a banner to:

  • Upload new banner
  • Remove banner image
  • Move banner image to node

Storing files on nodes

Nodes can handle pretty much any type of file. Drag a file onto a node in Tana and when you see a purple drop zone, let go to upload the file.

Files can be easily downloaded, and a few common web-friendly filetypes can be previewed in Tana. These include:

  • Images
  • Video
  • Audio
  • PDFs

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.
  • 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.

Related release notes

  • ImprovedPasting a Tana node or a link to a Tana node while text is selected, turns the selected text into an inline link to the node (similar to what happens if you paste an external URL over selected text) ()
  • ImprovedWe now automatically create a new checkboxed item when you hit enter at the end of one checkboxed item. A simple backspace will remove the checkbox on the new node. ()
  • ImprovedButtons in the panel header are now right aligned instead of left aligned, and showing only the source material icon, not text. ()
  • FixedFix issue where second right click didn't open native context menu on nodes in fields ()
  • InfoWe now hide first/last page button in pager menu if there's less than 5 pages ()
  • FixedRe-introduced: Right click when node options context menu is already open opens the native context menu. Now we can fix our spellng errors again! ()
  • ImprovedWhen you right-click a node now, you see a context menu instead of the toolbar. We've also added context menus on right-click to several places, like related content headers, panel headers, and breadcrumb items. ()
  • FixedDragging images to upload a new banner to a node was broken, it's fixed now. ()
  • NewWe have fullscreen preview! Expand image nodes by hitting <space> while it's focused. Use the previous/next buttons to navigate to the previous or next image in the list. ()
  • ImprovedFullscreen preview now supports video nodes, in addition to image nodes. It works just like images, and will autoplay when viewed. ()
  • Fixed@-mentions will now only show recently opened nodes from workspaces you have "allowed content from". ()
  • ImprovedWe decrease the font size of the panel header for very long node names ()
  • ImprovedThe sorting for at-mentions no longer penalizes nodes with title expressions, but we slightly boost nodes whose name (not title) start with the same string that you searched for ()
  • ImprovedEnsure that recently created nodes show up in the at-mentions immediately ()
  • FixedFix bug that prevented newer Vimeo videos with longer IDs from embedding ()

Related FAQs

Examples

  • How can I use system fields in Title expressions/Build title from field
    Dec 04, 2024

    Calculated system fields are prefixed with sys: to avoid being mixed up with user-created fields with the same name.

    Example: ${sys:owner}

    Calculated system fields and their respective title expressions can be found here.

  • How can I find references in one workspace that are owned by another?
    Sep 26, 2024

    To find all references in a workspace that are owned by another workspace:

    1. Go to your workspace home

    2. Create this search as a direct child of the workspace home node:

    • GRANDPARENTS DESCENDANTS WITH REFS
    • >NOT GRANDPARENTS DESCENDANTS

    To limit the search to specific workspaces, add the system field Workspace and specify the workspaces you want to target there.

  • How to find nodes with empty/not set descriptions
    Sep 05, 2024

    You can use regex to find this:

    • Add a reference to the area you want to search within
    • >NOT >Node description:: /.+/

Question

  • Why are line breaks not supported in Tana?
    Dec 02, 2024
  • When I check a checkbox node, it disappears. Where does it go?
    Sep 26, 2024
  • How can I save the image from AI-generated banners?
    Sep 26, 2024
  • Can you build a wiki in Tana?
    Sep 26, 2024
  • How do I delete nodes?
    Sep 26, 2024
  • What is the difference between the Owner and a Parent of a node?
    Sep 26, 2024
  • How do I remove the strikethrough on a node whose text is not formatted?
    Sep 26, 2024
  • What are all the ways I can copy data out of Tana?
    Sep 26, 2024
  • What does it mean when the yellow message "editing in X places" pops up?
    Sep 26, 2024
  • Can I create aliases in Tana?
    Sep 26, 2024
  • How can I merge two or more nodes/fields/supertags?
    Sep 26, 2024
  • Where do deleted/trashed nodes go? Does the trash get emptied?
    Sep 26, 2024
  • How do I set up relationships between nodes?
    Mar 18, 2024
  • What is a Reference in Tana?
    Feb 01, 2024