Cross-page anchor links from toctree (maxdepth > 1) don't resolve anchor on Confluence Cloud

[jhaase1]

Summary

When using maxdepth: 2 in toctrees, the builder generates cross-page section links using ac:link ac:anchor → ac:structured-macro ac:name="anchor". The storage format is correct on both source and target pages. However, on Confluence Cloud (v2/fabric editor), clicking these links navigates to the correct page but drops the anchor fragment — the browser does not scroll to the referenced section.

Environment

• sphinxcontrib-confluencebuilder: 3.0.0
• Sphinx: 9.0.4
• Python: 3.11.9
• Confluence: Cloud (.[atlassian.net/wiki/](http://atlassian.net/wiki/))
• Editor: v2 (auto-detected by builder v3.0)
• API mode: v2 (auto-detected)
• No explicit confluence_editor or confluence_api_mode set

Reproduction

Source document (guide/index.md)

## User Guide Pages

```{toctree}
:maxdepth: 2

models-to-focus

### Target document (`guide/models-to-focus.md`)

```markdown
# Models to Focus

Some intro text.

## Data Source

Models to Focus queries the `trigger_programs_of_concern` table...

## Key Metrics

### Score

A composite battery health score...

Build command

sphinx-build -M confluence docs docs/_build -E -a

Generated storage format

Source page (guide/index) — toctree links

<ac:link ac:anchor="Data-Source">
<ri:page ri:content-title="Models to Focus" />
<ac:link-body>Data Source</ac:link-body>
</ac:link>

Target page (guide/models-to-focus) — anchor definitions

<h2><ac:structured-macro ac:name="anchor">
<ac:parameter ac:name="">Data-Source</ac:parameter>
</ac:structured-macro><ac:structured-macro ac:name="anchor">
<ac:parameter ac:name="">ModelstoFocus-Data-Source</ac:parameter>
</ac:structured-macro>Data Source</h2>

Both sides match: ac:link ac:anchor="Data-Source" references ac:structured-macro ac:name="anchor" with parameter Data-Source.

Observed behavior

Clicking the "Data Source" link in the toctree navigates to:

https://example.atlassian.net/wiki/spaces/MYSPACE/pages/123456

The anchor fragment (#Data-Source) is not appended; the page loads at the top.

Expected behavior

The link should navigate to:

https://example.atlassian.net/wiki/spaces/MYSPACE/pages/123456/Models+to+Focus#Data-Source

...scrolling to the "Data Source" heading.

Additional context

• Confluence Cloud's v2 editor wraps anchor macros as inline extensions. Inspecting the rendered DOM, the heading's HTML id attribute becomes [inlineExtension][inlineExtension]Data-Source (because the two ac:structured-macro elements inside the <h2> are serialized as [inlineExtension] tokens). The ac:link ac:anchor="Data-Source" may fail to resolve because the rendered anchor ID doesn't match Data-Source.
• Same-page TOC links work. The Confluence-native TOC macro generates URLs with the [inlineExtension] prefix and correctly scrolls to sections.
• Using maxdepth: 1 avoids the issue (no sub-section anchor links generated), but loses section-level detail in navigation.
• Not the same as Link to section titles - broken ? #1057 (Data Center v2 anchor formatting, fixed v2.9). Our anchors have no special characters — simple slugs like Data-Source, Purpose, Key-Metrics.
• PR Replace special anchor handling #1129 ("Replace special anchor handling") targets anchors with characters like parentheses and is included in v3.0.0, but does not apply to our simple anchor names.
• A contributor in sphinxcontrib-confluencebuilder v3 Cloud Users Notice #1166 reported a similar symptom ("anchors link to page but not section") which allegedly resolved after republishing. We have republished multiple times (including with CONFLUENCE_CLOUD_V2_MIGRATION=1) and the issue persists.

Workaround

Set maxdepth: 1 on all toctrees to avoid generating cross-page section links. This prevents broken links but loses section-level navigation from parent pages.

[jdknight]

Thanks for the report and minimized example (it helps a lot).

I am able to see the same issue you are most likely experiencing. My first impression is that it looks to be a Confluence bug. Using your example, the storage format content reported on Confluence Cloud is:

<ul>

<li>
<ac:link>
<ri:page ri:content-title="Models to Focus" />
<ac:link-body>Models to Focus</ac:link-body>
</ac:link>
<ul>

<li>
<ac:link ac:anchor="Data-Source">
<ri:page ri:content-title="Models to Focus" />
<ac:link-body>Data Source</ac:link-body>
</ac:link></li>

<li>
<ac:link ac:anchor="Key-Metrics">
<ri:page ri:content-title="Models to Focus" />
<ac:link-body>Key Metrics</ac:link-body>
</ac:link></li>
</ul>
</li>
</ul>

Which (I believe) as valid anchor markup. But as you have also observed, no anchors are in the links:

What is interesting is that if I force republished:

CONFLUENCE_PUBLISH_FORCE=true sphinx-build ...

The anchors magically appear:

Re-checked if there is any differences in the storage format and did notice some attributes updated:

<ri:page ri:content-title="Models to Focus" />
 (to)
<ri:page ri:content-title="Models to Focus" ri:version-at-save="1" />

But this should not cause the anchors to break. That being said, performed a local test which applied the attribute on first publish but it did not fix the issue.

Curious to know if just a second page update fixes the issue. Adjusted the code to publish a page twice (once on new and re-update the page). However, no changes in the result.

Then, with the two page example provided, adjusted it to do two passed -- TOC, sub-page, TOC and sub-page. And this appeared to fix the anchor issues.

(speculation) I am wonder if Confluence is doing some link detection when a page is published which results in anchors being broken. Specifically, index.md is first published which references models-to-focus.md which has not been updated. This may result in anchors not being formed (e.g. some logic exists where it tried to detect a page, it fails and the resulting link used fails to handle an anchor value). Then models-to-focus.md is added. Then when we re-publish index.md, it finds the page and using a "normal" reference processing that results in the anchor for being included.

If that is the case, that is... annoying/unexpected. Will have to do more testing, but maybe in the extension we can detect when anchor references point to pages that do not exist yet. And after we publish the first set, we re-queue up anchor-holding pages that may need to be republish.

[jdknight]

The following script shows easily show the issue:

sphinx-contrib-confluencebuilder-issues-1178.py

Appears that when a page is created, Confluence tries to find a target page. If it does not, it automatically converts the link to a createpage.action. However, once a page is created, it converts the link page to a page link. But in this process, the anchor is dropped.

There looks to be a Confluence Cloud Jira about this: CONFCLOUD-78192

I have voted on the issue; I'd recommend others to vote as well.

That all being said, will try to see if we can implement a hack to address this since this is not the first nor probably last time people will experience this.

[jhaase1]

Thank you for taking a look at this!

[yunarta]

This pretty much break things up. Thanks for checking out. I'm currently looking for hackish way to temporarily address this.

[jdknight]

The workaround for existing spaces that have this issue is to do at least one force publish after the first publish event. For example:

sphinx-build ...
CONFLUENCE_PUBLISH_FORCE=true sphinx-build ...

In theory, pages will all exist on the first pass, and the second pass will re-update the links and recover.

I have a local change that I'm testing/verifying that should automatically handle this for new publication events. Although, it does not auto-correct/fix users who have already published and exhibit this issue (where they need to force a new publish event to fix).

[yunarta]

The workaround for existing spaces that have this issue is to do at least one force publish after the first publish event. For example:

sphinx-build ...
CONFLUENCE_PUBLISH_FORCE=true sphinx-build ...

In theory, pages will all exist on the first pass, and the second pass will re-update the links and recover.

I have a local change that I'm testing/verifying that should automatically handle this for new publication events. Although, it does not auto-correct/fix users who have already published and exhibit this issue (where they need to force a new publish event to fix).

Not working on my case.
I have doc reference in the source
But the idea is correct. Need to prepare all the pages before update

[jdknight]

If configuring confluence_publish_force is not fixing the scenario for you, I wonder if there is another isue at play.

[jdknight]

A change (#1181) has been merged which should attempt to support republished anchor-risk pages for new page targets on Confluence Cloud. This should reduce the risk of having new publications having broken links. This feature can be disabled using an advanced confluence_adv_disable_anchor_fix option.

This change is available now with a development installation and should be available next stable release (v3.1+).

Note that this fix does not help correct documentation sets already published where Confluence has broken anchor links. If a confluence_publish_force does not work, users are recommended to try to manually delete the page(s) in question and try a re-publish attempt.