docx-template-translator

name	docx-template-translator
description	Adaptive conversion of LaTeX, PDF, or Markdown sources into a complete Word .docx that follows a user-supplied .docx template. Use when pandoc --reference-doc alone is not enough — for thesis, dissertation, report, or institutional Word formatting that needs cover pages, declarations, TOC, heading numbering, captions, three-line tables, equations, citations, and visual verification.

DOCX Template Translator

Core Idea

Treat the input file as the content source and the Word template as the formatting source. Do not expect pandoc or PDF import to infer template semantics. Build a project-specific Python postprocessor after inspecting the template and the converted body document.

Do not treat the bundled starter pipeline or a preset JSON file as a finished converter for institutional templates. For thesis/dissertation templates, you must create or patch a project-specific pipeline for the concrete template and source project before claiming success.

Workflow

1. Identify inputs:
   • Source: .tex project, .pdf, .md, or an existing rough .docx.
   • Template: required .docx.
   • Output location and document metadata.
2. Inspect the template with the real CLI form:
   • python scripts/inspect_docx_template.py template.docx --out template_report.json
3. Create a rough body .docx:
   • LaTeX/Markdown: use pandoc when available.
   • PDF: try Word COM import or pdf2docx; prefer PDF only when the original source is unavailable.
   • Existing DOCX: use it as the rough body source.
4. Write or patch a project-specific Python pipeline:
   • Start from scripts/adaptive_docx_pipeline.py.
   • Copy it into the run/output directory or project workspace before patching; do not edit the bundled script in place for a one-off conversion.
   • Decide, from the template inspection, which template paragraphs/tables/sections are reusable and which are sample placeholders to delete.
   • Mark protected native-template regions before coding. For thesis templates, cover pages, English cover pages, originality/declaration pages, authorization pages, signatures, and their section breaks are protected by default until the first generated abstract/body marker.
   • Replace or fill template front matter such as cover pages, declarations, abstracts, keywords, TOC placeholders, headers, footers, page numbering, and section breaks when the source provides those fields.
   • In protected regions, replace text inside existing paragraphs/runs/tables without deleting and rebuilding the paragraph. Preserve paragraph styles, run fonts/sizes/bold, alignment, spacing, and page breaks unless the user explicitly asks to alter the template.
   • Insert the rough body at the real body start or rebuild the document around the template parts. Do not blindly append the rough body to the end of the template.
   • Copy template front matter if needed.
   • Append rough body content while remapping DOCX relationships.
   • Remap copied style IDs by visible style name before applying formatting; otherwise Heading 1/2/3 can silently become an unrelated template style when source and template style IDs collide.
   • Remap styles to the template's real body, heading, caption, reference, and TOC styles.
   • Scope global formatting passes to generated content only, for example with formatting_start_marker. Never run body-style remapping across native cover/declaration pages.
   • Clean or rebuild section header/footer references when deleting sample template sections; stale back-matter headers such as 致谢 must not appear on body pages.
   • Add or repair figure/table captions, table borders, hyperlinks, bookmarks, citations, and page breaks.
5. Finalize with Microsoft Word when available:
   • Use scripts/finalize_word_docx.py to update fields/TOC and export a PDF preview.
6. Automated and visual verification:
   • Use scripts/validate_docx_conversion.py final.docx --template template.docx --protected-until "中 文 摘 要" --pdf final.pdf --out validation.json for placeholder/order/header/image/table checks plus protected-front-matter format checks. Choose the real first generated marker for non-Zhengzhou templates.
   • Then run scripts/validate_docx_render.py final.docx --pdf final.pdf --out validation_render.json for render-level checks: TOC field presence, numId↔abstractNum consistency, multilevel heading format, reference-counter independence, body-header static-text leakage, and PDF field-error strings. The structural validator can return PASS while the document is visibly broken; the render validator is what catches "empty TOC", "chapters not auto-numbered", "references start at [47]", "body header still says 致谢", and "STYLEREF prints 错误!使用'开始'选项卡…".
   • Use scripts/render_pdf_preview.py to inspect cover pages, abstracts, TOC, representative tables, figures, formulas, and references.

Mandatory Quality Gate

Before reporting success, run an automated and visual QA pass. If any check fails, patch the project-specific pipeline and rerun; do not present the output as complete.

• Confirm the rough body is not appended after a back-matter placeholder such as 致谢, Acknowledgements, 参考文献, or sample appendices.
• Confirm template placeholder text is gone or intentionally preserved. Common failures include names like 李四, 王五, 张三, red formatting instructions, lorem ipsum, sample chapter headings, and template-only reference lists.
• Confirm source metadata and source front matter replaced the template placeholders: title, author, advisor, major/department, date, Chinese abstract, English abstract, keywords, declarations when applicable.
• Confirm protected front matter still matches the template's formatting. Content may change, but cover/declaration/signature pages must preserve paragraph styles, run-level fonts/sizes/bold, spacing, alignment, and page-break structure unless explicitly modified.
• Confirm TOC entries point to the generated source chapters, not only to the template's sample chapters.
• Confirm heading paragraphs are still heading styles after OOXML insertion; style ID collisions must not break TOC generation.
• Confirm body pages use the intended body style and do not inherit the last template section's header/footer.
• Confirm representative images, formulas, tables, captions, references, and citations survive the reconstruction.
• Record failures in the run report with PASS/FAIL/PARTIAL wording and concrete evidence.

Render-level Quality Gate (validate_docx_render.py)

The structural quality gate above checks counts and presence. It can return PASS while the rendered Word/PDF is visibly broken because pandoc-derived DOCX bodies often ship with a TOC paragraph that has no field, a Heading 1 style with no <w:numPr>, a numId rebound to a single-level abstract during reference repair, or a body section header whose static text is "致谢". Run validate_docx_render.py after validate_docx_conversion.py to catch those:

• TOC field presence: <w:fldChar w:fldCharType="begin"> plus <w:instrText> TOC . If absent, Word's "update fields" cannot populate a non-existent TOC. Use scripts/inject_toc_field.py to add one before finalization.
• numId ↔ abstractNum consistency: every (numId, ilvl) pair used by a paragraph or by a style's <w:numPr> must resolve to a defined <w:lvl ilvl=N> inside the bound abstract numbering. Missing levels silently fall back to level 0 — that is how 1.1 / 1.1.1 headings collapse to [1] after a reference repair re-points numId=1 at a single-level abstract.
• Multilevel heading format: the abstract numbering bound to Heading 1 (whether at style level or via inline numPr on body H1 paragraphs) must have lvlText matching the user-supplied chapter prefix pattern (default 第%1章 or Chapter %1) at level 0 and a multilevel pattern (default contains both %1 and %2) at levels 1/2. Configure with --chapter-prefix-pattern and --multilevel-pattern for non-default templates.
• Reference counter independence: any non-heading paragraph appearing after the last 参考文献 / References Heading 1 must not reuse a numId already used by Heading 1/2/3. This is the bug where 33 references render as [47]–[79] because their counter was shared with H2/H3 paragraphs upstream.
• Body header is not a back-matter literal: for every body section that uses a <w:headerReference>, the referenced headerN.xml must either contain a Word field (<w:fldChar>) or its static text must not equal 致谢 / Acknowledgements / 参考文献 / 附录 / 攻读学位期间…. The recommended fix is scripts/set_styleref_header.py --style-id 1 so the header dynamically shows the current chapter title.
• PDF field errors absent: scan the exported PDF for the localized field-error strings (错误!, Error!, !Reference source not found, ). These appear when STYLEREF/PAGEREF/REF can't resolve their target and are an immediate FAIL.

Demote any single check to a warning with --allow <check-name> when a project intentionally omits a TOC, intentionally shares a counter, etc.

Required Engineering Rules

• Prefer deterministic Python and OOXML operations over manual Word edits.
• Preserve content first; only change formatting unless the user explicitly asks to edit text.
• Treat native cover/declaration/signature pages as protected regions. Do not use delete-and-recreate paragraph replacement there; mutate existing runs/cells or use a project-specific OOXML placeholder replacement that preserves formatting.
• Any all-document style, table, hyperlink, heading-page-break, or font pass must have an explicit scope. If the template has front matter, start the scope after the protected marker rather than iterating over every doc.paragraphs / doc.tables.
• Keep a generated PDF preview beside the final DOCX.
• After copying OOXML between DOCX files, remap w:pStyle, w:rStyle, and w:tblStyle IDs by visible style name unless you have a stronger project-specific mapping.
• If the template contains sample back matter, explicitly inspect or remove section headerReference / footerReference entries after deleting sample sections.
• For LaTeX, extract structured information from .tex, .aux, .bbl, .toc, and source captions when pandoc loses numbering or labels.
• For equations, preserve pandoc-generated OMML when possible; avoid touching paragraphs containing m:oMath unless necessary.
• For hyperlinks, explicitly set black/no-underline styling if the target template requires print-style links.
• For references, add bookmarks at bibliography entries before converting in-text numeric citations into internal hyperlinks. Allocate a fresh numId (and a matching <w:abstractNum> with level 0 = [%1]) for the reference list — do not reuse the heading numId. Sharing the counter is what produces "33 references rendered as [47]…[79]" because the counter accumulates through every Heading 2/3 paragraph upstream.
• For institutional templates, avoid generic style names like Body Text; inspect the template because those names may be repurposed.
• For finalization, always run with macros disabled. The bundled finalize_word_docx.py sets Word.Application.AutomationSecurity = msoAutomationSecurityForceDisable before opening the document; do not loosen this for inputs of unknown provenance.
• Three-line table coercion is opt-in ( or in config). Don't enable it unless the target template actually requires that layout.

Common Pitfalls (with concrete fixes)

These are recurring failures observed when running this skill on real institutional templates. Each line names what to look for and which script or rule fixes it.

• Empty TOC paragraph. The rough body has a "目录 / Table of Contents" heading but no <w:fldChar> field after it. Word's "update fields" pass does nothing. → Run scripts/inject_toc_field.py final.docx --in-place before finalization, or detect via the toc-field check in validate_docx_render.py.
• Chapters do not auto-number. The Heading 1 style has no <w:numPr> and the body H1 paragraphs also have no inline numPr. → Either add <w:numPr><w:ilvl w:val="0"/><w:numId w:val="N"/></w:numPr> to the Heading 1 style, or insert paragraph-level numPr on every body H1 (skip the unnumbered front/back-matter titles like 摘要/ABSTRACT/参考文献/附录/致谢/攻读…). Detected by the multilevel-headings check.
• Section numbers render as [1], not 1.1 / 1.1.1. A reference repair re-pointed numId=1 at a single-level abstract list. Heading 2/3 paragraphs use (numId=1, ilvl=1/2) and fall back to level 0 = [%1]. → Restore the multilevel binding (the abstractNum whose level 0 is 第%1章 and level 1/2 contain %1.%2 / %1.%2.%3) and assign references their own numId. Detected by the numbering-consistency check.
• References start at [47] instead of [1]. The reference list shares numId=1 with body Heading 2/3 paragraphs, so the counter has already advanced through 46 sections before it reaches [1]. → Allocate a fresh numId for the reference list. Detected by the ref-counter-independence check.
• Body running header reads "致谢". Body and back-matter were collapsed into one section, and that section uses a headerReference whose target headerN.xml has the static text 致谢. → Run scripts/set_styleref_header.py final.docx --header headerN.xml --style-id 1 --in-place to replace the static text with a STYLEREF field that resolves to the current chapter heading. Detected by the body-header-non-back-matter check.
• Header prints 错误!使用'开始'选项卡… or . A field references the of the heading style; on localized templates the actual style name is "heading 1" (lowercase) or "标题 1", and the field cannot resolve. → Use (the numeric ); defaults to this. Detected by the check when is supplied.

Validator-authoring discipline

When you add or change a check inside validate_docx_render.py (or any text-pattern rule that disambiguates between candidates), follow these two rules. Both come from real regressions on this skill.

1. Translate every user-visible requirement into its own enforcement, not just its own detection. When the template demands "captions must be 图 X.Y 说明 AND centered", that is two requirements. A single check_caption_format that filters paragraphs to "those already matching 图 X.Y …" and then checks w:jc=center only enforces the centering half — captions that lost the 图 X.Y prefix are silently dropped from the candidate set and never reported. Split such checks into one per requirement (in this skill: caption-numbering, caption-centering, caption-untagged-near-figure-table) and make sure the candidate filter for each does not depend on the other requirements being met. The candidate filter for the "numbering" check must accept paragraphs whose lead is 图/表 with a digit follow (so body sentences like 表格型 Q-learning… or 表中的实验配置… are excluded by the \d requirement, not by accidentally matching the numbering pattern).

2. Disambiguation rules need a unit test before commit. When a citation or anchor disambiguator picks one of N candidates by a heuristic ("with et al. → the one with more secondary authors"), write the minimal unit test first: assert disambig("(Lozano-Cuadra et al. 2024)") == "lozano2024". The fall-back direction (keys_sorted[0] vs keys_sorted[-1]) is coin-flip easy to write backwards from the comment, and the only cheap way to catch the inversion is a fixture-driven test, not code review. For the GB/T 7714 citation rewriter specifically: when two bbl entries share (surname, year) and both carry et al., prefer the one whose secondary-author set or first-author initial matches the rendered author-year token; use word-boundary \b<initial>\b matching so a single-letter initial does not accidentally match inside et al. itself.

When a user files a list of complaints (e.g. "red text / double numbering / reference numbers / wrong header"), treat the list as a sample, not as an exhaustive bug catalog. Before reporting completion, run an explicit "source vs output" content audit at minimum:

1. Count \includegraphics (or equivalent figure references) in the source project and compare to <w:drawing> in the final docx.
2. Count \caption directives and compare to caption-styled paragraphs.
3. Count \begin{table} and compare to <w:tbl> count with three-line borders applied if the template requires three-line tables.
4. Walk the contact-sheet preview PNG of the exported PDF and look at every page where a body chapter starts; compare visible figure count and visible table border style against the source.

Concretely, do not declare success based only on a structural validator's PASS. Run the render validator with --source-latex-dir, --expected-table-style, and --pdf, and fix anything they surface.

Script Guide

• scripts/inspect_docx_template.py: dumps template styles (including those defined but unused in the body), paragraphs, tables, section settings, numbering hints, and hyperlink colors.
• scripts/adaptive_docx_pipeline.py: reusable starter pipeline for template-based reconstruction. It is a code base to copy and patch, not a final institutional-template converter. Behavior is config-driven (--config). It remaps copied DOCX style IDs by visible style name by default, provides run-preserving replacement helpers for protected regions, and can scope formatting with formatting_start_marker / formatting_end_marker. Optional config keys include clear_header_references, clear_footer_references, and heading_1_page_breaks. Three-line tables and other Chinese-thesis-specific tweaks are opt-in.
• scripts/finalize_word_docx.py: updates Word fields/TOC and optionally exports PDF through Word COM. Disables macros for safety, bootstraps missing Windows environment variables, and falls back through EnsureDispatch, DispatchEx, and Dispatch; use --prefer-dispatch-ex when an existing Word instance is unreliable.
• scripts/validate_docx_conversion.py: structural QA for common failures, including template placeholders, body/back-matter ordering, heading-style preservation, inherited section headers, image/table counts, and protected front-matter format drift against the original template.
• scripts/validate_docx_render.py: render-level QA that complements the structural validator. Twelve checks (TOC field, numbering consistency, multilevel heading format, reference-counter independence, body-header literal, figure-count-vs-source, table-border-style, citation-coverage, caption-count-vs-source, caption-numbering, caption-centering, caption-untagged-near-figure-table) plus the pdf-field-errors check when --pdf is supplied; each can be demoted with --allow. Run after Word COM finalization.
• scripts/inject_toc_field.py: idempotently insert a { TOC \o "1-3" \h \z \u } field after the 目录 / Contents / Table of Contents heading. Use when a rough conversion produced a TOC heading without a TOC field. Word's "update fields" cannot populate a TOC that isn't there.
• scripts/set_styleref_header.py: rewrite a single headerN.xml so its first paragraph contains a STYLEREF <styleId> \* MERGEFORMAT field that resolves to the current chapter title. Use (numeric form) for portability — the display-name form fails on localized templates and prints in the rendered header.

References

• Read references/pandoc-limitations.md when explaining why this workflow differs from pandoc defaults.
• Read references/zhengzhou-case-study.md when building or adapting a university-thesis pipeline.