Editor Overview
SpecDown's editor is powered by Monaco — the same engine behind VS Code — giving you a professional writing experience right in the browser.
Editor Layout
The editor is split into three main panels:
- File tree (left) — navigate your project's documents and folders
- Editor pane (center) — write Markdown with full syntax highlighting
- Preview pane (right) — live-rendered output, updates as you type
You can toggle panels using the toolbar at the top. On small screens the editor and preview are stacked vertically.
Keyboard Shortcuts
| Action | Mac | Windows / Linux |
|---|---|---|
| Save document | ⌘ S | Ctrl + S |
| Bold | ⌘ B | Ctrl + B |
| Italic | ⌘ I | Ctrl + I |
| Find in file | ⌘ F | Ctrl + F |
| Command palette | ⌘ Shift P | Ctrl + Shift + P |
| Toggle comment | ⌘ / | Ctrl + / |
| Indent line | Tab | Tab |
| Outdent line | Shift Tab | Shift + Tab |
| Duplicate line | ⌘ Shift D | Ctrl + Shift + D |
| Move line up/down | ⌥ ↑/↓ | Alt + ↑/↓ |
Toolbar Actions
Split view
Toggle editor / preview / split layout
Preview mode
Full-screen rendered preview
Insert image
Upload image to Cloudflare R2 CDN
Version history
Browse and restore past versions (Pro)
Backlinks
See which documents link to the current document
Document graph
Inspect incoming and outgoing links around the current doc
Share document
Create a public or password-protected share link
Keyboard shortcuts
View all shortcuts reference
Markdown Support
SpecDown supports the full CommonMark specification plus these extensions:
- GitHub Flavored Markdown (tables, strikethrough, task lists)
- Mermaid diagram blocks (see Mermaid Diagrams)
- Syntax highlighting for 150+ languages in fenced code blocks
- Footnotes
- Math blocks (LaTeX via KaTeX)
- [ ] or - [x] render as styled checkboxes in the preview pane. Clicking a checkbox toggles the underlying Markdown and auto-saves, so you can tick items off without leaving view mode. Read-only surfaces such as shared documents render the same styled checkboxes but disable interaction.[ ] and [x] tokens that appear mid-line (e.g., "Session timeout (BR2) [ ]") also render as interactive checkboxes — useful for Pass/Fail flags inside spec rows. Skipped contexts: fenced code blocks, link/reference syntax like [x](url), and the leading GFM marker on a list item.<input value="..." /> or <textarea>...</textarea> into your Markdown to embed inline form fields. In preview mode they render as proper inputs; typing into them rewrites the Markdown source so the values round-trip through editor mode and stay in version history.Linking between documents
Inline links in your Markdown can point to other documents in the same project, and clicking them opens the target doc in-place — no full reload, no losing your share token.
Three syntaxes are recognised:
- Absolute path:
[Screen list](/srs/screen-list)or with extension(/srs/screen-list.md). - Relative path:
[Spec 001](./SPEC-001)or(../guides/oauth). - Wiki link:
[[/srs/SPEC-001]]or with display text[[/srs/SPEC-001|Spec 001]].
- Links to existing docs render as normal links; clicking navigates inside the editor (or the share session for project shares).
- Links to a path that has no matching doc render in dotted red so you can spot broken references during review.
- External URLs (
https://…), anchors (#section), and attachment embeds ([@/path]) are untouched.
HTML documents
SpecDown isn't only Markdown — you can also store raw .html documents alongside .md files. Create one by switching the type toggle from MD to HTML in the New file form (or type a filename ending in .html).
- Monaco switches to HTML syntax highlighting automatically.
- The preview pane renders inside a sandboxed iframe: scripts, styles, and forms inside your HTML are isolated from the host app.
- HTML files show with a code icon (amber) in the file tree to make them easy to spot.
- Rename behaves the same as Markdown — the
.htmlextension is preserved automatically.
body { height: 100vh; overflow: hidden }(typical for interactive diagrams, dashboards, or single-page mockups), the preview locks to a viewport-relative height instead of trying to auto-grow from body.scrollHeight. This avoids runaway iframe height when users click inside your app — internal scrolling and your own click handlers still work normally..html document (or an existing .html attachment), the share URL serves your HTML as the entire page — no SpecDown header, no surrounding chrome, no iframe. The browser navigates straight into the HTML. Password-protected shares show the password gate first; after the password is verified the URL serves the raw HTML the same way. Scripts inside the HTML run in a sandboxed origin so they can't read SpecDown cookies or call the API with the visitor's session.Image Upload
Click the image icon in the toolbar or paste an image directly into the editor. Images are uploaded to Cloudflare R2 and inserted as a Markdown image tag with a CDN URL.
Project Attachments
The file tree can now hold more than Markdown. Upload PDFs, images, videos, CSV files, and text-like source files such as .json, .txt, .js,.tsx, or .py as project attachments.
- Markdown files still open in the full editor
- Attachments open in a preview-only tab
- Images, PDFs, and videos render with native viewers
- CSV files render as a table preview
- Text-like files render as readable code/text blocks
.md files with PDFs / images / other binaries, all of them land inside a single unified folder in the tree — markdown documents and attachments share the same folder row, so you no longer see two same-named folders sitting next to each other.flow.png you reference from a sibling Markdown file with<img src="./flow.png" /> resolves correctly without rewriting the path.<img src="./flow.webp" />, walk into siblings with , or use an absolute project path (/shared/diagram.svg). The viewer rewrites the src to the matching attachment's signed download URL — works for both authenticated editing and share-view rendering.<img src="./…"> references in sibling docs continue to resolve. While you drag, the file tree auto-scrolls when the cursor nears its top or bottom edge so folders sitting off-screen in a long list are still reachable..xlsx / .xls /.xlsm attachments are parsed client-side and shown as tabbed sheets — one tab per worksheet, rows / columns capped at sensible limits to stay responsive. ZIP archives upload normally and surface a download-only card.report.pdf, diagram.webp) rather than stripping the extension, so PDFs, images and other binaries are easy to tell apart at a glance..html attachment in the editor, the top-right corner shows an Edit as document button. Clicking it creates a new editable HTML document with the same content and opens it in a new tab — useful for HTML attachments created before HTML uploads became editable by default. The original attachment is left in place so existing share links keep working; delete it manually when you no longer need it.Inline Attachment Embeds
Inside Markdown, you can reference a project attachment by path using the syntax[@/path/to/file]. In preview mode, SpecDown resolves that path and renders the file inline.
[@/assets/architecture.pdf]
[@/media/demo.mp4]
[@/snippets/example.tsx]
[@/data/sample.csv]Missing paths render as a warning block in preview so broken references are obvious during review.
Auto-save
The editor auto-saves your work every 2 seconds after you stop typing. You'll see a subtle "Saved" indicator in the toolbar. Manual save with ⌘S triggers an immediate save and version snapshot if the content has changed.
Version History
Click the history icon to open the version history panel. Each version shows:
- Author who saved the version
- Timestamp of the save
- Size difference from previous version
- Restore button to roll back to that version
Click the preview icon on any version to open a full-content diff modal. The modal compares that version to the one immediately before it, highlighting added lines in green and removed lines in red. The first version shows the entire content as added.
The version history sidebar is resizable — drag its left edge to widen or narrow the panel. Your preferred width is remembered across sessions.
Editing alongside others
A user is counted as actively editing only after they have typed at least one character. Pure viewers (people who opened the document but haven't typed) do not trigger any warning — they appear in the presence avatars without a pencil badge.
When you open a document and someone is actively editing it (avatar shows the pencil badge), SpecDown shows a warning modal. Three options:
- Edit anyway — proceed normally. The other editor sees a warning toast that you have force-edited.
- View only — open the document read-only with a "Read only" badge. When the last editor stops typing and leaves, the latest content reloads automatically and you can edit.
- Request edit — sends a request to the user(s) currently editing. They see a toast with Accept / Deny. If accepted, you immediately get edit access. If denied or no response in 30 seconds, the modal returns to the three-button view so you can choose again.
The grantor's toast persists for 60 seconds. Multiple grantors may receive the request — the first to accept wins.
Backlinks
Click the backlinks icon in the editor header to open a panel of documents that already link to the current file. This makes it easier to understand dependency chains before you rename a section, restructure an ADR, or let an AI agent rewrite a document.
- Each entry shows the document title and full path
- Click an entry to open that document directly in the editor
- Use it together with review status to judge whether a change has broader impact
Project graph
Open a document and click the graph icon in the editor toolbar (the one shaped like a small node network) to see the entire project's documents as a force-directed graph. Each node is a document; each edge is an internal markdown link or wikilink between two documents.
- Click a node to jump to that document.
- Hover a node to highlight its neighbours and dim the rest.
- Filter by typing into the search box (matches document titles).
- Orphans only shows documents that have no incoming or outgoing internal links.
- Fullscreen expands the dialog edge-to-edge for larger graphs.
Nodes are colored by the top-level folder they live under, so clusters become visually obvious. Documents at the root are grouped together.
Ready to get started?
Write specs like code. Sync with Git. Share with your team.