Configuration¶

The following is an example of simple configuration (config.py) for Confluence generation and publishing:

extensions = [
    'sphinxcontrib.confluencebuilder',
]
confluence_publish = True
confluence_space_key = 'TEST'
confluence_parent_page = 'Documentation'
confluence_server_url = 'https://intranet-wiki.example.com/'
confluence_server_user = 'myawesomeuser'
confluence_ask_password = True

All configurations introduced by this extension are listed below. This extension may take advantage of a subset of Sphinx configurations as well when preparing documents.

Added in version 1.9: All options provided by this extension may be set from the running environment. For example, if confluence_publish is not explicitly set inside conf.py or provided via Sphinx’s command line, this extension may check the CONFLUENCE_PUBLISH environment option as a fallback. Note that this only applies options provided below and will not work for other configuration options provided by Sphinx or other Sphinx extensions.

Essential configuration ¶

confluence_publish¶

A boolean that decides whether or not to allow publishing. This option must be explicitly set to True if a user wishes to publish content. By default, the value is set to False.

confluence_publish = True

confluence_server_url¶

The URL for the Confluence instance to publish to. The URL should be prefixed with https:// or http:// (depending on the URL target). The target API folder should not be included in the URL (i.e. excluding rest/api/). For a Confluence Cloud instance, an example URL configuration is as follows:

confluence_server_url = 'https://example.atlassian.net/wiki/'

For Confluence Data Center, an example URL configuration, if the instance’s REST API is https://intranet-wiki.example.com/rest/api/, should be as follows:

confluence_server_url = 'https://intranet-wiki.example.com/'

confluence_space_key¶

Added in version 1.7.

Note

Use the key value for the space, not the name of the space. For example, MYAWESOMESPACE instead of My Awesome Space.
The space key is case-sensitive (typically uppercase).

Key of the space in Confluence to be used to publish generated documents to. For example:

confluence_space_key = 'MYAWESOMESPACE'

If attempting to publish to a user’s personal space, the space’s key will typically start with a tilde value followed by the space’s identifier. For example:

confluence_space_key = '~123456789'

confluence_server_user¶

Note

If using a personal access token (PAT), this option does not need to set (see confluence_publish_token).

Note

If trying to use netrc authentication, support is provided by the Requests library [1]. A user can default to using a configured netrc file by not setting a value for confluence_server_user.

The username value used to authenticate with the Confluence instance. If using Confluence Cloud, this value will most likely be the account’s E-mail address. If using Confluence Data Center, this value will most likely be the username value.

confluence_server_user = 'myawesomeuser@example.com'
 (or)
confluence_server_user = 'myawesomeuser'

confluence_api_token¶

Added in version 2.6.

Tip

Use this option for Confluence Cloud.

Caution

It is never recommended to store an API token into a committed/shared repository holding documentation.

A documentation’s configuration can modified various ways with Python to pull an authentication token for a publishing event such as reading from an environment variable, reading from a local file or acquiring a token from getpass.

Note

If attempting to use a personal access token (PAT), use the confluence_publish_token option instead.

The API token value used to authenticate with the Confluence instance. Set this option to an API token for the configured username value (see API tokens):

confluence_api_token = 'YDYDD3qVvKV0FbkErSxaQ2olmy...AMGwaPe8=02381T9A'

confluence_publish_token¶

Added in version 1.8.

Tip

Use this option for Confluence Data Center.

Caution

It is never recommended to store a personal access tokens (PAT) into a committed/shared repository holding documentation.

A documentation’s configuration can modified various ways with Python to pull an authentication token for a publishing event such as reading from an environment variable, reading from a local file or acquiring a token from getpass.

Note

If attempting to use an API token, use the confluence_server_pass option instead.

The personal access token value used to authenticate with the Confluence instance (see Using Personal Access Tokens):

confluence_publish_token = 'AbCdEfGhIjKlMnOpQrStUvWxY/z1234567890aBc'

confluence_server_pass¶

Warning

It is not recommended to use this option when authenticating with an API token or a personal access token.

Note

Functionally, this option is the same as confluence_api_token. It is recommended to use the API token variant solely for naming convention. Only limited cases can use a password value for publication over API tokens or personal access tokens (specifically, cases using Confluence Data Center). Unless users are expected to interact directly with their Confluence instance with user passwords, users should instead use either one of the following options instead:

confluence_api_token
confluence_publish_token

Caution

It is never recommended to store a raw password into a committed/shared repository holding documentation. If desired, this extension provides a method for prompting for a password (see confluence_ask_password).

Future versions may deprecate this option.

The password value used to authenticate with the Confluence instance. This value expects the plaintext password for the configured username value:

confluence_server_pass = 'myawesomepassword'

Generic configuration ¶

confluence_add_secnumbers¶

Added in version 1.2.

Add section numbers to page and section titles if toctree uses the :numbered: option. By default, this is enabled:

confluence_add_secnumbers = True

See also:

confluence_footer_file
confluence_header_data

confluence_header_data¶

Added in version 1.9.

Takes an optional dictionary. If this value is set then confluence_header_file is interpreted as a jinja2 template with these values passed in. If this value is not set then confluence_header_file is included verbatim.

Publishing configuration ¶

confluence_append_labels¶

Added in version 1.3.

Allows a user to decide how to manage labels for an updated page. When a page update contains new labels to set, they can either be stacked on existing labels or replaced. In the event that a publisher wishes to replace any existing labels that are set on published pages, this option can be set to False. By default, labels are always appended with a value of True.

confluence_append_labels = True

See also:

confluence_global_labels
confluence_metadata directive

confluence_api_mode¶

Added in version 2.5.

Configures the API mode to use for REST requests. Certain Confluence instances support a newer version of REST APIs (e.g. Confluence Cloud). This extension will attempt to use an appropriate API mode for a configuration set. However, a user can override the operating API mode based on preference or when handling situations where this extension cannot automatically determine the best API mode to use. Values accepted are either v1 or v2.

confluence_api_mode = 'v2'

By default, if a Confluence Cloud configuration is detected, this extension will use v2. For all other cases, the default is v1.

confluence_ask_password¶

Warning

User’s running Cygwin/MinGW may need to invoke with winpty to allow this feature to work.

Provides an override for an interactive shell to request publishing documents using an API key or password provided from a shell environment. While a password is typically defined in the option confluence_server_pass (either directly set, fetched from the project’s config.py or passed via an alternative means), select environments may wish to provide a way to accept an authentication token without needing to modify documentation sources or having a visible password value in the interactive session requesting the publish event. By default, this option is disabled with a value of False.

confluence_ask_password = False

A user can request for a password prompt by invoking build event by passing the define through the command line:

sphinx-build [options] -D confluence_ask_password=1 <srcdir> <outdir>

Note that some shell sessions may not be able to pull the password value properly from the user. For example, Cygwin/MinGW may not be able to accept a password unless invoked with winpty.

confluence_ask_user¶

Added in version 1.2.

Provides an override for an interactive shell to request publishing documents using a user provided from a shell environment. While a user is typically defined in the option confluence_server_user, select environments may wish to provide a way to accept a username without needing to modify documentation sources. By default, this option is disabled with a value of False.

confluence_ask_user = False

confluence_cleanup_archive¶

Added in version 1.9.

Warning

Publishing individual/subset of documents with this option may lead to unexpected results.

Note

This option cannot be used with confluence_cleanup_purge.

Warning

Only Confluence Cloud identifies support for an archiving API. Attempting to Confluence Data Center with this feature will most likely result in an “Unsupported Confluence API call” error (500).

Attention

Confluence’s archiving API is marked as experimental by Atlassian at the time of writing. This feature may experience issues over time until the API is flagged as stable (if ever).

A boolean value to whether to archive legacy pages detected in a space or parent page. By default, this value is set to False to indicate that no pages will be archived. If this configuration is set to True, detected pages in Confluence that do not match the set of published documents will be automatically archived. If the option confluence_parent_page is set, only pages which are a descendant of the configured parent page can be removed; otherwise, all flagged pages in the configured space could be archived.

confluence_cleanup_archive = False

While this capability is useful for updating a series of pages, it may lead to unexpected results when attempting to publish a single-page update. The archive operation will archive all pages that are not publish in the request. For example, if an original request publishes ten documents and archives excess documents, a following publish attempt with only one of the documents will archive the other nine pages.

See also:

confluence_cleanup_from_root
confluence_cleanup_purge
confluence_cleanup_search_mode
confluence_publish_dryrun

confluence_cleanup_from_root¶

Added in version 1.9.

A boolean value to which indicates that any cleanup attempt should be done from the root of a published root_doc page (instead of a configured parent page; i.e. confluence_parent_page). In specific publishing scenarios, a user may wish to publish multiple documentation sets based off a single parent/container page. To prevent any cleanup between multiple documentation sets, this option can be set to True. When generating legacy pages to be removed, this extension will only attempt to populate legacy pages based off the children of the root_doc page. This option requires either confluence_cleanup_archive or confluence_cleanup_purge to be set to True before taking effect. If confluence_publish_root is set, this option is implicitly enabled.

confluence_cleanup_from_root = False

See also:

confluence_cleanup_archive
confluence_cleanup_purge

confluence_cleanup_purge¶

Added in version 1.9.

Warning

Publishing individual/subset of documents with this option may lead to unexpected results.

Note

This option cannot be used with confluence_cleanup_archive.

A boolean value to whether or not purge legacy pages detected in a space or parent page. By default, this value is set to False to indicate that no pages will be removed. If this configuration is set to True, detected pages in Confluence that do not match the set of published documents will be automatically removed. If the option confluence_parent_page is set, only pages which are a descendant of the configured parent page can be removed; otherwise, all flagged pages in the configured space could be removed.

confluence_cleanup_purge = False

While this capability is useful for updating a series of pages, it may lead to unexpected results when attempting to publish a single-page update. The purge operation will remove all pages that are not publish in the request. For example, if an original request publishes ten documents and purges excess documents, a following publish attempt with only one of the documents will purge the other nine pages.

See also:

confluence_cleanup_archive
confluence_cleanup_from_root
confluence_cleanup_search_mode
confluence_publish_dryrun

confluence_disable_notifications¶

Changed in version 2.6: Option is enabled by default.

A boolean value which explicitly disables any page update notifications (i.e. treats page updates from a publish request as minor updates). By default, notifications are disabled with a value of True.

confluence_disable_notifications = True

Note that even if this option is set, there may be some scenarios where a notification will be generated for other users when a page is created or removed, depending on how other users may be watching a space.

Advanced publishing configuration ¶

confluence_additional_mime_types¶

Added in version 1.3.

Candidate selection for images will only support the internally managed list of MIME types supported by a default Confluence instance. A custom installation or future installations of a Confluence instance may support newer MIME types not explicitly managed by this extension. This configuration provides a user the option to register additional MIME types to consider for image candidates.

confluence_additional_mime_types = [
    'image/tiff',
]

confluence_asset_force_standalone¶

Added in version 1.3.

Provides an override to always publish individual assets (images, downloads, etc.) on each individual document which uses them. This extension will attempt to minimize the amount of publishing of shared assets on multiple documents by only hosting an asset in a single document. For example, if two documents use the same image, the image will be hosted on the root document of a set and each document will reference the attachment on the root page. A user may wish to override this feature. By configuring this option to True, this extension will publish asset files as an attachment for each document which may use the asset. By default, this extension will attempt to host shared assets on a single document with a value of False.

confluence_asset_force_standalone = True

confluence_asset_override¶

Provides an override for asset publishing to allow a user publishing to either force re-publishing assets or disable asset publishing. This extension will attempt to publish assets (images, downloads, etc.) to pages via Confluence’s attachment feature. Attachments are assigned a comment value with a hash value of a published asset. If another publishing event occurs, the hash value is checked before attempting to re-publish an asset. In unique scenarios, are use may wish to override this ability. By configuring this option to True, this extension will always publish asset files (whether or not an attachment with a matching hash exists). By configuring this option to False, no assets will be published by this extension. By default, this automatic asset publishing occurs with a value of None.

confluence_asset_override = None

confluence_ca_cert¶

Changed in version 2.3: Support relative paths.

Provide a CA certificate to use for server certificate authentication. The value for this option can either be a file of a certificate or a path pointing to an OpenSSL-prepared directory. Refer to the Requests SSL Cert Verification documentation (verify) for more information. If server verification is explicitly disabled, this option is ignored. By default, this option is ignored with a value of None.

confluence_ca_cert = 'ca.crt'

See also:

confluence_client_cert_pass
confluence_client_cert
confluence_disable_ssl_validation

confluence_cleanup_search_mode¶

Added in version 2.1.

Warning

The direct search mode may not work on Confluence Data Center instances. For these cases, Confluence may report the following error:

(Not Implemented; 500)

Page children is currently only supported for direct children.

Configures the search mode used for finding descendant pages to be cleaned up (when configured for archiving/purging legacy pages). By default, this extension will search Confluence for known descendants for the root page:

confluence_cleanup_search_mode = 'search'

However, in some cases, the provided list of descendants may be incorrect (due to the Confluence version used, the state of Confluence’s ancestors table caching, etc.). This configuration can be used to tweak how this extension searches for descendants, if a user experiences issues with the default method of searching. Supported modes are as follows:

direct: Query known descendants from a page’s cache.
search (default): Search for descendants using Confluence’s CQL capability.

Users can also postfix -aggressive (e.g. search-aggressive) on a mode to perform a recursive search for descendants ensure all descendants are found. Note that an aggressive search will increase the amount of API calls to a configured Confluence instance. See also:

confluence_cleanup_archive
confluence_cleanup_purge

confluence_client_cert¶

Provide a client certificate to use for two-way TLS/SSL authentication. The value for this option can either be a file (containing a certificate and private key) or as a tuple where both certificate and private keys are explicitly provided. If a private key is protected with a passphrase, a user publishing a documentation set will be prompted for a password (see also confluence_client_cert_pass). By default, this option is ignored with a value of None.

confluence_client_cert = 'cert_and_key.pem'
 (or)
confluence_client_cert = ('client.cert', 'client.key')

See also:

confluence_ca_cert
confluence_client_cert_pass
confluence_disable_ssl_validation

confluence_client_cert_pass¶

Caution

It is never recommended to store a certificate’s passphrase into a committed/shared repository holding documentation.

Provide a passphrase for confluence_client_cert. This prevents a user from being prompted to enter a passphrase for a private key when publishing. If a configured private key is not protected by a passphrase, this value will be ignored. By default, this option is ignored with a value of None.

confluence_client_cert_pass = 'passphrase'

confluence_ca_cert
confluence_client_cert
confluence_disable_ssl_validation

confluence_disable_autogen_title¶

A boolean value to explicitly disable the automatic generation of titles for documents which do not have a title set. When this extension processes a set of documents to publish, a document needs a title value to know which Confluence page to create/update. In the event where a title value cannot be extracted from a document, a title value will be automatically generated for the document. For automatically generated titles, the value will always be prefixed with autogen-. For users who wish to ignore pages which have no title, this option can be set to True. By default, this option is set to False.

confluence_disable_autogen_title = True

See also:

confluence_remove_title
confluence_title_overrides

confluence_disable_ssl_validation¶

Warning

It is not recommended to use this option.

A boolean value to explicitly disable verification of server SSL certificates when making a publish request. By default, this option is set to False.

confluence_disable_ssl_validation = False

confluence_ca_cert
confluence_client_cert
confluence_client_cert_pass

confluence_ignore_titlefix_on_index¶

Added in version 1.3.

When configured to add a prefix or postfix onto the titles of published documents, a user may not want to have any title modifications on the index page. To prevent modifying an index page’s title, this option can be set to True. By default, this option is set to False.

confluence_ignore_titlefix_on_index = True

See also:

confluence_publish_postfix
confluence_publish_prefix

confluence_page_search_mode¶

Added in version 2.6.

Note

This option is only supported using the v1 editor.

Configures the mode which pages will be fetched from Confluence. For Confluence Data Center instances, there may be performance issues when attempting to query content/ API (CONFSERVER-57639). Select environments may opt to disable this endpoint in attempt to avoid performance issues, which in turn prevents this extension from fetching page content. To support these environments, users can configure this extension to use an alternative mode for fetching page content.

confluence_page_search_mode = 'search'

Supported modes are as follows:

content (default): Pages will fetched using the content/ API.
search: Pages will fetched using the content/search/ API.

confluence_parent_override_transform¶

Added in version 2.2.

Note

Using this option may have unexpected results when using certain features of this extension. For example, users with purging enabled may not have pages with parent-ID overrides purged.

A function to override the parent page to publish a document under. This option is available for advanced users needing to tailor specific parent pages for individual documents. A provided transform is invoked with the document name and the expected parent page (numerical identifier) the document will be published under. A configuration can tweak the identifier used when publishing.

def my_publish_override(docname, parent_id):
    if docname == 'special-doc':
        return 123456

    return parent_id

confluence_parent_override_transform = my_publish_override

This extension will not check the validity of the identifiers set. If a provided page identifier does not exist or the publishing user does not have access to the parent page, the publication will fail with an error provided by Confluence.

See also:

Confluence Spaces and Unique Page Names
confluence_disable_autogen_title
confluence_publish_postfix
confluence_publish_prefix
confluence_remove_title

confluence_version_comment¶

Added in version 1.8.

Changed in version 2.1: Support comments for first/new pages on Confluence Cloud.

Note

Confluence Data Center does not support setting a version comment for the first/new page revision.

A string value to be added as a comment to Confluence’s version history.

confluence_version_comment = 'Automatically generated.'

Advanced processing configuration ¶

confluence_file_suffix¶

The file name suffix to use for all generated files. By default, all generated files will use the extension .conf.

confluence_file_suffix = '.conf'

confluence_html_macro¶

Added in version 2.7.

This option will configure the HTML macro type for the confluence_html directive. By default, the html macro identifier is set.

confluence_html_macro = 'html'

See also:

confluence_lang_overrides¶

Added in version 2.6.

A dictionary to override literal block-based directive language values to a Confluence supported code block macro language values. The default mapping accepts Pygments documented language types to Confluence-supported syntax highlight languages.

confluence_lang_overrides = {
    'rs': 'rust',
    'rust': 'rust',
}

In the event that a language entry is missing or returns a None value, the provided language type will be transform to a default language type as if this transform was not provided.

confluence_latex_macro¶

Added in version 1.8.

Note

Confluence does not provide stock support for LaTeX macros.

The name of a LaTeX macro to use when wishing to render LaTeX content on a Confluence instance. Stock Confluence instances do not support LaTeX content by default. However, if an instance has installed a marketplace add-on that supports LaTeX, this option can be used to hint to render LaTeX content (such as mathematical notation) by configuring this option.

confluence_latex_macro = 'macro-name'
 (or)
confluence_latex_macro = {
    'block-macro': 'block-macro-name',
    'inline-macro': 'inline-macro-name',
    'inline-macro-param': 'inline-macro-parameter', # (optional)
}

The name of a LaTeX macro will vary based on which add-on is installed. For a list of known macro names or steps to determine the name of a supported macro, see the macro table/instructions found in the math guide.

If this option is not set, any LaTeX content processed in a document will instead be converted to images using dvipng/dvisvgm (see also sphinx.ext.imgmath for additional information).

See also:

confluence_link_suffix¶

The suffix name to use for generated links to files. By default, all generated links will use the value defined by confluence_file_suffix.

confluence_link_suffix = '.conf'

confluence_mentions¶

Added in version 1.9.

Provides a dictionary of key-to-value mappings which can be used with confluence_mention roles. When defining mentions, documents can reference a user’s account identifier, user key or username (depending on the Confluence instance being published to). This configuration can be used to swap the value mentioned in a document with a value specified in configuration. For example, with the following configuration:

confluence_mentions = {
    'myuser':  '3c5369:fa8b5c24-17f8-4340-b73e-50d383307c59',
}

With a document such as follows:

For more information, contact :confluence_mention:`myuser`:

The value myuser will be replaced with the configured account identifier. This can be useful for when trying to manage multiple user’s account identifiers when targeting a Confluence Cloud instance, as well as providing a quick-way to swap a generic contact role which may change over time.

See also:

Mention roles

confluence_navdocs_transform¶

Added in version 1.7.

A function to override the document list used for populating navigational buttons generated from a confluence_prev_next_buttons_location configuration. This can be helpful in advanced publishing cases where a user would like ignore or re-order select pages from navigation, or even reference pages outside of documentation list.

 def my_navdocs_transform(builder, docnames):
     # override and return a new docnames list
     return docnames

confluence_navdocs_transform = my_navdocs_transform

confluence_permit_raw_html¶

Added in version 2.2.

Caution

Using this option is considered unsupported. This extension will allow users to directly publish HTML content defined in a document, but there is no guarantees that the content will render as expected, or even be able to be published to a configured Confluence instance.

Configure whether to permit the use of raw HTML content in generated documents. While Confluence renders pages through a website, content is stored using a “storage” format, which only supports a subset of HTML. Confluence may filter out or reject the publication of pages with certain HTML content.

Some documentation may rely on HTML-specific content, and if this HTML content is not too complex, this may be renderable on a Confluence instance. Users wanting to allow this can enable this option to have HTML content directly injected on pages, or even placed inside an HTML-supported macro (if such a macro is available for the target Confluence instance):

confluence_permit_raw_html = True
 (or)
confluence_permit_raw_html = 'html'

Using this option is not supported. Content may be automatically stripped when published into Confluence, content may not render as expected (e.g. styles can be ignored, JavaScript will not function) or Confluence may reject the publication of Confluence document (i.e. failing to upload a page).

See also:

confluence_disable_autogen_title
confluence_title_overrides

Other options ¶

suppress_warnings¶

Added in version 2.1.

This extension supports suppressing warnings using Sphinx’s suppress_warnings configuration. The following includes additional warning types that may be suppressed:

confluence – All warnings
confluence.deprecated – Configuration deprecated warnings
confluence.deprecated_develop – Development deprecated warnings
confluence.unsupported_code_lang – Unsupported code language

Deprecated options ¶

confluence_lang_transform¶: Changed in version 2.6.

This option has been replaced by confluence_lang_overrides.

confluence_master_homepage¶: Changed in version 1.6.

This option has been renamed to confluence_root_homepage.

confluence_parent_page_id_check¶

Changed in version 1.9: The confluence_parent_page option now accepts both a page name and identifier.

The page identifier check for confluence_parent_page. By providing an identifier of the parent page, both the parent page’s name and identifier must match before this extension will publish any content to a Confluence instance. This serves as a sanity-check configuration for the cautious.

confluence_parent_page_id_check = 123456

Option	Description
`owner` (required)	The owner (group or user) of a project.
`repo` (required)	The name of the repository.
`container`	The folder inside the repository which is holding the documentation. This will vary per project, for example, this may be `Documentation/` or `doc/`. If the documentation resides in the root of the repository, this option can be omitted or set to an empty string.
`version` (required)	The version of the sources to list. This is typically set to either a branch (e.g. `main`) or tag value. For Codeberg, also include the version type. For example, `branch/main` or `tag/1.0`.
`view`	The view mode to configure. By default, this value is set to `blob` for GitHub/GitLab and `view` for Bitbucket. GitHub/GitLab users may wish to change this to `edit` to create a link directly to the editing view for a specific document.
`host`	The hostname value to override. This option is useful for instances where a custom domain may be configured for an organization.
`protocol`	The protocol value to override (defaults to `https`).

Table of Contents

Previous topic

Next topic

This Page

Configuration¶

Essential configuration ¶

Generic configuration ¶

Publishing configuration ¶

Advanced publishing configuration ¶

Advanced processing configuration ¶

Other options ¶

Deprecated options ¶