Common Ink
All docs

Writing notes

A note is a markdown file in your workspace. This page covers titles and folders, links, mentions, tags, the / menu, files, Trash, tabs, Vim mode, and settings.

Titles and folders

A note's title is the text of its first # heading. A note with no heading takes its title from its first line of words, skipping a line that is only a web address. A note with no words shows as "Untitled".

To make a note, press New note on the left rail, or run New note from the command palette (mod+shift+p, where mod is ⌘ on a Mac and Ctrl elsewhere). If you close a new note without typing anything, the app discards it.

Every note is in one folder. A new note with no folder in front goes to your Unsorted, in your Private, which only you see. All notes, the first row of the folder tree, lists every note you can see. An editor can create, rename, and move folders. An admin can delete a folder once it is empty.

Folders are described in Settings, under Folders, which the command Manage folders opens: every folder as a tree, Unsorted first as in the sidebar and the rest in name order, each folder inside another indented under it, with how many notes are in it and the folders inside it, and a description that says what goes in it. Show in Settings in a folder's right-click menu in the sidebar opens it at that folder's row. Whoever can edit a folder writes the description there by clicking it, and renames, moves and makes folders there as Settings' Tags does tags: double-click a name, press F2 or click its pencil to rename it; drag a folder by its name onto another, or use Move to… in its right-click menu, to move it; and New folder, or New folder inside in a folder's menu, makes one. Agents read the description to choose where to file a note. Rest on a folder in the sidebar, or on one in the breadcrumbs above a note, to see its card: how many notes are in it and what it is for.

Type [[ to list your notes by title, then pick one. The app stores the link by the note's id, as [[k3j5h8d9f0a1]], and shows the note's current title. Renaming or moving the target changes nothing in the notes that link to it.

To give a link its own text, type | after the title and then the text. The link is stored as [[id|display text]].

Click a link to open its note, or mod-click to open it in a tab behind. A link to a note that doesn't exist, or that you can't see, reads as unavailable. The inspector's Backlinks panel lists the notes that link to the one in front.

A markdown link, [words](address), an address in < >, and an address written on its own are drawn as links. Click one to follow it. While the cursor is on it, which shows it as written, mod-click it instead. An address in Common Ink starts with one /, such as [Plugins](/plugins) or /note/…, and goes there in the same tab, or in a new tab with mod-click. A full address on Common Ink's own site does the same. A web address, one that starts www. without https:// too, or a mailto: link opens in a new tab. Any other address stays text.

Mentions

Type @ to list people, agents, days, notes, uploads and events: alone, it shows a few of each, and typing narrows them. Every time a repeating event is on shares one row, which says how many more times there are. While the list shows more than one kind, each kind shows its first five rows, so one kind never fills the list. The Show 7 more row under a kind lists all of it, each on its own row: reach it with the arrow keys and press Enter, or click it. The people are the workspace's members and your own contacts. A member's mention is stored by their id, as [[person:k3j5h8d9f0a1]], and shows their current name in the theme color. An agent's is [[agent:k3j5h8d9f0a1]], and shows its name in the theme color too. Anyone else's is stored by name, as [[person:Sam Okafor]], and shows in gray. To show words of your own instead of the name, type | and the words, as a link does. A guest, or anyone opening the note from a share link, sees a member's mention as "Someone".

A mention gives nobody access to the note and notifies nobody. Click a mention to open the person's or the agent's page. A mention on a todo's line assigns the todo. See Todos.

Tags

Write #tag anywhere outside code, with no space after the #. A tag tags the whole note, wherever it is written. A todo has only the tags on its line and the ones over it, as Todos says. It needs something besides digits, so #12 is not a tag, and matching ignores case. A / puts one tag inside another: #project/alpha is inside #project, and #project counts and finds the notes of the tags inside it too. The sidebar lists your tags with their counts of notes, and each tag has a page of its notes, which you search as you search a folder. Click a tag in the sidebar or in a note's card to open its page, or ⌘-click (Ctrl-click) one in a note or on a todo. Rest on a tag anywhere to see its card: how many notes have it and what it is for.

Tags are managed in Settings, under Tags, which the command Manage tags opens: every tag as a tree, each tag inside another indented under it, with its description and how many notes have it. Show in Settings in a tag's right-click menu, in the sidebar or on the page of every tag, opens it at that tag's row, and Rename there starts renaming it. An admin or an editor works on it as on a file tree:

  • Click a description, or press Enter on a row, to write it. Enter or clicking away keeps it, Shift+Enter starts a new line, and Escape puts it back. Agents read it to choose their tags.
  • Double-click a tag's name, press F2, or click the pencil beside it to rename it. Renaming a tag renames the tags inside it too.
  • Drag a tag by its name onto another to move it inside that one, or onto the strip under the table to move it to the top. Move to… in its right-click menu does the same from the keyboard. Moving a tag renames it, as #alpha becomes #project/alpha.
  • New tag, or New tag inside in a tag's menu, makes a tag before any note has it, so you and your agents can use it.
  • Delete… in the right-click menu, or Delete or Backspace on the row, deletes a tag no note has, nor a tag inside it, such as one made ahead, with the tags inside it. Undo in the notice after brings it back with its description. A tag a note has has no Delete: it goes when no note has it, or rename it into another.

Before a rename changes any note you see how many will, and renaming to a tag you already have merges the two, keeping that tag's description. Notes you can't edit keep the old name. Each note's history shows the rename as your change, and Undo in the notice after puts every note back. Anyone who can see a note with the tag can read its description. A description stays with the tag's name, so the tag stays listed, with no notes, after no note has it.

The / menu

Type / at the start of a line or after a space to open the insert menu. Each item says what it makes, with a small picture of it beside the list. Keep typing to narrow it, and pick an item to put it in the note.

Item What it makes
Heading 1, 2, 3 A large, medium or small title
Bulleted list, Numbered list, Todo list A list, with a dot, a number or a box to check before each item
Table Rows and columns, typed into cell by cell
Code block Code in a fixed-width font, drawn in its language's colors
Quote, Divider Words set apart as a quotation, or a line across the note
Timer A countdown that runs the same for everyone reading the note
Stopwatch A stopwatch whose time is kept in the note
Kanban board Columns of cards to drag from one to another
Form Questions that members answer, with the answers kept in the note
HTML A block of HTML that runs in a frame shut off from the app
Search results The notes a search finds, listed in the note and kept up to date
Drawing Shapes, arrows and words drawn by hand in Excalidraw
Upload an image, Upload a video, Upload a recording A picture, a video or a recording you pick from your computer, shown in the note
Upload a file Any file you pick from your computer. A picture, a video or a recording shows in the note, and anything else as a card
Insert an upload A file already uploaded to the workspace

To mention a contact or reference an event, type @ and its name. See Calendar and contacts.

Typing :: opens the same menu with the embeds alone, from the timer down, so ::kan and Enter makes a kanban board.

An embed with settings has an options button in its card, for a timer's length or a board's column colors. Dragging a card on a kanban board moves its lines in the note. Click a card's words to type in it on the board, where #, @ and [[ open the same lists as in the note.

An HTML embed can't read the app, your session, or other notes, and it reaches only the sites an admin lists. The setting html.run decides when one runs. With automatically it runs as soon as it is on screen. With ask first it shows a Run button. A page opened from a share link always asks first.

Some markdown is drawn in place without the menu:

  • A table is drawn as a table. Type in its cells, where #, @ and [[ offer tags, people, dates and notes as they do in the note, and right-click a cell to add or delete rows and columns.
  • LaTeX between $ signs, such as $e^{i\pi} + 1 = 0$, is drawn as math. $$ on lines of its own makes a display formula.
  • A fenced code block is drawn in its language's colors, with Copy and a wrap toggle. One tagged mermaid is drawn as a diagram, and the text stays in the note to edit. A flowchart, a stateDiagram-v2 and a sequenceDiagram are among the kinds. A diagram that can't be read shows the error and its text, and the rest of the note is drawn as usual.
flowchart LR
  A --> B
  • A YouTube address, or the address of a post on X or Bluesky, alone on a line shows the video or post below it.

Lists

A list works as an outline. With the cursor on a bullet, a numbered item or a todo, each of these keys takes what is under it along, and the items a selection takes in go together:

  • Option+↑ and Option+↓ move it up or down among the items beside it.
  • Option+→ or Tab puts it under the item above it, one level in. The first item of a list stays where it is: it has nothing to go under.
  • Option+← or Shift+Tab brings it back out a level. An item that is under nothing stays where it is.
  • Cmd+Shift+. folds an item with something under it, and unfolds it.

A numbered list is numbered 1, 2, 3 again after each move, from the number it starts at. A list written with the same number on every item, such as 1. on each, keeps that number, and an item that joins it takes it too. Off a Mac, use Alt for Option, and add Shift to Alt+← and Alt+→, which go back and forward. Anywhere else in a note, Option+← and Option+→ move the cursor by words as usual. Change any of these keys in Settings, under Keyboard shortcuts.

Files

Paste or drop a file into a note to upload it. A picture, a video, or a recording shows in the note. Any other file on a line of its own shows as a card with its name, size, and Download, and among words as a chip. A file can be up to 25 GB.

A drawing is drawn in Excalidraw, over the whole window: press Edit drawing on it, draw, and press Save. The note shows it as a picture, sized with the handle on its right edge as a picture is. Each save keeps the drawing as a new file, so undo in the note brings back the drawing before. The file is an .excalidraw file that Excalidraw opens, and an agent can read it and draw one too.

A file you upload goes in your Private, yours alone, until you put it in a note in a shared folder, which moves it into the note's folder. Then whoever can see that folder sees the file. In a note in your Private it stays where it is. The Uploads page lists every file you can see.

Archive and Trash

Archive keeps a note and its links, and leaves it out of folder lists, search, and the dashboard until a query asks for is:archived. Its open todos stay on your lists, marked as being in an archived note, and the notice says how many, with Backlog them to put them off for some day. Set Todos in archived notes to Hide to leave them off your lists, or to Move to backlog to do that every time you archive; one Undo then takes back both. Unarchive brings it back.

Move to Trash keeps a note in Trash for 30 days, where you can read it but not change it. Restore puts it back in its folder, or in Unsorted if that folder is gone. After 30 days the note and its history are removed. The member who made the note, or an admin, can Delete forever… sooner.

To act on several notes at once, select their cards in a folder's list, All notes included, or on a tag's page: Shift+↓ and Shift+↑ select the next or previous card too, and Shift-click selects every card from the last one you selected. A card's E, its Archive button and its menu then act on every card selected, and so do Archive, Move to… and Move to Trash above the list. Escape clears the selection. Trash, Uploads and the Todos page select their rows the same way, and there Cmd-click (Ctrl-click off a Mac) selects a row or unselects it too.

Whatever you do to a list's rows, Cmd+Z undoes while the list has the keyboard, and Cmd+Shift+Z does it again: archiving, moving, trashing and restoring notes and files, and checking off todos, wherever you did it. The notice that says what was done has Undo too.

Import and export

Settings → Account → Import, or Import notes from the command palette, brings in an export from another app. Choose the file, and Common Ink tells which app it came from and shows what it holds before anything is written: how many notes, folders, files, links and todos, what can't be carried over, and what will be left out and why.

From Choose
Obsidian Your vault's folder, zipped
Notion The zip from Export, as Markdown & CSV, with subpages
Evernote An .enex file, or a zip of several, one for each notebook
Google Keep The zip from Google Takeout with Keep ticked
Bear A .bear2bk backup
Logseq Your graph's folder, zipped
Roam The JSON from Export All, or its zip
Markdown A folder of Markdown, zipped
Common Ink An export from Settings

Everything goes in one new folder named for the app and the day, keeping its own folders inside it. Notes keep their dates, tags and todos, files become uploads, and links between the notes are links. A link to a note the file doesn't hold is kept as its words. Anything in a note that would run, such as an HTML embed, stays as words. A Common Ink export's pictures and files come as they were, and the preview offers to keep its other embeds, such as boards and timers: tick it only for an export you made or trust, since anyone can make a file that looks like one. For a day after an import, Remove beside it in Settings takes it out again, or ink import-remove. Imports your agents ran are listed there too, each saying who ran it, and nobody else sees yours or theirs. Notes you changed since stay, with the files they show.

Settings → Account → Export, or Export notes from the command palette, downloads a copy of every note and file you can see. As it comes it is a copy to keep and to bring back: notes hold links by id. Tick For other apps for a copy Obsidian, GitHub or any Markdown app can read, with links and files as relative paths.

Tabs and splits

A single click opens a note in a preview tab, shown in italics, which the next single click replaces. To keep a tab, double-click it, edit the note, or choose Keep tab open from the tab's menu.

In a folder's list, All notes, a search's results or a tag's page, click anywhere on a note's card to open the note there, with the cursor in it. Cmd-click (Ctrl-click off a Mac) or a middle click opens it in a tab behind the list, and Option-click (Alt-click off a Mac) opens it to the side. A link, a tag, a date, a mention, an embed such as a video, and Archive and the menu in the card's corner keep their own click, and a click on a picture opens the note. With the keyboard on a card, Enter opens it, Cmd+Enter opens it behind, Shift+Enter or Option+Enter opens it to the side and goes there, and Shift+Space opens it to the side and stays on the list.

To split the editor, choose Split right or Split down from a tab's menu, or drag a tab to the edge of a group. mod+. fills the window with the tab in front, and pressing it again puts everything back.

To open something to the side, as VS Code does, Option-click it in the sidebar (Alt-click on Windows and Linux): a favorite, a folder, a tag, or a page's link such as Todos. In quick open, mod+enter opens the note, page or file you picked to the side. Either one goes to the group beside the one you are in, or makes one when there is just one, and puts you there. On a phone, they open things as a click and Enter do.

Anything you can open drags the same way: a tab, a note's card, a folder in the sidebar, a tag, a page's link such as Todos, a crumb above a note, a note in the inspector's Backlinks panel, and any link to a note, folder, tag or page inside a page, such as a note on the Dashboard. Each tag opens in a tab of its own, so two tags can sit side by side. Drop it on the edge of a group to split it, on the middle to add a tab, or on the tab bar to put the tab where you let go. Today drops the day's note. New note makes a note where you drop it, in the folder you're looking at, as clicking it does.

Vim mode

Vim mode is off until you turn it on, on the Plugins page or with "vim.enabled": true in your settings. It gives every note's editor vim's modes, motions, and operators, and gd follows the link under the cursor, or opens the mention, the file or the reference to a record under it as a click does. On a link to an address in Common Ink, such as [Plugins](/plugins), gd goes there in the same tab. On a web address, one that starts www. too, a link to one, or a reference link such as [words][label] whose [label]: address is in the note, gd opens the site in a new tab. Alt+Enter follows a markdown link or an address the same way, with vim or without. With Vim mode on, to keep gd and Alt+Enter to what is in Common Ink, turn off gd and Alt+Enter open links to other sites in Settings, under Vim mode, or write "vim.gdOpensOtherSites": false in your settings. A link to an address in Common Ink still works then.

Outside a note's text, wherever you are not typing, vim's keys move through the app:

Keys What they do
ctrl+o, ctrl+i Go back and forward through the places you have been, across tabs. A list you go back to has the row you left selected again
j, k, gg, G, ctrl+d, ctrl+u Move through the rows of a list
enter, l or gd Open the selected row
h Collapse the selected row, or go to its parent
za Expand or collapse the selected row
dd Archive the selected note in a list of notes, or abandon the selected todo on the Todos page, or open an abandoned one again
V Select rows from the selected one as you move, or stop
u, ctrl+r Undo what was last done to a list's rows, and redo it
/, then escape Go to the search box, and back to the list
ctrl+w, then h, j, k, or l Go to the sidebar, editor group, or inspector on that side
gt, gT Go to the next or previous tab

Settings

Open Settings from the workspace menu, from the logo at the top of the left rail, or run Go to Settings from the command palette. Settings are JSON. Go to Settings (JSON), or Open settings (JSON) in Settings, opens the JSON in a tab, where you edit it as you edit a note, with Vim mode and typewriter mode if they are on. It isn't a note: it isn't in your folders, search, or exports, and only you see it. Open agents file, beside it, opens the workspace's agents file the same way. Only the values you change from a default are written, and they follow you to every browser. How much the workspace's files take, and its export, are in Settings under Account.

{
  "vim.enabled": true,
  "html.run": "ask first",
  "daily.folder": "Journal"
}

A value a setting doesn't allow is flagged, and its default is used. A key that no setting has is flagged and does nothing. JSON that can't be read isn't saved until you fix it. Agents can't read or change your settings.