Markdown Editor

Its own entry, Tiptap as optional peers

Both editors live at @comitor/ui/editor and run on Tiptap 3 — ProseMirror, the same foundation as Linear's editor. The @tiptap/* packages are optional peers: an app that never imports the entry pays nothing. Install them when you do, all at one version:

pnpm add @tiptap/core @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/markdown \
  @tiptap/extensions @tiptap/extension-list @tiptap/extension-table @tiptap/extension-image \
  @tiptap/extension-mention @tiptap/suggestion @tiptap/extension-paragraph \
  @tiptap/extension-code-block-lowlight lowlight highlight.js

• One version for every @tiptap package. They pin @tiptap/core and @tiptap/pm to the exact number, and an extension you write yourself must use that same copy — two copies of ProseMirror on a page and a node built by one does not fit a document of the other.
• About 234 KB gzipped — ProseMirror, Tiptap and the menus around 184 KB, the syntax highlighter (37 languages) around 53 KB. A page that does not need an editor the moment it opens can load it with next/dynamic — under webpack too (next dev --webpack) from 3.17.2, which gave every entry of the exports map a default condition.
• Server rendering: the editor builds on the client after hydration, holding its minimum height until then — read mode included.

A task description

variant="ghost": no frame, no padding, the document straight on the card. Everything below is live — edit the text and watch the stored Markdown change; tick a checkbox; select a word for the bubble; type / on an empty line, or @. Paste or drop an image and it uploads for real to /api/demo-upload, which keeps nothing — look at what lands in the value.

## Sign in with a one-time code

People who **forgot their password** need a fast way back in. See the [Account docs](https://comitor.ai/docs) and ask [@Wei Chen](mention:u5) about rate limits.

- [x] Design the code entry screen
- [ ] Send the code by email
  - [ ] At most 5 codes an hour
- [ ] Write the tests

> Codes expire after 10 minutes. Never store the raw code.

```ts
export function verifyCode(input: string, hash: string): boolean {
  // constant-time comparison
  return timingSafeEqual(sha256(input), hash)
}
```

| Step | Owner | Due |
| --- | --- | --- |
| Design | Priya Raman | Oct 5 |
| Backend | Tomas Berg | Oct 12 |

The image you drop shows at once, from the file itself, but it is not in the value until the upload returns — and then what lands is the key onImageUpload returned, not the address you see. Undo removes the image in one step, and redo brings back the real one: the half-uploaded picture is a decoration, never a node, so history cannot resurrect it.

What you can type

The / menu lists every block with its shortcut beside it, greyed — so the menu is also where the syntax is learned, and next time the person types it straight. It filters accent-insensitively, with synonyms per language.

⌘K inside the editor opens the link field, not the command palette — the shell's listener ignores the key when it comes from a contenteditable. Keys shown for macOS; elsewhere ⌘ is Ctrl and ⌥ is Alt.

A comment box

The default outline variant, framed like a Textarea. onSubmit takes ⌘↵, the handle clears the box, and each posted comment is the same editor with editable={false}.

Mentioning more than people

New in 3.7.0. An @ item with a kind — "task", "project" — is stored with that kind in front of its id, [@DS-388](mention:task/t388), while a person keeps the 3.5.0 form, so content saved before reads exactly as it did. icon stands in for the avatar in the menu, resolveLabel receives the kind as its second argument because ids of two kinds can collide, and getHref turns a mention into a link — here the task opens the Tasks pattern. Type @ds to find the tasks.

Blocked by [@DS-388](mention:task/t388) until [@Wei Chen](mention:u5) signs off the copy.

The address is drawn, never stored. getHref runs when the mention is painted, so moving tasks to another path changes no saved content. It is a plain <a href>: in a Next app a click is a full page load, not a router transition — the price of not wiring a listener into the editor.

In a form

Spread FormField's control into it like any input. Click the label: the caret goes in. Turn the error on: the frame turns --destructive-ink and the surface carries aria-invalid.

A pinned toolbar instead of the bubble

toolbar="fixed" suits people who do not know the shortcuts — long internal documents, say. The bar sticks to the top while the document scrolls, wraps onto a second row on a phone, and inside a table it locks the block and insert buttons: a GFM cell holds a single line, so a block button would do nothing there and an insert button would split the table to make room. Underline never appears here; Markdown has no syntax for it. From 3.14.0 the bar also aligns paragraphs and headings left, center or right — but not inside a list item or a table cell, where the buttons lock: a GFM table aligns whole columns, and a list item's trailing attribute would not survive the next open.

In Vietnamese

Every string follows ComitorLocaleProvider — placeholder Write something, or type “/” for blocks… in English, Viết nội dung, hoặc gõ “/” để chèn khối… in Vietnamese. Type /tieu: the menu finds “Tiêu đề” without the diacritics, and /h2 still works in every language.

The stored format is a contract

This is the entry's real public API: an app stores these strings, and changing how any of them is written means old content reads back differently.

• A mention is an ordinary Markdown link, not Tiptap's own [@ id="…"] syntax: a notification email, an agent reading over MCP or any other Markdown viewer prints “@Name” instead of a bracket soup. The name inside is a snapshot from the moment of mentioning; the live name is drawn through resolveLabel, for the same reason a Comitor module keeps no column of people's names.
• No underline, on purpose. Markdown has no syntax for it, and Tiptap would write ++text++ — which every other viewer prints raw.
• Alignment is a trailing attribute (3.14.0) — {align=center} or {align=right} after one space, the markdown-it-attrs convention. Another viewer prints it at the end of the line, which still reads. Text a person types that ends in {…} is saved as \{…} so it stays text. A page that renders the Markdown itself — an email, a channel's HTML — must understand the attribute or strip it.
• Five upstream round-trip bugs are patched and guarded by the package's test:editor-markdown gate: a paragraph starting # reopening as a heading, a code block cut short by its own backticks, table cells decaying into <br> one save at a time, mentions in a private syntax, and a parser that got fifteen times slower over a working day. Each was silent — the screen was right; the document was different the next time it opened.

Props

The handle

Through ref — MarkdownEditorHandle.

Accessibility

• The editing surface is a named textbox — role="textbox", aria-multiline, named by your aria-label, by a <label for> it finds through its id, or by a generic “Editor” as the last resort. In read mode it says role="none": a list of comments should not be announced as a column of read-only inputs.
• Both menus are listboxes driven from the keyboard — ↑ ↓ to move, Enter to pick, Escape to close. Inside a dialog, Escape closes the menu first and the dialog only on the next press, and clicking a menu item does not dismiss the dialog.
• Every toolbar button names itself and shows its shortcut in a tooltip that also appears on keyboard focus. Pressing one keeps focus in the document, so the selection it formats survives.
• Checkboxes are named after their item — “Task: Send the code by email”, not a bare “checkbox” — and a parent item's name stops at its own text, before its children's.
• An image that is still uploading is announced as an image named “Uploading image…”, and a rejected link address answers with a role="alert" line instead of silently doing nothing.
• 16 px text on phones. Below 16 px, Safari on iOS zooms the whole page when the surface is tapped; from md up the editor drops to 14 px, like Textarea and — since 3.13.4 — every other field in the package.