User Guide

This guide covers every part of Prisment, the local-first documentation workspace for AI and engineering teams: how it takes the Markdown, MDX, OpenAPI specs and data files your tools already produce and turns them into presentation-grade documents — with live Mermaid diagrams, KaTeX math, syntax-highlighted code and interactive API docs. Everything runs inside your browser. No account, no upload, no server.

1. Start here

What Prisment does

Five things, in order of how most people use them:

1. Renders Markdown, MDX, OpenAPI specs, YAML, JSON, CSV, Mermaid diagrams, Word, PDF and Excel files as finished-looking documents.
2. Edits Markdown from either side — raw source, or directly in the rendered page.
3. Syncs to a real folder on your disk, so an AI agent writing files and you reading them stay in step.
4. Reviews documents — comments on passages, decisions and an approval — saved as files in the folder, so Git or a shared drive carries them to your team and your AI agent (see Reviewing documents), and commits them from Source Control in the desktop app.
5. Exports any document as a standalone HTML page, or a whole workspace as a linked documentation site.

Your first five minutes

From the home page:

• Start Writing — on your first visit (Start Writing (Demo)) it opens the sample Demo Workspace on the rendered document; after that it opens a blank document in the editor. Best for a quick note, drafting an RFC, or trying things out.
• Open Local Folder — mounts a directory on your computer so edits sync straight to real files. This is the feature Prisment is built around; see Local disk sync.
• Go to workspace — once you have content it becomes the first button, and takes you back to your work. New Scratchpad sits beside it and adds a blank draft to that workspace.

The desktop app has no home page: it opens on Open a folder…, Clone a repository… or New here? Create a starter folder for me.

You can also drag & drop files anywhere onto the page. To bring in a whole project folder, use Open Local Folder (it mounts the folder), or, in any browser, Open Folder in the Files sidebar (it copies the folder's supported files into a browser workspace) — nothing is sent to a server either way. Supported: .md, .mdx, .txt, .html, .htm, .csv, .tsv, .json, .yml, .yaml, .mmd, .mermaid, .docx, .pdf, .xlsx, .xlsm and images (.png, .jpg, .jpeg, .gif, .webp, .svg).

The demo splits its live Markdown examples between README.md (the picture, the table, the quote, two diagrams, the Note and Tip alerts, keyboard keys and links) and docs/requirements.md (front matter, headings H1–H6, a task list, nested lists, formulas, code, footnotes, a collapsible section, badges and the Warning, Important and Caution alerts). No element is shown twice, so every example is a different thing to try; the README's Try Markdown editing section says where each lives. Switch to Edit to try the controls, then Undo a practice change. Updated examples appear in newly created demos; existing saved demo documents keep your changes.

The UI map

Once a document is open, the workspace has six regions:

The top bar stays in place. In Focus Mode it hides and comes back when you move the pointer (or touch) near the top; it stays down while a menu, popover or dialog is open.

Where Prisment runs

The same app ships through three channels, and two features differ between them.

2. Files & workspaces

Workspaces

A workspace is a collection of documents you work on together. There are two kinds:

The top of the sidebar shows the current workspace's name on one line, beside a compact folder or browser icon; a long name ends in an ellipsis. Hover the name to read it in full, with where the workspace is stored (Local folder, or Local Browser Storage). Press the Switch workspace icon (two opposite arrows) beside its name to choose another workspace, rename it or delete it; for a local folder, Close Workspace leaves its files on disk. The list opens below the workspace row and fits the sidebar. The + creates or opens a workspace, grouped beside Switch workspace with the same compact icons as the Files toolbar. The active workspace, the active document and which folders you had expanded are all remembered across a reload.

Hover or focus a workspace name in the list to see its complete name and storage type. These hints, and the sidebar controls' tooltips, fit inside the window; long names wrap so they stay readable.

The desktop app has no browser workspaces: every workspace is a folder. There a workspace can hold several folders — Add Folder in the Files header adds one, Refresh Folder re-reads the disk, and right-click a folder's header ▸ Close Folder takes it out. A browser workspace holds one.

Windows (desktop app). Each workspace can have a window of its own, so two projects sit side by side. Choose File ▸ New Window (Shift + Cmd/Ctrl + N) for an empty window, then pick a workspace in it from the switcher list or open a folder — or press Open in New Window beside a workspace in the list to open it in a window of its own. Choosing a workspace in a window switches that window; it never opens another. A workspace is open in at most one window: asking for one that another window shows — by choosing it in the list, by opening its folder, or by Open in New Window — brings that window forward instead of opening a second. The same goes for a folder: opening or adding a folder another window already has open — on its own or as one of several folders — brings that window forward, so two windows never write the same folder. A workspace another window shows is deleted from that window, not this one, and closing a workspace never moves its window onto one another window is showing. If you choose another workspace while a folder is still loading, your latest choice wins. Each window keeps its own tabs and unsaved drafts, is titled with its workspace's name, and returns to the same workspace after a reload; a file you open from Finder or Explorer lands in the window you used last — in an empty window, in the first workspace no other window shows, or a new one. When no window is open — on a Mac, Prisment keeps running after its last window closes — or Prisment is not running yet, opening a file opens a window, and the file lands in the workspace that window opens on. Closing a window leaves the others as they are. In a browser, use a second tab.

The file explorer

The Files sidebar is a full workspace explorer. Thin dividers above and below the Files header separate the workspace selector, controls and file list:

• Create, rename and delete files and subfolders — right-click a file or folder (long-press on a phone) for its actions. A new file can be Markdown, MDX, text, JSON, YAML or a Mermaid diagram — pick the extension beside the name. HTML, CSV, Word, PDF, Excel and pictures are opened or dropped in, not started here.
• Move files and folders by dragging them within the tree. Copy a file and Paste it into a folder to duplicate it; Copy Path and Copy Relative Path are in the same menu.
• Drop files in from your computer onto a folder, or anywhere in the workspace. A dropped file never replaces one already there: a different file with the same name is added as name (v2), and the very same file, unchanged, is not copied again — the one already there opens, and a notice at the top right says so. A move that cannot finish — a file another program holds, say — leaves the folder as it was, or tells you if the original stayed behind.
• Renaming a file or folder repairs the links to it in the documents that point at it. A document you are editing keeps your unsaved changes: only the link fix is saved to its file, and your edits stay unsaved on top of it. A change of letter case alone (notes.md → Notes.md) works in the desktop app, which renames in one step, and in a browser workspace; in a browser on a mounted folder, rename it to another name first, then to the one you want.
• Filter the tree by file name.
• File-type marks so a .csv never looks like a .md.
• Compact rows, with a blue highlight and a blue line on the selected file's left edge. Unsaved files keep their amber signal.
• On-demand loading, so a repository with thousands of files opens quickly.

Tabs

Open documents appear as tabs in the header. The selected tab is flat, with a slim blue line across the top, and matches the document page background, including a custom page colour. Click one to switch; right-click for its tab actions. The File information ⓘ (at the foot of the activity bar; in the ⋮ menu under 1024 px) reports the active file's size, line, word and character counts, its path, and when it was last saved to disk — with one-click copy for the name and path.

Relative links between documents work. Clicking [Architecture](./docs/architecture.md) in a rendered document opens that file as a tab, exactly as it would on GitHub. A link is read from the folder of the document it is written in, so ../README.md climbs from there; a file in a folder you have not opened yet opens all the same, and a link that leaves the workspace says so.

Closing a tab or a workspace never deletes its files from your computer. To delete a file or folder, choose Delete in the file navigator and confirm the named item; a notice at the top right then says what was deleted, and whether from your disk or only from the workspace. An AI delete proposal also waits for your explicit confirmation, even with automatic apply enabled.

Local disk sync

Open Local Folder mounts a directory. Files are read and written directly between the app and your disk — nothing is uploaded, and there is no cloud in the path.

• AI agent sync — point Prisment at the directory your coding agent writes into. The moment the agent saves a Markdown file or an OpenAPI spec, Prisment picks it up and renders it.
• External change detection — a file you have not edited follows the disk (a git branch switch, an agent, another editor); one with unsaved edits asks first. Moving or renaming a file in Prisment, or another program rewriting it with the same content, is not a change: the file keeps its undo history and no notice appears.
• External deletions — a file deleted on disk while open stays in its tab, struck through, with Remove from tab. This closes only the in-app tab; it never deletes, restores or changes a file on your disk, even if that file has reappeared. A folder that has gone says so, with Locate… or Close folder.

Source Control

The activity bar always shows Source Control. It looks for git repositories in each folder you opened and
in the folders below it, down to three levels — so a folder of projects lists every project's repository,
each named by its path (work/booking-app). The bar shows a count of what changed. Changed files are listed the way an editor lists them: the file's icon, its name with its
folder dimmed beside it, and a coloured letter at the right (M modified, A added, D
deleted — struck through, U untracked); each group (Staged Changes, Changes) has its count in a round badge. Press a name to see what changed — the last commit on the left, the file as
it is now on the right (see Compare with saved, below); hover a row for its buttons. The groups fold
away with their chevron. History — the branch and its last commits — is not drawn until you press the History
icon in the pane's toolbar (the repository's GitHub link is the icon beside the title); it opens under Changes,
the two scroll on their own, and with one repository the line between them moves (drag it, or use the arrow keys;
double-click puts it back). The count on the bar is refreshed every couple of minutes, when you return to the window and after each action — not as you type.

Several folders, several repositories. A workspace of several folders (or one folder of projects) lists every
repository, each as a row of its own — folder name, change count, branch, and its tools (History, ⋯, refresh). Several
repositories start folded, and a failure or a merge waiting stays in view even then. Which ones you opened or folded is
remembered in this browser.

In the desktop app (with git installed) it works like an editor's Source Control view:

• Write a message and press Commit — the full-width button under the message box. If you have
  staged files it commits those; if you have staged none, the button says Commit All and commits every
  change. The arrow beside it has Commit (Amend) (rewrites the last commit; leave the message empty to
  keep its message), Commit & Push and Commit & Sync.
• A row's buttons, on hover: Open file, Discard changes (it asks first; an untracked file is
  deleted and cannot be brought back) and + to stage — or − to unstage a staged file.
• The branch chip opens a list: switch, or type a new name to create a branch. Sync pulls then pushes
  when you are behind or ahead; Publish pushes a new branch — or one whose copy on the remote was deleted (its pull
  request merged), which Prisment says instead of quietly making it again. After a push, the pull-request page the host
  offered is one press away (Open a pull request on github.com). While a merge waits to be finished, Pull, Push, Sync
  and switching wait too; and while you are not on a branch (a tag checked out), Commit waits for you to create one.
• ⋯ is the Git menu — the options an editor's Source Control menu has, each with a sentence saying
  what it does (or why it can't, right now): Pull, Push, Clone…, Checkout to… (a branch or
  a tag), Fetch; then Commit (Commit All, Amend, Commit & Push or Sync, Undo Last Commit),
  Changes (stage or unstage everything, Discard All Changes), Pull, Push, Branch (merge,
  create, rename, delete), Remote (add or remove a server), Stash (set unfinished work aside and
  bring it back), Tags, and Show Git Output — the commands Prisment ran and what git answered.
  Push to… sends to another remote — your own fork, say — once, or and keeps pushing there.
  A group opens in place with a Back arrow; questions (a name, a choice, "are you sure?") are asked in the
  same panel. Anything that throws work away asks first and says what will be lost. Rebase is not offered.
• A merge that stops on the same lines shows a notice with Abort merge; the files are listed under
  Merge Conflicts. Fix them, stage, and Commit — or abort to go back to how things were.
• If git — or the host — says no, Prisment says what happened and what to do in plain words; git's own message is
  one click away under Details, and nothing is changed. A sign-in problem and a permission problem are told apart:
  when the host names your account ("denied to colleague"), you are signed in, so Prisment says that account can't
  push there and offers the real ways forward — ask the owner for write access, push to your own fork (Push to…), or,
  for the wrong account, a command that makes git forget the saved sign-in for that host. A branch only a pull request
  may change, a secret found in a commit, an organisation's single sign-on (with its authorisation page), an archived
  repository, a locked file and a host's own rule (its reason quoted) are each said as what they are.
  Where Prisment can take the next step, it is a button: Merge Their Changes and Push after a push the remote
  refused for newer work, Merge Their Changes after a Pull that can't simply move forward (a merge commit — nothing is
  rewritten), Switch to main or Publish Again for a branch deleted on the remote, and Take the Remote Version after
  someone rewrote the branch (what you had is kept on a backup branch).
• Clone a repository (File ▸ Clone Repository…, the welcome screen, the + beside Switch workspace, the
  workspace menu or ⋯): one box
  to search or paste. Type owner/repo (GitHub is assumed, and the same name on GitLab, Bitbucket and
  Codeberg is one click away; HTTPS or SSH), or paste an address, a link copied from the browser (a branch or
  pull-request page is cut down to the repository), or a git clone … line from a README. Repositories you
  cloned before are listed as you type. Choose the folder to clone into, and it opens as a workspace.
  As you pause typing (not per letter or word), the words are also searched for public repositories on the
  host you pick under the box — GitHub until you choose GitLab or Codeberg, or Off to search
  nothing. Only the words you typed are sent, to that one site. A private repository is cloned by pasting its
  address.
  If you have the GitHub CLI (gh) installed and signed in, the list also shows your own repositories,
  your organisations' private ones first, marked Private — Prisment asks gh, never sees your sign-in, and sends
  nothing you type for it. Without gh, everything else works as before, and pasting a private repository's
  address always works.
  The folder is named after the repository; if that name is already a folder where you are cloning, or the name
  of a workspace that is open, Prisment says so and uses the next free one (name-2) — you can type another.
• Who commits are from. If git has no name and email of its own, Prisment asks for them in place and uses
  them only where git has none.

Prisment runs your git, so your sign-in, SSH keys and hooks apply — with the PATH your terminal's login shell sets
up, so a repository's checks that need node or npx, Git LFS and gpg signing work even when Prisment is opened from
the Dock — and it sends nothing anywhere
except what you press — and, in Clone, the words you pause on in the search box, to the one host you chose (Off sends nothing). In the browser a page cannot run git, so Source Control is read-only and ends with a button to the desktop app, which does the rest. On a desktop without git it is read-only too, and points to git's official download and installation guide, with a Check again button: it
lists every file that differs from the last commit (the same rows, with Open file on hover, whatever the file's format), compares them, shows the
branch's History, and links to GitHub when origin is there; use your own git tool to commit (press ↻ after a switch). A
folder with no repository is never a blank pane: it says so, and — in the desktop app — offers Initialize Repository
(creates it here, on this computer only) or Connect to a remote (origin)… (creates it here and links it to a
repository on GitHub or another host in the same step; owner/name or any address works). A repository started without a remote is then
offered one — Connect, or Not now; ⋯ ▸ Remote is always there. Where git is not installed the pane says so and links to git's
download and installation guide, with Check again. A folder that lies inside another repository says which one. Repositories cloned later
appear when you press the pane's Look for repositories again, or when you come back to the window. With no folder from your computer open,
it asks you to open one.

Reviews travel through Git too. A review is saved as files in .review/; commit and push them with the
documents, and colleagues pull them — step by step under Review through Git, step by step in Reviewing documents.

Saving, drafts and conflicts

• Cmd/Ctrl + S saves the active document. In a local folder that writes straight to disk; in a browser workspace it persists to local storage.
• Save is the first of the top bar's buttons whenever a document you can edit is open — in the editor and in the preview alike. It lights up while there is something to save; pressing it — or Cmd/Ctrl + S — on a document with nothing unsaved says so instead of saving again. Undo, Redo, Find, Save as… and the rest are in the ☰ menu at the top of the activity bar (File and Edit), each with its shortcut; Find is offered wherever the view has text to search. File information is the ⓘ at the foot of the activity bar.
• Under 1024 px, and on a phone, there is no activity bar beside the document: the ⋮ at the end of the top bar holds the document's actions, File information among them. A phone shows Save on its own, and only while there is something to save. On a phone the Read / Review / Edit switch is three icons — an eye, a speech bubble and a pencil — so the open file's tab keeps its room; each still carries its name for a screen reader and on hover.
• Unsaved Drafts lists every file with unsaved edits at the top of the Files view. Each row has Compare (the draft against its saved version) and Revert (discard the edits) beside its name — and Compare works on a draft that is not the one open.
• Nothing is written to your folder until you save. Typing only keeps a draft inside Prisment; Cmd/Ctrl + S or Save writes the file.
• Drafts are protected. Unsaved edits are kept in the background, so closing a tab or reloading does not lose them.
• Your edits are never overwritten silently. A file you have not edited follows the disk. If one with unsaved edits changes on disk, Prisment asks — Load Disk File or Keep Draft (Load That Version when another tab saved it).
• Revert to saved discards unsaved edits and returns to the version on disk. It cannot be undone, so its shortcut and File ▸ Revert to Saved ask first.
• Compare with saved shows what you changed, in a diff like an editor's: the saved version on the left, your draft on the right, a gutter of line numbers with + and −, and the changed words highlighted. It fills the window, shows every line, and opens with the first change already in the middle; the button with the two chevrons folds the unchanged lines away (click a fold to open it). The arrows — or F7 and Shift + F7 — step through the changes, and the strip down the right edge shows where they are. On a narrow window it draws one column instead; the button beside the arrows switches.
• Save as… is for a picture you changed — an SVG you gave a background. It asks for a name, writes the copy beside the original and opens it; the original goes back to how it was saved. It is File ▸ Save As…, or Shift + Cmd/Ctrl + S. Where there is nothing to save as, the key and the menu item save.

3. Writing

The split editor

Two panes, side by side:

• Left — the source. The raw text, with line numbers and syntax highlighting.
• Right — the rendered document. Exactly what an export will look like.

For Markdown, both panes are editable. Type Markdown on the left, or edit the rendered document directly on the right; changes on the right are written back into clean Markdown source. A Markdown file opens on the rendered document alone — the editor that types straight into the page — and Split puts the source beside it, at 40% and the rendered result at 60%. Drag the divider to re-balance; your choice is remembered, and a double-click puts it back to 40 / 60.

The segmented control in the toolbar switches what you see:

• MD — source only.
• Split — both panes.
• HTML — the rendered document only (where a Markdown file opens until you choose otherwise).

Markdown and MDX use the same page card in HTML, the rendered side of Split, and Read: width, padding, colours, border and shadow follow your style settings. The source pane keeps its own flat editing surface.

A format whose preview you read rather than type into — an OpenAPI spec in YAML or JSON — is edited through its source, so it opens in Split, with its source button (YAML, JSON or Mermaid) and Split to choose from.

On narrow screens the panes stack vertically instead of sitting side by side.

Editing the rendered document

Click into the right pane and type. It behaves like a visual word processor: headings, bold, lists, tables, callouts and code blocks are all applied visually and serialized back to standard Markdown. Untouched parts of the file stay byte-for-byte identical, so a visual edit never quietly rewrites the rest of your document. Two things are Prisment's own, and are written only when you choose them: a picture's size and alignment (a short note after the picture) and a diagram's look (a prisment: block at the top of the diagram). Another tool shows the first as text and Mermaid ignores the second.

Pasting from Word or a web page keeps headings, lists, links and emphasis as Markdown. Pasting a picture opens the picture card. Choose Apply to save the picture beside this document and insert its relative path. In that card, Upload, Workspace and Path or URL are three ways in, one at a time. Upload takes a picture from your computer — choose it, or drop it on the card: if the workspace already has that very picture it is used as it is and nothing is copied, and otherwise a copy goes into an assets folder beside the document, so an export has it (Change folder lists the workspace's folders as a tree, each under its parent, so two folders with the same name are told apart; it picks the document's own folder or any other, and Prisment remembers the choice; you never have to). Workspace browses the pictures the workspace already has, with thumbnails and a search, and uses the one you pick as it is. Path or URL takes an address you type or paste, and suggests the workspace's pictures as you do. Under each, a line says whether an export will have the picture: a picture in the workspace is confirmed, one that is not is flagged, a web address is flagged (it needs a connection, and an offline export shows nothing), and a path on this computer (C:\…, /Users/…, ~/…) is flagged, because it shows only on that computer — uploading the file keeps a copy in the workspace, which is recommended. Nothing here is required: every one of them can be applied. Cancel saves nothing; undo removes the reference and keeps the picture file. Save the document into a workspace folder first if it has no folder yet; until then the card offers only the path. Pictures embedded in a mixed Word/web paste still need to be attached separately.

In Edit, a link is text like any other: a plain click puts the caret in it so you can change it, and Cmd/Ctrl+click follows it — an address opens in a new tab, a document opens in its tab, and a #link scrolls to its heading. A link shows the text cursor, and the pointer only while you hold the key; a footnote's number is not text, so it is a plain arrow until then. In Read and Review a click follows the link as usual.

Formatting controls are dimmed when the selection contains content that cannot carry that format, such as a formula, fenced code or metadata. Inline Code cannot turn a formula, picture, badge or footnote citation into plain code text. Select the surrounding text separately, or change the Markdown source. Editing a code block preserves its spaces, empty lines and literal backticks, including a Markdown sample with its own fences.

A quote, an alert, a list or a code block is not lost to Backspace or Delete. Backspace at the start of the first line of a quote, an alert, a list or a code block does nothing — it does not pull the text up into the paragraph above and take the container with it, and it does not strip a task's checkbox. Delete at the end of a paragraph just above one does not pull its first line up either, and Backspace at the start of a paragraph just below a code block or a table steps back into it instead of pouring the text into the code or the last cell. Take a container off with its button on the toolbar (lit while you are in it), with Enter on its empty last line, or by selecting across it and deleting. A later line or list item still joins the one above it, inside the container, and an emptied bullet is taken off by Backspace. A quote, an alert or a code block whose text you deleted stays, empty and ready to type in.

This is the fastest way to fix a word, restructure a list, or edit a table without hunting through source. What it means for a team's files and git history, with a before-and-after diff, is in Markdown editor with live preview.

Editing element properties

In HTML or Split, hover, tap or focus an element to show its pencil beside it. The icon has a tooltip and an accessible name identifying the element. Nearby controls use the same floating frame as table options. A short delay and a transparent bridge let you cross the gap to the button; it stays visible while you point at it, focus it from the keyboard, or keep its editor open. It disappears after you leave both the element and its controls, or press Esc. The pencil opens a small editor for that element. From the keyboard, place the caret inside an element and press Alt+Enter. Esc or clicking outside dismisses the editor without applying. On an element that is already in the document, a red Delete at the left of the card's footer removes it as one undoable step — for a link it reads Remove link and keeps the words, for a footnote its note and every mark that points at it go together, and a table cell has none (its toolbar owns it). To add an element, use its entry on the toolbar or in More Tools (see The formatting toolbar); it is written at the caret, or at the end if no caret is selected. Front matter always goes at the top; a footnote adds its reference at the caret and its definition at the end.

For a Mermaid diagram, use the pencil in its own control row, beside Copy, Customize and zoom. It stays available in Edit mode, including when the diagram has a syntax error or is fullscreen. It opens the existing .mmd editor in a fullscreen popup: source on the left and diagram on the right, or source above the diagram on mobile. Valid changes update the preview live; incomplete or invalid source keeps the last working diagram visible. The preview offers the usual diagram controls except the pencil. Customize changes the draft; Apply saves it as one undoable change and Cancel leaves the document alone. From the keyboard, use Tab to reach the pencil and Enter to open it.

The pencil sits where its element is. On a block — an alert, a code block, a formula on its own line, front matter, a footnote or a picture — it stands inside the top-right corner, beside the block's own controls (to the left of a code block's Copy) — or, when the block has a title or is a formula, right after the title (an alert's, the front matter's) or the formula itself, where you are already looking. On something in a sentence — a link, a badge, a footnote mark or a formula — it stands just above it, centred. It never sits over the block next to the one it edits. It is a solid button in the presentation's accent colour with a white pencil, so it reads on any page, light or dark, as the Mermaid pencil does; table cells keep their table toolbar and direct editing, without a separate pencil.

The editor is a compact card that opens under the pencil: a header naming the element, one column of fields, and a footer with Cancel and Apply. It hangs below a short element so the element stays in view while you edit it — above it when there is no room below — and a card too tall for the room beside the element takes the window instead — it slides up to show whole, over the element if it must, with its fields scrolling only when even the window is too short (the header and footer stay put). Code, formulas and YAML are set in a monospace face; a code block's language suggests names as you type; a formula or a badge shows a Preview as you type, and a picture shows itself first. An alert's type and a badge's colour are lists that draw each choice as the document does — its icon and its colour — with a tick on the current one; arrow keys move through them. Esc cancels; Ctrl+Enter (⌘+Enter on a Mac) applies from any field, so a multi-line field never needs the mouse.

Apply makes one change in the document's existing undo history. Cancel leaves it alone. If the document changes while the editor is open, reopen it to work from the current content. Changing files closes the editor. Formulas, diagrams and complex YAML use focused source fields; ordinary prose, lists, sections and tables remain editable directly on the page.

The formatting toolbar

The toolbar applies formatting to whichever pane you are working in.

The bar always shows the everyday tools — H1–H3, bold, italic, strikethrough, inline code, highlight, the three lists, blockquote, code block, link and table. More Tools holds the rest, so every element Prisment supports has an entry: H4–H6, keyboard key, subscript, superscript, inline math, collapsed section, the five alerts, Mermaid diagram, math block, image, horizontal rule, badge, footnote and front matter. In the Markdown source they write the Markdown — a footnote's mark at the caret and its note at the end, front matter at the top (or into the front matter already there). On the rendered page, Badge, Footnote, Front Matter and Inline Math open the same card the pencil uses, already on that element; the others work in place. There is no separate Insert element button: every element has its own entry. A block inserted while the caret is on an empty line takes that line — no blank paragraph is left above it — and the caret goes into the new block (a note's placeholder text is selected, so typing replaces it) or, for a rule, a diagram or a formula, to the text that follows.

The buttons that switch a format on and off — H1–H3, bold, italic, strikethrough, inline code, highlight, the three lists, blockquote, code block and link — light up while the caret, or the whole selection, is in that format, in the rendered pane and in the source pane, so you can see at a glance what the text under it is. Press a lit button to take the format off; press an unlit one to put it on. What sits behind More Tools is shown too, wherever its element can hold the caret: while the caret is in an H4–H6, a keyboard key, a subscript or superscript, a badge, an inline formula, a footnote's text, an alert or a collapsed section, that tool's button appears on the bar, pressed, just before More Tools and set apart by a separator, and goes when the caret leaves; the menu shows its card lit too, so you never open it to see where you are. Press the lit button to take the format off — an alert or a collapsed section lifts its contents out — and on the rendered page a lit Badge, Footnote or Inline Math opens the editor of the element you are in rather than adding another. A diagram, a block formula, a picture, a rule and front matter cannot hold the caret, so they show no state; use their pencil. In the Markdown source the marks, headings and badge are shown the same way. Taking a bullet off an item and putting it back leaves the list exactly as it was. Headings, blockquotes and code blocks also work inside list items and table cells. A list keeps its children and task checkbox. GFM cells cannot hold block Markdown, so rich cell content is written as inline HTML inside the pipe table; ordinary cells keep ordinary Markdown.

Find & Replace

Open it with Cmd/Ctrl + F, ☰ ▸ Edit ▸ Find, or Find in the ⋮ menu on a narrow window. Step through matches with Enter and Shift + Enter; Aa matches case and \b whole words. In Edit, Cmd/Ctrl + H or the arrow beside the box (Show Replace) adds Replace and All. Read mode only finds.

In Read, Find searches what you are reading: a document's text, or a code file's source — a text, JSON or YAML file — where it finds exactly what the editor finds.

Keyboard shortcuts

Some shortcuts are global; others depend on which pane your cursor is in. They are listed separately because that difference is real.

Anywhere in the workspace

Undo history is kept per document, so undoing in one tab never reaches into another. A new bullet you have only started — Enter, Tab, nothing typed yet — is not a step of its own: Undo takes you back to before it, never to a half-made list.

The menus show each shortcut in your keyboard's own names: ⇧⌘S on a Mac, Ctrl+Shift+S on Windows and Linux. Alt is Option on a Mac.

Every menu works from the keyboard as well as the mouse — the ☰ menu, the ⋮, a right-click menu, the Git menu, the model list: ↓ and ↑ move, Enter chooses, → opens a sub-menu and ← comes back, a letter jumps to the next item that starts with it, and Esc closes the menu — only the menu, not a dialog under it. A greyed item can be reached, so you can read what is unavailable, but does nothing.

Tabs work the same way wherever they appear — the sidebar's Files / Source Control / Knowledge bar, Review's sections, Share, the release notes, the heading levels in Customize Style: ← and → (↑ and ↓ on the sidebar's bar) move to the next tab and show it, Home and End jump to the first and last. An "are you sure?" question inside a panel — discarding changes, deleting a review — starts on its safe answer, and Esc is that answer.

Desktop app only (File and View menus)

In the rendered document (right pane)

Typing in the rendered document also works the way it does in a word processor:

In the Markdown source (left pane)

In a YAML or JSON source pane

Markdown's shortcuts are deliberately inert here — Cmd + B in a YAML file would write asterisks into your data.

4. Markdown reference

Prisment follows GitHub Flavored Markdown (GFM) and adds a small set of client-side extensions. Every example below is live: it is rendered by the same engine your documents go through. Open the Markdown source toggle under any example to see the exact text that produced it.

The standard syntax

Everything GFM defines works as you expect:

Headings also get automatic anchors, which is what makes the Index drawer and in-document links work.

Mermaid diagrams

A fenced code block tagged mermaid renders as a live SVG diagram with pan, zoom and fullscreen controls:

```mermaid
graph TD
  A[Raw Markdown] --> B(Local Parser)
  B --> C{Preview & Export}
  C --> D[Interactive WYSIWYG]
  C --> E[Standalone HTML File]
```

Prisment ships Mermaid 12, so every diagram type that version supports is available — flowcharts (graph / flowchart), sequence diagrams, state diagrams, class and ER diagrams, Gantt charts, pie charts, user journeys, mindmaps, timelines and more. Diagrams follow your document's light or dark scheme automatically.

If a diagram has a syntax error, Prisment shows the error next to the block instead of leaving an empty canvas — so a typo never costs you the rest of the page.

Chapter 5, Diagrams: customize, animate and share, shows what else a diagram can do: a new look, motion, presenting it one step at a time, and sharing it as a GIF.

Math with KaTeX

LaTeX renders client-side with KaTeX.

• Inline — wrap in single dollar signs: $E = mc^2$.
• Block — wrap a standalone equation in double dollar signs:

Inline: $E = mc^2$

$$
f(x) = \int_{-\infty}^{\infty} \hat{f}(\xi)\,e^{2\pi i \xi x}\,d\xi
$$

Callouts and alerts

GitHub-style alert blockquotes render as a coloured bar down the left, with a line icon and the title in that colour above the text. There are five (a title after the marker, > [!NOTE] Before you start, replaces the default label; INFO, SUCCESS, DANGER and ERROR also work):

> [!NOTE]
> Useful background information and helpful context.

> [!TIP]
> Helpful advice or recommendations for better workflows.

> [!IMPORTANT]
> Information a reader needs in order to succeed.

> [!WARNING]
> Urgent alerts about breaking changes or potential issues.

> [!CAUTION]
> Critical warnings regarding data loss or destructive actions.

This is portable syntax, not a Prisment invention — GitHub, Obsidian and most other previewers render it too.

Tables

Standard GFM tables, with column alignment and rich text inside cells:

| Feature | Client-Side | Cloud Upload |
| :--- | :---: | ---: |
| Markdown rendering | Yes | Never |
| Mermaid diagrams | Yes | Never |
| KaTeX math | Yes | Never |

Use :--- for left, :---: for centre and ---: for right alignment. In the rendered pane you can edit any cell, press Tab in the last cell to add a row, and insert a table from the toolbar.

Table options appear at the table’s right edge when you hover over it in Edit, Read and Review. Move into the toolbar to use it; a short delay and a transparent bridge let you cross the gap before it hides. Like nearby element controls, it stays visible while a control has keyboard focus or a panel is open. On touch screens, tap a cell. In Read and Review, keyboard users can focus the table and press Enter to reach its controls. Open Filter to filter rows by text. Numbers sort numerically. Reset clears the filter and restores the source order. These are view choices: hidden rows are kept, and sorting never reorders the saved Markdown.

In Read and Review, the eye-off button at the end of the toolbar (Hide table options) hides the options everywhere they are offered and says so in a notice that stays until you close it, with Undo. Edit has no such button and always shows the toolbar — the row and column actions are in it — whatever you chose for reading. Header sorting in Read and Review keeps working. To bring the options back, right-click any table and choose Show table options, or turn on Settings → Markdown → Show table options when I point at a table.

Right-clicking a table always opens its menu, in Edit, Read and Review, whether the toolbar is shown or hidden: Filter (opens beside the pointer), Sort column (any cell of the column), Expand table, Copy visible rows as CSV, and, in Read and Review, Hide table options or Show table options. In Edit it also holds Align column (left, centre, right or default), Row and Column (insert, move, duplicate, delete) and Delete table; the ⋯ button on the toolbar opens the same menu. In Read and Review the menu replaces the browser’s over a table; Shift+F10 opens it from the keyboard.

In Read and Review, clicking a header cycles through ascending, descending and source order; a small filled caret points up for ascending and down for descending. Header links still open normally. If the filter finds nothing, the row count says so. In Edit, headers remain editable; right-click a header or use its Edit table menu to choose ascending, descending or source order.

Expand table opens a full-screen view with scrolling, sticky headers, filtering and sorting. It starts with the current table view; changes there affect only that viewer. Copy CSV copies the header and the displayed rows in their current order, using readable cell text and escaping commas, quotes and line breaks. The row count appears after Copy CSV as (visible of total). CSV copy is also available directly in the floating toolbar. Both places report whether copying succeeded and disable copying when no rows match. Use Close or Esc to return to the document; keyboard users can sort a focused header with Enter or Space.

In Edit, right-click a cell or open Edit table. Row inserts above or below, moves up or down, duplicates or deletes the row; Column does the same left or right. Align column sets left, centre, right or default alignment, and Delete table removes the whole table. The menu acts on the last visible cell you clicked, falling back to the header if filtering hides its row; you can also open it with Shift+F10 while editing a cell. The header row stays a header and cannot be moved, duplicated or deleted as a row; deleting the last column deletes the whole table. Structural changes clear the table's sort and filter, keep column alignment, update the source, and support Undo and Redo.

Add row appends after the last source row, including when rows are sorted or hidden. Add column appends at the right edge.

For a walkthrough with pictures, see Sort, filter and edit Markdown tables.

Task lists

Checkboxes for action items, sprints and milestones:

• Completed task item
• In-progress milestone
• Pending review

- [x] Completed task item
- [ ] In-progress milestone
- [ ] Pending review

They render as checkboxes. In Edit, click a checkbox to tick or untick it (one step in Undo); in Read the page is left as it is. You can also edit the source ([ ] ↔ [x]) or use the Task list tool.

Footnotes

A source, a caveat or a definition, kept out of the sentence's way — numbered in the order they are cited, with ↩ to go back to where you were:

The studio's fill rate was 85% that week.¹

The studio's fill rate was 85% that week.[^fill]

[^fill]: 159 of 186 places booked, given to the nearest whole percent.

• The label is yours, the number is Prisment's. Write [^1] or [^fill]; notes are numbered by their first citation, wherever they are written. A note carries on over lines indented four spaces.
• Each note shows where you write it. Written at the end, as in most documents, the notes read as a list under a rule; a note written mid-document shows there. (GitHub gathers them at the end wherever they are written.)
• A label with no note stays as typed, and a note nobody cites shows without ↩ — so a missing one is easy to spot.
• They work in an exported page too, and editing in the rendered pane keeps [^fill] in the source, never the number.

Code blocks

Fenced code blocks across dozens of languages, syntax-highlighted, with a copy button:

interface DocumentExport {
  id: string;
  title: string;
  theme: string;
}

```typescript
interface DocumentExport {
  id: string;
  title: string;
  theme: string;
}
```

The same highlighter renders fenced blocks and standalone .json / .yml files, so identical code looks identical wherever it appears.

Collapsible sections

Fold long explanations or secondary detail behind a native toggle:

<details>
<summary>Click to view configuration details</summary>

Here is the additional detailed content inside the collapsible section.
</details>

In Edit, the chevron at the left of a section's title opens and shuts it, while a click on the title's text puts the caret there to rename it; Cmd/Ctrl + Enter opens or shuts the section the caret is in, and Enter in a title moves into the body, opening it if it was shut. In Read the whole title bar toggles. Which sections you have opened or shut is a view, never written to the file — the file's <details open> changes only when you choose Default view (below) or edit the source — but it is kept: adding or deleting a section, typing in either pane, switching to Read or to another file and back all leave your sections as you left them, and a section inserted from More Tools appears open so you can write in it.

A section's options menu is on its title: right-click the bar, click the ⋯ that appears at its end when you point at it, or press the Menu key (Shift + F10) with the caret in the title. Open section / Shut section is the view; Default view is what the file says — a submenu with Open (the file reads <details open>) and Shut (<details>), the current one ticked; Remove section, keep content takes the wrapper off, the title becoming a paragraph above the body; Delete section removes the section and everything in it. Each of these is one step in Undo. Like a quote or a code block, a section is taken off with its control, not by Backspace.

Badges

An MDX-style inline badge, in four variants — primary, success, warning and danger. Useful for status labels in a spec or a release note.

<Badge variant="primary">primary</Badge>
<Badge variant="success">success</Badge>
<Badge variant="warning">warning</Badge>
<Badge variant="danger">danger</Badge>

Front matter

YAML metadata between triple dashes at the very top of a file:

---
title: System Architecture RFC
author: Engineering Team
version: 1.0.0
---

---
title: System Architecture RFC
author: Engineering Team
version: 1.0.0
---

Prisment renders it as a styled metadata card at the top of the document — collapsed, so the document opens on its title; open it with its chevron, and what you open is a view that is never written to the file — and uses name (or title) as the document's title if the file has no # H1. A list is drawn as a row of tags (tags: [booking, requirements]), a nested mapping as a small key/value grid, and a multi-line value (| or >) keeps its line breaks, so structured metadata reads as structure rather than one line of text. Only a single-line value can be edited in the card; a list or a nested mapping is changed in the YAML card (the pencil) or the Markdown source, and is always written back exactly as it was.

In Edit, single-line scalar values can be changed in the card. Only the edited field changes; unrelated quotes, comments, lists and multiline values keep their source. Strings are safely quoted when changed, and a number or boolean keeps its type when the new value has that type. Field names, structured values, multiline text, aliases and fields with inline comments are read-only in the card: use the Edit Front matter control beside the card to change the keys and full YAML, including nested lists, objects, multiline values and comments. Invalid YAML is rejected before the document changes. Clearing the YAML removes the card. The card's title is a display label.

Keyboard keys

Inline HTML is supported for the small set of tags Markdown has no syntax for. <kbd>Cmd</kbd> + <kbd>S</kbd> renders as Cmd + S.

Images and links

• Remote images (https://…) load normally.
• Relative images are resolved against the files in your workspace: an image file (.png, .jpg, .gif, .webp, .svg) is shown in the preview and travels with an export — as an object beside the Markdown source in a single HTML file, as a file beside the page in a ZIP — while the Markdown keeps the path you wrote. The pictures a Word or PDF conversion keeps work this way.
• A relative image that matches no file in the workspace is dropped, not shown broken. If an image vanishes, check that the path resolves against a file the workspace can actually see — mount the folder that contains it.
• Relative links to other documents (./docs/api.md) open that file as a tab in the app, and are rewritten to point at the exported page in an export.
• Links to a section are written as on GitHub: the heading's words in lower case, spaces as hyphens, punctuation left out — [Setup](#getting-started) for ## Getting Started, #setup-1 for a second heading called Setup, #faq--help for ## FAQ & Help. They jump to that heading in Read, with Cmd/Ctrl+click while editing, and in an exported page. A section of another document is other.md#install: the document opens at that heading.
• Size and alignment of a picture are set from its options or written after it; see Picture size and alignment below.
• Click a picture in Read to zoom in where it stands — drag to look around, Cmd/Ctrl + wheel (or a pinch) zooms at the pointer, and the zoom level puts it back. Full screen shows it alone on the screen: a photo or screenshot as large as the screen allows but never past its own size, so it stays sharp; an SVG fills the screen. There it zooms too: Zoom out, the zoom level and Zoom in sit beside Exit full screen — press the level to fit it again — the mouse wheel or a pinch zooms at the pointer, +, − and 0 do the same, and a zoomed picture is dragged to look around. Esc, Exit full screen or a click beside the picture brings you back. Copy image puts the whole picture on the clipboard as a PNG, ready to paste into a chat or a slide; a picture from another website offers no Copy, because the page may not read it. A picture from your workspace also offers Open: its own tab, in the image viewer, with Copy and Convert to PNG, JPG or WebP; closing that tab brings you back to the page. In the editor a click places the caret and shows the same options, so you can look closer while you write; a picture inside a link follows the link — unless the link is to the picture itself, the usual “click to enlarge”, which shows the same options.

Picture size and alignment

Prisment draws a picture at the size its shape suits, and lets you choose another.

• By default, a picture is never wider than the text column, never taller than most of a screen, and never enlarged past its own size. A landscape picture fills the column; a tall one, such as a phone screenshot, stands narrower instead of running far down the page; a small one stays sharp. Nothing in your Markdown changes.
• To choose a size or an alignment, click the picture and press Size and alignment (the sliders icon) in its options. Align it left, centre or right; pick Fit (the default above) or 25, 50, 75 or 100 % of the column; or move the slider for anything between. Reset puts both back. Dragging the small square on the picture's corner resizes it too, and a picture keeps its proportions whatever you do. The options work in Read and in Edit — not in Review, and not for an .html file — and the choice is a change to the document like any other: unsaved until you save, and in the undo history. Pressing the alignment already chosen clears it.
• In the Markdown, the choices are written straight after the picture, in braces:

![A booking plan](plan.png){width=50% align=center}

width is a percentage of the column (1–100%) or whole pixels (300), height is whole pixels, and align is left, center or right. Anything else in the braces — a word Prisment does not know, a bad value — is left as the text it was, so nothing is lost; the braces must follow the picture with no space. Neither CommonMark nor GitHub has a size syntax, so another tool shows {width=50%} as text; an HTML <img src="plan.png" width="300"> is the portable form, and Prisment reads it the same way. It stays as you wrote it until you edit that paragraph in the rendered pane; then Prisment writes the brace form.

The size and alignment you choose are kept in an HTML export and on a printed page, which draw the picture as the workspace does. Removing the braces, or pressing Reset, brings back the default fit. The braces are Prisment's own: another Markdown editor, or an AI tool reading the file, sees them as text after the picture, and they never touch its path or alt text.

Framing a picture for social media

A picture file's Convert button opens one dialog, Export picture, with every way to take a copy: a format, a size, a frame to post in, and the original as it is. Open a .png, .jpg, .webp, .gif or .svg and press Convert. The picture is on the left and the options are on the right; the file is made on your device and downloads when you press Save. The dialog keeps its size and place whatever you choose.

The preview is the picture on the left, with the size it will be under it. In a frame it is the file itself, with its weight; in Crop it is the same layout drawn live, so it moves as you drag, and the file is made behind it. The name is the picture's, then the frame or scale: name-portrait.png, name@2x.png. The original is not changed, nothing is uploaded and no mark is added. A small picture is enlarged to its frame. For a diagram, the same frames are in Sharing a diagram as a GIF or a picture.

How Prisment differs from other Markdown tools

Three behaviours surprise people who come from VS Code or GitHub. All three are deliberate.

A single newline is a line break

Prisment renders line one + newline + line two as two lines. CommonMark — and VS Code's preview — would join them into one paragraph.

This matches how chat output and AI-generated Markdown are actually written, and it is the behaviour most people expect when they press Enter once. It is also the single most common reason a document looks different here than in another previewer. To join wrapped lines into paragraphs, as GitHub and VS Code do, choose Settings → Markdown → Line breaks → Join into paragraphs. A document can also decide for itself with breaks: false in its front matter.

--- means three different things

The middle one is standard Markdown (a "setext heading") and catches everyone at least once. If you meant a rule, leave a blank line above it.

Some popular extensions are not supported

These are widely used in other tools, and Prisment renders them literally — they will appear as raw text in your document:

For subscripts and superscripts, use math instead: $H_2O$ and $E = mc^2$ both render correctly — or write plain HTML: H<sub>2</sub>O, E = mc<sup>2</sup> and <mark>highlight</mark>.

5. Diagrams: customize, animate and share

Every Mermaid diagram in Prisment — a mermaid block in a document (see Mermaid diagrams in chapter 4) or a .mmd or .mermaid file — is live. It pans, zooms and opens fullscreen, and it can be restyled, set in motion, presented one step at a time and shared as a GIF. None of it changes your Mermaid text: the look is drawn on top of it.

The diagram toolbar

Every diagram carries a small toolbar:

A diagram file opens edge to edge, fitted to its pane. The mouse wheel zooms, and Reset fits it to the pane again. While you type in its source pane, the diagram follows in place: its zoom, its position and an open Customize panel stay, and a line you have not finished leaves the last working diagram on screen, with a note under it that names the line.

Customizing a diagram

Customize opens a panel with three tabs. Each choice shows on the diagram at once. In a document it is written into the diagram's text as you make it; on an exported page, or in Review, it lasts while the page is open (see Defaults).

A tab or an option appears only where it changes the diagram in front of you. What each type of diagram takes was measured against Mermaid's own drawings:

Every diagram takes a canvas, and every type but architecture, C4, Sankey and packet diagrams takes a theme. Layout reaches flowcharts and class, state, requirement and entity–relationship diagrams; lines reach flowcharts and class, state and requirement diagrams under Dagre, and block diagrams; spacing reaches those and entity–relationship diagrams under Dagre; label background reaches every diagram that puts text on its lines — those and block diagrams; corners reach the rectangular boxes of flowcharts, sequence and block diagrams; weight and stroke reach every diagram with arrows. A diagram whose Mermaid text sets its own theme, view, layout, lines or spacing keeps them, and its Theme row says so rather than overwrite a palette written by hand.

Motion

Motion runs along every arrow, from where it starts to where it points:

• Packets — dots travelling the line; a longer line carries more of them, not faster ones.
• Streaks — dots with a fading tail.
• Current — a steady stream of dashes.
• Signal — a bright segment sweeping the line, one crossing at a time.

Density sets how many packets or streaks are on their way at once, and Speed runs from 0.25× to 3×. An edge whose only arrowhead is at its start — Animal <|-- Duck in a class diagram — moves toward Animal, the way it points. Invisible links (A ~~~ B) and lines too short to travel carry nothing, and message numbers come only from autonumber in your text.

While a diagram moves, Pause holds it. A diagram scrolled out of view pauses by itself, and a printed page shows it still. If your system asks for reduced motion, diagrams stay still until you choose a motion in their panel.

Colour

• Themes follow the page. A dark style offers Indigo, Ultraviolet, Cobalt, Jade, Copper and Fuchsia; a light one Azure, Fern, Apricot, Blossom and Graphite; both offer Stock — Mermaid's own look and its own colours — and Aurora, Mermaid's look with the whole spectrum swept over it. A choice is kept for each, so a dark palette never lands on a light page.
• A theme is a range of colours, shown as a bar in the panel: Copper runs from amber to rose, Jade from teal to lime, Ultraviolet from violet to cyan, Aurora across the whole spectrum. Graphite, a monochrome, varies lightness instead. Stock's bar is Mermaid's own colours, the ones it gives a sequence diagram's participants and an ER diagram's entities: with Spectrum on, a box keeps the colour Mermaid drew it in, and a box Mermaid left plain — a flowchart's nodes, say — takes the next of them, so Stock never repaints a diagram in colours Mermaid did not use. A participant's figure, lifeline and lines wear its colour in every theme.
• A diagram that sets its own colours keeps them. An %%{init}%% line or a front matter that names a theme other than Mermaid's own — forest, neutral, dark — or any themeVariables, is the author's choice, and the Theme row says so instead of offering one. A theme: default is not: it is what Mermaid draws anyway, so you can still pick a theme, which is drawn in its place (your text is not changed). On a dark page that default is drawn in the dark theme, so the lettering stays readable on Spectrum's dark boxes.
• Spectrum: Flow gives each box its colour from where it stands along the flow. Each line blends from the colour it leaves to the colour it reaches, its arrowhead takes the colour it reaches, packets change colour as they travel, and groups take a faint tint of their place. In a sequence diagram, each participant takes a colour of its own and each message blends from sender to receiver.
• Spectrum: Mosaic gives each box its own colour, with neighbours far apart; each line, arrowhead included, takes the colour of the box it leaves, and packets take the colours in turn. A diagram is drawn in Mosaic to begin with — the one way Prisment's own look differs from Mermaid's; choose Off for Mermaid's colours alone, on one diagram or as your default in Settings › Diagrams.
• Glow lays a soft light along lines and outlines, strongest on a dark style. Fill: Filled gives a box that looks empty a soft fill of its line colour, and Outline draws every box as an outline on the canvas. To begin with, the one pressed is what Mermaid draws for that diagram — read from the drawing itself, so a flowchart opens on Outline (Mermaid fills its boxes with the canvas's own colour) and a block diagram on Filled. It is listed first and stays first, and pressing it again is not a change. An ⓘ beside Theme, Spectrum, Fill, Layout, Connection points, Corners, Label background, Reveal and Trace says what the row does, in the same note every button's tooltip uses. In fullscreen the buttons float over the corner and the diagram uses the whole screen. And Canvas puts a faint grid or dots behind the diagram.

Colours are picked so every step is equally bright on its canvas: deeper on a light style, brighter on a dark one.

Shape

• Direction turns the diagram: top to bottom (portrait), bottom to top, left to right (landscape) or right to left. A flowchart, a state, class, ER or requirement diagram takes all four; a git graph takes three (not right to left); a timeline two; an XY chart stands its bars up or lays them across. A sequence diagram, a Gantt chart, a pie chart or a mind map has no direction to turn, and shows no row. Your text is never edited: the diagram's first line stays as written, and the panel opens on the direction it gives. Unlike the rest of the look, direction has no default — it belongs to one diagram — so Settings has none, and Save for all diagrams and Try Prisment defaults leave it alone.
• Views: Mermaid draws flowcharts, sequence, class, state, entity–relationship, requirement, use case, agent flow and swimlane diagrams in Neo — rounded boxes with soft shadows, and a colour for each group — and everything else in Classic, its standard drawing; the panel opens on whichever your diagram is drawn in. Hand-drawn is Mermaid's own sketch look, so it appears only on the diagrams Mermaid draws that way — every row of the table above that lists it. A sequence diagram, a timeline, a Gantt chart and the other diagrams without it look the same in every one of Mermaid's looks, so they show no Hand-drawn button, and Prisment does not draw a sketch of its own over them. Nothing is added to a diagram until you choose it: with Settings → Diagrams → Default view on Mermaid's own, each diagram is drawn as Mermaid draws it.
• Layout says how Mermaid places the boxes. ELK, Mermaid's own since version 12, runs each line at right angles between rows and keeps a group's lines tidy; Dagre, the layout before it, curves its lines and is the one Lines and Spacing work with, so those two rows appear only under Dagre.
• Stepped lines (under Dagre) run at right angles over Mermaid's layout: each leaves its box on the side facing the flow, turns between rows, and meets its target head-on, a diamond at its tip. Balanced meets a box at the centre of its side when there is one line and spreads several evenly in their destination order. Shared centre starts and ends every line at that side's midpoint; lines that converge can overlap. Where two boxes line up, a line runs straight between them; parallel runs take separate channels where there is room. A group's title steps aside for a line that passes through it. These connection points apply to Classic and Neo where Prisment routes Stepped; Hand-drawn keeps Mermaid's own steps and endpoints.
• Straight lines keep Mermaid's layout, its converging groups of three or more lines, and branches to boxes in the same row. Other connections run directly between the sides facing each other where that path crosses no box. A group's title moves aside if a new line passes through it. Hand-drawn keeps Mermaid's own lines.
• Spacing sets how far apart boxes stand, and Weight how heavy the lines are; dotted and dashed lines keep their pattern.
• Corners: Square, Soft and Round set the corners of every rectangular box, subgraphs included, never over Hand-drawn. To begin with, the one pressed, and listed first, is the corners Mermaid draws — Square on a flowchart, Soft on a sequence diagram's participants; pressing it again is not a change. Stroke draws every line solid, dashed or dotted, keeping an author's own dotted or thick lines.
• Label background is the plate Mermaid draws behind the text on a line — "go" on an arrow, an ER relationship's name. Off removes it, and the words sit on the line itself; the row appears only where a line has text to carry.

Presenting a diagram

• Reveal builds the diagram in reading order the first time it scrolls into view: row by row, each line after the box it leaves, and a sequence diagram message by message. When the build is the diagram's only animation, the toolbar's Replay plays it again.
• Trace follows your pointer: everything leading to and from the box you point at stays lit, and the rest steps back. In a sequence diagram, point at a participant to see its messages; a frame such as alt or loop stays lit only if one of those messages is inside it. Turned on in the panel, it shows itself once on the diagram, for two seconds.
• Present tells a sequence diagram one message at a time, whenever you like — it is a button, not a setting. Press the presentation button on the diagram's toolbar, on the page or in fullscreen, and the diagram shows its participants; each click, →, ↓, Space, Enter or Page Down shows the next message or note, and ←, ↑, Backspace or Page Up goes back. Home and End jump to either end. The newest message stands in a soft spotlight and is the only one that moves; those before it step back by their lines, never their words, so what was said stays readable. An else or and part of a frame appears with its first message, and where you have zoomed in each step moves the diagram to keep the message in view. The toolbar shows where you are, such as 3 / 6, with Back and Next beside it (a Shift-click also goes back). Going into fullscreen or out keeps your place; press the button again for the whole diagram.
• Pin keeps a sequence diagram's participants in view while you move around it. Like Present it is a button on the toolbar, just to its left, not a setting. Zoom into a long diagram and drag down to read the later messages, and the names would leave with the top of the drawing — so to begin with they stay at the top, over the messages that pass under them. Press Pin and they stay at the bottom instead — the bottom row Mermaid draws, or the top row shown there when the diagram has none — press again to turn it off, and a third press brings back the top. Moving sideways carries each name along with its own lifeline, and while the real row is in view nothing is drawn twice. It works on the page and in fullscreen, beside Present, and lasts for as long as the page is open.

Defaults

A choice made in the panel is for that diagram, and in a document it is written as you make it: into the diagram's own text, as a prisment: block at the top of its mermaid block (see The prisment block, key by key). So a reload shows it, and saving the document (⌘S or Ctrl+S) keeps it — there is no separate save to remember. It is an edit like any other: the document shows unsaved, Undo takes it back, and nothing is announced at each press. The block stays a few lines, since it holds only what differs from Prisment's own look; where your defaults are not Prisment's, a choice of Prisment's own value is written too, so a reload does not bring the default back. While the look is written and the document is not yet saved, the foot of the panel says Written into this document and the Customize button carries an amber dot, so you can see it with the panel closed. Saving the document clears both. Before anything is written, the foot says Changes here are written into this document. In Review mode, and on an exported page, nothing is written: the choice is for the page only. When the diagram cannot be found in the document — it changed under you — the choice is for the page only, the foot says Changed — not saved in the file, and Reset undoes it. Two other saves are in the panel:

• Save for all diagrams makes what the panel shows your default for every diagram without a look of its own. It is kept in Settings → Diagrams, so a later change there reaches this diagram too. The notice that confirms it offers Undo.
• New diagram file keeps this diagram in a .mmd file beside the document, in the look it has now, whatever your defaults become (see below).

The ⚠ at the end of the line with New diagram file is a reminder that only Prisment draws the look a text or a file keeps, the animation above all: Mermaid ignores the prisment: block, so other Mermaid tools draw the plain diagram. A diagram file's panel shows the same mark beside Written into this file. A diagram whose text already gives the look shown says Its look is saved in its text. Taking a saved look out is a step with a link of its own, Remove all Prisment look: the prisment: block leaves the diagram's text and the diagram follows your defaults again. It is an edit, with Undo in the notice at the top right, and it is the one step that removes what was written. Reset, where it appears, is a link with a ▾ that always shows what it will do before it does it: Undo my changes drops the changes made on the page that the document could not take, and returns the diagram to the look its text saves — or to your defaults, where the text saves none. A diagram file keeps every choice as it is made, so its Reset is the removal.

Settings → Diagrams holds every default, and Restore Prisment defaults there puts back Prisment's own — Mermaid's own view and layout, Stock, still — with Undo. Try Prisment defaults, at the foot of the panel, appears when your defaults differ from Prisment's. It shows Prisment's look on the page first, with Keep Prisment's to make it yours or Back to mine to return. A diagram file shows it too, its own look set aside meanwhile; Keep Prisment's — in its panel, or in Settings while the file is open — takes that look out of the file.

When choices meet, the one made on the page wins, then the look saved in the diagram's prisment: block (see below), then the diagram's own Mermaid settings, then your defaults. A direction is the exception: it has no default, so the page's choice comes first, then the block, then the diagram's first line.

Keeping a look in a diagram file

In a .mmd or .mermaid file, the panel writes your choices into a prisment: block of the file's front matter, in the panel's own words:

---
prisment:
  direction: lr
  look: neo
  palette:
    light: fern
    dark: jade
  lines: stepped
  spectrum: on
  motion: packets
---
flowchart TD
  push[Commit pushed] --> build[Build]

Mermaid ignores the block, so the file still opens in any Mermaid tool, in Mermaid's own look — and, since its first line says flowchart TD, top to bottom. In Prisment it opens in its saved look. The panel writes only what you change — what differs from Prisment's own look — so choosing Packets adds one line, motion: packets, and choosing Off again takes it out, the block with it once nothing is left. What the block leaves out follows each reader's defaults; a value of Prisment's own is written too where your defaults say otherwise, so the file keeps the look you chose.

Each choice is an ordinary edit: the tab shows it unsaved, ⌘S or Ctrl+S saves it, and Undo, Revert or a change typed into the block redraws the diagram. For a diagram inside a document, New diagram file writes it beside the document as a .mmd file, in the look it has now, named after the diagram's title or else the document. A notice at the top right says where, with Open.

The prisment block, key by key

A diagram's look can be written by hand — or by your AI tool — as well as chosen in the panel. Put a prisment: block in the diagram's front matter: the --- lines that must open the diagram, at the top of a mermaid block in a document or of a .mmd file. Mermaid ignores it; Prisment draws the diagram in that look.

```mermaid
---
prisment:
  corners: round
  spectrum: mosaic
  motion: packets
  trace: on
---
sequenceDiagram
  Member->>App: Cancel my place
  App-->>Member: Cancellation email
```

Every key, with the values it takes, written exactly as here:

• Every key is optional. One left out follows the reader's defaults (Settings → Diagrams), which start as Prisment's own. look has no one value for Prisment's own: it is the view Mermaid draws that type in — neo for a flowchart, classic for a pie chart — and a block that says that view says nothing.
• Values are case-sensitive, as written above: handDrawn, not handdrawn. true and false read as on and off.
• Nothing breaks on a mistake. A key or a value Prisment does not know is ignored, and so is a key the diagram cannot take — corners on a pie chart, motion on a Gantt chart (see what each type takes, above) — or a theme of the other style, jade under light.
• palette takes its two themes nested, as in the diagram-file example above, or on one line: palette: { light: fern, dark: jade }.
• direction takes only the ways its type can run: all four for a flowchart, state, class, ER or requirement diagram; tb, bt, lr for a git graph; tb, lr for a timeline; bt (bars up) or lr (bars across) for an XY chart. As written means the key is left out and the diagram's first line decides — flowchart LR stays left to right. The diagram's text is never rewritten: the block turns what is drawn.
• speed and density change only a diagram that moves.
• Mermaid's own front matter stays. The block sits beside keys such as title: and config:, in any order.
• The panel changes only its own keys. When it writes the block, a key Prisment does not know, a key this diagram cannot take, a comment, and the indent and line breaks you use all stay where they are; a value that already says what you chose is not rewritten. Only Remove all Prisment look takes the whole block out, whatever is in it.
• Which choice wins when they meet — the page, the block, the Mermaid text, your defaults — is under Defaults.

Sharing a diagram as a GIF or a picture

While a diagram moves, Share as GIF… in its panel makes a looping GIF of it, on your device:

The preview is the GIF itself, with its size in pixels and in kilobytes; Save GIF saves it under the document's name. Nothing is uploaded, and no mark of Prisment's is added.

A diagram that does not move offers Save as image… instead: a PNG, or an SVG that carries its own background, in the same frames.

A picture file gets the same frames — see Framing a picture for social media.

Either file is the diagram as you see it: choose its look in the panel first.

Where each works

6. Other file types

Prisment is not only a Markdown tool. Every format below gets a viewer built for it.

At a glance

OpenAPI and Swagger

A .yml, .yaml or .json file with a top-level openapi: or swagger: key is recognised as an API specification and rendered as interactive API documentation — the same thing you would get from a hosted Swagger UI, with none of the hosting.

• Browse and expand endpoints, grouped by tag.
• Search paths and operations.
• Inspect request and response schemas, parameters and examples.
• Flip between the API docs and the raw source with the YAML / JSON button in the viewer's bar (it reads API docs while you look at the source). Beside the source pane there is no button, because the source is already on screen.

It updates as you type. Edit the spec in the source pane and the documentation re-renders. While an edit leaves the spec temporarily invalid, Prisment keeps showing the last valid version with a note, rather than blanking the pane at every keystroke — and the source pane marks the line the parser objected to.

The same document is the same document in either syntax: openapi.json and openapi.yml get an identical view.

Like everything else here, this runs entirely locally — the API viewer makes no external requests and sends nothing anywhere.

YAML

A .yml or .yaml file that is not a spec — a CI config, a Kubernetes manifest, a Docker Compose file — opens as a syntax-highlighted code view beside an editable source pane.

• Edit it and save with Cmd/Ctrl + S, exactly like Markdown.
• Enter carries the current indentation forward, and Tab / Shift + Tab move a block one level — because in YAML, indentation is the grammar.
• Parse errors are marked on the offending line.
• In Read, buttons over the code offer Find, Copy, line numbers and light/dark — the source pane's own controls. The file itself downloads from ⬇ Export on the activity bar.
• Choose whether YAML opens light or dark in Settings → JSON & YAML.

JSON

A .json file opens as a syntax-highlighted, editable source view. Its best presentation is its own source, so there is no second pane duplicating it — unless the file is an OpenAPI spec, in which case it gets the API docs described above.

• Live linting marks the line of a syntax error.
• The same indentation keys as YAML.
• In Read, Find, Copy, line numbers and light/dark over the code, as in the source pane; the file itself from ⬇ Export on the activity bar.
• Its own light/dark preference in Settings → JSON & YAML.

Plain text

A .txt file opens as itself. There is no rendering step and no second pane: # TODO stays
# TODO, an indented block keeps its indentation, and a line beginning * is a line beginning
*. What you type is exactly what is written back to disk.

That is deliberate rather than a missing feature. Running Markdown over a plain text file would
mean showing you something the file does not contain — and, the moment you edited it in a rendered
pane, saving that interpretation back over your file. Log excerpts, ASCII tables and pasted
snippets survive Prisment untouched.

• Line numbers beside the text, the same surface the editor pane paints. Hide them in Read or in the editor and they are hidden in both.
• In Read, Find, Copy, line numbers and light/dark over the text; the file itself from ⬇ Export on the activity bar.
• Its own light/dark preference in Settings → JSON & YAML (under Plain text files).
• Not registered with your operating system: double-clicking a .txt in Finder or File Explorer
  still opens your usual text editor. Prisment opens one you hand it.

CSV and TSV

Data files open as a proper table, not as text:

• Sort by any column — click its header.
• Search to filter rows down to what matches.
• Row numbers that refer to the row's position in the file, so they still mean something after a sort.
• Ragged rows — rows with the wrong number of cells are shown exactly as they are, never padded or dropped, with a notice telling you how many.
• Copy from the viewer's bar (Copy preview for a partial file); the file itself from ⬇ Export on the activity bar.
• Open in default app on desktop, to hand the file to a spreadsheet.

HTML

.html and .htm files render in a sandboxed, security-hardened preview, with an Open in New Tab button.

They are read-only, and they keep their own design — Prisment's presentation styles deliberately do not reach inside them, because an HTML file is already a finished document and imposing a theme on it would fight its author's CSS. On export, an HTML file is shown in a sandboxed frame inside a Prisment page, with Copy, Download and Open in new tab; its own markup and design are left alone.

Word, PDF and Excel files

Prisment opens common office documents directly in your workspace without uploading them to external services:

• Word documents (.docx) open as a clean prose reading view — headings, lists, tables, bold/italic, code blocks, links, images, and footnotes are preserved in a continuous reading view. The file’s original page width and margins define its square page frame (Letter size if the file omits them). Zoom in/out changes the viewing scale; the reset icon beside the percentage restores the page to its original width, shrinking it when the pane is narrower. Pagination, original fonts, headers and footers are not reproduced.
• PDF documents (.pdf) render page by page in a built-in viewer, on the web and on the desktop alike. A page opens at its original size (96 screen pixels per inch, matching Word), reduced only if the viewing area is narrower. Zoom in and Zoom out change the viewing scale; Reset zoom restores that original-size view, and the percentage button toggles between fitting the whole page and 100%, and each open document keeps its zoom while its tab is open. The original is always near: ⬇ Export on the activity bar, or on the web Open in new tab for your browser's own full-window viewer.
• Excel workbooks (.xlsx, .xlsm) load with full multi-sheet tabs. You can switch sheets, sort columns, search cells, and view formatted values.
• Page cards — Markdown and MDX use a spacious reading card by default in every built-in style, filling the available reading column with 24px around it. Customize Style → Page controls its maximum width, padding, border, corners and shadow; Document: Fills the page switches to a flat layout. Word and PDF already have their own square page frames and ignore these card settings; the Page section is hidden for them. Their zoom controls change viewing size without modifying the original file.
• Open in default application — when running in the native desktop app, the top toolbar offers an Open in default app button for Word, PDF, Excel, and HTML files so you can instantly hand the file off to Word, Excel, Preview, Acrobat, or your default browser.

Converting documents

Word, PDF and Excel files are expensive for an AI tool to read: a .docx and an .xlsx are archives of XML, and a PDF's text layer arrives wrapped in running headers, footers and page numbers. Prisment converts them, in your browser, into lean Markdown or CSV and puts the result in the same folder as the original, so an assistant reading that folder finds both and takes the one it can read.

To convert: drop the file anywhere on the page (or onto a converter page such as /word-to-markdown/) and choose Convert to Markdown (or Convert to CSV) instead of Open as is; or open the original and press Convert to Markdown / Convert to CSV in the viewer's bar, which leaves the original open and opens the new file in a tab. Progress shows pages for a PDF and sheets for a workbook, and Cancel leaves no partial file. Mounting a folder never asks: those files are already on your disk.

Names carry their origin and nothing is overwritten: if report.docx.md exists the next free number is used (report.docx-2.md). In a mounted folder the file is written to disk beside its source; in a browser workspace it lives under the same path in the app's storage, and All Source Files in Export is how it comes out. When a conversion finishes, the notice gives the new file's size and an approximate token count.

What Word conversion keeps and drops. Headings, bullet and numbered lists, tables, code from a Code style, callouts from a Callout or Note style, links, bold, italic, strikethrough, superscript, subscript and footnotes come across. A conversion that loses anything starts its Markdown with a > [!NOTE] callout naming each category and a count:

What PDF conversion depends on. Tagged PDFs (what Word, Google Docs and LibreOffice export by default) carry a structure tree, so headings, paragraphs, lists and tables are read from it. Untagged PDFs have only positioned text, so structure is rebuilt: lines by vertical clustering, paragraphs by gaps and indents, heading levels by font-size rank, bullets by their leading glyph, de-hyphenation at line ends, and running headers, footers and page numbers removed when the same text sits in the same place on most pages; tables are best-effort, and the callout says when column detection was unsure. A scanned PDF has no text, so conversion stops with a message and writes no file — there is no OCR. The callout always names which of the three tiers was used. Figures a tagged PDF draws rather than embeds, such as a vector logo or chart, are kept as pictures; the drawings of an untagged PDF are not recognised.

What Excel conversion writes. Each cell is its display text as Excel shows it: 15% stays 15%, a currency cell keeps its formatting, and a date is ISO 8601 (2026-09-05, or 2026-09-05T14:30:00 when the cell carries a time). Numbers keep up to 15 significant digits, text with a leading zero stays text, booleans are TRUE and FALSE, and errors keep their Excel text such as #N/A. Formulas contribute the value Excel cached when it last saved the file and are never recomputed; a workbook saved without cached values yields empty cells and a warning that counts them. Empty trailing rows and columns are trimmed, and hidden rows are included. A merged cell keeps its value in the top-left cell, the rest are blank, and a warning counts them.

Pictures. Before a Word or PDF conversion that actually contains pictures, one dialog offers two answers: leave them out (the lean default; the callout at the top of the Markdown says how many were dropped and what they weighed) or keep them in a folder named after the document, holding the Markdown and an images/ folder, linked relatively — kept pictures become files of their own and show in the preview, in a browser workspace as well as a mounted one. There is deliberately no embed option: a 200 KB picture inlined as a base64 data URI is roughly 270,000 characters, more than a long specification, so Prisment strips any data: picture a converter emits. Remember my choice stores the answer, and Settings → Conversion holds it as Ask each time, Leave them out or Keep in a folder.

Size ceilings. A PDF over 100 MB, a Word document or workbook over 50 MB and an image over 25 MB is never read into memory: it opens as a card offering to download it, or on the desktop to open it in its own application. Legacy .doc is not supported.

7. Look & feel

Appearance is controlled in three places, and they are independent of each other.

Presentation styles

The presentation style is the publication design of your document — typography, accent colour, surface rhythm, table treatment and code theme. It is what an export looks like, and it is chosen from the Style menu (the palette button on the activity bar, or in the top bar on a phone).

Five presets ship with Prisment:

The style is baked into your exported HTML, and the exported page carries a light/dark toggle of its own so whoever you send it to can read it their way.

The style customizer

Press the sliders icon beside any style in the Style menu (or Customize… in Settings → Document Style) to open Customize Style, a panel where you can build your own style from any preset, and watch the document change as you drag. On a built-in preset it starts a new style based on it; on one of your own it edits that one. Preview in the panel footer swaps your document for a sample holding every element a style can change — all six heading levels, tables, code, quotes, callouts and collapsible sections — and a search box at the top reaches inside the collapsed groups.

A style is a delta over a preset, not a stylesheet. You store only what you changed and inherit the rest, so a style of six changed values is still a complete one, and improvements to the preset still reach it. Four layers decide what a document looks like, and your style is the last of them: the base (structure and spacing, no colour), the light or dark scheme (every colour, once per scheme), the preset's own delta, then yours.

At the top, General (open by default) holds the style's name, an optional description, and Start from, which swaps the preset or saved style underneath your changes. Save (or Save as new style) is in the footer, with Reset and Delete. Below it the controls are grouped into seven sets, each collapsed until you open it:

• Page controls stay together in order. Layout sets the document mode and outside space; Behind the card sets the colour and pattern around a card; Card size and corners groups width, maximum width, padding and corners; Card border groups its weight and color; Card shadow groups its strength, angle and color. Search also matches these subsection names.
• Light / dark swaps the whole palette, not just the page background: page, panels, borders, code, secondary text and the header chrome all move. It is how you get "Sapphire Spec, but dark", and every other control then resolves against the palette you chose.
• Workspace chrome and panels have separate colour controls. Under Base colors, Workspace chrome changes the left icon rail, the title header, tab strip, toolbars, menus and utility dialogs, using the exact color shown in its picker. The inherited tint is already shown in the picker; choosing white produces white chrome. Hover and selection keep their own cues. Workspace panels changes the inner Files, Source Control and Knowledge panels — the logo and workspace name at the top of Files included — plus the Review dock and AI panel, together. Either can be reset independently to the style’s light/dark surface. Neither changes your document page. Folders, files and selection retain their familiar blue marks. Body and secondary text and borders also shape the interface. Files, Review and AI share the same softer workspace border colour for panel edges and dividers, keeping the lines above and below Files visible. The Borders control changes them together; document borders retain their original strength. Workspace text size is in Settings → Interface.
• One accent colour sets six values. From the colour you pick Prisment derives the accent itself, a button and chip fill, a darker step for hover, a soft translucent tint for backgrounds, a stronger step for emphasis, and a contrast colour for text sitting on the accent — white or near-black, chosen by contrast arithmetic. A pale yellow accent gets dark text and a navy one gets white, so an unreadable chip is not a state you can reach.
• Each heading level has four controls. Decoration is plain, underline, left rule, left rule and underline, box or accent bar. Colour is heading colour, accent, body text or secondary text. Size is smaller, default, larger or largest, relative to the base scale. Numbered step puts a numbered circle or square before the heading, the pattern Stepped Guide uses.
• Content background is what the text sits on. It colours the card when the document is one, the whole reading area when
  the document fills the page, and the Index column beside it — nothing else: not the margin around the card (that is Page › Behind the card › Color),
  not the panels, not the app. Until you set it, it is the style's own: most styles lift it a step off Page background and
  follow it; Dark Mode sets it to #090c0f, a whisper above its near-black page.
• Document panels and tables colour the document only. Document panels colours collapsible sections, front matter and cards; code blocks follow until you choose their own background. Tables have their own section. Neither control changes the sidebar, tabs or dialogs. Page background moves the style's inherited surfaces, while explicit Workspace chrome and Workspace panels colours stay independent.
• The shadow angle turns every container shadow — 0° is up, 90° right, 180° (the default) down — Shadow angle and Shadow color stay greyed out, with a line saying so, until Shadow is above None — the same goes for the banded row colour until rows are banded.
• Card settings apply to Markdown and MDX. Word and PDF already use their own square page frames, independent of the Page group. The Page section is hidden while either format is open, including its style sample. Word and PDF use zoom controls to change viewing size. Saved styles and HTML exports keep this format policy.
• Card decoration is independent of Containers. Its border and shadow colours use the same palette choices and follow light/dark. Card shadow angle uses 0° up, 90° right, 180° down and 270° left. At None, its shadow angle and colour stay greyed out with a hint; container shadow settings still affect only the boxed elements inside the document.
• Markdown/MDX cards are the default in every built-in style. They fill the reading column with 24px outside spacing, a subtle border and a soft shadow. Card max width starts at No limit; lower it for a narrower reading measure. Choose Fills the page for a flat layout.
• A card stays consistent while editing. The document sits on the same card in Read, Review, the HTML editor, the rendered side of Split and an exported page. On a window narrower than 768 px and on paper, it lies flat. The space around the document works the same way in every style, so a style that fills the page can be given room at its sides; around a card, that space is the whole gap between it and the window's edges — at 0 the card meets them — and the card never grows past its width. The background and the card's sliders stay greyed out until Document is Card. The card is the style's surface; the background behind it starts a step darker than the page on a dark style and greyer on a light one, so the card reads as a sheet even where the surface is the page colour, and its pattern takes the border colour. Dark Mode is the exception: its card sits above its page, so the background behind the card is exactly the Page background you set — pick black and the margin is black — and Behind the card › Color says Same as Page background until you set it. To colour the card itself, use Content background.
• Every control offers from base, the default. Leave it there and the control keeps resolving against the preset underneath.

Saved styles appear in the Style menu alongside the presets. A saved style keeps a frozen copy of the preset's values, used only if that preset is ever retired or the style was based on another saved style. While the preset exists, its improvements still reach every value you haven't changed, and hiding it from the Style menu changes nothing.

Styles can be exported and imported as .json files — Export on a style in Settings → Document Style saves one, and Import a style file… in the same place brings one in — which is how you share one with a teammate, or move it between the browser and the desktop app. A style also travels inside every HTML page you export, so the person who opens it sees your colours and fonts without ever opening Prisment.

App theme, text size and Focus Mode

• App theme — the light/dark look of Prisment's own pages (home, Help, Blog, Download), set with the sun/moon button in their header. Inside the workspace the sidebar, bars and dialogs take their colours from the presentation style, so a dark style gives dark chrome.
• Text size — Settings → Interface sets two sizes: the workspace (sidebar, tabs, menus and dialogs) and the document. They can be linked or set separately. The document size travels with an export, and the exported page keeps a control of its own.
• Focus Mode hides the top bar, the activity bar and the sidebar and goes fullscreen, leaving just the document. The document index stays, because it belongs to the document rather than to the chrome. Press Esc to leave, or move the pointer to the top edge (or press the Tap for Menu / Exit badge) to bring the bar back and press Exit focus mode.
• The Index drawer — any document with headings gets an interactive table of contents. It is hidden by default; the Index button opens it as a left column on desktop, or a drawer over the page on mobile. Every heading from # to ###### is listed as a tree: a heading's deeper headings sit under it beside a guide line, and a chevron on each parent folds them — what you fold stays folded while you edit that file. A lone # at the top is drawn as the title, with the sections below it. As you scroll, the entry for the heading you are in is highlighted (a folded parent is highlighted while you are inside it), and the Index scrolls to keep it in view. Click any entry to jump; if the heading is inside a collapsible section, the section opens. The column is the colour the text sits on — Content background — in every style, so it reads as the document's own column. Exported pages carry the same index, with the same folding and highlight.

Settings

The Settings dialog is organised in three groups. Everything in it applies to this device — nothing syncs between browsers, machines, or between the browser and the desktop app.

Import & Export writes a settings file you can carry across. You choose what goes in it:

• Document styles — every custom style you have saved.
• Preferences — selected style, Style-menu choices, appearance, language, and Markdown line-break and table-options choices.
• Mounted folder history — export only. Folder access is granted per machine, so these can be listed but not restored; re-open them with Open Folder.

8. Local AI that reads your whole workspace Desktop only

Everything so far is about one document. These three features are about the folder — what is in it,
how it hangs together, and asking questions of it.

The tag belongs to the assistant, which is the headline here: it runs in the desktop app only.
The workspace index, its graph and context packs run in a browser as well — two of the three features need no AI at all: they work with nothing
installed, and what they produce is useful to any tool you paste it into. The table below is that
difference in one place.

Two systems, and which is which

They are separate things that happen to sit near each other. Knowing which one you are using tells
you what it needs and where it runs.

The assistant writes nothing you cannot undo or delete, and neither system sends your documents
anywhere (see Privacy in section 11).

The rest of this section is those two systems in the order you meet them.

How a question actually gets answered

Worth ninety seconds, because almost every surprise with a local assistant comes from not knowing
which part did what.

1. You ask in plain language. No commands and no syntax. Typing @ offers file names to pick from, but you never have to.
2. Prisment finds what matters. It searches the map of your folder — which document links to
   which, what each file is about, what a source file declares — and picks the files most likely to
   hold your answer. This part is Prisment, and it works the same on any model.
3. It makes them fit. Your model can only read so much at once. The closest files go in whole,
   then the passages that matched, then an outline, then a path and a line — and the panel tells you which was which.
4. Your model reads and answers. This part is your model, and it is where a small one shows.
5. It can go and look. If what it was given is not enough, it asks to list a folder, search, read
   a file, check what links to something, or review the workspace for broken links and unlinked documents — and it does that while answering, up to four times.
6. It shows its working. A line above each answer says what it read; Context opens the full
   list, including what was left out.

The short version: Prisment decides what your model sees. Your model decides what to say
about it. A better model gives better answers; a bigger context window lets it see more at once.

Does the index help, and is it worth it?

You never have to build one — the assistant reads your folder on its first question of a session,
and that is the Reading your workspace… pause. Opening Workspace Knowledge on the activity bar
does the same work and keeps the result.

It does not make answers better — it makes them faster to start, and it unlocks the graph,
search and the two copy tools, which are not the assistant at all. If you never open Workspace
Knowledge, skipping it costs you a second per session.

Prisment keeps the map current by itself: it checks the folder before each question, after you save,
and when you come back to the window, so a branch switch in another tool is picked up.

Workspace Knowledge

Choosing Workspace Knowledge on the activity bar reads every file in the folder and builds a map of
it: which document links to which, what mentions what in prose, what each source file imports and
declares. It takes about a second on a large repository.

What you get, in the Knowledge view and the Workspace Graph that opens beside it (Open graph):

• Search across every file — type in the graph's search box: by path, by heading, by a declared
  function name, or by the text of the documents themselves. Pick a result to centre the graph on it;
  Open (or Enter, or a double-click) opens it.
• What references this file — select a file and the bar below the graph shows referenced by N ·
  references M; the links we inferred from a sentence are drawn dashed.
• Nothing references these — the Orphans chip shows or hides documents nothing in the workspace
  points at. Often the ones that quietly went stale.
• Broken links — a written link that resolves to no file. They are listed in Export workspace
  map, and the assistant checks them when you ask. Prose mentions are not reported here: a
  filename-shaped word in a sentence is our inference, and reporting those would bury the real ones.
• A picture of it, as a graph you can click through, with Documents only, Arrows, Top Hub
  and Active Doc.

Where a workspace has two or more folders, Folders Knowledge covers lets you Include or Leave
out each one.

Nothing is written into your folder. The desktop app keeps what it read in a cache on this
computer, so the next time the folder is opened only the files that changed are read again; a
browser tab keeps the index until you close it.

Used Prisment before version 1.2.1? Earlier versions wrote a .prisment/ folder into the
workspace — the map as graph.jsonl, and a small query script — and, if you installed it, an agent
skill in .agents/skills/ or in Claude Code's skills folder under .claude/, and a block in AGENTS.md. Nothing reads any of it
now, and nothing keeps it up to date. Prisment leaves all of it where it is and does not mention it
in the panel; delete what you do not want yourself.

Generate Context Pack

A context pack is your workspace, compressed to fit a model's context window, as one document
you can paste anywhere — Claude, ChatGPT, a coding agent, an issue.

Prisment fills about 8,000 tokens by relevance rather than alphabetically: the most relevant
files arrive whole, then the passages that matched with their line numbers, then an outline plus the
first sentence of each section, and the rest as a path and a summary line. It tells you what it reduced and what it left out, because a silently
truncated context produces a confidently wrong answer with nothing to notice.

• Credentials are scanned for and withheld before the pack exists — a .env, an AWS-shaped key,
  a private-key block — and the pack names what it held back. Published documentation placeholders
  are allowed through.
• A pack goes to your clipboard and nowhere else. Nothing is saved into your folder — a pack is
  document content, copied, and you decide where a copy of it lives. Generating another takes a press.
• Export workspace map is the smaller sibling: the shape of the workspace as a Markdown
  document, on your clipboard. Nothing is written to disk.

The local AI assistant Desktop only

Desktop app only, and off until you turn it on. It talks to a model running on your own
computer — Ollama or LM Studio — over a loopback connection that cannot reach anywhere else: there
is no address field anywhere in the app, and the code refuses any destination that is not your own
machine. The one other way out is a web page you allow: a link you type is read only after you say
so, and every new page asks (see What the assistant will not do below).

How it finds what to read, and what to expect from a small and a larger model, is in
Introducing the Prisment Local AI Assistant.

In Settings → Local AI, switch it On, press Detect, then Use this on the server it finds
(the ⓘ shows the steps). Then the Assistant button opens a panel on the right.

• It looks things up for itself. The assistant is not handed a fixed bundle and left to guess:
  it can look through a folder, search your files, read one, check what links to it, and review the workspace for broken links — and it
  does that while answering, as many as four rounds of it. Every lookup runs on your computer,
  against files the index already knows about, and nothing else is reachable.
  There is nothing for you to type. You ask a question in plain language; the assistant decides
  what it needs and tells you what it looked at, in a line above its answer.
• Every answer says what it was based on. Open Context on any reply to see the exact files —
  and how much of each — that went to the model, and the line above it shows what the model went and
  looked at, in the order it asked.
• An answer with nothing behind it says so. If no file matched your question, the reply is
  marked rather than presented as though it came from your documents.
• It can change your documents — not only the one you have open. It can edit any Markdown, text,
  YAML or SVG file in your workspace, write a new one, add a section to a long one, rename a file or
  folder, and delete a document. Source code is read-only: it reads your .ts, .java or .py
  files and writes what it learns into a Markdown file, never into the code.
• Ask or Edit, and where it reads. Above the box, the Ask / Edit switch decides whether a
  question may change files. Sources limits what is read: Workspace, Open document or
  Selection — and a selection only ever answers, it never changes files.
• How a change lands is your setting. The gear's Document changes chooses: Apply directly
  (the default) writes it and shows the diff with Undo; Review first waits for Accept; Plan
  first shows a to-do list and waits. Renaming and deleting always ask, whichever you choose.
• Every change is a diff, and every change is one press from undone. A rename shows you every
  link it will repair before anything moves. A deletion always asks first, whatever your review
  setting, and the file's text is saved to this computer before it goes — so Undo brings it back,
  and so does the file's own history afterwards.
• Several changes at once become one question, not a pile of cards. Ask for the same fix in
  three files and you get one card listing all three: apply all of them, apply just one, or type
  what you actually wanted in the Other box and the assistant picks it up as your next message.
• Memory, shown and controlled. The panel reports what the model is holding and what your
  machine has free, and under pressure it offers to unload the model, use a smaller context, or
  switch to a smaller model — each saying what it costs you. Nothing happens without a press.
  Keep the model in memory, behind the gear, stops it unloading between questions.
• The app checks every answer. Under it you may see Sources: path (lines 17–18), or Not found
  in the supplied sources for a figure no supplied line contains.
• The assistant can see the conversation. Follow-up questions work — "and how many of those
  are still open?" — and so do questions about the conversation itself. Earlier turns are sent
  with each question, up to what your context window can hold; when a long chat outgrows it, it is
  folded into a summary automatically (Summarise long chats, on by default; turn it off and the
  panel says how many turns fell off the front and offers the summary instead).
• Conversations are kept on this computer, in a database and not in your folder. The last 60
  turns of your ten most recent chats — Where Prisment keeps things, in section 11, says where.
  Clearing a conversation deletes it. Nothing about a chat is written into the folder you mounted,
  so nothing about it can be committed by accident.

What your model can do Important

The model is yours, and its size decides what the assistant can do with it. Prisment does the
retrieval — finding the right files, fitting them in the window, keeping your conversation — but the
thinking is your model's, and a small one cannot do everything a large one can.

✅ works · ⚠️ sometimes: it may leave a section out, guess, or say it did something and not do it

Measured in September 2026 against llama3.2:3b and qwen2.5-coder:14b. A 7–8B model generally
sits between the two. Models improve; if yours does better than this table says, trust your model.

⚠️ does not put your files at risk. When a small model gets a change wrong, the change is
usually refused — Prisment only edits text it can match exactly in your file, so a model that
guesses mostly gets "could not apply that" rather than a mangled document. And a change that does
land is always shown as a diff, one press from undone, so a wrong one is never quietly kept.

Ask in the language the document is written in, whatever your model. Prisment finds files by
the words they share with your question, so a question in English can miss the answer in a Spanish
document — the assistant then says it cannot find one rather than making one up.

Quote the words you want changed. Change "three times" to "five times" in docs/networking.md
tells Prisment exactly what the file should say afterwards, and it holds the model's edit to that:
if the edit does something else, Prisment makes the change you spelled out instead. In our trials
with a 3B model and a file that was not open, a quoted change landed every time, and a paraphrased
one nearly always. Quoting is the part that does not depend on the model.

Picking a model

We recommend a 14B model — qwen2.5-coder:14b is the one the assistant was checked on before
it left beta, at the 8,192-token window Prisment asks Ollama for. If the panel offers a
smaller window to save memory, answers can slip. Where memory will not allow a 14B, the rule is
how much you can spare:

The panel shows what your machine has free and what the model is holding, and offers to unload it
when you need the memory back. Nothing is downloaded by Prisment — you install models yourself,
in Ollama or LM Studio.

What the assistant will not do, whatever your model

These are decisions, not missing features:

• It cannot run commands. There is no shell, no terminal, no script execution. It reads and
  writes documents, and that is all it can do.
• It cannot write source code. It reads your code and documents it in Markdown.
• It reads the web only when you let it. A link you type into a question is read only after you
  allow it, in a window the app itself shows: Allow Once, Allow in This Chat or
  Allow in This Workspace — that page, or its whole site with the box ticked. If you don't allow
  it, or the page can't be read, the question is not sent: it comes back to the box with the reason,
  rather than being answered without the page. Once read, a page stays with the chat: later
  questions get it back from memory, without asking again or fetching it again. Links inside your
  documents are followed only with Follow links in documents on, behind the assistant's gear and
  off by default, and each new page still asks. The request carries the address and nothing else,
  with no cookies and nothing from your files. An address the assistant wrote itself is shown to you
  in full and can only be allowed as that exact page. The model itself never leaves your machine,
  and the web version has no assistant at all.
• It does not guess between folders. With several folders open, it names a file with its folder
  first (Docs/README.md); a name two folders share, given without its folder, is refused rather
  than applied to either.
• It cannot see anything outside the folder you opened.
• It cannot delete a folder — one document at a time, and it asks every time.

Set the reading window with the Context button in the assistant panel, beside Send. On
Ollama, Prisment loads the model at 8,192 tokens and the control goes up to what the model supports;
the choice is remembered per model. A bigger window reads more of your folder — the difference
between a pack of two files and a pack of twelve — but uses more memory. LM Studio decides its own
window when you load a model; Prisment assumes 4,096 until told otherwise. Setting it too high is
safe: the reply says it was truncated rather than quietly presenting a partial answer as a complete
one.

You do not have to build the index first. The assistant reads the workspace itself the first
time you ask something — that is the second or two of Reading your workspace… on your first
question of a session, and nothing is written to your folder doing it. Workspace Knowledge does
the same reading on a press, and opens the panel with search, references and the graph.

9. Reviewing documents

A review is how you check documents before they are acted on — most often an AI tool's plan before it
is built. You comment on passages, decide what Prisment's checks found, and approve the exact versions you
read. When the documents change, the review shows what changed and asks again. It needs no AI model, no
account and no network, and it never changes your documents on its own.

Beta. Reviewing is new and wears a Beta mark. It is safe to use and may still change.

Reviews are saved in a folder workspace — a Git checkout is one. In a browser workspace, Review asks you to open a folder and leaves you in Read or Edit.

Start a review

1. Open a document and choose Review beside Read and Edit. The review panel opens on the right.
2. Name this review — a name is suggested (Review and the date). The first time, also type Your name;
   it is shown beside your comments and is not verified. Press Start review.

Every comment you add goes into the review named at the top of the panel, across all of its documents.
Or continue a review opens one you already have; Or import a review reads a copy someone sent you.

No document open? When the folder already holds a review — yours, or one a colleague pushed or synced — the header
offers Read · Review with no file open. Review opens the whole review: every document's feedback, the documents it
covers and its details. Each card names its document; press the name (or the quoted passage) to open that document in
Review, at that passage, with the card open. To start a new review, open a document first.

Comment

• On a passage: select the words. The same toolbar appears above them — Comment, Flag an issue,
  Suggest removing text, Mark as reviewed (recorded at once) and a cross. Comment, flag and removal open a
  note; type, and Add comment (Cmd/Ctrl+Enter). The passage stays highlighted and a marker sits in the margin
  beside it. On desktop, Review keeps a little space between the page and the feedback panel for these markers.
• On a diagram, picture or code block: point at it (or tap it). A small toolbar appears on its top edge, and each button records a
  different kind of feedback: Comment (the speech bubble) opens a note; Flag an issue (the amber flag) opens a
  short list — Clarify, Missing detail, Needs a decision, Out of scope, Contradicts another document — and the one
  you choose labels the note; Suggest removing text (the red bin) proposes that the block be cut, with your reason;
  Mark as reviewed (the green thumbs-up) records at once that you read it and found nothing to change, with nothing
  to type; the cross closes the toolbar and records nothing. Suggest change, which gives replacement wording, is in
  the note's type menu once a note is open.
• On a table: a table has no toolbar. Point at a row and a comment button appears beside it, just outside the
  table on the left; press it, or click (or tap) the row, and choose the row (Table row 3) or Whole table.
  Nothing is drawn over the row, so dragging across a cell still selects its words.
• On the whole document: Comment on document. The panel names the document these go to — its name, with its folder
  after it — and a draft says Whole document · big-picture.svg, so a comment is never filed on a document you did not mean.
• On the whole review: Comment on the whole review, for feedback that belongs to no one document (the product needs an
  Advertise page). It is labelled Whole review, has no document to go to, and is listed under Entire review — and in the
  review you open with no document. It is not under This document.
• Feedback type turns a comment into Suggest change (with new wording), Suggest removing text,
  Flag an issue or Mark as reviewed.

Comments on passages, diagrams, pictures, code blocks and tables are available in Markdown and plain-text files.
Any other file takes Comment on document and Mark reviewed; where there is no text to select — a picture, a diagram file, YAML —
the panel says the document is commented on as a whole.

On a card: Resolve settles it, Reply answers it, Acknowledge settles it without a change, and ⋯ has
Edit and Delete on comments you wrote. A deletion offers Undo; ⋯ › Undo last change (or Cmd/Ctrl+Z outside a text field)
undoes a feedback action, even after a reload. If the document changes and a quote can no longer be placed with
certainty, its card says File changed and keeps the original quote — a comment is never moved to a guess. A
Document reviewed mark on a version of the file that has since changed says Earlier version. The note above the list
counts both (1 feedback item refers to an earlier version); the amber tail on a card shows which, and your original
feedback is always kept.

Mark reviewed records that you read this saved version of the document. It turns green; if the document
changes it offers Mark reviewed again. Reviewed is not approved, and an issue you flagged stays red until resolved.

The review panel

• The title is a dropdown of your reviews — closed ones under a Closed heading after the rest — and All reviews at its
  end. + starts another review on that line.
• ⋯ holds View user, Rename review (the person who started the review), History, Open review
  window, Undo last change, Close review… (or Reopen review) and Delete this review…. × returns to Read; it
  never closes the review.
• The line under the title says where the review stands: No feedback yet, In review, Changes requested,
  Ready to approve, Approved for … or Approval lapsed — or, once it is closed, Done or Cancelled and the day.
• Feedback · Documents · Details — one section open at a time. Feedback lists comments — Open, All
  or Settled, for This document or the Entire review, in document order, newest first or oldest first; Documents lists what the review covers, with open comments; Details holds
  what is needed to approve (below). In Entire review, a card on another document names it under its title (with
  several folders open, the folder's name first) — press it to go to that passage.
• New marks a comment — or New reply a reply — that reached this computer since you last looked, whatever day it was written:
  a colleague's file can arrive hours late through Git or a sync app, and it would otherwise sit unnoticed in the middle of the list.
  The Feedback section says 2 new since you last looked, with Show when some are outside what the list shows and Mark as
  read; opening a card reads it. What you wrote is never new, and nothing is the first time you open a review on a computer. While
  you read or edit with the panel closed, the Review button counts what is new — a dot and the number. The review you last had open
  is read in the background from a few seconds after Prisment opens, so the count is there even before you press Review.
• Older Prisment: Ben. Ask them to update. says that a colleague's file was last written by an earlier Prisment (before 2.0.14).
  Until they update, their screen does not show a review closed by someone other than its starter, or a comment an AI tool marked
  Fixed or Implemented — and if the review is deleted, their copy can bring it back. Hover it for that. It goes once their Prisment
  writes the review again.
• The foot says Saved in the folder and the time, with Sync beside it, and holds Share. Sync reads the folder now —
  Prisment also does every 15 seconds and when you come back to the window, and — in the desktop app, Chrome and Edge — the moment a
  review file in the folder changes, so a colleague's reply shows as soon as Git or your sync app brings it. In the desktop app, in a Git folder whose branch is on the
  remote, it is Sync with Git: it brings in what others pushed, commits the review's own files on top (never your documents),
  pushes them and reads the folder again — one press for both directions. Review files never conflict, since each person writes only
  their own, and Sync never makes a merge commit: what others pushed comes in as a fast-forward first. If you have commits of your own
  waiting and the remote moved too, Sync merges nothing of yours — it says so, and you bring the two together in Source Control. With
  commits of your own waiting, Sync commits the review's files but does not push: a push would publish your commits too, so you push
  from Source Control when you are ready, and the review goes with them. If git refuses anything else, the foot says why in one line,
  with Open Source Control. Once pushed, the foot says Synced with Git and the time. In a browser, pull with git first.

Decide and approve

Prisment reads the documents and runs structural checks. They say what is there, never whether a design is right:

Details › To decide lists them. Decide each — for example Intentional or Needs work (a change is Accepted).
Underlined broken links can be fixed in place: click one to see possible files, then Suggest replacement
(adds feedback) or Update link (changes the open document — then Save).

Approve for says what an approval permits next: Design, Task planning, Implementation, or Something else
(you name the step). Only Implementation tells an AI tool it may build. The decision it supports is a line of
purpose; both are saved with Save, by the person who started the review. The button reads Approve for
, and is offered once nothing is undecided,
nothing needs work and no comment is open; until then the panel says what is holding it back. Approval reads
the documents once more and approves exactly those versions. If one changes later, the review shows
Approval lapsed. Withdraw approval takes it back. Compare from now makes today's documents the new
starting point without approving anything.

History (in ⋯) lists every approval, decision, comment and link change, newest first, with View edit
for changed wording and an undo for each action that can be undone without replacing later work.

Close a review

When a review is finished — or stopped — anyone in it closes it from ⋯ › Close review…:

1. Keep Done (the review is finished; whatever it approved still stands) or choose Cancelled (the review was stopped; it
   approves nothing while it stays cancelled, and AI tools are told not to proceed).
2. Add a Note if you like — why it ended, or where the work went.
3. Press Close review. Open comments do not stop you; the panel says how many are still open, and they stay as they are.

A closed review is kept, not deleted: the line under its title says Done · 14 Oct (or Cancelled), and the panel says who closed it,
when, and the note. Nobody can comment, reply, settle, decide or approve in it — you can still read it, look at its History, share it,
rename it or delete it. To change it again, choose ⋯ › Reopen review: everything comes back as it was. Anyone in the review can close or reopen it — the panel names who did;
an AI tool cannot. When the person who started the review cancels it, their approval is withdrawn too, and reopening does not bring
it back: they approve again with Approve for …. When someone else cancels it, the approval only stops counting while it is
cancelled. In a shared folder, colleagues see it closed after the folder updates. A colleague on Prisment 2.0.13 or earlier still
sees it open when someone other than its starter closed it; on 2.0.10 or earlier they see it open whoever closed it (and any approval
withdrawn), and are told part of a file could not be read. If the folder has the review skill for AI tools, Share ›
AI tool shows Update available: update it so the tool's checker knows a review can be closed.

Share

Press Share at the foot of the panel (or the Share tab of the review window).

Review folder. A review is saved in the folder it reviews, so whoever can open that folder can see it —
Prisment does not decide that; the folder does. The card says only what Prisment knows: who has replied, whether
the folder is a Git repository (and has a remote) or, in the desktop app, inside OneDrive, Dropbox, Google Drive,
iCloud Drive or Box, and who decides. Otherwise it says the review is saved on this computer.

• A synced folder (OneDrive, Google Drive, Dropbox…): colleagues who open the folder in Prisment see the
  review under Shared reviews and can reply. Their replies arrive when your sync app delivers them; Prisment
  reads the folder when you return to it, every 15 seconds and — in the desktop app — the moment a review file changes, or press Sync at the foot of the panel (Refresh now here).
  What arrives is marked New.
• A Git folder: in the desktop app, Sync with Git at the foot of the panel commits the review's files, brings in what
  colleagues pushed and pushes yours; or use the Git tab, or Source Control (Open Source Control is on the card).
• Everyone may comment, reply, and close or reopen the review; only the person who started the review decides and
  approves. A decision or approval from anyone else is ignored and reported. Prisment says Saved in the folder, never Sent — it sees
  that it wrote the file, not when the file arrives elsewhere.
• If your sync app skips hidden folders, press the ⓘ beside Review folder and choose Use a visible
  folder: it uses reviews/ instead. The same note shows the exact file and who decides.

The panel is a strip of tabs — Folder, AI tool, Copy and Git — so you see one
job at a time. Folder is the card above, with Refresh now and, for a Git folder, Open Source Control, and below it
your name with View user (Settings › You: your name, your ID and the computers you have linked). Each tab's section has an ⓘ beside its name; press it for the explanation, press it again to put it away.

AI tool — Give it to your AI tool. Copy for AI puts the comments, the decisions and the exact file paths on the
clipboard as one message to paste (the eye button, Preview, shows it first). Under it, Install skill saves the review skill in the
folder (.agents/skills/prisment-review/, in the open Agent Skills format): instructions, a small program the
tool runs with Node, and the list of reviews it reads. An AI tool that reads skills can then read everyone's comments, check the approval
and the document versions before it builds, and mark a comment Fixed or Implemented once it has changed the document (see For AI tools reading the review). After
you copy, installing becomes the suggested next step. Anyone who can write to the folder can change the skill, so protect it like your
code. Prisment reads the folder, so it tells you what is there — a badge on the row reads Not installed, Installed, Update
available or Newer version — and offers the one button that fits: Update skill for an older one, Add this review when the
skill reads other reviews but not this one (the others stay). A skill a newer Prisment installed is left as it is. The ⓘ says what the
skill is for, and What gets saved lists the files.

When Prisment changes the skill. Opening a folder whose skill came from an older Prisment shows a notice at the top right — The review
skill for AI tools in "folder" is from an older Prisment — with Update. Nothing in your folder changes until you press it; the update
keeps every review the skill reads. The notice comes once per folder for each version; Share › AI tool still says Update available
after that.

Copy — Send a copy. Download saves the whole review as one Markdown file to attach to an email or a message.
It includes feedback and quoted passages, not the documents — send those separately. Copy text puts the same
file on the clipboard, and the eye button (Preview) shows it exactly. When they send their copy back, Import feedback
previews and merges it. The ⓘ shows the steps: the recipient opens the documents in Prisment and chooses
Or import a review. Save a copy in this workspace writes the file into a folder you opened: with several folders open,
choose which one first (with one, its name is simply the start of the path); a file that is already there is replaced only after you confirm.

Git — Commit and push this review. Only for a folder that is a Git repository; anywhere else the tab is greyed out and
says Not a Git repository. In the desktop app it shows the branch and the review's own files that changed, with a message
ready (Review “name”: feedback from you). Commit & Push commits exactly those files — never your documents or any other
change — on top of what others pushed, which it brings in first as a fast-forward, and pushes, so a colleague who pushed before you
no longer makes it fail and no merge commit is made; Push sends commits that are waiting. There is no Commit on its own: a commit that is not
pushed stays on this computer and shares nothing, so with no remote the tab says so and leaves it to Open Source Control. If
other changes are already staged, it says so and leaves them to Open Source Control too. If git refuses (no permission, a newer
remote…), it says what happened and what to do, as Source Control does. With several folders open, it uses the repository of
the folder that holds the review. In a browser, which cannot run git, the tab gives the commands to run in that folder — add,
commit, pull and push — with Copy commands.

Private at the foot: nothing is uploaded to Prisment. Prisment has no cloud storage and no accounts; it
writes only to the folder you opened, which Git or your shared drive carries.

Review through Git, step by step

A review in a Git repository travels with the documents it is about. The person who starts it:

1. Opens the repository as a folder and starts a review as above.
2. Presses Share at the foot of the panel. For a Git folder the card says so — with a remote, that you commit and
   push to share — and Open Source Control is on it.
3. In the desktop app, presses Sync with Git at the foot of the panel — or Commit & Push on the Git tab of Share,
   or opens Source Control, writes a message and chooses Commit & Push. The review's files under .review/ go with the documents; each computer's
   private folder is kept out by .review/.gitignore.

A colleague:

4. Pulls (Pull or Sync in Source Control, or their own git tool), opens the folder in Prisment and chooses the review
   under Shared reviews — no document needs to be open: Review is in the header as soon as the folder holds one.
5. Comments and replies, then presses Sync with Git (or Share › Git › Commit & Push), which commits and pushes their own file.

The person who started the review presses Sync with Git — or pulls and presses Sync — and the replies appear, marked New.
Everyone may comment, reply and close; only the starter decides and approves.

With OneDrive, Google Drive or Dropbox instead of Git: keep the project folder inside the synced folder your team
shares, and everyone opens it in Prisment. Steps 1, 2, 4 and 5 are the same, and step 3 is not needed: the sync app
carries the files. Prisment reads the folder when you return to it and every 15 seconds, or on Sync; how long
a file takes to arrive is up to your sync app, and a reply that arrives late is marked New wherever it falls in the list. If it skips hidden folders, press the ⓘ beside Review folder, then
Use a visible folder — it saves the review in reviews/ instead.

In a browser, Source Control is read-only, so commit and push with your own git tool — the Git tab of Share gives the
commands — or the desktop app. Prisment says
Saved in the folder, never Sent: a reply arrives when it has been pushed and pulled. A review is as private as the
repository — whoever can read the repository can read the review. The same steps, with pictures:
the blog article.

Where a review is saved

In the folder, under .review/ — hidden from your file list unless Settings › Review › Show review files in
my file list is on. Each computer keeps its own files and never changes another's:

• .review/r-<id>/<computer>/ — your review, its history and the document versions it captured, signed with
  a key that never leaves this computer. If the file is changed outside Prisment, Prisment uses the last copy
  it saved and says so. A file it cannot read is named, and the other reviews still open.
• .review/r-<id>/<name>-<computer>.review.md — your comments and decisions as others see them, signed.
• .review/.gitignore keeps each computer's private folder out of Git; desktop Discard All never touches .review.

If you clear this browser's data, or use another computer, your earlier reviews appear under Saved under your
name on another computer — Continue here makes your own copy (its approval is not carried over). Deleting a review deletes all of it, for everyone — anyone in the review can, from ⋯ › Delete this review…: its whole folder
goes, every person's comments, every computer's private files and its history; when it was the last review, the .review folder goes
with it, unless something else is in it. Your documents are not touched. The question names whose comments go, and says how to get it
back: in the desktop app it goes to the Trash; in a Git folder it is a change to commit (in Source Control), and Git's history can
bring it back; in a OneDrive, Dropbox, Google Drive or iCloud folder everyone who syncs it loses it too, and the app's deleted files keep
it for a while; in a browser with neither, it cannot be undone after the notice. Straight after, Undo in the notice at the top right
puts every file back exactly as it was and opens the review again — if one of its files cannot be read at that moment (not downloaded
yet), the question says it cannot be undone instead of promising Undo. If a colleague is still on an older Prisment, the question says so:
until they update, their copy can bring the review back. On a colleague's computer the review panel then says This review is no
longer in the folder — the foot says so too — and writes nothing back; nothing more can be added to it there. Remove it here takes
what is left of it on that computer only — if the files have come back by then, they stay. If its files come back (restored, or Git back
on a branch that has it), it carries on.

The list of reviews shows each review once, with the number of reviews beside its heading. Closed reviews are folded under
Closed at the end, each saying Done or Cancelled. A copy of a review saved as a file in
the folder (reviews/…review.md, what Save a copy in this workspace writes) is not a second review: it is on the review's row — 1 saved
copy — with an eye to Preview it and a file icon to Delete the file (it asks first, and in a Git folder the removal is a
change to commit). Deleting a review does not delete its saved copy. A copy of a review you do not hold is a row of its own,
with the same two icons.

Review from more than one computer

Each computer is a separate person to the review until you link them: a comment written on your laptop and one written on
your desktop show as two people, and only the computer that started the review may decide and approve. To make them one
person, link them in Settings › You (the review panel's ⋯ menu and Share both take you there, as View user) — it works for anyone,
with as many computers as you have. Without a review, use Link by code: show a code on one computer, type it on the other, then type
its reply back on the first. With a review open on both, pick your other computer from the list instead:

1. On the new computer, pick your other computer from the list (This is mine). It shows a matching code.
2. On the other computer, a Link my computers box appears in Share (and the Share button carries a count). Type that code and press Link.

Your name, your ID and the computers you have linked are kept on this computer (in this browser, or in the desktop app), not in any one
review, and shown in Settings › You whether or not a review is open — you can unlink there too.

To undo it, open Settings › You and press Unlink beside the computer. Either computer can do it: the one you unlink stops
counting as you, and loses any owner rights it had through you; its comments stay; and you can link it again whenever you like. Nothing
is ever deleted, so the folder keeps a signed note that the link ended.

You link once. From then on both computers are one person in every review: each adds its half the first time it opens a review the other
has written in, so there is nothing to repeat. They also share one ID (in Settings › You, with Copy ID) — the same on every linked
computer and in every review.

Both computers have to agree, so a stranger cannot claim to be you; and since the code is only ever on your own screen, a
request you did not make has nothing to type. If your other computer is not in the list yet, open the review on it first,
or use its computer code under Use a computer code instead. Link only computers you own: a linked computer can act as you
— if the first computer is the one that decides and approves, the new one can too. Requests you ignore go quiet after 14 days.

For AI tools reading the review

A review file opens with a note to the AI agent: the status, what it may do next, and a hash of every approved
document (sha256-lf — SHA-256 of the text with Windows line endings turned into LF and no byte-order mark;
sha256 for binary files), so the agent can tell when a document changed after approval. A review closed as
Cancelled tells the agent it approves nothing, and the checker in the review skill refuses it; one closed as Done keeps what it
approved. Approval is advisory: nothing stops an agent ignoring it, and the file never claims otherwise.

When your AI tool answers. Ask your AI tool to complete — or address — the review's comments. With the skill installed, it asks the
skill's program for the work list (todo: each open comment, what it asks — a rename, a replacement, a removal, a missing detail — the
document and the line its passage is on now), makes each change in that document, and replies to each comment it dealt with. A comment
that says rename xyz to abc becomes "abc" in the document and a reply such as Renamed xyz to abc in docs/plan.md (2 places). Each comment it changed the document for, it marks done: Fixed when it corrected something (a name, a value, a mistake),
Implemented when it added what was asked (a section, a detail). The comment then reads Fixed or Implemented and moves to
Settled; if the change is not right, press Reopen on its card. A comment it cannot settle — a decision only a person can make, a
detail it would have to invent — gets a reply that asks, and stays open. Its replies appear under your name with (AI) — Jitesh (AI)
— so everyone sees an AI tool working for you wrote them. Marking comments done never approves the review: the person who started it
still approves, and the AI's changes make an earlier approval lapse. An AI tool cannot reopen a comment, decide, approve or close:
Prisment ignores anything else it writes and says so. A colleague on Prisment 2.0.13 or earlier sees an AI's comment still open, with
Fixed — check it. Its replies are saved in its own file in the
review's folder, and they reach colleagues the way the folder does. The first reply makes a key for AI replies on that computer
(~/.config/prisment/), outside your project.

10. Sharing your work

Export one document

Press Export (or File ▸ Export…) to open Export Options, choose a card, then Export. With more than one file open it has Single File and Multiple Files tabs.

• HTML Page — a standalone, presentation-grade page carrying your chosen style, an interactive table of contents, working diagrams, and a light/dark toggle for the reader.
• Markdown / CSV / YAML / … — the card is named for the file's own format: the clean original, exactly as it is.
• PDF Document — a typeset copy, paginated with a running header and page numbers. The desktop app saves the PDF file, titled and with bookmarks, through a save panel; a browser opens its print dialog, where you choose Save as PDF. A format that is not typeset, such as plain text, offers Print / PDF instead, through the print dialog; a spreadsheet grid, a PDF viewer and an API-docs portal offer neither, because printing them would not produce the document.
• Copy HTML to clipboard — the same standalone page, on your clipboard. To copy the Markdown source, use Copy source in the editor's source pane.

Unsaved changes are exported. An export is the document as you see it: one with unsaved edits exports with them — in every format, and in a workspace export too. Exporting never saves: the saved version stays as it is until you press Save. While documents in the workspace have unsaved changes, the top of Export Options says how many.

PDF layout and name. The PDF uses the document's first title as its suggested filename, or the source filename if there is no title. It prints on A4 in Portrait unless you choose Landscape under Page orientation, which appears on the Export dialog while PDF Document is selected; your choice is remembered. Content never changes the orientation. Beside it, Wide tables chooses what happens to a table too wide for the page: Keep layout (the default) prints the table as it is drawn, lets its text wrap, and crops what still does not fit; Fit to page reshapes it, as described below. Collapsed sections, including front matter, print open, and code wraps its long lines; a code block taller than a page continues on the next. Body text is set at 10.5 pt, the size printed documents use, with headings, tables and code in proportion. Anything that fits the page prints as it looks on screen: a table in its card, a diagram whole in its frame. With Fit to page, a table that is too wide takes the first of these forms that fits and reads well, measured: its text wraps, with links and file paths breaking after a slash or before a dot and short values such as names, dates and amounts kept on one line; then a compact size, never below 8 pt; then, for a few records with many fields, rows and columns swapped so the records sit side by side; then, for a grid of figures, side-by-side panels that repeat the first column, printed one panel after another, as a spreadsheet prints; otherwise each row prints as a card, titled by its first column (and the name beside an ID), with every other column as its header beside its value. Figures align right. A table taller than a page continues with its header row repeated, and a heading or a short introduction ending in a colon stays on the page of the table or diagram it introduces. A diagram is never cut at its sides. It stays whole in its frame while its main labels print at 6 pt or larger (small message-number badges do not count), and a wide drawing that fits one page stays whole at any size. A drawing too tall for the page keeps its full width and continues down the pages that follow, cut between messages, with a sequence diagram's participant names repeated above each part; the first part says how to read them and each later one carries a quiet position such as "2 of 5". The lettering is whatever the page's width makes it, and the drawing is vector, so zoom in the PDF to read a large one. The PDF includes the whole drawing, regardless of the current screen zoom or pan. In a browser's print dialog, keep the supplied paper size and 100% scale to preserve this layout.

In the desktop app, every download says what it is doing. While a page, a ZIP or a PDF is being made, a notice at the top right says Preparing…. Once you have chosen where to put the file in the save panel, it says Saved “name”, with Show in folder to find it. If you dismiss the panel it says nothing was saved, and a download that breaks says so. The same notice appears for every file the app saves — a style, a settings file, a diagram picture. In a browser, its own download bar does this.

Export a whole workspace

Select any subset of the file tree — the filter field above it narrows the tree by name or by a pattern such as *.md, and Select All then acts on what the filter shows — and choose one of:

• Interlinked Wiki (recommended) — every selected document as a linked, browsable site, with a shared sidebar (search by file name) and every relative link rewritten so it still works.
• HTML Pages — a ZIP with each document as an independent standalone page.
• Source Files — a ZIP of the originals, every format, exactly as they are. For a browser workspace whose files live only in the app, this is how you get them out as files.

Every format in the workspace is included, each rendered by its own viewer: Markdown as a document, an OpenAPI spec as live API docs, a CSV as a sortable table, and an .html file as it is, in a frame of its own. Each page is named after its file — docs/plan.md becomes docs/plan.md.html — and a link to a file in the export opens that file's page.

What an exported page can do

An exported page is the workspace preview, in a file. Same layout, same style, same controls — that is a design rule, not a coincidence.

Readers get: the interactive index, a light/dark toggle, a text-size control, working Mermaid diagrams with pan and zoom, rendered math, syntax-highlighted code with copy buttons, searchable CSV tables, browsable API documentation, and a PDF's pages — drawn in the page, opened from disk too, whatever the browser's PDF setting. Download, in the page header, hands back the original file — the very one you exported from. A Markdown page that took pictures with it hands back a ZIP instead, which unpacks to a folder holding the Markdown and its pictures at the paths it names them by. No build step, no dependencies to install, and no Prisment branding on the page.

What an exported page needs

11. Apps, privacy & support

Install as an app

• Progressive Web App — install Prisment from your browser's install button for a standalone window, offline access and OS file associations.
• Desktop app — native builds for macOS (Apple Silicon and Intel), Windows and Linux.

The desktop app

The desktop app runs the same code with these additions:

• Local folders always work, with no browser API requirement.
• Native menus — File, Edit, View, Window and Help, including Cmd/Ctrl + O to open a file and Cmd/Ctrl + / to open this guide.
• Open in default app, for handing a file to a spreadsheet or another editor.
• The local AI assistant (chapter 8), and commit, push, pull and Clone in Source Control (File ▸ Clone Repository…).
• PDFs saved as files, a notice for every download (Preparing…, Saved with Show in folder, or what went wrong), and self-update — an Update button in the header, and Help ▸ Check for Updates…. Help also holds What's New, Third-Party Notices, Report an Issue and Email Support. Cmd/Ctrl + / opens prisment.io/help in your system browser, so it needs a connection.

Settings do not sync between the desktop app and the browser. Use Settings → Import & Export to move your styles and preferences across.

Open a file from a terminal

The desktop app opens a document named on the command line — from the folder you typed it in, whether
Prisment is already running or not.

Where Prisment is your default app for the file type, open notes.md (macOS), start notes.md
(Windows) and xdg-open notes.md (Linux) do the same.

From your editor. In VS Code or Cursor, a task opens the file you are looking at — on a Mac, add
this to .vscode/tasks.json and run Tasks: Run Task → Open in Prisment:

{
  "version": "2.0.0",
  "tasks": [
    { "label": "Open in Prisment", "type": "shell", "command": "open", "args": ["-a", "Prisment", "${file}"], "problemMatcher": [] }
  ]
}

On Windows or Linux, put the command from the table in command and keep "${file}" as its argument.

Where Prisment keeps things

Reviews are files in your workspace folder, under .review — each computer's own, signed with a key that stays on this computer (see Where a review is saved). Other derived data uses device storage. Prisment reads your folder and writes into it only what you
ask it to — a document you edit, a conversion you run. What it derives for itself stays on this
computer, in the app's own storage — not as files you can open:

Your choices (style, language, theme) are kept as small first-party cookies and in local storage on this device; they hold no document content.

These used to be files — first in a .prisment/ folder inside your workspace, then in a
library/ folder beside the app's settings. They are in a database now for two reasons, and both are
about you rather than about us: a conversation held there cannot end up in a commit, which while
it was a file depended on an ignore rule Prisment had to write into your folder first; and clearing
it is one press rather than a hunt through folders named after a hash.

The same reasoning retired the rest of .prisment/ in version 1.2.1: the workspace map, the query
script and saved packs are no longer written into your folder either. The source cache is kept by the
desktop app; a browser tab holds its index in memory until you close it. Neither is ever uploaded.

Freeing up disk space

The quickest way is in the app. Open the assistant, press Assistant settings, and look under Chat history →
Kept for this workspace: Clear shows what it will free, and a second press (Delete ?) does it, because a
conversation cannot be brought back. If there is more in other workspaces it says so, and the total.

Review files are in .review; the databases above hold the other device data. Clearing a workspace removes its
conversations for good, and the cache rebuilds itself the next time that workspace is indexed,
reading every file once instead of only the changed ones.

Smaller, more surgical options:

• Clear one conversation from the assistant panel's history list.
• Delete what an earlier version left in a folder yourself — the .prisment/ folder (the map, a
  query script, saved packs and conversations) and the agent skill Prisment wrote there before
  version 1.2.1. Nothing reads them any more, and Prisment never removes them for you. The same goes
  for a library/ folder beside Prisment's settings.

Privacy

Your documents never leave your device. All Markdown parsing, diagram rendering, math, API-spec rendering and HTML export run in local memory. No document text, file name or file content is uploaded, stored on a server, or sent to a cloud AI service. Mounting a folder connects your browser to your own disk directly, with no proxy in between. Prisment does not create or open review share links.

The assistant does not change that, and here is exactly why. When you turn Local AI on, document text is sent to a model server running on your own computer — and nowhere else. The app has no address field: you pick a port, everything else is fixed, and every request is checked against a list of what may be asked for before a connection is opened. A request to anything that is not your own machine is refused rather than sent. Every attempt, allowed or refused, is recorded in local-ai-audit.json in the desktop app's data folder, so the claim is one you can check rather than one you have to take.

The one exception is a web page you allow. The assistant reads a page only after you allow it in a window the app shows — once, for the chat or for the workspace; that page or its whole site — whether you typed the link or, with Follow links in documents on (off by default), a document links to it. The request carries the page's address and nothing from your files.

Git is the other exception, and it is yours. Source Control runs the git program on your computer; Pull, Fetch, Clone and Push talk only to the repository you chose, using your own sign-in. Clone's search sends only the words you typed, to the one host you picked (choose Off to send nothing). The desktop app also asks releases.prisment.io whether a newer version exists, sending no document data.

What is measured, and where:

• On the hosted website (prisment.io) we use standard Google Analytics to count aggregate page visits and which features are used — that a desktop download, an HTML export or a conversion happened (which formats, never which document) — and we measure conversions for our own advertising campaigns.
• The desktop app collects anonymous, aggregate usage data — a daily active signal, your OS, the app version, and country — against a random install identifier. You can turn it off any time from Help → Share Anonymous Usage Data. It carries no advertising SDK of any kind.
• On every platform: document text, file names and file contents are never collected and never sent to analytics. We do not sell user data.

Offline

Once Prisment has loaded, it keeps working with no connection — including opening, editing, styling and saving files. Note that exported pages have their own requirement; see What an exported page needs above.

Language

Switch the whole interface, and this guide, between English and Français from the language button on the home page, or from Settings → Language. Your documents are never translated.

Troubleshooting

Getting help

• This guide is under Help on the home page, at ☰ ▸ Help ▸ User Guide in the workspace (the Help menu in the desktop app), and at prisment.io/help.
• The FAQ answers questions about security, browser support and licensing.
• Questions or feedback: support@prisment.io.