Become a documentation ninja

Writing documentation sucks! But there are ways to make it easier and maybe even fun! In one of my previous blogs, I explained how you can embed your documentation in your pull requests and why you should consider doing it, too. In this blog, I want to go a bit deeper into the syntax you can use to improve your documentation pages on Confluence.

Syntax? You mean Markdown, right?

Yes, Markdown is the documentation syntax that Mark uses. However, it has some extensions that are still valid in Markdown format and allow you to use the macros from Confluence.

Linking to other pages

When you write documentation, you probably have different pages explaining different things. You can logically split areas, making it easier to navigate and read. But sometimes, you want to link from one page to another. The problem is that you don’t know the URL yet since that is a Confluence page. You could publish the page and look up the link, which kills the motivation to write documentation. Assume we have a page like this:

# My Confluence Page

My description of the page

And we want to link to this page. You can simply do this with the following syntax:

Read this on [My Confluence Page](ac:) or [read](ac:My Confluence Page) the page.

As you can see, you can link to the page title itself. Or, you can use a custom word, like “read” and link to the page. When mark uploads the page to Confluence the links will be resolved automatically.

Linking to Jira issues

Next to linking to pages, you will probably also refer to Jira issues. However, you could link to Jira issues using native markdown. When you use the Jira reference macro, the type, title, and status of the issue are shown. This gives immediate feedback to the reader on what the status is. What you need to do is to define a macro in the top of your markdown file and mention the issue as plain text. Here is an example:

<!-- Macro: MYJIRA-\d+
     Template: ac:jira:ticket
     Ticket: ${0} →

# My page that contains a Jira ticket reference

See task MYJIRA-123.

In this example, MYJIRA is the Jira project code. The macro definition matches everything that starts with MYJIRA- and is followed by a set of digits. You can then simply mention the issues in your markdown file, and they will be converted into Jira macros automatically.

Hide code snippets in collapsable macros

Especially when you write documentation, you may need to hide parts of the code snippets. One example that I use is for OS-dependent instructions. Assume you want to provide instructions on using your product on the command line. In that case, you could give instructions for Windows, Linux, and MacOS. To use this, you first need to define the macro. Then, use the macro to build the collapsable snippet.

<!-- Macro: :expand-start:(?s)(.*?):\n(.*?)\n:expand-end:
     Template: ac:expand
     Title: ${1}
     Body: ${2}  -->
# My page with command line instructions

Before you start, you must ensure you set the environment variable:

:expand-start:Unix:

Unix instructions go here

:expand-end:

:expand-start:Windows:

Windows instructions go here

:expand-end:

Page properties and status badges

This is my favorite! This is such a powerful feature of Confluence. For those of you who are not familiar with this functionality, you define a table, which contains a set of keys and values. For example, you can specify an owner and a date in this table. You also need to set a label on the page. This is required for the report page. The label is used to make a list of pages that have this label. But the cool thing is that you can also display the values of the page properties.

As you can see in the screenshot above, we have three pages. The parent page holds the report, and the child pages are Project 1 and Project 2. However, it also shows the date, owner, and status badge. This is a great way to give a nice overview of projects.

To create the page properties on the child page, you need the following syntax.

<!-- Parent: Projects -->
<!-- Label: project -->
<!-- Macro: :in-progress:
     Template: ac:status
     Title: In Progress
     Color: Blue -->

# Project 1

<ac:structured-macro ac:name="details" ac:schema-version="1">
    <ac:rich-text-body>
        <table>
            <tbody>
                <tr><th><strong>Status</strong></th><td>:in-progress:</td></tr>
                <tr><th><strong>Owner</strong></th><td>Joris Conijn</td></tr>
                <tr><th><strong>Date</strong></th><td>2025-02-15</td></tr>
            </tbody>
        </table>
    </ac:rich-text-body>
</ac:structured-macro>

The Project 2 markdown file is similar to the one above. However, the parent page has a different definition.

# Projects

<!-- Include: ac:detailssummary
     SortBy: Title
     CQL: 'space = "Projects" and label = "project"' -->

In this example, my confluence space is called Projects. The Confluence Query Language (CQL) retrieves all pages in the Projects space that have the label project. A third requirement is that the page also needs to have the page properties defined. We did this on Projects 1 and 2, so the two projects are rendered in the table.

Conclusion

Writing documentation doesn’t have to be a chore. By leveraging Confluence macros within Markdown, you can enhance your documentation with dynamic links, Jira issue references, collapsible content, and structured page properties. These features make your documentation more interactive, easier to maintain, and more useful for your team.

By embedding these enhancements directly in your markdown files, you streamline the process of writing and updating documentation, reducing friction and improving adoption. So, next time you document a feature or process, try incorporating these techniques. You might find documentation efficient and enjoyable!

Photo by cottonbro studio