Importing Word (.docx)
Word documents convert client-side via mammoth → turndown. Headings, lists, tables, links, images, bold/italic survive. Macros and complex layouts are dropped.
.docx files convert entirely in your browser — no server roundtrip. The pipeline is:
- Mammoth unzips the .docx and walks the XML to produce semantic HTML
- Turndown (with GFM tables) walks the HTML and emits Markdown
- Any embedded images are extracted, uploaded to our R2 storage via
/api/images/upload, and rewritten asin the output
We picked HTML as the intermediate (rather than mammoth’s built-in markdown writer) because Turndown + GFM gives much better fidelity on real-world Word docs.
Q4 Roadmap
The fourth quarter is structured around three releases.
- Identity v2 ships in October.
- Org audit log ships in November.
- SSO + SCIM ships in December.
| Release | Month | Owner |
|---|---|---|
| Identity v2 | Oct | Sam |
| Audit log | Nov | Lee |
| SSO + SCIM | Dec | Avery |
Q4 Roadmap
The fourth quarter is structured around three releases.
- Identity v2 ships in October.
- Org audit log ships in November.
- SSO + SCIM ships in December.
| Release | Month | Owner |
|---|---|---|
| Identity v2 | Oct | Sam |
| Audit log | Nov | Lee |
| SSO + SCIM | Dec | Avery |
What survives the conversion
| Word element | Markdown result |
|---|---|
| Title / Heading 1-6 | # through ###### |
| Paragraphs | Plain paragraphs |
| Bold, italic, | **bold**, *italic*, ~~strikethrough~~ |
| Bulleted lists, numbered lists | - and 1. lists with proper nesting |
| Tables | GFM pipe tables, header row preserved |
| Hyperlinks | [text](url) inline links |
| Inline code, code blocks | `inline` and fenced blocks |
Embedded images (.png, .jpeg, etc.) | Uploaded to our storage and embedded as  |
| Blockquotes | > blockquotes |
What’s lost or simplified
| Word element | Result |
|---|---|
| Page-level layout (margins, columns, headers, footers) | Dropped — Markdown is flow content, not page-based |
| Complex tables (merged cells, nested tables) | Cells preserved; merges flatten |
| Macros, VBA, ActiveX | Stripped |
| Comments, tracked changes, revisions | Not imported |
| Footnotes, endnotes | Inline-bracketed as plain text (sweetdocs doesn’t support footnote Markdown — see Markdown essentials) |
| Equations (OOXML math) | Dropped (no math support in v1) |
| Drawing canvas, SmartArt, charts | Dropped |
| Embedded videos, OLE objects | Dropped |
| Specific fonts and colors | Dropped — sweetdocs uses your theme |
Image handling
When mammoth encounters an embedded image, our convertImage callback:
- Reads the image bytes from the .docx archive
- Runs them through the same client-side optimizer used for paste/drop uploads (HEIC transcode, EXIF strip, AVIF re-encode, resize) — see Adding images
- POSTs the result to
/api/images/upload(with your auth token) - Replaces the
<img>with<img src="<r2-url>">in the intermediate HTML
If an upload fails (quota, network), that image is dropped from the output and a warning surfaces:
2 images couldn’t be uploaded.
The rest of the import still succeeds — broken images don’t fail the whole conversion.
Errors specific to .docx
| Cause | Message |
|---|---|
| File isn’t a valid .docx (wrong format / corrupted) | “Couldn’t read filename.docx” |
| Image upload quota hit mid-import | Warning per failed image; the import still completes |
| Auth missing for image upload | Same — images skipped, doc imports with warning |
What if the result needs cleanup?
Real Word documents vary widely. Common things to clean up after import:
- Excess blank paragraphs (Word users press Enter for spacing; Markdown uses block spacing)
- Inline tables of contents (Word generates them; in Markdown you write them by hand)
- Section dividers (a horizontal rule may be the closest equivalent)
The AI Author panel can clean up an imported doc in one prompt: “Tighten this imported Word doc — remove excess blank lines and merge fragmented paragraphs.”