How to build the Confluence macros you need without developing a custom app
Share on socials
How to build the Confluence macros you need without developing a custom app
Confluence comes with dozens of built-in macros that can help you organise information, improve page layouts, and surface content dynamically. But eventually you’ll run into a use case that isn't covered by the out-of-the-box macro library.
Maybe you want to
Display user information automatically
Create a custom reporting widget
Pull data from Jira
Show information from an external system
Extend the functionality of an existing Confluence macro
Traditionally, solving these problems meant building a custom app, a significant investment of time, development effort, and ongoing maintenance.
With ScriptRunner for Confluence Cloud, there’s an easier, more flexible solution for you.
This guide will show you examples of how to build the perfect custom macros for your business needs.
What are custom macros?
Custom macros in ScriptRunner for Confluence Cloud allow administrators to create their own reusable, script-powered macros using Groovy.
Instead of relying only on the native Confluence macros, you can build macros that:
- Fetch information from Confluence and other systems
- Process data
- Display content in a custom format
- Support business-specific workflows
Think of them as a way to extend Confluence without the overhead of building and maintaining a dedicated app.
What can you build with ScriptRunner custom macros?
Here are three use-cases to show what’s possible, make sure to watch the video to learn how to build them.
1. Display user data on a page
Instead of manually adding user details and letting them go out of date, this macro dynamically pulls and displays the information.
It can:
- Take a username as input
- Fetch user data
- Display it directly on the page
Why is this useful?
Great for onboarding pages, team directories, or contextual information.
2. Generate reports from labels
Want to track content across your workspace?
You can build a macro that:
- Finds all pages with a specific label
- Pulls relevant data
- Displays it in a structured table
Why is this useful?
This macro turns labels into an agile reporting mechanism and is perfect for knowledge tracking, project updates, and content reporting
3. Extend existing Confluence macros
Sometimes a built-in macro almost works, but isn’t quite there for what you need.
You can create your own version to:
- Pull data from different pages (not just the current one)
- Add more fields
- Customise how information is displayed
Why is this useful?
This gives admins more control than native Confluence functionality allows, helping teams create page experiences that better match their real workflows.
Prefer a walkthrough?
Check out the video below for a step-by-step demo of how to build all three use cases. Start at 9:10 to jump straight into the examples.
We’ve linked the video here at 9:10 already so you can jump right in
Ready to take the next steps?
Want to explore how custom macros can work for your team's specific use cases? Talk to a ScriptRunner Customer Success Manager for a walkthrough of real-world examples, answers to your questions, and help getting started.
Build the Confluence experience your team really needs
No two organisations use Confluence in exactly the same way. That's why relying solely on built-in functionality often leads to compromises. You shouldn’t have to compromise.
ScriptRunner custom macros give you the flexibility to create the functionality your teams need, whether that's reporting, governance, integrations, metadata management, or entirely new user experiences.
Instead of waiting for a Marketplace app to exist or investing in custom app development, you can build the macro you wish existed and make it available to your entire organisation.
Have an idea for how ScriptRunner could do even more?
We'd love to hear your feedback. Share your thoughts and help shape future product development.
Published on 27 July 2026
Authors
Nitin Chand
Share this tutorial