User guide

Getting started

Open mandrel.achery.dev and sign in with an Achery account — the same one you use for other Achery apps, or a new one.

Then create a vault. A vault is one world: a series, a standalone novel, a side project. Most people only ever need one.

Inside the vault, add a page from the tree: give it a name and pick its type — a note, a chapter, a scene, a character, a place, an item, a concept, a kind of thing (a rank, a species, an order), and so on. Any type you've made up for another page is offered too. It opens ready for writing.

Next time you open Mandrel, it goes straight back to the vault and page you were on.

A first hour

Make a character page and a place page. Then make a scene, type @ and the first letters of the character's name, and pick them. Type 's straight after and the mention reads as a possessive. Now rename the character from their page — and look at the scene again. That's most of Mandrel in miniature.


Vaults

A vault holds everything for one world. Nothing links or moves between vaults: mentions, moves, name lists and saved views all stay inside one.

Create, rename, switch between and delete vaults in Settings, where you can also download a vault (see Exporting and downloading). A deleted vault waits in Settings › Deleted vaults for 30 days, ready to restore. See The trash.

On the web, a vault's address uses its name (/v/my-book/…). It follows a rename unless you've set your own in Settings.


Pages and the tree

Everything in a vault is a page — manuscripts, chapters, scenes, characters, places, notes, name lists, languages — arranged in one tree you shape yourself.

  • Add a page at the top level or under any page.
  • Move a page by dragging it in the tree on the web, or with ••• › Move to… in the app. Its whole subtree moves with it, and nothing that links to it breaks.
  • Reorder pages among their siblings the same way. The order is the reading order of a manuscript.
  • Rename from the tree or from Properties. See Renaming.
  • Delete from the tree. A page with pages under it asks whether to delete them too or move them up a level. Deleted pages go to the trash for 30 days.

The tree starts collapsed and opens just enough to show the page you're on. Pinned pages sort first; drafts are shown dimmed.

The trash

Deleted pages wait in the vault's Trash — at the foot of the sidebar on the web, or in the bar at the bottom of the app (the tree's footer on an iPad) — for 30 days. Each shows how many days it has left, and how many pages went with it.

Open one to read it and choose:

  • Restore brings it back where it was, with everything deleted along with it. If the page it lived under is gone, it comes back at the top of the tree.
  • Delete permanently deletes it now, with its history and images. It can't be undone.

Empty trash deletes everything in it for good. Anything left in the trash for 30 days is deleted for good on its own. Deleted vaults work the same way, from Settings › Deleted vaults.

The trash doesn't touch your progress: words you wrote in a deleted page still count.

Properties

Each page's Properties hold what makes it what it is:

  • Type — any built-in type, one you've already used in this vault, or a new one you make up.
  • Status — Drafting, Needs detail or Complete.
  • Word goal — see Goals.
  • Aliases — other names it goes by. See Mentions.
  • Cover image — see Images.
  • Flags:
    • Referenceable — can be mentioned with @.
    • Count toward progress — its words count toward goals and stats.
    • Draft — hidden from @, shown dimmed in the tree.
    • Pinned — sorts first among its siblings.
    • Template — see Templates.
  • Properties — your own key/value notes, like pov: Kara, which saved views can filter on.

New pages get sensible flags for their type: a scene counts toward progress but can't be mentioned; a character is the other way round. You can change them. Every field saves as you leave it.

Templates

Turn on a page's Template flag and it becomes a pattern for others. On an empty page, Apply template… copies in the template's text, type, flags and properties, and replaces {{name}} with the new page's name. It only fills what's missing, so it never overwrites your own work.

Templates never appear in @ and never count toward progress.


Writing

Pages open in the editor on the web and in the app — the same editor, so a page written on your phone opens exactly the same at your desk.

  • Formatting: bold, italic, underline, strikethrough, three heading levels, bulleted and numbered lists, quotes, dividers and tables.

  • On the web, type / at the start of a line for headings, lists, quotes, dividers, tables and images, and select text for a formatting toolbar.

  • In the app, a toolbar sits above the keyboard, with row and column controls when you're in a table.

  • Contents lists the page's headings so you can jump around a long page.

Saving

There's no Save button. Mandrel saves a moment after you stop typing, and when you leave the page, and the status always shows whether you're saved.

If a save fails — usually a dropped connection — Mandrel keeps trying, and says how many changes are waiting. Those changes are kept on your device, so they survive a reload, the app closing, or a long time offline, and are saved when you're back. On the web, closing a tab with unsaved changes asks first.

You need a connection to open pages you haven't already loaded.

More than one device

You can use as many devices as you like. If the same page is open somewhere else — another tab, another device — the editor says so. You can carry on: if both change it, the later edit wins, and the other is kept in the page's history.

History

Each editing session keeps a version of the page as it was. Open History on a page to see every version, newest first, read any of them, and Restore this version. Restoring keeps the current text as a version too, so a restore can itself be undone.

History covers the page's text, and the contents of name lists, root inventories and threads. It doesn't cover renames, moves or properties. Every version is kept.


Mentions

Type @ and a few letters to mention a page — a character, a place, a faction, anything marked Referenceable. Picking one inserts a link to that page.

  • Suggestions match the start of any word of the name or an alias, so old keep finds "the old keep".
  • The people and places in this page come first, then pages it already mentions, then the rest of the vault.
  • ↑ and ↓ move through suggestions, and Enter or Tab picks one — on the web, and in the app with a keyboard attached.

A mention points at the page, not at the name, so it never goes stale. Its text is the page's current name, wherever it appears.

Possessives, plurals and lower case

Type 's straight after a mention and it becomes "Kara's" (or "Vass'" for a name ending in s). A bare s makes it plural. It's still one link, so it stays right after a rename.

Click or tap a mention to change its form, give it irregular plural text, or fix its wording entirely with a custom form, which is never changed automatically.

The same menu sets a mention's case, so "the chief warden" can still mention your Warden page. Lower first letter turns "The Wardens" into "the Wardens" mid-sentence; All lower case turns "High Priest" into "high priest". Case works alongside the form: "the wardens'" is lower case and possessive.

Aliases

Give a page every name it goes by — "Kara", "Kara Vass", "the Captain" — as Aliases in Properties. Each one can be found with @, and a mention made through an alias keeps reading as that alias. Click or tap the mention to switch which name it uses.

Fix an alias's spelling in place and the mentions that used it follow. Remove one and Mandrel tells you how many mentions will switch to the main name.

Renaming

Rename a page from the tree or its Properties. Before you commit, Mandrel shows how many mentions will follow; after, every one of them reads the new name — in every chapter, the contents, threads and exports — without opening anything.

Tip: keep the old name as an alias, so @ still finds them by it.

On the web, the page's address follows its name too, unless you've set your own in Properties.

Deleting a mentioned page

While a page is in the trash, mentions of it stay where they are, in red. Tap or click one and choose Open in trash to restore the page or delete it for good. Restore it and the mentions are ordinary mentions again. Delete it permanently and each one turns into plain text — its name at the time, in the mention's form — rather than a link to nothing.

The cast list, peeks and Used in

Open a page's Reference panel (a sheet in the app) to see:

  • Scope — everything the page mentions, plus anything you've pinned to it, each with a one-line reminder. Pin a character who turns up later in the scene and they come first in @, even before you've mentioned them.

  • Used in — every page that mentions this one, with a snippet and a count.

Choose an entry, or Peek from a mention, to read that page without leaving the one you're writing in. Go to page from a mention takes you there.


Images

On the web, paste or drop images into a page, or use / › Image. In the app, add them from your photo library with the toolbar. Images show up on every device.

Images must be under 5 MB; the app shrinks large photos first so ordinary ones fit.

Any page can have a cover image — a portrait, a map — shown across the top of the page and in peeks. On the web you can set which part of it stays in view.


Finding your way

  • Go to jumps to any page by name or alias: ⌘K (Ctrl+K) on the web, the bottom bar or tree in the app. With nothing typed, it lists your recent pages.

  • Recent lists the pages you've been working on over the last 60 days, ranked by how recently you touched them and how much you wrote there, so yesterday's long session isn't buried by a page you glanced at.

  • Rollups are saved views: every scene that's still Drafting, every page with pov: Kara. Build one from conditions on type, status, flags and properties, with a live preview, and it sits beside the tree.


Progress

Goals

Give any page a word goal in Properties — "about 4,000 words" for a chapter — and its progress shows under the editor and in the outline.

A vault can also have one deadline goal: "60,000 new words by 1 March". The vault home shows what you've written, what's left, the days left and today's target, which spreads any shortfall across the days remaining. While you write, the editor shows today's progress.

Sessions and stats

Writing on a page that counts toward progress starts a session. Mandrel counts the new words you add — deleting never takes them away, so a day of cutting doesn't count against you — and the time you spend writing.

The vault home shows words and time today and this week, by your own time zone; weeks start on Monday.

Outline

Outline on any page shows everything under it as a table: each page's words, goal, progress and status, and the totals. On a manuscript, that's where the book stands.


Threads

A thread is a story arc: a character's journey, a mystery's clues. Write it as an ordinary page of type thread, with a list: each list item is a beat, and nested items are sub-beats. Text before the first : is the beat's title.

Switch to Threads (on the web) or ••• › Threads (in the app) to see the beats as an outline, and link each beat to the scenes and chapters that carry it. Reorder, retitle or indent beats freely; their links stay attached.

A scene's Properties list the threads it moves forward.

When the manuscript tells two beats in a different order from the thread, a warning appears between them. If it's deliberate — a flashback, say — mark it as intended and it goes away.


Names

A name bucket is a list of names for a culture, a family or a book: each with a kind (given name, surname…), and optionally a meaning, tags and notes. Filter it, mark names as used, and pull a random unused name of the right kind when a minor character needs one now.

Every page's Properties has a Name section. Choose a name list (or a language), pull a name at random or build one, add its meaning, and choose Name this…. The name lands in the list, the page records where it came from, and Mandrel offers to rename the page to match.

A name and its list are one record: edit the name's meaning in the list and the character's page shows the change.

You don't need a constructed language for any of this.


Constructed languages

A language is a page of type conlang-spec. Put a root-inventory page under it to hold its roots.

Roots

The inventory is a table on the web and a list of cards in the app. Each root has a form, a meaning, a category and a type (a standard root, or a family header whose children share its consonants), with optional extras. Search, filter and sort it; group roots into categories you name.

A root with no form yet is a draft: lay out the meanings first and fill in forms later, inline on the web or in fill mode in the app.

Search by meaning finds synonyms and forgives typos: "sea" finds a root glossed "ocean".

Two roots with the same form are marked as duplicates, in amber. You can still save one: sometimes it's deliberate.

Sound rules

The language's phonotactics describe how it sounds: its vowels and consonants, which clusters it allows, how words may start and end. Edit them in the language page's Properties on the web, or with ••• › Phonotactics in the app. Every field explains itself in plain terms, and the inventory shows a summary while you work.

Roots and names that break the rules are marked in red as you type, with a plain explanation. A warning never stops you saving.

Pattern templates

If the language builds words by filling a fixed set of slots, declare them once as a pattern template in the language's Properties. Generate on a family then makes a draft for each slot, and only fills gaps when run again.

Daughter languages

A root can record the root it came from in another language, and always shows it with its meaning. Open the link to see the source in context.

Derive… on a daughter language's inventory lays out the parent's roots by category: pick some or all, and Mandrel creates linked drafts, keeping families together. Run it again later and it only adds roots that are new in the parent. Write the sound changes as notes on the language; they sit beside the drafts as you fill them in, with each parent form alongside.

Importing a spreadsheet

On the web, Import grid turns a spreadsheet of planned roots — concept slots across the top, meanings down the side — into families of drafts. Paste it in or upload a CSV, check the preview, then merge it into the inventory or replace it.


Exporting and downloading

  • Export on any page saves it as a markdown file, with its properties at the top. Mentions become [[wikilinks]] in their current names.

  • Download next to a vault in Settings gives you a zip of the whole vault: every page as a markdown file, in folders that follow your tree, with its images.

Name lists and root inventories export in their own readable formats. There's no import, and no export to Word yet.


Web, iPhone, iPad and Android

Mandrel works in any modern browser, and the apps for iPhone, iPad and Android do everything the web does.

A few things are web-only, because they need a mouse or a big screen: importing a spreadsheet of roots, and setting which part of a cover image stays in view.

On an iPad (or any wide screen), the app shows the tree, the page and its panels side by side, like the web. With a keyboard attached, ⌘K opens Go to, ⌘S saves, and Escape closes the open panel.


Settings

  • Theme — light, dark or follow your device, and an accent colour. Set it once and every device follows.
  • Vaults — create, rename, download and delete vaults, and restore deleted ones.
  • Privacy — on the web, whether to share usage and crash reports. See Privacy.
  • Account — the account you're signed in with, Log out, and Delete account….

Privacy

Your vaults are private to your account; no one else can open them.

The first time you use the web app in a browser, it asks whether to share usage and crash reports. Either answer is fine, and you can change it in Settings. The apps don't send any. What you write is never included. See the privacy policy.

To delete everything, use Settings › Delete account…. See Delete your account.