Topic: adr template confluence

ADR Template for Confluence

Q: What about Confluence Cloud vs Data Center — does the macro markup change?

The info, status, and table macros are all available in both. Storage format is identical for these macros. If you're on Data Center with custom plugins, your status options may render differently — confirm with a one-page test before rolling out the template space-wide.

A Confluence page template for architecture decision records — using the status, info, and table macros so the page renders as a structured record, not a wall of unstyled text. Plus a Markdown import path so engineering keeps ADRs in the repo and mirrors them to the wiki.

TL;DR

Create a space called Decisions. Save the page below as a space template (Space settings → Content tools → Templates → Create new template). Every new ADR starts pre-populated with the macros wired up. For repo-first teams, write the ADR in Markdown and use Confluence's Import → Markdown to mirror it.

The page template

Below is the storage-format markup Confluence renders. Paste it into the template editor in Source mode (the </> button). The macros render as colored status pills, an info panel, and a table — the visual scaffolding that signals "this is a structured record" instead of "this is a paragraph someone typed."

<h1>NNNN. &lt;Short title that describes the decision&gt;</h1>

<ac:structured-macro ac:name="info">
  <ac:rich-text-body>
    <p><strong>Status:</strong>
      <ac:structured-macro ac:name="status">
        <ac:parameter ac:name="colour">Green</ac:parameter>
        <ac:parameter ac:name="title">Accepted</ac:parameter>
      </ac:structured-macro>
    </p>
    <p><strong>Date:</strong> 2026-04-24</p>
    <p><strong>Deciders:</strong> @your-handle, @reviewer-1</p>
    <p><strong>Supersedes:</strong> —</p>
    <p><strong>Superseded by:</strong> —</p>
  </ac:rich-text-body>
</ac:structured-macro>

<h2>Context</h2>
<p>What forces are at play? What problem are we solving? Include
team size, scale assumptions, deadlines — anything a future reader
needs to understand why this mattered. 2-4 sentences.</p>

<h2>Decision</h2>
<p>The choice, in one sentence: "We will use X."</p>
<p>A short paragraph on how we'll use it.</p>

<h2>Alternatives considered</h2>
<table>
  <tbody>
    <tr><th>Option</th><th>Why rejected</th></tr>
    <tr><td>Y</td><td>&lt;one-line reason&gt;</td></tr>
    <tr><td>Z</td><td>&lt;one-line reason&gt;</td></tr>
  </tbody>
</table>

<h2>Consequences</h2>
<h3>Positive</h3>
<ul><li>What this unlocks.</li></ul>
<h3>Negative</h3>
<ul><li>What we're giving up.</li></ul>
<h3>Neutral</h3>
<ul><li>What this doesn't change.</li></ul>

<h2>Links</h2>
<ul>
  <li>Implementing PR: &lt;url&gt;</li>
  <li>Original discussion: &lt;chat / Slack / design-doc URL&gt;</li>
</ul>

The status macro options

Use exactly these four; lock the colour mapping so the space is scannable in a list view.

Status	Macro colour	When to use
`Proposed`	Yellow	Drafted, awaiting review. Should not stay in this state for more than a week — if it does, the decision isn't real yet.
`Accepted`	Green	The decision is in force. Code reflects it.
`Deprecated`	Grey	The decision is no longer being followed but no replacement exists yet. Useful as a flag for the next reviewer.
`Superseded`	Red	Replaced by a newer ADR. Always link the new one in the Superseded by field.

Repo-first workflow with Markdown import

Most engineering-led teams write ADRs in their repo (see the Markdown template) and only mirror them to Confluence so non-engineering stakeholders can read them. Confluence's Import → Markdown handles this in one click per file. The page above is structurally identical to the Nygard Markdown ADR — same five sections, same metadata block — so a Markdown ADR converts cleanly without any post-import editing.

For the bulk case, the Confluence REST API takes Markdown directly via POST /wiki/rest/api/content with representation: "wiki". A 40-line script can keep your doc/decisions/ dir mirrored into a Confluence space on every PR merge to main, with the page title locked to the ADR filename and the body re-uploaded on update. That gives engineering one source of truth (the repo) and stakeholders one read surface (the wiki).

How WhyChose helps

WhyChose exports decision records as Markdown, which Confluence imports natively. Point WhyChose at your ChatGPT/Claude exports and it produces a folder of Markdown ADRs in this exact structure; drop them into Confluence's import dialog (or wire the API call into CI). The macros render correctly because the Markdown maps cleanly to the storage format above. The extractor is open-source — if you need to keep extraction inside your VPC, run it locally.

Get early access