How Twig behaves

What the app does with your pages, your files and your account: the screens, sync and backups, the plans, files, notifications, sharing and publishing, and assistants.

Writing

Tables

A table is a block whose text is a Markdown pipe table: a row of headers, a rule of dashes under it, then a row per line. /table writes one with three columns and two rows, the first header selected to rename. The outline draws it as a table, and the block’s text stays the table, so Markdown, sync, a shared page, your site, Save as HTML and the API carry it as written.

• Click or tap a table to edit it: the block opens as its text. While the caret is in the table a bar under it adds a row or a column, deletes the row or the column the caret is in, and steps the column through left, center, right and no alignment. Tab is still the outline’s, indenting the block; move between cells with the arrow keys.
• A wide table scrolls sideways in its own box, its edges fading while there is more, and never widens the page. A long cell wraps.
• On a shared page, your site, a docs layout and in Save as HTML a table is a table, named by the same first line. In a one-line row (a backlink, a task, a search hit) and to an assistant reading through the API it is its Markdown. A table inside a quote stays its Markdown on a shared page and a plain site, which show a quote as it is written.
• A block from the Table plugin, {{table}} with its rows as the blocks under it, is drawn as a table too, the first row its headers, and the rows stay blocks under it. Editing it, the bar under it has Turn into a pipe table: the rows become the block’s own lines and the blocks under it go, one step for Undo. It is there when every row is one line with nothing under it, so nothing is lost.
• A heading or a task above a table stays a heading or a task; only words become a caption.

Maps

/map writes {{map }} for an address or a point: {{map 1 Main St, Arlington, WA}}, {{map 47.6,-122.3}}, or {{map 47.6,-122.3,16}} to come closer. A place page shows the same map under its fields at its coordinates when it has them; with only an address, Show on map looks it up and draws it, and a place found once is drawn at once after that. A block from the Map plugin is already one of these.

• Twig’s map is OpenStreetMap’s tiles, from tile.openstreetmap.org, with a dot in the accent. Drag to move it; the buttons zoom.
• An address goes to Twig’s server, which asks the US Census geocoder and then nominatim.openstreetmap.org. On Cloud Sync it keeps the address and the answer for your account alone, for up to thirty days or until the block or page the map is in is deleted; otherwise it keeps nothing. Without a server your browser asks nominatim.openstreetmap.org itself. Coordinates are drawn as they are, with nothing asked.
• A map is left out of a one-line row, and a shared page or your site shows none.

750 words

Three pages a day, after 750words.com: one plain surface for writing, in the rail below the places (first under More on a phone), at #/750, and on ⌘⇧7. Close, Escape or ⌘⇧7 again goes back to Today.

After you write

Once the day has words, the foot has After: the day read back, on a page over the words, until Words or Escape turns back to them. On a day with nothing yet it is Yesterday’s, when yesterday has words. It opens only when pressed, and on a phone the foot steps aside while the keyboard is up, so it is never there while you type.

Keyboard

A link, a search hit or a list row that opens another screen leaves the keyboard at the top of the new one, so the next Tab starts from its head.

Keycaps are set in the mono, and name the modifier the way the keyboard does: ⌘ on a Mac and Ctrl elsewhere, ⇧ for Shift, ⌥ for Alt.

Pages

• A tab shows only while it holds something, with its count in the mono. All counts pages, the same number as beside the title and in the sidebar; an image it lists is counted under Files.
• The tabs take one row that never scrolls sideways: as many as fit, in order, the chosen one always among them, and More for the rest, with their counts. All and Loose ends stay in the row at any width, so on the narrowest phone, or at 200%, the row wraps rather than put them under More. The arrow keys move along the row; Tab reaches More.
• The address keeps the tab, #/pages/books, so a link opens it whether it sits in the row or under More. A bare #/pages, or one naming a tab that holds nothing, opens on the tab last chosen on this device while that still holds something; otherwise on the first of People, Places, Books and Websites that does, and on All only when none does.
• + New makes the tab’s kind in one press: a person on People, a page on All. ▾ beside it offers every kind: a page, a whiteboard, then each type. What it makes is always a new page, never an Untitled one reopened, and it opens.
• Removing a page’s last link deletes it by itself when it is empty, so Nothing links here holds pages from New, an import or another device. A search that leaves both Loose ends lists empty says so once.
• Renaming a page is its title: type the new name and press Enter or leave the field, and every [[link]], #tag, @mention and tags:: line that named it is rewritten. A change of case alone is a rename like any other. A name another page already has, or answers to as an alias, stays in the field, and a note under it says which page holds it, what it is and how often it is mentioned, with Merge into it, Keep editing and Cancel (Esc), which puts the old name back.
• Merge into it keeps the other page, its id with it, so its mentions keep finding it. This page’s blocks go to its end, or open it when it has nothing written; it takes this page’s type when this page has one and it is a tag or has none, and when both have a type, a plain Page included, the note asks which to keep; its empty fields fill from this page’s, the picture included; lists join (tags, aliases, a field that names pages); a field both pages hold, set differently, keeps the other page’s value, and this page’s is kept in one block at its end, Merged from “…”; links to this page’s name are rewritten to the other’s. Then this page is deleted and the other opens. This page’s name stays on the other as an alias, so a link written elsewhere before the merge, a bookmark or Back still opens it; not a name the app gives itself (Untitled, New artist, a day’s 750 words page, Recovered blocks) or one another page already answers to. One undo puts both back. A day, a board or a PDF is never merged.
• On a phone + New floats above the tab bar with its ▾ beside it, More and the ▾ come up as sheets, and a row of a collection is two lines: the name, then what it holds.
• Once a page has something written on it, the line under its title adds its words and minutes to read, and On this page, beside the page or the day, counts its sentences, paragraphs and characters too. A page or a day with nothing written shows no counts at all.
• The counts leave out property lines, SCHEDULED and DEADLINE lines below a block’s first line, and empty blocks. A paragraph is a block with writing in it. A sentence ends at . ! ? or … before a space or the end of a line, and a line with no stop is one sentence, so a list of fragments counts one each; an abbreviation such as e.g. counts as an end too. Characters count spaces, as a word processor’s “characters with spaces” does; most emoji count once, and one built of several, such as a flag, counts as its parts. A code block counts as words and characters, but not as sentences or a paragraph, so a page of code shows no sentences rather than none of them.

The Graph

• Each list shows only when it has something in it, and its five first. A day is never in a list, and a whiteboard is in neither the lists nor the Map, though its notes count as links.
• The Map draws up to 120 pages, the most linked first, once it is opened, and the same pages and links in the same places each time. The busiest pages are named, and the one chosen and its neighbours. The map as a list, under it, says the same in words: each page and what it links with, pages first and the days as a count.
• The lists and the Map are worked out again half a second after the last change, and at midnight, so writing in the side pane with the Graph open never waits on them.

Types and properties

• A location’s kind is one of Business, Government, Non-profit, Residence, School, Medical, Park, City (a city, a town or a village) or Other.
• Actor, Director, Producer and Writer are a person’s roles, not types of their own: one person who acts and directs is one page, a Person whose Roles say both (roles:: Actor, Director). The page’s menu, under Type…, has each after Person, on or off; picking one on another kind of page makes it a person first. The line under the title says the roles in place of Person, and People filters by them.
• Band is an artist that is a band: an Artist’s Person or band says which (form:: Band), on its head as two buttons and in Type… as Band after Artist. An artist page that never said is a band when what it is names a group (“English rock band”, “Duo”) or it lists members, as it always was; nothing about it is rewritten. A band’s picture is a tile, a person’s a circle, and the line under the title says Band.
• On Cloud Sync a website keeps a copy of what its url shows: the first device to open the page asks, and Twig’s server fetches it once, so the site sees the server and not you. Its words (as Markdown) and its picture are kept as your files and counted in your room; its description fills About while About is empty. Take a new copy keeps another, and the old one’s files go thirty days after nothing names them. The card over a link to a website shows the kept picture and, on Cloud Sync, what the site says about itself now: its title and description, asked by Twig’s server once a day at most.
• Add an alias and Add tags, in the page’s menu, start the first of each. Commas part aliases; a name with a comma of its own goes in double quotes, alias:: "Washington, D.C.", DC.
• In a file a page’s properties are the lines before the first bullet; a page with none whose first block opens with a property gets title:: with its own name.
• A code block in a file stays one block with its indentation, and a line in it that reads like a bullet or a property (- item, key:: value) stays code.
• Pages from before 0.43 moved theirs onto the page once: at launch on a device not signed in, after the next sync on one that is.

A typed page’s head

The head of a typed page says first what the page is for. Under the title, set biggest, is the one fact that says it; then two that matter next; then its About as a paragraph; then the line that counts the page; then the rest of its facts, each a quiet label beside its value (in two columns, read down each, once a desktop has six or more). The picture stands on the right (a face in a circle, a cover, a site’s icon or a logo on a white tile, a place’s photo, an event’s or a film’s picture shown whole, an album’s sleeve as a square), and a page without one has its type’s tile there instead: a person’s or an organization’s initials, a book’s title on its cover, a website’s first letter, an event’s day on a calendar leaf, a place’s ⌖, an artist’s initials, an album’s title on a square, a film’s or a show’s title on a card, a track’s ♪. A track with no picture of its own shows its album’s.

• An email, a phone, an address or a date with its own word (“Born Oct 21, 1929”, “by”, “at”) shows no label; a screen reader still hears it. On a phone the two after the title are rows of their own, with no labels either, and so are a film’s year and its director (a show’s years and its maker), which a desktop sets on one line with a dot between.
• An organization’s people are the people whose Works at names it, by its name or an alias: three by name, and how many more, which opens the page sidebar on its Backlinks, where each is listed. They are read off their pages, so they are changed there; the card over a link to it says how many. An artist’s albums (the albums whose Artist names it, oldest first) and an album’s tracks (the tracks whose Album names it, in their numbers’ order) are read the same way; an album’s card says its own Tracks when that is a number (12 tracks), and the track pages only when it is not.
• A field with nothing in it is not a row but an invitation at the head’s foot: “+ Email” opens the email where it belongs, for typing, the fact under the title and the two after it first. Enrich leads them, and Add a field… (also in the page’s menu) has the rest of the fields Enrich brings. A book’s status and rating, a place’s kind and a film’s or a show’s stars are always there: unset, they are their own invitation.
• With a mouse, ✎ shows when its row is pointed at or reached with Tab; under a finger it is always at the row’s end. A press on any value that is not a link edits it in place, and Return or Esc gives the keyboard back to it.
• The page’s ••• sits at the end of the trail back, the page sidebar’s toggle after it, at every width, and they come after the trail with Tab.

Enrich

On Cloud Sync a typed page has Enrich at the foot of its head, and nothing is fetched until you press it. It looks up the page’s name (a website’s url; an album’s or a track’s with its artist, when the page names one, as a song’s title alone is a hundred songs) and lists what that could be, each with a line and, where the source has one, a small picture (a website’s one row has none). Use fills the fields the page has empty, or every one with Replace what’s filled ticked, all in one step: the notice’s Undo takes it all back, and closing the picker before an answer comes drops it. Twig’s server does the asking, so the source sees the server and not you, and it keeps the picture (a cover, a photo, a logo, a site’s icon) as one of your files, counted in your room and shown beside the title and on the card over a link to the page. What a source says is kept on the server for your account alone, for thirty days or until the page is deleted, so the same thing asked again is read from there; a read missing a part (the article’s opening, the geocoder’s answer) is kept an hour, and a website’s head a day, as its card’s is.

• A field that names pages, an event’s At, an organization’s Founded by, a band’s members, an album’s artist or a film’s cast, links them as typing the names would, and makes any that do not exist yet; a cast or a band names six at most.
• A page Enrich makes is the kind its field names: a film’s or a show’s cast are people with the Actor role, its director a Director, its writers and a show’s makers Writers, its producers Producers (one person in two of those is one page with both); a band’s members are artists who are people; an album’s artist is an artist, a place an event is at a location. A page you already have on this device, found by its name in any case or by an alias, is never retyped or changed. One of yours still coming over from another device folds into the page Enrich made when it arrives: yours is the page kept, and keeps its type and fields when it has a type, or takes the type and role Enrich gave when it has none. It is all one step: Undo takes back the fields and the pages made with them, and never a page of yours.
• Status and rating (a film’s and a show’s stars included: a source’s score is never written), a place’s Kind once it has one, the page’s type, its aliases and its tags stay as you set them, Replace or not.
• A field Enrich added shows on the head once it holds something; while empty, it is in Add a field…, at the head’s foot and in the page’s menu, on any plan, unless it is the fact under the title or one of the two after it (a person’s occupation, an organization’s base and founding, a place’s country), which are a “+” of their own. A type’s own fields (a person’s email, phone, birthday, work, home and people; a location’s address; a book’s author; a website’s URL and About; an organization’s site and address; an event’s date, place, people and URL) are each a “+” invitation there too. The card over a link shows the head in miniature: the picture, the fact under the title and the two after it, nothing from the facts.
• A date shows with its year, on the head and on the card. A date field takes a whole day: a birthday or an event’s date the source knows only to the year or the month is left empty (and an event’s end with it), while a date of death, a founding or an end is written as far as it is known (1976, 1976-04).
• MusicBrainz is asked once a second for everyone, as it asks; a search it cannot answer in time is asked of Wikidata instead, by the title alone, and what is picked from there is read from Wikidata. A track found by its title alone lists the song before its covers: of the ones that match as well, the one most releases carry.
• A track’s or an album’s length reads m:ss, or h:mm:ss from an hour (6:24, 1:12:05); a film’s runtime is said in words, 2 h 27 min or 48 min (its shortest cut). A year a film came out is its first, wherever that was.
• What a search lists comes in the source’s order, but for one named exactly what was asked, which comes first: in any case, with its punctuation (B.o.B is not Bob); an album’s or a track’s by its title, not the artist after the dash.
• The picture is image:: with its file id, as a website’s copy is; a page that has one, or an image:: of its own, keeps it unless Replace what’s filled is ticked. When the picture does not come, the fields are filled all the same and a notice of its own says so, with Try again. The page keeps where it would come from, picture-missed:: (the id Use read), and its stand-in on the head is a button until it comes, Add the picture: it asks for the picture alone, and never writes over one set since. Changing the page’s type ends the wait; an id the source will never take (one written by hand, say) ends it too, and Enrich opens to pick again.

Typed links

[[type:: Name, key:: value, +action]] in a block makes the page it names a typed one. It is read when the block is left (a blur, Enter, going elsewhere), never while you type, and all it does is one undo step, which its notice offers back.

The first word

A type’s key or another word for it, in any case: movie, tvshow (tv-show, tv), album, track, artist, band (an artist that is a band), person, actor, director, producer and writer (a person in that role), book, website, organization (org), event, location (place). Any other word, and a tag, leave the link a plain one.

A page that is there

Found as a link finds it, by its name or an alias, in any case. A page with a type keeps it; one without takes the link’s, and keeps what is written on it. A day, a board or a PDF takes no type. A link whose whole inside is a page’s name already is a link to that page.

Fields

Each key is a field of the type by its key or label (rating, Works at), in any case; an event’s At is also location, place or venue, its With participants or people. A field takes the value only where the page has none: a value it has stays, and the notice says what was not written. A role adds to a person’s roles, and band sets Person or band only while the artist says neither. A key that is no field is kept as a property of the page; type, image, pdf and the like are Twig’s own, and left out.

Values

As typing them into the field would keep them. A field that names pages links each name, and a page it makes is the kind its field says (an album’s artist an artist, an event’s place a location, a film’s director a director), marked as Enrich marks the pages it makes; a page you have is never changed. A rating is 1 to 5 (4, 4 of 5), a date a day written 2026-09-30; one that is not is left out, with a note. A choice takes its option’s spelling.

Commas

Commas part the pieces, and a piece that is not key:: value or +action belongs to the value before it, so address:: 1 Main St, Springfield is one address and participants:: Hayley Williams, Paramore two people. A name with a comma, where a field names pages, goes in double quotes or a link, location:: "Portland, OR" or location:: [[Portland, OR]], as an alias does; a quote inside the quotes is doubled. The curly quotes a phone types, “…” and ‘…’, count as quotes, and a long dash a phone makes of a hyphen is a hyphen in a key, a type’s word or a date.

The rewrite

Each link applied reads [[Name]], the name as you typed it, so it reads and finds the page as any link does; a # or @ before it stays. A link that could not be applied yet (its page still coming over from an older version) keeps its words, and is applied when the block is left again. One taken back with Undo keeps its words too, and on this device stays as typed, +enrich and all, in any block, until something inside it is changed (for 90 days); another device applies it when its block is left there. To keep a link as plain text everywhere, take out its ::.

+enrich

Runs Enrich on the page once the link is applied, on Cloud Sync. It looks the page up as Enrich does; when the first answer has the page’s name (a website’s, the site its url names), it is used as Use uses it, filling only what is empty, in a step of its own that its notice’s Undo takes back; the link’s own notice’s Undo takes back both. Any other answer is yours to pick: the notice’s Open Enrich opens the page’s picker. Any other +word is left out, with a note.

Typing one

After [[, a type’s word, :: and a name, the list under the block offers the type’s fields not given yet (an event’s At as location), each with what it takes, then +enrich; after a comma it narrows to what you type. ↑ ↓ choose, Enter or Tab puts the key in, Esc closes it. A [[, @ or # typed in a value opens its own list.

Where it works

Any block and the 750 words, typed or pasted. An imported file keeps its words as they are, and makes no page of such a link’s inside; editing the block applies it. An assistant’s or a script’s write that holds one is refused, with the way to make that page (create_page), so every change it makes is one Settings lists and can put back.

Tasks

• A task’s day is its DEADLINE:, else its SCHEDULED:, else the first day it links to, and the row says which: due, starts or linked.
• A row names the page it is written on under its words, and a journal day short, in the page line (@Sep 23) and in the words alike, with the year only when it is another. On a phone the words take the row’s width, and the page and the day share the line under them.
• A tab shows only while it holds a task, with its open count. Tasks opens on the tab last chosen, or on the most urgent there is. The tabs are Pages’ row: whatever does not fit is under More, and the arrow keys move along the row.
• Checked off there, a task stays a moment, about two seconds, struck through, with an Undo that gives back the marker it had; with the keyboard on the row it stays until the keyboard moves on. Then it leaves, and its tab with it if it was the last. A finished task is not listed with the tasks to do on Tasks, Today, the Calendar, a page’s Backlinks or a tag’s Mentions: it stays, struck through, on the page it was written on, and on Done for the week it was finished in.
• Done, the last tab, shows while a task was finished this week, the week starting as Settings › Appearance › Week starts on says. For today and for the week it says how many tasks are done, what their estimate:: planned and what their spent:: says was spent, in whole minutes, and the three that ran furthest over their plan, from a minute over, each a link to its task. The week’s finished tasks follow, the one finished last first. A done task counts on the day it was last changed, in Settings’ time zone: renaming a page it links to changes it, and so do moving and indenting it; restoring a backup or importing files changes every task they bring in. Only its spent:: counts. The Calendar’s day list ends with the same line for the tasks finished that day.

Views

• A column is its name and a count over a hairline; an empty one is a dashed box that says what to do. A card sits on the panel: the words, then the date, the page it lives on and a Move menu. The date reads today, tomorrow, 3d over in amber, or Sep 24; a done card is struck through.
• On a phone a board’s columns are 280px and snap one at a time. Dragging works with a mouse; the Move menu works everywhere.

Calendar

Every dated block on a month: a SCHEDULED: or DEADLINE: date, or, for a task with neither, the first day it links to, as on Tasks. It is at #/calendar (#/calendar/202610 for another month), and /calendar in a block opens it. A page with something dated has its own beside Outline, with only that page’s blocks, nested ones too, and month arrows that stay on the page. An address of the old Calendar view plugin opens the same month here.

• The three colors are each theme’s own, and --ok and --late are the Calendar’s alone. The color is on the dot before a line’s words (over in its place when late), a phone’s dot, and the list’s due or starts, which reads overdue when late.
• Only a task still to do is ever late. The whole calendar holds no done or canceled task; a page’s own calendar keeps that page’s, in the plain color and struck through, and a canceled one has no checkbox. A note is never late: green ahead, amber about now, plain once it is past. A day a task only links to stays plain, as on Tasks, and a task scheduled and due takes its due day’s color on both its lines.
• Each line is the block’s own words as the outline shows them, less a link to the day it sits on and the tags in front of the words or after them (a tag inside the sentence stays, and a link to the day in front is passed over with them); its priority is a small box before them, A filled in amber. The words wrap to as many lines as the cell has for them, two at least, and are never cut short for a screen reader. What is still to do comes first, and on a page’s own calendar what is finished comes last, quieter and struck through; a day with two or more than its cell holds ends with +N more, which opens the day’s list. A day with something on it is a tile, today is ringed, and a day whose journal has something written in it has a small hollow ring under its number. A day’s name, read out, says what the colors and the ring say: how many are dated, overdue, soon and upcoming, and the entry; a screen reader names today on its own. A line is read with its color first (overdue, due soon, soon, upcoming), or done or canceled.
• Choosing a day lists it beside the month where the calendar is wide enough to keep its days about 140px across (a desktop window of 1440 or so), and under it elsewhere; where that list is out of sight, choosing a day (a tap, Enter or Today) brings it into view with the keyboard on the day’s name. It is like a list on Tasks, by the same rules as the lines: a checkbox, the words, due, starts or linked, the page as @Sep 29, and Move… to give it another date. A task checked off there stays a moment, struck through, with an Undo in the place of its due or starts, and then leaves. The day’s name over the list opens that day.
• Drag a line or a row onto a day to move it. A task dated only by a link gets a SCHEDULED: line. A move you can see says nothing; one that takes a block off the month on screen says where it went.
• The month is one stop for Tab: the arrows move a day or a week, Home and End go to the week’s first and last day, PageUp and PageDown a month, and Enter or Space lists the day.
• Where the calendar is under 840px wide (a phone, or an iPad held upright) the month is a grid of numbers with up to three dots a day, the late ones first, its list underneath.

Sketch

/sketch in a block makes a drawing. With Cloud Sync it opens Excalidraw over the page: a card on a desktop, the whole screen on a phone. Draw, then Save. Cancel, or Escape, leaves the block as it was, and asks first when something is unsaved; a tap outside the editor does nothing.

• A drawing is kept as a picture in its block, with the drawing itself inside the picture: {{sketch}}, the picture on the line after it, and sketch-scene:: naming it. The outline, a shared page, your site, Export and print all show the picture without loading the editor; in the dark theme the outline darkens it, as Excalidraw does.
• Edit drawing, above the picture, opens it again. Each save is a new picture, at most 2048 pixels on its longest side and 20 MB, the cap on any image; the one it replaces is let go as a removed attachment is. A save waits 15 seconds for the server; past that, or offline, the picture is kept on this device and goes up with the next sync. Cancel while it saves stops the save and leaves the drawing open.
• A drawing whose picture never reached the server (the device that drew it has not synced it) says so when you open it, with Start over: the editor opens empty on that block, the drawing you save takes the old picture’s place, and Cancel leaves the block as it was.
• The editor is fetched the first time a sketch is opened, never with the app, and kept for offline from then until the next update. Its faces come from Twig’s own address; Chinese and Japanese text in a drawing is set in the system’s face.
• Signed out or on Free, a sketch is freehand: a surface in the block for a finger, a pen or a mouse, its strokes kept in the block as sketch:: path data. Undo, Clear and a field that takes a stroke as a path (M10 10 L50 50) work from the keyboard.
• Sketch with Excalidraw, under Appearance in Settings, is on by default; off, new sketches on this device are freehand. Open in Excalidraw on a freehand sketch turns its strokes into a drawing when you save it, and never on its own.
• When the editor cannot be had: after an update, a tab left open offers Restart, once (if it still cannot open after that, it says so and the sketch stays as it was); offline before it was ever fetched, a new sketch is freehand and a drawing opens once you are back online. If the editor stops while you draw, the sketch stays as it was. Escape or Cancel closes any of these.
• The Sketch block plugin is part of Twig now: what it drew keeps its strokes and stays editable, and it is no longer on the Plugins screen.

Sidebar

Every page, a day’s included, has a sidebar with two tabs, Backlinks and Export. It opens from the button at the end of the row with the page’s title (on a day, after its arrows; on a zoomed block, at the end of its trail; on a phone, beside the page’s actions at the top), with ⌘⇧E (Ctrl+Shift+E) anywhere on a page, or with /sidebar in a block, which on a desktop or an iPad leaves you writing (on a phone the sheet takes the keyboard, as it always does). Beside the page it stays open or closed as you left it on this device, from page to page and after a restart; a phone always starts with it closed.

• From 1100px wide it is a column of its own, 320 to 360px, in the place of On this page, Sync and Storage, and the page keeps its width; narrower, it lies over the page’s right side, and a tap anywhere outside it puts it away. A panel opened from a link lies over it until that is closed.
• On a phone it is a sheet from the right edge over the dimmed page, with rows a finger can hit and a close at the top; the page behind is out of reach and Tab stays inside until it closes. Going anywhere closes it: a link or a row in it, or Back.
• It is a landmark named Page sidebar, its tabs a tab list that the arrows move along. Opened by its key, or as a phone’s sheet, it takes the keyboard; Esc or its close gives it back to the button.
• It took the place of the Backlinks widget and Export page plugins, and of Linked from under the page. Their old addresses, #/x/backlinks/<page> and #/x/export-page/<page>, open the page with the sidebar on the tab that does what the plugin did.

Sync

Otherwise the word opens Cloud backup. An edit made while a push is under way waits in the change log for the next one.

1. Sync installed plugins is a switch under Sync in Settings, off until you turn it on on that device, and it needs Cloud Sync: the list lives on the server. Signed out, the row says it needs sign-in; on Free, that it needs Cloud Sync; not yet connected, that it is waiting for the connection.
2. The device syncs its list when you change a plugin, at launch, when the switch goes on and when the connection comes back: it reads the server’s copy, merges, installs what it lacks, removes what went elsewhere, matches on and off, and writes the result back, merging again if another device wrote in between.
3. It merges plugin by plugin: each install, removal and switch carries when it happened, and the later wins. A plugin installed before the switch existed carries no time, so any recorded change wins over it.
4. A removal is remembered for 30 days, the newest 50 of them; a device offline for longer can bring a removed plugin back. The server keeps up to 100 plugins, and past that a device says so and stops writing.
5. Another account signing in on the device turns the switch off and starts its list over, and so does Delete local data, so its plugins being off does not reach the others.

Written on two devices

1. A block’s words changed on two devices before either heard of the other: neither overwrites the other.
2. The block keeps this device’s words and shows the other’s beneath them, in a dashed amber box, with when each was written.
3. Keep this, Keep the other, or Keep both, which makes the other version the next block. Each keeps the block where it is on this device: Keep the other only swaps the words. Nothing goes up, and nothing of the other version comes down, until one is picked; the one kept is written fresh, so it wins everywhere.
4. The sidebar counts these blocks and Cloud backup lists them. A block not in conflict takes the newer write whole, order and indentation included; only words are ever kept apart.

Plans

• Everything written while Free waits on the device in the change log, and goes up the day Cloud Sync is on.
• An account on the server’s own list is Cloud Sync for life, unless the office has set its plan by hand.

1. When Cloud Sync ends the account is Free, with 30 days of grace: the server keeps the graph read-only. A device can still bring it down, each snapshot up to 16 MB unpacked can be downloaded from Cloud backup as a copy Restore from a copy reads back, nothing new goes up, and shared links and a published site stay up.
2. Renew within the 30 days and everything carries on.
3. After them the server no longer syncs or serves the graph, and shared links and the site go down. On Cloud Sync again they stay paused until you put them back up, from the page’s menu or from Your site in Settings; words written since go up with them.
4. A lifetime refunded in full, or disputed, ends the same way; a partial refund leaves it. A link or a site can be taken down at any time, on any plan.

Cloud backup

• A snapshot is the whole graph as it stood. With Cloud Sync the server takes one a day on its own, and one whenever you choose Back up now.
• The daily ones are kept grandfather-father-son: the newest of each of the last 7 days, 4 weeks, 12 months and 2 years that have one. A day with none takes no place, and one snapshot can stand for its day, its week, its month and its year. Back up now, and the snapshot kept before a restore, stay 30 days.
• The screen shows the plan, with its renewal date or Lifetime, and how much of the 10 GB is used by the graph, the files and the snapshots together. Past 10 GB a new snapshot or file is refused and “Backups paused: storage full” says so; syncing never is.
• A graph over 16 MB unpacked is too large for a snapshot: none is taken, and “Backups paused: too large for a snapshot” says so. Syncing and Export a copy carry on.
• Choosing a snapshot asks in place. Restore puts the graph back as it was and deletes anything newer, first keeping what is there as a snapshot of its own, so a restore can be undone the same way. It needs the server, and refuses while this device has changes the server has not taken or a block written on two devices waits for a choice.
• The copy you keep yourself is Export a copy and Restore from a copy, on the same screen, and Import a zip or a folder, under Data in Settings.

Files

1. Drop or paste a file onto a block, type /Upload (or /Image for the photo library), or press Attach a file on the phone’s editing bar. A file dropped on the outline lands on the block under it; below the blocks, on the last one when it is empty, or else a new one.
2. The block keeps plain Markdown, ![name](/api/files/<id>) for a picture and [name](/api/files/<id>) for anything else, and draws each for what it is.
3. While a block is written, each file on a line of its own is one piece between its words, with Rename and Remove, so its link stays whole. Backspace beside it picks it, and a second removes it whole as an undo step of its own; Rename changes the name the block shows, as a step of its own, keeping the extension and never the address. A link typed in the middle of words stays words, and a file’s link the editing damaged is written whole again as the block is left.
4. With Cloud Sync the file goes to the server and counts toward the 10 GB. Signed out, on Free (the notice says uploading needs Cloud Sync), or while the server cannot take it, it is kept on this device and shows the same.

• A file that did not go up is tried again after 1, 5 and 15 minutes, then every hour; a reload starts again at a minute. One that arrives when the storage is full is kept here too, and the notice says so.
• Files reach other devices only through Cloud Sync. Until the device it was attached on uploads it, another shows its name and “On another device: waiting for it to sync”, and Delete local data loses any that have not gone up.
• Offline, a file opens from this device when it is kept here: every file this device uploaded, and every one it opened whole. Up to 500 MB is kept, the oldest going first. A video or a sound only played here is not kept, nor a file seen on someone’s shared page; without the network such a file shows its name and “Not on this device: opens when you’re online”. Signing out, or Delete local data, clears them.

Notifications

• It is the one thing Twig sends: no reminders, mentions or sync alerts. It needs Cloud Sync, because the server sends it from the graph it holds.
• Send a test sends one now to every place turned on, and says where it went.
• A change made after the digest time counts today as done. At 10:00, moving a noon digest to 09:00 skips today: the first comes tomorrow at 09:00.
• Flying west to where it is still the day before, after the day’s digest went out, the next morning there brings one as usual.
• To stop, turn off Push to this device on each device, and Send to ntfy. Signing out turns push off on that device; ntfy goes on until it is turned off.

Updates

• A new version downloaded brings up the update bar: a card on the raised surface, above the tab bar on a phone and at the bottom right on a desktop, and a polite live region that announces its first line.
• It lists what changed, newest first: “What’s new in 0.39.0”, or, when several versions have come out, “Twig 0.39.0 is ready · what’s new since 0.37.0”, with each version under its number. About five lines show, fewer on a short screen, and the rest scroll.
• Restart now loads the new version, and Later hides the bar until Twig next opens. Offline, or for a version without notes, it says only “Twig 0.39.0 is ready”, and the button is Restart. The version stamp at the foot of Settings opens the notes for the one running.
• A tab left open across an update keeps its screen. When a part it had not opened yet (After, the drawing editor, a PDF, a map) can no longer be fetched, that part offers Restart in its place, and the update bar comes up, after a Later too: “Twig was updated” until it knows the new version’s number. Twig never restarts on its own.
• Every Restart, and Try again on a screen that broke, saves what you typed first, saying Saving… meanwhile; words typed while it saves are saved too. If they cannot be saved, nothing reloads: the bar says your changes are not being saved, and the screen stays as it is.

Print and export

• A printed page is in the light scheme whatever the screen shows, in the writing face at 11pt on a 46rem measure, without the rail, the sidebar, the toolbars or the grain. A block is kept whole across a page break; an empty row does not print, and one holding only properties or a date is not empty. The page sidebar, its backlinks with it, does not print; a tag page’s mentions do.
• Printed from the app, the title runs along the top of every sheet, and the address, the date and the sheet number (3 / 5) along the foot, in the mono at 8pt, in Chrome and Edge; a browser without page margin boxes prints its own. Each block’s number stands in the margin, counted in reading order, so a printout can be talked about by number. Print or save as PDF, in the sidebar’s Export tab, is this same print.
• The sidebar’s Export tab writes a page’s Markdown as the backup does (its properties as key:: value lines at the top, then a - bullet per block with its children tabbed in), under YAML front matter: id, title, tags (the page’s own and every one on its blocks), created and edited, written so a colon or a quote cannot break them. Import passes front matter over, so a page saved this way and picked on its own comes back as that page, named by its file. Save as HTML is one file with its own plain styles: the title, a typed page’s head as the app shows it (every field it holds, a person’s email, phone, birthday and home and a place’s address included, which a shared page keeps back; and its picture, a track’s album’s sleeve too), the page’s other properties but a file’s id, and the outline as nested lists in the words the app shows, code in its own box, and a link that goes to the web kept as a link. Its files are inside it as data URLs, up to 25 MB of them in the order the page names them: a picture shown, a recording with its player, any other file a link that saves it. A file past that, or one neither this device nor the server could give, is named and marked as not in the file, and the Export tab says how many. Save with its files, on a page that points at files, is a zip in the backup’s layout holding that one page, pages/<name>.md (journals/ for a day) beside twig/ with the page’s records and its files, so Import restores it as it restores a backup. In a zip, here or from Settings › Data, the Markdown links each file the zip holds at its copy in twig/assets/, so the Markdown opens in another editor with its pictures; Import restores from twig/ and never reads those links.
• The backup zip keeps a folder of pages/ and journals/ Markdown files, bullets and a page’s key:: value lines as its properties, so a copy restores into Twig and any editor opens it as it is.

Sharing a page

1. Share a read-only link, in a page’s menu (with Cloud Sync), sends what is on this device first, then copies an address under /p/ that anyone with it can open, without an account.
2. The page shows as the server has it when the link is opened. It is listed nowhere, asks search engines neither to list it nor to follow its links, and is never cached.
3. Posted in a chat, the link shows a card this device drew when the address was copied: the title, up to three of its tags, how many blocks, the first three, and the address, dark whatever the scheme. Copy the shared link draws it again when what it shows has changed. A typed page with nothing in its outline shows its picture instead; with no picture, its card says its type, its lead and its About.
4. Stop sharing takes the link down at once; deleting the page does once the deletion has synced. The address then says the page is not shared, and its files and its card are yours alone again. A whiteboard has no link.

Publish

1. Publish to your site, in a page’s menu (with Cloud Sync), sends what is on this device first, puts the page on your site at /p/@name/ on the sync server, and copies its address. It refuses while a block on the page, written on two devices, waits for a choice.
2. The first time, it sets the site up: a name of 3 to 32 lowercase letters, digits and hyphens that no one else has, a title of up to 100 characters at the top of every page, and a home page, one page or the list of published pages.
3. Readers get the home page, each published page with Linked from under it (the published pages that link there, each with the block that does), the list of pages, by name and then the journals newest first, and a search box.

Page addresses

An address is at most 80 characters, and renaming the page keeps it. Not in this version: custom domains, password protection and analytics.

Docs layout

Layout, under Your site in Settings, is Pages or Docs. Docs reads the same published pages as documentation: the pages in a tree beside each one, its sections under On this page (to its right on a wide screen, folded under its title on a narrow one), and the pages before and after it at the bottom. On a phone the tree folds into Pages at the top. The rest of the site is as it was: the search box, the escaping, and no script. Each page reads by these rules.

On this site, /docs can be one published site in the docs layout, whatever its own layout says: the app’s server names it with TWIG_DOCS_SITE, and until it does, /docs is these pages. They are also a Markdown folder Settings → Import takes, one Twig page each under Twig docs: pnpm docs:twig writes it to docs/twig-docs.zip.

Assistants

Twig is an MCP server: an assistant such as Claude Code, Claude Desktop or any other MCP client can read your graph, the pages, days, tasks and typed pages with their fields, as Cloud Sync keeps it on the server. It connects with a token made in Settings. A token made to read has the five tools that read; one made to read and write has six more, which add and change but never delete, move or rename, and every change they make is listed in Settings to revert. A script takes the same token to Twig’s API, which reads the same things as JSON and, with a token made to read and write, makes the same six writes: one write path on the server, one list of changes, one pair of limits. Its page is the last in these docs.

A list that stops short says which ones it showed and the offset that asks for the next, so search, list_pages and list_tasks reach every one, a stretch at a time; read_page and read_day read a long page the same way, whole blocks at a time.

1. In Settings, under Assistants (with Cloud Sync), choose what a new token can do, Read or Read and write, name it for where it goes, 1 to 60 characters, and choose Make. A token keeps what it was made with: for the other, make another. It also keeps the time zone this device tells time in (Settings › Appearance › Time zone, else the device’s own), so an assistant’s today is yours.
2. The token is shown once, with Copy, the command for Claude Code, and the JSON for a client that reads a config file. The server keeps only its SHA-256, so it cannot be shown again: a lost token is revoked and made again.
3. For Claude Code, run the command in a terminal, or put the JSON in a project’s .mcp.json, Claude Code’s project file: it reads the token from an environment variable, TWIG_TOKEN, so the file can be committed without it. Another client takes the same address and header, in its own config’s form.

claude mcp add --transport http twig \
  https://usetwig.app/api/mcp \
  --header "Authorization: Bearer twig_…"

{
  "mcpServers": {
    "twig": {
      "type": "http",
      "url": "https://usetwig.app/api/mcp",
      "headers": { "Authorization": "Bearer ${TWIG_TOKEN}" }
    }
  }
}