How to Fix Confluence Anchor Links

In this tutorial, you'll learn about How to Fix Confluence Anchor Links. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

Links to specific sections on a Confluence page scroll to the top instead of the intended heading. Confluence generates heading anchors automatically but may conflict.

The Wrong Way

// Using an HTML <a> tag as an anchor
page.content += '<a name="my-section"></a>';

Confluence's storage format strips raw HTML anchors. They disappear after page save.

The Right Way

Step 1: Use heading anchors (automatic)

# Every heading in Confluence gets an auto-generated anchor
# Format: <heading-text> (lowercase, spaces → hyphens)
# Example: "## My Section" → #my-section
# Full URL: https://your-space.atlassian.net/wiki/.../page#my-section

Step 2: Copy the anchor link

# Hover over the heading → a link icon (🔗) appears
# Click it → copies the anchor link to your clipboard
# Paste this link wherever you need to reference the section

Step 3: Handle duplicate headings

# If two headings are "Requirements":
# Confluence adds a suffix:
# #requirements → first occurrence
# #requirements-1 → second occurrence
# #requirements-2 → third occurrence

To find the correct anchor, hover and click the link icon on the second heading.

Step 4: Use the anchor macro for non-heading targets

# Insert → Other Macros → "Anchor"
# Give it a name: "decision-point-1"
# Link to: #decision-point-1

The Anchor macro works on any element, not just headings.

Anchor link "##API Reference" now navigates correctly — scrolls to the API Reference section from anywhere in the page.

Prevention

• Use Anchor macros only when headings are not available or appropriate.
• Check anchor links after renaming headings — anchors change when heading text changes.
• The anchor-generation logic is similar to Doda Browser's reader mode, which creates a table of contents from heading anchors automatically.

Common Mistakes with anchor link

1. Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors
2. Non-exhaustive pattern matches that compile with warnings then crash at runtime
3. Misunderstanding that String is [Char] with poor performance for large text operations

These mistakes appear frequently in real-world CONFLUENCE code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ