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.

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.
  • 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 DESCRIPTIONTITLE EXPRESSION
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 node
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 Commands: ${sys:nodeId}
(Content)The indented content of a node: its child nodes and references with their context expanded.Only works in Commands: ${sys:content}
(Context)The whole node: its name, fields, field values, child nodes and references.Only works in 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.

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

鉁∟EW Use slash on an empty node to get an option to add a number of things:

  • Field
  • Reference
  • Search
  • Heading
  • Checkbox
  • 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.

鉁∟EW 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

鉁∟EW 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

鉁∟EW 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.
  • 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.

Contextual content

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

It's available as columns in the table view and on items in the list view.

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

  • newReleased audio-powered fields and tags 馃棧锔 ()
  • newReleased related content ()
  • fixedIt's now possible to copy a reference when the focus is on the checkbox ()
  • fixedWe fixed a bug where the query builder under a heading would look strange. ()
  • fixedWe fixed a bug where clicking to move a node in Finder while holding 'Alt' would not leave a reference. ()
  • fixedWe fixed a bug where clicking on ... in the breadcrumbs in a search would open the node instead of expanding the breadcrumb ()
  • fixedWe fixed some issues with Chinese editing ()
  • improvedOpening nodes like Schema and Settings from workspace options now respect modifiers to open in new panel. (E.g. holding cmd while clicking) ()
  • improvedWe've made a change to selecting nodes and executing commands using keyboard only: We will no longer show node toolbar until the mouse has been moved. This now works similar to text selection toolbar to reduce visual distraction using keyboard only. ()
  • improvedWe improved legibility of heading hierarchy on the web client: - Slightly smaller sizes - Bolder top level heading - Looks nice ()
  • fixedInline refs inside of references (nodes that live elsewhere), were rendered without color. Now, however... 馃寛馃彸锔忊嶐煂堭煐嶏笍馃帹 ()
  • improvedWe should now be better at restoring scroll position when navigating between nodes ()
  • improvedWe added playback speed config to the audio player. You can now listen to yourself twice as fast. 鈴 ()
  • improvedUsing a '#' in a search will now strictly filter on matching tags if they exist so '#fruit du' should only find nodes tagged with fruit that has a word starting with 'du' in it. Search ranking has also been improved some, it will now only do a fuzzy search if there aren't enough 'strict' matches. ()
  • infoFor a smoother navigation experience, we've now made inline references more akin to the way traditional links work. They now show up in blue, and clicking on an inline ref will now open it directly. Right-clicking the inline ref will show the context menu or toolbar, depending on whether the context is a node or a reference. ()
  • improvedWe got keyboard shortcut for "Create new" - Alt+n for Windows/Linux, Ctrl+n for Mac! (Also: Reminder that you can open the Create new panel in the right or top dock by holding Cmd/Ctrl (right) or Shift (top) when you click on the button.) ()
  • improvedAnd, we got a "Create new in..." command line, including the option to create directly on daily page in other workspaces. ()
  • fixedSome unlinked references no longer showed up in reference section due to personal apostrophic reasons, but we managed to convince them to come back so hooray! ()
  • fixedPasting a bulleted list from Google Docs removed all formatting, but now works again. Things really fell flat on this one. ()
  • fixedWe changed something, then some users said using Tab for inserting dates doesn't work anymore, so using Tab to insert your @-mention selection works (again?). Now, the question is: who picks up the Tab on the second date? ()
  • fixedRight clicking on a table row now brings up the node tool bar ()
  • fixedRight click on a card now brings up the node toolbar ()
  • improvedFor incoming Roam/Workflowy/Obsidian/Logseq/Reflect etc. users, [[ now triggers the @-mentions. [[<3]] ()
  • newThere are now three sizes of headings - these are set automatically, based on nesting. The headings are relative to the closest item with a heading. If you zoom in to a parent of the smallest heading, the smallest heading will become the largest heading. It's like growing up. ()
  • fixedWe fixed a bug where numbers in fixed options, in options fields, were inserted as plain values, not references. ()
  • improvedYou can now type @ directly after a Chinese character (no need for a space) ()
  • fixedFixes an issue where the node icon or date icon sometimes appears on a separate line from the text in an inline ref. ()

Related FAQs

  • Can I create aliases in Tana?

    Yes: in Tana when you create an inline reference, you can change what is written and still retain the link.

    Click the inline reference and a toolbar will pop up that allows you to set the alias.

    Related docs:

  • Can you build a wiki in Tana?

    Absolutely: The most common place to do this is on the Home node. Here are some examples of top level wiki structures, usually arranged on workspace home nodes:

    Related docs:

  • Does Tana have backlinks?

    Yes, Tana has backlinks.

    We call them References, and there is a Reference section at the bottom of every node that shows all backlinks to this node.

    It is also possible to create a search node using the operator LINKS TO that captures backlinks, which you can customize to scope and filter in different ways.

    Related docs:

  • How can I find nodes where the node descriptions are empty/not set?

    You can use regex to find this:

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

    Related docs:

  • How can I merge two or more nodes/fields/supertags?

    Use the command Merge node.

    It also works on references i.e. it will merge the nodes referenced to and all references will be updated accordingly

    To merge nodes

    Select nodes, then run the command.

    To merge fields

    Get the field definitions in one place (copy/paste), select them and run the command:

    To merge supertags

    Get the supertag definitions in one place (copy/paste or @-mention), select them and run the command:

    Related docs:

  • How can I save the image from AI-generated banners?

    Right-click on the banner > Move banner image to node. Then you can download it like you would with any image.

    Related docs:

  • How can I use system fields in Title expressions/Build title from field

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

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

    Related docs:

  • How do I delete nodes?

    It depends what you are deleting, but almost always the cleanest way to delete nodes is using "hard delete" which clears the entire node at once. You can hard delete using the following methods:

    • Keyboard: Cmd/Ctrl+Shift+Backspace
    • Mouse: Right-click the node icon > Delete
    • If you delete a node, it goes to the trash.

    If you delete a node that is referenced one or more times in the graph, the node goes to the trash and the references will have a little trash icon next to them.

    If you want the node and all references deleted, use the command Hard delete including references

    If deleting the node was a mistake, you can click on the trash icon and resurrect the node through one of the references.

    If you delete a reference, it goes to the trash and the node it referred to and other references will still exist and not be trashed.

    Related docs:

  • How do I get the permalink to a node?

    Bookmarking the URL in your browser of the form https://app.tana.inc?wsid=XXX (note the wsid) will break as it is a temporary ID for your window state.

    To grab the permalink to a node, use the following ways:

    • Right clicking on a node > Copy link
    • using the options menu on the node > Copy link
    • running the command Copy link

    The link to a node never changes. They are URLs of the the format https://app.tana.inc?nodeid=XXX (note the nodeid)

    Related docs:

  • How do I remove the strikethrough on a node whose text is not formatted?

    It is likely the legacy implementation of the checkbox node styling. Cycle through the Cmd/Ctrl+Enter checkbox states to see if that removes it.

    Related docs:

  • How do I set up relationships between nodes?

    There are two main ways to create a connection between one node and another:

    References/inline references

    Use references or inline references to create an unstructured two-way connection between the nodes and the place you mention them in.

    The reference section shows you all unstructured mentions under "Referenced in..."

    Fields

    Fields and their field values create structured two-way connection between nodes. Structured in the sense that the connection is labeled via the name of the field.

    • Example: A book node has a field called Author, where you can enter a reference to any person. The relationship between the book and the person is that they are the Author.

    Fields offer a variety of ways to create structured connections:

    • Create a Plain field and copy/paste or @-mention any node into it
    • Create an Options field where you can choose from a list of your choice
    • Create a Supertag from Options field where you can choose from a list of all nodes tagged a chosen supertag.

    Fields show up in the Reference section as "Appears as [field name] in..."

    This screenshot demonstrates how the different connections show up in the Reference section of a node:

    Related docs:

  • What are all the ways I can copy data out of Tana?

    Basic copy-paste

    Copy-pasting content is the fastest way of getting data out of Tana.

    Select the content you want to copy, then hit Cmd/Ctrl+C. To paste, Cmd/Ctrl+V either in Tana (will create references) or elsewhere.

    More copy-paste options

    Via the command line (Cmd/Ctrl+K) there are various flavors of copy available to you.

    Copy full content to clipboard

    Copies the selected content in plain text format

    Copy as Tana Paste

    Copies the selected content in Tana Paste format

    Copy as plain markdown

    Copies the selected content in plain markdown format

    Other ways to get content out

    Export plain HTML

    Renders a HTML page of the selected content that you can copy the HTML of, or save as a HTML file.

    Export JSON

    To learn more about this, read here.

    Thanks to community member Michael Sklar for the FAQ idea!

    Related docs:

  • What does it mean when the yellow message "editing in X places" pops up?

    The "Editing in X places" usually pops up for a moment when you are editing a node that is referenced in multiple places. It's a reminder that the changes you're making here reflects on X amount of other nodes in the graph.

    To see all the other places this node is referenced, zoom into it and go to the Reference section at the bottom of the page. Here you'll find all the places in the graph where a reference of this node appears.

    Related docs:

  • What is a Reference in Tana?

    A reference in Tana is a mirror copy of a node. It's a node that lives in many places all at once. If you edit one of them, the change reflects in all copies, everywhere.

    References are handy because it makes digital objects work a bit more like reality.

    Example:

    Spinach doesn't only belong in your pantry, it also belongs as an ingredient in your quiche #recipe, an item at a local #vendor, or as a source of iron #nutrient.

    What's really helpful here is that all references to Spinach refer to the same node, so the node Spinach becomes an index for all things spinach in your life, whether it be in recipes, found in shops, or a nutrient source. As you encounter spinach more in your life, and connect it to more things in your graph, your knowledge about spinach will just keep on growing.

    Just like knowledge does in real life.

    For more on nodes vs. references, go here.

    Related docs:

  • What is the difference between the Owner and a Parent of a node?

    The Owner is the node's home (where it was created). A node has only one owner, but can have many parents.

    PARENT / GRANDPARENT search operators are used to refer to one and two levels up in the outline, respectively

    Source of FAQ: Tana Community Resource Hub

    Related docs:

  • When I check a checkbox node, it disappears. Where does it go?

    This is likely because you have "Show completed items" unchecked.

    Go to your Settings and check the Show completed items setting.

    Related docs:

  • Where do deleted/trashed nodes go? Does the trash get emptied?

    When you delete something, they go to Trash.

    You can access Trash via the command Open trash

    To empty trash, use the command Empty trash for workspace [current workspace]

    It may take a couple of times of running empty trash to get all nodes out.

    Related docs:

  • Why are line breaks not supported in Tana?

    Tana's speed is reliant on each node being a small packet of information. Larger nodes are slower to edit, slower to index, slower to update, and so on. Line breaks would encourage longer entries of information, and would break many other situations where the contents of a node needs to be rendered as one line, such as inline references, option values, title expressions just to name a few.

    We do recognize that some want to store small pieces of information under one node, like a poem or quote. We are continuing to do research to explore ways to solve this, and also to solve for other issues related to long-form writing. If you would like to contribute your thoughts on this, please visit ideas.tana.inc and submit your thoughts under an existing or new post there.

    Related docs: