sphinxcontrib-confluencebuilder v3 Cloud Users Notice

[jdknight]

(see the original notice in sphinxcontrib-confluencebuilder v3 Planning | Cloud and Legacy Editor Considerations)

For a v3.0 release (planned before end of January 2026), publishing to Confluence Cloud will default publish with the v2/modern editor. Users upgrading to v3 may need to perform an action for certain scenarios.

Already using Confluence Cloud and the v2 Editor

If an environment was already using a Confluence Cloud instance with an explicit v2 editor configuration:

confluence_editor = 'v2'

No changes are required. Users should be able to upgrade to this extension's v3 release without issue. Note that users may opt to removing the explicit confluence_editor configuration as it will be v2 by default for Confluence Cloud instances.

Already using Confluence Cloud and the v1 Editor

If an environment was already using a Confluence Cloud instance with an implicit/explicit v1 editor configuration, users may require a one-time migration invoke to help force pages to migration from their legacy editor state. Confluence Cloud instances are interacted with using the v2 API, and there is no v2 API to help force an upgrade from the legacy to modern editor. While Atlassian plans to force upgrade all pages from legacy to modern before the end of April 2026, users upgrading to the v3 extension will want to upgrade these pages sooner.

There are two approaches a user may perform:

1. Using Atlassian's guide to manually convert pages to the modern editor. After completing the conversion, running a Sphinx publish run should apply/rebuild content.
2. Users can enable a confluence_cloud_v2_migration configuration option for a single publish run. This will request a page conversion to the modern editor for each page published to. Note that the API trigger on Confluence will generate at least two revision updates for a given page. After performing a single publish run that upgrades the editor experience, this option should then be removed. Users who do not wish to edit the conf.py directly may instead use the CONFLUENCE_CLOUD_V2_MIGRATION=1 environment flag for a single run.

Confluence Cloud instances not hosted on an Atlassian domain

If publishing to a Confluence Cloud instance that is hosted with a custom domain (i.e. not on .atlassian.com or .atlassian.net), users will need to configure their project's to explicitly hint for Confluence Cloud support

confluence_cloud = True

Wishing to use v1 editor on Confluence Cloud

If looking to not change the experience when publishing to Confluence Cloud for the extension's v3 release, users an explicitly configure for the legacy editor by adding the following in their Sphinx configuration:

confluence_editor = 'v1'

Note that doing so is considered unsupported and will only function until Atlassian disables support (~April 2026).

Confluence Data Center users

No changes are required. Users can upgrade an exhibit the same experience.

[jdknight]

Note that v3.0 release of this extension has been completed.

Feel free to report issues here or create a new issue if issues are experienced. This issue will remain open for a period time.

[robert-schmidtke]

Hi @jdknight, thanks for collecting feedback here.

I have switched to version 3.0 and enabled the v2 editor, and I notice that for the Python module overview that is generated, all the class methods are reported as before, but they don't link to the anchor of the method itself anymore, just the main page.

Previously:

Now:

Is there a config option that I am missing here?

Thanks!

[robert-schmidtke]

It also seems that .. warning:: directives are rendered as Errors in Confluence

[jdknight]

I notice that for the Python module overview that is generated, all the class methods are reported as before, but they don't link to the anchor of the method itself anymore, just the main page.

Most likely a bug trying to handle some characters. I'll try to test something locally with a document name [1.2.3] My Title and something that might mimic your setup. Are you using a local .. contents:: directive and some autodocs code?

It also seems that .. warning:: directives are rendered as Errors in Confluence

Appears it has always be configured to that, mapping reStructuredText's warning type to Sphinx's warning type ("red"). However, maybe we should instead map it to a note type ("yellow") -- feels right to me for warning to be yellow coded.

We could also add a hook to override as well, if people have different opinions on this.

[robert-schmidtke]

Are you using a local .. contents:: directive and some autodocs code?

.. contents:: no, autodoc yes.

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.intersphinx",
    "sphinx.ext.todo",
    "sphinx.ext.autosummary",
    "sphinx.ext.viewcode",
    "sphinx.ext.coverage",
    "sphinx.ext.doctest",
    "sphinx.ext.ifconfig",
    "sphinx.ext.mathjax",
    "sphinx.ext.napoleon",
    "sphinx.ext.autosectionlabel",
    "sphinxcontrib.confluencebuilder",
]

# use both the class's and its __init__ docstrings
autoclass_content = "both"

# do not sort members alphabetically, but group them by type
autodoc_member_order = "groupwise"

# show types in description instead of signature
autodoc_typehints = "description"

# prefix each automatically generated section label with the containing document's name
autosectionlabel_prefix_document = True

Appears it has always be configured to that, mapping reStructuredText's warning type to Sphinx's warning type ("red")

True, I see the color being red in older versions as well. However the icon was an exclamation mark instead of a cross ("x").
But would expect it to be yellow actually, yes.

[jdknight]

Warning styling should be handled in #1170.

As for the autodocs reference issues, @robert-schmidtke, would you happen to have an example that helps show the issue? I have tried to replicate what you may be looking for without much success. Used the provided configuration and added some pages that utilize autosummary/automodule directives on Python standard modules, but the content is not structured in a way that you have setup.

[robert-schmidtke]

Thanks! I'll try and get a mini reproducer next week

[robert-schmidtke]

Thanks! I'll try and get a mini reproducer next week

As you notice I didn't get back to you but this is still on my TODO list. I just kept getting buried in other items but will pick this up.

[robert-schmidtke]

Warning styling should be handled in #1170.

As for the autodocs reference issues, @robert-schmidtke, would you happen to have an example that helps show the issue? I have tried to replicate what you may be looking for without much success. Used the provided configuration and added some pages that utilize autosummary/automodule directives on Python standard modules, but the content is not structured in a way that you have setup.

I have published a new version of our internal library documentation to Confluence, and I cannot observe the initially reported behavior anymore. It looks like the anchors work as expected.

I did see a warning from Confluence itself, asking me to refresh the page. So maybe it was never an issue of the confluence-builder here, but rather Confluence itself.

In any case, thank you for your support & this useful piece of software here :)

[jdknight]

Note that the reported issue in this thread about broken anchor links has since been found to be a Confluence issue (see CONFCLOUD-78192). A change (#1181) has been added to address this and will be available next release (v3.1+).