Writing & Editing

CompassDocs is built for everyone on the team — not just people who know Markdown. You can write in a familiar rich-text editor, organize documents into spaces, and clean up your writing with a single click.

Spaces

Spaces group related documents — typically one per team, product, or topic. They appear in the sidebar and organize browsing and search.

Admins manage them from Settings → Spaces (or the ＋ next to Spaces in the sidebar):

Create a space with a name, an optional description, an emoji icon, and a color. The URL slug is generated from the name automatically.
Edit a space’s name, description, icon, or color at any time.
Delete a space — but only once it’s empty. If it still holds documents, CompassDocs blocks the deletion so content is never removed by accident. Move or delete those documents first.

The editor

Creating a document starts from a template picker — six built-in scaffolds (SOP, runbook, policy, and more), your team’s custom templates, or a blank page. See Document templates for placeholders, per-space defaults, and template management.

When you create or edit a document you get three views, switchable with the tabs at the top of the editor:

Rich text (default) — a what-you-see-is-what-you-get editor with a toolbar for headings, bold, italic, underline, lists, quotes, links, code, and dividers. No Markdown knowledge required, every button shows a tooltip on hover, and the toolbar stays pinned to the top of the window while you scroll through long documents.
Markdown — a plain-text Markdown editor, for people who prefer to type syntax directly.
Preview — the document rendered exactly as readers will see it.

Both editors work on the same document: switch freely between Rich text and Markdown and your content stays in sync. Under the hood everything is stored as Markdown, so search, export, and version history are identical no matter which view you use.

Layout & formatting tools

Alignment — left, center, or right per paragraph or heading.
Indent / outdent — indents paragraphs; inside a list the same buttons nest and un-nest list items.
Format painter (🖌) — put the cursor in (or select) formatted text, click the brush, then select the text that should look the same. Click the brush again to cancel.
Clear formatting — strips marks, alignment, and indent from the selection in one click.
Heading highlights — with the cursor in an H1–H3, pick a pastel background from the palette (or the ⃠ swatch to remove it). Highlighted headings render as a colored pill in documents, the public site, and newsletter emails.

Tables

Insert a table from the toolbar (3×3 with a header row); once inside, extra buttons add or delete rows and columns, or delete the whole table. Simple tables are stored as plain Markdown pipe tables, so they stay portable.

The transparent table toggle removes all borders and shading — an invisible layout grid, ideal for placing photos or content side by side. In the editor the grid shows as dashed guides; readers (and email recipients) see none of it.

Color panels

The color panel button (🪣) wraps the current block in a colored container — the free-form sibling of code and email blocks. Put text, images, lists, or buttons inside; pick from nine backgrounds (pastels and deep colors). The text color adjusts automatically to stay readable on the chosen background, or force it with the Dark / White override. Panels render identically in documents, on the public site, and in newsletter emails.

Fonts

The font selector offers a small, deliberate set of email-safe choices — Default, Serif (Georgia), Typewriter (Courier), and Rounded (Trebuchet) — so whatever you pick looks the same in the app and in recipients’ inboxes.

Links

Links to external sites render as a soft chip showing the target site’s favicon next to the link text — fetched once server-side and cached, so readers never contact the external site just by viewing a page. Internal links (to other documents or app pages) stay as ordinary links, and in the editor external links show a chip with an ↗ marker.

Side-by-side images

Images smaller than full width flow inline: size two photos to ~45% each (see the slider below) and place them in the same paragraph and they’ll sit next to each other — no table needed. For more control (captions, uneven splits), use a transparent table with one image per cell.

Formatting Markdown can’t express (underline, alignment, indent) is stored as small sanitized HTML snippets inside the Markdown, so it round-trips through the Markdown view, renders on document pages and the public site, and survives export.

Saving and unsaved changes

Press ⌘S (CtrlS on Windows and Linux) to save without reaching for the mouse — the browser’s own “save page” dialog stays out of the way. The Save button rides along with you as you scroll a long document, so it’s never off the top of the screen when you want it, just as the formatting toolbar already was.

If you have unsaved edits, CompassDocs asks before it lets them go:

reloading or closing the tab,
pressing Cancel,
and clicking away to another page in the app — a sidebar link, a search result, anything.

A document you haven’t actually changed never prompts, so opening something to read it and clicking on is silent. Links that open in a new tab, downloads, and external links are left alone.

Reading width

Body text is capped at a comfortable reading column, so long paragraphs don’t run the full width of a widescreen monitor — and the cap follows the page width you picked, because choosing a wider page is a request for more on screen:

Page width	Body text
Normal	fills the column (~71 characters per line)
Wide	~98 characters
Full	~117 characters

It stays capped at every setting rather than running edge to edge. On a large monitor an uncapped column is around 190 characters per line, which is roughly three times the length most people can track comfortably.

Everything that isn’t body text uses the whole width you chose: the title, notices and toolbar, the right-hand panel, and every panel or piece of media in the document — tables, fenced code blocks, rendered diagrams, images, callouts, accordions, tabs, decision trees, video and embeds.

The rule is what the block is, not what’s inside it. A callout holds prose but it’s a panel, so it lines up with the table above it rather than with the paragraph. Only the document’s running text — paragraphs, lists, headings, quotes — keeps the measure.

Before 1.0.1 the measure capped the whole document body, so a wide table scrolled sideways inside a narrow strip while the rest of the page sat empty; 1.0.2 finished the job for the remaining block types. Printing is unaffected: on paper the page box already provides the measure.

Scheduled publish & unpublish

Users with publish rights see two optional fields next to Status in the editor (on existing documents):

Publish automatically at — on a draft: it goes live at that time, subscribers are notified exactly like a manual publish, and the action is audit-logged as a scheduled publish.
Unpublish automatically at — on a published document: it returns to draft at that time (useful for time-limited notices and expiring policies).

Schedules are one-shot and self-cleaning: publishing by hand (or trashing the document) clears a pending schedule rather than re-firing it. Clear a field to cancel. Because a scheduled publish skips the review queue when it fires, setting one requires publish rights.

Bulk operations

In a space’s Table view, editors get a checkbox column. Select documents and the action bar appears: Publish, Unpublish, set Type, Move to another space, or add/remove a tag — one action, many documents. Every document is checked against the same rules as a single edit (space scope, edit rights, and the approval workflow); anything ineligible is skipped with a reason shown, never forced.

Reader feedback

Every document ends with Was this helpful? — one vote per person, changeable, and a “No” invites an optional note about what’s missing. Ratings surface in Content health as a Poorly rated list, so the documents readers themselves flag get fixed first.

AI writing assist

The ✨ Write menu in the editor toolbar helps at every stage of a draft (it uses the same AI setup as Ask and proofreading — no extra configuration):

Draft from title — type just a title and get a structured starter draft: sensible headings and bullets to fill in, with [placeholders] where a real detail belongs. It never invents facts.
Improve writing — a clarity-and-flow rewrite that preserves every fact.
Expand / Make shorter — more detail and structure, or a tighter version with the filler removed.
Summarize — writes a 1–3 sentence summary straight into the document’s summary field.
Change tone — professional, friendly, concise, or confident.

Every result appears in a review panel first — nothing touches your document until you click apply, and you can dismiss any suggestion. Markdown structure and code blocks are always preserved.

AI proofreading

Click ✨ Proofread to have AI check the document for spelling, grammar, punctuation, and clarity. It returns:

a list of suggested changes (each labeled spelling, grammar, punctuation, or clarity, with a short reason), and
a polished version you can apply with one click — or dismiss to keep your original.

Proofreading preserves your meaning and Markdown structure, and never touches text inside code blocks.

Images & screenshots

Screenshots belong in the procedure, not at the bottom. In either editor mode you can put an image exactly where the reader needs it:

Paste — take a screenshot, put the cursor where it goes, and paste.
Drag & drop an image file into the editor.
Or use the 🖼️ toolbar button in the rich-text editor to pick a file.

The image uploads as a document attachment and is inserted as standard markdown (![alt](url)), so it renders everywhere the document does — including the public site. The workspace attachment size limit applies. If you paste into a brand-new, never-saved document, CompassDocs saves a draft first so the image has a document to live on — just keep writing.

Alt text: select an image and click Alt in the toolbar to describe it — screen readers read the description aloud, and it shows if the image fails to load. (In markdown it’s the standard alt: ![description](url).)

Sizing: click an image in the rich-text editor and drag the size slider (10–100% of the text column, in 5% steps). In markdown, the size is a title token you can type by hand: ![screenshot](/api/attachments/3 "w=45%"). Readers can click any image to zoom it full-screen (Esc closes), and every document page has a Normal / Wide / Full page-width toggle in the top-right corner. It’s a personal preference saved to your account, so it follows you to any browser you sign in from, and it applies across the whole app rather than to one document.

Training slide breaks

On enterprise workspaces using training & onboarding, the toolbar has a training page break button that inserts the --- divider where one training slide ends and the next begins. In the editor’s preview the break shows as a labeled “Slide break” marker so you can see the boundaries; on the published document page it renders as nothing — ordinary readers never see it.

Diagrams & rich blocks

Documents can include Mermaid and PlantUML diagrams, tabs, accordions, callouts, video and website embeds, interactive checklists, decision-tree guides, and filterable tables — all written in plain Markdown. Use the block buttons in the toolbar for ready-made templates, and see Diagrams & rich blocks for the full syntax.

Documents can link to each other with typed relationships, shown in the side panel next to every document (alongside attachments and suggestions):

Related — a general “see also” in both directions.
Procedure for ↔ Procedures — connect a policy to its accompanying procedures. Link from either side; the procedure shows “Procedure for” and the policy automatically lists its “Procedures”.
Supersedes ↔ Superseded by — when a document replaces another.

Anyone with edit rights on the document’s space can manage links: Link a document → pick the relationship (“This document is a procedure for…”) → search → click. Links respect permissions — a related document a reader can’t open (a private space, or a draft for viewers) simply isn’t shown to them.

Versions, restore & branches

Every save that changes the title or content adds a version — and the editor’s Change note field lets you say why (“Updated escalation contacts for Q3”). From the document’s Version history you can compare any two versions side-by-side or inline, restore an older version, and draft big rewrites on a private branch before merging them back. See Versions & branches for the full tour.

Documents with two or more headings (H1–H3) automatically get a Table of contents at the top of the page — collapsed by default; expand it and click any entry to jump to that section. Nothing to configure and no special markup: it’s built from the document’s own headings.

Printing & PDF

Every document page has a Print / PDF button (next to History/Edit). It opens your browser’s print dialog — choose a printer, or pick Save as PDF to export the document. The printout is a clean copy: just the title, byline, and content, with screenshots and code blocks kept intact. The same button appears on public site pages, so external readers can save a copy too.

Code & run blocks

Fenced code blocks get a header bar with the language label and a one-click Copy button. Shell-flavored blocks (```bash, ```sh, ```powershell, ```run, …) render as run blocks — terminal-styled with a Copy commands button — perfect for runbooks and step-by-step procedures:

```bash
fly status -a my-app
fly machines restart -a my-app
```

Nothing is ever executed by CompassDocs; run blocks are presentation only.

Email templates

For copy-paste email templates — refund confirmations, outage notices, onboarding welcomes — use an ```email block (or the ✉ Email template button in the rich editor’s toolbar). It renders as a letter-style card, clearly separated from the rest of the document:

Leading Subject:, To:, Cc:, and Bcc: lines become styled envelope fields; everything after is the body, shown in a normal reading font.
Readers get Copy subject, Copy body, and Copy all buttons, so pasting into a mail client takes one click per part.

```email
Subject: Your refund has been processed
To: [customer email]

Hi [first name],

Good news — your refund has been processed today.

Thanks,
[your name]
```

Discussing a document

Every document has a Comments thread at the bottom — for questions, context, and feedback that doesn’t belong in the document itself. Type @ to mention a teammate and they’re notified by email and on their dashboard. See Comments & @mentions for details, including the admin controls (workspace on/off switch, restricted words, moderation).

CompassDocs service status