DEV Community: Yamuno

Jira Bulk Change: Edit Many Work Items at Once

Yamuno — Tue, 03 Nov 2026 05:56:30 +0000

Jira Bulk Change: Edit Many Work Items at Once

Short answer: In Jira Cloud, search for the work items you want, then open More actions (•••) > Bulk change all work items. A four-step wizard lets you edit fields, transition, move, delete, or watch up to 1,000 work items in one go. You need the global Make bulk changes permission plus the normal permissions in each space, and there is no undo, so check your search before you start.

Bulk change is one of those Jira features people use a few times a year: closing out an old sprint, reassigning a leaver's work, fixing labels after an import, setting the missing resolution that keeps reports wrong. This guide walks through the native wizard, the JQL that makes it safe, the limits that trip people up, and what to do when the people who need bulk edits shouldn't be given the global permission.

What bulk change can do

Jira's bulk change works on the results of a search. From those results you pick one operation:

Operation	What it does	Typical use
Edit	Change fields on all selected work items	Set a fix version, add labels, change priority or assignee
Transition	Move work items through the workflow, filling any required fields	Close a batch as Done with a resolution
Move	Move work items to another space or work type	Reorganise after a team change
Delete	Delete the work items	Remove test or duplicate items
Watch / Stop watching	Add or remove yourself as a watcher	Follow a set of work items for a release

Which fields you can edit depends on the work items you selected. If they come from spaces with different field configurations, Jira only offers the fields they have in common.

How to bulk change work items in Jira Cloud

Go to Search and select View all work items.
Filter the list to the work items you want. Switching to JQL is the most reliable way to do this (see the next section).
Select More actions (•••) > Bulk change all n work items.
Choose work items. Every result is ticked. Untick anything you want to leave out, then select Next.
Choose operation. Pick Edit, Transition, Move, Delete, or Watch, then Next.
Operation details. Set the new values. For Edit, tick each field you want to change and give it a value. For Transition, pick the transition and fill in any fields it requires, such as the resolution.
Decide on notifications. Untick Send mail for this update if you don't want everyone involved to get an email for every work item.
Confirmation. Read the summary and select Confirm. Jira shows a progress page while it works through the items.

JQL to pick the right work items

The search is the most important part of a bulk change, because the wizard changes everything the search returns. A few patterns that come up often:

project = SUP AND statusCategory = Done AND resolution is EMPTY

Done work items with no resolution. These are the reason many reports and dashboards miscount closed work; bulk edit the resolution to fix them.

sprint in closedSprints() AND statusCategory != Done

Work left over in sprints that are already closed, ready to move to the backlog or a new sprint.

project = WEB AND updated < -90d AND statusCategory != Done

Open work nobody has touched in 90 days, a good candidate for a clean-up transition.

labels = legacy-import AND priority is EMPTY

Imported items still missing a priority.

Before you run a bulk change, read the result count and open a few results. If the number surprises you, the query is wrong. Saving the query as a filter also leaves you a record of exactly which work items were changed.

Limits to know before you start

Atlassian's documentation lists a few rules that explain most "why can't I do this" moments:

You need the global Make bulk changes permission. Without it, the bulk change option is missing from the menu. On top of that you need the usual permission for the change in every space involved, such as Move work items to move them.
Up to 1,000 work items at a time. A larger search has to be split, for example by space or by created date.
Transitions go one workflow at a time. If the selected work items use different workflows, Jira groups them and you transition one group at a time. Only one bulk transition can run at a time.
Moving can lose data. Fields that don't exist in the target space or work type are dropped.
There is no undo. The history of each work item shows what changed, but reversing a bad bulk change means another bulk change, if the old values are even known.

The permission is the one that hurts most in practice. Admins are often careful with it, because one bulk change can touch a thousand work items across every space the person can edit. That leaves team leads and support staff asking an admin every time they need to reassign or relabel a batch of work.

Bulk changes without the global permission

Script Toolkit for Jira includes seven ready-made bulk tools for exactly that situation:

Tool	What it does
Bulk Transition	Moves work items to a status, using whichever transition each one has available
Bulk Set Resolution	Sets the resolution on work items closed without one
Bulk Assign	Assigns work items to one person, or unassigns them
Bulk Add Comment	Posts the same comment on every matching work item
Bulk Edit Labels	Adds and removes labels, leaving other labels in place
Bulk Set Priority	Sets the priority on many work items at once
Copy Custom Field Values	Copies one custom field into another of the same type

An admin decides who can use each tool under Jira settings > Apps > Script Toolkit > Tools: nobody (the default), admins only, admins and chosen groups, or everyone. So you can open Bulk Assign and Bulk Edit Labels to your team leads group without handing anyone a site-wide bulk permission.

People open Apps > Script Toolkit Tools, pick a tool, type a JQL query (it suggests fields and values and flags invalid JQL as you type), and run it on up to 5,000 work items per run. Two details make this safe to hand out:

Tools run with the person's own Jira permissions. Access to a tool grants no new rights. If someone can't edit a work item, that item fails with an error instead of changing silently.
Every item gets a result. Progress is shown as the tool runs, and failed items say why.

Like the native wizard, these changes can't be undone, so the same habit applies: check the match count first. The tools don't move or delete work items; for those, use Jira's own bulk change. The tools guide covers access and limits, and the launch post shows what else the app does.

Repeat bulk updates with Automation

If the same bulk change keeps coming back, such as "every Monday, set the resolution on Done items that have none", don't run it by hand. Use Jira Automation:

In Space settings > Automation (or global automation for several spaces), create a rule with the Scheduled trigger.
Turn on the option to run a JQL search and act on each work item it finds, and paste your query.
Add an action such as Edit work item, Transition work item or Assign work item.
Turn the rule on and check its audit log after the first run.

Automation rules count toward your plan's automation usage, so very frequent rules over large searches are worth a second look. For logic a rule can't express, a Script Toolkit scheduled job runs your own JavaScript on a cron schedule.

A safe bulk change checklist

Write the JQL first, read the count, and open a few results.
Save the query as a filter so you know exactly what was changed.
Turn off email if the change is housekeeping that nobody needs to hear about.
For transitions, check which workflows are involved and what fields each transition requires.
Split anything over 1,000 work items (or 5,000 with Script Toolkit) into smaller searches.
Afterwards, check a few work items and the reports that depend on them. If you track flow metrics such as time in status, a mass transition will show up there, so note the date. Our guide to Jira reporting for product managers covers which reports are most affected by missing resolutions and stale statuses, and the Jira reporting dashboards setup shows how to keep an eye on them.

Frequently asked questions

How do I bulk edit in Jira Cloud?

Search for the work items, then select More actions (•••) > Bulk change all work items, choose Edit, tick the fields to change, give them values and confirm. You need the global Make bulk changes permission.

Why can't I see the bulk change option?

You probably don't have the global Make bulk changes permission. Ask a Jira admin to grant it, or to open a bulk tool to your group in an app such as Script Toolkit for Jira.

How many work items can I bulk change at once?

Up to 1,000 work items in one bulk change in Jira Cloud. Split larger searches into batches. Script Toolkit's tools run on up to 5,000 work items per run.

Can I undo a bulk change in Jira?

No. Each work item's history records what changed, but there is no button to reverse a bulk change. Save the search as a filter and check the result count before you confirm.

How do I bulk delete work items in Jira?

Use the same wizard and choose Delete. You need the Delete work items permission in each space as well as the global bulk permission. Deleted work items are gone for good, so consider transitioning them to a closed status instead.

Can I stop Jira from emailing everyone during a bulk change?

Yes. In the operation details step, untick Send mail for this update.

Try it

Next time someone asks you to "just close all of these", start with the JQL, then the bulk change wizard. If the people who need bulk edits shouldn't get the global permission, install Script Toolkit for Jira, free on the Atlassian Marketplace, and open the tools they need to their group. The tools guide takes a few minutes to set up.

Reusable components and brand tokens for Confluence HTML

Yamuno — Fri, 30 Oct 2026 11:26:38 +0000

Reusable components and brand tokens for Confluence HTML

Short answer: HTML Macro+ for Confluence 7.0 adds a library: shared variables, reusable components and brand tokens that every HTML macro on your site can use. An admin writes a footer, a banner or a brand colour once, and every page that uses it picks up the change on its next view. With this release HTML Macro+ also becomes a paid app for sites with more than 10 users. It stays free for sites with up to 10 users, and until 28 February 2027 there's 25% off monthly and annual subscriptions.

This post covers what the library does, how teams use it, and what the pricing change means for sites that already have the app.

The problem the library solves

Once a team starts using HTML on Confluence pages, the same pieces turn up again and again: a page footer with the owner and review date, a status notice, a release banner, a contact card. Each copy lives inside its own macro. When the brand colour changes or the support link moves, someone has to find and edit every page by hand, and a few always get missed.

The library moves those shared pieces into one place in the app's settings. Pages refer to them by name instead of carrying their own copy. There are three parts:

Part	What it holds	How a macro uses it
Variables	Named values such as a company name, a support link or a release number	`{{companyName}}` in HTML and CSS, `window.HTMLMacro.vars.companyName` in JavaScript
Components	Reusable HTML, CSS and JavaScript, such as banners, footers and cards	A tag such as `<ReleaseBanner />`
Brand	Colours, fonts, shape, logo, images and your own design tokens	CSS custom properties such as `var(--brand-primary)`, and `{{brand.logo}}` for images

Only Confluence admins can change the library. Page editors use it from the macro editor but can't add, change or delete items. See the library documentation for where to find it in the app's settings.

Variables: write a value once

A variable is a named value you would otherwise repeat on many pages. Use it in HTML or CSS with double braces:

<p>Questions? Contact {{supportEmail}} or see {{companyName}}'s help centre.</p>

In JavaScript, read the same value from window.HTMLMacro.vars.supportEmail.

A few things make variables safe to use widely:

Built-ins cover common cases with no setup: {{today}} for today's date in the reader's language, {{page.title}} for the page's title and {{space.key}} for its space.
Values are escaped before they reach the page, so a value can't inject markup into a macro.
Unknown placeholders are left as written, and the editor warns about them, so a typo is easy to spot.
Variables in use can't be deleted. The library settings show which pages use each one.

When a value changes, every page that uses it shows the new value the next time it's viewed. No one has to edit or republish the pages. See Variables for names, types and limits.

Components: build a block once, use it everywhere

A component is a reusable piece of HTML, CSS and JavaScript. An admin builds it once in the library, and anyone writing a macro adds it with a single tag:

<ReleaseBanner title="Version 5" />

Each component can have settings (props) of type text, number, colour, link or a list of options, with a label, help text and a default. Inside the component, a setting is {{title}} in HTML and CSS and HTMLMacro.props.title in JavaScript. A component's CSS applies only to that component, so its styles never leak into the rest of the macro.

Components are built for teams that maintain them over time:

Drafts and publishing. Save a draft without touching any page, then publish when it's ready. Every page that uses the component shows the published version on its next view.
Version history for each component.
Nesting up to 3 levels deep, so a project status card can include a contact card.
Starters for a page footer, document control, status notice, release banner, contact card, project status, FAQ and project roadmap. Set up a starter kit creates all of them in one go, along with the variables they read.
Save as component. If someone has already built something useful in a macro, an admin can turn it into a component from the editor's More menu and choose which placeholders become settings.

In the macro editor, the new Components button opens a picker with search, group filters, a live preview and a form for the component's settings. Add to my code inserts the tag at the cursor, and typing < in the HTML tab suggests component tags. See Components for the full guide and limits.

Brand: one set of tokens for every macro

The Brand section holds your colours, fonts, shape settings, logo and images, plus your own design-system tokens. Macros read them as CSS custom properties:

.notice {
  background: var(--brand-primary);
  color: #fff;
}

What it includes:

Dark mode values. Each token can have a separate dark mode value, and macros use the right one for the reader's Confluence theme. See Supporting dark mode.
Fonts from Google Fonts or your own font stylesheet. A font only loads on pages whose code uses it.
Images in PNG, JPEG, WebP, GIF or SVG, used as {{brand.logo}} and similar names.
Token import and Copy as CSS. Paste CSS custom properties or a tokens JSON file to add many tokens at once, and copy them all back out as CSS. Up to 500 tokens.

Together with components, this is what makes a branded Confluence knowledge base practical: the branded knowledge hub use case walks through a setup. See Brand for details.

Groups and the editor menus

Groups, such as Company, IT or HR, sort variables and components into sections in the settings and in the editor's menus, so people can find the right item on a site with many of them. The macro editor header now has Variables and Components buttons, and a More menu with Save as component (admins only), Embed templates, Copy AI prompt, Documentation and Support. See the HTML editor guide and the release notes for everything in 7.0.

New pricing

From version 7.0, HTML Macro+ is a paid app for sites with more than 10 users:

Free for sites with up to 10 users, with every feature included.
Larger sites subscribe monthly or annually through Atlassian, from $0.30 per user per month for 11 to 100 users and less per user on bigger sites. The licensing page has the full table.
A free 1-month trial through the Atlassian Marketplace, with every feature.
Launch offer: until 28 February 2027, 25% off monthly and annual subscriptions. Request the code, then enter it in Atlassian Administration when you subscribe, or later under Billing.

Pages always keep showing their content, licensed or not. Without a subscription or trial, macros still render with a short notice above them, the editor opens but can't save, and the app's settings show how to start the trial.

If you already have the app

A site admin approves the paid update once:

Go to admin.atlassian.com, choose your site, then Site settings → Connected apps.
Find HTML Macro+ for Confluence, which shows a Paid update tag, and select View app details.
Select Paid update, then start the free trial or subscribe.

Sites with up to 10 users go through the same steps and take the subscription at no charge. Update to the paid version has the steps with more detail.

Frequently asked questions

Is HTML Macro+ still free?

It is free for sites with up to 10 users, with every feature included. Larger sites subscribe monthly or annually through Atlassian after a free 1-month trial.

Is there a discount?

Yes. Until 28 February 2027 there's 25% off monthly and annual subscriptions. Request the code and enter it in Atlassian Administration when you subscribe, or later under Billing.

Will our pages stop working if we don't subscribe?

No. Pages keep showing their content. Without a subscription or trial, macros show a short notice that the app requires a valid license, and saving in the editor is turned off until an admin subscribes or starts the trial.

Who can change the library?

Only Confluence admins, from the app's settings. Page editors can insert variables and components from the macro editor but can't add, change or delete them.

Do pages update when a component changes?

Yes, once it's published. Drafts don't affect any page. After you publish, every page that uses the component shows the new version on its next view, with no need to edit the pages.

Can components use our brand colours and fonts?

Yes. Components and macros read brand tokens as CSS custom properties such as var(--brand-primary), with separate dark mode values where you set them.

Try it

Start with Set up a starter kit in the library to get a footer, banner, status notice and more in one step, then open the Components picker in any macro. For ideas, see 5 things you can build with HTML Macro+ and how to build a status dashboard in Confluence.

Get HTML Macro+ for Confluence on the Atlassian Marketplace

Does Confluence Support Mermaid? 3 Ways to Add Diagrams

Yamuno — Fri, 30 Oct 2026 11:26:26 +0000

Does Confluence Support Mermaid? 3 Ways to Add Diagrams

Short answer: Confluence Cloud doesn't render Mermaid on its own. Paste a Mermaid diagram into a page and you get a code block with the source in it, not a diagram. To draw it, add an app: a Mermaid macro such as Mermaid Diagram for Confluence, a Markdown macro that understands Mermaid, or an importer that turns the mermaid blocks in your .md files into diagrams as it creates the pages.

Mermaid is the diagram language developers already use. GitHub and GitLab draw it in READMEs, most docs-site generators support it, and a flowchart written as ten lines of text is easier to review and change than an image exported from a drawing tool. So when docs move into Confluence, the first question is usually what happens to the diagrams.

This guide covers the three routes and which one fits which job.

What Confluence does with Mermaid out of the box

Confluence's code block can be set to many languages, but Mermaid source in a code block stays as source. The editor has no Mermaid macro of its own, and the Markdown shortcuts it understands while you type don't include diagrams.

That leaves teams with three habits, none of them good:

Screenshots. Someone renders the diagram elsewhere and uploads a PNG. It looks right until the process changes, and then nobody has the source.
Code only. The Mermaid stays as a code block and readers are expected to picture it.
Link out. The page links to a diagram in a repository or the Mermaid Live Editor, which readers may not be able to open.

Each route below keeps the diagram as text inside Confluence and draws it on the page.

Option 1: A Mermaid macro

Best for: diagrams you draw and maintain in Confluence itself.

Mermaid Diagram for Confluence is a free app that adds a Mermaid Diagram macro. You write Mermaid on the left and the diagram updates on the right as you type.

Edit a page, type /mermaid and choose Mermaid Diagram.
Write a diagram, or click Templates and start from one of the 12 templates (flowchart, sequence, class, state, ER, Gantt, pie, mind map, timeline, user journey, Git graph and quadrant).
Click Save diagram and publish the page.

flowchart LR
    A[Pull request] --> B{Checks pass?}
    B -- Yes --> C[Merge]
    B -- No --> D[Fix and push]
    D --> B

Because the app is built only for diagrams, it goes further than drawing them:

Page trees. Insert a diagram of a page and the pages under it, as a flowchart or a mind map, where every box opens its page. See Page tree.
Links to pages. Right-click a flowchart box and link it to a Confluence page.
Colour themes. Admins create named themes with your brand colours, each with a dark-mode version, and every editor can pick them. See Colour themes.
Readers' tools. Zoom, full screen, the code view and a high-resolution PNG download sit under each published diagram.
Exports. PDF export uses a light-colour image of the diagram, and Word export includes the Mermaid code.

The app runs on Atlassian Forge and keeps diagrams in the app's Forge storage for your site, so nothing is sent to an outside server. If your team also uses Jira, Mermaid Diagrams for Jira draws the mermaid code blocks in issue descriptions and comments.

Option 2: Mermaid inside a Markdown macro

Best for: pages you already write in Markdown, where the diagram sits between headings, tables and code.

Markdown Macro+ for Confluence renders Mermaid inside its Markdown editor. You write a fenced code block with mermaid as the language, and the macro draws it in the preview and on the published page.

Type /markdown on a page and insert Markdown Macro+.
Start a fenced code block marked mermaid, write the diagram and close the block.
Check the preview, save the macro and publish.

## Deploy flow

Every merge to main runs the same pipeline:

```mermaid
sequenceDiagram
    participant Dev
    participant CI
    participant Prod
    Dev->>CI: Merge to main
    CI->>CI: Build and test
    CI->>Prod: Deploy
```

If the deploy fails, CI rolls back to the last good release.

The diagram is one block in the page, so a runbook can open with a flowchart of the process and follow it with the commands for each step. The same mermaid block you have in a README works here unchanged. More examples are in the Mermaid diagrams guide, and Confluence wiki markup vs Markdown explains where Markdown fits in Confluence in general.

Option 3: Import Markdown files with Mermaid in them

Best for: an existing docs folder or repository, with diagrams already written.

If your diagrams live in .md files, adding them one by one is the slow way. Markdown Importer for Confluence imports a single file, many files or a ZIP of folders as a page tree, and it can turn every mermaid code block it finds into a diagram on the new page.

A Confluence admin sets it once for the site:

Go to Confluence Settings and, under Apps, select Markdown Importer for Confluence.
Open the Import settings tab.
Under Mermaid diagrams, choose an option. It saves straight away.

Option	What each `mermaid` block becomes
Keep as code blocks (default)	A code block with the diagram source
Render with Mermaid Diagrams	A Mermaid Diagram macro, drawn on the page and editable in its live editor (needs Mermaid Diagram for Confluence)
Render with Markdown Macro+	A Markdown Macro+ macro that draws the diagram (needs Markdown Macro+)

Then import as usual: open a page's ••• menu, choose Markdown Importer & Exporter, pick your files or a ZIP, preview and click Import. The setting also applies to imports through the importer's REST API, so a CI job that publishes docs on every merge gets diagrams too. How to sync GitHub docs to Confluence automatically walks through that setup.

A few things to know before a big import:

Install the app you choose first. If it isn't installed, pages show Confluence's placeholder for a missing app instead of the diagram.
Top-level diagrams only. Confluence doesn't allow macros in every place, so diagrams inside lists, quotes or tables stay as code blocks.
New imports only. Changing the setting doesn't touch pages you imported earlier.
Government Cloud sites only offer Keep as code blocks for now.

The full reference is in the importer's Mermaid diagrams docs. For the import itself, see How to import Markdown into Confluence or, for a whole repository, Migrate GitHub and GitLab docs to Confluence.

Which one should you use?

You want to	Use
Draw and maintain diagrams in Confluence, with templates, page trees and brand colours	Mermaid Diagram for Confluence
Keep diagrams inside Markdown pages, next to text, tables and code	Markdown Macro+
Bring a docs folder or repository across with its diagrams drawn	Markdown Importer, set to one of the two above

The routes work together. A common setup is Markdown Importer set to Render with Mermaid Diagrams for the migration, then the Mermaid macro for new diagrams, so every diagram on the site has the same editor and the same colour themes. Teams that keep their docs in Markdown on both sides pick Markdown Macro+ instead, and can export pages back to .md later; see Confluence to Markdown: 4 ways to export.

Frequently asked questions

Does Confluence Cloud support Mermaid natively?

No. Confluence Cloud has no built-in Mermaid macro, and a Mermaid diagram pasted into a page stays as code. An app from the Atlassian Marketplace is needed to draw it.

Is there a free Mermaid app for Confluence?

Yes. Mermaid Diagram for Confluence is free on the Atlassian Marketplace and runs on Atlassian Forge.

Which Mermaid diagram types work in Confluence?

With Mermaid Diagram for Confluence, every type Mermaid supports, including flowcharts, sequence, class, state, entity relationship, Gantt, pie, mind map, timeline, user journey, Git graph and quadrant charts.

Can I import a README with Mermaid diagrams into Confluence?

Yes. Markdown Importer for Confluence imports the README as a page. Set its Mermaid option to Render with Mermaid Diagrams or Render with Markdown Macro+ first, and each top-level mermaid block becomes a diagram instead of code.

Do Mermaid diagrams show up in Confluence PDF exports?

With Mermaid Diagram for Confluence, yes: PDF export uses a light-colour image of the diagram, and Word export includes the Mermaid code.

Can I edit an imported diagram later?

Yes. A diagram imported with the Mermaid Diagrams option is a normal Mermaid Diagram macro, so anyone who can edit the page can open it in the live editor and change it.

Try it

Install Mermaid Diagram for Confluence from the Atlassian Marketplace, type /mermaid on a page and start from a template. If your diagrams are already in Markdown files, add Markdown Importer for Confluence and set its Mermaid option before you import. The Mermaid Diagram docs and the quick start cover the rest.

Confluence Documentation Best Practices for Findability

Yamuno — Thu, 29 Oct 2026 15:00:26 +0000

Confluence Documentation Best Practices for Findability

Short answer: Atlassian's 2026 State of Developer Experience report puts "finding information" at the top of the list of things that slow developers down, ahead of meetings. In Confluence, most of that friction comes from duplicate pages, vague titles, pages nobody owns, and copies of repo docs that drifted. Five habits fix most of it: one home per topic, titles that match how people search, an owner and review date on every page, archiving what is stale, and keeping repo docs and Confluence in sync.

What the 2026 developer experience report says

On October 20, 2026, Atlassian published a summary of its 2026 State of Developer Experience report. The headline numbers:

87% of developers say AI helps them ship work faster.
72% experience the same or more friction than before AI.
65% now regularly spend time correcting AI output.
The top sources of friction, in order: finding information, meetings, context switching, technical debt and unclear requirements. The write-up says finding information "takes top spot again in 2026".
Only 17% of developers and 23% of leaders say their organisation has a clearly communicated and implemented AI strategy. Developers at those organisations are twice as likely to report less friction than before AI.

The part that matters for anyone who runs a Confluence site is the ranking. Finding information beat meetings as a source of friction. That is a documentation problem, and most of it can be fixed without buying anything.

Why faster AI did not make docs easier to find

AI tools speed up writing code. They do not decide which of three "Deployment process" pages is the current one. An assistant that searches or summarises your Confluence site reads the same duplicates, stale runbooks and half-finished drafts a person would, and it can repeat an outdated answer with more confidence than a person would.

So the order of work matters. A tidy, well-labelled space makes both people and search tools better. A messy one makes both worse, and the report's 65% figure on correcting AI output is partly a measure of how much bad source material is out there.

Where your documentation actually lives

Before changing anything in Confluence, list where docs live today. In most engineering teams it is some mix of:

Confluence spaces: onboarding, architecture, runbooks, postmortems, decisions.
The repository: READMEs, docs/ folders, API specs, ADRs written in Markdown.
Jira: requirements and context buried in issue descriptions and comments.
Chat: answers given once in a thread and never written down.

Findability breaks at the seams between these. A developer searches Confluence, finds a page that was copied from a README a year ago, and does not know the README has changed since. The fix is not to force everything into one tool. It is to decide which tool is the source for each kind of doc, and make the others point to it. Our technical documentation use case shows one way to split it.

Five habits that make Confluence docs findable

One home per topic

Duplicate pages are the biggest single cause of "which one is right?". Pick one page as the home for each topic (a service, a process, a decision) and turn the others into short pointers or archive them.

A structure that helps: organise spaces around teams or services rather than projects, because projects end and their pages become orphans. Our guide to using Confluence as a developer wiki has a full example tree. When someone is about to create a page, the question to ask is "where would I look for this?", not "where am I right now?".

Titles that match how people search

People search for "payments service runbook" or "how to rotate the API key", not "Q3 platform notes v2". Write titles that:

Start with the thing, then the type: "auth-service: runbook", "Billing API: authentication".
Use the words your team says out loud, including product and service names.
Avoid dates and version numbers unless the page really is a dated record (a postmortem, a release note).

The first line under the title matters too. A one-sentence summary of what the page covers and who it is for shows up in search results and tells a reader in seconds whether they are in the right place. For API pages, see how to document APIs in Confluence.

An owner and a review date on every page

Confluence Cloud already tracks a page owner, shown in the page details. On Premium and Enterprise, admins can use the content manager to find pages whose owner has left and change the owner in bulk. Whatever your plan, make ownership visible on the page itself.

A simple pattern: put a small table at the top of every important page inside a Page Properties macro, with three rows:

Owner	Last reviewed	Status
@name	2026-10-15	current

Then add a Page Properties Report macro to the space home page. It collects those tables from every page with a given label into one list, so you can sort by "Last reviewed" and see what is overdue. A review every six months suits most reference pages; runbooks and onboarding pages are worth checking every quarter.

Archive or label what is stale

Stale pages are worse than missing pages, because they look trustworthy. Confluence Cloud lets you archive a page from its more actions menu on Standard, Premium and Enterprise, and Premium and Enterprise add bulk archiving. Archived pages keep their permissions and leave everyday search results, but they can be restored if someone needs them.

Use labels for the cases in between. A current label on maintained pages and a needs-review label on pages you are unsure about make it easy to build a "Content by label" list or a search filter. If old attachments are part of the clutter, Confluence storage cleanup covers how to audit them safely.

Keep repo docs and Confluence in sync

If a doc lives in the repository, it should be written there and published to Confluence, not maintained twice. Engineers update Markdown in the same pull request that changes the code, so the repo copy stays right. The Confluence copy is where product, support and new hires find it.

Markdown Importer for Confluence Cloud handles both the first move and the ongoing sync:

First move: import a single .md file, many files or a ZIP. Folders become parent pages, so a docs/ folder becomes a page tree, and local images are uploaded with the pages. See how to bulk import Markdown into Confluence.
Ongoing sync: a REST API that creates or updates one page per request, with Bearer tokens that expire after 1 to 30 days. A GitHub Actions workflow can send changed files on every merge to main. The step-by-step setup is in how to sync GitHub docs to Confluence automatically, and the Markdown Importer docs cover the API.

Add a line at the top of each synced page saying "Edit this in the repo" with a link, so nobody fixes the Confluence copy by hand and loses the change on the next sync. If you need the opposite direction, Markdown Exporter exports pages, page trees or whole spaces to Markdown; Confluence Markdown export for docs as code explains when that is worth doing.

A 30-minute findability audit

Pick your busiest engineering space and run this with a timer.

Ten searches (10 minutes). Write down ten questions new joiners asked in the last month. Search for each in Confluence. Note whether the right page was in the top three results, and how many competing pages came up.
Stale pages (5 minutes). In search, filter the space by "Last updated" and look at pages untouched for over a year. Mark each as keep, update or archive. Admins on Premium or Enterprise can use the content manager's "Last active" filter in space settings instead.
Owners (5 minutes). Open the ten most-viewed pages. Does each have a named, current owner? Note the ones that do not.
Duplicates (5 minutes). For the topics where search returned two or more candidates, pick the home page and list the others to merge or archive.
Repo drift (5 minutes). For three pages that started life as repo docs, compare them with the current Markdown in the repository. If they differ, that topic is a candidate for automated sync.

You end with a short list: pages to archive, pages that need owners, duplicates to merge and docs to sync. That list is usually enough work for one sprint.

What to measure next quarter

You do not need a dashboard to tell whether this worked. Re-run the same ten searches in three months and track:

Search hit rate: how many of the ten questions return the right page in the top three.
Pages with an owner and a review date in the last six months, as a share of the space.
Duplicates per topic for the topics you merged.
Repo-synced pages that match the repo, if you set up the sync.

If you want a people measure, ask new joiners in their first month how often they could not find something. It is the same question the Atlassian report asked, at the size of your team.

Frequently asked questions

What does the 2026 State of Developer Experience report say about documentation?

It does not mention documentation by name. It ranks "finding information" as the top source of developer friction for 2026, ahead of meetings, context switching, technical debt and unclear requirements. It also reports that 87% of developers say AI helps them ship faster, while 72% experience the same or more friction than before.

How do I find stale pages in Confluence?

Use the "Last updated" filter in Confluence search to list pages in a space that have not changed for a year or more. On Premium and Enterprise, space admins can also open space settings, choose the content manager and filter by "Last active". Review the list before archiving, because some old pages, such as decision records, are meant to stay unchanged.

Should engineering docs live in Confluence or in the repo?

Docs that change with the code, such as READMEs, API references and setup steps, are easiest to keep correct in the repo. Docs that other teams read, such as runbooks, onboarding guides and architecture overviews, are easier to find in Confluence. Many teams write in the repo and publish to Confluence automatically, so both audiences get the same content.

How often should Confluence pages be reviewed?

Every six months suits most reference pages. Runbooks, onboarding pages and anything tied to a fast-changing system are worth checking every quarter. Record the date on the page so anyone can see when it was last checked.

Does Confluence have page owners?

Yes. Confluence Cloud shows a page owner in the page details. On Premium and Enterprise, admins can find pages whose owners are no longer active and change the owner in bulk from the content manager. Many teams also add an Owner row to a Page Properties table so the owner is visible at the top of the page.

How do I stop duplicate pages in Confluence?

Give each topic one home page, organise spaces around teams or services, and use titles that match how people search, so the existing page shows up before someone creates a new one. When duplicates appear, merge the content into the home page and archive the rest.

Try it

Run the 30-minute audit on one space this week. If repo docs drifting out of date is on your list, Markdown Importer for Confluence Cloud can import your docs/ folder as a page tree and keep it in sync from GitHub Actions. The quick start takes a few minutes.

Time in Status in Jira: How to Measure It

Yamuno — Tue, 27 Oct 2026 11:28:15 +0000

Time in Status in Jira: How to Measure It

Short answer: Jira records every status change in each issue's history, but Jira Cloud has no built-in report that adds those changes up into time per status for a set of issues. You can read it one issue at a time in the History tab, or approximate it for a board with the Control chart. For a whole project, sprint or JQL search, use an app that reads the changelog and totals the time for you, such as Issue History+ for Jira.

"How long does work sit in review?" sounds like a question Jira should answer in one click. The data is there: every time an issue moves from one status to another, Jira writes a changelog entry with the old status, the new status, who moved it and when. What is missing is the arithmetic across many issues.

This guide covers what time in status means, what Jira Cloud gives you natively, how to read the numbers without being misled, and how to get a report for a whole project.

What time in status means

Time in status is how long an issue stays in a workflow status before it moves on. For a single issue it is simple: the issue entered In Review on Monday at 10:00 and left on Wednesday at 16:00, so it spent two days and six hours in review.

Three details make it less simple in practice:

Repeat visits. An issue can go In Progress, In Review, back to In Progress, then In Review again. Each stay is a separate visit, and the issue's total time in review is the sum of both.
The first status. The first status has no "entered" change in the history. It starts when the issue is created.
Calendar time or working time. An issue that enters a status on Friday evening and leaves on Monday morning spent most of a weekend there. Whether that counts depends on what you are measuring.

Across many issues, time in status tells you where work waits. If issues spend a day in development and four days in review, the review step is the bottleneck, whatever the team's velocity says.

What Jira Cloud shows out of the box

Jira gives you several partial views. Each one is useful, and each one stops short of a report you can run for any set of issues.

The History tab on each issue

Open an issue, scroll to Activity and choose History. You see every field change, including each status transition with its timestamp. You can work out time in each status by hand.

That works for one issue. For fifty issues it means fifty tabs and a spreadsheet.

The Control chart

On a company-managed Jira Software board, Reports > Control chart plots cycle time for issues across the board columns you select. It shows the trend and outliers well.

It is tied to a board and its columns rather than to statuses, it is not available in every project type, and it does not give you a per-issue table of time in each status that you can share or export.

Days in column on cards

Boards can show a small indicator of how long a card has been in its current column. It tells you an issue is sitting still now. It does not tell you where the time went before that, or how long the column usually takes.

JQL

JQL can find issues by their status history:

status CHANGED FROM "In Progress" TO "In Review" DURING ("2026-09-01", "2026-09-30")

status WAS "Blocked" ON "2026-10-01"

These are good for finding issues, for example everything that passed through Blocked last month. JQL returns issues, not durations, so it cannot tell you how long anything stayed in a status.

The changelog API

If you are comfortable with scripts, GET /rest/api/3/issue/{issueIdOrKey}/changelog returns the full, paginated history of an issue. You can fetch it for every issue in a search, walk the status changes and total the time per status yourself. Many teams do exactly this in a spreadsheet or notebook, and then maintain the script.

How to read time in status

Once you have the numbers, the way you summarise them matters more than the tool.

Use the median, not the average

Time in status is almost always skewed. Most issues pass through review in a day or two, and one issue that waited three weeks for a decision pulls the average up for everyone. The median is the typical visit: half the visits were shorter, half longer. It moves when the process changes, not when one issue gets stuck.

Add the 85th percentile

The median hides the slow tail. The 85th percentile answers a question people actually ask: "How long will this probably take?" If 85% of visits to In Review finish within three days, that is a fair expectation to give a stakeholder, and anything well beyond it is worth a look.

Count visits

A status with a short median but many visits per issue is a sign of rework. Issues bouncing between In Progress and In Review three times are not waiting long each time, but they are coming back.

Decide on business hours

If your team works weekdays, calendar time makes anything that crosses a weekend look slow. Business hours count only the working day. Pick one and use it consistently, especially when comparing teams.

Set SLAs per status

For support or operations work, a target per status is often more useful than a trend: "nothing should sit in Waiting for triage for more than 8 working hours." Then the report is a list of breaches rather than a chart to interpret.

Step by step: time in status for a whole project

Issue History+ for Jira reads the same changelog Jira already keeps and does the totals for any set of issues. It runs on Atlassian Forge with no external servers, and every request runs with the viewing user's Jira permissions.

Open Apps > Issue History. Choose a project, a sprint, an assignee, labels, a JQL query or a list of issue keys, and a date range. Click Search.
Open the Time in Status tab. Each status has a card with its median time per visit, the time 85% of visits finish within, and the number of visits. Below is a table with one row per issue and one column per status, in workflow order.
Sort by the slowest status. Click a status column header to see the issues that spent longest there, or Total for the longest-running issues overall.
Switch to business hours if you need them. In Settings > Analysis, choose business hours, set the working day, and decide whether weekends count.
Add SLA thresholds. In the same settings, pick a status and the maximum hours an issue should spend in it. Breaching cells are marked in the table, and a status card turns red when its typical visit is over the limit.
Check the Status Timeline tab. Each issue's path through the workflow appears as one bar, coloured by status category, so repeat visits and long waits are visible at a glance.
Export. Download CSV or Excel for further analysis, or a branded PDF with your company name and logo for people who don't use Jira.

The time in status documentation explains exactly how visits, medians and SLAs are calculated. The quick start walks through a first search.

Custom workflows work as they are. The app uses each status's Jira category (To Do, In Progress, Done), so statuses like Shipped or Won't Fix count correctly.

Three questions time in status answers

What is stuck right now?

The Insights tab has an Inactive work list: issues that are not done and have had no status change for 7, 14 or 30 days. It is a short list to bring to stand-up instead of scanning the board for old cards.

Where are we missing our targets?

With SLA thresholds set, Insights counts the issues over SLA and lists the worst overruns first. Excel and PDF exports include the SLA and the number of issues over it, which is usually what a service review needs.

How much work comes back?

Insights also shows reopened issues (anything that left Done at least once) and rework, the share of status moves that go back to an earlier category. Together with median cycle time and weekly throughput, they show whether work is flowing or circling. The Insights documentation defines each metric.

For a single issue, you don't need to leave it: an Issue Insights tab in the issue's Activity section shows its time in status, its status timeline and every change.

If you also report on Jira through dashboards, our guide to Jira reporting for product managers and building a Jira dashboard that tells you something cover the other half: where issues are now, rather than how long they took to get there.

Frequently asked questions

Does Jira Cloud have a built-in time in status report?

Not as a report for any set of issues. Jira records every status change in the issue history, and company-managed boards have a Control chart for cycle time across columns, but there is no native table of time per status per issue for a project, sprint or JQL search.

How is time in status calculated?

From the moment an issue enters a status until it leaves it. The first status starts at the issue's creation date. If an issue visits the same status more than once, each visit is measured separately and the issue's total is the sum.

Should I use the average or the median?

The median. One issue stuck for weeks can double an average, while the median shows the typical visit. Add the 85th percentile to see how long most visits take, including the slower ones.

Can I measure time in status in business hours?

In Issue History+ for Jira, yes: choose business hours in Settings > Analysis, set the working day and choose whether weekends count. Business hours use each viewer's local time zone, so use calendar time when comparing figures across time zones.

Does it work with custom statuses and workflows?

Yes. Issue History+ uses each status's Jira category, so any custom status counts correctly for time in status, cycle time and completion. It reads the standard changelog, which both company-managed and team-managed projects record.

Does my Jira data leave Atlassian?

No. Issue History+ runs entirely on Atlassian Forge and declares no egress. It stores only each user's saved searches and settings, in Forge storage. The data and privacy page lists exactly what it reads and stores.

Try it

Issue History+ for Jira is on the Atlassian Marketplace for Jira Cloud. Install it, open Apps > Issue History, pick a project and open the Time in Status tab. You will see where your work waits in the time it takes to run one search.

Confluence to Markdown: 4 Ways to Export, Compared

Yamuno — Mon, 26 Oct 2026 12:42:57 +0000

Confluence to Markdown: 4 Ways to Export, Compared

Short answer: Confluence Cloud can export pages to PDF and Word, and spaces to HTML, XML, CSV or PDF, but not to Markdown. For one page, you can copy the content into a Markdown editor or convert the HTML with Pandoc. For page trees, whole spaces or regular exports, use a Confluence Markdown exporter app such as the free Markdown Exporter for Confluence, which keeps the hierarchy, attachments and links between pages.

Teams want Markdown out of Confluence for a few reasons: moving docs into a Git repository, publishing with a static site generator, building an Obsidian vault, feeding documentation to AI tools, or keeping a plain-text backup that doesn't depend on any one vendor. Each method below gets you .md files. They differ in how much of the page survives and how much work it takes.

What Confluence exports on its own

Before reaching for a tool, it helps to know what Confluence Cloud gives you:

Export	Where	Formats
One page	••• menu on the page, Export	PDF, Word
A whole space	Space settings, Export space	HTML, XML, CSV, PDF

None of these is Markdown. The space HTML export is the closest starting point, because HTML converts to Markdown reasonably well, but it is a space admin task, it exports everything in the space, and the conversion is still on you. If you are curious how Confluence's own markup relates to Markdown, see Confluence wiki markup vs Markdown.

Option 1: Copy and paste

Open the page, select the content, and paste it into an editor that converts rich text to Markdown (many Markdown editors and note apps do this on paste).

Keeps: headings, bold and italic, simple lists, links.

Loses: images (they paste as links to Confluence, which need a login), tables with merged cells, panels, code block languages, and the page hierarchy. Links to other Confluence pages still point at Confluence.

Use it for: one or two short pages, once.

Option 2: The REST API and Pandoc

For a scripted export without an app, fetch the page body with the Confluence REST API and convert it.

Create an API token for your Atlassian account.
Fetch a page's rendered HTML:

curl -s -u you@example.com:$API_TOKEN \
  "https://your-site.atlassian.net/wiki/api/v2/pages/123456?body-format=export_view" \
  | jq -r '.body.export_view.value' > page.html

Convert it to GitHub-flavored Markdown:

pandoc -f html -t gfm page.html -o page.md

To export a page tree, list the children with /wiki/api/v2/pages/{id}/children, repeat for each page, and build the folders yourself.

Keeps: text, headings, lists, simple tables, code blocks.

Loses or needs extra code: attachments and images (a separate download per file, then rewriting the image links), links between pages (they still point at Confluence URLs), panels and other macros (they come out as raw HTML or vanish), and any front matter you want.

Use it for: developers who want full control and don't mind maintaining a script. Budget time for the edge cases; they are most of the work.

Option 3: Markdown Exporter for Confluence

Markdown Exporter for Confluence is a free app built only for export. It runs on Atlassian Forge, so your content never leaves Atlassian.

Open it from any page's ••• menu with Export to Markdown, or from Apps → Markdown Exporter to start from a space. Tick the pages you want in the page tree (ticking a parent selects its children) and click Export Selected.

What you get:

A ZIP that mirrors the page tree, with one .md file per page, or every page in one Markdown file if you prefer a single document
Attachments in an attachments/ folder, linked with relative paths so images still show after you unzip
Links between pages rewritten as relative .md paths, or as [[wikilinks]] in Obsidian mode
YAML front matter with title, author, date, space key and page ID, plus your own fields, ready for static site generators
Panels as callouts such as > [!NOTE], or as blockquotes or plain text
Filename patterns with {title}, {date} and {id}
A Markdown preview of any page before you export

For bigger jobs, released on 26 October 2026:

Background exports. Exports over 100 pages or 100 attachments run on Atlassian's servers, so you can close the page and download the result later from My exports. One export can include up to 2,000 pages.
Scheduled exports. Export a space or page tree every week or every month. Each run attaches a dated ZIP or .md file to an archive page, or keeps it in My exports, and can @mention people so Confluence emails them. That makes a regular Markdown backup of a space a one-time setup.
Export API. Start an export from a CI pipeline or script with one HTTP request and an API token, and attach the result to a page. There is also an OAuth REST API that returns Markdown directly, which suits docs-as-code workflows.

Use it for: page trees and whole spaces, moving docs to Git or a static site, Obsidian, and any export you want to repeat.

Option 4: Markdown Importer's built-in export

If your team also brings Markdown into Confluence, Markdown Importer for Confluence does both directions in one app. Its Export to Markdown action exports a single page, a page with its children, or a whole space as a ZIP, with the hierarchy kept as folders and attachments linked by relative paths.

It doesn't have the front matter, Obsidian mode, filename patterns, schedules or APIs of the standalone exporter, so pick it when two-way sync matters more than export options. The step-by-step export guide walks through it.

Side by side

	Copy and paste	REST API + Pandoc	Markdown Exporter	Markdown Importer export
Price	Free	Free, your time	Free	Paid, free up to 10 users
Page trees and spaces	No	With your own script	Yes	Yes
Images and attachments	No	Extra code	Yes, relative links	Yes, relative links
Links between pages	Point at Confluence	Point at Confluence	Relative `.md` or wikilinks	Relative links
Panels	Lost	Raw HTML	Callouts, blockquotes or text	GitHub callouts
YAML front matter	No	Your own code	Yes	No
One combined .md file	Yes	Your own code	Yes	No
Schedules	No	Your own cron job	Weekly or monthly	No
Automation	No	Yes	REST API and Export API	No

Choosing a Confluence Markdown exporter

Whichever tool you pick, test it on one real page tree before a big move, and check:

Do images survive? Unzip the export somewhere without a Confluence login and open a page with screenshots.
Do links between pages work offline? They should point at other .md files, not at Confluence URLs.
What happens to macros? Panels, expand sections, status labels and code blocks are where exports differ most.
Does it scale? Try your largest space, not your smallest.
Where does the content go? An app that runs on Atlassian Forge keeps the export inside Atlassian; an externally hosted app sends your pages to its own servers. See our Forge security checklist.

Frequently asked questions

Can Confluence export to Markdown natively?

No. Confluence Cloud exports pages to PDF and Word, and spaces to HTML, XML, CSV or PDF. To get Markdown, convert one of those or use a Marketplace app.

What is the best way to export a whole Confluence space to Markdown?

Use an exporter app that keeps the page tree. In Markdown Exporter, open Apps → Markdown Exporter, pick the space and its top page, tick the pages and export. Large spaces run in the background and arrive in My exports.

Can I export Confluence to Markdown automatically?

Yes. Markdown Exporter can export a space or page tree every week or month on a schedule, and its Export API lets a CI job start an export with one request. With your own script, you can do the same with the REST API, Pandoc and a cron job.

Are images included when I export Confluence to Markdown?

With copy-paste, no. With a script, only if you download each attachment and rewrite the links. Markdown Exporter puts attachments in an attachments/ folder in the ZIP and links them with relative paths.

Is there a free Confluence Markdown exporter?

Yes. Markdown Exporter for Confluence is free on the Atlassian Marketplace and works on Confluence Cloud.

Can I convert Markdown back into Confluence later?

Yes. Markdown Importer for Confluence imports .md files, folders or a ZIP as a page tree. See how to import Markdown into Confluence.

Try it

Install Markdown Exporter for Confluence from the Atlassian Marketplace, open any page's ••• menu, choose Export to Markdown, and export a small page tree to see what you get. The quick start covers the rest.

How to Embed an iframe in Confluence Cloud

Yamuno — Tue, 20 Oct 2026 13:24:09 +0000

How to Embed an iframe in Confluence Cloud

Short answer: Confluence Cloud gives you two built-in ways to embed another web page: paste the link and switch it to the Embed view, or insert the iFrame macro and give it a URL. If you want a responsive frame, a caption or two embeds side by side, use an HTML macro app; HTML Macro+ can write the iframe code for you from a normal YouTube, Figma, Google Docs or Power BI link. None of these can show a site that refuses to be framed, which is the usual reason an embed comes up blank.

This guide walks through all three options, shows working examples for YouTube, Google Sheets and dashboards, and ends with a checklist for blank embeds.

Three ways to embed in Confluence Cloud

Option	How you add it	Best for	Limits
Smart Link embed	Paste a link, select it, choose Embed in the link toolbar	Apps Atlassian already knows: videos, design files, Google files, Jira	Only works for supported sources
iFrame macro	Type `/iframe`, set the URL and size	Any page that allows framing, shown as is	Fixed width and height, no layout or caption
HTML macro	Type `/html`, paste a link into an embed template or write your own `<iframe>`	Responsive frames, captions, several embeds, embeds inside your own layout	Needs an app; admins decide which domains can load

Start with the first one that works. Smart Links need no setup, the iFrame macro covers most other cases, and an HTML macro is for when you want control over how the embed looks.

Option 1: Smart Link embed

When you paste a URL into a Confluence page, it usually turns into a Smart Link. Smart Links have several views: Inline shows just the title, Card adds a preview with some context, and Embed shows the content itself in the page so readers can use it without leaving Confluence.

To switch a link to an embed:

Paste the URL into the page, or type /link.
Select the link.
In the toolbar that appears, choose the embed view.
Drag the edges to resize it, then publish.

This is the quickest option for YouTube videos, Figma files, Loom recordings, Google Docs and Sheets, and Jira work items. Content from apps that need a login, such as a Google Sheet, is shown according to each reader's own access, so a reader without permission sees a prompt instead of the data. If a link does not offer an embed view, Confluence does not recognise the source, and you need one of the next two options.

Option 2: the built-in iFrame macro

The iFrame macro embeds any web page by URL. To add it:

Edit the page and type /iframe, then select iFrame.
Enter the address of the page you want to show. Use https://.
Set the other parameters in the macro panel. Changes save as you make them.
Publish the page.

The parameters that still have an effect in Cloud, according to Atlassian's documentation:

Parameter	What it does	Default
Width	Fixed width in pixels	Not set
Height	Fixed height in pixels	Not set
Align	Left or right	Left
frameborder	Show or hide a border around the frame	Show
scrolling	Yes, No or Auto	Auto

Older parameters such as title, ID, class and margin are deprecated and do nothing. In practice you set the URL and a height that fits the content, for example 600 pixels for a form or 800 for a dashboard.

The iFrame macro is the right choice when the embed only needs to appear on the page. It has no way to add a caption, keep a 16:9 ratio on narrow screens, or place two frames next to each other.

Option 3: your own iframe in an HTML macro

Confluence Cloud has no HTML macro of its own, so this needs an app from the Atlassian Marketplace. The examples below use HTML Macro+ for Confluence, which is free and runs on Atlassian Forge. Edit a page, type /html and select HTML Macro+ for Confluence. The editor has separate HTML, CSS and JavaScript tabs and a live preview.

Two things to know before you start:

Admins choose which domains can load. HTML Macro+ has three security modes: Block all, Whitelist only and Allow all. In Block all mode no iframes load. In Whitelist only mode, an iframe loads only if its domain is on the list; otherwise readers see a blocked content placeholder. An empty whitelist behaves like Block all. Admins set this under Confluence Administration > Manage apps > HTML Macro+ for Confluence > Configure, as described in the security settings guide.
The macro sizes itself. The macro's height follows its content, so you control the frame size with CSS instead of a height field.

Adding youtube.com to the whitelist also covers www.youtube.com, because an entry matches the domain and its subdomains. Use *.example.com if you want subdomains only.

The quick way: embed templates

You don't have to write the iframe yourself. In the HTML Macro+ editor, click Embed templates, pick the service and paste the link you already have. The template converts it into the address the service expects inside a frame and writes responsive HTML and CSS into the editor, with a preview before you insert it.

Category	Services
Video	YouTube, Vimeo, Loom
Design and whiteboards	Figma, Miro
Documents	Google Docs, Sheets, Slides, Forms and Drive files, Microsoft Forms, Word, Excel and PowerPoint on the web
Dashboards and data	Power BI, Tableau Public, Airtable, Google Maps, Google Calendar
Other	Any web page or PDF

Choose Add below to stack several embeds in one macro, or Replace content to start fresh. If your admin's settings block the service's domain, the dialog tells you before you insert it. The generated code stays editable, so you can still add a caption or change the size. See the embed templates guide for which link to paste for each service.

The examples below show the code by hand, for when you want a layout of your own.

Example: embed a YouTube video

On YouTube, open the video, select Share > Embed and copy the src address. It looks like https://www.youtube.com/embed/VIDEO_ID. A normal watch?v= link will not play in a frame. (The YouTube embed template in HTML Macro+ accepts the normal link and converts it for you.)

With the iFrame macro, paste that address and set the height to about 400 pixels. With HTML Macro+, you can make the frame keep its shape on any screen width:

HTML

<figure class="video">
  <iframe
    src="https://www.youtube.com/embed/VIDEO_ID"
    title="Onboarding walkthrough"
    allow="fullscreen; picture-in-picture"
    allowfullscreen
  ></iframe>
  <figcaption>Onboarding walkthrough, 8 minutes</figcaption>
</figure>

CSS

.video { margin: 0; font-family: -apple-system, "Segoe UI", sans-serif; }
.video iframe {
  width: 100%;
  aspect-ratio: 16 / 9;
  border: 0;
  border-radius: 10px;
}
.video figcaption { margin-top: 8px; font-size: 13px; color: #44546f; }

For HTML Macro+, youtube.com needs to be on the whitelist unless your admin allows all domains. If you prefer YouTube's privacy-enhanced mode, use youtube-nocookie.com in the address and whitelist that domain instead.

Example: embed a Google Sheet

There are two good ways to put a Google Sheet on a Confluence page.

For a sheet your team already shares in Google, paste the sheet's link and switch it to the embed view (Option 1). Readers see it with their own Google access, so permissions stay in Google.

For a read-only table anyone can see, publish it from Google Sheets:

In Google Sheets, open File > Share > Publish to web.
Choose the Embed tab, pick the whole document or one sheet, and select Publish.
Copy the iframe code. Its src starts with https://docs.google.com/spreadsheets/d/e/.

Paste that address into the iFrame macro, or use the full iframe code in HTML Macro+ with docs.google.com (or google.com) on the whitelist. Two cautions: a published sheet is visible to anyone who has the address, so never publish sheets with private data, and edits reach the embed only while the sheet's Automatically republish when changes are made option is on.

HTML Macro+ also lets you place a sheet next to something else, such as a chart and the table it comes from:

<div class="pair">
  <iframe src="https://docs.google.com/spreadsheets/d/e/SHEET_ID/pubhtml?widget=true&headers=false" title="Q3 budget"></iframe>
  <iframe src="https://docs.google.com/spreadsheets/d/e/SHEET_ID/pubchart?oid=CHART_ID&format=interactive" title="Q3 budget chart"></iframe>
</div>

.pair { display: grid; grid-template-columns: repeat(auto-fit, minmax(320px, 1fr)); gap: 16px; }
.pair iframe { width: 100%; height: 420px; border: 1px solid #dfe1e6; border-radius: 8px; }

If you would rather draw the chart in Confluence from your own data, see how to make a pie chart in Confluence.

Example: embed a dashboard or internal tool

Status pages, BI dashboards and internal web tools are common things to embed on a team's home page. Most BI tools have an embed or share option that gives you a frame address meant for this. Use it rather than the address in your browser bar, because the normal page often blocks framing.

A few notes:

Some tools need embedding turned on first. Grafana, for example, refuses to be framed until allow_embedding is enabled in its server configuration.
If the tool needs a login, readers sign in inside the frame, and some login pages refuse to load in a frame at all. Check with a colleague's account before you rely on it.
If you only need a few numbers on the page, consider building the panel in Confluence instead. Our guide to building a status dashboard in Confluence shows how.

Why an iframe shows blank

When an embed shows an empty box, a grey page or a "refused to connect" message, check these in order:

The site blocks framing. Many sites send an X-Frame-Options or Content-Security-Policy: frame-ancestors header that tells browsers not to show them inside other pages. No Confluence setting or app can override this. Look for the site's own embed address, or use a link instead.
The address uses http://. Confluence is served over HTTPS, and browsers block insecure frames on secure pages. Change the address to https://.
You used the page address, not the embed address. YouTube, Google Sheets, maps and BI tools all have a separate embed URL. In HTML Macro+, an embed template does this conversion for you.
The domain is not whitelisted (HTML Macro+). You will see a blocked content placeholder instead of a blank frame. Ask your admin to add the domain shown in the iframe's src. The troubleshooting guide lists the common ones.
The height is too small. In the iFrame macro, set an explicit height. In an HTML macro, give the iframe a height or an aspect ratio in CSS.
The browser blocked it. Privacy extensions and strict browser settings can block third-party frames. Try another browser to rule this out.

If you are moving from Confluence Data Center and your old pages used the HTML or HTML Include macro for embeds, see keeping legacy macros working after a Cloud migration.

Frequently asked questions

Does Confluence Cloud support iframes?

Yes. Confluence Cloud includes an iFrame macro that embeds a web page by URL, and Smart Links can show supported apps in an embed view. What it does not have is a built-in HTML macro for writing your own iframe code. For that you need a Marketplace app.

Why is my iframe blank in Confluence?

Usually because the site you are embedding does not allow other sites to frame it. Other common causes are an http:// address, using the normal page address instead of the embed address, and a height that is too small. With an HTML macro app, the domain may also need to be allowed by your admin.

How do I embed a Google Sheet in Confluence?

Paste the sheet's link and switch it to the embed view, which keeps Google's sharing permissions. For a public, read-only table, use File > Share > Publish to web in Google Sheets and put the embed address in the iFrame macro or an HTML macro.

Can I make an iframe responsive in Confluence?

Not with the iFrame macro, which uses a fixed width and height. In an HTML macro, set width: 100% and an aspect-ratio on the iframe in CSS, as in the YouTube example above. HTML Macro+ embed templates produce responsive code like this automatically.

How do I embed Power BI, Figma or Miro in Confluence?

Try a Smart Link embed first, which works for many design tools. For Power BI, Tableau Public, Airtable and anything without an embed view, use an HTML macro. In HTML Macro+, open Embed templates, choose the service and paste a "Publish to web" or share link. The file must be shared so that your readers can open it.

Is it safe to embed other sites in Confluence?

The embedded site runs in its own frame and cannot read your Confluence page. The bigger risk is showing content you did not mean to share, such as a published sheet, or letting editors frame any site. HTML Macro+ lets admins limit framing to approved domains and limit who can edit the macro.

Can I still use the old HTML macro from Data Center?

Not natively. Confluence Cloud does not include it, and migrated pages that used it show an error. An HTML macro app such as HTML Macro+ renders those legacy macros again; see our overview of the HTML macro for Cloud.

Try it

Try the built-in options first: paste a link and choose embed, or type /iframe. When you need a responsive frame, a caption, several embeds in one layout or an embed built from a plain link, install HTML Macro+ for Confluence, free on the Atlassian Marketplace, and follow the installation guide. For more ideas, see 5 ways to use HTML in Confluence Cloud.

Script Toolkit for Jira is live on the Marketplace

Yamuno — Thu, 15 Oct 2026 06:44:44 +0000

Script Toolkit for Jira is live on the Marketplace

Short answer: Script Toolkit for Jira is now on the Atlassian Marketplace, and it's free. It lets Jira admins extend Jira Cloud with JavaScript: your own panels on work items, dashboard gadgets, web triggers for other systems, scheduled jobs, scripted fields and workflow validators. Everything runs on Atlassian Forge, inside your Jira site, and backend scripts are read only unless you allow writes.

Most Jira teams have a short list of small things they wish Jira did. Show the linked deployment on every work item. Post a comment when CI finishes. Count overdue work every morning. Refuse a transition when a field is empty. Each one is a few lines of code, but until now each one meant building and hosting a whole app, or living without it. Script Toolkit gives those few lines a place to run.

What you can build

Try code in the Script Console

Open Jira settings → Apps → Script Toolkit → Script Console, write JavaScript, and press ⌘↵ (Ctrl+↵ on Windows). The console runs in your browser with your own Jira permissions and saves nothing, so it's a safe place to explore the Jira REST API before you turn code into a script:

const res = await requestJira('/rest/api/3/search/approximate-count', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ jql: 'statusCategory != Done AND assignee = currentUser()' }),
})
const { count } = await res.json()
return `${count} open work items assigned to you`

await works at the top level, and whatever you return is shown under the editor. The Script Console guide lists every global you can use.

Fragments: your own panels inside Jira

A fragment is HTML, CSS and JavaScript that Script Toolkit shows inside Jira. Put it in a panel on every work item, in a dialog opened from the work item's ••• menu, on a project page or in project settings. Several fragments in the same place appear as tabs.

Fragments run in the viewer's browser and call Jira as the viewer, so people only ever see what they could already see. Use Atlassian design tokens and your panel follows Jira's light and dark themes. The fragments guide has a minimal example you can paste and save.

Dashboard gadgets

Gadget scripts work like fragments, but on a dashboard. Add the Script Toolkit Gadget, pick one of your gadget scripts, and each gadget on the dashboard can show a different one. Each viewer sees their own data. See Gadgets for the setup. If what you need is a standard chart rather than custom code, Charts for Jira Dashboard is the quicker route.

Web triggers for other systems

A web trigger gives a script a secure URL with its own secret. A CI pipeline, a monitoring alert or a form can call it, and whatever the script returns comes back as JSON. Calls without the right secret get a 401 before any script runs, and you can rotate the secret at any time. The web triggers guide shows a full example that comments on a work item when a deploy finishes.

Scheduled jobs

Run a backend script on a cron schedule in UTC: a morning count of overdue work, a weekly clean-up, a nightly sync with another tool. Jobs are checked every five minutes and can run for up to five minutes each. See Scheduled jobs.

Scripted fields

Create a custom field whose value a script computes when the work item is shown: text, number, user, date or date time. For example, the number of done subtasks, or a due date worked out from other fields. Field runs have their own daily limit, so heavy browsing can't use up the budget your jobs and triggers need. See Scripted fields.

Workflow validators and post-functions

Attach a script to a transition. A validator can block it and tell the user why, for example "Assign this work item first." A post-function runs after the transition, to add a comment or set a field. A validator that fails or times out allows the transition, so a broken script can never lock a workflow. See Workflow extensions.

Bulk tools for people who aren't admins

Script Toolkit also includes seven ready-made bulk tools for work items: transition, set resolution, assign, add a comment, edit labels, set priority, and copy one custom field into another. You open each tool to admins, chosen groups or everyone. People run a tool on a JQL query, up to 5,000 work items at a time, and it uses their own Jira permissions, so access to a tool grants no new rights. The tools guide covers access and limits.

Safe by default

Running code inside Jira should not mean giving up control, so the defaults are strict:

Only Jira admins write scripts. Everyone else only sees the results, or runs the bulk tools you open to them.
Backend scripts are read only unless you set a script's Jira access to Read and write. Any request that would change data is refused before it is sent.
Outbound calls happen only if you allow them, either to a list of hosts you choose or to any public https host. Private and internal addresses are always refused.
Secrets stay secret. API keys live in Forge's encrypted secret storage, can't be read back from the UI, and are masked in logs.
Every run has limits: a time limit per run and daily limits per site, which admins can adjust within set ranges.
Every run is logged, grouped by run and filterable by script, with a retention you set.

Backend scripts run in an isolated JavaScript sandbox inside the app, on Atlassian's infrastructure. Yamuno runs no servers for Script Toolkit and receives none of your data. The data and privacy page lists what the app stores and each permission it asks for, and our Forge security checklist explains what "runs on Atlassian" means when you compare apps.

Who it's for

Jira admins who keep getting asked for "just one small panel" or "one more rule on this transition"
Platform and DevOps teams connecting CI, deploys and monitoring to Jira through web triggers
Team leads and support staff who need bulk changes without becoming Jira admins
Anyone reporting from Jira who wants a computed field or a scheduled count instead of a manual spreadsheet; our guide to Jira reporting for product managers covers where those numbers fit

If you also need to see what changed on work items and how long they sat in each status, Issue History+ for Jira works well alongside it.

Getting started

Install Script Toolkit for Jira from the Atlassian Marketplace.
Open Jira settings → Apps → Script Toolkit → Script Console and click Run on the starter script.
Open Scripts, choose Fragment, test it against a work item key in the Test tab, and save it.
Open that work item and find your fragment in the Script Toolkit panel.
Create a Web trigger and call it with the example command under How to call it.

The quick start walks through all of this in about fifteen minutes.

Frequently asked questions

How much does Script Toolkit cost?

It's free on the Atlassian Marketplace.

Which language are scripts written in?

JavaScript. Fragments and gadgets are HTML with JavaScript that runs in the viewer's browser. Backend scripts are modern JavaScript with top-level await, run in an isolated sandbox inside the app. There is no Node.js, so no require or file system.

Who can write scripts?

Only Jira admins. Fragments and gadgets then run for everyone who views them, with each viewer's own permissions, and bulk tools can be opened to chosen groups.

Do scripts run on external servers?

No. Everything runs on Atlassian Forge, inside your Jira site. Yamuno runs no servers for the app.

Can a backend script change Jira?

Only if you allow it. Each backend script is read only by default; set its Jira access to Read and write when it needs to create or change data.

Can I test a script before it goes live?

Yes. The editor's Test tab runs the unsaved code once, against a work item key or a request body, and fragments and gadgets can be previewed under the editor before you save.

Try it

Install Script Toolkit for Jira and run your first script in the console. Questions or feedback? Reach us through our support portal. Your input shapes what we build next.

Issue History+ for Jira is live on the Marketplace

Yamuno — Tue, 13 Oct 2026 16:43:42 +0000

Issue History+ for Jira is live on the Marketplace

Short answer: Issue History+ for Jira is now on the Atlassian Marketplace, and it's free. It reads the change history Jira already records and lets you search it for a whole project, sprint or JQL query, see how long work spends in each status, and find stuck work, rework and SLA breaches. It runs on Atlassian Forge, so your issue data never leaves Atlassian.

Jira writes down every change to every issue: who moved it, who reassigned it, who rewrote the description, and when. Reading that record is the hard part. The History tab shows one issue at a time, so answering "who moved these tickets back to In Progress last week?" means opening them one by one. We built Issue History+ to answer that kind of question in one search.

What the app does

Search the change history of many issues at once

Open Apps → Issue History, pick a project and a date range, and click Search. You get every field change for the matching issues in one table. There are three ways to choose the issues:

Standard: project, sprint, issue type, assignee, reporter, label, group and date range
JQL: paste a query you already use, with autocomplete and validation
Bulk: a list of issue keys, for example from a release note

Group the results by issue, project, author or field, or read them as a feed. Summary and description edits show word-level differences, so you can see exactly which words changed instead of comparing two long paragraphs. Highlight marks every change one person made. The searching history guide covers each option.

Time in status

The Time in Status tab shows, for each status, the median time per visit and the time 85% of visits finish within. We chose those over averages on purpose: one issue forgotten in review for three months can drag an average far from what a typical issue experiences, while the median and the 85th percentile stay honest.

Time runs from the moment an issue enters a status until it leaves, and repeat visits are added up. You can count calendar time or business hours, and set an SLA per status so breaching issues are marked. A per-issue table lets you sort by any status to find the issues that spent longest there. The time in status guide explains how each number is calculated.

Status timeline

The Status Timeline tab draws each issue's path through your workflow as one bar, coloured by status category. It makes ping-pong between In Progress and In Review easy to spot, which is hard to see in a list of changes.

Insights

Insights summarises the current search:

Completed and in-progress issues
Median cycle time and the cycle time 85% of issues finish within
Reopened issues: anything that left Done at least once
Inactive work: issues that are not done and have had no status change for 7, 14 or 30 days
Rework: the share of status moves that go backwards
SLA breaches, worst first

It also shows issues completed per week, the most common status changes, when changes happen during the week, and who changes what. Every metric is defined in the Insights guide.

Because the app uses each status's Jira category (To Do, In Progress, Done), custom statuses such as Shipped or Won't Fix count correctly without any setup.

Issue Insights on every issue

Each issue gets an Issue Insights tab in its Activity section. It shows that issue's total time in each status, its status timeline and every change, newest first. You don't need to leave the issue to see where it has been.

Restore

For status, assignee, priority and summary, Restore puts the field back to the value it had before a change. It uses Jira's normal edit and transition permissions, so it only works where you could make that change in Jira yourself.

Reports for people outside Jira

Export the current search to CSV, Excel or a PDF report with your company name and logo. Excel and PDF exports include SLA thresholds and how many issues went over them. You can also save a search as a private bookmark, and your last ten searches are one click away.

Your data stays in Atlassian

Issue History+ runs entirely on Atlassian Forge and declares no egress, so issue data is never sent to an external server. Every request runs as the signed-in user, which means people only see history for issues they can already browse in Jira.

The app stores only each user's saved searches, recent searches, settings and PDF branding, in Forge storage for your site. It doesn't store issue data, names or email addresses. The data and privacy page lists everything it reads and stores, along with each permission it asks for. If you are comparing apps on this point, our Forge security checklist explains what "runs on Atlassian" means in practice.

Who it's for

Scrum masters and team leads who want to see where work waits and which issues have gone quiet, before stand-up
Jira admins answering "who changed this field, and when?" for many issues at once
Support and service teams tracking time in each status against an SLA
Product and delivery managers who need cycle time and throughput without building a spreadsheet; our guide to Jira reporting for product managers shows where it fits alongside Jira's own reports
Anyone reporting to stakeholders who don't use Jira, through PDF and Excel exports

For a walkthrough of a full setup, from measuring time in status to setting SLAs, see the time in status and issue history use case. If you also want charts on your Jira dashboard, Charts for Jira Dashboard works well next to it.

Getting started

Install Issue History+ for Jira from the Atlassian Marketplace.
Open Apps → Issue History, choose a project and keep the default last 30 days.
Click Search, then open the Time in Status and Insights tabs.
Open any issue and choose Issue Insights under Activity.
Click Export to share a report.

The quick start takes about ten minutes.

Frequently asked questions

How much does Issue History+ cost?

It's free on the Atlassian Marketplace.

Where does the history come from?

From Jira's own changelog, read through the Jira REST API as the signed-in user. The app fetches the complete history of each issue, not only the most recent changes.

Can people see history for issues they can't access?

No. Every request runs with the viewing user's Jira permissions, so people only see history for issues they can already browse.

Does it work with company-managed and team-managed projects?

Yes. Both project types record the standard Jira changelog, which is what the app reads.

Does it change anything in Jira?

Only when someone clicks Restore, and only for status, assignee, priority or summary. Everything else is read only.

Try it

Install Issue History+ for Jira and run your first search. Questions or feedback? Reach us through our support portal. Your input shapes what we build next.

PDF Exporter adds scheduled exports and a REST API

Yamuno — Tue, 13 Oct 2026 07:58:10 +0000

PDF Exporter adds scheduled exports and a REST API

Short answer: the 13 October 2026 release of PDF Exporter for Confluence is the biggest since launch. Large exports now run on Atlassian's servers in the background, so you can close the page while they finish. Schedules export a space or page tree every week or month and attach a dated PDF to an archive page. And a REST API lets scripts and CI/CD pipelines start exports with an API token.

Until now, every export was built in your browser. That works well for a handful of pages, but a 400-page space export meant keeping a tab open, and a monthly compliance snapshot meant someone remembering to click Export on the first of the month. This release is about taking both of those jobs off people's hands.

Background exports and My exports

The exporter's sidebar has a new Where to generate option:

Auto (recommended): small exports are built in your browser, large ones go to the server. The exporter tells you which it picked and why.
This browser: always build locally. Fastest for a few pages, but the page has to stay open.
Server (background): always build on the server, and leave whenever you like.

With Auto, an export moves to the server when it has more than 30 pages, more than 60 attachments, or more than 50 MB of attachments.

A progress card shows each step (fetching pages, rendering, laying out the PDF). When it's done you can download from the card, or find the file later under My exports in the sidebar. If you close the exporter mid-export, the card comes back the next time you open it.

My exports keeps your server exports for 7 days by default. Large ZIP exports come in parts, download links are created when you click, and exports attached to a page have an Open on page link. Site admins set the retention period (1 to 90 days) and a storage limit for the site under Confluence Settings → PDF Exporter → Exports & storage.

Background exports run on Atlassian Forge and the files sit in Atlassian's own storage. Nothing leaves Atlassian. The background exports docs cover the details.

Scheduled exports

Schedules are for teams that keep audit or retention copies of their documentation, or anyone who needs a monthly "as it was" copy.

Open Apps → PDF Exporter for Confluence, choose Schedules in the sidebar and click New schedule. A schedule has:

What to export: a page and its children, or a whole space
Style Template: any saved template; template edits apply to the next run
Output: one merged PDF or a ZIP of PDFs
How often: weekly on a weekday, or monthly on a date from 1 to 28
Where it goes: attached to an archive page you choose, or kept in My exports only
Notify by email: every run, only failures, or off

When a run attaches its file to an archive page, the file is named with the schedule name and the run date, for example Compliance snapshot 2026-11-01.pdf. The page's attachments then list every run in order, and those files stay until someone deletes them.

Email notifications without noise

Notifications use Confluence itself. After a run, the app comments on the archive page and @mentions the people you picked, and Confluence emails them as it does for any mention. Each schedule keeps one comment thread and adds every later run as a reply, so a weekly schedule doesn't bury the page in comments after a year. Only failures keeps the thread quiet unless something goes wrong.

Failures you can act on

A failed run shows its reason in plain words, such as "Archive page was deleted". Problems that can't fix themselves (a deleted archive page, a deleted space, an owner who left) pause the schedule straight away. Other failures pause it after three in a row. Run now runs a schedule immediately without moving its regular dates, which is handy for a first test. Site admins see every schedule on the site, with its owner, status and next run.

Each run uses the access of the person who created the schedule, so it only exports pages they can view. The scheduled exports docs list every option. For the bigger picture on audit copies, see Confluence PDF export for compliance teams.

A REST API for scripts and pipelines

Some exports belong to a process rather than a person: release notes at the end of a deployment, a spec frozen when a project closes, a nightly copy of a runbook space. The new REST API covers those.

A site admin creates a token under Confluence Settings → PDF Exporter → API, choosing an expiry of 30 days, 90 days, 180 days or 1 year. Then one request starts an export:

curl -X POST 'YOUR_ENDPOINT_URL' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"pageId": "123456", "name": "Release notes"}'

A 202 response means the export started. The request can export a page, a page tree or a space, use any saved template, attach the file to a page and @mention up to 10 people. Send a requestId and a retried request starts nothing new. Each token has a Recent calls log of its last 25 requests, and only a hash of the token is stored.

One design choice is worth knowing about. API responses are fixed messages and carry no page data, and no data is sent out of Atlassian. That keeps PDF Exporter eligible for Atlassian's Runs on Atlassian program. It also means the response tells you the export started, not where the file is: you pick it up in My exports, on the page you attached it to, or from the mention email. The REST API guide and examples show common jobs.

If you already automate Confluence content, the same token-based approach is used by the Markdown Importer REST API.

Fair use: one server export at a time

Server exports run one at a time per site, and that includes scheduled runs and API calls. When another export is running, yours shows Waiting in Line with its place in the queue and a Cancel button, and starts on its own.

Each site can render 10,000 pages a month on the server. Browser exports don't count toward that, and the allowance resets on the first of each month (UTC). Admins see this month's usage under Server exports this month.

Because server exports need new permissions, sites on an older version see a notice that an update is waiting, with a link to Manage apps for admins.

Smaller changes and fixes

The exporter and the settings page now use a sidebar, and remember the open section in the page address
Clicking Export shows Preparing Export straight away, and the button can't be clicked twice
Custom emoji keep their image, panels keep their background colour and decision items keep their formatting
Table of contents zone macros are no longer left out
Long code lines without spaces wrap instead of running off the page
Embeds without a source show a named "not included" note

The full list is in the release notes.

Frequently asked questions

Do I need to do anything to get the new features?

A site admin needs to approve the update in Manage apps, because server exports use new permissions. Until then the exporter shows a notice with a link.

Do small exports still happen in my browser?

Yes. With Where to generate set to Auto, exports of up to 30 pages (and within the attachment limits) are still built in your browser and download straight away. You can also force either option.

How long are background exports kept?

Seven days by default. Admins can set anything from 1 to 90 days, plus a storage limit for the site. Files that a schedule or API call attached to a Confluence page stay on that page until someone deletes them.

Can a scheduled export run at a set time of day?

No. Schedules run once on their day, and Confluence picks the time. Dates are in UTC, so a schedule says "every Monday", not "every Monday at 9:00".

What can the REST API export?

A single page, a page tree or a whole space, with any saved template, as one merged PDF (up to 500 pages) or a ZIP of separate PDFs (up to 2,000 pages). Each token can start 30 exports an hour.

Does any of this send data outside Atlassian?

No. Background and scheduled exports run on Atlassian Forge and store files in Atlassian's storage, and API responses carry no page data.

Try it

Install PDF Exporter for Confluence from the Atlassian Marketplace, or update it under Manage apps if you already have it. New to the app? Start with how to export Confluence to PDF or the getting started guide.

Questions or feedback? Reach out via our support portal.

Confluence Markup: Wiki Markup vs Markdown in Cloud

Yamuno — Tue, 13 Oct 2026 07:57:58 +0000

Confluence Markup: Wiki Markup vs Markdown in Cloud

Short answer: Confluence markup, also called Confluence wiki markup or the Confluence markup language, is Atlassian's own text syntax (h1., *bold*, {code}), and Markdown is the syntax most developers write everywhere else (#, **bold**, triple backticks). The Confluence Cloud editor no longer accepts wiki markup, but it does turn common Markdown shortcuts into formatting as you type. If you want to keep Markdown as the source of a page, you need a Markdown macro or an importer.

If you have been using Confluence for a while, you probably learned wiki markup first. If you came from GitHub, GitLab or a docs-as-code setup, you think in Markdown. Both describe the same things, headings, lists, tables, code, but the symbols are different, and only one of them still has a place in the Cloud editor. This guide puts the two side by side and explains what to use today.

What is Confluence markup?

Confluence markup is the plain-text format the original Confluence editor was built around. Atlassian calls it wiki markup, and Jira Data Center and Jira's version 2 REST API use the same syntax. Before the rich text editor took over, you wrote pages as text with markup and Confluence rendered them. A heading was h2. Release notes, a table header row was ||Name||Owner||, and a code sample sat between {code} tags.

That syntax still exists in a few places:

Confluence Data Center still documents and supports wiki markup.
The legacy Confluence Cloud editor has an Insert > Markup dialog that accepts wiki markup or Markdown and converts it into rich text.
Older pages and scripts. Content written years ago, and tools built on Jira's version 2 REST API, which takes rich text fields as wiki markup, still use it.

In the current Confluence Cloud editor, Atlassian states plainly that markup insertion is not supported. You cannot open a page and edit its wiki markup source either; the page is stored in Confluence's own format and you work on it as rich text.

Markdown in the Confluence Cloud editor

What the Cloud editor does have is autoformatting that follows Markdown conventions. Type these and Confluence converts them on the spot:

# followed by a space for Heading 1, up to ###### for Heading 6
**bold**, *italic* and ~~strikethrough~~
`code` for inline code, and three backticks followed by a space for a code block
* followed by a space for a bulleted list, 1. followed by a space for a numbered list
[] followed by a space for an action item (a task)
> followed by a space for a quote, and --- followed by a space for a divider
[link text](https://example.com) for a link

This is handy when you write a page by hand. The catch is that it is a typing shortcut, not a Markdown mode. Once the text is formatted, the Markdown is gone. You cannot switch the page back to its Markdown source, and there is no table shortcut, so tables still come from the toolbar or the slash command. For more on code specifically, see inline code and code blocks in Confluence.

Wiki markup vs Markdown, side by side

Here is how the same formatting is written in each syntax.

What you want	Confluence wiki markup	Markdown
Heading 2	`h2. Title`	`## Title`
Bold	`bold`	`bold`
Italic	`_italic_`	`italic`
Strikethrough	`-deleted-`	`~~deleted~~`
Inline code	`{{code}}`	`code`
Code block	`{code:java}` … `{code}`	three backticks plus the language, then three backticks
Bulleted list	`* item`	`- item` or `* item`
Numbered list	`# item`	`1. item`
Link	`[title\	https://example.com]`{% endraw %}
Table header	{% raw %}`\	\
Quote	{% raw %}`bq. text`	`> text`
Horizontal rule	`----`	`---`

Three differences catch people out:

Asterisks mean different things. In wiki markup *text* is bold; in Markdown it is italic. Paste one into the other and the emphasis changes.
# is a numbered list in wiki markup and a heading in Markdown. A wiki-style numbered list pasted into a Markdown file turns into a stack of headings.
Links put the title and URL in a different order and with a different separator. Wiki markup uses [title|url], Markdown uses [title](url).

Confluence wiki markup cheat sheet

Wiki markup also covers things standard Markdown has no syntax for, such as coloured text, panels and user mentions. These are the ones you are most likely to meet in older pages and Jira issue descriptions.

What you want	Confluence wiki markup
Underline	`+underlined+`
Superscript and subscript	`^super^` and `~sub~`
Coloured text	`{color:red}text{color}`
Line break	`\\`
Image from an attachment	`!diagram.png!`, or `!diagram.png\
Link to an attachment	{% raw %}`[^report.pdf]`
Link to another page	`[Page title]` or `[SPACEKEY:Page title]`
Mention a user	`[~username]`
Anchor and link to it	`{anchor:setup}` and `[#setup]`
Table cell	`\
Info, note, tip, warning panels	{% raw %}`{info}text{info}`, `{note}`, `{tip}`, `{warning}`
Panel with a title	`{panel:title=Before you start}text{panel}`
Preformatted text, no highlighting	`{noformat}text{noformat}`
Multi-line quote	`{quote}text{quote}`
Table of contents	`{toc}`

Anything in curly braces is a macro, which is why {code}, {info} and {toc} look alike. Standard Markdown has no equivalent for most of them. In the Cloud editor you add the same things from the slash menu instead: type /info for an Info panel or /table of contents for a table of contents.

Which one should you use?

For new content, Markdown. It is what developers already write in READMEs, pull requests, chat and issue trackers, it is supported by almost every docs tool, and the Confluence Cloud editor's shortcuts follow it.

Wiki markup still makes sense in two situations: you run Confluence Data Center and your team already knows it, or you maintain scripts that write to Jira's version 2 API. Outside of those, learning wiki markup today mostly means learning a syntax that only Atlassian products read.

Converting between the two

There is no built-in converter in Confluence Cloud, so most teams handle it one of three ways:

By hand, for a few pages. The table above covers nearly everything. Watch the three traps: asterisks, # and link order.
Export existing pages to Markdown. If the content already lives in Confluence, export it rather than converting text. Markdown Exporter for Confluence exports a page, a page tree or a whole space to Markdown files with front matter. See how to export Confluence to Markdown.
Import Markdown into pages. Going the other way, Markdown Importer for Confluence turns .md files, folders or a ZIP into a Confluence page tree. The walkthrough is in how to import Markdown into Confluence.

Search-and-replace scripts between the two syntaxes look easy and rarely are. Nested lists, code blocks that contain asterisks, and tables with links all break simple patterns, so test a converted page before you trust a batch.

Keeping Markdown as Markdown in Confluence

The editor's shortcuts and the Insert > Markup dialog both convert Markdown into rich text. That is fine for a one-off page. It is a problem when the Markdown is the real source, a README, an API reference or a runbook that also lives in Git, because the next edit has to be made twice.

Two ways keep the Markdown intact:

Write Markdown inside the page. Markdown Macro+ for Confluence adds a macro with a split editor and live preview. You write GitHub-flavoured Markdown, including tables, task lists, code with syntax highlighting and KaTeX math, and the source stays editable afterwards. The quick start takes a couple of minutes, and how to write Markdown in Confluence covers it in depth.
Publish from your repository. Keep the .md files in Git and push them to Confluence with Markdown Importer, by hand or from CI. This is the docs-as-code setup described on the technical documentation use case page.

Both apps are built on Atlassian Forge, so the content stays on your Atlassian site.

Frequently asked questions

What is the Confluence markup language?

It is Confluence wiki markup, the plain-text syntax Atlassian created for Confluence and Jira. Headings are h1. to h6., bold is *text*, code blocks sit between {code} tags and macros are written in curly braces. The current Confluence Cloud editor no longer accepts it; Data Center and the legacy Cloud editor do.

Does Confluence Cloud still support wiki markup?

Not in the current editor. Atlassian's documentation says the new editor does not support markup insertion, and pages are not editable as wiki markup. The Insert > Markup dialog only exists in the legacy editor, and Confluence Data Center still supports wiki markup.

Can I write Markdown in Confluence Cloud?

You can type Markdown shortcuts such as ##, **bold** and three backticks, and the editor formats them as you type. The Markdown itself is not kept. To keep editable Markdown on a page, use a Markdown macro such as Markdown Macro+.

What is the difference between Confluence markup and Markdown?

They describe the same formatting with different symbols. The biggest differences: *text* is bold in wiki markup and italic in Markdown, # starts a numbered list in wiki markup and a heading in Markdown, and links are [title|url] versus [title](url).

How do I convert Confluence wiki markup to Markdown?

For a few pages, convert by hand with a reference table like the one above. For content that is already in Confluence, export the pages to Markdown instead of converting text, for example with Markdown Exporter for Confluence.

Can I paste a README into Confluence and keep its formatting?

Pasting raw Markdown into the Cloud editor does not reliably keep its formatting. Put it in a Markdown Macro+ macro on the page, or import the file with Markdown Importer so headings, tables and code blocks come through.

Try it

Write your next README-style page in Markdown and keep it that way: install Markdown Macro+ for Confluence from the Atlassian Marketplace, add the macro to a page and paste your Markdown in. If the docs live in Git, try Markdown Importer on one folder first.

LaTeX Inline Math: $...$, \$...\$ and Display Math

Yamuno — Thu, 08 Oct 2026 15:20:12 +0000

LaTeX Inline Math

Inline math is an equation that sits inside a sentence, like "the roots are x = ±2" or "the loss is O(n log n)". LaTeX has two ways to write it, and a separate mode for equations that should stand on their own line. This guide covers both, what changes when math is inline, and how inline equations work outside a LaTeX document, in Markdown, Jupyter and Confluence.

Short answer:

Inline math: wrap the expression in single dollar signs, $E = mc^2$ , or in $E = mc^2$.
Display math (its own centered line): use \[E = mc^2\]. Avoid $$...$$ in LaTeX documents.

$...$ or $...$?

Both produce exactly the same inline equation:

The area of a circle is $A = \pi r^2$.
The area of a circle is \(A = \pi r^2\).

$...$ is shorter and is what almost everyone types. $...$ is the LaTeX form: the opening and closing delimiters are different, so a missing one gives a clear error instead of silently swapping text and math for the rest of the paragraph. Pick one and use it consistently in a document.

To print a literal dollar sign in text, escape it: \$5.

Display math: \[...\], not $$...$$

When an equation needs its own line, use display math:

The solutions are
\[
  x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
\]
for any quadratic with a ≠ 0.

$$...$$ also produces display math, but it is plain TeX syntax. In a LaTeX document it can give inconsistent spacing above and below the equation and doesn't work with the fleqn option, so \[...\] (or an environment such as equation or align from amsmath) is the recommended form. Many Markdown renderers and web tools do accept $$...$$, which is why you see it so often online.

What changes when math is inline

LaTeX shrinks inline math so it doesn't push the lines of the paragraph apart:

Sums, products and limits put their limits to the side instead of above and below. $\sum_{i=1}^{n} x_i$ shows the i = 1 and n next to the sigma, not over and under it.
Fractions are set smaller, with the numerator and denominator in a smaller font.
Big operators such as integrals are smaller.

That is usually what you want. When it isn't, you can override it:

Goal	Write
Limits above and below a sum, inline	$\sum\limits_{i=1}^{n} x_i$
A full-size fraction inline	$\dfrac{a}{b}$ (amsmath)
A small fraction in display math	`\[\tfrac{1}{2}\]` (amsmath)
Display-size everything in one inline expression	$\displaystyle \sum_{i=1}^{n} \frac{1}{i}$

Use these sparingly. A tall inline expression forces extra space between lines, and the paragraph looks uneven. If an inline equation needs \displaystyle to be readable, it probably belongs on its own line.

Text and spacing inside inline math

Inside math, letters are variables and spaces are ignored. So:

Words need \text{}: $x > 0 \text{ for all } x \in S$ . Without it, "for all" prints as six italic variables with no spaces.
Function names need their commands: $\log n$ , $\sin x$ , $\max(a, b)$ . See log and ln in LaTeX.
Add space by hand when needed: \, (thin), \; (thick), \quad (wide).
Keep punctuation outside the math when it belongs to the sentence: $x = 2$. rather than $x = 2.$ .

Inline math in Markdown, GitHub and Jupyter

Most Markdown tools that support math use the same delimiters:

GitHub renders $...$ inline and $$...$$ as a block in Markdown files, issues and pull requests. If a dollar sign gets misread, GitHub also accepts the form with backticks inside the dollars, a dollar sign then a backtick before the math and a backtick then a dollar sign after it.
Jupyter notebooks render $...$ and $$...$$ in Markdown cells with MathJax.
Static site generators and docs tools usually need a math plugin (KaTeX or MathJax) enabled before $...$ renders at all.

Because $ also means money, some renderers only treat $...$ as math when there is no space just inside the dollar signs. $x$ works; $ x $ may not.

Inline math in Confluence

Confluence Cloud has no built-in math, so you need an app. With LaTeX Math for Confluence, type /latex in the editor and choose LaTeX Math (Inline) for an equation inside a sentence or LaTeX Math (Block) for display math.

Delimiters are optional in both macros. The inline macro accepts E = mc^2, $E = mc^2$ or $E = mc^2$, so you can paste LaTeX from a paper or a Markdown file as it is. If you paste display delimiters such as $$...$$ or \[...\] into the inline macro, they are converted to inline math. Multi-line environments and large matrices belong in the block macro.

The app renders with KaTeX, so the commands in our LaTeX symbols reference that are marked as KaTeX-supported all work. For a full walkthrough, see how to add math equations to Confluence.

Common mistakes

Problem	Cause	Fix
The rest of the paragraph turns italic	A missing closing `$`	Close the math, or switch to `$...$` so the error is reported
Words inside an equation run together	Text typed in math mode	Wrap words in `\text{}`
An inline fraction looks tiny	Inline style is applied	Use `\dfrac` once, or move the equation to display math
Lines in the paragraph spread apart	A tall inline expression	Put the equation on its own line with `\[...\]`
A price prints as math	`$` read as a delimiter	Escape it as `\$`

FAQ

What is the difference between $ and $$ in LaTeX?
Single dollars give inline math inside a sentence. Double dollars give display math on its own line, but in LaTeX documents \[...\] is preferred.

How do I write inline math in LaTeX without dollar signs?
Use $ and $. They behave exactly like $...$ .

How do I make a sum show its limits above and below inline?
Add \limits: $\sum\limits_{i=1}^{n}$ . Or set the whole expression in display style with \displaystyle.

Can I use inline math in a heading?
Yes in LaTeX, but use it sparingly, because the math also appears in the table of contents and in PDF bookmarks, where it may not render. In Confluence, put the equation in the body text instead.

Problem	Cause	Fix
The rest of the paragraph turns italic	A missing closing `$`	Close the math, or switch to `\(...\)` so the error is reported
Words inside an equation run together	Text typed in math mode	Wrap words in `\text{}`
An inline fraction looks tiny	Inline style is applied	Use `\dfrac` once, or move the equation to display math
Lines in the paragraph spread apart	A tall inline expression	Put the equation on its own line with `\[...\]`
A price prints as math	`$` read as a delimiter	Escape it as `\$`