Thesis Docx Sync

python skills/thesis-docx-sync/scripts/build_markdown_chapter.py ^
  --output writing/_chapter4_sync_tmp.md ^
  --title "Chapter 4 Title" ^
  --rewrite-rules skills/thesis-docx-sync/references/thesis_word_rewrites.json ^
  writing/chapter4_4.1.md ^
  writing/chapter4_4.2.md ^
  writing/chapter4_4.3.md ^
  writing/chapter4_4.4.md

For a single source chapter file:

python skills/thesis-docx-sync/scripts/build_markdown_chapter.py ^
  --output writing/_chapter2_sync_tmp.md ^
  --title "第二章 等离子体电磁特性与LFMCW诊断机理" ^
  --drop-leading-heading ^
  --shift-headings 0 ^
  --rewrite-rules skills/thesis-docx-sync/references/thesis_word_rewrites.json ^
  writing/第2章_等离子体电磁特性与LFMCW诊断机理_final.md

For front matter, always build a temporary sync file instead of syncing the raw source Markdown directly:

python skills/thesis-docx-sync/scripts/build_markdown_chapter.py ^
  --output writing/_thanks_sync_tmp.md ^
  --title "致谢" ^
  --shift-headings 0 ^
  writing/致谢.md

python skills/thesis-docx-sync/scripts/build_markdown_chapter.py ^
  --output writing/_author_bio_sync_tmp.md ^
  --title "作者简介" ^
  --drop-leading-heading ^
  --shift-headings 0 ^
  --demote-headings-to-strong 2,3 ^
  writing/作者简介.md

For 作者简介, do not map ## / ### to Word heading styles. The thesis template's Heading 5/6 numbering belongs to the body chapters and will turn manual items such as 1. 基本情况 into chapter-style numbers such as 6.4. For 致谢 and 作者简介, explicitly cross-check the canonical reference pair under resources/word2md/:

• 基于线性调频连续波的等离子体诊断系统设计-终稿-曹杠.docx
• 基于线性调频连续波的等离子体诊断系统设计-终稿-曹杠.md Treat them as the style authority for these two front-matter sections. The target output should preserve the same front-matter role split: a visible top title using the non-numbered title style, followed by body content / subordinate items that visually match the reference thesis rather than inheriting live chapter numbering from the current working DOCX.

5. Run the Markdown preflight check before sync. For this thesis project, the recommended profile is final_output_doc, which flags risky inline math and forbidden helper assets:

python skills/thesis-docx-sync/scripts/preflight_markdown_sync.py ^
  --markdown writing/_chapter4_sync_tmp.md ^
  --profile final_output_doc ^
  --fail-on-warning

6. When the master .docx is an old template, verify the target block by position and neighboring chapter headings, not by chapter number alone. Do not assume the requested Markdown chapter maps to the current fourth Heading 1 in Word.
7. Sync the Markdown section back into the master document:

python skills/thesis-docx-sync/scripts/sync_markdown_to_docx.py ^
  --docx path/to/master.docx ^
  --markdown path/to/chapter.md ^
  --match-heading "Target Heading" ^
  --level 1 ^
  --missing-images placeholder ^
  --output path/to/master_synced.docx

8. After syncing all chapters, run the mandatory comprehensive post-processor. This step is required — without it, body text uses wrong styles, tables lack formatting, captions are unstyled, and images may be clipped:

python skills/thesis-docx-sync/scripts/postprocess_styles.py ^
  --docx path/to/master_synced.docx ^
  --in-place

9. If the output path already exists, make sure Word is not keeping that file open. Otherwise write to a new filename first.
10. Open the output in Word and refresh the table of contents, figure index, and table index if needed.
11. Visually inspect formulas, tables, footnotes, hyperlinks, and chapter breaks.
12. Clean up temporary files:
    • Delete any temporary outline dump files (e.g., temp_outline.txt) created during the workflow
    • Delete temporary merged chapter Markdown files created by build_markdown_chapter.py (e.g., writing/正式参考文献版/_chapter3_sync_tmp.md)
    • Delete all iterative DOCX backup files created during in-place sync/post-process/cover-update steps (e.g., versions/final_name.bak-*.docx)
    • Do not leave sync_markdown_to_docx.py, postprocess_styles.py, update_cover_info.py, or fix_header_borders.py backup DOCX files in versions/ once the final output has been verified
    • If one rollback snapshot must be kept, rename exactly one chosen backup to an explicit archival filename; otherwise remove the whole matching *.bak-*.docx set
13. If the project stores cover metadata in a Markdown file such as 封面信息.md, update the working DOCX cover after the section sync:

python skills/thesis-docx-sync/scripts/update_cover_info.py ^
  --docx path/to/master_synced.docx ^
  --cover-markdown writing/正式参考文献版/封面信息.md

When the thesis has switched to another official cover variant, replace the cover/title-page block from the canonical template before filling metadata:

python skills/thesis-docx-sync/scripts/update_cover_info.py ^
  --docx path/to/master_synced.docx ^
  --cover-markdown writing/正式参考文献版/封面信息.md ^
  --cover-template-docx writing/2、西安电子科技大学专业学位硕士学位论文封面及中英文题名页模板（2015年版）-2022.11修订.docx

For this thesis repository, when 封面信息.md states 申请学位类别:工程硕士 or otherwise indicates the professional-degree cover, treat the first 7 pages as a special front-matter block: replace them from the official professional-master template first, then fill the metadata fields. Do not keep the academic-master front pages from resources/word2md/ in that case.

If Word is locking the target output during cover replacement, write to a new filename first (for example versions/codexv1_engineering_cover.docx), then overwrite the canonical working file only after the user closes the locked document.

Rules

• Treat the target .docx as the layout authority.
• Use --reference-doc against the target .docx or a style-identical template so pandoc emits compatible heading and paragraph styles.
• Replace only one heading-bounded section at a time.
• Prefer chapter or section headings that already exist in the master Word file.
• When syncing into a legacy thesis template, identify the replacement block from the actual Word outline, not from the intended chapter number in Markdown.
• If one logical chapter is stored as multiple Markdown files, merge them before sync and shift all heading levels down by one under a chapter-level heading.
• Keep merged temporary Markdown next to the original chapter files when the source uses relative image paths such as figures/....
• For this thesis repository, prefer the canonical reference thesis DOCX under resources/word2md/ as the layout mother file when front-matter headers, section breaks, TOC pages, and page styles must match the school template exactly.
• Run preflight_markdown_sync.py before every real sync when the chapter contains figures or dense math.
• Image paths follow the Markdown source: use whatever path is written in the .md file. Do not restrict images to a single canonical directory.
• Do not create helper images such as sync_fig*.png or _preview_*.png inside figure directories. Temporary conversions, previews, and staged copies must live under a temp directory only.
• In running text, flatten simple inline fractions to slash notation such as $d\tau_g/df$, $2\pi B/T_m$, or $d(f_p/f)^2/(2c)$ when that improves Word readability.
• Prefer script-driven rewrite rules over manual edits to temporary merged Markdown. For this repository, use skills/thesis-docx-sync/references/thesis_word_rewrites.json as the first pass for Word readability rewrites; extend that file when the same pattern recurs.
• Keep numbered derivations and display equations as block equations. Do not flatten numbered formulas solely for convenience.
• Avoid display-style constructs such as \frac, \dfrac, \underbrace, \left...\right, or long nested expressions inside inline math when a simpler body-text form is available.
• Strip Markdown heading prefixes such as 第二章, 2.1, or 2.4.1 before rendering when the target Word template already applies automatic heading numbering.
• Allow front-matter anchors such as 摘要 or ABSTRACT when the Word template uses a non-numbered title style instead of Heading 1.
• Allow local Markdown image references and display equations with \tag{...}; the script preprocesses those two cases before rendering.
• If a Markdown image path is broken or the user wants to reuse figures that only exist inside another Word thesis, pass --image-source-docx. The script will fall back to that DOCX and match figures by number such as 图5-1.
• Allow explicit DOCX-backed image placeholders like ![图5-1 宽带LFMCW诊断系统扩频后的射频前端链路架构](docx-figure://图5-1) when the source Markdown should not depend on a local image file path.
• If source image files are missing but the text sync still needs to proceed, use --missing-images placeholder to replace those image nodes with visible placeholder text in the output DOCX.
• Allow footnotes, endnotes, external hyperlinks, and internal #anchor jump links generated by pandoc.
• For bibliography citations generated as external links such as 参考文献.md#ref-12, retarget them to internal Word bookmarks like ref-12 instead of leaving file links or dropping click-through entirely.
• Align the first inserted heading paragraph to the target heading style so front-matter titles keep the template's existing formatting.
• Treat the table of contents and figure/table indexes as field-generated pages. Update them in Word after sync instead of editing those pages manually.
• Keep tracked changes, comments, and embedded OLE objects out of the Markdown fragment.
• Do not assume equation numbers will land in exactly the same visual position as a hand-crafted Word equation template; verify the layout after sync.
• If the user asks to modify a legacy .doc, convert it to .docx first instead of attempting direct .doc editing.
• Preserve existing front-matter section breaks when replacing 标题-无编号 sections such as 摘要, ABSTRACT, 符号对照表, or 缩略语对照表; otherwise Word headers can drift to the wrong section.
• For level-0 front-matter anchors such as 作者简介, keep nested sub-items inside the same replacement block. The section must end at the next peer front-matter title or chapter title, not at the first internal subheading.
• Temporary-file cleanup is part of the workflow, not optional polish. After final verification, remove generated _sync_tmp.md files and DOCX backups matching the current output stem such as versions/论文名.bak-*.docx.
• For 致谢, the heading must visually match the reference thesis front matter: keep a standalone visible 致谢 title in 标题-无编号 style, then body paragraphs in the normal body-text style. A raw body-only Markdown file is not enough; build a temporary file with the title before sync.
• For 作者简介, use the reference thesis as a style sample but not as a literal heading-depth prescription. The reference .md shows #####/###### because the original mother file stored those lines with Heading 5/6 formatting, but when that numbering chain is live in the working DOCX, directly reusing Heading 5/6 causes wrong labels such as 6.4. In that case, preserve the reference section's visual hierarchy with manual numbered bold paragraphs or another non-numbered equivalent, instead of inheriting chapter counters.
• After the normal sync/postprocess pass, run apply_reference_author_bio_style.py on the final DOCX so the 作者简介 subheading paragraphs are re-mapped to the canonical reference thesis styles instead of staying as plain bold body text.
• For this thesis repository, the final 符号对照表 should omit the 单位 column by default. Run strip_symbol_table_units.py on the final DOCX unless the user explicitly asks to keep the three-column layout.
• For this thesis repository, formulas and formula symbols in the final DOCX should use Times New Roman. Run force_math_font_tnr.py --in-place as a post-processing step. It performs three actions: (a) update the default math font in settings.xml, (b) rewrite every OMML math run (m:r) 's w:rFonts to Times New Roman, and (c) set ascii/hAnsi/cs on regular w:r runs that are immediately adjacent to inline m:oMath blocks so the cursor at formula boundaries also shows Times New Roman instead of the paragraph's default font (e.g. 宋体). CJK eastAsia font hints are preserved on adjacent runs.
• set_math_font.py only updates settings.xml metadata and may not be sufficient — Word can still render existing OMML runs with Cambria Math. Prefer force_math_font_tnr.py which explicitly sets font on every m:r element and adjacent boundary runs.
• If after force_math_font_tnr.py Word still shows Cambria Math for some equations, those equations may need a live Word/MathType reflow pass.
• If the thesis cover has changed from academic-master to professional-master style, replace the cover/title-page block from the official professional template before updating 封面信息.md fields.
• For this repository, writing/2、西安电子科技大学专业学位硕士学位论文封面及中英文题名页模板（2015年版）-2022.11修订.docx is the default cover source whenever the requested degree type is 工程硕士 / professional master.
• If the user explicitly wants the cover to stay visually aligned with the canonical reference thesis under resources/word2md/, use that reference DOCX as the cover source and adapt its labels/fields to the requested degree type instead of switching to another school template.
• When filling an official cover template that uses red placeholder text or content controls, strip the placeholder's direct font color/shading after replacement so filled fields inherit the normal template style.
• After swapping in an official cover template, normalize the cover block's section breaks and remove redundant empty section-only paragraphs before 学位论文独创性（或创新性）声明; otherwise Word may insert extra blank pages between the English cover and the declaration pages.
• For Chinese author and supervisor fields on the official cover, fill the full name into the first editable slot and clear the follow-up split-name slot; do not keep artificial surname/given-name spacing in the filled result.
• Treat the professional-master cover replacement as a front-matter-only operation: preserve the already-synced body chapters, abstract pages, reference section, and their section structure after page 7.
• Accept tracked insert/delete revisions in the cover block after metadata replacement; otherwise Word may display the newly filled cover fields in revision red even when the direct font color has already been cleared.
• For 符号对照表 and 缩略语对照表, treat Markdown tables as source data only. The synced DOCX should flatten those tables into paragraph-style line entries consistent with the reference thesis, not keep them as Word tables.
• When flattening 符号对照表, preserve OMML/math nodes from the first column instead of extracting only plain w:t text; otherwise symbols such as $n_e$ or $\tau_g(\omega)$ disappear.
• For 缩略语对照表, keep the mother template's tab-stop layout and acronym character style instead of emitting plain left-aligned text.
• IMPORTANT: fix_header_borders.py should run after any sync or cover replacement. The thesis template's header style (id ae) defines a double bottom border. After pandoc-based sync, some header XML paragraphs may be reset to style a4 (Normal Indent) which has no border, causing the underline to disappear. This script auto-detects the correct header style id and rewrites all non-conforming header paragraphs. Run it once on the final output after all syncs and post-processing are complete.
• IMPORTANT: strip_symbol_table_units.py removes the unit column from the 符号对照表. The symbol table uses a 3-column tab layout (symbol / unit / description). This script removes the middle column by deleting the unit text and the third tab character, leaving a 2-column layout (symbol / description). It handles inline OMML math in the symbol column and preserves bookmarks. It keeps only the first "符号 物理含义" header row and deletes all duplicate header rows that repeat mid-table. Run it once after syncing; it is idempotent on already-stripped files (entries with fewer than 3 tabs are skipped).
• IMPORTANT: postprocess_styles.py is mandatory after every sync. It now handles ALL of the following:
  • Body text style remapping (pandoc → Normal)
  • Figure caption detection (after image paragraphs → 标题-图)
  • Table caption detection (before w:tbl elements → 标题-表格)
  • Reference section styling (after 参考文献 heading → 参考文献)
  • Reference numbering normalization back to the mother template's bibliography list definition
  • Citation hyperlink retargeting for pandoc-generated 参考文献.md#ref-* links so正文引文 can jump to internal bibliography bookmarks
  • Display equation styling (paragraphs with m:oMathPara → 公式)
  • Table formatting: 三线表 style (thick top/bottom borders, thin header separator, no vertical lines, centered, 10.5pt font)
  • Image paragraph formatting: centered, auto line spacing
  • Page header updates: correct "第X章 标题" text per chapter, written to the section-ending sectPr that actually controls that chapter's pages
• When syncing multiple chapters in sequence, sync ALL chapters first, then run postprocess_styles.py once on the final output. Running it per-chapter is also fine but unnecessary.
• The --level CLI argument for sync_markdown_to_docx.py only accepts values 1–9. For level-0 headings (e.g., 摘要, ABSTRACT with 标题-无编号 style), omit the --level flag entirely — the heading text alone is sufficient for unique matching.

Markdown Preparation Rules

CRITICAL: Figure and table captions must NOT include number prefixes.

The Word template's 标题-图 and 标题-表格 styles apply automatic numbering (图3.1, 表4.2, etc.). If the Markdown caption also includes the number, the output will show duplicated numbering like "图3.1 图3.1 caption text".

• Figure captions: Write ![caption text](path) — not ![图3.1 caption text](path)
• Table captions: Write just caption text on the line before the table — not 表4.1 caption text
• Bold-wrapped captions like **表4.2 title** must also be stripped to just title

参考文献.md must have a heading.

The file writing/参考文献.md must start with # 参考文献 on the first line. Without it, the sync script replaces the heading text in Word with the first reference entry.

Complex inline math may be invisible in Word.

Inline math ($...$) containing \frac, \sqrt, or \boxed may render as invisible zero-height OMML in Word. Before sync:

• Convert complex inline fractions to display math blocks ($$...$$)
• Or simplify to slash notation: $\frac{a}{b}$ → $a/b$
• Remove \boxed{} from any formula (use plain display math instead)

Commands

• Dump outline:

python skills/thesis-docx-sync/scripts/dump_docx_outline.py path/to/master.docx

• Merge split Markdown files into one chapter file:

python skills/thesis-docx-sync/scripts/build_markdown_chapter.py ^
  --output path/to/chapter_merged.md ^
  --title "Chapter Title" ^
  --rewrite-rules skills/thesis-docx-sync/references/thesis_word_rewrites.json ^
  path/to/section1.md ^
  path/to/section2.md

• Preflight Markdown before sync:

python skills/thesis-docx-sync/scripts/preflight_markdown_sync.py ^
  --markdown path/to/chapter_merged.md ^
  --profile final_output_doc ^
  --fail-on-warning

• Sync to a new output file:

python skills/thesis-docx-sync/scripts/sync_markdown_to_docx.py ^
  --docx path/to/master.docx ^
  --markdown path/to/chapter.md ^
  --match-heading "Target Heading" ^
  --level 1 ^
  --missing-images placeholder ^
  --output path/to/master_synced.docx

• Post-process (mandatory, comprehensive):

python skills/thesis-docx-sync/scripts/postprocess_styles.py ^
  --docx path/to/synced.docx ^
  --in-place

• Post-process without header updates:

python skills/thesis-docx-sync/scripts/postprocess_styles.py ^
  --docx path/to/synced.docx ^
  --no-headers ^
  --in-place

• Fix header border styles (all page headers show the template bottom line):

python skills/thesis-docx-sync/scripts/fix_header_borders.py ^
  --docx path/to/synced.docx ^
  --in-place

• Re-apply canonical 作者简介 paragraph styles from the reference thesis:

python skills/thesis-docx-sync/scripts/apply_reference_author_bio_style.py ^
  --docx path/to/synced.docx ^
  --reference-docx resources/word2md/基于线性调频连续波的等离子体诊断系统设计-终稿-曹杠.docx ^
  --in-place

• Set the OMML default math font in settings.xml (metadata only):

python skills/thesis-docx-sync/scripts/set_math_font.py ^
  --docx path/to/synced.docx ^
  --font "Times New Roman" ^
  --in-place

• Force all OMML math runs and adjacent boundary runs to Times New Roman (preferred over set_math_font.py):

python skills/thesis-docx-sync/scripts/force_math_font_tnr.py ^
  --docx path/to/synced.docx ^
  --in-place

• Remove the unit column from 符号对照表:

python skills/thesis-docx-sync/scripts/strip_symbol_table_units.py ^
  --docx path/to/synced.docx ^
  --in-place

Resources

• Use scripts/dump_docx_outline.py to discover stable anchors before any edit.
• Use scripts/build_markdown_chapter.py when one logical chapter is stored as several Markdown files.
• Use scripts/preflight_markdown_sync.py to catch off-policy image paths and inline-math readability risks before rendering.
• Use scripts/sync_markdown_to_docx.py for section replacement.
• Use scripts/docx_figure_catalog.py to inspect which figure numbers a source DOCX can provide before relying on DOCX-backed image fallback.
• Use scripts/postprocess_styles.py after every sync — it is the single comprehensive post-processor that handles style remapping, caption detection, table formatting (三线表), image layout, and page headers.
• Use scripts/update_cover_info.py when the thesis keeps cover metadata in Markdown and the target DOCX cover/front-matter must be refreshed together with the body chapters.
• Use scripts/fix_header_borders.py after any sync or cover replacement if page headers lose their bottom border line. The thesis template defines a double bottom border on the header style (style-id ae); pandoc or manual editing may reset header paragraphs to a4 (Normal Indent) which lacks the border.
• Use scripts/apply_reference_author_bio_style.py after postprocess_styles.py when the DOCX includes 作者简介. It copies the canonical reference thesis paragraph styles for that section's subheadings and strips temporary manual numbering prefixes so the final display matches the school thesis sample more closely.
• Use scripts/force_math_font_tnr.py after the main sync/postprocess pass to force all OMML math runs and their adjacent boundary runs to Times New Roman. It rewrites every m:r element's w:rFonts in document.xml, footnotes, endnotes, and headers/footers; sets ascii/hAnsi/cs on w:r runs immediately adjacent to inline m:oMath so the cursor at formula edges also shows Times New Roman; and updates the default math font in settings.xml. This is the preferred math-font post-processor for this thesis.
• Use scripts/set_math_font.py only when metadata-level OMML math-font alignment is sufficient (settings.xml only, does not touch individual math runs).
• Use scripts/strip_symbol_table_units.py when the 符号对照表 should show only symbol and description columns (no unit column). The script removes the unit text and the third tab from every aff2-styled paragraph between the 符号对照表 and 缩略语对照表 headings.
• Read references/workflow.md when the user needs scope, constraints, or failure handling.

Decision Notes

IMPORTANT: Abstract files must be split into separate files.

• The Chinese abstract (摘要_中文.md) and English abstract (摘要_英文.md) MUST be stored as separate Markdown files.
• Each abstract file must contain ONLY ONE top-level heading (# 摘要 or # ABSTRACT).
• NEVER combine both abstracts in a single file — this will cause heading conflicts during sync and result in duplicate "Abstract" entries in the Word document.
• When syncing abstracts, omit the --level flag (the CLI does not accept --level 0). The heading text 摘要 or ABSTRACT is unique enough for matching.
• Sync order: Chinese abstract first, then English abstract.

IMPORTANT: Chapter title matching.

• When merging multiple Markdown files into one chapter, use the FULL chapter title (e.g., "第三章 宽带信号在色散介质中的传播机理与方法失效分析") as the --title parameter, NOT just "第3章".
• The merged file's first heading must match the Word template's existing chapter heading text.

IMPORTANT: Full multi-chapter sync workflow.

When syncing all chapters at once, follow this order:

1. Copy the master .docx to a working copy (never overwrite the master directly).
2. Sync abstracts: Chinese (--match-heading "摘要", no --level) → English (--match-heading "ABSTRACT", no --level).
3. Sync 符号对照表 and 缩略语对照表 (--match-heading, no --level).
4. Sync chapters 1–6 sequentially, each with --in-place on the working copy. Use --match-heading with the exact heading text from the Word outline, not the Markdown heading.
5. Sync 参考文献 (--match-heading "参考文献", no --level).
6. Sync 致谢 (--match-heading "致谢", no --level) and 作者简介 (--match-heading "作者简介", no --level) from the temporary files built above, not from the raw Markdown sources.
7. Run postprocess_styles.py --in-place once on the final working copy.
8. Run apply_reference_author_bio_style.py --in-place so 作者简介 matches the canonical reference thesis styles.
9. Run force_math_font_tnr.py --in-place for this thesis repository's final equation-font requirement (rewrites every OMML math run to Times New Roman).
10. Run strip_symbol_table_units.py --in-place for this thesis repository's final two-column 符号对照表 layout.
11. Run fix_header_borders.py --in-place to restore the bottom border on all page headers.
12. Open in Word, refresh TOC / figure index / table index, inspect images and tables.
13. If the degree type is 工程硕士 / professional master, run update_cover_info.py --cover-template-docx ...专业学位硕士学位论文封面及中英文题名页模板... after the body sync and verify that the first 7 pages now match the professional-master format instead of the academic-master mother file.

IMPORTANT: Heading-to-file mapping for this thesis.

IMPORTANT: Pandoc style mismatch — postprocess_styles.py is mandatory.

Full style remapping table:

• If the requested fragment contains images or Word-only objects that are not ordinary Markdown images, split the task: sync text automatically, then place those objects manually in Word.
• If Markdown image file paths are broken because of historical encoding damage or missing asset folders, prefer --image-source-docx over hand-copying figures from Word.
• If the project already has a canonical figure directory, do not generate helper assets inside it just to satisfy DOCX insertion. Fix the Markdown path or stage conversions in a temp folder instead.
• If the chapter contains dense inline formulas, preflight them first and rewrite only the running-text expressions that hurt Word readability. Leave numbered display equations intact.
• If the requested change spans many chapters, still execute one heading-bounded section at a time to reduce corruption risk.
• If heading text differs between Markdown and Word, trust the existing Word heading and use it as the anchor.
• If the requested chapter exists only as several section Markdown files, use scripts/build_markdown_chapter.py to create a temporary merged chapter file before sync.
• If the output file is open in Word, write to a new output path or close Word before rerunning the sync.
• If the chapter updates headings, captions, bookmarks, or note references, refresh fields in Word before judging the table of contents or figure/table index pages.