bookdown::word_document2章节交叉引用失效问题求助

I’ve run into this exact headache before—nothing’s more frustrating than cross-references working flawlessly for PDFs but breaking into ?? in Word. Let’s walk through the fixes step by step:

Why This Happens #

The root issue is how bookdown and pandoc interact with your Word template. Even if you’ve turned on section numbering, pandoc relies on recognizing default Word built-in heading styles (like "Heading 1", "Heading 2") to map your labeled sections to cross-references. Custom style names or misaligned style mappings trigger the "label not found" warning and broken references.

Step-by-Step Solutions #

1. Validate Your Word Template’s Heading Styles
   Open your template.docx and:

   • Right-click your first-level heading style → Select "Modify"
   • Ensure the style name is exactly "Heading 1" (stick to the default English name—avoid custom labels like "一级标题")
   • Repeat this check for all heading levels you use (Heading 2, Heading 3, etc.)
   • Confirm section numbering is enabled for each of these built-in styles

2. Tweak Your YAML Configuration
   Explicitly reference your template and add small tweaks to help pandoc parse your document structure:

   ---
   title: "Untitled"
   author: "Anonymous"
   date: "09/01/2020"
   output:
     bookdown::word_document2:
       reference_docx: "template.docx"  # Double-check the file path matches your setup
       toc: true  # Helps pandoc recognize the hierarchy of your sections
   ---
   
   # First Section {#sec1}
   Etc.
   
   # Second Section
   See section \@ref(sec1).
   

3. Update bookdown to the Latest Version
   Your installed bookdown version (0.16) is a bit dated, and newer releases fixed several Word cross-reference bugs. Run this in R to update:

   install.packages("bookdown")
   

4. Recompile and Test
   After making these changes, recompile your document. The "label(s) sec1 not found" warning should vanish, and \@ref(sec1) will render as the correct section number in your Word output.

Quick Additional Checks #

• Confirm your template.docx is in your R working directory (use getwd() in R to verify)
• If you must use non-English heading styles, you’ll need to map them explicitly via pandoc variables—but sticking to the default English built-in styles is the simplest fix.

内容的提问来源于stack exchange，提问作者nat