/drafts-tana-action-v2

Drafts Actions for exporting to Tana using the v2 Input API

Primary LanguageJavaScript

Drafts Action for Tana's V2 API

https://tana.inc/docs/input-api

The Tana Input API v2 adds functionality for saving more types of data and for specifying where data should be saved to.

This action allows the user to specify where in the Tana Workspace a new node should be placed. Additionally, it suports specifying a hierarchy of content nodes; one of the challenges in converting Markdown documents into Tana, because it is a hierarchical node-based system that does not support Markdown at all, is that you lose information about the document structure. Additionally, because Tana does not support newlines in any node, the exported drafts frequently look terrible if "squished" into a single Tana node.

Installing

TBD This is not yet published to the Drafts Directory.

Actions

Add to Tana Node

When run, the user is presented with a Prompt allowing them to select the node they wish to export the draft into; this node will be the parent of their new node.

If the user cancels the Prompt, the action will exit; if the user proceeds but does not select a node, the action will fall back to using their configured default node. If they don't have one configured (PEBKAC) it will use the INBOX.

Add to Tana

When run, the action will perform as above but without the logic of selecting from a list of parent nodes.

Saving

Given the API's support for exporting into a node hierarchy, this action permits the user to configure this.

The supported save modes allow the draft being exported to be saved as one node (title + body), a parent and one child (title and body), or a parent and many children (title and parsed body). It is easy to add more save modes, given access to a robust Markdown parser in the action (which it does not have).

For the modes that result in using the draft's title alone, this action uses the displayTitle attribute.

Configuring

This Action reuses a feature of the Obsidian action group, which uses Drafts Template Tags for configuring the action. This action uses Mustache template tags, because they support inline comments which allow these configurations to be documented.

Template Tags:

[[tanaDestinationNodes]]

A markdown list of nodes, with each list item containing comma-separated (identifier, nodeID) pairs. These will be used to drive a Prompt to select the destination node during action execution.

example:

- My favorite node, ghu1LlEXIN1u
- My other favorite, ghu1LlEXIN22

The identifier can be any string the user wants to see in the selection prompt.

At runtime, the selection is optional, and opting to not select a node will send the content to whatever the user has configured as their default.

In order to acquire these IDs, a user needs to use the Tana app and inspect the nodes they want to use. The Tana API docs go over this in detail.

[[tanaDefaultNode]]

The default node to send to: INBOX, LIBRARY, SCHEMA, or any Tana node's ID.

example:

INBOX

[[tanaSaveMode]]

The user can opt to send the whole draft as a single node, or have it parsed into a parent node with children. The options are:

  • single
    • the whole draft as a single node
  • child
    • the first line as a parent node, and the rest as a child node
  • children
    • the first line as a parent node, and the rest of the draft split by newlines as child nodes

The Future

Given the Tana Input API v2 supports the use or creation of supertags and fields (which are just nodes, in Tana), a future iteration of this action could apply Drafts tags or other metadata to exported content, or with access to a good Markdown parser it could split up drafts in various ways to make multiple nodes.

The Input API

The payloads generated by this action are in the form of:

{
    targetNodeId: the selected destinationNode or default,
    nodes: [
        {
            name: draft.displayTitle or draft.content,
            children: [
                {
                    name: ...
                }
            ]
        }
    ]
}

There are some good resources out there for anyone interested:

Screenshots

ScreenShot 2024-03-08 at 14 58 00@2x ScreenShot 2024-03-08 at 14 57 35@2x

Example: using "children" save mode

Source draft:

ScreenShot 2024-03-08 at 15 09 00@2x

Destination nodes in Tana

ScreenShot 2024-03-08 at 15 08 50@2x

Single-node Tana (behavior of the existing v1 action)

ScreenShot 2024-03-08 at 15 12 15@2x