Directives

The following outlines additional directives supported by this extension.

Directives listed below are only supported when using this extension. For users with documentation that is built with multiple builders, the following can be used to restrict these directives to supported builders by using the :only: directive. For example:

.. only:: builder_confluence or builder_singleconfluence

    .. confluence_metadata::
        :labels: label-test

Alternatively, users may be interested in a third-party extension which can help support the use of Confluence directives in other builders:

sphinx-confluencebuilder-bridge

https://github.com/adamtheturtle/sphinx-confluencebuilder-bridge

Common

.. confluence_excerpt::

The confluence_excerpt directive allows a user to define a Confluence Excerpt Macro to help build snippets of content to be shared for other pages. For example:

.. confluence_excerpt::

    This content is reusable.

This directive supports the following options:

:atlassian-macro-output-type: output type (block, inline)

When this option is configured to inline (default), the rendered excerpt macro will be presented inlined with other content in the page (no additional line breaks). The block type can be used to help render an excerpt macro as a block-level element.

.. confluence_excerpt::
    :atlassian-macro-output-type: block

    This content is reusable.

:hidden: flag (boolean)

Whether the macro’s content should be rendered on the page that defines it. Valid values are true or false (default).

.. confluence_excerpt::
    :hidden: true

    This content is reusable.

:name: value (string)

A name value to apply to the macros “name” field. This can be used to name a specific excerpt on a page, which can be explicitly mapped to with an excerpt-include when attempting to define multiple excerpts on the same page. If only a single excerpt is created, an excerpt-include will implicitly use the first excerpt on a page.

.. confluence_excerpt::
    :name: my-excerpt

    This content is reusable.

Added in version 2.0.

.. confluence_excerpt_include:: [ref]

The confluence_excerpt_include directive allows a user to define a Confluence Excerpt Include Macro to help include snippets of content provided by excerpt macro definitions. An include macro requires an explicit reference to the page which holds the excerpt content to load. Users can specify an exclamation-prefixed document name, referring to a local Sphinx documentation file to load an excerpt from. For example:

.. confluence_excerpt_include:: !my-excerpt-docname

Users may also specify a known document title name that may be managed outside their Sphinx project set. For example:

.. confluence_excerpt_include:: Custom excerpt

To target a page on a different space, the space name can be prefixed before the document title:

.. confluence_excerpt_include:: MYSPACE:Custom excerpt

This directive supports the following options:

:name: value (string)

The explicit name of the excerpt to use for a given page. If no name is provided, the excerpt-include macro will use the first available excerpt on the target page.

.. confluence_excerpt_include:: !my-excerpt-docname
    :name: my-excerpt

:nopanel: flag (boolean)

Whether the macro’s content should remove the panel around the excerpted content. Valid values are true or false (default).

.. confluence_excerpt_include:: !my-excerpt-docname
    :nopanel: true

Added in version 2.0.

.. confluence_expand::

The confluence_expand directive allows a user to define a Confluence Expand Macro to help manage the visibility of content on a page. For example:

.. confluence_expand::

    This content is captured inside the expand macro.

This directive supports the following options:

:title: value (string)

A string value to apply to the macros “title” field.

.. confluence_expand::
    :title: View more details...

    This content is captured inside the expand macro.

See also Collapsed content.

Added in version 1.3.

.. confluence_html::

Warning

The HTML Macro is disabled by default on Confluence instances. Using this directive is only useful for users that have instances where a system administrator has enabled their use.

The confluence_html directive allows a user to define a Confluence HTML Macro to render HTML content on a page. For example:

.. confluence_html::

    <h1>Header</h1>

    This is an <strong>example</strong>.

See also confluence_permit_raw_html.

Added in version 2.7.

.. confluence_metadata::

The confluence_metadata directive allows a user to define metadata information to be added during a publish event. This directive supports the following options:

:editor: value (v1, v2)

Deprecated since version 2.14: Support for page-specific editor overrides will be removed in 2026 as Confluence Cloud removes support for the v1 editor.

Pages are publish with the editor type configured through the confluence_editor option. However, users can override the editor for a specific page using the editor metadata option.

.. confluence_metadata::
    :editor: v2

See also confluence_editor.

:full-width: flag (boolean)

Pages are publish with the full-width appearance configured through the confluence_full_width option. However, users can override the appearance for a specific page using the full-width metadata option.

.. confluence_metadata::
    :full-width: false

See also confluence_full_width.

:guid: value (string)

Assign a user-managed GUID value for a page. This value can be shared in a subset of events generated by this extension.

:labels: value (space separated strings)

A space-separated list of label strings to apply to a page. The following example will result in the labels label-a and label-b being added to the document which defines this directive.

.. confluence_metadata::
    :labels: label-a label-b

See also confluence_global_labels.

Added in version 1.3.

Changed in version 2.2: Added editor and full-width support.

Changed in version 2.8: Added guid support.

.. confluence_newline::

The confluence_newline directive supports the injection of a newline in a document where separation may be desired between inlined elements.

.. confluence_newline::

Added in version 1.7.

.. confluence_panel::

The confluence_panel directive allows a user to define a Confluence Panel Macro to help format content in a customizable colored panel on a page. For example:

.. confluence_panel::

    This content is captured inside the panel macro.

This directive supports the following options:

:bg-color: value (string)

A string value to apply to the macros “bgColor” field.

.. confluence_panel::
    :bg-color: #00ff00

    This content is captured inside the panel macro.

:border-color: value (string)

A string value to apply to the macros “borderColor” field.

.. confluence_panel::
    :border-color: #ff0000

    This content is captured inside the panel macro.

:border-style: value (string)

A string value to apply to the macros “borderStyle” field.

.. confluence_panel::
    :border-style: solid

    This content is captured inside the panel macro.

:border-width: value (string)

A string value to apply to the macros “borderWidth” field.

.. confluence_panel::
    :border-width: 42

    This content is captured inside the panel macro.

:title: value (string)

A string value to apply to the macros “title” field.

.. confluence_panel::
    :title: This is my title

    This content is captured inside the panel macro.

:title-bg-color: value (string)

A string value to apply to the macros “titleBGColor” field.

.. confluence_panel::
    :title: my title
    :title-bg-color: #0000ff

    This content is captured inside the panel macro.

:title-color: value (string)

A string value to apply to the macros “titleColor” field.

.. confluence_panel::
    :title: my title
    :title-color: #ff00ff

    This content is captured inside the panel macro.

Added in version 2.13.

.. confluence_table_width::

The confluence_table_width directive allows a user to define widths for tables defined after the directive. For example:

.. confluence_table_width:: 800px

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | ...        | ...      |          |
+------------------------+------------+----------+----------+

To reset the table width for additional tables, a value unset can be provided.

.. confluence_table_width:: 800px

+------------+------------+--------------+
| Product    | Price      | Availability |
+============+============+==============+
| Widget     | $10        | In stock     |
+------------+------------+--------------+
| Gadget     | $15        | Out of stock |
+------------+------------+--------------+

.. confluence_table_width:: unset

+------------+------------+------------+
| Name       | Age        | City       |
+============+============+============+
| Alice      | 30         | New York   |
+------------+------------+------------+
| Bob        | 25         | London     |
+------------+------------+------------+

See also the confluence_default_table_width option.

Added in version 2.15.

.. confluence_toc::

The confluence_toc directive allows a user to define a Confluence Table of Contents Macro. Users are typically recommended to use reStructuredText’s Table of Contents directive when generating local table of contents; and Confluence’s Table of Contents macro is typically not a replacement of Sphinx’s toctree directive. However, if a user wishes to take advantage of Confluence’s TOC-specific macro capabilities, the following can be used:

.. confluence_toc::

This directive supports the following options:

:absolute-url: flag (boolean)

Whether the macro should generate full URLs for TOC entry links. Valid values are true or false (default).

.. confluence_toc::
    :absolute-url: true

:exclude: value (string)

Filter heading to exclude entries matching the provided value. The value should support a regular expressions string.

:include: value (string)

Filter heading to include entries matching the provided value. The value should support a regular expressions string.

:indent: value (string)

The indent to apply for header entries.

.. confluence_toc::
    :indent: 15px

:max-level: count (number)

Defines the lowest heading level to include in the table of contents.

.. confluence_toc::
    :max-level: 10

:min-level: count (number)

Defines the highest heading level to include in the table of contents.

.. confluence_toc::
    :min-level: 1

:outline: flag (boolean)

Whether the macro should include outline numbering for entries. Valid values are true or false (default).

.. confluence_toc::
    :outline: true

:printable: flag (boolean)

Whether the macro should render when a user prints a Confluence page. Valid values are true (default) or false.

.. confluence_toc::
    :printable: true

:separator: separator style type of the toc (brackets, braces, parens, <user-defined>)

When the type option is configured to flat, this option can configure the separator type applied between header entries. By default, the separator type is set to brackets.

.. confluence_toc::
    :separator: braces

:style: list style type of the toc (default, none, disc, circle, square, decimal, lower-alpha, lower-roman, upper-roman)

Configures how the table of contents will be style its list type. By default, the style type is set to default.

.. confluence_toc::
    :style: square

:type: outline type of the toc (flat or list)

Configures how the table of contents will be style its structure. Valid values are flat or list (default).

.. confluence_toc::
    :type: flat

Added in version 1.9.

.. confluence_viewpdf::

The confluence_viewpdf directive allows a user to define a Confluence PDF Macro to help inline PDF files in a page. For example:

.. confluence_viewpdf:: example.pdf

Added in version 2.14.

Jira

The following directives can be used to help include Jira macros into generated Confluence documents.

.. jira:: [jql]

The jira directive allows a user to build a Jira macro to be configured with a provided JQL query. For example:

.. jira:: project = "TEST"

This directive supports the following options:

:columns: value (comma separated numbers)

A comma-separated list of columns to use when displaying the macro to show in the Jira table.

.. jira:: project = "TEST"
    :columns: key,summary,updated,status,resolution

:count: flag (boolean)

Whether the macro should display a table or just the number of issues. Valid values are true or false.

.. jira:: project = "TEST"
    :count: true

:maximum-issues: count (number)

The maximum number of issues a jira directive will display. By default, Confluence defaults to 20.

.. jira:: project = "TEST"
    :maximum-issues: 10

:server: instance (string)

Indicates a named Jira server provided via confluence_jira_servers. When set, options server-id and server-name cannot be set.

.. jira:: project = "TEST"
    :server: server-1

:server-id: uuid (string)

The UUID of the Jira server to link with. When set, the option server-name needs to be set and the option server cannot be set.

.. jira:: project = "TEST"
    :server-id: d005bcc2-ca4e-4065-8ce8-49ff5ac5857d
    :server-name: MyAwesomeJiraServer

:server-name: name (string)

The name of the Jira server to link with. When set, the option server-id needs to be set and the option server cannot be set.

.. jira:: project = "TEST"
    :server-id: d005bcc2-ca4e-4065-8ce8-49ff5ac5857d
    :server-name: MyAwesomeJiraServer

Added in version 1.2.

.. jira_issue:: [issue-id]

The jira_issue directive allows a user to build a Jira macro to be configured with a provided Jira key. For example:

.. jira_issue:: TEST-123

This directive supports the following options:

:server: instance (string)

Indicates a named Jira server provided via confluence_jira_servers. When set, options server-id and server-name cannot be set.

.. jira_issue:: TEST-123
    :server: server-1

:server-id: uuid (string)

The UUID of the Jira server to link with. When set, the option server-name needs to be set and the option server cannot be set.

.. jira_issue:: TEST-123
    :server-id: d005bcc2-ca4e-4065-8ce8-49ff5ac5857d
    :server-name: MyAwesomeJiraServer

:server-name: name (string)

The name of the Jira server to link with. When set, the option server-id needs to be set and the option server cannot be set.

.. jira_issue:: TEST-123
    :server-id: d005bcc2-ca4e-4065-8ce8-49ff5ac5857d
    :server-name: MyAwesomeJiraServer

Added in version 1.2.

See also Jira roles.

LaTeX

Note

LaTeX support requires dvipng/dvisvgm to be installed on system; however, if a Confluence instance supports a LaTeX macro, the confluence_latex_macro option can be used instead. For more information, please read Math support.

The following directive can be used to help add LaTeX content into a Confluence page.

.. confluence_latex::

The confluence_latex directive allows a user to add LaTeX content into a document. For example:

.. confluence_latex::

    $\mathfrak{H}$ello world!

This directive supports the following options:

:align: "left", "center", or "right" (string)

The alignment to apply on the LaTeX content. By default, the value is set to center.

.. confluence_latex::
    :align: left

    $\mathfrak{H}$ello world!

Added in version 1.8.

See also LaTeX roles.

Smart links

Note

Smart links will only render when using Confluence Cloud.

.. confluence_doc::

The confluence_doc directive allows a user to define a link to a document that is styled with a card appearance. The directive accepts the name of a document in an absolute or relative fashion (in the same manner as Sphinx’s :doc: role). For example:

.. confluence_doc:: my-other-page

This directive supports the following options:

:card: card type (block, embed)

When using block, a smart link card is generated for the document link. The card will provide a summary of the target document. When using embed, the contents of the document will rendered on the page.

.. confluence_doc:: my-other-page
    :card: block

:layout: layout type (align-start, align-end, center, wrap-left, wrap-right)

Note

This option is only applicable when using an embed card.

Specifies how an embedded card will be laid out on a page. Embedded cards will default to 100% width. Therefore, to take advantage of certain layout capabilities, users should also assign an appropriate width as well.

.. confluence_doc:: my-other-page
    :card: embed
    :layout: align-end
    :width: 20

:width: value (integer)

Note

This option is only applicable when using an embed card.

Specifies the width to apply for an embedded card. The width is a value from 0 to 100 (e.g. a value of 80 for 80% of the page).

.. confluence_doc:: my-other-page
    :card: embed
    :width: 50

Added in version 2.1.

.. confluence_link::

The confluence_link directive allows a user to define a link to a page that is styled with a card appearance. The directive accepts a URL. How Confluence renders the context of a link card will vary based on which link targets Confluence supports. For example:

.. confluence_link:: https://example.com

This directive supports the following options:

:card: card type (block, embed)

When using block, a smart link card is generated for the link. The card will provide a summary of the target link. When using embed, the contents of the link will rendered on the page.

.. confluence_link:: https://example.com
    :card: block

:layout: layout type (align-start, align-end, center, wrap-left, wrap-right)

Note

This option is only applicable when using an embed card.

Specifies how an embedded card will be laid out on a page. Embedded cards will default to 100% width. Therefore, to take advantage of certain layout capabilities, users should also assign an appropriate width as well.

.. confluence_link:: https://example.com
    :card: embed
    :layout: align-end
    :width: 20

:width: value (integer)

Note

This option is only applicable when using an embed card.

Specifies the width to apply for an embedded card. The width is a value from 0 to 100 (e.g. a value of 80 for 80% of the page).

.. confluence_link:: https://example.com
    :card: embed
    :width: 50

Added in version 2.1.

See also smart link roles.