ADR Storage Format Comparison — Markdown vs AsciiDoc vs Notion vs Confluence vs SharePoint

Why storage choice is its own decision

Pick the wrong template (Nygard vs MADR vs arc42) and the cost is rewriting the section headers in N existing files — a half-day for any reasonable directory size, well-documented across the per-template pages on this site (Nygard, MADR, arc42). Pick the wrong storage layer and the cost is two orders of magnitude higher: a partial migration leaves half your ADRs in the old layer indefinitely, the cross-link graph between ADRs breaks, and the cultural muscle for reading ADRs in the original location atrophies. Storage is the more durable choice and deserves the more careful pick.

The five storage layers in this comparison are the ones that show up in real teams. The honest framing: each one is correct for a specific team shape, and each one fails predictably when used outside that shape. The decision matrix later on this page sorts the layers by team-shape fit; the per-layer sections below explain the trade-offs in detail.

The five layers, side by side

The decision matrix — pick by team shape

If you can answer the four questions below, the matrix picks the layer for you.

1. Who reads the ADR? Engineers only / Engineers + product / Cross-functional including non-technical execs.
2. Who writes the ADR? Engineers only / Engineers + PMs / Mixed with non-technical contributors.
3. Where does code review live? GitHub/GitLab/Bitbucket PRs / no formal code review / Jira tickets coupled with Atlassian.
4. What's the regulated-environment requirement? None / SOC 2 or ISO / HIPAA or higher / Microsoft-mandated tooling.

Markdown in a repo — the default, in detail

The canonical layout is /doc/decisions/NNNN-short-slug.md with one ADR per file, IDs allocated per the merge-base allocator, body shape per Nygard or MADR, frontmatter per the status template, and CI per the GitHub Action workflow. The whole sub-cluster of pages on this site assumes Markdown-in-repo as the default; the rest of this section explains why.

What this layer wins on

• Versioning is free. Every ADR change is a git commit. Status transitions, body edits, supersession links — all in git history with attribution and timestamps. No separate audit trail needed.
• PR review is the review surface. A PR that changes architecture comes with a PR that adds an ADR. Reviewers comment line-by-line on the ADR body, the same surface they comment on code. The ADR review is part of the engineering process, not a separate workflow that gets skipped under deadline pressure.
• Migration off is cheap. Every wiki and document tool has a Markdown importer. If you outgrow this layer (rare; mostly happens when the team grows past 100 engineers and centralized doc tooling becomes a coordination requirement), the migration is a script that runs in an afternoon.
• Tooling is universal. Every static site generator, every CI tool, every editor renders Markdown. The doc-tool dependency surface is exactly zero.

Where this layer breaks

• Non-engineer readers can't find it. A PM who needs to know "why did we pick Postgres" has to know which repo, which branch, which path, and how to render Markdown. The mitigation is a static-site published view (arch.example.com/decisions/ served via Mkdocs / Docusaurus / Hugo / Nextra) so non-engineers read at a URL while engineers edit in the repo.
• No granular permissions. Repo ACL is the only access control. Restricting some ADRs to a sub-team requires a separate repo. For most teams this is fine; for large enterprises with mixed-sensitivity decisions in the same directory, it's a real limitation.
• No rich embeds. Diagrams, video walkthroughs, interactive tables all need to be separate files referenced by URL. mermaid diagrams in fenced code blocks render inline on GitHub but not in every Markdown processor; PlantUML needs a build step. Plan the embed strategy upfront.

AsciiDoc — when it earns its place

AsciiDoc beats Markdown on three axes: include:: directives compose ADRs into a larger architecture document; cross-references survive renames (Markdown links break when files move); tables and footnotes are first-class. For teams already using arc42 (which ships in AsciiDoc by default) or DocBook-derived workflows, ADRs as sub-sections of the main architecture document is genuinely better in AsciiDoc than the equivalent Markdown setup.

Outside that case, AsciiDoc fights an uphill battle. The toolchain is heavier (Asciidoctor + Ruby vs the markdown-it / remark / mdast tooling that ships in every Node project). GitHub renders AsciiDoc but not as well as Markdown — fenced code blocks are less polished, anchor links are less reliable, and pull-request diffs are noisier because AsciiDoc's whitespace sensitivity is different from Markdown's. Most engineers know Markdown fluently and not AsciiDoc fluently — the contributor barrier is real.

Pick rule: AsciiDoc only if you're already on it. Don't pick AsciiDoc just for ADRs.

Notion database — the cross-functional answer

Notion's database view turns ADRs into rows with typed properties (Status, Date, Decision-by, Tags, Project link). The properties enable filters, sorts, and grouped views ("show me all Accepted decisions tagged billing from the last quarter") that Markdown directories require ad-hoc tooling for. Embedded media is one-click — Figma frames, Loom recordings, screenshots, Slack threads. Real-time multi-author editing during a decision meeting is genuinely useful when the decision is being co-written by a PM, an engineer, and a designer.

What this layer wins on

• Cross-functional contribution. A PM can co-write an ADR without learning Markdown or git. The "ADR as a Notion page" framing matches how non-engineers already work in Notion.
• Database queries for free. Status dashboards, per-team filtered views, pending-Trial-Period reminder boards — all configured in Notion's UI without writing code.
• Mobile reading is excellent. Notion's mobile app is the best of the five layers for reading on-the-go (the Wifi-on-flight reading session that Confluence loses to slow page loads and SharePoint loses to .docx download).

Where this layer breaks

• No git integration. ADR changes don't appear in PR diffs; reviewers reading the code change have to context-switch to Notion to see the ADR change. The cultural muscle "every architecture-significant PR carries an ADR" is harder to build when the ADR isn't in the PR.
• Page-level version history. Notion's version history shows page snapshots, not line-level diffs. For most ADR edits this is fine; for legal/compliance audits where "exactly which words changed when" matters, it's insufficient.
• Vendor lock-in is real. Notion's Markdown export is good for prose but doesn't preserve database properties cleanly — exporting 200 ADRs with their typed metadata requires the migration script described in the next section. The lock-in isn't catastrophic (the script works), but it's a tax.
• API rate limits at scale. Above ~500 ADRs in one database, Notion's API rate limits start biting on bulk operations. The product is built for <1000-page workspaces; very large ADR directories outgrow it.

Confluence pages — the Atlassian-native answer

If your team already runs on Jira and Bitbucket, Confluence is the path of least resistance for ADRs that need to be readable by non-engineers. Page permissions are mature (per-space, per-page, per-property restrictions), the Page Properties macro gives you the equivalent of database properties for filtering and dashboards, and the Atlassian audit log integrates ADR changes with the rest of your governance trail.

What this layer wins on

• Mature permissions. Per-page permission scoping is the strongest of the five layers. For regulated environments where some decisions need to be visible only to a security team or only to executives, Confluence handles it natively without separate tooling.
• Atlassian integration. Linking an ADR to a Jira epic, embedding a Bitbucket PR, surfacing ADR changes in the Atlassian audit log — all native, no plugins required.
• Templates and macros. The {status} macro renders colored pills, the Page Properties macro turns properties into queryable database, the {table-of-contents} macro auto-builds nav. Mature template ecosystem.

Where this layer breaks

• No branching. Confluence drafts are linear — you can't propose an ADR in a branch and merge it via PR. Reviewers see the live page (or a draft you've shared with them) but can't make comments on a parallel proposed version. The PR-review-as-ADR-review workflow doesn't translate.
• Slow reading UX. Confluence Cloud's page-load times are noticeably slow at the directory-of-50-ADRs scale. The Server / Data Center versions are faster but operationally heavier.
• Marketplace tax. Most quality-of-life features (better search, better diff view, better dashboards) are paid Marketplace plugins. License sprawl is a real cost above ~50 users.

SharePoint document library — when the enterprise mandates it

SharePoint is the storage layer mandated by some Microsoft 365-bound enterprises. The good news: it's already licensed, it integrates with Teams and Outlook, version control is familiar, and retention / DLP / e-discovery are built in. The bad news: SharePoint's UX is built around .docx files, not Markdown or web pages, and the "ADR as a document" framing fights the "ADR as a versioned text file" practice that actually works in real teams.

Mitigation: keep ADRs as .md files in the document library, accept that the SharePoint preview is poor, and publish a static-site rendered view at an internal URL for actual reading. Engineers will tolerate the SharePoint upload step if reading happens elsewhere; cultural buy-in on "ADRs in SharePoint" is fragile and often quietly drifts to a parallel repo within a quarter.

Pick rule: SharePoint only if mandated. The mandate carries the choice; don't fight it, but document the dual-surface (SharePoint as system-of-record, internal wiki for reading) explicitly so the practice survives.

Migration paths between layers

None of these is a one-way door. The migration costs are bounded; the work is mostly mechanical. Times below assume a 50-ADR directory.

Markdown → Notion (4–6 hours)

Notion's Markdown import creates pages but doesn't populate database properties. The script: parse each .md file's YAML frontmatter, create a database row via Notion's API with the typed properties, then upload the body as the page content. The Notion API has a 2000-character block limit so long ADRs need to be split into multiple paragraph blocks. @notionhq/client handles the bulk; budget extra time for property type mapping (Status as Select, Date as Date, Tags as Multi-select).

Notion → Markdown (6–8 hours)

Notion's per-page Export → Markdown gets you 80% of the way; the remaining 20% is database properties which need to be re-encoded as YAML frontmatter at the top of each file. Use Notion's API to fetch each row's properties as a JSON object, transform to YAML frontmatter, prepend to the exported Markdown body. The markdownify library plus a property-mapping table covers most cases; budget extra time for embedded media (Notion attachments need to be downloaded separately and the URLs rewritten to local paths).

Markdown → Confluence (8–12 hours)

Confluence's Markdown plugin renders .md directly but doesn't create the structured Page Properties for filtering. Use the Confluence REST API to create pages with the body as the rendered Markdown, then use a separate API call to add Page Properties from the YAML frontmatter. Linkrot is the biggest risk — Markdown internal links (./0042-foo.md) need to be rewritten to Confluence URLs, which requires a two-pass migration (first pass creates pages and captures the new URLs; second pass rewrites links).

Confluence → Markdown (12–16 hours, possibly more)

The hardest direction. Confluence's storage format is XHTML (the "Confluence storage format") with custom macros — not Markdown, despite the rendered view. Tools like confluence-to-markdown handle the basic prose; Page Properties macros, status macros, and Jira-ticket macros all need custom transformation. Budget significantly more time if the Confluence space uses a lot of macros. The page history is unrecoverable in the migration — only the current version makes the trip.

Any → AsciiDoc (1.5x the equivalent Markdown migration)

The conversion mechanics are similar to Markdown but the syntax differences (= headings vs #, [source,bash] vs ` ```bash `, * vs - ) and the include::-vs-link mismatch require a per-file pass. Tools like pandoc handle most of it; the failure surface is custom macros and embedded media.

Any → SharePoint (depends entirely on the rendering strategy)

If ADRs become .docx files in SharePoint, budget significant time per ADR (Markdown → .docx is fragile, code blocks lose formatting, links sometimes drop). If ADRs stay .md files in SharePoint, budget ~minutes per ADR (just the upload step, which Power Automate can script). Almost always do the latter.

The dual-surface pattern — when you can't pick just one

Many teams end up with a dual-surface pattern: ADRs live as Markdown in the repo (system of record), and a published view is rendered to a separate location for non-engineer readers. The system of record stays small, version-controlled, and PR-reviewed; the published view is generated automatically and never edited directly.

Common publish targets:

• Mkdocs / Docusaurus / Hugo / Nextra served at arch.example.com/decisions/ — the standard pattern, low maintenance, looks great. Suitable for any team.
• Confluence sync via a CI job that renders Markdown to Confluence storage format and updates pages on every merge. Requires Confluence already in use; the dual-surface pattern then bridges the engineering-only Markdown layer to the cross-functional Confluence layer.
• Notion sync via a CI job that uses the Notion API to update database rows on every merge. Same pattern as Confluence; Notion's API is friendlier for this than Confluence's.

The dual-surface pattern is more work than picking one layer, and the failure mode is drift between the two surfaces (the published view falls behind the source of truth). Mitigate with a CI job on every merge that fails the build if the published view didn't update successfully — drift is the failure mode that kills the pattern.

The failure modes specific to each layer

How WhyChose fits in

Storage choice doesn't change the upstream problem: most architecture decisions are made in chat conversations that never become ADRs at all, regardless of whether the team would have stored them in Markdown or Notion or Confluence. The WhyChose extractor reads your AI chat exports (ChatGPT, Claude, Gemini), surfaces decision-shaped exchanges with the trade-offs considered at the time, and outputs structured records ready to drop into any of the storage layers on this page. The extractor's output is YAML-frontmattered Markdown by default — drop it into doc/decisions/ and run the merge-base allocator, or use the migration paths above to land it in your Notion / Confluence / SharePoint layer of choice. The Pro tier ships dedicated exporters for Notion and Linear; the Team tier ships a Confluence sync. Whichever storage layer you picked, the extractor pre-fills the input.

Get early access

Related questions

Further reading

• Architecture decision record template — the three-template comparison (Nygard / MADR / arc42); pick the body shape, then return here for the storage layer.
• ADR template in Markdown — the Markdown-in-repo body template; the default storage layer's recommended template.
• The Nygard ADR template — the original 5-section template; works in any storage layer but pairs naturally with Markdown.
• MADR (Markdown ADR) template — the Markdown-frontmatter standard; the closest fit to this page's recommendations for the Markdown layer.
• arc42 ADR template — the section-9 integration; the natural fit for AsciiDoc-stored architecture documentation.
• ADR template for Notion — the database schema for the Notion layer; pair with the migration paths on this page.
• ADR template for Confluence — the Confluence page template with macros; pair with the dual-surface pattern if you also keep a Markdown source of truth.
• ADR template for GitHub — the /doc/decisions/ folder layout + PR template + GitHub Action for the Markdown-in-repo layer.
• ADR status template — the Status field's format; the placement (frontmatter vs heading vs property) varies by storage layer.
• ADR numbering scheme — the directory-level discipline; applies to Markdown / AsciiDoc layers, less so to Notion / Confluence (which auto-allocate).
• How to update an ADR — the supersession protocol; the workflow varies by storage layer (PR for Markdown, draft-then-publish for Confluence, edit-then-status-flip for Notion).
• The ADR GitHub Action workflow — the CI for the Markdown-in-repo layer; the dual-surface publish job goes here too.
• How to document architecture decisions — the cultural complement; storage choice and culture interact (PR-review culture pairs with Markdown; wiki culture pairs with Notion or Confluence).
• The open-source extractor — emits YAML-frontmattered Markdown; drop into any storage layer using the migration paths above.