Comments
Comments are supported across the full conversion round-trip. You can import a .docx that contains comments, work on those comments live in a collaborative Tiptap editor, export them back to a .docx, and re-import the result (including after it has been edited in Microsoft Word) without ending up with duplicates.
Support overview
| Import | Editor | Export | |
|---|---|---|---|
| Comments | Live collaboration threads (or data via REST API) | Read, reply, resolve, delete | DOCX comments |
| Replies | Preserved, in order | Threaded | Preserved |
| Resolved state | Preserved | Toggle | Preserved |
| Author, initials, date | Preserved | N/A | Preserved |
How it works
A round-trip has three stages:
- Import: each comment in the
.docxbecomes a thread anchored to the same text it marked in Word, carrying its author, initials, date, replies (in order), and resolved state. - Edit: threads are live in your collaborative editor: read them, reply, resolve or reopen, and delete.
- Export: your editor's threads are written back into the
.docxas native Word comments, anchored to the same text.
Re-importing an exported document recognises the comments that are already there and keeps them in sync instead of creating them again, even if the document was opened and edited in Microsoft Word in between.
Import
When an import is authenticated with Tiptap access control and targets an existing collaborative document, the comments are registered as live threads on that document automatically. They are ready to read and reply to the moment the document opens, with no extra wiring on your side.
Live comment threads require a Team plan
Registering live threads creates them on the Tiptap Document Server through the Comments REST API, which requires a Team plan or higher. The import forwards your access token to the Document Server, so an account below the Team plan is rejected and no live threads are created. The import itself still succeeds and returns the comment data with its original identifiers. Importing comments as data and exporting comments to DOCX are not affected by this requirement.
What is carried over from the Word document:
- Text anchor: the thread is attached to the same range of text the comment marked in Word.
- Author, initials, and date: shown on each comment.
- Replies: multi-comment conversations keep their order: the original comment first, then replies.
- Resolved state: threads marked resolved in Word arrive already resolved.
If the import is not authenticated for collaboration, or does not target a collaborative document, the import still succeeds and the comments are returned as data with their original identifiers, for you to handle yourself. See the import editor extension and import REST API for the integration details, and ConvertKit for configuring the editor to render imported content.
Live threads need collaboration
Comments become live, editable threads only when the import is authenticated with access control and points at a collaborative document. Every other import returns the comment data with its original identifiers and behaves exactly as before.
Editor
Imported comments are standard Tiptap collaboration threads. With the comments extension in your editor you can read each thread, reply, resolve or reopen it, and delete it, and those changes are reflected when you export.
Comments created live in the editor (not from a DOCX import) are first-class too: they export to DOCX alongside the imported ones, and they are never altered or removed by a later re-import.
Export
Your editor's comment threads are written into the exported .docx as native Word comments. Each thread becomes a comment anchored to the right text, replies are preserved as a threaded conversation in order, and resolved threads are exported as resolved. Author and date travel with each comment. See the export editor extension for setup.
The text inside a comment keeps its basic formatting (such as bold, italic, links, and line breaks). Comment bodies are intended for discussion text; very rich block content placed inside a comment may be simplified.
The full round-trip
This is the headline: you can take a document all the way around and back without your comments drifting.
- Import a
.docxwith comments into a collaborative document. - Read, reply to, resolve, and add comments live.
- Export to
.docx. - Optionally open and edit the comments in Microsoft Word.
- Re-import the document onto the same collaborative document.
On that re-import:
- No duplicates. Comments that are already present are recognised and left in place, not created again.
- Edits flow through. If a comment's text changed, the existing thread is updated to match.
- New comments come in once. A comment added in Word (or anywhere) during the round-trip is imported as a single new comment, in the right thread.
- Removals are cleaned up. A comment deleted from the document is removed on the next import.
- Resolved/reopened follows the document. Resolving or reopening a comment is reflected on re-import.
- Your live comments are protected. Comments authored directly in the editor are never changed or removed by a re-import; only comments that originated from a DOCX import are kept in sync.
Survives Microsoft Word
Microsoft Word reorganises its internal comment bookkeeping every time it saves a document. The round-trip is designed around that, so editing your exported comments in Word and re-importing does not create duplicates.
Best practice: one collaborative document per DOCX
Keep a one-to-one mapping between an imported .docx and the collaborative document you import it into. A re-import reconciles the comments against the threads already on that document, so importing several different DOCX files onto a single shared document mixes their comments together on the same surface. This shouldn't cause problems on its own, but dedicating one collaborative document to each DOCX lets you iterate on its comments collaboratively (adding, replying, resolving, and round-tripping through Word) with no chance of a re-import ever touching comments that originated from a different file. It's a simple safety net for clean, predictable iteration.
What to expect
- Importing a
.docxwith comments into a collaborative document gives you live threads with authors, dates, replies, and resolved state intact. - Exporting produces native Word comments that open cleanly in Microsoft Word and other Word-compatible editors.
- Re-importing keeps comments in sync (add, update, resolve, remove) rather than duplicating them, including after a Word edit.
What won't work
- Live threads require collaboration and a Team plan. Without access-control authentication and a target collaborative document, comments are returned as data rather than created as live threads. Creating live threads also requires a Team plan or higher, since it uses the Document Server's Comments REST API.
- Duplicate-free re-import applies to documents exported by Tiptap. A
.docxproduced elsewhere imports its comments fresh each time; its comments are never merged into unrelated threads. This is deliberate: it prevents comments from different documents being mistaken for one another. - Comments anchor to text. A comment is tied to the range of text it marks. If that text is removed, the comment's anchor goes with it, the same as in any word processor.
- Comment bodies are for discussion text. Basic inline formatting is preserved; complex block-level content inside a comment may be simplified on conversion.