Markdown Cross-References Not Working in Word? Fix Figure, Table, Equation, and Section References

A document can contain correctly formatted headings, figures, tables, and equations while its internal references still fail. Instead of “see Figure 3” or “refer to Section 2.4,” the Word file may show a raw label, an incorrect number, or ordinary text that no longer updates after content is moved.

Cross-references depend on stable targets. The source needs a unique identifier for the heading, figure, table, or equation, and the reference must point to that exact identifier. The target also needs a caption or numbering structure that Word can use after conversion.

What a cross-reference needs

A reliable cross-reference has two parts:

• Target: the heading, figure, table, equation, or appendix being referenced.
• Reference: the sentence that points readers to that target.

A simplified source pattern may look like this:

![System architecture](images/architecture.png){#fig-architecture}

See Figure @fig-architecture for the component relationships.

The exact syntax can vary by Markdown implementation, but the principle remains the same: the target identifier and the reference identifier must match exactly.

Problem 1: The target has no stable identifier

A caption such as “System Architecture” is visible to readers, but it may not be a unique machine-readable target. If the document contains several similar captions, a converter cannot safely infer which object a reference should follow.

![System architecture](images/architecture.png)

See the system architecture figure above.

The sentence is understandable at the moment, but “above” becomes inaccurate if a paragraph or another figure is inserted later. A stable identifier is more resilient:

![System architecture](images/architecture.png){#fig-system-architecture}

See Figure @fig-system-architecture.

Problem 2: The reference label does not match

Treat labels as exact identifiers. Avoid adding spaces, changing capitalization, or renaming targets without updating every reference.

Problem 3: Two targets reuse the same label

Duplicate identifiers are ambiguous. If two figures both use fig-overview, a converter may link to the first, the last, or fail to resolve the reference.

![Architecture overview](images/architecture.png){#fig-overview}

...

![Deployment overview](images/deployment.png){#fig-overview}

Use labels that reflect the target:

{#fig-architecture-overview}
{#fig-deployment-overview}

A predictable prefix convention also makes large source files easier to search:

• fig- for figures
• tbl- for tables
• eq- for equations
• sec- for sections
• app- for appendices

Problem 4: The caption is separated from the object

A figure or table caption should remain structurally associated with the object it describes. Several unrelated paragraphs, manual page breaks, or another object inserted between them can make that relationship unclear.

Keep the source compact:

![Request processing workflow](images/request-flow.png){#fig-request-flow}

Figure: Request processing workflow

Do not manually type “Figure 4” into the caption if the document is expected to renumber automatically. The visible number may become wrong when figures are inserted, removed, or reordered.

Problem 5: Manual numbers do not update

A sentence such as “see Table 6” is ordinary text unless it is connected to a field or reference target. After moving the table, the sentence still says “Table 6.”

The exact visible result depends on the conversion rules and template, but the source should point to a target rather than predict its final number.

Heading references need a stable structure

References to sections are most reliable when heading levels are consistent. A heading that jumps from H2 to H4 or is replaced by bold text may no longer participate in the expected numbering hierarchy.

## Deployment Process {#sec-deployment}

### Pre-deployment Checks

### Release Procedure

See Section @sec-deployment for the complete workflow.

If numbered headings are enabled, review the final section number after conversion. If numbering is disabled, decide whether the reference should display the heading title instead of a number.

Equation references require separate checks

An equation can render correctly while its label fails. Keep the identifier outside unsupported LaTeX commands and avoid manually typing a number into the formula image or source text.

$$
d = \frac{p \times D}{w}
$$ {#eq-clearance}

The clearance estimate is defined in Equation @eq-clearance.

After conversion, inspect:

• Whether the equation remains editable.
• Whether its number is visible and correctly positioned.
• Whether the reference points to the equation rather than the surrounding paragraph.
• Whether inserting another equation changes both numbers correctly.

Cross-references inside tables and captions

A reference inside a narrow table cell or caption may technically work but still create poor layout. Long generated titles, section names, or multiple references can make a cell excessively tall.

For clearer documents:

• Use short forms such as “Fig.” only if the required style allows them.
• Move several references into a note below the table.
• Avoid placing essential navigation only inside image captions.
• Keep cross-reference sentences in normal body text when possible.

A reliable troubleshooting workflow

1. Find the first unresolved reference. Copy its exact label.
2. Search for the target. Confirm that one matching identifier exists.
3. Check for duplicates. Search the complete document for the same target label.
4. Review the target structure. Confirm that the caption, heading, table, figure, or equation is recognized.
5. Remove manual numbering. Let the target and document fields control visible numbers.
6. Create a minimal test. Use one target and one reference.
7. Convert and update fields. Open the DOCX and refresh fields if the editor requires it.
8. Return the corrected pattern to the full document. Then review all reference types.

Review the final DOCX

Common symptoms and fixes

Frequently asked questions

Final checklist