DEV Community: Yamuno Software

Exporting Confluence Documentation for Clients: A Practical Guide

Yamuno — Wed, 24 Jun 2026 10:52:41 +0000

Exporting Confluence Documentation for Clients

Most Confluence documentation is written for internal audiences — people who have access to the instance and can navigate the space directly. But plenty of documentation ends up going to people who don't have Confluence access: clients receiving a project handover, stakeholders reviewing a technical spec, partners getting onboarded, or auditors requesting documentation exports.

Confluence's built-in PDF export exists, but it produces bare output: no cover page, no custom headers, no watermarks, and no way to save a consistent format so the next export looks like this one. For internal drafts that's fine. For a client deliverable, it's not.

This guide covers how to export professional, consistently formatted PDFs from Confluence for external distribution using PDF Exporter for Confluence.

The Setup: Admin Creates a Template, Users Apply It

The key to consistent output across a team is templates. An admin creates a "Client Deliverable" template once in Confluence Settings. After that, any team member exporting for a client selects that template and gets the same cover page, header, and formatting — without touching any configuration themselves.

Admin step (one time):

Go to Confluence Settings → PDF Exporter → Templates → New Template
Name it "Client Deliverable"
Configure it as described below
Save

User step (every export):

Open the Confluence page or parent page to export
••• → Export to PDF
Select "Client Deliverable" template
Choose scope (single page, page tree, or space)
Export and download

Recommended Template Settings for Client-Facing PDFs

Cover Page

Enable the cover page. For client deliverables, Corporate or Executive style works best:

Corporate — left-aligned with a solid color accent bar, professional and structured
Executive — minimal with a thin accent line, suits formal proposals and executive-level documents

Set the accent color to your company's primary brand color (hex). Upload your company logo. Add a subtitle field — "Prepared for [Client Name]" or "Confidential — [Date]" — as a manual step per export.

Header

Enable the header with your company name or document series title, centered. This appears on every content page and reinforces the source of the document even when pages are printed individually.

Footer

Add page numbers (right-aligned) and a confidentiality notice (left-aligned):

Confidential — [Company Name]                                       Page 1 of 10

This combination is standard for client-facing documentation in most professional services contexts.

Watermark

For documents that are drafts or under review, enable the watermark with "DRAFT" at 0.15 opacity. Remove it from the template (or create a separate "Client Draft" template) when the document is final.

Enable for any multi-page export. Set depth to 2 (H1 and H2). This is especially important for handover packages and technical specs where clients need to navigate to specific sections.

Page Breaks

Enable "Break before H1" so each major section starts on a new page. For longer documents, also enable "Break before H2."

Common Export Scenarios

Project Handover Package

A handover package typically spans multiple Confluence pages — architecture overview, runbooks, configuration guides, contact lists. Export the entire section as a page tree:

Navigate to the parent page of the handover section
••• → Export to PDF
Select the page tree — uncheck any internal-only pages you don't want in the client copy
Select "Client Deliverable" template
Export — downloads as a ZIP with each section as a separate PDF

Alternatively, if you want a single combined PDF, check all pages under one parent. The exporter bundles them in page tree order.

Technical Specification

A single-page export is appropriate for a spec document or proposal:

Open the spec page
••• → Export to PDF
Select "Client Deliverable" template
Export — single PDF download

If the spec has an H1-level structure with multiple major sections, the table of contents and page breaks make it easy to navigate without Confluence access.

Compliance Documentation Export

For regulatory submissions or audit requests, use a separate "Compliance Archive" template with:

Executive cover style
Watermark: "ARCHIVED" or "CONFIDENTIAL" at 0.2 opacity
Footer: department name and export date
No table of contents unless required by the submission format

Create this template with watermark enabled by default so it's never accidentally omitted on a compliance export.

Recurring Status Report

If you export a weekly or monthly status report page to send to a client, the template eliminates the manual formatting step entirely. Update the Confluence page with new content, export with the "Client Deliverable" template, and the output is ready to send. The cover page, header, and formatting are consistent every time without any effort.

Space Export for Full Documentation Sets

For clients receiving a complete documentation set (e.g., a full product documentation space), use the space export:

From the global Apps menu, open PDF Exporter for Confluence
The page tree for the current space is displayed
Select all pages or deselect internal-only pages
Apply the template
Export — downloads as a ZIP of PDFs matching the space hierarchy

This is useful for project completion handovers, vendor certifications, or any situation where the client needs a complete copy of a documentation space they won't have ongoing access to.

Before You Send

Before the PDF goes to the client:

Use the Preview option in the exporter to verify the cover page, header, and first few pages look correct
Check that the subtitle on the cover page reflects the correct client name or document version
Confirm the watermark is absent if the document is final (or present if it's still a draft)
Open the downloaded PDF to verify the table of contents links work and the page numbering is correct

The preview step takes 30 seconds and catches the issues — wrong accent color, missing logo, leftover watermark — that would otherwise be visible to the client.

Install PDF Exporter for Confluence →

Read the documentation →

How to Manage Confluence Attachments at Scale

Yamuno — Sat, 20 Jun 2026 10:34:44 +0000

How to Manage Confluence Attachments at Scale

Confluence storage fills up in a predictable way. Teams upload screenshots, export files, and old versions of diagrams. Pages get reorganized or deleted. The attachments stay. After a year or two, a significant portion of your Confluence storage is files that are no longer referenced by any page — orphaned attachments that cost storage budget without serving any purpose.

Cleaning this up manually is impractical at any scale. This guide covers how to audit and manage Confluence attachments systematically using Advanced Attachment Manager for Confluence.

The Core Problem: Unused Attachments

An unused attachment is a file that was uploaded to Confluence but is no longer referenced anywhere in page content. This happens when:

A page is deleted but its attachments remain
An image is uploaded, replaced by a newer version, and the old version is left
A file is attached to a page during a draft but never embedded in the final content
Content is migrated from one space to another and the source attachments are left behind

Confluence's native attachment view shows you files per page. It doesn't have a cross-space view, doesn't flag unused files, and doesn't support bulk operations. Advanced Attachment Manager does.

Step 1 — Find Unused Attachments

Open Advanced Attachment Manager from the Confluence global navigation: Apps → Advanced Attachment Manager.

The first filter to apply: Usage Status → Unused. This surfaces every attachment in the selected scope (page, space, or instance-wide) that isn't currently referenced by any page content.

For most Confluence instances that haven't been audited recently, this list is longer than expected. Sort by File Size (descending) to see the biggest storage consumers first — a handful of large video files or exported PDFs often account for a disproportionate share.

Step 2 — Filter Down to What's Safe to Delete

Not every unused attachment should be deleted. Some are referenced in archived pages. Some are version history that someone may need to reference. Apply additional filters to narrow to what's clearly safe:

Filter by file type: Images and exported PDFs are the most common orphans. Filter to Images or Documents to work through the most common cases first.

Filter by upload date: Files uploaded more than 12 months ago and never used are strong candidates for deletion. Set the upload date range to filter out recent uploads.

Filter by uploader: If a departed team member uploaded most of the unused files, filtering by uploader gives you a focused list to review.

Use shift-click and ctrl/cmd-click to select individual files, or Select All after applying filters to select the entire filtered result set.

Step 3 — Download Before Deleting (When Uncertain)

For any batch where you're not 100% confident, use Bulk Download before deleting. This downloads all selected files as a ZIP archive to your local machine.

Bulk Download is also useful for migration and archival purposes — before decommissioning a Confluence space, download all attachments to preserve them outside Confluence.

Step 4 — Bulk Delete

With the files selected:

Click Delete Selected
Review the confirmation dialog — it shows the count and total size being freed
Confirm the deletion

Deletions are logged to the audit trail immediately. If you delete something that turns out to be needed, check the audit log first to confirm what was removed, then check if it can be recovered from Confluence's trash.

Step 5 — Review the Audit Log

Every action taken in Advanced Attachment Manager — views, downloads, deletions — is recorded in the audit log. Access it from the app sidebar.

The audit log shows:

Action type (deleted, downloaded, viewed)
File name and size
Space and page the file was attached to
User who performed the action
Timestamp

This is important for compliance-sensitive environments: you have a complete record of what was removed, by whom, and when.

Scheduling Regular Cleanups

Attachment management is most effective as a recurring process rather than a one-time cleanup. A quarterly cadence works for most teams:

Filter to unused attachments uploaded more than 90 days ago
Sort by size, work through the top 50 by size
Bulk delete the clearly obsolete ones
Download and archive anything uncertain

After two or three cycles, the backlog of orphaned files is small enough that the quarterly review takes 15–20 minutes instead of hours.

Space-Level vs. Instance-Level Audits

Advanced Attachment Manager supports two scopes:

Space-level: Scope the view to a specific Confluence space. Useful for space owners doing routine maintenance on their own space.

Instance-level: Confluence admins can view attachments across the entire instance. This is the right starting point for a storage audit — see total consumption by space, identify which spaces are the biggest consumers, and then drill into each one.

A Note on Storage Recovery

After bulk deletion, Confluence doesn't immediately reclaim storage — deleted files go to Confluence trash first. A Confluence admin needs to empty the trash to release the storage.

Go to Confluence Administration → Trash → Empty Trash. After emptying, the storage reduction is reflected in your instance's storage usage.

Install Advanced Attachment Manager for Confluence →

How to Embed Interactive Charts in Confluence with HTML Macro

Yamuno — Tue, 16 Jun 2026 12:56:22 +0000

How to Embed Interactive Charts in Confluence with HTML Macro

Confluence is where a lot of teams track project status, document KPIs, and share team metrics. But when it comes to actually visualizing that data, the options are limited. You can paste a static image (which goes stale), use a third-party integration (which requires a separate subscription), or accept that your Confluence page just won't have charts.

HTML Macro for Confluence opens a fourth option: embed Chart.js directly inside a Confluence page. The charts are interactive (hover for tooltips, click to toggle series), render instantly, and live alongside your documentation — no external service required.

This guide covers four chart types with copy-paste code for each.

Before You Start

Install HTML Macro for Confluence from the Atlassian Marketplace. It's free and runs on Atlassian Forge.

Security note: The examples below load Chart.js from a CDN (cdn.jsdelivr.net). Your Confluence admin needs to add that domain to the HTML Macro whitelist. Go to Confluence Settings → HTML Macro → Security Settings and add https://cdn.jsdelivr.net to the allowed domains.

Once that's done, add the macro to any Confluence page (Insert → Macro → HTML Macro), paste the code, and use the live preview to verify it before saving.

Bar Chart — Team Metrics or Sprint Data

Good for: comparing values across categories — issues by status, story points per sprint, bugs per team member.

<canvas id="barChart" width="700" height="350"></canvas>
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<script>
  new Chart(document.getElementById('barChart'), {
    type: 'bar',
    data: {
      labels: ['To Do', 'In Progress', 'In Review', 'Done'],
      datasets: [{
        label: 'Issues',
        data: [12, 8, 5, 34],
        backgroundColor: ['#94a3b8', '#3b82f6', '#f59e0b', '#22c55e'],
        borderRadius: 6,
      }]
    },
    options: {
      responsive: false,
      plugins: {
        legend: { display: false },
        title: {
          display: true,
          text: 'Issue Status — Sprint 42',
          font: { size: 15, weight: '600' },
          color: '#1e293b',
        }
      },
      scales: {
        y: {
          beginAtZero: true,
          grid: { color: '#f1f5f9' },
          ticks: { color: '#64748b' }
        },
        x: {
          grid: { display: false },
          ticks: { color: '#64748b' }
        }
      }
    }
  });
</script>

Replace the labels and data arrays with your actual values. Each label maps to the corresponding data value by index.

Line Chart — Velocity Trend or Weekly Progress

Good for: showing trends over time — sprint velocity, bug discovery rate, weekly active users, anything with a time axis.

<canvas id="lineChart" width="700" height="350"></canvas>
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<script>
  new Chart(document.getElementById('lineChart'), {
    type: 'line',
    data: {
      labels: ['Sprint 37', 'Sprint 38', 'Sprint 39', 'Sprint 40', 'Sprint 41', 'Sprint 42'],
      datasets: [{
        label: 'Story Points Completed',
        data: [41, 38, 45, 52, 49, 55],
        borderColor: '#6366f1',
        backgroundColor: 'rgba(99, 102, 241, 0.08)',
        borderWidth: 2,
        pointBackgroundColor: '#6366f1',
        pointRadius: 4,
        fill: true,
        tension: 0.3,
      }]
    },
    options: {
      responsive: false,
      plugins: {
        legend: { position: 'top' },
        title: {
          display: true,
          text: 'Sprint Velocity — Last 6 Sprints',
          font: { size: 15, weight: '600' },
          color: '#1e293b',
        }
      },
      scales: {
        y: {
          beginAtZero: false,
          grid: { color: '#f1f5f9' },
          ticks: { color: '#64748b' }
        },
        x: {
          grid: { display: false },
          ticks: { color: '#64748b' }
        }
      }
    }
  });
</script>

Pie Chart — Issue Type or Priority Distribution

Good for: showing how a total is distributed — issue types, budget allocation, time spent by category. Keep it to five segments or fewer.

<canvas id="pieChart" width="500" height="400"></canvas>
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<script>
  new Chart(document.getElementById('pieChart'), {
    type: 'pie',
    data: {
      labels: ['Bug', 'Feature', 'Task', 'Tech Debt', 'Spike'],
      datasets: [{
        data: [18, 32, 25, 14, 11],
        backgroundColor: [
          '#ef4444',
          '#6366f1',
          '#3b82f6',
          '#f59e0b',
          '#94a3b8',
        ],
        borderWidth: 2,
        borderColor: '#fff',
      }]
    },
    options: {
      responsive: false,
      plugins: {
        legend: { position: 'right' },
        title: {
          display: true,
          text: 'Open Issues by Type',
          font: { size: 15, weight: '600' },
          color: '#1e293b',
        }
      }
    }
  });
</script>

Doughnut Chart — Goal Progress or Completion Status

Good for: showing a single metric against a target — sprint completion, budget consumed, onboarding progress.

<div style="position:relative; width:400px; margin:0 auto;">
  <canvas id="doughnutChart" width="400" height="400"></canvas>
  <div style="position:absolute; top:50%; left:50%; transform:translate(-50%,-50%); text-align:center; font-family:sans-serif;">
    <div style="font-size:36px; font-weight:700; color:#1e293b;">72%</div>
    <div style="font-size:13px; color:#64748b;">Complete</div>
  </div>
</div>
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<script>
  new Chart(document.getElementById('doughnutChart'), {
    type: 'doughnut',
    data: {
      datasets: [{
        data: [72, 28],
        backgroundColor: ['#6366f1', '#f1f5f9'],
        borderWidth: 0,
        cutout: '78%',
      }]
    },
    options: {
      responsive: false,
      plugins: {
        legend: { display: false },
        tooltip: { enabled: false },
      }
    }
  });
</script>

Change the 72 and 28 values (they must add to 100) and update the center label to match.

Multi-Dataset Line Chart — Compare Two Teams or Products

When you want to compare two data series on the same time axis:

<canvas id="multiLineChart" width="700" height="350"></canvas>
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<script>
  new Chart(document.getElementById('multiLineChart'), {
    type: 'line',
    data: {
      labels: ['Week 1', 'Week 2', 'Week 3', 'Week 4', 'Week 5', 'Week 6'],
      datasets: [
        {
          label: 'Team Alpha',
          data: [12, 19, 15, 22, 18, 25],
          borderColor: '#6366f1',
          backgroundColor: 'transparent',
          borderWidth: 2,
          pointRadius: 4,
          tension: 0.3,
        },
        {
          label: 'Team Beta',
          data: [8, 14, 20, 17, 24, 21],
          borderColor: '#22c55e',
          backgroundColor: 'transparent',
          borderWidth: 2,
          pointRadius: 4,
          tension: 0.3,
        }
      ]
    },
    options: {
      responsive: false,
      plugins: {
        legend: { position: 'top' },
        title: {
          display: true,
          text: 'Weekly Issues Resolved',
          font: { size: 15, weight: '600' },
          color: '#1e293b',
        }
      },
      scales: {
        y: { beginAtZero: true, grid: { color: '#f1f5f9' } },
        x: { grid: { display: false } }
      }
    }
  });
</script>

Tips for Production Use

Hard-code the data for now. Chart.js in Confluence can't call your Jira API or database — the data lives in the HTML. If your metrics change weekly, treat the Confluence page as a weekly snapshot: update the arrays when you update the commentary.

Use width and height attributes directly on <canvas>. Don't rely on responsive: true inside Confluence — the macro iframe has fixed dimensions and responsive sizing can behave unexpectedly.

Each chart needs a unique id. If you put multiple charts on the same page, give each canvas a different id (barChart, lineChart, etc.) to avoid conflicts.

Test in the live preview before saving. HTML Macro's side-by-side preview shows you exactly what Confluence page visitors will see — including CDN scripts loading.

A Note on the CDN Whitelist

Your admin needs to whitelist https://cdn.jsdelivr.net in HTML Macro's security settings for the Chart.js scripts to load. If the charts appear blank, that's the most common cause. Check the browser console for a CSP error and confirm the domain is in the allowlist.

For environments where all external CDNs are blocked, you can paste the minified Chart.js source directly into the <script> tag — it's about 60KB minified, which is manageable.

Install HTML Macro for Confluence — free on the Atlassian Marketplace

How to Sync Docs from GitHub to Confluence Automatically

Yamuno — Wed, 10 Jun 2026 11:40:41 +0000

How to Sync Docs from GitHub to Confluence Automatically

Documentation drift is one of the most common problems in engineering teams. The markdown files in your GitHub repo are accurate — they're updated as part of the same PR that changes the code. The Confluence pages that were supposed to mirror them were last updated six months ago by someone who has since left the team.

This guide shows how to wire GitHub and Confluence together so your repo is the single source of truth and Confluence stays in sync automatically, without anyone manually copying content between the two.

The Setup

The approach uses the Markdown Importer for Confluence REST API combined with a GitHub Actions workflow. When a push lands on your main branch, the workflow calls the API to import the updated markdown files into the right Confluence pages.

You need:

Markdown Importer for Confluence installed on your Confluence Cloud instance
A Confluence API token
A GitHub repository with markdown documentation

Step 1 — Generate a Confluence API Token

Go to id.atlassian.com/manage-profile/security/api-tokens
Click Create API token
Give it a name ("GitHub Actions — Confluence Sync")
Copy the token immediately — it's only shown once

Store it as a GitHub Actions secret: CONFLUENCE_API_TOKEN. Also store your Confluence email as CONFLUENCE_EMAIL and your Confluence base URL as CONFLUENCE_BASE_URL.

Step 2 — Find the Target Page ID

Each import needs a target Confluence page ID — the parent page where the markdown will be created or updated.

To find a page ID:

Open the target Confluence page
Click ••• → Page Information
The ID is in the URL: ...confluence/pages/edit-v2/123456789

Or use the Confluence REST API:

GET https://your-instance.atlassian.net/wiki/rest/api/content?title=Your+Page+Name&spaceKey=YOURSPACE

Store the page ID as a GitHub Actions variable (CONFLUENCE_PAGE_ID).

Step 3 — Create the GitHub Actions Workflow

Create .github/workflows/sync-docs-to-confluence.yml:

name: Sync Docs to Confluence

on:
  push:
    branches:
      - main
    paths:
      - 'docs/**'

jobs:
  sync:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Zip docs folder
        run: zip -r docs.zip docs/

      - name: Import to Confluence
        run: |
          curl -X POST \
            "https://your-instance.atlassian.net/wiki/rest/api/content/${{ vars.CONFLUENCE_PAGE_ID }}/child/page" \
            -u "${{ secrets.CONFLUENCE_EMAIL }}:${{ secrets.CONFLUENCE_API_TOKEN }}" \
            -H "Content-Type: multipart/form-data" \
            -F "file=@docs.zip" \
            -F "pageHierarchy=true" \
            -F "overwrite=true"

The paths filter means the workflow only triggers when files inside docs/ change — not on every push to main.

Step 4 — Use the Markdown Importer REST API Directly

The Markdown Importer REST API gives you more control than the UI. The key endpoint for automation:

POST /wiki/rest/atlassian-connect/1/addons/com.yamuno.markdown-importer/resources/api/import

Request body (multipart/form-data):

Field	Value
`file`	ZIP archive of markdown files
`parentPageId`	Target parent page ID
`spaceKey`	Target Confluence space key
`pageHierarchy`	`true` to preserve folder structure as page hierarchy
`overwrite`	`true` to update existing pages instead of creating duplicates

Authentication: HTTP Basic — email + API token.

A more complete workflow that handles individual files:

#!/bin/bash
# sync-to-confluence.sh

BASE_URL="${CONFLUENCE_BASE_URL}"
EMAIL="${CONFLUENCE_EMAIL}"
TOKEN="${CONFLUENCE_API_TOKEN}"
PAGE_ID="${CONFLUENCE_PAGE_ID}"
SPACE_KEY="${CONFLUENCE_SPACE_KEY}"

# Create ZIP from docs folder
zip -r docs.zip docs/

# Call the import API
curl -s -X POST \
  "${BASE_URL}/wiki/rest/atlassian-connect/1/addons/com.yamuno.markdown-importer/resources/api/import" \
  -u "${EMAIL}:${TOKEN}" \
  -F "file=@docs.zip" \
  -F "parentPageId=${PAGE_ID}" \
  -F "spaceKey=${SPACE_KEY}" \
  -F "pageHierarchy=true" \
  -F "overwrite=true" \
  | jq '.'

Step 5 — Preserve Folder Structure as Confluence Hierarchy

If your docs folder looks like this:

docs/
├── getting-started.md
├── installation.md
├── how-to/
│   ├── first-steps.md
│   └── advanced-usage.md
└── reference/
    ├── api.md
    └── config.md

With pageHierarchy=true, the importer creates a matching Confluence page tree:

Getting Started
Installation
How To
  ├── First Steps
  └── Advanced Usage
Reference
  ├── API
  └── Config

Each folder becomes a parent page. The markdown file names become page titles (with hyphens replaced by spaces and the first letter capitalized).

Step 6 — Handle Frontmatter

Markdown Importer reads YAML frontmatter and uses it to set page metadata:

---
title: "API Reference"
---

If a title field is present, the importer uses it as the Confluence page title instead of the filename. This lets you have api.md in the repo but "API Reference" as the Confluence page title.

Other frontmatter fields are ignored for the import but preserved if you export back to markdown.

Testing the Workflow

Push a small change to a doc file on main and watch the Actions tab in GitHub. The workflow should:

Trigger on the push event
Zip the docs folder
Call the import API
Return a 200 with the list of pages created or updated

Check Confluence to confirm the pages reflect the changes. The first import creates the pages; subsequent imports update them in place (because overwrite=true).

Common Patterns

Sync only changed files: Use git diff --name-only HEAD~1 HEAD -- docs/ in the workflow to identify which files changed, then import just those files instead of the full folder. Faster and avoids unnecessary Confluence page updates.

Multiple doc sources: Run the import step multiple times with different source folders and target page IDs. You can sync docs/public/ to a customer-facing space and docs/internal/ to an internal space in the same workflow.

Preview before merging: Add the sync workflow to pull request branches targeting a staging Confluence space. Reviewers can check how the docs render in Confluence before the PR merges.

Result

Once the workflow is running, your documentation process is:

Edit markdown in the repo
Open a PR, get it reviewed, merge
Confluence updates automatically within minutes

No manual copying. No drift. The engineers writing the code are the same people keeping the docs current — because it's the same commit.

Install Markdown Importer for Confluence →

Read the REST API documentation →

How to Create Custom PDF Templates in Confluence

Yamuno — Sat, 06 Jun 2026 10:07:14 +0000

How to Create Custom PDF Templates in Confluence

If your team exports Confluence pages to PDF regularly, you've probably run into this problem: every export looks different. One person adds a cover page, another doesn't. Headers are inconsistent. Some PDFs have page numbers, others don't. When the document goes to a client or a regulator, it looks like it came from three different organizations.

The fix is a shared template. Create it once, and every export from the instance uses it automatically — no manual configuration each time.

This guide covers how to set up PDF export templates in Confluence using PDF Exporter for Confluence.

Prerequisites

PDF Exporter for Confluence installed from the Atlassian Marketplace
Confluence admin access (templates are configured in Confluence Settings)

Regular users can apply templates but cannot create or edit them.

Step 1 — Open Template Management

Go to Confluence Settings (gear icon, top-right)
In the left sidebar, find PDF Exporter
Click Templates

You'll see the template list. New instances have three built-in templates: Default, Report, and Minimal. You can edit these or create new ones.

Step 2 — Create a New Template

Click New Template and give it a name. Use something descriptive — "Client Deliverable," "Internal Report," "Compliance Archive" — so team members know which template to pick.

Add an optional description explaining when to use this template.

Step 3 — Configure Page Layout

Under Page Layout, set:

Page Size — A4 for international use, Letter for North America, Legal for formal legal documents
Orientation — Portrait for most documentation, Landscape for wide tables or diagrams
Font Size — Medium is the default and works for most use cases; Large if the document will be read on screen rather than printed

Step 4 — Set Up the Cover Page

Cover pages are one of the most visible differences between a professional-looking PDF and a bare export. Turn them on under Cover Page.

Style options:

Style	When to use
Classic	General internal documents
Corporate	Client-facing deliverables with a formal tone
Modern	Product documentation with a contemporary feel
Executive	Board reports, executive summaries
Bold	Team-facing reports where visual impact matters
Minimal	When you only need the title and author, no decoration

Customization:

Accent Color — set a hex value to match your brand palette. The default is Yamuno purple (#504DC4); change it to your company's primary color
Subtitle — optional text below the page title (e.g., "Confidential — Not for Distribution" or "Version 2.1")
Author — appears on the cover. Use a team name ("Solutions Engineering") rather than a person's name if the template will be shared
Logo — upload a PNG, JPG, or SVG. The logo is stored per template and appears on the cover automatically

The template editor shows a live preview as you configure, so you can see exactly how the cover will look before saving.

Step 5 — Configure Headers and Footers

Headers and footers appear on every content page (not the cover).

Header:

Enable it and add text — typically a document title, project name, or team name
Position: Left, Center, or Right

Footer:

Enable it and add text — typically a confidentiality notice, date, or department name
Position: Left, Center, or Right

Page Numbers:

Enable separately from the footer
Format options: 1, 1 / 10, or Page 1 of 10
Position: Left, Center, or Right

A common layout: document title centered in the header, page numbers right-aligned in the footer, confidentiality notice left-aligned in the footer.

Step 6 — Add a Watermark (Optional)

Watermarks are useful for draft reviews, confidential documents, or compliance archives.

Enable Watermark, enter the text (e.g., "DRAFT," "CONFIDENTIAL," "FOR REVIEW ONLY"), and set the opacity. The default opacity of 0.15 is visible without dominating the content. Go lower for a more subtle mark, higher if the watermark needs to be unmissable.

Step 7 — Table of Contents

For multi-page exports, a table of contents makes the document navigable.

Enable Table of Contents and set the depth:

Depth 1: H1 headings only
Depth 2: H1 and H2
Depth 3: H1, H2, and H3

For technical documentation, Depth 2 is usually the right balance. Depth 3 can make the TOC longer than some sections.

Step 8 — Page Breaks

Under Page Breaks, you can configure the exporter to insert automatic page breaks before H1 and/or H2 headings. This keeps major sections starting on a fresh page, which looks significantly cleaner in multi-topic exports.

Enable "Break before H1" at minimum. Enable "Break before H2" for documents with long subsections.

Step 9 — Save and Test

Click Save. The template is immediately available to all users on the Confluence instance.

To verify it works:

Navigate to any Confluence page
Click ••• → Export to PDF
Select your new template from the dropdown
Use the Preview option before downloading

Check the cover page, headers, and watermark. If anything looks off, go back to Settings → PDF Exporter → Templates → Edit.

Managing Multiple Templates

For most teams, two or three templates covers the range of use cases:

Client-facing — cover page (Corporate style), branded header, confidentiality footer, page numbers, no watermark
Internal draft — cover page (Minimal), watermark "DRAFT," page numbers
Compliance archive — cover page (Executive), watermark "ARCHIVED," page numbers, department footer

Archive templates you no longer want used (rather than deleting them) — the Archive option hides them from user dropdowns while preserving the settings for reference.

Result

Once your templates are set up, the export workflow for every user is:

Open the page → ••• → Export to PDF
Pick a template
Click Export

No formatting decisions. No inconsistent output. The same cover, the same header, the same page layout — every time.

Install PDF Exporter for Confluence →

Read the documentation →

Best Jira Dashboard Widgets and Charts in 2026

Yamuno — Tue, 02 Jun 2026 12:06:39 +0000

Best Jira Dashboard Widgets and Charts in 2026

Most Jira dashboards fail the same way: too many gadgets, none of them useful. A pie chart of issue types nobody asked for. A filter results table showing 200 tickets. A sprint burndown that's three sprints out of date.

The best dashboards answer one or two specific questions for a specific audience. This guide covers the widgets and chart types that consistently deliver value — and the setups that make them useful in practice.

The Right Frame Before You Start

Before picking any widget, decide who the dashboard is for and what decision it needs to support.

A dashboard for a sprint team answers: "Are we on track this week?" It needs velocity, blocked issues, and scope change.

A dashboard for an engineering manager answers: "Where are the bottlenecks?" It needs cycle time, work in progress by assignee, and escalated bugs.

A dashboard for a product stakeholder answers: "What shipped and what's coming?" It needs release status, feature progress, and open defects.

If you try to serve all three audiences on one dashboard, you serve none of them.

Bar Chart — Issue Distribution by Status or Assignee

Best for: Sprint planning, workload reviews, standup summaries.

A bar chart with issues grouped by status (To Do / In Progress / In Review / Done) gives you the distribution at a glance. When combined with a sprint or fix version filter, it answers "where is everything right now?" in one view.

Grouped by assignee, the same chart becomes a workload visualization. If one person has 18 open issues and another has 3, that's visible immediately — no one needs to pull a report.

Setup in Charts for Jira Dashboard:

Chart type: Bar
Group by: Status or Assignee
Filter: Current sprint or active fix version
Orientation: Horizontal for assignee view (names read better)

Line Chart — Velocity Trend Over Time

Best for: Sprint retrospectives, capacity planning, stakeholder updates.

A single sprint's velocity is nearly meaningless. A six-sprint trend tells you whether the team is improving, declining, or stable. That context is what makes capacity planning possible.

Set the X-axis to sprint and the Y-axis to story points completed. Add a trend line. The slope tells you more than any individual data point.

What to avoid: Reporting velocity in isolation without noting team size changes. A jump in velocity after two people joined isn't an improvement — it's headcount. Track points per person if you want a clean signal.

Setup:

Chart type: Line
X-axis: Sprint
Y-axis: Story points (completed)
Enable: Trend line
Filter: Last 6–8 sprints

Pie Chart — Issue Type or Priority Breakdown

Best for: Bug triage, backlog health checks, executive summaries.

Pie charts are often overused but have a legitimate place for proportion data. The question "what percentage of open work is bugs vs. features vs. tech debt?" is a proportion question — a pie chart answers it directly.

Keep it to five slices or fewer. Beyond that, the chart becomes a color matching exercise.

Setup:

Chart type: Pie
Group by: Issue type or Priority
Filter: Open issues in the relevant project
Labels: Show percentages

Area Chart — Cumulative Flow

Best for: Identifying bottlenecks, WIP limit enforcement, kanban teams.

A cumulative flow diagram shows how issues accumulate and drain through each status over time. When one band (say "In Review") grows noticeably wider, it means work is piling up there — a bottleneck you can address before it delays the sprint.

This is the most analytically powerful chart on this list and the one teams are most likely to underuse.

Setup:

Chart type: Area (stacked)
X-axis: Date
Y-axis: Issue count
Group by: Status
Filter: Active sprint or last 30 days

Scatter Chart — Effort vs. Completion Time

Best for: Estimation calibration, cycle time analysis.

Plot story points on the X-axis and actual days to complete on the Y-axis. Each issue is a dot. What you're looking for: are small-point issues actually completing faster? Are there outliers — high-point issues that took surprisingly little time, or vice versa?

This chart is most useful for teams trying to improve their estimation accuracy. After a few sprints, the pattern (or lack of one) tells you whether your point scale correlates with actual effort.

Setup:

Chart type: Scatter
X-axis: Story points
Y-axis: Cycle time (days)
Filter: Completed issues, last 3 months

Table View — Blocked Issues and Escalations

Best for: Daily standup, impediment tracking, management escalation.

Sometimes you don't need a visualization — you need a list. A table filtered to "Blocked" issues with columns for assignee, block reason, and days blocked is more actionable in a standup than any chart.

Setup:

View type: Table
Filter: Status = Blocked, or Label = "escalated"
Columns: Issue key, Summary, Assignee, Days open
Sort: Days open (descending)

One Dashboard, One Audience

The practical setup that works: one dashboard per team type, pinned as the default for that team's Jira project.

Sprint team: Velocity line + status bar + blocked table
Engineering manager: Workload bar + cumulative flow area + cycle time scatter
Product stakeholder: Release progress bar + priority pie + escalation table

Each dashboard has three gadgets. Three is usually enough. If you need a fourth, something on the existing board isn't earning its space.

Getting Started

Charts - Reports and Graphs for Jira Dashboard is available on the Atlassian Marketplace. Add it to any Jira dashboard gadget, choose your chart type, connect it to a project or JQL filter, and it renders immediately from your live Jira data.

Install Charts for Jira Dashboard →

How Finance Teams Document Quantitative Models in Confluence

Yamuno — Fri, 29 May 2026 11:32:11 +0000

How Finance Teams Document Quantitative Models in Confluence

Most quantitative model documentation is a mess — not because quants don't care about documentation, but because the tools for writing math and the tools for sharing knowledge with a team don't overlap.

The model lives in Python or R. The derivations live in a LaTeX PDF that took three days to write and is now orphaned in a shared drive folder nobody navigates. The assumptions are in a Word document last edited in 2023. The backtesting results are in Excel. A new analyst joining the team has to reconstruct the model's intent by reading code comments and asking questions.

Confluence is where team knowledge should live. But until recently, Confluence had no good way to write actual math — which meant quant teams had the choice between prose approximations that lose precision, or screenshots of equations that become wrong the moment the model changes.

What Quantitative Model Documentation Should Include

Good model documentation isn't just the formula. It's the context that makes the formula meaningful to someone who didn't build it.

Model purpose and scope — what decision this model informs, what asset class or portfolio it applies to, and what it explicitly does not cover. This section is often skipped and is often the most important.

Assumptions — every model has them. Write them down explicitly. Which distributional assumptions are you making? What market conditions does the model assume? Where does it break down?

Formula derivation — the derivation from first principles, or a clear reference to where that derivation lives. Not just the final formula, but why it takes that form.

Input and output specification — what goes in, what comes out, what units, what frequency, what data sources. A table is cleaner than prose here.

Backtesting and validation results — summary statistics, time period, benchmark comparison. These change as you re-run validation; note the date.

Limitations and known failure modes — where the model underperforms, what conditions make it unreliable, what it should not be used for. This is the section that protects the team.

Version and change history — when the model was last updated, what changed, and why.

Writing Formulas in Confluence with LaTeX

LaTeX Math for Confluence adds a /latex macro to Confluence that renders LaTeX equations live on the page. Type the macro, write the LaTeX source, and the rendered equation appears — inline or as a block. No screenshots, no external editors, no export-and-upload cycle.

Here's what real quant model documentation looks like with it.

Option Pricing: Black-Scholes

The Black-Scholes formula for a European call option:

C = S_0 \, N(d_1) - K e^{-rT} N(d_2)

Where:

d_1 = \frac{\ln(S_0 / K) + (r + \tfrac{1}{2}\sigma^2)T}{\sigma\sqrt{T}}
\qquad
d_2 = d_1 - \sigma\sqrt{T}

And $N(\cdot)$ is the standard normal CDF. Documenting the variable definitions inline is straightforward — you can mix inline LaTeX like $S_0$ (current price), $K$ (strike), $r$ (risk-free rate), $\sigma$ (volatility), $T$ (time to expiry) into a paragraph without switching formats.

Portfolio Risk: Variance and Volatility

Portfolio variance for a two-asset portfolio:

\sigma_p^2 = w_1^2 \sigma_1^2 + w_2^2 \sigma_2^2 + 2 w_1 w_2 \sigma_1 \sigma_2 \rho_{12}

Generalised to $n$ assets using the covariance matrix $\Sigma$:

\sigma_p^2 = \mathbf{w}^\top \Sigma \, \mathbf{w}

Where $\mathbf{w}$ is the vector of portfolio weights. This is the kind of expression that, written in plain text, requires three sentences to explain what a single line of math conveys unambiguously.

Performance Metrics: Sharpe and Sortino Ratios

Sharpe ratio:

S = \frac{\mathbb{E}[R_p - R_f]}{\sigma_p}

Sortino ratio, which penalises only downside volatility:

\text{Sortino} = \frac{\mathbb{E}[R_p - R_f]}{\sigma_d}
\qquad
\sigma_d = \sqrt{\mathbb{E}\left[\min(R_p - R_f,\, 0)^2\right]}

Documenting both on the same page with their formulas makes clear why you might prefer one over the other for a strategy with asymmetric return distributions — which is precisely the kind of reasoning that should be captured in model documentation.

Risk Models: Value at Risk

Parametric VaR at confidence level $\alpha$:

\text{VaR}_\alpha = \mu_p - z_\alpha \, \sigma_p

Historical simulation VaR — defined as the $(1-\alpha)$ quantile of the empirical return distribution ${r_t}_{t=1}^T$:

\text{VaR}_\alpha = -Q_{1-\alpha}\left(\{r_t\}\right)

Conditional VaR (Expected Shortfall):

\text{CVaR}_\alpha = -\mathbb{E}\left[R \mid R \leq -\text{VaR}_\alpha\right]

These three measures are often discussed together but have meaningfully different properties in tail events. Having all three on one page with their exact definitions eliminates the ambiguity that shows up in verbal descriptions.

Fixed Income: Duration and Convexity

Modified duration:

D_{mod} = -\frac{1}{P} \frac{dP}{dy} = \frac{D_{mac}}{1 + y/m}

Where $D_{mac}$ is Macaulay duration, $y$ is yield to maturity, and $m$ is the number of coupon periods per year.

Convexity:

C = \frac{1}{P} \frac{d^2P}{dy^2}

Price change approximation incorporating both:

\frac{\Delta P}{P} \approx -D_{mod} \cdot \Delta y + \frac{1}{2} C \cdot (\Delta y)^2

Structuring a Model Documentation Page in Confluence

A consistent page template makes model docs easier to write and easier to audit. Here's a structure that works:

Model: [Model Name]
├── 1. Overview
│   ├── Purpose
│   ├── Scope and applicable instruments
│   └── Owner and last review date
├── 2. Assumptions
│   └── Numbered list — be specific
├── 3. Model Specification
│   ├── Notation table (define every symbol)
│   ├── Derivation (or reference)
│   └── Final formula(s) as block equations
├── 4. Inputs and Outputs
│   └── Table: variable, type, source, frequency
├── 5. Implementation Notes
│   ├── Code reference (link to repo/file)
│   └── Numerical considerations (overflow, precision)
├── 6. Validation and Backtesting
│   ├── Methodology
│   ├── Time period
│   └── Results summary (table)
├── 7. Limitations
│   └── Explicit failure modes
└── 8. Change Log
    └── Date | Change | Author

The notation table in section 3 is often skipped and almost always needed. Every symbol used in the formulas should appear in a table with its definition, units, and typical range. A reader who wasn't in the original modelling sessions shouldn't have to guess what $\lambda$ refers to.

Keeping Model Documentation Up to Date

Model documentation drifts for the same reason all documentation drifts: updating it is a separate step from updating the model.

A few practices that help:

Treat the Confluence page as part of the model. Link to it from the code repository — a comment in the main model file pointing to the Confluence page URL. When a developer opens the file to make changes, the docs link is visible.

Add a documentation review step to your model validation process. Most quant teams already have a formal model validation workflow. Add a checkpoint: has the Confluence page been updated to match the current implementation?

Use the change log section. It doesn't need to be exhaustive — a one-line entry per model update (date, what changed, who changed it) is enough to give future readers context. This is much cheaper to maintain than reconstructing history from git blame.

Keep equations as LaTeX source, not images. The point of using LaTeX Math for Confluence is that the source is editable in place. When a formula changes, you edit the LaTeX directly on the Confluence page — two minutes of work, not an export-and-upload cycle. That lower friction is what makes it realistic to keep docs in sync.

Getting Started

Install LaTeX Math for Confluence from the Atlassian Marketplace. On any Confluence page, type /latex to insert a block equation or use the inline variant for in-paragraph math.

Full documentation is at LaTeX Math for Confluence docs.

Questions? Reach out via our support portal.

How to Use Confluence as a Developer Wiki

Yamuno — Sat, 23 May 2026 09:56:30 +0000

How to Use Confluence as a Developer Wiki

Confluence has a reputation problem with developers. It's slow. The editor is clunky. Markdown support used to be nonexistent. Half the team wants to write docs in GitHub, the other half uses Notion, and Confluence ends up as a graveyard of stale meeting notes and quarterly plans nobody reads.

That reputation is partially deserved and partially outdated. There are cases where Confluence is genuinely the right choice for a developer wiki — and when it is, there's a right way to set it up so developers will actually use it.

When Confluence Makes Sense for Developers

Don't reach for Confluence just because your company already has a license. Use it when these conditions are true:

Your team already uses Jira. The Jira ↔ Confluence integration is genuinely useful — linking a runbook to an incident, embedding a sprint's Jira issues in a planning page, referencing an ADR from a ticket. If your team lives in Jira, having docs one click away is real value.

You need docs linked to project history. GitHub wikis are disconnected from non-code work. Notion has no Jira integration worth mentioning. Confluence lets you tie documentation to the projects, releases, and sprints that produced it.

Compliance or audit requirements exist. If your team needs documented approval workflows, page history with authors and timestamps, or access controls on specific documentation, Confluence handles this natively. Most alternatives don't.

Your organization is large enough that discoverability matters. In a 10-person team, everyone knows where docs live. In a 200-person engineering organization, cross-team search across a unified Confluence instance is worth a lot. Fragmented Notion workspaces and GitHub wikis across dozens of repos don't have that.

If none of these apply, Notion or a docs-as-code approach (MDX files in a repo, rendered with a tool like Docusaurus) is probably the better call. Confluence is not the right tool for every team.

How to Structure a Developer Wiki in Confluence

The most common failure mode is dumping everything into one space with no structure. Within a year it's unsearchable. The second failure mode is over-structuring — five levels of nesting that nobody can navigate.

A practical structure for an engineering team's Confluence space:

Engineering (space root)
├── Onboarding
│   ├── New Engineer Setup
│   ├── Development Environment
│   ├── Access & Permissions Request
│   └── First Week Checklist
├── Architecture
│   ├── System Overview
│   ├── Architecture Decision Records (ADRs)
│   │   ├── ADR-001: Use PostgreSQL for primary storage
│   │   ├── ADR-002: Adopt event-driven architecture
│   │   └── ADR-003: ...
│   └── Data Flow Diagrams
├── Services
│   ├── auth-service
│   │   ├── Overview & Runbook
│   │   ├── API Reference
│   │   └── Known Issues
│   └── payments-service
│       └── ...
├── Runbooks
│   ├── Incident Response
│   ├── Database Failover
│   ├── Deployment Rollback
│   └── On-Call Handoff Template
├── Incident Postmortems
│   ├── 2026-04-12 Payment Processing Outage
│   └── 2026-03-07 Auth Service Latency Spike
└── Release Notes
    └── (one page per release or sprint)

A few principles behind this structure:

Runbooks get their own section — not buried under individual services. When something is on fire at 2am, you want fast access without knowing which service owns the runbook.

ADRs live in Architecture and follow a consistent template (context, decision, consequences). They're written once and rarely updated — that's fine, they're meant to capture a decision at a point in time.

Incident Postmortems are first-class content. Don't hide them or let them expire. They're the most valuable institutional knowledge a team produces.

Services have a lightweight, consistent structure — not every possible sub-page, just overview, runbook, and API reference at minimum.

Making Confluence Actually Dev-Friendly

The editor is where most developers tap out. The default Confluence editor is fine for business users writing prose, but it's friction for developers who think in markdown.

Markdown support. Markdown Renderer for Confluence lets you write and maintain Confluence pages in pure markdown — including fenced code blocks with syntax highlighting, tables written as markdown tables, and inline formatting that looks exactly like it does in a README. No dealing with the visual editor for technical content.

Importing existing docs. If your team already has markdown documentation in a GitHub repo or a folder of .md files, Markdown Importer for Confluence can pull those in directly — preserving heading hierarchy, code blocks, internal links, and images — without a manual copy-paste operation for each file. For teams migrating from a GitHub wiki or a docs folder, this is the fastest path.

Code blocks. Confluence has native code block macros. Use them. Always specify the language. Unformatted terminal output and code snippets in regular text boxes are unusable.

Labels and page properties. Use labels consistently (e.g., runbook, adr, postmortem, service:auth) and you get free filtering. The Confluence built-in page properties macro lets you build tables that auto-populate from child pages — useful for a service catalog or ADR index.

What Not to Do

Don't put everything in Confluence. Real-time communication belongs in Slack. Code review discussion belongs in GitHub. Work-in-progress thinking belongs in personal notes. Confluence is for stable, findable reference material — runbooks, specs, decisions, and onboarding docs. If it's likely to change daily, it probably shouldn't be in Confluence.

Don't create pages without linking them to Jira. The Jira integration is the main reason to choose Confluence over alternatives. If you're writing an ADR for a significant architecture decision, link it to the epic. If you're writing a runbook for a service, link the relevant Confluence page from the Jira project. Orphaned documentation gets stale because nobody finds it.

Don't make pages too long. Confluence has no natural incentive to keep pages short. A 10,000-word page that should be five linked pages is common and terrible. If you're scrolling for more than two screens to find what you need, split the page.

Don't treat Confluence as a ticket system. Action items and tasks go in Jira. Using Confluence pages to track work that should be in a Jira board is how you end up with two half-maintained systems instead of one.

An Honest Assessment

Confluence is a real tradeoff. The editor is slower than a markdown file in VS Code. Search is good but not great for code snippets. Free-tier teams will find the cost steep. And it requires active maintenance — without someone periodically reviewing and archiving stale pages, it degrades into a documentation graveyard.

What it's genuinely better at: stable, findable reference documentation for teams inside larger organizations that already run Jira. If that describes your situation, invest in a clear structure from day one, get markdown support in place so developers don't fight the editor, and keep the scope tight. A small, well-maintained Confluence space beats a large, neglected one every time.

Questions? Reach out via our support portal.

How to Document APIs in Confluence

Yamuno — Wed, 20 May 2026 10:53:44 +0000

How to Document APIs in Confluence

API docs fail for the same reasons every time: they live in too many places, nobody owns them, and updating them feels optional.

The Postman collection is the real reference. The Swagger file is six months behind the code. The Confluence page was accurate once. The README has a curl example that stopped working in v2. Developers new to the codebase have to triangulate between all of them and ask a colleague anyway.

Centralizing API documentation in Confluence doesn't fix all of this automatically — but it gives you a single place to link from everywhere else, and the right structure makes it far easier to keep up to date.

Why API Documentation Gets Stale

The core problem isn't that people are lazy. It's that documentation lives in a different tool than the code, so every change requires two actions: update the code, then update the docs. That second step gets skipped when deadlines are tight, and it never catches up.

Secondary problems layer on top:

No clear owner. The developer who built it moves on. Nobody else knows enough to update it confidently.
Wrong format. Prose descriptions of request bodies are ambiguous. Code examples with no explanation assume too much. A mix of both with no consistent structure is the worst of both worlds.
Swagger/OpenAPI as the only source. Auto-generated docs show you what the API does, not why, what the gotchas are, or what the actual production behavior looks like in edge cases.

Good API documentation combines auto-generated spec output with hand-written context. Confluence is where the hand-written context should live.

What Good API Documentation Includes

For each API (or logical group of endpoints), your documentation should cover:

Authentication and authorization — how to get credentials, token lifetime, scope requirements, which endpoints need which permissions. This is the most-asked question from new integrators and the hardest to find in auto-generated docs.

Base URL and versioning — current version, how versioning works, deprecation policy. A table showing v1/v2 differences is worth more than a paragraph.

Endpoint reference — for each endpoint: method, path, description, request parameters (path, query, header, body), example request, example response, error codes. See the template at the bottom of this post.

Error codes — a dedicated table of all error codes, what they mean, and what the caller should do about them. 400 Bad Request is not useful documentation.

Changelog — what changed between versions and when. The changelog is the first thing an existing integrator checks when something breaks after a release.

Rate limits and quotas — numbers, what triggers throttling, what the response looks like, how to handle retry.

Structuring API Docs in Confluence

A Confluence space structure that works well for a team maintaining one or more APIs:

API Documentation (space root)
├── Getting Started
│   ├── Authentication
│   ├── Rate Limits & Quotas
│   └── SDKs & Client Libraries
├── API Reference
│   ├── Users API
│   │   ├── GET /users
│   │   ├── POST /users
│   │   ├── GET /users/{id}
│   │   └── DELETE /users/{id}
│   └── Orders API
│       └── ...
├── Changelog
│   ├── v3.0.0 (2026-04-01)
│   ├── v2.5.0 (2025-12-10)
│   └── ...
└── Guides
    ├── Handling Pagination
    ├── Webhook Setup
    └── Error Handling Patterns

Keep the API Reference section flat within each API group — one page per endpoint. Deep nesting makes the sidebar useless. The Changelog and Guides sections are where you write prose; the Reference section is where you write specs.

Writing Request and Response Examples in Confluence

This is where most Confluence API docs fall apart. People write prose descriptions of JSON fields, or paste unformatted request examples that are impossible to scan.

The right approach is structured code blocks with clear labels. Markdown Renderer for Confluence lets you write these directly in markdown on any Confluence page — including fenced code blocks with language hints that render with syntax highlighting.

A request example written in markdown on a Confluence page:

**Request**

http
POST /v3/orders
Authorization: Bearer {token}
Content-Type: application/json

{
"customer_id": "cus_8f3k2",
"items": [
{ "sku": "WIDGET-001", "quantity": 2 },
{ "sku": "GADGET-042", "quantity": 1 }
],
"shipping_address": {
"line1": "123 Main St",
"city": "Austin",
"state": "TX",
"zip": "78701"
}
}
`

Response — 201 Created

json { "order_id": "ord_9g4m1", "status": "pending", "created_at": "2026-05-20T14:32:00Z", "total_cents": 4799 } ``


This renders cleanly in Confluence via Markdown Renderer, and it's easy to edit. No Confluence macro hunting, no storage format XML — just write markdown.

---

## Keeping Docs in Sync with Code

The documentation drift problem doesn't go away with better structure — it needs a process fix too.

**Link the Confluence page from the code.** Add a comment in the route handler or controller pointing to the Confluence page. When a developer changes the endpoint, the link is right there.

python

POST /v3/orders

Docs: https://yourspace.atlassian.net/wiki/x/AbCdEf

@app.route("/v3/orders", methods=["POST"])
def create_order():
...


**Add the docs update to your PR checklist.** If your team uses a PR template, add a checkbox: "Updated API docs in Confluence if endpoints changed." It sounds obvious but it works.

**Use the Confluence REST API for automated updates.** For teams with documentation-as-code workflows, the Confluence REST API lets you push page updates from CI. Your OpenAPI spec can be auto-rendered into a Confluence page on every merge to main, and the hand-written context pages stay separate and stable.

bash

Update a Confluence page via REST API

curl -X PUT \
"https://yoursite.atlassian.net/wiki/rest/api/content/{pageId}" \
-H "Authorization: Bearer $CONFLUENCE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"version": { "number": 12 },
"title": "GET /users/{id}",
"type": "page",
"body": {
"storage": {
"value": "

Updated content here

",
"representation": "storage"
}
}
}'


---

## Page Template: API Endpoint Reference

Here's a practical template for a single endpoint page. Copy it, fill it in, repeat per endpoint.

markdown

Overview

Brief description of what this endpoint does and when to use it.

Request

Method & Path: POST /v3/users

Authentication: Bearer token required. Scope: users:write

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer {token}`
`Content-Type`	Yes	`application/json`

Body Parameters

Field	Type	Required	Description
`email`	string	Yes	User's email address
`name`	string	Yes	Display name
`role`	string	No	One of: `admin`, `member`, `viewer`. Default: `member`

Example Request

POST /v3/users
Authorization: Bearer eyJhb...
Content-Type: application/json

{
  "email": "alex@example.com",
  "name": "Alex Kim",
  "role": "member"
}
` ``

## Response

### 201 Created

json
{
"user_id": "usr_7c2p9",
"email": "alex@example.com",
"name": "Alex Kim",
"role": "member",
"created_at": "2026-05-20T10:00:00Z"
}
`

Error Codes

Code	Meaning	Action
`400`	Missing required field	Check request body against schema
`409`	Email already registered	Use existing account or change email
`422`	Invalid role value	Use one of: admin, member, viewer
`429`	Rate limit exceeded	Back off and retry after `Retry-After` header

Notes

Any gotchas, rate limit specifics, or behavior that differs from the general rules.
`

Getting Started

Install Markdown Renderer for Confluence from the Atlassian Marketplace to write and edit API docs in markdown directly on Confluence pages — code blocks, tables, and all.

Questions? Reach out via our support portal.

How Engineering Teams Use Confluence Effectively

Yamuno — Fri, 15 May 2026 10:27:11 +0000

How Engineering Teams Use Confluence Effectively

Most engineering teams have a love-hate relationship with Confluence. They hate writing in it, but they rely on it when they need to find something — architecture decisions, onboarding docs, incident runbooks. The problem is that the content is usually out of date, hard to find, or both.

This post is about the structural and cultural patterns that make Confluence actually work for engineering teams — not just as a place to store things, but as a resource people actively use.

Why Engineering Documentation Fails

Before talking about what works, it's worth being honest about why it usually doesn't.

Docs Written Once, Never Touched Again

The most common failure mode: documentation is written at project kick-off or system launch, never updated, and goes stale within a quarter. Engineers stop trusting it. When they stop trusting it, they stop reading it. When they stop reading it, nobody updates it because nobody's reading it.

Stale documentation is worse than no documentation in one specific way: it creates false confidence. A runbook that worked 18 months ago and has been superseded by infrastructure changes will mislead the on-call engineer who follows it.

No Structure, Everything in Tickets

Jira tickets are not documentation. They capture decisions in the context of a sprint, not in a form that's navigable six months later. Teams that default to "it's all in the tickets" are actually defaulting to "we have no documentation."

Tickets are ephemeral by design. Documentation needs to be durable.

Flat Spaces With No Hierarchy

A Confluence space with 300 pages at the root level is a search problem disguised as a documentation problem. If the only way to find something is to know its exact title and search for it, your information architecture has failed.

What High-Performing Teams Do Differently

One Space Per Team or Service

The clearest organizing principle that works at scale: one Confluence space per team or service domain, not per project or initiative.

Projects come and go. Teams and services are durable. If your documentation is organized around projects, it fragments and orphans over time. If it's organized around teams, there's always a clear owner and a natural home for new content.

A backend services team might have one space. Inside that space: onboarding, system architecture, runbooks, ADRs, deployment guides. Every page has a clear home because every page belongs to the team, not to a project that ended.

Clear Page Templates

Consistency reduces the activation energy for writing documentation. When engineers have to invent the structure from scratch, many just don't. When there's a template, the blank page is already half-filled.

Useful templates for engineering teams:

RFC (Request for Comments) — for proposing significant changes before implementation. Sections: Background, Proposal, Alternatives Considered, Open Questions, Decision. The goal is to force structured thinking before anyone writes code.

ADR (Architecture Decision Record) — for recording decisions after they're made. Shorter than an RFC. Sections: Context, Decision, Status, Consequences. ADRs are valuable specifically because they capture the why, not just the what.

Runbook — for operational procedures. Sections: Purpose, When to Use This, Prerequisites, Steps, Rollback, Escalation. A runbook that doesn't have a rollback section isn't complete.

Incident Post-Mortem — for documenting what went wrong, why, and what changes. Sections: Timeline, Root Cause, Contributing Factors, Action Items. No blame, lots of specificity.

Create these as Confluence templates in your space. When someone creates a new page and selects the template, the structure is there immediately.

Linking Jira and Confluence Intentionally

Confluence and Jira are designed to interoperate, but most teams use them in parallel rather than together. The patterns that work:

Link Jira epics to Confluence specs. When you start planning a significant feature, create the Confluence RFC or spec first, then link it from the Jira epic. Every engineer who opens that epic can navigate to the detailed context without searching.

Link Confluence runbooks to Jira service requests. If your team uses Jira Service Management, link the relevant runbooks to request types. On-call engineers get the runbook in context, not as a bookmark to remember.

Reference ADRs from Jira epics that implement them. When a decision is made and recorded as an ADR, link it from every Jira epic that implements or is affected by it. This gives future engineers the context for why things are built the way they are.

These links don't take long to add and pay significant dividends when someone is debugging or onboarding six months later.

Writing Docs Engineers Will Actually Read

The content matters as much as the structure. Documentation that engineers actually read shares a few traits:

Short and Specific

Documentation that tries to cover everything is documentation nobody reads. A runbook should cover exactly what it says it covers. An ADR should explain the decision, not the entire history of the system.

Write for the person who has a specific question, not the person who's reading from the beginning.

Code-First Where Relevant

For engineering documentation, showing beats telling. If you're documenting how to configure a service, show the config file. If you're documenting an API, show the request and response. If you're documenting a deployment process, show the commands.

# Deploy to staging
git tag -a v1.4.2 -m "Release v1.4.2"
git push origin v1.4.2
# CI picks up the tag and deploys automatically
# Monitor at: https://grafana.internal/d/deploy-status

This is clearer and more useful than three paragraphs describing the same process.

Acknowledge When Things Are Outdated

Teams that add a "Last verified: [date]" note to runbooks and architecture docs create a signal that helps readers calibrate. A runbook last verified six months ago warrants more skepticism than one verified last week. It also creates a natural trigger for review — if you see a last-verified date that's too old, update it when you next use the doc.

Markdown-Friendly

Engineers are comfortable with markdown. They use it in pull requests, READMEs, and issue comments. Forcing them into the Confluence rich text editor creates friction that compounds over time — small enough to ignore, large enough to matter.

Markdown Renderer for Confluence lets engineers write documentation in markdown syntax directly inside Confluence pages. The macro renders it properly — tables, code blocks, task lists — without requiring them to change their writing workflow.

For teams migrating existing documentation from GitHub wikis, Notion, or internal docs sites, Markdown Importer for Confluence handles bulk imports — preserving hierarchy, converting links, and pulling content directly from a repository URL.

The Onboarding Test

Here's a practical way to evaluate whether your Confluence space is working: give a new engineer exactly 30 minutes to find the answers to these questions using only Confluence:

How do I set up my local development environment?
Where does service X store its data, and what's the schema?
Who do I contact if the payment pipeline is down?
What was the reasoning behind the message queue architecture choice?
How do I deploy to staging?

If a new engineer can't answer these questions from your documentation in 30 minutes, the structure isn't working — regardless of whether the information technically exists somewhere.

Run this test every six months. Use the results to drive documentation sprints, not individual blame.

Keeping It Current

Documentation maintenance isn't glamorous, but it's the actual hard part. A few practices that help:

Assign page ownership. Every page in a team space should have an owner — the person responsible for keeping it current. Confluence's page properties feature can track this. Without clear ownership, pages decay by default.

Review runbooks during incidents. If you follow a runbook during an incident, update it immediately after. You have fresh context on what worked, what didn't, and what's missing. Incident reviews are the best documentation maintenance sessions you'll ever have.

Documentation as part of definition of done. If your team has a Definition of Done for Jira tickets, add "relevant documentation updated" as a criterion for anything that changes system behavior, configuration, or process. This is cultural, not technical — it requires enforcement through code review and sprint retrospectives.

Quarterly cleanup sprints. Once a quarter, allocate a half-day for the team to review and update documentation. Not create new docs — review and update existing ones. Archive pages that are no longer relevant. Fix links that are broken. Update last-verified dates.

Summary

Confluence works for engineering teams when the structure is clear (one space per team, templates for common doc types), when it's connected to Jira intentionally, and when the documentation is written the way engineers think — short, specific, code-first.

The tooling helps. Markdown support removes friction for engineers who'd rather write in a text editor. Structured import handles migrations. But the structure and discipline are the foundation. Get those right and the rest follows.

Questions? Reach out via our support portal.

Best Atlassian Marketplace Apps for Technical Documentation in 2026

Yamuno — Tue, 12 May 2026 10:34:21 +0000

Best Atlassian Marketplace Apps for Technical Documentation in 2026

Confluence out of the box is solid for general team documentation. For technical documentation specifically — API references, runbooks, architecture records, data science notebooks, engineering wikis — it has gaps. The native editor isn't built for developers, math rendering doesn't exist, and moving content in and out requires manual reformatting.

The Marketplace fills most of these gaps. This is a category-by-category look at which apps are worth installing for technical teams, covering markdown support, math/equations, HTML embeds, and attachment management.

Category 1: Markdown Support

The Problem

Developers write in markdown. Confluence doesn't speak markdown natively. This creates a translation tax — content written in a repo, a README, or a docs-as-code workflow has to be manually reformatted when it enters Confluence.

The inverse is also true: documentation written in Confluence can't easily leave it. Export options produce mediocre HTML or PDFs, not clean markdown that can live in a Git repo.

Markdown Renderer for Confluence

Markdown Renderer for Confluence adds a macro to the Confluence editor that renders markdown inline. Paste markdown into the macro body, save the page, and it renders — tables, code blocks, math, task lists, all of it. No conversion step.

This is the right tool when you want to write and maintain markdown directly inside Confluence without migrating your workflow.

Good for: developers who prefer writing in markdown, teams embedding markdown content from other sources, documentation where the source needs to stay readable as plain text.

Markdown Importer & Exporter for Confluence

Markdown Importer for Confluence & Markdown Exporter handles bulk movement of content: import a ZIP of markdown files, a GitHub repository, or a single file — and export Confluence pages back to markdown.

It preserves hierarchy (folder structure becomes page tree), converts internal links, handles frontmatter, and exposes a REST API for CI/CD pipeline integration.

Good for: migrating documentation from GitHub, GitLab, Notion, or any markdown-native source into Confluence; maintaining docs-as-code workflows where Confluence is the published output.

Other options: There are a few other markdown import tools on the Marketplace. Most are Connect-based (externally hosted), which introduces data routing concerns for teams with strict data residency requirements. Markdown Importer is Forge-native — all processing happens inside Atlassian infrastructure.

Category 2: Math and Equations

The Problem

Technical documentation for engineering, data science, and academic teams frequently needs equations. Confluence has no native math rendering. Your options without an app are: screenshots (bad for accessibility and editability), plain text approximations, or external image generators with manual embed.

LaTeX Math for Confluence

LaTeX Math for Confluence adds a Forge-native LaTeX macro that renders equations server-side. Write standard LaTeX syntax, get rendered math on the page — both inline and display (block) modes supported.

\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}

The macro handles the full LaTeX math environment: fractions, summations, integrals, matrices, Greek letters, operator names — anything in the standard math mode command set.

Good for: machine learning documentation, engineering specifications, scientific research, academic writing published to Confluence, or any technical content where equations need to be editable (not screenshots).

Other options: MathJax-based browser-side renderers exist on the Marketplace. They work, but rendering happens client-side — which can produce flash-of-unstyled-content issues and inconsistency across exported PDFs. Server-side rendering (Forge) is more reliable for documentation that needs to be exported or printed.

Category 3: Diagrams and Visuals

The Problem

Architecture diagrams, flow charts, and sequence diagrams are core to technical documentation. They need to be editable by team members, not just the original author who exported a PNG from their laptop.

What's Available

draw.io / Diagrams.net for Confluence is the dominant tool here. It's widely used, has good Confluence integration, and supports UML, BPMN, network diagrams, and general flowcharts. It's a Connect app (externally hosted by JGraph), which is worth knowing.

Gliffy is the other major option — similar capabilities, longer history in the Confluence ecosystem. Also Connect-based.

For code-based diagrams (Mermaid, PlantUML, Graphviz), there are several Forge-native apps emerging that let you write diagram definitions as text and render them inline. This fits well with docs-as-code workflows where diagrams should be version-controllable.

Yamuno doesn't currently publish a diagram app. The draw.io and Gliffy integrations are solid choices for general diagram needs.

Category 4: HTML and Code Embeds

The Problem

Some technical documentation needs custom HTML — embedded interactive demos, styled tables that go beyond Confluence's native capabilities, custom callout boxes, or content migrated from an HTML-based documentation system.

Confluence strips raw HTML by default for security reasons. The native editor provides no HTML passthrough.

HTML Macro for Confluence

HTML Macro for Confluence adds a Forge-native macro that renders raw HTML on Confluence pages. Write or paste HTML into the macro body and it renders in-page.

This is useful for:

Interactive embeds — API sandbox widgets, embedded iframes, interactive demos
Custom styled tables — when the native Confluence table editor isn't flexible enough
Migrated content — documentation originally written in HTML that needs to land in Confluence without losing formatting
Custom callout layouts — info boxes, warning panels, or custom visual elements not available natively

Security note: HTML rendering is controlled by Confluence admins. The macro respects Confluence's content security policies — scripts and external resource loading are subject to the same controls as the rest of the instance.

Category 5: Attachment Management

The Problem

Technical documentation accumulates attachments — build artifacts, design files, exported reports, architecture diagrams, release packages. Over time, Confluence spaces fill with orphaned attachments, duplicate files, and files nobody can find because there's no organization layer.

The native Confluence attachment experience is minimal: files attached to pages, a basic list view, no folder structure, no bulk operations.

Advanced Attachment Manager for Confluence

Advanced Attachment Manager for Confluence adds structured attachment management to Confluence pages — folder organization, version tracking, bulk upload/download, and better search across attachments.

Good for: teams that use Confluence pages to distribute files (release packages, build artifacts, design assets), engineering teams running design review or release management in Confluence, documentation spaces where attachments are first-class content.

How to Evaluate Marketplace Apps

Two things worth checking before installing any Marketplace app:

Forge vs Connect

Forge apps run inside Atlassian's infrastructure. Your data never routes through an external server. This matters for teams with data residency requirements, SOC 2 compliance obligations, or strict network policies.

Connect apps (labeled "server" or with an external vendor hosting model) route data through the vendor's servers. This is fine for many teams but is worth understanding upfront — especially for apps that process documentation content.

All Yamuno apps are Forge-native. On any app's Marketplace listing, the hosting model is listed under the app details.

Permissions and Scopes

Check what Confluence and Jira permissions an app requests at install time. A diagram app that requests write access to your entire Confluence space should prompt questions. Most legitimate apps request narrow, sensible scopes — if something seems excessive, read the privacy policy and check the vendor's security documentation.

Summary

Need	App
Write markdown in Confluence	Markdown Renderer for Confluence
Import/export markdown in bulk	Markdown Importer & Exporter for Confluence
LaTeX equations	LaTeX Math for Confluence
Diagrams	draw.io or Gliffy
Raw HTML embeds	HTML Macro for Confluence
Attachment organization	Advanced Attachment Manager for Confluence

All Yamuno apps are available on the Atlassian Marketplace — free to try, Forge-native.

Questions? Reach out via our support portal.

Building a Jira Dashboard That Actually Tells You Something

Yamuno — Thu, 07 May 2026 10:26:51 +0000

Building a Jira Dashboard That Actually Tells You Something

Most Jira dashboards are abandoned within a month of being created. They start with good intentions — someone sets up a few gadgets, shares the link in Slack, and declares victory. Two sprints later, nobody opens it because the numbers don't mean anything or the widgets are always stale.

The problem isn't Jira. It's that dashboards get built around what's easy to surface rather than what decisions they're supposed to support.

This post covers how to think about Jira dashboards, what metrics actually matter, and how to set up charts that a real team will check daily.

What Makes a Dashboard Useless

Before getting into what works, it's worth naming the failure modes. Most bad Jira dashboards share a few characteristics:

Too many widgets. A dashboard with 12 gadgets isn't 4x as useful as one with 3 — it's less useful because nothing stands out. If everything is visible, nothing is.

Wrong time horizon. A sprint burndown chart that resets every two weeks doesn't help you plan the quarter. A velocity trend over one sprint isn't a trend. Match the widget to the time horizon of the question you're asking.

Metrics that measure activity, not outcomes. "Issues created this week" tells you your team is logging tickets. It doesn't tell you whether the project is on track. Issues closed vs committed is a more honest number.

No audience. A dashboard built for standup looks completely different from one built for an exec review. Mixing those purposes produces something that's mediocre for both.

The Metrics That Actually Matter

Here are the five metrics worth tracking for most software teams, and why:

Sprint Burndown

The most immediate signal. Are you on track to complete your sprint commitment? A healthy burndown slopes steadily toward zero. A flat line mid-sprint means work isn't getting closed. A cliff at the end means scope wasn't broken down properly.

Track it per sprint. The shape matters as much as the final number.

Velocity (Rolling Average)

Sprint velocity — story points or issue count completed per sprint — is useful when you look at it over 4–8 sprints. A single sprint's velocity is noise. A rolling average is a planning input.

Watch for velocity swings greater than ±30% — those usually point to estimation drift, unplanned work, or sprint scope changes worth discussing in retrospectives.

Cycle Time

How long does an issue take from "In Progress" to "Done"? Cycle time is one of the most diagnostic metrics in software delivery. High cycle times for small issues usually indicate blockers, review bottlenecks, or unclear acceptance criteria. High variance means your process is inconsistent.

This is the metric most teams skip and then wonder why estimates are always wrong.

Blockers by Assignee

How many blocked issues does each person have? This is a team health metric disguised as a workload metric. If one person has 5 blocked issues and everyone else has zero, that's a structural problem — not an individual one.

Surface this in your standup dashboard so blockers get visibility before they become incidents.

Issues Without Assignees

Work that's been created but not picked up. In a healthy sprint this number should be low. In a backlog it's expected. When it climbs during a sprint, it usually means scope crept in through the side door.

Setting Up Charts with Charts for Jira Dashboard

Charts - Reports and Graphs for Jira Dashboard is a Forge-native gadget that adds a proper charting layer to Jira dashboards. It supports bar charts, line charts, pie charts, and burndown-style visualizations — all configured directly in the dashboard without needing external tools or BI integrations.

Adding a Chart Gadget

Open your Jira dashboard (or create a new one)
Click Add gadget
Search for Charts — select the Charts gadget
Configure the data source: choose your project, board, or a saved JQL filter
Select the chart type
Set your grouping dimension — status, assignee, priority, sprint, label, component
Set the time range
Save

The gadget renders immediately and stays live — data updates automatically as issues change.

Grouping Options Worth Knowing

Group by status gives you a distribution view — how many issues are in each workflow state. Useful for spotting pileups (10 issues in "In Review," 2 in "Done" — something's blocking review).

Group by assignee shows workload distribution. Combine with a filter for a specific sprint and you can see at a glance if load is balanced.

Group by label or component is useful for teams that run mixed-project sprints — you can see how effort is distributed across workstreams.

Group by sprint over multiple sprints gives you the velocity trend you need for planning conversations.

Three Dashboard Layouts for Different Audiences

Standup Dashboard

Audience: the team. Time horizon: current sprint.

Widget	What It Shows
Sprint burndown	Are we on track?
Blocked issues by assignee	What needs unblocking?
Issues in each status	Where is work piling up?
Issues without assignees	What hasn't been picked up?

Keep this to 4 widgets maximum. The goal is a 60-second read at 9am.

Exec / Stakeholder Dashboard

Audience: non-engineering leadership. Time horizon: current quarter.

Widget	What It Shows
Velocity trend (rolling 6 sprints)	Is the team's throughput stable?
Epic progress (% complete)	Are we hitting roadmap milestones?
Issues by priority (open)	What's the risk surface?
Releases completed this quarter	Shipping cadence

Avoid sprint-level detail here. Execs want quarter-level signal, not sprint noise.

Retrospective Dashboard

Audience: the team. Time horizon: completed sprint.

Widget	What It Shows
Sprint burndown (completed sprint)	Did we hit the commitment?
Cycle time distribution	Were estimates accurate?
Unresolved issues carried over	What spilled?
Velocity vs previous sprint	Did throughput improve?

This dashboard exists to feed the retro conversation, not to survive past it. Create it, run the retro, archive it.

A Note on JQL Filters

Every chart in Charts for Jira is backed by a JQL filter. Learning a few patterns makes dashboard configuration much faster:

-- Current sprint, this project
project = MYPROJ AND sprint in openSprints()

-- Blocked issues
project = MYPROJ AND status = "Blocked"

-- Issues completed in last 30 days
project = MYPROJ AND status = Done AND resolutiondate >= -30d

-- High priority, unassigned
project = MYPROJ AND priority = High AND assignee is EMPTY

Save your most-used filters in Jira's filter management — then reference them by name when configuring gadgets rather than re-entering JQL each time.

Getting Started

Install Charts - Reports and Graphs for Jira Dashboard from the Atlassian Marketplace. It's Forge-native and works on Jira Cloud.

Full documentation is at /docs/charts-for-jira-dashboard.

Questions? Reach out via our support portal.