confluencebuilder

confluencebuilder copied to clipboard

Hello everyone,

Recently I started working on a tool which extracts info from Jira and Confluence and builds a nice Confluence page, based on the fetched information. It makes use of Sphinx Confluence builder to generate the Confluence page and the input is a filled-out rst template. So far, it works perfectly, but I need to extend it further

My question regards adding Confluence macros to this page. So, at the very bottom of the document I need to insert a sigrantures macro (see the picure below). I was wondering if the Confluence builder supports this particular macro. And if it does, how can insert it into the rst template, before uploading it to Confluence?

Thank you in advance, Jordan

Hey @JordanRad, I'm not too familiar with this extension, but going to make the assumption that this is a (paid) third-party extension. I do not recall there being a signature macro in stock Confluence. If I assumed incorrectly, let me know.

For third-party extension, we typically do not provide support for them. And by support, I mean providing a extension-specific directive or role definition in this extension's implementation. That being said, it still should be possible to achieve what you want by using the raw directive. The general steps are as follows:

• Generate a page on your Confluence instance, add the macro you desire on that page and save it.
• Selecting the page's option menu and selecting "View Storage format"
• In the page's content, you should see a ac:structured-macro block.
• Copy the contents of this block and add the contents into a raw directive (in theory, you can exclude any ac:schema-version or ac:macro-id tags).

For example:

.. raw:: confluence_storage

    <ac:structured-macro ac:name="my-macro-name">
        <ac:parameter ac:name="my-macro-param">value</ac:parameter>
        <ac:plain-text-body><![CDATA[ TODO_CONTENT ]]></ac:plain-text-body>
    </ac:structured-macro>

(maybe we should document something like this in the documentation instead of just saying "we support the raw directive")

Updated the documentation to provide a mini-guide on how to use custom Confluence macros. The draft before next release can be found here:

Confluence Macros https://sphinxcontrib-confluencebuilder.readthedocs.io/en/latest/guide-confluence-macros/

Feel free to provide any comments or mention any concerns.

With the information provided and changes to the documentation outlining how users can inject support for custom macros, there does not seem to be any other action items from this question. Ideally, this is enough information for users to help customized their own documentation. With that in mind, will mark this issue as closed.