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_expand::

New in version 1.3.

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

New in version 1.3.

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

: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 (ref).

.. confluence_newline::

New in version 1.7.

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

.. confluence_newline::

Jira

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

.. jira:: [jql]

New in version 1.2.

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 (ref). 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
.. jira_issue:: [issue-id]

New in version 1.2.

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 (ref). 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

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 (ref) 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::

New in version 1.8.

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!

See also LaTeX roles.