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

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