Rich-Text Paste & Document Upload

The Backlog.md Web interface editor supports one-click conversion of external rich-text content to Markdown, including paste from Word, Google Docs, and webpages, as well as uploading .docx files. It also supports screenshot paste, automatically uploading images and embedding them into the task body.

Paste as Markdown

In the Markdown editing area of the task editor, copy and paste content directly from an external source. The editor automatically recognizes rich-text HTML and converts it to clean Markdown.

Supported Sources

Paste Flow

1. Select content in the external app and copy.
2. Press Ctrl+V (or Cmd+V) in the Backlog.md editor.
3. The editor reads text/html from the clipboard.
4. Word/Excel-specific markup is cleaned (noisy tags, inline styles, mso-list, etc.).
5. If images are present, they are extracted and uploaded to a temporary directory.
6. Turndown converts the cleaned HTML to Markdown.
7. The conversion result is inserted at the editor cursor position.

If the clipboard does not contain HTML (plain text only), the editor falls back to native paste behavior without extra processing.

Upload Word Documents

In addition to clipboard paste, the editor supports direct upload of .docx files. This is especially useful for documents with many images or complex formatting.

How to Use

In the task editor:

• Click the "Upload Word" button in the editor toolbar and select a local .docx file.
• Or drag and drop a .docx file directly into the editor area.

Conversion Flow

1. The front end sends the .docx file to the back end via POST /api/docx/convert.
2. The back end uses the mammoth library to parse the document and extract text content as HTML.
3. Embedded images in the document are extracted and uploaded to backlog/assets/.temp/.
4. The back end returns the raw HTML, image list, and conversion warnings.
5. The front end uses the exact same cleanHtml + Turndown pipeline as "Paste as Markdown" to convert the HTML to Markdown.
6. Image references are embedded in the body as /assets/.temp/{uuid}.png.

Unified Pipeline Ensures Consistency

Word document upload and rich-text paste share the same front-end conversion logic, ensuring consistent output formats. For complex tables, nested lists, and similar scenarios, the unified pipeline avoids format differences that could arise from back-end direct conversion.

Image Handling

Screenshot Paste

When pasting a screenshot directly (such as from QQ/WeChat or system screenshot tools):

• The image is uploaded as an image/png blob.
• It is saved to backlog/assets/.temp/{uuid}.png.
• A preview thumbnail is shown in the editor.

Webpage Images

When pasted content contains <img> tags from a webpage:

• Data URI images: base64 data is extracted and uploaded to the temporary directory.
• HTTP(S) URL images: downloaded securely by the back end and then uploaded.
• file:// local paths: rejected (browser security restriction).

Promote on Save

All temporary images (including pasted screenshots and images extracted from Word documents) are automatically promoted when the task is saved:

1. The front end scans Markdown for /assets/.temp/ references.
2. It calls POST /api/assets/promote to move files in batches.
3. Images are moved from .temp/ to the permanent paste/ directory.
4. The front end updates URL mappings in the Markdown and then performs the save.

Expired files in the temporary directory (older than 30 minutes) are automatically cleaned up when the server starts.

Limitations and Notes

• File size: single files over 20MB return an error.
• Format support: only .docx file upload is supported; older .doc files must be converted first.
• Corrupted documents: unreadable documents show a readable error message instead of crashing.
• Image size: if a single image exceeds the size limit, it may be skipped or cause the overall operation to fail (depending on policy configuration).