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

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)

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 seperation may be desired between inlined elements.

.. confluence_newline::

Added in version 1.7.

.. 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.

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.