User Guide

Prisment is a local-first documentation workspace for AI and engineering teams. 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

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

1. Renders Markdown, MDX, OpenAPI specs, YAML, JSON, CSV and HTML 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. 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 — opens a blank document in the split 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.

You can also drag & drop files or whole folders anywhere onto the page. Supported: .md, .mdx, .html, .htm, .csv, .tsv, .json, .yml and .yaml.

The UI map

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

The top bar autohides as you scroll down and comes straight back when you scroll up or move the pointer near the top. It locks in place whenever a menu, popover or dialog is open.

Where Prisment runs

The same app ships through three channels, and one feature differs between them.

2. Files & workspaces

Workspaces

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

Switch between workspaces from the picker at the top of the Files sidebar; create, rename and delete them there too. The active workspace, the active document and which folders you had expanded are all remembered across a reload.

The file explorer

The Files sidebar is a full workspace explorer:

• 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 any supported type: pick the extension beside the name.
• Move files and folders by dragging them within the tree.
• Filter the tree by file name.
• File-type marks so a .csv never looks like a .md.
• On-demand loading, so a repository with thousands of files opens quickly.

Tabs

Open documents appear as tabs in the header. Click one to switch; right-click for its tab actions. The file info button in the header 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.

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 — if a file changes underneath you (a git branch switch, an agent, another editor), Prisment notices and offers to reconcile rather than silently reloading.
• External deletions are reconciled the same way.

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.
• Auto Save keeps a mounted folder in sync as you type.
• Drafts are protected. Unsaved edits are kept in the background, so closing a tab or reloading does not lose them.
• Nothing open is ever overwritten silently. If a file you have open — or one with unsaved edits — changes or disappears on disk, Prisment asks first, showing a side-by-side diff of what changed so you can keep your draft or take the disk version.
• Revert discards unsaved edits and returns to the version on disk.

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. New documents open with the source at 40% and the rendered result at 60% — drag the divider to re-balance, and your choice is remembered.

The segmented control in the toolbar switches what you see:

• MD — source only.
• Split — both panes (the default).
• HTML — the rendered document only.

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.

This is the fastest way to fix a word, restructure a list, or edit a table without hunting through source.

The formatting toolbar

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

Narrow toolbars show the common tools and move the rest into the More Tools menu.

Find & Replace

Open it with the Find button or Cmd/Ctrl + F. Step through matches, and use Cmd/Ctrl + H to replace one or all occurrences.

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.

In the rendered document (right pane)

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 11, 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.

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 with their own accent colour and icon. There are five:

> [!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. You can also add, remove and edit rows and columns visually in the rendered pane.

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 are interactive in both the editor and an exported page — ticking a box in the rendered pane updates the Markdown source.

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>

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, and uses title (or name) as the document's title if the file has no # H1.

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 and embedded into the document, so they survive an export.
• 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.

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 get a joined paragraph, put the text on one line.

--- 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.

5. Other file types

Prisment is not only a Markdown tool. Five formats each get a viewer built for them.

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 API docs and the raw Source from the toggle in the viewer's bar.

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.
• Copy and Download act on the file from the viewer's 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.
• Copy and Download from the viewer's bar.
• Its own light/dark preference in Settings → JSON & YAML.

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 and Download from the viewer's 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 copied out unchanged rather than wrapped in a Prisment page.

6. Look & feel

Three settings control appearance, 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 in the header.

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

Customize in the Style menu opens a panel where you can build your own style from any preset, and watch the document change as you drag. It is grouped into five sets of controls:

Saved styles appear in the Style menu alongside the presets. A saved style freezes the tokens it was built from, so it keeps rendering the way you left it even if you later hide or change the preset you started from.

Styles can be exported and imported as .json files, which is how you share one with a teammate — or move it between the browser and the desktop app.

App theme, text size and Focus Mode

• App theme — the light/dark chrome of the Prisment interface itself, toggled from the header. This is separate from the presentation style; a light app around a dark document is a perfectly valid combination.
• 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, closes 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 or click the floating badge to come back.
• 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. Click any entry to jump. Exported pages carry the same index.

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 and language.
• Mounted folder history — export only. Folder access is granted per machine, so these can be listed but not restored; re-open them with Open Local Folder.

7. Sharing your work

Export one document

From the Export menu:

• HTML Document — a standalone, presentation-grade page carrying your chosen style, an interactive table of contents, working diagrams, and a light/dark toggle for the reader.
• Source file — the clean original: the .md, .yml, .json or .csv exactly as it is.
• Print / PDF — formatted output through your browser's print dialog.
• Copy MD / Copy HTML — the raw source or the rendered markup, straight to your clipboard.

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 documentation site — every selected document as a linked, searchable offline wiki, with a shared sidebar and every relative link rewritten so it still works.
• ZIP of HTML pages — each document as an independent standalone page.
• ZIP of source files — 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 .html files copied out untouched.

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, tickable checkboxes, sortable CSV tables, and browsable API documentation. No build step, no dependencies to install, and no Prisment branding on the page.

What an exported page needs

8. 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 three 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.

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

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 any AI service. Mounting a folder connects your browser to your own disk directly, with no proxy in between.

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 or an HTML export happened, never the document itself — 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 switcher in the header, or from Settings → Language. Your documents are never translated.

Troubleshooting

Getting help

• This guide is always available from the Help button in the header, and at prisment.io/help.
• The FAQ answers questions about security, browser support and licensing.
• Questions or feedback: support@prisment.io.