Supporting include and excerpt confluence macros

[girivs82]

Are the include and excerpt confluence macros supported? If not, is there a plan to support them? These macros are essential in my documentation.

[jdknight]

At this time, there is no immediate directive-based support to utilize Confluence's excerpt macros.

A workaround would be to manually create an excerpt macro on one page, such as follows:

pagea
=====

.. raw:: confluence_storage

    <ac:structured-macro ac:name="excerpt" ac:schema-version="1">
        <ac:parameter ac:name="name">test</ac:parameter>
        <ac:parameter ac:name="atlassian-macro-output-type">INLINE</ac:parameter>
        <ac:rich-text-body>

This is a **test**.

.. raw:: confluence_storage

        </ac:rich-text-body>
    </ac:structured-macro>

Followed by utilizing an excerpt-include macro in another document:

pageb
=====

.. raw:: confluence_storage

    <ac:structured-macro ac:name="excerpt-include" ac:schema-version="1">
        <ac:parameter ac:name="name">test</ac:parameter>
        <ac:parameter ac:name=""><ac:link><ri:page ri:content-title="pagea" /></ac:link></ac:parameter>
    </ac:structured-macro>

---

To support such an enhancement, it is assumed the following should be aimed for:

• Adding support for a confluence_except and confluence_except_include directives, where these entries can be gracefully mapped across documents without the need for a user to manage the document linking.
• Attempt to handle a situation where a user may wish to use confluence_except_include to reference an except that is built outside a documentation (referencing a pre-created page, outside the document tree being published).
• A warning should be generated when trying to build an except-include on the same page as an except (which looks to cause an exception warning in Confluence Cloud).

[girivs82]

Thanks! I will use the workaround for now until this enhancement is implemented. If you could document this, it would be a very useful reference for such uses until the enhancement.

[girivs82]

I added the confluence_excerpt keyword in a fork of this repo, and while testing, I noticed that headings disappear if they are within the confluence_except directive. Should I send a pull request for review?

[girivs82]

Same problem with the existing confluence_expand macro. Headings disappear if within the context of the macro.

[girivs82]

I think the problem may be the excerpt macro itself. I think it may not work across sections and I heard from a colleague that for this, I need to use a multi excerpt macro. In any case, I will send a pull request.

[jdknight]

Changes that were first introduced in #677 have been updated and expanded on to provide a more "complete" support for excerpt macros. The changes add support for an confluence_excerpt and confluence_excerpt_include directive. This change has been added into the main branch and should be made available next stable release. Thanks for the initial changes and hopefully this may serve the active (or original) use case. Feel free to leave a comment if there is anything that appears to be missing.

If users wish to use this capability before a release is made, the development version of this extension can be installed.

[jdknight]

v2.0 is now available on PyPI -- marking as closed.