{"id":6888,"library":"sphinxcontrib-confluencebuilder","title":"Sphinx Confluence Builder","description":"Sphinx extension to build Confluence® compatible markup format files and optionally publish them to a Confluence instance. It supports both Confluence Cloud and Data Center deployments. The current version is 3.1.0, with regular updates typically following Sphinx and Confluence API changes.","status":"active","version":"3.1.0","language":"en","source_language":"en","source_url":"https://github.com/sphinx-contrib/confluencebuilder","tags":["Sphinx","Confluence","documentation","publishing","extension"],"install":[{"cmd":"pip install sphinxcontrib-confluencebuilder","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for core documentation generation and extension framework.","package":"Sphinx","version":">=8.0"},{"reason":"Used for communicating with Confluence REST API during publishing.","package":"requests","version":">=2.30.0"},{"reason":"Minimum Python version required.","package":"Python","version":">=3.10"}],"imports":[{"note":"This library is a Sphinx extension; it is activated by adding its name to the 'extensions' list in your Sphinx project's conf.py, not by a direct Python import statement in application code.","symbol":"sphinxcontrib.confluencebuilder","correct":"extensions = ['sphinxcontrib.confluencebuilder'] # in conf.py"}],"quickstart":{"code":"import os\n\n# --- In conf.py ---\n\n# Add 'sphinxcontrib.confluencebuilder' to your extensions list\nextensions = [\n    'sphinxcontrib.confluencebuilder'\n]\n\n# --- Essential Confluence Publishing Configuration ---\n# Ensure these are set to enable publishing to Confluence\nconfluence_publish = True\nconfluence_space_key = os.environ.get('CONFLUENCE_SPACE_KEY', 'MYSPACE') # Use your Confluence space key\nconfluence_parent_page = os.environ.get('CONFLUENCE_PARENT_PAGE', 'MyDocumentation') # Top-level page under which docs will be published\nconfluence_server_url = os.environ.get('CONFLUENCE_SERVER_URL', 'https://example.atlassian.net/wiki/') # Your Confluence URL\nconfluence_server_user = os.environ.get('CONFLUENCE_SERVER_USER', 'myuser@example.com') # Your Confluence username (email for Cloud)\n\n# Using an API token is highly recommended instead of a password.\n# Store securely, e.g., in an environment variable.\n# For Confluence Cloud, use confluence_publish_token for API tokens.\n# For Data Center, confluence_server_pass can be used for password or PAT.\nconfluence_publish_token = os.environ.get('CONFLUENCE_PUBLISH_TOKEN', '')\n\n# Optional: Enable dry run to check what would be published without actually publishing\n# confluence_publish_dryrun = True\n\n\n# --- To build and publish from your project root (after conf.py is setup) ---\n# Run in your terminal:\n# sphinx-build -M confluence . _build -E -a\n# or\n# python -m sphinx -M confluence . _build -E -a","lang":"python","description":"To quickly get started, add `sphinxcontrib.confluencebuilder` to the `extensions` list in your Sphinx project's `conf.py`. Then, configure the essential publishing options, including your Confluence server URL, space key, and authentication credentials (preferably an API token via environment variable). Finally, execute Sphinx with the `confluence` builder to generate and publish your documentation."},"warnings":[{"fix":"Review Confluence page rendering post-upgrade. If issues occur, adjust content or set `confluence_editor = 'v1'` in `conf.py` if 'v1' is still supported by your Confluence instance and desired.","message":"The default editor for Confluence Cloud switched from 'v1' to 'v2' in version 3.0. Users with custom configurations relying on 'v1' might experience rendering issues.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Consult the latest documentation for equivalent or new configuration options. Replace any removed options. For `confluence_editor`, consider if `v2` is acceptable or if `confluence_cloud` and `confluence_publish_token` options provide necessary alternatives for modern Confluence environments.","message":"All deprecated configuration options from 2.x and older versions were completely removed in version 3.0. This includes the `confluence_editor` option being deprecated.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade your Python environment to 3.10 or newer to use versions 2.16+ of `sphinxcontrib-confluencebuilder`.","message":"Support for Python 3.9 was dropped starting with version 2.16 (with v2.15 being the final release to support it).","severity":"breaking","affected_versions":">=2.16.0"},{"fix":"Remove `confluence_asset_force_standalone` from your `conf.py` as its behavior is now default. Avoid using page-specific editor overrides and transition to global or builder-specific configurations if possible.","message":"The `confluence_asset_force_standalone` option was removed in version 2.15 as assets are now always standalone. Page-specific editor overrides were also deprecated in version 2.14.","severity":"deprecated","affected_versions":">=2.15.0"},{"fix":"Use environment variables (e.g., `os.environ.get('CONFLUENCE_PUBLISH_TOKEN')`), a secure credential manager, or prompt for credentials at build time (e.g., `confluence_ask_password = True`) to keep secrets out of source control.","message":"It is never recommended to store sensitive authentication information (API tokens or raw passwords) directly in a committed repository.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}