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 when the Word template uses a non-numbered title style instead of .

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.

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.