DEV Community: Yamuno

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.

Docs as Code: How to Export Confluence to Git-Ready Markdown

Yamuno — Sun, 03 May 2026 09:23:26 +0000

Docs as Code: How to Export Confluence to Git-Ready Markdown

Docs-as-code treats documentation like source code: written in plain text, versioned in Git, reviewed in pull requests, and deployed through a CI/CD pipeline. The format is almost always Markdown.

Confluence doesn't fit this model natively. Its export produces HTML or PDF — neither of which belongs in a Git repository. But for many teams, Confluence is where the documentation actually gets written and reviewed. Replacing it isn't always an option.

The practical solution: use Confluence as the editing surface and Git as the source of truth. Export Confluence to Markdown on a cadence, commit the output, and let your pipeline handle the rest.

Markdown Exporter for Confluence is built for exactly this workflow.

What You Need

Confluence Cloud (the app requires Forge and runs on Cloud only)
Markdown Exporter for Confluence installed on your Confluence instance
A Git repository with a docs/ folder (or equivalent)
Optionally: a static site generator like MkDocs or Docusaurus

Step 1 — Structure Your Confluence Space for Export

The exporter preserves your Confluence page hierarchy as a folder structure. If your pages are organised logically in Confluence, the output will be organised logically on disk.

A Confluence structure like this:

Documentation (space root)
├── Getting Started
│   ├── Installation
│   └── Quick Start
├── Architecture
│   ├── Overview
│   └── API Reference
└── Operations
    └── Runbooks

Becomes this folder structure in the exported ZIP:

docs/
├── Getting Started/
│   ├── Installation.md
│   └── Quick Start.md
├── Architecture/
│   ├── Overview.md
│   └── API Reference.md
└── Operations/
    └── Runbooks.md

Most static site generators — MkDocs, Docusaurus, Jekyll, Eleventy — can work directly with this structure.

Step 2 — Configure Filename Patterns

Consistent filenames matter in a Git repo. If file names change between exports, Git treats the old file as deleted and the new one as added — losing commit history.

Markdown Exporter lets you define a filename pattern using tokens:

Token	Value
`{title}`	The Confluence page title
`{date}`	Export date in `YYYY-MM-DD` format
`{id}`	The Confluence page ID

For a stable docs-as-code workflow, use {title} only — so filenames stay consistent across exports as long as page titles don't change. If you need uniqueness guarantees even when titles change, add {id}.

Step 3 — Enable YAML Front Matter

Most static site generators read metadata from YAML front matter at the top of Markdown files. Enable it in the exporter and configure which fields to include:

---
title: API Reference
author: Platform Team
date: 2026-04-23
space: DOCS
confluence_id: "789012"
---

You can also add custom key-value fields — useful for tagging pages with a category, product, or version that your site generator uses to build navigation or filter content.

Step 4 — Export and Commit

Run the export from the Confluence space or page tree you want to publish:

Click ••• → Export to Markdown on the root page, or open from the Apps menu
Set scope to Include Child Pages or Full Space
Enable YAML front matter and set your filename pattern
Click Export and download the ZIP
Extract the ZIP over your docs/ folder in the repository
Commit: git add docs/ && git commit -m "docs: sync from Confluence 2026-04-23"

On the next CI run, your pipeline picks up the updated Markdown and publishes the new docs.

Works With MkDocs and Docusaurus

MkDocs

The exported folder structure maps directly to MkDocs nav. A minimal mkdocs.yml:

site_name: Platform Docs
docs_dir: docs
nav:
  - Getting Started:
    - docs/Getting Started/Installation.md
    - docs/Getting Started/Quick Start.md
  - Architecture:
    - docs/Architecture/Overview.md
    - docs/Architecture/API Reference.md

Or let MkDocs auto-generate nav from the folder structure with the awesome-pages plugin.

Docusaurus

Place the extracted folder under docs/ in your Docusaurus repo. Docusaurus reads YAML front matter natively — the title and date fields will be picked up automatically. Enable autogenerated sidebars and the folder hierarchy becomes the sidebar structure.

Keeping Content in Sync

For a lightweight sync loop:

Export on a schedule — run a full space export weekly, or per-section after each sprint
Review the diff — git diff docs/ shows exactly what changed since the last export
Commit and push — let CI build and deploy the updated site

For more frequent syncs, you can automate around the export step using browser automation or Confluence webhooks that trigger a reminder to re-export. The exporter itself is UI-driven and doesn't currently expose a REST API — so fully automated pipelines work best when paired with a scheduler that prompts the export step.

What the Export Handles

Text formatting — headings, bold, italic, strikethrough, inline code
Tables — column alignment and header rows preserved
Code blocks — fenced with language tag for syntax highlighting
Lists — ordered, unordered, nested, task lists
Images and attachments — downloaded and referenced with relative paths
Internal links — converted to relative Markdown links between files
Info / note panels — converted to blockquotes

Getting Started

Install Markdown Exporter for Confluence free from the Atlassian Marketplace.

Full documentation at /docs/markdown-exporter-for-confluence.

Questions or feedback? Reach out via our support portal.

How to Write Markdown in Confluence Without Losing Formatting

Yamuno — Sat, 02 May 2026 09:10:19 +0000

How to Write Markdown in Confluence Without Losing Formatting

If you've ever pasted markdown into a Confluence page, you know what happens: the formatting disappears and you're left with raw asterisks, backticks, and pound signs. Confluence has its own editor — it doesn't interpret markdown syntax natively.

That's a real problem for technical writers and engineers who write in markdown by default. You end up maintaining two versions of everything, or spending time manually reformatting content every time it moves.

Markdown Renderer for Confluence solves this directly: add the macro to a page, write markdown inside it, and it renders live. No conversion, no reformatting, no copy-paste friction.

Why Confluence Doesn't Support Markdown Natively

Confluence uses a proprietary storage format called Confluence Storage Format (XHTML-based). The editor works at that level — not at the markdown level. When you type in the editor, you're generating structured XML under the hood, not markdown.

There's no built-in way to write **bold** and have it render as bold. You'd have to use the editor's toolbar, keyboard shortcuts, or Confluence macros. That workflow doesn't fit teams who live in markdown — documentation-as-code practitioners, developers writing runbooks, or technical writers migrating content from GitHub or Notion.

What Markdown Renderer Does

Markdown Renderer for Confluence is a Forge-native macro that renders markdown inline on a Confluence page. You insert the macro, paste or write your markdown inside it, and the page displays the rendered output — headings, tables, code blocks, math, and all.

The key behaviors:

Live rendering — what you write in the macro body renders as formatted content on save
GFM support — GitHub Flavored Markdown is fully supported, including tables, task lists, and strikethrough
Code blocks with syntax highlighting — fenced code blocks with language identifiers render with proper highlighting
Math support — inline and block LaTeX expressions via $...$ and $$...$$ syntax
No external requests — everything runs inside Confluence via Forge; your content never leaves Atlassian infrastructure

How to Insert the Macro

Open or create a Confluence page
In the editor, type / to open the macro browser
Search for Markdown Renderer
Select it — a macro placeholder appears on the page
Click into the macro body and write or paste your markdown
Save the page

That's it. The macro renders on save, and any editor who opens the page for editing sees the raw markdown in the macro body — editable as plain text.

Markdown Features Supported

Headings and Text

Standard ATX-style headings (#, ##, ###) render as Confluence heading levels. Emphasis (*italic*, **bold**), strikethrough (~~text~~), and inline code (`code`) all work as expected.

Tables

GFM pipe tables render correctly, including column alignment:

| Method | Endpoint         | Auth     |
| ------ | ---------------- | -------- |
| GET    | /api/v1/users    | Required |
| POST   | /api/v1/sessions | None     |

This is particularly useful for API documentation and reference tables — content types that are painful to build in the Confluence native editor.

Code Blocks

Fenced code blocks with language identifiers:

```

python
def parse_webhook(payload: dict) -> Event:
    return Event(
        type=payload["type"],
        data=payload.get("data", {}),
    )


```
```

`

Syntax highlighting is applied automatically based on the language tag.

### Math

If you're writing technical documentation that includes equations, the macro supports LaTeX math syntax:

```markdown
The time complexity is $O(n \log n)$.

$$
\sum_{i=1}^{n} x_i = \frac{n(n+1)}{2}
$$
```

This uses the same rendering pipeline as [LaTeX Math for Confluence](https://marketplace.atlassian.com/apps/1238016/latex-math-for-confluence?hosting=cloud&tab=overview) — equations render cleanly without needing a separate macro for simple cases.

### Task Lists

```markdown
- [x] Write the API spec
- [x] Review with backend team
- [ ] Update the runbook
- [ ] Notify stakeholders
```

These render as visual checkboxes, making them useful for runbooks, checklists, and release notes embedded in Confluence pages.

---

## Practical Tips for Technical Writers

**Keep your source in markdown.** If you're maintaining documentation in a Git repo, the Markdown Renderer macro lets you paste the current content into Confluence without reformatting it. When the source changes, you update the macro body. It's not automated sync (for that, use Markdown Importer's REST API), but it's fast enough for most workflows.

**Use one macro per logical section.** You don't have to put an entire page inside a single macro. Mix native Confluence content with markdown macro blocks — use the native editor for page layouts, comments, or Confluence-specific macros, and drop into the markdown macro for content-heavy sections.

**Watch your frontmatter.** If you paste markdown from a file that has YAML frontmatter (`---` block at the top), strip it before pasting — the renderer will display it as text. Frontmatter is handled at import time by Markdown Importer, not at render time.

**Tables with many columns.** Confluence pages have a fixed width. Very wide markdown tables can overflow the macro boundary. Either reduce the column count or apply a full-width page layout before inserting the macro.

---

## When to Use Markdown Renderer vs Markdown Importer

These are different tools for different problems:

| Scenario | Tool |
| -------- | ---- |
| Write markdown inline on a Confluence page | Markdown Renderer |
| Bring in a file, folder, or GitHub repo as Confluence pages | Markdown Importer |
| Automate doc sync via CI/CD | Markdown Importer (REST API) |
| Live markdown editing in Confluence | Markdown Renderer |

If your workflow is "write in markdown, publish to Confluence," you likely want both.

---

## Getting Started

Install [Markdown Renderer for Confluence](https://marketplace.atlassian.com/apps/1238017/markdown-renderer-for-confluence?hosting=cloud&tab=overview) from the Atlassian Marketplace. It's Forge-native, so no external server connections, no CSP exceptions, and no admin firewall approvals needed.

Full documentation is at [/docs/markdown-renderer-for-confluence](/docs/markdown-renderer-for-confluence).

---

_Questions? Reach out via our [support portal](https://yamuno.atlassian.net/servicedesk/customer/portals)._

Yamuno is a Finalist for Atlassian Partner of the Year 2026: Marketplace Rising Star

Yamuno — Thu, 30 Apr 2026 17:32:49 +0000

Yamuno is a Finalist for Atlassian Partner of the Year 2026: Marketplace Rising Star

We have some exciting news to share: Yamuno has been named a finalist for the Atlassian Partner of the Year 2026: Marketplace Rising Star Award.

This recognition means a great deal to our team. The Atlassian Marketplace is home to thousands of apps, and being recognized as a Marketplace Rising Star is a reflection of the trust that Confluence and Jira users have placed in our products. We don't take that lightly.

What is the Atlassian Partner of the Year 2026: Marketplace Rising Star Award?

The Atlassian Partner Awards are given annually to recognize partners who demonstrate exceptional commitment to customer success, product quality, and growth within the Atlassian ecosystem. The Marketplace Rising Star category specifically honors vendors who have shown outstanding momentum, adoption, and customer impact over the past year.

Being named a finalist means Atlassian has recognized Yamuno among the top performers in this category — and that is something we are genuinely proud of.

Our Journey on the Atlassian Marketplace

Yamuno started with a single mission: build Forge-native apps that teams can actually trust. No external servers. No data leaving Atlassian infrastructure. Just reliable tools that do exactly what they promise.

Over the past year, we've grown our portfolio to eight apps — all built on Atlassian Forge and focused on making Confluence and Jira more powerful for the people who use them every day:

Markdown Importer for Confluence Cloud — import and export markdown files, page trees, and entire spaces with full formatting support
Markdown Exporter for Confluence — export pages to clean, portable Markdown with YAML front matter, Obsidian wikilinks, and custom filename patterns
HTML Macro for Confluence — embed custom HTML, CSS, and JavaScript inside Confluence pages with enterprise CSP controls
LaTeX Math for Confluence — professional LaTeX equation rendering with live preview and access controls
Charts for Jira Dashboard — interactive, customizable charts and tables built directly into your Jira dashboard
Markdown Macro for Confluence — write, preview, and publish rich Markdown content natively in Confluence
Advanced Attachment Manager for Confluence — find, filter, and clean up attachments across your entire Confluence instance
PDF Exporter for Confluence — export pages, hierarchies, or spaces to professionally formatted PDFs with custom templates

Each app was built in response to real pain points we heard from the community — things teams needed but couldn't find a reliable solution for.

This Wouldn't Exist Without You

Recognition like this isn't built in a vacuum. Every review left on the Marketplace, every support ticket that pushed us to make something better, every user who suggested a feature or reported an edge case — that community feedback is what shaped these products into what they are today.

If you've been a Yamuno customer, this nomination belongs to you as much as it does to us. Thank you.

What's Next

We're continuing to build. The same principles that got us here — Forge-native security, focus on real workflows, and responsiveness to user feedback — are what will drive everything we ship next.

Explore our full app portfolio on the Atlassian Marketplace or reach out at support@yamuno.com.

How to Export Confluence to Obsidian (With Wikilinks)

Yamuno — Tue, 28 Apr 2026 10:17:28 +0000

How to Export Confluence to Obsidian (With Wikilinks)

Confluence and Obsidian serve different needs. Confluence is where teams collaborate on documentation. Obsidian is where individuals build a personal knowledge base, connect ideas, and think in networks of linked notes.

If you use both, you've probably felt the friction: Confluence content doesn't transfer cleanly to Obsidian. Copy-pasting loses formatting. Downloading HTML is useless. Internal links between pages become broken references.

Markdown Exporter for Confluence solves this with a dedicated Obsidian mode that converts Confluence page links to [[wikilinks]] automatically.

The Problem With Standard Confluence Export

Confluence's built-in export options are HTML and PDF. Neither works with Obsidian:

HTML — Obsidian doesn't render HTML as notes. You'd need to strip tags manually.
PDF — read-only, not searchable in Obsidian's graph, and not linkable.

Even if you extract text, internal links ([See also: Architecture Overview](/wiki/spaces/PROJ/pages/...) become long URLs that Obsidian doesn't recognise as note links. Your knowledge graph breaks.

What Obsidian Mode Does

When you enable Obsidian mode in Markdown Exporter, every internal Confluence page link is converted to [[Page Title]] format:

Before (standard export):

See the [Architecture Overview](https://yoursite.atlassian.net/wiki/spaces/PROJ/pages/123456/Architecture+Overview) for context.

After (Obsidian mode):

See the [[Architecture Overview]] for context.

Obsidian resolves wikilinks by note title, so as long as the referenced page is in your vault, the link works — and shows up in the graph view.

Step-by-Step: Export Confluence to Obsidian

Step 1 — Install Markdown Exporter

Install Markdown Exporter for Confluence from the Atlassian Marketplace. It requires Confluence Cloud and takes about 30 seconds to install.

Step 2 — Open the Exporter

Navigate to the Confluence page or space you want to export. Click ••• (More actions) → Export to Markdown. For a full space, open it from the Apps menu in global navigation.

Step 3 — Enable Obsidian Mode

In the export options panel, toggle Obsidian Wikilinks on. This switches internal link output from standard Markdown links to [[Page Title]] format.

Step 4 — Configure YAML Front Matter (Optional)

Enable YAML front matter to include metadata at the top of each exported note:

---
title: Architecture Overview
author: Jane Smith
date: 2026-04-23
space: PROJ
confluence_id: "123456"
---

This is useful if you use Obsidian plugins like Dataview to query note properties, or if you want to track which Confluence page each note came from.

Step 5 — Select Scope and Export

Choose your scope:

Single page — exports one .md file
Page tree — exports a parent page and its children as a structured ZIP
Full space — exports everything in the space as a ZIP with folder hierarchy

Use the in-tree search to find specific pages if you only need a subset.

Step 6 — Add to Your Obsidian Vault

Extract the ZIP into a folder inside your Obsidian vault. Obsidian will immediately index the notes. If you enabled wikilinks mode, the internal links between pages will resolve — and they'll appear in the graph view.

What the Export Preserves

Content Type	Obsidian Output
Headings	`#`, `##`, `###`
Bold / Italic	`bold`, `italic`
Tables	Standard Markdown tables
Code blocks	Fenced with language tag
Lists	Ordered and unordered
Images & attachments	Downloaded, referenced with relative paths
Internal page links	`[[Page Title]]` wikilinks
External links	Standard `[text](url)`
Info / warning panels	Blockquotes

Tips for Obsidian Users

Use a dedicated folder. Keep your Confluence imports in a subfolder like confluence/ so they don't mix with your personal notes. You can still link across folders.

Sync regularly with a script. If your team's Confluence content changes often, set up a regular export and overwrite the vault folder. Links won't break as long as page titles stay the same.

Combine with Dataview. If you include YAML front matter, you can build Dataview queries over your Confluence notes — e.g. all pages in a specific space, or notes modified after a certain date.

Check complex macros. Most Confluence content converts cleanly. Heavily customised layouts or third-party macros may need a quick review after export.

Getting Started

Install Markdown Exporter for Confluence free from the Atlassian Marketplace.

Full documentation is at /docs/markdown-exporter-for-confluence.

Questions? Reach out via our support portal.

5 Ways to Clean Up Confluence Storage Without Breaking Anything

Yamuno — Fri, 24 Apr 2026 09:47:34 +0000

5 Ways to Clean Up Confluence Storage Without Breaking Anything

Confluence storage has a way of quietly filling up. Old attachments accumulate, duplicate files get uploaded, outdated page versions pile up — and suddenly your admins are getting storage warnings.

The tricky part is cleaning it up safely. Delete the wrong file and you break a page that someone still relies on. Here are five practical approaches to reclaim storage without causing collateral damage.

1. Audit Attachments Before You Delete Anything

The first mistake most admins make is deleting files before understanding what's actually taking up space. Start with an audit.

Advanced Attachment Manager for Confluence gives you a searchable, filterable view of every attachment across your entire Confluence instance — sorted by file size, type, space, or date. You can instantly see:

Which spaces are consuming the most storage
Which file types are taking up the most space (PDFs? Videos? Zip files?)
Which attachments are oldest and most likely outdated
Which pages have the most attachments

This takes the guesswork out of cleanup. You know exactly what to target before you touch anything.

2. Delete Old Attachment Versions

Every time someone re-uploads a file with the same name, Confluence keeps the previous version. Over time, old attachment versions accumulate invisibly — they don't show up in search but they count against your storage quota.

To clean up attachment versions:

In standard Confluence: go to a page → Attachments → select an attachment → view history → delete old versions
With Advanced Attachment Manager: identify pages with many attachment versions across the whole instance and bulk-delete old versions in one operation

This is often one of the biggest wins in a storage cleanup — old file versions can account for a surprising percentage of total usage.

3. Find and Remove Duplicate Files

Teams frequently upload the same file multiple times — the same logo across ten different spaces, the same template ZIP uploaded by multiple people, the same diagram in slightly different versions.

To find duplicates:

Use Advanced Attachment Manager's filter by file type and size to spot files of identical size
Search by filename to find the same file uploaded across multiple spaces
Consolidate duplicates — keep one canonical version, update page references, delete the rest

For images specifically, bulk-replacing references and consolidating to a single version can reclaim significant space.

4. Clean Up Orphaned Attachments

Orphaned attachments are files that were uploaded to a page and then the page content changed — the file is still there but no longer referenced in the page body. It shows in the attachments list but isn't embedded anywhere.

These are almost always safe to delete, but confirming manually across thousands of pages is impractical. Advanced Attachment Manager lets you filter for unreferenced attachments and review them in bulk — so you can clean them up with confidence rather than blindly deleting.

5. Archive Old Spaces Instead of Letting Them Rot

One of the biggest contributors to storage bloat is spaces that are no longer active but never archived or cleaned up. Old project spaces, deprecated product docs, completed initiative wikis — they accumulate attachments and page versions indefinitely.

The right approach:

Identify inactive spaces — no edits in the last 6–12 months
Export the space to markdown or PDF if you want a permanent record (Markdown Exporter handles this)
Archive the space in Confluence — it becomes read-only and stops accumulating versions
Delete the space if you're confident nothing in it is needed

Archiving before deleting gives you a safety net. Export first if there's any doubt.

Bulk Actions Save Hours

The reason storage cleanups get neglected is that the manual process is slow. Click into each page, open attachments, check each file, decide, delete. Multiply that by thousands of pages and it becomes a multi-day project.

Advanced Attachment Manager's bulk actions let you:

Select multiple attachments across pages and spaces
Delete, move, or download them in one operation
Filter by type, size, date, or space to scope your cleanup precisely

What would take days manually takes an hour with the right tooling.

Before You Delete Anything

A few rules of thumb:

Check if the file is referenced in a page body. Deleting an attachment that's embedded in a page will break the embed. Advanced Attachment Manager shows you where each attachment is used.

Start with the obvious. Target large files first — videos, zips, PDFs. A single 500MB video file does more damage to your quota than a thousand small images.

Use spaces to scope your cleanup. Don't try to clean the entire instance at once. Pick one or two high-storage spaces and clean those first.

Don't delete page versions from active pages. Version history is there for a reason. Focus on old attachment versions, not page versions.

Getting Started

Advanced Attachment Manager for Confluence is available on the Atlassian Marketplace.

Full documentation at /docs/advanced-attachment-manager.

Questions? Reach out via our support portal.