Features

The following outlines the reStructuredText/Sphinx markup, configuration entries and more supported by this extension. The intent of this extension is to support various standard Sphinx features that can be rendered on a Confluence instance. Below will identify features that have been tested, planned to be implemented in the future or is not compatible with Confluence.

reStructuredText markup

Type	Notes
admonitions	Supported
bibliographic fields	Supported
block quotes	Supported
bullet lists	Supported
citations	Supported
compound paragraph	Supported
container	Supported
csv-table	Supported
definition lists	Supported
enumerated lists	Limited support. Only auto-enumerator lists (#) are supported. Using other types of enumerated lists will be handled as auto-enumerators. This is a limitation in the Confluence markup.
epigraph	Supported
footnotes	Supported
highlights	Supported
hyperlink targets	Supported
images	Limited support. When using a Confluence v2 editor, images cannot be inlined.
inline markup	Supported
list-table	Supported
literal blocks	Supported
math	Supported with additional system tools. Requires a LaTeX and dvipng/dvisvgm installation. When using a Confluence v2 editor, images cannot be offset to be aligned in a paragraph.
parsed literal block	Limited support. When using a Confluence v2 editor, literal blocks cannot be parsed and the contents will be placed inside a code macro.
option lists	Supported
pull-quote	Supported
raw	Supported. Use the confluence_storage format type to inject raw data into a document.
rubric	Supported
sections	Supported
tables	Supported
transitions	Supported

(note: directive options “class” and “name” are mostly ignored as they are not supported in a Confluence format document)

Sphinx markup

Type	Notes
centered	Supported
code	Limited support. Supported languages (for highlighting) are limited to the languages supported by Confluence’s code block macro. This applies to a language defined in a code-block directive or set through a highlight directive. The code-block directive contain the options emphasize-lines and lines which are not supported in the Confluence markup. The code block macro only supports a simple line numbers (configurable with the linenos option; Confluence v1 editor only). When the class attribute contains collapse, the macro will be configured to be collapsed.
deprecated	Supported
download	Supported
glossary	Supported
hlist	Limited support. When using a Confluence v2 editor, the maximum columns for an hlist is three.
manpage	Supported
production list	Supported
toctree	Supported
versionadded	Supported
versionchanged	Supported

Markdown support

This extension can support the rendering of Markdown content with the use of Sphinx with the MyST Parser. Most content can be translated to an applicable Confluence storage format. However, not all content produced by MyST Parser will work with this extension. Specifically, any directives that generate HTML content or users who add raw HTML content to documents are not accepted by default by this extension. This includes line breaks, strikethroughs and more. Users may attempt to use the confluence_permit_raw_html option to help workaround select use cases, but the use of the option is unsupported. When the option is enabled, published content may not render as expected or may not be able to be published.

Extensions

This extension will attempt to support any extension that is integrated in Sphinx’s main source repository. The following section shows the status of each of these extensions:

Type	Notes
sphinx.ext.autodoc	Supported
sphinx.ext.autosectionlabel	Supported
sphinx.ext.autosummary	Supported
sphinx.ext.coverage	N/A
sphinx.ext.doctest	Supported
sphinx.ext.duration	Supported
sphinx.ext.extlinks	Supported
sphinx.ext.githubpages	N/A
sphinx.ext.graphviz	Supported
sphinx.ext.ifconfig	Supported
sphinx.ext.imgconverter	N/A
sphinx.ext.imgmath	Supported
sphinx.ext.inheritance_diagram	Supported
sphinx.ext.intersphinx	Limited support. Users should have no issues when using external modules via intersphinx_mapping. When building with publishing enabled, this extension will generate an objects.inv inventory file which can be used by other documentation sets.
sphinx.ext.jsmath	Unsupported. Confluence does not support the injection of JavaScript into a page in most scenarios.
sphinx.ext.linkcode	Supported (Sphinx v8.1+)
sphinx.ext.mathjax	Unsupported. Confluence does not support the injection of JavaScript into a page in most scenarios.
sphinx.ext.napoleon	Supported
sphinx.ext.todo	Supported
sphinx.ext.viewcode	Unsupported. This extension only supports injecting references for the html builder.

Extensions (Third-party)

Note

Support with third-party extensions (if any) may be limited. While an extension may work with other builders (such as the html builder), it may be implemented in a way which it cannot be integrated with this extension. In addition, some features that an extension may use (e.g. using JavaScript) cannot be used with a stock Confluence instance and therefore, cannot be supported.

Atlassian Confluence Builder for Sphinx does not guarantee support for third-party extensions found outside of Sphinx’s main source repository. Changes are considered towards this extension’s processing and API to make it flexible for other extensions to integrate. Also, this extension may provide optional support for select third-party extensions (if permitted and rational), to help improve user experience.

Developers wishing to integrate a third-party extension with Atlassian Confluence Builder can either attempt to add implementation inside the third-party extension itself, propose non-intrusive changes to this extension or create a new extension which can bind both desired extensions together (e.g. sphinx-confluence-nbsphinx-test). Any changes directly submitted to be added into this extension’s repository will be limited to the arbitrary release/development windows of this extension.

The following table shows a most recent state of various third-party extensions interacting with this extension:

Type	Notes
mlx.traceability	Limited support. Formatting of content may not be as expected.
sphinx-data-viewer	Limited support. Can render JSON data inside code blocks. Content has collapse all data or expand all data, but not parts of the data.
sphinx-design	Limited support. Single card support (include header, title, body and footer). No side-by-side cards, alignment or extended capabilities such as images or clickable support. Dropdowns will function except for pre-expanded directives. Support for some badges but limited to select colors supported by Confluence. No extended support for tabs, button and inline icons.
sphinx-diagrams	Supported
sphinx-gallery	Supported
sphinx-needs	Limited support. Formatting of content may not be as expected. The needs_default_layout option may need to be tailored specifically for a Confluence build.
sphinx-toolbox	Supported
sphinxcontrib-aafig	Supported. May require configuration of the aafig_format option.
sphinxcontrib-actdiag	Limited support. PNGs only; cannot configure for SVG at this time.
sphinxcontrib-blockdiag	Limited support. PNGs only; cannot configure for SVG at this time.
sphinxcontrib-drawio	Supported
sphinxcontrib-httpdomain	Supported
sphinxcontrib-kroki	Supported
sphinxcontrib-mermaid	Limited support. Requires a PNG/SVG configuration. Raw/HTML renders can be used for environments with HTML macro support.
sphinxcontrib-nwdiag	Limited support. PNGs only; cannot configure for SVG at this time.
sphinxcontrib-openapi	Supported
sphinxcontrib-plantuml	Supported. sphinxcontrib-plantuml provides its own support for this extension.
sphinxcontrib-programoutput	Supported
sphinxcontrib-seqdiag	Limited support. PNGs only; cannot configure for SVG at this time.
sphinxcontrib-svgbob	Supported
sphinxcontrib-video	Supported
sphinxcontrib-youtube	Supported

Other

If a feature or extension is not listed above, is not working as expected or has another concern, feel free to bring up an issue:

Atlassian Confluence Builder for Confluence — Issues

https://github.com/sphinx-contrib/confluencebuilder/issues