Beauti Doc

A Word-like editor for Markdown in VS Code, made for formal documents: GB/T 8567 software documents (SRS, SDD, test reports, development plans), GB/T 9704 党政机关公文, reports and papers.

The .md file stays the single source of truth. The editor (CodeMirror 6 live preview) styles the text in place and never rewrites text you did not touch: opening a file does not mark it modified, and an edit changes exactly the characters you typed — table cells included. Exports to Word, PDF and HTML use the same numbering and page setup you see in the print layout.

The interface is Chinese-first and follows VS Code's display language (Chinese or English).

Contents

• Getting started
• Features
• Commands
• Keyboard shortcuts
• Settings
• Front matter
• Templates
• Export
• Import and compare
• Sharing for review
• Requirements
• Security and Restricted Mode
• Development

Getting started

Open a .md file and run Beauti Doc: Open as Document (Ctrl+Shift+Alt+D, on macOS Cmd+Shift+Alt+D, the book icon in the editor title, or right-click the file in the Explorer). Ctrl+Shift+Alt+D again, or { } Source, returns to the Markdown source. To always open Markdown this way:

"workbench.editorAssociations": { "*.md": "beautiDoc.editor" }

Beauti Doc opens as an option, so git diffs and search keep using the text editor. Git revisions and read-only files open read-only, and the editor switches in place when that changes. The editor reopens where you left off and follows the VS Code theme.

Features

A Word-style window

Title bar with quick access (save, undo, redo), a ribbon with Fluent (Office) icons, an A4 page on a grey canvas with a ruler, a navigation pane with search, and a status bar with page count, word count, view buttons and a zoom slider. Double-click a tab to collapse the ribbon. Right-click (or Shift+F10) opens Word's context menu for text, links, table cells and pictures; selecting text shows a mini toolbar.

Content

The full syntax is in docs/spec/syntax.md.

Commands

Keyboard shortcuts

On macOS use ⌘ for Ctrl (the ribbon tooltips show the Mac form).

Word shortcuts with no Markdown form (Ctrl+U, Ctrl+E/L/R/J, Ctrl+=, Ctrl+Shift+=) are swallowed so they don't trigger VS Code commands.

Settings

All settings are under beautiDoc.. Document settings resolve as defaults → style preset → VS Code settings → front matter; most have a front-matter key (see below). Settings marked 🔒 are restricted in untrusted workspaces.

Editor

Pictures

Page and style

Numbering, references, notes

Export

Front matter

A YAML block at the top of the document sets document info and overrides settings. Keys accept English or Chinese names. Main keys:

---
title: 软件需求规格说明
文档编号: SRS-2026-001
版本: "1.2"
编制: 张工
日期: 2026-10-20
样式: 国标
标题编号: decimal
toc: true
页边距: {上: 25, 下: 25, 左: 30, 右: 25}
修订记录:
  - 版本: "1.0"
    日期: 2026-09-01
    说明: 初稿
---

The document info card at the top of the editor shows this block; the Design and Layout tabs can write to it (This Document Only). Every key and alias: docs/spec/syntax.md.

Templates

File › New or Beauti Doc: New Document from Template…:

Export

• Page setup and presets: paper, orientation, margins and typography from default, gb (国标正文: 宋体 小四, 1.5 lines, 2-character indent, 黑体 headings), gongwen (GB/T 9704: 仿宋_GB2312 三号, fixed 28.95 pt lines, margins 37/35/28/26 mm, centred — 1 — page number, red 版头) or academic.
• Header/footer: left|center|right with ${title} ${subtitle} ${docNo} ${version} ${author} ${date} ${organization} ${classification} ${page} ${pages} ${today} and any front-matter key.
• Watermark, table of contents ([TOC], <!-- toc --> or toc: true), heading numbers, page breaks (<!-- pagebreak -->, or automatically before chapters).
• Line spacing as a multiple or fixed: 行距: 28磅 (Word's 固定值).
• Reference .docx template (export.docxTemplate / 模板:) supplies Word styles.
• Output folder (export.outputFolder); an existing file asks to overwrite or save as.
• Folder export: every .md/.markdown file in a folder and its subfolders (hidden folders and node_modules skipped) to one or more formats.
• Font check: warns before PDF/Word export when fonts of the style are not installed, naming the fallback.
• Properties: title, author, subject and keywords (export.metadata).

Import and compare

• Import Word Document: converts a .docx into a new Markdown file next to it, pictures saved in the image folder. Cover/properties become front matter; headings (by style or outline level), heading numbering, captions, merged cells, footnotes, equations (OMML → $…$), callouts, the TOC field, and tracked changes and comments (→ CriticMarkup) are kept.
• Compare with Word Document: converts a returned .docx and opens a VS Code diff against the Markdown. Differences the round trip cannot preserve (padding, list markers, escapes, picture widths, front matter) are taken from the original, so the diff shows only real edits.

Both need documents saved on disk.

Sharing for review

Comments, replies and tracked changes are stored in the .md file (CriticMarkup), so a Git repository is all you need to share a document for review. Share the link to the repository or to the file; reviewers need access to the repository, VS Code and Beauti Doc.

1. Author: commit the document and push it, then send the link.
2. Reviewer: clone the repository (or pull), create a branch, open the .md file with Beauti Doc, set beautiDoc.review.authorName once, turn on Track Changes (Ctrl+Shift+E), edit, and add comments (Ctrl+Alt+M) or replies. Save, commit, push the branch and open a pull request.
3. Author: check out the branch, open the document and go through it with 审阅 › previous/next change and thread: accept or reject each change, reply to or resolve comments, then merge.

Because Beauti Doc never rewrites text you did not touch, the pull request diff contains only the reviewer's edits and comments, each an inline {++…++}, {--…--} or {>>…<<} mark. Two reviewers changing the same paragraph get an ordinary Git merge conflict; resolve it in the text (both sets of marks can be kept).

Opening the link in a browser (GitHub, vscode.dev, github.dev) shows the Markdown source, not the Word-style editor: Beauti Doc runs in desktop VS Code only. Reviewers without VS Code can work on an exported Word file instead (see Import and compare).

Requirements

• VS Code 1.85 or later.
• Microsoft Edge or Google Chrome (or Chromium) for PDF export and Mermaid diagrams in Word; set beautiDoc.export.browserPath if it is not found.
• Optional: GitHub Copilot Chat (or another chat provider) for Ask Copilot.
• Node.js 22.18 or later only to build the extension (.nvmrc).

Security and Restricted Mode

• No telemetry. The extension contacts the network only for: web pictures in PDF export (see below), a PlantUML server you configure, and the viewer's browser loading KaTeX/Mermaid for an exported HTML file.
• Restricted Mode: in an untrusted workspace, workspace and folder values of diagram.plantumlServer, export.css, export.docxTemplate, export.outputFolder, imageFolder, citations.bibliography, citations.style and style.fonts are ignored; user settings apply. A workspace imageFolder must also stay inside the document's folder or workspace.
• The editor's ribbon never writes path settings (export.css, export.outputFolder, export.docxTemplate, citations.bibliography) and only built-in citation styles.
• Path confinement: pictures, bibliography, CSL style and Word template named in a document must lie in the document's folder, its workspace (or, for a file opened without a workspace, the folder above it) or the picture folder; links and junctions leading elsewhere are not followed, and network paths (\\server\share, //server/share, file://server/…) are never opened. Paths in your user settings may point anywhere. A picture left out is reported after the export.
• Your name in comments: new comments and replies are signed with review.authorName, or, when it is empty, your operating-system user name, which is then written into the document (and its Word export). Set review.authorName to choose the name.
• PlantUML is off by default; with a server set, diagram source is sent to it.
• Remote pictures: only PDF export downloads them, over http(s) only, never from this machine or the local network: host names are checked, resolved by the extension (DNS check), and the picture is downloaded from the checked address (redirects are checked too; 25 MB / 20 s per picture). Word export does not fetch web pictures. Limit: when an HTTP proxy or a fake-IP proxy tool (Clash and the like) resolves names, a name the proxy maps to its own local network cannot be detected.
• Exports are sanitized: raw HTML keeps formatting only (no scripts, styles, frames or event handlers); diagram SVGs are sanitized. Standalone HTML loads KaTeX and Mermaid from jsDelivr with Subresource Integrity.

Development

npm install
npm run build        # bundles into dist/ and prepares playground/
npm run typecheck    # tsc --noEmit
npm test             # unit tests (vitest)
npm run test:e2e     # webview end-to-end tests in headless Edge (BD_BROWSER=chrome to switch)
npm run test:vscode  # integration tests in a real VS Code
npm run test:all     # build + typecheck + unit + e2e + VS Code
npm run package      # production build + .vsix (pinned @vscode/vsce)

F5 ("Run Beauti Doc") opens playground/, a scratch copy of test/fixtures made by the build, with only Beauti Doc loaded; "Run Beauti Doc (with my other extensions)" is there when you need them. test/fixtures/sample.md must stay byte-identical to the original sample; a unit test checks its hash.

Bundles: dist/extension.js and dist/webview/ load with the editor; dist/export.js (export and import), dist/bibliography.js (citations) and dist/graphviz.js (Graphviz WebAssembly) load on first use.

How sync works. The webview sends every CodeMirror transaction as exact line/character edits; the host applies them with a WorkspaceEdit and recognises its own echo. Changes made elsewhere (git, other editors, format-on-save) come back as the smallest possible edit; edits typed while such a change is in flight are rebased onto it and resent, so no keystroke is lost.

License

MIT