repository·main·Indexed 43 days ago
https://github.com/sphinx-contrib/confluencebuilderA Sphinx extension to build Confluence-compatible markup and publish documentation to Confluence Cloud or Data Center 9.1+ instances. It includes the 'confluence' builder for multiple documents and the 'singleconfluence' builder (v1.3+) for a single document. Supports custom Sphinx nodes, environment variable configuration (v1.9+), and a CLI tool for wiping Confluence spaces.
Smart links render as cards and are only supported when publishing to Confluence Cloud.
Use the :confluence_doc: role to define an inlined link to a document. It accepts document names in absolute or relative formats (similar to Sphinx's :doc: role).
See :confluence_doc:`my-other-page`.Use the :confluence_link: role to define an inlined link to a page using a URL.
See :confluence_link:`https://example.com`.See :confluence_doc:`my-other-page`.
See :confluence_link:`https://example.com`.You can automatically manage pages in Confluence that are no longer part of your current Sphinx documentation set.
Set confluence_cleanup_archive = True to automatically archive pages in a space or parent page that do not match the current published documents.
Set confluence_cleanup_purge = True to permanently remove legacy pages that do not match the current published documents.
confluence_cleanup_from_root: If True, cleanup is restricted to descendants of the root_doc_ page. This prevents cleanup from affecting other documentation sets sharing the same parent.confluence_parent_page: If set, cleanup only affects descendants of this specific page/identifier.confluence_cleanup_archive = False
confluence_cleanup_purge = False
confluence_cleanup_from_root = FalseConfluence requires unique page names within a single space. The confluencebuilder extension uses the document's title to determine whether to create a new page or update an existing one.
If your Sphinx documentation contains a page title that matches an existing manually created page in the target Confluence space, the extension will update and move the existing page to become a child of the documentation container, rather than creating a new nested page. This can mangle manually prepared content.
To prevent this, use one of the following configuration options to ensure Sphinx-generated pages have unique names that do not collide with existing content:
confluence_publish_prefix: Adds a prefix to all published page titles.confluence_publish_postfix: Adds a postfix to all published page titles.Support for third-party Sphinx extensions in confluencebuilder varies. While many extensions work with the html builder, they may not integrate correctly with the Confluence builder due to implementation details or reliance on features (like JavaScript) that standard Confluence instances do not support.
Key considerations:
sphinx-design only supports single cards, not side-by-side layouts).sphinx-inline-tabs, sphinx-tabs) often require a Confluence instance with a third-party macro installed and the confluence_tab_macro configured.sphinxcontrib-actdiag, sphinxcontrib-blockdiag, sphinxcontrib-nwdiag, sphinxcontrib-seqdiag) are limited to PNG output and cannot currently be configured for SVG.confluencebuilder.You can render Markdown content by using Sphinx with the MyST Parser. While most content can be translated to Confluence storage format, there are restrictions:
confluence_permit_raw_html option to allow raw HTML, but this is unsupported. Enabling this may cause content to render incorrectly or fail to publish.Starting from version 1.9, all configuration options provided by this extension can be set via environment variables as a fallback if they are not explicitly defined in conf.py.
For example, if confluence_publish is not set in conf.py, the extension will check the CONFLUENCE_PUBLISH environment variable.
The confluence builder processes a Sphinx documentation set and generates a separate Confluence-compatible document for each individual document in your source. These generated documents can then be published to a configured Confluence instance.
To run this builder, use the sphinx-build command with the -M flag specifying confluence.
sphinx-build -M confluence . _build -E -aAfter installation, you can verify that the package is correctly installed and check its version by running the following command in your terminal.
python -m sphinxcontrib.confluencebuilder --versionIf you are starting a new documentation project, you can either use the Sphinx quick-start utility or create a minimalistic manual setup.
Open a terminal in your target directory and run:
sphinx-quickstart
# or
python -m sphinx.cmd.quickstart
# or
python -m sphinx.quickstartindex.rst file:My documentation
================
This is a test document.conf.py file with an empty extensions list:extensions = []After completing either method, proceed to Configuring to use this extension.
sphinx-quickstartThe singleconfluence builder (added in version 1.3) processes a Sphinx documentation set and collapses the entire documentation set into a single Confluence-compatible document. This is useful when you want your entire Sphinx project to appear as one large page in Confluence.
To run this builder, use the sphinx-build command with the -M flag specifying singleconfluence.
sphinx-build -M singleconfluence . _build -E -aIf your Sphinx project uses multiple builders (e.g., HTML and Confluence), you can prevent Confluence-specific directives from causing errors in other builders by using the Sphinx :only: directive.
To ensure a directive only executes when building for Confluence, wrap it in a block targeting builder_confluence or builder_singleconfluence.
.. only:: builder_confluence or builder_singleconfluence
.. confluence_metadata::
:labels: label-test