confluencebuilder

confluencebuilder copied to clipboard

this is a feature request

Please add the option to generate TOC (using confluence's toc macro) within a page given a heading structure. It also helps to create deeplinks. If it is available. please improve the documentation so that this info can be found easier.

The Table of Contents Macro macro does not have a directive support yet, but we can plan to add a confluence_toc directive type in attempt to support this.

At this time, a workaround would be to add something like this to use Confluence's TOC macro:

(default)

.. raw:: confluence_storage

    <ac:structured-macro ac:name="toc" ac:schema-version="1" />

(parameter examples; see Confluence's TOC tree macro for more macro options)

.. raw:: confluence_storage

    <ac:structured-macro ac:name="toc" ac:schema-version="1">
        <ac:parameter ac:name="maxLevel">6</ac:parameter>
        <ac:parameter ac:name="minLevel">2</ac:parameter>
        <ac:parameter ac:name="outline">true</ac:parameter>
        <ac:parameter ac:name="type">flat</ac:parameter>
    </ac:structured-macro>

To my own understanding, Confluence's TOC tree macro is for local page header/TOC only. I believe a matching reStructuredText equivalent would be the use of the contents directive, such as follows:

.. contents::
    :local:

This will provide support for things like backlinks; but will not have capabilities such as Confluence flat-type TOCs.

Initial support has been introduced (#660) to support Confluence's Table of Contents macros through Sphinx-supported directives. This change has been added into the main branch and should be made available next stable release. If users wish to use this capability before a release is made, the development version of this extension can be installed.

v1.9 is now available on PyPI -- marking as closed.