# NGPILOT > NGPILOT builds 35+ apps for Atlassian Confluence and Jira. Key products: Modern Code Blocks (Monaco editor, 85+ languages, dark/light themes), Enhanced Markdown (WYSIWYG + raw Markdown editor), Google Fonts (1942+ font families as macro), Modern Numbered Headings (auto-number H1-H6), Mermaid Plus Diagrams & AI Agent (30 diagram types), Excalidraw Plus (freeform whiteboard), Raw Storage Source Editor (edit Confluence storage format XML), and more. All apps available on Atlassian Marketplace for Confluence Cloud and Jira Cloud. - [NGPILOT](/index.md) ## apps - [Apps for Confluence & Jira](/apps.md): Browse all NGPILOT apps for Atlassian Confluence and Jira — diagrams, code blocks, Markdown editor, fonts, templates, and more. Free for up to 10 users. - [Attachment Reviewer for Jira](/apps/attachment-reviewer-for-jira.md): Enforce file type and size policies for Jira attachments. Validate uploads and prevent security risks. Free for up to 10 users. - [Checklist Workflow Automation for Jira](/apps/checklist-workflow-automation-for-jira.md): Task checklists for Jira issues with templates, automatic apply, and reminders that mention the assignee. Free for up to 10 users. - [Component Hierarchy for Jira](/apps/component-hierarchy-for-jira.md): Parent-child component trees for Jira: cascading issue picker, subtree JQL via inComponentHierarchy(), CSV import/export. Nodes are real Jira components. - [Content Craft for Confluence](/apps/content-craft-for-confluence.md): Free business SVG library for Confluence — ready-made icons and illustrations. Free for up to 10 users. - [Content Formatting Macros & Page Builder for Confluence](/apps/content-formatting-macros-page-builder-for-confluence.md): 23 content formatting macros that turn Confluence into a page builder — hero sections, pricing tables, tabs, cards, and a global theme editor. Free for up to 10 users. - [Enhanced Markdown for Confluence](/apps/enhanced-markdown-for-confluence.md): Write Markdown in Confluence with live split preview, Mermaid diagrams, KaTeX/LaTeX math, and 190+ code languages. Free for up to 10 users. - [EPUB Reader for Confluence](/apps/epub-reader-for-confluence.md): Read EPUB files directly in Confluence. Enhance document accessibility for long-form reading. Free for up to 10 users. - [Excalidraw Diagrams plus Whiteboards for Jira](/apps/excalidraw-diagrams-plus-whiteboards-for-jira.md): Add an Excalidraw whiteboard to every Jira issue with 229 shape libraries. Sketch flowcharts, wireframes, and ER diagrams inline. Free for up to 10 users. - [Excalidraw & Mermaid Diagrams for Confluence](/apps/excalidraw-mermaid-diagrams-for-confluence.md): Excalidraw and Mermaid diagram editor combined in one Confluence app. Freehand drawing plus text-based diagrams. Free for up to 10 users. - [Excalidraw Plus Whiteboards & AI Agent for Confluence](/apps/excalidraw-plus-for-confluence.md): Create and edit Excalidraw whiteboards in Confluence with a Rovo AI agent — 220+ shape libraries, Mermaid and PlantUML import. Free for up to 10 users. - [Google Fonts for Confluence](/apps/google-fonts-for-confluence.md): Add custom Google Fonts to Confluence — 1,942+ font families with live preview, custom size, color, and alignment. Free for up to 10 users. - [Graphviz Charts for Confluence](/apps/graphviz-charts-for-confluence.md): Render Graphviz DOT diagrams in Confluence with live preview. Perfect for network graphs and dependency maps. Free for up to 10 users. - [Issue History Agent for Jira](/apps/issue-history-agent-for-jira.md): Field-level change history, word-level before/after diffs, a multi-issue report with CSV export, and a Rovo agent for Jira. Free for up to 10 users. - [JSON Graph Viewer & Visualizer for Jira](/apps/json-graph-viewer-visualizer-for-jira.md): Visualize JSON in Jira as an interactive graph — issue fields, entity properties, or paste. Code, graph, and side-by-side views. Free for up to 10 users. - [JSON Structure Viewer for Confluence](/apps/json-structure-viewer-for-confluence.md): Visualize JSON as interactive structure diagrams in Confluence. Collapsible tree view for nested data. Free for up to 10 users. - [Manim for Confluence](/apps/manim-for-confluence.md): Create mathematical animations in Confluence using the Manim engine. Dynamic visualisations of equations. Free for up to 10 users. - [Markdown Mind Maps for Confluence](/apps/markdown-mind-maps-for-confluence.md): Render Markdown as interactive mind maps in Confluence. Supports zoom, pan, dark mode, 10+ templates. Free for up to 10 users. - [Mermaid Plus Diagrams for Jira](/apps/mermaid-plus-diagrams-for-jira.md): Add Mermaid diagrams to Jira issues — 30 diagram types, live preview, and one-click templates. Free for up to 10 users. - [Mermaid Plus Diagrams & AI Agent for Confluence](/apps/mermaid-plus-for-confluence.md): Create Mermaid diagrams in Confluence with a Rovo AI agent — 30 diagram types, live preview, dark mode, and one-click templates. Free for up to 10 users. - [Modern Announcement Banner for Jira](/apps/modern-announcement-banner-for-jira.md): Create rich-text announcement banners in Jira with scheduling and audience targeting. Free for up to 10 users. - [Modern Code Blocks for Confluence](/apps/modern-code-blocks-for-confluence.md): Modern code blocks for Confluence powered by the Monaco editor — 85+ languages, 50+ themes, diff view, and auto dark/light mode. Free for up to 10 users. - [Modern FAQ for Confluence](/apps/modern-faq-for-confluence.md): Build accordion-style FAQ sections in Confluence with drag-and-drop reordering and two themes. Free for up to 10 users. - [Modern Importer & Exporter for Confluence](/apps/modern-importer-exporter-for-confluence.md): Bulk import and export Confluence content between JSON, XML, HTML, and Markdown formats. Free for up to 10 users. - [Modern Issue Templates for Jira](/apps/modern-issue-templates-for-jira.md): Create Jira issues from reusable templates with variables, GitHub import, and auto-apply rules. Free for up to 10 users. - [Modern My Tasks for Confluence](/apps/modern-my-tasks-for-confluence.md): Centralized task management for Confluence with inline editing and smart filtering. Free for up to 10 users. - [Modern Numbered Headings for Confluence](/apps/modern-numbered-headings-for-confluence.md): Auto-number Confluence headings (H1–H6) in 5 styles with live preview. Decimal, Roman, Alphabetic, Legal numbering. Free for up to 10 users. - [Modern OpenAPI (Swagger) Integration for Confluence](/apps/modern-openapi-swagger-integration-for-confluence.md): Render interactive OpenAPI and Swagger documentation on Confluence pages with validation and syntax highlighting. Free for up to 10 users. - [Modern Questions for Confluence](/apps/modern-questions-for-confluence.md): Add interactive Q&A with voting and accepted answers to Confluence pages. Free for up to 10 users. - [Pagination Buttons for Confluence](/apps/pagination-buttons-for-confluence.md): Add customizable Previous/Next pagination buttons to Confluence pages. Free for up to 10 users. - [PSD Attachments Viewer for Confluence](/apps/psd-attachments-viewer-for-confluence.md): View PSD files in Confluence with instant previews and auto dark mode. No Photoshop required. Free for up to 10 users. - [QR Code for Confluence](/apps/qrcode-for-confluence.md): Embed QR codes into Confluence pages. Link to mobile resources and share quick-scan links. Free for up to 10 users. - [Raw Storage Source Editor for Confluence (Free)](/apps/raw-storage-source-editor-for-confluence.md): Free raw storage format editor for Confluence. Edit the underlying page XML. Free for up to 10 users. - [Raw Storage Source Editor Pro for Confluence](/apps/raw-storage-source-editor-pro-for-confluence.md): Edit the raw XML storage format of Confluence pages with formatting, find-and-replace, and diff view. Free for up to 10 users. - [Simple Bulk Attachment Downloader for Jira](/apps/simple-bulk-attachment-downloader-for-jira.md): Download all Jira attachments in one click with parallel processing. 3x faster than one-by-one. Free for up to 10 users. - [Simple Bulk Issues Excel CSV Export for Jira](/apps/simple-bulk-issues-excel-csv-export-for-jira.md): Export filtered Jira issues to Excel or CSV with custom fields and JQL. Handles large result sets. Free for up to 10 users. - [Widget Carousel for Confluence](/apps/widget-carousel-for-confluence.md): Embed image carousels in Confluence pages to showcase visuals, banners, or product images. Free for up to 10 users. ## blog - [Blog](/blog.md): Blog - [Advanced Modern Code Blocks Features — Performance Tuning & Tips](/blog/advanced-code-blocks-confluence.md): Deeper configuration for Modern Code Blocks in Confluence: max-height, lazy loading, terminal window chrome, and performance tuning for large code samples. Companion to the main code blocks guide. - [AI Code Review in Confluence: Document and Share Code Reviews](/blog/ai-code-review-confluence.md): Use AI to document code reviews in Confluence. Learn how to create structured review templates, automate summaries, and share review outcomes with your team. - [How to Use AI for Confluence Documentation Review](/blog/ai-for-confluence-documentation-review.md): Use AI to review and improve Confluence documentation. Learn how to audit content quality, identify gaps, and ensure consistency across your knowledge base. - [How to Use AI for Jira Sprint Planning and Velocity Prediction](/blog/ai-for-jira-sprint-planning-velocity-prediction.md): Use AI to improve Jira sprint planning with velocity prediction, capacity forecasting, and scope recommendations. Learn how AI helps teams plan more accurately. - [AI for Jira Workflows: Automate Triage, Assignment, and Prioritization](/blog/ai-for-jira-workflows-automate-triage-assignment.md): Use AI to automate Jira workflow tasks like issue triage, assignment, and prioritization. Learn native AI features and third-party tools for smarter issue management. - [AI Meeting Notes in Confluence: Capture and Share Automatically](/blog/ai-meeting-notes-confluence.md): Automatically generate AI meeting notes in Confluence. Learn how to transcribe, summarize, and share meeting outcomes with action items and decisions. - [AI-Powered Confluence Search: Find Anything Fast](/blog/ai-powered-confluence-search.md): Improve Confluence search with AI-powered features. Learn semantic search, natural language queries, and how to configure Atlassian Intelligence for better search results. - [Archive](/blog/archive.md): Archive - [Authors](/blog/authors.md) - [How to Auto-Number Headings in Confluence (H1–H6, With Live Preview)](/blog/auto-number-headings-confluence.md): Automatically number Confluence headings 1.1, 1.2, 1.2.1 style across H1-H6. Decimal, Roman, and alphabetic numbering with hierarchical indentation — no manual numbering. - [Best Confluence Apps & Plugins in 2026 — Developer Tools Compared](/blog/best-confluence-apps-developers.md): The best Confluence apps and plugins in 2026. Compare code block apps, diagram tools, markdown editors, font apps, FAQ sections, and page builders. Curated by NGPILOT with honest feature comparisons. - [How to Add a Block Quote in Confluence (3 Methods Compared)](/blog/block-quote-confluence.md): Add a block quote in Confluence with the native indent tool, Markdown blockquote syntax, or a styled panel macro. Step-by-step with examples, plus how to nest and style quotes. - [How to Make Text Bold or Strikethrough in Confluence (Ctrl+B, Toolbar & Markdown)](/blog/bold-text-confluence.md): Make text bold in Confluence with the B button or Ctrl+B, or with Markdown ** bold ** syntax inside Enhanced Markdown. Covers keyboard shortcuts, strikethrough, and bold in tables. - [How to Build an AI Chatbot for Confluence Knowledge Base](/blog/build-ai-chatbot-confluence-knowledge-base.md): Create an AI chatbot that answers questions from your Confluence knowledge base. Learn no-code and code solutions for building a Confluence AI assistant. - [Build Modern Confluence Pages in 2026: Hero Sections & QR Codes](/blog/build-modern-confluence-pages-hero-articles-qr-forms.md): Six ways to make Confluence pages look like they belong on the modern web — hero sections, Medium-style article layouts, styled tables, QR codes, inline surveys, and glossary tooltips — all from inside the Confluence editor. - [How to Bulk Download All Jira Attachments (Step-by-Step Guide)](/blog/bulk-download-jira-attachments.md): How to quickly download all attachments from Jira search results using Simple Bulk Attachment Downloader — tips for organizing, handling large sets, and troubleshooting. - [Confluence Code Block Themes — Dark Mode, Monaco Editor & 85+ Languages](/blog/code-blocks-confluence-monaco-editor.md): Complete guide to Confluence code block themes. Compare syntax highlighting apps: Modern Code Blocks vs Better Code Macro. Auto dark/light mode, Monaco editor, 85+ languages. Free for up to 10 users. - [How to Configure Google Fonts in Confluence (Step-by-Step)](/blog/configure-google-fonts-confluence.md): Step-by-step guide to installing and configuring Google Fonts for Confluence pages using the Google Fonts for Confluence app. Includes live preview tips and performance considerations. - [Dark Mode for Confluence Code Blocks — Setup Walkthrough](/blog/confluence-code-editor-syntax-highlighting.md): Step-by-step setup walkthrough for enabling dark mode and syntax highlighting in Confluence code blocks with Modern Code Blocks. Companion to the main code blocks guide. - [Can You Change the Font in Confluence? (Default Stack & Custom Font Options)](/blog/confluence-default-font-change-font.md): You can't change Confluence's default font globally, but you can style page text with custom fonts via macro. Here's what's possible, what isn't, and how Confluence's font stack works. - [Best Diagram Tool for Confluence — Mermaid vs Excalidraw vs Graphviz](/blog/confluence-diagram-tools-comparison.md): Compare the 3 best diagram tools for Confluence: Mermaid (text-based), Excalidraw (visual canvas) and Graphviz (network graphs). Features, pricing and best use cases. - [Drawing vs Diagramming in Confluence — Canvas vs Text vs Graph](/blog/confluence-drawing-diagramming-tools.md): When to use a freeform canvas (Excalidraw), text-based diagrams (Mermaid), or auto-layout graphs (Graphviz) in Confluence. Companion to the main diagram tools comparison. - [Expand Macro for Confluence: Collapsible Sections Compared (Native vs Styled)](/blog/confluence-expand-macro.md): Confluence's expand macro hides long content behind a click. How the native expand works, where it falls short (no icons, one section at a time, plain styling), and styled accordion alternatives. - [Confluence Font Apps Compared: Google Fonts vs Custom Fonts Pro](/blog/confluence-font-apps-comparison.md): Compare Confluence font apps: Google Fonts for Confluence by NGPILOT vs Fonts for Confluence vs Custom Fonts Pro. Features, pricing, ratings, and pros/cons for each. - [Free Diagram Apps for Confluence — Excalidraw & Free-Tier Limits](/blog/confluence-free-diagram-plugin.md): Which Confluence diagram apps are free, and what the free tier (10-user) actually covers: Mermaid Plus, Excalidraw Plus, Graphviz Charts. Companion to the main diagram tools comparison. - [Best Confluence Import/Export Apps Compared — 2026 Guide](/blog/confluence-import-export-comparison.md): Compare Confluence import/export apps: Scroll PDF, Scroll Word, Markdown Exporter, Content Exporter, and more. Features, ratings, and honest pros/cons from real marketplace data. - [JSON Formatting & Display in Confluence: Code Blocks vs Structure Viewer](/blog/confluence-json-schema-viewer.md): How to format, highlight, and display JSON in Confluence. Modern Code Blocks for syntax-highlighted JSON (Monaco, 50+ themes) vs JSON Structure Viewer for an interactive tree. Comparison and step-by-step. - [Enhanced Markdown vs Other Confluence Markdown Apps — Feature Matrix](/blog/confluence-markdown-editor-comparison.md): Feature matrix comparing Enhanced Markdown for Confluence against other Confluence Markdown apps: raw mode, WYSIWYG, charts, PlantUML, table merging. Companion to the main Markdown editor FAQ. - [Markdown Tables in Confluence — Syntax Reference & Alignment](/blog/confluence-markdown-tables.md): Syntax reference for GitHub Flavored Markdown tables in Confluence via Enhanced Markdown: pipe syntax, column alignment, merged cells, and pasting from GitHub. Companion to the main Markdown editor FAQ. - [Monospace in Confluence: How to Format Inline Code (Shortcuts & Markdown)](/blog/confluence-monospace.md): Format inline code in Confluence with the code shortcut (Ctrl+Shift+M), backtick autoformatting, or Markdown syntax in Enhanced Markdown. Inline vs code block. - [Best Numbered Headings App for Confluence — 2026 Comparison](/blog/confluence-numbered-headings-comparison.md): Compare every Confluence numbered headings app on the Marketplace: Modern Numbered Headings, Appfire Numbered Headings, Easy Numbered Headings, and more. Features, ratings, and honest pros and cons. - [Confluence Pagination: How to Paginate Pages and Tables (3 Methods)](/blog/confluence-pagination.md): Confluence has no built-in pagination for pages or tables. Split long content into a page series with Prev/Next buttons, chunk in-page, or restructure tables. - [Confluence Permissions: The Ultimate Guide (2026)](/blog/confluence-permissions-ultimate-guide-2026.md): Master Confluence permissions: space admin vs site admin, page restrictions, space permissions, and permission inheritance explained with step-by-step instructions. - [QR Code for Confluence — Which QR App Should Your Team Use?](/blog/confluence-qr-code-comparison.md): Compare Confluence QR code apps: qr2page by Seibert, QR Code by NGPILOT, Moves QR Generator, and Barcodes for Confluence. Features, ratings, and honest pros/cons. - [Confluence FAQ Macro & Q&A Template: Add FAQ Sections to Pages](/blog/confluence-questions-answers-template.md): How to add an FAQ macro to Confluence and build Q&A sections. Two apps: Modern FAQ (accordion FAQ macro) and Modern Questions (community Q&A with voting and accepted answers). - [Confluence Source Editor Compared — Free vs Pro](/blog/confluence-source-editor-comparison.md): Compare Confluence source editor apps: Raw Storage Source Editor (free) vs Raw Storage Source Editor Pro. Edit Confluence storage format XML directly — fix broken macros, bulk-edit markup. - [Tabs in Confluence: Native Layout Tabs vs Tabs Macros Compared](/blog/confluence-tabs-macro.md): Confluence Cloud now has native page tabs. How the built-in layout tabs work, what tabs macros add (per-tab styling, images, positioning), and how to choose per page. - [Confluence Wiki Markup: How to View, Edit & Convert It](/blog/confluence-wiki-markup.md): Wiki markup in Confluence Cloud: where the legacy syntax went, how to view a page's storage format (with or without space admin), and safe ways to edit or convert it. - [Flowchart Syntax Reference for Confluence — Mermaid, DOT & Canvas](/blog/create-flowcharts-confluence.md): Copy-paste flowchart syntax for Confluence across Mermaid, Excalidraw, and Graphviz, with worked examples per tool. Companion to the main diagram tools comparison. - [How to Create Jira Issue Templates for Consistent Team Workflows](/blog/create-jira-issue-templates-for-consistent-workflows.md): Create reusable Jira issue templates to standardize bug reports, feature requests, and tasks. Learn native Jira templates, bulk create, and advanced template workflows. - [How to Create Jira Issues from Templates (3 Methods, With Examples)](/blog/create-jira-issues-from-templates.md): Stop retyping the same ticket structure. Create Jira issues from reusable templates — with variables, GitHub/Markdown import, and auto-apply. Step-by-step guide for bugs, incidents, and feature requests. - [Create Mermaid diagrams in Confluence: a step-by-step guide](/blog/create-mermaid-diagrams-confluence.md): How to write and preview Mermaid diagrams inside Confluence using Mermaid Plus and related plugins. Includes full list of supported diagram types with short examples you can copy-paste into Confluence. - [Mermaid App Roundup for Confluence — Mermaid Plus vs Stratus vs weweave](/blog/create-mermaid-diagrams-in-confluence.md): Roundup of Mermaid diagram apps for Confluence: Mermaid Plus, Mermaid Diagrams by Stratus, Mermaid Charts by weweave. Feature and ratings comparison. Companion to the main diagram tools comparison. - [How to Display JSON, XML, YAML & Code in Confluence (With Syntax Highlighting)](/blog/display-json-xml-code-in-confluence.md): Format and syntax-highlight JSON, XML, YAML, SQL, and 85+ languages in Confluence pages using a Monaco-powered editor. Step-by-step guide for API docs, config references, and developer wikis. - [Does Confluence Support Mermaid? Setup Guide & Diagram Types](/blog/does-confluence-support-mermaid.md): Confluence does not support Mermaid natively. Learn how to add Mermaid diagrams to Confluence with Mermaid Plus — flowcharts, sequence, Gantt, class, ER, mindmaps, and 20+ more types. - [How to Edit the Confluence Storage Format (And When You'd Need To)](/blog/edit-confluence-storage-format-source-editor.md): Edit the raw XML storage format of Confluence pages directly — format documents, find and replace, diff changes, and fix broken macros. A power-user guide for admins and developers. - [How to Display & Format JSON in Confluence (Code Blocks + Viewer)](/blog/embed-json-confluence.md): Two ways to embed JSON in Confluence: Modern Code Blocks for syntax-highlighted, themed JSON snippets (Monaco editor), and JSON Structure Viewer for an interactive collapsible tree. Step-by-step with examples. - [Excalidraw AI Agent for Confluence: Whiteboards You Can Talk To](/blog/excalidraw-ai-agent-confluence.md): Whiteboards are for people; text is what AI speaks. The new Excalidraw Plus agent closes the gap in Confluence: draw whiteboards from a prompt, edit shapes in plain language, search a space, and convert Mermaid and PlantUML. - [How to Add Excalidraw Whiteboards to Jira Issues (Setup Guide)](/blog/excalidraw-whiteboards-jira.md): How to create and collaborate on Excalidraw whiteboards inside Jira issues using Excalidraw Diagrams plus Whiteboards for Jira. Covers setup, sharing, and best practices. - [How to Export Jira Audit Logs for Compliance and Security Reviews](/blog/export-jira-audit-logs-compliance.md): Export Jira audit logs for compliance audits, security reviews, and change tracking. Learn native Jira audit log, JQL-based exports, and third-party tools for detailed logging. - [Export Jira Issues to Excel or CSV: Complete Guide (2026)](/blog/export-jira-issues-to-excel.md): Step-by-step guide to export Jira issues to Excel (XLS/XLSX) or CSV using Simple Bulk Issues — with JQL examples, field selection tips, and performance best practices. - [How to Export Jira Issues to Excel for Stakeholder Reporting](/blog/export-jira-issues-to-excel-csv-reporting.md): Export Jira issues to Excel and CSV for stakeholder reporting. Learn native export, JQL-based exports, and advanced techniques for custom reports and dashboards. - [Jira Bulk Operations FAQ: Exports, Edits & Downloads](/blog/faq-bulk-operations-jira.md): How to safely run bulk operations in Jira: export, edit, and download issues and attachments in batches. Includes permissions, rollback, and performance tips. - [Modern Code Blocks Performance & Large Snippet FAQ](/blog/faq-code-blocks-performance.md): Performance FAQ for Modern Code Blocks in Confluence: handling large code samples, lazy loading, max-height, and DOM size. Companion to the main code blocks guide. - [Confluence Dark Mode Apps FAQ: Themes, Fonts & Code Blocks](/blog/faq-confluence-dark-mode-apps.md): Answers about dark mode in Confluence: which apps support it, how to configure dark themes for code blocks, diagrams, fonts, and what Confluence's native dark mode covers. - [How to Write Markdown in Confluence — Syntax, Tables & Code Blocks](/blog/faq-confluence-markdown-editor.md): Write Markdown directly in Confluence with syntax highlighting, tables, code blocks and images. See how Enhanced Markdown compares to the native WYSIWYG editor — with examples. - [Markdown vs WYSIWYG in Confluence — When to Pick Which](/blog/faq-confluence-markdown-vs-wysiwyg.md): Decision guide for choosing Markdown vs WYSIWYG editing in Confluence by content type and team. Companion to the main Markdown editor FAQ, which covers syntax and setup. - [Mermaid Sequence Diagrams in Confluence: FAQ & Examples](/blog/faq-confluence-mermaid-sequence-diagram.md): Answers to common questions about creating sequence diagrams with Mermaid in Confluence: syntax, participants, arrows, alt blocks, loops, notes, and troubleshooting. - [Confluence Page Navigation FAQ: TOC, Numbered Headings & Structure](/blog/faq-confluence-page-navigation-apps.md): Answers about improving page navigation in Confluence: table of contents, numbered headings, anchor links, collapsible sections, and which apps help readers find content faster. - [Confluence Whiteboard Apps FAQ: Excalidraw, draw.io & Built-in Compared](/blog/faq-confluence-whiteboard-apps.md): Compare whiteboard and drawing apps for Confluence: Excalidraw Plus, draw.io, and Confluence's built-in whiteboard. Features, pricing, performance, and which one to pick for your team. - [FAQ: Widget Carousel for Confluence — Image Sliders, Banners & Dashboards](/blog/faq-confluence-widget-carousel.md): Everything you need to know about Widget Carousel for Confluence: image sliders, carousel modes, navigation controls, responsive design, and how it compares to Confluence's built-in gallery macro. - [FAQ: EPUB Reader for Confluence — Everything You Need to Know](/blog/faq-epub-reader-confluence.md): Answers to common questions about reading EPUB files in Confluence, including supported formats, embedding eBooks on pages, mobile support, navigation features, and file size limits. - [Excalidraw for Confluence & Jira: FAQ, Tips & Best Practices](/blog/faq-excalidraw-best-practices.md): Answers to common questions about Excalidraw in Confluence and Jira: storage, export, collaboration, performance, and accessibility tips. - [Running Design Whiteboarding Sessions in Confluence — Why We Picked Excalidraw over draw.io](/blog/faq-excalidraw-vs-drawio-confluence.md): How a product team runs design and architecture whiteboarding sessions inside Confluence. The workflow that made us choose Excalidraw over draw.io — plus the honest feature comparison so you can decide for your team. - [Export Jira Issues to CSV/Excel: Common Problems & FAQ](/blog/faq-exporting-jira-issues.md): Troubleshoot Jira issue exports to CSV and Excel. Fix field mismatches, encoding issues, custom field exports, timeouts, and automate recurring exports. - [Confluence Custom Fonts FAQ: Change Fonts, Setup & Alternatives](/blog/faq-google-fonts-confluence-alternatives.md): How to change the default font in Confluence pages. Custom font setup, Google Fonts alternatives, pricing, performance impact, and which typography app fits your team. - [Google Fonts for Confluence: Performance Impact & FAQ](/blog/faq-google-fonts-performance.md): Learn how Google Fonts affect Confluence page performance, how to reduce font loading time, and best practices for using custom typography in your workspace. - [Confluence Graphviz Diagrams: DOT Language FAQ & Examples](/blog/faq-graphviz-charts-confluence.md): How to create Graphviz diagrams in Confluence. DOT language syntax, supported diagram types, auto-layout, styling, export, and comparison with Mermaid. Includes copy-paste DOT examples. - [Customize Jira Announcement Banner — Rich Text, Scheduling & Targeting](/blog/faq-jira-announcement-banner-customization.md): How to customize Jira announcement banners with rich text, emojis, scheduling, and per-project visibility. Modern Announcement Banner extends Jira's native banner — free for up to 10 users. - [Jira Attachment Permissions FAQ: Download, Access & Troubleshoot](/blog/faq-jira-attachments-permissions.md): Fix Jira attachment download issues, permission errors, missing files after migration, and troubleshoot bulk downloader problems. - [Jira Issue Templates FAQ: Auto-Apply, Variables & Automation](/blog/faq-jira-issue-templates-automation.md): Answers to common questions about Jira issue templates: auto-apply rules, template variables, GitHub import, and how to automate consistent ticket creation across projects. - [All 30 Mermaid Diagram Types in Confluence: Complete Reference](/blog/faq-mermaid-diagram-types-confluence.md): The complete list of all 30 Mermaid diagram types supported in Confluence — flowchart, sequence, ER, class, state, Gantt, C4, swimlane, timeline, git graph, pie, mindmap, and more. Keywords, categories, when to use each, and copy-paste syntax. - [Documenting Microservice Architectures in Confluence with Mermaid](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md): How engineering teams use Mermaid to document microservices in Confluence: service maps, request flows, sequence diagrams and ERDs. Copy-paste syntax patterns for each, plus a full node-shape and arrow reference. - [Mermaid in Confluence Not Rendering? Fixes & FAQ](/blog/faq-mermaid-troubleshooting.md): Fix Mermaid diagrams not rendering in Confluence. Covers syntax errors, performance, color issues, and export problems with step-by-step solutions. - [Modern FAQ vs Modern Questions for Confluence — Feature Comparison](/blog/faq-questions-confluence-comparison.md): Feature comparison of Modern FAQ vs Modern Questions for Confluence: when to use curated FAQ sections vs community Q&A. Companion to the main Q&A template guide. - [Are Confluence & Jira Plugins Safe? Marketplace App Security Guide](/blog/faq-using-plugins-security.md): How to evaluate Atlassian Marketplace app security: Forge vs Connect data residency, scope review, Cloud Fortified, least privilege, and a plugin security checklist for admins. - [Forge vs Connect: What Atlassian Admins Need to Know in 2026](/blog/forge-vs-connect-atlassian-admins-2026.md): Forge and Connect are the two ways Atlassian Marketplace apps are built. This guide explains the real differences — hosting, security, the 2026 Connect penalty, and what it means for admins evaluating apps. - [Google Fonts for Confluence — Which Custom Typography App Fits Your Team?](/blog/google-fonts-confluence-custom-typography.md): Compare Confluence font apps: Google Fonts, Fonts for Confluence, Custom Fonts Pro, and more. Features, pricing, and honest pros/cons. - [Graphviz Charts in Confluence: draw.io vs Graphviz vs Mermaid](/blog/graphviz-charts-confluence-comparison.md): Compare Confluence graph and chart apps: draw.io, Graphviz Charts, Mermaid, Lucidchart. Features, ratings, and honest pros/cons from real marketplace data. - [How to Change Fonts in Confluence (Google Fonts, Custom Typography & More)](/blog/how-to-add-custom-fonts-confluence.md): How to change fonts in Confluence pages using Google Fonts for Confluence macro. Choose from 1942+ font families, apply to selected text, pair fonts, and follow brand guidelines. - [How to Add SVG Illustrations to Confluence Pages](/blog/how-to-add-svg-illustrations-confluence.md): Step-by-step guide to inserting professional SVG illustrations into Confluence pages using Content Craft for Confluence. Covers installation, gallery browsing, keyword search, category filtering, and real-world use cases. - [Modern FAQ Themes & Reordering — Accordion vs Centered](/blog/how-to-build-faq-sections-confluence.md): How to theme and reorder FAQ sections in Confluence with Modern FAQ: accordion vs centered layouts, drag-and-drop ordering, and styling tips. Companion to the main Q&A template guide. - [How to Choose a Markdown Editor for Confluence](/blog/how-to-choose-markdown-editor-confluence.md): Confluence has no native Markdown support. This guide compares the options — from paste-and-convert tools to full Markdown macros with live preview, math, and diagrams — so you can pick the right one for your team. - [How to Create Architecture Diagrams in Confluence (3 Methods with Examples)](/blog/how-to-create-architecture-diagrams-confluence.md): Step-by-step guide to creating architecture diagrams in Confluence using Mermaid, Excalidraw, or Diagram Duo. Includes copy-paste Mermaid examples for microservices, AWS, and C4 diagrams. - [Create UML Class Diagrams in Confluence — Free with Mermaid](/blog/how-to-create-class-diagrams-confluence.md): Create UML class diagrams in Confluence with Mermaid Plus. Covers inheritance, composition, visibility, generics, namespaces, and 3 copy-paste examples. Free for up to 10 users. - [ER Diagrams in Confluence: How to Add, Create, and Render Database Schemas](/blog/how-to-create-er-diagrams-confluence.md): Add an ER (entity-relationship) diagram to Confluence with Mermaid Plus. Covers how to embed database schema diagrams, the full erDiagram syntax, key types, cardinality, and 3 copy-paste examples including e-commerce and SaaS schemas. - [Manual Toggles vs Modern FAQ for Confluence — 3 Methods Compared](/blog/how-to-create-faq-pages-confluence.md): Comparison of three ways to build FAQ pages in Confluence: manual toggle macros, Modern FAQ, and template-based approaches. Companion to the main Q&A template guide. - [How to Create a Flowchart in Jira — 3 Methods with Copy-Paste Examples](/blog/how-to-create-flowchart-in-jira.md): Create flowcharts in Jira using the native whiteboard or Mermaid syntax. 3 copy-paste examples for bug triage, approval workflows and incident escalation. Free for up to 10 users. - [How to Create Gantt Charts in Confluence — Mermaid Examples](/blog/how-to-create-gantt-charts-confluence.md): Create Gantt charts in Confluence using Mermaid syntax. 3 copy-paste examples for project timelines, sprint planning and marketing campaigns. Free for up to 10 users. - [Create Jira Issue Templates — Import from GitHub, Markdown & Rich Text](/blog/how-to-create-jira-issue-templates.md): Create Jira issue templates for bug reports, user stories and sprint tasks. Import from GitHub and Markdown, rich text formatting, auto-apply rules. Free for up to 10 users. - [How to Create Math and Technical Animations in Confluence Using Manim](/blog/how-to-create-math-animations-confluence.md): Step-by-step guide to creating mathematical animations in Confluence with Manim. Build equation derivations, geometric transformations, and animated proofs directly on your pages. - [Create Mermaid Diagrams on Jira Issues — Flowcharts, Sequence & More](/blog/how-to-create-mermaid-diagrams-jira.md): Add Mermaid flowcharts, sequence diagrams and class diagrams directly to Jira issues. Copy-paste examples for bug reproduction, API flows and design discussions. Free for up to 10 users. - [Create Mind Maps in Confluence — Free with Mermaid Plus](/blog/how-to-create-mindmaps-confluence.md): Create mind maps in Confluence with Mermaid Plus. Syntax reference, copy-paste examples for brainstorming, and tips for organizing ideas. Free for up to 10 users. - [Create Pie Charts in Confluence — Free with Mermaid Syntax](/blog/how-to-create-pie-charts-confluence.md): Create pie charts and data visualizations in Confluence with Mermaid syntax. Copy-paste examples for surveys, budgets and project allocation. Free for up to 10 users. - [How to Build a Release Timeline in Jira — 3 Methods with Copy-Paste Examples](/blog/how-to-create-release-timeline-jira.md): Build a release timeline in Jira with Mermaid Gantt syntax. 3 copy-paste examples for version milestones, parallel team tracks and launch day sequencing. Free for up to 10 users. - [How to Create Sequence Diagrams in Confluence (Mermaid Examples)](/blog/how-to-create-sequence-diagrams-confluence.md): Step-by-step guide to creating sequence diagrams in Confluence using Mermaid Plus. Includes copy-paste examples for API flows, user authentication, and microservice communication. - [Create State Diagrams in Confluence — Mermaid Syntax & Examples](/blog/how-to-create-state-diagrams-confluence.md): Create state diagrams in Confluence with Mermaid Plus. Covers stateDiagram syntax, transitions, composite states, notes, and 3 copy-paste examples. Free for up to 10 users. - [How to Create Wireframes and UI Mockups in Confluence with Excalidraw Plus](/blog/how-to-create-wireframes-confluence.md): Step-by-step tutorial for creating wireframes and UI mockups directly in Confluence using Excalidraw Plus. Covers shape libraries, layout grids, component patterns, and prototyping workflows. - [How to Evaluate an Atlassian Marketplace App: A Security Checklist](/blog/how-to-evaluate-atlassian-marketplace-app.md): A practical security checklist for evaluating Atlassian Marketplace apps before you install them — Cloud Fortified status, scopes, data residency, Forge vs Connect, and the questions every admin should ask. - [How to Migrate Confluence Content — Server-to-Cloud, Space Moves & Format Conversion](/blog/how-to-migrate-confluence-content.md): Complete Confluence content migration guide: Server/Data Center to Cloud, space reorganization, M&A consolidation, and Markdown/HTML/JSON format conversion. Tools, pitfalls, and a migration checklist. - [How to Set Up Announcement Banners in Confluence and Jira](/blog/how-to-set-up-announcement-banners-confluence-jira.md): Step-by-step guide to creating announcement banners in Confluence and Jira. Covers native options, Modern Announcement Banner for Jira, customization tips, and best practices for maintenance alerts. - [How to Use ChatGPT in Confluence: AI-Powered Writing for Better Docs](/blog/how-to-use-chatgpt-in-confluence.md): Integrate ChatGPT with Confluence to write, edit, and improve documentation faster. Learn native AI features, third-party apps, and prompt engineering for Confluence content. - [How to Add Numbered Headings in Confluence (Auto-Number H1-H6)](/blog/how-to-use-numbered-headings-confluence.md): Step-by-step guide to adding automatic numbered headings in Confluence. Set up H1-H6 auto-numbering with decimal, Roman, and alphanumeric schemes. Includes TOC integration and best practices. - [How to Use QR Codes in Confluence: Complete Guide](/blog/how-to-use-qr-codes-confluence.md): Step-by-step guide to adding QR codes to Confluence pages. Generate QR codes for URLs, text, email addresses, phone numbers, and more using QRCode for Confluence by NGPILOT. - [Enhanced Markdown Setup Tutorial — Insert Macro, Modes & Publish](/blog/how-to-write-markdown-in-confluence.md): Step-by-step setup tutorial for Enhanced Markdown for Confluence: install, insert the macro, switch raw/WYSIWYG modes, and publish. Companion to the main Markdown editor FAQ. - [Import Markdown into Confluence: Paste, GitHub, .md Files](/blog/import-markdown-into-confluence.md): Move Markdown into Confluence without losing formatting: paste a .md document into a live-preview macro, tables and code fences render as-is. Copy-paste workflow inside. Free for up to 10 users. - [Jira Attachment Management Apps Compared: Bulk Downloader vs Attachment Reviewer](/blog/jira-attachment-management-comparison.md): Compare NGPILOT's Jira attachment apps: Simple Bulk Attachment Downloader for bulk exports and Attachment Reviewer for file policy enforcement. Features, use cases, and which one fits your team. - [Jira Backlog Grooming: The Complete Guide to Refining Stories](/blog/jira-backlog-grooming-complete-guide.md): Master Jira backlog grooming with a proven refinement workflow. Learn how to write acceptance criteria, estimate story points, and keep your backlog sprint-ready. - [How to Add a Checklist to Jira — and Block Transitions Until Done](/blog/jira-checklist.md): Three ways to add checklists to Jira issues — description bullets, subtasks, and a checklist app with required items that block workflow transitions. Includes a definition-of-done template and JQL queries. - [How to Create a Component Hierarchy in Jira](/blog/jira-component-hierarchy.md): Jira components are a flat list. Three ways to build a parent-child hierarchy — naming conventions, labels, and a component tree app with subtree-wide JQL. Copy-paste examples included. - [How to Set Up Jira Dashboards for Sprint Tracking and Stakeholder Visibility](/blog/jira-dashboard-sprint-tracking-setup.md): Build effective Jira dashboards for sprint health, team velocity, and stakeholder reporting. Includes gadget configurations, filter setup, and dashboard sharing best practices. - [Best Diagram App for Jira — 2026 Comparison with Mermaid & Excalidraw](/blog/jira-diagram-apps-comparison.md): Compare Jira diagram apps: draw.io, Mermaid Charts, Excalidraw Whiteboard, Draw UI, and more. Features, ratings, and honest pros/cons from real marketplace data. - [Jira Export Limit: How to Export More Than 1,000 Issues (2026)](/blog/jira-export-limit.md): Hit Jira's 1,000-issue export limit? Three ways to export more, including Simple Bulk Issues' new 5,000-issue export with field selection and truncation notices. - [How to See Who Changed What in Jira — Field-Level Issue History](/blog/jira-issue-history.md): Who changed what on a Jira issue? Three ways to read issue history — the History tab, the REST changelog, and a panel with word-level diffs, cross-issue reports, and CSV export. - [Jira issue templates: best practices for consistent ticket creation](/blog/jira-issue-templates-best-practices.md): How to use Modern Issue Templates for Jira to create standardized, reusable issue templates. Covers template design, auto-apply rules, and GitHub import for teams that want consistent tickets. - [Issue Templates for Jira — Templating.app & Top Apps Compared](/blog/jira-issue-templates-comparison.md): Compare Jira issue template apps: Issue Templates by Deviniti, Templating.app by Seibert, Easy Issue Templates by AppLiger, Issue Templates Pro by Narva, and more. Features, ratings, and honest pros/cons. - [Jira JQL Cheat Sheet: 20 Queries Every Team Needs](/blog/jira-jql-cheat-sheet-common-queries.md): Master Jira JQL with 20 essential queries for finding issues, tracking sprints, and reporting. Includes copy-paste examples for common filters and dashboards. - [How to View JSON in Jira — Fields, Entity Properties & Pasted Payloads](/blog/jira-json-viewer.md): Three ways to read JSON in Jira — raw fields, browser dev tools, and an issue-panel graph viewer that turns any JSON into an expandable node tree. With copy-paste examples. - [Jira Permissions Explained: How to Set Up Project Security Without Breaking Workflows](/blog/jira-permissions-explained-project-security-setup.md): Configure Jira project permissions, roles, and schemes to control who can view, create, and transition issues. Includes permission schemes, role-based access, and common permission patterns. - [How to Run Jira Sprint Retrospectives That Drive Real Change](/blog/jira-sprint-retrospectives-that-drive-change.md): Run effective Jira sprint retrospectives with a structured format. Learn facilitation techniques, action item tracking, and how to turn feedback into measurable improvements. - [Jira vs Confluence: What Each Is Actually For (with Examples)](/blog/jira-vs-confluence.md): Jira and Confluence are often bought together but solve different problems. This guide explains what each is for, when to use which, and how they connect — with concrete examples, not marketing copy. - [Jira Workflow Automation: Complete Guide (2026)](/blog/jira-workflow-automation-complete-guide-2026.md): Automate Jira workflows with automation rules, triggers, and conditions. Step-by-step guide to reducing manual work and human error in Jira. - [Jira Workflow Automation: How to Automate Repetitive Tasks and Save Hours](/blog/jira-workflow-automation-guide.md): Automate Jira workflows with built-in automation rules. Learn triggers, conditions, and actions for common automations like assignee rotation, status updates, and notifications. - [Why Markdown Became the Documentation Format of the AI Era](/blog/markdown-ai-era-documentation-format.md): Markdown beat docx, HTML, RTF and plain text as the default format for technical docs — and the AI era locked it in. The token economics, the tooling, and what AI-native documentation needs inside Confluence. - [Markdown Code Blocks in Confluence — 190+ Languages](/blog/markdown-code-block-confluence.md): Paste fenced Markdown code blocks into Confluence and get syntax highlighting for 190+ languages with GitHub themes and copy buttons. Copy-paste examples inside. Free for up to 10 users. - [Math Equations in Confluence: LaTeX & KaTeX via Markdown](/blog/markdown-math-equations-confluence.md): Write LaTeX and KaTeX math equations in Confluence with Markdown. Copy-paste inline math, display equations, and aligned derivation examples. Free for up to 10 users. - [Meeting Notes in Confluence with Markdown (Copy-Paste Template)](/blog/markdown-meeting-notes-confluence.md): Run meeting notes in Confluence as Markdown: a copy-paste template with decision and action tables, code fences for snippets, and a split-pane view for live note-taking. - [From Markdown Notes to a Mind Map in Confluence — No Drawing](/blog/markdown-mind-map-confluence.md): Turn a Markdown outline into an interactive mind map on a Confluence page. Paste headings and bullets, get branches you can expand and collapse — no canvas, no syntax to learn. - [Import Markdown into Confluence — 3 Methods Compared (2026)](/blog/markdown-to-confluence-converter.md): Import Markdown files into Confluence pages. Three methods compared: Enhanced Markdown editor, Modern Importer/Exporter, and copy-paste. Free for up to 10 users. - [Atlassian Marketplace App Selection Criteria for Enterprise](/blog/marketplace-app-selection-criteria-enterprise.md): Enterprise teams need a rigorous process for evaluating Atlassian Marketplace apps. This guide covers the 10 criteria security, procurement, and IT teams should check before approving an app — from Cloud Fortified to data residency to vendor viability. - [Mermaid 12 in Confluence & Jira: UML Use Case Diagrams and a New Look](/blog/mermaid-12-confluence-jira.md): Mermaid 12 is now live in Enhanced Markdown for Confluence, Mermaid Plus Diagrams & AI Agent for Confluence, and Mermaid Plus Diagrams for Jira — with UML use case diagrams (usecase-beta), a new default layout engine, and refreshed diagram styling. Copy-paste example included. - [Mermaid AI Agent for Confluence: Create, Update & Convert Diagrams by Chat](/blog/mermaid-ai-agent-confluence.md): How the Mermaid Plus AI agent works in Confluence: create diagrams from a prompt, read back the source, update in place, convert code blocks. With prompts to try. - [API Sequence Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-api-sequence-diagram-confluence.md): Document API flows in Confluence with Mermaid sequence, packet and ZenUML diagrams. 3 copy-paste examples for request traces, protocol frames and async flow. Rendered with Mermaid Plus Diagrams & AI Agent for Confluence. - [System Architecture Diagrams in Confluence with Mermaid C4](/blog/mermaid-c4-system-architecture-confluence.md): Document system architecture in Confluence with Mermaid C4, architecture and block diagrams. 3 copy-paste examples: system context, container API flow and infrastructure topology. Rendered with Mermaid Plus Diagrams & AI Agent for Confluence. - [Mermaid Charts for Confluence Dashboards: Pie & XY in One Post](/blog/mermaid-charts-dashboard-confluence.md): Build data charts in Confluence with Mermaid pie and XY charts. 3 copy-paste examples for share-of-work, weekly trends and release metrics dashboards. Rendered with Mermaid Plus Diagrams & AI Agent for Confluence. - [CI/CD Pipeline Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-ci-cd-pipeline-diagram-confluence.md): Document your deploy pipeline in Confluence with Mermaid. 3 copy-paste CI/CD examples for linear stages, quality gates and deploy-to-tag flows. Rendered live with Mermaid Plus Diagrams & AI Agent for Confluence. - [Document Your Codebase in Confluence with Mermaid Class Diagrams](/blog/mermaid-class-diagram-document-codebase-confluence.md): Put your codebase architecture in Confluence with Mermaid class diagrams. 3 copy-paste examples for onboarding, module boundaries and API sketches. Rendered live with Mermaid Plus Diagrams & AI Agent for Confluence. - [Decision Framework Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-decision-framework-diagrams-confluence.md): Run better decisions in Confluence with Mermaid Venn, Cynefin and quadrant diagrams. 3 copy-paste examples for overlap analysis, sense-making and prioritization. Rendered with Mermaid Plus Diagrams & AI Agent for Confluence. - [Mermaid Diagrams for Jira Sprint Workflows — Which Diagrams Actually Help the Standup](/blog/mermaid-diagrams-jira-sprint-workflows.md): A sprint team's guide to the Mermaid diagram types that earn their place in Jira: flowcharts for definition-of-done, Gantt for sprint timelines, sequence diagrams for handoffs. Worked examples plus the full 30-type reference. - [Database Schema Diagrams in Confluence with Mermaid ER (Entity Relationship) — Copy-Paste](/blog/mermaid-er-diagram-database-schema-confluence.md): Document your database schema in Confluence with Mermaid ER (entity relationship) diagrams and class diagrams. 3 copy-paste examples for order tables, attribute mapping and relationship keys. Rendered with Mermaid Plus Diagrams & AI Agent for Confluence. - [Root Cause Analysis in Confluence with Mermaid Fishbone + 5 Whys](/blog/mermaid-fishbone-root-cause-analysis-confluence.md): Do root cause analysis in Confluence with Mermaid. Copy-paste ishikawa fishbone (6 cause categories) plus a 5 Whys flowchart that ends at one actionable fix. Free for up to 10 users. - [Visualize Git Branches & Releases Inside Jira with Mermaid GitGraph](/blog/mermaid-gitgraph-jira-branch-history.md): Put git branch and release history next to the issue. 3 copy-paste Mermaid gitGraph examples for feature branches, hotfixes and release tags — rendered live in Jira with Mermaid Plus Diagrams for Jira. - [Build an Incident Postmortem Timeline in Confluence (Mermaid, Copy-Paste)](/blog/mermaid-incident-postmortem-timeline-confluence.md): Build an incident postmortem timeline in Confluence with Mermaid. Copy-paste detection-to-resolution timeline plus a failure-path sequence diagram. Free for up to 10 users. - [Customer Journey Maps in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-journey-diagram-customer-confluence.md): Draw customer journey maps in Confluence with Mermaid journey diagrams. 3 copy-paste examples with satisfaction scores for onboarding, support and checkout flows. Rendered with Mermaid Plus Diagrams & AI Agent for Confluence. - [Kanban Board Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-kanban-board-workflow-confluence.md): Document team workflow in Confluence with Mermaid Kanban and state diagrams. 3 copy-paste examples for sprint boards, WIP-limit labels and issue lifecycle. Rendered with Mermaid Plus Diagrams & AI Agent for Confluence. - [Mind Maps & Hierarchy Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-mindmap-hierarchy-diagram-confluence.md): Brainstorm, outline and document structure in Confluence with Mermaid mindmap, tree view and treemap. 3 copy-paste examples for ideation, folder maps and nested priorities. Rendered with Mermaid Plus Diagrams & AI Agent for Confluence. - [Swimlane Process Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-process-flow-swimlane-diagram-confluence.md): Map cross-functional handoffs in Confluence with Mermaid swimlane and sequence diagrams. 3 copy-paste examples for ticket routing, approval steps and actor handoffs. Rendered with Mermaid Plus Diagrams & AI Agent for Confluence. - [Radar & Skill Matrix Charts in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-radar-skill-matrix-charts-confluence.md): Track skills and grammar in Confluence with Mermaid radar, treeView and railroad diagrams. 3 copy-paste examples for capability snapshots, repo trees and syntax. Rendered with Mermaid Plus Diagrams & AI Agent for Confluence. - [Requirements Traceability in Confluence with Mermaid Requirement Diagrams](/blog/mermaid-requirement-diagram-confluence.md): Track PRD to test coverage in Confluence with Mermaid requirement diagrams. 3 copy-paste examples for feature traceability, compliance checks and epic-to-test gaps. Rendered with Mermaid Plus Diagrams & AI Agent for Confluence. - [Roadmap & Prioritization Charts in Confluence with Mermaid](/blog/mermaid-roadmap-prioritization-charts-confluence.md): Plan and prioritize in Confluence with Mermaid Gantt charts, quadrant charts and Sankey flows. 3 copy-paste examples for quarter planning, effort-impact scoring and budget flows. Rendered with Mermaid Plus Diagrams & AI Agent for Confluence. - [Map States & Approval Workflows in Confluence with Mermaid](/blog/mermaid-state-diagram-workflow-confluence.md): Document state machines and approval chains in Confluence with Mermaid state diagrams. 3 copy-paste examples for issue workflows, spending approvals and retry loops. Rendered with Mermaid Plus Diagrams & AI Agent for Confluence. - [draw.io vs Mermaid in Confluence: Which Fits Your Docs?](/blog/mermaid-vs-drawio-confluence.md): draw.io now supports Mermaid, so the real difference is what happens to the source. Mermaid Plus Diagrams & AI Agent vs draw.io for Confluence: text-native vs shapes, AI, pricing. - [Mermaid vs PlantUML vs Graphviz for Confluence: Which Diagram Tool to Choose](/blog/mermaid-vs-plantuml-vs-graphviz-confluence.md): Three text-based diagramming languages, three different strengths. This guide compares Mermaid, PlantUML, and Graphviz for Confluence teams — syntax, diagram types, ease of use, and when to pick each. - [Blog](/blog/page/10.md): Blog - [Blog](/blog/page/11.md): Blog - [Blog](/blog/page/12.md): Blog - [Blog](/blog/page/13.md): Blog - [Blog](/blog/page/14.md): Blog - [Blog](/blog/page/15.md): Blog - [Blog](/blog/page/16.md): Blog - [Blog](/blog/page/17.md): Blog - [Blog](/blog/page/2.md): Blog - [Blog](/blog/page/3.md): Blog - [Blog](/blog/page/4.md): Blog - [Blog](/blog/page/5.md): Blog - [Blog](/blog/page/6.md): Blog - [Blog](/blog/page/7.md): Blog - [Blog](/blog/page/8.md): Blog - [Blog](/blog/page/9.md): Blog - [Paste Mermaid Diagrams into Confluence — Now on Mermaid 12](/blog/paste-mermaid-diagrams-into-confluence.md): Your diagrams live in the repo, your docs live in Confluence, and the paste breaks. How to paste Markdown with Mermaid 12 fences into Confluence and have the diagrams render. - [How to Plan Jira Sprints That Actually Work (Step-by-Step Guide)](/blog/plan-jira-sprints-that-actually-work.md): Learn how to plan Jira sprints effectively with a proven workflow covering backlog grooming, story point estimation, sprint capacity planning, and daily standups. - [RAG with Confluence: Build an AI Knowledge Base from Your Docs](/blog/rag-with-confluence-build-ai-knowledge-base.md): Build a RAG (Retrieval-Augmented Generation) system using Confluence as the knowledge base. Learn how to index, query, and extract answers from your Confluence content. - [How to Set Up Announcement Banners in Jira (Rich Text, Scheduling & Targeting)](/blog/set-up-announcement-banners-jira.md): Create Jira announcement banners with rich text, custom colors, dismissible option, and per-project visibility. Keep teams informed about maintenance, outages, and policy changes. Step-by-step guide. - [Tags](/blog/tags.md) - [One post tagged with "5-whys"](/blog/tags/5-whys.md) - [4 posts tagged with "accordion"](/blog/tags/accordion.md) - [5 posts tagged with "admin"](/blog/tags/admin.md) - [2 posts tagged with "administration"](/blog/tags/administration.md) - [One post tagged with "agc"](/blog/tags/agc.md) - [2 posts tagged with "agent"](/blog/tags/agent.md) - [5 posts tagged with "agile"](/blog/tags/agile.md) - [14 posts tagged with "ai"](/blog/tags/ai.md) - [14 posts tagged with "ai"](/blog/tags/ai/page/2.md) - [One post tagged with "animation"](/blog/tags/animation.md) - [3 posts tagged with "announcement-banner"](/blog/tags/announcement-banner.md) - [One post tagged with "answers"](/blog/tags/answers.md) - [2 posts tagged with "api"](/blog/tags/api.md) - [3 posts tagged with "api-documentation"](/blog/tags/api-documentation.md) - [One post tagged with "approval"](/blog/tags/approval.md) - [3 posts tagged with "architecture"](/blog/tags/architecture.md) - [2 posts tagged with "architecture-diagram"](/blog/tags/architecture-diagram.md) - [9 posts tagged with "atlassian"](/blog/tags/atlassian.md) - [4 posts tagged with "attachments"](/blog/tags/attachments.md) - [One post tagged with "audit"](/blog/tags/audit.md) - [One post tagged with "audit-logs"](/blog/tags/audit-logs.md) - [6 posts tagged with "automation"](/blog/tags/automation.md) - [One post tagged with "backlog-grooming"](/blog/tags/backlog-grooming.md) - [One post tagged with "backup"](/blog/tags/backup.md) - [One post tagged with "barcode"](/blog/tags/barcode.md) - [One post tagged with "best-apps"](/blog/tags/best-apps.md) - [2 posts tagged with "best-practices"](/blog/tags/best-practices.md) - [One post tagged with "block-diagram"](/blog/tags/block-diagram.md) - [One post tagged with "blockquote"](/blog/tags/blockquote.md) - [One post tagged with "bold"](/blog/tags/bold.md) - [3 posts tagged with "brainstorming"](/blog/tags/brainstorming.md) - [One post tagged with "branching"](/blog/tags/branching.md) - [One post tagged with "bug-template"](/blog/tags/bug-template.md) - [3 posts tagged with "bulk"](/blog/tags/bulk.md) - [One post tagged with "c4-model"](/blog/tags/c-4-model.md) - [One post tagged with "carousel"](/blog/tags/carousel.md) - [One post tagged with "changelog"](/blog/tags/changelog.md) - [4 posts tagged with "charts"](/blog/tags/charts.md) - [One post tagged with "chatbot"](/blog/tags/chatbot.md) - [One post tagged with "chatgpt"](/blog/tags/chatgpt.md) - [One post tagged with "cheat-sheet"](/blog/tags/cheat-sheet.md) - [One post tagged with "checklist"](/blog/tags/checklist.md) - [One post tagged with "ci-cd"](/blog/tags/ci-cd.md) - [3 posts tagged with "class-diagram"](/blog/tags/class-diagram.md) - [One post tagged with "code-block"](/blog/tags/code-block.md) - [One post tagged with "code-block-themes"](/blog/tags/code-block-themes.md) - [8 posts tagged with "code-blocks"](/blog/tags/code-blocks.md) - [One post tagged with "code-review"](/blog/tags/code-review.md) - [13 posts tagged with "comparison"](/blog/tags/comparison.md) - [13 posts tagged with "comparison"](/blog/tags/comparison/page/2.md) - [3 posts tagged with "compliance"](/blog/tags/compliance.md) - [One post tagged with "components"](/blog/tags/components.md) - [121 posts tagged with "confluence"](/blog/tags/confluence.md) - [One post tagged with "confluence-admin"](/blog/tags/confluence-admin.md) - [One post tagged with "confluence-apps"](/blog/tags/confluence-apps.md) - [One post tagged with "confluence-markdown-editor"](/blog/tags/confluence-markdown-editor.md) - [One post tagged with "confluence-tips"](/blog/tags/confluence-tips.md) - [121 posts tagged with "confluence"](/blog/tags/confluence/page/10.md) - [121 posts tagged with "confluence"](/blog/tags/confluence/page/11.md) - [121 posts tagged with "confluence"](/blog/tags/confluence/page/12.md) - [121 posts tagged with "confluence"](/blog/tags/confluence/page/13.md) - [121 posts tagged with "confluence"](/blog/tags/confluence/page/2.md) - [121 posts tagged with "confluence"](/blog/tags/confluence/page/3.md) - [121 posts tagged with "confluence"](/blog/tags/confluence/page/4.md) - [121 posts tagged with "confluence"](/blog/tags/confluence/page/5.md) - [121 posts tagged with "confluence"](/blog/tags/confluence/page/6.md) - [121 posts tagged with "confluence"](/blog/tags/confluence/page/7.md) - [121 posts tagged with "confluence"](/blog/tags/confluence/page/8.md) - [121 posts tagged with "confluence"](/blog/tags/confluence/page/9.md) - [One post tagged with "connect"](/blog/tags/connect.md) - [One post tagged with "content-craft"](/blog/tags/content-craft.md) - [One post tagged with "content-formatting"](/blog/tags/content-formatting.md) - [One post tagged with "content-transfer"](/blog/tags/content-transfer.md) - [One post tagged with "converter"](/blog/tags/converter.md) - [4 posts tagged with "csv"](/blog/tags/csv.md) - [2 posts tagged with "custom-fonts"](/blog/tags/custom-fonts.md) - [One post tagged with "customer-experience"](/blog/tags/customer-experience.md) - [3 posts tagged with "customization"](/blog/tags/customization.md) - [One post tagged with "cynefin"](/blog/tags/cynefin.md) - [3 posts tagged with "dark-mode"](/blog/tags/dark-mode.md) - [2 posts tagged with "dashboard"](/blog/tags/dashboard.md) - [One post tagged with "dashboards"](/blog/tags/dashboards.md) - [One post tagged with "data-visualization"](/blog/tags/data-visualization.md) - [2 posts tagged with "database"](/blog/tags/database.md) - [One post tagged with "decision"](/blog/tags/decision.md) - [One post tagged with "definition-of-done"](/blog/tags/definition-of-done.md) - [One post tagged with "deployment"](/blog/tags/deployment.md) - [One post tagged with "design"](/blog/tags/design.md) - [9 posts tagged with "developer-tools"](/blog/tags/developer-tools.md) - [2 posts tagged with "developers"](/blog/tags/developers.md) - [One post tagged with "development"](/blog/tags/development.md) - [2 posts tagged with "devops"](/blog/tags/devops.md) - [One post tagged with "devtools"](/blog/tags/devtools.md) - [One post tagged with "diagram-types"](/blog/tags/diagram-types.md) - [32 posts tagged with "diagrams"](/blog/tags/diagrams.md) - [32 posts tagged with "diagrams"](/blog/tags/diagrams/page/2.md) - [32 posts tagged with "diagrams"](/blog/tags/diagrams/page/3.md) - [32 posts tagged with "diagrams"](/blog/tags/diagrams/page/4.md) - [One post tagged with "docs"](/blog/tags/docs.md) - [One post tagged with "document-viewer"](/blog/tags/document-viewer.md) - [8 posts tagged with "documentation"](/blog/tags/documentation.md) - [One post tagged with "dot"](/blog/tags/dot.md) - [One post tagged with "draw-io"](/blog/tags/draw-io.md) - [One post tagged with "drawing"](/blog/tags/drawing.md) - [One post tagged with "drawio"](/blog/tags/drawio.md) - [One post tagged with "education"](/blog/tags/education.md) - [4 posts tagged with "engineering"](/blog/tags/engineering.md) - [6 posts tagged with "enhanced-markdown"](/blog/tags/enhanced-markdown.md) - [One post tagged with "enterprise"](/blog/tags/enterprise.md) - [One post tagged with "epub"](/blog/tags/epub.md) - [2 posts tagged with "er-diagram"](/blog/tags/er-diagram.md) - [14 posts tagged with "excalidraw"](/blog/tags/excalidraw.md) - [One post tagged with "excalidraw-vs-mermaid"](/blog/tags/excalidraw-vs-mermaid.md) - [14 posts tagged with "excalidraw"](/blog/tags/excalidraw/page/2.md) - [4 posts tagged with "excel"](/blog/tags/excel.md) - [One post tagged with "expand"](/blog/tags/expand.md) - [5 posts tagged with "explained"](/blog/tags/explained.md) - [8 posts tagged with "export"](/blog/tags/export.md) - [27 posts tagged with "faq"](/blog/tags/faq.md) - [27 posts tagged with "faq"](/blog/tags/faq/page/2.md) - [27 posts tagged with "faq"](/blog/tags/faq/page/3.md) - [One post tagged with "fedramp"](/blog/tags/fedramp.md) - [One post tagged with "fishbone"](/blog/tags/fishbone.md) - [One post tagged with "flow"](/blog/tags/flow.md) - [4 posts tagged with "flowchart"](/blog/tags/flowchart.md) - [2 posts tagged with "flowcharts"](/blog/tags/flowcharts.md) - [4 posts tagged with "fonts"](/blog/tags/fonts.md) - [One post tagged with "forge"](/blog/tags/forge.md) - [7 posts tagged with "formatting"](/blog/tags/formatting.md) - [One post tagged with "free"](/blog/tags/free.md) - [4 posts tagged with "gantt"](/blog/tags/gantt.md) - [One post tagged with "git"](/blog/tags/git.md) - [2 posts tagged with "gitgraph"](/blog/tags/gitgraph.md) - [One post tagged with "github"](/blog/tags/github.md) - [7 posts tagged with "google-fonts"](/blog/tags/google-fonts.md) - [One post tagged with "government-cloud"](/blog/tags/government-cloud.md) - [7 posts tagged with "graphviz"](/blog/tags/graphviz.md) - [One post tagged with "heading-numbering"](/blog/tags/heading-numbering.md) - [One post tagged with "hierarchy"](/blog/tags/hierarchy.md) - [95 posts tagged with "how-to"](/blog/tags/how-to.md) - [95 posts tagged with "how-to"](/blog/tags/how-to/page/10.md) - [95 posts tagged with "how-to"](/blog/tags/how-to/page/2.md) - [95 posts tagged with "how-to"](/blog/tags/how-to/page/3.md) - [95 posts tagged with "how-to"](/blog/tags/how-to/page/4.md) - [95 posts tagged with "how-to"](/blog/tags/how-to/page/5.md) - [95 posts tagged with "how-to"](/blog/tags/how-to/page/6.md) - [95 posts tagged with "how-to"](/blog/tags/how-to/page/7.md) - [95 posts tagged with "how-to"](/blog/tags/how-to/page/8.md) - [95 posts tagged with "how-to"](/blog/tags/how-to/page/9.md) - [One post tagged with "illustrations"](/blog/tags/illustrations.md) - [4 posts tagged with "import"](/blog/tags/import.md) - [One post tagged with "import-export"](/blog/tags/import-export.md) - [One post tagged with "incident"](/blog/tags/incident.md) - [2 posts tagged with "incident-management"](/blog/tags/incident-management.md) - [One post tagged with "inline-code"](/blog/tags/inline-code.md) - [One post tagged with "ishikawa"](/blog/tags/ishikawa.md) - [One post tagged with "isolated-cloud"](/blog/tags/isolated-cloud.md) - [One post tagged with "issue-history"](/blog/tags/issue-history.md) - [5 posts tagged with "issue-templates"](/blog/tags/issue-templates.md) - [45 posts tagged with "jira"](/blog/tags/jira.md) - [One post tagged with "jira-admin"](/blog/tags/jira-admin.md) - [2 posts tagged with "jira-automation"](/blog/tags/jira-automation.md) - [One post tagged with "jira-cloud"](/blog/tags/jira-cloud.md) - [One post tagged with "jira-diagrams"](/blog/tags/jira-diagrams.md) - [One post tagged with "jira-issues"](/blog/tags/jira-issues.md) - [One post tagged with "jira-plugin"](/blog/tags/jira-plugin.md) - [2 posts tagged with "jira-templates"](/blog/tags/jira-templates.md) - [45 posts tagged with "jira"](/blog/tags/jira/page/2.md) - [45 posts tagged with "jira"](/blog/tags/jira/page/3.md) - [45 posts tagged with "jira"](/blog/tags/jira/page/4.md) - [45 posts tagged with "jira"](/blog/tags/jira/page/5.md) - [One post tagged with "journey"](/blog/tags/journey.md) - [2 posts tagged with "jql"](/blog/tags/jql.md) - [4 posts tagged with "json"](/blog/tags/json.md) - [One post tagged with "json-schema"](/blog/tags/json-schema.md) - [One post tagged with "kanban"](/blog/tags/kanban.md) - [2 posts tagged with "katex"](/blog/tags/katex.md) - [2 posts tagged with "keyboard-shortcuts"](/blog/tags/keyboard-shortcuts.md) - [6 posts tagged with "knowledge-base"](/blog/tags/knowledge-base.md) - [2 posts tagged with "latex"](/blog/tags/latex.md) - [One post tagged with "layout"](/blog/tags/layout.md) - [One post tagged with "macro"](/blog/tags/macro.md) - [4 posts tagged with "macros"](/blog/tags/macros.md) - [One post tagged with "manim"](/blog/tags/manim.md) - [22 posts tagged with "markdown"](/blog/tags/markdown.md) - [2 posts tagged with "markdown-editor"](/blog/tags/markdown-editor.md) - [22 posts tagged with "markdown"](/blog/tags/markdown/page/2.md) - [22 posts tagged with "markdown"](/blog/tags/markdown/page/3.md) - [3 posts tagged with "marketplace"](/blog/tags/marketplace.md) - [2 posts tagged with "math"](/blog/tags/math.md) - [2 posts tagged with "mathjax"](/blog/tags/mathjax.md) - [2 posts tagged with "meeting-notes"](/blog/tags/meeting-notes.md) - [50 posts tagged with "mermaid"](/blog/tags/mermaid.md) - [One post tagged with "mermaid-12"](/blog/tags/mermaid-12.md) - [50 posts tagged with "mermaid"](/blog/tags/mermaid/page/2.md) - [50 posts tagged with "mermaid"](/blog/tags/mermaid/page/3.md) - [50 posts tagged with "mermaid"](/blog/tags/mermaid/page/4.md) - [50 posts tagged with "mermaid"](/blog/tags/mermaid/page/5.md) - [4 posts tagged with "migration"](/blog/tags/migration.md) - [4 posts tagged with "mindmap"](/blog/tags/mindmap.md) - [One post tagged with "mockup"](/blog/tags/mockup.md) - [3 posts tagged with "monaco-editor"](/blog/tags/monaco-editor.md) - [One post tagged with "monospace"](/blog/tags/monospace.md) - [One post tagged with "navigation"](/blog/tags/navigation.md) - [One post tagged with "notification"](/blog/tags/notification.md) - [4 posts tagged with "numbered-headings"](/blog/tags/numbered-headings.md) - [One post tagged with "packet"](/blog/tags/packet.md) - [One post tagged with "page-builder"](/blog/tags/page-builder.md) - [One post tagged with "page-structure"](/blog/tags/page-structure.md) - [One post tagged with "pagination"](/blog/tags/pagination.md) - [One post tagged with "pdf"](/blog/tags/pdf.md) - [One post tagged with "performance"](/blog/tags/performance.md) - [3 posts tagged with "permissions"](/blog/tags/permissions.md) - [2 posts tagged with "pie-chart"](/blog/tags/pie-chart.md) - [One post tagged with "planning"](/blog/tags/planning.md) - [2 posts tagged with "plantuml"](/blog/tags/plantuml.md) - [2 posts tagged with "postmortem"](/blog/tags/postmortem.md) - [One post tagged with "power-user"](/blog/tags/power-user.md) - [One post tagged with "prd"](/blog/tags/prd.md) - [One post tagged with "printable-qr"](/blog/tags/printable-qr.md) - [One post tagged with "printables"](/blog/tags/printables.md) - [2 posts tagged with "process"](/blog/tags/process.md) - [One post tagged with "procurement"](/blog/tags/procurement.md) - [One post tagged with "product"](/blog/tags/product.md) - [8 posts tagged with "productivity"](/blog/tags/productivity.md) - [3 posts tagged with "project-management"](/blog/tags/project-management.md) - [One post tagged with "project-structure"](/blog/tags/project-structure.md) - [One post tagged with "project-templates"](/blog/tags/project-templates.md) - [One post tagged with "q-and-a"](/blog/tags/q-and-a.md) - [2 posts tagged with "qr-code"](/blog/tags/qr-code.md) - [One post tagged with "qrcode"](/blog/tags/qrcode.md) - [2 posts tagged with "quadrant"](/blog/tags/quadrant.md) - [One post tagged with "quality"](/blog/tags/quality.md) - [One post tagged with "queries"](/blog/tags/queries.md) - [3 posts tagged with "questions"](/blog/tags/questions.md) - [One post tagged with "radar-chart"](/blog/tags/radar-chart.md) - [One post tagged with "rag"](/blog/tags/rag.md) - [One post tagged with "railroad"](/blog/tags/railroad.md) - [One post tagged with "reading"](/blog/tags/reading.md) - [2 posts tagged with "release"](/blog/tags/release.md) - [One post tagged with "release-notes"](/blog/tags/release-notes.md) - [4 posts tagged with "reporting"](/blog/tags/reporting.md) - [One post tagged with "requirement-diagram"](/blog/tags/requirement-diagram.md) - [One post tagged with "retrospective"](/blog/tags/retrospective.md) - [One post tagged with "roadmap"](/blog/tags/roadmap.md) - [One post tagged with "root-cause-analysis"](/blog/tags/root-cause-analysis.md) - [One post tagged with "rovo"](/blog/tags/rovo.md) - [One post tagged with "sankey"](/blog/tags/sankey.md) - [One post tagged with "schema"](/blog/tags/schema.md) - [2 posts tagged with "scrum"](/blog/tags/scrum.md) - [One post tagged with "search"](/blog/tags/search.md) - [6 posts tagged with "security"](/blog/tags/security.md) - [6 posts tagged with "sequence-diagram"](/blog/tags/sequence-diagram.md) - [One post tagged with "skills"](/blog/tags/skills.md) - [One post tagged with "software-design"](/blog/tags/software-design.md) - [2 posts tagged with "source-editor"](/blog/tags/source-editor.md) - [One post tagged with "sprint"](/blog/tags/sprint.md) - [2 posts tagged with "sprint-planning"](/blog/tags/sprint-planning.md) - [One post tagged with "sprint-tracking"](/blog/tags/sprint-tracking.md) - [One post tagged with "standardization"](/blog/tags/standardization.md) - [3 posts tagged with "state-diagram"](/blog/tags/state-diagram.md) - [2 posts tagged with "storage-format"](/blog/tags/storage-format.md) - [One post tagged with "svg"](/blog/tags/svg.md) - [One post tagged with "svg-library"](/blog/tags/svg-library.md) - [One post tagged with "swimlane"](/blog/tags/swimlane.md) - [One post tagged with "syntax"](/blog/tags/syntax.md) - [6 posts tagged with "syntax-highlighting"](/blog/tags/syntax-highlighting.md) - [2 posts tagged with "table-of-contents"](/blog/tags/table-of-contents.md) - [One post tagged with "tables"](/blog/tags/tables.md) - [One post tagged with "tabs"](/blog/tags/tabs.md) - [One post tagged with "team-performance"](/blog/tags/team-performance.md) - [2 posts tagged with "template"](/blog/tags/template.md) - [One post tagged with "templates"](/blog/tags/templates.md) - [One post tagged with "themes"](/blog/tags/themes.md) - [One post tagged with "ticket-descriptions"](/blog/tags/ticket-descriptions.md) - [2 posts tagged with "timeline"](/blog/tags/timeline.md) - [3 posts tagged with "toc"](/blog/tags/toc.md) - [One post tagged with "traceability"](/blog/tags/traceability.md) - [One post tagged with "treemap"](/blog/tags/treemap.md) - [2 posts tagged with "treeview"](/blog/tags/treeview.md) - [2 posts tagged with "troubleshooting"](/blog/tags/troubleshooting.md) - [One post tagged with "tutorial"](/blog/tags/tutorial.md) - [6 posts tagged with "typography"](/blog/tags/typography.md) - [One post tagged with "ui-design"](/blog/tags/ui-design.md) - [3 posts tagged with "uml"](/blog/tags/uml.md) - [One post tagged with "url-shortener"](/blog/tags/url-shortener.md) - [2 posts tagged with "use-case-diagram"](/blog/tags/use-case-diagram.md) - [One post tagged with "usecase-diagram"](/blog/tags/usecase-diagram.md) - [One post tagged with "user-story-template"](/blog/tags/user-story-template.md) - [One post tagged with "velocity"](/blog/tags/velocity.md) - [One post tagged with "venn-diagram"](/blog/tags/venn-diagram.md) - [One post tagged with "visual-documentation"](/blog/tags/visual-documentation.md) - [6 posts tagged with "whiteboard"](/blog/tags/whiteboard.md) - [One post tagged with "widget"](/blog/tags/widget.md) - [One post tagged with "wiki-markup"](/blog/tags/wiki-markup.md) - [One post tagged with "wireframe"](/blog/tags/wireframe.md) - [One post tagged with "word"](/blog/tags/word.md) - [6 posts tagged with "workflow"](/blog/tags/workflow.md) - [One post tagged with "workflows"](/blog/tags/workflows.md) - [One post tagged with "writing"](/blog/tags/writing.md) - [3 posts tagged with "wysiwyg"](/blog/tags/wysiwyg.md) - [2 posts tagged with "xml"](/blog/tags/xml.md) - [One post tagged with "xychart-beta"](/blog/tags/xychart-beta.md) - [One post tagged with "yaml"](/blog/tags/yaml.md) - [2 posts tagged with "zenuml"](/blog/tags/zenuml.md) - [UML Use Case Diagrams in Confluence (Mermaid, Copy-Paste)](/blog/uml-use-case-diagram-confluence.md): Draw UML use case diagrams in Confluence with Mermaid's usecase-beta: actors, system boundaries, include relationships. Copy-paste examples with rendered output. Free for up to 10 users. - [Excalidraw for Confluence — Which Whiteboard and Drawing App Fits Your Team?](/blog/use-excalidraw-in-confluence-whiteboard-diagrams.md): Compare Confluence Excalidraw and whiteboard apps: Excalidraw Plus by NGPILOT, Excalidraw Diagrams by Narva, draw.io, and more. Features, ratings, and honest pros/cons. - [How to Visualize Confluence Documentation with SVGs (No Design Skills Required)](/blog/visualize-confluence-documentation-with-svgs.md): Enhance your Confluence documentation with 1,300+ ready-to-use SVGs across 25 professional categories — no design skills required. - [What Is Atlassian Government Cloud (AGC)? NGPILOT Apps Available (2026)](/blog/what-is-atlassian-government-cloud.md): Learn what Atlassian Government Cloud is, FedRAMP requirements, and which NGPILOT apps are available for government and regulated industries. - [What Is Atlassian Isolated Cloud? NGPILOT Apps Available (2026)](/blog/what-is-atlassian-isolated-cloud.md): Learn what Atlassian Isolated Cloud is, how it differs from standard cloud, and which NGPILOT apps are available for deployment in your own isolated instance. - [What Is Atlassian Rovo? (And How It Differs from Atlassian Intelligence)](/blog/what-is-atlassian-rovo.md): Atlassian Rovo is the cross-platform AI layer that searches, chats, and runs agents across Jira, Confluence, and external SaaS tools. This guide explains what it does, how it differs from Atlassian Intelligence, and what it means for admins. - [Whiteboarding Architecture Sessions in Jira & Confluence](/blog/whiteboarding-architecture-sessions-jira-confluence.md): How engineering teams run architecture and design whiteboarding sessions inside Jira and Confluence. Sketching flowcharts, ER diagrams, and wireframes with Excalidraw — 229 shape libraries, freehand drawing, and Mermaid import. - [How to Write Better Jira Ticket Descriptions with AI](/blog/write-better-jira-ticket-descriptions-with-ai.md): Use AI to write clear, detailed Jira ticket descriptions that reduce back-and-forth. Learn prompt templates, description standards, and AI tools for better issue writing. - [Write Markdown in Confluence With Mermaid, LaTeX & Code — One Editor, Live Preview](/blog/write-markdown-confluence-mermaid-latex-code.md): How engineering and research teams write Markdown in Confluence with live split preview, Mermaid diagrams, KaTeX/LaTeX math, and 190+ code languages — all in one editor, no external CDN. - [ZenUML Sequence Diagrams in Confluence: Copy-Paste Guide](/blog/zenuml-sequence-diagram-confluence.md): Write ZenUML sequence diagrams in Confluence with plain text: if/else branches, try/catch error paths, and par blocks. Copy-paste examples with rendered output. Free for up to 10 users. ## search - [Search the documentation](/search.md) ## solutions - [Start with the problem,not the app](/solutions.md): Problem-first solutions for Confluence and Jira — diagrams, Markdown, fonts, code, page building, data export, attachments, and workflows. See the why, the how, and the apps that do it. - [Put AI agents to work on your content](/solutions/ai-agents-in-atlassian-apps.md): How scoped AI agents work in Confluence and Jira: create, edit, and convert content by chat. See what to check before installing one, and which apps ship them. - [Build polished pages, portals, and navigation in Confluence](/solutions/build-pages-and-portals-in-confluence.md): Learn how to build polished Confluence pages, portals, and intranets — layout macros, auto-numbered headings, and Previous/Next navigation, no HTML or CSS required. - [Show code, JSON, and API docs in Confluence](/solutions/code-and-api-docs-in-confluence.md): Learn how to present code, JSON, and API documentation in Confluence with syntax highlighting and interactive viewers — readable technical content for the whole team. - [Organize Jira Components into a Tree](/solutions/component-hierarchy-in-jira.md): Give Jira components a parent-child tree: platforms, modules, submodules. Cascading issue picker, subtree-wide JQL search, and boards and reports that keep working. - [Use custom fonts and branding in Confluence](/solutions/custom-fonts-and-branding-in-confluence.md): Learn how to add custom Google Fonts and on-brand illustrations to Confluence pages. Make your wiki reflect your brand without HTML or CSS. - [Create diagrams in Confluence](/solutions/diagrams-in-confluence.md): Learn how to create diagrams in Confluence — flowcharts, sequence, ER, Gantt and freehand whiteboards. See the apps that render them live inside your pages. - [Add diagrams to Jira issues](/solutions/diagrams-in-jira.md): Learn how to add diagrams to Jira issues — flowcharts, sequence diagrams, wireframes, and architecture sketches that live right on the ticket. - [Export Jira issues to Excel or CSV](/solutions/export-jira-issues-to-excel.md): Learn how to export Jira issues to Excel and CSV with custom field selection and JQL — even large result sets the native export times out on. - [Manage Jira attachments](/solutions/manage-jira-attachments.md): Learn how to manage Jira attachments — download them in bulk with parallel processing and enforce file type and size rules for security. - [Add media and interactive elements to Confluence pages](/solutions/media-and-interactive-elements-in-confluence.md): Learn how to add media and interactive elements to Confluence pages — QR codes for offline-to-online links and animated math with the Manim engine. - [Migrate, back up, and organize Confluence content](/solutions/migrate-and-backup-confluence-content.md): Learn how to migrate and back up Confluence content — export pages between JSON, XML, HTML, and Markdown, and move them between spaces safely. - [Standardize Jira workflows with templates and banners](/solutions/standardize-jira-workflows.md): Learn how to standardize Jira workflows — reusable issue templates with auto-apply rules and rich announcement banners that keep the team informed. - [Run team knowledge with FAQs, Q&A, and tasks in Confluence](/solutions/team-knowledge-faq-qa-and-tasks-in-confluence.md): Learn how to run team knowledge in Confluence — FAQ accordions, Q&A with voting, and centralized task tracking so answers and action items never get lost. - [Track Issue History in Jira](/solutions/track-issue-history-in-jira.md): See who changed what on Jira issues: field-level change history, before/after diffs, multi-issue CSV reports, and a Rovo agent that answers what changed. - [Visualize JSON in Jira](/solutions/visualize-json-in-jira.md): Learn how to visualize JSON stored in Jira issue fields, entity properties, or pasted payloads as an interactive graph — without leaving the issue view. - [Write Markdown in Confluence](/solutions/write-markdown-in-confluence.md): Learn how to write Markdown in Confluence — with live split preview, Mermaid diagrams, LaTeX math and 190+ code languages. Everything you need to write docs in Markdown. ## support - [How can we help?](/support.md): Get help with NGPILOT apps. Browse FAQs, check response time commitments, and submit a support request. ## trust - [Trust & Security](/trust.md): NGPILOT Trust Center: security architecture, compliance certifications, privacy practices, and platform transparency for enterprise buyers. ## docs - [Attachment Reviewer for Jira - User Guide](/docs/Attachment-Reviewer-for-Jira/user-docs.md): Enforce file type and size policies for Jira attachments. Automatically validate uploads and prevent security risks with customizable rules. - [Usage](/docs/carousel-for-confluence/usage.md): Embed and display image carousels in Confluence pages. Showcase visuals, banners, or product images with customizable layouts. - [Checklist Workflow Automation for Jira — User Guide](/docs/Checklist-Workflow-Automation-for-Jira/user-docs.md): Issue checklists with real enforcement: required items block workflow transitions until they're done. Statuses, due dates, templates, CSV, JQL and reminders. - [Component Hierarchy for Jira — User Guide](/docs/Component-Hierarchy-for-Jira/user-docs.md): Parent-child component trees for Jira: build the tree on a project page, pick a node path on issues, and search whole branches with one JQL function. - [How to use Content Craft for Confluence](/docs/Content-Craft-for-Confluence/usage.md): Learn how to use Content Craft for Confluence to create and manage content efficiently. - [Content Formatting Macros & Page Builder for Confluence — User Guide](/docs/Content-Formatting-Macros-Page-Builder-for-Confluence/user-docs.md): 23 powerful macros — buttons, hero sections, pricing tables, tabs, FAQ, image galleries, forms, theme editor, and more. Free for teams up to 10. - [Usage](/docs/diagram-duo-for-confluence/usage.md): Integrate Excalidraw and Mermaid into Confluence. Create and edit freeform drawings and structured flowcharts in one macro. - [Linking and Navigation inside the Markdown Macro](/docs/Enhanced-Markdown-for-Confluence/navigation.md): Jump to any heading inside an Enhanced Markdown macro with in-page anchors. Learn how heading anchors are generated, build a hand-written table of contents, and avoid the slugs that silently fail. - [Enhanced Markdown for Confluence — User Guide](/docs/Enhanced-Markdown-for-Confluence/usage.md): Write Markdown in Confluence with live split preview, Mermaid 12 (including UML use case diagrams) and ZenUML diagrams, KaTeX and MathJax math, and 190+ language syntax highlighting. - [User Guide](/docs/epub-reader-for-confluence/usage.md): Read EPUB files directly within Confluence. Upload, view, and navigate EPUB documents with a built-in reader interface. - [EULA](/docs/eula.md): NGPILOT End User License Agreement for Confluence and Jira apps available on the Atlassian Marketplace. Covers licensing terms, support, liability, and warranty. - [Excalidraw Diagrams plus Whiteboards — User Guide](/docs/Excalidraw-Diagrams-plus-Whiteboards-for-Jira/usage.md): Add Excalidraw-powered whiteboards to Jira issues. Sketch flowcharts, ER diagrams, wireframes, and more with 229 built-in shape packs. - [Usage](/docs/Excalidraw-plus-for-Confluence/usage.md): Modern drawing for Confluence: Excalidraw plus Mermaid plus 220+ libraries. Create freeform drawings, flowcharts, and diagrams natively. - [Google Fonts for Confluence — User Guide](/docs/Google-Fonts-for-Confluence/usage.md): Change the font on any Confluence page. Browse 1,942+ Google Fonts with live preview, custom size, color and alignment. Dark mode support. Free for up to 10 users. - [Usage](/docs/Graphviz-Charts-for-Confluence/usage.md): Create Graphviz charts directly in Confluence. Visualize ideas with fast, customizable graph diagrams and full data control. - [Welcome to NGPILOT Apps](/docs/intro.md): Documentation hub for NGPILOT's 35+ Confluence and Jira apps. Browse guides for Mermaid diagrams, Excalidraw whiteboards, Markdown editor, Google Fonts, code blocks, bulk operations, and more. - [Issue History Agent for Jira — User Guide](/docs/Issue-History-Agent-for-Jira/usage.md): Field-level change history on any Jira issue, word-level before/after diffs, a multi-issue report with CSV export, and an agent that answers "what changed?". - [JSON Graph Viewer & Visualizer for Jira — User Guide](/docs/JSON-Graph-Viewer-Visualizer-for-Jira/user-docs.md): Visualize JSON in Jira issue fields, entity properties, or pasted payloads as an interactive node graph. Code, graph, and side-by-side views with light & dark themes. - [Usage](/docs/json-structure-viewer-for-confluence/usage.md): Best JSON viewer for Confluence. Paste JSON code to create interactive structure diagrams, visualize data. Free trial available. - [Manim for Confluence — User Documentation](/docs/Manim-for-Confluence/user-docs.md): Create mathematical animations in Confluence using Manim. Bring complex concepts to life with dynamic visualizations. - [Markdown Mind Maps for Confluence — User Guide](/docs/Markdown-Mind-Maps-for-Confluence/user-docs.md): Turn Markdown headings and bullets into interactive mind maps on a Confluence page. Live preview, 10 templates, auto light/dark mode, expand levels, alignment and height. - [Mermaid+ Diagrams for Jira — User Guide](/docs/Mermaid-plus-Diagrams-for-Jira/usage.md): Add Mermaid diagrams to any Jira issue with 30 diagram types, live preview, and one-click templates. - [Mermaid Plus Diagrams & AI Agent for Confluence — User Guide](/docs/Mermaid-Plus-for-Confluence/usage.md): Create Mermaid diagrams directly in Confluence with 30 diagram types, a Rovo AI agent, live preview, customizable themes, and one-click templates. - [Modern Announcement Banner for Jira - User Documentation](/docs/Modern-Announcement-Banner-for-Jira/user-docs.md): Create Jira announcement banners with rich text, emojis, custom colors, scheduling and per-project visibility. Dismissible option. Free for up to 10 users. - [Modern Code Blocks for Confluence — User Guide](/docs/Modern-Code-Blocks-for-Confluence/user-docs.md): 50+ code block themes for Confluence with Monaco editor (VS Code), 85+ languages, diff view, dark/light mode, minimap, font ligatures. Free for up to 10 users. - [How to use Modern FAQ for Confluence](/docs/Modern-FAQ-for-Confluence/usage.md): Build and customize FAQ sections in Confluence with drag-and-drop sorting, collapsible accordion style, and inline editing. - [Modern Importer & Exporter for Confluence - User Guide](/docs/Modern-Importer-Exporter-for-Confluence/user-docs.md): Table of Contents - [Modern Issue Templates for Jira - User Guide](/docs/Modern-Issue-Templates-for-Jira/user-docs.md): Create and auto-apply issue templates with rich formatting and GitHub import for streamlined Jira workflows. - [Modern My Tasks - User Guide](/docs/Modern-My-Tasks-for-Confluence/user-docs.md): Centralized task management for Confluence with inline editing, smart filtering, and personal task dashboards. - [User Guide - Modern Numbered Headings for Confluence](/docs/Modern-Numbered-Headings-for-Confluence/user-docs.md): Automatically generate professional table of contents with multiple numbering styles. One-click TOC insertion with live preview. - [Modern OpenAPI (Swagger) Integration for Confluence — User Guide](/docs/Modern-OpenAPI-Swagger-Integration-for-Confluence/user-docs.md): Render interactive OpenAPI 3.x and Swagger 2.x API documentation directly on Confluence pages. Paste YAML or JSON specs for instant, navigable API docs with validation and theme support. - [Modern Questions for Confluence — User Guide](/docs/Modern-Questions-for-Confluence/user-docs.md): Structured Q&A for Confluence. Post questions, write answers, vote on responses, and mark accepted answers. - [Usage](/docs/Pagination-Buttons-for-Confluence/usage.md): Add customizable Previous and Next navigation buttons to Confluence pages with flexible design and alignment options. - [Privacy Policy](/docs/privacy-policy.md): NGPILOT privacy policy — how we collect, use, store, and protect personal data for users of our Confluence and Jira apps on Atlassian Marketplace. - [User Docs](/docs/PSD-Attachments-Viewer-for-Confluence/user-docs.md): PSD Attachments Viewer for Confluence is a macro app. - [QRCode for Confluence — User Guide](/docs/QRCode-for-Confluence/usage.md): Embed QR codes into Confluence pages easily. Generate QR codes from any text or URL with customizable sizes. - [Usage](/docs/raw-storage-source-editor-for-Confluence/usage.md): Edit the raw storage format of Confluence pages directly. Format documents, use find and replace, and access command palette. - [Usage](/docs/raw-storage-source-editor-pro-for-Confluence/usage.md): Advanced raw storage editor for Confluence with diff view, format document, find and replace, and theme customization. - [Security Policy](/docs/security-policy.md): NGPILOT security policy — architecture, encryption, access controls, vulnerability management, incident response, and compliance practices for our Atlassian Marketplace apps. - [Simple Bulk Attachment Downloader - User Guide](/docs/Simple-Bulk-Attachment-Downloader-for-Jira/user-docs.md): Related blog post: Bulk download Jira attachments in one click - [User Guide - Simple Bulk Issues Excel CSV Export for Jira](/docs/Simple-Bulk-Issues-Excel-CSV-Export-for-Jira/user-docs.md): Reference for the Simple Bulk Issues Excel CSV Export app: where to find it in Jira, the field selection panel, supported field types, file naming, and troubleshooting. --- # Full Documentation Content Atlassian Marketplace # Apps for Confluence & Jira 36 simple, intuitive apps — diagrams, code blocks, Markdown, fonts, templates, and more. All free for up to 10 users. --- ![Attachment Reviewer for Jira icon](/img/Attachment-Reviewer-for-Jira.svg) Jira App # Attachment Reviewer for Jira Attachment Reviewer validates Jira attachments against customizable file-type and file-size rules. Block oversized uploads, reject unsupported formats, and prevent security risks before files land on your issues. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/4167596304/attachment-reviewer-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=attachment-reviewer-for-jira)[User Guide](/docs/Attachment-Reviewer-for-Jira/user-docs.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Checklist Workflow Automation for Jira icon](/img/Checklist-Workflow-Automation-for-Jira.svg) Jira App # Checklist Workflow Automation for Jira Add task checklists to Jira issues and automate the busywork around them — apply checklist templates automatically by issue type, get reminders that mention the assignee, and track completion at a glance. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1795968238?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=checklist-workflow-automation-for-jira)[User Guide](/docs/Checklist-Workflow-Automation-for-Jira/user-docs.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Component Hierarchy for Jira icon](/img/Component-Hierarchy-for-Jira.svg) Jira App # Component Hierarchy for Jira Jira components are a flat list — a poor fit for layered systems where Auth sits under Platform, and SSO under Auth. Component Hierarchy adds a parent-child tree: build it on a project page, pick a full path like Platform/Auth/SSO on each issue, and search a whole branch with one JQL function. Every node is a real Jira component, so boards, releases, and reports keep working exactly as before. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/2232005585?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=component-hierarchy-for-jira)[User Guide](/docs/Component-Hierarchy-for-Jira/user-docs.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Content Craft for Confluence icon](/img/content-craft-for-confluence.svg) Confluence App # Content Craft for Confluence Content Craft gives you a searchable library of business-oriented SVG icons and illustrations to drop into Confluence pages. No more hunting for clipart or exporting from design tools — browse, insert, done. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237728/content-craft-free-business-svg-library-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=content-craft-for-confluence)[User Guide](/docs/Content-Craft-for-Confluence/usage.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Content Formatting Macros & Page Builder for Confluence icon](/img/Content-Formatting-Macros-Page-Builder-for-Confluence.svg) Confluence App # Content Formatting Macros & Page Builder for Confluence A bundle of 23 content formatting macros — hero sections, pricing tables, tabs, cards, photo galleries, QR codes, forms, and a global theme editor — that let you build rich, marketing-style pages inside Confluence without HTML or CSS. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/4209461142/content-formatting-macros-page-builder-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=content-formatting-macros-page-builder-for-confluence)[User Guide](/docs/Content-Formatting-Macros-Page-Builder-for-Confluence/user-docs.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Enhanced Markdown for Confluence icon](/img/enhanced-markdown-for-confluence.svg) Confluence App # Enhanced Markdown for Confluence Enhanced Markdown for Confluence is a full Markdown editor that lives inside Confluence pages. Write in raw Markdown with a live split-pane preview, or flip to a WYSIWYG view. Powered by the Quikdown engine, it supports GFM tables, Mermaid diagrams, KaTeX and LaTeX math, MathJax, and syntax highlighting for 190+ languages. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=enhanced-markdown-for-confluence)[User Guide](/docs/Enhanced-Markdown-for-Confluence/usage.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![EPUB Reader for Confluence icon](/img/epub-reader-for-confluence.svg) Confluence App # EPUB Reader for Confluence EPUB Reader lets you read EPUB e-book files directly within Confluence, enhancing document accessibility and collaboration for teams that share long-form reading material. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1238253/epub-reader-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=epub-reader-for-confluence)[User Guide](/docs/epub-reader-for-confluence/usage.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Excalidraw Diagrams plus Whiteboards for Jira icon](/img/excalidraw-diagrams-plus-whiteboards-for-jira.svg) Jira App # Excalidraw Diagrams plus Whiteboards for Jira Attach a freehand drawing canvas to any Jira issue. Sketch a flowchart for a bug report, a wireframe for a feature, or an ER diagram for a data model — all without leaving Jira. Ships with 229 shape packs so you rarely need to draw from scratch. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/2139233994/excalidraw-diagrams-plus-whiteboards-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=excalidraw-diagrams-plus-whiteboards-for-jira)[User Guide](/docs/Excalidraw-Diagrams-plus-Whiteboards-for-Jira/usage.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Excalidraw & Mermaid Diagrams for Confluence icon](/img/diagram-duo-for-confluence.svg) Confluence App # Excalidraw & Mermaid Diagrams for Confluence Get the best of both diagramming styles in a single app. Use Excalidraw for freeform whiteboarding and quick sketches; switch to Mermaid when you need precise, version-controllable diagrams from text. One install, two editors. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237659/excalidraw-mermaid-diagrams-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=excalidraw-mermaid-diagrams-for-confluence)[User Guide](/docs/diagram-duo-for-confluence/usage.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Excalidraw Plus Whiteboards & AI Agent for Confluence icon](/img/excalidraw-plus-for-confluence.svg) Confluence App # Excalidraw Plus Whiteboards & AI Agent for Confluence Excalidraw Plus Whiteboards & AI Agent for Confluence puts a hand-drawn-style whiteboard inside your Confluence pages, with a Rovo AI agent that works on the board from chat. Ask for a diagram and it draws one on the page; ask for a rename, a grouping, or a relayout and it edits the existing shapes in place. Sketch architecture diagrams, wireframes, and flowcharts on a drag-and-drop canvas backed by 229 shape libraries, and import Mermaid or PlantUML syntax as an editable drawing. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=excalidraw-plus-for-confluence)[User Guide](/docs/Excalidraw-plus-for-Confluence/usage.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Google Fonts for Confluence icon](/img/google-fonts-for-confluence.svg) Confluence App # Google Fonts for Confluence Google Fonts for Confluence lets you apply any of 1,942+ web font families to text on your Confluence pages. Insert the macro, browse the font library, pick a family, and see a live preview before you save. Control size, color, and alignment to match your brand. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236413/google-fonts-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=google-fonts-for-confluence)[User Guide](/docs/Google-Fonts-for-Confluence/usage.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Graphviz Charts for Confluence icon](/img/Graphviz-Charts-for-Confluence.svg) Confluence App # Graphviz Charts for Confluence Graphviz Charts for Confluence renders technical network and relationship graphs from the DOT language. Ideal for dependency maps, organisational charts, and any graph where the structure matters more than the aesthetics. Live preview shows your graph as you type. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237380/graphviz-charts-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=graphviz-charts-for-confluence)[User Guide](/docs/Graphviz-Charts-for-Confluence/usage.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Issue History Agent for Jira icon](/img/issue-history-agent-for-jira.svg) Jira App # Issue History Agent for Jira Issue History shows who changed what on a Jira issue, when, and exactly what the values were before and after. A panel on every issue lists changes newest-first with word-level diffs for long text fields, a global report covers a whole JQL-filtered issue set with CSV export, and a Rovo agent answers "what changed?" questions in plain language — always as the asking user, so people only ever see issues they already have permission to read. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/675742747?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=issue-history-agent-for-jira)[User Guide](/docs/Issue-History-Agent-for-Jira/usage.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![JSON Graph Viewer & Visualizer for Jira icon](/img/JSON-Graph-Viewer-Visualizer-for-Jira.svg) Jira App # JSON Graph Viewer & Visualizer for Jira Visualize JSON held in Jira issue fields, entity properties, or pasted payloads as an interactive node graph. Pan, zoom, and collapse nested structures, switch between code, graph, and side-by-side views, with light and dark themes that follow Jira. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1886661294?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=json-graph-viewer-visualizer-for-jira)[User Guide](/docs/JSON-Graph-Viewer-Visualizer-for-Jira/user-docs.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![JSON Structure Viewer for Confluence icon](/img/file_json_144dp_255290_FILL0_wght400_GRAD0_opsz48.svg) Confluence App # JSON Structure Viewer for Confluence JSON Structure Viewer turns raw JSON into a collapsible, visual tree that makes nested data structures easy to understand. Paste your JSON, and readers can expand and collapse nodes to explore the shape of the data — far clearer than a wall of formatted text. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237254/json-structure-viewer-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=json-structure-viewer-for-confluence)[User Guide](/docs/json-structure-viewer-for-confluence/usage.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Manim for Confluence icon](/img/Manim-for-Confluence.svg) Confluence App # Manim for Confluence Manim for Confluence renders mathematical animations using the Manim engine (the same one used by 3Blue1Brown). Bring complex concepts to life with dynamic, frame-by-frame visualisations of equations and transformations. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1384425933/manim-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=manim-for-confluence)[User Guide](/docs/Manim-for-Confluence/user-docs.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Markdown Mind Maps for Confluence icon](/img/Markdown-Mind-Maps-for-Confluence.svg) Confluence App # Markdown Mind Maps for Confluence Render Markdown as interactive mind maps directly in Confluence pages. Supports zoom, pan, alignment options, and 10+ templates for brainstorming, sprint planning, and more. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/588881414?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=markdown-mind-maps-for-confluence)[User Guide](/docs/Markdown-Mind-Maps-for-Confluence/user-docs.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Mermaid Plus Diagrams for Jira icon](/img/mermaid-plus-diagrams-for-jira.svg) Jira App # Mermaid Plus Diagrams for Jira Mermaid Plus Diagrams for Jira lets you add flowcharts, sequence diagrams, architecture sketches, and 27 other diagram types directly to a Jira issue. A live preview updates as you type, and Quick Templates load a working starting point for every diagram type. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/2658777397/mermaid-plus-diagrams-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-diagrams-for-jira)[User Guide](/docs/Mermaid-plus-Diagrams-for-Jira/usage.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Mermaid Plus Diagrams & AI Agent for Confluence icon](/img/mermaid-plus-for-confluence.svg) Confluence App # Mermaid Plus Diagrams & AI Agent for Confluence Mermaid Plus Diagrams & AI Agent for Confluence brings text-based diagramming into Confluence — plus a Rovo AI agent that creates, reads, updates, and converts diagrams from chat, right on the page. Write Mermaid syntax in a code editor and see the diagram render live. All 30 Mermaid v12 diagram types are supported — flowcharts, sequence, class, state, Gantt, pie, ER, C4, mindmaps, ZenUML, use case, and more — each with a one-click template so you never start from a blank canvas. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence)[User Guide](/docs/Mermaid-Plus-for-Confluence/usage.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Modern Announcement Banner for Jira icon](/img/Modern-Announcement-Banner-for-Jira.svg) Jira App # Modern Announcement Banner for Jira Modern Announcement Banner for Jira displays rich-text announcements at the top of Jira. Schedule banners to appear and disappear on set dates, and target them to specific audiences so the right teams see the right messages. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/194301976/modern-announcement-banner-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-announcement-banner-for-jira)[User Guide](/docs/Modern-Announcement-Banner-for-Jira/user-docs.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Modern Code Blocks for Confluence icon](/img/Modern-Code-Blocks-for-Confluence.svg) Confluence App # Modern Code Blocks for Confluence Modern Code Blocks replaces Confluence’s built-in code macro with the Monaco editor — the same engine that powers VS Code. Get syntax highlighting for 85+ languages (JSON, XML, YAML, SQL, Python, and more), 50+ themes, a side-by-side diff view, collapsible blocks, one-click copy, and automatic light/dark theme detection. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-code-blocks-for-confluence)[User Guide](/docs/Modern-Code-Blocks-for-Confluence/user-docs.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Modern FAQ for Confluence icon](/img/modern-faq-for-confluence.svg) Confluence App # Modern FAQ for Confluence Modern FAQ for Confluence turns a flat list of questions into a clean, collapsible accordion. Reorder items with drag-and-drop, choose between two built-in themes, and let readers expand only the answers they care about. Great for onboarding pages, product FAQs, and internal knowledge bases. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236739/modern-faq-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-faq-for-confluence)[User Guide](/docs/Modern-FAQ-for-Confluence/usage.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Modern Importer & Exporter for Confluence icon](/img/Modern-Importer-Exporter-for-Confluence.svg) Confluence App # Modern Importer & Exporter for Confluence Modern Importer & Exporter is an enterprise-grade content migration and backup tool for Confluence. Move pages between spaces, convert between JSON, XML, HTML, and Markdown, and export content for safe-keeping — all without copy-pasting or external scripts. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/977066696/modern-importer-exporter-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-importer-exporter-for-confluence)[User Guide](/docs/Modern-Importer-Exporter-for-Confluence/user-docs.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Modern Issue Templates for Jira icon](/img/Modern-Issue-Templates-for-Jira.svg) Jira App # Modern Issue Templates for Jira Modern Issue Templates for Jira lets you build reusable issue templates with fill-in variables, import templates from GitHub, and set auto-apply rules so the right template loads for the right issue type and project. Stop copy-pasting from old tickets. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/2564635381/modern-issue-templates-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-issue-templates-for-jira)[User Guide](/docs/Modern-Issue-Templates-for-Jira/user-docs.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Modern My Tasks for Confluence icon](/img/Modern-My-Tasks-for-Confluence.svg) Confluence App # Modern My Tasks for Confluence Modern My Tasks pulls all the action items assigned to you across Confluence into one filterable, inline-editable list. No more digging through pages to find what you owe — see and update your tasks in one place. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/377171035/modern-my-tasks-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-my-tasks-for-confluence)[User Guide](/docs/Modern-My-Tasks-for-Confluence/user-docs.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Modern Numbered Headings for Confluence icon](/img/Modern-Numbered-Headings-for-Confluence.svg) Confluence App # Modern Numbered Headings for Confluence Modern Numbered Headings automatically numbers your Confluence page headings (H1–H6) so long documents read like a structured report. Choose from five numbering styles — Decimal, Roman, Alphabetic, Legal, and custom — and preview the result before you save. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/2096741841/modern-numbered-headings-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-numbered-headings-for-confluence)[User Guide](/docs/Modern-Numbered-Headings-for-Confluence/user-docs.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Modern OpenAPI (Swagger) Integration for Confluence icon](/img/Modern-OpenAPI-Swagger-Integration-for-Confluence.svg) Confluence App # Modern OpenAPI (Swagger) Integration for Confluence Modern OpenAPI renders your OpenAPI/Swagger specification as interactive documentation inside Confluence. Paste your spec, get a theme-aware viewer with validation, syntax highlighting, and expandable endpoints — ideal for internal API docs. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/2844069010/modern-openapi-swagger-integration-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-openapi-swagger-integration-for-confluence)[User Guide](/docs/Modern-OpenAPI-Swagger-Integration-for-Confluence/user-docs.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Modern Questions for Confluence icon](/img/modern-questions-for-confluence.svg) Confluence App # Modern Questions for Confluence Modern Questions adds a Stack Overflow-style Q\&A experience to Confluence. Post questions, write answers, let the team vote on the best response, and mark an accepted answer — all without leaving your wiki. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/3250836705/modern-questions-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-questions-for-confluence)[User Guide](/docs/Modern-Questions-for-Confluence/user-docs.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Pagination Buttons for Confluence icon](/img/Pagination-Buttons-for-Confluence.svg) Confluence App # Pagination Buttons for Confluence Pagination Buttons adds customizable Previous and Next navigation buttons to the bottom of Confluence pages. Design and align them to match your site, and link a series of pages into a readable sequence. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237371/pagination-buttons-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=pagination-buttons-for-confluence)[User Guide](/docs/Pagination-Buttons-for-Confluence/usage.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![PSD Attachments Viewer for Confluence icon](/img/PSD-Attachments-Viewer-for-Confluence.svg) Confluence App # PSD Attachments Viewer for Confluence PSD Attachments Viewer renders Photoshop PSD files directly in Confluence so designers and reviewers can preview layered artwork without downloading the file or opening Photoshop. Includes auto dark mode. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237413/psd-attachments-viewer-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=psd-attachments-viewer-for-confluence)[User Guide](/docs/PSD-Attachments-Viewer-for-Confluence/user-docs.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![QR Code for Confluence icon](/img/qrcode-for-confluence.svg) Confluence App # QR Code for Confluence QR Code for Confluence generates and embeds QR codes into your pages. Link to mobile resources, share Wi-Fi credentials, or provide a quick-scan link to a page — all without an external generator. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236735/qr-code-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=qrcode-for-confluence)[User Guide](/docs/QRCode-for-Confluence/usage.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Raw Storage Source Editor for Confluence (Free) icon](/img/source-editor-for-confluence-144x144.svg) Confluence App # Raw Storage Source Editor for Confluence (Free) The free edition of the Raw Storage Source Editor. Edit the underlying storage format of a Confluence page to fix broken macros or clean up pasted content. For formatting, find-and-replace, and diff view, upgrade to the Pro edition. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237066/raw-storage-source-editor-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=raw-storage-source-editor-for-confluence)[User Guide](/docs/raw-storage-source-editor-for-Confluence/usage.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Raw Storage Source Editor Pro for Confluence icon](/img/source-editor-for-confluence-144x144.svg) Confluence App # Raw Storage Source Editor Pro for Confluence Raw Storage Source Editor Pro lets you edit the underlying XML storage format of a Confluence page directly. Useful for fixing broken macros, cleaning up copied content, or making bulk structural changes the visual editor can’t. Includes formatting, find-and-replace, and a diff view so you can review changes before saving. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/2739097621/raw-storage-source-editor-pro-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=raw-storage-source-editor-pro-for-confluence)[User Guide](/docs/raw-storage-source-editor-pro-for-Confluence/usage.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Simple Bulk Attachment Downloader for Jira icon](/img/Simple-Bulk-Attachment-Downloader-for-Jira.svg) Jira App # Simple Bulk Attachment Downloader for Jira Simple Bulk Attachment Downloader grabs every attachment from a set of Jira issues in a single click. Parallel processing makes it roughly 3x faster than downloading files one by one, and it preserves the issue-key naming so you can match files back to tickets. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/984902822/simple-bulk-attachment-downloader-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=simple-bulk-attachment-downloader-for-jira)[User Guide](/docs/Simple-Bulk-Attachment-Downloader-for-Jira/user-docs.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Simple Bulk Issues Excel CSV Export for Jira icon](/img/Simple-Bulk-Issues-Excel-CSV-Export-for-Jira.svg) Jira App # Simple Bulk Issues Excel CSV Export for Jira Simple Bulk Issues Export lets you export filtered Jira issues to Excel (XLS/XLSX) or CSV. Choose exactly which fields to include, drive the export with a JQL filter, and handle large result sets that the native export times out on. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/3818473739/simple-bulk-issues-excel-csv-export-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=simple-bulk-issues-excel-csv-export-for-jira)[User Guide](/docs/Simple-Bulk-Issues-Excel-CSV-Export-for-Jira/user-docs.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ![Widget Carousel for Confluence icon](/img/carousel-32x32.svg) Confluence App # Widget Carousel for Confluence Widget Carousel lets you embed and display image carousels on Confluence pages — showcase visuals, banners, or product images in a compact, swipeable format. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237046/widget-carousel-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=widget-carousel-for-confluence)[User Guide](/docs/carousel-for-confluence/usage.md) Free for up to 10 users · Cloud · Atlassian Marketplace --- ## [Excalidraw AI Agent for Confluence: Whiteboards You Can Talk To](/blog/excalidraw-ai-agent-confluence.md) October 10, 2026 · 7 min read [NGPilot](https://ngpilot.com) Confluence holds your team's diagrams in two worlds, and the two don't talk to each other. Text-defined diagrams — Mermaid and friends — are what AI speaks natively. They're source code, so a chat agent can read them, write them, and revise them. We shipped exactly that last week: [an AI agent for Mermaid in Confluence](/blog/mermaid-ai-agent-confluence.md). Whiteboards are the other world. Freeform shapes, hand-drawn lines, arrows you drag where they need to go — the format that's actually intuitive to put in front of people. Every team has one: the architecture board on the team page, the incident flow everyone references, the onboarding map. And AI couldn't touch any of it. Ask a chat agent for a change to a whiteboard and you'd get a text *description* of a change, and someone still had to open the canvas and do it by hand. That gap is why whiteboards go stale. Editing shapes one drag at a time is slow enough that nobody does it, and AI — the thing that was supposed to make maintenance cheap — had no way in. The AI agent in [Excalidraw Plus Whiteboards & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence) closes the gap: the whiteboard stays what it always was — visual, intuitive, for people — but now you can operate it in plain language, from Confluence chat. **Tags:** * [confluence](/blog/tags/confluence.md) * [excalidraw](/blog/tags/excalidraw.md) * [whiteboard](/blog/tags/whiteboard.md) * [diagrams](/blog/tags/diagrams.md) * [ai](/blog/tags/ai.md) * [agent](/blog/tags/agent.md) [**Read more**](/blog/excalidraw-ai-agent-confluence.md) --- # Advanced Modern Code Blocks Features — Performance Tuning & Tips April 21, 2026 · 2 min read [NGPilot](https://ngpilot.com) Modern Code Blocks adds a Monaco-powered editor and syntax highlighting for 85+ languages in Confluence. This article explains embedding, theming, and performance tips. ## Quick prerequisites[​](#quick-prerequisites "Direct link to Quick prerequisites") * Confluence Cloud with [Modern Code Blocks](/docs/Modern-Code-Blocks-for-Confluence/user-docs.md) installed ## Embedding large snippets[​](#embedding-large-snippets "Direct link to Embedding large snippets") * Set Max Height to keep long code blocks manageable * Avoid inline images in code blocks ## Theme & editor tips[​](#theme--editor-tips "Direct link to Theme & editor tips") * Choose appropriate theme for readability * Use Monaco's formatting shortcuts to tidy code ## Related apps & resources[​](#related-apps--resources "Direct link to Related apps & resources") * [Modern Code Blocks for Confluence](/apps/modern-code-blocks-for-confluence.md) * [Enhanced Markdown for Confluence](/apps/enhanced-markdown-for-confluence.md) — Markdown editing with live preview * [Code blocks performance FAQ](/blog/faq-code-blocks-performance.md) — performance tips and best practices * [Confluence Markdown vs WYSIWYG FAQ](/blog/faq-confluence-markdown-vs-wysiwyg.md) — choosing the right editor Try Modern Code Blocks for Confluence Monaco editor, 85+ languages (JSON, XML, YAML, SQL), 50+ themes, diff view, and auto dark/light mode — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-code-blocks-for-confluence) ## Related guides * [Code Blocks for Confluence — Monaco Editor & Themes](/blog/code-blocks-confluence-monaco-editor.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [code-blocks](/blog/tags/code-blocks.md) * [how-to](/blog/tags/how-to.md) --- # AI Code Review in Confluence: Document and Share Code Reviews July 30, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer AI can help document code reviews in Confluence by summarizing changes, organizing findings, and extracting action items. Create templates, use AI to populate them, and build a searchable review knowledge base. What you'll learn 1. How to create code review templates in Confluence 2. How to use AI to summarize code changes and PRs 3. How to document review findings with AI assistance 4. How to extract and track action items from reviews Code reviews happen in pull requests, but the decisions and context often get lost. When someone asks "why did we implement it this way?" the answer is buried in a closed PR with hundreds of comments. Documenting code reviews in Confluence preserves this context. AI can automate the documentation, turning unstructured PR discussions into organized knowledge. This guide covers how to use AI for code review documentation. ## Why Document Code Reviews[​](#why-document-code-reviews "Direct link to Why Document Code Reviews") **Institutional memory.** Decisions, trade-offs, and context get preserved. New team members can understand past choices. **Knowledge sharing.** Reviews become learning opportunities. Team members can read past reviews to understand patterns and conventions. **Audit trail.** Security reviews, compliance checks, and architectural decisions are documented for future reference. **Pattern identification.** Over time, you can identify common issues, recurring patterns, and areas for improvement. ## How to Use AI for Code Review Documentation: Step-by-Step[​](#how-to-use-ai-for-code-review-documentation-step-by-step "Direct link to How to Use AI for Code Review Documentation: Step-by-Step") ### 1. Create a Code Review Template in Confluence[​](#1-create-a-code-review-template-in-confluence "Direct link to 1. Create a Code Review Template in Confluence") **Template structure:** ``` # Code Review: [PR Title] ## PR Information - **PR Link:** [link to pull request] - **Author:** @author - **Reviewer(s):** @reviewer1, @reviewer2 - **Date:** {{date}} - **Jira Issue:** [link to Jira ticket] ## Code Summary [AI-generated summary of changes] ## Changes Overview | File | Type | Description | |------|------|-------------| | [file] | Added/Modified/Deleted | [what changed] | ## Review Findings ### Critical Issues - [issue 1] ### Suggestions - [suggestion 1] ### Questions - [question 1] ## Decisions Made - [decision 1]: [rationale] ## Action Items | Action | Assignee | Jira Issue | Status | |--------|----------|------------|--------| | [task] | @person | [link] | Pending | ## Testing - [ ] Unit tests added/updated - [ ] Integration tests pass - [ ] Manual testing completed ## Lessons Learned [What we learned from this review] ``` **How to create the template:** 1. Create a new Confluence page 2. Click **... > Templates > Create Template** 3. Paste the template structure 4. Save with name "Code Review Template" 5. Set as default for code review pages ### 2. Use AI to Summarize Code Changes[​](#2-use-ai-to-summarize-code-changes "Direct link to 2. Use AI to Summarize Code Changes") **Input for AI summarization:** ``` Summarize this code change for documentation: PR Title: Add rate limiting to API endpoints Files changed: - src/middleware/rateLimit.ts (added) - src/routes/api.ts (modified) - src/config/settings.ts (modified) - tests/middleware/rateLimit.test.ts (added) Description: Added rate limiting middleware to prevent API abuse. Uses sliding window algorithm with configurable limits per endpoint. Default: 100 requests per minute. Review comments: - @john: "Consider adding rate limit headers in response" - @sarah: "Should we apply this to internal APIs too?" - @mike: "LGTM, tests look good" ``` **AI output:** ``` ## Code Summary This PR adds rate limiting protection to API endpoints to prevent abuse and ensure fair usage. The implementation uses a sliding window algorithm that tracks request counts per client IP. ### Key Changes: 1. **New middleware** (`rateLimit.ts`): Implements rate limiting logic with configurable limits and time windows 2. **API integration**: Applied rate limiting to all public API endpoints 3. **Configuration**: Added rate limit settings to central config 4. **Tests**: Comprehensive test coverage for rate limiting behavior ### Technical Decisions: - Sliding window algorithm (more accurate than fixed window) - Per-IP tracking (prevents abuse from single clients) - Configurable limits per endpoint (flexibility for different use cases) - Rate limit headers in responses (helps clients respect limits) ### Review Highlights: - Response headers suggested for client-side rate limit awareness - Consideration for internal API exemptions - Positive feedback on test coverage ``` ### 3. Document Review Findings with AI Assistance[​](#3-document-review-findings-with-ai-assistance "Direct link to 3. Document Review Findings with AI Assistance") **Organizing review comments:** ``` Organize these code review comments into structured findings: Comments: - "This function is too long, consider breaking it up" (line 45) - "Missing error handling for network failures" (line 78) - "Great use of the strategy pattern here" (line 23) - "Should we add logging for rate limit hits?" (line 92) - "Variable name is unclear, suggest 'maxRetries'" (line 34) ``` **AI output:** ``` ## Review Findings ### Code Quality - **Function length** (line 45): Consider breaking up long function into smaller, focused functions for better readability and testability - **Variable naming** (line 34): Rename variable to 'maxRetries' for clarity ### Error Handling - **Network failures** (line 78): Add error handling for network failures to prevent unhandled exceptions ### Observability - **Rate limit logging** (line 92): Add logging when rate limits are hit for monitoring and debugging ### Positive Feedback - **Design pattern** (line 23): Good use of strategy pattern for flexible rate limiting algorithms ``` ### 4. Extract Action Items from Reviews[​](#4-extract-action-items-from-reviews "Direct link to 4. Extract Action Items from Reviews") **AI extraction of action items:** ``` Extract action items from this code review: Review discussion: - @john: "We should add rate limit headers" → @sarah agreed - @sarah: "Need to document the rate limit values in API docs" - @mike: "Create a follow-up ticket for internal API rate limiting" - Team decided to defer logging to next sprint ``` **AI output:** ``` ## Action Items | Action | Assignee | Jira Issue | Priority | Due | |--------|----------|------------|----------|-----| | Add rate limit headers to API responses | @sarah | [API-123] | High | Sprint 24 | | Document rate limit values in API docs | @john | [DOC-456] | Medium | Sprint 24 | | Create ticket for internal API rate limiting | @mike | [API-789] | Low | Backlog | | Add rate limit hit logging | Unassigned | [LOG-012] | Medium | Sprint 25 | ``` ### 5. Build a Code Review Knowledge Base[​](#5-build-a-code-review-knowledge-base "Direct link to 5. Build a Code Review Knowledge Base") **Organize reviews for retrieval:** ``` Code Reviews/ ├── 2026/ │ ├── Q3/ │ │ ├── Security Reviews/ │ │ │ ├── rate-limiting-api.md │ │ │ └── auth-token-validation.md │ │ ├── Architecture Changes/ │ │ │ ├── database-migration-v2.md │ │ │ └── microservice-extraction.md │ │ └── Feature Reviews/ │ │ ├── dark-mode-implementation.md │ │ └── export-csv-feature.md ``` **Metadata for search:** Add page properties to each review: ``` --- pr-link: https://github.com/org/repo/pull/123 author: @john reviewers: @sarah, @mike date: 2026-07-30 type: security status: approved jira-issue: PERF-456 --- ``` **Search examples:** * "Show me all security reviews from Q3" * "Find reviews by @sarah" * "What reviews are linked to PERF-456?" * "Show reviews with critical findings" ## FAQ[​](#faq "Direct link to FAQ") ### Can AI help with code review documentation?[​](#can-ai-help-with-code-review-documentation "Direct link to Can AI help with code review documentation?") Yes. AI can summarize code changes, organize review comments, extract action items, and generate structured documentation from unstructured review discussions. ### How do I document code reviews in Confluence?[​](#how-do-i-document-code-reviews-in-confluence "Direct link to How do I document code reviews in Confluence?") Create a template with sections for PR link, code summary, findings, decisions, and action items. Use AI to populate the template from PR descriptions and review comments. ### Can AI identify code review patterns?[​](#can-ai-identify-code-review-patterns "Direct link to Can AI identify code review patterns?") Yes. AI can analyze review history to find common issues, recurring patterns, and team coding conventions. This helps improve code quality over time. ### How do I link code reviews to Jira issues?[​](#how-do-i-link-code-reviews-to-jira-issues "Direct link to How do I link code reviews to Jira issues?") Include Jira issue links in your review template. AI can extract these links and create bidirectional references between Confluence reviews and Jira tickets. ### Should all code reviews be documented in Confluence?[​](#should-all-code-reviews-be-documented-in-confluence "Direct link to Should all code reviews be documented in Confluence?") Document significant reviews (security fixes, architecture changes, complex features) but skip trivial changes. Focus on reviews that provide learning value or decision context. ## Related guides[​](#related-guides "Direct link to Related guides") * [How to Use ChatGPT in Confluence for Better Documentation](/blog/how-to-use-chatgpt-in-confluence.md) * [AI Meeting Notes in Confluence: Capture and Share Automatically](/blog/ai-meeting-notes-confluence.md) * [How to Write Better Jira Ticket Descriptions with AI](/blog/write-better-jira-ticket-descriptions-with-ai.md) * [Confluence Page Templates: How to Create and Use Them](/blog/advanced-code-blocks-confluence.md) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [ai](/blog/tags/ai.md) * [code-review](/blog/tags/code-review.md) * [how-to](/blog/tags/how-to.md) * [development](/blog/tags/development.md) --- # How to Use AI for Confluence Documentation Review July 30, 2026 · 7 min read [NGPilot](https://ngpilot.com) Quick Answer AI can automatically review Confluence documentation for quality issues, content gaps, and consistency problems. Run AI audits to identify outdated content, missing sections, and improvement opportunities. What you'll learn 1. How to run AI content audits on your Confluence spaces 2. How to identify content gaps with AI analysis 3. How to ensure consistency with AI style checking 4. How to create automated quality reports Documentation quality degrades over time. Pages get outdated, formats drift, and gaps emerge as the team and product evolve. Manual review is time-consuming and often inconsistent. AI can automate documentation review, identifying quality issues and improvement opportunities at scale. This guide covers how to use AI for Confluence documentation review, from audits to automated reports. ## Why AI Documentation Review Matters[​](#why-ai-documentation-review-matters "Direct link to Why AI Documentation Review Matters") **Scale.** AI can review hundreds of pages in minutes, something that would take humans days or weeks. **Consistency.** AI applies the same standards to every page. No more subjective quality assessments. **Proactivity.** AI can identify issues before they become problems — outdated content, missing sections, consistency drift. **Actionable insights.** AI doesn't just find problems; it suggests specific improvements and prioritizes them by impact. ## How to Use AI for Confluence Documentation Review: Step-by-Step[​](#how-to-use-ai-for-confluence-documentation-review-step-by-step "Direct link to How to Use AI for Confluence Documentation Review: Step-by-Step") ### 1. Run an AI Content Audit on Your Confluence Space[​](#1-run-an-ai-content-audit-on-your-confluence-space "Direct link to 1. Run an AI Content Audit on Your Confluence Space") **What an AI audit checks:** | Category | Issues Found | | ----------------------- | ------------------------------------------- | | Outdated content | Pages not updated in 6+ months | | Broken links | Internal and external links that don't work | | Missing sections | Pages without required structure | | Low readability | Complex sentences, jargon, passive voice | | Inconsistent formatting | Mixed heading styles, list formats | | Accessibility issues | Missing alt text, poor contrast | **How to run an audit:** 1. Go to **Space Settings > Content Audit** (or use a third-party app) 2. Select the space to audit 3. Configure audit criteria: * **Freshness threshold** — pages older than X months * **Quality standards** — readability score, structure requirements * **Consistency rules** — terminology, formatting, tone 4. Run the audit 5. Review the report **Example audit output:** ``` Space: Engineering Pages audited: 247 Issues found: 89 Breakdown: - Outdated content: 23 pages (not updated in 6+ months) - Broken links: 15 pages with dead links - Missing sections: 12 pages without FAQ or Related sections - Low readability: 28 pages below reading level 8 - Inconsistent formatting: 11 pages with mixed styles ``` ### 2. Identify Content Gaps with AI Analysis[​](#2-identify-content-gaps-with-ai-analysis "Direct link to 2. Identify Content Gaps with AI Analysis") AI can find topics you're missing: **How AI identifies gaps:** 1. Analyze your existing content 2. Compare against industry standards and competitor documentation 3. Identify common topics for your technology stack 4. Flag areas with insufficient coverage **Gap analysis categories:** | Gap Type | Example | | ----------------- | --------------------------------------------- | | Missing topics | No documentation for API authentication | | Shallow coverage | Only 1 paragraph on error handling | | Missing audiences | No content for non-technical stakeholders | | Missing formats | No video tutorials or interactive guides | | Missing updates | Documentation doesn't reflect recent features | **How to run gap analysis:** 1. Use a third-party tool (Tettra, Guru, or custom solution) 2. Define your documentation scope: * Product features * Technical processes * Team policies 3. Run the analysis 4. Review suggested gaps 5. Prioritize by business impact **Example gap analysis:** ``` Topic: API Authentication Current coverage: 1 page, 200 words Industry standard: 5 pages, 2000 words Missing sections: - OAuth 2.0 implementation guide - API key management - Rate limiting documentation - Error handling for auth failures - Security best practices ``` ### 3. Ensure Consistency with AI Style Checking[​](#3-ensure-consistency-with-ai-style-checking "Direct link to 3. Ensure Consistency with AI Style Checking") AI can enforce consistent style across all pages: **Style rules AI can enforce:** * **Terminology** — consistent use of terms (e.g., "deploy" vs. "ship") * **Formatting** — heading levels, list styles, code block formats * **Tone** — formal vs. casual, technical vs. accessible * **Structure** — required sections, page layout * **Metadata** — required labels, properties, and tags **Configuration:** 1. Define your style guide in the AI tool 2. Set rules for each category: * **Required terms** — "use 'deploy' not 'ship'" * **Forbidden terms** — avoid jargon, acronyms * **Formatting rules** — H2 for sections, H3 for subsections * **Structure rules** — must have Introduction, FAQ, Related 3. Run style check on all pages 4. Review flagged issues 5. Apply fixes (bulk or individually) **Example style issues:** ``` Page: "Deployment Process" Issues found: - Terminology: Uses "release" instead of "deploy" (line 45) - Formatting: H3 used where H2 expected (line 12) - Structure: Missing FAQ section - Tone: Too casual for policy document (line 23) ``` ### 4. Generate Improvement Suggestions with AI[​](#4-generate-improvement-suggestions-with-ai "Direct link to 4. Generate Improvement Suggestions with AI") AI doesn't just find problems; it suggests improvements: **Types of AI suggestions:** * **Expand thin content** — add detail to short sections * **Add examples** — include code samples, screenshots * **Improve clarity** — simplify complex sentences * **Add structure** — include headings, lists, tables * **Link related content** — connect to other pages **How to get AI suggestions:** 1. Select a page to improve 2. Click **AI > Suggest improvements** 3. Review AI recommendations: * **Content gaps** — sections that need expansion * **Clarity issues** — sentences that are hard to understand * **Missing examples** — areas that need illustration * **Structure improvements** — better organization 4. Apply suggestions (accept, modify, or reject) **Example suggestions:** ``` Page: "Database Migration Guide" AI suggestions: 1. Expand "Prerequisites" section — currently 1 sentence, needs 3-5 items 2. Add code example for migration script (line 67) 3. Simplify sentence at line 89 — too complex for target audience 4. Add troubleshooting section for common migration errors 5. Link to related page: "Database Backup Procedures" ``` ### 5. Create Automated Quality Reports[​](#5-create-automated-quality-reports "Direct link to 5. Create Automated Quality Reports") Set up regular AI audits that generate reports: **Weekly automated report:** ``` # Documentation Quality Report — Week of Jul 28, 2026 ## Overall Health Score: 78/100 (↑ 3 from last week) ## Issues Found - New issues: 12 - Resolved issues: 15 - Outstanding issues: 67 ## Top Issues 1. Outdated content: 23 pages need review 2. Broken links: 8 new broken links found 3. Missing sections: 5 pages without FAQ ## Improvement Actions - [ ] Review 5 oldest pages for accuracy - [ ] Fix 8 broken links - [ ] Add FAQ sections to 5 pages - [ ] Update terminology on 3 pages ## Trends - Content freshness: Improving (fewer outdated pages) - Readability: Stable (average grade 9.2) - Consistency: Improving (fewer style violations) ``` **How to set up automated reports:** 1. Configure weekly audit schedule 2. Define report recipients 3. Set quality thresholds for alerts 4. Include trend analysis (week-over-week) 5. Add action items with assignees ## FAQ[​](#faq "Direct link to FAQ") ### Can AI review Confluence documentation automatically?[​](#can-ai-review-confluence-documentation-automatically "Direct link to Can AI review Confluence documentation automatically?") Yes. AI tools can analyze Confluence pages for quality issues, content gaps, consistency problems, and improvement opportunities. Atlassian Intelligence and third-party apps provide these capabilities. ### What quality issues can AI identify in documentation?[​](#what-quality-issues-can-ai-identify-in-documentation "Direct link to What quality issues can AI identify in documentation?") AI can find outdated content, broken links, missing sections, inconsistent terminology, unclear writing, and accessibility issues. It can also identify pages that need updates based on code or process changes. ### How does AI identify content gaps?[​](#how-does-ai-identify-content-gaps "Direct link to How does AI identify content gaps?") AI compares your documentation against industry standards, competitor content, and common topics for your technology stack. It identifies areas where you lack coverage or depth. ### Can AI ensure documentation consistency?[​](#can-ai-ensure-documentation-consistency "Direct link to Can AI ensure documentation consistency?") Yes. AI can enforce consistent terminology, formatting, tone, and structure across all pages. It can flag deviations from your style guide and suggest corrections. ### How often should I run AI documentation audits?[​](#how-often-should-i-run-ai-documentation-audits "Direct link to How often should I run AI documentation audits?") Run a full audit monthly for active spaces, quarterly for stable spaces. Set up weekly automated reports to track content health trends and catch issues early. ## Related guides[​](#related-guides "Direct link to Related guides") * [How to Organize Your Confluence Space for Easy Navigation](/blog/faq-confluence-dark-mode-apps.md) * [How to Use ChatGPT in Confluence for Better Documentation](/blog/how-to-use-chatgpt-in-confluence.md) * [Confluence Page Templates: How to Create and Use Them](/blog/advanced-code-blocks-confluence.md) * [AI-Powered Confluence Search: Find Anything Fast](/blog/ai-powered-confluence-search.md) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [ai](/blog/tags/ai.md) * [documentation](/blog/tags/documentation.md) * [how-to](/blog/tags/how-to.md) * [quality](/blog/tags/quality.md) --- # How to Use AI for Jira Sprint Planning and Velocity Prediction July 30, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer AI can predict sprint velocity and forecast capacity by analyzing historical data. Use AI recommendations to plan realistic sprints, suggest optimal scope, and track prediction accuracy over time. What you'll learn 1. How to enable AI velocity prediction in Jira 2. How to use AI for capacity forecasting 3. How to get AI scope recommendations for sprint planning 4. How to track and improve AI prediction accuracy Sprint planning is part science, part guesswork. Teams estimate velocity based on gut feeling, leading to overcommitment or underutilization. AI can replace this guesswork with data-driven predictions. This guide covers how to use AI for Jira sprint planning, from velocity prediction to scope recommendations. ## Why AI Sprint Planning Matters[​](#why-ai-sprint-planning-matters "Direct link to Why AI Sprint Planning Matters") **Accuracy.** AI analyzes historical data to predict velocity more accurately than gut feeling. This reduces sprint overruns and missed commitments. **Realism.** AI factors in team capacity, absences, and interruptions to forecast what is actually achievable, not what you hope to achieve. **Optimization.** AI suggests the optimal mix of stories based on priority, dependencies, and team expertise to maximize sprint value. **Learning.** AI improves over time as it sees more sprints and outcomes. It learns your team's patterns and gets better at predictions. ## How to Use AI for Jira Sprint Planning: Step-by-Step[​](#how-to-use-ai-for-jira-sprint-planning-step-by-step "Direct link to How to Use AI for Jira Sprint Planning: Step-by-Step") ### 1. Enable AI Velocity Prediction in Jira[​](#1-enable-ai-velocity-prediction-in-jira "Direct link to 1. Enable AI Velocity Prediction in Jira") **For Jira Cloud:** 1. Go to **Project Settings > AI Planning** 2. Enable **Velocity prediction** 3. Configure training data: * **Historical sprints** — how many past sprints to analyze * **Factors to include** — team size, velocity, completion rate * **Exclusions** — skip anomalous sprints (holidays, incidents) 4. Set prediction confidence levels: * **High confidence** — use AI recommendation directly * **Medium confidence** — use as reference * **Low confidence** — ignore, use manual estimation **For Jira Server/Data Center:** 1. Go to **Administration > Applications > AI Planning** 2. Enable velocity prediction 3. Configure the prediction model 4. Set project-specific settings ### 2. Use AI for Capacity Forecasting[​](#2-use-ai-for-capacity-forecasting "Direct link to 2. Use AI for Capacity Forecasting") AI capacity forecasting considers multiple factors: **Factors AI analyzes:** | Factor | How It's Used | | ------------------- | -------------------------------- | | Historical velocity | Baseline for capacity | | Team size changes | Adjust for additions/removals | | Known absences | Subtract PTO, holidays | | Past interruptions | Factor in on-call, incidents | | Story complexity | Adjust for harder/easier stories | **Example capacity forecast:** ``` Sprint 24 Capacity Forecast Base velocity: 42 points (average of last 5 sprints) Adjustments: - Team size: +1 developer (+8 points) - PTO: -2 days (-6 points) - On-call rotation: -3 points - Holiday (July 4th): -2 points Predicted capacity: 39 points Recommended scope: 35-37 points (90% of predicted) ``` **How to configure:** 1. Go to **Sprint Planning > AI Capacity** 2. Enable **Smart forecasting** 3. Connect to team calendar for PTO/holidays 4. Configure interruption factors: * **On-call rotation** — subtract X points per sprint * **Incident response** — subtract Y points per sprint * **Meeting load** — subtract Z points per sprint ### 3. Get AI Scope Recommendations[​](#3-get-ai-scope-recommendations "Direct link to 3. Get AI Scope Recommendations") AI suggests which stories to include in a sprint: **How AI recommends scope:** 1. Analyze backlog stories (priority, points, dependencies) 2. Factor in team capacity and velocity 3. Consider story dependencies and risks 4. Optimize for maximum business value 5. Suggest sprint scope with confidence scores **Example recommendation:** ``` Sprint 24 Scope Recommendation Recommended stories (37 points): 1. PERF-123: Rate limiting (8 points) — High priority, no dependencies 2. PERF-456: Caching layer (13 points) — High priority, depends on PERF-123 3. UI-789: Dark mode toggle (5 points) — Medium priority, no dependencies 4. DOC-012: API documentation (3 points) — Low priority, quick win 5. TEST-345: Integration tests (5 points) — Medium priority, improves quality Deferred (not enough capacity): - FEAT-678: Export feature (8 points) — Schedule for Sprint 25 - FEAT-901: Bulk operations (8 points) — Schedule for Sprint 25 Confidence: 87% (based on similar sprint patterns) ``` **Configuration:** 1. Go to **Sprint Planning > AI Scope** 2. Enable **Smart recommendations** 3. Set optimization goals: * **Maximize value** — prioritize high-business-value stories * **Minimize risk** — prefer low-dependency, low-complexity stories * **Balance** — mix of value and risk 4. Configure constraints: * **Minimum story points** — don't underload * **Maximum story points** — don't overload * **Required story types** — must include bugs, tech debt, etc. ### 4. Track Prediction Accuracy Over Time[​](#4-track-prediction-accuracy-over-time "Direct link to 4. Track Prediction Accuracy Over Time") **Metrics to track:** | Metric | Target | How to Measure | | ------------------- | --------- | ----------------------------------- | | Velocity prediction | ±10% | Compare predicted vs. actual | | Capacity accuracy | ±15% | Compare forecasted vs. achieved | | Scope completion | 85%+ | Stories completed / stories planned | | Prediction trend | Improving | Track accuracy over sprints | **Accuracy dashboard:** ``` Sprint Prediction Accuracy Sprint 20: Predicted 40, Actual 38 (95% accuracy) Sprint 21: Predicted 42, Actual 35 (83% accuracy) Sprint 22: Predicted 38, Actual 40 (95% accuracy) Sprint 23: Predicted 41, Actual 39 (95% accuracy) Average accuracy: 92% Trend: Stable ``` **How to track:** 1. Go to **Project Settings > AI Planning > Accuracy** 2. Enable **Prediction tracking** 3. Review after each sprint: * Compare predicted velocity with actual * Analyze why predictions were off * Adjust AI factors if needed ### 5. Refine AI Recommendations with Feedback[​](#5-refine-ai-recommendations-with-feedback "Direct link to 5. Refine AI Recommendations with Feedback") **Feedback loop:** 1. Review AI recommendations before each sprint 2. Accept suggestions that are accurate 3. Modify suggestions that need adjustment 4. Reject suggestions that are wrong 5. Provide reason for modifications/rejections **Example feedback:** ``` Sprint 24 Planning Review AI Recommendation: 37 points Team Commitment: 35 points Modifications: - Removed PERF-456 (13 points) — team felt it was underestimated - Added BUG-234 (2 points) — critical bug, high priority Feedback provided: - PERF-456 complexity: AI underestimated (13 → 17 points) - BUG-234 priority: AI marked low, but it's actually high ``` **How feedback improves AI:** * AI learns from complexity underestimations * AI adjusts priority weights based on corrections * AI improves dependency analysis * AI refines capacity calculations ## FAQ[​](#faq "Direct link to FAQ") ### Can AI predict sprint velocity accurately?[​](#can-ai-predict-sprint-velocity-accurately "Direct link to Can AI predict sprint velocity accurately?") AI can predict velocity with reasonable accuracy based on historical data. Most teams see 80-90% accuracy after 3-5 sprints of training data. Predictions improve as more data becomes available. ### How does AI forecast sprint capacity?[​](#how-does-ai-forecast-sprint-capacity "Direct link to How does AI forecast sprint capacity?") AI factors in team size, historical velocity, known absences, holidays, and past interruptions to forecast realistic capacity. It adjusts for team changes and process improvements. ### Can AI recommend which stories to include in a sprint?[​](#can-ai-recommend-which-stories-to-include-in-a-sprint "Direct link to Can AI recommend which stories to include in a sprint?") Yes. AI analyzes story priority, dependencies, team expertise, and capacity to suggest optimal sprint scope. It considers historical completion rates for similar stories. ### What data does AI need for accurate predictions?[​](#what-data-does-ai-need-for-accurate-predictions "Direct link to What data does AI need for accurate predictions?") AI needs 3-5 sprints of historical data including planned vs. completed story points, team composition, and any factors that affected velocity (holidays, incidents, etc.). ### Can I override AI sprint planning recommendations?[​](#can-i-override-ai-sprint-planning-recommendations "Direct link to Can I override AI sprint planning recommendations?") Yes. AI provides recommendations, but humans have final control. You can accept, modify, or reject any AI suggestion based on your team's judgment. ## Related guides[​](#related-guides "Direct link to Related guides") * [How to Plan Jira Sprints That Actually Work](/blog/plan-jira-sprints-that-actually-work.md) * [Jira Backlog Grooming: The Complete Guide](/blog/jira-backlog-grooming-complete-guide.md) * [How to Set Up Jira Dashboards for Sprint Tracking](/blog/jira-dashboard-sprint-tracking-setup.md) * [AI for Jira Workflows: Automate Triage and Assignment](/blog/ai-for-jira-workflows-automate-triage-assignment.md) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [ai](/blog/tags/ai.md) * [sprint-planning](/blog/tags/sprint-planning.md) * [velocity](/blog/tags/velocity.md) * [how-to](/blog/tags/how-to.md) --- # AI for Jira Workflows: Automate Triage, Assignment, and Prioritization July 30, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer AI in Jira automates issue triage, assignment, and prioritization by analyzing content and historical patterns. Configure Atlassian Intelligence to suggest categories, assignees, and priorities automatically. What you'll learn 1. How to enable and configure AI features in Jira 2. How to set up AI-powered issue triage and categorization 3. How to configure intelligent assignment based on team capacity 4. How to enable AI prioritization suggestions Every new Jira issue needs decisions: What type is it? Who should work on it? How urgent is it? These decisions happen manually today, taking time and introducing inconsistency. AI can automate these decisions by analyzing issue content, historical patterns, and team context. This guide covers how to use AI for Jira workflow automation, from triage to assignment. ## Why AI Matters for Jira Workflows[​](#why-ai-matters-for-jira-workflows "Direct link to Why AI Matters for Jira Workflows") **Speed.** Issues get triaged and assigned instantly instead of waiting for a human to review. This reduces time-to-start on critical work. **Consistency.** AI applies the same criteria to every issue. No more subjective prioritization or inconsistent categorization. **Scale.** As issue volume grows, manual triage becomes a bottleneck. AI handles any volume without additional overhead. **Learning.** AI improves over time as it sees more issues and outcomes. It learns your team's patterns and gets better at recommendations. ## How to Use AI for Jira Workflows: Step-by-Step[​](#how-to-use-ai-for-jira-workflows-step-by-step "Direct link to How to Use AI for Jira Workflows: Step-by-Step") ### 1. Enable Atlassian Intelligence in Jira[​](#1-enable-atlassian-intelligence-in-jira "Direct link to 1. Enable Atlassian Intelligence in Jira") **For Jira Cloud:** 1. Go to **Site Administration > Products > Atlassian Intelligence** 2. Enable **Issue triage** features: * **Auto-categorization** — suggest issue types and components * **Smart assignment** — recommend assignees * **Priority suggestions** — suggest priority levels 3. Configure which projects to apply AI to 4. Set permissions for AI features **For Jira Server/Data Center:** 1. Go to **Administration > Applications > Atlassian Intelligence** 2. Enable issue triage features 3. Configure the AI model and training data 4. Set project-specific rules ### 2. Set Up AI-Powered Issue Triage[​](#2-set-up-ai-powered-issue-triage "Direct link to 2. Set Up AI-Powered Issue Triage") AI triage analyzes new issues and suggests categorization: **How it works:** 1. User creates a new issue with a summary and description 2. AI analyzes the content against historical patterns 3. AI suggests: * Issue type (Bug, Task, Story, Epic) * Components (Frontend, Backend, Database) * Labels (performance, security, ui) * Priority (High, Medium, Low) **Configuration:** 1. Go to **Project Settings > AI Triage** 2. Enable **Auto-categorization** 3. Train the AI model: * Upload historical issues with correct categories * Review AI suggestions on new issues * Provide feedback (correct/incorrect) 4. Adjust confidence thresholds: * **High confidence (90%+)** — auto-apply * **Medium confidence (70-90%)** — suggest to user * **Low confidence (<70%)** — leave for manual triage **Example:** ``` New issue: "Login page shows white screen on Chrome" AI suggests: - Issue type: Bug (98% confidence) - Component: Frontend (95% confidence) - Label: ui, browser-compatibility (87% confidence) - Priority: High (82% confidence) Action: Auto-apply type and component, suggest label and priority ``` ### 3. Configure Intelligent Assignment Rules[​](#3-configure-intelligent-assignment-rules "Direct link to 3. Configure Intelligent Assignment Rules") AI assignment considers multiple factors to suggest the best person: **Factors AI considers:** * **Expertise** — who has worked on similar issues before * **Workload** — who has capacity right now * **Availability** — who is on-call, who is on PTO * **Rotation** — fair distribution across the team * **Dependencies** — who is blocked, who is available **Configuration:** 1. Go to **Project Settings > AI Assignment** 2. Enable **Smart assignment** 3. Define assignment rules: * **By component** — Frontend issues go to frontend team * **By expertise** — Database issues go to DB specialists * **Round-robin** — Distribute evenly among team members * **Load-balanced** — Assign to least busy person **Example assignment logic:** ``` Issue: "API endpoint returning 500 error" AI analysis: - Component: Backend (inferred from "API endpoint") - Expertise: @sarah (resolved 15 similar issues) - Workload: @sarah has 3 open issues, @john has 7 - Availability: @sarah is available, @john is on PTO AI recommendation: Assign to @sarah (95% confidence) ``` **Override rules:** * Critical issues always go to on-call engineer * Security issues always go to security team * Customer-reported issues always go to support lead ### 4. Enable AI Prioritization Suggestions[​](#4-enable-ai-prioritization-suggestions "Direct link to 4. Enable AI Prioritization Suggestions") AI prioritization analyzes issue impact and urgency: **How it works:** 1. AI analyzes issue content, linked issues, and business context 2. Compares against historical priority patterns 3. Suggests priority level with confidence score 4. Explains reasoning (optional) **Priority factors:** | Factor | Weight | Example | | --------------- | ------ | ----------------------------------- | | Business impact | High | Affects all users vs. one user | | Urgency | High | Production issue vs. enhancement | | Complexity | Medium | Simple fix vs. architectural change | | Dependencies | Medium | Blocks other work vs. standalone | | Customer impact | High | External customer vs. internal | **Configuration:** 1. Go to **Project Settings > AI Prioritization** 2. Enable **Priority suggestions** 3. Train on historical data: * Upload past issues with correct priorities * Review AI suggestions on new issues * Provide feedback on accuracy 4. Set auto-apply rules: * **High confidence** — auto-apply priority * **Medium confidence** — suggest to assignee * **Low confidence** — leave for manual prioritization **Example:** ``` Issue: "Critical: Payment processing failing for all users" AI analysis: - Business impact: High (affects revenue) - Urgency: High (production issue) - Scope: All users (not isolated) - Historical pattern: Similar to previous P0 incidents AI suggestion: Priority = Critical (97% confidence) Reasoning: Production payment issue affecting all users ``` ### 5. Monitor and Refine AI Recommendations[​](#5-monitor-and-refine-ai-recommendations "Direct link to 5. Monitor and Refine AI Recommendations") AI needs ongoing monitoring and refinement: **Monitoring dashboard:** * **Triage accuracy** — % of AI suggestions accepted vs. modified * **Assignment accuracy** — % of assignments accepted vs. reassigned * **Priority accuracy** — % of priorities accepted vs. changed * **Response time** — time from issue creation to assignment * **Resolution time** — time from assignment to resolution **Feedback loop:** 1. Review AI suggestions daily for the first week 2. Provide feedback on incorrect suggestions 3. Track patterns in feedback (which categories need improvement) 4. Adjust AI rules based on feedback 5. Retrain models monthly with new data **Common issues and fixes:** | Issue | Cause | Fix | | ------------------ | -------------------------- | ------------------------------------ | | Wrong categories | Insufficient training data | Add more historical examples | | Poor assignment | Workload data outdated | Sync with calendar and capacity | | Incorrect priority | Missing business context | Add priority factors to descriptions | | Low confidence | Ambiguous content | Improve issue description templates | ## FAQ[​](#faq "Direct link to FAQ") ### Can AI automatically triage Jira issues?[​](#can-ai-automatically-triage-jira-issues "Direct link to Can AI automatically triage Jira issues?") Yes. Atlassian Intelligence can analyze issue content and suggest categories, priorities, and assignees based on historical patterns and team configuration. ### How does AI assign Jira issues to the right person?[​](#how-does-ai-assign-jira-issues-to-the-right-person "Direct link to How does AI assign Jira issues to the right person?") AI considers factors like team member expertise, current workload, past assignments, and issue complexity to suggest the best assignee. ### Can AI prioritize issues based on business impact?[​](#can-ai-prioritize-issues-based-on-business-impact "Direct link to Can AI prioritize issues based on business impact?") AI can analyze issue descriptions, linked issues, and business context to suggest priority levels. It learns from your team's prioritization patterns over time. ### What Jira data does AI use for recommendations?[​](#what-jira-data-does-ai-use-for-recommendations "Direct link to What Jira data does AI use for recommendations?") AI analyzes issue content, comments, labels, components, historical assignments, resolution times, and team patterns to make informed recommendations. ### Can I override AI suggestions in Jira?[​](#can-i-override-ai-suggestions-in-jira "Direct link to Can I override AI suggestions in Jira?") Yes. AI provides suggestions, but humans always have final control. You can accept, modify, or reject any AI recommendation. ## Related guides[​](#related-guides "Direct link to Related guides") * [Jira Workflow Automation: How to Automate Repetitive Tasks](/blog/jira-workflow-automation-guide.md) * [How to Write Better Jira Ticket Descriptions with AI](/blog/write-better-jira-ticket-descriptions-with-ai.md) * [Jira JQL Cheat Sheet: 20 Queries Every Team Needs](/blog/jira-jql-cheat-sheet-common-queries.md) * [How to Set Up Jira Dashboards for Sprint Tracking](/blog/jira-dashboard-sprint-tracking-setup.md) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [ai](/blog/tags/ai.md) * [automation](/blog/tags/automation.md) * [workflow](/blog/tags/workflow.md) * [how-to](/blog/tags/how-to.md) --- # AI Meeting Notes in Confluence: Capture and Share Automatically July 30, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer AI meeting notes in Confluence transcribe, summarize, and extract action items from meetings automatically. Connect your meeting platform, configure AI summarization, and share results with your team. What you'll learn 1. How to connect meeting platforms to Confluence for automatic transcription 2. How to configure AI to extract decisions and action items 3. How to create standardized meeting note templates 4. How to turn AI-extracted action items into Jira issues Meetings are where decisions get made, but the notes rarely get written. Someone volunteers to take notes, gets distracted by the conversation, and the team leaves with fragmented memories and no clear action items. AI meeting notes solve this by automatically capturing, transcribing, and summarizing meetings. This guide covers how to set up AI meeting notes in Confluence, from transcription to follow-up. ## Why AI Meeting Notes Matter[​](#why-ai-meeting-notes-matter "Direct link to Why AI Meeting Notes Matter") **Institutional memory.** Decisions, context, and rationale get captured automatically. New team members can read meeting history instead of asking "why did we do this?" **Accountability.** Action items with assignees and deadlines are extracted automatically. No more "I thought someone else was doing that." **Time savings.** The 30 minutes someone spends writing meeting notes after every meeting adds up to hours per week. AI handles this instantly. **Consistency.** Every meeting gets the same format, same level of detail, same structure. No more varying quality based on who took notes. ## How to Set Up AI Meeting Notes in Confluence: Step-by-Step[​](#how-to-set-up-ai-meeting-notes-in-confluence-step-by-step "Direct link to How to Set Up AI Meeting Notes in Confluence: Step-by-Step") ### 1. Connect Your Meeting Platform to Confluence[​](#1-connect-your-meeting-platform-to-confluence "Direct link to 1. Connect Your Meeting Platform to Confluence") **Option A: Atlassian Intelligence (native)** 1. Go to **Site Administration > Products > Atlassian Intelligence** 2. Enable **Meeting transcription** 3. Connect your calendar (Google Calendar or Outlook) 4. AI automatically transcribes meetings and creates Confluence pages **Option B: Third-party integrations** | App | Platform | Features | | ------------ | ----------------- | ----------------------------------- | | Grain | Zoom | Transcription, highlights, clips | | Fireflies.ai | Zoom, Teams, Meet | Transcription, action items, search | | Otter.ai | Zoom, Teams | Live transcription, summaries | | tl;dv | Zoom, Meet | Recording, transcription, clips | **Setup for Grain:** 1. Install Grain from Atlassian Marketplace 2. Connect your Zoom account 3. Enable auto-sync to Confluence 4. Configure which meetings to transcribe ### 2. Configure AI Summarization Settings[​](#2-configure-ai-summarization-settings "Direct link to 2. Configure AI Summarization Settings") Once transcription is enabled, configure how AI processes the content: **Go to:** Site Administration > Atlassian Intelligence > Meeting Notes **Settings to configure:** * **Auto-summarize** — generate summary when transcription completes * **Extract action items** — identify tasks, assignees, deadlines * **Extract decisions** — capture key decisions and rationale * **Extract follow-ups** — identify questions that need answers * **Create Jira issues** — automatically create issues from action items **Example output from AI summarization:** ``` ## Summary Team discussed Q3 roadmap priorities. Decided to focus on performance improvements over new features. Budget approved for caching infrastructure. ## Decisions 1. Prioritize performance work in Q3 over new features 2. Allocate $20k for caching infrastructure 3. Move feature X to Q4 backlog ## Action Items - @john: Research caching solutions by Friday - @sarah: Update roadmap document with new priorities - @mike: Schedule follow-up meeting for caching vendor demos ## Follow-up Questions - What is the expected performance improvement from caching? - Can we parallelize caching work with the current sprint? ``` ### 3. Create Meeting Note Templates[​](#3-create-meeting-note-templates "Direct link to 3. Create Meeting Note Templates") Standardize your meeting notes with templates: **Template structure:** ``` # Meeting: [Title] **Date:** {{date}} **Attendees:** {{attendees}} **Duration:** {{duration}} ## Agenda 1. [Topic 1] 2. [Topic 2] 3. [Topic 3] ## Notes [AI-generated transcription and summary] ## Decisions - [Decision 1]: [Rationale] - [Decision 2]: [Rationale] ## Action Items | Action | Assignee | Deadline | Status | |--------|----------|----------|--------| | [Task] | @[name] | [date] | Pending | ## Next Meeting **Date:** [date] **Topics:** [list] ``` **How to create the template:** 1. Create a new Confluence page 2. Click **... > Templates > Create Template** 3. Paste the template structure 4. Save with a descriptive name 5. Set as default for meeting notes pages ### 4. Share and Follow Up on Action Items[​](#4-share-and-follow-up-on-action-items "Direct link to 4. Share and Follow Up on Action Items") AI-extracted action items need follow-up to be effective: **Automatic Jira issue creation:** 1. Configure Atlassian Intelligence to create Jira issues from action items 2. Map action items to issue types (Task, Story, Bug) 3. Set default project and assignee rules 4. Enable notifications for new issues **Manual follow-up workflow:** 1. Review AI-extracted action items in the meeting notes page 2. Verify assignees and deadlines are correct 3. Create Jira issues for important items 4. Link Jira issues back to the meeting notes page 5. Track completion in sprint planning **Meeting notes with linked Jira issues:** ``` ## Action Items | Action | Jira Issue | Assignee | Deadline | |--------|------------|----------|----------| | Research caching | [PERF-123] | @john | Jul 5 | | Update roadmap | [PLAN-456] | @sarah | Jul 3 | ``` ### 5. Build a Meeting Notes Archive[​](#5-build-a-meeting-notes-archive "Direct link to 5. Build a Meeting Notes Archive") Organize meeting notes for easy retrieval: **Space structure:** ``` Meeting Notes/ ├── Team Standups/ │ ├── 2026-07/ │ │ ├── 2026-07-01-standup.md │ │ ├── 2026-07-02-standup.md │ │ └── ... ├── Sprint Planning/ │ ├── Sprint 23/ │ └── Sprint 24/ ├── Retrospectives/ │ ├── Sprint 22/ │ └── Sprint 23/ └── Project Meetings/ ├── Q3 Planning/ └── Vendor Reviews/ ``` **Page properties for search:** Add metadata to each meeting notes page: ``` --- meeting-type: standup date: 2026-07-01 team: engineering project: PERF --- ``` **Search examples:** * `meeting-type = standup AND date >= 2026-07-01` * `project = PERF AND meeting-type = planning` * `team = engineering AND meeting-type = retrospective` ## FAQ[​](#faq "Direct link to FAQ") ### Can Confluence automatically transcribe meetings?[​](#can-confluence-automatically-transcribe-meetings "Direct link to Can Confluence automatically transcribe meetings?") Yes. Atlassian Intelligence can transcribe audio from meeting recordings and generate text. For live transcription, third-party apps like Grain or Fireflies.ai integrate with Confluence to capture real-time notes. ### How accurate are AI-generated meeting notes?[​](#how-accurate-are-ai-generated-meeting-notes "Direct link to How accurate are AI-generated meeting notes?") AI transcription is typically 85-95% accurate depending on audio quality, speaker clarity, and technical terminology. Always review notes for accuracy before sharing with stakeholders. ### Can AI extract action items from meeting notes?[​](#can-ai-extract-action-items-from-meeting-notes "Direct link to Can AI extract action items from meeting notes?") Yes. Atlassian Intelligence can identify action items, assignees, and deadlines from meeting transcripts. It can also create Jira issues automatically from extracted action items. ### How do I organize meeting notes in Confluence?[​](#how-do-i-organize-meeting-notes-in-confluence "Direct link to How do I organize meeting notes in Confluence?") Create a dedicated 'Meeting Notes' space with templates for different meeting types (standup, retrospective, planning). Use page properties for metadata like date, attendees, and project. ### Can AI summarize recurring meetings?[​](#can-ai-summarize-recurring-meetings "Direct link to Can AI summarize recurring meetings?") Yes. AI can summarize weekly standups, monthly reviews, and quarterly planning sessions. Use templates with consistent structure so AI can extract patterns and trends over time. ## Related guides[​](#related-guides "Direct link to Related guides") * [How to Use ChatGPT in Confluence for Better Documentation](/blog/how-to-use-chatgpt-in-confluence.md) * [Confluence Page Templates: How to Create and Use Them](/blog/advanced-code-blocks-confluence.md) * [How to Automate Jira Issues from Confluence Pages](/blog/jira-issue-templates-best-practices.md) * [AI-Powered Confluence Search: Find Anything Fast](/blog/ai-powered-confluence-search.md) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [ai](/blog/tags/ai.md) * [meeting-notes](/blog/tags/meeting-notes.md) * [how-to](/blog/tags/how-to.md) * [productivity](/blog/tags/productivity.md) --- # AI-Powered Confluence Search: Find Anything Fast July 30, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer AI-powered Confluence search uses semantic understanding to find content even when keywords don't match. Ask questions in natural language and get relevant answers from your knowledge base. What you'll learn 1. How to enable and configure AI search in Confluence 2. How to write natural language queries for better results 3. How to use AI filters and facets to narrow search results 4. How to improve content discoverability with metadata Confluence search is powerful but often frustrating. You know the information exists, but your search queries don't find it. Keywords miss synonyms, related content uses different terminology, and results bury the answer under irrelevant pages. AI-powered search fixes this by understanding intent instead of just matching keywords. This guide covers how to use and optimize AI search in Confluence. ## Why AI Search Matters[​](#why-ai-search-matters "Direct link to Why AI Search Matters") **Natural language.** Instead of guessing keywords, ask questions: "How do we handle production incidents?" AI understands the intent and finds relevant content. **Synonym matching.** AI understands that "deployment," "release," and "ship" are related. You don't need to guess which term the author used. **Context awareness.** AI considers the surrounding context, not just isolated words. "Python" in a programming context is different from "Python" in a snake context. **Cross-page synthesis.** AI can combine information from multiple pages to answer complex questions that span multiple documents. ## How to Use AI-Powered Confluence Search: Step-by-Step[​](#how-to-use-ai-powered-confluence-search-step-by-step "Direct link to How to Use AI-Powered Confluence Search: Step-by-Step") ### 1. Enable Atlassian Intelligence Search Features[​](#1-enable-atlassian-intelligence-search-features "Direct link to 1. Enable Atlassian Intelligence Search Features") **For Confluence Cloud:** 1. Go to **Site Administration > Products > Atlassian Intelligence** 2. Enable **Semantic search** 3. Configure indexing: * **All spaces** — index everything * **Specific spaces** — index only selected spaces * **Exclude spaces** — skip certain spaces 4. Wait for initial indexing (varies by content size) **For Confluence Server/Data Center:** 1. Go to **Administration > General Configuration > Atlassian Intelligence** 2. Enable semantic search 3. Configure the search index: * Set index update frequency * Choose content to include/exclude * Configure embedding model ### 2. Use Natural Language Queries[​](#2-use-natural-language-queries "Direct link to 2. Use Natural Language Queries") AI search understands questions, not just keywords: **Keyword search (old way):** ``` deployment process production rollback ``` **Natural language search (AI way):** ``` How do we deploy to production and rollback if something goes wrong? ``` **Example natural language queries:** | Query Type | Example | | --------------- | ------------------------------------------------------- | | How-to | "How do I set up a new Confluence space?" | | Policy | "What is our remote work policy?" | | Troubleshooting | "Why does the build fail with error code 503?" | | Comparison | "What's the difference between staging and production?" | | Process | "What are the steps for onboarding a new engineer?" | **Tips for better queries:** * Be specific: "How do I deploy to production?" not "deploy" * Ask questions: "What is...?" "How do I...?" "Why does...?" * Include context: "for the mobile app" or "in the EU region" * Use complete sentences: AI understands natural language ### 3. Refine Search with AI Filters and Facets[​](#3-refine-search-with-ai-filters-and-facets "Direct link to 3. Refine Search with AI Filters and Facets") AI search provides intelligent filtering: **Filter by content type:** * Pages only * Blog posts only * Attachments only * Comments only **Filter by metadata:** * Space: "Show results from Engineering space only" * Author: "Pages written by @john" * Date: "Updated in the last 30 days" * Labels: "Pages tagged with 'production'" **AI-suggested filters:** When you search, AI may suggest related filters: * "Did you mean to filter by space: Engineering?" * "Most results are from the last 6 months — filter by date?" * "This topic has a dedicated FAQ page — view it?" **Example workflow:** ``` Query: "How do we handle database migrations?" AI results: 15 pages found Suggested filters: - Filter by space: Engineering (12 results) - Filter by date: Last year (10 results) - Filter by labels: database, migration (8 results) After filtering: 8 highly relevant results ``` ### 4. Save and Share Effective Search Queries[​](#4-save-and-share-effective-search-queries "Direct link to 4. Save and Share Effective Search Queries") **Creating saved searches:** 1. Run your search query 2. Click **Save search** (bookmark icon) 3. Name the search descriptively 4. Choose visibility: * **Private** — only you can see it * **Shared** — team members can access it **Useful saved searches to create:** | Search Name | Query | Use Case | | ------------------- | ------------------------------------------- | ----------------------------- | | My recent edits | "pages edited by me in last 7 days" | Track your contributions | | Production issues | "production incident OR outage OR rollback" | Quick access to critical docs | | New hire onboarding | "onboarding OR getting started OR new hire" | Help new team members | | API documentation | "API endpoint OR REST OR integration" | Developer reference | | Policy updates | "policy update OR change OR revision" | Compliance tracking | **Sharing saved searches:** 1. Go to **Search > Saved Searches** 2. Select the search to share 3. Click **Share** 4. Add team members or groups 5. They see it in their saved searches ### 5. Improve Content Discoverability with Metadata[​](#5-improve-content-discoverability-with-metadata "Direct link to 5. Improve Content Discoverability with Metadata") AI search works better with well-structured content: **Add labels to every page:** * Topic labels: `api`, `database`, `deployment`, `security` * Type labels: `how-to`, `policy`, `troubleshooting`, `reference` * Audience labels: `developer`, `manager`, `new-hire` * Status labels: `draft`, `approved`, `outdated` **Use page properties for metadata:** ``` --- title: Deployment Process author: Engineering Team last-reviewed: 2026-07-01 status: approved audience: developers --- ``` **Consistent heading structure:** * Use H1 for page title (one per page) * Use H2 for main sections * Use H3 for subsections * Include an introduction paragraph **Content best practices for search:** * Write clear, descriptive titles * Include a summary paragraph at the top * Use lists and tables for structured data * Link to related pages * Keep content up to date ## FAQ[​](#faq "Direct link to FAQ") ### How does AI search differ from regular Confluence search?[​](#how-does-ai-search-differ-from-regular-confluence-search "Direct link to How does AI search differ from regular Confluence search?") Regular search matches keywords. AI search understands intent, synonyms, and context. It can find relevant content even when the exact words don't match, using semantic understanding. ### Do I need Atlassian Intelligence for AI search?[​](#do-i-need-atlassian-intelligence-for-ai-search "Direct link to Do I need Atlassian Intelligence for AI search?") Atlassian Intelligence provides native AI search in Confluence. Third-party apps like Guru and Slab also offer AI-powered search for Confluence content. ### Can AI search across multiple Confluence spaces?[​](#can-ai-search-across-multiple-confluence-spaces "Direct link to Can AI search across multiple Confluence spaces?") Yes. AI search can query across all spaces you have access to, or be limited to specific spaces. It respects Confluence permissions so users only see content they can access. ### How do I improve AI search results?[​](#how-do-i-improve-ai-search-results "Direct link to How do I improve AI search results?") Add clear titles, use consistent headings, include labels and tags, and keep content up to date. Well-structured content produces better search results. ### Can AI search find content in comments and attachments?[​](#can-ai-search-find-content-in-comments-and-attachments "Direct link to Can AI search find content in comments and attachments?") Depending on the search tool, AI can index and search page comments, file attachments, and embedded content. Check your search tool's configuration for indexing options. ## Related guides[​](#related-guides "Direct link to Related guides") * [How to Organize Your Confluence Space for Easy Navigation](/blog/faq-confluence-dark-mode-apps.md) * [RAG with Confluence: Build an AI Knowledge Base](/blog/rag-with-confluence-build-ai-knowledge-base.md) * [Confluence Page Templates: How to Create and Use Them](/blog/advanced-code-blocks-confluence.md) * [How to Use ChatGPT in Confluence for Better Documentation](/blog/how-to-use-chatgpt-in-confluence.md) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [ai](/blog/tags/ai.md) * [search](/blog/tags/search.md) * [how-to](/blog/tags/how-to.md) * [productivity](/blog/tags/productivity.md) --- ### 2026[​](#2026 "Direct link to 2026") * [April 9](/blog/use-excalidraw-in-confluence-whiteboard-diagrams.md) [ - ](/blog/use-excalidraw-in-confluence-whiteboard-diagrams.md) [Excalidraw for Confluence — Which Whiteboard and Drawing App Fits Your Team?](/blog/use-excalidraw-in-confluence-whiteboard-diagrams.md) * [April 12](/blog/create-mermaid-diagrams-in-confluence.md) [ - ](/blog/create-mermaid-diagrams-in-confluence.md) [Mermaid App Roundup for Confluence — Mermaid Plus vs Stratus vs weweave](/blog/create-mermaid-diagrams-in-confluence.md) * [April 18](/blog/jira-issue-templates-comparison.md) [ - ](/blog/jira-issue-templates-comparison.md) [Issue Templates for Jira — Templating.app & Top Apps Compared](/blog/jira-issue-templates-comparison.md) * [April 18](/blog/jira-diagram-apps-comparison.md) [ - ](/blog/jira-diagram-apps-comparison.md) [Best Diagram App for Jira — 2026 Comparison with Mermaid & Excalidraw](/blog/jira-diagram-apps-comparison.md) * [April 18](/blog/google-fonts-confluence-custom-typography.md) [ - ](/blog/google-fonts-confluence-custom-typography.md) [Google Fonts for Confluence — Which Custom Typography App Fits Your Team?](/blog/google-fonts-confluence-custom-typography.md) * [April 18](/blog/faq-questions-confluence-comparison.md) [ - ](/blog/faq-questions-confluence-comparison.md) [Modern FAQ vs Modern Questions for Confluence — Feature Comparison](/blog/faq-questions-confluence-comparison.md) * [April 18](/blog/confluence-qr-code-comparison.md) [ - ](/blog/confluence-qr-code-comparison.md) [QR Code for Confluence — Which QR App Should Your Team Use?](/blog/confluence-qr-code-comparison.md) * [April 18](/blog/confluence-numbered-headings-comparison.md) [ - ](/blog/confluence-numbered-headings-comparison.md) [Best Numbered Headings App for Confluence — 2026 Comparison](/blog/confluence-numbered-headings-comparison.md) * [April 18](/blog/confluence-markdown-editor-comparison.md) [ - ](/blog/confluence-markdown-editor-comparison.md) [Enhanced Markdown vs Other Confluence Markdown Apps — Feature Matrix](/blog/confluence-markdown-editor-comparison.md) * [April 18](/blog/confluence-import-export-comparison.md) [ - ](/blog/confluence-import-export-comparison.md) [Best Confluence Import/Export Apps Compared — 2026 Guide](/blog/confluence-import-export-comparison.md) * [April 18](/blog/code-blocks-confluence-monaco-editor.md) [ - ](/blog/code-blocks-confluence-monaco-editor.md) [Confluence Code Block Themes — Dark Mode, Monaco Editor & 85+ Languages](/blog/code-blocks-confluence-monaco-editor.md) * [April 21](/blog/faq-using-plugins-security.md) [ - ](/blog/faq-using-plugins-security.md) [Are Confluence & Jira Plugins Safe? Marketplace App Security Guide](/blog/faq-using-plugins-security.md) * [April 21](/blog/faq-mermaid-troubleshooting.md) [ - ](/blog/faq-mermaid-troubleshooting.md) [Mermaid in Confluence Not Rendering? Fixes & FAQ](/blog/faq-mermaid-troubleshooting.md) * [April 21](/blog/faq-jira-attachments-permissions.md) [ - ](/blog/faq-jira-attachments-permissions.md) [Jira Attachment Permissions FAQ: Download, Access & Troubleshoot](/blog/faq-jira-attachments-permissions.md) * [April 21](/blog/faq-google-fonts-performance.md) [ - ](/blog/faq-google-fonts-performance.md) [Google Fonts for Confluence: Performance Impact & FAQ](/blog/faq-google-fonts-performance.md) * [April 21](/blog/faq-exporting-jira-issues.md) [ - ](/blog/faq-exporting-jira-issues.md) [Export Jira Issues to CSV/Excel: Common Problems & FAQ](/blog/faq-exporting-jira-issues.md) * [April 21](/blog/faq-excalidraw-best-practices.md) [ - ](/blog/faq-excalidraw-best-practices.md) [Excalidraw for Confluence & Jira: FAQ, Tips & Best Practices](/blog/faq-excalidraw-best-practices.md) * [April 21](/blog/faq-confluence-markdown-vs-wysiwyg.md) [ - ](/blog/faq-confluence-markdown-vs-wysiwyg.md) [Markdown vs WYSIWYG in Confluence — When to Pick Which](/blog/faq-confluence-markdown-vs-wysiwyg.md) * [April 21](/blog/faq-code-blocks-performance.md) [ - ](/blog/faq-code-blocks-performance.md) [Modern Code Blocks Performance & Large Snippet FAQ](/blog/faq-code-blocks-performance.md) * [April 21](/blog/faq-bulk-operations-jira.md) [ - ](/blog/faq-bulk-operations-jira.md) [Jira Bulk Operations FAQ: Exports, Edits & Downloads](/blog/faq-bulk-operations-jira.md) * [April 21](/blog/export-jira-issues-to-excel.md) [ - ](/blog/export-jira-issues-to-excel.md) [Export Jira Issues to Excel or CSV: Complete Guide (2026)](/blog/export-jira-issues-to-excel.md) * [April 21](/blog/excalidraw-whiteboards-jira.md) [ - ](/blog/excalidraw-whiteboards-jira.md) [How to Add Excalidraw Whiteboards to Jira Issues (Setup Guide)](/blog/excalidraw-whiteboards-jira.md) * [April 21](/blog/create-mermaid-diagrams-confluence.md) [ - ](/blog/create-mermaid-diagrams-confluence.md) [Create Mermaid diagrams in Confluence: a step-by-step guide](/blog/create-mermaid-diagrams-confluence.md) * [April 21](/blog/configure-google-fonts-confluence.md) [ - ](/blog/configure-google-fonts-confluence.md) [How to Configure Google Fonts in Confluence (Step-by-Step)](/blog/configure-google-fonts-confluence.md) * [April 21](/blog/bulk-download-jira-attachments.md) [ - ](/blog/bulk-download-jira-attachments.md) [How to Bulk Download All Jira Attachments (Step-by-Step Guide)](/blog/bulk-download-jira-attachments.md) * [April 21](/blog/advanced-code-blocks-confluence.md) [ - ](/blog/advanced-code-blocks-confluence.md) [Advanced Modern Code Blocks Features — Performance Tuning & Tips](/blog/advanced-code-blocks-confluence.md) * [April 24](/blog/jira-issue-templates-best-practices.md) [ - ](/blog/jira-issue-templates-best-practices.md) [Jira issue templates: best practices for consistent ticket creation](/blog/jira-issue-templates-best-practices.md) * [April 24](/blog/embed-json-confluence.md) [ - ](/blog/embed-json-confluence.md) [How to Display & Format JSON in Confluence (Code Blocks + Viewer)](/blog/embed-json-confluence.md) * [April 24](/blog/create-flowcharts-confluence.md) [ - ](/blog/create-flowcharts-confluence.md) [Flowchart Syntax Reference for Confluence — Mermaid, DOT & Canvas](/blog/create-flowcharts-confluence.md) * [April 24](/blog/confluence-diagram-tools-comparison.md) [ - ](/blog/confluence-diagram-tools-comparison.md) [Best Diagram Tool for Confluence — Mermaid vs Excalidraw vs Graphviz](/blog/confluence-diagram-tools-comparison.md) * [May 2](/blog/jira-attachment-management-comparison.md) [ - ](/blog/jira-attachment-management-comparison.md) [Jira Attachment Management Apps Compared: Bulk Downloader vs Attachment Reviewer](/blog/jira-attachment-management-comparison.md) * [May 2](/blog/how-to-use-qr-codes-confluence.md) [ - ](/blog/how-to-use-qr-codes-confluence.md) [How to Use QR Codes in Confluence: Complete Guide](/blog/how-to-use-qr-codes-confluence.md) * [May 2](/blog/how-to-use-numbered-headings-confluence.md) [ - ](/blog/how-to-use-numbered-headings-confluence.md) [How to Add Numbered Headings in Confluence (Auto-Number H1-H6)](/blog/how-to-use-numbered-headings-confluence.md) * [May 2](/blog/how-to-migrate-confluence-content.md) [ - ](/blog/how-to-migrate-confluence-content.md) [How to Migrate Confluence Content — Server-to-Cloud, Space Moves & Format Conversion](/blog/how-to-migrate-confluence-content.md) * [May 2](/blog/how-to-create-wireframes-confluence.md) [ - ](/blog/how-to-create-wireframes-confluence.md) [How to Create Wireframes and UI Mockups in Confluence with Excalidraw Plus](/blog/how-to-create-wireframes-confluence.md) * [May 2](/blog/how-to-create-state-diagrams-confluence.md) [ - ](/blog/how-to-create-state-diagrams-confluence.md) [Create State Diagrams in Confluence — Mermaid Syntax & Examples](/blog/how-to-create-state-diagrams-confluence.md) * [May 2](/blog/how-to-create-sequence-diagrams-confluence.md) [ - ](/blog/how-to-create-sequence-diagrams-confluence.md) [How to Create Sequence Diagrams in Confluence (Mermaid Examples)](/blog/how-to-create-sequence-diagrams-confluence.md) * [May 2](/blog/how-to-create-pie-charts-confluence.md) [ - ](/blog/how-to-create-pie-charts-confluence.md) [Create Pie Charts in Confluence — Free with Mermaid Syntax](/blog/how-to-create-pie-charts-confluence.md) * [May 2](/blog/how-to-create-mindmaps-confluence.md) [ - ](/blog/how-to-create-mindmaps-confluence.md) [Create Mind Maps in Confluence — Free with Mermaid Plus](/blog/how-to-create-mindmaps-confluence.md) * [May 2](/blog/how-to-create-mermaid-diagrams-jira.md) [ - ](/blog/how-to-create-mermaid-diagrams-jira.md) [Create Mermaid Diagrams on Jira Issues — Flowcharts, Sequence & More](/blog/how-to-create-mermaid-diagrams-jira.md) * [May 2](/blog/how-to-create-math-animations-confluence.md) [ - ](/blog/how-to-create-math-animations-confluence.md) [How to Create Math and Technical Animations in Confluence Using Manim](/blog/how-to-create-math-animations-confluence.md) * [May 2](/blog/how-to-create-jira-issue-templates.md) [ - ](/blog/how-to-create-jira-issue-templates.md) [Create Jira Issue Templates — Import from GitHub, Markdown & Rich Text](/blog/how-to-create-jira-issue-templates.md) * [May 2](/blog/how-to-create-gantt-charts-confluence.md) [ - ](/blog/how-to-create-gantt-charts-confluence.md) [How to Create Gantt Charts in Confluence — Mermaid Examples](/blog/how-to-create-gantt-charts-confluence.md) * [May 2](/blog/how-to-create-er-diagrams-confluence.md) [ - ](/blog/how-to-create-er-diagrams-confluence.md) [ER Diagrams in Confluence: How to Add, Create, and Render Database Schemas](/blog/how-to-create-er-diagrams-confluence.md) * [May 2](/blog/how-to-create-class-diagrams-confluence.md) [ - ](/blog/how-to-create-class-diagrams-confluence.md) [Create UML Class Diagrams in Confluence — Free with Mermaid](/blog/how-to-create-class-diagrams-confluence.md) * [May 2](/blog/how-to-create-architecture-diagrams-confluence.md) [ - ](/blog/how-to-create-architecture-diagrams-confluence.md) [How to Create Architecture Diagrams in Confluence (3 Methods with Examples)](/blog/how-to-create-architecture-diagrams-confluence.md) * [May 2](/blog/how-to-build-faq-sections-confluence.md) [ - ](/blog/how-to-build-faq-sections-confluence.md) [Modern FAQ Themes & Reordering — Accordion vs Centered](/blog/how-to-build-faq-sections-confluence.md) * [May 2](/blog/how-to-add-svg-illustrations-confluence.md) [ - ](/blog/how-to-add-svg-illustrations-confluence.md) [How to Add SVG Illustrations to Confluence Pages](/blog/how-to-add-svg-illustrations-confluence.md) * [May 2](/blog/how-to-add-custom-fonts-confluence.md) [ - ](/blog/how-to-add-custom-fonts-confluence.md) [How to Change Fonts in Confluence (Google Fonts, Custom Typography & More)](/blog/how-to-add-custom-fonts-confluence.md) * [May 2](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md) [ - ](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md) [Documenting Microservice Architectures in Confluence with Mermaid](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md) * [May 2](/blog/faq-mermaid-diagram-types-confluence.md) [ - ](/blog/faq-mermaid-diagram-types-confluence.md) [All 30 Mermaid Diagram Types in Confluence: Complete Reference](/blog/faq-mermaid-diagram-types-confluence.md) * [May 2](/blog/faq-jira-issue-templates-automation.md) [ - ](/blog/faq-jira-issue-templates-automation.md) [Jira Issue Templates FAQ: Auto-Apply, Variables & Automation](/blog/faq-jira-issue-templates-automation.md) * [May 2](/blog/faq-jira-announcement-banner-customization.md) [ - ](/blog/faq-jira-announcement-banner-customization.md) [Customize Jira Announcement Banner — Rich Text, Scheduling & Targeting](/blog/faq-jira-announcement-banner-customization.md) * [May 2](/blog/faq-graphviz-charts-confluence.md) [ - ](/blog/faq-graphviz-charts-confluence.md) [Confluence Graphviz Diagrams: DOT Language FAQ & Examples](/blog/faq-graphviz-charts-confluence.md) * [May 2](/blog/faq-google-fonts-confluence-alternatives.md) [ - ](/blog/faq-google-fonts-confluence-alternatives.md) [Confluence Custom Fonts FAQ: Change Fonts, Setup & Alternatives](/blog/faq-google-fonts-confluence-alternatives.md) * [May 2](/blog/faq-excalidraw-vs-drawio-confluence.md) [ - ](/blog/faq-excalidraw-vs-drawio-confluence.md) [Running Design Whiteboarding Sessions in Confluence — Why We Picked Excalidraw over draw.io](/blog/faq-excalidraw-vs-drawio-confluence.md) * [May 2](/blog/faq-epub-reader-confluence.md) [ - ](/blog/faq-epub-reader-confluence.md) [FAQ: EPUB Reader for Confluence — Everything You Need to Know](/blog/faq-epub-reader-confluence.md) * [May 2](/blog/faq-confluence-widget-carousel.md) [ - ](/blog/faq-confluence-widget-carousel.md) [FAQ: Widget Carousel for Confluence — Image Sliders, Banners & Dashboards](/blog/faq-confluence-widget-carousel.md) * [May 2](/blog/faq-confluence-whiteboard-apps.md) [ - ](/blog/faq-confluence-whiteboard-apps.md) [Confluence Whiteboard Apps FAQ: Excalidraw, draw.io & Built-in Compared](/blog/faq-confluence-whiteboard-apps.md) * [May 2](/blog/faq-confluence-page-navigation-apps.md) [ - ](/blog/faq-confluence-page-navigation-apps.md) [Confluence Page Navigation FAQ: TOC, Numbered Headings & Structure](/blog/faq-confluence-page-navigation-apps.md) * [May 2](/blog/faq-confluence-mermaid-sequence-diagram.md) [ - ](/blog/faq-confluence-mermaid-sequence-diagram.md) [Mermaid Sequence Diagrams in Confluence: FAQ & Examples](/blog/faq-confluence-mermaid-sequence-diagram.md) * [May 2](/blog/faq-confluence-markdown-editor.md) [ - ](/blog/faq-confluence-markdown-editor.md) [How to Write Markdown in Confluence — Syntax, Tables & Code Blocks](/blog/faq-confluence-markdown-editor.md) * [May 2](/blog/faq-confluence-dark-mode-apps.md) [ - ](/blog/faq-confluence-dark-mode-apps.md) [Confluence Dark Mode Apps FAQ: Themes, Fonts & Code Blocks](/blog/faq-confluence-dark-mode-apps.md) * [May 2](/blog/confluence-source-editor-comparison.md) [ - ](/blog/confluence-source-editor-comparison.md) [Confluence Source Editor Compared — Free vs Pro](/blog/confluence-source-editor-comparison.md) * [May 2](/blog/confluence-font-apps-comparison.md) [ - ](/blog/confluence-font-apps-comparison.md) [Confluence Font Apps Compared: Google Fonts vs Custom Fonts Pro](/blog/confluence-font-apps-comparison.md) * [May 6](/blog/how-to-write-markdown-in-confluence.md) [ - ](/blog/how-to-write-markdown-in-confluence.md) [Enhanced Markdown Setup Tutorial — Insert Macro, Modes & Publish](/blog/how-to-write-markdown-in-confluence.md) * [May 6](/blog/does-confluence-support-mermaid.md) [ - ](/blog/does-confluence-support-mermaid.md) [Does Confluence Support Mermaid? Setup Guide & Diagram Types](/blog/does-confluence-support-mermaid.md) * [May 6](/blog/confluence-markdown-tables.md) [ - ](/blog/confluence-markdown-tables.md) [Markdown Tables in Confluence — Syntax Reference & Alignment](/blog/confluence-markdown-tables.md) * [May 6](/blog/confluence-drawing-diagramming-tools.md) [ - ](/blog/confluence-drawing-diagramming-tools.md) [Drawing vs Diagramming in Confluence — Canvas vs Text vs Graph](/blog/confluence-drawing-diagramming-tools.md) * [May 6](/blog/confluence-code-editor-syntax-highlighting.md) [ - ](/blog/confluence-code-editor-syntax-highlighting.md) [Dark Mode for Confluence Code Blocks — Setup Walkthrough](/blog/confluence-code-editor-syntax-highlighting.md) * [May 10](/blog/markdown-to-confluence-converter.md) [ - ](/blog/markdown-to-confluence-converter.md) [Import Markdown into Confluence — 3 Methods Compared (2026)](/blog/markdown-to-confluence-converter.md) * [May 10](/blog/confluence-questions-answers-template.md) [ - ](/blog/confluence-questions-answers-template.md) [Confluence FAQ Macro & Q\&A Template: Add FAQ Sections to Pages](/blog/confluence-questions-answers-template.md) * [May 10](/blog/confluence-json-schema-viewer.md) [ - ](/blog/confluence-json-schema-viewer.md) [JSON Formatting & Display in Confluence: Code Blocks vs Structure Viewer](/blog/confluence-json-schema-viewer.md) * [May 10](/blog/confluence-free-diagram-plugin.md) [ - ](/blog/confluence-free-diagram-plugin.md) [Free Diagram Apps for Confluence — Excalidraw & Free-Tier Limits](/blog/confluence-free-diagram-plugin.md) * [May 10](/blog/confluence-default-font-change-font.md) [ - ](/blog/confluence-default-font-change-font.md) [Can You Change the Font in Confluence? (Default Stack & Custom Font Options)](/blog/confluence-default-font-change-font.md) * [May 10](/blog/best-confluence-apps-developers.md) [ - ](/blog/best-confluence-apps-developers.md) [Best Confluence Apps & Plugins in 2026 — Developer Tools Compared](/blog/best-confluence-apps-developers.md) * [May 23](/blog/how-to-set-up-announcement-banners-confluence-jira.md) [ - ](/blog/how-to-set-up-announcement-banners-confluence-jira.md) [How to Set Up Announcement Banners in Confluence and Jira](/blog/how-to-set-up-announcement-banners-confluence-jira.md) * [May 23](/blog/how-to-create-faq-pages-confluence.md) [ - ](/blog/how-to-create-faq-pages-confluence.md) [Manual Toggles vs Modern FAQ for Confluence — 3 Methods Compared](/blog/how-to-create-faq-pages-confluence.md) * [July 23](/blog/write-markdown-confluence-mermaid-latex-code.md) [ - ](/blog/write-markdown-confluence-mermaid-latex-code.md) [Write Markdown in Confluence With Mermaid, LaTeX & Code — One Editor, Live Preview](/blog/write-markdown-confluence-mermaid-latex-code.md) * [July 23](/blog/whiteboarding-architecture-sessions-jira-confluence.md) [ - ](/blog/whiteboarding-architecture-sessions-jira-confluence.md) [Whiteboarding Architecture Sessions in Jira & Confluence](/blog/whiteboarding-architecture-sessions-jira-confluence.md) * [July 23](/blog/set-up-announcement-banners-jira.md) [ - ](/blog/set-up-announcement-banners-jira.md) [How to Set Up Announcement Banners in Jira (Rich Text, Scheduling & Targeting)](/blog/set-up-announcement-banners-jira.md) * [July 23](/blog/mermaid-diagrams-jira-sprint-workflows.md) [ - ](/blog/mermaid-diagrams-jira-sprint-workflows.md) [Mermaid Diagrams for Jira Sprint Workflows — Which Diagrams Actually Help the Standup](/blog/mermaid-diagrams-jira-sprint-workflows.md) * [July 23](/blog/edit-confluence-storage-format-source-editor.md) [ - ](/blog/edit-confluence-storage-format-source-editor.md) [How to Edit the Confluence Storage Format (And When You'd Need To)](/blog/edit-confluence-storage-format-source-editor.md) * [July 23](/blog/display-json-xml-code-in-confluence.md) [ - ](/blog/display-json-xml-code-in-confluence.md) [How to Display JSON, XML, YAML & Code in Confluence (With Syntax Highlighting)](/blog/display-json-xml-code-in-confluence.md) * [July 23](/blog/create-jira-issues-from-templates.md) [ - ](/blog/create-jira-issues-from-templates.md) [How to Create Jira Issues from Templates (3 Methods, With Examples)](/blog/create-jira-issues-from-templates.md) * [July 23](/blog/auto-number-headings-confluence.md) [ - ](/blog/auto-number-headings-confluence.md) [How to Auto-Number Headings in Confluence (H1–H6, With Live Preview)](/blog/auto-number-headings-confluence.md) * [July 29](/blog/plan-jira-sprints-that-actually-work.md) [ - ](/blog/plan-jira-sprints-that-actually-work.md) [How to Plan Jira Sprints That Actually Work (Step-by-Step Guide)](/blog/plan-jira-sprints-that-actually-work.md) * [July 29](/blog/jira-workflow-automation-guide.md) [ - ](/blog/jira-workflow-automation-guide.md) [Jira Workflow Automation: How to Automate Repetitive Tasks and Save Hours](/blog/jira-workflow-automation-guide.md) * [July 29](/blog/jira-sprint-retrospectives-that-drive-change.md) [ - ](/blog/jira-sprint-retrospectives-that-drive-change.md) [How to Run Jira Sprint Retrospectives That Drive Real Change](/blog/jira-sprint-retrospectives-that-drive-change.md) * [July 29](/blog/jira-permissions-explained-project-security-setup.md) [ - ](/blog/jira-permissions-explained-project-security-setup.md) [Jira Permissions Explained: How to Set Up Project Security Without Breaking Workflows](/blog/jira-permissions-explained-project-security-setup.md) * [July 29](/blog/jira-jql-cheat-sheet-common-queries.md) [ - ](/blog/jira-jql-cheat-sheet-common-queries.md) [Jira JQL Cheat Sheet: 20 Queries Every Team Needs](/blog/jira-jql-cheat-sheet-common-queries.md) * [July 29](/blog/jira-dashboard-sprint-tracking-setup.md) [ - ](/blog/jira-dashboard-sprint-tracking-setup.md) [How to Set Up Jira Dashboards for Sprint Tracking and Stakeholder Visibility](/blog/jira-dashboard-sprint-tracking-setup.md) * [July 29](/blog/jira-backlog-grooming-complete-guide.md) [ - ](/blog/jira-backlog-grooming-complete-guide.md) [Jira Backlog Grooming: The Complete Guide to Refining Stories](/blog/jira-backlog-grooming-complete-guide.md) * [July 29](/blog/export-jira-issues-to-excel-csv-reporting.md) [ - ](/blog/export-jira-issues-to-excel-csv-reporting.md) [How to Export Jira Issues to Excel for Stakeholder Reporting](/blog/export-jira-issues-to-excel-csv-reporting.md) * [July 29](/blog/export-jira-audit-logs-compliance.md) [ - ](/blog/export-jira-audit-logs-compliance.md) [How to Export Jira Audit Logs for Compliance and Security Reviews](/blog/export-jira-audit-logs-compliance.md) * [July 29](/blog/create-jira-issue-templates-for-consistent-workflows.md) [ - ](/blog/create-jira-issue-templates-for-consistent-workflows.md) [How to Create Jira Issue Templates for Consistent Team Workflows](/blog/create-jira-issue-templates-for-consistent-workflows.md) * [July 30](/blog/write-better-jira-ticket-descriptions-with-ai.md) [ - ](/blog/write-better-jira-ticket-descriptions-with-ai.md) [How to Write Better Jira Ticket Descriptions with AI](/blog/write-better-jira-ticket-descriptions-with-ai.md) * [July 30](/blog/what-is-atlassian-isolated-cloud.md) [ - ](/blog/what-is-atlassian-isolated-cloud.md) [What Is Atlassian Isolated Cloud? NGPILOT Apps Available (2026)](/blog/what-is-atlassian-isolated-cloud.md) * [July 30](/blog/what-is-atlassian-government-cloud.md) [ - ](/blog/what-is-atlassian-government-cloud.md) [What Is Atlassian Government Cloud (AGC)? NGPILOT Apps Available (2026)](/blog/what-is-atlassian-government-cloud.md) * [July 30](/blog/rag-with-confluence-build-ai-knowledge-base.md) [ - ](/blog/rag-with-confluence-build-ai-knowledge-base.md) [RAG with Confluence: Build an AI Knowledge Base from Your Docs](/blog/rag-with-confluence-build-ai-knowledge-base.md) * [July 30](/blog/jira-workflow-automation-complete-guide-2026.md) [ - ](/blog/jira-workflow-automation-complete-guide-2026.md) [Jira Workflow Automation: Complete Guide (2026)](/blog/jira-workflow-automation-complete-guide-2026.md) * [July 30](/blog/how-to-use-chatgpt-in-confluence.md) [ - ](/blog/how-to-use-chatgpt-in-confluence.md) [How to Use ChatGPT in Confluence: AI-Powered Writing for Better Docs](/blog/how-to-use-chatgpt-in-confluence.md) * [July 30](/blog/graphviz-charts-confluence-comparison.md) [ - ](/blog/graphviz-charts-confluence-comparison.md) [Graphviz Charts in Confluence: draw.io vs Graphviz vs Mermaid](/blog/graphviz-charts-confluence-comparison.md) * [July 30](/blog/confluence-permissions-ultimate-guide-2026.md) [ - ](/blog/confluence-permissions-ultimate-guide-2026.md) [Confluence Permissions: The Ultimate Guide (2026)](/blog/confluence-permissions-ultimate-guide-2026.md) * [July 30](/blog/build-ai-chatbot-confluence-knowledge-base.md) [ - ](/blog/build-ai-chatbot-confluence-knowledge-base.md) [How to Build an AI Chatbot for Confluence Knowledge Base](/blog/build-ai-chatbot-confluence-knowledge-base.md) * [July 30](/blog/ai-powered-confluence-search.md) [ - ](/blog/ai-powered-confluence-search.md) [AI-Powered Confluence Search: Find Anything Fast](/blog/ai-powered-confluence-search.md) * [July 30](/blog/ai-meeting-notes-confluence.md) [ - ](/blog/ai-meeting-notes-confluence.md) [AI Meeting Notes in Confluence: Capture and Share Automatically](/blog/ai-meeting-notes-confluence.md) * [July 30](/blog/ai-for-jira-workflows-automate-triage-assignment.md) [ - ](/blog/ai-for-jira-workflows-automate-triage-assignment.md) [AI for Jira Workflows: Automate Triage, Assignment, and Prioritization](/blog/ai-for-jira-workflows-automate-triage-assignment.md) * [July 30](/blog/ai-for-jira-sprint-planning-velocity-prediction.md) [ - ](/blog/ai-for-jira-sprint-planning-velocity-prediction.md) [How to Use AI for Jira Sprint Planning and Velocity Prediction](/blog/ai-for-jira-sprint-planning-velocity-prediction.md) * [July 30](/blog/ai-for-confluence-documentation-review.md) [ - ](/blog/ai-for-confluence-documentation-review.md) [How to Use AI for Confluence Documentation Review](/blog/ai-for-confluence-documentation-review.md) * [July 30](/blog/ai-code-review-confluence.md) [ - ](/blog/ai-code-review-confluence.md) [AI Code Review in Confluence: Document and Share Code Reviews](/blog/ai-code-review-confluence.md) * [July 31](/blog/build-modern-confluence-pages-hero-articles-qr-forms.md) [ - ](/blog/build-modern-confluence-pages-hero-articles-qr-forms.md) [Build Modern Confluence Pages in 2026: Hero Sections & QR Codes](/blog/build-modern-confluence-pages-hero-articles-qr-forms.md) * [August 2](/blog/what-is-atlassian-rovo.md) [ - ](/blog/what-is-atlassian-rovo.md) [What Is Atlassian Rovo? (And How It Differs from Atlassian Intelligence)](/blog/what-is-atlassian-rovo.md) * [August 2](/blog/mermaid-vs-plantuml-vs-graphviz-confluence.md) [ - ](/blog/mermaid-vs-plantuml-vs-graphviz-confluence.md) [Mermaid vs PlantUML vs Graphviz for Confluence: Which Diagram Tool to Choose](/blog/mermaid-vs-plantuml-vs-graphviz-confluence.md) * [August 2](/blog/marketplace-app-selection-criteria-enterprise.md) [ - ](/blog/marketplace-app-selection-criteria-enterprise.md) [Atlassian Marketplace App Selection Criteria for Enterprise](/blog/marketplace-app-selection-criteria-enterprise.md) * [August 2](/blog/jira-vs-confluence.md) [ - ](/blog/jira-vs-confluence.md) [Jira vs Confluence: What Each Is Actually For (with Examples)](/blog/jira-vs-confluence.md) * [August 2](/blog/how-to-evaluate-atlassian-marketplace-app.md) [ - ](/blog/how-to-evaluate-atlassian-marketplace-app.md) [How to Evaluate an Atlassian Marketplace App: A Security Checklist](/blog/how-to-evaluate-atlassian-marketplace-app.md) * [August 2](/blog/how-to-choose-markdown-editor-confluence.md) [ - ](/blog/how-to-choose-markdown-editor-confluence.md) [How to Choose a Markdown Editor for Confluence](/blog/how-to-choose-markdown-editor-confluence.md) * [August 2](/blog/forge-vs-connect-atlassian-admins-2026.md) [ - ](/blog/forge-vs-connect-atlassian-admins-2026.md) [Forge vs Connect: What Atlassian Admins Need to Know in 2026](/blog/forge-vs-connect-atlassian-admins-2026.md) * [August 5](/blog/block-quote-confluence.md) [ - ](/blog/block-quote-confluence.md) [How to Add a Block Quote in Confluence (3 Methods Compared)](/blog/block-quote-confluence.md) * [August 11](/blog/bold-text-confluence.md) [ - ](/blog/bold-text-confluence.md) [How to Make Text Bold or Strikethrough in Confluence (Ctrl+B, Toolbar & Markdown)](/blog/bold-text-confluence.md) * [August 21](/blog/markdown-ai-era-documentation-format.md) [ - ](/blog/markdown-ai-era-documentation-format.md) [Why Markdown Became the Documentation Format of the AI Era](/blog/markdown-ai-era-documentation-format.md) * [August 21](/blog/confluence-tabs-macro.md) [ - ](/blog/confluence-tabs-macro.md) [Tabs in Confluence: Native Layout Tabs vs Tabs Macros Compared](/blog/confluence-tabs-macro.md) * [August 21](/blog/confluence-expand-macro.md) [ - ](/blog/confluence-expand-macro.md) [Expand Macro for Confluence: Collapsible Sections Compared (Native vs Styled)](/blog/confluence-expand-macro.md) * [September 2](/blog/jira-export-limit.md) [ - ](/blog/jira-export-limit.md) [Jira Export Limit: How to Export More Than 1,000 Issues (2026)](/blog/jira-export-limit.md) * [September 13](/blog/how-to-create-release-timeline-jira.md) [ - ](/blog/how-to-create-release-timeline-jira.md) [How to Build a Release Timeline in Jira — 3 Methods with Copy-Paste Examples](/blog/how-to-create-release-timeline-jira.md) * [September 13](/blog/how-to-create-flowchart-in-jira.md) [ - ](/blog/how-to-create-flowchart-in-jira.md) [How to Create a Flowchart in Jira — 3 Methods with Copy-Paste Examples](/blog/how-to-create-flowchart-in-jira.md) * [September 18](/blog/markdown-mind-map-confluence.md) [ - ](/blog/markdown-mind-map-confluence.md) [From Markdown Notes to a Mind Map in Confluence — No Drawing](/blog/markdown-mind-map-confluence.md) * [September 18](/blog/jira-json-viewer.md) [ - ](/blog/jira-json-viewer.md) [How to View JSON in Jira — Fields, Entity Properties & Pasted Payloads](/blog/jira-json-viewer.md) * [September 18](/blog/jira-checklist.md) [ - ](/blog/jira-checklist.md) [How to Add a Checklist to Jira — and Block Transitions Until Done](/blog/jira-checklist.md) * [September 19](/blog/mermaid-12-confluence-jira.md) [ - ](/blog/mermaid-12-confluence-jira.md) [Mermaid 12 in Confluence & Jira: UML Use Case Diagrams and a New Look](/blog/mermaid-12-confluence-jira.md) * [September 23](/blog/jira-issue-history.md) [ - ](/blog/jira-issue-history.md) [How to See Who Changed What in Jira — Field-Level Issue History](/blog/jira-issue-history.md) * [September 23](/blog/jira-component-hierarchy.md) [ - ](/blog/jira-component-hierarchy.md) [How to Create a Component Hierarchy in Jira](/blog/jira-component-hierarchy.md) * [September 23](/blog/confluence-wiki-markup.md) [ - ](/blog/confluence-wiki-markup.md) [Confluence Wiki Markup: How to View, Edit & Convert It](/blog/confluence-wiki-markup.md) * [September 24](/blog/zenuml-sequence-diagram-confluence.md) [ - ](/blog/zenuml-sequence-diagram-confluence.md) [ZenUML Sequence Diagrams in Confluence: Copy-Paste Guide](/blog/zenuml-sequence-diagram-confluence.md) * [September 24](/blog/uml-use-case-diagram-confluence.md) [ - ](/blog/uml-use-case-diagram-confluence.md) [UML Use Case Diagrams in Confluence (Mermaid, Copy-Paste)](/blog/uml-use-case-diagram-confluence.md) * [September 24](/blog/mermaid-state-diagram-workflow-confluence.md) [ - ](/blog/mermaid-state-diagram-workflow-confluence.md) [Map States & Approval Workflows in Confluence with Mermaid](/blog/mermaid-state-diagram-workflow-confluence.md) * [September 24](/blog/mermaid-roadmap-prioritization-charts-confluence.md) [ - ](/blog/mermaid-roadmap-prioritization-charts-confluence.md) [Roadmap & Prioritization Charts in Confluence with Mermaid](/blog/mermaid-roadmap-prioritization-charts-confluence.md) * [September 24](/blog/mermaid-requirement-diagram-confluence.md) [ - ](/blog/mermaid-requirement-diagram-confluence.md) [Requirements Traceability in Confluence with Mermaid Requirement Diagrams](/blog/mermaid-requirement-diagram-confluence.md) * [September 24](/blog/mermaid-radar-skill-matrix-charts-confluence.md) [ - ](/blog/mermaid-radar-skill-matrix-charts-confluence.md) [Radar & Skill Matrix Charts in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-radar-skill-matrix-charts-confluence.md) * [September 24](/blog/mermaid-process-flow-swimlane-diagram-confluence.md) [ - ](/blog/mermaid-process-flow-swimlane-diagram-confluence.md) [Swimlane Process Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-process-flow-swimlane-diagram-confluence.md) * [September 24](/blog/mermaid-mindmap-hierarchy-diagram-confluence.md) [ - ](/blog/mermaid-mindmap-hierarchy-diagram-confluence.md) [Mind Maps & Hierarchy Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-mindmap-hierarchy-diagram-confluence.md) * [September 24](/blog/mermaid-kanban-board-workflow-confluence.md) [ - ](/blog/mermaid-kanban-board-workflow-confluence.md) [Kanban Board Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-kanban-board-workflow-confluence.md) * [September 24](/blog/mermaid-journey-diagram-customer-confluence.md) [ - ](/blog/mermaid-journey-diagram-customer-confluence.md) [Customer Journey Maps in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-journey-diagram-customer-confluence.md) * [September 24](/blog/mermaid-incident-postmortem-timeline-confluence.md) [ - ](/blog/mermaid-incident-postmortem-timeline-confluence.md) [Build an Incident Postmortem Timeline in Confluence (Mermaid, Copy-Paste)](/blog/mermaid-incident-postmortem-timeline-confluence.md) * [September 24](/blog/mermaid-gitgraph-jira-branch-history.md) [ - ](/blog/mermaid-gitgraph-jira-branch-history.md) [Visualize Git Branches & Releases Inside Jira with Mermaid GitGraph](/blog/mermaid-gitgraph-jira-branch-history.md) * [September 24](/blog/mermaid-fishbone-root-cause-analysis-confluence.md) [ - ](/blog/mermaid-fishbone-root-cause-analysis-confluence.md) [Root Cause Analysis in Confluence with Mermaid Fishbone + 5 Whys](/blog/mermaid-fishbone-root-cause-analysis-confluence.md) * [September 24](/blog/mermaid-er-diagram-database-schema-confluence.md) [ - ](/blog/mermaid-er-diagram-database-schema-confluence.md) [Database Schema Diagrams in Confluence with Mermaid ER (Entity Relationship) — Copy-Paste](/blog/mermaid-er-diagram-database-schema-confluence.md) * [September 24](/blog/mermaid-decision-framework-diagrams-confluence.md) [ - ](/blog/mermaid-decision-framework-diagrams-confluence.md) [Decision Framework Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-decision-framework-diagrams-confluence.md) * [September 24](/blog/mermaid-class-diagram-document-codebase-confluence.md) [ - ](/blog/mermaid-class-diagram-document-codebase-confluence.md) [Document Your Codebase in Confluence with Mermaid Class Diagrams](/blog/mermaid-class-diagram-document-codebase-confluence.md) * [September 24](/blog/mermaid-ci-cd-pipeline-diagram-confluence.md) [ - ](/blog/mermaid-ci-cd-pipeline-diagram-confluence.md) [CI/CD Pipeline Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-ci-cd-pipeline-diagram-confluence.md) * [September 24](/blog/mermaid-charts-dashboard-confluence.md) [ - ](/blog/mermaid-charts-dashboard-confluence.md) [Mermaid Charts for Confluence Dashboards: Pie & XY in One Post](/blog/mermaid-charts-dashboard-confluence.md) * [September 24](/blog/mermaid-c4-system-architecture-confluence.md) [ - ](/blog/mermaid-c4-system-architecture-confluence.md) [System Architecture Diagrams in Confluence with Mermaid C4](/blog/mermaid-c4-system-architecture-confluence.md) * [September 24](/blog/mermaid-api-sequence-diagram-confluence.md) [ - ](/blog/mermaid-api-sequence-diagram-confluence.md) [API Sequence Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-api-sequence-diagram-confluence.md) * [September 24](/blog/markdown-meeting-notes-confluence.md) [ - ](/blog/markdown-meeting-notes-confluence.md) [Meeting Notes in Confluence with Markdown (Copy-Paste Template)](/blog/markdown-meeting-notes-confluence.md) * [September 24](/blog/markdown-math-equations-confluence.md) [ - ](/blog/markdown-math-equations-confluence.md) [Math Equations in Confluence: LaTeX & KaTeX via Markdown](/blog/markdown-math-equations-confluence.md) * [September 24](/blog/markdown-code-block-confluence.md) [ - ](/blog/markdown-code-block-confluence.md) [Markdown Code Blocks in Confluence — 190+ Languages](/blog/markdown-code-block-confluence.md) * [September 24](/blog/import-markdown-into-confluence.md) [ - ](/blog/import-markdown-into-confluence.md) [Import Markdown into Confluence: Paste, GitHub, .md Files](/blog/import-markdown-into-confluence.md) * [September 28](/blog/paste-mermaid-diagrams-into-confluence.md) [ - ](/blog/paste-mermaid-diagrams-into-confluence.md) [Paste Mermaid Diagrams into Confluence — Now on Mermaid 12](/blog/paste-mermaid-diagrams-into-confluence.md) * [September 28](/blog/mermaid-vs-drawio-confluence.md) [ - ](/blog/mermaid-vs-drawio-confluence.md) [draw.io vs Mermaid in Confluence: Which Fits Your Docs?](/blog/mermaid-vs-drawio-confluence.md) * [October 1](/blog/confluence-monospace.md) [ - ](/blog/confluence-monospace.md) [Monospace in Confluence: How to Format Inline Code (Shortcuts & Markdown)](/blog/confluence-monospace.md) * [October 4](/blog/confluence-pagination.md) [ - ](/blog/confluence-pagination.md) [Confluence Pagination: How to Paginate Pages and Tables (3 Methods)](/blog/confluence-pagination.md) * [October 7](/blog/mermaid-ai-agent-confluence.md) [ - ](/blog/mermaid-ai-agent-confluence.md) [Mermaid AI Agent for Confluence: Create, Update & Convert Diagrams by Chat](/blog/mermaid-ai-agent-confluence.md) * [October 10](/blog/excalidraw-ai-agent-confluence.md) [ - ](/blog/excalidraw-ai-agent-confluence.md) [Excalidraw AI Agent for Confluence: Whiteboards You Can Talk To](/blog/excalidraw-ai-agent-confluence.md) --- # Authors * [NGPilot](https://ngpilot.com) --- # How to Auto-Number Headings in Confluence (H1–H6, With Live Preview) July 23, 2026 · 6 min read [NGPilot](https://ngpilot.com) Who should read this * **Technical writers** building structured documentation in Confluence * **Compliance teams** who need formal numbered sections (1.1, 1.2, 1.2.1) * **Anyone** tired of manually typing and re-numbering headings when content moves What you'll learn 1. Why Confluence doesn't number headings natively (and why manual numbering breaks) 2. How to auto-number H1-H6 with 5 styles (Decimal, Roman, Alphabetic, …) 3. Choosing heading levels and hierarchical indentation 4. Maintaining numbering when you add, remove, or reorder sections The scenario every documentation team hits: you're writing a policy doc or technical spec in Confluence, and it needs numbered sections — `1. Introduction`, `1.1 Overview`, `1.2 Getting Started`, `2. Configuration`. So you type the numbers manually into each heading. Then product changes the structure: a section moves up, a new one gets inserted in the middle, and now every number below the change is wrong. You spend twenty minutes renumbering by hand, miss one, and the doc ships with `1.2` followed by `1.4`. Confluence has no native heading-numbering feature. Headings are just styled text — there's no automatic `1.1` / `1.2` scheme. [**Modern Numbered Headings for Confluence**](https://marketplace.atlassian.com/apps/2096741841/modern-numbered-headings-for-confluence) fixes this by generating numbered headings automatically from your H1-H6 structure, with a live preview and five numbering styles. When you reorder sections, the numbers update. This guide walks through setting it up. ## Why manual heading numbering breaks[​](#why-manual-heading-numbering-breaks "Direct link to Why manual heading numbering breaks") Manual numbering fails for one reason: it's disconnected from the document structure. When you type "1.2" into a heading, Confluence treats it as plain text. It has no idea that: * This heading is the second child of section 1 * Inserting a new heading before it should bump it to 1.3 * Deleting the parent section should remove the number entirely So every structural change — adding a section, reordering, merging — requires a manual renumber pass. On a 30-section document, that's a fragile, error-prone chore. The fix is to derive the numbers from the actual heading hierarchy, which is exactly what an auto-numbering tool does. ## Step-by-step: auto-number Confluence headings[​](#step-by-step-auto-number-confluence-headings "Direct link to Step-by-step: auto-number Confluence headings") ### 1. Install Modern Numbered Headings for Confluence[​](#1-install-modern-numbered-headings-for-confluence "Direct link to 1. Install Modern Numbered Headings for Confluence") Install [Modern Numbered Headings for Confluence](https://marketplace.atlassian.com/apps/2096741841/modern-numbered-headings-for-confluence) from the Atlassian Marketplace. It's free for up to 10 users. After installation, no setup is needed — the app works immediately. ### 2. Open a page with headings[​](#2-open-a-page-with-headings "Direct link to 2. Open a page with headings") Navigate to any Confluence page that contains headings (H1 through H6). Look for the numbered-headings icon (📋) in the page byline, just under the page title. Click it to open the configuration modal. If you don't see the icon, make sure the page actually has headings — the app only activates on pages with heading structure. ### 3. Pick a numbering style and heading levels[​](#3-pick-a-numbering-style-and-heading-levels "Direct link to 3. Pick a numbering style and heading levels") The configuration modal gives you two main choices: **Numbering style** — five professional formats, each suited to different document types: | Style | Format | Best for | | ------------------------- | ------------------ | ------------------------------------ | | **Decimal** (default) | `1. → 1.1 → 1.2` | Technical documentation, general use | | **Roman numerals** | `I. → I.I → I.II` | Formal documents, academic papers | | **Alphabetic** | `A. → A.A → A.B` | Structured lists, procedures | | **Legal** | `1. → 1.1 → 1.1.1` | Legal documents, compliance specs | | **Numbered with restart** | restarts per H1 | Long docs with independent chapters | **Heading levels** — choose which levels (H1-H6) to include in the numbering. Most documents number H1 through H3 and leave H4-H6 unnumbered. Use the checkboxes to select any combination; only headings present on the page get processed. ### 4. Configure indentation and preview[​](#4-configure-indentation-and-preview "Direct link to 4. Configure indentation and preview") Two display options shape the final result: * **Hierarchical indentation** — when enabled, child headings indent visually to show their place in the hierarchy (1.1 sits slightly right of 1). This makes the document structure scannable. Disable it for a flat, compact look. * **Live preview** — the modal shows exactly how the numbered headings will appear before you apply them. Use this to verify the style and levels are right. ### 5. Apply and maintain[​](#5-apply-and-maintain "Direct link to 5. Apply and maintain") Click **Insert** to apply the numbering. The page reloads with numbered headings. To navigate, click any numbered heading entry to scroll to that section. **When the structure changes** (you add, remove, or reorder sections), simply reopen the app icon and re-apply — the numbers regenerate from the new hierarchy. No manual renumbering. To remove numbering entirely, open the modal and select **Remove TOC**. ## When to use numbered headings vs. a table of contents[​](#when-to-use-numbered-headings-vs-a-table-of-contents "Direct link to When to use numbered headings vs. a table of contents") Numbered headings and a table of contents (TOC) solve related but different problems: | You want to… | Use | | ------------------------------------------------------- | ------------------------------------------ | | Make sections referenceable ("see section 1.2.3") | **Numbered headings** | | Give readers a clickable navigation overview at the top | **Table of contents** | | Meet a compliance spec that requires numbered sections | **Numbered headings** | | Help readers jump around a long page | **Both** (numbered headings + a TOC macro) | Many formal documents use both: numbered headings for the referenceable structure, and a TOC at the top for navigation. Modern Numbered Headings focuses on the numbering; pair it with Confluence's native TOC macro for the navigation overview. ## FAQ[​](#faq "Direct link to FAQ") ### Does Confluence number headings automatically?[​](#does-confluence-number-headings-automatically "Direct link to Does Confluence number headings automatically?") No. Confluence has no native heading-numbering feature. Headings are styled text with no automatic 1.1 / 1.2 scheme. To auto-number headings (so they update when you reorder sections), you need a Marketplace app like Modern Numbered Headings for Confluence. ### Can I number headings in Confluence without a plugin?[​](#can-i-number-headings-in-confluence-without-a-plugin "Direct link to Can I number headings in Confluence without a plugin?") You can type numbers manually into headings ("1.2 Overview"), but this is plain text — it doesn't update when you add, remove, or reorder sections, so you must renumber by hand after every structural change. Automatic numbering (derived from the H1-H6 hierarchy) requires an app. ### What heading levels can I number?[​](#what-heading-levels-can-i-number "Direct link to What heading levels can I number?") With Modern Numbered Headings, you can number any combination of H1 through H6. Most documents number H1-H3 and leave finer levels unnumbered, but you have full control via checkboxes in the configuration modal. ### What numbering styles are supported?[​](#what-numbering-styles-are-supported "Direct link to What numbering styles are supported?") Five: Decimal (1.1, 1.2), Roman numerals (I.I, I.II), Alphabetic (A.A, A.B), Legal style (1.1.1), and a restart-per-H1 style for long documents with independent chapters. ### Is Modern Numbered Headings for Confluence free?[​](#is-modern-numbered-headings-for-confluence-free "Direct link to Is Modern Numbered Headings for Confluence free?") Yes — Modern Numbered Headings is free for up to 10 users. Beyond 10 users, standard Atlassian Marketplace licensing applies. ## Related guides[​](#related-guides "Direct link to Related guides") Try Modern Numbered Headings for Confluence Auto-number H1-H6 headings in 5 styles (Decimal, Roman, Alphabetic, Legal) with live preview — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/2096741841/modern-numbered-headings-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-numbered-headings-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [numbered-headings](/blog/tags/numbered-headings.md) * [table-of-contents](/blog/tags/table-of-contents.md) * [how-to](/blog/tags/how-to.md) * [documentation](/blog/tags/documentation.md) --- # Best Confluence Apps & Plugins in 2026 — Developer Tools Compared May 10, 2026 · 7 min read [NGPilot](https://ngpilot.com) Developer teams use Confluence differently than marketing or HR. You document APIs, share architecture diagrams, write runbooks, and collaborate on code reviews. The default Confluence editor works, but it wasn't built for technical documentation. This guide covers the best Confluence apps for developers in 2026, organized by use case. We built several of these apps at NGPILOT, so we'll be transparent about where our apps fit and where competitors offer better solutions. ## Quick Summary: Best Confluence Apps by Category[​](#quick-summary-best-confluence-apps-by-category "Direct link to Quick Summary: Best Confluence Apps by Category") | Category | Best App | Why | Alternative | | ---------------- | -------------------------------- | -------------------------------------------- | ------------------------------- | | Code Blocks | Modern Code Blocks | Monaco editor, dark mode sync, 85+ languages | Better Code Macro (free, basic) | | Diagrams | Excalidraw & Mermaid | Whiteboard + code-based diagrams in one app | draw\.io, Gliffy | | Markdown | Enhanced Markdown for Confluence | Live preview, WYSIWYG editing | Native paste (limited) | | Math/Equations | Manim for Confluence | Python-based animations, LaTeX support | Native limited support | | Fonts/Typography | Google Fonts for Confluence | 1,942+ fonts, live preview | Custom Fonts Pro | | FAQ Sections | Modern FAQ | Customizable FAQ sections | Native expand macro | | Page Building | Content Formatting Macros | 23 macros: hero, tabs, cards, pricing | — | ## 1. Code Blocks & Syntax Highlighting[​](#1-code-blocks--syntax-highlighting "Direct link to 1. Code Blocks & Syntax Highlighting") Developers need more than basic code formatting. You want syntax highlighting for obscure languages, dark mode that actually works, line numbers for code reviews, and an editing experience that feels like VS Code. ### Best: Modern Code Blocks for Confluence[​](#best-modern-code-blocks-for-confluence "Direct link to Best: Modern Code Blocks for Confluence") **Why it wins:** Built on Monaco Editor (the same engine that powers VS Code), giving you autocomplete, find/replace, multi-cursor editing, and keyboard shortcuts inside Confluence. **Key features:** * 85+ languages with accurate syntax highlighting * Auto dark/light theme sync — code blocks match Confluence theme automatically * Line numbers (absolute, relative, or off) * Minimap navigation for long files * JetBrains Mono font with ligatures * Copy to clipboard button * Free for up to 10 users [Install Modern Code Blocks →](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence) ### Alternative: Better Code Macro (Free)[​](#alternative-better-code-macro-free "Direct link to Alternative: Better Code Macro (Free)") Atlassian Labs offers Better Code Macro for free. It adds basic improvements over the native code block but lacks the editor experience, dark mode sync, and active maintenance of newer apps. Good enough for simple use cases. ## 2. Diagrams & Whiteboards[​](#2-diagrams--whiteboards "Direct link to 2. Diagrams & Whiteboards") Architecture diagrams, flowcharts, sequence diagrams, and wireframes are essential for engineering documentation. Confluence has native whiteboard now, but it doesn't support code-based diagrams like Mermaid or PlantUML. ### Best: Excalidraw & Mermaid Diagrams for Confluence[​](#best-excalidraw--mermaid-diagrams-for-confluence "Direct link to Best: Excalidraw & Mermaid Diagrams for Confluence") **Why it wins:** Combines two approaches in one app — a visual whiteboard (Excalidraw) for freehand sketches and Mermaid for code-based diagrams. Both render in the same macro, so you can mix approaches on one page. **Key features:** * Excalidraw whiteboard with hand-drawn aesthetic * Mermaid support for flowcharts, sequence, Gantt, class diagrams * Live preview for both modes * One app covers visual and code-based diagramming * Free for up to 10 users [Install Excalidraw & Mermaid →](https://marketplace.atlassian.com/apps/1237659/excalidraw-mermaid-diagrams-for-confluence) On a zero budget? The [free diagram plugin options for Confluence](/blog/confluence-free-diagram-plugin.md) cover the no-cost paths, free tiers included. ### Alternative: draw\.io[​](#alternative-drawio "Direct link to Alternative: draw.io") The long-established incumbent — its publisher cites 80k+ installs across all draw\.io products on the Atlassian Marketplace. Feature-rich with extensive shape libraries, but heavier and more complex than Excalidraw. Good for formal diagrams, overkill for quick sketches. Deciding between the two? We wrote a full [Excalidraw vs draw.io comparison](/blog/faq-excalidraw-vs-drawio-confluence.md). ## 3. Markdown Editing[​](#3-markdown-editing "Direct link to 3. Markdown Editing") Confluence Cloud can paste Markdown and auto-convert it. But you can't edit in Markdown after pasting — it converts to rich text. If your team prefers writing in Markdown, you need a dedicated app. ### Best: Enhanced Markdown for Confluence[​](#best-enhanced-markdown-for-confluence "Direct link to Best: Enhanced Markdown for Confluence") **Why it wins:** WYSIWYG editor with live Markdown preview. You see formatted output as you type, then publish to Confluence. Full Markdown syntax support including tables, code blocks, and images. **Key features:** * Split-pane editor: write Markdown, see preview * Full CommonMark and GFM support * Export to .md files * Dark mode compatible [Install Enhanced Markdown →](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence) ### Free option: Native paste[​](#free-option-native-paste "Direct link to Free option: Native paste") Confluence Cloud converts pasted Markdown automatically. Use this if you only need to paste once and don't need to edit later. ## 4. Math Equations & Animations[​](#4-math-equations--animations "Direct link to 4. Math Equations & Animations") Technical documentation often includes formulas, equations, and mathematical visualizations. Confluence has basic LaTeX support, but it's limited. ### Best: Manim for Confluence[​](#best-manim-for-confluence "Direct link to Best: Manim for Confluence") **Why it wins:** Built on the Manim animation engine (created by 3Blue1Brown), this app renders math animations directly in Confluence pages. Write Python code, get beautiful mathematical visualizations. **Key features:** * Python-based math animations * LaTeX equation rendering * Educational content creation * Scientific documentation support [Install Manim for Confluence →](https://marketplace.atlassian.com/apps/1384425933/manim-for-confluence) ## 5. Custom Fonts & Typography[​](#5-custom-fonts--typography "Direct link to 5. Custom Fonts & Typography") Developer docs don't always need custom fonts, but if you're building client-facing documentation, API references, or branded knowledge bases, typography matters. ### Best: Google Fonts for Confluence[​](#best-google-fonts-for-confluence "Direct link to Best: Google Fonts for Confluence") **Why it wins:** Access to 1,942+ Google Fonts directly in the Confluence editor. Live preview before publishing. No file uploads or hosting required. **Key features:** * 1,942+ font families from Google Fonts CDN * Macro-based insertion: type `/google fonts` * Live preview with size, color, alignment controls * Dark mode compatible * Cloud Fortified [Install Google Fonts →](https://marketplace.atlassian.com/apps/1236413/google-fonts-for-confluence) ## 6. Beyond Developer Tools: Apps Every Confluence Team Needs[​](#6-beyond-developer-tools-apps-every-confluence-team-needs "Direct link to 6. Beyond Developer Tools: Apps Every Confluence Team Needs") Developer docs don't live in a vacuum. The same Confluence instance hosts FAQs, onboarding guides, intranet pages, and team homepages — and these categories fill gaps the default editor leaves open. ### FAQ & accordion sections: Modern FAQ for Confluence[​](#faq--accordion-sections-modern-faq-for-confluence "Direct link to FAQ & accordion sections: Modern FAQ for Confluence") Builds customizable FAQ sections directly in the editor — the structured Q\&A pattern the native editor lacks. Useful for support spaces, onboarding hubs, and internal help centers. [Read the Modern FAQ docs →](/docs/Modern-FAQ-for-Confluence/usage.md) ### Numbered headings & TOC: Modern Numbered Headings for Confluence[​](#numbered-headings--toc-modern-numbered-headings-for-confluence "Direct link to Numbered headings & TOC: Modern Numbered Headings for Confluence") Auto-generates numbered headings and a table of contents, so long procedure docs and runbooks stay navigable without manual numbering. [Read the Numbered Headings docs →](/docs/Modern-Numbered-Headings-for-Confluence/user-docs.md) ### Page building & content formatting: Content Formatting Macros & Page Builder[​](#page-building--content-formatting-content-formatting-macros--page-builder "Direct link to Page building & content formatting: Content Formatting Macros & Page Builder") A toolkit of 23 macros — hero sections, pricing tables, tabs, cards, and templates — for turning plain Confluence pages into marketing-grade portals and intranets. [Read the Page Builder docs →](/docs/Content-Formatting-Macros-Page-Builder-for-Confluence/user-docs.md) ### Content migration & backup: Modern Importer Exporter[​](#content-migration--backup-modern-importer-exporter "Direct link to Content migration & backup: Modern Importer Exporter") Covers enterprise content migration and backup — bulk operations that Confluence's native per-page export doesn't handle. [Read the Importer Exporter docs →](/docs/Modern-Importer-Exporter-for-Confluence/user-docs.md) ## Honorable Mentions[​](#honorable-mentions "Direct link to Honorable Mentions") ### Graphviz Charts for Confluence[​](#graphviz-charts-for-confluence "Direct link to Graphviz Charts for Confluence") For teams using DOT/Graphviz syntax for graph visualization. Renders directed and undirected graphs directly from code. [Install Graphviz Charts →](https://marketplace.atlassian.com/apps/1237027/graphviz-charts-for-confluence) ### QR Code for Confluence[​](#qr-code-for-confluence "Direct link to QR Code for Confluence") Generate QR codes directly on Confluence pages. Useful for print documentation, physical signage linking to wiki pages, and mobile access. [Install QR Code →](https://marketplace.atlassian.com/apps/1236735/qr-code-for-confluence) ## How to Choose[​](#how-to-choose "Direct link to How to Choose") When evaluating Confluence apps for your developer team, consider: 1. **Active maintenance.** Check the "Last Updated" date on Marketplace. Apps not updated in 2+ years may break with Confluence updates. 2. **Free tier.** Most apps offer free trials or free tiers for small teams. Test with your actual content before committing. 3. **Cloud Fortified.** This Atlassian badge indicates higher security, reliability, and support standards. 4. **Editor experience.** Developer tools should feel like developer tools — not clunky workarounds. ## Related Posts[​](#related-posts "Direct link to Related Posts") * [Code Block Comparison: Monaco Editor vs Native vs Better Code Macro](/blog/code-blocks-confluence-monaco-editor.md) * [Confluence Diagram Tools: Excalidraw vs draw.io vs Gliffy](/blog/confluence-diagram-tools-comparison.md) * [Markdown Editors for Confluence Compared](/blog/confluence-markdown-editor-comparison.md) *** **Questions or feedback?** Reach out at — we build several of these apps and are always looking to improve. ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [comparison](/blog/tags/comparison.md) * [confluence](/blog/tags/confluence.md) * [developer-tools](/blog/tags/developer-tools.md) * [best-apps](/blog/tags/best-apps.md) * [code-blocks](/blog/tags/code-blocks.md) * [diagrams](/blog/tags/diagrams.md) * [markdown](/blog/tags/markdown.md) --- # How to Add a Block Quote in Confluence (3 Methods Compared) August 5, 2026 · 5 min read [NGPilot](https://ngpilot.com) A **block quote** sets a passage apart from the surrounding text — usually indented with a left border — to indicate that the words are quoted from another source. Confluence does not have a dedicated "quote block" button, but there are three reliable ways to create one. This guide walks through each and helps you pick the right one. What you'll learn 1. The native method (toolbar Indent) — no app required 2. The Markdown method (`>` syntax) — fastest for keyboard users 3. The panel macro method (Content Formatting) — most styling control 4. How to nest quotes and add attribution ## Quick comparison[​](#quick-comparison "Direct link to Quick comparison") | Method | App needed | Styling | Best for | | ------------- | ------------------------------------------------------------------------------------------- | ---------------------- | ---------------------------------- | | Native Indent | None | Indent + left border | Quick, one-off quotes | | Markdown `>` | [Enhanced Markdown](/apps/enhanced-markdown-for-confluence.md) | Styled blockquote | Developers, keyboard-first writing | | Panel macro | [Content Formatting Macros](/apps/content-formatting-macros-page-builder-for-confluence.md) | Colors, borders, icons | Branded docs, emphasis | ## Method 1: Native Confluence indent (no app)[​](#method-1-native-confluence-indent-no-app "Direct link to Method 1: Native Confluence indent (no app)") This is the default way to create a quote-like block with the built-in editor. ### Steps[​](#steps "Direct link to Steps") 1. Open your Confluence page and click **Edit**. 2. Type or paste the text you want to quote. 3. Select the paragraph. 4. Click the **Indent** button in the toolbar (it looks like `→|`), or press **Tab**. The text shifts right and Confluence draws a light left border, giving it a quote appearance. ### Pros and cons[​](#pros-and-cons "Direct link to Pros and cons") * ✅ No installation required — works in every Confluence Cloud instance * ✅ Fast for a single short quote * ❌ Limited styling — no color, custom border, or background control * ❌ No built-in attribution field; you add the source manually * ❌ Pressing Tab once indents only one level ## Method 2: Markdown blockquote syntax (Enhanced Markdown)[​](#method-2-markdown-blockquote-syntax-enhanced-markdown "Direct link to Method 2: Markdown blockquote syntax (Enhanced Markdown)") If you write in Markdown — or paste content from GitHub, a README, or another wiki — the blockquote is a single character. ### Steps[​](#steps-1 "Direct link to Steps") 1. Install [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence) (free for up to 10 users). 2. On your page, type `/enhanced markdown` and insert the macro. 3. Type a greater-than sign and a space before the line: ``` > This is a block quote. It renders indented with a left border. >> This is a nested block quote — two greater-than signs. > This is a quote with attribution. > — Jane Doe, *Engineering Handbook* ``` 4. Click **Publish**. The blockquotes render as styled quote blocks. ### Why developers prefer this[​](#why-developers-prefer-this "Direct link to Why developers prefer this") * **Keyboard-first** — no mouse or toolbar needed * **Portable** — the same `>` syntax works in GitHub, Slack, and every Markdown renderer * **Nesting is trivial** — `>>` for level two, `>>>` for level three * **Mixes with other Markdown** — bold, italic, and links work inside the quote See the full syntax reference in the [Confluence Markdown editor FAQ](/blog/faq-confluence-markdown-editor.md). ## Method 3: Panel macro (Content Formatting Macros)[​](#method-3-panel-macro-content-formatting-macros "Direct link to Method 3: Panel macro (Content Formatting Macros)") For styled quotes — colored backgrounds, custom borders, icons — the [Content Formatting Macros](/apps/content-formatting-macros-page-builder-for-confluence.md) app includes a Panel macro: a callout container that holds any rich text, so your quote gets full styling control. ### Steps[​](#steps-2 "Direct link to Steps") 1. Install [Content Formatting Macros — Page Builder for Confluence](https://marketplace.atlassian.com/apps/4209461142/content-formatting-macros-page-builder-for-confluence). 2. On your page, type `/panel` and select the macro. 3. Paste your quoted text into the macro body. 4. Configure the macro: pick a **style** (Info, Warning, Success, or Custom), set the **border position** and colors, and optionally add a **title** or **icon**. 5. Add the attribution (e.g. `— Jane Doe, Engineering Handbook`) as a final styled line inside the panel. 6. **Publish** the page. ### Best for[​](#best-for "Direct link to Best for") * Customer testimonials with branded styling * Important warnings or pull quotes in documentation * Pages where the quote needs to stand out visually ## How to nest blockquotes[​](#how-to-nest-blockquotes "Direct link to How to nest blockquotes") Nesting shows that a quote itself contains a quoted passage. * Markdown * Native editor * Macro ``` > Outer quote begins here. > >> This is the nested inner quote. > > Outer quote continues. ``` Select the inner line and press **Tab** a second time. Each Tab adds one indent level with its own left border. Place a second Panel macro inside the first and give it a different style (e.g. a Custom background) so the nesting stays visible. ## How to add attribution[​](#how-to-add-attribution "Direct link to How to add attribution") A good block quote names its source. The common pattern: ``` > "Simplicity is the soul of efficiency." > — Austin Freeman, *The Complete adventures of Dr. Thorndyke* ``` For customer testimonials, wrap the quote in a [Content Formatting](/apps/content-formatting-macros-page-builder-for-confluence.md) Panel macro and type the attribution as the last line inside the panel — you control its color and styling directly. ## Which method should you use?[​](#which-method-should-you-use "Direct link to Which method should you use?") * **You just need one quick quote and have no apps installed** → Method 1 (native indent). * **You write in Markdown or paste from GitHub/READMEs** → Method 2 ([Enhanced Markdown](/apps/enhanced-markdown-for-confluence.md) `>` syntax). * **You need branded colors, borders, or a testimonial block** → Method 3 ([Content Formatting Panel macro](/apps/content-formatting-macros-page-builder-for-confluence.md)). ## Related resources[​](#related-resources "Direct link to Related resources") * [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence) | [documentation](/apps/enhanced-markdown-for-confluence.md) * [Content Formatting Macros — Page Builder](https://marketplace.atlassian.com/apps/4209461142/content-formatting-macros-page-builder-for-confluence) | [documentation](/apps/content-formatting-macros-page-builder-for-confluence.md) * [Confluence Markdown editor FAQ](/blog/faq-confluence-markdown-editor.md) * [How to write Markdown in Confluence](/blog/how-to-write-markdown-in-confluence.md) ## More formatting guides[​](#more-formatting-guides "Direct link to More formatting guides") * [Make text bold in Confluence](/blog/bold-text-confluence.md) — Ctrl+B, toolbar, and Markdown `**` syntax * [Confluence Markdown tables](/blog/confluence-markdown-tables.md) — Pipe-table syntax and merged cells * [Auto-number Confluence headings](/blog/auto-number-headings-confluence.md) — Automatic section numbering * [Best Confluence apps for developers](/blog/best-confluence-apps-developers.md) — Curated tooling list ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [formatting](/blog/tags/formatting.md) * [blockquote](/blog/tags/blockquote.md) * [enhanced-markdown](/blog/tags/enhanced-markdown.md) * [content-formatting](/blog/tags/content-formatting.md) --- # How to Make Text Bold or Strikethrough in Confluence (Ctrl+B, Toolbar & Markdown) August 11, 2026 · 3 min read [NGPilot](https://ngpilot.com) **Bold text** is one of the most common formatting actions in Confluence — for headings, callouts, and emphasis inside paragraphs. There are two ways to do it: the toolbar button / keyboard shortcut in the standard editor, and Markdown syntax inside [Enhanced Markdown for Confluence](/apps/enhanced-markdown-for-confluence.md). This guide covers both, plus the common "why isn't it working" cases. What you'll learn 1. The standard editor method — B button or Ctrl+B / Cmd+B 2. The Markdown method — `**bold**` syntax 3. Bold vs italic vs strikethrough 4. Fixing bold that renders as literal asterisks ## Method 1: The toolbar button or keyboard shortcut (standard editor)[​](#method-1-the-toolbar-button-or-keyboard-shortcut-standard-editor "Direct link to Method 1: The toolbar button or keyboard shortcut (standard editor)") The quickest way: 1. Select the text you want to bold. 2. Press **Ctrl+B** (Windows/Linux) or **Cmd+B** (Mac), **or** click the **B** button in the editor toolbar. The selection is wrapped in bold immediately. Press Ctrl+B again to remove it. This works everywhere in the standard editor: body text, table cells, and headings. The keyboard shortcut is the fastest option if you're already typing — select the word and hit Ctrl+B as you go. ## Method 2: Markdown `**bold**` syntax (Enhanced Markdown)[​](#method-2-markdown-bold-syntax-enhanced-markdown "Direct link to method-2-markdown-bold-syntax-enhanced-markdown") If your team writes in Markdown (or you're pasting Markdown from elsewhere), bold is written as text wrapped in two asterisks with no spaces: ``` This is **bold** text. This has *italic* and **bold**. ``` When you publish, Enhanced Markdown for Confluence renders `**bold**` as bold. The same applies inside table cells: ``` | **Header** | Plain | |------------|-------| | **Bold** | Value | ``` > GitHub Flavored Markdown is supported, so `__bold__` (double underscore) also works. ## Bold, italic, and strikethrough — the difference[​](#bold-italic-and-strikethrough--the-difference "Direct link to Bold, italic, and strikethrough — the difference") | Style | Markdown | Result | | ------------- | ------------ | ---------- | | Bold | `**text**` | **text** | | Italic | `*text*` | *text* | | Bold+italic | `***text***` | ***text*** | | Strikethrough | `~~text~~` | ~~text~~ | In the standard editor, the toolbar shows **B** for bold, *I* for italic, and S for strikethrough — select text and click the button. ## Fixing "my bold text shows as \*\* asterisks \*\*"[​](#fixing-my-bold-text-shows-as--asterisks- "Direct link to Fixing \"my bold text shows as ** asterisks **\"") The most common issue: you typed `**bold**` manually in the **standard** (rich text) editor. Confluence's rich text editor does not parse Markdown, so it shows the literal asterisk characters. * If you're in the standard editor: select the text and press **Ctrl+B** instead of typing asterisks. * If you want to type Markdown and see it formatted: install [Enhanced Markdown for Confluence](/apps/enhanced-markdown-for-confluence.md) and edit pages in Markdown mode. ## Related guides[​](#related-guides "Direct link to Related guides") * [How to write Markdown in Confluence](/blog/faq-confluence-markdown-editor.md) — headings, lists, links, code * [How to add a block quote in Confluence](/blog/block-quote-confluence.md) — quoted text and callouts * [Monospace in Confluence: inline code shortcuts & Markdown](/blog/confluence-monospace.md) — `code` formatting and the Ctrl+Shift+M shortcut * [Confluence bold and formatting](/docs/Enhanced-Markdown-for-Confluence/usage.md) — the Enhanced Markdown macro's full formatting coverage ## Related guides * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [formatting](/blog/tags/formatting.md) * [markdown](/blog/tags/markdown.md) * [bold](/blog/tags/bold.md) * [enhanced-markdown](/blog/tags/enhanced-markdown.md) * [keyboard-shortcuts](/blog/tags/keyboard-shortcuts.md) --- # How to Build an AI Chatbot for Confluence Knowledge Base July 30, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer Build an AI chatbot that answers questions from your Confluence knowledge base using no-code tools or custom development. Connect Confluence content, train the chatbot, and deploy to Slack or Teams. What you'll learn 1. How to choose the right chatbot platform for your needs 2. how to prepare and export Confluence content for chatbot ingestion 3. How to connect the chatbot to your Confluence data 4. How to train, test, and deploy your Confluence chatbot Teams waste hours searching Confluence for answers that already exist. A chatbot can bridge this gap by providing instant answers from your knowledge base, right where the team works. This guide covers how to build an AI chatbot for Confluence, from no-code solutions to custom development. ## Why Build a Confluence Chatbot[​](#why-build-a-confluence-chatbot "Direct link to Why Build a Confluence Chatbot") **Instant answers.** Team members get answers in seconds instead of searching through pages for 10-15 minutes. **Reduced support burden.** Senior team members answer fewer repetitive questions because the chatbot handles them. **Always available.** The chatbot works 24/7, including weekends and holidays when no one is available to answer questions. **Consistent responses.** Every user gets the same accurate answer, not variations based on who answers. ## How to Build a Confluence Chatbot: Step-by-Step[​](#how-to-build-a-confluence-chatbot-step-by-step "Direct link to How to Build a Confluence Chatbot: Step-by-Step") ### 1. Choose Your Chatbot Platform[​](#1-choose-your-chatbot-platform "Direct link to 1. Choose Your Chatbot Platform") **Option A: No-code platforms** | Platform | Features | Pricing | | ----------- | ---------------------------------- | ------------------------ | | Chatbase | Custom GPT, Confluence integration | $19/month | | Botpress | Visual builder, multi-channel | Free tier available | | Tettra | Confluence-native, AI Q\&A | $99/month | | Custom GPTs | OpenAI's GPT Builder | $20/month (ChatGPT Plus) | **Best for:** Non-technical teams, quick deployment, limited budget **Option B: Marketplace apps** | App | Features | Pricing | | ------------------------- | ------------------------------- | -------------- | | AI Chatbot for Confluence | Native integration, permissions | $10/user/month | | Guru | Knowledge base + chatbot | $15/user/month | | Slab | AI search + chat | $66/month | **Best for:** Teams wanting native Confluence integration **Option C: Custom development** * **Stack:** LangChain + OpenAI + Vector DB * **Pros:** Full control, custom models, unlimited customization * **Cons:** Requires development effort, hosting, maintenance * **Best for:** Teams with specific requirements or sensitive data ### 2. Prepare Your Confluence Content for Chatbot Ingestion[​](#2-prepare-your-confluence-content-for-chatbot-ingestion "Direct link to 2. Prepare Your Confluence Content for Chatbot Ingestion") **Content cleanup:** * Remove outdated pages * Fix broken links * Add clear titles and headings * Include FAQ sections * Add metadata (labels, tags) **Content export methods:** **Method 1: Confluence REST API** ``` import requests # Get all pages from a space def get_confluence_pages(space_key, base_url, auth): url = f"{base_url}/rest/api/content" params = { "spaceKey": space_key, "expand": "body.storage", "limit": 100 } response = requests.get(url, params=params, auth=auth) return response.json()["results"] # Export pages to JSON pages = get_confluence_pages("ENG", "https://your-domain.atlassian.net", ("email", "api_key")) ``` **Method 2: Confluence export** 1. Go to **Space Settings > Content Tools > Export** 2. Select **XML export** 3. Download the export file 4. Parse and clean the XML for chatbot ingestion **Method 3: Third-party tools** * **Confluence Exporter** — scheduled exports to JSON/CSV * **Content Exporter** — custom export with filtering * **API connectors** — Zapier, Make, n8n integrations ### 3. Connect the Chatbot to Your Confluence Data[​](#3-connect-the-chatbot-to-your-confluence-data "Direct link to 3. Connect the Chatbot to Your Confluence Data") **For no-code platforms:** 1. Create a new chatbot project 2. Select **Confluence** as the data source 3. Enter your Confluence URL and API credentials 4. Select which spaces to index 5. Wait for initial indexing **For custom development:** ``` from langchain.document_loaders import ConfluenceLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain.embeddings import OpenAIEmbeddings from langchain.vectorstores import Pinecone # Load from Confluence loader = ConfluenceLoader( url="https://your-domain.atlassian.net", username="email@company.com", api_key="your-api-key" ) docs = loader.load(space_key="ENG") # Split into chunks splitter = RecursiveCharacterTextSplitter( chunk_size=1000, chunk_overlap=200 ) chunks = splitter.split_documents(docs) # Create vector store embeddings = OpenAIEmbeddings() vectorstore = Pinecone.from_documents( chunks, embeddings, index_name="confluence-chatbot" ) ``` ### 4. Train and Test the Chatbot[​](#4-train-and-test-the-chatbot "Direct link to 4. Train and Test the Chatbot") **Testing checklist:** * Test with 20-30 common questions * Verify answers are accurate * Check that sources are cited correctly * Test edge cases (out-of-scope questions) * Verify permission filtering works * Test with different user roles **Example test cases:** | Question | Expected Answer | Status | | --------------------------------------- | ----------------------------- | ---------- | | "How do I deploy to production?" | Step-by-step deployment guide | ✅ | | "What is our vacation policy?" | Policy document summary | ✅ | | "Who do I contact for security issues?" | Security team contact info | ✅ | | "How do I fix the login bug?" | Troubleshooting guide | ⚠️ Partial | | "What's the meaning of life?" | Out-of-scope fallback | ✅ | **Fine-tuning:** 1. Review failed queries in chatbot logs 2. Identify missing content or incorrect answers 3. Add missing Confluence pages to the knowledge base 4. Adjust chunking strategy for better retrieval 5. Retrain the model with corrected examples ### 5. Deploy and Monitor Chatbot Performance[​](#5-deploy-and-monitor-chatbot-performance "Direct link to 5. Deploy and Monitor Chatbot Performance") **Deployment options:** * **Slack bot** — ask questions in Slack channels * **Microsoft Teams** — integrate with Teams channels * **Web widget** — embed on your documentation site * **Confluence integration** — AI assistant within Confluence * **API endpoint** — custom applications **Monitoring metrics:** | Metric | Target | Action if below | | ----------------- | ---------- | ------------------------ | | Answer accuracy | 90%+ | Review failed queries | | Response time | <3 seconds | Optimize vector search | | User satisfaction | 4+ stars | Improve answer quality | | Query volume | Increasing | Promote chatbot adoption | | Failed queries | <5% | Add missing content | **Continuous improvement:** * Review query logs weekly * Identify common questions without good answers * Add missing Confluence pages * Update outdated content * Refine chatbot prompts and responses ## FAQ[​](#faq "Direct link to FAQ") ### Can I build a Confluence chatbot without coding?[​](#can-i-build-a-confluence-chatbot-without-coding "Direct link to Can I build a Confluence chatbot without coding?") Yes. Tools like Chatbase, Botpress, and Tettra provide no-code chatbot builders that can ingest Confluence content and answer questions without writing code. ### How accurate are AI chatbots for Confluence content?[​](#how-accurate-are-ai-chatbots-for-confluence-content "Direct link to How accurate are AI chatbots for Confluence content?") Accuracy depends on content quality and chatbot configuration. Well-structured Confluence pages typically yield 85-95% accuracy. Always test and refine before deploying to your team. ### Can a Confluence chatbot access restricted content?[​](#can-a-confluence-chatbot-access-restricted-content "Direct link to Can a Confluence chatbot access restricted content?") Most enterprise chatbots respect Confluence permissions. They only return content the querying user has access to, ensuring sensitive information stays protected. ### How do I handle chatbot errors and edge cases?[​](#how-do-i-handle-chatbot-errors-and-edge-cases "Direct link to How do I handle chatbot errors and edge cases?") Implement fallback responses for out-of-scope questions, log failed queries for review, and set up alerts for accuracy drops below your threshold. ### Can I integrate a Confluence chatbot with Slack or Teams?[​](#can-i-integrate-a-confluence-chatbot-with-slack-or-teams "Direct link to Can I integrate a Confluence chatbot with Slack or Teams?") Yes. Most chatbot platforms support Slack, Microsoft Teams, and other messaging tools. Users ask questions in chat, and the bot responds with answers from Confluence. ## Related guides[​](#related-guides "Direct link to Related guides") * [RAG with Confluence: Build an AI Knowledge Base](/blog/rag-with-confluence-build-ai-knowledge-base.md) * [AI-Powered Confluence Search: Find Anything Fast](/blog/ai-powered-confluence-search.md) * [How to Use ChatGPT in Confluence for Better Documentation](/blog/how-to-use-chatgpt-in-confluence.md) * [How to Organize Your Confluence Space for Easy Navigation](/blog/faq-confluence-dark-mode-apps.md) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [ai](/blog/tags/ai.md) * [chatbot](/blog/tags/chatbot.md) * [knowledge-base](/blog/tags/knowledge-base.md) * [how-to](/blog/tags/how-to.md) --- # Build Modern Confluence Pages in 2026: Hero Sections & QR Codes July 31, 2026 · 9 min read [NGPilot](https://ngpilot.com) Who should read this * **Confluence admins and space owners** who want their intranet, portal, or knowledge base to look professional * **Marketing and product teams** building landing pages, announcements, and product updates in Confluence * **Anyone** who has ever thought "I know what I want this page to look like — I just can't make Confluence do it" What you'll learn 1. How to make a Confluence page read like Medium (drop caps, clean typography, bilingual mode) 2. How to add a proper hero section with CTAs — something the native editor doesn't have 3. How to style tables without fighting the editor 4. How to add QR codes, collect survey responses, and define glossary terms inline — all without external tools Take a look at your most-visited Confluence page right now. Does it look like it belongs on the modern web — or does it look like internal documentation from 2015? If your answer is the latter, you're not alone. Teams across thousands of Confluence sites tell us the same story: "I know exactly what I want my page to look like. I just can't make Confluence do it." In this guide, we'll show you six concrete ways to level up your Confluence pages — from Medium-style reading layouts to interactive surveys — all without leaving your editor. ![Article macro template selection showing the reading layout presets.](/assets/images/article-macro-6b867e151f1994edea33fa83ed915d2a.png) ## 1. How to Make a Confluence Page Read Like Medium[​](#1-how-to-make-a-confluence-page-read-like-medium "Direct link to 1. How to Make a Confluence Page Read Like Medium") You've seen Medium's clean, distraction-free article layout. Drop caps, beautiful typography, a reading experience that makes people actually want to read. **The problem:** Confluence's native editor gives you headings and paragraphs. That's fine for documentation, but not for long-form content like announcements, product updates, or knowledge base deep-dives. **The fix:** The **Article macro** in [Content Formatting Macros & Page Builder for Confluence](https://marketplace.atlassian.com/apps/4209461142/content-formatting-macros-page-builder-for-confluence) gives you a full reading template system with 6 presets — Medium, Quora, Substack, NYT, GitHub, and Minimal. ![Configuring the Article macro — choosing a reading template.](/assets/images/article-config-30cc2f6bdd08f1a4d54cf0668cfdd32b.gif) Drop the macro on any page, pick your template, and paste your content. You get: * Clean typography with 15 bundled fonts (Merriweather, Inter, PT Serif, Playfair Display, etc.) * Optional drop cap on the first paragraph * Bilingual mode — stack a translation beneath each paragraph for multilingual teams No CSS. No custom styling. Just select a template and write. ## 2. How to Add a Hero Section That Actually Looks Good[​](#2-how-to-add-a-hero-section-that-actually-looks-good "Direct link to 2. How to Add a Hero Section That Actually Looks Good") Every modern website starts with a hero — a full-width header with a title, subtitle, and call-to-action buttons. It's the first thing visitors see, and it sets the tone for the entire page. **The problem:** Confluence's native editor doesn't have a hero block. Teams either paste an image at the top or skip it entirely. Existing formatting apps treat hero sections as an afterthought — most don't have one at all. **The fix:** The **Hero Section macro** gives you a full hero builder with: * Title, subtitle, and up to two CTA buttons * Background color, gradient, or image (with overlay controls) * Min height from 150px to 600px * Left, center, or right alignment ![Configuring the Hero Section — full-width header with CTA buttons.](/assets/images/hero-config-a486227298ef15bd01057b0bb44b8a27.gif) Set it once, and every visitor sees a polished landing page header — no design skills required. ## 3. How to Add a Styled Table Without Wrestling the Editor[​](#3-how-to-add-a-styled-table-without-wrestling-the-editor "Direct link to 3. How to Add a Styled Table Without Wrestling the Editor") Confluence's native table is functional but basic. You can add rows and columns, but styling requires manual work, and the result rarely looks professional. **The problem:** Tables in Confluence default to plain lines and white backgrounds. Adding zebra striping, header colors, or modern styles requires workarounds or external tools. **The fix:** The **Table macro** has 4 built-in style presets — Striped, Bordered, Minimal, and Modern. Drop it in, pick your style, and your data looks presentation-ready immediately. ![Table macro with style presets.](/assets/images/table-config-b367255e356b8422080447893fc31d5b.gif) Key features: * Up to 8 columns and 50 rows * Configurable header background color * Zebra striping for dense data * First-column emphasis option for property/value tables * 4 starter templates (Comparison Matrix, Spec Sheet, Data Table, Schedule) ## 4. How to Add a QR Code — Right on the Page, No External Tools[​](#4-how-to-add-a-qr-code--right-on-the-page-no-external-tools "Direct link to 4. How to Add a QR Code — Right on the Page, No External Tools") Teams frequently ask: "Can I put a QR code on my Confluence page?" The answer used to be: generate one externally, download the image, upload it as an attachment. **The problem:** External QR generators require leaving Confluence. Uploaded images go out of date when you need to change the URL. **The fix:** The **QR Code macro** generates scannable QR codes entirely inside Confluence — no external tools, no image uploads, no stale links. ![QR Code macro on a published page.](/assets/images/qrcode-macro-5dfb13775841fc2dd8f55b2993a65ef7.png) It supports 7 content types: * URL, Text, Email, Phone, SMS, WiFi credentials, vCard contacts * Optional logo overlay in the center * Adjustable size (128–512px), colors, and error correction * Built-in download button ![QR Code with logo overlay.](/assets/images/qrcode-with-logo-6c905a5b0b6893843348e54e220e72d9.gif) ![QR Code configuration — choosing content type and appearance.](/assets/images/qrcode-config-4207329705202cab4c69e68161c01b9a.gif) Add a QR code to an event page for registration, a conference room page for WiFi access, or a team page for contact details. It updates instantly when you change the config. ## 5. How to Collect Feedback Without Adding Another Tool[​](#5-how-to-collect-feedback-without-adding-another-tool "Direct link to 5. How to Collect Feedback Without Adding Another Tool") Internal surveys, event RSVPs, feedback forms — teams build these in Google Forms, Typeform, or SurveyMonkey, then embed or link from Confluence. That means data lives in a separate tool, responses are disconnected from your content, and you're managing yet another subscription. **The problem:** Every external survey tool creates a data silo. Responses live outside Confluence, and there's no easy way to tie feedback back to the page it references. **The fix:** The **Form macro** lets you collect survey responses directly on any Confluence page — stored in Confluence, viewable from a dedicated admin dashboard. ![Form builder configuration — choosing field types.](/assets/images/form-config-35174718755c3fe3b75dcc5486d821b4.gif) It supports 7 field types: * Short text, Long text, Dropdown, Checkboxes, Star rating, Email, Date picker * Submissions are stored server-side in Forge Storage * Space admins can view, export CSV, and delete submissions ![Form submissions dashboard.](/assets/images/form-submissions-9e246b8d47de9bebc3b51ad7103a2643.png) ![Submitting a form on a published page.](/assets/images/form-submission-783dfe4e799755c865debb0267f3a606.gif) Use it for team satisfaction surveys, event RSVPs, contact forms, or feedback collection — all without adding a third-party tool. ## 6. How to Add Terms and Glossary Definitions Inline[​](#6-how-to-add-terms-and-glossary-definitions-inline "Direct link to 6. How to Add Terms and Glossary Definitions Inline") Documentation pages often need to define terms — acronyms, technical terms, industry jargon. The standard approach is a glossary section at the bottom of the page, which forces readers to scroll back and forth. **The problem:** Inline tooltips for terms don't exist in Confluence natively. Teams either define terms in parentheses (cluttering the text) or link to an external glossary page. **The fix:** The **Annotation macro** is an inline macro that renders within your prose — no paragraph break. Hover over the term to reveal its definition in a tooltip. ![Annotation configuration — styling an inline term.](/assets/images/annotation-config-1714a5e6ad5ca2f76754f5faf996a8f2.gif) Features: * 9 visual styles: Plain, Bold, Italic, Underline (solid/dashed), Citation, Highlight, Badge, Strikethrough * 8 color tokens that adapt to light/dark mode * Configurable position, delay, and info icon * 6 presets: Acronym, Definition, Hint, Citation, Highlight, Badge Define an acronym once with Annotation, and readers see the definition on hover — no glossary page required. ## These 6 macros are part of a larger system[​](#these-6-macros-are-part-of-a-larger-system "Direct link to These 6 macros are part of a larger system") Content Formatting Macros & Page Builder for Confluence includes **23 macros total** — 16 in the Standard edition and 7 premium macros — plus a global **Theme Editor** that controls colors, fonts, spacing, and shadows across every macro at once. ![Theme Editor — global colors, fonts, spacing, and shadows.](/assets/images/theme-editor-5ea9091cfc81d377532104abf532def1.png) Five theme presets (Default, Dark, Minimal, Bold, Pastel) let you switch your entire page's look in one click. Here's how it compares to the popular formatting apps on the Marketplace: | Feature | Content Formatting Macros & Page Builder | AURA | Optics | Mosaic | Refined | | -------------------------------- | ---------------------------------------- | ------------- | ------------ | ----------- | ----------- | | Hero Section | ✅ Full hero with CTAs | ✅ Full-width | Banner only | Banner only | Banner only | | Pricing Table | ✅ Multi-tier | Basic | ❌ | ❌ | ❌ | | FAQ with Search | ✅ Search + categories | Expand only | ❌ | ❌ | ❌ | | Countdown Timer | ✅ Animated | ✅ | ✅ | ❌ | ✅ | | Numbered Headings | ✅ (9 presets) | ✅ | ❌ | ✅ | ✅ | | Image Gallery | ✅ (masonry + lightbox) | ❌ | Image Slider | ❌ | ❌ | | **QR Code** | **✅** | ❌ | ❌ | ❌ | ❌ | | **Annotation (inline tooltips)** | **✅** | ❌ | ❌ | ❌ | ❌ | | **Article Mode (bilingual)** | **✅** | ❌ | ❌ | ❌ | ❌ | | **Form / Survey** | **✅** | ❌ | ❌ | ❌ | ❌ | | Card Grid (carousel) | ✅ | Cards only | Cards only | ❌ | ❌ | | Hover Animations | ✅ (5 types) | ❌ | ❌ | ❌ | ❌ | | Global Theme Presets | ✅ (5 presets) | Color Mgmt | Style Guide | ❌ | ❌ | | Auto Dark/Light Mode | ✅ | ✅ (toggle) | ❌ | ❌ | ❌ | | Macro Presets | ✅ (76+ presets) | ✅ | ✅ | ✅ | ❌ | **QR Code, Annotation, Article Mode, and Form/Survey are features no competitor offers at all.** The rest — animations, global theming, dark mode detection, page-builder macros — fill gaps that the 58 user reviews we analyzed consistently asked for. ![Countdown timer configuration.](/assets/images/countdown-config-80c547d8165fbc95d770504d2c1039d0.gif) ![Pricing table configuration.](/assets/images/pricing-table-config-a745415718fed78d8fea38edabd57e77.gif) Every macro opens with a template — 76+ presets across all 23 macros — so you never start from a blank config panel. Live preview updates in real time as you adjust settings. ## FAQ[​](#faq "Direct link to FAQ") ### Can I build a landing page in Confluence?[​](#can-i-build-a-landing-page-in-confluence "Direct link to Can I build a landing page in Confluence?") Yes. With Content Formatting Macros & Page Builder for Confluence you can assemble a full landing page inside Confluence: a Hero Section for the header, an Article macro for long-form content, styled Tables, Card Grids, FAQ sections, countdown timers, QR codes, and a Form for lead capture — plus a global Theme Editor to keep colors and fonts consistent. No HTML or CSS required. ### Do I need to know HTML or CSS to use these macros?[​](#do-i-need-to-know-html-or-css-to-use-these-macros "Direct link to Do I need to know HTML or CSS to use these macros?") No. Every macro is configured through a visual panel with templates and live preview. Colors, fonts, spacing, and shadows are controlled through presets and theme tokens, not code. ### Can I use these macros on existing pages?[​](#can-i-use-these-macros-on-existing-pages "Direct link to Can I use these macros on existing pages?") Yes. Any macro can be inserted into an existing page — edit the page, type `/` and search for the macro name, configure it, and save. The macros coexist with native Confluence content and other apps. ### Do the macros adapt to dark mode?[​](#do-the-macros-adapt-to-dark-mode "Direct link to Do the macros adapt to dark mode?") Yes. The macros use Atlassian Design Tokens, so colors adapt automatically when Confluence switches between light and dark mode. The Theme Editor also ships 5 presets (Default, Dark, Minimal, Bold, Pastel) you can apply page-wide in one click. ## Related guides[​](#related-guides "Direct link to Related guides") * [Confluence QR Code Apps Compared](/blog/confluence-qr-code-comparison.md) * [How to Create FAQ Pages in Confluence](/blog/how-to-create-faq-pages-confluence.md) * [Confluence Markdown Editor Comparison](/blog/confluence-markdown-editor-comparison.md) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [page-builder](/blog/tags/page-builder.md) * [macros](/blog/tags/macros.md) * [how-to](/blog/tags/how-to.md) * [productivity](/blog/tags/productivity.md) --- # How to Bulk Download All Jira Attachments (Step-by-Step Guide) April 21, 2026 · 2 min read [NGPilot](https://ngpilot.com) Collecting attachments from many Jira issues can be tedious. The Simple Bulk Attachment Downloader app automates parallel downloads and packages attachments by issue for easy sharing and archiving. ## When to use it[​](#when-to-use-it "Direct link to When to use it") * Migrating files during releases * Gathering screenshots and logs for QA or support * Archiving project assets before cleanup ## Quick prerequisites[​](#quick-prerequisites "Direct link to Quick prerequisites") * Jira Cloud account with the [Simple Bulk Attachment Downloader](/docs/Simple-Bulk-Attachment-Downloader-for-Jira/user-docs.md) installed * Permission to view attachments in the issues ## Step 1 — Filter the issues[​](#step-1--filter-the-issues "Direct link to Step 1 — Filter the issues") Use Jira issue navigator or a saved filter. Example JQL to find issues with attachments: ``` project = MYPROJECT AND attachments IS NOT EMPTY ``` ## Step 2 — Run the attachment analyzer[​](#step-2--run-the-attachment-analyzer "Direct link to Step 2 — Run the attachment analyzer") Click the **Simple Bulk Attachment Downloader** action. The analyzer reports: * Number of issues * Total attachments * Estimated download size ## Step 3 — Download and organization[​](#step-3--download-and-organization "Direct link to Step 3 — Download and organization") Click **Download X Attachments as ZIP**. Files are organized as `ISSUE-123 - Summary/attachments` inside the ZIP. ### Tips for large sets[​](#tips-for-large-sets "Direct link to Tips for large sets") * Use date ranges (created >= -30d) to split exports * Ensure enough local disk space before large downloads ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") * If downloads stall: try smaller batches, clear browser cache, or use another browser * If permission errors: confirm attachments are visible to your account ## Related apps & resources[​](#related-apps--resources "Direct link to Related apps & resources") * [Simple Bulk Attachment Downloader](/apps/simple-bulk-attachment-downloader-for-jira.md) * [Simple Bulk Issues Excel CSV Export](/apps/simple-bulk-issues-excel-csv-export-for-jira.md) — export issue data alongside attachments * [Attachment Reviewer for Jira](/apps/attachment-reviewer-for-jira.md) — enforce file type and size policies * [Jira attachments & permissions FAQ](/blog/faq-jira-attachments-permissions.md) — troubleshoot permission issues * [Export Jira issues to Excel/CSV](/blog/export-jira-issues-to-excel.md) — step-by-step export guide *** *Suggested featured image: a ZIP file structure screenshot showing attachments organized by issue.* Try Simple Bulk Attachment Downloader for Jira Download all attachments from Jira issues in one click with parallel processing — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/984902822/simple-bulk-attachment-downloader-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=simple-bulk-attachment-downloader-for-jira) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [attachments](/blog/tags/attachments.md) * [bulk](/blog/tags/bulk.md) * [how-to](/blog/tags/how-to.md) --- # Confluence Code Block Themes — Dark Mode, Monaco Editor & 85+ Languages April 18, 2026 · 5 min read [NGPilot](https://ngpilot.com) **Confluence code block themes** let you customize how code appears in your documentation. The built-in code macro offers limited theme support, but third-party apps bring dark mode, syntax highlighting, and VS Code-like editing to Confluence. This guide compares the best **Confluence code block** apps for syntax highlighting, including Modern Code Blocks, Better Code Macro, and Prism Syntax Highlighter. Learn which one fits your team's needs for **Confluence code block themes**, language support, and developer experience. ## The Problem with Confluence Code Block Themes[​](#the-problem-with-confluence-code-block-themes "Direct link to The Problem with Confluence Code Block Themes") Confluence's default code macro is fine for a quick `console.log`. But when your team needs to: * Reference specific lines in code reviews * Display code in both light and dark Confluence themes * Navigate long code blocks with a minimap * Use a proper editor with find/replace and keyboard shortcuts ...the default macro falls short. That's where third-party code block apps come in. ### Native Code Block Theme Limitations[​](#native-code-block-theme-limitations "Direct link to Native Code Block Theme Limitations") The built-in Confluence code block has limited theme support: * **No automatic dark/light switching** — Code blocks don't adapt when users toggle Confluence dark mode * **Limited language support** — Common languages work, but newer or niche languages may not highlight correctly * **No editor experience** — It's a plain textarea, not a code editor with autocomplete or syntax checking * **Fixed appearance** — No control over font size, line numbers, or visual style For developer teams documenting APIs, sharing runbooks, or writing technical guides, these limitations become friction points daily. ## What's Available on the Marketplace[​](#whats-available-on-the-marketplace "Direct link to What's Available on the Marketplace") We looked at every code block and syntax highlighting app currently available for Confluence Cloud. Here's the landscape: | App | Vendor | Installs | Rating | Last Updated | Pricing | | -------------------------------- | ------------------- | -------- | ------------------ | ------------ | ---------------- | | Better Code Macro | Atlassian Labs | 2,823 | 2.5/5 (30 reviews) | Sep 2025 | Free | | Advanced Code Syntax Highlighter | Toshihiro Sato | 133 | 2.3/5 (6 reviews) | Dec 2023 | From $10/yr | | Code Syntax Highlighter | Narva Software Labs | 105 | 3.0/5 (4 reviews) | Apr 2022 | From $80/yr | | Prism Syntax Highlighter | weweave | 98 | 3.9/5 (7 reviews) | Mar 2026 | Free to 10 users | | **Modern Code Blocks** | **NGPILOT** | — | — | **Apr 2026** | Free to 10 users | *Data from Atlassian Marketplace, April 2026.* **Better Code Macro** (by Atlassian Labs) leads in installs but hasn't had a meaningful update since September 2025 and carries a 2.5-star rating — users report issues with theme support and limited features. **Code Syntax Highlighter** claims 300+ languages but was last published in April 2022 — over four years without an update. **Prism Syntax Highlighter** is the most actively maintained competitor, updated in March 2026 with a respectable 3.9-star rating. ## Feature Comparison[​](#feature-comparison "Direct link to Feature Comparison") | Feature | Modern Code Blocks | Better Code Macro | Prism Highlighter | Advanced Code SH | Code SH | | ------------------------- | ------------------ | ----------------- | ----------------- | ---------------- | --------- | | **Editor engine** | Monaco (VS Code) | Basic | Basic | Basic | Basic | | **Languages** | 85+ | Many | 260+ | 220+ | 300+ | | **Dark/light theme sync** | Auto | No | No | No | No | | **Line numbers** | On/Off/Relative | No | Yes | No | No | | **Minimap** | Yes | No | No | No | No | | **Font ligatures** | Yes | No | No | No | No | | **Auto-height** | Yes | No | No | No | No | | **Find & Replace** | Yes | No | No | No | No | | **Word wrap** | Configurable | No | No | No | No | | **Copy to clipboard** | Yes | Yes | Yes | No | No | | **Actively maintained** | Yes (2026) | Limited (2025) | Yes (2026) | No (2023) | No (2022) | ### Where Modern Code Blocks Stands Out[​](#where-modern-code-blocks-stands-out "Direct link to Where Modern Code Blocks Stands Out") **VS Code editing experience** — The Monaco Editor gives you autocomplete, multi-cursor, find/replace, and keyboard shortcuts that developers already know. No other Confluence code block app offers this. **Auto dark/light theme** — Code blocks automatically match the reader's Confluence theme. When a reader switches to dark mode, the code block switches to VS Code Dark. No manual configuration needed. **Code block themes that work** — Modern Code Blocks includes multiple VS Code-compatible themes: | Theme | Best For | | ------------- | -------------------------------------------- | | VS Code Dark | Dark mode Confluence, long coding sessions | | VS Code Light | Light mode Confluence, printed documentation | | High Contrast | Accessibility requirements, low-vision users | The theme syncs automatically with Confluence's appearance settings. No need to configure code blocks per theme — they just work. **Auto-height with scroll** — Blocks expand to fit short snippets and scroll when code is long. No fixed-height boxes with wasted whitespace. **Actively maintained** — Shipped in April 2026 with regular updates planned. ### Where We Could Improve[​](#where-we-could-improve "Direct link to Where We Could Improve") * **Language count** — We support 85+ languages compared to Prism's 260+ and Code Syntax Highlighter's 300+. We're adding more with each release. * **New app** — We launched recently, so we don't have the install base or review history of older apps yet. We're working on earning that trust. * **No GitHub/Bitbucket embedding** — Some apps can embed code directly from Git repositories. This is on our roadmap. ## Why Teams Choose Modern Code Blocks[​](#why-teams-choose-modern-code-blocks "Direct link to Why Teams Choose Modern Code Blocks") * **Familiar editing** — Developers already know VS Code. Monaco gives them the same experience inside Confluence. * **Zero configuration for themes** — code blocks just look right in both light and dark mode. * **Professional rendering** — JetBrains Mono font stack with ligatures, minimap, and line numbers make code blocks feel like a real IDE. * **Fair pricing** — Free for teams up to 10 users. ## Related Posts[​](#related-posts "Direct link to Related Posts") * [Google Fonts for Confluence — Which Custom Typography App Fits Your Team?](/blog/google-fonts-confluence-custom-typography.md) * [Markdown Editor for Confluence — Which App Should You Choose for Writing Docs?](/blog/confluence-markdown-editor-comparison.md) * [Numbered Headings for Confluence — Which Table of Contents App Fits Your Docs?](/blog/confluence-numbered-headings-comparison.md) * [Best Confluence Apps & Plugins in 2026 — Developer Tools Compared](/blog/best-confluence-apps-developers.md) ## Get Started[​](#get-started "Direct link to Get Started") * Install Modern Code Blocks for Confluence from the Atlassian Marketplace * [Read the full documentation](/docs/Modern-Code-Blocks-for-Confluence/user-docs.md) **Ready to improve your Confluence code blocks?** [Try Modern Code Blocks for Confluence with a free trial →](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence?hosting=cloud\&tab=overview) Have questions or feedback? Reach out to us at — we'd love to hear from you. Try Modern Code Blocks for Confluence Monaco editor, 85+ languages (JSON, XML, YAML, SQL), 50+ themes, diff view, and auto dark/light mode — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-code-blocks-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [code-blocks](/blog/tags/code-blocks.md) * [syntax-highlighting](/blog/tags/syntax-highlighting.md) * [confluence](/blog/tags/confluence.md) * [monaco-editor](/blog/tags/monaco-editor.md) * [developer-tools](/blog/tags/developer-tools.md) * [code-block-themes](/blog/tags/code-block-themes.md) * [dark-mode](/blog/tags/dark-mode.md) --- # How to Configure Google Fonts in Confluence (Step-by-Step) April 21, 2026 · 2 min read [NGPilot](https://ngpilot.com) Using custom fonts can dramatically improve readability and branding in Confluence. This guide shows how to use the Google Fonts for Confluence app to apply fonts, configure previews, and balance performance. ## Quick prerequisites[​](#quick-prerequisites "Direct link to Quick prerequisites") * Confluence Cloud site with the [Google Fonts](/docs/Google-Fonts-for-Confluence/usage.md) app installed * Permission to edit pages or space styles ## Step 1 — Choose the right font[​](#step-1--choose-the-right-font "Direct link to Step 1 — Choose the right font") * Consider legibility and weights * Prefer variable fonts for performance ## Step 2 — Apply font to a page[​](#step-2--apply-font-to-a-page "Direct link to Step 2 — Apply font to a page") * Edit page → Insert Google Fonts macro → select font → save ## Step 3 — Use live preview and fallback rules[​](#step-3--use-live-preview-and-fallback-rules "Direct link to Step 3 — Use live preview and fallback rules") * Test in multiple browsers * Add CSS fallbacks for system fonts ## Performance tips[​](#performance-tips "Direct link to Performance tips") * Limit webfont file size by choosing only needed weights * Use font-display: swap to avoid invisible text ## Related apps & resources[​](#related-apps--resources "Direct link to Related apps & resources") * [Google Fonts for Confluence](/apps/google-fonts-for-confluence.md) * [Enhanced Markdown for Confluence](/apps/enhanced-markdown-for-confluence.md) — pair custom fonts with Markdown editing * [Google Fonts performance FAQ](/blog/faq-google-fonts-performance.md) — performance tips and common questions Try Google Fonts for Confluence 1,942+ Google Font families with live preview, custom size/color/alignment — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236413/google-fonts-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=google-fonts-for-confluence) ## Related guides * [Can You Change the Font in Confluence? Custom Options](/blog/confluence-default-font-change-font.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [fonts](/blog/tags/fonts.md) * [google-fonts](/blog/tags/google-fonts.md) * [how-to](/blog/tags/how-to.md) --- # Dark Mode for Confluence Code Blocks — Setup Walkthrough May 6, 2026 · 4 min read [NGPilot](https://ngpilot.com) Confluence's built-in code block macro is limited — it supports roughly 30 languages, has no dark theme, and lacks basic features like copy buttons and collapsible sections. If your team writes documentation with code snippets, you need something better. This guide shows how to add a VS Code-grade code editor to Confluence with syntax highlighting for 85+ languages, automatic dark/light theme detection, and one-click copy buttons. ## The problem with Confluence's native code blocks[​](#the-problem-with-confluences-native-code-blocks "Direct link to The problem with Confluence's native code blocks") Confluence's default code block macro has several limitations: * **Limited language support** — only about 30 languages have syntax highlighting * **No dark theme** — the code block always renders in light mode, even if Confluence is in dark mode * **No copy button** — users must manually select and copy code * **No line numbers** — difficult to reference specific lines in code reviews * **No collapsible blocks** — long code snippets take up entire pages ## Modern Code Blocks for Confluence[​](#modern-code-blocks-for-confluence "Direct link to Modern Code Blocks for Confluence") [Modern Code Blocks for Confluence](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence?hosting=cloud\&tab=overview) replaces the native code block with a Monaco-powered editor — the same engine that powers VS Code. ### Key features[​](#key-features "Direct link to Key features") | Feature | Native Code Block | Modern Code Blocks | | ------------------ | ----------------- | ----------------------------- | | Language support | \~30 languages | 85+ languages | | Dark/light theme | Light only | Auto-detects Confluence theme | | Copy button | No | Yes, on every block | | Collapsible blocks | No | Yes | | Line numbers | No | Yes | | Editor | Basic textarea | Monaco editor | | Font | System font | Customizable monospace | ## How to add syntax highlighting to Confluence code blocks[​](#how-to-add-syntax-highlighting-to-confluence-code-blocks "Direct link to How to add syntax highlighting to Confluence code blocks") ### Step 1: Install Modern Code Blocks[​](#step-1-install-modern-code-blocks "Direct link to Step 1: Install Modern Code Blocks") Go to the [Modern Code Blocks listing on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence?hosting=cloud\&tab=overview) and click **Get it now**. The app installs directly into your Confluence Cloud instance. Modern Code Blocks is free for up to 10 users. Beyond 10 users, standard Atlassian Marketplace licensing applies. ### Step 2: Insert the macro[​](#step-2-insert-the-macro "Direct link to Step 2: Insert the macro") Open any Confluence page in edit mode. Type `/modern code` and select **Modern Code Blocks** from the macro dropdown. ### Step 3: Paste code and select a language[​](#step-3-paste-code-and-select-a-language "Direct link to Step 3: Paste code and select a language") Paste your code into the editor. Choose the programming language from the dropdown — 85+ languages are supported including: * **Web**: JavaScript, TypeScript, HTML, CSS, SCSS, Vue, React JSX * **Backend**: Python, Java, Go, Rust, C#, Ruby, PHP, Kotlin, Scala * **Data**: SQL, GraphQL, JSON, YAML, TOML, XML * **DevOps**: Dockerfile, Terraform, Kubernetes YAML, Bash, PowerShell * **And many more**: Swift, Dart, R, Lua, Haskell, Elixir, and more ### Step 4: Choose a theme[​](#step-4-choose-a-theme "Direct link to Step 4: Choose a theme") Modern Code Blocks auto-detects your Confluence dark/light mode setting and matches it automatically. If your Confluence is in dark mode, code blocks render in dark mode — and vice versa. You can also manually override the theme per block if needed. ### Step 5: Save the page[​](#step-5-save-the-page "Direct link to Step 5: Save the page") Click **Publish** or **Save**. The code block renders with full syntax highlighting, line numbers, and a one-click copy button. ## Supported languages (selection)[​](#supported-languages-selection "Direct link to Supported languages (selection)") Here are some of the most popular languages with full syntax highlighting: ``` Python, JavaScript, TypeScript, Java, Go, Rust, C++, C#, Ruby, PHP, Swift, Kotlin, Scala, R, MATLAB, SQL, GraphQL, HTML, CSS, SCSS, JSON, YAML, TOML, XML, Markdown, Bash, PowerShell, Dockerfile, Terraform, Kubernetes, Vue, React JSX, Angular, Svelte, Dart, Lua, Haskell, Elixir, Clojure, Perl, Erlang, Groovy, Vim Script ``` ## When to use Modern Code Blocks[​](#when-to-use-modern-code-blocks "Direct link to When to use Modern Code Blocks") * **API documentation** — syntax-highlighted endpoints with copy buttons for curl commands * **Runbooks** — collapsible code blocks for long scripts so pages stay readable * **Architecture decision records** — code examples alongside diagrams * **Onboarding guides** — new developers can copy setup scripts in one click * **Code reviews** — line numbers make it easy to reference specific lines ## Alternative: Enhanced Markdown[​](#alternative-enhanced-markdown "Direct link to Alternative: Enhanced Markdown") If you prefer writing code blocks in Markdown syntax, [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?hosting=cloud\&tab=overview) also supports fenced code blocks with syntax highlighting. Write standard Markdown code blocks with triple backticks and language identifiers, and they render with highlighting. Read the comparison: [Confluence Markdown vs WYSIWYG Editor FAQ](/blog/faq-confluence-markdown-vs-wysiwyg.md). ## Related resources[​](#related-resources "Direct link to Related resources") * [Modern Code Blocks — marketplace](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence?hosting=cloud\&tab=overview) | [documentation](/apps/modern-code-blocks-for-confluence.md) * [Code block themes & syntax highlighting guide](/blog/advanced-code-blocks-confluence.md) * [Code blocks performance FAQ](/blog/faq-code-blocks-performance.md) * [Best Confluence apps for developers](/blog/best-confluence-apps-developers.md) * [Confluence Markdown vs WYSIWYG FAQ](/blog/faq-confluence-markdown-vs-wysiwyg.md) ## Related guides * [Code Blocks for Confluence — Monaco Editor & Themes](/blog/code-blocks-confluence-monaco-editor.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [code-blocks](/blog/tags/code-blocks.md) * [syntax-highlighting](/blog/tags/syntax-highlighting.md) * [dark-mode](/blog/tags/dark-mode.md) * [monaco-editor](/blog/tags/monaco-editor.md) * [developers](/blog/tags/developers.md) --- # Can You Change the Font in Confluence? (Default Stack & Custom Font Options) May 10, 2026 · 3 min read [NGPilot](https://ngpilot.com) Confluence uses a system font stack that looks different on every operating system. You can't change the default font globally, and Confluence offers no built-in way to use custom fonts on individual pages. This guide shows what font Confluence uses and how to add custom fonts. ## What font does Confluence use?[​](#what-font-does-confluence-use "Direct link to What font does Confluence use?") Confluence uses the following system font stack: * **macOS**: San Francisco (-apple-system) * **Windows**: Segoe UI * **Android**: Roboto * **Linux**: Liberation Sans or Nimbus Sans This means Confluence pages look slightly different depending on your operating system. There is no setting to change this globally. ## How to change the font in Confluence[​](#how-to-change-the-font-in-confluence "Direct link to How to change the font in Confluence") [Google Fonts for Confluence](https://marketplace.atlassian.com/apps/1236413/google-fonts-for-confluence?hosting=cloud\&tab=overview) adds **1,942+ Google Font families** that you can apply to any text on Confluence pages. ### Step-by-step[​](#step-by-step "Direct link to Step-by-step") 1. Install [Google Fonts for Confluence](https://marketplace.atlassian.com/apps/1236413/google-fonts-for-confluence?hosting=cloud\&tab=overview) from the Marketplace (free for up to 10 users) 2. Open a Confluence page in edit mode 3. Type `/google fonts` in the editor 4. Browse or search the font library (1,942+ families) 5. Select a font and see a live preview 6. Type your text — it renders in the chosen font 7. Save the page ### Popular fonts for Confluence documentation[​](#popular-fonts-for-confluence-documentation "Direct link to Popular fonts for Confluence documentation") | Font | Style | Best For | | ---------------- | ------------------------ | --------------------------- | | Inter | Clean sans-serif | Body text, UI documentation | | JetBrains Mono | Monospace | Code-related content | | Merriweather | Readable serif | Long-form articles | | Roboto Slab | Friendly slab-serif | Headers and titles | | Source Sans Pro | Professional sans-serif | Corporate documentation | | Fira Code | Monospace with ligatures | Developer documentation | | Playfair Display | Elegant serif | Marketing pages | ## Why change the font in Confluence?[​](#why-change-the-font-in-confluence "Direct link to Why change the font in Confluence?") * **Branding** — match Confluence pages to your company's brand fonts * **Readability** — better fonts make long documentation easier to read * **Professionalism** — custom typography makes pages look polished * **Code documentation** — use monospace fonts for technical content ## Confluence font options compared[​](#confluence-font-options-compared "Direct link to Confluence font options compared") | Option | Font Count | Live Preview | Easy Setup | | --------------------------- | ----------------- | ------------ | ------------------- | | Native Confluence | System fonts only | N/A | N/A | | Google Fonts for Confluence | 1,942+ | Yes | 1-click macro | | Custom CSS (admin only) | Any web font | No | Requires CSS access | Google Fonts is the simplest option — no admin access or CSS knowledge needed. ## Related resources[​](#related-resources "Direct link to Related resources") * [Google Fonts for Confluence — marketplace](https://marketplace.atlassian.com/apps/1236413/google-fonts-for-confluence?hosting=cloud\&tab=overview) | [documentation](/apps/google-fonts-for-confluence.md) * [How to add custom fonts to Confluence](/blog/how-to-add-custom-fonts-confluence.md) * [Confluence font apps comparison](/blog/confluence-font-apps-comparison.md) * [Google Fonts performance FAQ](/blog/faq-google-fonts-performance.md) * [Confluence custom fonts FAQ](/blog/faq-google-fonts-confluence-alternatives.md) Try Google Fonts for Confluence 1,942+ Google Font families with live preview, custom size/color/alignment — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236413/google-fonts-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=google-fonts-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [fonts](/blog/tags/fonts.md) * [google-fonts](/blog/tags/google-fonts.md) * [typography](/blog/tags/typography.md) * [customization](/blog/tags/customization.md) --- # Best Diagram Tool for Confluence — Mermaid vs Excalidraw vs Graphviz April 24, 2026 · 9 min read [NGPilot](https://ngpilot.com) Looking for the best **diagram tool for Confluence**? Confluence has no built-in diagramming, so every team adds a Marketplace app — but the right choice depends entirely on *what* you draw and *how* you prefer to work. This guide compares the three strongest options — [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?hosting=cloud\&tab=overview), [Excalidraw Plus Whiteboards & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence?hosting=cloud\&tab=overview), and [Graphviz Charts for Confluence](https://marketplace.atlassian.com/apps/1237380/graphviz-charts-for-confluence?hosting=cloud\&tab=overview) — so you can pick the diagram tool that fits your team instead of guessing. Quick answer For most Confluence teams, **Mermaid Plus** is the best diagram tool — it covers the widest range (30 diagram types), is the easiest to learn, and renders text into diagrams that version cleanly with your docs. Pick **Excalidraw Plus** if you need freehand whiteboarding and wireframes. Pick **Graphviz Charts** for dense network and dependency graphs. Many teams install more than one. What you'll learn 1. Which diagram tool fits each type of Confluence team 2. The strengths and trade-offs of Mermaid, Excalidraw, and Graphviz 3. Pricing, hosting, and integration differences 4. A decision framework so you can choose in under a minute ## Why Confluence needs a dedicated diagram tool[​](#why-confluence-needs-a-dedicated-diagram-tool "Direct link to Why Confluence needs a dedicated diagram tool") Confluence's native editor handles text, tables, and images — but it cannot draw. There is no flowchart builder, no UML support, no whiteboard, and no way to render a diagram from text. Any team that documents architecture, processes, or systems ends up pasting screenshots from external tools, where they go stale the moment the source changes. A dedicated Confluence diagram tool fixes this by embedding the editor directly in the page, so diagrams live next to the text they illustrate, update in place, and export with the rest of the document. The question is which one — and the three below cover essentially every diagramming need a Confluence team has. ## Quick comparison: the three diagram tools at a glance[​](#quick-comparison-the-three-diagram-tools-at-a-glance "Direct link to Quick comparison: the three diagram tools at a glance") | Feature | Mermaid Plus | Excalidraw Plus | Graphviz Charts | | ----------------- | ------------------------------------------------------ | ---------------------------------------- | -------------------------------------------- | | **Input method** | Text / code editor | Visual canvas (drag & drop) | Text / DOT language | | **Diagram types** | 29 (flowcharts, sequence, class, Gantt, ER, mindmaps…) | Freeform drawing, wireframes, sketches | Directed/undirected graphs, network diagrams | | **Live preview** | Yes | Yes (real-time canvas) | Yes | | **Templates** | Built-in, one-click per type | 220+ shape packs | DOT snippets | | **Visual style** | Clean, modern, themeable | Hand-drawn, freeform | Technical, utilitarian | | **Best for** | Structured diagrams, documentation | Brainstorming, wireframes, whiteboarding | Technical network and dependency diagrams | | **Free tier** | Free for ≤10 users | Free for ≤10 users | Free for ≤10 users | ## Mermaid Plus Diagrams & AI Agent for Confluence — structured diagrams from text[​](#mermaid-plus-diagrams--ai-agent-for-confluence--structured-diagrams-from-text "Direct link to Mermaid Plus Diagrams & AI Agent for Confluence — structured diagrams from text") [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?hosting=cloud\&tab=overview) lets you write diagram code and renders it instantly. It supports 30 diagram types including flowcharts, sequence diagrams, class diagrams, Gantt charts, pie charts, mindmaps, timelines, and more. **When to choose Mermaid Plus:** * You want to version and diff diagrams alongside documentation * You need many standardized diagram types (flowcharts, sequence, ER, Gantt) * Your team prefers text-based editing over drag-and-drop Read the step-by-step guide: [Create Mermaid diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md). ## Excalidraw Plus Whiteboards & AI Agent for Confluence — freeform whiteboarding[​](#excalidraw-plus-whiteboards--ai-agent-for-confluence--freeform-whiteboarding "Direct link to Excalidraw Plus Whiteboards & AI Agent for Confluence — freeform whiteboarding") [Excalidraw Plus Whiteboards & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence?hosting=cloud\&tab=overview) provides a visual canvas where you draw freely with shapes, lines, and text. It ships with 220+ shape libraries covering flowcharts, UML, wireframes, network diagrams, and more, plus a Rovo AI agent that draws and edits whiteboards from Confluence chat. **When to choose Excalidraw Plus:** * You need freeform drawing and brainstorming * You want to sketch wireframes or mockups * Your team prefers a drag-and-drop visual editor * You want an AI agent to keep whiteboards current instead of redrawing them by hand * You also need whiteboards in Jira — try [Excalidraw Diagrams plus Whiteboards for Jira](/docs/Excalidraw-Diagrams-plus-Whiteboards-for-Jira/usage.md) Read the step-by-step guide: [Excalidraw AI Agent for Confluence](/blog/excalidraw-ai-agent-confluence.md). > **Excalidraw vs draw\.io?** If you're weighing Excalidraw against draw\.io (diagrams.net) specifically, see our dedicated [Excalidraw vs draw.io for Confluence comparison](/blog/faq-excalidraw-vs-drawio-confluence.md) — it covers whiteboarding vs structured UML, Mermaid support, shape libraries, and pricing side by side. ## Graphviz Charts for Confluence — technical graph diagrams[​](#graphviz-charts-for-confluence--technical-graph-diagrams "Direct link to Graphviz Charts for Confluence — technical graph diagrams") [Graphviz Charts for Confluence](https://marketplace.atlassian.com/apps/1237659/graphviz-charts-for-confluence?hosting=cloud\&tab=overview) uses the DOT language to generate directed and undirected graphs. It excels at rendering complex dependency trees, network topologies, and state machines. **When to choose Graphviz Charts:** * You need automatic layout of complex node-and-edge graphs * You are documenting network topologies, dependency trees, or state machines * You prefer specifying relationships in text and letting the engine handle layout ## Want both Excalidraw AND Mermaid?[​](#want-both-excalidraw-and-mermaid "Direct link to Want both Excalidraw AND Mermaid?") The [Excalidraw & Mermaid Diagrams for Confluence](https://marketplace.atlassian.com/apps/1237659/excalidraw-mermaid-diagrams-for-confluence?hosting=cloud\&tab=overview) combines both tools in a single macro — freeform drawing on one tab, structured Mermaid diagrams on the other. See the [documentation](/docs/diagram-duo-for-confluence/usage.md). ## Which should you install?[​](#which-should-you-install "Direct link to Which should you install?") * **Documentation-heavy teams**: Mermaid Plus — structured diagrams that are easy to maintain * **Design and product teams**: Excalidraw Plus — visual brainstorming and wireframes * **DevOps and engineering**: Graphviz Charts — automated layout of technical graphs * **Need everything**: Install all three — each serves a different purpose All three apps are available on the [Atlassian Marketplace](https://marketplace.atlassian.com/vendors/1226848/) with free trials. ## Decision framework: pick your diagram tool in 60 seconds[​](#decision-framework-pick-your-diagram-tool-in-60-seconds "Direct link to Decision framework: pick your diagram tool in 60 seconds") Not sure which Confluence diagram tool to choose? Answer these in order: 1. **Do you draw mostly freehand sketches and wireframes?** → Yes: **Excalidraw Plus**. Its hand-drawn canvas is purpose-built for brainstorming and early-stage design. 2. **Do you diagram dense networks, dependencies, or call graphs with many nodes?** → Yes: **Graphviz Charts**. Its auto-layout engine handles complexity that breaks manual editors. 3. **Do you want standardized, maintainable diagrams (flowcharts, sequence, ER, Gantt) that diff cleanly?** → Yes (the most common answer): **Mermaid Plus**. Text-based diagrams version with your docs and cover 30 types. If you answered "yes" to more than one, install the matching combination — the three apps do not conflict and each owns a different category. ## Diagram tool by use case[​](#diagram-tool-by-use-case "Direct link to Diagram tool by use case") | If you need to draw… | Best diagram tool | Why | | ------------------------------- | ------------------------ | ----------------------------------------------------- | | Flowcharts and process diagrams | Mermaid Plus | Text syntax + templates, diffs in version control | | Architecture and system design | Mermaid Plus or Graphviz | Mermaid for C4/sequence; Graphviz for dependency maps | | Wireframes and UI mockups | Excalidraw Plus | Freehand canvas with shape libraries | | Sequence and class diagrams | Mermaid Plus | First-class UML support, 30 types | | Network topology | Graphviz Charts | Auto-layout of nodes and edges at scale | | Gantt and project timelines | Mermaid Plus | Native Gantt syntax | | Whiteboarding and brainstorming | Excalidraw Plus | Real-time multi-user freehand canvas | | Entity-relationship diagrams | Mermaid Plus | ER syntax with cardinality | ## Pricing and hosting[​](#pricing-and-hosting "Direct link to Pricing and hosting") All three diagram tools run on **Atlassian Forge** (Cloud-only) and are **free for up to 10 users** — so small teams can adopt them at no cost. Paid tiers scale with team size and are billed through the Atlassian Marketplace. None of the three requires a separate server, external rendering service, or self-hosted component; everything renders client-side or via Forge compute, which keeps diagrams inside your Confluence security boundary. ## Frequently asked questions[​](#frequently-asked-questions "Direct link to Frequently asked questions") ### Does Confluence have a built-in diagram tool?[​](#does-confluence-have-a-built-in-diagram-tool "Direct link to Does Confluence have a built-in diagram tool?") No. Confluence's native editor cannot draw diagrams — there is no flowchart, UML, or whiteboard feature. You add diagramming through a Marketplace app. The three recommended above (Mermaid Plus, Excalidraw Plus, Graphviz Charts) are the most capable options for Confluence Cloud. ### What is the best free diagram tool for Confluence?[​](#what-is-the-best-free-diagram-tool-for-confluence "Direct link to What is the best free diagram tool for Confluence?") For teams of 10 users or fewer, **Mermaid Plus**, **Excalidraw Plus**, and **Graphviz Charts** are all free. Mermaid Plus is the best starting point because it covers the widest range of diagram types (29) with the easiest learning curve. See our [free diagram plugin guide](/blog/confluence-free-diagram-plugin.md) for more. ### Can I use draw\.io or Lucidchart instead?[​](#can-i-use-drawio-or-lucidchart-instead "Direct link to Can I use draw.io or Lucidchart instead?") You can, but they have trade-offs. draw\.io (diagrams.net) is structured and precise, with deep cloud and network shape libraries — and since 2026 it also inserts Mermaid, so the real question is text-native versus shapes; see [draw.io vs Mermaid in Confluence](/blog/mermaid-vs-drawio-confluence.md) and our [Excalidraw vs draw.io comparison](/blog/faq-excalidraw-vs-drawio-confluence.md). The NGPILOT tools above are Forge-native, run entirely inside Confluence, and are free for small teams. ### Which diagram tool is best for developers?[​](#which-diagram-tool-is-best-for-developers "Direct link to Which diagram tool is best for developers?") Developers generally prefer **Mermaid Plus** — diagrams are plain text, so they diff in pull requests, live in version control, and render the same way in Confluence as in GitHub. For dense infrastructure graphs, add **Graphviz Charts**. **Ready to add diagrams to your Confluence?** [Try our diagram tools with free trials →](https://marketplace.atlassian.com/vendors/1226848/) ## Related resources[​](#related-resources "Direct link to Related resources") * [Mermaid Plus Diagrams & AI Agent for Confluence — marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?hosting=cloud\&tab=overview) | [documentation](/apps/mermaid-plus-for-confluence.md) * [Excalidraw Plus Whiteboards & AI Agent for Confluence — marketplace](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence?hosting=cloud\&tab=overview) | [documentation](/apps/excalidraw-plus-for-confluence.md) * [Excalidraw & Mermaid Diagrams for Confluence — marketplace](https://marketplace.atlassian.com/apps/1237659/excalidraw-mermaid-diagrams-for-confluence?hosting=cloud\&tab=overview) | [documentation](/apps/excalidraw-mermaid-diagrams-for-confluence.md) * [Create Mermaid diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md) — how-to guide with examples * [All 30 Mermaid diagram types](/blog/faq-mermaid-diagram-types-confluence.md) — complete reference: C4, flowchart, sequence, Gantt, swimlane, and more * [ER diagrams in Confluence](/blog/how-to-create-er-diagrams-confluence.md) — embed database schemas with Mermaid erDiagram syntax * [Excalidraw best practices FAQ](/blog/faq-excalidraw-best-practices.md) * [Excalidraw vs draw.io for Confluence](/blog/faq-excalidraw-vs-drawio-confluence.md) — freehand whiteboarding vs structured UML diagrams * [draw.io vs Mermaid in Confluence](/blog/mermaid-vs-drawio-confluence.md) — when the source text stays the diagram, and when shapes win * [Mermaid troubleshooting FAQ](/blog/faq-mermaid-troubleshooting.md) * [Best Confluence apps for developers — the full 2026 comparison](/blog/best-confluence-apps-developers.md) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [diagrams](/blog/tags/diagrams.md) * [mermaid](/blog/tags/mermaid.md) * [excalidraw](/blog/tags/excalidraw.md) * [graphviz](/blog/tags/graphviz.md) * [comparison](/blog/tags/comparison.md) * [excalidraw-vs-mermaid](/blog/tags/excalidraw-vs-mermaid.md) --- # Drawing vs Diagramming in Confluence — Canvas vs Text vs Graph May 6, 2026 · 5 min read [NGPilot](https://ngpilot.com) Adding diagrams to Confluence pages helps teams communicate architecture, processes, and workflows visually. This guide covers the three main approaches to creating diagrams in Confluence and helps you choose the right tool for your needs. ## Overview: Three approaches to diagrams in Confluence[​](#overview-three-approaches-to-diagrams-in-confluence "Direct link to Overview: Three approaches to diagrams in Confluence") | Approach | App | Input Method | Best For | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ---------------------------------------- | | Text-based diagrams | [Mermaid Plus](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?hosting=cloud\&tab=overview) | Write code → get diagram | Structured diagrams, documentation | | Visual drawing | [Excalidraw Plus](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence?hosting=cloud\&tab=overview) | Drag & drop on canvas | Brainstorming, wireframes, whiteboarding | | Network graphs | [Graphviz Charts](https://marketplace.atlassian.com/apps/1237659/graphviz-charts-for-confluence?hosting=cloud\&tab=overview) | Write DOT language | Dependency trees, network topologies | ## 1. Mermaid Plus — diagrams from text[​](#1-mermaid-plus--diagrams-from-text "Direct link to 1. Mermaid Plus — diagrams from text") [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?hosting=cloud\&tab=overview) lets you write diagram definitions in text and renders them instantly. It supports **30 diagram types** including flowcharts, sequence diagrams, class diagrams, ER diagrams, Gantt charts, pie charts, mindmaps, timelines, and more. ### How it works[​](#how-it-works "Direct link to How it works") 1. Type `/mermaid` in the Confluence editor 2. Write Mermaid syntax in the code pane 3. See the live preview update in real time 4. Choose a theme (default, dark, forest, neutral) 5. Save — the diagram renders on the page ### Best for[​](#best-for "Direct link to Best for") * **Architecture decision records** — diagrams alongside text that can be versioned and diffed * **API documentation** — sequence diagrams showing request/response flows * **Process documentation** — flowcharts with clear steps and decision points * **Project planning** — Gantt charts and timelines Read more: [Create Mermaid diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md). ## 2. Excalidraw Plus — freeform drawing[​](#2-excalidraw-plus--freeform-drawing "Direct link to 2. Excalidraw Plus — freeform drawing") [Excalidraw plus Whiteboards for Confluence](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence?hosting=cloud\&tab=overview) provides a visual canvas where you draw with shapes, lines, and text. It ships with **220+ shape libraries** covering flowcharts, UML, wireframes, network diagrams, and more. ### How it works[​](#how-it-works-1 "Direct link to How it works") 1. Type `/excalidraw` in the Confluence editor 2. A full drawing canvas opens inside the page 3. Drag shapes from the library, draw lines, add text 4. Save — the drawing embeds in the page ### Best for[​](#best-for-1 "Direct link to Best for") * **Brainstorming sessions** — freeform drawing without constraints * **Wireframes and mockups** — sketch UI ideas quickly * **Whiteboarding** — collaborative visual thinking * **Custom diagrams** — anything that doesn't fit a standard diagram type Also available for Jira: [Excalidraw Diagrams plus Whiteboards for Jira](/docs/Excalidraw-Diagrams-plus-Whiteboards-for-Jira/usage.md). ## 3. Graphviz Charts — automatic graph layout[​](#3-graphviz-charts--automatic-graph-layout "Direct link to 3. Graphviz Charts — automatic graph layout") [Graphviz Charts for Confluence](https://marketplace.atlassian.com/apps/1237659/graphviz-charts-for-confluence?hosting=cloud\&tab=overview) uses the DOT language to generate directed and undirected graphs with automatic layout. It excels at complex node-and-edge diagrams. ### How it works[​](#how-it-works-2 "Direct link to How it works") 1. Type `/graphviz` in the Confluence editor 2. Write DOT syntax defining nodes and edges 3. The engine automatically computes the layout 4. Save — the graph renders on the page ### Best for[​](#best-for-2 "Direct link to Best for") * **Network topologies** — show how servers and services connect * **Dependency trees** — visualize package or module dependencies * **State machines** — show states and transitions * **Org charts** — hierarchical tree layouts ## Which should you choose?[​](#which-should-you-choose "Direct link to Which should you choose?") ### By use case[​](#by-use-case "Direct link to By use case") | Use Case | Recommended Tool | | ---------------------- | ------------------------------- | | Flowcharts | Mermaid Plus or Excalidraw Plus | | Sequence diagrams | Mermaid Plus | | Wireframes | Excalidraw Plus | | Architecture diagrams | Mermaid Plus or Excalidraw Plus | | Network diagrams | Graphviz Charts | | Gantt charts | Mermaid Plus | | Mindmaps | Mermaid Plus | | Freeform brainstorming | Excalidraw Plus | | Dependency trees | Graphviz Charts | ### By team type[​](#by-team-type "Direct link to By team type") * **Engineering teams** — Mermaid Plus (diagrams-as-code integrates with docs) * **Design teams** — Excalidraw Plus (visual canvas with shape libraries) * **DevOps teams** — Graphviz Charts (automated network graph layout) * **Cross-functional teams** — install all three, each serves different needs ## Want multiple tools in one app?[​](#want-multiple-tools-in-one-app "Direct link to Want multiple tools in one app?") [Excalidraw & Mermaid Diagrams for Confluence](https://marketplace.atlassian.com/apps/1237659/excalidraw-mermaid-diagrams-for-confluence?hosting=cloud\&tab=overview) combines both Excalidraw and Mermaid in a single macro — freeform drawing on one tab, structured Mermaid diagrams on the other. See the [documentation](/docs/diagram-duo-for-confluence/usage.md). ## Get started[​](#get-started "Direct link to Get started") All three apps are available on the [Atlassian Marketplace](https://marketplace.atlassian.com/vendors/1226848/) with free trials. Each is free for up to 10 users. **Ready to add diagrams to your Confluence?** [Browse all NGPILOT apps →](https://marketplace.atlassian.com/vendors/1226848/) ## Related resources[​](#related-resources "Direct link to Related resources") * [Confluence diagram tools compared](/blog/confluence-diagram-tools-comparison.md) — detailed feature comparison * [Does Confluence support Mermaid?](/blog/does-confluence-support-mermaid.md) — setup guide * [Create flowcharts in Confluence](/blog/create-flowcharts-confluence.md) — step-by-step tutorial * [Excalidraw best practices FAQ](/blog/faq-excalidraw-best-practices.md) * [Mermaid troubleshooting FAQ](/blog/faq-mermaid-troubleshooting.md) * [Mermaid diagram types FAQ](/blog/faq-mermaid-diagram-types-confluence.md) ## Related guides * [Best Diagram Tool for Confluence — Compared](/blog/confluence-diagram-tools-comparison.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [diagrams](/blog/tags/diagrams.md) * [drawing](/blog/tags/drawing.md) * [mermaid](/blog/tags/mermaid.md) * [excalidraw](/blog/tags/excalidraw.md) * [graphviz](/blog/tags/graphviz.md) * [comparison](/blog/tags/comparison.md) --- # Expand Macro for Confluence: Collapsible Sections Compared (Native vs Styled) August 21, 2026 · 5 min read [NGPilot](https://ngpilot.com) Long pages die from scroll fatigue. Onboarding checklists, troubleshooting trees, API reference details, legal disclaimers — content that only some readers need some of the time is the canonical use case for collapsible sections. Confluence ships a native **expand macro** for exactly this, and for many pages it's enough. This guide covers how the native expand works, where teams typically outgrow it, and what a styled accordion macro adds — so you can pick per page, not per vendor. ## The native expand macro: how it works[​](#the-native-expand-macro-how-it-works "Direct link to The native expand macro: how it works") The built-in macro is one slash command away: 1. Edit a page, type `/expand` 2. Enter a title — this becomes the clickable toggle text 3. Put any content inside: text, tables, images, even other macros 4. Publish — viewers click the title to expand or collapse **What it does well:** * Zero setup — works in every Confluence Cloud instance * Nested content support — anything you can put on a page can go inside * Predictable, accessible toggle behavior * Indexes normally in Confluence search **Where teams outgrow it:** * **One section per macro.** A FAQ with twelve questions means twelve separate macros to create, align, and reorder — each with its own styling drift. * **No accordion mode.** All native expands can be open simultaneously; there's no "close others when one opens" behavior. * **Plain styling.** The title renders as plain text — no accent color, no icon, no visual hierarchy between sections. * **Collapsed-by-default exports.** PDF export of a page full of collapsed expands exports the hidden content in an inconsistent way, which bites print/compliance workflows. ## When you need an accordion: the styled Expand macro[​](#when-you-need-an-accordion-the-styled-expand-macro "Direct link to When you need an accordion: the styled Expand macro") When a page has repeated collapsible sections — FAQs, multi-step guides, release notes grouped by version — what you actually want is one macro holding many sections, with consistent styling and accordion behavior. That's the shape of the **Expand** macro in [Content Formatting Macros & Page Builder for Confluence](/apps/content-formatting-macros-page-builder-for-confluence.md): * **Multiple sections in one macro** — add as many as you need, drag to reorder, rich text in each * **True accordion mode** — "Allow Multiple Open" off means opening one section closes the others * **Per-section control** — title, per-section emoji or character icon, and an "Initially Open" toggle per section (useful for exports: print the sections that matter) * **Five design styles** — Simple, Bordered, Shadowed, Gradient, or Minimal, with an accent color picker and content padding control * **Animation** — smooth expand/collapse (100–1000ms) instead of an instant jump The mental model: native expand is a single toggle; a styled accordion is a **content structure**. Pages with 2–3 toggles rarely need more than native. Pages with 8+ sections benefit from treating the set as one editable unit. ## Which should you use, per page type[​](#which-should-you-use-per-page-type "Direct link to Which should you use, per page type") | Page type | Recommendation | | ------------------------------------ | -------------------------------------------------------------------------------------------- | | Hiding one long table or code sample | Native expand — nothing to gain from more structure | | FAQ with many Q\&As | Styled accordion (or a dedicated [FAQ macro](/blog/how-to-build-faq-sections-confluence.md)) | | Troubleshooting decision tree | Styled accordion with "one open at a time" so readers follow one path | | Meeting notes with optional detail | Native expand | | Release notes grouped by version | Styled accordion — drag-reorder as versions change | | Onboarding checklist | Styled accordion with icons per phase | ## One mechanism, many names[​](#one-mechanism-many-names "Direct link to One mechanism, many names") Teams arrive at this page searching for "collapse text", "click to expand", "expandable section", or a "toggle list" — in Confluence they are all the same primitive: | What you searched | What Confluence calls it | | ---------------------------------------- | -------------------------------------------------------- | | Collapse text / hide text behind a click | Expand macro (collapsed by default) | | Click to expand a section | The expand macro's title bar toggle | | Expandable / collapsible section | An expand macro holding that section | | Toggle list, accordion, drop-down list | A stack of expand macros — or one styled accordion macro | | Spoiler / details tag | Expand macro with a short title | The native `/expand` macro covers all of these with plain styling; the styled Expand macro in [Content Formatting Macros & Page Builder](/apps/content-formatting-macros-page-builder-for-confluence.md) covers them with icons, accent colors, and accordion behavior. ## Common questions from teams[​](#common-questions-from-teams "Direct link to Common questions from teams") **"Does collapsed content hurt SEO?"** Content inside collapsible sections is indexed by Google and by Confluence search — collapsing is a presentation choice, not a content hiding mechanism. (That said, critical keywords your page should rank for belong in the open parts of the page, not only inside toggles.) **"Can I nest expand inside expand?"** Yes, in both the native macro and the styled accordion's rich-text sections. Nested accordions two levels deep are usually a sign the content wants to be separate pages, though. **"How does this interact with page exports?"** Native: collapsed sections may export inconsistently depending on export path. Styled accordion: the "Initially Open" toggle decides, which gives you deterministic print output. ## Related reading[​](#related-reading "Direct link to Related reading") * [How to build FAQ sections in Confluence](/blog/how-to-build-faq-sections-confluence.md) — the FAQ-shaped cousin of the accordion * [Confluence block quotes, three ways](/blog/block-quote-confluence.md) — another formatting primitive compared * [Confluence pagination: pages and tables](/blog/confluence-pagination.md) — collapsing vs splitting long content across a page series * [Content Formatting Macros & Page Builder](/apps/content-formatting-macros-page-builder-for-confluence.md) — the full macro suite, 23 macros ## Related guides * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [macros](/blog/tags/macros.md) * [expand](/blog/tags/expand.md) * [accordion](/blog/tags/accordion.md) * [formatting](/blog/tags/formatting.md) * [how-to](/blog/tags/how-to.md) --- # Confluence Font Apps Compared: Google Fonts vs Custom Fonts Pro May 2, 2026 · 11 min read [NGPilot](https://ngpilot.com) Confluence ships with a fixed set of system fonts. For most teams that works fine, but if your company has brand guidelines, an accessibility requirement for specific typefaces, or simply wants documentation that looks polished and professional, the default typography falls short. The Atlassian Marketplace now offers several apps that let you use custom fonts on your Confluence pages. But with different feature sets, pricing models, and levels of maturity, choosing the right one takes more than a quick glance at star ratings. This post compares the leading Confluence custom font apps side by side so you can make an informed decision for your team. ## Why Teams Want Custom Fonts in Confluence[​](#why-teams-want-custom-fonts-in-confluence "Direct link to Why Teams Want Custom Fonts in Confluence") Before we get into the apps, here are the most common reasons teams give for installing a font app: * **Brand consistency.** Your marketing site, pitch decks, and product UI all use a specific typeface. Confluence documentation that still uses the default font feels disconnected from the rest of your brand ecosystem. * **Accessibility and readability.** Some organizations are required to meet WCAG readability standards. Choosing a font optimized for legibility at various sizes can make a measurable difference for users with dyslexia or low vision. * **Professional appearance.** Client-facing spaces, partner wikis, and public knowledge bases look more credible when the typography is intentional rather than generic. * **Team identity.** Engineering teams, design teams, and HR teams often want their spaces to feel distinct without rebuilding the entire theme. Whatever your reason, the good news is that you no longer need custom CSS injections or unreliable workarounds. Marketplace apps now handle font loading, fallback behavior, and scope configuration safely. ## The Contenders: Confluence Font Apps on the Marketplace[​](#the-contenders-confluence-font-apps-on-the-marketplace "Direct link to The Contenders: Confluence Font Apps on the Marketplace") There are currently a handful of font-related apps available for Confluence Cloud. We will focus on the three most prominent options and briefly mention others. ### 1. Google Fonts for Confluence (by NGPILOT)[​](#1-google-fonts-for-confluence-by-ngpilot "Direct link to 1. Google Fonts for Confluence (by NGPILOT)") **What it does:** This app provides a Confluence macro that gives you access to the entire Google Fonts library (over 1,942 font families) directly on your Confluence pages. You insert the macro on a page, type `/google fonts` in the editor, then select your font family, variant, size, color, and alignment through a configuration panel with live preview. **Key features:** * Access to the full Google Fonts catalog (1,942+ font families) without uploading anything * Macro-based insertion — type `/google fonts` on any page to add styled text * Live preview in the configuration panel so you see exactly how your text looks before saving * Font family, variant (regular, italic, bold, bold italic), size, color, and alignment controls * Google Fonts CDN loading for fast global delivery with no server-side hosting required * Dark theme compatibility so your styled text adapts to both Confluence light and dark modes * Cloud Fortified status, which means it meets Atlassian's highest bar for security, reliability, and support responsiveness **Pros:** * Largest available font library of any Confluence font app * No file uploads or hosting required; everything comes from the Google Fonts CDN * Simple macro-based UI — insert, configure, save * Live preview lets you test fonts on your actual content before publishing * Cloud Fortified badge provides confidence for enterprise security reviews * Actively maintained with regular updates aligned to Confluence platform changes * Free trial available so you can test it with your content before committing **Cons:** * Macro-based approach means you add styled text per instance rather than changing fonts globally across a space or site * Limited to fonts available on Google Fonts; if your brand uses a proprietary typeface not on Google Fonts, this app alone will not cover that use case * Requires an internet connection to load fonts from the CDN (offline Confluence instances will not load custom fonts) ### 2. Fonts for Confluence (by Skanda Consulting)[​](#2-fonts-for-confluence-by-skanda-consulting "Direct link to 2. Fonts for Confluence (by Skanda Consulting)") **What it does:** Fonts for Confluence by Skanda Consulting provides a curated selection of fonts that can be applied across Confluence. It focuses on simplicity and ease of setup, targeting teams that want a quick way to change the default typeface without navigating a large catalog. **Key features:** * Pre-selected font collection chosen for readability and professional appearance * Space-level configuration for per-team customization * Simple setup with minimal configuration options * Compatible with Confluence Cloud **Pros:** * Straightforward to install and configure; the limited selection makes choices simple * Works well if you already know which of the included fonts you want * Lower price point compared to some alternatives **Cons:** * Limited font selection compared to apps that pull from the full Google Fonts library * No variable font support as of the most recent update * Fewer configuration options for fine-tuning fallback stacks and font weights * Update cadence has been slower; the app has gone longer stretches between releases * Not Cloud Fortified, which may be a consideration for organizations with strict procurement requirements ### 3. Custom Fonts Pro (by Aptify Tech)[​](#3-custom-fonts-pro-by-aptify-tech "Direct link to 3. Custom Fonts Pro (by Aptify Tech)") **What it does:** Custom Fonts Pro focuses on uploading and serving your own font files. If your organization has a proprietary typeface or a licensed font that is not available on any public font service, this app lets you upload the files and apply them in Confluence. **Key features:** * Upload custom font files (WOFF, WOFF2, TTF, OTF) * Space-level and site-level configuration * Font file management dashboard for organizing uploaded typefaces * Support for multiple font weights and styles per family **Pros:** * The go-to option if you need a proprietary or licensed font not available on Google Fonts * Full control over which font files are loaded and from where * Useful for organizations with strict brand guidelines that mandate a specific typeface **Cons:** * You must supply your own font files and manage licensing compliance yourself * Font files are hosted within the app, which means loading performance depends on Atlassian's infrastructure rather than a dedicated global CDN * Smaller font library out of the box; you build the library yourself * More setup effort required compared to apps with built-in catalogs * Not Cloud Fortified * Variable font support is limited ### Other Apps Worth Noting[​](#other-apps-worth-noting "Direct link to Other Apps Worth Noting") The Marketplace also has a few niche or newer entries. Some theme apps include basic font selection as part of a broader customization suite. These can be worth considering if you already use or plan to use a full theme app, but they tend to offer fewer typography-specific features than dedicated font apps. Always check the most recent reviews and update history before relying on a newer app in a production environment. ## Feature Comparison Table[​](#feature-comparison-table "Direct link to Feature Comparison Table") | Feature | Google Fonts (NGPILOT) | Fonts for Confluence (Skanda) | Custom Fonts Pro (Aptify Tech) | | ---------------------------- | ------------------------------------------- | ----------------------------- | ------------------------------ | | Font source | Full Google Fonts library (1,942+ families) | Curated built-in collection | User-uploaded font files | | Approach | Macro-based (per-page insertion) | Theme-level config | Theme-level config | | Space-level config | No (macro-based) | Yes | Yes | | Site-level config | No (macro-based) | Limited | Yes | | Live preview | Yes | No | No | | Font size control | Yes (any px value) | Limited | Limited | | Color picker | Yes | No | No | | Text alignment | Yes | No | No | | Fallback font stacks | Automatic | Basic | Manual | | CDN loading | Google Fonts CDN (global) | App-hosted | App-hosted | | Number of fonts available | 1,942+ | \~50 | Unlimited (user-supplied) | | Font variant selection | Regular, Italic, Bold, Bold Italic | Limited variants | Depends on uploaded files | | Free trial | Yes | Yes | Yes | | Cloud Fortified | Yes | No | No | | Dark theme support | Yes | Partial | Partial | | Last updated | Actively maintained (2026) | Updated periodically | Updated periodically | | Atlassian Marketplace rating | High | Moderate | Moderate | ## Which Font App Should You Choose?[​](#which-font-app-should-you-choose "Direct link to Which Font App Should You Choose?") Every team's needs are different, but here are three common scenarios with clear recommendations. ### Scenario 1: You Want the Best Selection With Zero Hassle[​](#scenario-1-you-want-the-best-selection-with-zero-hassle "Direct link to Scenario 1: You Want the Best Selection With Zero Hassle") **Recommendation: Google Fonts for Confluence (NGPILOT)** If your goal is to pick from a wide variety of high-quality, freely available fonts and use them on your Confluence pages within minutes, Google Fonts for Confluence is the strongest choice. The live preview alone saves significant back-and-forth. You insert the macro, browse fonts, see how your text looks in real time, and save. The Cloud Fortified status and active maintenance cadence make it a safe bet for teams that want something they will not have to worry about. This is the best option for teams that need styled headings, branded text, and custom typography on specific pages. The macro-based approach gives you precise control over where custom fonts appear. ### Scenario 2: You Need a Proprietary or Licensed Font[​](#scenario-2-you-need-a-proprietary-or-licensed-font "Direct link to Scenario 2: You Need a Proprietary or Licensed Font") **Recommendation: Custom Fonts Pro (Aptify Tech)** If your brand guidelines require a specific typeface that is not on Google Fonts, Custom Fonts Pro is your best option. You upload the font files you already have a license for, and the app serves them in Confluence. The trade-off is more setup work and self-managed licensing compliance, but for organizations where brand consistency is non-negotiable, this is the right tool. Some teams use Google Fonts for Confluence for general spaces and Custom Fonts Pro for the specific spaces that require the proprietary brand font. The two apps can coexist if configured carefully. ### Scenario 3: You Want Something Simple and Inexpensive[​](#scenario-3-you-want-something-simple-and-inexpensive "Direct link to Scenario 3: You Want Something Simple and Inexpensive") **Recommendation: Fonts for Confluence (Skanda) or Google Fonts for Confluence (NGPILOT)** If budget is the primary concern and you just want to move away from the default Confluence font, Fonts for Confluence offers a lower-cost option with a small curated selection. However, it is worth comparing the price difference against what Google Fonts for Confluence provides. The larger library, live preview, Cloud Fortified status, and variable font support from NGPILOT often justify a modest price difference, especially for teams that value a polished setup experience and reliable ongoing support. ## A Note on Performance[​](#a-note-on-performance "Direct link to A Note on Performance") Loading custom fonts in a web application always has a performance implication. Here is how the apps handle it: * **Google Fonts for Confluence** loads fonts from the Google Fonts CDN, which is one of the most widely used and heavily optimized content delivery networks in the world. Chances are your users' browsers already have Google Fonts cached from other websites. The app also implements proper `font-display` strategies and fallback stacks to prevent invisible text during loading. * **Fonts for Confluence** and **Custom Fonts Pro** host fonts through the app infrastructure. Performance is generally acceptable but will not match the caching benefits and edge distribution of a purpose-built global CDN. For teams where page load speed is a measured KPI, the CDN approach used by Google Fonts for Confluence is a tangible advantage. ## A Note on Compliance and Security[​](#a-note-on-compliance-and-security "Direct link to A Note on Compliance and Security") If your organization conducts security reviews of Marketplace apps (and most mid-to-large companies do), the Cloud Fortified badge matters. It means Atlassian has verified that the app meets specific standards for data handling, incident response, and reliability. As of this writing, only Google Fonts for Confluence by NGPILOT holds Cloud Fortified status among the dedicated font apps. Custom Fonts Pro requires you to upload font files, which means the font data resides in the app. Make sure your security team reviews where that data is stored and how it is transmitted. Google Fonts for Confluence does not store any font data; it loads fonts from the public Google Fonts CDN on the client side, which simplifies compliance. ## Making Your Decision[​](#making-your-decision "Direct link to Making Your Decision") To summarize the decision framework: 1. **Do you need a proprietary font?** Go with Custom Fonts Pro. 2. **Do you want the largest selection with the least effort?** Go with Google Fonts for Confluence by NGPILOT. 3. **Are you budget-constrained and only need a basic change?** Compare Fonts for Confluence against the free trial of Google Fonts for Confluence before deciding. All three apps offer free trials. The best way to decide is to install the ones you are considering, test them with your actual Confluence content, and see which one feels right for your team. Most teams find that the trial period makes the decision obvious. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Google Fonts for Confluence — documentation](/apps/google-fonts-for-confluence.md) * [Google Fonts for Confluence — setup and usage docs](/docs/Google-Fonts-for-Confluence/usage.md) * [How to Configure Google Fonts in Confluence](/blog/configure-google-fonts-confluence.md) * [Google Fonts Performance & FAQ](/blog/faq-google-fonts-performance.md) * [Google Fonts Alternatives FAQ](/blog/faq-google-fonts-confluence-alternatives.md) * [Google Fonts for Confluence — Which Typography App?](/blog/google-fonts-confluence-custom-typography.md) Try Google Fonts for Confluence 1,942+ Google Font families with live preview, custom size/color/alignment — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236413/google-fonts-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=google-fonts-for-confluence) ## Related guides * [Can You Change the Font in Confluence? Custom Options](/blog/confluence-default-font-change-font.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [comparison](/blog/tags/comparison.md) * [confluence](/blog/tags/confluence.md) * [fonts](/blog/tags/fonts.md) * [google-fonts](/blog/tags/google-fonts.md) * [typography](/blog/tags/typography.md) --- # Free Diagram Apps for Confluence — Excalidraw & Free-Tier Limits May 10, 2026 · 4 min read [NGPilot](https://ngpilot.com) Need diagram tools for Confluence without paying for a large team? NGPILOT's three diagramming apps — Mermaid Plus, Excalidraw Plus, and Graphviz Charts — are all **free for up to 10 users**. This guide compares them so you can pick the right free diagram plugin for your Confluence. ## Free diagram plugins for Confluence compared[​](#free-diagram-plugins-for-confluence-compared "Direct link to Free diagram plugins for Confluence compared") | Feature | Mermaid Plus | Excalidraw Plus | Graphviz Charts | | ------------- | ------------------------------------------- | ---------------------------------------- | ------------------------------------ | | Free tier | Up to 10 users | Up to 10 users | Up to 10 users | | Input method | Text / code | Visual canvas (drag & drop) | Text / DOT language | | Diagram types | 30 types | Freeform drawing | Directed/undirected graphs | | Best for | Flowcharts, sequence, Gantt, class diagrams | Whiteboarding, wireframes, brainstorming | Network topologies, dependency trees | | Live preview | Yes | Yes | Yes | | Templates | Built-in library | 220+ shape packs | DOT snippets | ## Mermaid Plus — free flowcharts, sequence & Gantt charts[​](#mermaid-plus--free-flowcharts-sequence--gantt-charts "Direct link to Mermaid Plus — free flowcharts, sequence & Gantt charts") [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?hosting=cloud\&tab=overview) lets you write diagram code and renders it instantly. It supports **30 diagram types** including flowcharts, sequence diagrams, class diagrams, ER diagrams, Gantt charts, pie charts, mindmaps, and timelines. **Why it's great for free use:** * Text-based diagrams are fast to create and easy to maintain * 30 diagram types cover most documentation needs * One-click templates get you started immediately * Diagrams are versionable alongside your documentation Read the full guide: [Does Confluence support Mermaid?](/blog/does-confluence-support-mermaid.md). ## Excalidraw Plus — free whiteboarding & drawing[​](#excalidraw-plus--free-whiteboarding--drawing "Direct link to Excalidraw Plus — free whiteboarding & drawing") [Excalidraw plus Whiteboards for Confluence](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence?hosting=cloud\&tab=overview) provides a visual canvas with drag-and-drop shapes, freeform drawing, and **220+ shape libraries**. It's like having a digital whiteboard in every Confluence page. **Why it's great for free use:** * Visual editor — no syntax to learn * 220+ shape packs (AWS, Azure, UML, networking, wireframes) * Perfect for brainstorming and quick sketches * Also available for Jira: [Excalidraw for Jira](/docs/Excalidraw-Diagrams-plus-Whiteboards-for-Jira/usage.md) ## Graphviz Charts — free network & dependency graphs[​](#graphviz-charts--free-network--dependency-graphs "Direct link to Graphviz Charts — free network & dependency graphs") [Graphviz Charts for Confluence](https://marketplace.atlassian.com/apps/1237659/graphviz-charts-for-confluence?hosting=cloud\&tab=overview) uses the DOT language to generate directed and undirected graphs with automatic layout. It excels at complex node-and-edge diagrams. **Why it's great for free use:** * Automatic layout — no manual positioning needed * Perfect for network topologies and dependency trees * DOT language is simple and expressive * Great for documenting infrastructure ## Which free diagram plugin should you install?[​](#which-free-diagram-plugin-should-you-install "Direct link to Which free diagram plugin should you install?") * **Need flowcharts and process diagrams?** → Mermaid Plus * **Need whiteboarding and freeform drawing?** → Excalidraw Plus * **Need network graphs and dependency trees?** → Graphviz Charts * **Need all of the above?** → Install all three — each is free for up to 10 users All three apps are available on the [Atlassian Marketplace](https://marketplace.atlassian.com/vendors/1226848/) with free trials. ## Get started[​](#get-started "Direct link to Get started") **Install free diagram plugins for Confluence:** [Browse all NGPILOT apps →](https://marketplace.atlassian.com/vendors/1226848/) ## Related resources[​](#related-resources "Direct link to Related resources") * [Mermaid Plus — marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?hosting=cloud\&tab=overview) | [docs](/apps/mermaid-plus-for-confluence.md) * [Excalidraw Plus — marketplace](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence?hosting=cloud\&tab=overview) | [docs](/apps/excalidraw-plus-for-confluence.md) * [Graphviz Charts — marketplace](https://marketplace.atlassian.com/apps/1237659/graphviz-charts-for-confluence?hosting=cloud\&tab=overview) | [docs](/apps/graphviz-charts-for-confluence.md) * [Confluence diagram tools comparison](/blog/confluence-diagram-tools-comparison.md) * [Drawing & diagramming tools guide](/blog/confluence-drawing-diagramming-tools.md) ## Related guides * [Best Diagram Tool for Confluence — Compared](/blog/confluence-diagram-tools-comparison.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [diagrams](/blog/tags/diagrams.md) * [free](/blog/tags/free.md) * [mermaid](/blog/tags/mermaid.md) * [excalidraw](/blog/tags/excalidraw.md) * [graphviz](/blog/tags/graphviz.md) * [comparison](/blog/tags/comparison.md) --- # Best Confluence Import/Export Apps Compared — 2026 Guide April 18, 2026 · 7 min read [NGPilot](https://ngpilot.com) Teams move content in and out of Confluence every day — migrating between instances, backing up documentation, importing from other tools, exporting for offline review. Confluence has basic PDF and HTML export built in, but it's limited. No bulk operations, no multi-format support, no structured import workflow. Over a dozen marketplace apps try to fill this gap, but most solve one narrow problem: PDF export, Word import, or Markdown conversion. We built **Modern Importer & Exporter for Confluence** to handle both directions — import and export — across multiple formats. In this post we compare it against every alternative on the Atlassian Marketplace. ## The Problem with Confluence's Built-in Export[​](#the-problem-with-confluences-built-in-export "Direct link to The Problem with Confluence's Built-in Export") Confluence can export a single page to PDF or a whole space to HTML. That's it. If you need to: * **Import** content from Word, Markdown, or HTML files * **Export** multiple pages across different spaces in one operation * **Migrate** content between Confluence instances without losing formatting * **Backup** specific pages (not entire spaces) in a reusable format * **Convert** between formats — say, HTML to Confluence-native ADF ...you need a marketplace app. The problem is that most apps handle one direction (import OR export) in one format. Teams end up installing multiple apps for tasks that should be simple. ## What's Available on the Marketplace[​](#whats-available-on-the-marketplace "Direct link to What's Available on the Marketplace") The landscape splits into two categories: **export-focused** apps and **import-focused** apps. Very few do both. ### Export Apps[​](#export-apps "Direct link to Export Apps") | App | Vendor | Installs | Rating | Last Updated | Formats | Hosting | | ------------------------- | --------------- | -------- | ------------------- | ------------ | --------------- | ---------- | | Scroll PDF Exporter | K15t | 9,284 | 3.8/5 (224 reviews) | Apr 2026 | PDF | Cloud + DC | | Scroll Word Exporter | K15t | 4,853 | 3.9/5 (135 reviews) | Apr 2026 | DOCX | Cloud + DC | | Markdown Exporter | Narva Software | 2,284 | 3.3/5 (20 reviews) | Dec 2025 | Markdown | Cloud | | Content Exporter | META-INF KFT | 1,190 | 2.8/5 (28 reviews) | Apr 2026 | PDF, Word, HTML | Cloud | | PDF/HTML/Word Exporter | miniOrange | 217 | 2.5/5 (8 reviews) | Dec 2025 | PDF, Word, HTML | Cloud | | PDF Export for Confluence | Warsaw Dynamics | 116 | 1.0/5 (2 reviews) | Dec 2025 | PDF | Cloud | | HTML Exporter | Philip Lindner | 32 | 1.0/5 (1 review) | Dec 2025 | HTML | Cloud | ### Import Apps[​](#import-apps "Direct link to Import Apps") | App | Vendor | Installs | Rating | Last Updated | Formats | Hosting | | ---------------------------- | ------------------- | -------- | ------------------ | ------------ | -------------------------------- | ------- | | Markdown Importer & Editor | Narva Software Labs | 1,302 | 2.2/5 (5 reviews) | Mar 2026 | Markdown | Cloud | | Markdown Importer & Exporter | Yamuno Software | 977 | 3.0/5 (3 reviews) | Apr 2026 | Markdown | Cloud | | All-in-one File Importer | Narva Software Labs | 470 | 1.3/5 (24 reviews) | Dec 2025 | Word, Markdown, HTML, LaTeX, 30+ | Cloud | | MS OneNote Importer | Narva Software Labs | 178 | 1.3/5 (33 reviews) | Feb 2026 | OneNote | Cloud | | Word Importer for Confluence | Canary Apps | 62 | 4.0/5 (1 review) | Apr 2026 | DOCX | Cloud | ### Import + Export Combined[​](#import--export-combined "Direct link to Import + Export Combined") | App | Vendor | Installs | Rating | Last Updated | Formats | Hosting | | ------------------------------ | ----------- | -------- | ------ | ------------ | ----------------------------- | --------- | | **Modern Importer & Exporter** | **NGPILOT** | **12** | — | **Apr 2026** | **JSON, XML, HTML, Markdown** | **Cloud** | *Data from Atlassian Marketplace, April 2026.* **K15t dominates** with Scroll PDF (9,284 installs) and Scroll Word (4,853 installs). Both are mature, Cloud Fortified apps with professional template editors. But they only export — no import — and each handles a single format. **Narva Software Labs** has four apps in this space, but ratings tell the story: All-in-one File Importer has 1.3 stars from 24 reviews, and Markdown Importer & Editor has 2.2 stars. **Only our app and Yamuno's Markdown Importer & Exporter** offer both import and export. But Yamuno only handles Markdown. Modern Importer & Exporter supports JSON, XML, HTML, and Markdown in both directions. ## Feature Comparison[​](#feature-comparison "Direct link to Feature Comparison") We compared the top apps that are actively maintained and relevant to teams needing content import/export: | Feature | Modern Importer & Exporter (NGPILOT) | Scroll PDF (K15t) | Scroll Word (K15t) | Markdown Exporter (Narva) | Content Exporter (META-INF) | Markdown Importer & Exporter (Yamuno) | | --------------------------- | ------------------------------------ | ------------------- | -------------------- | ------------------------- | --------------------------- | ------------------------------------- | | **Import** | Yes | No | No | No | No | Yes (Markdown) | | **Export** | Yes | Yes (PDF) | Yes (DOCX) | Yes (Markdown) | Yes (PDF/Word/HTML) | Yes (Markdown) | | **Bidirectional** | Yes | No | No | No | No | Yes (Markdown only) | | **Export formats** | ADF JSON, ADF XML, HTML | PDF | DOCX | Markdown | PDF, Word, HTML | Markdown | | **Import formats** | JSON, XML, HTML, Markdown | — | — | — | — | Markdown | | **Bulk export** | Yes (multi-space) | Yes (page trees) | Yes (page trees) | Yes (full hierarchy) | Yes (page trees) | No | | **Bulk import** | Yes | — | — | — | — | Yes | | **Individual page actions** | Yes (right-click) | No | No | No | No | No | | **Multi-space selection** | Yes | No | No | No | No | No | | **Template customization** | No | Yes (visual editor) | Yes (Word templates) | No | Yes (custom CSS) | No | | **Progress tracking** | Yes | No | No | No | No | No | | **Conflict resolution** | Yes (auto-rename) | — | — | — | — | No | | **Cloud Fortified** | No | Yes | No | No | No | No | | **Hosting** | Cloud | Cloud + DC | Cloud + DC | Cloud | Cloud | Cloud | ### Where Modern Importer & Exporter Stands Out[​](#where-modern-importer--exporter-stands-out "Direct link to Where Modern Importer & Exporter Stands Out") **Bidirectional multi-format** — The only app that imports AND exports across JSON, XML, HTML, and Markdown. Every other app is either export-only (Scroll, Markdown Exporter, Content Exporter) or import-only (Word Importer, OneNote Importer), or limited to a single format (Yamuno only does Markdown). **Multi-space bulk operations** — Select content from multiple spaces and export it all in one operation. No other app offers cross-space selection with bulk export and import. **Individual content actions** — Right-click any page or blog post to export or import content directly. No need to navigate to a separate admin page. Quick actions for single items, bulk operations for migrations. **Four import formats** — JSON (native ADF, best fidelity), XML, HTML, and Markdown. Most importers support one format. All-in-one File Importer supports 30+ formats but carries a 1.3-star rating. **Override or append import modes** — Choose whether imported content replaces the existing page or appends to it. Gives you control over how content lands. **Progress tracking** — Real-time progress indicators during bulk operations. Know how far along your export or import is, with success/error counts on completion. ### Where We Could Improve[​](#where-we-could-improve "Direct link to Where We Could Improve") * **12 installs** — We're brand new in a space where K15t has over 14,000 combined installs. Building trust takes time. * **No PDF export** — Scroll PDF by K15t is the gold standard for professional PDF output with custom templates, branding, and watermarks. Our app focuses on structured data formats (JSON, XML, HTML, Markdown) rather than print-ready documents. * **No Word/DOCX support** — Scroll Word handles professional Word export with custom templates. We don't export to DOCX yet. * **No template editor** — K15t's Scroll apps have visual template editors for branding and styling. Our exports use the content's native formatting. * **No attachment export/import** — We handle page content only. Attachments are not included in exports or imports. * **No Cloud Fortified status** — K15t's Scroll PDF has completed Atlassian's Cloud Fortified program. We're working toward this. * **No Data Center support** — Cloud-only. K15t serves both Cloud and DC customers. ## Honest Comparison: NGPILOT vs K15t (Market Leader)[​](#honest-comparison-ngpilot-vs-k15t-market-leader "Direct link to Honest Comparison: NGPILOT vs K15t (Market Leader)") K15t is the established leader with Scroll PDF (9,284 installs) and Scroll Word (4,853 installs). Here's how we differ: | | Scroll PDF + Word (K15t) | Modern Importer & Exporter (NGPILOT) | | --------------------- | ----------------------------------------------------------- | ---------------------------------------------------- | | **Approach** | Two specialized export apps | One app for import AND export | | **Combined installs** | 14,137 | 12 | | **Rating** | 3.8–3.9/5 | — | | **Import** | No | Yes (JSON, XML, HTML, Markdown) | | **Export** | PDF + DOCX | JSON, XML, HTML | | **Template editor** | Yes — visual editor | No | | **Hosting** | Cloud + DC | Cloud | | **Cloud Fortified** | Yes (PDF) | No | | **Best for** | Professional document export (reports, manuals, compliance) | Content migration, backup, and multi-format transfer | K15t's Scroll apps are the right choice if you need professional PDF or Word output with branded templates. They've earned their market position over years of development. Our app is for teams that need to **move content in both directions** — import from external sources and export for backup or migration — without installing separate apps for each format. ## Which App Do You Need?[​](#which-app-do-you-need "Direct link to Which App Do You Need?") | You need... | Use this | | ------------------------------------------------------- | --------------------------------------------- | | Professional PDF export with templates and branding | Scroll PDF Exporter by K15t | | Professional Word/DOCX export with templates | Scroll Word Exporter by K15t | | Markdown export only | Markdown Exporter by Narva | | Word import only | Word Importer by Canary Apps | | Bidirectional import AND export across multiple formats | **Modern Importer & Exporter for Confluence** | | Content migration between Confluence instances | **Modern Importer & Exporter for Confluence** | | Bulk backup of specific pages across spaces | **Modern Importer & Exporter for Confluence** | ## Related Posts[​](#related-posts "Direct link to Related Posts") * [FAQ and Q\&A Apps for Confluence — Which One Is Right for Your Team?](/blog/faq-questions-confluence-comparison.md) * [Markdown Editor for Confluence — Which App Should You Choose for Writing Docs?](/blog/confluence-markdown-editor-comparison.md) ## Get Started[​](#get-started "Direct link to Get Started") * Install **Modern Importer & Exporter for Confluence** from the [Atlassian Marketplace](https://marketplace.atlassian.com/apps/977066696/modern-importer-exporter-for-confluence) * [Read the full documentation](/docs/Modern-Importer-Exporter-for-Confluence/user-docs.md) Have questions or feedback? Reach out to us at — we'd love to hear from you. Try Modern Importer & Exporter for Confluence Bulk import/export between JSON, XML, HTML, and Markdown formats — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/977066696/modern-importer-exporter-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-importer-exporter-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [import](/blog/tags/import.md) * [export](/blog/tags/export.md) * [confluence](/blog/tags/confluence.md) * [migration](/blog/tags/migration.md) * [backup](/blog/tags/backup.md) * [markdown](/blog/tags/markdown.md) * [pdf](/blog/tags/pdf.md) * [word](/blog/tags/word.md) * [content-transfer](/blog/tags/content-transfer.md) --- # JSON Formatting & Display in Confluence: Code Blocks vs Structure Viewer May 10, 2026 · 4 min read [NGPilot](https://ngpilot.com) Confluence's native code block macro renders JSON as plain text with no real formatting, no themes, and no copy button. There are two purpose-built apps that fix this, and each serves a different JSON display need: * **[Modern Code Blocks for Confluence](/docs/Modern-Code-Blocks-for-Confluence/user-docs.md)** — renders JSON as **syntax-highlighted code** with the Monaco editor (VS Code engine), 50+ themes, line numbers, copy button, and dark/light mode. **Best for API docs, snippets, and most JSON display.** * **[JSON Structure Viewer for Confluence](/docs/json-structure-viewer-for-confluence/usage.md)** — renders JSON as an **interactive collapsible tree** you can zoom and rotate. **Best for exploring large, deeply nested structures.** This guide compares the two so you can pick the right one for each page. ## Modern Code Blocks: syntax-highlighted JSON[​](#modern-code-blocks-syntax-highlighted-json "Direct link to Modern Code Blocks: syntax-highlighted JSON") [Modern Code Blocks for Confluence](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence) uses the Monaco editor — the same engine behind VS Code — to render JSON with proper syntax highlighting. Keys, strings, numbers, booleans, and null each get distinct colors, and you can switch between 50+ themes (Monokai, Dracula, GitHub Dark, Solarized) or let the block auto-match Confluence's light/dark mode. ### Features for JSON[​](#features-for-json "Direct link to Features for JSON") * **Monaco-grade highlighting** — distinct colors for keys, strings, numbers, booleans, null * **50+ themes** — or Auto, which follows Confluence dark/light mode * **Line numbers** — readers can reference "line 42" * **Copy button** — one-click copy of the payload * **Window chrome** — optional macOS/Windows title bar with auto-derived filename (`config.json`) * **Diff view** (Advanced edition) — show a JSON config change as a colored before/after * **85+ languages** — the same macro handles JSON, YAML, SQL, Python, and more ### How to format JSON with Code Blocks[​](#how-to-format-json-with-code-blocks "Direct link to How to format JSON with Code Blocks") 1. Install [Modern Code Blocks](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence) from the Marketplace (free for up to 10 users) 2. Edit a Confluence page, type `/code` and select **Modern Code Blocks for Confluence** 3. Paste your JSON into the editor 4. Set the **Language** to **JSON** 5. Optionally pick a **Theme** 6. Save the macro Example — an API response rendered with JSON syntax highlighting: ``` { "users": [ {"id": 1, "name": "Alice", "role": "admin"}, {"id": 2, "name": "Bob", "role": "editor"} ], "pagination": {"page": 1, "total": 42} } ``` For the full configuration reference — themes, max height, font size, minimap, window chrome, diff mode — see the [Modern Code Blocks user guide](/docs/Modern-Code-Blocks-for-Confluence/user-docs.md). ## JSON Structure Viewer: interactive tree[​](#json-structure-viewer-interactive-tree "Direct link to JSON Structure Viewer: interactive tree") [JSON Structure Viewer for Confluence](https://marketplace.atlassian.com/apps/1237254/json-structure-viewer-for-confluence) renders JSON as an interactive visual tree. Readers click nodes to expand and collapse, and use a toolbar to zoom and rotate. Use it when the JSON is too large or nested to read line-by-line and readers need to explore the shape of the data. ### When to use the tree view[​](#when-to-use-the-tree-view "Direct link to When to use the tree view") * A 500-line configuration file readers must navigate * Showing the hierarchical *shape* of a data model * Exploring an API response with many nested arrays To use it, install JSON Structure Viewer, type `/json` on a page, and paste your JSON. See the [JSON Structure Viewer docs](/docs/json-structure-viewer-for-confluence/usage.md). ## Comparison: which should you use?[​](#comparison-which-should-you-use "Direct link to Comparison: which should you use?") | Feature | Modern Code Blocks | JSON Structure Viewer | | ------------------------- | ----------------------------- | ---------------------------- | | **Render style** | Syntax-highlighted code | Interactive collapsible tree | | **Highlighting** | Monaco engine, 50+ themes | Color-coded keys/values | | **Line numbers** | Yes | No (tree view) | | **Copy button** | Yes | No | | **Zoom & rotate** | No | Yes | | **Expand/collapse nodes** | No (scroll instead) | Yes | | **Themes** | 50+ (Monokai, Dracula, …) | Dark/light auto | | **Diff view** | Yes (Advanced) | No | | **Other languages** | 85+ (YAML, SQL, Python, …) | JSON only | | **Best for** | API docs, snippets, most JSON | Large nested structures | For most Confluence pages — API docs, config examples, tutorials — **Modern Code Blocks is the better default** because readers want to copy the payload and read it with familiar IDE-style highlighting. Add JSON Structure Viewer when a structure is too large to read as text and readers need to explore it as a tree. ## Related resources[​](#related-resources "Direct link to Related resources") * [Modern Code Blocks — marketplace](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence) | [documentation](/apps/modern-code-blocks-for-confluence.md) * [JSON Structure Viewer — marketplace](https://marketplace.atlassian.com/apps/1237254/json-structure-viewer-for-confluence) | [documentation](/apps/json-structure-viewer-for-confluence.md) * [How to display and format JSON in Confluence](/blog/embed-json-confluence.md) — deeper how-to guide * [Advanced code blocks in Confluence](/blog/advanced-code-blocks-confluence.md) — themes, performance, diff view * [Best Confluence apps for developers](/blog/best-confluence-apps-developers.md) Try JSON Structure Viewer for Confluence Visualize JSON as interactive structure diagrams — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237254/json-structure-viewer-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=json-structure-viewer-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [json](/blog/tags/json.md) * [json-schema](/blog/tags/json-schema.md) * [api-documentation](/blog/tags/api-documentation.md) * [code-blocks](/blog/tags/code-blocks.md) --- # Enhanced Markdown vs Other Confluence Markdown Apps — Feature Matrix April 18, 2026 · 8 min read [NGPilot](https://ngpilot.com) Developers write in Markdown. Confluence doesn't. Every engineering team that moves from GitHub wikis, README files, or Hugo docs to Confluence hits the same wall — the rich text editor feels slow, and there's no way to write in the format they already know. Several marketplace apps bring Markdown to Confluence, but they take different approaches. Some embed Markdown as macros. Others import Markdown files. A few offer live editing. We built **Enhanced Markdown for Confluence** to give teams a full WYSIWYG Markdown editor with code highlighting, charts, UML diagrams, and table merging — all inside the Confluence page editor. In this post we compare it against every alternative. ## Three Approaches to Markdown in Confluence[​](#three-approaches-to-markdown-in-confluence "Direct link to Three Approaches to Markdown in Confluence") Before comparing apps, it helps to understand the three ways teams use Markdown in Confluence: **Macro-based rendering** — You insert a macro on the page, paste Markdown inside it, and the app renders it. The content lives inside the macro, not as native Confluence content. **File import** — You import a Markdown file from Git, disk, or URL. The app converts it to Confluence-native content. The Markdown source is gone — it becomes a regular Confluence page. **Live editing** — You write Markdown in an embedded editor with real-time preview. The content renders inline on the page. You keep the Markdown source and can re-edit it anytime. Our app uses the live editing approach. Let's see how the alternatives compare. ## What's Available on the Marketplace[​](#whats-available-on-the-marketplace "Direct link to What's Available on the Marketplace") Six apps bring Markdown to Confluence, plus our app launching soon: | App | Vendor | Installs | Rating | Last Updated | Hosting | Approach | | ------------------------------------ | ------------------- | --------------- | ------------------ | ------------ | ---------- | ----------------------- | | Just Add+ Embed Markdown | Modus Create | 8,871 | 3.5/5 (49 reviews) | Dec 2025 | Cloud | Git embed + inline | | Markdown for Confluence | Appfire | 2,274 | 2.8/5 (16 reviews) | Apr 2026 | Cloud + DC | Macro-based | | Markdown Exporter | Narva Software | 2,284 | 3.3/5 (20 reviews) | Dec 2025 | Cloud | Export only | | Markdown Importer & Editor | Narva Software Labs | 1,302 | 2.2/5 (5 reviews) | Mar 2026 | Cloud | Import + native editor | | Include from Bitbucket | Elevatic | 1,068 | 3.5/5 (19 reviews) | Apr 2026 | Cloud + DC | Git include | | Markdown Extensions | Appfire | 779 | 2.8/5 (22 reviews) | Apr 2026 | Cloud + DC | Macro + live preview | | **Enhanced Markdown for Confluence** | **NGPILOT** | **Coming soon** | — | **Apr 2026** | **Cloud** | **Live WYSIWYG editor** | *Data from Atlassian Marketplace, April 2026.* **Just Add+ by Modus Create** dominates with 8,871 installs. It's a versatile embed tool — pull Markdown, Mermaid, PlantUML, LaTeX, and more from Git repos or inline text. Cloud Fortified. But it's not primarily a Markdown editor — it's an embed tool that happens to support Markdown. **Appfire** has two entries: **Markdown for Confluence** (2,274 installs) with three macro types, and **Markdown Extensions** (779 installs) with a built-in editor and live preview. Both are Cloud Fortified. **Narva Software Labs** has two apps: an exporter (2,284 installs) and an importer/editor (1,302 installs) — but both carry below-average ratings (2.2 and 3.3 stars). **Elevatic's Include from Bitbucket** (1,068 installs) is specialized — it includes files from Bitbucket repos and renders them. Great if your docs live in Bitbucket. ## Feature Comparison[​](#feature-comparison "Direct link to Feature Comparison") | Feature | Enhanced Markdown (NGPILOT) | Just Add+ (Modus Create) | Markdown for Confluence (Appfire) | Markdown Extensions (Appfire) | Markdown Importer & Editor (Narva) | Include from Bitbucket (Elevatic) | | ------------------------------- | --------------------------- | ----------------------------- | --------------------------------- | ----------------------------- | ---------------------------------- | --------------------------------- | | **Live WYSIWYG editor** | Yes (Toast UI) | No | No | Yes | Yes (basic) | No | | **Markdown + Visual dual mode** | Yes | No | No | No | No | No | | **Code syntax highlighting** | Yes (dozens of languages) | Yes | No | No | No | Yes | | **Charts** | Yes | No | No | No | No | No | | **UML / PlantUML diagrams** | Yes | Yes | No | No | No | Yes | | **Table merged cells** | Yes | No | No | No | No | No | | **Color syntax with previews** | Yes | No | No | No | No | No | | **Import from Git repos** | No | Yes (GitHub/GitLab/Bitbucket) | No (App Links only) | Yes (Bitbucket/GitHub/GitLab) | No | Yes (Bitbucket only) | | **Import from file** | No | No | No | No | Yes | No | | **Import from URL** | No | Yes | Yes | No | No | No | | **LaTeX support** | No | Yes | No | No | No | No | | **AsciiDoc support** | No | Yes | No | No | No | Yes | | **Mermaid diagrams** | No | Yes | No | No | No | Yes | | **Dark mode** | Auto | No | No | No | No | No | | **Content stored as** | Macro (re-editable) | Macro | Macro | Macro | Native Confluence | Macro | | **Cloud Fortified** | No | Yes | Yes | Yes | No | Yes | | **Data Center support** | No | No | Yes | Yes | No | Yes | ### Where Enhanced Markdown Stands Out[​](#where-enhanced-markdown-stands-out "Direct link to Where Enhanced Markdown Stands Out") **WYSIWYG + Markdown dual mode** — The only app with a true dual-mode editor powered by Toast UI. Switch between writing raw Markdown and a visual editing experience. Other apps either render Markdown without editing, or offer a basic editor without a visual mode. **Charts in Markdown** — Embed charts directly in your Markdown content using chart syntax. No other Markdown editor app for Confluence supports inline chart rendering. **Table merged cells** — Go beyond standard Markdown tables with merged cells for complex layouts. Standard Markdown tables don't support merging — our editor does. **Color syntax with previews** — Write color values in Markdown and see them rendered with visual color previews. Useful for design documentation and style guides. **Code syntax highlighting** — Fenced code blocks render with syntax highlighting for dozens of programming languages. Same capability as Just Add+, but inside the editor instead of an embed tool. **Auto dark mode** — Content automatically adapts to Confluence's dark/light theme. No other Markdown editor app handles dark mode. ### Where We Could Improve[​](#where-we-could-improve "Direct link to Where We Could Improve") * **Not on marketplace yet** — Just Add+ has 8,871 installs and years of market presence. We're launching fresh. * **No Git integration** — Just Add+ and Include from Bitbucket pull content directly from GitHub, GitLab, and Bitbucket repos. Our app is for writing Markdown inside Confluence, not importing from Git. * **No LaTeX support** — Just Add+ renders LaTeX math equations. We don't support this yet. * **No Mermaid diagrams** — Several competitors render Mermaid diagrams. If you need Mermaid in Confluence, our separate [Mermaid Plus Diagrams & AI Agent for Confluence](/docs/Mermaid-Plus-for-Confluence/usage.md) app handles this with 30 diagram types and a dedicated editor. * **No AsciiDoc support** — Elevatic and Just Add+ support AsciiDoc alongside Markdown. * **No Data Center support** — Cloud-only. Appfire's apps and Elevatic serve both Cloud and DC. * **No Cloud Fortified status** — Just Add+ and both Appfire apps are Cloud Fortified. ## Honest Comparison: NGPILOT vs Just Add+ (Market Leader)[​](#honest-comparison-ngpilot-vs-just-add-market-leader "Direct link to Honest Comparison: NGPILOT vs Just Add+ (Market Leader)") Just Add+ Embed Markdown by Modus Create has 8,871 installs. Here's how we differ: | | Just Add+ (Modus Create) | Enhanced Markdown (NGPILOT) | | ---------------------- | ----------------------------------------------- | --------------------------------------------------- | | **Installs** | 8,871 | Coming soon | | **Rating** | 3.5/5 (49 reviews) | — | | **Approach** | Embed tool — pull from Git repos or inline text | Markdown editor — write and edit in Confluence | | **WYSIWYG editor** | No | Yes (Toast UI, dual mode) | | **Git integration** | Yes (GitHub, GitLab, Bitbucket) | No | | **Markdown rendering** | Yes | Yes | | **Code highlighting** | Yes | Yes | | **PlantUML** | Yes | Yes | | **Charts** | No | Yes | | **Table merging** | No | Yes | | **LaTeX** | Yes | No | | **Mermaid** | Yes | No | | **AsciiDoc** | Yes | No | | **Dark mode** | No | Yes (auto) | | **Cloud Fortified** | Yes | No | | **Best for** | Teams that keep docs in Git repos | Teams that want to write Markdown inside Confluence | These apps solve different problems. Just Add+ is for teams that author documentation in Git repositories and want to render it in Confluence. Our app is for teams that want to write in Markdown directly inside Confluence — with a proper editor, not just a render-then-forget approach. ## Which App Do You Need?[​](#which-app-do-you-need "Direct link to Which App Do You Need?") | You need... | Use this | | ------------------------------------------------------------ | ------------------------------------ | | Render Markdown from Git repos in Confluence | Just Add+ by Modus Create | | Include files from Bitbucket specifically | Include from Bitbucket by Elevatic | | Export Confluence pages to Markdown | Markdown Exporter by Narva | | Import Markdown files to native Confluence pages | Markdown Importer & Editor by Narva | | Simple macro-based Markdown rendering | Markdown for Confluence by Appfire | | Live Markdown editor with charts, UML, and dual-mode editing | **Enhanced Markdown for Confluence** | | Write docs in Markdown directly inside Confluence pages | **Enhanced Markdown for Confluence** | ## Related Posts[​](#related-posts "Direct link to Related Posts") * [Code Blocks for Confluence — Which Syntax Highlighting App Should You Choose?](/blog/code-blocks-confluence-monaco-editor.md) * [Google Fonts for Confluence — Which Custom Typography App Fits Your Team?](/blog/google-fonts-confluence-custom-typography.md) * [Numbered Headings for Confluence — Which Table of Contents App Fits Your Docs?](/blog/confluence-numbered-headings-comparison.md) * [Best Confluence Apps & Plugins in 2026 — Developer Tools Compared](/blog/best-confluence-apps-developers.md) ## Get Started[​](#get-started "Direct link to Get Started") * **Enhanced Markdown for Confluence** — Coming soon to the Atlassian Marketplace. [Read the docs](/docs/Enhanced-Markdown-for-Confluence/usage.md) Have questions or want early access? Reach out to us at — we'd love to hear from you. Try Enhanced Markdown for Confluence Write Markdown with live split preview, Mermaid diagrams, KaTeX/LaTeX math, and 190+ code languages — all in one macro, free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=enhanced-markdown-for-confluence) ## Related guides * [How to Write Markdown in Confluence](/blog/faq-confluence-markdown-editor.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [markdown](/blog/tags/markdown.md) * [markdown-editor](/blog/tags/markdown-editor.md) * [confluence](/blog/tags/confluence.md) * [wysiwyg](/blog/tags/wysiwyg.md) * [syntax-highlighting](/blog/tags/syntax-highlighting.md) * [plantuml](/blog/tags/plantuml.md) * [charts](/blog/tags/charts.md) * [confluence-markdown-editor](/blog/tags/confluence-markdown-editor.md) --- # Markdown Tables in Confluence — Syntax Reference & Alignment May 6, 2026 · 4 min read [NGPilot](https://ngpilot.com) Confluence has a visual table editor, but it's slow for creating structured tables — you need to click to add rows and columns one at a time. If you write documentation in Markdown, you can create tables much faster with Markdown syntax. This guide shows how to create, format, and edit tables in Confluence using Markdown. ## The problem with Confluence's native table editor[​](#the-problem-with-confluences-native-table-editor "Direct link to The problem with Confluence's native table editor") Confluence's built-in table editor requires multiple clicks: 1. Click the table button 2. Select the number of rows and columns 3. Click each cell to enter content 4. Use the toolbar to format alignment For developers and technical writers who already have data in Markdown format, this is tedious. You can't paste a Markdown table into the native editor — it won't render. ## Solution: Enhanced Markdown for Confluence[​](#solution-enhanced-markdown-for-confluence "Direct link to Solution: Enhanced Markdown for Confluence") [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?hosting=cloud\&tab=overview) adds full Markdown support including GitHub Flavored Markdown (GFM) tables. ### Basic Markdown table syntax[​](#basic-markdown-table-syntax "Direct link to Basic Markdown table syntax") ```` | Feature | Supported | Notes | |---------|-----------|-------| | Headings | Yes | H1–H6 | | Tables | Yes | GFM syntax | | Code blocks | Yes | Fenced with ``` | | Task lists | Yes | - [ ] and - [x] | ```` This renders as a formatted Confluence table with borders and padding. ### Table alignment[​](#table-alignment "Direct link to Table alignment") Control column alignment using colons in the separator row: ``` | Left aligned | Center aligned | Right aligned | |:-------------|:--------------:|--------------:| | Left | Center | Right | | Text | Text | Text | ``` * `:---` = left aligned (default) * `:---:` = center aligned * `---:` = right aligned ### How to create a Markdown table in Confluence[​](#how-to-create-a-markdown-table-in-confluence "Direct link to How to create a Markdown table in Confluence") 1. Install [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?hosting=cloud\&tab=overview) from the Marketplace (free for up to 10 users) 2. Open a Confluence page in edit mode 3. Type `/enhanced markdown` and select the macro 4. Write your table in Markdown syntax 5. Switch to WYSIWYG mode to see the rendered result 6. Save the page ### Copy tables from GitHub[​](#copy-tables-from-github "Direct link to Copy tables from GitHub") You can paste any Markdown table directly from GitHub READMEs, pull requests, or issues into the Enhanced Markdown editor. It renders correctly without any modification. This is especially useful for: * **API documentation** — paste parameter tables from spec files * **Changelog tables** — copy release notes from GitHub releases * **Comparison tables** — migrate feature comparison tables from Markdown docs * **Decision records** — paste pros/cons tables from architecture discussions ## Markdown tables vs Confluence tables[​](#markdown-tables-vs-confluence-tables "Direct link to Markdown tables vs Confluence tables") | Feature | Native Table | Markdown Table | | ------------------------ | ------------------ | ----------------- | | Creation speed | Slow (click-based) | Fast (type-based) | | Copy from GitHub | No | Yes | | Version control friendly | No | Yes (plain text) | | Alignment control | Toolbar clicks | `:---` syntax | | Merge cells | Yes | No | | Row/column span | Yes | No | | Background colors | Yes | No | Markdown tables are ideal for structured data where every row has the same columns. For complex layouts with merged cells, use the native Confluence table editor. ## Markdown table tips[​](#markdown-table-tips "Direct link to Markdown table tips") **Keep columns narrow** — wide tables are hard to read in raw Markdown. Use abbreviations or short headers. **Use alignment for numbers** — right-align numeric columns for better readability: ``` | Metric | Q1 | Q2 | Q3 | |--------|---:|---:|---:| | Revenue | 120 | 145 | 178 | | Users | 1,200 | 1,500 | 2,000 | ``` **Link in tables** — you can include links in table cells: ``` | App | Documentation | |-----|---------------| | Mermaid Plus | [Docs](/docs/Mermaid-Plus-for-Confluence/usage) | | Code Blocks | [Docs](/docs/Modern-Code-Blocks-for-Confluence/user-docs) | ``` ## Related resources[​](#related-resources "Direct link to Related resources") * [Enhanced Markdown — marketplace](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?hosting=cloud\&tab=overview) | [documentation](/apps/enhanced-markdown-for-confluence.md) * [How to write Markdown in Confluence](/blog/how-to-write-markdown-in-confluence.md) * [Confluence Markdown vs WYSIWYG FAQ](/blog/faq-confluence-markdown-vs-wysiwyg.md) * [Confluence Markdown editor FAQ](/blog/faq-confluence-markdown-editor.md) * [Confluence Markdown editor comparison](/blog/confluence-markdown-editor-comparison.md) Try Enhanced Markdown for Confluence Write Markdown with live split preview, Mermaid diagrams, KaTeX/LaTeX math, and 190+ code languages — all in one macro, free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=enhanced-markdown-for-confluence) ## Related guides * [How to Write Markdown in Confluence](/blog/faq-confluence-markdown-editor.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [tables](/blog/tags/tables.md) * [formatting](/blog/tags/formatting.md) * [enhanced-markdown](/blog/tags/enhanced-markdown.md) --- # Monospace in Confluence: How to Format Inline Code (Shortcuts & Markdown) October 1, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Select the text and press **Ctrl+Shift+M** (Windows) or **Opt+Shift+M** (Mac) to apply inline code, or type `` `backticks` `` around text as you write — the Confluence Cloud editor autoformats them. Pasted Markdown keeps its backticks as literal characters, so paste into [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence/) instead, which renders inline code, code blocks, and diagrams from your Markdown source. Inline code — monospace text on a subtle background — is how you mark up variable names, file paths, key names, and short commands inside a sentence: set `MAX_RETRIES = 3`, edit `~/.zshrc`, or run `kubectl get pods`. Confluence Cloud has three ways to produce it, and each fits a different moment: formatting as you go, typing Markdown, or bringing Markdown in from your repo. What you'll learn 1. The keyboard shortcut — Ctrl+Shift+M, and the Mac split between Opt+Shift+M and Cmd+Shift+M 2. Backtick autoformatting while you type 3. The Markdown method for pasted content (Enhanced Markdown) 4. Inline code vs code block — which one to use where ## Method 1: the keyboard shortcut (standard editor)[​](#method-1-the-keyboard-shortcut-standard-editor "Direct link to Method 1: the keyboard shortcut (standard editor)") 1. Select the text you want in monospace. 2. Press **Ctrl+Shift+M** (Windows/Linux) or **Opt+Shift+M** (Mac). The selection turns into inline code immediately — press the shortcut again to toggle it off. The same style is in the toolbar: select text, open the text formatting menu, and pick **Code**. One Mac quirk worth knowing: Atlassian lists **two** code shortcuts. **Opt+Shift+M** applies *inline code* to a selection (text formatting), while **Cmd+Shift+M** creates a *code block* (block formatting). If you wanted a highlighted snippet and got a whole code section instead — or the reverse — that's the split you hit. On Windows both are Ctrl+Shift+M. To see the full shortcut list on your site, press **Ctrl+/** (**Cmd+/** on Mac) while editing. ## Method 2: backtick autoformatting while you type[​](#method-2-backtick-autoformatting-while-you-type "Direct link to Method 2: backtick autoformatting while you type") The Confluence Cloud editor parses a set of Markdown shortcuts as you type, and inline code is one of them: type a backtick, the text, and a closing backtick, and it converts to inline code on the closing tick — the same mechanic as `**bold**`, `*italic*`, and `~~strikethrough~~`. ``` Type this: `MAX_RETRIES` Get this: MAX_RETRIES in inline code style ``` This is the fastest method if your hands are already on the keyboard — no selection, no menu. The catch: autoformatting only runs **while typing**. It is not a paste converter. ## Method 3: pasted Markdown (Enhanced Markdown)[​](#method-3-pasted-markdown-enhanced-markdown "Direct link to Method 3: pasted Markdown (Enhanced Markdown)") If your content starts life as Markdown — a README, a runbook, an architecture doc with inline code, fenced code blocks, and diagrams — pasting it into the standard editor lands every backtick as a literal character. Retyping them works for one sentence, not for a 200-line document. [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence/) takes the paste directly: inline code, fenced code blocks with syntax highlighting, tables, math, and Mermaid diagrams all render from the pasted source, and the Markdown stays re-editable on the page — fix a variable name by editing the line, not by re-importing. The full syntax coverage is in the [user guide](/docs/Enhanced-Markdown-for-Confluence/usage.md). ## Inline code vs code block — which one where[​](#inline-code-vs-code-block--which-one-where "Direct link to Inline code vs code block — which one where") | | Inline code | Code block | | ------------------- | ----------------------------------------- | -------------------------------------------------------------------------------- | | Shortcut | Ctrl+Shift+M / Opt+Shift+M | Cmd+Shift+M (Mac) / Ctrl+Shift+M (Win) | | Markdown | `` `one tick` `` | ` ``` ` fences | | Use for | variables, paths, keys, one-line commands | multiline snippets, config files, scripts | | Syntax highlighting | no | yes (190+ languages in [Markdown apps](/blog/markdown-code-block-confluence.md)) | | Line breaks | no — collapses with the sentence | preserved | Rule of thumb: if it fits inside a sentence, inline code. If it needs its own lines, a code block. ## Styling limits (and what apps add)[​](#styling-limits-and-what-apps-add "Direct link to Styling limits (and what apps add)") Native inline code has exactly one style: monospace font, light background, no options. There is no theme, no per-space color, no size control — and no way to add a second emphasis level next to bold and italic. If pages need styled code at the block level — themes, custom colors, highlighted lines — [Modern Code Blocks](/docs/Modern-Code-Blocks-for-Confluence/user-docs.md) handles that; inline code stays native either way. For teams living in Markdown, [Enhanced Markdown](/apps/enhanced-markdown-for-confluence.md) covers the paste path described above. And if what you actually want is a colored label rather than code — a chip that says *In review* or *Deprecated* — Confluence's native status element (type `/status`) is the closer tool. ## Related guides[​](#related-guides "Direct link to Related guides") * [How to make text bold in Confluence](/blog/bold-text-confluence.md) — the sibling text-formatting shortcut and `**bold**` syntax * [Markdown code blocks in Confluence](/blog/markdown-code-block-confluence.md) — fenced blocks, highlighting, and themes * [How to write Markdown in Confluence](/blog/faq-confluence-markdown-editor.md) — the full syntax the editor supports * [Paste Mermaid diagrams into Confluence](/blog/paste-mermaid-diagrams-into-confluence.md) — the repo-Markdown paste workflow, end to end ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [formatting](/blog/tags/formatting.md) * [markdown](/blog/tags/markdown.md) * [monospace](/blog/tags/monospace.md) * [inline-code](/blog/tags/inline-code.md) * [enhanced-markdown](/blog/tags/enhanced-markdown.md) * [keyboard-shortcuts](/blog/tags/keyboard-shortcuts.md) --- # Best Numbered Headings App for Confluence — 2026 Comparison April 18, 2026 · 7 min read [NGPilot](https://ngpilot.com) Long Confluence pages need structure. When your documentation runs past ten headings, readers lose track of where they are. Numbered headings — like "1. Introduction", "1.1 Background", "2. Methods" — give every section a clear position in the hierarchy. Technical docs, legal documents, SOPs, and compliance reports all rely on them. Confluence doesn't number headings out of the box. A handful of marketplace apps fill this gap, but the market is small — Appfire's **Numbered Headings** dominates with 5,484 installs. We built **Modern Numbered Headings for Confluence** to bring a fresh approach with live preview, one-click TOC insertion, and five numbering styles. In this post we compare it against the alternatives. ## Why You Need Numbered Headings[​](#why-you-need-numbered-headings "Direct link to Why You Need Numbered Headings") If your team writes any of these in Confluence, numbered headings help: * **Technical documentation** — API references, architecture docs, runbooks * **Standard operating procedures** — Step-by-step processes that need clear section references * **Legal and compliance documents** — Contract sections, policy chapters, audit reports * **Training materials** — Course outlines, onboarding guides * **Meeting notes and proposals** — Structured documents shared with stakeholders Without numbered headings, you get "see the section about authentication" instead of "see Section 3.2." The second is precise. The first is ambiguous. ## What's Available on the Marketplace[​](#whats-available-on-the-marketplace "Direct link to What's Available on the Marketplace") Only five apps do numbered headings for Confluence. The market is concentrated: | App | Vendor | Installs | Rating | Last Updated | Hosting | | ------------------------------------------- | -------------------- | --------------- | ------------------- | ------------ | ----------- | | Numbered Headings | Appfire | 5,484 | 3.6/5 (113 reviews) | Mar 2026 | Cloud | | Numbered Headings for Confluence | Kolekti (Adaptavist) | 290 | 4.0/5 (1 review) | Apr 2026 | Cloud | | Easy Numbered Headings | Appfire | 272 | 3.3/5 (12 reviews) | Apr 2026 | Cloud + DC | | Numbered Headings (easily number) | Easy Apps | 44 | — | Sep 2025 | Cloud | | Auto Numbered Headings | Hivestone | 37 | 4.0/5 (4 reviews) | Jan 2026 | DC + Server | | **Modern Numbered Headings for Confluence** | **NGPILOT** | **Coming soon** | — | **Apr 2026** | **Cloud** | *Data from Atlassian Marketplace, April 2026.* **Appfire dominates** with two apps totaling 5,756 installs. Their original **Numbered Headings** (5,484 installs) is the clear market leader — Cloud Fortified, bug bounty program, 113 reviews. But it requires macros on every page. **Easy Numbered Headings** (also Appfire) takes a different approach — no macros needed, it works automatically. But only 272 installs suggest it hasn't caught on despite the Appfire brand. **Kolekti/Adaptavist's** entry (290 installs) recently migrated from Connect to Forge — a modern architecture choice but very early adoption. **Hivestone's Auto Numbered Headings** (37 installs) is the only option for Data Center/Server teams who want numbering beyond just headings (it also numbers tables and images). But no Cloud version. ## Feature Comparison[​](#feature-comparison "Direct link to Feature Comparison") | Feature | Modern Numbered Headings (NGPILOT) | Numbered Headings (Appfire) | Easy Numbered Headings (Appfire) | Numbered Headings (Kolekti/Adaptavist) | Numbered Headings (Easy Apps) | | ---------------------------- | ---------------------------------------------- | ----------------------------------------------- | --------------------------------- | -------------------------------------- | ----------------------------- | | **Numbering styles** | 5 (Decimal, Roman, Alphabetic, Outline, Mixed) | Multiple (decimal, Roman, Latin, Greek, custom) | Custom patterns (e.g. "1-A.4(a)") | Standard | Standard | | **No macro needed** | Yes | No (macro required) | Yes | No | Yes | | **Live preview** | Yes | No | No | No | No | | **One-click insert** | Yes | No | Yes | No | Yes | | **One-click remove** | Yes (smart detection) | No | Yes | No | Yes | | **Heading level filtering** | Yes (H1-H6 customizable) | Yes | Yes | Yes | Yes | | **Hierarchical indentation** | Yes | No | No | No | No | | **Mobile responsive** | Yes | No | No | No | No | | **PDF/Word export support** | No | Yes | Yes | No | No | | **Table/image numbering** | No | No | No | No | No (but Hivestone does) | | **Forge-based** | Yes | No (Connect) | No (Connect) | Yes | Yes | | **Cloud Fortified** | No | Yes | Yes | No | Yes | | **Data Center support** | No | No | Yes | No | No | ### Where Modern Numbered Headings Stands Out[​](#where-modern-numbered-headings-stands-out "Direct link to Where Modern Numbered Headings Stands Out") **Live preview** — See your numbered headings update in real-time as you change styles and settings. No other app offers a live preview. With competitors, you configure a macro, save the page, and check if it looks right. If not, edit the macro again. **Five professional numbering styles** — Decimal (1, 1.1, 1.1.1), Roman (I, I.I, I.I.I), Alphabetic (A, A.A, A.A.A), Outline (1., 1.A., 1.A.i), and Mixed (combinations). Covers every standard document format. **One-click TOC with smart removal** — Insert a complete table of contents with one click. Remove it with one click. The app uses smart detection ("magic markers") to find and clean up its own TOC without leaving artifacts. **Hierarchical indentation** — Indent sub-headings to visualize the document structure. Makes long documents scannable at a glance. **No macros** — Unlike Appfire's market leader, you don't place a macro on every page. The app generates the TOC directly, which means fewer page edits and less maintenance. **Mobile responsive** — The TOC works on every screen size. Your documentation is readable on phones and tablets, not just desktop browsers. **Forge-based architecture** — Built on Atlassian's modern Forge platform. Runs entirely within Atlassian's infrastructure — no external servers, no data leaving the Atlassian ecosystem. ### Where We Could Improve[​](#where-we-could-improve "Direct link to Where We Could Improve") * **Not on marketplace yet** — We're preparing for launch. Appfire's apps have a combined 14+ years of market presence. * **No PDF/Word export integration** — Appfire's Numbered Headings integrates with Confluence's PDF and Word export so numbering is preserved in exported documents. Our app doesn't support this yet. * **No Data Center support** — Cloud-only. If you're on Confluence Data Center, Easy Numbered Headings by Appfire or Auto Numbered Headings by Hivestone are your options. * **No Cloud Fortified status** — Appfire's apps are Cloud Fortified. We're working toward this. * **No custom numbering patterns** — Easy Numbered Headings supports complex patterns like "1-A.4(a)". We offer five preset styles but not freeform patterns. * **No table/image numbering** — Only Hivestone's app offers numbering beyond headings (tables, images), but it's DC-only. ## Honest Comparison: NGPILOT vs Appfire (Market Leader)[​](#honest-comparison-ngpilot-vs-appfire-market-leader "Direct link to Honest Comparison: NGPILOT vs Appfire (Market Leader)") Appfire's **Numbered Headings** has 5,484 installs and years of development. Here's how we differ: | | Numbered Headings (Appfire) | Modern Numbered Headings (NGPILOT) | | ----------------------------- | ------------------------------------ | ------------------------------------------ | | **Installs** | 5,484 | Coming soon | | **Rating** | 3.6/5 (113 reviews) | — | | **Approach** | Macro-based — add macro to each page | One-click TOC generation | | **Live preview** | No | Yes | | **Mobile responsive** | No | Yes | | **PDF/Word export** | Yes | No | | **Custom numbering patterns** | Yes | No (5 preset styles) | | **Numbering formats** | Decimal, Roman, Latin, Greek, custom | Decimal, Roman, Alphabetic, Outline, Mixed | | **Cloud Fortified** | Yes | No | | **Architecture** | Connect | Forge | | **Best for** | Teams that need export integration | Teams that want fast, visual TOC creation | Appfire's app is the right choice if you need numbering preserved in PDF/Word exports or want highly customized numbering patterns. It's proven and reliable. Our app is for teams that want a simpler experience — click to add a TOC, see it live, pick a style, done. No macros to maintain, no configuration pages. The live preview and one-click workflow save time on every document. ## Which App Do You Need?[​](#which-app-do-you-need "Direct link to Which App Do You Need?") | You need... | Use this | | -------------------------------------------- | ------------------------------------------------------------------------ | | The established, proven option | Numbered Headings by Appfire | | Numbering preserved in PDF/Word exports | Numbered Headings by Appfire | | Automatic numbering without macros | Easy Numbered Headings by Appfire | | Data Center support | Easy Numbered Headings by Appfire or Auto Numbered Headings by Hivestone | | Number tables and images (not just headings) | Auto Numbered Headings by Hivestone (DC only) | | Live preview and one-click TOC generation | **Modern Numbered Headings for Confluence** | | Mobile-responsive table of contents | **Modern Numbered Headings for Confluence** | ## Related Posts[​](#related-posts "Direct link to Related Posts") * [Code Blocks for Confluence — Which Syntax Highlighting App Should You Choose?](/blog/code-blocks-confluence-monaco-editor.md) * [Markdown Editor for Confluence — Which App Should You Choose for Writing Docs?](/blog/confluence-markdown-editor-comparison.md) ## Get Started[​](#get-started "Direct link to Get Started") * **Modern Numbered Headings for Confluence** — Coming soon to the Atlassian Marketplace. [Read the docs](/docs/Modern-Numbered-Headings-for-Confluence/user-docs.md) Have questions or want early access? Reach out to us at — we'd love to hear from you. ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [numbered-headings](/blog/tags/numbered-headings.md) * [table-of-contents](/blog/tags/table-of-contents.md) * [confluence](/blog/tags/confluence.md) * [documentation](/blog/tags/documentation.md) * [toc](/blog/tags/toc.md) * [heading-numbering](/blog/tags/heading-numbering.md) --- # Confluence Pagination: How to Paginate Pages and Tables (3 Methods) October 4, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Confluence Cloud has no built-in pagination — pages render as one long scroll and tables render every row. The three working approaches: **split long content into a page series** and connect the parts with Previous/Next buttons ([Pagination Buttons for Confluence](https://marketplace.atlassian.com/apps/1237371/pagination-buttons-for-confluence/)), **chunk in-page** with tabs or expand sections, or **restructure** so the long table becomes linked category pages. What Confluence does paginate natively is search results and API responses — not your content. A 4,000-word runbook. A 300-row release checklist. A training doc with five chapters. Sooner or later every Confluence space hits the wall: the page that takes forever to scroll, buries the section the reader needs, and times out in the editor when someone tries to reorganize it. Pagination is the standard fix everywhere else on the web — and Confluence doesn't have it, a gap the community has flagged since 2018. Here's what actually works instead. What you'll learn 1. What Confluence paginates natively (search, API) and what it doesn't (pages, tables) 2. Method 1 — split into a page series with Prev/Next buttons 3. Method 2 — chunk in-page with tabs and expand sections 4. Method 3 — restructure long tables instead of paginating them ## What Confluence paginates natively (and what it doesn't)[​](#what-confluence-paginates-natively-and-what-it-doesnt "Direct link to What Confluence paginates natively (and what it doesn't)") | Content type | Paginated natively? | What you get instead | | ------------------ | ------------------- | ------------------------------------------- | | Search results | yes | paged result list | | REST API responses | yes | `limit` + cursor paging | | A published page | **no** | one long scroll | | Tables | **no** | all rows render; sorting and filtering only | | Blog posts macro | partially | shows the most recent N posts | The rest of this post is about the two **no** rows. ## Method 1: page series with Previous/Next buttons (best for guides and runbooks)[​](#method-1-page-series-with-previousnext-buttons-best-for-guides-and-runbooks "Direct link to Method 1: page series with Previous/Next buttons (best for guides and runbooks)") The document-style fix: each chapter becomes its own page, and readers page through with ‹ Prev | Next › controls at the bottom — the same pattern as this article series or a book. 1. **Split at natural boundaries.** Break the long page into chapters. Create child pages under the parent (page tree → move), so the series stays organized and each part gets its own URL and search entry. 2. **Leave a hub on the parent page.** A short intro plus a table of contents linking every part. Anyone landing on the old URL still finds the whole series. 3. **Add [Pagination Buttons for Confluence](https://marketplace.atlassian.com/apps/1237371/pagination-buttons-for-confluence/)** — type `/pagination`, then paste the previous and next page URLs in the macro config. Button style is symbol or text; layout options include center and space-between so the pair sits at the edges of the content, the way readers expect. 4. **Repeat per page.** First page gets only a Next URL; last page only a Previous. Why this beats one long page: each part loads fast, gets its own search result, and comments stay scoped to the section they're about. The cost is maintenance — inserting a chapter means re-numbering and re-wiring the buttons around it. Series that change weekly are better off as Method 2. ## Method 2: in-page chunking with tabs and expand (best for content that stays one page)[​](#method-2-in-page-chunking-with-tabs-and-expand-best-for-content-that-stays-one-page "Direct link to Method 2: in-page chunking with tabs and expand (best for content that stays one page)") When the content belongs together — reference material, an FAQ, a spec — keep one page and hide the bulk behind interaction: * **Tabs** separate modes or audiences: a Setup / Usage / Troubleshooting split reads as three short pages. Details and comparisons in [Tabs in Confluence](/blog/confluence-tabs-macro.md). * **Expand sections** hide long sub-blocks behind a one-line title — the pattern Atlassian's own docs use. Details in [Expand macro for Confluence](/blog/confluence-expand-macro.md). Both are native-capable (expand is built in; tabs come from a template or a macro). The limit: they paginate *attention*, not *rendering* — everything is still on the page and in the export. For a 300-row table no amount of collapsing helps; that's Method 3. ## Method 3: long tables — restructure instead of paginate[​](#method-3-long-tables--restructure-instead-of-paginate "Direct link to Method 3: long tables — restructure instead of paginate") There is no way to paginate a native Confluence table today. The working patterns: | Pattern | How | Good fit | | ----------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------- | | Split by category | one child page per category, parent links them | reference tables (people, endpoints, flags) | | Summarize on top | 10-row "current status" table up top, full archive table below (or in a collapsed expand) | trackers, checklists | | Page series | Method 1, one table-part per page | archives that grow append-only | | Sort + filter | native table sorting/filtering | finding a row, not reducing the page | The summarize-on-top pattern is the highest-value one: readers who need "where are we now" get a fast answer, and the archive stays in place for the few who need it. ## What about the REST API?[​](#what-about-the-rest-api "Direct link to What about the REST API?") If you landed here writing an integration: Confluence's API paginates with a `limit` parameter and cursor-based `_links.next` URLs — see [Atlassian's REST API pagination docs](https://developer.atlassian.com/cloud/confluence/rest/intro/). That governs API responses only; it doesn't change what readers see on a page. ## Related guides[​](#related-guides "Direct link to Related guides") * [Tabs in Confluence](/blog/confluence-tabs-macro.md) — native layout tabs vs tab macros * [Expand macro for Confluence](/blog/confluence-expand-macro.md) — collapsible sections, native vs styled * [How to add a block quote in Confluence](/blog/block-quote-confluence.md) — formatting long-form content * [Pagination Buttons for Confluence](/apps/pagination-buttons-for-confluence.md) — the Prev/Next macro used in Method 1 ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [pagination](/blog/tags/pagination.md) * [macros](/blog/tags/macros.md) * [formatting](/blog/tags/formatting.md) * [page-structure](/blog/tags/page-structure.md) * [how-to](/blog/tags/how-to.md) --- # Confluence Permissions: The Ultimate Guide (2026) July 30, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Confluence permissions control who can view, edit, and administer content. You manage permissions at three levels: **site admin** (global), **space admin** (space-level), and **page restrictions** (page-level). Understanding the inheritance hierarchy is key — lower-level settings always override higher-level ones. ## What Are Confluence Permissions?[​](#what-are-confluence-permissions "Direct link to What Are Confluence Permissions?") Confluence permissions are access controls that determine what actions users can perform on content. Without proper permission management, teams risk exposing sensitive information or blocking collaboration. Confluence has three permission layers: | Level | Controls | Managed By | | --------------------- | ------------------------------------------- | ------------------------- | | **Site admin** | Global permissions, app access, user groups | Site admins | | **Space admin** | Space-level view/edit/admin permissions | Space admins | | **Page restrictions** | Individual page view/edit access | Page owners, space admins | *** ## Site Admin Permissions (Global)[​](#site-admin-permissions-global "Direct link to Site Admin Permissions (Global)") Site admins control global access through **Global Permissions**. This is the highest level of permission control. ### How to Access Global Permissions[​](#how-to-access-global-permissions "Direct link to How to Access Global Permissions") 1. Click your profile icon → **Administration** 2. Navigate to **User Management** → **Groups** 3. Select **Global Permissions** ### Global Permission Groups[​](#global-permission-groups "Direct link to Global Permission Groups") | Group | Purpose | Default Members | | --------------------- | --------------------------- | -------------------- | | `site-admins` | Full site control | Manual assignment | | `confluence-admins` | Confluence-specific admin | Manual assignment | | `confluence-users` | Basic access to Confluence | All registered users | | `confluence-ex-users` | Users with expired licenses | Auto-populated | ### Key Global Permissions[​](#key-global-permissions "Direct link to Key Global Permissions") * **Confluence Administrator**: Access admin console, manage users, configure apps * **System Administrator**: Full system control (including non-Confluence settings) * **Can Use**: Basic access to log in and use Confluence *** ## Space Admin Permissions[​](#space-admin-permissions "Direct link to Space Admin Permissions") Space admins control permissions within individual spaces. Every space has at least one space admin. ### How to Manage Space Permissions[​](#how-to-manage-space-permissions "Direct link to How to Manage Space Permissions") 1. Go to the space → **Space Settings** → **Permissions** 2. Add/remove users or groups 3. Set view, edit, and admin permissions ### Space Permission Types[​](#space-permission-types "Direct link to Space Permission Types") | Permission | What It Allows | | ---------- | ------------------------------------- | | **View** | See the space and its pages | | **Edit** | Create and modify pages | | **Add** | Attach files and comments | | **Delete** | Remove pages and attachments | | **Admin** | Manage space settings and permissions | ### Inheritance Rules[​](#inheritance-rules "Direct link to Inheritance Rules") Permissions follow a hierarchy: ``` Site Admin → Space Admin → Page Restrictions ``` **Lower-level settings always win.** If a page restriction denies access, it overrides space-level grants. *** ## Page Restrictions[​](#page-restrictions "Direct link to Page Restrictions") Page restrictions let you control access to specific pages without changing space permissions. ### Two Types of Restrictions[​](#two-types-of-restrictions "Direct link to Two Types of Restrictions") | Restriction | Effect | | -------------------- | -------------------------------------- | | **View restriction** | Only specified users can view the page | | **Edit restriction** | Only specified users can edit the page | ### How to Restrict a Page[​](#how-to-restrict-a-page "Direct link to How to Restrict a Page") 1. Open the page 2. Click **More actions** (⋯) → **Restrictions** 3. Add users or groups to the view or edit restriction list ### Key Behaviors[​](#key-behaviors "Direct link to Key Behaviors") * Restrictions apply to the page **and all child pages** * Only page owners, space admins, or users with "Admin" permission can set restrictions * Restricted pages appear in search results but cannot be accessed by unauthorized users *** ## Permission Inheritance Explained[​](#permission-inheritance-explained "Direct link to Permission Inheritance Explained") Inheritance is the most confusing part of Confluence permissions. Here's the complete picture: ### The Inheritance Hierarchy[​](#the-inheritance-hierarchy "Direct link to The Inheritance Hierarchy") ``` 1. Global Permissions (site-wide) ↓ 2. Space Permissions (space-level) ↓ 3. Page Restrictions (page-level) ``` ### How Inheritance Works[​](#how-inheritance-works "Direct link to How Inheritance Works") | Scenario | Result | | --------------------------------------------------------------- | ------------------------------------ | | User has view permission at all levels | ✅ Can view | | User has view permission at space level, but page is restricted | ❌ Cannot view | | User is in a denied group at space level | ❌ Cannot view (even if page allows) | | User has no explicit permission at any level | ❌ Cannot view | ### Common Gotchas[​](#common-gotchas "Direct link to Common Gotchas") 1. **"Everyone" group**: Adding "Everyone" to space permissions grants access to all logged-in users 2. **Group membership**: Users inherit permissions from all groups they belong to 3. **Restriction scope**: Page restrictions cascade to child pages 4. **Space key in URL**: Users can see the space key in URLs even if they can't access content *** ## Troubleshooting Permission Issues[​](#troubleshooting-permission-issues "Direct link to Troubleshooting Permission Issues") ### "I can't see a page"[​](#i-cant-see-a-page "Direct link to \"I can't see a page\"") Check these in order: 1. **Global permissions**: Are you in `confluence-users`? 2. **Space permissions**: Does your group have "View" permission? 3. **Page restrictions**: Is the page restricted to specific users? ### "I can't edit a page"[​](#i-cant-edit-a-page "Direct link to \"I can't edit a page\"") 1. **Space permissions**: Does your group have "Edit" permission? 2. **Page restrictions**: Is edit access restricted? 3. **Page status**: Is the page archived or locked? ### "I'm a space admin but can't change permissions"[​](#im-a-space-admin-but-cant-change-permissions "Direct link to \"I'm a space admin but can't change permissions\"") * Verify you're a **space admin**, not just a content creator * Check if the space is a **archived space** (permissions are frozen) *** ## Best Practices[​](#best-practices "Direct link to Best Practices") 1. **Use groups, not individuals**: Assign permissions to groups for easier management 2. **Limit page restrictions**: Overusing restrictions creates maintenance overhead 3. **Audit regularly**: Review permissions quarterly to remove stale access 4. **Document exceptions**: Keep a log of any permission overrides for compliance 5. **Test in production**: Use the "Impersonate" feature (site admins) to verify access *** ## Frequently Asked Questions[​](#frequently-asked-questions "Direct link to Frequently Asked Questions") **What's the difference between site admin and space admin?** Site admins control global settings and user access. Space admins control permissions within individual spaces. A space admin cannot modify global permissions. **Can I restrict a page without affecting child pages?** No. Page restrictions cascade to all child pages. You must manage each child page individually if you need different access. **What happens when a user is removed from a group?** They lose all permissions inherited from that group. Existing page restrictions they set remain (if they were page owners). **Can I see who has access to a page?** Yes. Go to **Page Restrictions** → **Who can see this?** to view the effective permission list. **How do I transfer page ownership?** Edit the page → **More actions** → **Page History** → **Take Ownership** (requires space admin permission). *** ## Related Guides[​](#related-guides "Direct link to Related Guides") * [Best Confluence Apps for Developers (2026)](/blog/best-confluence-apps-developers.md) * [Confluence Markdown Editor Comparison](/blog/confluence-markdown-editor-comparison.md) * [Confluence Import & Export Comparison](/blog/confluence-import-export-comparison.md) * [Code Blocks in Confluence: Monaco Editor Guide](/blog/code-blocks-confluence-monaco-editor.md) *** *This guide is part of our Confluence admin series. Bookmark it for reference.* ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [confluence-admin](/blog/tags/confluence-admin.md) * [permissions](/blog/tags/permissions.md) * [security](/blog/tags/security.md) * [atlassian](/blog/tags/atlassian.md) --- # QR Code for Confluence — Which QR App Should Your Team Use? April 18, 2026 · 5 min read [NGPilot](https://ngpilot.com) Teams print Confluence page links on posters, equipment labels, desk signs, and handouts. A QR code on a physical object that links to the relevant Confluence page saves everyone from typing long URLs. It's a small thing that removes friction in offices, warehouses, and events. But Confluence has no built-in QR code generation. A handful of marketplace apps fill this niche — it's a small market with roughly 130 total installs across all apps. We built **QRCode for Confluence** to let teams embed QR codes directly into pages with a simple `/qrcode` slash command. In this post we compare it against the alternatives. ## Use Cases for QR Codes in Confluence[​](#use-cases-for-qr-codes-in-confluence "Direct link to Use Cases for QR Codes in Confluence") * **Equipment and asset labels** — Stick a QR code on a server rack or office printer. Scan it to open the Confluence page with specs, instructions, or support info. * **Event handouts** — Print QR codes on conference materials that link to detailed session notes or documentation. * **Office signage** — Put QR codes on meeting room doors linking to booking pages or room policies. * **Onboarding materials** — New hires scan codes on their desk to open IT setup guides, team wikis, or HR resources. * **Warehouse and inventory** — QR codes on shelves link to inventory procedures or safety docs. ## What's Available on the Marketplace[​](#whats-available-on-the-marketplace "Direct link to What's Available on the Marketplace") Only five apps generate QR codes for Confluence. The market is tiny: | App | Vendor | Installs | Rating | Last Updated | Hosting | Price (50 users/yr) | | ------------------------- | ----------- | -------- | ----------------- | ------------ | --------- | ------------------- | | qr2page | Seibert | 71 | 3.5/5 (2 reviews) | Mar 2026 | Cloud | $50 | | Barcodes for Confluence | codalyx | 38 | 3.5/5 (4 reviews) | Mar 2026 | DC only | $125 | | QR Code Generator | Atlas Inc. | 13 | 3.0/5 (1 review) | Apr 2018 | Cloud | $150 | | Moves QR Generator | Dmove | 6 | — | Sep 2025 | Cloud | Free | | **QRCode for Confluence** | **NGPILOT** | **2** | — | **Apr 2025** | **Cloud** | **$75** | *Data from Atlassian Marketplace, April 2026.* This is one of the smallest app categories on the marketplace. No app has crossed 100 installs. None are Cloud Fortified. **Seibert's qr2page** (71 installs) leads — from the same vendor behind draw\.io and Templating.app. It generates QR codes from the page menu for printing, focused on physical-to-digital bridging. **Barcodes for Confluence** by codalyx (38 installs) is the only Data Center option and supports multiple barcode formats beyond QR codes. Most reviewed app in this category (4 reviews). **Atlas Inc.'s QR Code Generator** (13 installs) was last updated in **April 2018** — effectively abandoned after 8 years. Still listed and still charging $150/yr. **Moves QR Generator** by Dmove (6 installs) is the only completely free option but has minimal adoption. ## Feature Comparison[​](#feature-comparison "Direct link to Feature Comparison") | Feature | QRCode for Confluence (NGPILOT) | qr2page (Seibert) | Barcodes for Confluence (codalyx) | QR Code Generator (Atlas) | Moves QR Generator (Dmove) | | --------------------------- | ------------------------------- | ------------------- | --------------------------------- | ------------------------- | -------------------------- | | **Slash command** | Yes (`/qrcode`) | No | No | No | No | | **Inline embed in page** | Yes (macro on page) | No (page menu only) | Yes (macro) | Yes (macro) | Yes | | **Encode any text/URL** | Yes | No (page URL only) | Yes | Yes | Yes | | **Customizable sizes** | 5 (XS to XL) | No | No | No | No | | **QR code format** | Yes | Yes | Yes | Yes | Yes | | **Other barcode formats** | No | No | Yes (multiple) | No | No | | **Generate from page menu** | No | Yes | No | No | No | | **Print-focused** | No | Yes | No | No | No | | **Free tier** | Yes (10 users) | Yes (10 users) | Yes (10 users) | No ($10/yr min) | Yes (fully free) | | **Actively maintained** | Yes (2025) | Yes (2026) | Yes (2026) | **No (2018)** | Limited (2025) | | **Hosting** | Cloud | Cloud | DC only | Cloud | Cloud | ### Where QRCode for Confluence Stands Out[​](#where-qrcode-for-confluence-stands-out "Direct link to Where QRCode for Confluence Stands Out") **Slash command workflow** — Type `/qrcode` in the Confluence editor and the macro appears immediately. No navigating to page menus or admin panels. The fastest way to add a QR code to any page. **Encode any content** — Enter any text or URL, not just the current page URL. Encode website links, email addresses, phone numbers, Wi-Fi credentials, or plain text. Other apps like qr2page only generate codes for the current Confluence page. **Five size options** — Choose from X-Small, Small, Medium, Large, and X-Large. Use XS for inline badges, XL for posters and signs that need to be scanned from a distance. Most competitors offer a single fixed size. **Re-editable** — Click on an existing QR code and select Edit to change the content or size. Your settings are preserved across edits. **Free for small teams** — Full features available free for up to 10 users. ### Where We Could Improve[​](#where-we-could-improve "Direct link to Where We Could Improve") * **2 installs** — The smallest install base in this category. We launched in early 2025 and are building traction. * **No print-focused workflow** — Seibert's qr2page generates QR codes from the page menu specifically for printing and attaching to physical objects. Our app embeds QR codes inline on pages. * **No other barcode formats** — Barcodes for Confluence by codalyx supports multiple barcode types (EAN, Code128, etc.) beyond QR codes. We only generate QR codes. * **No Data Center support** — Cloud-only. Barcodes for Confluence is the only DC option. * **No batch generation** — Can't generate QR codes for multiple pages at once. Each one is added individually. ## Which App Do You Need?[​](#which-app-do-you-need "Direct link to Which App Do You Need?") | You need... | Use this | | ----------------------------------------------------- | ---------------------------------- | | Generate QR codes from the page menu for printing | qr2page by Seibert | | Multiple barcode formats (not just QR) on Data Center | Barcodes for Confluence by codalyx | | A completely free option | Moves QR Generator by Dmove | | Quick inline QR codes with `/qrcode` slash command | **QRCode for Confluence** | | Customizable QR code sizes for different use cases | **QRCode for Confluence** | | Encode custom text (not just page URLs) | **QRCode for Confluence** | ## Related Posts[​](#related-posts "Direct link to Related Posts") * [Google Fonts for Confluence — Which Custom Typography App Fits Your Team?](/blog/google-fonts-confluence-custom-typography.md) * [Numbered Headings for Confluence — Which Table of Contents App Fits Your Docs?](/blog/confluence-numbered-headings-comparison.md) ## Get Started[​](#get-started "Direct link to Get Started") * Install **QRCode for Confluence** from the [Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236735/qrcode-for-confluence) — free for up to 10 users * [Read the full documentation](/docs/QRCode-for-Confluence/usage.md) Have questions or feedback? Reach out to us at — we'd love to hear from you. ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [qr-code](/blog/tags/qr-code.md) * [qrcode](/blog/tags/qrcode.md) * [confluence](/blog/tags/confluence.md) * [barcode](/blog/tags/barcode.md) * [url-shortener](/blog/tags/url-shortener.md) * [printable-qr](/blog/tags/printable-qr.md) --- # Confluence FAQ Macro & Q\&A Template: Add FAQ Sections to Pages May 10, 2026 · 3 min read [NGPilot](https://ngpilot.com) Confluence is great for documentation, but it has no built-in **FAQ macro** or Q\&A tool. If you need FAQ pages, knowledge bases, or community-style Q\&A in Confluence, NGPILOT offers two purpose-built apps. ## Two approaches to Q\&A in Confluence[​](#two-approaches-to-qa-in-confluence "Direct link to Two approaches to Q\&A in Confluence") | App | Style | Best For | | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ------------------------------------- | | [Modern FAQ for Confluence](https://marketplace.atlassian.com/apps/1236413/modern-faq-for-confluence?hosting=cloud\&tab=overview) | Static FAQ sections | Product FAQ pages, support docs | | [Modern Questions for Confluence](https://marketplace.atlassian.com/apps/modern-questions-for-confluence?hosting=cloud\&tab=overview) | Interactive Q\&A | Knowledge base, team Q\&A, onboarding | ## Modern FAQ — structured FAQ sections[​](#modern-faq--structured-faq-sections "Direct link to Modern FAQ — structured FAQ sections") [Modern FAQ for Confluence](https://marketplace.atlassian.com/apps/1236413/modern-faq-for-confluence?hosting=cloud\&tab=overview) adds customizable FAQ sections to any Confluence page. Questions appear in an accordion format — click to expand the answer. ### Features[​](#features "Direct link to Features") * **Accordion layout** — questions expand/collapse on click * **Categories** — group questions by topic * **Search** — users can search within FAQ sections * **Customizable styling** — match your Confluence theme * **Mobile-friendly** — responsive on all devices ### How to create an FAQ section[​](#how-to-create-an-faq-section "Direct link to How to create an FAQ section") 1. Install Modern FAQ for Confluence (free for up to 10 users) 2. Open a Confluence page in edit mode 3. Type `/modern faq` and select the macro 4. Add your questions and answers 5. Organize by category if needed 6. Save the page ### Use cases[​](#use-cases "Direct link to Use cases") * **Product FAQ pages** — common questions about your product or service * **Support documentation** — self-service answers to frequent support tickets * **Onboarding guides** — new hire FAQ sections in onboarding spaces * **Project wikis** — project-specific Q\&A for team reference Read the full guide: [How to build FAQ sections in Confluence](/blog/how-to-build-faq-sections-confluence.md). ## Modern Questions — interactive Q\&A[​](#modern-questions--interactive-qa "Direct link to Modern Questions — interactive Q\&A") [Modern Questions for Confluence](https://marketplace.atlassian.com/apps/modern-questions-for-confluence?hosting=cloud\&tab=overview) adds a community-style Q\&A experience to Confluence. Users can post questions, write answers, vote on the best responses, and mark accepted answers. ### Features[​](#features-1 "Direct link to Features") * **Post questions** — any user can ask a question * **Submit answers** — multiple answers per question * **Voting** — upvote the most helpful answers * **Accepted answers** — mark the best answer (like Stack Overflow) * **Search** — find existing questions before asking ### How to set up Q\&A[​](#how-to-set-up-qa "Direct link to How to set up Q\&A") 1. Install Modern Questions for Confluence (free for up to 10 users) 2. Open a Confluence page in edit mode 3. Type `/modern questions` and select the macro 4. The Q\&A section appears on the page 5. Users can start posting questions immediately ### Use cases[​](#use-cases-1 "Direct link to Use cases") * **Team knowledge base** — capture tribal knowledge as Q\&A * **IT support** — internal Stack Overflow for your team * **Product feedback** — let users ask questions about features * **Training** — new team members ask questions, experienced members answer ## FAQ vs Q\&A: which do you need?[​](#faq-vs-qa-which-do-you-need "Direct link to FAQ vs Q\&A: which do you need?") | Need | Use | | --------------------------------------- | ---------------- | | Predefined questions with fixed answers | Modern FAQ | | Users need to ask new questions | Modern Questions | | One-time setup, no ongoing moderation | Modern FAQ | | Community engagement, evolving answers | Modern Questions | | Product/support documentation | Modern FAQ | | Internal team knowledge sharing | Modern Questions | You can use both on the same Confluence site — FAQ for static support pages and Questions for interactive team Q\&A. ## Get started[​](#get-started "Direct link to Get started") Both apps are available on the [Atlassian Marketplace](https://marketplace.atlassian.com/vendors/1226848/) and free for up to 10 users. **Ready to add Q\&A to your Confluence?** [Browse all NGPILOT apps →](https://marketplace.atlassian.com/vendors/1226848/) ## Related resources[​](#related-resources "Direct link to Related resources") * [Modern FAQ — documentation](/apps/modern-faq-for-confluence.md) * [Modern Questions — documentation](/apps/modern-questions-for-confluence.md) * [How to build FAQ sections in Confluence](/blog/how-to-build-faq-sections-confluence.md) * [Best Confluence apps for developers](/blog/best-confluence-apps-developers.md) Try Modern Questions for Confluence Interactive Q\&A with voting and accepted answers, right inside Confluence pages — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/3250836705/modern-questions-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-questions-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [faq](/blog/tags/faq.md) * [questions](/blog/tags/questions.md) * [answers](/blog/tags/answers.md) * [template](/blog/tags/template.md) * [knowledge-base](/blog/tags/knowledge-base.md) * [macro](/blog/tags/macro.md) --- # Confluence Source Editor Compared — Free vs Pro May 2, 2026 · 11 min read [NGPilot](https://ngpilot.com) Confluence stores every page as XML in a format called "Confluence storage format." Most users never see it. But if you have ever tried to fix a broken macro, remove hidden formatting artifacts, or bulk-edit repetitive markup, you know the rich text editor alone is not enough. You need direct access to the underlying source. At NGPILOT, we built two apps for exactly this purpose: **Raw Storage Source Editor for Confluence** (free) and **Raw Storage Source Editor Pro for Confluence** (paid). Both let you open, view, and edit the raw XML behind any Confluence page. This post compares them feature by feature so you can pick the right one for your team. ## Why Edit Confluence Storage Format Directly?[​](#why-edit-confluence-storage-format-directly "Direct link to Why Edit Confluence Storage Format Directly?") Confluence's storage format is an XML dialect based on XHTML with Confluence-specific elements like ``, ``, and ``. When you edit a page normally, the rich text editor generates this XML behind the scenes. Most of the time that works fine. But there are situations where the visual editor gets in the way: * **Fixing broken macros.** Sometimes a macro becomes corrupted and the visual editor refuses to render or save the page. Editing the XML directly lets you remove the offending element. * **Removing invisible formatting.** Copy-pasting from Word or Google Docs can inject stray inline styles, empty paragraphs, and nested `` tags that bloat pages and break layouts. * **Bulk find and replace.** Need to update a URL that appears in 30 places across a long page? Search and replace in the source is faster than clicking through each macro. * **Building advanced macros.** Power users who construct complex macros, nested layouts, or custom HTML blocks benefit from seeing and editing the exact XML structure. * **Migrating content.** Teams moving content between spaces or instances sometimes need to manually adjust links, references, and macro parameters in the source. If any of these sound familiar, a Confluence storage format editor is not a luxury — it is a necessity. The question is whether the free version is enough, or whether the Pro version's additional capabilities are worth it. ## Raw Storage Source Editor for Confluence (Free)[​](#raw-storage-source-editor-for-confluence-free "Direct link to Raw Storage Source Editor for Confluence (Free)") The free version gives you straightforward, no-frills access to the raw storage format of any Confluence page. It is built on the Monaco editor — the same engine that powers VS Code — so it feels familiar to developers from the first keystroke. ### How It Works[​](#how-it-works "Direct link to How It Works") Open any Confluence page, click the **"More actions"** menu (the three-dot button), and select **"Source Editor for Confluence."** The full XML source of the page loads in a code editor. Make your changes and click Save. The page reloads with your edits applied. ### Key Features[​](#key-features "Direct link to Key Features") **Format Document.** Right-click in the editor and choose "Format Document" to automatically re-indent and tidy up the XML structure. This is useful when the storage format is a dense block of unformatted XML, which happens frequently with pages that have been edited many times or imported from other systems. **Command palette.** Press `F1`, `Ctrl+P` (Windows/Linux), or `Cmd+P` (macOS) to open Monaco's command palette. This gives you access to the full set of editor commands — go to line, change encoding, toggle whitespace rendering, and more. **Lightweight and fast.** The free version opens instantly and stays out of your way. It does one thing — show you the XML and let you edit it — and does it reliably. ### What It Does Not Include[​](#what-it-does-not-include "Direct link to What It Does Not Include") The free version is intentionally minimal. There is no diff view to compare your changes against the original, no editor theme options, and no dedicated search panel. If you need those capabilities, the Pro version adds them. ## Raw Storage Source Editor Pro for Confluence (Paid)[​](#raw-storage-source-editor-pro-for-confluence-paid "Direct link to Raw Storage Source Editor Pro for Confluence (Paid)") The Pro version takes the same core experience — open a page's XML, edit it, save it — and wraps it in a professional-grade editing environment. It is still built on Monaco, but with significant enhancements that make it suitable for daily use by developers, system administrators, and technical writers. ### How It Works[​](#how-it-works-1 "Direct link to How It Works") Same workflow: open a page, click **"More actions,"** and select **"Source Editor Pro for Confluence."** The difference is what you see when the editor opens. ### Key Features[​](#key-features-1 "Direct link to Key Features") **Syntax highlighting and themes.** The Pro version includes three editor themes: Light, Dark, and High Contrast. Click the palette icon in the top toolbar to switch. Your preference persists across sessions. The syntax highlighting makes XML elements, attributes, values, and CDATA blocks visually distinct, which dramatically improves readability on complex pages. **Diff View.** This is the headline feature. As soon as you start editing, a "Diff View" button appears at the bottom-right of the window. Click it to open a side-by-side comparison: the left panel shows the original XML as it was when you loaded the page, and the right panel shows your current edits. You can continue editing on the right side while the diff is visible. This makes it easy to review exactly what you are changing before saving — critical when editing production pages where a wrong edit could break layouts or lose content. **Find panel.** Click the search icon in the top toolbar or press `Ctrl+F` / `Cmd+F` to open a dedicated Find panel. In normal edit mode, it searches the full document. In Diff View, it searches the modified (right) side. Combined with Monaco's built-in replace functionality, this makes bulk edits fast and safe. **Toggle word wrap.** Long lines of XML are common in Confluence storage format, especially in macro parameters and inline styles. The word-wrap toggle in the toolbar lets you switch between wrapped and unwrapped modes. In Diff View, word wrap is automatically disabled so that differences align cleanly between the two panels. **Format Document.** Same as the free version — right-click and select "Format Document" to re-indent and tidy the XML. If the XML structure is invalid, formatting may fail — fix the errors first and then try formatting again. **Full Monaco command palette.** Like the free version, pressing `F1`, `Ctrl+P`, or `Cmd+P` opens the command palette. The palette exposes Monaco functionality such as advanced search and replace with regex support, go to line, go to symbol, toggle minimap, render whitespace characters, and more. Most Monaco features work inside the editor. **Save and Cancel with safety guards.** The Save button is disabled when there are no changes, when the editor is still loading, or when a save is already in progress. This prevents accidental double-saves and ensures you only write back to Confluence when you intend to. Cancel closes the editor without saving any changes. ## Feature Comparison[​](#feature-comparison "Direct link to Feature Comparison") | Feature | Free | Pro | | -------------------------------------------- | --------------------------- | --------------------------- | | View raw Confluence storage format (XML) | Yes | Yes | | Edit raw XML and save back to page | Yes | Yes | | Format Document (XML re-indentation) | Yes | Yes | | Monaco editor engine | Yes | Yes | | Command palette (F1 / Ctrl+P / Cmd+P) | Yes | Yes | | Syntax highlighting with XML-aware coloring | Yes (Monaco-based) | Yes (Monaco-based) | | Editor themes (Light / Dark / High Contrast) | No | Yes | | Diff View (side-by-side original vs. edited) | No | Yes | | Dedicated Find panel | No | Yes | | Toggle word wrap | No | Yes | | Regex search and replace | Yes (via command palette) | Yes (via command palette) | | Minimap navigation | Yes (via command palette) | Yes (via command palette) | | Go to line / symbol | Yes (via command palette) | Yes (via command palette) | | Invalid XML warning before formatting | Formatting fails if invalid | Formatting fails if invalid | | Save button safety guards (disabled states) | — | Yes | | Theme preference persisted across sessions | No | Yes | | Price | Free | Paid | ## When to Use Each[​](#when-to-use-each "Direct link to When to Use Each") Choosing between the free and Pro versions comes down to how often you edit storage format and how complex those edits are. ### Use the Free Version If...[​](#use-the-free-version-if "Direct link to Use the Free Version If...") * **You only need occasional access.** If you open the source editor once a month to fix a broken macro or remove some stray formatting, the free version is all you need. * **Your edits are simple and targeted.** Removing a single broken element, changing a URL in one place, or checking what XML the visual editor generated — these tasks do not require diff views or themes. * **You are evaluating whether you need a source editor at all.** The free version is a zero-risk way to test the workflow. Install it, try it on a test page, and see if editing storage format fits into your team's process. * **Budget is the primary constraint.** Small teams and individual users who cannot justify a paid app for occasional use. ### Use the Pro Version If...[​](#use-the-pro-version-if "Direct link to Use the Pro Version If...") * **You edit storage format regularly.** System administrators, template builders, and developers who frequently work with the source XML will benefit from syntax highlighting, themes, and the diff view every single session. * **You need to review changes before saving.** The Diff View is invaluable when editing production pages. Seeing exactly what changed — side by side with the original — prevents costly mistakes. * **You perform bulk edits with search and replace.** The dedicated Find panel plus regex support in the command palette makes it fast to update URLs, macro parameters, or class names across an entire page. * **You build or maintain Confluence templates.** Template authors who construct complex layouts with nested macros need precise control over the XML. Syntax highlighting and minimap navigation help you understand the structure at a glance. * **You migrate content between spaces or instances.** Large-scale content migrations often require manual adjustments to links, page references, and macro configurations. The Pro version's diff and search capabilities make this manageable. * **Your team includes non-developers who edit source.** The themes, word wrap, and formatted XML make the source less intimidating for technical writers and content managers who are not used to reading raw XML. ## Real-World Scenarios[​](#real-world-scenarios "Direct link to Real-World Scenarios") Here are concrete examples of when each version shines. **Scenario 1: Removing a broken macro.** A user reports that a page will not load in edit mode. You suspect a corrupted macro. You open the free source editor, find the macro element in the XML, delete it, and save. The page works again. Time: two minutes. The free version handles this perfectly. **Scenario 2: Cleaning up pasted content.** A 50-page spec document was pasted from Google Docs into Confluence. The page is bloated with inline styles, empty paragraphs, and nested spans. You open the Pro editor, use Format Document to make the XML readable, then use regex find and replace to strip out the unwanted formatting. Diff View lets you verify the cleanup before saving. The Pro version saves you significant time here. **Scenario 3: Updating links after a space rename.** After renaming a Confluence space, dozens of internal links on a key page still reference the old space key. You open the Pro editor, use search and replace to update all references at once, then check Diff View to confirm only the links changed. This would be tedious and error-prone in the free version. **Scenario 4: Debugging a custom macro.** You are building a User Macro and need to see exactly what XML it generates. The free version lets you inspect the output quickly. For ongoing development where you iterate on the macro and check results repeatedly, the Pro version's theme support and syntax highlighting reduce eye strain. ## A Note on Safety[​](#a-note-on-safety "Direct link to A Note on Safety") Editing Confluence storage format is powerful. A single wrong character can break a page's layout or cause macros to fail. Both apps include the Format Document feature to help you keep the XML well-structured. The Pro version adds an extra layer of safety with Diff View — you always see what will change before you commit. Regardless of which version you use, we recommend: * **Test on a copy first.** Duplicate the page, edit the copy, verify it renders correctly, then apply the same edit to the original. * **Use Format Document before editing.** Reformatted XML is easier to read and harder to accidentally break. * **Keep backups.** If your Confluence instance has page history enabled, you can always revert. Confirm this is turned on for critical pages. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Raw Storage Source Editor (Free) — Usage Guide](/apps/raw-storage-source-editor-for-confluence.md) * [Raw Storage Source Editor Pro — Usage Guide](/apps/raw-storage-source-editor-pro-for-confluence.md) * [Enhanced Markdown for Confluence](/apps/enhanced-markdown-for-confluence.md) — write Markdown with a WYSIWYG editor instead of editing XML * [Best Confluence Apps for Developers](/blog/best-confluence-apps-developers.md) — our roundup of developer-focused Confluence apps ## Get Started[​](#get-started "Direct link to Get Started") Both apps are available on the Atlassian Marketplace. Install the **free version** to get started immediately, or go straight to **Pro** if you know you need the advanced features. You can always start with free and upgrade later — the workflow is identical, so there is no learning curve when you switch. Have questions about which version fits your team? Reach out to us at — we are happy to help. ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [comparison](/blog/tags/comparison.md) * [confluence](/blog/tags/confluence.md) * [source-editor](/blog/tags/source-editor.md) * [developer-tools](/blog/tags/developer-tools.md) --- # Tabs in Confluence: Native Layout Tabs vs Tabs Macros Compared August 21, 2026 · 4 min read [NGPilot](https://ngpilot.com) Tabs are the layout workhorse of product pages, API references, and comparison docs: they let one page hold three versions of the truth (per environment, per plan, per language) without tripling the scroll length. Confluence's answer to tabs has changed over the years, so this page sorts out what exists today and which to use when. ## What Confluence gives you natively[​](#what-confluence-gives-you-natively "Direct link to What Confluence gives you natively") Confluence Cloud now ships **page tabs**: when you create a page using a tabs-capable template (or add tabs to an existing page), each tab is backed by a **child page** rendered inside the parent. **What this buys you:** * **No app required** — works in every Cloud instance * **Per-tab permissions** — because tabs are real pages, space permissions apply per tab * **Direct links and history** — each tab has its own URL and version history * **Scales well** — a tab can hold a full page's worth of content **The trade-offs:** * **Structural weight.** Tabs-as-child-pages is an opinionated structure; a quick 3-tab comparison means creating 3 pages plus the parent. * **Content-level tabs are missing.** You can't drop a small tabbed panel *inside a section* of a page — it's a whole-page layout decision. * **Limited styling.** The tab bar looks like Confluence; per-tab colors, images, and layouts aren't options. ## What a tabs macro adds[​](#what-a-tabs-macro-adds "Direct link to What a tabs macro adds") For tabbed *content* — panels inside a page, styled to match the page's design — Marketplace tabs macros fill the gap. The **Tabs** macro in [Content Formatting Macros & Page Builder for Confluence](/apps/content-formatting-macros-page-builder-for-confluence.md) works like this: * Up to **8 tabs per macro**, each with a title, optional heading and description, and rich-text content * **Per-tab imagery** — image, background color, image fit/position/size, and overlay for building product-style panels * **Layout control** — tab position (top, left, or right), alignment, underline, and hover effects * **Styles and presets** — line, pills, or card styles; presets like Image Left, Image Top, and Image Background for landing-page-like sections Multiple tabs macros can sit on one page — a common pattern is one per major section, each grouping 3–4 variants (per plan, per environment, per audience). ## How to add tabs to a Confluence page[​](#how-to-add-tabs-to-a-confluence-page "Direct link to How to add tabs to a Confluence page") **Native page tabs** (tabs as child pages): 1. Create the parent page, or open the page that should hold the tab bar. 2. Create the tab content as **child pages** under it (via the page tree or a tabs-capable template). 3. The parent renders a tab bar across the top — each tab opens its child page inline, and every tab keeps its own URL, history, and permissions. **Tabs inside the page body** (tabs macro, works on any existing page): 1. Edit the page and put the cursor where the tabbed panel should sit. 2. Type `/tabs` and select the **Tabs** macro. 3. Add each tab's title and content — up to 8 tab panels per macro, rich text in every one. 4. Style per tab (image, background color) and choose position (top, left, right) and style (line, pills, card). 5. Save. Multiple tabs macros per page are fine — one per section is the common pattern. The first route restructures content into pages; the second keeps everything in the page you already have. ## Choosing per page[​](#choosing-per-page "Direct link to Choosing per page") | Situation | Best fit | | ---------------------------------------------------------- | --------------------------------------- | | Documentation with permission differences per section | Native tabs (child-page permissions) | | Product page with styled panels and images | Tabs macro | | Quick comparison of CLI flags / API versions inside a doc | Tabs macro (lighter than 3 child pages) | | Multi-language docs where each tab is a full translation | Native tabs | | Landing-page-style sections (pricing, features) | Tabs macro with presets | | Content that must be one page for export/search simplicity | Tabs macro (single page body) | The rule of thumb: **native tabs when tabs are pages; tabs macro when tabs are content.** ## A note on migrations[​](#a-note-on-migrations "Direct link to A note on migrations") If you're coming from Server/Data Center, old third-party tabs macros stored content in a single page body. Moving to Cloud native tabs means promoting each tab's content into child pages — worth doing when permissions or per-tab history matter, and worth avoiding when the tabs are small content fragments (then a Cloud tabs macro keeps the original shape). ## Related reading[​](#related-reading "Direct link to Related reading") * [Expand macro for Confluence](/blog/confluence-expand-macro.md) — the accordion cousin: hiding content vertically instead of horizontally * [How to build FAQ sections in Confluence](/blog/how-to-build-faq-sections-confluence.md) — structured Q\&A without tab sprawl * [Confluence pagination: pages and tables](/blog/confluence-pagination.md) — when content outgrows one page entirely * [Content Formatting Macros & Page Builder](/apps/content-formatting-macros-page-builder-for-confluence.md) — tabs, expand, panels, and 20 more macros ## Related guides * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [macros](/blog/tags/macros.md) * [tabs](/blog/tags/tabs.md) * [layout](/blog/tags/layout.md) * [formatting](/blog/tags/formatting.md) * [how-to](/blog/tags/how-to.md) --- # Confluence Wiki Markup: How to View, Edit & Convert It September 23, 2026 · 6 min read [NGPilot](https://ngpilot.com) Every Confluence page has two faces: the one you see in the editor, and the one the database sees. The database face is the **storage format** — an XHTML document with macros as tags — and before it, Confluence stored pages as **wiki markup**: `h1. headings`, `*bold text*`, `{code}` blocks. People still search for wiki markup because half the internet's Confluence advice, every migration script, and a lot of content written before \~2017 speaks that language. And in 2026 the topic got urgent: Atlassian is retiring the legacy editor (full deprecation April 2026), and the new cloud editor **dropped the Markup macro** entirely. Here's how to view, edit, and convert what's actually stored — with or without admin rights. **Quick answer:** To view a page's markup, open the **••• → View storage format** menu (needs space admin) or call `GET /wiki/rest/api/content/{pageId}?expand=body.storage`. To edit it, use [Raw Storage Source Editor](https://marketplace.atlassian.com/apps/1237066/raw-storage-source-editor-for-confluence), which shows a diff before saving. Legacy wiki markup syntax itself is being retired — the legacy editor is fully deprecated in April 2026 and the new editor no longer accepts the Markup macro. ## Method 1 — View Storage Format Natively (Read-Only)[​](#method-1--view-storage-format-natively-read-only "Direct link to Method 1 — View Storage Format Natively (Read-Only)") Open any page, click the **•••** (More options) menu in the top right, and pick **View storage format**. Confluence opens the raw XHTML in a new browser tab: every macro is a `` or `` tag, formatting is literal XHTML, and page properties show up as structured blocks. Two things to know before you go looking for it: * **It's permission-gated.** The option only appears for users with space admin (or explicitly granted) permissions — if the menu item is missing, that's usually why. * **It's read-only.** This is an inspection window. Nothing you do here changes the page, and copy-pasting it elsewhere doesn't give you an editable copy of the page. **Good for:** checking what a macro actually stored, diagnosing why something renders oddly, or feeding the XML to a script. ## Method 2 — The REST API (No Space Admin Needed)[​](#method-2--the-rest-api-no-space-admin-needed "Direct link to Method 2 — The REST API (No Space Admin Needed)") The same document is one API call away, and API access is governed by normal page permissions rather than the storage-format menu's admin gate: ``` curl -u user@example.com:api-token \ "https://your-site.atlassian.net/wiki/rest/api/content/123456789?expand=body.storage" ``` The markup comes back in `body.storage.value`. It's read-only again — but for auditing, diffing two pages, or bulk-reporting which pages still carry legacy macro tags, it's the programmable route. ## Method 3 — Edit the Markup Directly (Recommended for Fixes)[​](#method-3--edit-the-markup-directly-recommended-for-fixes "Direct link to Method 3 — Edit the Markup Directly (Recommended for Fixes)") Native editing is where Confluence draws a hard line: the visual editor edits the rendered view, and there's no built-in raw editor on Cloud. When you *need* to touch the markup — a broken macro from a migration, junk `` soup from pasted Word content, a bulk rename that must preserve structure — editing the XML by hand through the API means writing blind, and one wrong tag can take the whole page down. [Raw Storage Source Editor for Confluence](https://marketplace.atlassian.com/apps/1237066/raw-storage-source-editor-for-confluence) (free) puts a raw editor inside Confluence instead: 1. Open a page and launch the editor — the page's storage format loads as editable XML. 2. Make your change — full find-and-replace for cleanup jobs, direct edits for surgical ones. 3. **Review the diff before saving.** You see exactly which lines change, so a slip is a rejected edit instead of a broken page. It's the same job Atlassian's own Storage Format Source Editor did on Data Center — built for Cloud, where that app never shipped. There's also a [Pro version](https://marketplace.atlassian.com/apps/2739097621/raw-storage-source-editor-pro-for-confluence) with batch operations for whole-space cleanups. ## Method 4 — Legacy Wiki Markup: Convert It Before April 2026[​](#method-4--legacy-wiki-markup-convert-it-before-april-2026 "Direct link to Method 4 — Legacy Wiki Markup: Convert It Before April 2026") If your space predates the cloud editor, some pages may still carry legacy wiki markup or the old macro syntax. With the [legacy editor's full deprecation set for April 2026](https://community.atlassian.com), the clock matters more than the syntax: 1. **Inventory first.** A REST call scanning `body.storage.value` for legacy tags (`` with deprecated names, raw `h1.`-style content) tells you how much is left. 2. **Open and let the editor convert.** Editing a page in the cloud editor converts what it recognizes into modern macros. Fix anything it can't convert by hand. 3. **Replace markup-dependent workflows.** The new editor has no Markup macro, so any process that *inserted* wiki markup (templates, scripts, copy-paste snippets) needs a new home — modern macros, page templates, or [writing in Markdown instead](/blog/how-to-write-markdown-in-confluence.md) with an app like [Enhanced Markdown for Confluence](/apps/enhanced-markdown-for-confluence.md), which renders Mermaid, math, and code natively. **Good for:** teams with pre-2017 spaces or migrations from Data Center. If your space is young, this section doesn't apply — and that's the point of checking. ## A Pocket Reference: Legacy Syntax → What It Became[​](#a-pocket-reference-legacy-syntax--what-it-became "Direct link to A Pocket Reference: Legacy Syntax → What It Became") | Legacy wiki markup | Modern equivalent | | -------------------------------- | ------------------------------------------ | | `h1. Heading` | Heading (type `/heading`) | | `*bold*`, `_italic_` | `**bold**`, `_italic_` (or toolbar) | | `{code:java}...{code}` | Code block macro (`/code`) | | `{panel}`, `{info}`, `{warning}` | Panel, info, and warning panels (`/panel`) | | `{table}`-style rows `\|\|` | Standard tables | | `{color:red}text{color}` | Text color in the toolbar | The pattern: almost everything has a modern macro equivalent — the syntax is what died. The migration work is mostly mechanical, with the exceptions worth checking page by page. ## Which Method Should You Use?[​](#which-method-should-you-use "Direct link to Which Method Should You Use?") | Need | Use | | ---------------------------------- | ---------------------------------------------------------------- | | Peek at what a page really stored | ••• → View storage format | | Read markup without space admin | REST API, `expand=body.storage` | | Fix a broken macro or clean up XML | Raw Storage Source Editor (diff before save) | | Retire legacy wiki markup | Inventory via API, convert in the cloud editor before April 2026 | The storage format is the page's source of truth — readable natively, editable safely with a diff in front of you, and worth converting now rather than in April. Install [Raw Storage Source Editor for Confluence](https://marketplace.atlassian.com/apps/1237066/raw-storage-source-editor-for-confluence) free from the Atlassian Marketplace and open your most structurally-damaged page to see the difference. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [How to Write Markdown in Confluence](/blog/how-to-write-markdown-in-confluence.md) — Markdown as the modern alternative to legacy markup * [Markdown FAQ: Syntax, Tables & Code Blocks in Confluence](/blog/faq-confluence-markdown-editor.md) — the markdown cluster's reference page * [Markdown to Confluence Converter](/blog/markdown-to-confluence-converter.md) — bring markdown content in without markup loss * [Raw Storage Source Editor for Confluence](/apps/raw-storage-source-editor-for-confluence.md) — full app details and documentation ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [wiki-markup](/blog/tags/wiki-markup.md) * [storage-format](/blog/tags/storage-format.md) * [how-to](/blog/tags/how-to.md) * [admin](/blog/tags/admin.md) * [migration](/blog/tags/migration.md) --- # Flowchart Syntax Reference for Confluence — Mermaid, DOT & Canvas April 24, 2026 · 3 min read [NGPilot](https://ngpilot.com) Flowcharts are one of the most common diagrams teams add to Confluence pages — for process documentation, onboarding, decision trees, and troubleshooting guides. This article shows three ways to create them using NGPILOT apps. ## Method 1: Mermaid Plus (text-based flowcharts)[​](#method-1-mermaid-plus-text-based-flowcharts "Direct link to Method 1: Mermaid Plus (text-based flowcharts)") [Mermaid Plus Diagrams & AI Agent for Confluence](/docs/Mermaid-Plus-for-Confluence/usage.md) renders flowcharts from a simple text syntax. It's fast, versionable, and supports complex branching. **Copy-paste example:** ``` graph TD A[User submits request] --> B{Auto-validation} B -- Valid --> C[Route to team] B -- Invalid --> D[Return to user with errors] D --> A C --> E{Team review} E -- Approve --> F[Process request] E -- Reject --> G[Notify user] ``` **Steps:** 1. Edit a Confluence page 2. Type `/mermaid` and select the Mermaid Plus macro 3. Paste your flowchart code 4. Preview and save Mermaid supports styled nodes, subgraphs, click events, and themes. See the full syntax guide: [Create Mermaid diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md). ## Method 2: Excalidraw Plus (visual drag-and-drop)[​](#method-2-excalidraw-plus-visual-drag-and-drop "Direct link to Method 2: Excalidraw Plus (visual drag-and-drop)") [Excalidraw Plus for Confluence](/docs/Excalidraw-plus-for-Confluence/usage.md) gives you a visual canvas where you drag shapes, connect them with arrows, and add labels. It ships with built-in shape libraries for flowcharts. **Steps:** 1. Edit a Confluence page 2. Type `/excalidraw` and select the macro 3. Drag shapes from the flowchart library onto the canvas 4. Connect shapes with arrows and add labels 5. Save **Best for:** Teams that prefer visual editing over code, brainstorming sessions, and early-stage process mapping. See also: [Excalidraw best practices FAQ](/blog/faq-excalidraw-best-practices.md). ## Method 3: Graphviz Charts (auto-layout graphs)[​](#method-3-graphviz-charts-auto-layout-graphs "Direct link to Method 3: Graphviz Charts (auto-layout graphs)") [Graphviz Charts for Confluence](/docs/Graphviz-Charts-for-Confluence/usage.md) uses the DOT language to generate flowcharts with automatic layout. The engine handles node positioning, so you focus on relationships. **Copy-paste example:** ``` digraph { rankdir=TD A [label="Start"] B [label="Process"] C [label="Decision", shape=diamond] D [label="End"] A -> B -> C C -> D [label="Yes"] C -> B [label="No"] } ``` **Best for:** Complex graphs with many nodes where automatic layout saves time, or when you need consistent styling across many diagrams. ## Which method should you use?[​](#which-method-should-you-use "Direct link to Which method should you use?") | Need | Best choice | | ------------------------------------- | ------------------------ | | Quick flowcharts with standard shapes | Mermaid Plus | | Freeform brainstorming and sketches | Excalidraw Plus | | Complex auto-laid-out graphs | Graphviz Charts | | Version control and diffs | Mermaid Plus or Graphviz | | Non-technical team members | Excalidraw Plus | ## Related resources[​](#related-resources "Direct link to Related resources") * [Mermaid Plus Diagrams & AI Agent for Confluence — documentation](/apps/mermaid-plus-for-confluence.md) * [Excalidraw Plus for Confluence — documentation](/apps/excalidraw-plus-for-confluence.md) * [Graphviz Charts for Confluence — documentation](/apps/graphviz-charts-for-confluence.md) * [Confluence diagram tools comparison](/blog/confluence-diagram-tools-comparison.md) * [Mermaid troubleshooting FAQ](/blog/faq-mermaid-troubleshooting.md) ## Related guides * [Best Diagram Tool for Confluence — Compared](/blog/confluence-diagram-tools-comparison.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [flowcharts](/blog/tags/flowcharts.md) * [mermaid](/blog/tags/mermaid.md) * [excalidraw](/blog/tags/excalidraw.md) * [graphviz](/blog/tags/graphviz.md) * [how-to](/blog/tags/how-to.md) --- # How to Create Jira Issue Templates for Consistent Team Workflows July 29, 2026 · 7 min read [NGPilot](https://ngpilot.com) Quick Answer Jira issue templates standardize how bugs, features, and tasks are reported. Create pre-filled templates with required fields and structured descriptions to eliminate incomplete issues. What you'll learn 1. How to identify and catalog your team's recurring issue types 2. How to create pre-filled templates that enforce required fields 3. How to use bulk create for batch issue generation from spreadsheets 4. How to train your team to use templates consistently Inconsistent issue reporting is a silent productivity killer. One developer writes a two-line bug report with no steps to reproduce. Another writes a three-paragraph feature request buried in technical jargon. The result: wasted time clarifying, misestimated work, and frustrated teams. Issue templates solve this by standardizing how work is described. Every bug report has the same structure. Every feature request includes the same fields. This guide shows how to create and enforce templates in Jira. ## Why Issue Templates Matter[​](#why-issue-templates-matter "Direct link to Why Issue Templates Matter") Without templates, every issue is a blank canvas. That sounds flexible, but it creates problems: **Incomplete reports.** Developers skip fields they do not think are important. QA cannot reproduce bugs without steps. Product cannot prioritize features without business value. **Inconsistent formatting.** One person uses Markdown, another uses plain text. One includes screenshots, another includes a wall of text. The team wastes time reformatting instead of working. **Missed fields.** Custom fields like "Environment," "Affected Version," or "Business Value" get left empty. Reports that depend on these fields show incomplete data. **Onboarding friction.** New team members do not know what fields to fill in. They guess, and the team corrects them repeatedly. Templates eliminate these issues by providing a structured starting point for every issue type. ## How to Create Jira Issue Templates: Step-by-Step[​](#how-to-create-jira-issue-templates-step-by-step "Direct link to How to Create Jira Issue Templates: Step-by-Step") ### 1. Identify Your Team's Recurring Issue Types[​](#1-identify-your-teams-recurring-issue-types "Direct link to 1. Identify Your Team's Recurring Issue Types") Before creating templates, catalog the issue types your team uses most: | Issue Type | Frequency | Key Fields | | --------------- | --------- | ---------------------------------------------------- | | Bug Report | High | Steps to reproduce, environment, severity | | Feature Request | High | Business value, acceptance criteria, priority | | Task | Medium | Description, due date, assignee | | Story | Medium | User story format, story points, acceptance criteria | | Sub-task | High | Parent issue, description, time estimate | **For each type, list:** * Which fields are required * Which fields are optional * What the description should include * What labels or components should be applied ### 2. Create Issue Templates with Pre-Filled Fields[​](#2-create-issue-templates-with-pre-filled-fields "Direct link to 2. Create Issue Templates with Pre-Filled Fields") Jira's native templates are limited. For full control, use one of these approaches: **Option A: Native Jira Issue Types (Basic)** 1. Go to **Project Settings > Issue Types** 2. Select the issue type (Bug, Task, Story) 3. Edit the **Default Screen** to set default field values 4. This pre-fills fields but does not include description templates **Option B: Marketplace App (Recommended)** Install a template app like **Issue Templates for Jira** or **ScriptRunner**: 1. Create a "master" issue with all fields filled in 2. Save it as a template with a name (e.g., "Bug Report - Standard") 3. When users create a new issue, they select the template 4. All fields, including description, are pre-filled **Option C: Confluence Template (Free)** 1. Create a Confluence page with the template structure 2. Link to it from the project's issue creation screen 3. Users copy-paste the structure into new issues 4. Less automated but free and flexible ### 3. Standardize Required Fields and Descriptions[​](#3-standardize-required-fields-and-descriptions "Direct link to 3. Standardize Required Fields and Descriptions") For each template, define: **Required fields:** * Summary (always required) * Issue type (always required) * Priority (always required) * Assignee (optional at creation, required before moving to "In Progress") **Description template for bug reports:** ``` ## Bug Description [Clear, concise description of the bug] ## Steps to Reproduce 1. [Step 1] 2. [Step 2] 3. [Step 3] ## Expected Result [What should happen] ## Actual Result [What actually happens] ## Environment - OS: [e.g., Windows 11, macOS 14] - Browser: [e.g., Chrome 125, Firefox 126] - Jira Version: [e.g., 9.12.0] - App Version: [e.g., 2.3.1] ## Screenshots/Videos [Attach if applicable] ## Severity - [ ] Critical (system down, data loss) - [ ] High (major feature broken) - [ ] Medium (feature impaired but workaround exists) - [ ] Low (cosmetic issue) ``` **Description template for feature requests:** ``` ## Feature Summary [One-sentence description of the feature] ## User Story As a [role], I want [feature] so that [benefit]. ## Business Value [Why this feature matters — quantify if possible] ## Acceptance Criteria - [ ] [Criterion 1] - [ ] [Criterion 2] - [ ] [Criterion 3] ## Technical Notes [Any implementation considerations] ## Mockups/Wireframes [Attach if applicable] ``` ### 4. Set Up Bulk Create for Batch Operations[​](#4-set-up-bulk-create-for-batch-operations "Direct link to 4. Set Up Bulk Create for Batch Operations") For onboarding new projects, sprints, or migrating data, use Jira's bulk create: 1. Go to **Issues > Bulk Create** 2. Upload a CSV or TSV file with your data 3. Map columns to Jira fields 4. Preview and confirm 5. Create up to 1000 issues at once **CSV format example:** ``` Summary,Issue Type,Priority,Assignee,Description "Fix login timeout",Bug,High,jdoe,"Steps to reproduce: 1. Open login page 2. Enter credentials 3. Click Login 4. Wait 30+ seconds" "Add dark mode",Task,Medium,asmith,"Implement dark mode toggle in user settings" ``` **Use cases:** * Sprint planning (import stories from a spreadsheet) * Project setup (import standard tasks and milestones) * Data migration (import issues from another tool) * Recurring events (import standard retro actions, sprint ceremonies) ### 5. Train Your Team on Template Usage[​](#5-train-your-team-on-template-usage "Direct link to 5. Train Your Team on Template Usage") Templates only work if the team uses them consistently. **Training steps:** 1. Document which template to use for each scenario 2. Create a quick-reference guide in Confluence 3. Enforce template usage through board rules or automation 4. Review issues in sprint planning — if a new issue lacks required fields, send it back **Enforcement options:** * **Jira automation:** Validate that required fields are filled before transitioning to "In Progress" * **Board rules:** Block issues from moving to "In Review" if description is empty * **Template app:** Force users to select a template before creating an issue * **Sprint planning gate:** Scrutinize every new issue in planning — incomplete issues go back ## FAQ[​](#faq "Direct link to FAQ") ### Does Jira have built-in issue templates?[​](#does-jira-have-built-in-issue-templates "Direct link to Does Jira have built-in issue templates?") Jira has basic issue type templates that pre-fill the issue type and some fields. For more advanced templates with pre-filled descriptions, custom fields, and labels, you need a Marketplace app like Issue Templates for Jira or ScriptRunner. ### How do I create a custom issue template in Jira?[​](#how-do-i-create-a-custom-issue-template-in-jira "Direct link to How do I create a custom issue template in Jira?") Create a sample issue with all fields filled in, then use a template app to save it as a template. Alternatively, create a Confluence page with the template structure and link to it from your Jira project's issue creation screen. ### Can I bulk create Jira issues from a spreadsheet?[​](#can-i-bulk-create-jira-issues-from-a-spreadsheet "Direct link to Can I bulk create Jira issues from a spreadsheet?") Yes. Go to Issues > Bulk Create, upload a CSV or TSV file, map columns to Jira fields, and create up to 1000 issues at once. This is useful for sprint planning, project setup, or migrating data from other tools. ### How do I enforce template usage in Jira?[​](#how-do-i-enforce-template-usage-in-jira "Direct link to How do I enforce template usage in Jira?") Use Jira automation to validate that required fields are filled based on issue type. Alternatively, use a template app that forces users to select a template before creating an issue. Board rules can also validate issues meet criteria before moving to certain columns. ### What fields should a bug report template include?[​](#what-fields-should-a-bug-report-template-include "Direct link to What fields should a bug report template include?") A bug report template should include: summary, environment (OS, browser, version), steps to reproduce, expected result, actual result, screenshots/attachments, severity, and affected version. This ensures QA has everything needed to reproduce and fix the bug. ## Related guides[​](#related-guides "Direct link to Related guides") * [How to Export Jira Issues to Excel for Stakeholder Reporting](/blog/export-jira-issues-to-excel-csv-reporting.md) * [Creating Jira Issues from Templates with Bulk Create](/blog/create-jira-issues-from-templates.md) * [Jira JQL Cheat Sheet: 20 Queries Every Team Needs](/blog/jira-jql-cheat-sheet-common-queries.md) * [How to Plan Jira Sprints That Actually Work](/blog/plan-jira-sprints-that-actually-work.md) Try Modern Issue Templates for Jira Create issues from reusable templates with variables, GitHub import, and auto-apply — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/2564635381/modern-issue-templates-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-issue-templates-for-jira) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [issue-templates](/blog/tags/issue-templates.md) * [how-to](/blog/tags/how-to.md) * [productivity](/blog/tags/productivity.md) * [standardization](/blog/tags/standardization.md) --- # How to Create Jira Issues from Templates (3 Methods, With Examples) July 23, 2026 · 7 min read [NGPilot](https://ngpilot.com) Who should read this * **Jira admins and project leads** standardizing ticket creation across teams * **Engineering teams** who retyped the same bug/incident/story structure every week * **Anyone** asked "is there a template for this?" and wanting a real answer What you'll learn 1. Why Jira's native project templates don't solve per-ticket templating 2. Three ways to create issues from templates (starter library, custom, GitHub import) 3. How variables like `\{\{currentUser\}\}` and `\{\{today+7d\}\}` make templates dynamic 4. Auto-applying templates so the right one loads for each issue type The scenario every Jira team hits: a new bug comes in, and the reporter writes "it's broken" with no steps to reproduce, no environment, no severity. Or an incident gets logged without the services-affected checklist. You write a Confluence page titled "How to file a good bug," link to it from the project home, and nobody reads it. The tickets keep coming in malformed. The real fix is to put the template *on the ticket* — so the moment someone opens Create Issue for a bug, the description already has the "Steps to reproduce / Expected / Actual / Environment" structure, the right labels, and the right assignee. That's per-issue templating, and [**Modern Issue Templates for Jira**](https://marketplace.atlassian.com/apps/2564635381/modern-issue-templates-for-jira) does exactly that. This guide covers three ways to create issues from templates, from quickest to most customized. ![The Modern Issue Templates gallery showing the starter library of pre-built templates.](/assets/images/h0-daf9f727cbdfdd661b7b14d47c3cd64c.png) ## First: Jira project templates vs. issue templates — the distinction that matters[​](#first-jira-project-templates-vs-issue-templates--the-distinction-that-matters "Direct link to First: Jira project templates vs. issue templates — the distinction that matters") Jira ships with *project* templates (Scrum, Kanban, Bug Tracking) — but these only set up the project's scheme, issue types, and workflow. They do **not** pre-fill the content of individual issues. When someone creates a bug, they still start with a blank description. *Issue* templates are different: they pre-fill the **summary, description, labels, components, and even custom fields** of each new issue, based on its type and project. That's the gap Modern Issue Templates fills. If your team has a structure every bug/incident/story should follow, issue templates enforce it at creation time — no Confluence page required. ## Method 1: The Starter Library (fastest — 2 minutes)[​](#method-1-the-starter-library-fastest--2-minutes "Direct link to Method 1: The Starter Library (fastest — 2 minutes)") The fastest path to value is the curated **Starter Template Library**: 22 pre-built templates across Software Engineering, Operations, Product, Team & People, and General. Every template ships with summary and description pre-filled, and uses variables so it works out of the box. 1. In Jira, open **Apps → Modern Issue Templates**. 2. Click **Starter Library** in the toolbar. 3. Filter by category (e.g., Software Engineering) or browse all 22. 4. Click **Import** on the templates you want — they land in your template manager. 5. **Assign** each imported template to the project(s) where it should apply. This gets a team from zero to standardized tickets in two minutes, without authoring anything. The imported templates are fully editable, so you can tweak them after import. Common starters teams grab first: * **Bug report** — Steps to reproduce / Expected / Actual / Environment / Severity * **Incident** — Summary of impact / Affected services / Detected by / Mitigation * **Feature request** — Problem / Proposed solution / Success metric / Dependencies * **Spike** — Question to answer / Context / Timebox / Output ## Method 2: Create a custom template from scratch[​](#method-2-create-a-custom-template-from-scratch "Direct link to Method 2: Create a custom template from scratch") When the starters don't fit, author your own. 1. Open **Apps → Modern Issue Templates → New Template**. 2. Fill in the **Summary** (the issue title template) and **Description** (the body template). Both support rich text. 3. Use **variables** to make the template dynamic (see below). 4. **Assign** the template to a project and issue type. ![Editing a template\'s summary, description, and fields in the template editor.](/assets/images/h1-67d02f071b2e77e3bfef44a52a7cec0e.png) ### Variables that make templates dynamic[​](#variables-that-make-templates-dynamic "Direct link to Variables that make templates dynamic") Hardcoded templates go stale. Variables keep them accurate per-issue: | Variable | Resolves to | Example use | | ----------------- | --------------------------- | ------------------------------------ | | `{{currentUser}}` | The user creating the issue | "Reported by `\{\{currentUser\}\}`" | | `{{today}}` | Today's date | "Detected: `\{\{today\}\}`" | | `{{today+7d}}` | Today + 7 days | "Mitigation due: `\{\{today+7d\}\}`" | | `{{projectKey}}` | The project key | "Impact area: `\{\{projectKey\}\}`" | So a bug template's description might read: ``` h3. Steps to reproduce 1. 2. 3. h3. Expected h3. Actual h3. Environment - Reporter: {{currentUser}} - Detected: {{today}} - Severity: (S1 / S2 / S3) ``` Every new bug created from this template gets the reporter and date filled in automatically — no manual entry, no inconsistency. ## Method 3: Import from GitHub / Markdown / JSON[​](#method-3-import-from-github--markdown--json "Direct link to Method 3: Import from GitHub / Markdown / JSON") If your team already maintains issue templates in a GitHub repo (`.github/ISSUE_TEMPLATE/`), or writes them in Markdown, you don't need to re-author them in Jira. Modern Issue Templates imports directly from those sources. 1. Open **Apps → Modern Issue Templates → Import**. 2. Choose the source: **GitHub** (paste a repo URL or raw file URL), **Markdown** (paste text or upload `.md`), or **JSON** (paste or upload). 3. Map the imported content to the template's summary and description fields. 4. Assign to projects. This is how teams migrating from GitHub Issues to Jira preserve their existing template investment instead of rewriting it. ## Auto-applying templates by issue type[​](#auto-applying-templates-by-issue-type "Direct link to Auto-applying templates by issue type") The goal is for the *right* template to load automatically based on the issue type and project, with no manual template selection. Assign templates to projects in the template manager, and the app detects conflicts (two templates competing for the same issue type in the same project) and warns you. When configured: * Creating a **Bug** in the ENG project → loads the bug template * Creating an **Incident** in the OPS project → loads the incident template * Creating a **Story** anywhere → loads the story template The reporter doesn't need to know a template exists — they just create the issue and the structure is there. ### Multi-field pre-fill (Advanced edition)[​](#multi-field-pre-fill-advanced-edition "Direct link to Multi-field pre-fill (Advanced edition)") Beyond summary and description, the Advanced edition pre-fills **labels, due date, components, and custom fields** at issue creation. This is useful for compliance-driven workflows where, say, every incident must carry a specific label and component without relying on the reporter to remember. ## FAQ[​](#faq "Direct link to FAQ") ### Does Jira have built-in issue templates?[​](#does-jira-have-built-in-issue-templates "Direct link to Does Jira have built-in issue templates?") Jira has project templates (Scrum, Kanban, etc.) that set up a project's scheme, but it does **not** have per-issue content templates out of the box. To pre-fill the summary, description, and fields of individual issues, you need a Marketplace app like Modern Issue Templates for Jira. ### Can I import GitHub issue templates into Jira?[​](#can-i-import-github-issue-templates-into-jira "Direct link to Can I import GitHub issue templates into Jira?") Yes. Modern Issue Templates imports issue templates from GitHub repositories (`.github/ISSUE_TEMPLATE/`), as well as from Markdown files and JSON. This lets teams migrating from GitHub Issues to Jira keep their existing template structure. ### How do template variables work?[​](#how-do-template-variables-work "Direct link to How do template variables work?") Variables like `{{currentUser}}`, `{{today}}`, `{{today+7d}}`, and `{{projectKey}}` are resolved at issue creation time. When a user creates an issue from a template, the variables are replaced with real values — the current user, today's date, a date offset, or the project key. This keeps templates accurate without manual editing. ### What is the difference between Modern Issue Templates Standard and Advanced?[​](#what-is-the-difference-between-modern-issue-templates-standard-and-advanced "Direct link to What is the difference between Modern Issue Templates Standard and Advanced?") Both editions include template CRUD, the rich-text editor, GitHub/Markdown/JSON import, the 22-template starter library, variables, and multi-project assignment. The Advanced edition adds multi-field pre-fill (labels, due date, components, custom fields) and a full application log with CSV export. Both are free for up to 10 users. ### How many templates come in the Starter Library?[​](#how-many-templates-come-in-the-starter-library "Direct link to How many templates come in the Starter Library?") 22 pre-built templates across 5 categories: Software Engineering, Operations, Product, Team & People, and General. Each ships with summary and description pre-filled and demonstrates the variable system. They are fully editable after import. ### Is Modern Issue Templates for Jira free?[​](#is-modern-issue-templates-for-jira-free "Direct link to Is Modern Issue Templates for Jira free?") Yes — Modern Issue Templates is free for up to 10 users. Beyond 10 users, per-user pricing applies (Standard and Advanced tiers), scaling down as the team grows. ## Related guides[​](#related-guides "Direct link to Related guides") Try Modern Issue Templates for Jira Create issues from reusable templates with variables, GitHub import, and auto-apply — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/2564635381/modern-issue-templates-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-issue-templates-for-jira) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [issue-templates](/blog/tags/issue-templates.md) * [automation](/blog/tags/automation.md) * [how-to](/blog/tags/how-to.md) * [productivity](/blog/tags/productivity.md) --- # Create Mermaid diagrams in Confluence: a step-by-step guide April 21, 2026 · 5 min read [NGPilot](https://ngpilot.com) **Mermaid diagrams in Confluence** let you create flowcharts, sequence diagrams, and more using simple text syntax. This guide covers **Confluence Mermaid** setup with Mermaid Plus — live preview, 30 diagram types, and copy-paste examples. Who should read this * Developers adding diagrams to Confluence documentation * Teams switching from draw\.io to text-based diagrams (see [Excalidraw vs draw.io](/blog/faq-excalidraw-vs-drawio-confluence.md) if you're comparing visual tools too) * Anyone needing flowcharts, sequence diagrams, or ER diagrams in Confluence What you'll learn 1. How to set up Mermaid in Confluence 2. Creating flowcharts, sequence diagrams, Gantt charts 3. All 30 supported diagram types with examples 4. Troubleshooting common issues ## Quick prerequisites[​](#quick-prerequisites "Direct link to Quick prerequisites") * Confluence Cloud with [Mermaid Plus](/docs/Mermaid-Plus-for-Confluence/usage.md) (or Mermaid-enabled) app installed * Basic familiarity with Markdown-style editing in Confluence ## How to insert a Mermaid diagram[​](#how-to-insert-a-mermaid-diagram "Direct link to How to insert a Mermaid diagram") 1. Edit a Confluence page. 2. Insert the Mermaid macro (type `/mermaid` and choose the plugin). 3. Paste one of the examples below into the editor and preview. 4. Adjust labels, colors, and sizes as needed, then save. ## Best practices[​](#best-practices "Direct link to Best practices") * Start small and iterate: preview often while editing. * Use templates for repetitive diagrams. * Prefer simple node labels for readability. * Use `theme` and color settings for accessible contrast. ## Full list of common Mermaid diagram types (with examples)[​](#full-list-of-common-mermaid-diagram-types-with-examples "Direct link to Full list of common Mermaid diagram types (with examples)") ### Flowchart (graph)[​](#flowchart-graph "Direct link to Flowchart (graph)") A directed graph for processes and workflows. ``` graph TD A[Start] --> B{Is it ok?} B -- Yes --> C[Proceed] B -- No --> D[Fix issue] D --> B C --> E[Done] ``` ### Sequence diagram (sequenceDiagram)[​](#sequence-diagram-sequencediagram "Direct link to Sequence diagram (sequenceDiagram)") Interaction over time between participants. ``` sequenceDiagram participant Alice participant Bob Alice->>Bob: Request data Bob-->>Alice: Return result Alice->>Bob: Acknowledge ``` ### Class diagram (classDiagram)[​](#class-diagram-classdiagram "Direct link to Class diagram (classDiagram)") Model object-oriented classes and relationships. ``` classDiagram class Animal { +int age +eat() } class Dog { +bark() } Animal <|-- Dog ``` ### State diagram (stateDiagram-v2)[​](#state-diagram-statediagram-v2 "Direct link to State diagram (stateDiagram-v2)") Finite state machine transitions. ``` stateDiagram-v2 [*] --> Idle Idle --> Processing : start Processing --> Done : finish Done --> [*] ``` ### Entity-Relationship (erDiagram)[​](#entity-relationship-erdiagram "Direct link to Entity-Relationship (erDiagram)") Database entities and relations. ``` erDiagram CUSTOMER ||--o{ ORDER : places ORDER ||--|{ LINE_ITEM : contains CUSTOMER { string name int id } ``` ### Gantt chart (gantt)[​](#gantt-chart-gantt "Direct link to Gantt chart (gantt)") Project timelines with tasks and dependencies. ``` gantt title Project Schedule dateFormat YYYY-MM-DD section Design Research :a1, 2026-05-01, 10d Develop :after a1, 20d Test :2026-06-01, 10d ``` ### Pie chart (pie)[​](#pie-chart-pie "Direct link to Pie chart (pie)") Simple proportional data visualization. ``` pie title Time Allocation "Development" : 50 "Testing" : 30 "Meeting" : 20 ``` ### Git graph (gitGraph)[​](#git-graph-gitgraph "Direct link to Git graph (gitGraph)") Visualize branch and commit history. ``` gitGraph commit branch develop checkout develop commit checkout main merge develop commit ``` ### Mindmap (mindmap)[​](#mindmap-mindmap "Direct link to Mindmap (mindmap)") Hierarchical brainstorming diagrams. ``` mindmap root((Product)) Features Performance UX Roadmap Q2 Q3 ``` ### Timeline (timeline)[​](#timeline-timeline "Direct link to Timeline (timeline)") Chronological events. ``` timeline title Company milestones 2019 : Founded 2020 : First release 2022 : Series A ``` ### Requirement diagram (requirementDiagram)[​](#requirement-diagram-requirementdiagram "Direct link to Requirement diagram (requirementDiagram)") Traceability of requirements to elements. ``` requirementDiagram requirement R1 { id: 1 text: "Data export must support CSV" } element E1 { type: component } E1 - satisfies -> R1 ``` ### C4 & Architecture (C4Context)[​](#c4--architecture-c4context "Direct link to C4 & Architecture (C4Context)") High-level system context diagrams. ``` C4Context title System Context Person(user, "User") System(api, "Public API") Rel(user, api, "Uses") ``` ### Quadrant chart (quadrantChart)[​](#quadrant-chart-quadrantchart "Direct link to Quadrant chart (quadrantChart)") Two-axis analysis charts. ``` quadrantChart title Feature Analysis x-axis Low --> High y-axis Low --> High quadrant-1 Prioritize quadrant-2 Consider Item A: [0.7, 0.6] Item B: [0.2, 0.8] ``` ### Sankey diagram (sankey)[​](#sankey-diagram-sankey "Direct link to Sankey diagram (sankey)") Bulk flow volumes between nodes. ``` sankey A [Source] -> B [Target] : 100 A -> C : 50 C -> B : 30 ``` ### XY chart (xychart)[​](#xy-chart-xychart "Direct link to XY chart (xychart)") Line and bar charts for time-series or categorical data. ``` xychart title Revenue x-axis [Q1,Q2,Q3,Q4] y-axis "USD" line [30,40,50,60] ``` ### Block diagram (block)[​](#block-diagram-block "Direct link to Block diagram (block)") Simple block/column diagrams. ``` block A[Frontend] --> B[API] B --> C[Database] ``` ### Packet diagram (packet)[​](#packet-diagram-packet "Direct link to Packet diagram (packet)") Network packet structure. ``` packet 0-15: Source Port 16-31: Destination Port 32-63: Sequence Number ``` ### Kanban (kanban)[​](#kanban-kanban "Direct link to Kanban (kanban)") Board-style task flow. ``` kanban To Do Task A In Progress Task B Done Task C ``` ### Treemap (treemap)[​](#treemap-treemap "Direct link to Treemap (treemap)") Hierarchical data as nested rectangles. ``` treemap "Category A" "Item 1" : 10 "Item 2" : 20 ``` ### Ishikawa / Fishbone (ishikawa)[​](#ishikawa--fishbone-ishikawa "Direct link to Ishikawa / Fishbone (ishikawa)") Cause-and-effect analysis. ``` ishikawa Problem: "Low throughput" People Lack of training Process Missing steps ``` ### Venn diagram (venn)[​](#venn-diagram-venn "Direct link to Venn diagram (venn)") Set relationships. ``` venn A B A & B ``` ### ZenUML (zenuml)[​](#zenuml-zenuml "Direct link to ZenUML (zenuml)") Alternative sequence diagram syntax. ``` zenuml title Login Flow Actor User System API User -> API: login() ``` ## Troubleshooting & tips[​](#troubleshooting--tips "Direct link to Troubleshooting & tips") * If diagrams don't render, check the plugin settings or try the Mermaid Live Editor to validate syntax. * Use small examples while iterating; large diagrams can be hard to edit inside Confluence. * For accessibility, prefer clear color contrasts and short labels. ## Related apps & resources[​](#related-apps--resources "Direct link to Related apps & resources") * [All 30 Mermaid diagram types in Confluence](/blog/faq-mermaid-diagram-types-confluence.md) — complete reference across every diagram type * [Mermaid Plus Diagrams & AI Agent for Confluence](/apps/mermaid-plus-for-confluence.md) * [Mermaid Plus Diagrams for Jira](/apps/mermaid-plus-diagrams-for-jira.md) — add Mermaid diagrams to Jira issues * [Excalidraw & Mermaid Visual Editor](/apps/excalidraw-mermaid-diagrams-for-confluence.md) — combine freeform drawing with Mermaid * [Graphviz Charts for Confluence](/apps/graphviz-charts-for-confluence.md) — another diagram format option ## More Related Guides[​](#more-related-guides "Direct link to More Related Guides") * [Mermaid Plus Diagrams & AI Agent for Confluence](/apps/mermaid-plus-for-confluence.md) — Full feature guide * [Does Confluence support Mermaid?](/blog/does-confluence-support-mermaid.md) — Setup guide * [Mermaid diagram types explained](/blog/faq-mermaid-diagram-types-confluence.md) — All 30 types Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [diagrams](/blog/tags/diagrams.md) * [how-to](/blog/tags/how-to.md) --- # Mermaid App Roundup for Confluence — Mermaid Plus vs Stratus vs weweave April 12, 2026 · 6 min read [NGPilot](https://ngpilot.com) Engineering teams need diagrams in Confluence — flowcharts for runbooks, sequence diagrams for API docs, ER models for database schemas, architecture diagrams for design decisions. Writing diagrams as code (text-based syntax) is faster than drag-and-drop for developers. Mermaid is the most popular text-based diagram language. Several marketplace apps bring Mermaid to Confluence, plus the major visual diagramming tools (draw\.io, Gliffy, Lucidchart) also support it. We built **Mermaid Plus Diagrams & AI Agent for Confluence** to offer 30 diagram types with live preview, one-click templates, and a built-in syntax guide. In this post we compare it against every alternative. ## Text-Based vs Visual Diagramming[​](#text-based-vs-visual-diagramming "Direct link to Text-Based vs Visual Diagramming") **Text-based (Mermaid)** — You write code, the app renders a diagram. Fast for developers. Version-controllable. Easy to update. Flowcharts, sequence diagrams, ER models, class diagrams, Gantt charts. **Visual (draw\.io, Gliffy, Lucidchart)** — You drag and drop shapes with a mouse. More flexible for complex layouts. Better for non-technical users. No syntax to learn. Both approaches are valid. This post focuses on **text-based Mermaid apps** for teams that prefer writing diagrams as code. We also cover the visual alternatives for comparison. ## What's Available on the Marketplace[​](#whats-available-on-the-marketplace "Direct link to What's Available on the Marketplace") ### Mermaid-Specific Apps[​](#mermaid-specific-apps "Direct link to Mermaid-Specific Apps") | App | Vendor | Installs | Rating | Last Updated | Hosting | | --------------------------------------------------- | --------------- | -------- | ------------------ | ------------ | ---------- | | Mermaid Diagrams for Confluence | Stratus Add-ons | 5,974 | 3.2/5 (22 reviews) | Jan 2026 | DC only | | Mermaid Charts & Diagrams | weweave | 1,794 | 3.7/5 (15 reviews) | Apr 2026 | Cloud + DC | | Mermaid for Confluence | Tech Labs | 566 | 4.0/5 (2 reviews) | Dec 2024 | Cloud | | Mermaid Integration for Confluence | Toshihiro Sato | 579 | 3.3/5 (7 reviews) | Sep 2025 | DC only | | **Mermaid Plus Diagrams & AI Agent for Confluence** | **NGPILOT** | **New** | — | **2026** | **Cloud** | ### Major Visual Diagramming Apps (for reference)[​](#major-visual-diagramming-apps-for-reference "Direct link to Major Visual Diagramming Apps (for reference)") | App | Vendor | Installs | Rating | Last Updated | Hosting | | -------------------- | ------- | -------- | --------------------- | ------------ | ---------- | | draw\.io Diagrams | Seibert | 66,827 | 3.9/5 (1,197 reviews) | Apr 2026 | Cloud + DC | | Lucidchart Connector | Lucid | 27,558 | 2.8/5 (258 reviews) | Mar 2026 | Cloud + DC | | Gliffy Diagrams | Gliffy | 17,768 | 3.6/5 (797 reviews) | Apr 2026 | Cloud + DC | *Data from Atlassian Marketplace, April 2026.* **draw\.io** dominates the entire diagram market with 66,827 installs. It supports Mermaid alongside its visual editor, but it's primarily a drag-and-drop tool with premium pricing ($975/yr for 50 users). **Stratus Add-ons' Mermaid Diagrams** (5,974 installs) leads the Mermaid-specific category but its latest version is **Data Center only** — no Cloud version available. **weweave's Mermaid Charts** (1,794 installs) is the most established Cloud + DC option with Cloud Fortified status. **The Cloud Mermaid market is underserved** — the two highest-installed Mermaid apps (Stratus and weweave) are DC-focused or dual-hosted. Teams on Confluence Cloud have limited options. ## Feature Comparison: Mermaid Apps[​](#feature-comparison-mermaid-apps "Direct link to Feature Comparison: Mermaid Apps") | Feature | Mermaid Plus (NGPILOT) | Mermaid Diagrams (Stratus) | Mermaid Charts (weweave) | Mermaid for Confluence (Tech Labs) | Mermaid Integration (Toshihiro Sato) | | ------------------------- | ----------------------------------------- | -------------------------- | ------------------------ | ---------------------------------- | ------------------------------------ | | **Diagram types** | 29 | Limited | Limited | Standard | Standard | | **Live preview** | Yes | No | No | No | Yes | | **Quick templates** | 29 (one per type) | No | No | No | No | | **Built-in syntax guide** | Yes (29 examples) | No | No | No | No | | **Custom colors** | 5 (Node, Text, Border, Line, Bg) | No | No | No | No | | **Font selection** | 5 families | No | No | No | No | | **Theme support** | 4 themes (Default, Dark, Forest, Neutral) | No | No | No | No | | **Dark mode** | Auto-adapts to Confluence | No | No | No | No | | **Output size control** | 4 sizes | No | No | No | No | | **Cached SVG rendering** | Yes (library loaded only during editing) | No | No | No | No | | **Cloud hosting** | Yes | No (DC only) | Yes | Yes | No (DC only) | | **Data Center support** | No | Yes | Yes | No | Yes | | **Cloud Fortified** | No | Yes | Yes | No | No | ### Where Mermaid Plus Stands Out[​](#where-mermaid-plus-stands-out "Direct link to Where Mermaid Plus Stands Out") **Most diagram types** — 30 Mermaid diagram types including flowchart, sequence, class, state, ER, C4 architecture, Gantt, mindmap, timeline, Git graph, pie chart, radar, Sankey, Kanban, architecture, Venn, Ishikawa, and more. More than any other Mermaid Confluence app. **Built-in syntax guide** — Click the **?** button to browse all 30 diagram types with descriptions and code examples. Insert any template directly into the editor. No need to leave Confluence to look up Mermaid syntax. **Live preview** — See your diagram render in real-time as you type. Other Mermaid apps show the diagram only after saving. **One-click templates** — 30 templates, one for each diagram type. Click a template to load starter code, then customize it. **Full customization** — Five color pickers (node, text, border, line, background), five font families, four output sizes, and four Mermaid themes. No other Mermaid app offers this level of styling control. **Performance-first** — Diagrams render from cached SVG on page load. The Mermaid.js library is only loaded during editing, not when viewing pages. Your Confluence stays fast. **Auto dark mode** — Diagrams automatically adapt to Confluence's dark/light theme without manual configuration. ### Where We Could Improve[​](#where-we-could-improve "Direct link to Where We Could Improve") * **New app** — We recently launched with no install history yet. Stratus has 5,974 installs and years of market presence. * **No Data Center support** — Cloud-only for now. If you're on Confluence Data Center, Stratus or weweave are your best options. * **No Cloud Fortified status** — Stratus and weweave have completed Atlassian's Cloud Fortified program. We're working toward this. * **No PDF export** — Stratus offers PDF export of rendered diagrams. We focus on inline rendering. * **No version history** — Stratus supports diagram version history. We store the Mermaid source in the macro for re-editing but don't track versions. ## Honest Comparison: NGPILOT vs Stratus (Mermaid Market Leader)[​](#honest-comparison-ngpilot-vs-stratus-mermaid-market-leader "Direct link to Honest Comparison: NGPILOT vs Stratus (Mermaid Market Leader)") | | Mermaid Diagrams (Stratus) | Mermaid Plus (NGPILOT) | | ------------------- | --------------------------------- | ------------------------------------------------- | | **Installs** | 5,974 | New | | **Rating** | 3.2/5 (22 reviews) | — | | **Cloud** | No (DC only) | Yes | | **Diagram types** | Standard set | 29 (most comprehensive) | | **Live preview** | No | Yes | | **Syntax guide** | No | Yes (29 examples) | | **Templates** | No | 29 one-click templates | | **Custom colors** | No | 5 customizable colors | | **Themes** | No | 4 themes + auto dark mode | | **PDF export** | Yes | No | | **Cloud Fortified** | Yes | No | | **Best for** | Data Center teams needing Mermaid | Cloud teams wanting full-featured Mermaid editing | Stratus is the established choice for Data Center deployments. Our app is the better choice for Cloud teams that want a complete Mermaid editing experience with live preview, templates, and customization. ## Which App Do You Need?[​](#which-app-do-you-need "Direct link to Which App Do You Need?") | You need... | Use this | | ---------------------------------------- | --------------------------------------------------- | | Visual drag-and-drop diagramming | draw\.io by Seibert (66,827 installs) | | Mermaid on Data Center | Mermaid Diagrams by Stratus (5,974 installs) | | Budget-friendly Cloud Mermaid | Mermaid Charts by weweave ($115/yr for 50 users) | | The most diagram types with live preview | **Mermaid Plus Diagrams & AI Agent for Confluence** | | Built-in syntax guide and templates | **Mermaid Plus Diagrams & AI Agent for Confluence** | | Dark mode and full color customization | **Mermaid Plus Diagrams & AI Agent for Confluence** | ## Related Posts[​](#related-posts "Direct link to Related Posts") * [Excalidraw for Confluence — Which Whiteboard and Drawing App Fits Your Team?](/blog/use-excalidraw-in-confluence-whiteboard-diagrams.md) * [Diagram Apps for Jira — Which Diagramming Tool Should Your Team Use?](/blog/jira-diagram-apps-comparison.md) ## Get Started[​](#get-started "Direct link to Get Started") * Install **Mermaid Plus Diagrams & AI Agent for Confluence** from the [Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence) * [Read the full documentation](/docs/Mermaid-Plus-for-Confluence/usage.md) Have questions or feedback? Reach out to us at — we'd love to hear from you. Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [Best Diagram Tool for Confluence — Compared](/blog/confluence-diagram-tools-comparison.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [mermaid](/blog/tags/mermaid.md) * [diagrams](/blog/tags/diagrams.md) * [confluence](/blog/tags/confluence.md) --- # How to Display JSON, XML, YAML & Code in Confluence (With Syntax Highlighting) July 23, 2026 · 10 min read [NGPilot](https://ngpilot.com) Who should read this * **Developer teams** documenting APIs, configs, and schemas in Confluence * **Tech writers** who need formatted code samples alongside prose * **Anyone** pasting JSON, XML, YAML, or SQL into Confluence and getting an unreadable wall of text What you'll learn 1. Why Confluence's built-in code block struggles with JSON, XML, and config files 2. How to embed syntax-highlighted code in 85+ languages using a Monaco-powered editor 3. Theme configuration, diff views, and screenshot-ready window chrome 4. When to use a code block vs. a visual JSON structure diagram The scenario every engineering team hits: you're documenting an API in Confluence, and the page needs to show a JSON response, an XML config, a YAML deployment manifest, and a SQL query — all on the same page. You paste each one into Confluence's built-in code block macro, publish, and the result is a wall of monochrome text. No syntax colors. No line numbers that work. JSON braces, XML tags, and YAML indentation all blur together. The reader has to copy-paste your snippet into VS Code just to understand it. The root problem is that Confluence's native code block uses a basic highlighter that wasn't built for the structured data formats modern teams actually work with. JSON, XML, YAML, and SQL each have specific visual conventions — matched braces, nested tags, indentation scopes — that a generic highlighter doesn't handle well. [**Modern Code Blocks for Confluence**](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence) solves this by bringing the Monaco Editor — the same engine that powers VS Code — into Confluence. It accurately highlights 85+ languages including JSON, XML, YAML, SQL, GraphQL, Terraform, Dockerfile, and every mainstream programming language. This guide walks through embedding formatted code and data formats in your Confluence pages. ## Why the native Confluence code block falls short for JSON and XML[​](#why-the-native-confluence-code-block-falls-short-for-json-and-xml "Direct link to Why the native Confluence code block falls short for JSON and XML") Confluence ships with a built-in Code Block macro. It works for short snippets, but teams documenting real systems run into three recurring problems: **1. Limited and inaccurate syntax highlighting.** The native macro uses a basic regex highlighter. For JSON, nested objects and arrays often lose their color context as depth increases. For XML, attribute values and tag names aren't consistently distinguished. YAML's indentation-based scoping — where a single misaligned space breaks the file — gets no visual emphasis at all. **2. No live preview while editing.** You write code into a plain text area and only see how it renders after you save and publish. If the highlighting is wrong or a line wraps awkwardly, you're back into edit mode to fix it. This round-trip adds up when you're building an API doc page with 10+ code samples. **3. No theme control.** The native block has a single visual style. If your Confluence is in dark mode, the code block doesn't match — it stays light. There's no way to pick a theme that fits your page or your team's preference. ## The Monaco Editor difference[​](#the-monaco-editor-difference "Direct link to The Monaco Editor difference") Monaco is the editor technology behind VS Code. It understands language grammar at a deep level — not just keywords, but token types, bracket matching, and scope-aware coloring. When you bring it into Confluence via Modern Code Blocks, JSON, XML, and YAML get the same quality of highlighting you'd see in your IDE. | Format | Native Confluence code block | Modern Code Blocks (Monaco) | | ----------- | -------------------------------------------------- | ------------------------------------------------------------------------------ | | **JSON** | Flat highlighting; nested objects lose color depth | Key, string, number, boolean tokens each get distinct colors; bracket matching | | **XML** | Tags and attributes often the same color | Tag names, attributes, values, and comments all differentiated | | **YAML** | Treated as plain text in most cases | Keys, values, anchors, and comments highlighted; indentation visually clear | | **SQL** | Basic keyword highlighting | Dialect-aware (MySQL, PostgreSQL); keywords, functions, strings separated | | **Theme** | One fixed style | Auto light/dark + 50+ premium themes (Monokai, Dracula, GitHub Dark, …) | | **Editing** | Plain text area, no preview | Monaco editor with live preview before you save | ## Step-by-step: display formatted JSON, XML, or YAML in Confluence[​](#step-by-step-display-formatted-json-xml-or-yaml-in-confluence "Direct link to Step-by-step: display formatted JSON, XML, or YAML in Confluence") ### 1. Install Modern Code Blocks for Confluence[​](#1-install-modern-code-blocks-for-confluence "Direct link to 1. Install Modern Code Blocks for Confluence") Go to the [Modern Code Blocks listing](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence) on the Atlassian Marketplace and click **Get it now**. The app installs into your Confluence Cloud instance. It's free for up to 10 users. Once installed, the macro appears in Confluence's macro browser under the name **Modern Code Blocks for Confluence**. ### 2. Insert the code block macro[​](#2-insert-the-code-block-macro "Direct link to 2. Insert the code block macro") Edit any Confluence page. In the editor, type `/modern code` or `/code` and select **Modern Code Blocks for Confluence** from the dropdown. The configuration panel opens with the Monaco editor on the left and settings on the right. ### 3. Paste your content and pick a language[​](#3-paste-your-content-and-pick-a-language "Direct link to 3. Paste your content and pick a language") Paste your JSON, XML, YAML, SQL, or any code into the Monaco editor. Then select the language from the **Language** dropdown. The editor immediately applies accurate syntax highlighting. Here's what each major format looks like: **JSON** — select "JSON" from the language dropdown. Keys, string values, numbers, booleans, and null each get distinct colors. Nested objects and arrays are bracket-matched, so readers can trace structure at a glance. This is the format teams search for most: *"how to show JSON in Confluence"*. **XML** — select "XML". Tag names, attribute names, attribute values, comments, and CDATA sections are all visually differentiated. This matters for teams documenting SOAP APIs, Maven POMs, or Confluence's own storage format. **YAML** — select "YAML". Keys, values, comments, and anchors are highlighted. Because YAML's structure depends entirely on indentation, the visual emphasis on scope helps readers spot misalignment that would break parsing. **SQL** — select your dialect (MySQL, PostgreSQL, or generic SQL). Keywords, function names, string literals, and numeric values are separated. The full supported list covers 85+ languages, including Python, TypeScript, Go, Rust, Java, C#, GraphQL, Terraform, Dockerfile, Shell/Bash, and more. ### 4. Configure the theme and display[​](#4-configure-the-theme-and-display "Direct link to 4. Configure the theme and display") Before saving, configure how the block looks to readers: * **Theme** — **Auto** matches each reader's Confluence light/dark setting automatically. Or pick a fixed theme: 4 built-ins (VS Code Light, VS Code Dark, High Contrast) or 50+ premium themes in the Advanced edition (Monokai, Dracula, Nord, Solarized, GitHub Dark, One Dark Pro, and more). * **Line Numbers** — On, Off, or Relative (relative numbering is useful for Vim users reading vimdiff-style output). * **Font Size** — 8–32px. The default 14px works for most documentation; bump to 16px for presentation pages. * **Max Height** — the block auto-sizes to fit content, up to this limit (100–5000px). Code beyond the limit scrolls. This prevents a 500-line JSON file from consuming the entire page. * **Word Wrap** — wrap long lines or allow horizontal scroll. For JSON with long single-line values, wrapping is usually kinder to readers. * **Show Minimap** — a VS Code-style code overview in the corner. Useful for very long code samples where readers need to jump around. ### 5. Save and publish[​](#5-save-and-publish "Direct link to 5. Save and publish") Click **Save** to insert the rendered code block. Publish the page. Every viewer sees the code with your chosen language highlighting and theme — the rendering is consistent across readers, browsers, and Confluence themes. ## Advanced: diff views for migration guides and changelogs[​](#advanced-diff-views-for-migration-guides-and-changelogs "Direct link to Advanced: diff views for migration guides and changelogs") When you're documenting a code change — a config migration, an API version bump, a refactor — a before/after comparison is clearer than two separate blocks. Modern Code Blocks (Advanced edition) supports a **Diff View**: 1. Set **View Mode** to **Diff** 2. Paste a unified diff (`.patch` / `.diff` format) or upload a `.patch` file 3. Pick a **Render Mode**: * **Raw** — the patch text with `+` lines in green, `-` lines in red (GitHub-style) * **Inline** — the diff parsed and interleaved into a single view (the layout `git diff` produces) 4. Optionally choose a separate theme for the diff block This is ideal for release notes, migration guides, and changelogs where the reader needs to see exactly what changed. ## Advanced: window chrome for screenshot-ready snippets[​](#advanced-window-chrome-for-screenshot-ready-snippets "Direct link to Advanced: window chrome for screenshot-ready snippets") If you're publishing code samples to marketing pages, landing pages, or external-facing documentation, plain code blocks can look flat. The Advanced edition's **Window Chrome** option wraps your block in an OS-style title bar: * **macOS** — three traffic-light buttons on the left * **Windows** — three caption buttons on the right The title bar auto-derives a filename from your selected language (`main.js` for JavaScript, `config.yaml` for YAML, `response.json` for JSON). The result looks like a screenshot from a real editor — the aesthetic popularized by [carbon.now.sh](https://carbon.now.sh) and [ray.so](https://ray.so), but inline in your Confluence page. ## When to use a code block vs. a visual JSON diagram[​](#when-to-use-a-code-block-vs-a-visual-json-diagram "Direct link to When to use a code block vs. a visual JSON diagram") Modern Code Blocks and [JSON Structure Viewer for Confluence](/docs/json-structure-viewer-for-confluence/usage.md) serve different purposes. Here's how to choose: | You want to… | Use | | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | Show formatted, syntax-highlighted JSON/XML/YAML/code that developers can read like an IDE | **Modern Code Blocks** | | Visualize the *structure* of a JSON object as a collapsible tree or diagram for non-developers | **JSON Structure Viewer** | | Show a JSON API response in a developer guide | **Modern Code Blocks** (developers want syntax colors) | | Show a complex nested JSON schema to a business analyst | **JSON Structure Viewer** (they want the tree view) | Many teams use both on the same page: a code block for the raw JSON, and a structure diagram below it for the visual breakdown. ## FAQ[​](#faq "Direct link to FAQ") ### Does Confluence have a native way to display JSON?[​](#does-confluence-have-a-native-way-to-display-json "Direct link to Does Confluence have a native way to display JSON?") Confluence's built-in Code Block macro supports JSON as a language, but its highlighting is basic — nested structures lose color depth, and there's no live preview. For JSON-heavy documentation (APIs, configs), a Monaco-powered editor like Modern Code Blocks produces significantly more readable output. ### Can I display XML and YAML in Confluence too?[​](#can-i-display-xml-and-yaml-in-confluence-too "Direct link to Can I display XML and YAML in Confluence too?") Yes. Modern Code Blocks supports XML, YAML, JSON, and 85+ other languages with accurate Monaco-based highlighting. Each format gets language-aware token coloring — XML tag names vs. attributes, YAML keys vs. values, etc. ### How do I show code in Confluence dark mode?[​](#how-do-i-show-code-in-confluence-dark-mode "Direct link to How do I show code in Confluence dark mode?") Modern Code Blocks has an **Auto** theme that matches each reader's Confluence light/dark setting automatically. When Confluence is in dark mode, the code block renders in VS Code Dark; in light mode, it uses VS Code Light. You can also force a specific theme per block. ### Can I copy code from a Confluence page?[​](#can-i-copy-code-from-a-confluence-page "Direct link to Can I copy code from a Confluence page?") Yes. Every Modern Code Blocks snippet includes a copy button in the top-right corner for one-click copying. This is especially useful for JSON configs and SQL queries that readers need to paste elsewhere. ### How many languages does Modern Code Blocks support?[​](#how-many-languages-does-modern-code-blocks-support "Direct link to How many languages does Modern Code Blocks support?") 85+ languages, including JSON, XML, YAML, SQL (MySQL, PostgreSQL), Python, TypeScript, JavaScript, Go, Rust, Java, C#, GraphQL, Terraform, Dockerfile, Shell/Bash, HTML, CSS/SCSS, PHP, Ruby, Scala, Kotlin, Swift, and many more. ### Is Modern Code Blocks free?[​](#is-modern-code-blocks-free "Direct link to Is Modern Code Blocks free?") Modern Code Blocks is free for up to 10 users. The Advanced edition (50+ premium themes, diff view, window chrome) is unlocked by the license tier purchased on the Atlassian Marketplace. Trial licenses unlock all Advanced features for the duration of the trial. ## Related guides[​](#related-guides "Direct link to Related guides") Try Modern Code Blocks for Confluence Monaco editor, 85+ languages (JSON, XML, YAML, SQL), 50+ themes, diff view, and auto dark/light mode — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-code-blocks-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [json](/blog/tags/json.md) * [xml](/blog/tags/xml.md) * [yaml](/blog/tags/yaml.md) * [code-blocks](/blog/tags/code-blocks.md) * [syntax-highlighting](/blog/tags/syntax-highlighting.md) * [how-to](/blog/tags/how-to.md) * [api-documentation](/blog/tags/api-documentation.md) --- # Does Confluence Support Mermaid? Setup Guide & Diagram Types May 6, 2026 · 4 min read [NGPilot](https://ngpilot.com) No, Confluence does not support Mermaid diagrams natively. There is no built-in macro or feature that renders Mermaid syntax in Confluence pages. To add Mermaid diagrams to Confluence, you need a Marketplace app. This guide covers how to set up Mermaid in Confluence and which diagram types you can create. ## How to add Mermaid to Confluence[​](#how-to-add-mermaid-to-confluence "Direct link to How to add Mermaid to Confluence") [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?hosting=cloud\&tab=overview) adds a full Mermaid diagram editor to Confluence. It supports 30 diagram types with a live preview, built-in templates, and multiple themes. ### Installation[​](#installation "Direct link to Installation") 1. Go to [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?hosting=cloud\&tab=overview) on the Atlassian Marketplace 2. Click **Get it now** — the app installs into your Confluence Cloud instance 3. Mermaid Plus is free for up to 10 users ### Creating your first diagram[​](#creating-your-first-diagram "Direct link to Creating your first diagram") 1. Open a Confluence page in edit mode 2. Type `/mermaid` and select **Mermaid Plus** from the macro dropdown 3. The macro opens a split-pane editor with a code editor on the left and live preview on the right 4. Paste or write your Mermaid syntax — the preview updates in real time 5. Click **Save** on the macro, then publish the page ## Mermaid diagram types supported in Confluence[​](#mermaid-diagram-types-supported-in-confluence "Direct link to Mermaid diagram types supported in Confluence") Mermaid Plus supports 30 diagram types. Here are the most popular ones: ### Flowcharts[​](#flowcharts "Direct link to Flowcharts") ``` flowchart TD A[Start] --> B{Decision} B -->|Yes| C[Action 1] B -->|No| D[Action 2] C --> E[End] D --> E ``` Read the full tutorial: [Create flowcharts in Confluence](/blog/create-flowcharts-confluence.md). ### Sequence diagrams[​](#sequence-diagrams "Direct link to Sequence diagrams") ``` sequenceDiagram Client->>API: POST /login API->>Auth: Validate credentials Auth-->>API: Token API-->>Client: 200 OK + Token ``` ### Class diagrams[​](#class-diagrams "Direct link to Class diagrams") ``` classDiagram class User { +String name +String email +login() } class Order { +Date created +Float total +checkout() } User --> Order : places ``` ### ER diagrams[​](#er-diagrams "Direct link to ER diagrams") ``` erDiagram CUSTOMER ||--o{ ORDER : places ORDER ||--|{ LINE-ITEM : contains CUSTOMER { string name string email } ORDER { date created float total } ``` ### Gantt charts[​](#gantt-charts "Direct link to Gantt charts") ``` gantt title Project Timeline section Phase 1 Research :a1, 2026-01-01, 30d Design :a2, after a1, 20d section Phase 2 Development :a3, after a2, 45d Testing :a4, after a3, 15d ``` ### Mindmaps[​](#mindmaps "Direct link to Mindmaps") ``` mindmap root((Confluence)) Diagrams Flowcharts Sequence Class Documents Markdown Code Blocks ``` ### More diagram types[​](#more-diagram-types "Direct link to More diagram types") | Category | Diagram Types | | ---------- | ------------------------------------- | | Structured | Flowchart, Sequence, Class, State, ER | | Planning | Gantt, Timeline, Requirement | | Charts | Pie, XYChart, Blockbench | | Visual | Mindmap, Quadrant | | Technical | GitGraph, C4, Architecture | | Other | Journey, Sankey,radar | See all 30 types: [Mermaid diagram types FAQ](/blog/faq-mermaid-diagram-types-confluence.md). ## Mermaid Plus features[​](#mermaid-plus-features "Direct link to Mermaid Plus features") * **Live preview** — see your diagram render as you type * **Template library** — one-click templates for every diagram type * **Multiple themes** — default, dark, forest, neutral * **Export** — download diagrams as PNG or SVG * **Auto-resize** — diagrams scale to fit the page width ## Alternatives to Mermaid in Confluence[​](#alternatives-to-mermaid-in-confluence "Direct link to Alternatives to Mermaid in Confluence") | App | Input Method | Best For | | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ---------------------------------- | | [Mermaid Plus](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?hosting=cloud\&tab=overview) | Text (Mermaid syntax) | Structured diagrams, documentation | | [Excalidraw Plus](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence?hosting=cloud\&tab=overview) | Visual (drag & drop) | Freeform drawing, wireframes | | [Graphviz Charts](https://marketplace.atlassian.com/apps/1237659/graphviz-charts-for-confluence?hosting=cloud\&tab=overview) | Text (DOT language) | Network graphs, dependency trees | Read the full comparison: [Confluence diagram tools compared](/blog/confluence-diagram-tools-comparison.md). ## Related resources[​](#related-resources "Direct link to Related resources") * [Mermaid Plus — marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?hosting=cloud\&tab=overview) | [documentation](/apps/mermaid-plus-for-confluence.md) * [Create Mermaid diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md) * [Mermaid troubleshooting FAQ](/blog/faq-mermaid-troubleshooting.md) * [Mermaid syntax cheat sheet](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md) * [Confluence diagram tools comparison](/blog/confluence-diagram-tools-comparison.md) * [Best Confluence apps for developers](/blog/best-confluence-apps-developers.md) Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [diagrams](/blog/tags/diagrams.md) * [flowcharts](/blog/tags/flowcharts.md) * [sequence-diagram](/blog/tags/sequence-diagram.md) * [gantt](/blog/tags/gantt.md) * [mindmap](/blog/tags/mindmap.md) --- # How to Edit the Confluence Storage Format (And When You'd Need To) July 23, 2026 · 7 min read [NGPilot](https://ngpilot.com) Who should read this * **Confluence admins** fixing broken pages, macros, or corrupted formatting * **Developers** migrating or bulk-editing page content via the storage format * **Power users** who need find-and-replace across a page's underlying XML What you'll learn 1. What the Confluence storage format is and why you'd edit it directly 2. How to open the raw XML of a page and make safe changes 3. Formatting, find-and-replace, and diffing changes before saving 4. When editing storage format is the right tool (and when it isn't) Most Confluence users never see it, but every page is stored as an XML document in Confluence's *storage format* — a specific XHTML dialect with custom tags for macros, layouts, and embeddings. The visual editor hides this. But sometimes the only way to fix a problem is to edit that XML directly: a macro is corrupted and won't render, a copy-paste introduced broken formatting, or you need to find-and-replace a URL across a long page that the visual editor can't reach. Confluence exposes the storage format through its REST API, but there's no built-in visual editor for it. [**Raw Storage Source Editor for Confluence**](https://marketplace.atlassian.com/apps/1237026) adds one — a Monaco-powered editor that opens the raw storage XML of any page, with format, find-and-replace, and (in the Pro edition) a diff view. This guide covers when and how to use it safely. ## What is the Confluence storage format?[​](#what-is-the-confluence-storage-format "Direct link to What is the Confluence storage format?") The storage format is the canonical representation of a Confluence page — the XML that Confluence itself stores and renders. It looks like this: ```

Project Overview

This document covers the Q3 release plan.

Reviewers: please comment by Friday.

 ``` Standard HTML tags (`

`, `

`, ``) sit alongside Confluence-specific namespaced tags (``, ``, ``). Macros, layouts, embedded images, and links all have dedicated storage-format tags. When you edit in the visual editor, Confluence updates this XML behind the scenes. When you edit the XML directly, you're changing exactly what Confluence stores. ## When you'd edit the storage format directly[​](#when-youd-edit-the-storage-format-directly "Direct link to When you'd edit the storage format directly") Editing storage format is a power-user tool. It's the right approach when: | Problem | Why storage-format editing helps | | ---------------------------------------------- | ------------------------------------------------------------------------- | | **A macro is corrupted and won't render** | The macro's XML is malformed; fix the tag structure directly | | **Broken formatting from a bad copy-paste** | Pasted content left stray tags; clean them out of the XML | | **Find-and-replace across a long page** | The visual editor's find is limited; the XML editor has full find/replace | | **Bulk-editing repeated structures** | e.g. updating the same macro parameter in 20 places on one page | | **Removing an embedded resource that's stuck** | A broken `` reference that the UI won't let you delete | | **Migrating content between formats** | Inspecting and adjusting the XML during a migration | It is **not** the right tool for everyday editing — the visual editor is faster and safer for normal content changes. Use the source editor when the visual editor can't reach or fix the problem. ## Step-by-step: edit a page's storage format[​](#step-by-step-edit-a-pages-storage-format "Direct link to Step-by-step: edit a page's storage format") ### 1. Install Raw Storage Source Editor for Confluence[​](#1-install-raw-storage-source-editor-for-confluence "Direct link to 1. Install Raw Storage Source Editor for Confluence") Install [Raw Storage Source Editor for Confluence](https://marketplace.atlassian.com/apps/1237026) (Free edition) or [Source Editor Pro](https://marketplace.atlassian.com/apps/1237026) from the Marketplace. Both are free for up to 10 users. After installation, a **Source Editor** option appears in the More Actions menu on every page. ### 2. Open the source editor[​](#2-open-the-source-editor "Direct link to 2. Open the source editor") Open the Confluence page you want to edit. Click the **More Actions** (⋯) button and choose **Source Editor for Confluence**. The editor opens, showing the page's raw storage format XML. ### 3. Edit, format, or find-and-replace[​](#3-edit-format-or-find-and-replace "Direct link to 3. Edit, format, or find-and-replace") The editor is Monaco-based (the same engine as VS Code), so the shortcuts are familiar: * **Format Document** — right-click and choose *Format Document* to clean up messy or inconsistently indented XML. This makes the structure readable before you edit. * **Find / Find and Replace** — `Ctrl+F` (find) and `Ctrl+H` (find and replace). Useful for updating a repeated value (a URL, a parameter) across the page. * **Command palette** — press `F1` or `Ctrl+P` / `Cmd+P` to see all available editor functions. Make your changes carefully. Storage-format XML is strict — an unclosed tag or a broken `ac:` namespace reference can prevent the page from rendering. If you're unsure, test on a copy of the page first. ### 4. Preview the diff (Pro edition) and save[​](#4-preview-the-diff-pro-edition-and-save "Direct link to 4. Preview the diff (Pro edition) and save") In the **Pro edition**, a **Diff View** button appears once you've made changes. Click it to open a side-by-side comparison: the original on the left, your changes on the right. This is the safest way to verify exactly what you changed before committing it. Review the diff. Once you're confident, save to apply the changes to the page. The page re-renders with your storage-format edits applied. ## Free vs. Pro: which do you need?[​](#free-vs-pro-which-do-you-need "Direct link to Free vs. Pro: which do you need?") | Feature | Free | Pro | | -------------------------------------------------- | ---- | --- | | Edit raw storage format XML | ✅ | ✅ | | Format Document | ✅ | ✅ | | Find and find-and-replace | ✅ | ✅ | | Command palette | ✅ | ✅ | | **Diff View** (compare changes before saving) | — | ✅ | | **Theme switching** (Light / Dark / High Contrast) | — | ✅ | For occasional fixes, the Free edition is enough. For regular bulk-editing or migration work, the Pro edition's diff view is worth it — it catches mistakes before they hit the page. ## A warning: storage format is powerful but unforgiving[​](#a-warning-storage-format-is-powerful-but-unforgiving "Direct link to A warning: storage format is powerful but unforgiving") Editing storage format is the most direct way to change a Confluence page, which means it's also the easiest way to break one. Three rules: 1. **Test on a copy first** if you're doing anything beyond a simple find-and-replace. Copy the page, edit the copy's storage format, verify it renders, then apply the same change to the real page. 2. **Respect the `ac:` and `ri:` namespaces.** These are Confluence's custom tags. Don't rename or remove namespace declarations; a broken namespace reference can corrupt the page. 3. **Use the diff view (Pro) before saving.** It's much easier to spot a stray deleted closing tag in a diff than in the rendered result. ## FAQ[​](#faq "Direct link to FAQ") ### Can you edit the source code of a Confluence page?[​](#can-you-edit-the-source-code-of-a-confluence-page "Direct link to Can you edit the source code of a Confluence page?") Yes, but "source code" means the page's storage format XML, not HTML. Confluence stores every page as XML in a custom XHTML dialect with namespaced tags for macros and layouts. The Raw Storage Source Editor app lets you open and edit this XML directly from the More Actions menu. ### How do I access the Confluence storage format?[​](#how-do-i-access-the-confluence-storage-format "Direct link to How do I access the Confluence storage format?") Confluence exposes the storage format through its REST API (`/rest/api/content/{id}?expand=body.storage`), but there's no built-in visual editor for it. To edit it interactively, install a Marketplace app like Raw Storage Source Editor for Confluence, which adds a source-editor option to the page's More Actions menu. ### Is editing Confluence storage format safe?[​](#is-editing-confluence-storage-format-safe "Direct link to Is editing Confluence storage format safe?") It's safe if you're careful and test on a copy first. The storage format is strict XML — an unclosed tag or a broken macro namespace reference can prevent the page from rendering. For anything beyond a simple find-and-replace, use the diff view (Pro edition) to verify your changes before saving. ### What is the difference between Source Editor Free and Pro?[​](#what-is-the-difference-between-source-editor-free-and-pro "Direct link to What is the difference between Source Editor Free and Pro?") Both editions let you edit the raw storage format XML with format, find, and find-and-replace. The Pro edition adds a diff view (side-by-side comparison of your changes against the original) and theme switching. The diff view is the key Pro feature for anyone doing regular or complex edits. ### Is Raw Storage Source Editor for Confluence free?[​](#is-raw-storage-source-editor-for-confluence-free "Direct link to Is Raw Storage Source Editor for Confluence free?") The Free edition is free for up to 10 users. The Pro edition (with diff view and themes) is also free for up to 10 users; beyond that, standard Marketplace licensing applies. ## Related guides[​](#related-guides "Direct link to Related guides") Try Raw Storage Source Editor for Confluence (Free) Edit the raw XML storage format of Confluence pages with format, find-and-replace, and diff view — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237066/raw-storage-source-editor-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=raw-storage-source-editor-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [source-editor](/blog/tags/source-editor.md) * [storage-format](/blog/tags/storage-format.md) * [xml](/blog/tags/xml.md) * [how-to](/blog/tags/how-to.md) * [developer-tools](/blog/tags/developer-tools.md) * [power-user](/blog/tags/power-user.md) --- # How to Display & Format JSON in Confluence (Code Blocks + Viewer) April 24, 2026 · 4 min read [NGPilot](https://ngpilot.com) Confluence's native code block macro renders JSON as plain text — no real syntax highlighting, no themes, no copy button. For API documentation, config references, or any page where JSON needs to be readable, that's not good enough. There are two better ways to embed JSON in Confluence, and the best one depends on how you want readers to interact with the data. Two approaches 1. **[Modern Code Blocks](/docs/Modern-Code-Blocks-for-Confluence/user-docs.md)** — renders JSON as syntax-highlighted **code** with the Monaco editor (VS Code engine), 50+ themes, line numbers, copy button, and dark/light mode. **Best for API docs, snippets, and most use cases.** 2. **[JSON Structure Viewer](/docs/json-structure-viewer-for-confluence/usage.md)** — renders JSON as an interactive **collapsible tree** you can zoom and rotate. **Best for exploring large, deeply nested structures.** ## Method 1: Modern Code Blocks (syntax-highlighted JSON)[​](#method-1-modern-code-blocks-syntax-highlighted-json "Direct link to Method 1: Modern Code Blocks (syntax-highlighted JSON)") [Modern Code Blocks for Confluence](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence) uses the Monaco editor — the same engine behind VS Code — to render JSON with proper syntax highlighting, 50+ themes, line numbers, a copy button, and automatic dark/light theme matching. It supports 85+ languages total, with first-class JSON support including nested object and array coloring. ### Step-by-step[​](#step-by-step "Direct link to Step-by-step") 1. Install [Modern Code Blocks](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence) from the Marketplace (free for up to 10 users) 2. Edit a Confluence page, type `/code` and select **Modern Code Blocks for Confluence** 3. Paste your JSON into the editor 4. Set the **Language** to **JSON** 5. Optionally pick a **Theme** (Monokai, Dracula, GitHub Dark, or Auto to match Confluence) 6. Click **Save** The JSON renders inline with full syntax highlighting. Example output: ``` { "user": { "id": 1234, "name": "Jane Developer", "email": "jane@example.com", "roles": ["admin", "editor"], "preferences": { "theme": "dark", "notifications": { "email": true, "slack": false } } } } ``` ### Why Code Blocks wins for most JSON use cases[​](#why-code-blocks-wins-for-most-json-use-cases "Direct link to Why Code Blocks wins for most JSON use cases") * **Monaco-grade highlighting** — keys, strings, numbers, booleans, and null each get distinct colors * **50+ themes** — match your brand or your reader's preference (Auto follows Confluence dark/light mode) * **Line numbers and copy button** — readers can reference line 42 and copy the payload with one click * **Window chrome** — optional macOS/Windows title bar (auto-derived filename, e.g. `config.json`) for screenshot-ready snippets * **Diff view** (Advanced edition) — show a JSON migration or config change as a colored before/after * **One app for all code** — the same macro handles JSON, YAML, SQL, Python, and 80+ other languages For full configuration options — themes, max height, font size, minimap, window chrome — see the [Modern Code Blocks user guide](/docs/Modern-Code-Blocks-for-Confluence/user-docs.md). ## Method 2: JSON Structure Viewer (interactive tree)[​](#method-2-json-structure-viewer-interactive-tree "Direct link to Method 2: JSON Structure Viewer (interactive tree)") When JSON is large or deeply nested and readers need to **explore** the structure rather than read it line by line, [JSON Structure Viewer for Confluence](/docs/json-structure-viewer-for-confluence/usage.md) renders the data as an interactive, collapsible tree. Readers click nodes to expand and collapse, and can zoom and rotate the diagram. ### When to pick the tree view over code highlighting[​](#when-to-pick-the-tree-view-over-code-highlighting "Direct link to When to pick the tree view over code highlighting") | Use case | Best choice | | -------------------------------------------- | -------------------------------------------- | | API request/response examples in docs | **Code Blocks** (copy button, line numbers) | | Short JSON snippets in tutorials | **Code Blocks** (themes, syntax colors) | | A 500-line config file readers must navigate | **JSON Structure Viewer** (collapsible tree) | | Showing the *shape* of a data model | **JSON Structure Viewer** (visual hierarchy) | | Changelog / migration diff | **Code Blocks** diff view | | Mixed code (JSON + YAML + SQL) on one page | **Code Blocks** (one macro, 85+ languages) | To use the tree view, install JSON Structure Viewer, type `/json` on a page, and paste your JSON. See the [JSON Structure Viewer docs](/docs/json-structure-viewer-for-confluence/usage.md) for details. ## Tips for documenting JSON in Confluence[​](#tips-for-documenting-json-in-confluence "Direct link to Tips for documenting JSON in Confluence") * **Pair the two apps** — use Code Blocks for the readable snippet and Structure Viewer for the explorable tree on the same API-docs page * **Anonymize sensitive data** — replace real credentials and emails with placeholders before embedding * **Break up large files** — one macro per major section reads better than one massive blob * **Use Markdown alongside** — [Enhanced Markdown for Confluence](/docs/Enhanced-Markdown-for-Confluence/usage.md) lets you write prose in Markdown and embed JSON macros inline ## Related resources[​](#related-resources "Direct link to Related resources") * [Modern Code Blocks — documentation](/apps/modern-code-blocks-for-confluence.md) | [marketplace](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence) * [JSON Structure Viewer — documentation](/apps/json-structure-viewer-for-confluence.md) | [marketplace](https://marketplace.atlassian.com/apps/1237254/json-structure-viewer-for-confluence) * [Advanced code blocks in Confluence](/blog/advanced-code-blocks-confluence.md) — performance, themes, and diff view * [Best Confluence apps for developers](/blog/best-confluence-apps-developers.md) * [Enhanced Markdown — documentation](/apps/enhanced-markdown-for-confluence.md) — write docs in Markdown with embedded JSON Try JSON Structure Viewer for Confluence Visualize JSON as interactive structure diagrams — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237254/json-structure-viewer-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=json-structure-viewer-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [json](/blog/tags/json.md) * [api-documentation](/blog/tags/api-documentation.md) * [how-to](/blog/tags/how-to.md) * [code-blocks](/blog/tags/code-blocks.md) --- # Excalidraw AI Agent for Confluence: Whiteboards You Can Talk To October 10, 2026 · 7 min read [NGPilot](https://ngpilot.com) Confluence holds your team's diagrams in two worlds, and the two don't talk to each other. Text-defined diagrams — Mermaid and friends — are what AI speaks natively. They're source code, so a chat agent can read them, write them, and revise them. We shipped exactly that last week: [an AI agent for Mermaid in Confluence](/blog/mermaid-ai-agent-confluence.md). Whiteboards are the other world. Freeform shapes, hand-drawn lines, arrows you drag where they need to go — the format that's actually intuitive to put in front of people. Every team has one: the architecture board on the team page, the incident flow everyone references, the onboarding map. And AI couldn't touch any of it. Ask a chat agent for a change to a whiteboard and you'd get a text *description* of a change, and someone still had to open the canvas and do it by hand. That gap is why whiteboards go stale. Editing shapes one drag at a time is slow enough that nobody does it, and AI — the thing that was supposed to make maintenance cheap — had no way in. The AI agent in [Excalidraw Plus Whiteboards & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence) closes the gap: the whiteboard stays what it always was — visual, intuitive, for people — but now you can operate it in plain language, from Confluence chat. **Quick answer:** Open Confluence chat on any page and describe the board — "make an architecture diagram of our checkout system" draws it as an Excalidraw whiteboard right on the page. Follow-ups edit the existing shapes in place ("rename Service A to Auth Service"), the agent can search a whole space for boards, and it converts Mermaid and PlantUML into editable Excalidraw whiteboards — and back. ![The Excalidraw Plus agent open in Confluence chat beside a live whiteboard — starters for converting a Mermaid diagram, creating a flowchart, and finding diagrams in the space](/assets/images/excalidraw-ai-agent-chat-8980a8da88243b4bc5a01d14b753afee.png) *The agent lives in Confluence chat, next to the board it operates on.* ## What the agent can do[​](#what-the-agent-can-do "Direct link to What the agent can do") | Verb | What you say | What happens | | ------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Create** | "Draw the deployment flow on this page" | An Excalidraw whiteboard is added to the page — from a template (flowchart, sequence, architecture, mindmap, kanban, wireframe) or from your own element list | | **Read** | "What's in the architecture board on this page?" | The agent summarizes the board's contents in chat — every board on the page, by name | | **Edit** | "Rename Service A to Auth Service" | The named shapes change; everything else stays exactly where it was | | **Style & lay out** | "Group the AWS boxes and make them green" / "lay this out top to bottom" | Colors, fonts, roughness, grouping, and auto-layout applied to the existing board | | **Search** | "Which pages in this space have diagrams?" | A list of pages with Excalidraw boards in the space | | **Convert** | "Turn this Mermaid code block into a whiteboard" | Mermaid or PlantUML becomes editable Excalidraw shapes — or an Excalidraw board becomes Mermaid text | The **edit** verb is the one that changes how whiteboards live. Until now, a board was a snapshot: right the day someone drew it, wronger every sprint after. When the agent can rename, move, group, and restyle individual shapes on command, "update the board" becomes a sentence instead of an afternoon. ## The bridge runs both ways[​](#the-bridge-runs-both-ways "Direct link to The bridge runs both ways") The convert verb deserves its own note, because it's the literal bridge between the two worlds. Text diagrams are easy for AI to write and awkward for people to read — raw Mermaid syntax is not what you put on a screen in a design review. Whiteboards are the opposite: great for people, opaque to machines. The agent moves work across that line in whichever direction the moment needs: * **Mermaid → Excalidraw.** That flowchart definition sitting in a code block on your page becomes real shapes you can drag, restyle, and extend — and then keep maintaining by chat. * **PlantUML → Excalidraw.** Same deal for the older PlantUML diagrams many teams have lying around. * **Excalidraw → Mermaid.** And when a board needs to live as text — to diff in a PR, to version with the code it documents — the agent converts it back out. Converted boards are real elements on the canvas, not screenshots. Everything the agent can do afterwards — edit, style, layout — applies to them the same as to anything drawn by hand. If you read the [Mermaid agent post](/blog/mermaid-ai-agent-confluence.md): that agent lives on the text side and turns text into rendered diagrams. This one lives on the canvas side and turns text into *editable drawings*. Same chat, two destinations — pick by audience, not by tool. ## A working session[​](#a-working-session "Direct link to A working session") The scenario this was built for: the architecture board on your team page, three sprints out of date. 1. **Open Confluence chat on that page** and start where the board is wrong: *"Rename Service A to Auth Service, and add a caching layer between it and the database."* 2. **Keep going in the same breath:** *"Group the three AWS boxes into one container, and make the whole group green."* 3. **Tidy up:** *"Lay this out top to bottom."* The agent rearranges the board into a clean top-down flow — you're not dragging eleven boxes into alignment yourself. 4. **Then answer the question you actually get asked:** *"Which other pages in this space have architecture diagrams?"* — because there are always four more, equally stale. 5. **Hand off when it matters:** the board is a normal Excalidraw macro. Anyone can click it and adjust by hand; the agent checks the latest saved version before each write, so its edits don't overwrite what a teammate changed an hour ago. A detail that matters on real pages: one page can hold several boards, and the agent keeps track of which is which. *"Update the deployment flow, not the network map"* works. ## Where you take over[​](#where-you-take-over "Direct link to Where you take over") The agent is honest about its limits, and so are we: * **Layout is deliberate, not freeform.** Auto-layout today means top-to-bottom flow or a grid. Ask for a radial tree and the agent will tell you those are the two it does — then you arrange the rest by hand, once, and the board stays put. * **Chat shows no pictures.** The agent works on the board's data, so it replies with what changed and a link to the page — you look at the result where everyone else will. * **Deletion has a seatbelt.** Ask it to remove one of five similar boxes and it checks with you first, rather than guessing which one you meant. * **Anything sacred stays hand-drawn.** For boards that are compliance artifacts or just carefully art-directed, edit on the canvas as always — nothing the agent does is locked in, and nothing you hand-tune gets quietly redrawn. ## Not an agent-only app[​](#not-an-agent-only-app "Direct link to Not an agent-only app") The chat is one of two ways in, and the classic editor is unchanged — type `/excalidraw` and you get the full whiteboard: freehand drawing, **220+ built-in shape libraries**, templates from flowcharts to wireframes, and **built-in Mermaid** rendering in the same app. Manual first, agent when you want speed. Both write the same kind of macro, so a board that started in chat is indistinguishable from one drawn by hand. ## Prompts to try on your first day[​](#prompts-to-try-on-your-first-day "Direct link to Prompts to try on your first day") * *"Draw an architecture diagram of our checkout system — web, API, payments, inventory."* * *"Rename Service A to Auth Service and move it next to the API gateway."* * *"Group the three AWS boxes and make them green."* * *"Which pages in this space have Excalidraw diagrams?"* * *"Convert the Mermaid flowchart in this page's code block into an editable whiteboard."* * *"Lay this board out top to bottom."* ## Related resources[​](#related-resources "Direct link to Related resources") * [Excalidraw Plus Whiteboards for Confluence](/docs/Excalidraw-plus-for-Confluence/usage.md) — full feature guide and documentation * [Mermaid AI Agent for Confluence](/blog/mermaid-ai-agent-confluence.md) — the text-side twin: create, read, update, and convert Mermaid by chat * [draw.io vs Mermaid in Confluence](/blog/mermaid-vs-drawio-confluence.md) — when the source text stays the diagram, and when shapes win * [Best diagram tool for Confluence](/blog/confluence-diagram-tools-comparison.md) — Mermaid vs Excalidraw vs Graphviz **Ready to try it?** [Install Excalidraw Plus Whiteboards & AI Agent for Confluence →](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence) — free for up to 10 users. Try Excalidraw Diagrams plus Whiteboards for Jira Add a freehand drawing canvas to every Jira issue, with 229 shape libraries — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/2139233994/excalidraw-diagrams-plus-whiteboards-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=excalidraw-diagrams-plus-whiteboards-for-jira) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [excalidraw](/blog/tags/excalidraw.md) * [whiteboard](/blog/tags/whiteboard.md) * [diagrams](/blog/tags/diagrams.md) * [ai](/blog/tags/ai.md) * [agent](/blog/tags/agent.md) --- # How to Add Excalidraw Whiteboards to Jira Issues (Setup Guide) April 21, 2026 · One min read [NGPilot](https://ngpilot.com) Excalidraw-powered whiteboards let teams sketch ideas directly inside Jira issues. This quick guide covers creating boards, saving snapshots, and sharing with team members. ## Quick prerequisites[​](#quick-prerequisites "Direct link to Quick prerequisites") * Jira Cloud with [Excalidraw Diagrams plus Whiteboards](/docs/Excalidraw-Diagrams-plus-Whiteboards-for-Jira/usage.md) app installed * Permission to add app content to issues ## Create a whiteboard[​](#create-a-whiteboard "Direct link to Create a whiteboard") * Open issue → click Excalidraw action → create new board * Use shape libraries and templates for common diagrams ## Collaboration tips[​](#collaboration-tips "Direct link to Collaboration tips") * Locking & versioning: snapshot boards before edits * Exporting: save as PNG/SVG for sharing ## Related apps & resources[​](#related-apps--resources "Direct link to Related apps & resources") * [Excalidraw Diagrams plus Whiteboards for Jira](/apps/excalidraw-diagrams-plus-whiteboards-for-jira.md) * [Excalidraw Plus for Confluence](/apps/excalidraw-plus-for-confluence.md) — freeform drawing in Confluence pages * [Excalidraw & Mermaid Visual Editor](/apps/excalidraw-mermaid-diagrams-for-confluence.md) — combine Excalidraw and Mermaid * [Excalidraw best practices FAQ](/blog/faq-excalidraw-best-practices.md) — tips and troubleshooting * [Create Mermaid diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md) — another diagram tool option Try Excalidraw Diagrams plus Whiteboards for Jira Add a freehand drawing canvas to every Jira issue, with 229 shape libraries — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/2139233994/excalidraw-diagrams-plus-whiteboards-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=excalidraw-diagrams-plus-whiteboards-for-jira) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [excalidraw](/blog/tags/excalidraw.md) * [whiteboard](/blog/tags/whiteboard.md) * [how-to](/blog/tags/how-to.md) --- # How to Export Jira Audit Logs for Compliance and Security Reviews July 29, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer Jira audit logs track who changed what, when, and where. Export logs to CSV or via REST API for compliance audits, security investigations, and change management documentation. What you'll learn 1. How to access and navigate the Jira audit log 2. How to filter audit entries by user, date, and action type 3. How to export audit data to CSV or via REST API 4. How to set up automated logging and retention policies 5. How to analyze audit data for compliance and security Audit logs are the paper trail of your Jira instance. They record who did what, when, and where — essential information for compliance audits, security investigations, and change management. Without proper audit logging, you cannot prove who deleted that issue, when permissions changed, or whether someone accessed restricted data. This guide covers how to access, export, and analyze Jira audit logs. ## Why Audit Logs Matter[​](#why-audit-logs-matter "Direct link to Why Audit Logs Matter") Audit logs serve multiple purposes: **Compliance.** Many regulations (SOC 2, ISO 27001, GDPR) require documented change trails. Jira audit logs provide this evidence. **Security investigations.** When something goes wrong — unauthorized access, data deletion, permission changes — the audit log tells you what happened and who was involved. **Change management.** Track configuration changes, workflow modifications, and permission updates to understand how your Jira instance evolved. **Dispute resolution.** When there is a disagreement about who changed what, the audit log is the source of truth. ## How to Access the Jira Audit Log[​](#how-to-access-the-jira-audit-log "Direct link to How to Access the Jira Audit Log") ### Jira Cloud[​](#jira-cloud "Direct link to Jira Cloud") 1. Go to **Jira Settings > System > Audit Log** 2. Use the date range picker to select a time period 3. Filter by: * **Category** — Issues, Projects, Permissions, etc. * **Action** — Created, Updated, Deleted, etc. * **User** — specific user who performed the action 4. Click **Export** to download a CSV ### Jira Server/Data Center[​](#jira-serverdata-center "Direct link to Jira Server/Data Center") 1. Go to **Jira Settings > System > Audit Log** 2. Click **Advanced Audit Log** for detailed entries 3. Use the search bar to filter by keywords 4. Click **Export** to download **What the audit log tracks:** | Category | What It Records | | ----------- | ----------------------------------------------------- | | Issues | Creation, updates, deletion, transitions, comments | | Projects | Creation, configuration changes, deletion | | Permissions | Scheme changes, role assignments, group modifications | | Workflows | Schema changes, transition additions | | Users | Account creation, deactivation, group membership | | System | Configuration changes, plugin installations | ## How to Export Jira Audit Logs: Step-by-Step[​](#how-to-export-jira-audit-logs-step-by-step "Direct link to How to Export Jira Audit Logs: Step-by-Step") ### 1. Access the Audit Log[​](#1-access-the-audit-log "Direct link to 1. Access the Audit Log") Navigate to the audit log in your Jira version: **Jira Cloud:** ``` Jira Settings (gear icon) > System > Audit Log ``` **Jira Server:** ``` Jira Administration > System > Advanced Audit Log ``` ### 2. Filter Audit Log Entries[​](#2-filter-audit-log-entries "Direct link to 2. Filter Audit Log Entries") Use the built-in filters to narrow results: **Filter by date:** * Select a start and end date * Use presets: Last 24 hours, Last 7 days, Last 30 days **Filter by category:** * Issues — all issue-related changes * Projects — project creation and modification * Permissions — access and role changes * Users — account changes **Filter by action:** * Created — new items * Updated — modifications * Deleted — removals * Transitioned — workflow changes **Filter by user:** * Enter a username to see all actions by that person * Useful for insider threat investigations ### 3. Export Audit Log Data[​](#3-export-audit-log-data "Direct link to 3. Export Audit Log Data") **CSV export (simple):** 1. Apply your filters 2. Click **Export** (top right) 3. Choose CSV format 4. Download and open in Excel or Google Sheets **REST API export (programmatic):** ``` # Get audit records from the last 30 days curl -u admin:password \ "https://your-domain.atlassian.net/rest/api/2/auditing/record" \ -H "Content-Type: application/json" \ -d '{ "from": "2026-06-29T00:00:00.000Z", "to": "2026-07-29T23:59:59.999Z", "filters": ["category:issues"] }' ``` **For large exports:** * Use the API with pagination * Export in batches (e.g., 7-day chunks) * Store in a database or SIEM tool ### 4. Set Up Automated Audit Logging[​](#4-set-up-automated-audit-logging "Direct link to 4. Set Up Automated Audit Logging") **Retention policy:** * Jira Cloud: 60 days default (upgrade for longer retention) * Jira Server: Configurable (default 90 days) * Best practice: Export weekly and archive for 1 year+ **Automated exports:** 1. Create a script that calls the audit log API 2. Schedule it with cron (Linux) or Task Scheduler (Windows) 3. Store exports in a secure, immutable location 4. Set up alerts for sensitive operations (permission changes, deletions) **Sensitive operations to monitor:** * Permission scheme changes * User role assignments * Issue deletions * Workflow modifications * System configuration changes ### 5. Analyze Audit Log Data[​](#5-analyze-audit-log-data "Direct link to 5. Analyze Audit Log Data") **In Excel/Google Sheets:** 1. Import the CSV 2. Sort by date to see chronological changes 3. Filter by user to see individual activity 4. Filter by category to focus on specific changes 5. Create pivot tables for summary views **In a SIEM tool (Splunk, ELK, etc.):** 1. Ingest audit log CSV or API data 2. Create dashboards for: * Daily change volume * Top users by activity * Permission changes over time * Anomaly detection (unusual access patterns) 3. Set up alerts for suspicious activity **Key metrics to track:** * Total changes per day/week/month * Changes by user (identify outliers) * Permission changes (security-sensitive) * Issue deletions (data integrity) * Failed login attempts (security) ## FAQ[​](#faq "Direct link to FAQ") ### What does the Jira audit log track?[​](#what-does-the-jira-audit-log-track "Direct link to What does the Jira audit log track?") The audit log tracks user logins, issue changes (creation, updates, deletions), project changes (creation, configuration, deletion), permission changes, workflow transitions, and administrative actions. The level of detail depends on your Jira version and licensing. ### How long does Jira keep audit log data?[​](#how-long-does-jira-keep-audit-log-data "Direct link to How long does Jira keep audit log data?") Jira Cloud keeps audit logs for 60 days by default. Jira Server/Data Center retains logs based on your configuration (default 90 days). For longer retention, export logs regularly and store them in an external system. ### Can I export Jira audit logs via API?[​](#can-i-export-jira-audit-logs-via-api "Direct link to Can I export Jira audit logs via API?") Yes. Jira provides REST API endpoints for audit log data. Use the /rest/api/2/auditing/record endpoint to query audit records programmatically. This is useful for large exports or integration with SIEM tools. ### How do I track who changed a specific Jira issue?[​](#how-do-i-track-who-changed-a-specific-jira-issue "Direct link to How do I track who changed a specific Jira issue?") Go to the issue > Click History tab to see all changes. For bulk tracking, use the audit log with filter category 'Issues' and the issue key as the search term. The audit log shows who changed what and when. ### Is the Jira audit log sufficient for SOC 2 compliance?[​](#is-the-jira-audit-log-sufficient-for-soc-2-compliance "Direct link to Is the Jira audit log sufficient for SOC 2 compliance?") The audit log provides a baseline, but SOC 2 requires more: access reviews, change management documentation, and incident response procedures. Use the audit log as one input into your compliance program, not the entire solution. ## Related guides[​](#related-guides "Direct link to Related guides") * [Jira Permissions Explained: Project Security Setup](/blog/jira-permissions-explained-project-security-setup.md) * [How to Export Jira Issues to Excel for Stakeholder Reporting](/blog/export-jira-issues-to-excel-csv-reporting.md) * [Jira JQL Cheat Sheet: 20 Queries Every Team Needs](/blog/jira-jql-cheat-sheet-common-queries.md) * [How to Set Up Jira Dashboards for Sprint Tracking](/blog/jira-dashboard-sprint-tracking-setup.md) Try Simple Bulk Issues Excel CSV Export for Jira Export filtered Jira issues to Excel (XLS/XLSX) or CSV with custom fields and JQL — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/3818473739/simple-bulk-issues-excel-csv-export-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=simple-bulk-issues-excel-csv-export-for-jira) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [audit-logs](/blog/tags/audit-logs.md) * [compliance](/blog/tags/compliance.md) * [security](/blog/tags/security.md) * [how-to](/blog/tags/how-to.md) * [administration](/blog/tags/administration.md) --- # Export Jira Issues to Excel or CSV: Complete Guide (2026) April 21, 2026 · 4 min read [NGPilot](https://ngpilot.com) Who should read this * Jira administrators needing to export issues for reporting * Project managers importing Jira data to Excel or Google Sheets * Anyone needing to bulk export issues for analysis What you'll learn 1. How to use Simple Bulk Issues to export Jira issues 2. JQL query tips and field selection 3. Best practices for handling large exports Exporting Jira issues to Excel or CSV is useful for reporting, audits, and sharing issues with stakeholders. This guide walks through exporting filtered results using the Simple Bulk Issues Excel CSV Export app with practical JQL examples and field-selection tips. ## Why use Simple Bulk Issues[​](#why-use-simple-bulk-issues "Direct link to Why use Simple Bulk Issues") * Exports up to 5,000 issues with selectable fields * Supports CSV, XLS and XLSX formats * Preserves dates, users, multi-value fields and attachments metadata ## Quick prerequisites[​](#quick-prerequisites "Direct link to Quick prerequisites") 1. Jira Cloud instance with the [Simple Bulk Issues Excel CSV Export](/docs/Simple-Bulk-Issues-Excel-CSV-Export-for-Jira/user-docs.md) app installed and licensed 2. Permission to view issues you want to export 3. A saved filter or JQL query that returns the desired issues ## Step 1 — Prepare your filter (JQL)[​](#step-1--prepare-your-filter-jql "Direct link to Step 1 — Prepare your filter (JQL)") Example: export all bugs in the last 30 days for PROJECT: ``` project = PROJECT AND issuetype = Bug AND created >= -30d ``` Tips: * Test your JQL in Jira issue navigator first. * Use saved filters for repeatable exports. ## Step 2 — Open the export dialog[​](#step-2--open-the-export-dialog "Direct link to Step 2 — Open the export dialog") Navigate to Issues → Search for Issues, run your filter, then click the **Simple Bulk Issues Excel CSV Export** action in the toolbar. ## Step 3 — Select fields to export[​](#step-3--select-fields-to-export "Direct link to Step 3 — Select fields to export") Choose only fields you need to keep file size manageable. Recommended fields for reporting: * Key, Summary, Status, Assignee, Reporter * Created, Updated, Resolution Date * Priority, Issue Type, Labels, Components ### Quick selection tips[​](#quick-selection-tips "Direct link to Quick selection tips") * Use “Select Default” for a compact report * Use “Select All” for a complete data dump (beware of large files) ## Step 4 — Choose format and export[​](#step-4--choose-format-and-export "Direct link to Step 4 — Choose format and export") Select CSV, XLS or XLSX and click export. The file downloads automatically with a timestamped filename. ## Handling large exports[​](#handling-large-exports "Direct link to Handling large exports") ### How do I export more than 1,000 Jira issues to Excel?[​](#how-do-i-export-more-than-1000-jira-issues-to-excel "Direct link to How do I export more than 1,000 Jira issues to Excel?") Jira's native export caps a single export at 1,000 issues. Simple Bulk Issues Export raises that ceiling to 5,000 issues per export, and shows a notice when a filter matches more than the cap so partial exports are never mistaken for complete ones. The workaround is to split your query into batches and concatenate the files afterward: * **By date range** — `project = ENG AND created >= "2026-01-01" AND created <= "2026-03-31"`, then re-run for the next quarter. * **By project** — `project in (ENG, PLATFORM, INFRA)` becomes three exports, one per project. * **By issue type or status** — `project = ENG AND issuetype = Bug` and `project = ENG AND issuetype = Story` as separate runs. Keep the same field selection across batches so columns line up when you concatenate. For a focused look at every way around Jira's export limits, see [Jira Export Limit: How to Export More Than 1,000 Issues](/blog/jira-export-limit.md), and for scripting recurring multi-batch pulls via the Jira REST API, see the [Exporting Jira issues FAQ](/blog/faq-exporting-jira-issues.md). ### Format choice for large exports[​](#format-choice-for-large-exports "Direct link to Format choice for large exports") * Use **XLSX** if you want rich formatting, multi-sheet grouping, or downstream pivot tables. * Use **CSV** if you're loading the data into a database, BI tool, or script pipeline. CSVs are smaller and faster to concatenate in code. ## Examples & automation[​](#examples--automation "Direct link to Examples & automation") * Automate exports by using saved filters combined with scheduled tasks that pull exported files from your team. ## Related apps & resources[​](#related-apps--resources "Direct link to Related apps & resources") * [Simple Bulk Issues Excel CSV Export](/apps/simple-bulk-issues-excel-csv-export-for-jira.md) * [Simple Bulk Attachment Downloader](/apps/simple-bulk-attachment-downloader-for-jira.md) — download attachments in bulk * [Attachment Reviewer for Jira](/apps/attachment-reviewer-for-jira.md) — validate file uploads * [Exporting Jira issues FAQ](/blog/faq-exporting-jira-issues.md) — common export questions * [Bulk operations FAQ](/blog/faq-bulk-operations-jira.md) — tips for bulk workflows * [Bulk download Jira attachments](/blog/bulk-download-jira-attachments.md) — companion guide for attachment downloads *** ## More Related Guides[​](#more-related-guides "Direct link to More Related Guides") * [Bulk operations FAQ](/blog/faq-bulk-operations-jira.md) — Tips for bulk Jira workflows * [Bulk download Jira attachments](/blog/bulk-download-jira-attachments.md) — Download multiple attachments * [Simple Bulk Issues Excel CSV Export](/apps/simple-bulk-issues-excel-csv-export-for-jira.md) — Complete feature guide *** *Suggested featured image: screenshot of export dialog with field selection.* Try Simple Bulk Issues Excel CSV Export for Jira Export filtered Jira issues to Excel (XLS/XLSX) or CSV with custom fields and JQL — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/3818473739/simple-bulk-issues-excel-csv-export-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=simple-bulk-issues-excel-csv-export-for-jira) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [export](/blog/tags/export.md) * [excel](/blog/tags/excel.md) * [csv](/blog/tags/csv.md) * [how-to](/blog/tags/how-to.md) --- # How to Export Jira Issues to Excel for Stakeholder Reporting July 29, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer Export Jira issues to Excel or CSV for stakeholder reporting, custom analysis, and cross-project visibility. Use JQL queries to filter exactly the data you need. What you'll learn 1. How to use Jira's built-in export to CSV and Excel 2. How to customize which fields are included in exports 3. How to write JQL queries for targeted, filtered exports 4. How to schedule automated exports for regular reporting 5. How to build Excel reports from Jira export data Jira's built-in reports are useful, but stakeholders often want data in Excel. Whether it is a weekly status report, a velocity trend analysis, or a custom dashboard, Excel gives you full control over how Jira data is presented. This guide covers how to export Jira issues to Excel and CSV, from simple one-click exports to scheduled automated reports. ## Why Export Jira Issues to Excel[​](#why-export-jira-issues-to-excel "Direct link to Why Export Jira Issues to Excel") Jira's built-in gadgets cover common reports, but they have limitations: **Custom analysis.** Excel lets you create pivot tables, charts, and formulas that Jira gadgets cannot replicate. **Stakeholder access.** Not everyone has a Jira license. Excel files can be shared with anyone. **Historical tracking.** Export snapshots over time to track trends outside Jira's retention window. **Cross-project reporting.** Combine data from multiple Jira projects in a single spreadsheet. **Compliance.** Some audits require documented reports in standard formats. ## How to Export Jira Issues to Excel: Step-by-Step[​](#how-to-export-jira-issues-to-excel-step-by-step "Direct link to How to Export Jira Issues to Excel: Step-by-Step") ### 1. Use the Built-in Export Button[​](#1-use-the-built-in-export-button "Direct link to 1. Use the Built-in Export Button") The fastest way to export: 1. Go to **Issues > Search for issues** 2. Run a JQL query or use the basic search 3. Click **Export** (top right of results) 4. Choose your format: * **Export CSV (Current Fields)** — exports visible columns * **Export CSV (All Fields)** — exports every available field * **Export Excel (All Fields)** — native Excel format (XLSX) 5. Save the file **Recommended:** Use CSV format for maximum compatibility. Excel opens CSV files directly, and they are easier to work with for large datasets. ### 2. Customize Exported Fields[​](#2-customize-exported-fields "Direct link to 2. Customize Exported Fields") To control which fields appear in the export: 1. In the issue navigator, click **Fields** (above the results) 2. Add or remove columns to show only what you need 3. Click **Export > Export CSV (Current Fields)** 4. The CSV contains only the fields you selected **Useful fields for stakeholder reports:** | Field | Why It Matters | | ------------ | -------------------------- | | Summary | Issue title | | Status | Current workflow state | | Assignee | Who is working on it | | Priority | Importance ranking | | Story Points | Effort estimate | | Sprint | Which sprint it belongs to | | Fix Version | Target release | | Due Date | Deadline | | Labels | Custom categorization | ### 3. Use JQL for Targeted Exports[​](#3-use-jql-for-targeted-exports "Direct link to 3. Use JQL for Targeted Exports") JQL lets you filter exactly the issues you need: **Export all open issues in a project:** ``` project = MYPROJECT AND status != Done ``` **Export issues completed in the last sprint:** ``` project = MYPROJECT AND status = Done AND sprint in closedSprints() ``` **Export issues by a specific team:** ``` project = MYPROJECT AND assignee in membersOf("engineering-team") ``` **Export high-priority bugs:** ``` project = MYPROJECT AND issuetype = Bug AND priority = High ``` Run the query, then export the results. ### 4. Schedule Automated Exports[​](#4-schedule-automated-exports "Direct link to 4. Schedule Automated Exports") For regular reporting, automate the export: **Option A: Jira Subscriptions** 1. Save your JQL query as a filter 2. Go to **Filters > Manage Filters** 3. Select your filter > **Details > New Subscription** 4. Set frequency (daily, weekly) 5. Add email recipients 6. Jira emails a CSV of matching issues on schedule **Option B: REST API Script** ``` #!/bin/bash # Export Jira issues to CSV via API curl -u admin:password \ "https://your-domain.atlassian.net/rest/api/2/search?jql=project=MYPROJECT+AND+status!=Done&fields=summary,status,assignee,priority" \ -o issues.json # Convert JSON to CSV with jq jq -r '.issues[] | [.key, .fields.summary, .fields.status.name, .fields.assignee.displayName, .fields.priority.name] | @csv' \ issues.json > issues.csv ``` **Option C: Third-Party Tools** * **Exalate** — sync Jira data to Excel/Google Sheets * **ScriptRunner** — scheduled exports via Groovy scripts * **Jira REST API + Python** — full custom export pipeline ### 5. Build Excel Reports from Exports[​](#5-build-excel-reports-from-exports "Direct link to 5. Build Excel Reports from Exports") Once you have the CSV, transform it into a report: **Pivot table for sprint velocity:** 1. Import CSV into Excel 2. Insert > PivotTable 3. Rows: Sprint, Values: Count of Issue Key 4. Add a chart for visual trend **Conditional formatting for status:** 1. Select the Status column 2. Home > Conditional Formatting > Color Scale 3. Green for Done, Yellow for In Progress, Red for To Do **Chart for priority distribution:** 1. Insert > Chart > Pie Chart 2. Data: Count of issues by Priority 3. Color-code: Red (High), Yellow (Medium), Green (Low) **Dashboard layout:** | Section | Content | | --------- | -------------------------------------------- | | Top left | Sprint velocity bar chart | | Top right | Status distribution pie chart | | Middle | Issue list table with conditional formatting | | Bottom | Trend line (created vs resolved over time) | ## FAQ[​](#faq "Direct link to FAQ") ### What is the best way to export Jira issues to Excel?[​](#what-is-the-best-way-to-export-jira-issues-to-excel "Direct link to What is the best way to export Jira issues to Excel?") Use the Export button in the issue navigator. Select Export CSV (Current Fields) for a quick export, or Export Fields Customized to choose which fields to include. The CSV opens directly in Excel. ### Can I export Jira issues automatically on a schedule?[​](#can-i-export-jira-issues-automatically-on-a-schedule "Direct link to Can I export Jira issues automatically on a schedule?") Yes. Use Jira subscriptions to email a filter's results on a schedule. Alternatively, use the Jira REST API with a script to pull issue data and save it to Excel or CSV automatically. ### How do I export all fields for Jira issues?[​](#how-do-i-export-all-fields-for-jira-issues "Direct link to How do I export all fields for Jira issues?") In the issue navigator, click Export > Export CSV (All Fields). This includes every field available on the issues. For very large exports, use the REST API to avoid timeout issues. ### Can I export Jira issues to Google Sheets?[​](#can-i-export-jira-issues-to-google-sheets "Direct link to Can I export Jira issues to Google Sheets?") Export to CSV from Jira, then import the CSV into Google Sheets. For live data, use the Jira REST API with a Google Sheets script to pull issues directly into a spreadsheet. ### How do I export Jira issues with custom fields?[​](#how-do-i-export-jira-issues-with-custom-fields "Direct link to How do I export Jira issues with custom fields?") Custom fields appear in the export if they are visible on the issue screen. Use Export Fields Customized to select specific custom fields, or Export CSV (All Fields) to include everything. ## Related guides[​](#related-guides "Direct link to Related guides") * [Jira JQL Cheat Sheet: 20 Queries Every Team Needs](/blog/jira-jql-cheat-sheet-common-queries.md) * [How to Set Up Jira Dashboards for Sprint Tracking](/blog/jira-dashboard-sprint-tracking-setup.md) * [How to Export Jira Audit Logs for Compliance](/blog/export-jira-audit-logs-compliance.md) * [Creating Jira Issues from Templates with Bulk Create](/blog/create-jira-issues-from-templates.md) Try Simple Bulk Issues Excel CSV Export for Jira Export filtered Jira issues to Excel (XLS/XLSX) or CSV with custom fields and JQL — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/3818473739/simple-bulk-issues-excel-csv-export-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=simple-bulk-issues-excel-csv-export-for-jira) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [export](/blog/tags/export.md) * [excel](/blog/tags/excel.md) * [csv](/blog/tags/csv.md) * [reporting](/blog/tags/reporting.md) * [how-to](/blog/tags/how-to.md) --- # Jira Bulk Operations FAQ: Exports, Edits & Downloads April 21, 2026 · 10 min read [NGPilot](https://ngpilot.com) Managing a Jira instance at scale means sooner or later you will need to act on dozens, hundreds, or even thousands of issues at once. Whether you are migrating projects, cleaning up stale tickets, bulk-downloading attachments for an audit, or exporting an entire backlog for offline analysis, doing it one issue at a time is not realistic. Bulk operations let teams apply the same change across many issues simultaneously, saving hours of repetitive manual work and reducing the risk of inconsistency that comes with editing tickets individually. However, bulk operations carry real risk. A single misconfigured bulk edit can change the status, assignee, or custom field value of hundreds of issues in seconds, and Jira does not offer a one-click undo. That is why understanding the right tools, permissions, safeguards, and workflows is critical before you run any bulk job. This FAQ covers the most common questions teams ask when planning and executing bulk operations in Jira, from safety and rollback strategies to performance tuning and permission requirements. ## How do I safely perform bulk edits in Jira?[​](#how-do-i-safely-perform-bulk-edits-in-jira "Direct link to How do I safely perform bulk edits in Jira?") Safety starts before you touch production data. If your organization maintains a staging or sandbox Jira environment, always rehearse your bulk edit there first. This lets you confirm that your JQL filter targets exactly the right issues and that field changes behave as expected without any surprises. If a staging instance is not available, consider creating a small test project with sample issues and running the operation there instead. When you move to production, limit each batch to between 100 and 500 issues. Smaller batches are easier to review in Jira's built-in preview step, which shows you exactly what will change before you confirm. Large batches that span thousands of issues make the preview harder to validate and increase the blast radius if something goes wrong. Notify relevant stakeholders -- project managers, team leads, and anyone who relies on the affected issues -- before you execute the change. A short heads-up in a Slack channel or email thread gives people a chance to flag concerns and ensures everyone knows the data will shift. Finally, lean on Jira's native bulk change wizard. After you select your issues and choose the fields to modify, the wizard presents a confirmation screen summarizing every change. Review it line by line. This single step catches more mistakes than any other safeguard. ## Can I revert bulk changes in Jira?[​](#can-i-revert-bulk-changes-in-jira "Direct link to Can I revert bulk changes in Jira?") Jira does not provide a built-in undo button for bulk operations, so recovery depends on preparation. The first line of defense is a pre-edit export. Before running any bulk change, export the affected issues to CSV or Excel using Simple Bulk Issues Export. This snapshot captures the current state of every field, and you can use it later to manually or programmatically restore values if needed. The second tool is Jira's audit log. Available to site and organization admins, the audit log records who changed what and when. For bulk edits, it lists every issue that was modified along with the old and new field values. You can search the log by user, date range, and activity type, which makes it possible to reconstruct the state before the change and reverse it by hand or through a second bulk operation. For teams that run bulk edits regularly, a more robust approach is to prepare Jira automation rules in advance. Create a rule that triggers on the specific field change your bulk edit will make and stores the previous value in a custom "backup" field. If the edit needs to be rolled back, you can run a second bulk operation or automation that copies the backup field value back into the original field. This strategy requires upfront effort but pays off quickly in environments where bulk corrections are common. ## How do I prevent bulk operations from affecting Jira performance?[​](#how-do-i-prevent-bulk-operations-from-affecting-jira-performance "Direct link to How do I prevent bulk operations from affecting Jira performance?") Bulk jobs are resource-intensive. They generate heavy database writes, update Lucene indexes, and can trigger notification emails for every affected issue. To minimize the impact on other users, schedule large operations during off-peak hours -- early mornings, late evenings, or weekends depending on your team's time zones. If you use Jira Cloud, be aware of API rate limits that throttle requests when the platform is under load. Splitting a large job into smaller sequential batches helps as well. Instead of editing 5,000 issues in one shot, process them in chunks of 500 with a short pause between batches. This gives Jira's indexing threads time to catch up and prevents long-running database locks that can slow down the entire instance. Where possible, use tools that keep the UI responsive. Simple Bulk Issues Export processes the export and downloads the file directly to your browser with a timestamped filename. The app supports up to 1,000 issues per export, so split larger result sets into batches. Simple Bulk Attachment Downloader uses parallel downloading with real-time progress tracking so you can see download status as files are fetched. ## Should I use Jira's UI or the API for bulk exports?[​](#should-i-use-jiras-ui-or-the-api-for-bulk-exports "Direct link to Should I use Jira's UI or the API for bulk exports?") The answer depends on frequency, volume, and whether you need human judgment in the loop. For ad-hoc, one-time exports of up to 1,000 issues per run, the UI is the fastest path. Install Simple Bulk Issues Export, navigate to your Jira filter or project, select the issues, and choose your export format. The app handles column selection, date formatting, and field mapping without writing a single line of code. This approach is ideal for product managers preparing a report, support teams pulling a ticket snapshot, or finance teams reconciling time-tracking data. For automated, recurring, or very large exports, the Jira REST API is the better choice. The API supports pagination -- you request results in pages of 50 to 100 issues and iterate until the full set is retrieved. This lets you script exports that run on a schedule, integrate with data pipelines, or feed business intelligence tools. Pagination also means you can handle exports that far exceed what the UI can download in a single file. Combine the API with retry logic and exponential backoff to handle transient network errors and rate limits gracefully. In practice, many teams use both: the UI for quick exploratory exports and the API for production-grade data pipelines. ## What permissions do I need for bulk operations in Jira?[​](#what-permissions-do-i-need-for-bulk-operations-in-jira "Direct link to What permissions do I need for bulk operations in Jira?") Bulk operations touch multiple permission layers in Jira, and missing any one of them will cause the operation to fail silently or with an error. **Bulk Change** is the most fundamental permission. It is granted at the global level and determines whether a user can use Jira's bulk change wizard at all. Without it, the "Bulk Change" option does not appear in the issue action menu. Administrators enable it through the global permissions settings. **Browse Project** controls read access to issues. You need this permission for every project whose issues you want to export, edit, or include in a bulk operation. If you are working across multiple projects, confirm that your role grants Browse Project in each one. **View Attachments** is required for any bulk operation that involves downloading or exporting file attachments. This is a separate permission from Browse Project, so even users who can see issues may not be able to access their attachments unless this permission is explicitly granted. **Project Admin** or equivalent rights may be necessary for certain advanced operations such as bulk-moving issues between projects, bulk-deleting issues, or modifying project-specific configuration fields. Check with your Jira administrator if you encounter permission errors on these actions. ## What are best practices for Jira bulk operations?[​](#what-are-best-practices-for-jira-bulk-operations "Direct link to What are best practices for Jira bulk operations?") Treat bulk operations with the same discipline you would apply to a production database migration. Start by documenting your procedures in a shared wiki or runbook. Include the JQL filter, the fields being changed, the expected batch size, and the rollback plan. This documentation turns one-person knowledge into team knowledge and provides an audit trail for compliance-heavy organizations. Use saved JQL filters to define your issue sets. Saved filters are version-controlled in the sense that they are stored in Jira and can be referenced by name, which prevents ad-hoc query typos from pulling in the wrong issues. Before running a bulk edit, load the saved filter in the issue navigator and visually confirm the results look correct. Split large jobs into chunks of no more than 500 issues. This keeps Jira responsive, makes the preview step manageable, and limits the scope of any single mistake. If you are running multiple batches, leave a few minutes between them so indexers and notification queues can drain. Always preview before you apply. Jira's bulk change wizard shows a detailed confirmation screen. Read it. Check that the issue count matches your expectation, that the correct fields are listed, and that the new values are accurate. This takes an extra thirty seconds but can save hours of cleanup. Finally, use purpose-built tools rather than workarounds. Simple Bulk Issues Export and Simple Bulk Attachment Downloader are designed specifically for bulk scenarios and handle edge cases like custom fields, large attachments, and character encoding that generic approaches often miss. ## Jira bulk operation types[​](#jira-bulk-operation-types "Direct link to Jira bulk operation types") | Operation | Tool | Best For | | ---------------------------------- | --------------------------------- | ------------------------------------------------------------ | | Export issues to Excel/CSV | Simple Bulk Issues Export | Ad-hoc reporting, audit snapshots, data migration | | Download attachments in bulk | Simple Bulk Attachment Downloader | Compliance archiving, offline reviews, project migration | | Bulk edit fields, status, assignee | Jira native Bulk Change wizard | Mass updates, sprint clean-up, workflow transitions | | Automated recurring exports | Jira REST API + scripts | Data pipelines, BI integration, scheduled backups | | Enforce file upload policies | Attachment Reviewer for Jira | Blocking risky file types, enforcing size limits per project | ## Pre-flight checklist for bulk operations[​](#pre-flight-checklist-for-bulk-operations "Direct link to Pre-flight checklist for bulk operations") Before running any bulk operation in Jira, walk through these five steps to reduce risk and ensure a smooth execution. 1. **Verify your JQL filter.** Open the filter in Jira's issue navigator and confirm the returned issues match your intent. Check the total count and spot-check individual issues for correctness. A misconfigured filter is the single most common cause of unintended bulk changes. 2. **Export a backup.** Use Simple Bulk Issues Export to download the current state of all affected issues as a CSV or Excel file. Store this file in a shared location so the team can reference it if a rollback is needed. 3. **Confirm permissions.** Ensure your user account holds Bulk Change, Browse Project, and View Attachments permissions for every project involved. Missing permissions cause partial failures that are difficult to untangle after the fact. 4. **Notify stakeholders.** Send a brief message to affected teams letting them know what is changing, when, and how to report issues. This is especially important for operations that modify status, assignee, or priority fields that appear on team boards and dashboards. 5. **Preview and execute.** Run through Jira's bulk change preview step or the app's confirmation screen. Verify the issue count, field changes, and target values one final time. If everything looks correct, confirm the operation and monitor the results for the next few minutes. ## Related resources[​](#related-resources "Direct link to Related resources") * [Bulk download Jira attachments](/blog/bulk-download-jira-attachments.md) — step-by-step attachment download guide * [Export Jira issues to Excel/CSV](/blog/export-jira-issues-to-excel.md) — complete export walkthrough * [Simple Bulk Attachment Downloader](/apps/simple-bulk-attachment-downloader-for-jira.md) * [Simple Bulk Issues Excel CSV Export](/apps/simple-bulk-issues-excel-csv-export-for-jira.md) * [Attachment Reviewer for Jira](/apps/attachment-reviewer-for-jira.md) Try Modern FAQ for Confluence Accordion-style FAQ sections with drag-and-drop reordering and two themes — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236739/modern-faq-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-faq-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [jira](/blog/tags/jira.md) * [bulk](/blog/tags/bulk.md) * [export](/blog/tags/export.md) * [attachments](/blog/tags/attachments.md) --- # Modern Code Blocks Performance & Large Snippet FAQ April 21, 2026 · 10 min read [NGPilot](https://ngpilot.com) Code blocks are one of the most frequently used macros in Confluence for engineering teams. Whether you are documenting API endpoints, sharing configuration files, or writing runbooks, the ability to embed readable, well-formatted code directly inside a Confluence page is essential. Yet the native code block macro that ships with Confluence has remained essentially unchanged for years: limited language support, no interactive editing, and a rendering approach that can bog down pages when multiple large snippets are present. Teams that write technical documentation need proper syntax highlighting, fast page loads, and features like copy-to-clipboard and in-block search. This FAQ addresses the most common questions about code block performance in Confluence and explains how **Modern Code Blocks for Confluence** solves these problems by integrating the Monaco Editor — the same editor that powers VS Code — into your wiki pages. *** ## Do large code blocks slow down Confluence pages?[​](#do-large-code-blocks-slow-down-confluence-pages "Direct link to Do large code blocks slow down Confluence pages?") Yes, they can. A single code block containing several hundred lines of code adds hundreds of DOM nodes to the page. When multiple large blocks appear on the same page, the browser must parse, style, and lay out all of those elements during the initial render. This increases time-to-interactive and can make scrolling feel sluggish, especially on older hardware or complex pages with embedded images and tables. Modern Code Blocks for Confluence addresses this in two ways. First, it uses **Monaco Editor with lazy initialization**: the heavy editor component is not loaded until a user actually interacts with the code block. Until then, a lightweight static rendering handles the display. Second, the macro supports a configurable **Max Height** setting (100 to 5000 pixels) that enables vertical scrolling for long code. Code blocks automatically expand to fit their content up to the max height, keeping pages responsive. If you regularly paste very large files into Confluence, consider linking to the source file in your repository instead and using the code block for the most relevant excerpt. This keeps the page responsive while still providing full context through the external link. *** ## What is the performance impact of Monaco Editor in Confluence?[​](#what-is-the-performance-impact-of-monaco-editor-in-confluence "Direct link to What is the performance impact of Monaco Editor in Confluence?") Monaco Editor is a full-featured code editor, and that richness comes with a larger JavaScript bundle compared to lightweight syntax highlighters like Prism or Highlight.js. Loading Monaco on every page view would add noticeable weight to the initial page load, particularly on pages with many macros. Modern Code Blocks avoids this problem through **client-side lazy loading**. On a published page, the macro renders syntax-highlighted code as static HTML. The full Monaco Editor is only downloaded and initialized when a user clicks into a code block to edit it. This split approach means readers get fast, lightweight pages, while editors still have access to the full power of Monaco — including bracket matching, find and replace, and standard editor shortcuts — when they need it. Code blocks load on demand, not on page load, so the critical rendering path stays clear. In practice, teams using Modern Code Blocks see no measurable difference in page load speed compared to the native Confluence code block, even though the editing experience is dramatically better. *** ## How many programming languages does syntax highlighting support?[​](#how-many-programming-languages-does-syntax-highlighting-support "Direct link to How many programming languages does syntax highlighting support?") Modern Code Blocks for Confluence supports **syntax highlighting for over 85 programming languages**. This covers every mainstream language you would expect — JavaScript, TypeScript, Python, Java, C#, Go, Rust, Ruby, PHP, Swift, Kotlin, and C++ — plus a broad range of infrastructure and data languages such as SQL, YAML, JSON, TOML, HCL (Terraform), Dockerfile, Shell/Bash, PowerShell, and XML. Less common languages like Elixir, Haskell, R, Lua, and Julia are also included. Language-specific grammar components are loaded on demand. When a page contains a Python code block and a YAML code block, only the tokenizers for those two languages are fetched. This on-demand loading strategy keeps each page lightweight regardless of how many total languages the plugin supports. You never pay the cost of loading grammars you are not using. *** ## Can I search within code blocks in Confluence?[​](#can-i-search-within-code-blocks-in-confluence "Direct link to Can I search within code blocks in Confluence?") Yes. When you click into a code block to edit it, the Monaco Editor activates and provides **built-in find and replace** via the standard Ctrl+F (or Cmd+F on macOS) keyboard shortcut. The search bar supports regex matching, whole-word matching, and case-sensitive toggles, just like the find experience in VS Code. You can also open find-and-replace mode with Ctrl+H to quickly rename a variable across a snippet. For published pages where the code is rendered as static HTML, Confluence's built-in browser page search (Ctrl+F outside the editor) can still find text inside code blocks. Modern Code Blocks generates semantic HTML that browsers can index, so in-page search works reliably across all major browsers without any extra configuration. *** ## Are code blocks accessible for screen readers?[​](#are-code-blocks-accessible-for-screen-readers "Direct link to Are code blocks accessible for screen readers?") Accessibility is an important consideration for any team producing documentation that must meet WCAG guidelines or internal accessibility standards. Modern Code Blocks generates **semantic HTML with proper ARIA labels** so that screen readers can identify and navigate code content meaningfully. The code container is marked with the appropriate `role` and `aria-label` attributes, and line breaks are preserved in a way that assistive technology can interpret correctly. The plugin also supports **keyboard navigation** within the Monaco Editor. Users can move through code line by line, jump to specific line numbers, and trigger common actions without touching a mouse. For teams that need to provide alternative formats, it is good practice to include a link to a downloadable plain-text version of the code alongside the embedded block. Finally, both the **dark and light themes** included with Modern Code Blocks are designed with sufficient color contrast ratios for syntax highlighting. This ensures that color-coded tokens remain distinguishable for users with color vision deficiencies. *** ## How do I export or copy code from Confluence code blocks?[​](#how-do-i-export-or-copy-code-from-confluence-code-blocks "Direct link to How do I export or copy code from Confluence code blocks?") Modern Code Blocks includes a **copy button on every code block**. With one click, the entire contents of the block are copied to the clipboard in plain text, ready to paste into a terminal, IDE, or configuration file. The copy button appears in the top-right corner of the block on hover, so it does not clutter the display but is always easy to reach. For bulk export scenarios, you can use Confluence's built-in **export to PDF** feature, which preserves code formatting including syntax highlighting colors. If you need raw text for scripting or version control, you can also attach source files directly to the Confluence page and link to them from within the documentation. This dual approach — embedded code for readability, attached files for download — gives readers the best of both worlds. *** ## Does Modern Code Blocks support dark and light themes?[​](#does-modern-code-blocks-support-dark-and-light-themes "Direct link to Does Modern Code Blocks support dark and light themes?") Yes. Modern Code Blocks ships with both a **dark theme and a light theme** so that code blocks visually integrate with your Confluence space regardless of how it is styled. The dark theme uses a VS Code-inspired color palette that reduces eye strain during long reading sessions, while the light theme provides clean, high-contrast syntax highlighting for spaces that use a lighter color scheme. Theme selection can be configured at the macro level, meaning you can use a dark theme for one code block and a light theme for another on the same page if needed. Both themes have been tested against WCAG 2.1 AA contrast requirements to ensure that syntax tokens remain readable for all users. *** ## Comparison: Modern Code Blocks vs native Confluence code block vs Better Code Macro[​](#comparison-modern-code-blocks-vs-native-confluence-code-block-vs-better-code-macro "Direct link to Comparison: Modern Code Blocks vs native Confluence code block vs Better Code Macro") | Feature | Modern Code Blocks for Confluence | Native Confluence Code Block | Better Code Macro | | ------------------------------------ | --------------------------------- | ---------------------------- | -------------------- | | Editor engine | Monaco Editor (VS Code) | Plain text area | Prism.js highlighter | | Initialization | Lazy — loads on demand | Immediate | Immediate | | Languages supported | 85+ | \~30 | \~50 | | Dark and light themes | Yes | Limited | Yes | | Copy button | Built-in, on every block | No | Yes | | Find and replace (Ctrl+F) | Yes | No | No | | Keyboard navigation | Full Monaco keybindings | Basic | Basic | | Max Height with scroll for long code | Yes | No | No | | IntelliSense / autocomplete | No | No | No | | On-demand grammar loading | Yes | No | No | | Bracket matching | Yes | No | No | | Line numbers toggle | Yes | Yes | Yes | | Confluence Cloud support | Yes | Yes | Yes | | Confluence Data Center support | No (Forge app) | Yes | Limited | The table above summarizes how the three options compare. The native Confluence code block is fine for short, simple snippets where you just need basic monospace text with simple highlighting. Better Code Macro improves on that with Prism-based rendering and a copy button. Modern Code Blocks goes further by embedding a full Monaco Editor experience with lazy loading, 85+ languages, find-and-replace, configurable Max Height, and themes — all while keeping page performance comparable to the lightweight alternatives. *** ## Best practices for code blocks in Confluence[​](#best-practices-for-code-blocks-in-confluence "Direct link to Best practices for code blocks in Confluence") ### 1. Keep snippets short and focused[​](#1-keep-snippets-short-and-focused "Direct link to 1. Keep snippets short and focused") Resist the temptation to paste an entire 2,000-line file into a single code block. Instead, extract the 20 to 50 lines that are actually relevant to the point you are making. If readers need the full file, link to it in your source repository or attach it as a downloadable file. Shorter blocks render faster, are easier to scan visually, and make your documentation more readable overall. ### 2. Always specify the language[​](#2-always-specify-the-language "Direct link to 2. Always specify the language") Explicitly setting the language on every code block ensures correct syntax highlighting. When the language is set to "auto" or left blank, the highlighter must guess, and it frequently guesses wrong — especially for short snippets where several languages share similar syntax. Taking two seconds to select "Python" or "YAML" from the dropdown saves every future reader from staring at un-highlighted or incorrectly highlighted code. ### 3. Use Max Height for long reference material[​](#3-use-max-height-for-long-reference-material "Direct link to 3. Use Max Height for long reference material") Configuration files, JSON payloads, and log excerpts are often necessary for completeness but are rarely the primary focus of a page. Set a reasonable Max Height for these code blocks so that the page stays scannable and the narrative flow is not interrupted by walls of text. Readers can scroll within the block to see the full content without navigating away from the page. ### 4. Add a title or filename to each block[​](#4-add-a-title-or-filename-to-each-block "Direct link to 4. Add a title or filename to each block") A code block without context forces the reader to guess which file the code comes from or where it should be placed. Add context above the code block — such as a filename like `docker-compose.yml` or a description like `main.py — API handler` — so that readers immediately understand what they are looking at. ### 5. Leverage the copy button for runnable code[​](#5-leverage-the-copy-button-for-runnable-code "Direct link to 5. Leverage the copy button for runnable code") When documenting installation steps, CLI commands, or quick-start scripts, structure the code so that it can be copied and run directly. Avoid splitting a single command across multiple code blocks, and make sure environment variables or placeholders are clearly marked. The built-in copy button in Modern Code Blocks means a reader can go from reading your documentation to running the code in a single click, which dramatically reduces friction in onboarding and incident-response workflows. *** ## Related resources[​](#related-resources "Direct link to Related resources") * [Modern Code Blocks for Confluence — documentation](/apps/modern-code-blocks-for-confluence.md) * [Advanced code blocks in Confluence](/blog/advanced-code-blocks-confluence.md) — full how-to guide * [Enhanced Markdown for Confluence](/apps/enhanced-markdown-for-confluence.md) — Markdown editing with code support * [Confluence Markdown vs WYSIWYG FAQ](/blog/faq-confluence-markdown-vs-wysiwyg.md) Try Modern Code Blocks for Confluence Monaco editor, 85+ languages (JSON, XML, YAML, SQL), 50+ themes, diff view, and auto dark/light mode — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-code-blocks-for-confluence) ## Related guides * [Code Blocks for Confluence — Monaco Editor & Themes](/blog/code-blocks-confluence-monaco-editor.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [code-blocks](/blog/tags/code-blocks.md) * [confluence](/blog/tags/confluence.md) * [monaco-editor](/blog/tags/monaco-editor.md) * [syntax-highlighting](/blog/tags/syntax-highlighting.md) --- # Confluence Dark Mode Apps FAQ: Themes, Fonts & Code Blocks May 2, 2026 · 13 min read [NGPilot](https://ngpilot.com) Dark mode has moved from a developer preference to an expectation across every tool in the modern workspace. Confluence Cloud introduced a native dark mode toggle, which is a welcome step, but the reality of implementing a fully dark-themed Confluence experience is more nuanced than flipping a single switch. The built-in dark mode transforms the Confluence chrome -- the navigation bar, sidebar, and page background -- but it does not reach inside macro content. Code blocks, diagrams, embedded content, and custom-styled elements often remain in their default light appearance, creating a jarring mismatch that breaks the immersive dark experience your team is looking for. This FAQ addresses the most common questions teams have about achieving a cohesive dark mode setup in Confluence. We cover what the native dark mode handles, where it falls short, and how marketplace apps from NGPILOT and others fill the gaps for code blocks, Mermaid diagrams, typography, and overall page design. ## Does Confluence have a built-in dark mode?[​](#does-confluence-have-a-built-in-dark-mode "Direct link to Does Confluence have a built-in dark mode?") Yes, Confluence Cloud ships with a native dark mode. You can activate it by clicking your profile avatar in the top-right corner and toggling the theme option between light and dark. Once enabled, Confluence applies a dark color scheme to the entire interface: the top navigation bar, the left sidebar, page backgrounds, comment sections, and standard content areas all switch to dark tones. However, the native dark mode has clear boundaries. It controls the application shell and standard Confluence content rendering, but it does not extend to content rendered inside third-party macros or custom-styled elements. This means: * **Code blocks** rendered by the default Confluence code macro keep their light background regardless of your theme setting. * **Diagrams** from macros like Mermaid, PlantUML, or Draw\.io remain in their original color scheme. * **Custom-styled content** using inline HTML or CSS does not automatically adapt to the dark theme. * **Third-party macro content** depends entirely on whether the app developer has implemented dark mode support. For teams that primarily use standard Confluence features like text, tables, and images, the built-in dark mode covers most needs. For engineering teams that rely heavily on code blocks, architecture diagrams, and technical documentation, the gaps are immediately visible and disruptive. This is where marketplace apps with dedicated dark theme support become essential. ## Do NGPILOT apps support dark mode in Confluence?[​](#do-ngpilot-apps-support-dark-mode-in-confluence "Direct link to Do NGPILOT apps support dark mode in Confluence?") Yes, several NGPILOT apps are built with dual-theme support from the ground up. Rather than relying on Confluence to invert colors automatically, these apps ship their own dark and light theme configurations that you control independently. This approach gives you precise control over how content looks in each mode. **Modern Code Blocks for Confluence** provides separate dark and light syntax highlighting themes. The dark theme uses a carefully tuned color palette inspired by popular IDE dark modes, with high-contrast syntax colors that remain readable against the dark background. You select the theme directly in the macro configuration, so code blocks always match your preferred look regardless of the Confluence-level theme setting. **Mermaid Plus Diagrams & AI Agent for Confluence** supports custom color themes that you can configure to work with both light and dark Confluence modes. You can set the theme per diagram using the configuration panel, choosing from Default, Dark, Forest, or Neutral themes. The macro also automatically adapts to Confluence's dark/light mode, adjusting text and background colors for readability. **Google Fonts for Confluence** renders correctly in both light and dark modes because it focuses on font selection and typography rather than color. The fonts themselves are color-neutral -- they inherit the text color from the surrounding Confluence theme. This means your custom typography choices work seamlessly whether your team uses light mode, dark mode, or a mix of both. The key principle across all these apps is that dark mode support is implemented at the content level, not left to chance with automatic color inversion. This produces results that look professional and intentional rather than washed out or poorly contrasted. ## How do I get dark-themed code blocks in Confluence?[​](#how-do-i-get-dark-themed-code-blocks-in-confluence "Direct link to How do I get dark-themed code blocks in Confluence?") Getting dark-themed code blocks in Confluence requires a marketplace app because the default Confluence code macro does not offer theme options. The default macro renders code against a light gray background with basic syntax coloring, and this appearance does not change when you enable Confluence's native dark mode. **Modern Code Blocks for Confluence** solves this with a dedicated dark theme. Here is how to set it up: 1. **Install the app** from the Atlassian Marketplace. It is available for Confluence Cloud. 2. **Insert the macro** on any page by typing `/modern-code-blocks` in the editor or selecting it from the macro browser. 3. **Paste your code** into the macro body and select the programming language for accurate syntax highlighting. 4. **Choose the dark theme** in the macro configuration panel. The dark theme uses VS Code-style dark colors with high contrast for keywords, strings, comments, and other syntax elements. 5. **Save and publish** the page to see the dark-themed code block in action. The dark theme in Modern Code Blocks is designed to match the visual expectations developers have from their daily IDE work. Keywords appear in bright, distinguishable colors against the dark background. Strings, comments, and function names each have their own distinct color, making the code easy to scan and understand. Line numbers are rendered in a muted tone that is visible but does not compete with the code itself. For teams that want consistency, you can configure the default theme at the app level so that every new code block starts with the dark theme pre-selected. Individual authors can still override this on a per-macro basis if a specific page calls for the light theme. The app also supports features that enhance the dark code block experience: line highlighting for drawing attention to specific lines, collapsible sections for long code files, and a copy-to-clipboard button that is styled to match the dark theme. These features work together to create code blocks that feel like a native part of a dark-themed documentation experience rather than a jarring light-colored island on an otherwise dark page. ## Can Mermaid diagrams use dark themes in Confluence?[​](#can-mermaid-diagrams-use-dark-themes-in-confluence "Direct link to Can Mermaid diagrams use dark themes in Confluence?") Yes, Mermaid diagrams can use dark themes in Confluence when you use an app that supports theme customization. The default Mermaid rendering in Confluence uses the standard light Mermaid theme, which produces diagrams with white or light gray backgrounds, dark text, and default blue color schemes. These diagrams stand out awkwardly against a dark Confluence page. **Mermaid Plus Diagrams & AI Agent for Confluence** provides full theme control for Mermaid diagrams: * **Per-diagram theme selection**: Choose from Default, Dark, Forest, or Neutral themes in the macro configuration panel for each diagram. * **Custom color definitions**: Use Mermaid's `style` and `classDef` statements to specify exact colors for nodes, edges, and labels that are optimized for dark backgrounds. When building Mermaid diagrams for dark mode, keep these guidelines in mind: * **Use light text colors** for labels and node text. Dark text on a dark background is unreadable regardless of the diagram shape. * **Choose saturated fill colors** for nodes rather than pastel tones, which can appear washed out against dark backgrounds. * **Increase stroke width** on edges and node borders to maintain visual clarity at smaller sizes. * **Test with actual dark mode enabled** in Confluence to see how your diagram interacts with the surrounding page theme. Mermaid Plus renders diagrams as SVG, which scales cleanly and respects color values precisely. This means the colors you specify are the colors that appear in the final output, without unexpected shifts or compression artifacts that can affect raster image formats. ## Why do my custom fonts look different in dark mode?[​](#why-do-my-custom-fonts-look-different-in-dark-mode "Direct link to Why do my custom fonts look different in dark mode?") Font rendering is influenced by the background color in ways that many people do not anticipate. The same font at the same size can appear noticeably different when displayed against a dark background compared to a light one. This is caused by several factors: **Anti-aliasing behavior.** Font rendering engines use sub-pixel anti-aliasing to make text look smooth on screen. The algorithms that drive this rely on the background color to determine how to blend the edges of each glyph. When the background changes from light to dark, the anti-aliasing produces different edge smoothing, which can make fonts appear slightly thinner or thicker. **Contrast perception.** Human eyes perceive contrast differently depending on the surrounding brightness. Dark text on a light background and light text on a dark background at the same measured contrast ratio can look like different levels of contrast to the reader. Fonts that appear crisp and readable in light mode can seem slightly fuzzy or heavy in dark mode. **Font weight perception.** Light text on a dark background tends to appear slightly bolder than dark text on a light background at the same font weight. This is a well-documented optical illusion in typography. Some designers recommend using a slightly lighter font weight for dark mode to compensate. **Google Fonts for Confluence** handles these issues well because it uses web fonts loaded from the Google Fonts CDN, which are designed and hinted for screen rendering across various backgrounds. The app applies fonts through standard CSS mechanisms, so the text color inherits from Confluence's theme automatically. When Confluence switches to dark mode, the text color changes to a light shade and the font renders with appropriate anti-aliasing for the dark background. To get the best results: * **Choose fonts with good screen rendering.** Fonts like Inter, Roboto, Source Sans Pro, and JetBrains Mono are specifically designed for screen legibility and perform well in both light and dark contexts. * **Test at your actual usage sizes.** A font that looks great at 16px in light mode might need adjustment at that size in dark mode. Test at the sizes you actually use in your documentation. * **Avoid very thin font weights in dark mode.** Weights below 300 often lose legibility against dark backgrounds, especially at smaller sizes. * **Check heading and body text separately.** Headings often use heavier weights that are less affected by the background change, while body text at regular weights shows more difference. ## How do I make my Confluence pages look good in both light and dark mode?[​](#how-do-i-make-my-confluence-pages-look-good-in-both-light-and-dark-mode "Direct link to How do I make my Confluence pages look good in both light and dark mode?") Building Confluence pages that work well in both light and dark modes requires a shift in how you think about content design. The goal is not to make the page look identical in both modes -- that is neither possible nor desirable. Instead, aim for pages that look intentional and polished in each mode on its own terms. **Use apps with dual-theme support.** This is the single most impactful step. When your code blocks, diagrams, and typography each handle their own theme rendering, you avoid the patchwork appearance of some content adapting and other content staying light. Modern Code Blocks, Mermaid Plus, and Google Fonts all support both themes natively. **Avoid hardcoded colors in content.** Confluence pages sometimes use inline styles or HTML macros with specific color values like `color: #333` or `background: #f5f5f5`. These colors look correct in light mode but break in dark mode because the dark text on a dark background becomes invisible, or the light background clashes with the dark page. Use Confluence's built-in text formatting whenever possible, and let the theme control the colors. **Test every page in both modes.** Make it part of your review process to check pages in both light and dark mode. What looks clean in one mode might have readability issues in the other. Pay special attention to: * Tables with colored header rows * Info panels and callout macros * Images with transparent backgrounds * Embedded content from external services * Custom HTML or CSS in macros **Use neutral or adaptive color palettes for diagrams.** When creating Mermaid diagrams, choose colors that have sufficient contrast against both light and dark backgrounds. Mid-tone blues, teals, and greens often work well in both contexts. Avoid very light colors that disappear on light backgrounds or very dark colors that vanish on dark backgrounds. **Set sensible defaults at the app level.** Configure your apps with theme defaults that match your team's most common mode. If 80% of your team uses dark mode, set Modern Code Blocks to default to the dark theme and Mermaid Plus to default to your dark color scheme. Team members who prefer light mode can override per-page if needed. ## NGPILOT Apps Dark Mode Support[​](#ngpilot-apps-dark-mode-support "Direct link to NGPILOT Apps Dark Mode Support") | App | Dark Mode Support | Details | | ----------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------- | | Modern Code Blocks for Confluence | Full | Dark and light syntax highlighting themes, configurable per macro and globally | | Mermaid Plus Diagrams & AI Agent for Confluence | Full | Custom color themes, per-diagram theme configuration, automatic dark/light adaptation, SVG rendering | | Google Fonts for Confluence | Compatible | Fonts inherit theme colors automatically, no manual adjustment needed | ## Tips for Confluence Dark Mode[​](#tips-for-confluence-dark-mode "Direct link to Tips for Confluence Dark Mode") **Start with the built-in toggle.** Before investing in marketplace apps, enable Confluence's native dark mode and assess where the gaps are for your team. Different teams have different content patterns, and understanding your specific needs helps you choose the right apps. **Standardize on one theme for your team.** While Confluence allows each user to choose their own theme, teams that standardize on one mode can optimize their content more aggressively. If your team has standardized on dark mode, you can configure all your apps for dark-first rendering without worrying about light mode edge cases. **Create a style guide for dark mode.** Document which colors, fonts, and diagram styles your team should use. Include examples of correctly formatted code blocks, diagrams, and pages in both light and dark modes. This reduces the trial-and-error for content authors and keeps your documentation visually consistent. **Review third-party app compatibility before installing.** Not all Confluence apps handle dark mode well. Before installing a new app, test it with dark mode enabled to see how its macros render. Apps that only support light rendering will create visible inconsistencies on your dark-themed pages. **Use browser extensions for preview.** Browser extensions that force dark mode on web pages can give you a preview of how your content might look, but they often produce poor results with Confluence because they apply blanket color inversion. Use them only for rough previews, not for final design decisions. **Keep accessibility in mind.** Dark mode is not just an aesthetic preference. For some users, it is an accessibility requirement. Ensure that your dark-themed content meets WCAG contrast standards. Both Modern Code Blocks and Mermaid Plus use color palettes designed to maintain accessible contrast ratios in their dark themes. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Modern Code Blocks for Confluence](/apps/modern-code-blocks-for-confluence.md) -- Configuration guide for syntax highlighting themes, including dark mode setup * [Mermaid Plus Diagrams & AI Agent for Confluence](/apps/mermaid-plus-for-confluence.md) -- Usage documentation covering theme configuration and custom color schemes * [Google Fonts for Confluence](/apps/google-fonts-for-confluence.md) -- Typography setup and font selection for Confluence pages * [Code Blocks Performance FAQ](/blog/faq-code-blocks-performance.md) -- Performance considerations for code-heavy Confluence pages * [Mermaid Troubleshooting FAQ](/blog/faq-mermaid-troubleshooting.md) -- Common issues and solutions for Mermaid diagrams in Confluence * [Best Confluence Apps for Developers](/blog/best-confluence-apps-developers.md) -- Curated list of Confluence apps for engineering teams Try Modern FAQ for Confluence Accordion-style FAQ sections with drag-and-drop reordering and two themes — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236739/modern-faq-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-faq-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [confluence](/blog/tags/confluence.md) * [dark-mode](/blog/tags/dark-mode.md) * [themes](/blog/tags/themes.md) --- # How to Write Markdown in Confluence — Syntax, Tables & Code Blocks May 2, 2026 · 13 min read [NGPilot](https://ngpilot.com) Who should read this * **Developers and tech writers** who want to write Markdown in Confluence instead of the WYSIWYG editor * **Teams migrating** README files, docs repos, or API references into Confluence * **Anyone** who needs Mermaid diagrams or LaTeX math inside Markdown content What you'll learn 1. Whether Confluence supports Markdown natively (and why it doesn't) 2. How to write Markdown with live preview, including code blocks, tables, and Mermaid 3. How Markdown content behaves after publish (search, exports, permissions) 4. When to use Markdown vs. Confluence's native WYSIWYG editor Confluence's built-in editor is strictly WYSIWYG — there is no native Markdown editor. For teams who already write in Markdown (README files, docs repos, pull request descriptions), that means manually reformatting every doc through toolbar buttons, losing time and introducing inconsistencies. **Enhanced Markdown for Confluence** solves this by embedding a full Markdown editor with live split preview directly inside Confluence — and it renders Mermaid diagrams, KaTeX/LaTeX math, and 190+ code-highlighted languages, all in one macro. This FAQ answers the questions teams ask most often about writing Markdown in Confluence. *** ## Frequently Asked Questions[​](#frequently-asked-questions "Direct link to Frequently Asked Questions") ### 1. Does Confluence support Markdown natively?[​](#1-does-confluence-support-markdown-natively "Direct link to 1. Does Confluence support Markdown natively?") No. Confluence's built-in editor is entirely WYSIWYG (What You See Is What You Get). You format content using toolbar buttons, keyboard shortcuts, and slash commands -- not by writing markup. While Confluence can display Markdown content that has been imported or embedded through specific macros, there is no first-party Markdown editor where you write and edit page content in Markdown syntax directly. This is a significant limitation for developer teams. Most developers write in Markdown every day: README files in Git repositories, pull request descriptions on GitHub or Bitbucket, documentation in static site generators like Docusaurus or MkDocs, and comments in Jira. Having to switch from Markdown to a visual editor when moving content into Confluence adds friction and slows down the documentation process. **Enhanced Markdown for Confluence** fills this gap. It installs from the Atlassian Marketplace and adds a dedicated Markdown editing macro to your Confluence instance. Once installed, any user on your Confluence site can insert a Markdown block by typing `/enhanced markdown` in the editor and selecting the macro. The macro opens a full-featured Markdown editing environment right inside the Confluence page, with a live split preview (powered by the Quikdown engine) so you see the rendered output — including Mermaid diagrams and LaTeX math — as you type. The key advantage is that the rendered output becomes standard Confluence content. It participates in Confluence search indexing, respects page permissions, works with exports, and integrates with all of Confluence's platform features just like any other page content. ### 2. How does Enhanced Markdown for Confluence work?[​](#2-how-does-enhanced-markdown-for-confluence-work "Direct link to 2. How does Enhanced Markdown for Confluence work?") Enhanced Markdown for Confluence operates as a Confluence macro that you insert into any page. Here is the step-by-step workflow: 1. **Edit a Confluence page** and place your cursor where you want the Markdown content to appear. 2. **Type `/enhanced markdown`** in the editor and select **Enhanced Markdown for Confluence** from the macro list. 3. **Write or paste your Markdown** into the editor that opens. The editor provides a live split preview (powered by the Quikdown engine), so you see the rendered output — including Mermaid diagrams and LaTeX math — as you type. 4. **Preview in WYSIWYG mode.** Switch to WYSIWYG mode at any time to see how the rendered content will look, so you can catch formatting issues before saving. 5. **Click Save** to render the Markdown onto the page. The content is stored in standard Confluence storage format. 6. **Re-edit anytime.** Click on an existing Enhanced Markdown macro and select Edit to reopen the editor. Your Markdown source is fully preserved, so you can continue editing from where you left off. Under the hood, the app converts your Markdown into Confluence's native storage format when you save. This means the rendered content is fully compatible with Confluence's export engines (PDF, HTML, Word), search indexing, macro processing, and page permissions. From Confluence's perspective, the output is no different from content created in the native editor. The editor also supports dark mode automatically. When a user has Confluence's dark theme enabled, the Markdown macro adapts its appearance to match, ensuring a consistent visual experience. For a complete walkthrough of all features and configuration options, see the [Enhanced Markdown for Confluence usage guide](/docs/Enhanced-Markdown-for-Confluence/usage.md). ### 3. What Markdown syntax does Enhanced Markdown for Confluence support?[​](#3-what-markdown-syntax-does-enhanced-markdown-for-confluence-support "Direct link to 3. What Markdown syntax does Enhanced Markdown for Confluence support?") The editor supports comprehensive Markdown syntax covering both the CommonMark specification and GitHub Flavored Markdown (GFM) extensions. Here is a detailed breakdown of what is available: **Core formatting:** * Headings (H1 through H6 using `#` prefix) * Bold (`**text**`), italic (`*text*`), and strikethrough (`~~text~~`) * Ordered and unordered lists with nesting * Task lists with checkboxes (`- [ ]` and `- [x]`) * Links (inline and reference-style) * Blockquotes (`>`) — see the [block quote in Confluence guide](/blog/block-quote-confluence.md) for nesting and attribution * Horizontal rules (`---` or `***`) **GitHub Flavored Markdown extensions:** * Pipe tables with column alignment * Fenced code blocks with language-specific syntax highlighting * Task lists **Advanced features beyond standard Markdown:** * Table merged cells for complex table layouts * Color syntax with visual color previews * Chart embedding * PlantUML diagram rendering for UML diagrams (sequence, class, use case, and more) This syntax coverage means that virtually any Markdown content you write in GitHub, VS Code, or your documentation toolchain will render correctly when pasted into Enhanced Markdown for Confluence. You do not need to learn Confluence-specific syntax or adjust your writing habits. ### 4. Can I use code blocks with syntax highlighting in Markdown content?[​](#4-can-i-use-code-blocks-with-syntax-highlighting-in-markdown-content "Direct link to 4. Can I use code blocks with syntax highlighting in Markdown content?") Yes, code blocks are one of the strongest features of Enhanced Markdown for Confluence. The editor supports fenced code blocks with language identifiers, and they render with syntax highlighting for dozens of programming languages. To create a code block, wrap your code with triple backticks and specify the language: ```` ```python def calculate_total(items): total = sum(item.price * item.quantity for item in items) return round(total, 2) ``` ```` ```` ```javascript const fetchData = async (endpoint) => { const response = await fetch(endpoint); return response.json(); }; ``` ```` The syntax highlighting engine automatically applies language-aware color formatting based on the identifier you specify. Common identifiers include `python`, `javascript`, `java`, `go`, `rust`, `typescript`, `sql`, `bash`, `json`, `yaml`, `xml`, `html`, `css`, and many more. Code blocks also adapt to Confluence's theme. When a user views the page in dark mode, the code block rendering adjusts to maintain readability and contrast. This ensures that technical content looks professional regardless of the viewer's theme preference. For teams that need even more advanced code display features -- such as configurable line numbers, minimap navigation, and the Monaco editor experience -- Enhanced Markdown for Confluence works alongside Modern Code Blocks for Confluence. You can learn more about advanced code display options in the [advanced code blocks guide](/blog/advanced-code-blocks-confluence.md). ### 5. How do tables and images work in the Markdown editor?[​](#5-how-do-tables-and-images-work-in-the-markdown-editor "Direct link to 5. How do tables and images work in the Markdown editor?") **Tables** are supported through standard Markdown pipe syntax. You create tables by separating columns with pipe characters and defining the header row with separator dashes: ``` | Feature | Supported | Notes | |---------|-----------|-------| | Basic tables | Yes | Standard pipe syntax | | Column alignment | Yes | Use `:---`, `:---:`, `---:` | | Merged cells | Yes | Beyond standard Markdown | ``` Column alignment is controlled by adding colons to the separator row: `:---` for left-aligned, `:---:` for center-aligned, and `---:` for right-aligned. Enhanced Markdown for Confluence goes beyond standard Markdown table support by offering **merged cells**. This allows you to create complex table layouts with cells that span multiple rows or columns -- something that standard Markdown cannot express but that is common in project status reports, comparison matrices, and detailed technical specifications. **Images** are added using standard Markdown image syntax: ``` ![Alt text describing the image](https://example.com/image.png) ``` Images render inline on the Confluence page. Alt text is preserved for accessibility. You can reference externally hosted images or images that have been attached to the Confluence page. The rendered images behave like native Confluence image embeds -- they display at an appropriate size within the page layout and are accessible through the page's attachment management. ### 6. How does the Markdown editor compare to Confluence's native WYSIWYG editor?[​](#6-how-does-the-markdown-editor-compare-to-confluences-native-wysiwyg-editor "Direct link to 6. How does the Markdown editor compare to Confluence's native WYSIWYG editor?") The two editors serve different audiences and workflows. Here is a detailed comparison: **Editing experience.** The native Confluence editor is toolbar-driven. You select text and click buttons to apply formatting, or use slash commands to insert elements. Enhanced Markdown for Confluence is keyboard-centric — you type formatting syntax directly, which is significantly faster for users who are comfortable with Markdown. The editor also provides a live split preview (powered by the Quikdown engine), so you see exactly how the rendered page will look — including Mermaid diagrams, LaTeX math, and syntax-highlighted code — as you write. **Content portability.** Markdown content is plain text. You can copy it out of Confluence and paste it into GitHub, VS Code, a static site generator, or any other Markdown-compatible tool without reformatting. WYSIWYG content is stored in Confluence's proprietary XML-based storage format, which is difficult to extract and reuse outside of Confluence. **Version control compatibility.** Plain-text Markdown files diff cleanly in Git and other version control systems. You can review changes line by line in a pull request. WYSIWYG content stored in Confluence's storage format produces XML diffs that are nearly impossible to review manually. If your documentation workflow involves Git-based review processes, Markdown is the clear winner. **Learning curve.** WYSIWYG editing has essentially no learning curve -- anyone can click a Bold button. Markdown requires learning a lightweight syntax, but for developers and technical writers who already know it, there is zero additional learning required. The Markdown editor's dual-mode design (raw Markdown and WYSIWYG) also provides a safety net for users who are still learning the syntax. **Macro support.** The native editor has access to the full Confluence macro library through the macro browser. Enhanced Markdown for Confluence supports macro syntax for commonly used macros like info panels, tables of contents, and code blocks. For pages that rely heavily on specialized Confluence macros, the native editor may be more practical. Many teams use a hybrid approach: Markdown for the body content and native Confluence macros for specialized elements. | Feature | Enhanced Markdown | Native WYSIWYG | | ------------------------ | -------------------------------- | ------------------------------ | | Editing mode | Raw Markdown + WYSIWYG | WYSIWYG only | | Keyboard-centric writing | Yes | Partial (shortcuts) | | Live preview | Yes — switch to WYSIWYG mode | Native (inline) | | Code syntax highlighting | Fenced blocks with language tags | Code block macro | | Table merged cells | Supported | Supported | | PlantUML diagrams | Supported | Requires separate macro | | Dark mode adaptation | Automatic | Automatic | | Content portability | Plain text, works everywhere | Confluence storage format only | | Version control diffs | Clean, line-by-line | XML, hard to review | | Full macro library | Common macros supported | All macros available | | Re-editing source | Source preserved | N/A (visual) | *** ## Markdown Syntax Quick Reference[​](#markdown-syntax-quick-reference "Direct link to Markdown Syntax Quick Reference") Here is a quick reference for the Markdown syntax supported by Enhanced Markdown for Confluence. Use this table as a cheat sheet when writing content. | Element | Syntax | Example | | ---------------------- | --------------------------- | ------------------------------- | | Heading H1 | `# text` | `# Project Overview` | | Heading H2 | `## text` | `## Installation` | | Heading H3 | `### text` | `### Prerequisites` | | Bold | `**text**` | `**important note**` | | Italic | `*text*` | `*emphasis*` | | Strikethrough | `~~text~~` | `~~deprecated~~` | | Unordered list | `- item` | `- First item` | | Ordered list | `1. item` | `1. First step` | | Task list (incomplete) | `- [ ] task` | `- [ ] Write tests` | | Task list (complete) | `- [x] task` | `- [x] Deploy to staging` | | Link | `[text](url)` | `[NGPILOT](https://ngpilot.io)` | | Image | `![alt](url)` | `![Logo](/img/logo.png)` | | Inline code | `` `code` `` | `` `console.log()` `` | | Code block | Triple backticks + language | See code block examples above | | Blockquote | `> text` | `> This is a note` | | Horizontal rule | `---` | `---` | | Table | Pipe syntax with header row | See table examples above | *** ## Tips for Getting the Most Out of Markdown in Confluence[​](#tips-for-getting-the-most-out-of-markdown-in-confluence "Direct link to Tips for Getting the Most Out of Markdown in Confluence") **Start with new pages.** Rather than converting your existing documentation immediately, begin by writing new pages in Markdown. This lets your team get comfortable with the editing workflow before touching existing content. **Use the WYSIWYG mode as a crutch.** If you forget a specific Markdown syntax, switch to the WYSIWYG mode in the editor toolbar. Format the content visually, then switch back to Markdown mode to see the generated syntax. This is an excellent way to learn Markdown incrementally. **Specify language identifiers on code blocks.** Always add a language tag after the opening triple backticks (for example, `python`, `javascript`, `sql`). This ensures syntax highlighting is applied correctly and makes your code snippets more readable for the team. **Leverage PlantUML for diagrams.** Instead of uploading image files for architecture diagrams, flowcharts, and sequence diagrams, write them in PlantUML syntax directly in your Markdown content. They render automatically and can be updated by editing the text -- no image editor required. **Take advantage of merged cells for complex tables.** Standard Markdown tables are limited to simple grids. Enhanced Markdown for Confluence supports merged cells, which means you can build the kind of complex status tables and comparison matrices that project management and technical documentation often require. **Test your exports.** Although Enhanced Markdown for Confluence renders to standard Confluence storage format (meaning PDF, HTML, and Word exports work out of the box), always verify the export output for pages with complex formatting. Nested tables, PlantUML diagrams, and color syntax elements should be checked in your most commonly used export format. *** ## Confluence wiki markup vs Markdown[​](#confluence-wiki-markup-vs-markdown "Direct link to Confluence wiki markup vs Markdown") Searches for "Confluence markup" usually mean one of two different things, and it helps to separate them: **Wiki markup** is the legacy plain-text syntax of the Server/Data Center editor: `h1. Heading`, `*bold*`, `{{monospace}}`, `||Header||Header||` tables, `{code:java}` macros. It was how you "wrote the source" of a Confluence page before the visual editor took over. In Cloud it is no longer an editing mode — but it still shows up in real life: * **Server → Cloud migrations**, where imported pages may carry wiki markup remnants * **Old exports and backups** written in wiki markup * **The Insert > Markup dialog** (`/markup` in the editor), which still converts pasted wiki markup and Markdown fragments into editor content — good for a one-off snippet, lossy for complex content **Confluence storage format** is the current "source of truth": the XHTML-based format every Cloud page is stored in. Nobody writes it by hand, but you may need to *see* it when debugging a broken macro or auditing an import: * Via the REST API: `GET /rest/api/content/{id}?expand=body.storage` * Or on the page itself with the [Raw Storage Source Editor for Confluence](/apps/raw-storage-source-editor-for-confluence.md), which displays and edits the storage format in place If what you actually want is a markup language you can write daily, Markdown is the ecosystem default — and [importing Markdown into Confluence](/blog/markdown-to-confluence-converter.md) is exactly what Enhanced Markdown automates: type or paste Markdown, get standard Confluence content. *** ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Enhanced Markdown for Confluence usage guide](/apps/enhanced-markdown-for-confluence.md) -- complete documentation for all features, configuration, and tips * [Confluence Markdown vs WYSIWYG: Which Should You Use?](/blog/faq-confluence-markdown-vs-wysiwyg.md) -- detailed comparison of Markdown and WYSIWYG editing approaches in Confluence * [Best Confluence Apps for Developers](/blog/best-confluence-apps-developers.md) -- roundup of NGPILOT apps that make Confluence a better development workspace * [How to add a block quote in Confluence](/blog/block-quote-confluence.md) -- three methods compared: native indent, Markdown `>` syntax, and a styled panel macro * [Advanced Code Blocks in Confluence](/blog/advanced-code-blocks-confluence.md) -- how-to guide for advanced code display features including line numbers, code folding, and Monaco editor integration Try Enhanced Markdown for Confluence Write Markdown with live split preview, Mermaid diagrams, KaTeX/LaTeX math, and 190+ code languages — all in one macro, free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=enhanced-markdown-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [markdown-editor](/blog/tags/markdown-editor.md) * [writing](/blog/tags/writing.md) --- # Markdown vs WYSIWYG in Confluence — When to Pick Which April 21, 2026 · 12 min read [NGPilot](https://ngpilot.com) Confluence has been the go-to knowledge base and documentation platform for thousands of organizations. At its core, Confluence uses a WYSIWYG (What You See Is What You Get) editor that lets users format content visually -- clicking toolbar buttons for headings, bold text, tables, and macros without writing a single line of markup. But an increasing number of teams are asking a different question: can we write Confluence content in Markdown instead? Markdown is a lightweight plain-text formatting syntax originally created by John Gruber in 2004. It has become the default writing format for developers, technical writers, and content teams who work with Git repositories, static site generators, and API documentation. Its appeal is simple: you focus on structure and meaning rather than visual styling, and the formatted output is generated automatically. Teams choose Markdown over WYSIWYG for several compelling reasons. Developer-heavy teams often already write in Markdown daily -- in README files, pull request descriptions, and documentation repos. Switching to a WYSIWYG editor for Confluence pages feels like a step backward. Markdown content is also plain text, which means it works seamlessly with version control systems like Git, diff tools, and automated pipelines. Finally, Markdown files are portable; the same `.md` file can be published to GitHub, a static site, or a Confluence page without reformatting. On the other hand, WYSIWYG editing remains the better choice for non-technical users who prefer visual feedback, drag-and-drop file attachments, and toolbar-driven formatting. Many business teams have no interest in learning syntax rules, no matter how lightweight. This FAQ addresses the most common questions teams have when evaluating Markdown versus WYSIWYG editing in Confluence, and explains how Enhanced Markdown for Confluence by NGPILOT bridges the gap between both worlds. ## Can I use Markdown in Confluence?[​](#can-i-use-markdown-in-confluence "Direct link to Can I use Markdown in Confluence?") Out of the box, Confluence does not provide a native Markdown editor. The built-in editor is entirely WYSIWYG, with formatting applied through toolbar buttons, keyboard shortcuts, and slash commands. While Confluence can *display* Markdown content that has been imported or embedded, there is no first-party way to write and edit pages in Markdown syntax directly. This is where third-party apps fill the gap. **Enhanced Markdown for Confluence** by NGPILOT adds a full-featured Markdown editor directly inside Confluence. It provides both a raw Markdown mode and a WYSIWYG mode powered by Toast UI Editor, so you can switch between writing raw Markdown and a visual editing experience depending on your preference. The editor supports standard Markdown syntax including headings, bold and italic text, ordered and unordered lists, links, images, blockquotes, and horizontal rules. Beyond the basics, it handles GitHub Flavored Markdown extensions such as tables, task lists with checkboxes, strikethrough text, and fenced code blocks with language-specific syntax highlighting. This means developers can write content in the same Markdown syntax they already use in GitHub, VS Code, and documentation toolchains -- and publish it directly to Confluence without any manual conversion. ## When should I use Markdown instead of the WYSIWYG editor?[​](#when-should-i-use-markdown-instead-of-the-wysiwyg-editor "Direct link to When should I use Markdown instead of the WYSIWYG editor?") Choosing between Markdown and WYSIWYG depends on your team, your content, and your workflow. Here are the scenarios where Markdown is the stronger choice: * **Technical documentation and API references.** Markdown is purpose-built for structured technical content. Code blocks, inline code, tables, and heading hierarchies map naturally to API docs, runbooks, and architecture decision records. * **Version-controlled content.** If your documentation lives in a Git repository and flows through pull requests, Markdown is the ideal format. Plain-text files diff cleanly, making it easy to review changes line by line. WYSIWYG content stored in Confluence's storage format is XML-based and nearly impossible to diff meaningfully. * **Developer-oriented teams.** Developers write Markdown constantly -- in README files, commit messages, pull request descriptions, and Jira comments. Forcing them into a WYSIWYG editor for Confluence pages adds friction. Markdown lets them stay in the writing mode they already know. * **Content reuse and automation.** Markdown files can be generated from templates, populated by scripts, and processed by CI/CD pipelines. This is far more difficult with WYSIWYG content that lives inside Confluence's proprietary format. * **Cross-platform publishing.** A single Markdown file can be published to Confluence, a static website, GitHub Pages, or npm documentation packages without rewriting. Conversely, WYSIWYG is the better fit when your contributors are non-technical business users, when pages rely heavily on Confluence macros and dynamic content, or when drag-and-drop file embedding is a core part of the workflow. ## Do Confluence macros work inside Markdown content?[​](#do-confluence-macros-work-inside-markdown-content "Direct link to Do Confluence macros work inside Markdown content?") One of the most common concerns about adopting Markdown in Confluence is macro compatibility. Confluence macros -- such as info panels, tables of contents, code blocks, and status indicators -- are a core part of many teams' documentation workflows. If Markdown content cannot use macros, the value proposition drops significantly. **Enhanced Markdown for Confluence** addresses this by providing a macro syntax that maps to commonly used Confluence macros. Rather than inserting macros through a visual dialog, you write them inline in your Markdown using a concise, readable syntax. For example, you can create an info panel, a warning callout, or a table of contents macro directly in your Markdown source. The most frequently used macros have direct Markdown equivalents or first-class integration. These include info, tip, note, and warning panels for callouts, table-of-contents generation for long pages, and code block macros with language-specific formatting. For macros that are not yet supported, you can combine Markdown content with native Confluence macros by using Markdown for the body content and falling back to the standard editor for macro-specific sections. It is worth noting that the macro coverage continues to expand with each release of Enhanced Markdown for Confluence. If a specific macro you need is not supported, it is worth checking the latest release notes or reaching out to the NGPILOT team. ## How do I migrate existing WYSIWYG pages to Markdown?[​](#how-do-i-migrate-existing-wysiwyg-pages-to-markdown "Direct link to How do I migrate existing WYSIWYG pages to Markdown?") Migrating from WYSIWYG to Markdown is a straightforward process, but it requires some planning to avoid disruption. Here is a recommended approach: 1. **Start with new pages.** Rather than converting existing content immediately, begin by writing new pages in Markdown. This lets your team get comfortable with the workflow without risking existing documentation. 2. **Use the import and conversion feature.** Enhanced Markdown for Confluence can import and convert certain content types from existing WYSIWYG pages. This handles the bulk of the transformation for standard formatting like headings, lists, tables, and text styling. 3. **For complex pages, export and convert manually.** Pages with heavy macro usage, embedded media, or complex layouts may require manual adjustment. You can export the page content from Confluence, convert it using a tool like Pandoc, and then clean up the result in the Markdown editor. 4. **Always test on a copy.** Before replacing a production page, duplicate it and test the Markdown version thoroughly. Verify that all formatting, links, images, and macros render correctly. 5. **Iterate in phases.** Migrate one space or content type at a time. Start with the simplest pages (meeting notes, decision logs) and work up to more complex documentation sets. The key principle is to avoid a big-bang migration. Incremental adoption reduces risk and gives your team time to develop Markdown writing habits naturally. ## Will Markdown content export to PDF and HTML correctly?[​](#will-markdown-content-export-to-pdf-and-html-correctly "Direct link to Will Markdown content export to PDF and HTML correctly?") Yes. Enhanced Markdown for Confluence renders Markdown to standard Confluence storage format at publish time. This means that once a Markdown page is saved, it behaves exactly like any other Confluence page from the perspective of the platform's export engines. PDF exports, HTML exports, and Word exports all work as expected. The rendered content flows into the export template just like WYSIWYG-authored content. Links, images, tables, and code blocks all translate properly because the underlying storage format is identical. There are a few edge cases to be aware of. If you are using Markdown-specific macro syntax for callout panels or tables of contents, verify that these render correctly in the export format you use most frequently. Some complex nested structures may need minor adjustment. Additionally, if you have paired Enhanced Markdown with Modern Code Blocks for advanced syntax highlighting, confirm that the code block styling carries through to the exported document -- in rare cases, theme-specific highlighting may render differently in PDF output compared to the browser view. ## What are best practices for writing Markdown in Confluence?[​](#what-are-best-practices-for-writing-markdown-in-confluence "Direct link to What are best practices for writing Markdown in Confluence?") Adopting Markdown in Confluence is most successful when your team follows a few consistent practices: * **Keep sections short and well-structured.** Use heading levels (H2, H3) to create a clear hierarchy. Each section should cover a single topic. This makes content easier to scan, search, and maintain. * **Use code blocks with proper language tags.** Always specify the language in fenced code blocks (for example, ``python` or ``javascript\`). This ensures syntax highlighting works correctly and makes code snippets more readable. * **Create reusable templates.** For repetitive content types like runbooks, incident reports, or architecture decision records, create Markdown templates that team members can copy and fill in. This ensures consistency across pages. * **Pair Markdown with Modern Code Blocks for technical documentation.** If your pages contain significant amounts of code, Enhanced Markdown for Confluence works seamlessly with Modern Code Blocks for Confluence to deliver advanced syntax highlighting for over 85 programming languages, line numbering, and a Monaco-powered editing experience. * **Preview before publishing.** The WYSIWYG mode in Enhanced Markdown for Confluence lets you see how your Markdown renders visually. Always review the rendered output before saving, especially for complex tables or nested structures. * **Establish team conventions.** Agree on style details like how to format filenames (backticks or bold), whether to use ATX-style headings (the `#` prefix), and how to handle long links (inline or reference-style). Consistency matters more than the specific choice. ## Markdown vs WYSIWYG: Comparison Table[​](#markdown-vs-wysiwyg-comparison-table "Direct link to Markdown vs WYSIWYG: Comparison Table") | Feature | Markdown | WYSIWYG | Best For | | ----------------------------------- | --------------------------------------------------- | ----------------------------------------------------- | -------------------------------------- | | Learning curve | Low for developers; requires syntax knowledge | Very low; toolbar-driven | WYSIWYG for non-technical users | | Writing speed | Fast for keyboard-centric users | Moderate; relies on mouse interactions | Markdown for power users | | Version control compatibility | Excellent -- plain text diffs cleanly | Poor -- XML storage format is hard to diff | Markdown for Git-based workflows | | Live preview | Yes — switch to WYSIWYG mode to preview | Native (what you see is what you get) | Tie | | Code blocks and syntax highlighting | Strong -- fenced blocks with language tags | Limited -- relies on macro insertion | Markdown for technical content | | Table editing | Write in Markdown syntax or use visual tools | Visual table builder with drag-and-resize | WYSIWYG for complex layouts | | Image management | Markdown image syntax; paste or drag supported | Drag-and-drop, gallery macros, resize handles | WYSIWYG for media-heavy pages | | Macro support | Macro syntax for common macros (Enhanced Markdown) | Full macro browser with all Confluence macros | WYSIWYG for macro-heavy workflows | | Content portability | High -- plain text works anywhere | Low -- tied to Confluence storage format | Markdown for multi-platform publishing | | Automation and scripting | Native -- text files can be generated and processed | Difficult -- requires Confluence API calls | Markdown for CI/CD pipelines | | Collaboration for mixed teams | Good with live preview and intuitive syntax | Excellent -- visual editing is universally understood | WYSIWYG for cross-functional teams | ## When to Use Markdown vs WYSIWYG: Decision Guide[​](#when-to-use-markdown-vs-wysiwyg-decision-guide "Direct link to When to Use Markdown vs WYSIWYG: Decision Guide") If you are still unsure which approach fits your team, use this decision framework: **Choose Markdown when:** * Your team is primarily composed of developers, DevOps engineers, or technical writers who already write in Markdown daily. * Your documentation is version-controlled in Git and flows through pull request reviews before publishing. * You need to generate documentation programmatically from templates, API schemas, or CI/CD pipelines. * Your content is heavily code-oriented with frequent code blocks, inline code references, and technical tables. * You publish the same content to multiple platforms (Confluence, GitHub, static sites) and need a single source format. **Choose WYSIWYG when:** * Your contributors include project managers, HR teams, marketing staff, or other non-technical roles. * Your pages rely on a wide range of Confluence macros, third-party app macros, or dynamic content like Jira issue filters. * Drag-and-drop file embedding and visual image placement are critical to your workflow. * Your team has no existing familiarity with Markdown and the learning investment is not justified by the content types you produce. **Use both when:** * Your organization has mixed teams. Technical documentation spaces can adopt Markdown while business-facing spaces stay with WYSIWYG. * Enhanced Markdown for Confluence supports both editing modes in the same Confluence instance, so each team can choose the approach that fits without conflict. * Some pages within a single space can be Markdown while others remain WYSIWYG. There is no need for an all-or-nothing decision. The bottom line is that Markdown and WYSIWYG are not mutually exclusive. The best documentation strategy is the one that removes friction for the people actually writing the content. Enhanced Markdown for Confluence gives teams the flexibility to choose the right tool for each page, each space, and each contributor -- without leaving Confluence. ## Related resources[​](#related-resources "Direct link to Related resources") * [Enhanced Markdown for Confluence](/apps/enhanced-markdown-for-confluence.md) — WYSIWYG Markdown editor with live preview * [Modern Code Blocks for Confluence](/apps/modern-code-blocks-for-confluence.md) — syntax highlighting for 85+ languages * [Advanced code blocks in Confluence](/blog/advanced-code-blocks-confluence.md) — how-to guide * [Code blocks performance FAQ](/blog/faq-code-blocks-performance.md) Try Enhanced Markdown for Confluence Write Markdown with live split preview, Mermaid diagrams, KaTeX/LaTeX math, and 190+ code languages — all in one macro, free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=enhanced-markdown-for-confluence) ## Related guides * [How to Write Markdown in Confluence](/blog/faq-confluence-markdown-editor.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [markdown](/blog/tags/markdown.md) * [confluence](/blog/tags/confluence.md) * [wysiwyg](/blog/tags/wysiwyg.md) * [documentation](/blog/tags/documentation.md) --- # Mermaid Sequence Diagrams in Confluence: FAQ & Examples May 2, 2026 · 17 min read [NGPilot](https://ngpilot.com) Sequence diagrams are one of the most widely used diagram types in software documentation. They show exactly how participants -- users, services, databases, external APIs -- exchange messages over time. For Confluence teams, embedding sequence diagrams directly on wiki pages means architecture docs, API specifications, and incident post-mortems stay in one place instead of scattered across external tools. Mermaid's text-based syntax makes sequence diagrams fast to write and easy to update, but the syntax has its own set of rules that can trip you up. This FAQ answers the questions Confluence users ask most often about building sequence diagrams with Mermaid, with expanded explanations, working code examples, and copy-paste templates you can drop straight into a Mermaid Plus macro. ## How do I create a sequence diagram in Confluence with Mermaid?[​](#how-do-i-create-a-sequence-diagram-in-confluence-with-mermaid "Direct link to How do I create a sequence diagram in Confluence with Mermaid?") Creating a sequence diagram in Confluence requires two things: a Mermaid-compatible macro on the page and the correct `sequenceDiagram` syntax in the macro body. Here is the step-by-step process. **Step 1: Install Mermaid Plus Diagrams & AI Agent for Confluence.** Go to the Atlassian Marketplace, search for **Mermaid Plus Diagrams & AI Agent for Confluence**, and click **Get App**. If your organization requires admin approval for marketplace apps, submit a request through your internal process. Once installed, the macro is available in every Confluence space. **Step 2: Insert the macro on a page.** Open any Confluence page in edit mode. Type `/mermaid` in the editor and select the **Mermaid Plus** macro from the dropdown. A code editor panel opens where you can write and preview your diagram. **Step 3: Write the sequence diagram code.** Start with the `sequenceDiagram` keyword, declare your participants, and add messages between them: ``` sequenceDiagram participant Client participant API as API Gateway participant DB as Database Client->>API: POST /users API->>DB: INSERT INTO users DB-->>API: Row created API-->>Client: 201 Created ``` **Step 4: Preview and publish.** Click **Preview** inside the macro editor to verify the diagram renders correctly. When you are satisfied, click **Save** on the macro, then **Publish** the Confluence page. The `participant` keyword is optional -- Mermaid will infer participants from the message lines -- but declaring them explicitly gives you control over the display order and lets you use the `as` keyword to set friendly display names while keeping short aliases in the code. ## What arrow types does Mermaid support in sequence diagrams?[​](#what-arrow-types-does-mermaid-support-in-sequence-diagrams "Direct link to What arrow types does Mermaid support in sequence diagrams?") Arrow types are the most important visual cue in a sequence diagram. Different arrow styles communicate different types of interactions, and using them consistently makes your diagrams immediately understandable. Mermaid supports six distinct arrow operators for sequence diagrams: | Arrow Type | Syntax | Meaning | When to Use | | -------------------------- | -------------- | ---------------------- | -------------------------------------- | | Solid arrow with message | `A->>B: Text` | Synchronous request | Direct calls, RPCs, form submissions | | Dashed arrow with message | `A-->>B: Text` | Response or return | Return values, acknowledgments | | Solid open arrow | `A-)B: Text` | Asynchronous message | Event emissions, fire-and-forget calls | | Dashed open arrow | `A--)B: Text` | Asynchronous return | Callback completions | | Solid line (no arrowhead) | `A-B: Text` | Flat connection | General association | | Dashed line (no arrowhead) | `A--B: Text` | Dashed flat connection | Weak or indirect association | Here is an example that uses both solid and dashed arrows to distinguish between requests and responses: ``` sequenceDiagram participant User participant Web as Web App participant Auth as Auth Service participant DB as User Store User->>Web: Login with credentials Web->>Auth: Validate credentials Auth->>DB: Lookup user record DB-->>Auth: User data Auth-->>Web: JWT token Web-->>User: Dashboard loaded ``` A common convention is to use `->>` for all outgoing requests and `-->>` for all responses. This creates a clear visual rhythm where solid lines go left-to-right (or top-to-bottom) and dashed lines come back. Your team should agree on a convention and apply it consistently across all sequence diagrams in your documentation. ## How do I add conditional logic (if/else) in Mermaid sequence diagrams?[​](#how-do-i-add-conditional-logic-ifelse-in-mermaid-sequence-diagrams "Direct link to How do I add conditional logic (if/else) in Mermaid sequence diagrams?") Real-world interactions are rarely linear. Conditional branches -- where the flow diverges based on a condition -- are modeled in Mermaid using `alt`/`else`/`end` blocks. Every `alt` block must be closed with an `end` keyword, and you can include one or more `else` sections for alternative paths. Here is a basic `alt`/`else` block: ``` sequenceDiagram participant User participant API as Payment API participant Bank as Bank Gateway User->>API: Process payment API->>Bank: Charge card alt Charge succeeds Bank-->>API: 200 OK, charge_id API-->>User: Payment confirmed else Charge declined Bank-->>API: 402 Declined API-->>User: Payment failed end ``` You can also nest `alt` blocks for multi-level conditional logic. For example, a payment flow might first check whether the card is valid, then check whether sufficient funds are available: ``` sequenceDiagram participant User participant API as Payment API participant Bank as Bank Gateway User->>API: Process payment API->>Bank: Validate and charge alt Card is valid Bank->>Bank: Check balance alt Sufficient funds Bank-->>API: Charge successful API-->>User: Payment confirmed else Insufficient funds Bank-->>API: Insufficient funds API-->>User: Payment declined - low balance end else Card declined Bank-->>API: Card rejected API-->>User: Invalid card details end ``` For optional steps that have no alternative -- meaning they may or may not happen -- use the `opt` block instead of `alt`: ``` sequenceDiagram participant Client participant API as API Client->>API: Place order API-->>Client: Order confirmed opt User is premium member API->>API: Apply discount API-->>Client: Discount applied end ``` A few things to watch for when working with conditional blocks: * Every `alt` must have exactly one matching `end`. Count them carefully before publishing. * You cannot use `else` outside of an `alt` block. * `opt` blocks do not take an `else` clause because they represent an optional step, not a branching choice. ## Can I add loops in Mermaid sequence diagrams?[​](#can-i-add-loops-in-mermaid-sequence-diagrams "Direct link to Can I add loops in Mermaid sequence diagrams?") Yes. Loops are one of the most useful constructs in sequence diagrams because they let you model retry logic, polling intervals, batch processing, and any other repeated interaction. Mermaid uses the `loop` keyword followed by a description and closed with `end`. Here is a basic loop that models a client polling a server for job status: ``` sequenceDiagram participant Client participant Server as Job Server Client->>Server: Submit job Server-->>Client: Job ID: 12345 loop Poll every 5 seconds Client->>Server: GET /jobs/12345 Server-->>Client: Status: processing end Client->>Server: GET /jobs/12345 Server-->>Client: Status: complete ``` The rendered diagram draws a labeled rectangle around the messages inside the loop block, making it visually distinct from the surrounding flow. The description text appears as a label in the top-left corner of the rectangle. Loops are frequently combined with `alt` blocks to model retry-with-fallback patterns: ``` sequenceDiagram participant Client participant Service as Downstream Service Client->>Service: Send request alt Service responds Service-->>Client: 200 OK else Service times out loop Retry up to 3 times Client->>Service: Retry request alt Success on retry Service-->>Client: 200 OK else Still failing Note right of Client: Wait 2s, then retry end end end ``` You can nest loops inside `alt` blocks and vice versa, but be careful with deeply nested structures. Each nesting level adds complexity and makes the diagram harder to read. If you find yourself going three or more levels deep, consider splitting the diagram into two separate diagrams and linking them with descriptive text. ## How do I add notes to a Mermaid sequence diagram?[​](#how-do-i-add-notes-to-a-mermaid-sequence-diagram "Direct link to How do I add notes to a Mermaid sequence diagram?") Notes let you annotate specific participants or spans of the diagram with contextual information that does not belong in the message flow itself. Mermaid supports three note placement options: * `Note left of A: Text` -- places a note to the left of participant A * `Note right of A: Text` -- places a note to the right of participant A * `Note over A,B: Text` -- places a note spanning from participant A to participant B Here is an example that uses all three: ``` sequenceDiagram participant Client participant API as API Gateway participant DB as Database Note left of Client: Mobile app user Client->>API: GET /products Note over Client,API: TLS 1.3 encrypted API->>DB: SELECT * FROM products DB-->>API: Result set API-->>Client: JSON response Note right of DB: Read replica ``` Notes are best used for annotations that help a reader understand the diagram without cluttering the message arrows. Good candidates for notes include: * Security annotations (encrypted connections, authentication method) * Infrastructure context (read replica, cache layer, load balancer) * Business rules that apply to a specific step * SLA or performance targets for a particular call * References to external documentation or runbooks Avoid using notes for information that belongs in the message labels themselves. If you find yourself writing a note that says "Client sends a login request," put that information in the arrow label instead: `Client->>API: POST /auth/login`. Notes should add information that is not already conveyed by the message flow. For multiline notes, Mermaid does not support explicit line breaks within a single `Note` statement in all versions. If you need a longer annotation, consider placing it in the surrounding Confluence text rather than inside the diagram. ## Why is my sequence diagram not rendering in Confluence?[​](#why-is-my-sequence-diagram-not-rendering-in-confluence "Direct link to Why is my sequence diagram not rendering in Confluence?") When a sequence diagram shows raw code instead of a rendered diagram, or when it renders partially and then stops, the cause is almost always a syntax error. Here are the most common issues and how to fix each one. **Missing `sequenceDiagram` keyword.** Every Mermaid sequence diagram must begin with the `sequenceDiagram` keyword on its own line. Without it, Mermaid does not know what type of diagram to render. ``` sequenceDiagram participant A as Alice participant B as Bob A->>B: Hello ``` **Unclosed `alt` or `loop` blocks.** Every `alt`, `opt`, `loop`, `par`, and `critical` block must have a matching `end`. If you open three blocks, you need three `end` statements. Missing `end` keywords are the single most common cause of failed renders. ``` %% INCORRECT -- missing end alt Condition A A->>B: Action else Condition B A->>B: Other action %% No end keyword! %% CORRECT alt Condition A A->>B: Action else Condition B A->>B: Other action end ``` **Special characters in labels not wrapped in quotes.** If a message label contains parentheses, brackets, or other special characters, wrap the label in double quotes: ``` %% INCORRECT A->>B: Send (urgent) message %% CORRECT A->>B: "Send (urgent) message" ``` **Missing colon before message text.** Every arrow must include a colon followed by the message text. Without the colon, Mermaid cannot parse the line: ``` %% INCORRECT A->>B Send data %% CORRECT A->>B: Send data ``` **The Mermaid macro is not installed or enabled.** If typing `/mermaid` in the Confluence editor does not show a macro option, the Mermaid Plus app may not be installed. Check **Confluence Administration > Apps** to verify the app is present and active. **The fastest way to debug.** Copy your Mermaid code and paste it into the [Mermaid Live Editor](https://mermaid.live). The Live Editor renders the diagram in real time and highlights the exact line where parsing fails. Fix the error in the Live Editor, then paste the corrected code back into Confluence. ## Sequence Diagram Syntax Quick Reference[​](#sequence-diagram-syntax-quick-reference "Direct link to Sequence Diagram Syntax Quick Reference") Keep this table handy when writing sequence diagrams in Confluence. It covers every commonly used syntax element. | Element | Syntax | Description | | --------------------- | ----------------------------- | -------------------------------------- | | Diagram type | `sequenceDiagram` | Required first line | | Participant | `participant A as Alice` | Declare a named participant with alias | | Actor | `actor User` | Stick-figure actor instead of box | | Solid message | `A->>B: Text` | Synchronous request or call | | Dashed message | `A-->>B: Text` | Response, return value, async reply | | Open arrow (solid) | `A-)B: Text` | Asynchronous message | | Open arrow (dashed) | `A--)B: Text` | Asynchronous return | | Note (left) | `Note left of A: Text` | Note to the left of a participant | | Note (right) | `Note right of A: Text` | Note to the right of a participant | | Note (spanning) | `Note over A,B: Text` | Note spanning multiple participants | | Conditional | `alt Cond ... else ... end` | If/else branching | | Optional | `opt Cond ... end` | Optional step, no else | | Loop | `loop Desc ... end` | Repeated interaction | | Parallel | `par ... and ... end` | Concurrent execution | | Critical | `critical ... option ... end` | Must-complete block with fallback | | Activate bar | `activate A` | Show active processing on participant | | Deactivate bar | `deactivate A` | Remove activation bar | | Shortcut activation | `A->>+B: Text` | Activate B automatically | | Shortcut deactivation | `A->>-B: Text` | Deactivate B automatically | | Auto-numbering | `autonumber` | Number messages sequentially | | Comment | `%% Text` | Inline comment, not rendered | | Delay | `...` | Visual delay/spacer in the timeline | | Background | `rect rgb(r,g,b) ... end` | Colored background for a section | ## Copy-Paste Sequence Diagram Examples[​](#copy-paste-sequence-diagram-examples "Direct link to Copy-Paste Sequence Diagram Examples") The following three examples are complete, ready to paste into a Mermaid Plus macro in Confluence. Modify the participants, messages, and labels to match your own architecture. ### Example 1: Authentication Flow with Token Refresh[​](#example-1-authentication-flow-with-token-refresh "Direct link to Example 1: Authentication Flow with Token Refresh") This diagram shows a full OAuth 2.0-style authentication flow including login, token issuance, resource access, and token refresh. It covers the happy path and the expired-token recovery path. ``` sequenceDiagram autonumber actor User participant FE as Frontend participant Auth as Auth Service participant Resource as Resource Server participant Cache as Token Store User->>FE: Enter email and password FE->>Auth: POST /auth/login {email, password} Auth->>Auth: Validate credentials alt Valid credentials Auth->>Cache: Store refresh token Auth-->>FE: 200 {access_token, refresh_token, expires_in} FE->>FE: Store tokens in memory FE-->>User: Redirect to dashboard Note over User,Resource: --- Subsequent API calls --- User->>FE: View profile FE->>Resource: GET /api/profile (Authorization: Bearer ) Resource->>Auth: Validate access token Auth-->>Resource: Token valid Resource-->>FE: 200 {user profile} FE-->>User: Display profile Note over User,Auth: --- Token expires after 1 hour --- User->>FE: View orders FE->>Resource: GET /api/orders (Authorization: Bearer ) Resource-->>FE: 401 Token expired FE->>Auth: POST /auth/refresh {refresh_token} Auth->>Cache: Verify refresh token Cache-->>Auth: Token valid Auth-->>FE: 200 {new_access_token} FE->>Resource: GET /api/orders (Authorization: Bearer ) Resource-->>FE: 200 {orders} FE-->>User: Display orders else Invalid credentials Auth-->>FE: 401 Unauthorized FE-->>User: Show error: Invalid email or password end ``` ### Example 2: Order Processing with Inventory and Payment[​](#example-2-order-processing-with-inventory-and-payment "Direct link to Example 2: Order Processing with Inventory and Payment") This diagram models an e-commerce order placement flow. It shows the synchronous calls to inventory and payment services, the event-driven notification, and the rollback path when payment fails. ``` sequenceDiagram autonumber participant Customer participant Web as Web App participant Order as Order Service participant Inv as Inventory Service participant Pay as Payment Service participant Bus as Event Bus participant Email as Email Service Customer->>Web: Place order Web->>Order: POST /orders {items, payment_method} activate Order Order->>Inv: POST /inventory/reserve {items} activate Inv alt Items in stock Inv-->>Order: 200 {reservation_id} deactivate Inv Order->>Pay: POST /payments/charge {amount, method} activate Pay alt Payment succeeds Pay-->>Order: 200 {charge_id} deactivate Pay Order->>Order: Create order record Order->>Bus: Publish order.created event Bus-->>Email: Deliver event Email->>Email: Send confirmation email Order-->>Web: 201 {order_id, status: confirmed} Web-->>Customer: Order confirmation page else Payment fails Pay-->>Order: 402 Payment declined deactivate Pay Order->>Inv: POST /inventory/release {reservation_id} Inv-->>Order: 200 Released Order-->>Web: 402 {error: payment_declined} Web-->>Customer: Payment failed, try again end else Items out of stock Inv-->>Order: 409 {error: insufficient_stock} deactivate Inv Order-->>Web: 409 Out of stock Web-->>Customer: Items unavailable end deactivate Order ``` ### Example 3: Error Handling with Retry and Circuit Breaker[​](#example-3-error-handling-with-retry-and-circuit-breaker "Direct link to Example 3: Error Handling with Retry and Circuit Breaker") This diagram illustrates a resilient client calling a downstream service through retry middleware and a circuit breaker. It covers the healthy path, the retry path, and the circuit-open fallback. ``` sequenceDiagram autonumber participant App as Application participant Retry as Retry Middleware participant CB as Circuit Breaker participant Svc as Downstream Service participant Fallback as Fallback Service App->>Retry: Send request Retry->>CB: Forward request alt Circuit is closed (healthy) CB->>Svc: Proxy request alt Service responds successfully Svc-->>CB: 200 OK CB->>CB: Record success CB-->>Retry: 200 OK Retry-->>App: Success response else Service returns 5xx Svc-->>CB: 503 Unavailable CB->>CB: Record failure loop Retry up to 3 times with exponential backoff Retry->>CB: Retry request CB->>Svc: Proxy request alt Retry succeeds Svc-->>CB: 200 OK CB-->>Retry: 200 OK else Retry fails Svc-->>CB: 503 Unavailable CB->>CB: Increment failure count end end alt At least one retry succeeded CB-->>Retry: 200 OK Retry-->>App: Success response else All retries exhausted CB->>CB: Open circuit CB->>Fallback: Request fallback response Fallback-->>CB: Cached or default data CB-->>Retry: Degraded response Retry-->>App: 200 with fallback data Note right of CB: Circuit stays open for 30s end end else Circuit is open (tripped) CB->>Fallback: Serve from cache Fallback-->>CB: Stale data CB-->>Retry: Degraded response Retry-->>App: 200 with cached data Note over CB: After 30s timeout, circuit goes to half-open end ``` ## Tips for Readable Sequence Diagrams[​](#tips-for-readable-sequence-diagrams "Direct link to Tips for Readable Sequence Diagrams") A sequence diagram is only useful if your team can read and understand it at a glance. These tips help you produce diagrams that communicate clearly. **Limit participants to five or six.** Each additional participant reduces the horizontal space available for message labels. If your architecture involves more than six actors, split the interaction into multiple diagrams. For example, diagram the client-to-gateway interaction separately from the gateway-to-backend interaction. **Use the `as` keyword for short aliases.** Write `participant AuthSvc as Authentication Service` in your code. This keeps the Mermaid source readable while displaying the full name in the rendered diagram. Short aliases also reduce the chance of typos when writing arrow statements. **Auto-number your messages.** Add `autonumber` on the line immediately after `sequenceDiagram`. Numbered messages give your team a shared vocabulary for discussing specific steps ("the issue is at step 4 where the API gateway times out"). **Be consistent with arrow conventions.** Agree with your team that solid arrows (`->>`) always represent requests and dashed arrows (`-->>`) always represent responses. Consistent visual language reduces the cognitive load of reading the diagram. **Add notes for non-obvious context.** Use `Note over A,B: Text` for cross-cutting concerns like encryption, rate limiting, or SLA boundaries. Place notes only where they add information that is not already in the message labels. **Split large diagrams by phase.** If a single diagram would exceed 20 to 25 messages, break it into phases. For example, split an order flow into "Order Placement," "Payment Processing," and "Fulfillment" diagrams. Link them with a brief prose description on the Confluence page. **Use `activate` and `deactivate` sparingly.** Activation bars show when a participant is actively processing a request. They add visual clarity to simple diagrams but create clutter in complex ones. Use them for the most important service interactions and omit them for trivial pass-through calls. **Test in the Mermaid Live Editor first.** Before pasting code into Confluence, validate it at [mermaid.live](https://mermaid.live). The Live Editor shows rendering errors in real time, which is faster than saving, publishing, and reloading a Confluence page to check each change. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Mermaid Plus Diagrams & AI Agent for Confluence](/apps/mermaid-plus-for-confluence.md) -- complete usage guide with configuration, themes, and all 30 supported diagram types * [How to Create Sequence Diagrams in Confluence](/blog/how-to-create-sequence-diagrams-confluence.md) -- step-by-step tutorial for building sequence diagrams from scratch * [Mermaid Syntax Cheat Sheet](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md) -- quick reference for all Mermaid diagram types supported in Confluence * [Mermaid Troubleshooting FAQ](/blog/faq-mermaid-troubleshooting.md) -- solutions for rendering issues, syntax errors, and performance problems * [Create Mermaid Diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md) -- broader guide covering flowcharts, class diagrams, Gantt charts, and more Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [mermaid](/blog/tags/mermaid.md) * [confluence](/blog/tags/confluence.md) * [sequence-diagram](/blog/tags/sequence-diagram.md) * [diagrams](/blog/tags/diagrams.md) --- # Confluence Page Navigation FAQ: TOC, Numbered Headings & Structure May 2, 2026 · 15 min read [NGPilot](https://ngpilot.com) Page navigation is one of those things that nobody notices when it works well and everyone complains about when it does not. In Confluence, where pages routinely grow to thousands of words — technical specifications, onboarding guides, compliance documentation, project charters — helping readers find the right section quickly is not a nice-to-have. It is the difference between a knowledge base that people use and one that people ignore. Confluence provides some building blocks for navigation: headings, a basic table of contents macro, anchor links, and an expand macro for collapsible content. These are functional, but they leave significant gaps. There is no automatic heading numbering. There is no way to create professional accordion-style FAQ sections without manual formatting. There is no structured system that ties together a table of contents, numbered headings, and collapsible sections into a cohesive reading experience. This FAQ answers the most common questions about improving page navigation in Confluence. We cover how to add and configure tables of contents, how auto-numbered headings work, how to create collapsible sections, how anchor links function, and how to combine these techniques for long pages. Along the way, we reference two NGPILOT apps — **Modern Numbered Headings for Confluence** and **Modern FAQ for Confluence** — that fill the gaps left by Confluence's built-in tools. ## How do I add a table of contents to a Confluence page?[​](#how-do-i-add-a-table-of-contents-to-a-confluence-page "Direct link to How do I add a table of contents to a Confluence page?") Confluence includes a built-in TOC macro that generates a table of contents from the headings on your page. To insert it, open the page editor and type `/toc` to bring up the macro. Once added, it scans your page for headings (H1 through H6) and renders them as a clickable list. Readers can click any entry to jump directly to that section. The built-in TOC macro supports basic configuration. You can set the minimum and maximum heading levels to include, choose between flat and hierarchical display, and control whether the TOC entries are numbered or plain. These options cover simple use cases, but they have limitations: * **No automatic heading numbering.** The TOC can display numbers, but those numbers are generated by the macro itself and do not appear in the actual page headings. If you want numbered headings that appear both in the TOC and in the page body, you need a separate solution. * **Limited formatting control.** You cannot change the font, colors, or indentation style beyond the basic options. Teams that want a branded or polished look will find the defaults constraining. * **Manual updates.** If you restructure your page significantly, the TOC usually updates on page refresh, but complex nested structures can sometimes display incorrectly until the page is re-published. For teams that want numbered headings inside the TOC, **Modern Numbered Headings for Confluence** integrates directly with the TOC macro. Instead of typing numbers into your headings manually, the app generates them automatically based on your chosen scheme. When you insert a TOC macro on a page that uses Modern Numbered Headings, the TOC entries display with the same numbering that appears in the page body — creating a consistent, professional navigation experience. The workflow is straightforward: install the app, click the app icon in the page byline to configure your numbering scheme, insert the TOC macro at the top of your page, and publish. The TOC picks up the numbered headings automatically, and every structural change you make to the page updates the numbers without any manual intervention. ## Can I auto-number headings in Confluence?[​](#can-i-auto-number-headings-in-confluence "Direct link to Can I auto-number headings in Confluence?") Confluence does not number headings natively. You can add numbers manually by typing them into the heading text — for example, typing "1.1 System Requirements" as an H2 heading — but this approach breaks the moment you insert, delete, or reorder sections. Every edit becomes a renumbering exercise, and on long documents, that exercise can consume significant time. **Modern Numbered Headings for Confluence** automates this entirely. After installing the app from the Atlassian Marketplace, a clipboard icon appears in the page byline on every Confluence page. Clicking it opens a configuration modal where you select your preferred numbering scheme and heading levels. The app offers five numbering styles: 1. **Decimal** (1, 1.1, 1.1.1) — the most widely used format for technical documentation, project plans, and general business documents. It communicates hierarchy depth at a glance. 2. **Roman numerals** (I, I.I, I.II) — suited for formal documents, academic papers, executive summaries, and any context where a traditional appearance is preferred. 3. **Alphabetic** (A, A.A, A.B) — commonly used for structured procedures, checklists, and process documentation where letters differentiate major sections. 4. **Outline** (1), 1.1), 1.1.1)) — a format frequently seen in business reports and legal documents where the closing parenthesis style is the standard convention. 5. **Mixed** (1, A, i, a) — designed for complex hierarchies with many nesting levels, where alternating between number and letter formats at each level improves readability. All five styles support the full range of heading levels from H1 through H6. A live preview in the configuration modal shows exactly how your page will look with each scheme, so you can compare options before committing. Once you apply a scheme, the numbers appear on the published page automatically. Adding a new section between 2.1 and 2.2 shifts the numbering for 2.2, 2.3, and so on — without any manual work. The numbers also appear in the built-in TOC macro and in anchor links. This consistency is what makes automatic numbering valuable: references like "see section 3.2.1" remain accurate even as the document evolves. ## How do I create collapsible sections in Confluence?[​](#how-do-i-create-collapsible-sections-in-confluence "Direct link to How do I create collapsible sections in Confluence?") Confluence provides a built-in expand macro that creates a single collapsible section. Type `/expand` in the editor, give the section a title, and add content inside. When readers view the page, the section appears collapsed with only the title visible. Clicking the title expands the section to reveal the content underneath. The expand macro works for individual collapsible sections, but it has clear limitations when you need multiple collapsible items on a page: * **No accordion behavior.** Expanding one section does not collapse the others. On pages with many expand macros, readers end up with a long, fully expanded page that defeats the purpose of collapsible content. * **No bulk management.** Each expand macro is independent. There is no way to reorder them with drag and drop, apply a consistent theme, or manage them as a group. * **Inconsistent appearance.** Because each expand macro is manually configured, the visual style can vary across pages and authors. **Modern FAQ for Confluence** addresses these limitations with a dedicated macro designed for FAQ sections and collapsible content groups. The app provides two display themes: * **Accordion theme** — clicking one question expands its answer and collapses any previously expanded answer. This keeps the page compact and focused, which is ideal for FAQ pages where readers typically look for one specific answer. * **Centered theme** — all answers are visible on the page in a structured, formatted layout. This works well for pages where readers benefit from scanning all the content at once. The app also includes drag-and-drop reordering in the editor. You can add questions, rearrange them by dragging, and delete individual items without touching the surrounding content. Each answer supports full Confluence rich text formatting, including links, images, tables, and code blocks. To use Modern FAQ for Confluence, type `/Modern FAQ for Confluence` in the editor. Select your preferred theme by clicking the theme image in the configuration panel. Add your questions and answers one by one, using the plus button to add new items and the minus button to remove the last one. Click OK to apply. After insertion, you can drag and drop items to reorder them on the published page. ## Can I link to specific sections of a Confluence page?[​](#can-i-link-to-specific-sections-of-a-confluence-page "Direct link to Can I link to specific sections of a Confluence page?") Yes, and this is one of the most underused navigation features in Confluence. Every heading on a Confluence page automatically receives an anchor — a fragment identifier that you can use in URLs to link directly to that heading's position on the page. To get the anchor link for a heading, navigate to the published page and hover over the heading. A small link icon appears to the left of the heading text. Clicking this icon updates your browser's address bar with the full URL including the anchor fragment. Copy this URL and share it in Slack, email, Jira tickets, or other Confluence pages. When someone clicks the link, they land on the page scrolled directly to that heading. You can also construct anchor links manually. Confluence generates anchors from the heading text by converting to lowercase, replacing spaces with hyphens, and removing special characters. For example, a heading "System Requirements" gets the anchor `#SystemRequirements`. The full URL would look like `https://your-domain.atlassian.net/wiki/spaces/TEAM/pages/12345#SystemRequirements`. When you use **Modern Numbered Headings for Confluence**, the anchor links incorporate the numbering, making them more descriptive and stable. A link to section 2.1 reads as `#2.1SystemRequirements` rather than just `#SystemRequirements`. This is especially useful in technical documentation where section numbers are the primary way people reference content. When a colleague asks "can you send me the link to section 3.2.1?", the anchor link directly reflects that numbering. For pages that use Modern FAQ for Confluence, each FAQ item also has a distinct position on the page. While FAQ items are not standard headings and do not generate anchors in the same way, the collapsible sections keep content organized so readers can scan question titles quickly without needing to jump to specific FAQ entries via URL. ## How do I improve navigation for long Confluence pages?[​](#how-do-i-improve-navigation-for-long-confluence-pages "Direct link to How do I improve navigation for long Confluence pages?") Long pages are where navigation matters most — and where Confluence's built-in tools fall short on their own. A 4,000-word technical specification with 30 headings, multiple tables, and embedded diagrams can overwhelm readers if there is no structured way to navigate through it. The key is to combine multiple navigation techniques into a layered approach. **Add a table of contents at the top.** This is the most fundamental step. Insert the built-in TOC macro at the very beginning of the page, before any content. Configure it to display all heading levels used on the page. Readers arriving at the page can immediately see the full structure and jump to any section. **Use numbered headings for structured references.** Install Modern Numbered Headings for Confluence and apply a decimal numbering scheme. This gives every section a unique identifier. The numbered headings appear in the TOC, in the page body, and in anchor links. When someone references "section 4.2.3" in a meeting or a Jira comment, there is zero ambiguity about what they mean. **Break very long pages into child pages.** If a page exceeds roughly 5,000 words, consider splitting it into child pages under a parent overview. The parent page contains a summary, the table of contents linking to child pages, and links to each section. This approach works well for multi-chapter documentation, API references, and comprehensive process guides. Confluence's page tree navigation in the sidebar then becomes an additional navigation layer. **Use collapsible sections for optional content.** Not every reader needs every section. Appendices, troubleshooting guides, and advanced configuration details can be wrapped in collapsible sections so they do not clutter the main reading flow. For FAQ-style content, Modern FAQ for Confluence provides accordion behavior that keeps the page compact. **Add a "back to top" convention.** While Confluence does not have a built-in back-to-top button, you can place a text link at the end of each major section that links back to the top of the page using an anchor. This small addition significantly improves the experience for readers who are scanning through a long document section by section. ## What is the best numbering format for technical documentation?[​](#what-is-the-best-numbering-format-for-technical-documentation "Direct link to What is the best numbering format for technical documentation?") The short answer is decimal numbering: 1, 1.1, 1.1.1. This is the dominant format in technical documentation across software, engineering, manufacturing, and healthcare. It is used in ISO standards, RFC documents, military specifications, and the vast majority of technical writing style guides. Decimal numbering works so well because it encodes hierarchy depth directly into the section number. When you see "3.4.2," you immediately know three things: this is in chapter 3, it is the fourth major subsection of chapter 3, and it is the second item within that subsection. No other numbering format communicates this information as efficiently. That said, different documentation contexts have different conventions, and Modern Numbered Headings supports all of them: * **Decimal (1, 1.1, 1.1.1)** for technical documentation, software specifications, user guides, and API docs. This is the default and most versatile choice. * **Roman numerals (I, I.I, I.II)** for executive summaries, board papers, academic publications, and any formal context where roman numerals are the expected convention. * **Alphabetic (A, A.A, A.B)** for procedural checklists, training materials, and process documentation where sections represent distinct phases or stages. * **Outline (1), 1.1), 1.1.1))** for legal documents, compliance reports, and business proposals where the outline format is the industry standard. * **Mixed (1, A, i, a)** for highly detailed specifications with four or more nesting levels, where alternating between numbers, letters, and roman numerals at each level prevents confusion between adjacent levels. If you are unsure which format to choose, start with decimal. You can always switch later by clicking the app icon in the page byline and selecting a different scheme. The live preview shows the result before you commit, so there is no risk of choosing the wrong format and needing to undo formatting changes manually. ## Page structure best practices[​](#page-structure-best-practices "Direct link to Page structure best practices") Good page navigation starts with good page structure. No amount of tooling can fix a document where headings are used inconsistently, sections are organized illogically, or the hierarchy is too deep to follow. These five practices form the foundation for navigable Confluence pages. **1. Use a consistent heading hierarchy.** Every page should follow a clear hierarchy: H1 for the page title, H2 for major sections, H3 for subsections, and so on. Never skip levels — jumping from H1 directly to H3 confuses both readers and assistive technology. If your H1 is "Deployment Guide," your H2s should be "Prerequisites," "Installation Steps," and "Troubleshooting," not random text styled as headings. **2. Keep nesting to three levels.** Most documents work well with H1, H2, and H3. If you find yourself adding H4 and H5 headings regularly, the page is probably too complex for a single Confluence page. Consider splitting it into child pages or consolidating some subsections into their parent sections. Three levels of nesting is readable; six levels is not. **3. Write descriptive heading text.** Headings serve as navigation signposts. "Configuration" tells the reader something. "Configuring Database Connections for High Availability" tells them exactly what to expect. Descriptive headings make the TOC more useful and anchor links more meaningful when shared in conversations. **4. Place the TOC before the main content.** Readers expect to find the table of contents at the top of the page. Placing it after an introduction or in the middle of the content means readers have to scroll past content they may not need to find the navigation tool that helps them skip to the content they do need. **5. Review and update structure when content changes.** Pages are living documents. When you add a new section, remove an outdated one, or reorganize the flow, take 30 seconds to check the heading hierarchy and TOC. With Modern Numbered Headings, the numbering updates automatically — but you still need to verify that the overall structure makes sense for the updated content. ## NGPILOT apps for better page structure[​](#ngpilot-apps-for-better-page-structure "Direct link to NGPILOT apps for better page structure") | App | What it does | Key features | | --------------------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | Modern Numbered Headings for Confluence | Automatically numbers headings on Confluence pages | 5 numbering schemes (decimal, roman, alphabetic, outline, mixed), live preview, heading level filtering, TOC macro integration, one-click insert and remove | | Modern FAQ for Confluence | Creates professional FAQ sections with collapsible content | Accordion and centered display themes, drag-and-drop reordering, rich text answers with images and links, consistent formatting across pages | These two apps address the two most common navigation gaps in Confluence. Modern Numbered Headings gives your pages a structured, numbered hierarchy that makes the TOC useful and cross-references unambiguous. Modern FAQ gives you a clean way to organize question-and-answer content without manual formatting or expand macro stacking. Both apps install from the Atlassian Marketplace in under a minute and work immediately with no per-space configuration. They are designed to complement Confluence's built-in tools rather than replace them — the TOC macro, anchor links, and page tree navigation all continue to work as expected. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Modern Numbered Headings for Confluence](/apps/modern-numbered-headings-for-confluence.md) -- Full user guide covering installation, numbering styles, heading level filtering, and TOC integration * [Modern FAQ for Confluence](/apps/modern-faq-for-confluence.md) -- Usage documentation for building FAQ sections with accordion behavior and drag-and-drop management * [How to Set Up Numbered Headings](/blog/how-to-use-numbered-headings-confluence.md) -- Step-by-step tutorial for configuring automatic heading numbering in Confluence * [How to Build FAQ Sections](/blog/how-to-build-faq-sections-confluence.md) -- Complete guide to creating professional FAQ pages with templates and best practices * [Numbered Headings Comparison](/blog/confluence-numbered-headings-comparison.md) -- Comparison of numbered headings apps for Confluence, including features, pricing, and use cases Try Modern FAQ for Confluence Accordion-style FAQ sections with drag-and-drop reordering and two themes — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236739/modern-faq-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-faq-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [confluence](/blog/tags/confluence.md) * [navigation](/blog/tags/navigation.md) * [toc](/blog/tags/toc.md) * [numbered-headings](/blog/tags/numbered-headings.md) --- # Confluence Whiteboard Apps FAQ: Excalidraw, draw\.io & Built-in Compared May 2, 2026 · 13 min read [NGPilot](https://ngpilot.com) Confluence has become the central hub where engineering teams write technical specs, document architecture decisions, and collaborate on project plans. But text alone is often not enough. When you need to sketch a system architecture, map out a user flow, brainstorm a retro board, or draw a quick wireframe, you need a whiteboard or drawing tool embedded directly in your Confluence pages. Switching between Confluence and an external app breaks your flow, scatters artifacts across tools, and makes it harder for teammates to find and update visual content later. There are three main options for adding whiteboard and drawing capabilities to Confluence: the **built-in Confluence whiteboard** that Atlassian provides natively, **Excalidraw Plus for Confluence** with its freeform hand-drawn style and extensive shape libraries, and **draw\.io** (now rebranded as Diagrams.net) for formal structured diagrams. Each tool serves a different purpose, and many teams end up using more than one depending on the situation. This FAQ answers the questions teams ask most often when evaluating Confluence whiteboard and drawing apps, provides a detailed feature comparison, and offers a practical decision guide so you can pick the right tool for each scenario. *** ## Does Confluence have a built-in whiteboard?[​](#does-confluence-have-a-built-in-whiteboard "Direct link to Does Confluence have a built-in whiteboard?") Yes, Confluence Cloud ships with a native whiteboard feature. You can create a whiteboard from the page insert menu and use basic drawing tools -- rectangles, circles, lines, arrows, and text -- on a freeform canvas. It is convenient because it requires no installation and is immediately available to every Confluence user. However, the built-in whiteboard has meaningful limitations for engineering teams that rely on diagrams as part of their daily workflow. The shape library is small, covering only basic geometric primitives. There is no support for specialized stencils like AWS architecture icons, Azure service symbols, UML notation, or network topology shapes. You cannot generate diagrams from Mermaid syntax. Export options are limited, and there is no way to save a diagram as a reusable template that other team members can start from. For casual sketching -- a quick arrow-and-box diagram during a meeting, or a simple flow to illustrate a point in a meeting note -- the built-in whiteboard works fine. But for teams that create architecture diagrams, system flows, wireframes, or any structured visual documentation on a regular basis, the built-in whiteboard runs out of capability quickly. That is where dedicated drawing apps like Excalidraw Plus and draw\.io come in. *** ## What is the best drawing app for Confluence?[​](#what-is-the-best-drawing-app-for-confluence "Direct link to What is the best drawing app for Confluence?") There is no single best answer because the right choice depends on what kind of visual content your team produces. Here is how the main options break down by use case: **Excalidraw Plus for Confluence** is the best choice for teams that value freeform sketching, brainstorming, and a hand-drawn visual style. The sketch-like aesthetic makes diagrams feel approachable and encourages participation -- people are less intimidated by a hand-drawn wireframe than by a pixel-perfect mockup. Excalidraw Plus includes 220+ shape libraries covering major cloud providers (AWS, Azure, GCP), UML, network diagrams, and more. It provides a full visual editor with freeform drawing tools, shape libraries, export to PNG/SVG/JSON, and auto-save. **draw\.io** (Diagrams.net) by Seibert Media is the best choice for formal, structured diagrams. If your team produces UML class diagrams, BPMN process models, entity-relationship diagrams, or detailed network topologies where precision and standard notation matter, draw\.io provides the most comprehensive set of tools. It has the largest install base on the Atlassian Marketplace and supports Cloud, Data Center, and Server deployments. **Mermaid Plus Diagrams & AI Agent for Confluence** is ideal for teams that prefer text-based diagram creation. Developers write Mermaid syntax in a code block and the app renders a diagram automatically. This approach is fast, version-controllable, and works well for flowcharts, sequence diagrams, and architecture documentation. In practice, many teams use a combination. Excalidraw Plus for brainstorming and early-stage ideation, Mermaid Plus for structured code-driven diagrams, and occasionally draw\.io for formal specifications that require precise notation. *** ## Can I use Excalidraw in Confluence for free?[​](#can-i-use-excalidraw-in-confluence-for-free "Direct link to Can I use Excalidraw in Confluence for free?") The open-source Excalidraw editor at excalidraw\.com is completely free to use. You can create diagrams in the browser, export them as PNG, SVG, or JSON, and paste the exported image into a Confluence page. However, this approach has significant drawbacks: diagrams are not embedded in the page, they cannot be edited in place, and there is no integration with Confluence permissions, search, or attachments. **Excalidraw Plus for Confluence** is a paid marketplace app that integrates the Excalidraw editor directly into Confluence pages. It offers a **free trial** on the Atlassian Marketplace so your team can evaluate the full feature set before committing. During the trial period you get access to all features including the 220+ shape libraries, export to PNG/SVG/JSON, auto-save, grid alignment, and template management. After the trial, a paid license is required. The license is per-user and follows Atlassian's standard marketplace pricing model. For teams that create diagrams regularly, the productivity gains from having the editor embedded directly in Confluence -- no context switching, no manual image uploads, no version mismatches between external files and page content -- typically justify the cost within the first month. *** ## How do Excalidraw diagrams compare to Confluence's native whiteboard?[​](#how-do-excalidraw-diagrams-compare-to-confluences-native-whiteboard "Direct link to How do Excalidraw diagrams compare to Confluence's native whiteboard?") Excalidraw Plus for Confluence offers a significantly richer feature set than Confluence's built-in whiteboard. Here are the key differences: **Shape libraries.** The native whiteboard provides basic shapes only. Excalidraw Plus includes 220+ shape packs from the Excalidraw community library, covering AWS, Azure, GCP, UML, network topology, office layout, user interface components, and many more categories. These pre-built stencils save hours of manual drawing and ensure that your diagrams use standard, recognizable symbols. **Mermaid syntax generation.** Excalidraw Diagrams plus Whiteboards for Jira supports generating diagrams from Mermaid syntax. You type a flowchart, sequence diagram, or class diagram in Mermaid format, and the Jira app renders it as an Excalidraw canvas that you can then customize with the drawing tools. The Confluence version of Excalidraw Plus does not include built-in Mermaid support. For Mermaid diagrams in Confluence, use Mermaid Plus Diagrams & AI Agent for Confluence. The native whiteboard has no equivalent capability. **Export options.** Excalidraw Plus exports to PNG for image embedding, SVG for scalable vector graphics, and JSON for full diagram backup and re-import. The native whiteboard has more limited export capabilities. **Auto-save and version tracking.** Excalidraw Plus auto-saves your work as you draw, storing the diagram as a JSON attachment on the Confluence page. This means your diagrams benefit from Confluence's built-in version history for attachments. You can roll back to a previous version of a diagram the same way you would roll back any other attachment. **Grid alignment and snapping.** Excalidraw Plus includes configurable grid alignment and element snapping, which helps keep diagrams clean and organized. The native whiteboard has basic alignment tools but lacks the precision snapping that Excalidraw provides. **Template reuse.** Excalidraw Plus lets you save diagrams as reusable templates, so your team can standardize on shared visual patterns. The native whiteboard does not support templates. *** ## Can I convert Excalidraw diagrams to other formats?[​](#can-i-convert-excalidraw-diagrams-to-other-formats "Direct link to Can I convert Excalidraw diagrams to other formats?") Yes. Excalidraw Plus for Confluence supports three export formats, each suited to a different purpose: * **PNG** -- Raster image format. Best for embedding diagrams in emails, Slack messages, presentations, or any context where a flat image is sufficient. PNG exports capture the current viewport, so adjust your zoom and framing before exporting to get the desired output. * **SVG** -- Scalable vector graphics. Ideal when you need resolution-independent output that looks sharp at any size. SVG files can be opened and edited in vector graphics tools like Adobe Illustrator or Inkscape, making this format useful for design teams that want to refine Excalidraw sketches into polished visuals. * **JSON** -- The full diagram source data. This is the most complete export because it preserves every element, style, position, and text property. Use JSON for backups, migration between Confluence instances, or importing into the open-source Excalidraw editor at excalidraw\.com. JSON files can be version-controlled in Git, which is useful for teams that manage architecture diagrams alongside code. All diagrams are stored as JSON attachments on the Confluence page, so you always have access to the raw data through Confluence's attachment management. This means your diagrams are included in space exports, site backups, and migrations automatically. *** ## Is there a Jira version of Excalidraw?[​](#is-there-a-jira-version-of-excalidraw "Direct link to Is there a Jira version of Excalidraw?") Yes. **Excalidraw Diagrams plus Whiteboards for Jira** adds a diagram editor to every Jira issue. It uses the same Excalidraw editor core as the Confluence version but is designed to fit the Jira workflow. Diagrams appear in a dedicated panel on the issue view, so developers and project managers can create and edit visuals without leaving the issue. The Jira version includes **229 bundled shape libraries** -- even more than the Confluence version -- covering AWS, Azure, GCP, UML, network topology, and other specialized categories. It also includes a **Mermaid syntax generator** that lets developers define diagrams in text-based Mermaid format and render them as Excalidraw visuals within the Jira issue. Diagrams are saved as JSON attachments on the Jira issue, the same pattern used by the Confluence app. This means they travel with the issue through exports, backups, and project migrations. For teams that use both Confluence and Jira, having Excalidraw in both tools creates a consistent diagramming experience across your entire Atlassian stack. *** ## Comparison: Excalidraw Plus vs draw\.io vs Confluence Built-in Whiteboard[​](#comparison-excalidraw-plus-vs-drawio-vs-confluence-built-in-whiteboard "Direct link to Comparison: Excalidraw Plus vs draw.io vs Confluence Built-in Whiteboard") The following table compares the three main whiteboard and drawing options for Confluence across ten key dimensions: | Feature | Excalidraw Plus for Confluence | draw\.io (Diagrams.net) | Confluence Built-in Whiteboard | | ------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------- | ------------------------------ | | **Visual style** | Hand-drawn, sketch-like | Formal, precise, corporate | Basic geometric shapes | | **Shape libraries** | 220+ packs (AWS, Azure, GCP, UML, network, UI) | Extensive stencil sets (UML, BPMN, flowchart, network, floorplan) | Limited to basic shapes | | **Mermaid support** | No (Mermaid available in Jira version) | No native Mermaid support | No | | **Export formats** | PNG, SVG, JSON | PNG, SVG, PDF, XML, VSDX | Limited (image copy) | | **Diagram storage** | JSON attachment on Confluence page | Embedded macro content + attachments | Embedded in page | | **Template reuse** | Yes -- save and share templates | Yes -- template library | No | | **Real-time collaboration** | Multi-user editing on shared canvas | Multi-user editing with cursors | Basic multi-user support | | **Auto-save** | Yes | Yes | Yes | | **Grid alignment and snapping** | Configurable grid with element snapping | Advanced alignment and distribution tools | Basic alignment | | **Pricing model** | Per-user license with free trial | Free tier available; paid for advanced features | Included with Confluence Cloud | Each tool has clear strengths. Excalidraw Plus excels at freeform creativity with a low barrier to entry. draw\.io offers the most precision and the deepest feature set for formal diagram types. The built-in whiteboard is fine for quick, informal sketches that do not need to be preserved or reused. *** ## When to use each tool -- a decision guide[​](#when-to-use-each-tool----a-decision-guide "Direct link to When to use each tool -- a decision guide") Choosing the right drawing tool for each situation saves time and produces better results. Here is a practical guide based on common scenarios teams encounter: ### Use Excalidraw Plus for Confluence when:[​](#use-excalidraw-plus-for-confluence-when "Direct link to Use Excalidraw Plus for Confluence when:") * **You are brainstorming or ideating.** The hand-drawn style encourages participation and makes it clear that ideas are preliminary. Sprint retrospectives, architecture brainstorming sessions, and early-stage wireframing are all great fits. * **You need cloud architecture stencils.** The 220+ shape libraries include AWS, Azure, and GCP icons, so you can drag official cloud service symbols onto the canvas instead of drawing them from scratch. * **You want to generate diagrams from text.** Excalidraw Diagrams plus Whiteboards for Jira includes a Mermaid syntax generator that lets developers write a flowchart or sequence diagram in code and render it as an editable Excalidraw canvas. * **You are creating diagrams that will evolve.** Because Excalidraw diagrams are saved as JSON attachments with auto-save, they work well as living documents that the team updates iteratively over time. ### Use draw\.io when:[​](#use-drawio-when "Direct link to Use draw.io when:") * **You need formal UML or BPMN diagrams.** draw\.io has the most complete set of UML stencils (class, use case, activity, state, sequence, component, deployment) and BPMN notation elements. * **Precision matters more than speed.** For network topology diagrams, database schema visualizations, and technical specifications that require exact positioning and standard notation, draw\.io provides the necessary control. * **You need to import Visio files.** draw\.io can import and export VSDX format, making it the right choice for teams transitioning from Microsoft Visio. * **You are on Data Center or Server.** draw\.io supports all three Atlassian hosting models (Cloud, Data Center, Server), while Excalidraw Plus is focused on Confluence Cloud. ### Use Mermaid Plus Diagrams & AI Agent for Confluence when:[​](#use-mermaid-plus-diagrams--ai-agent-for-confluence-when "Direct link to Use Mermaid Plus Diagrams & AI Agent for Confluence when:") * **Your team prefers text-based workflows.** Developers who think in code can write Mermaid syntax and get a rendered diagram without touching a drawing tool. * **You want diagrams in version control.** Mermaid diagrams are plain text, so they can be stored in Git alongside documentation and code. * **You need consistent, reproducible diagrams.** Text-based diagrams look the same every time they are rendered, which is valuable for documentation that must maintain a uniform appearance. ### Use the built-in whiteboard when:[​](#use-the-built-in-whiteboard-when "Direct link to Use the built-in whiteboard when:") * **You just need a quick sketch.** If you are in a meeting and want to draw three boxes and two arrows to illustrate a point, the built-in whiteboard is the fastest option because it requires no setup or installation. * **Your diagram is disposable.** For throwaway sketches that will not be reused, referenced later, or shared outside the meeting, the built-in whiteboard is sufficient. * **You cannot install marketplace apps.** If your organization restricts third-party app installations, the native whiteboard is your only option. *** ## Can I use multiple drawing tools together?[​](#can-i-use-multiple-drawing-tools-together "Direct link to Can I use multiple drawing tools together?") Absolutely. In fact, most productive teams use a combination of tools depending on the phase of their work and the type of diagram they need. A common pattern is: 1. **Early ideation:** Use Excalidraw Plus for freeform brainstorming sessions where the goal is to explore ideas quickly. The hand-drawn style keeps the conversation focused on concepts rather than visual polish. 2. **Refinement and documentation:** As ideas solidify, either refine the Excalidraw diagram with structured shape libraries and grid alignment, or transition to Mermaid Plus for text-based diagrams that can be version-controlled alongside your documentation. 3. **Formal specifications:** For diagrams that need to follow strict notation standards (UML, BPMN, ArchiMate), use draw\.io to produce publication-quality visuals. All three tools store their output on the Confluence page, so readers get a consistent experience regardless of which tool produced the diagram. The key is to match the tool to the task rather than trying to force a single app to cover every scenario. *** ## Related resources[​](#related-resources "Direct link to Related resources") * [Excalidraw Plus for Confluence](/apps/excalidraw-plus-for-confluence.md) -- setup guide and usage documentation * [Excalidraw for Confluence & Jira: FAQ](/blog/faq-excalidraw-best-practices.md) -- common questions about Excalidraw in Atlassian tools * [Confluence diagram tools compared](/blog/confluence-diagram-tools-comparison.md) -- detailed comparison of all diagram apps for Confluence * [How to create flowcharts in Confluence](/blog/create-flowcharts-confluence.md) -- step-by-step guide to building flowcharts * [Excalidraw vs draw.io FAQ](/blog/faq-excalidraw-vs-drawio-confluence.md) -- head-to-head comparison of the two most popular drawing apps Try Excalidraw Plus Whiteboards & AI Agent for Confluence Freeform whiteboards with 220+ shape libraries, plus a Rovo AI agent that draws and edits them from chat — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=excalidraw-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [confluence](/blog/tags/confluence.md) * [whiteboard](/blog/tags/whiteboard.md) * [excalidraw](/blog/tags/excalidraw.md) * [diagrams](/blog/tags/diagrams.md) --- # FAQ: Widget Carousel for Confluence — Image Sliders, Banners & Dashboards May 2, 2026 · 15 min read [NGPilot](https://ngpilot.com) Confluence pages are powerful containers for knowledge, documentation, and team collaboration. But when it comes to displaying visual content -- product screenshots, event photos, marketing banners, or process walkthroughs -- the standard page layout falls short. Images stacked vertically create long, scroll-heavy pages that are difficult to scan, and Confluence's built-in gallery macro only offers a static thumbnail grid with no interactive slideshow behavior. **Widget Carousel for Confluence** solves this by adding a fully interactive image carousel macro that you can embed on any Confluence page. You select images from page attachments or upload new ones directly, then display them in a customizable slider with configurable width options. The result is a polished, professional-looking carousel that transforms how visual content is presented in your Confluence workspace. This FAQ covers the most common questions teams have about Widget Carousel for Confluence -- from basic setup and content types to advanced configuration, responsive design, and how it compares to Confluence's native gallery macro. Whether you are building a company dashboard, a project landing page, or a team portal, this guide will help you get the most out of the carousel. ## What is Widget Carousel for Confluence and what does it do?[​](#what-is-widget-carousel-for-confluence-and-what-does-it-do "Direct link to What is Widget Carousel for Confluence and what does it do?") Widget Carousel for Confluence is an Atlassian Marketplace app that adds an interactive image carousel macro to your Confluence editor. Once installed, you can insert the macro on any page and configure it with images to create a professional slideshow display. The app integrates directly into the Confluence editing experience. You insert the macro by typing `/widget` in the editor and selecting "Widget Carousel" from the dropdown, or by clicking the "+" insert button and choosing it from the macro browser. This follows the same pattern as other Confluence macros, so there is no learning curve for authors who are already familiar with the editor. Once inserted, the macro presents a visual image picker that shows all attachments on the current page. You can select existing images or upload new ones directly through the picker interface. After selecting your images and clicking "Save," the carousel appears on the page ready to use. The entire setup process takes less than a minute for most configurations. Widget Carousel supports three width configurations that control how much horizontal space the carousel occupies: * **Default width** -- The carousel fits within the standard Confluence content column, matching the width of regular page content. This is the best choice for carousels embedded within longer pages that also contain text, tables, or other macros. * **Wide width** -- The carousel extends beyond the standard content column to use more of the available page width. This works well for carousels that are the primary content on a page, such as a dashboard banner or a product showcase section. * **Full width** -- The carousel spans the entire width of the page, edge to edge. This is ideal for hero banners on landing pages or portal homepages where you want the carousel to be the dominant visual element. You configure the width using the macro edit buttons that appear when you select the macro in the editor. This is the same interface Confluence uses for other width-aware macros, keeping the experience consistent. The carousel renders with smooth transitions between slides, navigation controls for moving forward and backward through the image sequence, and a clean visual design that integrates with Confluence's page styling. For a detailed walkthrough of the setup process, see the [Widget Carousel usage documentation](/docs/carousel-for-confluence/usage.md). ## How does Widget Carousel compare to Confluence's built-in gallery macro?[​](#how-does-widget-carousel-compare-to-confluences-built-in-gallery-macro "Direct link to How does Widget Carousel compare to Confluence's built-in gallery macro?") Confluence ships with a built-in gallery macro that many users discover first when looking for image display options. Understanding the differences between the gallery macro and Widget Carousel helps you choose the right tool for each use case. **Layout model.** The built-in gallery macro arranges images in a static grid of thumbnails. You configure the number of columns, and Confluence places each image into a cell in the grid. Users click individual thumbnails to open a lightbox overlay where they can browse through the full-size images. Widget Carousel takes a fundamentally different approach: it displays one image (or a defined set of images) at a time in a horizontal slider, with smooth transitions between slides. The carousel format is inherently sequential, guiding the viewer through images in order. **Width and layout control.** The gallery macro renders within the standard content column with basic column count configuration. Widget Carousel offers three distinct width modes (default, wide, full width) that give you precise control over how the carousel integrates with the page layout. For pages where the image display needs to be a prominent visual element rather than an inline content block, the wide and full-width options provide layout flexibility that the gallery macro cannot match. **Interactivity.** The gallery macro's interactivity is limited to clicking a thumbnail to open the lightbox. There is no timed transitions and no sequential navigation within the page itself -- the browsing happens in the lightbox overlay. Widget Carousel provides on-page navigation controls that let users move through slides without leaving the page context. **Use case fit.** The gallery macro works well for photo albums, design review collections, and any scenario where users need to browse a large number of images independently. Widget Carousel is the better choice when images need to be presented as a narrative sequence -- product feature walkthroughs, process step illustrations, announcement rotations, or any context where the order and progression of images matters. **Setup workflow.** The gallery macro uses a file pattern or label filter to pull in all matching attachments from the page. Widget Carousel uses an explicit image picker where you select specific images in a specific order. The picker approach gives you more control over which images appear and in what sequence, at the cost of needing to manually select each image rather than relying on automatic filtering. In practice, many teams use both: the gallery macro for general image collections and Widget Carousel for featured displays, banners, and sequential presentations. ## What content types can I display in a Widget Carousel?[​](#what-content-types-can-i-display-in-a-widget-carousel "Direct link to What content types can I display in a Widget Carousel?") Widget Carousel is focused on image content, supporting the most common image formats used in Confluence environments. **Supported image formats:** * **JPEG (.jpg, .jpeg)** -- The most common format for photographs and screenshots. JPEG images work well for product photos, team pictures, and any content with complex color gradients. * **PNG (.png)** -- Ideal for screenshots, diagrams, and images with text overlays. PNG supports transparency, which allows images to blend cleanly with different background colors. * **GIF (.gif)** -- Supports simple animations. Animated GIFs play their animation cycle within the carousel, adding motion to your image displays. * **SVG (.svg)** -- Scalable vector graphics that render crisply at any size. SVG is a strong choice for logos, icons, diagrams, and any visual content that needs to look sharp at both small and large display sizes. **Image source options:** * **Page attachments** -- The primary source for carousel images. When you open the macro configuration, the image picker displays all files currently attached to the Confluence page. You can select any image attachment to include it in the carousel. * **Upload during configuration** -- If the image you need is not yet attached to the page, you can upload it directly through the macro configuration interface. The upload adds the file as a page attachment and includes it in the carousel in one step, without needing to navigate to a separate attachment management screen. **Preparing images for best results:** * **Consistent dimensions** -- Images with the same aspect ratio produce the most polished carousel display. When images have different aspect ratios, the carousel adapts, but consistent sizing creates a smoother visual experience. * **Optimized file sizes** -- Large image files slow down page load times. Resize images to the display dimensions you need before uploading, and use JPEG compression for photographs. Confluence's built-in image handling helps, but starting with optimized files produces the fastest results. * **Descriptive file names** -- Use clear, descriptive file names for your images. This helps team members identify the correct images when configuring the carousel and makes attachment management easier over time. **Content strategies for effective carousels:** * **Product feature highlights** -- Create a series of annotated screenshots that walk through key features, with each slide focusing on one feature. * **Event photo galleries** -- Curate the best photos from team events, conferences, or company milestones into a sequential display. * **Process walkthroughs** -- Use step-by-step screenshots to illustrate workflows, onboarding procedures, or technical processes where each slide represents one step. * **Announcement rotations** -- Design visual announcement cards (using a consistent template) and rotate through them on dashboard pages. ## Does Widget Carousel support navigation controls?[​](#does-widget-carousel-support-navigation-controls "Direct link to Does Widget Carousel support navigation controls?") Widget Carousel renders navigation elements that allow users to move through the image sequence. The controls are designed to be intuitive and unobtrusive -- visible enough to discover but not so prominent that they distract from the image content itself. Users can move forward and backward through the slides, giving them full control over the viewing pace. **Configuration workflow:** Navigation and display settings are configured through the macro editor. You insert the Widget Carousel macro, select your images, and configure the layout before saving. The settings apply to that specific macro instance, so you can have different carousel configurations on different pages or even multiple carousels with different settings on the same page. ## Is Widget Carousel responsive and mobile-friendly?[​](#is-widget-carousel-responsive-and-mobile-friendly "Direct link to Is Widget Carousel responsive and mobile-friendly?") Responsive design is critical for Confluence pages because your team accesses content from a range of devices -- desktop workstations, laptops, tablets, and mobile phones. Widget Carousel is built to adapt to different screen sizes and container dimensions. **Width adaptation:** The three width modes (default, wide, full width) determine the starting container size, and the carousel scales proportionally within that container. On wider screens, the carousel takes full advantage of the available space. On narrower screens, it compresses gracefully while maintaining image aspect ratios and navigation functionality. * **Default width** carousels scale with the Confluence content column, which itself adapts to the viewport. This produces consistent behavior across devices. * **Wide and full-width** carousels expand to use more horizontal space on desktop but compress appropriately on smaller screens, ensuring that images remain fully visible without horizontal scrolling. **Image scaling:** Images within the carousel are scaled to fit the carousel container while preserving their aspect ratio. This means images are never stretched or distorted regardless of the screen size. On smaller screens, images appear at a reduced size but maintain their visual integrity. **Navigation control scaling:** The navigation controls scale with the carousel to remain accessible on touch devices. Tapping navigation elements on a tablet or phone works the same as clicking them on a desktop. The touch target sizes are designed to meet mobile usability standards, so navigation does not require precise tapping. **Confluence theme compatibility:** Widget Carousel renders within Confluence's standard macro container, which means it respects the active Confluence theme. Whether your instance uses the default Confluence theme, a custom theme, or a third-party theme, the carousel integrates with the surrounding page design rather than appearing as an isolated element. **Performance on mobile networks:** Since the carousel displays images from page attachments, Confluence's built-in CDN and caching infrastructure handle image delivery. This means images are served efficiently on mobile networks, with appropriate caching to minimize redundant downloads on repeat visits. ## What are the best use cases for Widget Carousel in Confluence?[​](#what-are-the-best-use-cases-for-widget-carousel-in-confluence "Direct link to What are the best use cases for Widget Carousel in Confluence?") Widget Carousel shines in scenarios where sequential image display creates a better user experience than static layouts. Here are the most effective use cases we see teams deploying. **Team dashboards with rotating banners:** Many Confluence spaces serve as team dashboards -- central pages where team members check for updates, announcements, and key metrics. A carousel at the top of the dashboard can rotate through: * Sprint goals and current status visuals * Team announcements and upcoming events * Key performance indicator charts and graphs * Recognition highlights and team achievements The carousel format keeps the content organized so that repeat visitors can browse through different highlights. This approach keeps dashboards feeling dynamic without requiring frequent manual updates to the page layout. **Project landing pages and product showcases:** When you create a Confluence page to introduce a project, product, or initiative, visual impact matters. A full-width carousel at the top of the page can display: * Product screenshots highlighting key features * Architecture diagrams showing system design * User interface mockups for design reviews * Timeline graphics showing project milestones The sequential nature of the carousel lets you tell a visual story -- guiding viewers through features in a logical order rather than presenting them all at once in an overwhelming grid. **Onboarding and training portals:** Confluence is widely used for employee onboarding and internal training. Widget Carousel enhances these pages by presenting step-by-step visual guides: * Software walkthrough screenshots where each slide shows one step * Office orientation photos for new employee guides * Process diagrams that build progressively across slides * Safety training visuals for compliance documentation The navigation controls let new employees move through the content at their own pace, and the carousel format keeps the page compact compared to displaying all images simultaneously. **Company intranet and portal pages:** For organizations using Confluence as an intranet platform, Widget Carousel adds a professional visual element to portal pages: * Company news and announcement banners * Event photo highlights from recent activities * Employee spotlight features with photos and bios * Cultural value illustrations and mission statement visuals The carousel format mirrors the visual banner pattern that users expect from modern intranet homepages, bringing that familiar experience into the Confluence environment. **Documentation and knowledge base enhancement:** Even in traditional documentation contexts, carousels add value when used strategically: * Before-and-after comparisons in change documentation * Version history screenshots showing UI evolution * Troubleshooting guides with sequential diagnostic screenshots * Release note highlights with annotated feature screenshots ## Setting Up Widget Carousel: A Quick Reference[​](#setting-up-widget-carousel-a-quick-reference "Direct link to Setting Up Widget Carousel: A Quick Reference") Follow these steps to add a carousel to any Confluence page: 1. **Insert the macro** -- Type `/widget` in the Confluence editor and select "Widget Carousel" from the dropdown, or click the "+" button and choose "Widget Carousel" from the insert menu. 2. **Select images** -- Use the image picker to select images from existing page attachments, or upload new images directly through the picker interface. 3. **Save the macro** -- Click "Save" on the macro configuration to confirm your image selection. 4. **Configure width** -- Use the macro edit buttons to set the width: default, wide, or full width, depending on how prominent you want the carousel to be on the page. 5. **Save the page** -- Save or publish the Confluence page to see the carousel rendered live. The entire process takes under a minute for most configurations. See the [full usage guide](/docs/carousel-for-confluence/usage.md) for detailed instructions with screenshots. ## Widget Carousel vs. Built-in Gallery Macro: Feature Comparison[​](#widget-carousel-vs-built-in-gallery-macro-feature-comparison "Direct link to Widget Carousel vs. Built-in Gallery Macro: Feature Comparison") | Feature | Widget Carousel | Built-in Gallery Macro | | ------------------- | -------------------------------------- | ------------------------------- | | Display format | Horizontal slider / carousel | Static thumbnail grid | | Image navigation | Sequential with transitions | Click-to-open lightbox | | Width configuration | Default, wide, full width | Standard content column | | Image selection | Visual picker (explicit selection) | File pattern or label filter | | Order control | Manual, explicit ordering | Alphabetical by filename | | Use case focus | Featured displays, banners, narratives | Image collections, photo albums | ## Tips for Getting the Most Out of Widget Carousel[​](#tips-for-getting-the-most-out-of-widget-carousel "Direct link to Tips for Getting the Most Out of Widget Carousel") **Standardize your image dimensions.** Carousels look most professional when all slides have consistent dimensions. Create a template canvas size for your team and resize all carousel images to match before uploading. Common choices include 1200x600 for banner-style carousels and 800x600 for standard content carousels. **Design for the slide format.** Each slide in the carousel is displayed individually, which means each image needs to stand on its own. Add clear titles, annotations, or captions directly to the images if the visual needs context. Avoid splitting a single concept across multiple slides unless the progression is self-explanatory. **Limit the number of slides.** Carousels with too many images become difficult to navigate and can overwhelm viewers. Aim for 5 to 10 slides for most use cases. If you need to display more images, consider splitting them across multiple carousels organized by category or theme. **Use full-width mode for landing pages.** When the carousel is the primary visual element on a page -- such as a project landing page or team portal -- the full-width configuration creates the most impact. For carousels embedded within content-heavy pages, stick with the default width to maintain page flow. **Keep file sizes reasonable.** Large images slow down page loads, especially for carousels with many slides. Optimize images before uploading by resizing to the display dimensions and compressing JPEG files. This is particularly important for dashboards and portal pages that team members load frequently. **Pair with other macros for rich pages.** Widget Carousel works well alongside other Confluence macros. Combine a carousel banner at the top of a page with text sections, tables, and other macros below to create comprehensive, visually engaging pages. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Widget Carousel for Confluence -- Usage Guide](/apps/widget-carousel-for-confluence.md) -- Step-by-step setup instructions with screenshots for configuring your first carousel * [Best Confluence Apps for Developers](/blog/best-confluence-apps-developers.md) -- Curated list of NGPILOT apps that enhance Confluence for engineering teams * [FAQ: Are Confluence Plugins Safe?](/blog/faq-using-plugins-security.md) -- Security evaluation guide for Atlassian Marketplace apps, covering permissions, data residency, and safe installation practices Try Modern FAQ for Confluence Accordion-style FAQ sections with drag-and-drop reordering and two themes — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236739/modern-faq-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-faq-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [confluence](/blog/tags/confluence.md) * [carousel](/blog/tags/carousel.md) * [widget](/blog/tags/widget.md) * [dashboard](/blog/tags/dashboard.md) --- # FAQ: EPUB Reader for Confluence — Everything You Need to Know May 2, 2026 · 14 min read [NGPilot](https://ngpilot.com) Confluence is where your team stores knowledge, documents, and reference materials. But when it comes to reading long-form content like eBooks, technical manuals, training guides, or policy documents distributed as EPUB files, teams often hit a wall. Confluence's native attachment viewer can display images, PDFs, and Office documents, but it does not render EPUB files. That means every time someone needs to reference an EPUB, they have to download it, open it in a separate application, and switch back and forth between their reader and Confluence. **EPUB Reader for Confluence** removes that friction entirely. It adds a dedicated macro that embeds a full-featured eBook reader directly on any Confluence page. Your team can open, navigate, and read EPUB documents without ever leaving the browser. Whether you are distributing employee handbooks, sharing research publications, or making training manuals available alongside project documentation, EPUB Reader for Confluence keeps everything in one place. This FAQ covers the most common questions teams ask when evaluating EPUB Reader for Confluence, from how it works and what formats it supports to embedding workflows, mobile reading, navigation features, and file size considerations. For the complete setup and configuration walkthrough, visit the [EPUB Reader for Confluence usage guide](/docs/epub-reader-for-confluence/usage.md). *** ## What does EPUB Reader for Confluence do?[​](#what-does-epub-reader-for-confluence-do "Direct link to What does EPUB Reader for Confluence do?") EPUB Reader for Confluence is an Atlassian Marketplace app that adds eBook reading capability directly inside Confluence. Once installed by your administrator, it provides a macro that you can place on any Confluence page to embed and read EPUB files. Instead of treating EPUBs as opaque attachments that must be downloaded and opened externally, the app renders the full contents of the EPUB -- chapters, text, images, and styled layouts -- inside a purpose-built reader interface. The reader opens in a full-screen overlay within your Confluence browser tab. This means you get a clean, distraction-free reading environment while remaining logged into Confluence and connected to your team's workspace. When you close the reader, you return to the Confluence page exactly where you left off. There is no context switching, no separate application to install on your computer, and no need to manage local copies of files that might be outdated. For teams that use Confluence as a central knowledge repository, this is particularly valuable. You can store employee onboarding guides, compliance manuals, product documentation, and reference publications as EPUB attachments on the relevant Confluence pages. Anyone with page access can then read those materials immediately, with full navigation and search capabilities, without needing external software. This also means that access control is handled entirely through Confluence's existing permission system -- if someone can see the page, they can read the EPUB. Compared to native Confluence attachment viewing, which supports PDFs and images but cannot render EPUB content, the EPUB Reader fills a meaningful gap. Native attachment previews show a generic file icon and a download link for EPUB files, providing no way to actually read the content inline. The EPUB Reader macro transforms that experience from a dead-end download into an interactive reading session. ## Which file formats does EPUB Reader for Confluence support?[​](#which-file-formats-does-epub-reader-for-confluence-support "Direct link to Which file formats does EPUB Reader for Confluence support?") The app is purpose-built for the **EPUB format** (files with the `.epub` extension). EPUB is the widely adopted open standard for digital publications, maintained by the W3C. It is the same format used by eBook retailers, digital libraries, and publishing platforms worldwide. EPUB files can contain reflowable text that adapts to different screen sizes, embedded images, styled layouts with CSS, hyperlinks, tables, and even multimedia elements in newer EPUB 3 specifications. If your organization currently distributes content in other formats, there are a few things to consider. Confluence's native viewer already handles PDF files, Microsoft Office documents, and common image formats reasonably well. For Word documents and PDFs that you want to convert to EPUB, free and paid conversion tools are available -- Calibre is a popular open-source option that can convert from PDF, DOCX, HTML, and many other formats into EPUB. Once converted, the EPUB files can be uploaded to Confluence and read using the EPUB Reader macro. It is worth noting that the EPUB format offers advantages over PDF for long-form reading within a browser. EPUB content is reflowable, meaning text adjusts to the width of the reader rather than being locked to a fixed page size. This makes EPUB files more comfortable to read on different screen sizes, from large desktop monitors to mobile phones, because you never need to zoom or scroll horizontally. PDF files, by contrast, have fixed layouts that can be difficult to read on smaller screens because the text does not reflow. ## How do I embed an EPUB file on a Confluence page?[​](#how-do-i-embed-an-epub-file-on-a-confluence-page "Direct link to How do I embed an EPUB file on a Confluence page?") Embedding an EPUB on a Confluence page is a straightforward process that takes just a few clicks. The workflow is designed to be intuitive even for non-technical users, and it follows the same pattern as other Confluence macros. First, navigate to the Confluence page where you want the EPUB to appear and click **Edit** to enter the page editor. In the editor, type `/epub` in the slash command menu, or click the `+` button in the toolbar and search for "EPUB Reader for Confluence." Select the macro to add it to your page. This opens the macro's configuration panel. The configuration panel presents two options for selecting an EPUB file. If you have already attached EPUB files to the current Confluence page, they will be listed and you can simply click one to select it. If you need to add a new file, click the **Upload EPUB File** button to upload an EPUB directly from your computer. The uploaded file is saved as a standard Confluence attachment on the page, and it is automatically selected for display in the macro. You also have the option to set a **custom title** for the reader. If you leave this field blank, the EPUB's filename will be used as the display title. If you want to show a more readable or descriptive name -- for example, "Employee Handbook 2026" instead of "employee-handbook-v3-final.epub" -- enter it in the title field. Once you have selected a file and optionally set a title, click **Save** to finalize the macro. When you publish or save the page, the macro appears as a card displaying the EPUB's title and a **Read** button. Anyone viewing the page can click the Read button to open the full reader interface. This card-based presentation keeps pages clean and uncluttered while making the EPUB content easily accessible. For step-by-step instructions with screenshots, see the [EPUB Reader for Confluence usage documentation](/docs/epub-reader-for-confluence/usage.md). ## Can I read EPUBs on mobile devices in Confluence?[​](#can-i-read-epubs-on-mobile-devices-in-confluence "Direct link to Can I read EPUBs on mobile devices in Confluence?") Yes, EPUB Reader for Confluence is designed to work across devices, including mobile phones and tablets. The reader interface adapts to the available screen size, maintaining readable text and functional navigation controls even on smaller displays. This is where the reflowable nature of the EPUB format provides a significant advantage over fixed-layout formats like PDF -- text automatically adjusts to fit the screen width, so you never need to pinch-to-zoom or scroll horizontally to read a paragraph. When you access a Confluence page containing an EPUB Reader macro from a mobile browser or the Confluence mobile app, the macro card appears just as it does on desktop. Tapping the **Read** button opens the reader in a full-screen view optimized for touch interaction. The navigation arrows on either side of the screen are easy to tap, and the bottom toolbar with progress tracking remains accessible without crowding the reading area. The reading settings -- light and dark themes, and font size adjustment -- are fully functional on mobile devices. Dark mode is particularly useful for reading on phones in low-light environments, and the font size controls let you increase text size for comfortable reading without glasses or in bright outdoor conditions. Your reading progress is saved per device, so you can start reading a document on your desktop at the office and continue from where you left off on your phone during your commute. For organizations with field teams, mobile sales staff, or remote workers who rely on phones and tablets as their primary devices, mobile EPUB reading support means that training materials, product guides, and reference documents are accessible wherever your team happens to be working. ## What navigation and customization features does the reader include?[​](#what-navigation-and-customization-features-does-the-reader-include "Direct link to What navigation and customization features does the reader include?") The EPUB Reader provides a comprehensive set of navigation and customization tools that make reading long-form content practical and comfortable within Confluence. These features are accessible through a clean toolbar that does not distract from the reading experience. **Table of contents navigation** is available through the menu icon in the top toolbar. Clicking it opens the EPUB's structured table of contents, which displays the full chapter and section hierarchy of the document. You can jump directly to any chapter or section with a single click, which is essential for reference materials and technical manuals where readers rarely consume content sequentially from beginning to end. This is a significant advantage over native Confluence attachment viewing, which provides no way to navigate within an EPUB file at all. **Page navigation** is available through multiple methods. On-screen arrow buttons (`<` and `>`) appear on the left and right sides of the reading area for clicking or tapping. Keyboard users can press the Left Arrow and Right Arrow keys to page through content. The bottom toolbar also includes dedicated **Previous** and **Next** buttons. These redundant navigation paths ensure that every user can move through the document in the way that feels most natural to them. **Reading progress tracking** appears in the bottom toolbar. A visual progress bar fills as you advance through the document, and a percentage indicator shows exactly how far you have read. This gives you a clear sense of how much content remains, which is especially useful for long documents like employee handbooks or training manuals that span dozens of chapters. Your reading progress is automatically saved, so if you close the reader and return later, you can pick up exactly where you left off without needing to bookmark your position manually. **Display customization** is available through the settings icon in the top toolbar. The reader offers both **Light** and **Dark** themes, which switch the background and text colors for comfortable reading in different lighting conditions. The dark theme reduces eye strain in low-light environments and is also preferred by many users during extended reading sessions. **Font size adjustment** lets you increase or decrease the text size to your preference, which improves readability for users with visual impairments or those reading on high-resolution displays where default font sizes may appear small. ## Are there file size limits for EPUB attachments in Confluence?[​](#are-there-file-size-limits-for-epub-attachments-in-confluence "Direct link to Are there file size limits for EPUB attachments in Confluence?") The practical file size limits for EPUB files in the EPUB Reader are determined by your Confluence instance's attachment configuration rather than by the app itself. Confluence administrators can set maximum attachment sizes at the global level, and individual spaces can have their own attachment limits. These limits apply to all file types, including EPUB. For most Confluence Cloud instances, the default attachment size limit is generous enough to accommodate even lengthy EPUB files containing hundreds of pages and embedded images. In terms of performance, the EPUB Reader handles large files well because it loads content progressively. Rather than parsing and rendering the entire EPUB at once, the reader loads content as you navigate through it. This means that opening a 50-megabyte EPUB with high-resolution images is just as responsive as opening a smaller text-heavy document. The initial load is fast, and page transitions are smooth regardless of the total file size. For organizations with very large EPUB files -- such as illustrated technical manuals, image-heavy training materials, or compiled documentation sets -- it is worth considering whether the EPUB can be split into logical volumes. While the reader handles large files capably, splitting a 500-page manual into separate EPUB files by section or chapter can improve organization and make it easier for readers to find specific content quickly. Each volume can be embedded on its own Confluence page within a structured space hierarchy. If you encounter issues uploading particularly large EPUB files, check with your Confluence administrator about the current attachment size limits and whether they can be increased for your use case. The EPUB Reader macro itself does not impose any additional restrictions beyond what Confluence allows for attachments. *** ## EPUB Reader vs native Confluence attachment viewing[​](#epub-reader-vs-native-confluence-attachment-viewing "Direct link to EPUB Reader vs native Confluence attachment viewing") One of the most common questions is how EPUB Reader for Confluence compares to Confluence's built-in attachment handling. Here is a direct comparison of the two approaches for EPUB files. | Feature | EPUB Reader for Confluence | Native Confluence Attachments | | ------------------------ | ------------------------------------------- | --------------------------------- | | **EPUB rendering** | Full content rendering with reflowable text | File icon with download link only | | **In-page reading** | Read directly on the Confluence page | Must download and open externally | | **Table of contents** | Interactive chapter navigation | Not available for EPUB files | | **Progress tracking** | Visual progress bar with percentage | Not available | | **Theme options** | Light and dark themes | Not applicable | | **Font size control** | Adjustable within the reader | Not applicable | | **Keyboard navigation** | Arrow key paging | Not applicable | | **Mobile reading** | Responsive reader interface | Download required on mobile | | **Saved progress** | Automatically resumes where you left off | Not available | | **Custom display title** | Configurable in macro settings | Shows filename | The comparison makes it clear that native Confluence attachment handling provides essentially no reading experience for EPUB files. The EPUB Reader macro transforms EPUB from a downloadable file into a first-class content type that your team can interact with directly. For teams that regularly distribute reading materials through Confluence, this difference is the gap between "technically possible" and "actually practical." ## When to use EPUB Reader for Confluence[​](#when-to-use-epub-reader-for-confluence "Direct link to When to use EPUB Reader for Confluence") EPUB Reader for Confluence is valuable in a wide range of scenarios. Here are common use cases where teams get the most from the app: * **Employee onboarding and handbooks.** Distribute your organization's employee handbook as an EPUB on the onboarding space. New hires can read it directly in Confluence alongside onboarding checklists, team introductions, and process documentation. * **Training and certification materials.** Publish training manuals, study guides, and certification preparation materials as EPUBs on dedicated training spaces. Learners can track their reading progress and return to specific chapters easily. * **Technical reference documentation.** For teams that maintain long-form technical documentation, distributing it as EPUB allows readers to navigate by chapter, adjust display settings, and read comfortably on any device. * **Policy and compliance documents.** Make policy documents, compliance guides, and regulatory references available as EPUBs that anyone in the organization can access and read without special software. * **Research and knowledge sharing.** Teams that compile research findings, literature reviews, or annotated bibliographies can share them as EPUB files that colleagues can read and navigate efficiently. ## Getting started[​](#getting-started "Direct link to Getting started") Setting up EPUB Reader for Confluence is quick. Your Confluence administrator installs the app from the Atlassian Marketplace. Once installed, the EPUB Reader macro is available on every page in your instance. There is no per-user configuration required -- any user with edit permission on a page can add the macro, and any user with view permission can read the embedded EPUB. Visit the [EPUB Reader for Confluence usage guide](/docs/epub-reader-for-confluence/usage.md) for detailed installation instructions, configuration screenshots, and a complete feature walkthrough. ## Related resources[​](#related-resources "Direct link to Related resources") * [Best Confluence apps for developers](/blog/best-confluence-apps-developers.md) -- a curated guide to the most useful Confluence Marketplace apps for engineering teams * [FAQ: Using Confluence and Jira plugins safely](/blog/faq-using-plugins-security.md) -- security best practices for evaluating and managing Atlassian Marketplace apps * [EPUB Reader for Confluence documentation](/apps/epub-reader-for-confluence.md) -- full usage guide with setup steps and feature details Try Modern FAQ for Confluence Accordion-style FAQ sections with drag-and-drop reordering and two themes — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236739/modern-faq-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-faq-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [confluence](/blog/tags/confluence.md) * [epub](/blog/tags/epub.md) * [document-viewer](/blog/tags/document-viewer.md) * [reading](/blog/tags/reading.md) --- # Excalidraw for Confluence & Jira: FAQ, Tips & Best Practices April 21, 2026 · 11 min read [NGPilot](https://ngpilot.com) Excalidraw is a virtual whiteboard tool known for its hand-drawn, sketch-like visual style that makes diagrams feel approachable and easy to understand. Teams choose Excalidraw because it lowers the barrier to visual communication -- you do not need to be a designer to create clear architecture diagrams, flowcharts, wireframes, or brainstorming boards. When integrated directly into Confluence and Jira through dedicated apps, Excalidraw becomes even more powerful: diagrams live alongside your documentation and issues, eliminating the need to switch between external tools and your workspace. Two Atlassian Marketplace apps bring Excalidraw into the Atlassian ecosystem. **Excalidraw Plus for Confluence** embeds a full drawing editor into Confluence pages, giving teams freeform canvas tools for brainstorming, planning, and documentation. **Excalidraw Diagrams plus Whiteboards for Jira** adds a diagramming panel directly inside Jira issues, so developers and project managers can create and edit visual artifacts without leaving the issue view. Both apps store diagrams as JSON attachments, which means your visual data stays inside your Atlassian instance and travels with your content through exports, backups, and migrations. This FAQ covers the most common questions teams ask when adopting Excalidraw inside Confluence and Jira, along with practical answers, feature comparisons, and best practices to help you get the most from the tools. *** ## Where are Excalidraw diagrams stored?[​](#where-are-excalidraw-diagrams-stored "Direct link to Where are Excalidraw diagrams stored?") Excalidraw diagrams are saved as **JSON file attachments** on the Confluence page or Jira issue where they were created. In Confluence, you will find the `.json` file in the page's attachment list alongside any other uploaded files. In Jira, the diagram is stored as an attachment on the issue itself, visible in the issue's attachment section. Storing diagrams as JSON attachments has several advantages. First, the diagram data never leaves your Atlassian instance, which is important for organizations with strict data residency or compliance requirements. Second, the JSON format preserves full editing fidelity -- when you reopen the diagram, every shape, line, text element, and style setting is exactly as you left it. Third, because the attachment travels with the page or issue, it is included automatically in Confluence space exports, Jira project exports, and server-to-server migrations. If you need to back up diagrams outside of Atlassian, you can download the JSON attachment file directly from the attachment list. This file can later be re-imported into any Excalidraw editor, including the open-source version at excalidraw\.com, giving you full portability. ## Can multiple users collaborate on Excalidraw diagrams in real time?[​](#can-multiple-users-collaborate-on-excalidraw-diagrams-in-real-time "Direct link to Can multiple users collaborate on Excalidraw diagrams in real time?") Real-time collaboration works differently depending on which app and platform you are using. **Excalidraw Plus for Confluence** supports collaborative editing when multiple users have the same Confluence page open and enter the Excalidraw editor simultaneously. Each collaborator's cursor is visible, and changes are synchronized so the team can draw together on a shared canvas. In **Excalidraw Diagrams plus Whiteboards for Jira**, collaboration happens through the issue-level diagram panel. Team members who have access to the Jira issue can view and edit the diagram, with changes saved as updates to the JSON attachment. Because the diagram is tied to a single issue, editing is typically sequential -- one person edits at a time, and the saved version is immediately available to the next person who opens it. For teams that need simultaneous editing in Confluence, make sure all collaborators have edit permissions on the page and are using a supported browser. The collaboration experience is smoothest in Chrome and Firefox. If you notice sync delays, try refreshing the page or closing and reopening the editor. ## How do I export Excalidraw diagrams?[​](#how-do-i-export-excalidraw-diagrams "Direct link to How do I export Excalidraw diagrams?") Both apps provide flexible export options suited to different use cases. From inside the Excalidraw editor, you can export your diagram to **PNG** for raster images, **SVG** for scalable vector graphics, or the raw **JSON** source file. Here is when to use each format: * **PNG** -- Best for embedding diagrams in emails, presentations, or documents where a flat image is sufficient. PNG exports respect your current canvas zoom and viewport, so make sure to frame the diagram the way you want it before exporting. * **SVG** -- Ideal when you need a resolution-independent image that scales cleanly at any size, such as for print materials or high-resolution displays. SVG files can also be edited in vector graphics tools like Illustrator or Inkscape. * **JSON** -- The full diagram source file. Use JSON for backups, version control, or importing into another Excalidraw instance. This is the most complete export because it preserves every element and its properties. In Confluence, the diagram renders inline on the page as a viewable image, so external export is only needed when you want to use the diagram outside Confluence. In Jira, the diagram appears in the issue panel and is also available as an attachment that can be downloaded. ## How can I improve performance with large diagrams?[​](#how-can-i-improve-performance-with-large-diagrams "Direct link to How can I improve performance with large diagrams?") Large canvases with hundreds or thousands of elements can slow down any browser-based editor, and Excalidraw is no exception. If you notice lag when panning, zooming, or selecting elements, try these strategies: **Break large diagrams into smaller ones.** Instead of drawing an entire system architecture on a single canvas, split it into focused diagrams -- one per service, layer, or domain. Link between related Confluence pages so readers can navigate the full picture without loading one massive canvas. **Use shape libraries instead of manual drawing.** Both apps include extensive shape libraries with pre-built elements. **Excalidraw Plus for Confluence** ships with **220+ shape packs**, and **Excalidraw Diagrams plus Whiteboards for Jira** includes **229 bundled shape libraries** covering AWS, Azure, GCP, UML, and more. Dragging a pre-built shape from a library is faster and lighter than assembling it from basic primitives. **Enable grid alignment.** Grid snapping helps keep your canvas tidy, which reduces visual clutter and makes the diagram easier for the renderer to handle. A well-aligned diagram also communicates more clearly to readers. **Minimize overlapping transparent elements.** Overlapping shapes with opacity settings require the browser to composite layers repeatedly during pan and zoom. Use solid fills where possible and group related elements together. ## Can I reuse Excalidraw diagram templates and shapes?[​](#can-i-reuse-excalidraw-diagram-templates-and-shapes "Direct link to Can I reuse Excalidraw diagram templates and shapes?") Yes -- both apps provide robust reuse capabilities that save time and enforce visual consistency across your team. **Excalidraw Plus for Confluence** includes a template library where you can save commonly used diagrams as reusable starting points. Teams often create templates for standard flowcharts, sprint retro boards, system architecture layouts, and UI wireframes. When a new page needs a diagram, you pick a template and customize it rather than starting from scratch. The app also provides access to **220+ shape packs** from the Excalidraw library community, covering everything from basic geometric shapes to specialized icon sets for technology, business, and design. **Excalidraw Diagrams plus Whiteboards for Jira** comes with **229 bundled shape libraries** that include pre-built stencils for major cloud providers (AWS, Azure, GCP), UML diagrams, network topology, and more. These libraries are particularly useful for engineering teams that need to create consistent architecture diagrams across multiple Jira issues. The app also supports **Mermaid syntax generation**, allowing you to define diagrams in text-based Mermaid format and render them as Excalidraw visuals -- a powerful option for developers who prefer code over drawing. ## How do I make Excalidraw diagrams accessible?[​](#how-do-i-make-excalidraw-diagrams-accessible "Direct link to How do I make Excalidraw diagrams accessible?") Accessibility is an important consideration when diagrams convey critical information. While visual diagrams are inherently graphical, you can take concrete steps to make them more inclusive: * **Add alt text descriptions.** Surround the diagram with descriptive text on the Confluence page or Jira issue that explains what the diagram shows. A screen reader cannot interpret the visual canvas, so a written summary is essential. * **Use high-contrast color palettes.** Excalidraw Plus supports a range of color options. Choose color combinations with strong contrast ratios, and avoid relying solely on color to convey meaning. Use labels, patterns, or line styles as additional differentiators. * **Label all elements clearly.** Every shape and connector in your diagram should have a text label. Unlabeled shapes are meaningless to anyone using assistive technology or reading a text-only export. * **Provide a text-based alternative.** For complex diagrams, consider writing a structured text outline below the visual. This serves double duty as both an accessibility aid and a quick-reference summary for all readers. * **Test with your audience.** Ask team members who use screen readers or other assistive tools whether your diagrams are understandable. Their feedback will guide improvements you may not have considered. ## What is the difference between the Confluence and Jira Excalidraw apps?[​](#what-is-the-difference-between-the-confluence-and-jira-excalidraw-apps "Direct link to What is the difference between the Confluence and Jira Excalidraw apps?") While both apps are built on the same Excalidraw editor, they are designed for different workflows and contexts. Here is a side-by-side comparison of their key features: | Feature | Excalidraw Plus for Confluence | Excalidraw Diagrams plus Whiteboards for Jira | | -------------------- | ---------------------------------------------------- | --------------------------------------------------- | | **Location** | Embedded editor on Confluence pages | Right-side panel on Jira issues | | **Primary use case** | Documentation, brainstorming, knowledge base visuals | Issue-level diagrams, technical specs, architecture | | **Drawing tools** | Shapes, freehand, text, lines, arrows | Shapes, freehand, text, lines, arrows | | **Styling options** | Colors, line styles, opacity, fill patterns | Colors, line styles, opacity, fill patterns | | **Shape libraries** | 220+ shape packs from community library | 229 bundled libraries (AWS, Azure, GCP, UML) | | **Mermaid support** | Not built in | Yes -- generate diagrams from Mermaid syntax | | **Export formats** | PNG, SVG, JSON | PNG, SVG, JSON | | **Storage** | JSON attachment on Confluence page | JSON attachment on Jira issue | | **Templates** | Template library for team reuse | Shape libraries for consistent stencils | | **Auto-save** | Yes | Yes | | **Grid alignment** | Yes | Yes | | **Collaboration** | Real-time multi-user editing | Sequential editing per issue | Choose the Confluence app when your team needs a freeform drawing space for collaborative documentation, retrospectives, or knowledge articles. Choose the Jira app when your workflow requires diagrams tightly coupled to specific issues -- for example, attaching an architecture diagram to a design ticket or sketching a bug reproduction flow directly on a bug report. ## Best practices for using Excalidraw effectively[​](#best-practices-for-using-excalidraw-effectively "Direct link to Best practices for using Excalidraw effectively") Over years of helping teams adopt Excalidraw in Confluence and Jira, we have identified several practices that consistently lead to better outcomes. ### 1. Standardize on shared shape libraries[​](#1-standardize-on-shared-shape-libraries "Direct link to 1. Standardize on shared shape libraries") Before your team starts drawing, agree on which shape libraries to use for common diagram types. If everyone uses the same AWS stencil pack for architecture diagrams, the resulting visuals will be consistent and easier to read. Assign a team member to curate and publish approved libraries in the Excalidraw Plus template library or the Jira shape library panel. ### 2. Keep diagrams focused on one concept[​](#2-keep-diagrams-focused-on-one-concept "Direct link to 2. Keep diagrams focused on one concept") Resist the temptation to put everything on a single canvas. A diagram that tries to show an entire microservices architecture, plus data flows, plus deployment pipelines, plus team ownership will be unreadable. Instead, create a high-level overview diagram and link to separate detail diagrams on dedicated Confluence pages or Jira issues. Each diagram should answer one question. ### 3. Use the auto-save feature to your advantage[​](#3-use-the-auto-save-feature-to-your-advantage "Direct link to 3. Use the auto-save feature to your advantage") Both apps auto-save your work as you draw. This means you can treat the canvas as a living document that evolves alongside your project. Encourage the team to update diagrams when architecture changes, rather than letting them go stale. Set a recurring reminder to review and update key diagrams during sprint retrospectives or milestone reviews. ### 4. Combine freeform drawing with structured libraries[​](#4-combine-freeform-drawing-with-structured-libraries "Direct link to 4. Combine freeform drawing with structured libraries") Excalidraw's hand-drawn style is great for early-stage brainstorming where you want to emphasize that ideas are preliminary. As concepts mature, switch to structured shape libraries for polished diagrams that convey precision and authority. This two-phase approach -- sketch first, refine later -- takes advantage of Excalidraw's unique visual character without sacrificing professionalism. ### 5. Export and embed for broader visibility[​](#5-export-and-embed-for-broader-visibility "Direct link to 5. Export and embed for broader visibility") Not everyone who needs to see your diagram will have access to the Confluence page or Jira issue where it lives. Use the PNG or SVG export to embed diagrams in Slack messages, email threads, or presentation decks. Keeping a shared drive folder with the latest exported versions of key diagrams ensures that stakeholders can reference them without navigating into Atlassian tools. ## Related resources[​](#related-resources "Direct link to Related resources") * [Excalidraw Plus for Confluence](/apps/excalidraw-plus-for-confluence.md) -- freeform drawing in Confluence * [Excalidraw Diagrams plus Whiteboards for Jira](/apps/excalidraw-diagrams-plus-whiteboards-for-jira.md) -- whiteboards in Jira issues * [Excalidraw & Mermaid Visual Editor](/apps/excalidraw-mermaid-diagrams-for-confluence.md) -- combine freeform and structured diagrams * [Using Excalidraw whiteboards in Jira](/blog/excalidraw-whiteboards-jira.md) -- setup guide * [Create Mermaid diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md) -- alternative diagram tool Try Excalidraw Diagrams plus Whiteboards for Jira Add a freehand drawing canvas to every Jira issue, with 229 shape libraries — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/2139233994/excalidraw-diagrams-plus-whiteboards-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=excalidraw-diagrams-plus-whiteboards-for-jira) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [excalidraw](/blog/tags/excalidraw.md) * [confluence](/blog/tags/confluence.md) * [jira](/blog/tags/jira.md) * [diagrams](/blog/tags/diagrams.md) --- # Running Design Whiteboarding Sessions in Confluence — Why We Picked Excalidraw over draw\.io May 2, 2026 · 13 min read [NGPilot](https://ngpilot.com) When teams need to add diagrams to Confluence, two tools come up again and again: **Excalidraw** and **draw\.io** (also known as diagrams.net). Both are popular Confluence diagram apps on the Atlassian Marketplace, but they take fundamentally different approaches to visual communication — and picking the wrong one wastes time and licensing budget. The short version: for **live whiteboarding, brainstorming, and freeform sketching**, Excalidraw wins. For **formal, finalized diagrams** (UML, network topology, BPMN), draw\.io is the better fit. Most teams end up needing both — and the rest of this post is the honest, feature-by-feature comparison so you can make the right call for your workflow. Who should read this * **Product/design teams** deciding between Excalidraw and draw\.io for whiteboarding * **Eng leads** choosing a diagramming tool for architecture sketches and UML * **Anyone** comparing the two for freeform vs structured diagramming ## The scenario that forced our choice[​](#the-scenario-that-forced-our-choice "Direct link to The scenario that forced our choice") The decision became concrete for us during a Monday design review. The team sketches flows, argues about architecture, and leaves the meeting with a whiteboard full of diagrams that someone has to photograph, lose, and redraw. We wanted those sketches to live on the Confluence page the ticket links to — editable by anyone, versioned, and still there next sprint. That requirement is what drove our Excalidraw-vs-draw\.io decision, and it's a useful lens because it exposes where each tool fits a real workflow rather than a feature checklist. When teams need to add diagrams to Confluence pages, two names come up again and again: **Excalidraw** and **draw\.io** (also known as diagrams.net). Both are popular diagramming tools with Confluence integrations available on the Atlassian Marketplace, but they take fundamentally different approaches to visual communication. Excalidraw is built around a freeform, hand-drawn aesthetic that encourages brainstorming and rapid ideation. Its sketch-like style signals that ideas are works in progress, which makes it perfect for whiteboarding sessions, architecture discussions, and early-stage planning. **Excalidraw Plus for Confluence** brings this experience directly into your Confluence pages with a full visual editor and 220+ shape libraries. draw\.io, on the other hand, is a structured diagramming tool focused on precision and formality. It uses clean, geometric shapes with snap-to-grid alignment and automatic layout engines, making it a strong choice for UML diagrams, network topologies, BPMN workflows, and org charts. The draw\.io app for Confluence embeds a full-featured editor as a macro on any page. Choosing between them is not a matter of one being universally better -- it is about matching the tool to your team's workflow. This FAQ answers the most common questions teams ask when comparing Excalidraw and draw\.io for Confluence, with detailed feature analysis and recommendations for different use cases. *** ## Is Excalidraw or draw\.io better for Confluence?[​](#is-excalidraw-or-drawio-better-for-confluence "Direct link to Is Excalidraw or draw.io better for Confluence?") The honest answer is that neither tool is objectively better -- they serve different purposes, and the right choice depends on what your team needs to accomplish. **Excalidraw** excels at freeform sketching, whiteboarding, and any situation where you want to quickly capture ideas without worrying about pixel-perfect alignment. Its hand-drawn visual style makes diagrams feel approachable and invites collaboration from team members who might be intimidated by rigid, formal tools. If your team frequently holds architecture whiteboard sessions, brainstorms on Confluence pages, or needs to sketch wireframes and rough flows, Excalidraw is the stronger fit. **draw\.io** is better suited for structured, precise diagrams that need to follow formal notation standards. If your organization requires UML class diagrams, BPMN process models, detailed network topologies with exact IP addressing, or compliance-ready flowcharts, draw\.io's grid-based editor and auto-layout features will save you time. The tool enforces visual consistency through its stencil system, which is valuable when multiple people are producing diagrams that need to look uniform. For teams that produce technical documentation destined for external stakeholders or auditors, draw\.io's polished output is often preferred. The best approach for many teams is to evaluate what types of diagrams you create most often and match the tool to the dominant use case. You can also run both side by side -- more on that later. ## Does draw\.io support Mermaid diagrams in Confluence?[​](#does-drawio-support-mermaid-diagrams-in-confluence "Direct link to Does draw.io support Mermaid diagrams in Confluence?") Yes -- as of 2026. draw\.io inserts Mermaid from `Arrange > Insert > Mermaid` (or the `+` button in the toolbar) and documents 29 supported Mermaid keywords, from flowcharts and sequence diagrams through C4, treemaps and Wardley maps. Since July 2026 the inserted diagram is generated with native draw\.io shapes inside a Mermaid container group, with the source attached so you can restyle the shapes and regenerate from the source again. Mermaid is a text-based diagram language that lets you define flowcharts, sequence diagrams, class diagrams, and other diagram types using simple code statements. Many developer teams prefer Mermaid because diagrams can be version-controlled, reviewed in pull requests, and generated programmatically. So the decision is no longer *whether* draw\.io can take Mermaid, but what the source becomes. In draw\.io the Mermaid text is an import step that becomes native shapes; in **Mermaid Plus Diagrams & AI Agent for Confluence** the text stays the canonical form of the diagram, with live preview, 30 diagram types, one-click templates, and a Rovo agent that creates, reads, updates and converts diagrams on the page. The full argument is in [draw.io vs Mermaid in Confluence](/blog/mermaid-vs-drawio-confluence.md). **Excalidraw Plus for Confluence** is a third option: Mermaid import onto a freeform canvas, for teams that want hand-drawn output. ## Which has more shape libraries: Excalidraw or draw\.io?[​](#which-has-more-shape-libraries-excalidraw-or-drawio "Direct link to Which has more shape libraries: Excalidraw or draw.io?") Both tools offer extensive shape libraries, though they differ in how those libraries are accessed and organized. **Excalidraw Plus for Confluence** includes **220+ built-in shape packs** that cover a wide range of categories: cloud architecture (AWS, Azure, GCP), software design (UML, entity-relationship), networking, databases, user interface wireframes, and general business diagrams. The shape browser is fully searchable and sortable, so you can quickly find the stencil you need without scrolling through long nested menus. **draw\.io** also provides a large collection of shape libraries -- its stencil collection is one of the most comprehensive among diagramming tools, with hundreds of shape sets organized by category. However, the browsing experience in draw\.io tends to require more clicks to navigate through hierarchical menus, and the search functionality is less streamlined than Excalidraw's dedicated shape browser panel. Some users report that finding specific shapes in draw\.io can feel slower, especially when you are working across multiple cloud provider icon sets. For teams that frequently switch between different diagram types -- say, sketching a cloud architecture in the morning and a UML sequence diagram in the afternoon -- Excalidraw's searchable shape library makes it faster to find and place the right elements. For teams that primarily use one or two diagram types and have memorized where those shapes live, draw\.io's library depth is perfectly adequate. ## Is Excalidraw free for Confluence?[​](#is-excalidraw-free-for-confluence "Direct link to Is Excalidraw free for Confluence?") The pricing models for the two tools differ significantly, and understanding the distinction is important for budget planning. **Excalidraw Plus for Confluence** is a paid app available on the Atlassian Marketplace. It offers a free trial period so your team can evaluate whether it fits your workflow before committing to a subscription. The open-source Excalidraw project at excalidraw\.com is free to use, but it does not integrate with Confluence -- it is a standalone web application that runs separately from your Atlassian instance. **draw\.io for Confluence** is a paid Marketplace app with a free trial, not a free tier. It is sold in two editions -- Standard (the full editor, Smart Templates, standard support) and Advanced (dedicated account manager, custom security reviews, development previews, and a zero-egress option). Licensing is per user, so a small team pays a modest amount and a large rollout is a real line item; for teams standardising on one tool across hundreds of users, that difference is worth modelling before you pick. When comparing costs, factor in the total value each tool delivers. Excalidraw Plus includes 220+ shape libraries, Mermaid support, template management, and collaborative editing as part of its subscription. If your team would otherwise need separate tools for whiteboarding and structured diagramming, Excalidraw Plus can consolidate those costs into a single app. ## Which is faster for quick diagrams in Confluence?[​](#which-is-faster-for-quick-diagrams-in-confluence "Direct link to Which is faster for quick diagrams in Confluence?") Speed depends entirely on the type of diagram you are creating and your preferred working style. For **quick sketches, brainstorming sessions, and architecture whiteboarding**, Excalidraw is significantly faster. Its freeform canvas means you can draw, connect, and label elements without worrying about snap-to-grid alignment or precise positioning. The hand-drawn style is forgiving by nature -- a slightly crooked line or off-center label does not look out of place. This makes Excalidraw the tool of choice for live whiteboarding sessions where you need to capture ideas as they flow. For **formal, structured diagrams**, draw\.io can be faster because of its automatic layout engine and snap-to-grid system. When you need a clean UML class diagram or a network topology with precise spacing, draw\.io's alignment features save you the manual effort of positioning every element. The auto-layout function can arrange complex diagrams in seconds, which would take much longer to do by hand on a freeform canvas. In practice, the speed difference is most pronounced during the early stages of a project when ideas are fluid and diagrams change frequently. Excalidraw's low-friction drawing experience means you can iterate quickly without getting bogged down in formatting. As a project matures and diagrams need to become more polished, draw\.io's structure-oriented features help maintain consistency and professionalism across many pages of documentation. ## Can I use both Excalidraw and draw\.io in Confluence?[​](#can-i-use-both-excalidraw-and-drawio-in-confluence "Direct link to Can I use both Excalidraw and draw.io in Confluence?") Yes, absolutely. Both apps run independently as separate macros in Confluence, and there is no conflict between them. You can install both from the Atlassian Marketplace and use them on different pages -- or even on the same page -- without any issues. Many teams adopt exactly this strategy: **Excalidraw Plus for brainstorming, whiteboarding, and early-stage ideation**, and **draw\.io for formal technical diagrams, process documentation, and compliance artifacts**. This dual-tool approach works well because each tool's strengths complement the other's weaknesses. When a new feature is being designed, the team can use Excalidraw to sketch out ideas on a Confluence page during a planning session. Once the design is finalized and needs to be documented as a formal architecture diagram for stakeholders, the same content can be recreated in draw\.io with precise layout and standardized notation. The overhead of maintaining two diagramming tools is minimal. Both store their diagrams as page attachments, both integrate with Confluence's permission system, and both provide export options (PNG, SVG) for sharing diagrams outside Confluence. The main consideration is licensing cost -- you will need active subscriptions for both apps if you are using paid tiers. For teams that create a high volume of diverse diagram types, the investment is typically worthwhile. ## Feature comparison: Excalidraw Plus vs draw\.io for Confluence[​](#feature-comparison-excalidraw-plus-vs-drawio-for-confluence "Direct link to Feature comparison: Excalidraw Plus vs draw.io for Confluence") | Feature | Excalidraw Plus | draw\.io | | -------------------- | -------------------------------------- | --------------------------------------------------------- | | **Drawing style** | Freeform, hand-drawn aesthetic | Structured, geometric precision | | **Editor type** | Visual drag-and-drop canvas | Visual drag-and-drop canvas with grid | | **Shape libraries** | 220+ searchable shape packs | Extensive stencil library (hierarchical menus) | | **Mermaid support** | Yes -- Mermaid syntax input | Yes -- since 2026, 29 Mermaid keywords | | **Auto-layout** | Manual positioning | Automatic layout engine | | **Collaboration** | Real-time multi-user editing | Real-time multi-user editing | | **Export formats** | PNG, SVG, JSON | PNG, SVG, PDF, XML | | **Template library** | Built-in, team-shareable | Built-in with custom templates | | **Snap-to-grid** | Optional grid alignment | Default grid with snapping | | **Pricing model** | Paid subscription with free trial | Paid per user, Standard and Advanced editions, free trial | | **Data storage** | JSON attachment on Confluence page | Embedded content on Confluence page | | **Best for** | Brainstorming, whiteboarding, sketches | UML, BPMN, network diagrams, formal docs | ## When to choose Excalidraw[​](#when-to-choose-excalidraw "Direct link to When to choose Excalidraw") Choose **Excalidraw Plus for Confluence** when your team's primary needs align with any of the following: * **Brainstorming and ideation sessions** where you need to capture ideas quickly without formatting overhead * **Architecture discussions** where the hand-drawn style keeps conversations focused on concepts rather than visual polish * **Wireframing and early-stage design** where a sketch-like aesthetic signals that the design is preliminary * **Team whiteboarding** where multiple collaborators need to contribute simultaneously on a shared canvas * **Developer workflows** that rely on Mermaid syntax for text-based diagram generation alongside visual editing * **Rapid iteration** where diagrams change frequently and you need a low-friction editing experience Excalidraw's strength is its accessibility. Team members who are not diagramming experts can jump in and create meaningful visuals without learning a complex tool. The hand-drawn style removes the pressure to produce pixel-perfect output, which encourages more people to participate in visual communication. ## When to choose draw\.io[​](#when-to-choose-drawio "Direct link to When to choose draw.io") Choose **draw\.io for Confluence** when your requirements lean toward structure and formality: * **UML diagrams** (class, sequence, activity, use case) that need to follow strict notation standards * **BPMN process models** for business process documentation and compliance * **Network diagrams** with precise topology layouts, IP addressing, and equipment labels * **Org charts and hierarchy diagrams** where automatic layout and consistent spacing matter * **Cross-functional flowcharts** (swimlane diagrams) that require aligned lanes and standardized symbols * **Compliance and audit documentation** where diagrams need to look polished and follow organizational standards draw\.io's strength is its rigor. The tool enforces visual consistency through grid alignment, snapping, and structured shape libraries, which produces diagrams that look professional and standardized. For teams producing documentation that will be reviewed by external stakeholders, regulators, or auditors, this consistency is valuable. ## A third option: Diagram Duo for Confluence[​](#a-third-option-diagram-duo-for-confluence "Direct link to A third option: Diagram Duo for Confluence") If you want **both freeform sketching and structured diagramming in a single macro**, [Diagram Duo for Confluence](/docs/diagram-duo-for-confluence/usage.md) combines an Excalidraw visual canvas with a Mermaid code editor. Instead of choosing between drawing styles, your team can: * **Sketch ideas visually** on the Excalidraw canvas during whiteboard sessions * **Switch to Mermaid code** to formalize parts of the diagram in versionable text * **Work in either mode** on the same diagram without switching between apps Diagram Duo eliminates the need to install and license two separate diagramming tools. It is particularly useful for engineering teams that want the flexibility of both visual and text-based workflows in one place. ## Related resources[​](#related-resources "Direct link to Related resources") * [Excalidraw Plus for Confluence](/apps/excalidraw-plus-for-confluence.md) -- documentation and usage guide * [Mermaid Plus Diagrams & AI Agent for Confluence](/apps/mermaid-plus-for-confluence.md) -- dedicated Mermaid editor with 30 diagram types * [Diagram Duo for Confluence](/apps/excalidraw-mermaid-diagrams-for-confluence.md) -- combined Excalidraw + Mermaid editor in one macro * [Confluence diagram tools compared](/blog/confluence-diagram-tools-comparison.md) -- Mermaid vs Excalidraw vs Graphviz * [How to create flowcharts in Confluence](/blog/create-flowcharts-confluence.md) -- step-by-step guide with three methods Try Excalidraw Diagrams plus Whiteboards for Jira Add a freehand drawing canvas to every Jira issue, with 229 shape libraries — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/2139233994/excalidraw-diagrams-plus-whiteboards-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=excalidraw-diagrams-plus-whiteboards-for-jira) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [excalidraw](/blog/tags/excalidraw.md) * [confluence](/blog/tags/confluence.md) * [diagrams](/blog/tags/diagrams.md) * [comparison](/blog/tags/comparison.md) --- # Export Jira Issues to CSV/Excel: Common Problems & FAQ April 21, 2026 · 11 min read [NGPilot](https://ngpilot.com) Who should read this * **Jira admins** exporting issues for migration, reporting, or compliance * **Engineering/ops leads** hitting timeouts or field mismatches on large exports * **Anyone** who needs >1,000 issues out of Jira in one go What you'll learn 1. How to fix CSV field mismatches, encoding errors, and date formats 2. How to export custom fields and >1,000 issues without timeouts 3. What to do with attachments (they don't come with a CSV) 4. How to automate recurring exports Exporting Jira issues sounds simple until you try it at scale. Jira's native CSV export works for small result sets, but teams quickly hit field mismatches, encoding errors, custom field headaches, timeouts on large projects, and the question of what to do with attachments. This FAQ walks through each common problem and the practical fix — most of which [Simple Bulk Issues Excel CSV Export for Jira](https://marketplace.atlassian.com/apps/3818473739/simple-bulk-issues-excel-csv-export-for-jira) handles out of the box. ## Why do CSV fields mismatch after importing Jira exports?[​](#why-do-csv-fields-mismatch-after-importing-jira-exports "Direct link to Why do CSV fields mismatch after importing Jira exports?") Field mismatches are the most frequent complaint when teams move Jira data into another system. The root cause is almost always a difference in column order, delimiter settings, or date formatting between what Jira produces and what the target application expects. When Jira generates a CSV file, the columns appear in a fixed order determined by the fields visible in your issue navigator view. If the receiving tool expects columns in a different order, rows shift and data lands in the wrong place. Always verify that header rows are included in the export so the target system can map columns by name rather than position. Delimiters matter too: Jira uses commas by default, but some European locale settings in Excel interpret commas as decimal separators, causing the file to parse incorrectly. In those cases, switching to a semicolon delimiter or using an Excel (XLSX) export avoids the problem entirely. Date formats are another common source of trouble. Jira can output dates in several formats depending on your instance settings. For maximum compatibility, use ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) so that every downstream system interprets timestamps consistently regardless of locale. Simple Bulk Issues Export gives you explicit control over which fields to include and their column order, so you can match the schema your target system expects without manual rearranging after the fact. ## How do I handle special characters in Jira CSV exports?[​](#how-do-i-handle-special-characters-in-jira-csv-exports "Direct link to How do I handle special characters in Jira CSV exports?") Jira issues often contain special characters, especially in summary and description fields where users paste error messages, code snippets, or text with non-ASCII characters. If encoding is not handled correctly, these characters appear corrupted after import. The solution is to ensure your CSV file uses UTF-8 encoding throughout the export and import pipeline. UTF-8 covers virtually every character in use and is the de facto standard for data interchange. Most modern tools default to UTF-8, but older versions of Microsoft Excel sometimes assume a Windows-specific code page (such as Windows-1252) when opening CSV files. To avoid this, open the file through Excel's "Data > From Text/CSV" wizard, which lets you explicitly select UTF-8 before loading. Within the CSV itself, any field that contains a comma, double quote, or line break must be enclosed in double quotes per RFC 4180. If a field value itself contains double quotes, those quotes are escaped by doubling them (`""`). Most export tools handle this automatically, but it is worth spot-checking a few rows after export to confirm. Simple Bulk Issues Export generates UTF-8 encoded files by default and properly quotes fields that contain commas, line breaks, and special characters, so descriptions and comments survive the round trip intact. ## Can I export Jira custom fields to Excel or CSV?[​](#can-i-export-jira-custom-fields-to-excel-or-csv "Direct link to Can I export Jira custom fields to Excel or CSV?") Custom fields are where Jira data gets organization-specific. Every company configures its own set of custom fields for sprint names, story point estimates, business units, customer segments, and dozens of other domain-specific attributes. Exporting them correctly is critical for reporting and migration. The challenge is that some export tools only include standard Jira fields by default and require explicit mapping to pull in custom fields. Even when custom fields are included, the export sometimes uses the human-readable display name (for example, "Story Points") instead of the raw field key (for example, `customfield_10002`). The display name can change between Jira instances or even between projects, but the field key is stable and unique, making it far more reliable when importing data into another system. If you are migrating between two Jira instances, check whether the custom field keys match. If they differ, you will need a mapping table to translate old keys to new ones during import. For reporting purposes, the display name is usually fine as long as you know which field it refers to. Simple Bulk Issues Export makes custom fields available in the field selection panel (marked with a "Custom" label), so you can include them alongside system fields. The "Select All" button includes all custom fields, or you can pick specific ones. The display name is used for column headers, giving you readable output for reports and downstream tools. ## Why do large Jira exports time out?[​](#why-do-large-jira-exports-time-out "Direct link to Why do large Jira exports time out?") Jira's built-in export functions are designed for interactive use and enforce limits on result set size. When you try to export thousands of issues at once, the request can exceed server timeouts or memory limits, resulting in an incomplete file or an error page. The most effective workaround is to split your export into smaller batches. You can do this by scoping your JQL query to a specific date range (for example, `created >= "2025-01-01" AND created <= "2025-03-31"`), by project, or by issue type. Export each batch separately and combine the files afterward. This approach also makes it easier to retry a single batch if something goes wrong, rather than starting the entire export over. Another strategy is to reduce the number of fields included in each export. Every additional column increases processing time and file size. Export only the fields you actually need, and omit verbose fields like description or comments unless they are required. Simple Bulk Issues Export handles large exports up to 5,000 issues per run. For exports beyond that limit, split your query into smaller batches by date range or project. The app processes field selection and formatting so the downloaded file is ready to use in Excel, Google Sheets, or any reporting tool. ## Can I include attachments when exporting Jira issues?[​](#can-i-include-attachments-when-exporting-jira-issues "Direct link to Can I include attachments when exporting Jira issues?") Attachments are a special case because CSV and Excel files are purely text-based formats. There is no standard way to embed binary files like images, PDFs, or documents inside a spreadsheet cell. This means attachments require a separate export step. The recommended approach is a two-part process. First, export your issues to CSV or Excel with all the metadata you need. Then, use Simple Bulk Attachment Downloader to export all attachments in bulk, organized by issue key. The attachment downloader preserves the folder structure and file names, making it straightforward to match attachments back to their parent issues. If you only need a reference to the attachments rather than the files themselves, include the attachment URL column in your issue export. This column contains a direct link to each attachment in Jira, which is useful for reports and dashboards where clickable references are sufficient. For teams migrating to a new tool, the combination of a full issue export plus a separate attachment download gives you everything needed to reconstruct the issue history in the target system. ## How do I automate recurring Jira issue exports?[​](#how-do-i-automate-recurring-jira-issue-exports "Direct link to How do I automate recurring Jira issue exports?") Manual exports are fine for one-time tasks, but teams that run weekly status reports, monthly compliance audits, or continuous data synchronization need an automated workflow. The starting point is a saved JQL filter. Define the exact query that captures the issues you need, save it with a descriptive name, and reuse it every time you export. This ensures consistency between runs and eliminates the risk of accidentally changing the scope. For full automation, the Jira REST API accepts JQL queries and returns results in JSON format, which you can convert to CSV or load directly into a database. Wrap the API call in a script and schedule it with cron (on Linux/macOS), Jenkins, or a cloud automation tool like Zapier or AWS Lambda. Include error handling in your script so you are notified if the API returns an error or if the result set is unexpectedly empty. Simple Bulk Issues Export works with any saved JQL filter loaded in Jira's issue navigator. Load your saved filter in the navigator, then open the export dialog to export the filtered results. This ensures you always export the same issue set without rewriting the query each time. ## Jira export format comparison[​](#jira-export-format-comparison "Direct link to Jira export format comparison") Choosing between CSV and Excel (XLSX) depends on your use case. The table below compares the two formats across the features that matter most for Jira exports. | Feature | CSV | Excel (XLSX) | | ----------------------- | ----------------------------------------------------------------- | ------------------------------------------------- | | File size | Small, plain text | Larger, compressed XML | | Encoding | Must specify UTF-8 explicitly | UTF-8 by default | | Maximum rows | No hard limit (practical limit around 1 million for most editors) | 1,048,576 rows per sheet | | Rich formatting | Not supported | Supported (fonts, colors, conditional formatting) | | Multi-sheet | Not supported | Supported | | Special characters | Requires proper quoting | Handled natively | | Date handling | Locale-dependent parsing | Stored as serialized datetime | | Tool compatibility | Universal (any text editor, database loader, script) | Requires Excel or compatible application | | Automation friendliness | Easy to generate and parse in scripts | Requires a library (openpyxl, Apache POI) | | Cell size limit | Practical limit around 32,767 characters | 32,767 characters per cell | If you need maximum compatibility and plan to import the data into a database, scripts, or a BI tool, CSV is the better choice. If you are producing reports for stakeholders who expect formatted spreadsheets with multiple tabs, Excel is worth the extra overhead. ## Field mapping guide[​](#field-mapping-guide "Direct link to Field mapping guide") When exporting Jira issues, it helps to know the standard field names Jira uses in export files. The table below maps common Jira fields to their export column names so you can verify your data after export or configure field selection before running one. | Jira field | Export column name | Notes | | ------------------ | ----------------------------------- | ---------------------------------------------- | | Issue Key | `Issue key` | Unique identifier, format `PROJECT-123` | | Summary | `Summary` | Issue title | | Status | `Status` | Current workflow status | | Issue Type | `Issue Type` | Bug, Story, Task, Epic, etc. | | Priority | `Priority` | Highest, High, Medium, Low, Lowest | | Assignee | `Assignee` | Display name of the assigned user | | Reporter | `Reporter` | Display name of the user who created the issue | | Created Date | `Created` | ISO 8601 timestamp | | Updated Date | `Updated` | ISO 8601 timestamp | | Resolution Date | `Resolution Date` | Empty if unresolved | | Due Date | `Due Date` | Date only, no time component | | Description | `Description` | May contain wiki markup or HTML | | Labels | `Labels` | Semicolon-delimited in CSV | | Components | `Components` | Semicolon-delimited in CSV | | Fix Version/s | `Fix Version/s` | Semicolon-delimited if multiple | | Sprint | `Sprint` | Sprint name and ID | | Story Points | `Story Points` | Numeric, stored as a custom field | | Original Estimate | `Original Estimate` | Duration in seconds or formatted string | | Time Spent | `Time Spent` | Duration in seconds or formatted string | | Remaining Estimate | `Remaining Estimate` | Duration in seconds or formatted string | | Attachments | `Attachments` | Count or semicolon-delimited file names | | Comment | `Comment` | All comments, may be multiline | | Custom fields | `customfield_NNNNN` or display name | Naming depends on export tool settings | Custom fields deserve special attention. In Jira's API and database, each custom field has a unique key in the format `customfield_` followed by a five-digit number. Some export tools use this key as the column header, while others use the display name configured in your instance. If you are automating imports or building a data pipeline, prefer the raw field key for stability. If you are sharing the file with business users, the display name is more readable. ## Related resources[​](#related-resources "Direct link to Related resources") * [Simple Bulk Issues Excel CSV Export](/apps/simple-bulk-issues-excel-csv-export-for-jira.md) * [Export Jira issues to Excel/CSV](/blog/export-jira-issues-to-excel.md) — step-by-step guide * [Bulk download Jira attachments](/blog/bulk-download-jira-attachments.md) — download attachments alongside exports * [Bulk operations FAQ](/blog/faq-bulk-operations-jira.md) — general bulk workflow tips Try Modern FAQ for Confluence Accordion-style FAQ sections with drag-and-drop reordering and two themes — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236739/modern-faq-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-faq-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [jira](/blog/tags/jira.md) * [export](/blog/tags/export.md) * [csv](/blog/tags/csv.md) * [excel](/blog/tags/excel.md) --- # Confluence Custom Fonts FAQ: Change Fonts, Setup & Alternatives May 2, 2026 · 15 min read [NGPilot](https://ngpilot.com) Confluence ships with a single default font family and limited formatting options. For teams that care about brand consistency, readability, or simply making their documentation look polished, that constraint becomes obvious fast. Custom typography transforms a generic Confluence space into something that feels intentional and professional, whether it is an internal knowledge base, a client-facing project portal, or a team landing page. But choosing the right approach to custom fonts in Confluence is not always straightforward. The Atlassian Marketplace offers several font apps with different feature sets, pricing models, and limitations. Some support only the Google Fonts library. Others let you upload proprietary brand fonts. A few are free, but come with reliability trade-offs. This FAQ answers the most common questions teams ask when evaluating Confluence font apps, compares the leading options side by side, and provides practical recommendations for getting the best typography setup for your workspace. ## What is the best Google Fonts app for Confluence?[​](#what-is-the-best-google-fonts-app-for-confluence "Direct link to What is the best Google Fonts app for Confluence?") Google Fonts for Confluence by NGPILOT is purpose-built for teams that want direct access to the full Google Fonts catalog inside Confluence Cloud. It connects to the official Google Fonts library of over 1,942 font families and exposes them through a searchable browser with live preview right inside your Confluence space. The key features that distinguish it from other font apps on the Marketplace are: * **Live preview** -- See exactly how a font will look on your Confluence pages before you apply it. The preview renders your actual content with the selected font, size, color, and alignment, so there are no surprises after publishing. * **Macro-based insertion** -- Type `/google fonts` on any page to open the configuration panel. Select your font family, variant, size, color, and alignment, then save to insert the styled text block. * **Performance-optimized loading** -- All fonts are loaded from the Google Fonts CDN with `font-display: swap`, which means text is always visible immediately using a system font fallback, then swapped to the custom font once it finishes downloading. * **Variable font support** -- Variable fonts pack multiple weights into a single file, reducing total download size compared to loading static weight files individually. * **Fuzzy search** -- Type part of a font name and find it instantly, rather than scrolling through a dropdown with nearly two thousand options. For teams that want a reliable, well-maintained Confluence font app with a modern feature set, Google Fonts for Confluence is the strongest option currently available on the Atlassian Marketplace. ## Are there free alternatives to Google Fonts for Confluence?[​](#are-there-free-alternatives-to-google-fonts-for-confluence "Direct link to Are there free alternatives to Google Fonts for Confluence?") The Google Fonts library itself is entirely free and open-source. Every font is released under the SIL Open Font License or the Apache License, both of which permit free commercial use with no restrictions. You will never pay licensing fees for the font files themselves, regardless of how many users or spaces you have. When it comes to Confluence apps that apply those fonts to your workspace, the pricing landscape looks different: * **Fonts for Confluence by Skanda Atlassian Apps** is free for all instance sizes. It has the largest install base on the Marketplace (222 installs as of April 2026) but carries a 1.5-star rating based on user reviews that report broken access controls and usability issues. It is free, but the reliability concerns are worth noting. * **Google Fonts for Confluence by NGPILOT** offers a free tier for teams up to 10 users, with paid plans for larger instances. It includes live preview, dark mode support, and fuzzy search -- features that the free alternatives do not offer. * **Custom Fonts Pro by Aptify Tech** is free for up to 10 users, then paid. It supports Google Fonts and adds visual effects like text shadows and gradients, though it does not include live preview or font search. If your primary constraint is budget and you have a small team, both Google Fonts for Confluence and Custom Fonts Pro offer meaningful free tiers. If you want completely free software regardless of team size, Fonts for Confluence by Skanda is the only option, but evaluate the reviews carefully before relying on it for production documentation. ## Can I use custom font files instead of Google Fonts in Confluence?[​](#can-i-use-custom-font-files-instead-of-google-fonts-in-confluence "Direct link to Can I use custom font files instead of Google Fonts in Confluence?") This depends on which font app you choose. There are two distinct approaches to custom typography in Confluence: **CDN-hosted fonts** (Google Fonts and similar). Apps like Google Fonts for Confluence load fonts from the Google Fonts CDN. This approach has significant advantages: fonts are served from a globally distributed content delivery network, browsers may already have popular font families cached from other websites, and you never need to manage font file hosting yourself. The trade-off is that you are limited to fonts available in the Google Fonts catalog. **Self-hosted font files** (WOFF, WOFF2, TTF). Some apps, including Custom Fonts for Confluence by Canary Apps and Webfonts for Confluence by TNG, allow you to upload your own font files or reference custom URLs. This is the right approach if your organization uses proprietary brand fonts that are not available on Google Fonts -- for example, a custom corporate typeface or a licensed font from a commercial foundry like Hoefler & Co, Monotype, or Dalton Maag. Google Fonts for Confluence focuses exclusively on the Google Fonts library. If your brand guidelines specify proprietary fonts that are not available on Google Fonts, you should look for an app that supports custom file upload. However, for the vast majority of teams, the 1,942+ families available on Google Fonts provide more than enough variety to establish a distinctive visual identity. ## How much does Google Fonts for Confluence cost?[​](#how-much-does-google-fonts-for-confluence-cost "Direct link to How much does Google Fonts for Confluence cost?") Google Fonts for Confluence follows the standard Atlassian Marketplace pricing model, with costs that scale based on your Confluence instance size. The app offers a free trial so you can evaluate the full feature set before committing to a purchase. The Google Fonts library itself is always free. There are no per-seat font licensing charges, no download limits, and no restrictions on the number of spaces or pages where you apply custom fonts. The cost of the app covers the integration layer -- the font browser, live preview, macro-based styled text insertion, and performance optimization -- not the font files. For current pricing details, visit the Google Fonts for Confluence listing on the Atlassian Marketplace. Pricing is displayed based on your Confluence edition and user tier before you install. To put the cost in perspective: even the paid tiers are typically a fraction of what organizations spend on design tools, brand assets, or documentation platforms. If custom typography saves your team time on formatting or improves the professionalism of client-facing documentation, the return on investment is straightforward. ## Does Confluence have built-in custom font support?[​](#does-confluence-have-built-in-custom-font-support "Direct link to Does Confluence have built-in custom font support?") No. Confluence's native editor provides a single default font family, a limited set of heading sizes (H1 through H6), and basic bold, italic, and underline formatting. There is no built-in mechanism to change the typeface, apply custom font families, or configure typography at the space or page level. This is a deliberate design choice by Atlassian. Standardizing on a single font family across all Confluence instances ensures consistency and reduces the surface area for formatting bugs. But it also means that teams with strong brand guidelines or specific accessibility requirements need to look beyond the default editor. The only way to use custom fonts in Confluence is through a Marketplace app. These apps take different approaches: some inject custom CSS globally, while others provide macros you insert on individual pages. Google Fonts for Confluence uses a macro-based approach. You insert the macro on a page using the `/google fonts` slash command, configure your font family, variant, size, color, and alignment in the configuration panel with live preview, then save to insert the styled text. The app loads the selected Google Font from the Google Fonts CDN and renders your text inline on the page. You never need to edit stylesheets, manage @font-face declarations, or handle font file hosting yourself. ## Can I use different fonts in different Confluence spaces?[​](#can-i-use-different-fonts-in-different-confluence-spaces "Direct link to Can I use different fonts in different Confluence spaces?") Yes. Google Fonts for Confluence uses a macro-based approach, which means you insert and configure styled text on a per-page basis. You can use different fonts in different spaces -- or on different pages within the same space -- by inserting the macro with different font selections: * **Multi-brand organizations** -- A company with several sub-brands can use different typefaces in each brand's Confluence space, reinforcing visual identity without cross-contamination. * **Client-facing vs. internal spaces** -- External project portals can use polished, branded typography while internal documentation uses a plainer, faster-loading font selection. * **Departmental identity** -- Engineering, design, and marketing teams often have distinct visual languages. The macro approach lets each team express that identity within Confluence. To maintain consistency within a space, establish a typography style guide that specifies which fonts team members should use when inserting the macro. This keeps the visual language coherent across pages while still allowing flexibility where needed. ## Comparison: Confluence Font Apps Side by Side[​](#comparison-confluence-font-apps-side-by-side "Direct link to Comparison: Confluence Font Apps Side by Side") The table below compares the leading font apps currently available on the Atlassian Marketplace. Data is based on Marketplace listings as of April 2026. | Feature | Google Fonts for Confluence (NGPILOT) | Fonts for Confluence (Skanda) | Custom Fonts Pro (Aptify Tech) | Custom Fonts (Canary Apps) | Webfonts (TNG) | | ---------------------- | ------------------------------------- | ------------------------------- | ------------------------------ | -------------------------- | ------------------ | | **Hosting** | Confluence Cloud | Confluence Cloud | Confluence Cloud | Confluence Cloud | Data Center only | | **Font library size** | 1,942+ Google Fonts | Google Fonts (count not listed) | 800+ Google Fonts | Custom upload only | Custom URLs | | **Live preview** | Yes | No | No | No | No | | **Font search** | Fuzzy search | No | No | No | No | | **Space-level config** | No (macro-based) | No | No | No | No | | **Variable fonts** | Yes | Not documented | Not documented | Not documented | Not documented | | **Dark mode support** | Auto-adapts | No | No | No | No | | **Visual effects** | No | No | Shadows, gradients | No | Text shadow | | **Custom font upload** | No | No | No | Yes | Yes | | **Pricing model** | Free to 10 users, then paid | Free | Free to 10 users, then paid | From $50/year | From $10/year (DC) | | **User rating** | New (no reviews yet) | 1.5/5 (4 reviews) | No reviews | No reviews | 4.0/5 (1 review) | | **Last updated** | 2026 | 2025 | 2026 | 2024 | 2026 | ### Key takeaways from the comparison[​](#key-takeaways-from-the-comparison "Direct link to Key takeaways from the comparison") **Google Fonts for Confluence (NGPILOT)** leads on feature depth for Cloud instances. The combination of live preview, fuzzy search, macro-based styled text insertion, and variable font support makes it the most capable option for teams that want a polished typography experience. The free tier for up to 10 users makes it accessible for small teams. **Fonts for Confluence (Skanda)** has the largest install base but the lowest rating. It is the only completely free option with no user limits, which explains its install count. However, the 1.5-star average and user reports of broken access controls suggest reliability issues that are worth weighing carefully. **Custom Fonts Pro (Aptify Tech)** is the only Cloud app that adds visual effects like text shadows and gradients. If decorative text styling is important to your use case, this is worth considering. It lacks live preview and font search, though. **Custom Fonts (Canary Apps)** is the only option that supports uploading your own font files (WOFF, WOFF2, TTF) without relying on the Google Fonts library. If your brand uses a proprietary typeface, this is your path. However, it was last updated in 2024, which raises questions about ongoing maintenance. **Webfonts (TNG)** is the strongest option for Data Center deployments, but it does not support Cloud at all. If you are on Confluence Cloud, this app is not available to you. ## Recommended font pairings for Confluence[​](#recommended-font-pairings-for-confluence "Direct link to Recommended font pairings for Confluence") Choosing individual fonts is only half the challenge. Pairing fonts that work harmoniously together is where good typography becomes great typography. Here are five pairings that perform well in Confluence spaces, balancing readability, visual hierarchy, and page weight. ### 1. Inter (body) + Merriweather (headings)[​](#1-inter-body--merriweather-headings "Direct link to 1. Inter (body) + Merriweather (headings)") Inter is a highly readable sans-serif designed specifically for screen use. Its tall x-height and open apertures make it one of the best body text fonts available at the sizes typically used in documentation. Merriweather adds editorial gravitas to headings with its serif construction, giving your space a professional, slightly formal tone. Both families offer variable font versions, keeping the total download payload small. This pairing works particularly well for corporate knowledge bases and technical documentation. ### 2. Roboto (body) + Playfair Display (headings)[​](#2-roboto-body--playfair-display-headings "Direct link to 2. Roboto (body) + Playfair Display (headings)") Roboto is one of the most widely cached fonts on the internet. Because it is the default system font on Android and is used across Google's product suite, there is a strong chance your users already have it cached in their browser from visiting other websites. This means zero additional download time for the body font in many cases. Playfair Display gives headings a sophisticated, high-contrast serif appearance that pairs well with Roboto's clean neutrality. This combination is effective for client-facing project spaces and marketing documentation. ### 3. Source Sans 3 (body) + Source Serif 4 (headings)[​](#3-source-sans-3-body--source-serif-4-headings "Direct link to 3. Source Sans 3 (body) + Source Serif 4 (headings)") Both fonts come from Adobe's Source family, which means they share underlying proportions, stroke widths, and design philosophy. This shared DNA ensures visual harmony without requiring any manual adjustment. Source Sans 3 is optimized for body text readability, while Source Serif 4 brings a refined serif character to headings. Both families support a wide range of Unicode characters and OpenType features, making this a strong choice for international teams that need consistent typography across Latin, Cyrillic, and Greek scripts. ### 4. Nunito Sans (body) + Nunito (headings)[​](#4-nunito-sans-body--nunito-headings "Direct link to 4. Nunito Sans (body) + Nunito (headings)") Nunito Sans and Nunito share the same rounded geometric foundation, giving your Confluence space a friendly and approachable visual tone. The subtle contrast between Nunito Sans' lighter stroke weights for body text and Nunito's slightly rounder terminals for headings creates clear visual hierarchy without any jarring transitions. This pairing is well suited for internal wikis, onboarding documentation, and team spaces where you want the tone to feel welcoming rather than formal. ### 5. IBM Plex Sans (body) + IBM Plex Mono (code)[​](#5-ibm-plex-sans-body--ibm-plex-mono-code "Direct link to 5. IBM Plex Sans (body) + IBM Plex Mono (code)") If your Confluence space is heavily technical -- API references, runbooks, architecture decision records -- this pairing keeps everything in the IBM Plex superfamily. IBM Plex Sans is a clean, highly legible sans-serif that works well for both body text and headings. IBM Plex Mono handles code blocks, inline code, and terminal output with consistent character widths and clear differentiation between easily confused characters (0/O, 1/l/I). Using two variants from the same family ensures that headings, body text, and code blocks feel cohesive rather than competing for attention. ## Choosing the right font app for your team[​](#choosing-the-right-font-app-for-your-team "Direct link to Choosing the right font app for your team") The best font app for your Confluence instance depends on three factors: your hosting environment, your typography requirements, and your budget. **If you are on Confluence Cloud** and want the most feature-complete Google Fonts integration, Google Fonts for Confluence by NGPILOT is the strongest choice. Live preview, fuzzy search, macro-based styled text insertion with configurable font family, variant, size, color, and alignment, variable font support, and automatic dark mode adaptation give you the most control over your typography with the least manual effort. **If you need proprietary brand fonts** that are not available on Google Fonts, look at Custom Fonts for Confluence by Canary Apps (for custom file upload) or Webfonts for Confluence by TNG (for custom URL references). Keep in mind that TNG's app is Data Center only. **If budget is your primary constraint**, Fonts for Confluence by Skanda is free for all instance sizes. Read the user reviews carefully before committing, and test it on a non-critical space first. **If you want decorative text effects** like shadows and gradients alongside basic font changes, Custom Fonts Pro by Aptify Tech is the only Cloud app that offers these features. ## Performance considerations[​](#performance-considerations "Direct link to Performance considerations") Regardless of which font app you choose, the same performance principles apply: * **Limit your font families to two or three.** One for headings, one for body text, and optionally one for code blocks. Every additional font family adds HTTP requests and download weight. * **Use only the weights you need.** If you only use regular (400) and bold (700), do not load light (300), medium (500), or extra-bold (800). Audit your font configuration and remove unused weights. * **Prefer variable fonts.** A single variable font file covering all weights is often smaller than two separate static weight files. Google Fonts for Confluence supports variable fonts natively. * **Test on slow connections.** Use your browser's network throttling tools to simulate a 3G connection and verify that your Confluence pages remain readable while fonts load. The `font-display: swap` strategy used by Google Fonts for Confluence ensures text is always visible during loading, but it is still worth confirming the experience on slow networks. For a deeper dive into font performance topics, including caching behavior, fallback strategies, and request optimization, see our dedicated [Google Fonts Performance FAQ](/blog/faq-google-fonts-performance.md). ## Related resources[​](#related-resources "Direct link to Related resources") * [Google Fonts for Confluence](/apps/google-fonts-for-confluence.md) -- full documentation and configuration guide * [How to Configure Google Fonts in Confluence](/blog/configure-google-fonts-confluence.md) -- step-by-step setup walkthrough * [Google Fonts Performance & FAQ](/blog/faq-google-fonts-performance.md) -- detailed performance analysis and optimization tips * [Google Fonts for Confluence -- Which Typography App?](/blog/google-fonts-confluence-custom-typography.md) -- in-depth comparison of all Confluence font apps on the Marketplace Try Google Fonts for Confluence 1,942+ Google Font families with live preview, custom size/color/alignment — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236413/google-fonts-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=google-fonts-for-confluence) ## Related guides * [Can You Change the Font in Confluence? Custom Options](/blog/confluence-default-font-change-font.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [google-fonts](/blog/tags/google-fonts.md) * [confluence](/blog/tags/confluence.md) * [typography](/blog/tags/typography.md) * [fonts](/blog/tags/fonts.md) --- # Google Fonts for Confluence: Performance Impact & FAQ April 21, 2026 · 10 min read [NGPilot](https://ngpilot.com) Custom typography is one of the most effective ways to reinforce brand identity inside Confluence. When every team member opens a space and immediately recognizes the visual language of your organization, documentation feels less like a generic wiki and more like a polished internal product. Google Fonts for Confluence brings that capability directly into your workspace, but teams often ask a reasonable follow-up question: **what does adding external fonts do to page performance?** This FAQ covers the most common concerns around font loading speed, caching behavior, fallback strategies, and practical tips for keeping your Confluence instance fast while still looking great. ## Do Google Fonts slow down Confluence page loading?[​](#do-google-fonts-slow-down-confluence-page-loading "Direct link to Do Google Fonts slow down Confluence page loading?") Adding external font resources does introduce additional HTTP requests, and each font family and weight you load is a separate network round trip. However, the real-world impact depends heavily on how many fonts you load and how you configure them. Google Fonts for Confluence loads all fonts from the official Google Fonts CDN (`fonts.googleapis.com` and `fonts.gstatic.com`), which is one of the most widely distributed content delivery networks in the world. Responses are compressed, cacheable, and served from edge locations close to your users. The app also uses `font-display: swap` on every font face it declares. This means that when a user opens a Confluence page, the browser renders text immediately using a system font fallback, then swaps in the custom Google Font once the file has finished downloading. Your users will never stare at a blank page waiting for typography to load. The visible text during loading ensures that content is always readable, even on slow connections. To keep the performance footprint low, limit your selection to two or three font families and only include the weights you actually use. A typical setup might be one weight for headings and one for body text. Every additional weight or style you enable adds another file the browser must download, so being selective pays off. ## How can I reduce Google Fonts request size in Confluence?[​](#how-can-i-reduce-google-fonts-request-size-in-confluence "Direct link to How can I reduce Google Fonts request size in Confluence?") Request size is determined by the number of character subsets, weights, and styles you load. Google Fonts for Confluence gives you a live preview of every font before you apply it, so you can evaluate both the visual appearance and the likely performance impact before committing to a font stack. Here are the most effective strategies for keeping request sizes small. **Choose variable fonts where possible.** Variable fonts pack multiple weights and widths into a single file. Instead of downloading separate 400-weight and 700-weight files, you download one file and the browser interpolates between axes. Google Fonts has been adding variable font versions for many popular families, and Google Fonts for Confluence supports variable font rendering. This can cut your total font payload in half compared to loading static weights individually. **Limit weights and styles.** If you only need regular (400) and bold (700) weights, do not also load light (300) or extra-bold (800). The same applies to italic variants. Google Fonts for Confluence lets you pick exactly which weights to include, so audit your selection and remove anything your space does not use. **Preview before you apply.** The live preview feature is not just about aesthetics. It lets you load a font in context and see whether the visual difference justifies the performance cost. Sometimes a font looks excellent in a standalone specimen but loses clarity at small sizes inside Confluence tables or code blocks. Previewing helps you catch these issues before they affect every page in your space. ## Are Google Fonts cached across different websites?[​](#are-google-fonts-cached-across-different-websites "Direct link to Are Google Fonts cached across different websites?") Yes, and this is one of the underappreciated advantages of using the official Google Fonts CDN. Browsers cache font files by their full URL. Because millions of websites load fonts from `fonts.gstatic.com`, there is a good chance that your users already have popular families like Roboto, Open Sans, or Lato cached locally from visiting other sites. When a user opens your Confluence space, the browser may not need to make a network request at all for those fonts. That said, caching is per variant. A browser that has cached Roboto Regular (400) will still need to download Roboto Bold (700) if it has not encountered that variant before. Different weights, different styles (italic vs. normal), and different Unicode subsets are all separate cache entries. Google Fonts for Confluence loads fonts through the standard Google Fonts API URLs, so your users benefit from this shared caching ecosystem directly. The Google Fonts CDN also sets aggressive cache-control headers. Once a font file is downloaded, the browser will typically cache it for a very long time, which means repeat visits to your Confluence pages will not trigger additional font downloads at all. ## What happens when Google Fonts fail to load in Confluence?[​](#what-happens-when-google-fonts-fail-to-load-in-confluence "Direct link to What happens when Google Fonts fail to load in Confluence?") Network issues, corporate firewalls, and CDN outages can all prevent external fonts from loading. Google Fonts for Confluence handles this gracefully by declaring a system font fallback in every `font-face` rule. When the Google CDN is unreachable, the browser simply uses the fallback font stack and your Confluence pages remain fully readable. This fallback behavior is different from the older `font-display: auto` or `font-display: block` approaches, which could cause a flash of invisible text (FOIT) where the browser hides content for up to three seconds while waiting for the font file. Because Google Fonts for Confluence uses `font-display: swap`, text is always visible immediately. If the custom font never loads at all, the fallback font is already doing its job and the user experience is uninterrupted. For organizations that operate behind strict firewalls, this fallback mechanism is essential. Even if your security team blocks external CDN requests entirely, Confluence pages will render cleanly with system fonts. The typography will not match your brand guidelines, but no content will be lost or hidden. ## Are Google Fonts free to use in Confluence?[​](#are-google-fonts-free-to-use-in-confluence "Direct link to Are Google Fonts free to use in Confluence?") Yes. Every font hosted on Google Fonts is released under an open-source license, typically the SIL Open Font License (OFL) or the Apache License. Both licenses permit free commercial use, modification, and redistribution. You can use any Google Font in your Confluence workspace without paying licensing fees or worrying about legal compliance. Google Fonts for Confluence loads fonts directly from the official Google Fonts API at no additional cost. The app itself is a Confluence add-on, but the font files themselves are always free. There are no per-seat font licensing charges, no download limits, and no restrictions on the number of spaces or pages where you apply custom fonts. If your organization has specific compliance requirements around open-source software, you can review the license for each font on the Google Fonts website. The license information is displayed on every font's detail page, so you can confirm compliance before enabling a font in your Confluence instance. ## What are best practices for using Google Fonts in Confluence?[​](#what-are-best-practices-for-using-google-fonts-in-confluence "Direct link to What are best practices for using Google Fonts in Confluence?") After helping hundreds of teams configure custom typography in their Confluence workspaces, a few clear patterns have emerged. Following these practices will help you get the most visual impact with the least performance overhead. **Restrict fonts to two or three families.** Google Fonts for Confluence is a macro that inserts styled text on individual pages, so visual consistency depends on your team reusing the same font choices across pages. Agree on a small set of fonts at the team level and apply them consistently. A common and effective pattern is one font for headings, one for body text, and optionally one monospace font for code blocks. Going beyond three families rarely improves the reading experience and significantly increases page weight. **Use live preview to test readability.** Fonts that look beautiful in a specimen sheet can perform poorly at the sizes used inside Confluence tables, macros, and inline elements. The live preview feature in the macro configuration panel lets you see exactly how a font will look in context before you commit to it. **Audit your macros.** Because each Google Fonts macro instance loads its own font variant, having many macros with different font families or weights on a single page increases the total number of font resources the browser must download. Review your pages periodically and standardize on the fonts and variants your team actually uses. ## Font performance comparison[​](#font-performance-comparison "Direct link to Font performance comparison") The table below shows approximate performance characteristics for different numbers of font families loaded in a typical Confluence space. These figures are based on average Google Fonts file sizes and assume one regular weight and one bold weight per family. | Configuration | Approx. total size | HTTP requests | Typical load impact | | --------------------------- | ------------------ | ------------- | ------------------------------------------------------------------------------------- | | 1 font family (2 weights) | 40-80 KB | 2-3 | Minimal. Most users will not notice any difference from system fonts. | | 2 font families (4 weights) | 80-160 KB | 4-6 | Low. Still well within acceptable performance thresholds for most teams. | | 3 font families (6 weights) | 120-240 KB | 6-9 | Moderate. Acceptable for most connections, but worth testing on slower networks. | | 5+ font families | 200+ KB | 10+ | High. Noticeable impact on slower connections. Avoid unless you have a strong reason. | Keep in mind that variable fonts can reduce these numbers significantly. A single variable font file covering all weights might be only 50-100 KB, compared to 30-50 KB per static weight file. If your chosen font family offers a variable version, prefer it. ## Recommended font pairings for Confluence[​](#recommended-font-pairings-for-confluence "Direct link to Recommended font pairings for Confluence") Choosing fonts that work well together can be tricky. Here are five pairings that perform well in Confluence spaces, balancing readability, performance, and visual appeal. **1. Inter for body, Merriweather for headings.** Inter is a highly readable sans-serif designed for screen use, and Merriweather adds a touch of editorial gravitas to headings. Both are available as variable fonts, keeping the total payload small. **2. Roboto for body, Playfair Display for headings.** Roboto is one of the most widely cached fonts on the internet, which means many users will already have it in their browser cache. Playfair Display gives headings a sophisticated, high-contrast serif look. **3. Source Sans 3 for body, Source Serif 4 for headings.** This pairing comes from the same type family, ensuring harmonious proportions. Both support a wide range of Unicode characters, making this a strong choice for international teams. **4. Nunito Sans for body, Nunito for headings.** Both fonts share the same rounded geometric foundation, giving your space a friendly and approachable feel. The slight contrast between the sans and the rounded versions creates visual hierarchy without clashing. **5. IBM Plex Sans for body, IBM Plex Mono for code.** If your Confluence space is heavily technical, this pairing keeps everything in the IBM Plex family. The sans-serif works beautifully for body text and headings, while the monospace variant handles code blocks and inline code with consistent spacing and alignment. ## Related resources[​](#related-resources "Direct link to Related resources") * [Google Fonts for Confluence — documentation](/apps/google-fonts-for-confluence.md) * [How to configure Google Fonts in Confluence](/blog/configure-google-fonts-confluence.md) — setup walkthrough * [Enhanced Markdown for Confluence](/apps/enhanced-markdown-for-confluence.md) — pair custom fonts with Markdown Try Google Fonts for Confluence 1,942+ Google Font families with live preview, custom size/color/alignment — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236413/google-fonts-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=google-fonts-for-confluence) ## Related guides * [Can You Change the Font in Confluence? Custom Options](/blog/confluence-default-font-change-font.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [google-fonts](/blog/tags/google-fonts.md) * [confluence](/blog/tags/confluence.md) * [typography](/blog/tags/typography.md) * [performance](/blog/tags/performance.md) --- # Confluence Graphviz Diagrams: DOT Language FAQ & Examples May 2, 2026 · 16 min read [NGPilot](https://ngpilot.com) Graphviz has been the backbone of automated graph visualization for over three decades. Originally developed at AT\&T Labs, it powers dependency graphs in build systems, call graphs in profilers, and database schemas in ORMs -- anywhere that diagrams need to be generated from structured data rather than drawn by hand. Graphviz Charts for Confluence brings that same engine directly into your Confluence pages, letting you write DOT language descriptions and get polished, auto-laid-out diagrams without leaving your wiki. This FAQ answers the most common questions teams ask when getting started with Graphviz Charts for Confluence. Whether you are evaluating the app for the first time, migrating from a manual diagramming tool, or deciding between Graphviz and Mermaid, you will find practical answers below along with copy-paste DOT examples you can try immediately. ## What is Graphviz and how does it work in Confluence?[​](#what-is-graphviz-and-how-does-it-work-in-confluence "Direct link to What is Graphviz and how does it work in Confluence?") Graphviz is an open-source graph visualization software suite that takes text descriptions of graphs and produces diagrams as output. It is not a drawing tool -- you do not drag shapes or connect boxes with a mouse. Instead, you describe the structure of your graph in plain text using the DOT language, and Graphviz's layout algorithms compute where every node and edge should appear. The result is a clean, consistent diagram that scales to hundreds of nodes without manual adjustment. Graphviz Charts for Confluence wraps this engine in a Confluence macro. You insert the macro by typing `/Graphviz Charts for Confluence` in the Confluence editor, write or paste your DOT code into the macro body, and click save. The app renders the diagram inline on the page. You can also click the edit icon on the macro to configure it further, and you can use Confluence's built-in alignment options to position the rendered diagram within the page layout. The app supports Confluence Cloud and Confluence Data Center. Because the DOT code is stored as plain text inside the macro, it is fully version-controlled through Confluence's page history. Every edit to the graph is tracked, and you can diff changes between versions just like any other page content. For the full setup and configuration details, see the [Graphviz Charts for Confluence usage guide](/docs/Graphviz-Charts-for-Confluence/usage.md). ## What is the DOT language and how do I get started?[​](#what-is-the-dot-language-and-how-do-i-get-started "Direct link to What is the DOT language and how do I get started?") DOT is the primary language for describing graphs in Graphviz. It is a declarative, plain-text format where you define nodes, edges, and their properties, and the layout engine handles positioning and routing. Learning DOT takes minutes -- the syntax is intentionally minimal. Here is the smallest possible directed graph: ``` digraph { A -> B -> C } ``` This creates three nodes (`A`, `B`, `C`) connected by directed edges with arrowheads. The `digraph` keyword indicates a directed graph. For undirected graphs (no arrowheads), use `graph` and double-dash edges: ``` graph { A -- B -- C } ``` You can add labels, shapes, and styling attributes to nodes and edges using square brackets: ``` digraph { rankdir=LR Start [label="User Request", shape=box, style=filled, fillcolor="#E8F5E9"] Validate [label="Validate Input", shape=box] Decision [label="Valid?", shape=diamond] Process [label="Process Request", shape=box, style=filled, fillcolor="#E3F2FD"] Error [label="Return Errors", shape=box, style=filled, fillcolor="#FFEBEE"] Start -> Validate -> Decision Decision -> Process [label="Yes"] Decision -> Error [label="No"] } ``` Key DOT syntax elements you will use regularly: * **`digraph`** -- directed graph with arrow-headed edges. Edges use `->`. * **`graph`** -- undirected graph with plain-line edges. Edges use `--`. * **`rankdir`** -- controls layout direction. `TB` (top to bottom, default), `LR` (left to right), `BT` (bottom to top), `RL` (right to left). * **`[label="text"]`** -- sets the display label for a node or edge. Without a label, the node ID is used. * **`[shape=...]`** -- sets node shape. Common values: `box`, `ellipse`, `diamond`, `circle`, `record`, `plaintext`. * **`[style=filled fillcolor="#hex"]`** -- fills the node background with a color. * **`[color="#hex"]`** -- sets the border or edge color. The official DOT language reference is available at [graphviz.org/doc/info/lang.html](https://graphviz.org/doc/info/lang.html), and the Graphviz layout documentation is at [graphviz.org/docs/layouts/](https://graphviz.org/docs/layouts/). ## What types of diagrams can I create with Graphviz Charts?[​](#what-types-of-diagrams-can-i-create-with-graphviz-charts "Direct link to What types of diagrams can I create with Graphviz Charts?") Graphviz is not limited to a single diagram type. Through different graph kinds and layout engines, it covers a wide range of visualization needs. ### Directed graphs (digraph)[​](#directed-graphs-digraph "Direct link to Directed graphs (digraph)") Directed graphs are the most common Graphviz output. Every edge has a direction indicated by an arrowhead, making them ideal for flowcharts, dependency trees, data pipelines, and state machines. The `dot` layout engine (the default) produces ranked, hierarchical layouts that minimize edge crossings and produce clean, top-down or left-right diagrams. ``` digraph dependencies { rankdir=TB node [shape=box, style=rounded] APIGateway [label="API Gateway"] AuthSvc [label="Auth Service"] UserSvc [label="User Service"] OrderSvc [label="Order Service"] DB [label="Database", shape=cylinder] Cache [label="Redis Cache", shape=parallelogram] APIGateway -> AuthSvc APIGateway -> UserSvc APIGateway -> OrderSvc UserSvc -> DB OrderSvc -> DB UserSvc -> Cache OrderSvc -> Cache } ``` This example shows a microservices dependency graph. Notice how the `dot` engine automatically layers the nodes so that dependencies flow downward, making the architecture immediately readable. ### Undirected graphs (graph)[​](#undirected-graphs-graph "Direct link to Undirected graphs (graph)") Undirected graphs use plain lines without arrowheads. They are useful for network topologies, social graphs, relationship maps, and any scenario where directionality does not matter. The `neato` and `fdp` layout engines work well for undirected graphs, producing spring-model layouts that cluster related nodes together. ### Record structures[​](#record-structures "Direct link to Record structures") Graphviz supports record-based node shapes that display fields in a structured, table-like format. This is particularly useful for entity schemas, class diagrams, and data model documentation where you want to show the internal structure of a node. ``` digraph data_model { rankdir=LR node [shape=record] User [label="{User|+ id: int\l+ name: string\l+ email: string\l+ created_at: timestamp\l}"] Order [label="{Order|+ id: int\l+ user_id: int\l+ total: decimal\l+ status: enum\l}"] Product [label="{Product|+ id: int\l+ name: string\l+ price: decimal\l+ stock: int\l}"] User -> Order [label="has many"] Order -> Product [label="contains"] } ``` The `\l` characters in record labels produce left-aligned text within each field row. This DOT code renders three entity boxes with their field lists and relationships -- a format that is immediately recognizable to anyone who has worked with database schemas or UML class diagrams. ### Layout engines[​](#layout-engines "Direct link to Layout engines") Graphviz Charts for Confluence supports the full set of Graphviz layout engines: | Engine | Best for | Layout style | | ------- | -------------------------------- | ---------------------------------------------------- | | `dot` | Hierarchical and directed graphs | Top-down ranked layers (default) | | `neato` | Undirected graphs, spring model | Force-based positioning | | `fdp` | Large undirected graphs | Force-directed placement | | `sfdp` | Very large graphs | Scalable force-directed (handles thousands of nodes) | | `circo` | Circular relationships | Circular arrangement | | `twopi` | Radial layouts | Concentric circles around a root node | Choose the engine that matches your graph structure. For most flowcharts and dependency diagrams, `dot` produces the clearest results. For network topologies with no inherent hierarchy, `neato` or `fdp` often work better. ## How does Graphviz auto-layout compare to manual diagramming?[​](#how-does-graphviz-auto-layout-compare-to-manual-diagramming "Direct link to How does Graphviz auto-layout compare to manual diagramming?") The single biggest advantage Graphviz offers over visual drag-and-drop tools is automatic layout. When you draw a diagram by hand -- whether in Excalidraw, draw\.io, or a desktop application -- you spend significant time positioning nodes, routing edges, and adjusting spacing every time the diagram changes. With Graphviz, you describe the relationships and the engine handles all visual positioning. This matters most when diagrams grow large. A dependency graph with 50 nodes and 80 edges takes hours to lay out manually and is nearly impossible to keep tidy as nodes are added or removed. Graphviz recomputes the layout in milliseconds, producing a consistent, readable diagram every time. Edge crossings are minimized, spacing is uniform, and the hierarchical structure is preserved without manual intervention. Auto-layout also eliminates the "drift" problem that plagues manually maintained diagrams. When different team members edit a drag-and-drop diagram over months, the layout gradually degrades -- nodes get nudged, spacing becomes inconsistent, and the diagram loses its original clarity. With text-based DOT code, the layout is always computed fresh from the current graph definition, so it stays clean regardless of how many people contribute changes. The tradeoff is control. Graphviz decides where nodes go, and you cannot manually override specific positions (though you can influence the layout through `rank` constraints, `group` attributes, and `rankdir` settings). For teams that need pixel-perfect placement -- for example, architecture diagrams that must match a specific visual template -- a visual tool like Excalidraw Plus or Diagram Duo may be more appropriate. ## Can I style and customize Graphviz diagrams in Confluence?[​](#can-i-style-and-customize-graphviz-diagrams-in-confluence "Direct link to Can I style and customize Graphviz diagrams in Confluence?") Graphviz provides extensive styling capabilities through DOT attributes. You can customize nearly every visual aspect of nodes and edges without touching any CSS or external styling. **Node styling.** Control the appearance of individual nodes or set global defaults: ``` digraph { // Global default for all nodes node [shape=box, style="rounded,filled", fillcolor="#F5F5F5", color="#333333", fontname="Helvetica", fontsize=11] // Per-node overrides Start [fillcolor="#4CAF50", fontcolor="white", label="Start"] Process [fillcolor="#2196F3", fontcolor="white", label="Process Data"] End [fillcolor="#F44336", fontcolor="white", label="Complete"] Start -> Process -> End } ``` **Edge styling.** Control line color, thickness, style, and labels: ``` digraph { A -> B [label="sync", color="#2196F3", penwidth=2] B -> C [label="async", style=dashed, color="#FF9800"] C -> D [label="retry", style=dotted, color="#F44336", dir=both] } ``` **Available style attributes include:** * `color` -- border/edge color (hex or named color) * `fillcolor` -- node fill color (requires `style=filled`) * `fontname`, `fontsize`, `fontcolor` -- text styling * `penwidth` -- edge or border thickness * `style` -- `filled`, `rounded`, `dashed`, `dotted`, `bold`, or combinations like `"rounded,filled"` * `shape` -- `box`, `ellipse`, `diamond`, `circle`, `hexagon`, `octagon`, `parallelogram`, `trapezium`, `cylinder`, `record`, and more * `arrowhead` / `arrowtail` -- arrow shape (`normal`, `vee`, `dot`, `odot`, `empty`, `inv`, and others) * `dir` -- edge direction (`forward`, `back`, `both`, `none`) Graphviz Charts for Confluence also respects Confluence's editor alignment options. Once the macro is on the page, you can use the alignment toolbar to center, left-align, or right-align the rendered diagram. This works the same way as aligning images or tables in Confluence. ## How does Graphviz Charts compare to Mermaid for Confluence diagrams?[​](#how-does-graphviz-charts-compare-to-mermaid-for-confluence-diagrams "Direct link to How does Graphviz Charts compare to Mermaid for Confluence diagrams?") Both Graphviz Charts and Mermaid Plus render diagrams from text-based syntax inside Confluence macros. They share the benefits of version control, diffability, and no-external-tool dependency. But they have different strengths. ### Where Mermaid excels[​](#where-mermaid-excels "Direct link to Where Mermaid excels") Mermaid supports a broader range of diagram types out of the box: flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, Gantt charts, pie charts, mindmaps, timelines, Git graphs, C4 architecture diagrams, Sankey diagrams, and more. If you need to create a sequence diagram showing API interactions between services, Mermaid's `sequenceDiagram` syntax is purpose-built for that. Graphviz has no equivalent. Mermaid's syntax is also simpler for common cases. A basic flowchart in Mermaid is more concise than the same flowchart in DOT: ``` flowchart TD A --> B --> C ``` versus: ``` digraph { rankdir=TB A -> B -> C } ``` For teams already using Mermaid across tools (GitHub, GitLab, Notion, Obsidian), staying in the Mermaid ecosystem reduces context-switching. ### Where Graphviz excels[​](#where-graphviz-excels "Direct link to Where Graphviz excels") Graphviz produces superior layouts for large, complex graphs. The `dot` engine's hierarchical ranking algorithm handles graphs with hundreds of nodes and produces more readable results than Mermaid's layout engine at that scale. If you are visualizing a build dependency graph with 200 packages, or a database schema with 80 tables, Graphviz will produce a cleaner diagram. Graphviz also supports record-based node structures for showing entity fields -- a feature Mermaid does not offer in its flowchart syntax. For data model documentation where you want to display column names and types inside each table node, Graphviz is the right choice. Graphviz offers more layout engines (`dot`, `neato`, `fdp`, `sfdp`, `circo`, `twopi`), giving you more control over how different graph structures are visually arranged. Mermaid uses a single layout engine with direction flags. ### Quick comparison[​](#quick-comparison "Direct link to Quick comparison") | Criteria | Graphviz Charts | Mermaid Plus | | -------------------------- | ------------------------------------------- | ----------------------------------------------------- | | **Diagram types** | Directed graphs, undirected graphs, records | 15+ types including sequence, Gantt, pie, mindmap, C4 | | **Layout engines** | 6 (dot, neato, fdp, sfdp, circo, twopi) | 1 with direction flags | | **Large graph handling** | Excellent -- optimized for 100+ nodes | Good up to \~100 nodes | | **Record/node structures** | Yes -- field-level detail in nodes | No -- labels only | | **Syntax simplicity** | Moderate -- more verbose | Simple -- concise for common cases | | **Learning curve** | DOT language has more attributes to learn | Easier for basic diagrams | | **Ecosystem** | Used in build tools, profilers, ORMs | Used in GitHub, GitLab, Notion, Obsidian | **Recommendation:** Use Mermaid Plus for flowcharts, sequence diagrams, Gantt charts, and quick diagrams where syntax simplicity matters. Use Graphviz Charts for large dependency graphs, network topologies, data model diagrams with field-level detail, and any scenario where automatic layout quality is the top priority. Read the [full usage guide](/docs/Graphviz-Charts-for-Confluence/usage.md) to get started with Graphviz Charts. ## Copy-paste DOT examples for Confluence[​](#copy-paste-dot-examples-for-confluence "Direct link to Copy-paste DOT examples for Confluence") Here are three ready-to-use DOT examples you can paste directly into the Graphviz Charts for Confluence macro. Each demonstrates a different graph type and styling approach. ### Example 1 -- CI/CD pipeline flowchart[​](#example-1----cicd-pipeline-flowchart "Direct link to Example 1 -- CI/CD pipeline flowchart") ``` digraph ci_pipeline { rankdir=LR node [shape=box, style="rounded,filled", fillcolor="#E3F2FD", fontsize=11] Commit [label="Git Commit", fillcolor="#4CAF50", fontcolor="white"] Build [label="Build", fillcolor="#2196F3", fontcolor="white"] UnitTest [label="Unit Tests", fillcolor="#2196F3", fontcolor="white"] Integration [label="Integration Tests", fillcolor="#2196F3", fontcolor="white"] Staging [label="Deploy Staging", fillcolor="#FF9800", fontcolor="white"] Approval [label="Manual Approval", shape=diamond, fillcolor="#FFF9C4", fontcolor="#333"] Production [label="Deploy Production", fillcolor="#F44336", fontcolor="white"] Commit -> Build -> UnitTest -> Integration -> Staging -> Approval -> Production } ``` This example uses left-to-right layout (`rankdir=LR`) to show a CI/CD pipeline as a linear flow. Color coding distinguishes source control (green), build/test stages (blue), deployment (orange), approval gates (yellow), and production (red). ### Example 2 -- Network topology (undirected graph)[​](#example-2----network-topology-undirected-graph "Direct link to Example 2 -- Network topology (undirected graph)") ``` graph network { layout=neato node [shape=circle, style=filled, fontsize=9] Router [fillcolor="#4A90D9", fontcolor="white"] Firewall [fillcolor="#F44336", fontcolor="white"] Switch1 [fillcolor="#FF9800", fontcolor="white"] Switch2 [fillcolor="#FF9800", fontcolor="white"] Server1 [fillcolor="#4CAF50", fontcolor="white"] Server2 [fillcolor="#4CAF50", fontcolor="white"] Server3 [fillcolor="#4CAF50", fontcolor="white"] DB [fillcolor="#9C27B0", fontcolor="white", label="Database"] Router -- Firewall Firewall -- Switch1 Firewall -- Switch2 Switch1 -- Server1 Switch1 -- Server2 Switch2 -- Server3 Switch2 -- DB Server1 -- DB [style=dotted] Server2 -- DB [style=dotted] } ``` This uses the `neato` layout engine for a spring-model arrangement that clusters connected nodes together naturally. The undirected edges (`--`) indicate bidirectional network connections. ### Example 3 -- Data model with record structures[​](#example-3----data-model-with-record-structures "Direct link to Example 3 -- Data model with record structures") ``` digraph schema { rankdir=LR node [shape=record, fontsize=10] Customer [label="{Customer|+ id: UUID\l+ name: string\l+ email: string\l+ tier: enum\l}"] Subscription [label="{Subscription|+ id: UUID\l+ customer_id: UUID\l+ plan: string\l+ status: enum\l+ expires_at: date\l}"] Invoice [label="{Invoice|+ id: UUID\l+ subscription_id: UUID\l+ amount: decimal\l+ paid_at: timestamp\l}"] Plan [label="{Plan|+ id: UUID\l+ name: string\l+ price: decimal\l+ features: json\l}"] Customer -> Subscription [label=" 1:N "] Subscription -> Invoice [label=" 1:N "] Plan -> Subscription [label=" 1:N "] } ``` This record-structure diagram shows a SaaS billing data model with four entities and their field definitions. Each entity box displays its columns, making the schema immediately understandable without a separate data dictionary. ## How to insert a Graphviz diagram in Confluence[​](#how-to-insert-a-graphviz-diagram-in-confluence "Direct link to How to insert a Graphviz diagram in Confluence") Follow these steps to add a Graphviz diagram to any Confluence page: 1. **Open the Confluence editor** by editing an existing page or creating a new one. 2. **Insert the macro** by typing `/Graphviz Charts for Confluence` in the editor. Select **Graphviz Charts for Confluence** from the dropdown. 3. **Write or paste your DOT code** into the macro body. You can use any of the examples above as a starting point. 4. **Click the edit icon** on the macro to configure layout engine, alignment, and other settings. 5. **Save the macro** and publish the page. The diagram renders inline for all page viewers. The macro stores your DOT code as plain text, so it is fully searchable through Confluence's full-text search and tracked in page history. ## Frequently Asked Questions[​](#frequently-asked-questions "Direct link to Frequently Asked Questions") ### Can I use Graphviz Charts alongside Mermaid on the same Confluence page?[​](#can-i-use-graphviz-charts-alongside-mermaid-on-the-same-confluence-page "Direct link to Can I use Graphviz Charts alongside Mermaid on the same Confluence page?") Yes. Both macros are independent and can coexist on the same page without conflict. A common pattern is to use Mermaid for sequence diagrams and flowcharts, and Graphviz for dependency graphs and data models, all on the same architecture documentation page. ### Does Graphviz Charts for Confluence support export?[​](#does-graphviz-charts-for-confluence-support-export "Direct link to Does Graphviz Charts for Confluence support export?") The rendered diagram can be exported using Confluence's built-in export features. When you export the page to PDF, the Graphviz diagram is included as part of the page content. You can also use browser print-to-PDF or screenshot tools to capture the rendered diagram independently. ### How large can Graphviz diagrams get before performance suffers?[​](#how-large-can-graphviz-diagrams-get-before-performance-suffers "Direct link to How large can Graphviz diagrams get before performance suffers?") Graphviz's native C engine is highly optimized and can handle graphs with hundreds of nodes efficiently. For most practical use cases in Confluence documentation, diagrams stay under 200 nodes and render in under a second. Very large graphs (500+ nodes) may take longer to render and could benefit from the `sfdp` layout engine, which is designed for scalability. For readability purposes, consider splitting very large graphs into multiple focused diagrams linked together. ### Can I use variables, loops, or conditional logic in DOT?[​](#can-i-use-variables-loops-or-conditional-logic-in-dot "Direct link to Can I use variables, loops, or conditional logic in DOT?") DOT itself is a static description language and does not support variables or logic. However, because DOT is plain text, you can generate it programmatically using scripts, templates, or Confluence's template variables. Teams often write Python or shell scripts that query their codebase or infrastructure and output DOT code, which they then paste into the Graphviz macro. ### Is the DOT code visible to page viewers?[​](#is-the-dot-code-visible-to-page-viewers "Direct link to Is the DOT code visible to page viewers?") No. Page viewers see only the rendered diagram. The DOT source code is stored inside the macro and is only visible when editing the page. This keeps your documentation pages clean while preserving the text-based source for editors who need to update the diagram. ## Related resources[​](#related-resources "Direct link to Related resources") * [Graphviz Charts for Confluence -- full usage guide](/apps/graphviz-charts-for-confluence.md) -- installation, configuration, and all layout engine options * [How to create flowcharts in Confluence](/blog/create-flowcharts-confluence.md) -- flowchart tutorial comparing Mermaid, Excalidraw, and Graphviz * [Mermaid troubleshooting FAQ](/blog/faq-mermaid-troubleshooting.md) -- fixes for common Mermaid rendering issues in Confluence * [How to create architecture diagrams in Confluence](/blog/how-to-create-architecture-diagrams-confluence.md) -- step-by-step architecture diagram guide with copy-paste examples * [Confluence diagram tools compared](/blog/confluence-diagram-tools-comparison.md) -- side-by-side comparison of all NGPILOT diagramming apps Graphviz Charts for Confluence gives your team a powerful way to create complex, auto-laid-out diagrams directly inside Confluence. The DOT language is straightforward to learn, the layout engine handles positioning automatically, and the text-based approach keeps your diagrams version-controlled and easy to maintain. Whether you are documenting microservices dependencies, database schemas, or network topologies, Graphviz produces clean, consistent diagrams that scale with your documentation. Try Graphviz Charts for Confluence Render Graphviz DOT diagrams with live preview — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237380/graphviz-charts-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=graphviz-charts-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [confluence](/blog/tags/confluence.md) * [graphviz](/blog/tags/graphviz.md) * [dot](/blog/tags/dot.md) * [diagrams](/blog/tags/diagrams.md) * [charts](/blog/tags/charts.md) --- # Customize Jira Announcement Banner — Rich Text, Scheduling & Targeting May 2, 2026 · 14 min read [NGPilot](https://ngpilot.com) Announcement banners are one of the few communication channels in Jira that guarantee visibility. Unlike emails that get buried in crowded inboxes or Slack messages that scroll past in minutes, a banner sits at the top of every Jira page until an administrator removes it. That makes banners the right tool for maintenance notifications, policy changes, security alerts, and any information that every Jira user -- or a specific subset of users -- needs to see. But Jira's built-in announcement banner has significant limitations. It supports only plain text. There is no way to schedule it. It is visible to every user on the instance with no option to target specific teams or projects. Only one banner can be active at a time. And enabling or disabling it is a manual process that someone has to remember to do, which means banners often stay live long after the information they contain becomes irrelevant. [Modern Announcement Banner for Jira](/docs/Modern-Announcement-Banner-for-Jira/user-docs.md) extends Jira's native banner system with the features teams actually need: a saved announcement library for quick reuse, dismissible banner options, public/private visibility control, and one-click switching between saved announcements. This FAQ answers the most common questions about Jira announcement banner customization and explains how Modern Announcement Banner helps manage the gaps in the native experience. ## Does Jira have a built-in announcement banner?[​](#does-jira-have-a-built-in-announcement-banner "Direct link to Does Jira have a built-in announcement banner?") Yes. Jira Cloud includes a native announcement banner that administrators can enable through the system settings. It displays a single line of plain text at the top of every Jira page, visible to all users on the instance. The configuration is minimal: you type your message, toggle the banner on, and it appears. Toggle it off, and it disappears. For simple use cases -- a single sentence reminding everyone about an upcoming holiday, for example -- the native banner works. But the limitations become apparent quickly when you need to do anything beyond plain text. You cannot add links, so if you want to direct users to a Confluence page or an external resource, you have to include a raw URL and hope people copy and paste it. You cannot format the text with bold, italic, or color, which means important details cannot be visually distinguished from the rest of the message. You cannot include bullet lists, so multi-item announcements must be crammed into a single paragraph. More fundamentally, the native banner is all-or-nothing. It is visible to every user on the instance. There is no way to restrict it to a specific project, team, or group. If the engineering team needs to see a maintenance notice but the sales team does not, the native banner cannot make that distinction. And only one banner can be active at a time, so if you have two different announcements that need to run concurrently -- a maintenance window and a new policy rollout, for instance -- you have to combine them into a single message or choose one over the other. Modern Announcement Banner for Jira addresses several of these gaps. It provides a saved announcement library so you can prepare banners in advance and activate them with one click. It supports dismissible banners that users can close after reading, and persistent banners that remain visible until an admin disables them. It offers Public and Private visibility settings. It is important to note that the app uses plain text only (no rich text formatting or clickable links), does not support automatic scheduling, and allows only one active banner at a time -- but it makes managing and reusing announcements significantly easier than the native Jira banner. ## Can I schedule announcement banners in Jira?[​](#can-i-schedule-announcement-banners-in-jira "Direct link to Can I schedule announcement banners in Jira?") Neither Jira's native announcement banner nor Modern Announcement Banner currently supports automatic scheduling. An administrator must manually enable the banner when they want it to appear and manually disable it when it is no longer needed. This creates two common failure modes. The first is forgetting to enable the banner on time, which means the announcement goes unseen during the critical window. The second is forgetting to disable it, which means a stale banner about an event that already happened continues to clutter every Jira page for days or weeks until someone remembers to turn it off. Both failure modes are common in practice. The person responsible for the banner is often the same person managing the maintenance window, the policy rollout, or the incident response -- all of which are high-pressure situations where toggling a Jira banner is easy to forget. And once the dust settles, going back to clean up the banner feels like a low priority compared to the work that just finished. Modern Announcement Banner for Jira mitigates this by letting you pre-create and save announcements in advance. You can prepare a maintenance window banner ahead of time and enable it with one click when the window approaches, rather than composing the message under pressure. After the event, disable it just as quickly. While it does not auto-schedule, the saved announcement library reduces the friction of manual management significantly. ## Can I show different banners to different teams in Jira?[​](#can-i-show-different-banners-to-different-teams-in-jira "Direct link to Can I show different banners to different teams in Jira?") Targeted communication is one of the most requested capabilities for Jira announcement banners, and it is something neither the native banner nor Modern Announcement Banner currently supports with granular control. When you enable a banner, every user on the instance sees it regardless of their role, group membership, or the projects they work on. Modern Announcement Banner for Jira does offer a Public/Private visibility setting. Public banners are visible to all users, while Private banners follow Jira's privacy settings. However, granular group-based or project-based targeting -- such as showing a banner only to the engineering team or only within a specific project -- is not currently supported. The best workaround for team-specific communication is to use the banner for company-wide announcements and rely on other channels (Slack, email, Confluence) for team-specific messages. When you do need a banner that is relevant to only some users, the dismissible option lets those who are not affected close it after reading, reducing the noise impact. ## How do I add links and formatting to Jira banners?[​](#how-do-i-add-links-and-formatting-to-jira-banners "Direct link to How do I add links and formatting to Jira banners?") Both Jira's native announcement banner and Modern Announcement Banner accept only plain text. No bold, no italic, no hyperlinks, no lists, no color. If you want to include a URL, it appears as raw text that users must copy and paste into their browser. If you want to emphasize a date or a deadline, you cannot make it bold or red. If you have three separate points to communicate, you must concatenate them into a single unbroken string. This limitation is more than an aesthetic problem. Plain text banners are harder to scan, harder to act on, and more likely to be ignored. A banner with a clear structure -- headline, explanation, and a URL to detailed instructions -- communicates its message faster. But with plain text, you must rely on punctuation and careful wording to convey emphasis. Modern Announcement Banner does support emojis in banner messages, which can help draw attention. Use emojis strategically -- for example, a warning triangle emoji before a maintenance notice, or a calendar emoji before a deadline. While not a replacement for rich formatting, emojis can make plain text banners more scannable. For actionable banners, include the full URL as plain text and keep messages under 200 characters for best readability. Compose the URL to be as short and memorable as possible, or use a URL shortener if the target link is long. ## Can I use announcement banners for maintenance windows?[​](#can-i-use-announcement-banners-for-maintenance-windows "Direct link to Can I use announcement banners for maintenance windows?") Announcement banners are the ideal channel for maintenance window notifications in Jira because they appear in the tool where work is already happening. Unlike an email that competes with dozens of other messages or a Slack notification that disappears in the feed, a banner is persistently visible every time a user loads a Jira page. That continuous visibility is exactly what you want for a maintenance window: the information stays top of mind from the moment it becomes relevant until the window closes. The recommended approach for maintenance window banners depends on the timeline. For maintenance scheduled a week or more in advance, create a dismissible banner with the date, time, duration, and impact. The dismissible option lets users acknowledge that they have seen the notice and removes the banner from their view for their current session, which prevents banner fatigue during the lead-up period. Include a plain-text URL to a Confluence page or status dashboard with full details. As the maintenance window approaches, edit the banner to make it non-dismissible (uncheck the Dismissible setting). This ensures that even users who dismissed the advance notice see the final reminder. After the maintenance window closes, disable the banner manually. Users who return to Jira after maintenance and see a banner about it may assume the maintenance is still in progress or that something went wrong. With Modern Announcement Banner, you can pre-save both the advance notice and the maintenance-in-progress banners, then switch between them with one click -- but you do need to remember to disable the banner when the window closes. For recurring maintenance windows, save the banner as one of your stored announcements so you can re-enable it quickly each time the window comes around. ## How do Modern Announcement Banner banners differ from Jira's native banner?[​](#how-do-modern-announcement-banner-banners-differ-from-jiras-native-banner "Direct link to How do Modern Announcement Banner banners differ from Jira's native banner?") The differences between Modern Announcement Banner for Jira and Jira's native announcement banner fall into several categories, each of which addresses a specific limitation of the built-in option. **Text formatting.** Both the native banner and Modern Announcement Banner support plain text only. Neither offers rich text, bold, italic, clickable links, or color. Modern Announcement Banner does support emojis in banner text. **Scheduling.** Neither the native banner nor Modern Announcement Banner supports automatic scheduling. An administrator must manually enable and disable banners in both systems. Modern Announcement Banner mitigates this by letting you save announcements in advance and enable them with one click. **Targeting.** Both the native banner and Modern Announcement Banner are visible to all users (or follow Jira's privacy settings in Private mode). Granular group-based or project-based targeting is not available in either system. Modern Announcement Banner offers Public and Private visibility settings. **Multiple banners.** Both the native system and Modern Announcement Banner support only one active banner at a time. Enabling a new banner automatically disables the current one. However, Modern Announcement Banner lets you save multiple announcements and switch between them with one click, making it faster to change the active banner. **Dismissible options.** The native banner is always visible until an administrator removes it. Modern Announcement Banner lets you configure banners as dismissible or persistent. Dismissible banners allow users to close them for their current session, which is appropriate for informational announcements. Persistent banners remain visible until disabled, which is appropriate for critical alerts. **Announcement management.** The native banner is a single configuration field. Modern Announcement Banner provides a full management interface where you can save unlimited announcements for reuse, switch between them with one click, and maintain a library of messages for common scenarios. ## Feature comparison: Native Jira Banner vs Modern Announcement Banner[​](#feature-comparison-native-jira-banner-vs-modern-announcement-banner "Direct link to Feature comparison: Native Jira Banner vs Modern Announcement Banner") The table below compares Jira's built-in announcement banner with Modern Announcement Banner across eight key capabilities. | Feature | Jira Native Banner | Modern Announcement Banner for Jira | | -------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | Text formatting | Plain text only. No bold, italic, color, or HTML. | Plain text with emoji support. No rich text, links, or HTML. | | Scheduling | No scheduling. Administrator must manually enable and disable the banner. | No automatic scheduling. Manual enable/disable, but pre-saved announcements enable faster activation. | | Audience targeting | Global visibility. Every user on the instance sees the banner. | Public or Private visibility. Granular group/project targeting not supported. | | Multiple banners | Only one banner can be active at a time. | Only one banner can be active at a time. Multiple saved announcements can be switched between with one click. | | Links and actions | Raw URLs only. Users must copy and paste links manually. | Raw URLs only. No clickable links (plain text). | | Dismissible behavior | Always visible until administrator disables it. | Configurable per banner: dismissible (user can close for session) or persistent. | | Banner management | Single configuration field with no history or reuse. | Full management interface with saved announcements, one-click switching, and unlimited saved messages. | | Visibility control | No visibility options. | Public or Private toggle. | ## Banner use cases[​](#banner-use-cases "Direct link to Banner use cases") Understanding when and how to use announcement banners is just as important as knowing which tool to use. Below are five practical scenarios where announcement banners deliver clear value, along with specific recommendations for each. ### Scheduled maintenance window[​](#scheduled-maintenance-window "Direct link to Scheduled maintenance window") Maintenance windows are the most common and most time-sensitive use case for announcement banners. Jira administrators need to notify all users -- or a specific subset -- that the system will be unavailable during a defined period. The banner should appear well in advance, remain prominent as the window approaches, and disappear immediately after maintenance concludes. Configure the banner with a bold headline ("Scheduled Maintenance"), the exact date and time window, expected duration, and a link to a status page or Confluence document with details. Use scheduling to automate the lifecycle: set the start date to one week before maintenance and the end date to the planned completion time. If the maintenance only affects certain projects, use project-based targeting to keep the banner invisible to unaffected teams. ### New policy or process rollout[​](#new-policy-or-process-rollout "Direct link to New policy or process rollout") When a team or organization introduces a new process -- mandatory code reviews, updated time tracking requirements, new issue creation standards -- an announcement banner ensures the change does not go unnoticed. Unlike a one-time email that people read and forget, a banner provides continuous visibility during the transition period. Write the banner with a brief summary of the policy change, the effective date in bold, and a clickable link to the full documentation. Make the banner dismissible so users can acknowledge it once they have read and understood the change. Set a two-to-four-week schedule so the banner naturally expires once the new process has been adopted. Use group targeting if the policy only applies to certain teams. ### Incident response and emergency alerts[​](#incident-response-and-emergency-alerts "Direct link to Incident response and emergency alerts") During an active production incident, speed of communication is critical. An announcement banner in Jira can alert all relevant teams that an incident is in progress, point them to the incident response channel, and provide a link to the real-time status dashboard. For incident banners, use persistent visibility (non-dismissible) so the alert cannot be closed until the incident is resolved. Use bold red text for the incident status to create visual urgency. Include direct links to the Slack incident channel and the status page. Once the incident is resolved, update the banner to reflect the resolved status briefly before scheduling it to auto-remove an hour later. ### Onboarding and welcome messages[​](#onboarding-and-welcome-messages "Direct link to Onboarding and welcome messages") New team members joining a Jira instance benefit from a welcome banner that points them to key resources: the team wiki, onboarding documentation, project conventions, and points of contact. This is a low-urgency but high-value use case that helps new users orient themselves during their first days. Keep the tone friendly and informative. Use bullet lists to link to multiple resources. Make the banner dismissible since it only needs to be seen once. Target the banner to a "new-users" group if your organization provisions one, or keep it global with a two-week schedule for new hires. Save the banner as a reusable template so it can be quickly re-enabled each time a new cohort joins. ### Compliance and audit notifications[​](#compliance-and-audit-notifications "Direct link to Compliance and audit notifications") Organizations subject to compliance requirements -- SOC 2, GDPR, HIPAA, or internal audit standards -- often need to communicate mandatory actions to specific teams. An announcement banner ensures the communication is visible within Jira where the relevant work is happening, rather than relying solely on email. Craft the banner with precise language about the required action, the deadline in bold, and a link to the compliance documentation or form. Target the banner to the specific groups responsible for the action -- the security team, the data engineering team, or the finance team -- rather than broadcasting it to the entire organization. Set the end date to the compliance deadline. Use persistent visibility to ensure the banner cannot be dismissed until the required action is completed. ## Related resources[​](#related-resources "Direct link to Related resources") * [Modern Announcement Banner for Jira](/apps/modern-announcement-banner-for-jira.md) — full documentation, setup guide, and configuration reference * [Browse all NGPILOT apps](/docs/intro.md) — explore the complete suite of Jira and Confluence apps by NGPILOT Try Modern FAQ for Confluence Accordion-style FAQ sections with drag-and-drop reordering and two themes — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236739/modern-faq-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-faq-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [jira](/blog/tags/jira.md) * [announcement-banner](/blog/tags/announcement-banner.md) * [customization](/blog/tags/customization.md) --- # Jira Attachment Permissions FAQ: Download, Access & Troubleshoot April 21, 2026 · 12 min read [NGPilot](https://ngpilot.com) Managing attachments in Jira sounds straightforward until users start reporting that they cannot download files, the bulk downloader is missing items, or attachments disappeared after a migration. Most of these problems trace back to permissions, storage configuration, or network infrastructure rather than a bug in Jira itself. Jira's permission model is layered: global settings, project roles, issue-level security schemes, and workflow properties all feed into whether a user can view or download a given attachment. Understanding how these layers interact is the key to diagnosing problems quickly. This FAQ covers the most common attachment-related issues we hear about, explains why they happen, and walks you through concrete resolution steps. Whether you are a Jira administrator investigating a support ticket or an end user trying to understand why a download failed, the sections below should point you in the right direction. ## Why can't I download some Jira attachments?[​](#why-cant-i-download-some-jira-attachments "Direct link to Why can't I download some Jira attachments?") The most common cause is a missing **View Attachments** permission on the project or issue in question. Jira ties attachment visibility directly to issue visibility: if a user cannot see the issue, they cannot see its attachments. Even when a user can view the issue itself, a project administrator or scheme configuration may have removed the *View Attachments* permission from their role. Issue-level security adds a second gate. Some projects use security schemes to restrict which users or groups can access certain issue types (for example, security vulnerabilities or HR tickets). If an issue is protected by a security level that excludes your account, every attachment on that issue will be invisible regardless of your project-level permissions. If you are confident your permissions are correct and the problem persists, ask a Jira administrator to verify the issue. An admin can use the **Permission Helper** tool (available under Administration > System > Permission Helper) to check exactly which permissions your account holds on a specific issue. This tool reports whether you have *View Attachments*, whether any issue security level blocks you, and which permission scheme is in effect. ## Why does the bulk downloader show fewer files than expected?[​](#why-does-the-bulk-downloader-show-fewer-files-than-expected "Direct link to Why does the bulk downloader show fewer files than expected?") Simple Bulk Attachment Downloader (and similar tools) respects Jira's permission model. It can only list and download attachments that the authenticated user is allowed to see. If another user uploaded files with restricted visibility or if the uploader limited file access to a specific group, those attachments will not appear in your bulk download session. Another frequent cause is restricted uploads. Some projects allow only certain roles to attach files. If you are not in that role, you may still be able to view the issue but not the attachments added by users who *do* hold the upload role, depending on how the permission scheme is configured. The fastest way to confirm is to ask a Jira project administrator or system administrator to run the same bulk download with an admin account. If the admin sees more files than you do, the gap is permission-related. If the admin also sees fewer files than expected, the attachments may have been deleted or the JQL filter used by the downloader may need adjustment. ## Why are attachments missing after a Jira migration?[​](#why-are-attachments-missing-after-a-jira-migration "Direct link to Why are attachments missing after a Jira migration?") Migrations between Jira instances (Server to Data Center, Server to Cloud, or even host-to-host moves) are a common source of attachment loss. The usual culprit is a mismatch between the attachment storage path configured in the source instance and the path in the target instance. Jira stores attachments on disk in a directory that is defined in `jira-config.properties` or through the Administration console under *Attachments*. If the target instance points to a different directory, or if the migration tool did not copy the attachment directory, the links in the database will point to files that do not exist on the new server. To diagnose this, open the Jira administration console on the target instance and navigate to *System > Attachments*. Verify that the attachment path matches the location where files were restored. Then pick a known issue with attachments and check whether the file exists on disk at the expected path. Link integrity is another factor. The database stores attachment metadata (filename, size, author, issue ID) separately from the files on disk. If the database was migrated but the file system was not, or vice versa, attachments will appear broken. Ensure that both the database and the attachment directory were included in the backup and restore process. Tools like Jira's built-in XML backup, Atlassian's JCMA (Jira Cloud Migration Assistant), or third-party solutions each handle attachment migration differently; consult the tool's documentation to confirm that attachments are covered. ## Can antivirus or proxy software block Jira attachment downloads?[​](#can-antivirus-or-proxy-software-block-jira-attachment-downloads "Direct link to Can antivirus or proxy software block Jira attachment downloads?") Yes, and this is more common than many teams realize. Corporate network proxies, web application firewalls, and endpoint antivirus products can all interfere with attachment downloads. The interference usually takes one of two forms: file-type filtering or domain-level blocking. File-type filtering blocks downloads of certain extensions such as `.exe`, `.zip`, `.jar`, or macro-enabled Office files (`.xlsm`, `.docm`). The proxy inspects the response headers or URL pattern and drops the connection. Users see a generic browser error rather than a Jira error, which makes the problem hard to trace back to Jira. Domain whitelisting issues occur when the proxy does not recognize the Jira attachment download URL pattern. Jira serves attachments through paths like `/secure/attachment/` followed by a numeric ID and filename. If your proxy rules only whitelist the base Jira domain but not these sub-paths, downloads may fail silently. To resolve this, ask your network team to whitelist your Jira domain (including all sub-paths) and specifically allow the `/secure/attachment/` URL pattern. If you are using Simple Bulk Attachment Downloader, the ZIP file downloads through your browser's built-in download manager, so ensure your browser download settings allow large file downloads and that no corporate proxy blocks ZIP file responses. ## What are Jira's attachment size limits?[​](#what-are-jiras-attachment-size-limits "Direct link to What are Jira's attachment size limits?") Jira enforces two configurable size limits for attachments: * **Per-file limit** (default: 10 MB). Any single file larger than this value is rejected at upload time. The user sees an error message in the attachment dialog. * **Per-issue limit** (default: unlimited on Server/Data Center; Cloud enforces a total that varies by plan, with a practical maximum of 104 MB per issue on some tiers). This controls the combined size of all attachments on a single issue. Administrators can adjust both limits. On Jira Server and Data Center, navigate to *Administration > System > Advanced > Attachments*. On Jira Cloud, the limits are managed under *Project settings > Attachments* or through the global administration area. If users are consistently hitting the per-file limit, consider whether large binaries (virtual machine images, database dumps, video files) belong in Jira at all. A better workflow is to store large artifacts in a dedicated file-sharing or artifact management system and link to them from the Jira issue. This keeps Jira's attachment storage lean and avoids the need to raise limits for everyone. To check your current limits, open an issue and attempt to attach a test file of known size. Jira will display a clear error message if the file exceeds the configured maximum. You can also inspect the settings directly as an admin under the Attachments configuration page. ## How do I troubleshoot Jira attachment permission errors?[​](#how-do-i-troubleshoot-jira-attachment-permission-errors "Direct link to How do I troubleshoot Jira attachment permission errors?") Start with a systematic approach rather than guessing. The following diagnostic steps will resolve the majority of attachment permission problems: 1. **Reproduce the issue as an administrator.** Log in with a Jira admin account and attempt the same action the user reported (view the issue, download the attachment, run the bulk downloader). If the admin can perform the action but the user cannot, the problem is permission-related. If the admin also fails, the problem is likely in storage, configuration, or the attachment itself. 2. **Verify issue-level permissions.** Use the **Permission Helper** (Administration > System > Permission Helper) to check which permissions the affected user holds on the specific issue. Enter the user's name, the issue key, and select *View Attachments*. The helper will show you the exact permission scheme, project role, and any issue security level that applies. 3. **Check that the attachment still exists in storage.** Navigate to the attachment directory on the Jira server (or check the Cloud storage status) and confirm the file is present. Attachments can be deleted directly from disk by automated cleanup scripts or storage migration errors, leaving orphaned metadata in the database. 4. **Review the audit log.** Jira's audit log records attachment creation and deletion events. Search for the issue key or the attachment filename to see if the file was deleted by a user or an automated process. On Server and Data Center, find the audit log under Administration > System > Audit Log. On Cloud, it is under Project settings > Audit Log. 5. **Confirm the user's role includes both Create Attachments and View Attachments.** Some permission schemes grant one but not the other, leading to situations where a user can upload but cannot later download their own uploads, or vice versa. ## Jira attachment permission hierarchy[​](#jira-attachment-permission-hierarchy "Direct link to Jira attachment permission hierarchy") Understanding the order in which Jira evaluates permissions helps you trace why a particular user can or cannot access an attachment. Jira checks permissions in the following layers, and the most restrictive result wins: **Global permissions.** These are site-wide settings managed under Administration > System > Global Permissions. The *Use Jira* permission determines whether a user can log in at all. The *Jira Administrators* and *Jira System Administrators* global permissions bypass most project-level restrictions. **Project permissions via permission schemes.** Every project is associated with a permission scheme. The scheme maps each permission (including *View Attachments* and *Create Attachments*) to a combination of project roles, groups, assignees, reporters, and other criteria. If the scheme does not grant *View Attachments* to the user's role on the project, the user cannot see attachments on any issue in that project. **Issue security schemes.** Applied at the issue level, these schemes restrict visibility of specific issues to certain users or groups. An issue security level is more restrictive than project permissions; it can hide an issue (and all its attachments) from users who would otherwise have full project access. Issue security is typically used for sensitive issue types such as security vulnerabilities or executive escalations. **Workflow properties.** Jira workflows can include conditions or properties that restrict actions based on the issue's current status. For example, a workflow property might prevent attachment uploads when an issue is in the *Closed* status. This does not affect viewing existing attachments, but it can prevent new uploads. When diagnosing attachment problems, work from the bottom of this hierarchy upward. Start with workflow properties and issue security (the most specific), then check the permission scheme, and finally confirm global permissions. ## Troubleshooting flowchart[​](#troubleshooting-flowchart "Direct link to Troubleshooting flowchart") Follow this numbered diagnostic process when a user reports an attachment access problem. Each step either resolves the issue or narrows down the next area to investigate. 1. **Ask the user to open the specific issue.** If they cannot open the issue at all, the problem is issue-level security or project visibility. Move to step 5. 2. **Check whether the attachment icon or section is visible on the issue.** If the section is hidden entirely, the user lacks the *View Attachments* permission. Move to step 4. 3. **If attachments are visible but a specific file cannot be downloaded**, attempt to download it as an administrator. If the admin can download it, the user's session or network may be the problem (proxy, antivirus). If the admin also fails, the file may be missing from storage. Move to step 6. 4. **Verify the permission scheme.** Open Administration > Issues > Permission Schemes, find the scheme used by the project, and confirm that *View Attachments* is granted to the user's project role or group. 5. **Check issue security.** Open the issue and look at the security level displayed near the issue summary. Navigate to the issue security scheme and verify that the user's group or role is included in that security level. 6. **Verify storage.** On Server or Data Center, check the attachment directory path in `jira-config.properties` and confirm the file exists on disk. On Cloud, verify the attachment is not flagged as corrupted in the issue view. 7. **Review the audit log** for deletion events or migration activities that may have affected the attachment. 8. **Check network infrastructure** if the file exists and permissions are correct but downloads still fail. Ask the user to try from a different network or have IT review proxy and antivirus logs for blocked requests. ## Quick admin checklist[​](#quick-admin-checklist "Direct link to Quick admin checklist") Before escalating an attachment problem, run through these five items. Most issues are resolved by one of these checks. 1. **Confirm the user has View Attachments permission** on the project via the Permission Helper tool. This single step resolves more than half of all reported attachment problems. 2. **Verify issue security levels** are not blocking the user. Open the issue and check the security level; ensure the user's group is listed in the corresponding issue security scheme. 3. **Check the attachment storage path** in Administration > System > Attachments. Confirm the path is correct, writable, and that disk space is available. A full disk will cause silent upload failures. 4. **Review the Jira audit log** for the affected issue key. Look for attachment deletion events, migration entries, or permission scheme changes that coincide with the reported problem. 5. **Test from a different network** if permissions and storage look correct. Have the user attempt the download over a mobile hotspot or VPN to rule out proxy or antivirus interference. ## Related resources[​](#related-resources "Direct link to Related resources") * [Simple Bulk Attachment Downloader](/apps/simple-bulk-attachment-downloader-for-jira.md) * [Bulk download Jira attachments](/blog/bulk-download-jira-attachments.md) — step-by-step guide * [Attachment Reviewer for Jira](/apps/attachment-reviewer-for-jira.md) — enforce file policies * [Bulk operations FAQ](/blog/faq-bulk-operations-jira.md) — general bulk workflow tips Try Modern FAQ for Confluence Accordion-style FAQ sections with drag-and-drop reordering and two themes — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236739/modern-faq-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-faq-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [jira](/blog/tags/jira.md) * [attachments](/blog/tags/attachments.md) * [permissions](/blog/tags/permissions.md) * [troubleshooting](/blog/tags/troubleshooting.md) --- # Jira Issue Templates FAQ: Auto-Apply, Variables & Automation May 2, 2026 · 12 min read [NGPilot](https://ngpilot.com) Creating consistent Jira issues across a growing team is harder than it sounds. Without templates, one developer files a bug report with detailed reproduction steps and environment details while another submits a two-line summary with no context. Product managers write user stories that vary wildly in structure, making backlog grooming slower than it needs to be. Support teams log incidents using different formats depending on who is on shift. These inconsistencies compound over time and erode the reliability of your Jira data. Issue templates solve this by standardizing the structure and content of every new ticket. But templates are only part of the solution. To get the full benefit, you need automation that applies templates without relying on people to remember to select the right one, variables that personalize each ticket automatically, and a system flexible enough to share templates across projects. This FAQ answers the most common questions teams have about setting up, automating, and scaling Jira issue templates using [Modern Issue Templates for Jira](/docs/Modern-Issue-Templates-for-Jira/user-docs.md). ## Can Jira automatically apply templates to new issues?[​](#can-jira-automatically-apply-templates-to-new-issues "Direct link to Can Jira automatically apply templates to new issues?") Yes, and this is the feature that transforms templates from a nice-to-have into a truly scalable system. Modern Issue Templates for Jira supports auto-apply rules that watch for new issues matching criteria you define and automatically populate them with your template content before the issue enters the active workflow. Auto-apply rules work by evaluating conditions when a new issue is created. You configure these conditions based on project and issue type. When a new issue matches the assigned project and issue type, the template is applied immediately. The person creating the issue does not need to take any extra steps -- the summary and description fields are pre-filled automatically. This eliminates the most common failure mode of template adoption: people forgetting to use them. Even when templates are available, busy team members often skip the template selection step in favor of creating an issue quickly. Auto-apply rules ensure that every new bug report gets the bug template, every new story gets the user story template, and every new incident gets the incident template -- regardless of whether the person creating the issue remembers to select it. The recommended approach is to start with a single project and map each issue type to its corresponding template. Once you have validated that the rules are working correctly and the templates are producing the right output, expand the configuration to additional projects. For organizations with multiple teams that follow different standards, project-specific overrides allow each team to maintain its own templates while still benefiting from the auto-apply mechanism. ## What are template variables in Jira issue templates?[​](#what-are-template-variables-in-jira-issue-templates "Direct link to What are template variables in Jira issue templates?") The power of issue templates lies in standardizing the structure of every ticket so that the person creating the issue only needs to fill in the specifics. Modern Issue Templates for Jira pre-fills the summary and description fields with your structured content. The user sees the sections they need to complete -- Steps to Reproduce, Expected Result, Actual Result, Environment -- and fills in the blanks. The practical benefit is significant. Consider a bug report template that includes sections for "Steps to Reproduce," "Expected Result," "Actual Result," and "Environment." Without a template, every person filing a bug has to decide what information to include, and the result varies wildly. With a template, the structure is consistent every time, and the person creating the issue can focus on describing the problem rather than deciding how to format it. Templates assigned to multiple projects work in each project without modification. An incident template assigned to both your engineering project and your support project will pre-fill consistently in both contexts. This means you can create one well-designed template and assign it to multiple projects, ensuring the same format across your organization. ## Can I import issue templates from GitHub?[​](#can-i-import-issue-templates-from-github "Direct link to Can I import issue templates from GitHub?") Yes. Modern Issue Templates for Jira can import templates directly from GitHub repositories, which is a powerful capability for engineering teams that already use GitHub issue templates in their `.github/ISSUE_TEMPLATE/` directory. The import workflow is straightforward. Click **Import Templates**, select the **From GitHub URL** tab, paste a direct file URL (for example, `https://github.com/username/repo/blob/main/.github/ISSUE_TEMPLATE/bug_report.md`), and click **Fetch**. The app converts the file into a Jira issue template, extracting YAML frontmatter (name, title, labels) and converting the markdown body to rich text. You can also import from GitHub Gists using the **From GitHub Gist** tab. Once imported, the templates work exactly like manually created ones -- they support auto-apply rules and multi-project assignment. This integration solves a real workflow problem for teams that operate across both GitHub and Jira. Many engineering teams define their issue templates in GitHub because templates live alongside the codebase, are version-controlled, and go through the same review process as code changes through pull requests. Before this import capability, those teams had to maintain two separate sets of templates -- one in GitHub for repository-level issues and one in Jira for project management -- and keep them in sync manually. With GitHub import, the GitHub repository becomes the single source of truth and Jira templates are derived from it. After the initial import, you can re-import templates when the GitHub versions change. This keeps your Jira templates up to date as your team refines its issue formats over time. For teams that prefer to manage templates entirely within Jira, the app also provides a full template editor that does not require any connection to GitHub. ## How do I share issue templates across multiple Jira projects?[​](#how-do-i-share-issue-templates-across-multiple-jira-projects "Direct link to How do I share issue templates across multiple Jira projects?") Modern Issue Templates for Jira supports assigning a single template to multiple projects, which is a significant advantage over per-project templates that must be recreated or manually copied for every new project. To share a template across projects, use the **Assign to Project** action to map it to specific projects and issue types. A single template can be assigned to multiple projects at once. When you update a template, the change takes effect for every project it is assigned to, which eliminates the drift that occurs when teams maintain independent copies of the same template. This is especially valuable for organizations with standardized processes. If your company has a standard incident response template, a standard change request template, or a standard accessibility review template, you create it once and assign it to every relevant project. Compliance teams benefit because they can audit a single template rather than chasing variations across projects. New projects get the organizational standard from day one, reducing onboarding time and ensuring consistency from the start. For teams that need project-specific variations, you can clone a template and customize the copy. This gives you the efficiency of shared base templates without forcing every team into an identical format. ## What is the difference between Jira native templates and Modern Issue Templates?[​](#what-is-the-difference-between-jira-native-templates-and-modern-issue-templates "Direct link to What is the difference between Jira native templates and Modern Issue Templates?") Jira provides basic template functionality that allows you to pre-fill certain fields when creating a new issue. You can define a default summary, description, and a handful of field values that appear when someone selects the template. This works well for simple use cases where you just need a few pre-filled fields and your team is disciplined about selecting the right template every time. Modern Issue Templates for Jira extends this foundation with capabilities designed for teams that need more control, automation, and scalability. The table below provides a detailed feature-by-feature comparison. ## How do I create a bug report template for Jira?[​](#how-do-i-create-a-bug-report-template-for-jira "Direct link to How do I create a bug report template for Jira?") Creating an effective bug report template in Modern Issue Templates takes just a few minutes and pays dividends every time someone files a bug. Here is the recommended setup. First, create a new template. Give it a clear name like "Bug Report" and set a summary template such as `Bug: [brief description]`. Then assign it to your projects and the Bug issue type. This ensures the template applies automatically whenever someone creates a Bug issue in those projects. Next, fill in the description with your standard bug report format. A well-structured bug template should include the following sections: * **Steps to Reproduce** -- numbered list with blank steps so the reporter can fill in the exact sequence * **Expected Result** -- what the user expected to happen * **Actual Result** -- what actually happened, including any error messages * **Environment** -- browser, OS, app version, or deployment environment where the bug was observed * **Attachments / Screenshots** -- a prompt to attach visual evidence Finally, assign the template to your project and the Bug issue type using the **Assign to Project** action. Once assigned, every new bug created in that project will have the summary and description pre-filled, and the reporter only needs to fill in the bug-specific details. ## Feature comparison: Modern Issue Templates vs alternatives[​](#feature-comparison-modern-issue-templates-vs-alternatives "Direct link to Feature comparison: Modern Issue Templates vs alternatives") The table below compares the three most common approaches to issue templates in Jira across eight key capabilities. | Feature | Modern Issue Templates for Jira | Jira Native Templates | Issue Templates for Jira (Deviniti) | | --------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | Auto-apply rules | Yes. Detects project and issue type combinations to apply templates automatically without user action. | No. Users must manually select a template each time they create an issue. | Yes. Supports auto-apply based on project and issue type criteria. | | Rich text editor | Yes. Full rich text editor with headings, lists, code blocks, links, and inline editing. | Yes. Standard Jira rich text editor available for template descriptions. | Yes. Standard Jira rich text editor available for template descriptions. | | GitHub import | Yes. Import templates directly from GitHub repository URLs and Gists. | No. Templates must be created manually in the Jira interface. | No. Templates must be created manually or imported from other Jira projects. | | File import | Yes. Import from JSON and Markdown files with YAML frontmatter support. | No. Templates must be created manually in the Jira interface. | Limited. May support some file import formats. | | Multi-project sharing | Yes. Assign a single template to multiple projects and issue types. | No. Templates are scoped to individual projects and must be recreated for each one. | Yes. Supports shared templates across projects with some configuration limitations. | | Inline editing | Yes. Edit summary and description directly in the template table without opening the full editor. | No. Templates must be opened in the editor to make changes. | Limited. Editing typically requires opening the full template editor. | | Template export | Yes. Export selected templates as JSON files for backup and sharing. | No. No export functionality. | Limited. May support export in some formats. | | Template cloning | Yes. Clone existing templates to create variations quickly. | No. Templates must be recreated manually. | Yes. Supports template cloning. | | Issue type mapping | Yes. Map templates to specific issue types per project. | Yes. Basic issue type association when creating a template. | Yes. Templates can be associated with issue types during configuration. | ## Template automation best practices[​](#template-automation-best-practices "Direct link to Template automation best practices") Getting issue templates right is not just about enabling the feature. The way you design, deploy, and maintain your templates determines whether they actually improve consistency or become shelfware that people ignore. These five best practices will help you build a template system that scales with your team. ### 1. Map every issue type to a template[​](#1-map-every-issue-type-to-a-template "Direct link to 1. Map every issue type to a template") Do not leave any issue type without a corresponding template. If you have Bug, Story, Task, Epic, and Incident issue types, you should have at least five templates -- one for each. When a team member creates an issue and no template applies, that is a gap in your system. Configure auto-apply rules for every issue type in every project where templates are active. This ensures full coverage and prevents the inconsistent tickets that templates are meant to eliminate. ### 2. Use placeholder text to guide reporters[​](#2-use-placeholder-text-to-guide-reporters "Direct link to 2. Use placeholder text to guide reporters") Make it obvious which fields need human input. Use bracketed placeholders like `[brief description]`, `[browser / OS]`, or `[expected result]` to mark sections the reporter should fill in. The less ambiguity in your template, the more likely people are to complete it correctly. A template with clear, labeled sections will be adopted without friction. A template that is ambiguous about what to fill in will be abandoned. ### 3. Version your templates through GitHub import[​](#3-version-your-templates-through-github-import "Direct link to 3. Version your templates through GitHub import") For engineering teams that already use GitHub, importing templates from your repository gives you version control for free. Every change to a template goes through a pull request, gets reviewed by a teammate, and is tracked in your git history. If a template change introduces a problem, you can revert to the previous version just like you would revert a code change. When templates change, re-import the updated file from GitHub. The app handles duplicate names by appending a number suffix, so you can rename the updated version and delete the old one. This is more robust than editing templates directly in Jira, where changes are immediate and there is no built-in mechanism for review or rollback. ### 4. Start with one project, then expand[​](#4-start-with-one-project-then-expand "Direct link to 4. Start with one project, then expand") Rolling out templates to every project simultaneously is tempting but risky. Differences in team workflows, custom fields, and issue type schemes mean that a template that works perfectly in one project may need adjustments in another. Start with your most active project or the team that has the strongest need for consistency. Validate the templates and assignment rules in that context, gather feedback from the team, and iterate. Once the templates are stable and the team is satisfied with the output, assign them to additional projects, making project-specific adjustments as needed. ### 5. Review and update templates quarterly[​](#5-review-and-update-templates-quarterly "Direct link to 5. Review and update templates quarterly") Templates are not set-and-forget. As your team's processes evolve, your templates should evolve with them. Schedule a quarterly review where a project manager or team lead examines each active template and asks whether the format still matches the team's current workflow. Have new fields become important? Have some sections become unnecessary? Are reporters consistently leaving certain sections blank because they do not apply? Update the templates to reflect the current reality. Stale templates that do not match how the team actually works will be abandoned, and once people stop trusting the templates, getting them back is difficult. ## Related resources[​](#related-resources "Direct link to Related resources") * [Modern Issue Templates for Jira](/apps/modern-issue-templates-for-jira.md) — full documentation and setup guide * [Jira issue templates best practices](/blog/jira-issue-templates-best-practices.md) — detailed walkthrough of template design, auto-apply configuration, and GitHub import * [Issue Templates for Jira — Which Template App?](/blog/jira-issue-templates-comparison.md) — in-depth comparison of template apps on the Atlassian Marketplace Try Modern FAQ for Confluence Accordion-style FAQ sections with drag-and-drop reordering and two themes — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236739/modern-faq-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-faq-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [jira](/blog/tags/jira.md) * [issue-templates](/blog/tags/issue-templates.md) * [automation](/blog/tags/automation.md) * [jira-automation](/blog/tags/jira-automation.md) --- # All 30 Mermaid Diagram Types in Confluence: Complete Reference May 2, 2026 · 21 min read [NGPilot](https://ngpilot.com) Mermaid supports **30 diagram types** — from flowcharts and sequence diagrams to C4 architecture, swimlanes, Gantt charts, ER diagrams, git graphs, and more. With [Mermaid Plus Diagrams & AI Agent for Confluence](/apps/mermaid-plus-for-confluence.md), all 30 render from plain text inside a single macro. This page is the complete reference: every type, its keyword, its category, when to use it, and worked examples for the ones a software team reaches for most. What you'll find here * **[The full 30-type table](#all-30-mermaid-diagram-types-at-a-glance)** — every type, keyword, and category at a glance * **[When to use each type](#when-to-use-each-mermaid-diagram-type)** — flowchart vs sequence vs C4 vs ER vs state vs Gantt, with examples * **[The types a sprint team actually uses](#the-diagram-types-a-sprint-team-actually-uses)** — practical playbook for Jira and Confluence * **[Beta types explained](#frequently-asked-questions)** — sankey, packet, architecture, radar, swimlane, use case, and more If you are deciding which diagram type fits your use case, jump to [When to use each Mermaid diagram type](#when-to-use-each-mermaid-diagram-type). For the quick reference table, see below. For installation and the macro basics, see [Create Mermaid diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md). ## The diagram types a sprint team actually uses[​](#the-diagram-types-a-sprint-team-actually-uses "Direct link to The diagram types a sprint team actually uses") ### 1. Flowcharts — the definition-of-done diagram[​](#1-flowcharts--the-definition-of-done-diagram "Direct link to 1. Flowcharts — the definition-of-done diagram") Every team has a "what does Done mean?" conversation. A flowchart pinned to the sprint page removes the ambiguity: branches for QA, security review, and docs gate the path to Done. In Jira, the same flowchart on the workflow transition screen reminds the engineer what's expected before they drag the ticket. Whether you are documenting a microservices architecture, onboarding new engineers, or writing an RFC, the diagrams you choose shape how quickly your audience can understand the system. Flowcharts, sequence diagrams, and ER diagrams are the workhorses of most teams, but Mermaid also offers specialized types like C4 diagrams, git graphs, and kanban boards that solve specific documentation problems. This guide covers all of them, with a comparison table and practical advice for using each type inside Confluence. ## All 30 Mermaid Diagram Types at a Glance[​](#all-30-mermaid-diagram-types-at-a-glance "Direct link to All 30 Mermaid Diagram Types at a Glance") Mermaid supports the following diagram types. Each one has a dedicated keyword that you use at the top of your code block to tell the renderer which type to expect. | # | Diagram Type | Keyword | Category | | -- | -------------------- | -------------------------------------------- | --------------- | | 1 | Flowchart | `flowchart` or `graph` | Process | | 2 | Sequence Diagram | `sequenceDiagram` | Interaction | | 3 | Class Diagram | `classDiagram` | Structure | | 4 | State Diagram | `stateDiagram-v2` | Behavior | | 5 | ER Diagram | `erDiagram` | Data | | 6 | User Journey | `journey` | UX | | 7 | Gantt Chart | `gantt` | Planning | | 8 | Pie Chart | `pie` | Data | | 9 | Git Graph | `gitGraph` | Version Control | | 10 | Mindmap | `mindmap` | Brainstorming | | 11 | Timeline | `timeline` | Chronology | | 12 | Requirement Diagram | `requirementDiagram` | Requirements | | 13 | C4 Diagram | `C4Context` / `C4Container` / `C4Deployment` | Architecture | | 14 | Quadrant Chart | `quadrantChart` | Analysis | | 15 | Sankey Diagram | `sankey-beta` | Flow | | 16 | XY Chart | `xychart-beta` | Data | | 17 | Block Diagram | `block-beta` | Structure | | 18 | Packet Diagram | `packet-beta` | Networking | | 19 | Kanban Board | `kanban` | Workflow | | 20 | Architecture Diagram | `architecture-beta` | Infrastructure | | 21 | Radar Chart | `radar-beta` | Comparison | | 22 | TreeView | `treeView-beta` | Hierarchy | | 23 | Treemap | `treemap` | Data | | 24 | Ishikawa (Fishbone) | `ishikawa` | Root Cause | | 25 | Venn Diagram | `venn-beta` | Sets | | 26 | ZenUML | `zenuml` | Interaction | | 27 | Swimlane | `swimlane-beta` | Process | | 28 | Cynefin | `cynefin-beta` | Framework | | 29 | Railroad | `railroad-ebnf-beta` | Grammar | | 30 | UML Use Case Diagram | `usecase-beta` | UML | All 30 types are supported in Mermaid Plus Diagrams & AI Agent for Confluence. You can access one-click templates for each type from the Quick Templates panel in the macro configuration. ## Frequently Asked Questions[​](#frequently-asked-questions "Direct link to Frequently Asked Questions") ### 1. How many Mermaid diagram types are there, and which ones does Confluence support?[​](#1-how-many-mermaid-diagram-types-are-there-and-which-ones-does-confluence-support "Direct link to 1. How many Mermaid diagram types are there, and which ones does Confluence support?") Mermaid currently supports 30 diagram types, ranging from flowcharts and sequence diagrams to radar charts and fishbone diagrams. Mermaid Plus Diagrams & AI Agent for Confluence supports all 30 types through a single macro -- type `/mermaid` in the editor, choose your diagram from the Quick Templates panel, and start writing. Every diagram type is available with live preview, so you can see changes in real time as you write. The 30 types span several broad categories. Process diagrams (flowcharts, kanban) capture workflows and decision logic. Interaction diagrams (sequence, ZenUML) show how components communicate over time. Structure diagrams (class, ER, block) model data and code organization, and UML use case diagrams (`usecase-beta`, new in Mermaid 12) map actors to system capabilities. Planning diagrams (Gantt, timeline) visualize schedules. Data diagrams (pie, XY chart, treemap) present quantitative information. Specialized types like C4, git graph, and packet diagram address domain-specific needs such as architecture documentation, branching strategy visualization, and network protocol illustration. For a complete syntax reference with code examples for every diagram type, see the [Mermaid Plus Diagrams & AI Agent for Confluence usage guide](/docs/Mermaid-Plus-for-Confluence/usage.md). ### 2. Which Mermaid diagram types are most useful for software development teams?[​](#2-which-mermaid-diagram-types-are-most-useful-for-software-development-teams "Direct link to 2. Which Mermaid diagram types are most useful for software development teams?") The five most essential diagram types for software teams are flowcharts (process and decision logic), sequence diagrams (service interactions and API flows), class diagrams (object-oriented design), ER diagrams (database schemas), and state diagrams (lifecycle and status transitions). C4 diagrams are also highly valuable for architecture documentation. These six types cover the majority of documentation needs in a typical engineering organization. **Flowcharts** are the most versatile. Use them for CI/CD pipeline visualization, user journey mapping, decision trees, and any process with branching logic. The `flowchart` keyword supports four directions (TD, LR, BT, RL) and rich node shapes including diamonds for decisions, cylinders for databases, and circles for connectors. ``` flowchart LR A[Code Push] --> B[CI Build] B --> C{Tests Pass?} C -->|Yes| D[Deploy to Staging] C -->|No| E[Notify Team] D --> F{QA Approved?} F -->|Yes| G[Deploy to Production] F -->|No| H[Rollback] ``` **Sequence diagrams** are indispensable for documenting API interactions, service-to-service communication, and any protocol where order matters. They show participants as vertical lifelines with horizontal arrows representing messages. For detailed guidance, see our [guide to creating sequence diagrams in Confluence](/blog/how-to-create-sequence-diagrams-confluence.md). **Class diagrams** capture object-oriented design, showing classes with their attributes, methods, and relationships (inheritance, composition, aggregation). They are essential for design documents and API documentation. See our [class diagram tutorial for Confluence](/blog/how-to-create-class-diagrams-confluence.md) for a deeper walkthrough. **ER diagrams** document database schemas and entity relationships using a compact notation (`||--o{` for one-to-many, `||--||` for one-to-one). They are the fastest way to communicate a data model in a design doc or migration plan. **State diagrams** model the lifecycle of entities -- order statuses, user account states, deployment phases, and similar state machines that drive business logic. **C4 diagrams** follow the C4 model for software architecture, letting you document systems at context, container, and deployment levels. They are the right choice when you need to show how services, databases, and external systems relate to each other. ### 3. Do all Mermaid diagram types render correctly in Confluence?[​](#3-do-all-mermaid-diagram-types-render-correctly-in-confluence "Direct link to 3. Do all Mermaid diagram types render correctly in Confluence?") Yes, all 30 diagram types render correctly when using Mermaid Plus Diagrams & AI Agent for Confluence. The app pre-renders diagrams to cached SVG at save time, so pages load fast and diagrams display consistently for all viewers. Beta diagram types like `sankey-beta`, `xychart-beta`, and `block-beta` are fully supported. The only consideration is that very large diagrams (over 100 nodes) may benefit from being split into smaller pieces for better readability. Rendering reliability depends on a few factors. First, ensure you are using the correct keyword for each diagram type. A misspelled keyword (for example, `flowshart` instead of `flowchart`) will cause the renderer to fail silently or display raw code. Second, verify that special characters in labels are wrapped in double quotes -- labels containing parentheses, brackets, or angle brackets must be quoted to parse correctly. Third, keep your diagram complexity reasonable. While Mermaid can handle hundreds of nodes, layouts become harder to read as diagrams grow. The live preview in Mermaid Plus makes it easy to catch rendering issues before you save. As you type, the left column of the configuration panel updates in real time. If your code has a syntax error, the preview shows the error message immediately, so you can fix it before inserting the macro into the page. For comprehensive troubleshooting guidance, see our [Mermaid syntax cheat sheet for Confluence](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md). ### 4. How do I choose the right Mermaid diagram type for my documentation?[​](#4-how-do-i-choose-the-right-mermaid-diagram-type-for-my-documentation "Direct link to 4. How do I choose the right Mermaid diagram type for my documentation?") Match the diagram type to the story you are telling. Use flowcharts for processes and decisions, sequence diagrams for interactions over time, class diagrams for code structure, ER diagrams for data relationships, state diagrams for status changes, Gantt charts for timelines, C4 diagrams for architecture, and mindmaps for brainstorming. If you are unsure, start with a flowchart -- it is the most versatile type and works well for most software documentation scenarios. Here is a decision framework based on the question you are trying to answer: **"How does this process work?"** -- Use a **flowchart**. Flowcharts handle branching logic, parallel paths, and decision points naturally. They are the default choice for documenting any multi-step process. **"How do these systems talk to each other?"** -- Use a **sequence diagram**. When the order of messages matters and you need to show who sends what to whom, sequence diagrams are the clearest representation. **"What does the data model look like?"** -- Use an **ER diagram** for database schemas and relational data, or a **class diagram** for object models with behavior. **"What states can this entity be in?"** -- Use a **state diagram**. State diagrams are ideal for order lifecycles, approval workflows, and any system with defined transitions between discrete states. **"What is the architecture?"** -- Use a **C4 diagram** for formal C4 model documentation, or an **architecture diagram** (`architecture-beta`) for infrastructure and service topology. Flowcharts also work well for simplified architecture views. **"What is the timeline?"** -- Use a **Gantt chart** for project schedules with dependencies, or a **timeline** for chronological events without dependency tracking. **"How is this built in code?"** -- Use a **class diagram** for OOP class hierarchies, a **block diagram** for component layout, or a **TreeView** for file and directory structure. **"What went wrong?"** -- Use an **Ishikawa (fishbone) diagram** for root cause analysis, or a **quadrant chart** for prioritizing factors by urgency and impact. ### 5. Can I use multiple Mermaid diagram types on the same Confluence page?[​](#5-can-i-use-multiple-mermaid-diagram-types-on-the-same-confluence-page "Direct link to 5. Can I use multiple Mermaid diagram types on the same Confluence page?") Absolutely. You can insert as many Mermaid macros as you need on a single page, and each one can use a different diagram type. This is especially useful for architecture decision records, design documents, and onboarding guides where you need a flowchart for the process, a sequence diagram for the API flow, and an ER diagram for the data model all in one place. For performance, try to keep the total node count across all diagrams reasonable -- under 200 nodes per page is a good guideline. Combining multiple diagram types on a single page is one of the most effective documentation patterns. A well-structured design document might include: * A **flowchart** showing the high-level process at the top of the page * A **sequence diagram** detailing the API interaction for a specific step * A **class diagram** or **ER diagram** documenting the data model * A **state diagram** showing entity lifecycle transitions This layered approach lets readers understand the system at different levels of abstraction. Someone who just needs the big picture can read the flowchart and skip the details, while an engineer implementing a specific service can dive into the sequence diagram and class diagram for that component. To keep pages performant, Mermaid Plus pre-renders each diagram to a cached SVG at save time. This means the page does not execute JavaScript for every diagram on load -- it simply displays the pre-rendered images. Even pages with five or six diagrams load quickly because the rendering work was done once when the author saved the page. ### 6. What are the beta Mermaid diagram types, and are they stable enough for production documentation?[​](#6-what-are-the-beta-mermaid-diagram-types-and-are-they-stable-enough-for-production-documentation "Direct link to 6. What are the beta Mermaid diagram types, and are they stable enough for production documentation?") Mermaid marks newer diagram types with a `-beta` suffix during their initial release phase. These include `block-beta`, `packet-beta`, `architecture-beta`, `radar-beta`, `treeView-beta`, `venn-beta`, `sankey-beta`, and the newer `swimlane-beta`, `cynefin-beta`, and `railroad-ebnf-beta`. Despite the beta label, these diagram types are stable enough for production use in Confluence and render reliably through Mermaid Plus. The suffix simply means the syntax may receive minor refinements in future Mermaid versions, so your diagrams may need small adjustments after upgrading. The beta types are some of the most useful additions to Mermaid in recent versions. Here is what each one offers: * **`block-beta`** -- Component block diagrams with columns and nested groups. Useful for system-level architecture views where you need more control over layout than a flowchart provides. * **`packet-beta`** -- Network packet structure diagrams that show field positions and bit ranges. Essential for protocol documentation and network engineering. * **`architecture-beta`** -- Infrastructure and service architecture diagrams with cloud, database, and server icons. A lighter-weight alternative to C4 diagrams. * **`radar-beta`** -- Multi-axis comparison charts. Useful for technology evaluations, skill assessments, and feature comparisons. * **`treeView-beta`** -- File and folder tree visualizations. Great for documenting project structure, configuration hierarchies, and directory layouts. * **`venn-beta`** -- Set relationship diagrams showing overlaps between categories. Useful for stakeholder analysis and capability mapping. * **`sankey-beta`** -- Flow diagrams that show quantities moving through a system. Ideal for data pipeline visualization and resource allocation charts. * **`swimlane-beta`** -- Cross-functional process diagrams showing hand-offs between teams or actors. Each lane is a subgraph; great for order fulfilment and approval flows. * **`cynefin-beta`** -- Dave Snowden's sense-making framework with five domains (clear, complicated, complex, chaotic, confusion). Useful for agile and strategy discussions. * **`railroad-ebnf-beta`** -- Syntax/grammar (railroad) diagrams for technical writers and language designers. Visualizes EBNF grammar rules. All of these render correctly in Mermaid Plus Diagrams & AI Agent for Confluence. When you open the Quick Templates panel, each beta type has its own template with working code that you can modify. ## Comparison: Top 10 Mermaid Diagram Types for Software Teams[​](#comparison-top-10-mermaid-diagram-types-for-software-teams "Direct link to Comparison: Top 10 Mermaid Diagram Types for Software Teams") The table below compares the ten diagram types most commonly used in software documentation, with guidance on when each one is the right choice. | Diagram Type | Keyword | Best For | Confluence Rendering | Complexity | | ------------ | ------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------- | -------------- | | Flowchart | `flowchart` | Process flows, decision trees, CI/CD pipelines, onboarding steps | Full support with all directions and node shapes | Low to Medium | | Sequence | `sequenceDiagram` | API call flows, service interactions, protocol documentation | Full support with notes, loops, and alt blocks | Low to Medium | | Class | `classDiagram` | OOP design, API data models, interface contracts | Full support with visibility, inheritance, composition | Medium | | ER | `erDiagram` | Database schemas, data models, migration planning | Full support with all relationship notations | Low | | State | `stateDiagram-v2` | Entity lifecycles, order statuses, deployment states | Full support with composite states and notes | Medium | | C4 | `C4Context` | System architecture, service boundaries, deployment topology | Full support with context, container, and deployment views | Medium to High | | Gantt | `gantt` | Sprint planning, release timelines, project milestones | Full support with dependencies and task states | Low | | Git Graph | `gitGraph` | Branching strategies, release workflows, Git collaboration | Full support with merge, branch, and commit | Low | | Mindmap | `mindmap` | Brainstorming sessions, topic breakdowns, knowledge maps | Full support with multi-level branching | Low | | Architecture | `architecture-beta` | Infrastructure topology, service dependencies, cloud diagrams | Full support with typed service icons | Medium | ## When to Use Each Mermaid Diagram Type[​](#when-to-use-each-mermaid-diagram-type "Direct link to When to Use Each Mermaid Diagram Type") ### Flowcharts: The Default Choice[​](#flowcharts-the-default-choice "Direct link to Flowcharts: The Default Choice") Flowcharts are the most commonly used Mermaid diagram type for good reason. They handle any scenario where you need to show steps, decisions, and branches. For software teams, the most frequent use cases are CI/CD pipeline documentation, user onboarding flows, error handling paths, and high-level system overviews. Use a flowchart when your diagram has decision points (diamond nodes), parallel paths, or loops. Choose the direction based on the shape of your content: top-down (`TD`) for hierarchical processes, left-right (`LR`) for linear pipelines. ### Sequence Diagrams: API and Service Communication[​](#sequence-diagrams-api-and-service-communication "Direct link to Sequence Diagrams: API and Service Communication") Sequence diagrams shine when you need to show who talks to whom and in what order. They are the standard choice for documenting REST API interactions, gRPC call chains, event-driven architectures, and any multi-service workflow where timing matters. Each participant gets a vertical lifeline, and horizontal arrows represent messages. Solid arrows indicate synchronous calls, dashed arrows indicate responses, and open-arrow heads indicate asynchronous messages. You can add notes, loop blocks, and alternative (alt) blocks for conditional flows. ### Class Diagrams: Code and Data Structure[​](#class-diagrams-code-and-data-structure "Direct link to Class Diagrams: Code and Data Structure") Class diagrams are essential for object-oriented design documentation. They show classes with their attributes and methods, along with relationships like inheritance (`<|--`), composition (`*--`), aggregation (`o--`), and dependency (`..>`). Use them in design documents, API specifications, and onboarding materials where new engineers need to understand the codebase structure quickly. ### ER Diagrams: Database Documentation[​](#er-diagrams-database-documentation "Direct link to ER Diagrams: Database Documentation") ER diagrams are the fastest way to document a database schema in text. They use a compact notation for relationships that is both human-readable and precise. Use them in migration plans, data model reviews, and any documentation that needs to explain how entities relate to each other. ### State Diagrams: Lifecycle and Status Documentation[​](#state-diagrams-lifecycle-and-status-documentation "Direct link to State Diagrams: Lifecycle and Status Documentation") State diagrams model the transitions an entity goes through during its lifetime. They are ideal for documenting order statuses, user account states, deployment phases, approval workflows, and any system where entities move through discrete states with defined transitions. ### C4 Diagrams: Software Architecture[​](#c4-diagrams-software-architecture "Direct link to C4 Diagrams: Software Architecture") C4 diagrams follow the C4 model for software architecture, providing views at three levels of abstraction: context (system-level), container (service-level), and deployment (infrastructure-level). Use them when you need formal architecture documentation that follows a widely recognized standard. ### Gantt Charts: Project Timelines[​](#gantt-charts-project-timelines "Direct link to Gantt Charts: Project Timelines") Gantt charts visualize project schedules with tasks, dependencies, milestones, and completion states. They are useful for sprint planning documents, release roadmaps, and any Confluence page that tracks time-based work. ### Git Graphs: Version Control Strategy[​](#git-graphs-version-control-strategy "Direct link to Git Graphs: Version Control Strategy") Git graphs visualize branching strategies, merge patterns, and release workflows. They are particularly useful in contributor guidelines and DevOps documentation where teams need to agree on a branching model. ### Mindmaps: Brainstorming and Knowledge Mapping[​](#mindmaps-brainstorming-and-knowledge-mapping "Direct link to Mindmaps: Brainstorming and Knowledge Mapping") Mindmaps are hierarchical tree diagrams for brainstorming, topic breakdowns, and knowledge organization. Use them in meeting notes, research summaries, and planning documents where you need to capture and organize ideas quickly. ### Timeline: Chronological Events[​](#timeline-chronological-events "Direct link to Timeline: Chronological Events") Timelines show events in chronological order, organized by sections. Use them for release histories, incident post-mortems, project milestones, and any documentation where sequence matters but dependency tracking (as in Gantt charts) is not needed. ## Less Common but Valuable Diagram Types[​](#less-common-but-valuable-diagram-types "Direct link to Less Common but Valuable Diagram Types") The remaining diagram types serve niche but important purposes in software documentation: **Requirement diagrams** link requirements to design elements, useful for traceability matrices and compliance documentation. **User journey maps** combine tasks with satisfaction scores (1-5), making them useful for UX documentation and customer experience mapping. **Quadrant charts** categorize items on two axes, ideal for prioritization matrices, risk assessments, and technology radar visualizations. **Pie charts** and **XY charts** present quantitative data -- survey results, budget breakdowns, performance metrics, and similar numerical information. **Treemaps** show hierarchical data as nested rectangles, useful for visualizing codebase size by directory, budget allocation, or test coverage distribution. **Sankey diagrams** visualize flow quantities through a system, making them ideal for data pipeline documentation and resource flow analysis. **Ishikawa (fishbone) diagrams** support root cause analysis with categorized causes feeding into a central problem statement -- a standard tool in incident post-mortems. **Packet diagrams** document network protocol structures with bit-level field positions, essential for networking and IoT teams. **Kanban boards** provide a simple board-style task visualization directly in Confluence, useful for lightweight project tracking. **Radar charts** compare multiple entities across several axes, helpful for technology evaluations and skill gap analysis. **TreeViews** visualize file and folder hierarchies, useful for project structure documentation and configuration walkthroughs. **Venn diagrams** show set overlaps, useful for stakeholder analysis and capability mapping. **Block diagrams** offer structured component layouts with column control, serving as a middle ground between flowcharts and C4 diagrams. **ZenUML** provides an alternative syntax for sequence diagrams with typed participants (Actor, Database, Participant), preferred by teams already familiar with ZenUML notation. ## How Mermaid Diagrams Render in Confluence[​](#how-mermaid-diagrams-render-in-confluence "Direct link to How Mermaid Diagrams Render in Confluence") Understanding how Mermaid Plus Diagrams & AI Agent for Confluence handles rendering helps you write better diagrams and troubleshoot issues faster. **Live preview.** When you insert a Mermaid macro and open the configuration panel, the left column shows a real-time preview of your diagram. As you type or modify settings, the preview updates instantly. This means you can catch layout problems, syntax errors, and visual issues before saving the macro to the page. **Cached SVG output.** When you save a diagram, Mermaid Plus renders it to a static SVG and caches the result. Page visitors see the cached SVG, not a client-side JavaScript rendering. This approach has two major benefits: pages load faster because no JavaScript execution is needed for diagrams, and diagrams display consistently across all browsers and devices. **Dark mode support.** Mermaid Plus automatically adapts diagrams to Confluence's dark/light mode. When you save a diagram, the current Confluence theme is recorded. When the page loads, if the theme has changed, text and background colors are adjusted for readability. You can also manually choose a theme (default, dark, forest, or neutral) for each macro instance. **Custom colors and fonts.** The settings panel provides five customizable colors (node, text, border, line, background) with visual color pickers, plus font family and size controls. These settings give you fine-grained control over how diagrams look without modifying the Mermaid code itself. **Output size.** You can control how large the diagram appears on the Confluence page with four size options: Small (0.5x), Medium (1x, default), Large (1.5x), and X-Large (2x). This is useful when a diagram needs to be larger for a presentation page or smaller to fit alongside text. For complete details on configuration options, themes, and settings, see the [Mermaid Plus Diagrams & AI Agent for Confluence usage guide](/docs/Mermaid-Plus-for-Confluence/usage.md). ## Tips for Writing Diagrams That Work Well in Confluence[​](#tips-for-writing-diagrams-that-work-well-in-confluence "Direct link to Tips for Writing Diagrams That Work Well in Confluence") **Start with a template.** The Quick Templates panel provides working code for all 30 diagram types. Click any template to load it into the editor, then modify it to match your needs. This is faster than writing from scratch and helps you avoid syntax errors. **Keep diagrams focused.** Each diagram should tell one story. If your flowchart has grown to 20+ nodes, consider splitting it into two or three smaller diagrams that each cover a specific part of the process. Focused diagrams are easier to read, easier to maintain, and render faster. **Use subgraphs to organize complex diagrams.** In flowcharts, subgraphs group related nodes into bordered sections. This improves both visual organization and layout efficiency, because the rendering engine treats each subgraph as a single unit during placement. **Choose the right direction.** Flowcharts support four directions. Top-down (`TD`) works best for hierarchical processes. Left-right (`LR`) is better for linear pipelines and stage-based flows. Experiment with both to find the orientation that makes your diagram easiest to follow. **Test in both light and dark modes.** Confluence users may have either theme active. Check that your diagrams are readable in both modes by toggling the Confluence theme and reviewing the rendered output. If you use custom colors, ensure they have sufficient contrast against both light and dark backgrounds. **Validate syntax before publishing.** Use the live preview in the configuration panel to catch errors before saving. For complex diagrams, consider validating in the Mermaid Live Editor at mermaid.live first, then pasting the validated code into Confluence. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Mermaid Plus Diagrams & AI Agent for Confluence -- Usage Guide](/apps/mermaid-plus-for-confluence.md) -- complete documentation for the Mermaid Plus app with templates, themes, and customizable settings * [Mermaid Syntax Cheat Sheet for Confluence](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md) -- quick reference for Mermaid syntax with copy-paste examples * [How to Create Sequence Diagrams in Confluence](/blog/how-to-create-sequence-diagrams-confluence.md) -- step-by-step guide for documenting API interactions and service communication * [How to Create Class Diagrams in Confluence](/blog/how-to-create-class-diagrams-confluence.md) -- tutorial for object-oriented design documentation with class hierarchies and relationships Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [mermaid](/blog/tags/mermaid.md) * [confluence](/blog/tags/confluence.md) * [diagram-types](/blog/tags/diagram-types.md) * [documentation](/blog/tags/documentation.md) * [developers](/blog/tags/developers.md) --- # Documenting Microservice Architectures in Confluence with Mermaid May 2, 2026 · 14 min read [NGPilot](https://ngpilot.com) Mermaid is the most popular text-based diagramming language for technical documentation. One line of code generates a flowchart. A few more produce a sequence diagram, ER diagram, or Gantt chart. Teams using Confluence can embed Mermaid diagrams directly on their pages, keeping diagrams alongside the documentation they illustrate. Who should read this * **Platform/backend engineers** documenting a microservice architecture * **Tech leads** keeping architecture docs in sync with code * **Anyone** who wants a copy-paste Mermaid syntax reference for Confluence The scenario we'll work through is the one most engineering teams hit: you run a handful of microservices, requests bounce between them, and onboarding a new engineer means drawing the system on a whiteboard every time. The fix is to capture that architecture once, in text, inside Confluence — so it versions with your docs and survives a whiteboard being wiped. Below are the four diagram patterns that cover most of a microservice architecture, each with copy-paste syntax. The full node-shape and arrow reference follows, so the same page works as both a worked example and a syntax cheat sheet. ## The four diagrams that document a microservice architecture[​](#the-four-diagrams-that-document-a-microservice-architecture "Direct link to The four diagrams that document a microservice architecture") ### 1. The service map (flowchart with subgraphs)[​](#1-the-service-map-flowchart-with-subgraphs "Direct link to 1. The service map (flowchart with subgraphs)") Start with a high-level map showing every service and how requests enter the system. Use `subgraph` to group services by boundary (edge, core, data) so the diagram reads in layers rather than as a hairball. To render Mermaid diagrams on your Confluence pages, you need a Mermaid macro. Here are three options, ranked by features: 1. **[Mermaid Plus Diagrams & AI Agent for Confluence](/docs/Mermaid-Plus-for-Confluence/usage.md)** — dedicated Mermaid editor with 30 diagram types, live preview, templates, and customizable themes. Type `/mermaid` to insert the macro. Install from the [Atlassian Marketplace](https://marketplace.atlassian.com/). 2. **[Diagram Duo for Confluence](/docs/diagram-duo-for-confluence/usage.md)** — combines a full Mermaid editor **and** an Excalidraw visual canvas in one macro. Best choice if your team uses both text-based and visual diagrams. Type `/mermaid` or `/excalidraw` on any page. 3. **Confluence built-in Mermaid macro** — limited to basic diagram types with no template library or theme customization. All examples on this page work with any of these options. Copy the code, paste it into the macro, and publish. ## Quick Syntax Reference[​](#quick-syntax-reference "Direct link to Quick Syntax Reference") *** ## Frequently Asked Questions[​](#frequently-asked-questions "Direct link to Frequently Asked Questions") ### 1. How do I create a flowchart in Mermaid?[​](#1-how-do-i-create-a-flowchart-in-mermaid "Direct link to 1. How do I create a flowchart in Mermaid?") Flowcharts are the most popular Mermaid diagram type. Start with the `flowchart` keyword followed by a direction indicator: * `TD` or `TB` -- top-down (top to bottom) * `BT` -- bottom to top * `LR` -- left to right * `RL` -- right to left Then define nodes and connections: ``` flowchart TD A[Start] --> B{Decision} B -->|Yes| C[Process Action] B -->|No| D[End] C --> D ``` The direction keyword controls the overall layout. Every node is referenced by an ID (like `A`, `B`, `C`) and you define its shape with brackets around the label text. ### 2. How do I add text labels to Mermaid arrows?[​](#2-how-do-i-add-text-labels-to-mermaid-arrows "Direct link to 2. How do I add text labels to Mermaid arrows?") Labels on arrows make your diagrams self-documenting. Use the pipe `|` character immediately after the arrow operator: ``` flowchart LR A[Submit Request] -->|Approved| B[Process Payment] A -->|Rejected| C[Notify Customer] ``` For longer labels that contain special characters, wrap the label text in double quotes: ``` flowchart LR A -->|"Long label with (special) characters"| B ``` You can also place labels on the arrow using the `-- text -->` syntax: ``` flowchart LR A -- Review needed --> B ``` ### 3. How do I create subgraphs in Mermaid?[​](#3-how-do-i-create-subgraphs-in-mermaid "Direct link to 3. How do I create subgraphs in Mermaid?") Subgraphs group related nodes together visually with a bordered box. Use the `subgraph` keyword, indent the grouped content, and close with `end`: ``` flowchart TB subgraph Frontend A[UI Layer] --> B[State Management] end subgraph Backend C[API Gateway] --> D[Service Layer] end B --> C ``` You can also give a subgraph a display title and control its direction independently: ``` flowchart TB subgraph Auth["Authentication Module"] direction LR E[Login] --> F[Token Validation] F --> G[Session] end ``` ### 4. How do I style nodes with different shapes?[​](#4-how-do-i-style-nodes-with-different-shapes "Direct link to 4. How do I style nodes with different shapes?") Mermaid uses different bracket types to control node shapes. Here is a comprehensive reference: ``` flowchart LR A[Rounded Rectangle] B([Stadium / Pill Shape]) C[[Subroutine]] D[(Database Cylinder)] E((Circle)) F>Asymmetric Flag] G{Diamond / Decision} H{{Hexagon}} ``` | Bracket Syntax | Shape | Typical Use | | -------------- | ----------------- | ---------------------- | | `[text]` | Rounded rectangle | Standard process step | | `([text])` | Stadium / pill | Start or end terminal | | `[[text]]` | Subroutine | Reusable process | | `[(text)]` | Cylinder | Database or data store | | `((text))` | Circle | Junction or connector | | `>text]` | Asymmetric | Manual input or output | | `{text}` | Diamond | Decision point | | `{{text}}` | Hexagon | Preparation step | ### 5. What is the correct syntax for a sequence diagram?[​](#5-what-is-the-correct-syntax-for-a-sequence-diagram "Direct link to 5. What is the correct syntax for a sequence diagram?") Sequence diagrams show interactions between participants over time. Start with the `sequenceDiagram` keyword: ``` sequenceDiagram participant User participant Frontend participant API participant DB User->>Frontend: Submit form Frontend->>API: POST /api/orders API->>DB: INSERT query DB-->>API: Confirmation API-->>Frontend: 201 Created Frontend-->>User: Success message ``` Key arrow types for sequence diagrams: * `->>` solid line with arrowhead (synchronous request) * `-->>` dashed line with arrowhead (response or return) * `--)` solid line with open arrow (asynchronous message) * `--)` dashed line with open arrow (asynchronous return) Add notes to clarify specific steps: ``` sequenceDiagram participant A as Client participant B as Server Note over A: User initiates request A->>B: GET /data Note over A,B: TLS encrypted B-->>A: JSON response ``` ### 6. How do I create an ER diagram in Mermaid?[​](#6-how-do-i-create-an-er-diagram-in-mermaid "Direct link to 6. How do I create an ER diagram in Mermaid?") Entity-relationship diagrams use the `erDiagram` keyword. Define entities with their attributes and relationships between them: ``` erDiagram CUSTOMER ||--o{ ORDER : "places" ORDER ||--|{ LINE_ITEM : "contains" CUSTOMER { int id PK string name string email date created_at } ORDER { int id PK int customer_id FK date order_date string status } LINE_ITEM { int id PK int order_id FK string product_name int quantity float price } ``` Relationship notation uses these operators: | Symbol | Meaning | | ------------ | ------------------- | | `\|\|` | Exactly one | | `o{` | Zero or more | | `\|\|--o{` | One to zero-or-more | | `\|\|--\|{` | One to one-or-more | | `\|\|--\|\|` | One to one | ### 7. How do I create a class diagram in Mermaid?[​](#7-how-do-i-create-a-class-diagram-in-mermaid "Direct link to 7. How do I create a class diagram in Mermaid?") Class diagrams use the `classDiagram` keyword. Define classes with their attributes, methods, and relationships: ``` classDiagram class Animal { +String name +int age +makeSound() void +move() void } class Dog { +String breed +fetch() void +bark() void } class Cat { +bool indoor +purr() void +scratch() void } Animal <|-- Dog Animal <|-- Cat ``` Visibility modifiers: * `+` public * `-` private * `#` protected Relationship types include `<|--` (inheritance), `*--` (composition), `o--` (aggregation), `-->` (association), and `..>` (dependency). ### 8. How do I create a Gantt chart in Mermaid?[​](#8-how-do-i-create-a-gantt-chart-in-mermaid "Direct link to 8. How do I create a Gantt chart in Mermaid?") Gantt charts visualize project schedules using the `gantt` keyword: ``` gantt title Project Timeline dateFormat YYYY-MM-DD axisFormat %b %d section Planning Requirements gathering :done, req, 2026-05-01, 10d Architecture design :active, arch, after req, 5d section Development Frontend implementation :dev-fe, after arch, 15d Backend API :dev-be, after arch, 12d Integration testing :test, after dev-fe, 7d section Deployment Staging release :stage, after test, 3d Production release :prod, after stage, 2d ``` Task states include `done`, `active`, and (default) future tasks. You can set task dependencies using `after` followed by the task ID. ### 9. How do I add comments in Mermaid syntax?[​](#9-how-do-i-add-comments-in-mermaid-syntax "Direct link to 9. How do I add comments in Mermaid syntax?") Comments use the `%%` prefix and are ignored during rendering: ``` flowchart LR %% This is a comment and will not appear in the diagram A[Start] --> B[End] %% You can also comment out lines for debugging %% A --> C[Hidden node] ``` Comments are useful for leaving notes for collaborators or temporarily disabling parts of a diagram during editing. ### 10. How do I style Mermaid diagrams with custom colors?[​](#10-how-do-i-style-mermaid-diagrams-with-custom-colors "Direct link to 10. How do I style Mermaid diagrams with custom colors?") Use the `style` keyword to apply CSS-like properties to specific nodes: ``` flowchart LR A[Start] --> B[Process] --> C[End] style A fill:#4CAF50,stroke:#2E7D32,color:#fff style B fill:#2196F3,stroke:#1565C0,color:#fff style C fill:#f44336,stroke:#c62828,color:#fff ``` For reusable styles, define class definitions with `classDef`: ``` flowchart LR A[Start] --> B[Process] --> C[End] classDef green fill:#e8f5e9,stroke:#4CAF50,stroke-width:2px classDef blue fill:#e3f2fd,stroke:#2196F3,stroke-width:2px class A green class B,C blue ``` ### 11. How do I use Mermaid diagrams in Confluence?[​](#11-how-do-i-use-mermaid-diagrams-in-confluence "Direct link to 11. How do I use Mermaid diagrams in Confluence?") You have three options for rendering Mermaid diagrams in Confluence: **[Mermaid Plus Diagrams & AI Agent for Confluence](/docs/Mermaid-Plus-for-Confluence/usage.md)** (recommended) — dedicated Mermaid editor with 30 diagram types, live preview, templates, and theme customization. Best if your team wants a focused Mermaid experience. 1. Install Mermaid Plus from the Atlassian Marketplace 2. Open a Confluence page in edit mode 3. Type `/mermaid` and select the Mermaid Plus macro 4. Paste your Mermaid code into the code editor 5. Preview, save, and publish the page **[Diagram Duo for Confluence](/docs/diagram-duo-for-confluence/usage.md)** — combines a Mermaid code editor with an Excalidraw visual canvas in one macro. Switch between text-based and visual diagramming on the same page. Type `/mermaid` or `/excalidraw` to insert. **Confluence built-in macro** — supports basic diagram types with no template library or theme options. Good for getting started quickly. All three options render the Mermaid syntax documented in this cheat sheet. ### 12. How do I create a pie chart in Mermaid?[​](#12-how-do-i-create-a-pie-chart-in-mermaid "Direct link to 12. How do I create a pie chart in Mermaid?") Pie charts use the `pie` keyword: ``` pie title Market Share by Region "North America" : 35 "Europe" : 28 "Asia Pacific" : 25 "Latin America" : 8 "Other" : 4 ``` The values are treated as relative proportions. Mermaid calculates the percentages automatically based on the total. ### 13. How do I create a state diagram in Mermaid?[​](#13-how-do-i-create-a-state-diagram-in-mermaid "Direct link to 13. How do I create a state diagram in Mermaid?") State diagrams use the `stateDiagram-v2` keyword (the v2 version supports more features): ``` stateDiagram-v2 [*] --> Idle Idle --> Processing : Start Processing --> Success : Complete Processing --> Error : Failure Error --> Idle : Retry Success --> [*] ``` Use `[*]` to denote the start and end states. Add labels to transitions with a colon after the target state. ### 14. How do I create a mind map in Mermaid?[​](#14-how-do-i-create-a-mind-map-in-mermaid "Direct link to 14. How do I create a mind map in Mermaid?") Mind maps are supported in Mermaid v9.3 and later using the `mindmap` keyword: ``` mindmap root((Central Topic)) Branch A Sub-topic A1 Sub-topic A2 Branch B Sub-topic B1 Detail B1a Detail B1b Sub-topic B2 Branch C Sub-topic C1 ``` Indentation defines the hierarchy. Each level of indentation creates a deeper branch. ### 15. How do I troubleshoot Mermaid diagrams that do not render?[​](#15-how-do-i-troubleshoot-mermaid-diagrams-that-do-not-render "Direct link to 15. How do I troubleshoot Mermaid diagrams that do not render?") When a Mermaid diagram fails to render in Confluence, check these common issues: * **Missing keyword**: Every diagram must start with a valid keyword (`flowchart`, `sequenceDiagram`, `erDiagram`, etc.) * **Incorrect indentation**: Some diagram types are sensitive to indentation, especially subgraphs and class definitions * **Special characters in labels**: Wrap labels containing special characters in double quotes * **Trailing whitespace**: Extra spaces at the end of lines can sometimes cause parsing errors * **Unsupported features**: Confluence may use an older version of Mermaid that does not support newer features like mind maps For a comprehensive troubleshooting guide, see [Mermaid Not Rendering? Fixes and FAQ](/blog/faq-mermaid-troubleshooting.md). *** ## Quick Syntax Reference[​](#quick-syntax-reference-1 "Direct link to Quick Syntax Reference") | Element | Syntax | Example | | ------------------ | ----------------------- | ------------------------------ | | Flowchart | `flowchart TD/LR` | `flowchart TD` | | Sequence diagram | `sequenceDiagram` | `sequenceDiagram` | | Class diagram | `classDiagram` | `classDiagram` | | ER diagram | `erDiagram` | `erDiagram` | | Gantt chart | `gantt` | `gantt` | | State diagram | `stateDiagram-v2` | `stateDiagram-v2` | | Pie chart | `pie` | `pie title Sales` | | Mind map | `mindmap` | `mindmap` | | Arrow with label | \`--> | text | | Dashed arrow | `-.->` | `A -.-> B` | | Thick arrow | `==>` | `A ==> B` | | Subgraph | `subgraph Name ... end` | `subgraph Auth\n A --> B\nend` | | Comment | `%% text` | `%% This is a comment` | | Node style | `style ID fill:#hex` | `style A fill:#4CAF50` | | Rounded rectangle | `A[text]` | `A[Start]` | | Diamond / decision | `A{text}` | `B{Choice?}` | | Circle | `A((text))` | `C((Merge))` | | Database cylinder | `A[(text)]` | `DB[(Database)]` | *** ## Frequently Asked Questions[​](#frequently-asked-questions-1 "Direct link to Frequently Asked Questions") *** ## 5 Copy-Paste Mermaid Diagrams[​](#5-copy-paste-mermaid-diagrams "Direct link to 5 Copy-Paste Mermaid Diagrams") These five diagrams cover the most common patterns teams need. Copy any of them into your Confluence Mermaid macro and customize the content. ### Flowchart: User Registration Process[​](#flowchart-user-registration-process "Direct link to Flowchart: User Registration Process") ``` flowchart TD A([User visits signup page]) --> B[Fill registration form] B --> C{Valid input?} C -->|Yes| D[Create account] C -->|No| E[Show validation errors] E --> B D --> F{Email verification?} F -->|Verified| G[Activate account] F -->|Pending| H[Send reminder email] H --> I{Max retries?} I -->|No| H I -->|Yes| J[Deactivate account] G --> K([User logged in]) ``` ### Sequence Diagram: API Authentication Flow[​](#sequence-diagram-api-authentication-flow "Direct link to Sequence Diagram: API Authentication Flow") ``` sequenceDiagram participant Client participant AuthServer as Auth Server participant ResourceServer as Resource Server participant Cache as Redis Cache Client->>AuthServer: POST /oauth/token (credentials) AuthServer->>Cache: Check existing session Cache-->>AuthServer: No active session AuthServer->>AuthServer: Validate credentials AuthServer-->>Client: Access token + Refresh token Note over Client: Store tokens securely Client->>ResourceServer: GET /api/data (Bearer token) ResourceServer->>AuthServer: Validate token AuthServer-->>ResourceServer: Token valid ResourceServer-->>Client: 200 OK + JSON data Note over Client,AuthServer: After token expires Client->>AuthServer: POST /oauth/token (refresh token) AuthServer-->>Client: New access token ``` ### Class Diagram: E-Commerce Order System[​](#class-diagram-e-commerce-order-system "Direct link to Class Diagram: E-Commerce Order System") ``` classDiagram class User { +int id +String name +String email +login() bool +logout() void } class Order { +int id +Date createdAt +String status +calculateTotal() float +cancel() bool } class Product { +int id +String name +float price +int stock +reduceStock(qty: int) void } class Payment { +int id +float amount +String method +process() bool +refund() bool } class OrderItem { +int quantity +float unitPrice +getSubtotal() float } User "1" --> "*" Order : places Order "1" --> "*" OrderItem : contains OrderItem "*" --> "1" Product : references Order "1" --> "1" Payment : paid by ``` ### ER Diagram: Blog Platform Schema[​](#er-diagram-blog-platform-schema "Direct link to ER Diagram: Blog Platform Schema") ``` erDiagram AUTHOR ||--o{ POST : "writes" POST ||--o{ COMMENT : "receives" POST }o--|| CATEGORY : "belongs to" POST ||--o{ TAG_POST : "tagged with" TAG ||--o{ TAG_POST : "applied to" AUTHOR { int id PK string username string email string bio date joined_at } POST { int id PK int author_id FK int category_id FK string title text content string status date published_at } COMMENT { int id PK int post_id FK string author_name text body date created_at } CATEGORY { int id PK string name string slug } TAG { int id PK string name string slug } TAG_POST { int tag_id FK int post_id FK } ``` ### Gantt Chart: Software Release Timeline[​](#gantt-chart-software-release-timeline "Direct link to Gantt Chart: Software Release Timeline") ``` gantt title Software Release v2.0 Timeline dateFormat YYYY-MM-DD axisFormat %b %d section Design UX research :done, ux, 2026-04-01, 7d Wireframes :done, wire, after ux, 5d Visual design :done, vis, after wire, 7d section Development Frontend sprint 1 :active, fe1, 2026-04-21, 10d Frontend sprint 2 :fe2, after fe1, 10d Backend API :be, 2026-04-21, 14d Integration :int, after fe2, 5d section Testing QA regression :qa, after int, 7d UAT :uat, after qa, 5d Bug fixes :fix, after uat, 5d section Release Staging deploy :stage, after fix, 2d Production deploy :prod, after stage, 1d Post-release monitor :mon, after prod, 5d ``` *** ## Tips for Using Mermaid in Confluence[​](#tips-for-using-mermaid-in-confluence "Direct link to Tips for Using Mermaid in Confluence") **Keep diagrams focused.** A single diagram should tell one story. If your flowchart has more than 15 nodes, consider splitting it into multiple diagrams with linking subgraphs. **Use consistent naming.** Adopt a naming convention for your node IDs (like `step1`, `step2` or `A`, `B`, `C`) and stick with it across your team's diagrams. This makes collaboration and code reviews much easier. **Test incrementally.** When building complex diagrams, add a few nodes at a time and preview after each addition. This makes it much easier to spot the exact change that broke the rendering. **Leverage templates.** If your team creates similar diagrams repeatedly (onboarding flows, deployment pipelines, API interactions), save the Mermaid code as a Confluence template so everyone starts from a consistent baseline. **Version your diagrams.** Since Mermaid is text-based, Confluence's page history captures every change. Use meaningful commit messages when updating complex diagrams so your team can track what changed and why. *** ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Mermaid Plus Diagrams & AI Agent for Confluence](/apps/mermaid-plus-for-confluence.md) -- dedicated Mermaid editor with 30 diagram types, templates, and theme settings * [Excalidraw Plus for Confluence](/apps/excalidraw-plus-for-confluence.md) -- visual drawing with 220+ shape libraries for architecture and design diagrams * [Diagram Duo for Confluence](/apps/excalidraw-mermaid-diagrams-for-confluence.md) -- combined Mermaid + Excalidraw editor in one macro * [Graphviz Charts for Confluence](/apps/graphviz-charts-for-confluence.md) -- alternative text-based diagramming with DOT/Graphviz syntax for network and graph diagrams * [Confluence Diagram Tools Compared](/blog/confluence-diagram-tools-comparison.md) -- side-by-side comparison of diagramming options available for Confluence teams * [Mermaid Diagram Types for Confluence](/blog/faq-mermaid-diagram-types-confluence.md) -- when to use each of the 30 diagram types * [How to Create Gantt Charts in Confluence](/blog/how-to-create-gantt-charts-confluence.md) -- step-by-step guide with copy-paste examples * [How to Create Pie Charts in Confluence](/blog/how-to-create-pie-charts-confluence.md) -- data visualization guide with Mermaid syntax * [Free Confluence Diagram Plugin](/blog/confluence-free-diagram-plugin.md) -- free diagram apps compared Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [mermaid](/blog/tags/mermaid.md) * [confluence](/blog/tags/confluence.md) * [syntax](/blog/tags/syntax.md) * [cheat-sheet](/blog/tags/cheat-sheet.md) * [diagrams](/blog/tags/diagrams.md) --- # Mermaid in Confluence Not Rendering? Fixes & FAQ April 21, 2026 · 13 min read [NGPilot](https://ngpilot.com) Mermaid diagrams have become a go-to way for engineering and product teams to document architectures, workflows, and data models directly inside Confluence pages. Instead of exporting images from a desktop tool and re-uploading every time something changes, you write a few lines of text and the diagram renders inline. But when something breaks — a diagram shows raw code, colors disappear, or the whole page grinds to a halt — it can be frustrating to figure out where the problem lies. This FAQ covers the most common issues teams encounter when using Mermaid inside Confluence, with specific fixes, syntax tips, and performance guidance. Whether you are troubleshooting a single broken flowchart or standardizing diagram practices across a large organization, the answers below should get you back on track quickly. ## Why does my Mermaid code show raw text instead of a diagram?[​](#why-does-my-mermaid-code-show-raw-text-instead-of-a-diagram "Direct link to Why does my Mermaid code show raw text instead of a diagram?") When you see raw Mermaid syntax on the published page instead of a rendered diagram, the root cause is almost always that the Mermaid macro is not properly inserted or the app is not enabled. In the Confluence editor, type `/mermaid` and select the **Mermaid Plus** macro from the dropdown. If that command does not appear, the Mermaid Plus app is either not installed or not enabled for your space. To resolve this, navigate to **Confluence Administration > Apps** and confirm that Mermaid Plus Diagrams & AI Agent for Confluence is listed and active. If you are a space admin but not a site admin, check whether the app has been restricted to certain spaces. In some cases, the macro appears in the editor but the published page still shows raw text — this typically means the app's JavaScript bundle is being blocked by a Content Security Policy or an ad-blocker browser extension. Try opening the page in an incognito window to rule out browser extensions, and ask your Confluence administrator to verify the CSP headers allow scripts from the app domain. If you recently upgraded Confluence, verify that the Mermaid Plus app version is compatible with your new Confluence version. App vendors usually release compatibility updates within a few days of a major Confluence release. ## My diagram renders in the editor but not on the published page. How do I fix it?[​](#my-diagram-renders-in-the-editor-but-not-on-the-published-page-how-do-i-fix-it "Direct link to My diagram renders in the editor but not on the published page. How do I fix it?") This is one of the most frequently reported issues, and it usually comes down to script loading behavior. The Confluence editor and the published page view use different rendering pipelines. In the editor, the Mermaid app can inject its JavaScript directly. On the published page, scripts may be lazy-loaded or deferred for performance reasons, which can cause a race condition where the page HTML loads but Mermaid never initializes. First, try clearing your browser cache and doing a hard refresh of the published page. If that works, the issue was a cached version of the page that predated your macro insertion. If the problem persists, check whether your Confluence theme or any custom HTML injections are interfering with the Mermaid script tags. Some third-party themes strip inline scripts for security. Another common cause is a mismatch between the app version and the Confluence version. Check the Mermaid Plus release notes for compatibility information. If you are on Confluence Cloud, the app updates automatically, but on Confluence Data Center you may need to manually approve the update in the Universal Plugin Manager. Republishing the page after an app update often resolves the issue. ## I get a "Syntax error" in my Mermaid diagram. How do I debug it?[​](#i-get-a-syntax-error-in-my-mermaid-diagram-how-do-i-debug-it "Direct link to I get a \"Syntax error\" in my Mermaid diagram. How do I debug it?") Syntax errors are by far the most common problem for teams new to Mermaid. The fastest way to diagnose one is to paste your code into the **Mermaid Live Editor** at [mermaid.live](https://mermaid.live). The Live Editor renders your diagram in real time and highlights the exact line where parsing fails, which removes the guesswork entirely. Here are the syntax errors teams encounter most often: **Unclosed subgraph or block.** Every `subgraph` keyword must have a matching `end`. Mermaid will not throw an error on the `subgraph` line — it will fail at the end of the file when it runs out of input without finding `end`. Always count your `subgraph` and `end` pairs. ``` flowchart TD subgraph A node1 --> node2 end subgraph B node3 --> node4 end ``` **Wrong indentation.** Unlike Python, Mermaid does not require indentation, but inconsistent indentation in class diagrams and sequence diagrams can cause parsers to misread your intent. Keep indentation purely for readability and do not mix tabs and spaces. **Missing arrows or operators.** In flowcharts, every connection needs a valid arrow operator (`-->`, `---`, `==>`, `-.-`, and so on). A bare `node1 node2` with no operator between them will produce a syntax error. **Unsupported diagram features.** Mermaid adds new features regularly, but the version bundled in your Confluence app may lag behind the latest upstream release. If a feature works in the Live Editor but fails in Confluence, check which Mermaid version your app uses and consult the Mermaid changelog for when that feature was introduced. ## Common Mermaid syntax errors[​](#common-mermaid-syntax-errors "Direct link to Common Mermaid syntax errors") | Error message or symptom | Cause | Fix | | ------------------------------------------ | -------------------------------------------------- | --------------------------------------------------------------------------------- | | "Parse error on line X" | Unclosed `subgraph` or missing `end` | Add a matching `end` for every `subgraph` block | | Diagram renders partially and stops | Invalid arrow operator or typo in a node reference | Double-check all `-->`, `---`, and node IDs for typos | | "Error: Lexical error" | Special characters in labels not wrapped in quotes | Wrap label text containing `()[]{}>` in double quotes: `A["Label (with parens)"]` | | Entire diagram shows as code | Macro not inserted or app disabled | Type `/mermaid` in editor; verify app is installed and enabled | | Blank white space where diagram should be | JavaScript blocked by CSP or browser extension | Test in incognito; ask admin to allow script domains in CSP | | Colors not applied from `style` statements | Style references node ID that does not exist | Ensure the `style` line references the exact node ID used in the diagram | | Sequence diagram participants overlap | Too many participants for default width | Use shorter aliases or reduce participant count; split into two diagrams | ## Supported diagram types[​](#supported-diagram-types "Direct link to Supported diagram types") Mermaid supports a wide range of diagram types, and Mermaid Plus Diagrams & AI Agent for Confluence exposes all of them through a single macro. The following table lists each diagram type, its keyword, and a brief description of when to use it. | Diagram type | Keyword | Use for | | ------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | Flowchart | `flowchart` | Process flows, decision trees, system architecture. Supports direction flags: `TD` (top-down), `LR` (left-right), `BT` (bottom-top), `RL` (right-left) | | Sequence | `sequenceDiagram` | Interactions between actors/services over time, API call flows, step-by-step processes | | Class | `classDiagram` | Object-oriented class hierarchies, data models, UML-style relationships | | State | `stateDiagram-v2` | State machines, lifecycle diagrams, status transitions | | Entity-Relationship | `erDiagram` | Database schemas, entity relationships, data architecture | | Gantt | `gantt` | Project timelines, milestone tracking, sprint planning | | Pie | `pie` | Proportional data, survey results, budget breakdowns | | Mindmap | `mindmap` | Brainstorming trees, hierarchical topic breakdowns, knowledge maps | | Timeline | `timeline` | Chronological events, release histories, project milestones | | Gitgraph | `gitGraph` | Branching strategies, release workflows, Git collaboration models | | C4 | `C4Context`, `C4Container`, `C4Deployment` | Software architecture diagrams following the C4 model | | Sankey | `sankey-beta` | Flow of resources, budget allocation, energy transfers between categories | | Block | `block-beta` | Block diagrams for system components and their relationships | | Quadrant | `quadrantChart` | Priority matrices, risk/effort analysis, two-axis categorizations | Not every diagram type supports every feature. For example, `style` statements work in flowcharts and sequence diagrams but have limited support in pie and gantt charts. When in doubt, test in the Mermaid Live Editor first. ## How do I control the layout direction of my flowchart?[​](#how-do-i-control-the-layout-direction-of-my-flowchart "Direct link to How do I control the layout direction of my flowchart?") Flowcharts in Mermaid default to top-down (`TD`), but you can change the orientation by specifying a direction flag after the `flowchart` keyword. The four supported directions are: * **TD** or **TB** — Top to Down (default). Best for hierarchical processes and org charts. * **LR** — Left to Right. Ideal for linear pipelines, CI/CD stages, and timeline-like flows. * **BT** — Bottom to Top. Useful for bottom-up dependency charts and reverse traceability. * **RL** — Right to Left. Rare but helpful for RTL language layouts or reverse data-flow diagrams. Example: ``` flowchart LR A[Source] --> B[Build] --> C[Test] --> D[Deploy] ``` Choosing the right direction can make a significant difference in readability. Wide, shallow diagrams usually work best with `LR`, while deep, branching structures are easier to follow with `TD`. If your diagram has more than three levels of nesting, consider splitting it into subgraphs or multiple linked diagrams. ## Why are colors not showing consistently in my Mermaid diagrams?[​](#why-are-colors-not-showing-consistently-in-my-mermaid-diagrams "Direct link to Why are colors not showing consistently in my Mermaid diagrams?") Color inconsistencies in Mermaid diagrams usually stem from one of three sources: theme conflicts, incorrect style syntax, or CSS overrides from the Confluence space. **Theme conflicts.** Mermaid Plus Diagrams & AI Agent for Confluence ships with built-in themes that automatically adapt to Confluence's light and dark modes. If you hardcode colors using `style` statements or `classDef` rules, those colors may look fine in light mode but become invisible against a dark background. The recommended approach is to use semantic color names or test your diagrams in both modes using the theme toggle in Mermaid Plus settings. **Incorrect style syntax.** Style statements in Mermaid must reference exact node IDs and use valid CSS properties. A common mistake is styling a node ID that includes special characters without quoting it correctly. For example: ``` flowchart TD A["My Node"] --> B["Other Node"] style A fill:#f9f,stroke:#333 ``` Note that the `style` statement references the node ID `A`, not the label text `"My Node"`. Mixing these up will silently fail — the style is simply not applied. **CSS overrides from Confluence.** Space administrators can inject custom CSS that may override Mermaid's default styles. If your diagrams look correct in one space but broken in another, compare the space stylesheets. Remove or scope any global rules that target `svg`, `path`, or `rect` elements, as these will interfere with Mermaid's rendered output. ## How can I improve Mermaid rendering performance?[​](#how-can-i-improve-mermaid-rendering-performance "Direct link to How can I improve Mermaid rendering performance?") Performance becomes a real concern when diagrams grow large or when a single Confluence page contains multiple complex diagrams. The guidelines below will help keep your pages responsive. **Keep individual diagrams under 100 nodes.** Beyond roughly 100 nodes, client-side Mermaid rendering starts to degrade noticeably, especially on older hardware or mobile devices. If your architecture diagram has grown to 150+ nodes, split it into logical subsystems using subgraphs or break it into multiple separate diagrams on the same page. **Use cached SVG for large diagrams.** Mermaid Plus Diagrams & AI Agent for Confluence renders diagrams to cached SVG, so page visitors see the pre-rendered result without needing client-side JavaScript execution on every page load. This keeps pages fast even with multiple diagrams. **Avoid deeply nested subgraphs.** Each level of nesting increases the layout computation time. If you have subgraphs three or four levels deep, consider flattening the structure or representing the outer containers as separate linked diagrams. **Minimize simultaneous diagrams on one page.** A Confluence page with ten large flowcharts will be slow regardless of how well each individual diagram is written. If you need many diagrams on a single page (for example, a design-decision document), consider using collapsible sections or a table-of-contents structure that spreads diagrams across child pages. **Use descriptive but concise labels.** Long labels force the layout engine to allocate more space and can result in awkward node sizes. Aim for labels under 30 characters where possible, and use line breaks (`
`) inside labels rather than relying on the engine to wrap text. ## My Mermaid diagrams are too large or overlap other content. What can I do?[​](#my-mermaid-diagrams-are-too-large-or-overlap-other-content-what-can-i-do "Direct link to My Mermaid diagrams are too large or overlap other content. What can I do?") Oversized or overlapping diagrams are usually a layout problem rather than a syntax one. Here are the most effective fixes. **Adjust the direction flag.** A diagram that sprawls horizontally in `LR` mode may fit cleanly in `TD` mode, or vice versa. Experiment with different direction flags to find the orientation that best uses the available page width. **Shorten labels and reduce node count.** Every additional word in a label increases the rendered width of that node. Use abbreviations or move detailed descriptions into tooltips or surrounding text. **Use subgraphs to group related nodes.** Subgraphs not only organize your diagram logically — they also help the layout engine allocate space more efficiently by treating groups as single units during the initial placement pass. **Configure the macro's width and scale settings.** Mermaid Plus Diagrams & AI Agent for Confluence lets you set a maximum width and a scale factor for each macro instance. If your diagram is rendering at full size and overflowing the page container, set a max-width of 100% and enable auto-scaling so the SVG fits within the available space. **Split into multiple diagrams.** If none of the above work, the most reliable solution is to break the diagram into two or three smaller diagrams connected by descriptive text. This also improves readability for your audience, since a single massive flowchart is harder to follow than a series of focused ones. ## What features does Mermaid Plus Diagrams & AI Agent for Confluence provide?[​](#what-features-does-mermaid-plus-diagrams--ai-agent-for-confluence-provide "Direct link to What features does Mermaid Plus Diagrams & AI Agent for Confluence provide?") Mermaid Plus Diagrams & AI Agent for Confluence extends the base Mermaid library with features specifically designed for enterprise Confluence environments. **Macro insertion.** Type `/mermaid` in the Confluence editor to insert the macro instantly. The macro opens an inline code editor with syntax highlighting, so you can write and preview your diagram without leaving the page. **Custom themes.** The app includes multiple built-in themes (default, dark, forest, neutral) and supports custom theme definitions that space admins can configure. This ensures your diagrams match your organization's visual identity. **Light and dark mode.** Mermaid Plus automatically detects whether a user is viewing Confluence in light or dark mode and applies the appropriate theme. You can also force a specific theme per macro if you need consistent colors regardless of the user's preference. **Cached SVG rendering.** Instead of rendering every diagram in the browser on each page load, Mermaid Plus renders diagrams to cached SVG. This keeps pages fast because the Mermaid.js library is only loaded during editing -- not when viewing pages. ## Quick tips for writing reliable Mermaid diagrams[​](#quick-tips-for-writing-reliable-mermaid-diagrams "Direct link to Quick tips for writing reliable Mermaid diagrams") * Always validate your syntax in the [Mermaid Live Editor](https://mermaid.live) before pasting into Confluence. * Use double quotes around any label that contains special characters. * Count your `subgraph` and `end` pairs every time you edit a flowchart. * Keep individual diagrams under 100 nodes for best performance. * Test your diagrams in both light and dark Confluence themes before publishing. * Use `classDef` and `style` statements instead of external CSS for coloring nodes. * Choose the right diagram type for the job — do not force a flowchart when a sequence diagram or ER diagram communicates the idea more clearly. ## Related resources[​](#related-resources "Direct link to Related resources") * [Mermaid Plus Diagrams & AI Agent for Confluence — documentation](/apps/mermaid-plus-for-confluence.md) * [Mermaid Plus Diagrams for Jira](/apps/mermaid-plus-diagrams-for-jira.md) — Mermaid in Jira issues * [Create Mermaid diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md) — complete how-to guide with examples * [Excalidraw & Mermaid Visual Editor](/apps/excalidraw-mermaid-diagrams-for-confluence.md) — combine freeform and structured diagrams Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [mermaid](/blog/tags/mermaid.md) * [confluence](/blog/tags/confluence.md) * [diagrams](/blog/tags/diagrams.md) * [troubleshooting](/blog/tags/troubleshooting.md) --- # Modern FAQ vs Modern Questions for Confluence — Feature Comparison April 18, 2026 · 6 min read [NGPilot](https://ngpilot.com) Teams need two types of knowledge sharing in Confluence: **structured FAQ sections** for pages, and **community Q\&A forums** for ongoing discussion. Confluence has no built-in solution for either. We built two apps to cover both needs — **Modern FAQ for Confluence** for polished, drag-and-drop FAQ sections, and **Modern Questions for Confluence** for structured Q\&A with voting and accepted answers. In this post we compare both against the alternatives on the Atlassian Marketplace. ## Two Problems, One Ecosystem[​](#two-problems-one-ecosystem "Direct link to Two Problems, One Ecosystem") **FAQ sections** — You want a clean, collapsible list of questions and answers on a Confluence page. Think product FAQs, onboarding guides, or IT help pages. Teams typically cobble together toggles or tables that look clunky. **Q\&A forums** — You want a space where anyone can ask a question, others can answer, and the best answer rises to the top. Think Stack Overflow for your company. Confluence has nothing built-in for this. These are different problems — and the apps that solve them are different too. Let's look at both. *** ## Part 1: FAQ Apps for Confluence[​](#part-1-faq-apps-for-confluence "Direct link to Part 1: FAQ Apps for Confluence") ### What's Available[​](#whats-available "Direct link to What's Available") | App | Vendor | Installs | Rating | Last Updated | Pricing | | ----------------------------- | ---------------- | -------- | ------------------ | ------------ | ------------------ | | FAQ for Confluence | VECTORS | 310 | 2.2/5 (12 reviews) | Mar 2026 | Paid | | FAQ Basic for Confluence | Start Off Easily | 183 | 4.0/5 (1 review) | May 2025 | Free (unsupported) | | **Modern FAQ for Confluence** | **NGPILOT** | **5** | — | **Feb 2026** | **Paid** | *Data from Atlassian Marketplace, April 2026.* The FAQ space is small and underserved. The market leader (VECTORS) has only 310 installs with a 2.2-star rating — users report frustrating configuration experiences. FAQ Basic is free but has been **unsupported since May 2025**. ### Feature Comparison[​](#feature-comparison "Direct link to Feature Comparison") | Feature | Modern FAQ (NGPILOT) | FAQ for Confluence (VECTORS) | FAQ Basic (Start Off Easily) | | ------------------------- | ------------------------ | ---------------------------- | ---------------------------- | | **Display themes** | 2 (Centered + Accordion) | 1 | 1 (Accordion) | | **Drag-and-drop reorder** | Yes | No | Yes | | **WYSIWYG editing** | Yes | No | No | | **Inline editing** | Yes | No | No | | **Expand/collapse all** | Yes | No | Partial | | **Actively maintained** | Yes (2026) | Yes (2026) | **No — unsupported** | ### Where Modern FAQ Stands Out[​](#where-modern-faq-stands-out "Direct link to Where Modern FAQ Stands Out") * **Two modern themes** — clean centered layout or accordion collapse style * **Drag-and-drop** — reorder questions by dragging, no cutting and pasting * **WYSIWYG answers** — rich text with formatting, links, and images * **Actively maintained** — updated February 2026 ### Where We Could Improve[​](#where-we-could-improve "Direct link to Where We Could Improve") * **5 installs** — we're brand new in a category where even the leader has only 310 * **No JSM public portal** — VECTORS can publish FAQs to Jira Service Management portals; our app is for internal Confluence pages * **No reviews yet** — building trust with early adopters *** ## Part 2: Q\&A Apps for Confluence[​](#part-2-qa-apps-for-confluence "Direct link to Part 2: Q\&A Apps for Confluence") ### What's Available[​](#whats-available-1 "Direct link to What's Available") | App | Vendor | Installs | Rating | Last Updated | Hosting | | ----------------------------------- | -------------- | --------- | ------------------ | ------------ | ----------- | | Questions for Confluence | **Atlassian** | **4,021** | 2.4/5 (77 reviews) | Mar 2026 | **DC only** | | Questions & Answers | EliteSoft | 670 | 3.1/5 (26 reviews) | Mar 2026 | DC only | | Smart Questions and Answers | Purde Software | 280 | 3.5/5 (13 reviews) | Jan 2026 | Cloud + DC | | Community Questions | Firnity | 157 | 4.0/5 (4 reviews) | Jan 2026 | Cloud | | **Modern Questions for Confluence** | **NGPILOT** | **1** | — | **Apr 2026** | **Cloud** | *Data from Atlassian Marketplace, April 2026.* This is a bigger market. Atlassian's own **Questions for Confluence** dominates with 4,021 installs — but it's **Data Center only** (no Cloud version) and carries a 2.4-star rating from 77 reviews. Many of those reviews cite a dated interface and missing features. **EliteSoft's Q\&A** (670 installs) is also DC-only. **Smart Q\&A** and **Community Questions** offer Cloud versions but haven't matched the install numbers. ### Feature Comparison[​](#feature-comparison-1 "Direct link to Feature Comparison") | Feature | Modern Questions (NGPILOT) | Questions for Confluence (Atlassian) | Smart Q\&A (Purde) | Community Questions (Firnity) | | ---------------------------- | -------------------------- | ------------------------------------ | ------------------ | ----------------------------- | | **Hosting** | Cloud | **DC only** | Cloud + DC | Cloud | | **Ask questions** | Yes | Yes | Yes | Yes | | **Write answers** | Yes | Yes | Yes | Yes | | **Upvote/downvote** | Yes | Yes | No | No | | **Accept answers** | Yes | Yes | No | No | | **Modern UI** | Yes | No (legacy) | No | Partial | | **Searchable in Confluence** | Yes | Yes | Yes | Yes (Rovo) | | **Slack/Teams integration** | No | No | No | Yes | | **Actively maintained** | Yes (Apr 2026) | Yes (Mar 2026) | Yes (Jan 2026) | Yes (Jan 2026) | ### Where Modern Questions Stands Out[​](#where-modern-questions-stands-out "Direct link to Where Modern Questions Stands Out") * **Cloud-native** — built for Confluence Cloud, unlike Atlassian's DC-only offering * **Voting + accepted answers** — Stack Overflow-style workflow that surfaces the best answer * **Modern UI** — clean interface that fits naturally into Confluence * **Newest app in the category** — shipped April 2026 with fresh architecture ### Where We Could Improve[​](#where-we-could-improve-1 "Direct link to Where We Could Improve") * **1 install** — just launched, no track record yet * **No Slack/Teams notifications** — Community Questions by Firnity offers this * **No DC version** — Cloud-only for now; the largest competitors serve the DC market ### The Cloud Opportunity[​](#the-cloud-opportunity "Direct link to The Cloud Opportunity") Here's the key insight: **Atlassian's Questions for Confluence has 4,021 installs but is DC-only**. If you're on Confluence Cloud and want a Q\&A experience, your options are limited to Smart Q\&A (280 installs, 3.5 stars), Community Questions (157 installs, 4.0 stars), or our Modern Questions (brand new, April 2026). The Cloud Q\&A market is underserved and waiting for a better option. *** ## Which App Do You Need?[​](#which-app-do-you-need "Direct link to Which App Do You Need?") | You need... | Use this | | -------------------------------------------------- | ----------------------------------- | | A polished FAQ section on a Confluence page | **Modern FAQ for Confluence** | | A team Q\&A forum with voting and accepted answers | **Modern Questions for Confluence** | | Both — FAQ pages AND a Q\&A community | **Both apps together** | These two apps complement each other. Use **Modern FAQ** for curated, editor-controlled FAQ content on specific pages. Use **Modern Questions** for open community Q\&A where anyone can contribute. *** ## Related Posts[​](#related-posts "Direct link to Related Posts") * [Import Export for Confluence — Which Content Migration App Should You Choose?](/blog/confluence-import-export-comparison.md) * [Numbered Headings for Confluence — Which Table of Contents App Fits Your Docs?](/blog/confluence-numbered-headings-comparison.md) ## Get Started[​](#get-started "Direct link to Get Started") * Install **Modern FAQ for Confluence** from the Atlassian Marketplace — [Read the docs](/docs/Modern-FAQ-for-Confluence/usage.md) * Install **Modern Questions for Confluence** from the Atlassian Marketplace — [Read the docs](/docs/Modern-Questions-for-Confluence/user-docs.md) Have questions or feedback? Reach out to us at — we'd love to hear from you. Try Modern FAQ for Confluence Accordion-style FAQ sections with drag-and-drop reordering and two themes — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236739/modern-faq-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-faq-for-confluence) ## Related guides * [Confluence Questions & Answers Template](/blog/confluence-questions-answers-template.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [questions](/blog/tags/questions.md) * [q-and-a](/blog/tags/q-and-a.md) * [confluence](/blog/tags/confluence.md) * [knowledge-base](/blog/tags/knowledge-base.md) * [accordion](/blog/tags/accordion.md) --- # Are Confluence & Jira Plugins Safe? Marketplace App Security Guide April 21, 2026 · 11 min read [NGPilot](https://ngpilot.com) Who should read this * **Cloud admins** evaluating Marketplace apps before install * **Security/compliance teams** running vendor risk reviews for Atlassian * **Procurement** needing a plugin security checklist for SOC 2 / ISO 27001 What you'll learn 1. The **Forge vs Connect** security model difference (where your data lives) 2. How to read app **scopes** and spot overprivileged apps 3. What **Cloud Fortified** actually verifies 4. A copy-paste **plugin security checklist** for vendor reviews Atlassian Marketplace offers thousands of plugins for Confluence, Jira, and other Atlassian products. While these apps can dramatically extend what your teams accomplish, every plugin you install introduces a third-party component into your environment. For organizations handling sensitive project data, customer information, or internal knowledge bases, understanding plugin security is not optional — it is a core part of your governance and risk management strategy. This guide walks through the most common security questions administrators and security teams ask when evaluating, installing, and managing Atlassian Marketplace apps. Each section provides concrete steps you can take to reduce risk and make informed decisions. ## The single most important question: Forge or Connect?[​](#the-single-most-important-question-forge-or-connect "Direct link to The single most important question: Forge or Connect?") Before any scope or permission review, ask one question: **is this app built on Forge or on the older Connect framework?** The answer determines where your data is processed and is the biggest single security differentiator on the Marketplace today. | | **Forge apps** | **Connect apps** | | ----------------------- | ----------------------------------------------------------------- | ------------------------------------------------- | | Where code runs | Inside Atlassian's own infrastructure | On the vendor's own servers (AWS, GCP, etc.) | | Where data is processed | Atlassian Cloud — data does not leave Atlassian | Data is sent to the vendor's backend over HTTPS | | Data residency | Inherits Atlassian's residency controls automatically | Depends on the vendor's hosting region and policy | | Compliance footprint | Covered by Atlassian's existing certs (SOC 2, ISO 27001, FedRAMP) | Requires separate vendor compliance review | | Deployment model | No vendor-hosted backend to audit | Vendor backend is part of your attack surface | **Why this matters for your audit:** A Forge app's data handling is covered by Atlassian's compliance program. A Connect app's data handling is the vendor's responsibility and must be reviewed separately. If you are running a SOC 2 or ISO 27001 audit, this distinction can save weeks of vendor due-diligence work. All NGPILOT apps are Forge-based, which means customer data stays inside Atlassian Cloud and is not transmitted to NGPILOT-operated servers. ## How do I evaluate a Confluence or Jira plugin's security?[​](#how-do-i-evaluate-a-confluence-or-jira-plugins-security "Direct link to How do I evaluate a Confluence or Jira plugin's security?") Evaluating a plugin before installation is the single most important step you can take. Start by researching the vendor's reputation on the Atlassian Marketplace. Look at the number of installations, customer reviews, how long the vendor has been active, and whether they respond to support requests in a timely manner. A vendor with a long track record and active engagement is generally a safer bet than a newly listed app with no reviews. Next, check whether the vendor publishes a dedicated security policy page. A transparent security policy signals that the vendor takes security seriously and has formal processes in place. Examine the permissions the app requests during installation. Atlassian's permission model requires apps to declare the scopes they need, such as read access to Confluence pages or write access to Jira issues. If an app requests permissions that seem excessive for its stated functionality, treat that as a warning sign. Whenever possible, look for apps that make their source code available for review or that have published third-party security audit reports. The Atlassian Marketplace also indicates whether an app has achieved Cloud Fortified status, which means the vendor has met Atlassian's additional security and reliability requirements. NGPILOT publishes a security policy and all NGPILOT apps follow Atlassian's security requirements for Cloud Fortified compliance. ## What is the principle of least privilege for Atlassian apps?[​](#what-is-the-principle-of-least-privilege-for-atlassian-apps "Direct link to What is the principle of least privilege for Atlassian apps?") The principle of least privilege means granting an application only the minimum permissions it needs to perform its intended function. When you install a plugin, Atlassian shows you the scopes the app is requesting. Before clicking approve, ask yourself whether each scope is truly necessary. A macro that displays task lists, for example, should not need administrative access to user management. Avoid installing apps that request global admin scope unless there is a clear and compelling reason. Global admin permissions give an app broad access across your entire instance, which significantly increases the potential impact if something goes wrong. Instead, look for apps that use fine-grained scopes aligned to their specific features. You can review and manage installed app permissions through the Universal Plugin Manager (UPM) in your Atlassian administration console. The UPM shows which scopes each app has been granted and allows you to disable apps that seem overprivileged. Make it a regular practice to audit app permissions, especially after major updates or organizational changes. Most NGPILOT apps request only the specific scopes they need — for example, read access to page content for search features, or write access to specific entity properties for configuration storage — rather than broad administrative scopes. ## Should I be concerned about data residency with plugins?[​](#should-i-be-concerned-about-data-residency-with-plugins "Direct link to Should I be concerned about data residency with plugins?") Data residency is a critical consideration, particularly for organizations subject to regulations like GDPR, CCPA, or industry-specific compliance requirements. When you install a plugin, you need to understand where your data flows and where it is stored or processed. There are three common models: the app runs entirely within Atlassian's Cloud infrastructure, the app sends data to the vendor's own servers, or the app operates on-premise in your own data center. Apps built using Atlassian's Forge platform run within Atlassian's own infrastructure and are subject to Atlassian's data residency and compliance controls. Connect-based apps, on the other hand, may transmit data to external servers operated by the vendor. Always review the vendor's privacy policy to understand how data is collected, stored, processed, and eventually deleted. Pay attention to where the vendor's servers are located and whether they support data residency restrictions for specific regions. NGPILOT apps are designed to run within Atlassian's infrastructure and follow Atlassian's data residency requirements, which means your data does not leave the Atlassian Cloud environment. This approach reduces the attack surface and simplifies compliance audits because you can rely on Atlassian's existing compliance certifications rather than evaluating a separate vendor's infrastructure. ## How do I check if a plugin vendor has a vulnerability disclosure program?[​](#how-do-i-check-if-a-plugin-vendor-has-a-vulnerability-disclosure-program "Direct link to How do I check if a plugin vendor has a vulnerability disclosure program?") A mature vulnerability disclosure program is a strong indicator that a vendor takes security seriously. Start by looking for a dedicated security contact email or a security policy page on the vendor's website. This page should describe how security researchers and customers can report vulnerabilities, what the vendor's response timeline looks like, and whether they offer a bug bounty program. Responsible disclosure is the industry standard approach. Under this model, the researcher reports the vulnerability privately, gives the vendor a reasonable timeframe to fix it, and only publishes details after a patch is available. Vendors who follow this practice and publish CVE (Common Vulnerabilities and Exposures) information demonstrate transparency and accountability. You can search public CVE databases for a vendor's name to see their disclosure history. Vendors with a bug bounty program go a step further by actively incentivizing the security community to find and report vulnerabilities before malicious actors can exploit them. When evaluating a vendor, check whether they list their security practices on their Atlassian Marketplace vendor page and whether their apps carry Cloud Fortified status, which requires adherence to specific security practices. NGPILOT maintains a published security policy with clear contact information and follows responsible disclosure practices. ## Why is it important to keep Confluence and Jira apps updated?[​](#why-is-it-important-to-keep-confluence-and-jira-apps-updated "Direct link to Why is it important to keep Confluence and Jira apps updated?") App updates are not just about new features. A significant portion of updates released by responsible vendors contain security patches that address vulnerabilities discovered since the last release. Running outdated apps leaves your instance exposed to known vulnerabilities that attackers can exploit, sometimes within days of a public disclosure. Make it a habit to monitor release notes for the apps you have installed. Most vendors tag security fixes clearly in their changelogs. Atlassian Marketplace sends notifications to administrators when updates are available, and you can configure email preferences to ensure security-related updates are not missed. Where available, enable automatic updates so that critical patches are applied without delay. This reduces the window of exposure between when a vulnerability is disclosed and when your instance is patched. For larger organizations, consider establishing a regular update cadence. For example, review and apply updates on a weekly or biweekly schedule, with an expedited process for critical security patches. Keep a record of which app versions are installed and when they were last updated. This documentation is valuable during security audits and compliance reviews. ## Should I test plugins in a staging environment first?[​](#should-i-test-plugins-in-a-staging-environment-first "Direct link to Should I test plugins in a staging environment first?") Testing new plugins in a staging or sandbox environment before deploying to production is a best practice that can save your team significant headaches. A staging environment that mirrors your production setup allows you to evaluate how a plugin behaves with your specific configuration, customizations, and existing apps without risking disruption to your users. During staging testing, verify that the plugin works correctly with your current version of Confluence or Jira. Check that the plugin does not introduce performance degradation, especially if your instance handles large volumes of data or concurrent users. Test the permission configurations to ensure the app operates within the expected scopes and does not overreach. Pay particular attention to potential conflicts with existing apps — two plugins that modify the same part of the interface or rely on the same data structures can sometimes interfere with each other. Document your testing process and results. This creates a repeatable evaluation framework your team can use for future plugin evaluations. If a plugin passes staging tests and is promoted to production, keep the staging environment updated with the same plugin versions so you can pre-test future updates before rolling them out. ## Plugin security evaluation checklist[​](#plugin-security-evaluation-checklist "Direct link to Plugin security evaluation checklist") Use this checklist when evaluating any Atlassian Marketplace plugin before installation. | Check | What to Look For | Red Flags | | ------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | Vendor reputation | Long Marketplace history, many installations, positive reviews, active support | New vendor with no reviews, unresolved support tickets, abandoned apps | | Security policy | Published security page, vulnerability disclosure process, security contact | No security policy, no way to report vulnerabilities, vague security claims | | Permissions and scopes | Minimal scopes matching app functionality, clear justification for each scope | Global admin scope for simple features, broad read/write access beyond stated purpose | | Data handling | Privacy policy with clear data processing details, data stays in Atlassian infrastructure | Data sent to unknown third-party servers, no privacy policy, unclear data retention | | Cloud Fortified status | App listed as Cloud Fortified on Marketplace, meets Atlassian's reliability bar | No Cloud Fortified status, no participation in Atlassian security programs | | Update history | Regular updates, documented release notes, timely security patches | Infrequent updates, no changelog, long gaps between releases | | Compliance | SOC 2, GDPR, or other relevant certifications documented | No compliance information, vague claims without evidence | | Source code transparency | Public source code repository, third-party audit reports available | Closed source with no audit trail, refusal to share security practices | ## What Cloud Fortified means[​](#what-cloud-fortified-means "Direct link to What Cloud Fortified means") Cloud Fortified is an Atlassian program that recognizes apps meeting additional standards for security, reliability, and support. When you see the Cloud Fortified badge on a Marketplace listing, it means the vendor has gone through a structured assessment process and committed to practices that protect customer data and ensure app reliability. To achieve Cloud Fortified status, a vendor must meet several requirements. Their app must use Atlassian's latest development platform, which provides better security isolation and infrastructure controls. The vendor must demonstrate responsible vulnerability management, including timely patching and transparent disclosure. They must maintain a minimum level of support responsiveness, ensuring customers can get help when they need it. The app must also meet specific uptime and reliability targets, reducing the risk of outages that affect your workflows. Cloud Fortified apps are also required to participate in Atlassian's bug bounty program, which means they are continuously tested by security researchers. For administrators, choosing Cloud Fortified apps simplifies the evaluation process because Atlassian has already verified many of the security and reliability checks that you would otherwise need to perform yourself. NGPILOT apps are built to meet Cloud Fortified standards, providing an additional layer of confidence for security-conscious organizations. ## Related resources[​](#related-resources "Direct link to Related resources") * [NGPILOT security policy](/docs/security-policy.md) * [NGPILOT privacy policy](/docs/privacy-policy.md) * [Browse all NGPILOT apps](/docs/intro.md) * [NGPILOT on Atlassian Marketplace](https://marketplace.atlassian.com/vendors/1226848/) Try Modern FAQ for Confluence Accordion-style FAQ sections with drag-and-drop reordering and two themes — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236739/modern-faq-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-faq-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [security](/blog/tags/security.md) * [confluence](/blog/tags/confluence.md) * [jira](/blog/tags/jira.md) * [best-practices](/blog/tags/best-practices.md) --- # Forge vs Connect: What Atlassian Admins Need to Know in 2026 August 2, 2026 · 10 min read [NGPilot](https://ngpilot.com) Quick Answer Forge and Connect are the two frameworks Atlassian Marketplace apps can be built on. **Forge** runs on Atlassian's own infrastructure; **Connect** runs on vendor-hosted servers. Starting January 1, 2026, Atlassian applies a penalty to Connect apps in Marketplace rankings and requires Forge for new Cloud Fortified status. For admins evaluating apps in 2026, Forge is the safer, more future-proof choice where a capable option exists. What you'll learn 1. The real architectural difference between Forge and Connect 2. What the 2026 Connect penalty changes for app discovery and trust 3. How to tell which framework an app uses before you install it 4. A practical decision framework for evaluating apps in 2026 If you administer Jira or Confluence Cloud, every app you install from the Marketplace runs on one of two frameworks: **Forge** or **Connect**. For years the difference was mostly an implementation detail that admins could ignore. In 2026 that changed. The Connect penalty, the Cloud Fortified requirement, and Atlassian's clear strategic direction mean the framework an app uses now affects its security posture, its discoverability, and how long it will keep working. This guide explains what changed, why it matters, and how to make better app decisions because of it. ## The core difference: who hosts the app[​](#the-core-difference-who-hosts-the-app "Direct link to The core difference: who hosts the app") The simplest way to understand the split is to ask **where the app's code runs and where its data lives**. **Connect** is the older framework, introduced in 2014. A Connect app is built by the vendor and hosted on **the vendor's own servers** — AWS, GCP, a private datacenter, or a Platform-as-a-Service like Heroku. The app integrates with Atlassian Cloud through REST APIs, webhooks, JWT-signed requests, and an iframe UI that Atlassian embeds inside Jira or Confluence. The vendor is responsible for the app's uptime, scaling, security patching, and data storage. **Forge** is the newer framework, generally available since 2021. A Forge app runs on **Atlassian-managed infrastructure** — compute, storage, and a hosted UI layer (UI Kit or Custom UI) all provided by Atlassian's platform. The vendor writes the app logic and deploys it with the Forge CLI, but Atlassian operates the runtime. Permissions are declared up front in a manifest and enforced by the platform, so an app cannot access data it has not explicitly requested. | Aspect | Connect | Forge | | ------------------------- | ----------------------------- | ------------------------------------------ | | **Hosting** | Vendor's own servers | Atlassian-managed infrastructure | | **Compute** | Vendor-managed (any language) | Atlassian runtime (Node.js) | | **Storage** | Vendor's database | Atlassian Forge storage | | **Auth** | JWT (vendor-issued) | Forge Invocation Token (FIT) | | **Permissions** | Granted implicitly at install | Declared in manifest, enforced by platform | | **Data egress** | Vendor controls it | Governed by declared scopes | | **UI** | iframe (any web stack) | UI Kit or Custom UI | | **Scaling** | Vendor's responsibility | Automatic, Atlassian-managed | | **Atlassian's direction** | Legacy, being phased down | The platform of record | The architectural shift is significant: **Connect apps process customer data on infrastructure the admin cannot inspect, while Forge apps process it inside the Atlassian tenant they already trust.** For regulated industries, government, and security-conscious enterprises, that distinction is the whole story. ## What changed in 2026: the Connect penalty[​](#what-changed-in-2026-the-connect-penalty "Direct link to What changed in 2026: the Connect penalty") The most time-sensitive development is the **Connect ranking penalty**, which took effect on **January 1, 2026**. This is not a deprecation — Connect apps still work — but it changes the economics of the Marketplace for vendors and the discovery experience for customers. What the penalty means in practice: 1. **Marketplace search and recommendations.** Connect apps rank lower in Marketplace search results and in the "recommended apps" surfaces inside Jira and Confluence, all else being equal. A Forge app and a Connect app with similar ratings and install counts no longer compete on even footing. 2. **Cloud Fortified requires Forge.** The Cloud Fortified program — Atlassian's trust tier that signals an app meets security, reliability, and support standards — now requires Forge. New Cloud Fortified designations are Forge-only, so Connect apps cannot earn the badge going forward. 3. **Vendor incentives.** Because discovery and trust signals now favor Forge, vendors have a strong commercial reason to migrate. Many are mid-migration, which means the Connect app you install today may be replaced by a Forge successor tomorrow. The penalty is the clearest signal yet that Atlassian is consolidating the ecosystem on Forge. Connect is not being killed overnight, but its strategic position is eroding, and the trajectory is unambiguous. ## Why Forge is more secure by default[​](#why-forge-is-more-secure-by-default "Direct link to Why Forge is more secure by default") Security is where the framework choice matters most for admins. The difference is not theoretical — it is structural. **Connect's security depends on the vendor.** A Connect app runs on the vendor's infrastructure, stores data in the vendor's database, and makes outbound network calls the admin cannot see. The vendor is responsible for encryption at rest, TLS in transit, access control, vulnerability patching, and breach response. Atlassian reviews Connect apps at submission, but ongoing security is the vendor's job — and vendors vary wildly in maturity. A Connect app could be running an unpatched dependency, storing data in an unencrypted bucket, or making unexpected egress calls, and the admin has no visibility into any of it. **Forge's security is enforced by the platform.** A Forge app declares its required permissions and egress destinations in a manifest that is reviewed and enforced by Atlassian. The app cannot access product data outside its declared scopes, cannot make network calls to undeclared endpoints, and runs on infrastructure that inherits Atlassian's own security controls — encryption, access management, audit logging. There is no vendor-controlled server to compromise or that can go offline independently of Atlassian. For admins, this collapses the security review from "audit the vendor's entire hosting setup" to "read the declared permission scopes." This is why regulated industries, government customers evaluating Atlassian Isolated Cloud, and security teams doing app reviews increasingly treat Forge as the default and Connect as the exception that requires justification. ## How to tell which framework an app uses[​](#how-to-tell-which-framework-an-app-uses "Direct link to How to tell which framework an app uses") Before you install an app, you can identify its framework in a few seconds: * **On the Marketplace listing**, look for the **"Built on Forge"** badge or a hosting line in the technical details. Forge apps display this prominently; Connect apps reference external hosting or make no framework claim. * **Check the permissions dialog at install time.** Forge apps show a scoped permission list (e.g. "read jira :issue ", "write confluence :content ") that the platform enforces. Connect apps typically present a broader, less granular consent. * **Look for "Cloud Fortified."** If an app earned Cloud Fortified in 2025 or later, it is Forge. Connect apps can no longer receive the designation. * **Ask the vendor.** A reputable vendor will state plainly which framework their app uses and what their migration plans are. When an app offers both a Connect and a Forge version, prefer the Forge version — it is the one receiving investment and the one that will keep ranking well. ## A decision framework for 2026[​](#a-decision-framework-for-2026 "Direct link to A decision framework for 2026") For admins evaluating apps this year, a practical framework: 1. **Prefer Forge where a capable option exists.** It is more secure by default, better governed, and aligned with Atlassian's direction. The Connect penalty means Forge apps will increasingly dominate search and recommendation surfaces. 2. **Do not panic-uninstall working Connect apps.** Established Connect apps continue to function, and ripping out a working integration creates more risk than the penalty creates. Plan to migrate at the vendor's pace, not under self-imposed pressure. 3. **Be cautious with new Connect purchases.** If you are buying fresh in 2026, ask why a Forge equivalent does not exist. In categories where Forge options are mature (diagraming, content formatting, export tools, templates), there is rarely a good reason to choose Connect. 4. **Scrutinize Connect apps that handle sensitive data.** For apps touching compliance-relevant data — audit logs, security flags, customer PII — the vendor-hosted model of Connect adds real review burden. Forge removes most of it. 5. **Watch vendor migration signals.** Vendors openly migrating to Forge are investing in the future; vendors silent on the topic may be stuck. A vendor's posture on Forge vs Connect tells you something about their long-term commitment to the Cloud ecosystem. ## What this means for the NGPILOT catalog[​](#what-this-means-for-the-ngpilot-catalog "Direct link to What this means for the NGPILOT catalog") Every NGPILOT app — all 30-plus of them across Confluence and Jira — is built exclusively on Forge. That was a deliberate decision made for three reasons: Forge's platform-enforced security model means no NGPILOT customer data ever leaves the Atlassian tenant; Atlassian-managed compute means apps scale automatically with zero operational burden on either side; and Forge is the framework Atlassian is investing in, so NGPILOT apps stay aligned with the platform's direction rather than fighting it. If you are evaluating NGPILOT apps against Connect alternatives, the framework difference is one more data point in the comparison — alongside features, pricing, and support. Browse the [full app catalog](/apps.md) or explore [solutions by scenario](/solutions.md) to see which apps fit the problems your team is trying to solve. ## Frequently Asked Questions[​](#frequently-asked-questions "Direct link to Frequently Asked Questions") ### Is Connect being discontinued?[​](#is-connect-being-discontinued "Direct link to Is Connect being discontinued?") No. Atlassian has not announced an end-of-life date for Connect, and existing Connect apps continue to work. But the 2026 ranking penalty, the Cloud Fortified requirement, and Atlassian's investment pattern make the direction clear: Forge is the future, and Connect's role is shrinking. Treat Connect as supported-but-declining rather than stable. ### Do Forge apps have any limitations compared to Connect?[​](#do-forge-apps-have-any-limitations-compared-to-connect "Direct link to Do Forge apps have any limitations compared to Connect?") Yes, in some edge cases. Forge's runtime and permission model are more constrained than Connect's "run anything on your own servers" approach, so a handful of apps that need deep custom integrations, exotic runtime languages, or heavy background processing still lean on Connect. The gap is closing as Forge matures, but it has not fully closed. For the vast majority of app categories — content, diagrams, templates, export, admin tools — Forge is now fully capable. ### How does the Connect penalty affect apps I already installed?[​](#how-does-the-connect-penalty-affect-apps-i-already-installed "Direct link to How does the Connect penalty affect apps I already installed?") It does not break them. Installed Connect apps keep working. The penalty affects **discoverability** — how easily new customers find the app in Marketplace search and recommendations — not the function of apps you already use. Your existing Connect installs are safe until you choose to migrate or the vendor does. ### Are Forge apps slower than Connect apps?[​](#are-forge-apps-slower-than-connect-apps "Direct link to Are Forge apps slower than Connect apps?") Not in practice. Forge compute runs on Atlassian infrastructure close to the product data, which often makes data access faster than a Connect app calling APIs over the public internet from a vendor's region. Cold-start latency on Forge was a concern early in the platform's life; it has largely been addressed. For interactive apps — macros, panels, issue views — Forge performance is competitive. ### Where can I read Atlassian's official guidance?[​](#where-can-i-read-atlassians-official-guidance "Direct link to Where can I read Atlassian's official guidance?") Atlassian's developer documentation covers the [differences between Forge and Connect](https://developer.atlassian.com/platform/adopting-forge-from-connect/limitations-and-differences/) and the [Forge platform overview](https://developer.atlassian.com/platform/forge/). The Cloud Fortified program requirements and the Connect penalty timeline are documented in Atlassian's partner and Marketplace resources. *** *NGPILOT builds exclusively on Forge. Browse the [app catalog](/apps.md) or read more about [how NGPILOT apps handle security and data](/trust.md).* ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [atlassian](/blog/tags/atlassian.md) * [forge](/blog/tags/forge.md) * [connect](/blog/tags/connect.md) * [marketplace](/blog/tags/marketplace.md) * [explained](/blog/tags/explained.md) * [admin](/blog/tags/admin.md) --- # Google Fonts for Confluence — Which Custom Typography App Fits Your Team? April 18, 2026 · 5 min read [NGPilot](https://ngpilot.com) Every Confluence page looks the same — same font, same size, same limited formatting. When you want a landing page that stands out, a team announcement that gets read, or documentation that looks professional, Confluence's built-in typography holds you back. Several apps on the Atlassian Marketplace try to solve this. We built **Google Fonts for Confluence** to give teams access to the full Google Fonts library (1,942+ families) with a live preview editor. In this post we compare it against every alternative so you can choose the right one. ## The Problem with Confluence's Default Typography[​](#the-problem-with-confluences-default-typography "Direct link to The Problem with Confluence's Default Typography") Confluence gives you one font family, a handful of sizes, and basic bold/italic. That's it. If you want to: * Create a space homepage that looks professional * Make team announcements that actually get noticed * Use your brand font in documentation * Display text at large sizes for presentations ...you're out of luck with the default editor. That's where font apps come in. ## What's Available on the Marketplace[​](#whats-available-on-the-marketplace "Direct link to What's Available on the Marketplace") There are 5 font apps for Confluence. Here's the current landscape: | App | Vendor | Installs | Rating | Last Updated | Pricing | | ------------------------------- | ------------------------- | -------- | ----------------- | ------------ | --------------------- | | Fonts for Confluence | Skanda Atlassian Apps | 222 | 1.5/5 (4 reviews) | Apr 2025 | Free | | Webfonts for Confluence | TNG Technology Consulting | 200 | 4.0/5 (1 review) | Feb 2026 | From $10/yr (DC only) | | **Google Fonts for Confluence** | **NGPILOT** | **15** | — | **Apr 2025** | **Free to 10 users** | | Custom Fonts for Confluence | Canary Apps | 6 | No reviews | Jul 2024 | From $50/yr | | Custom Fonts Pro for Confluence | Aptify Tech | 2 | No reviews | Jan 2026 | Free to 10 users | *Data from Atlassian Marketplace, April 2026.* **Fonts for Confluence** (Skanda) leads in installs at 222, but users report serious issues — the 1.5-star rating reflects broken access controls and usability problems. It's also free, which explains the install count despite poor reviews. **Webfonts for Confluence** (TNG) is the oldest competitor with 10,000+ historical downloads, but it's **Data Center only** — no Cloud version available. If you're on Confluence Cloud, this isn't an option. ## Feature Comparison[​](#feature-comparison "Direct link to Feature Comparison") | Feature | Google Fonts (NGPILOT) | Fonts for Confluence (Skanda) | Custom Fonts Pro (Aptify) | Custom Fonts (Canary) | Webfonts (TNG) | | ----------------------- | ------------------------------- | ----------------------------- | ------------------------- | --------------------- | -------------- | | **Hosting** | Cloud | Cloud | Cloud | Cloud | DC only | | **Font library** | 1,942+ Google Fonts | Google Fonts | 800+ Google Fonts | Custom | Custom URLs | | **Font search** | Fuzzy search | No | No | No | No | | **Font variants** | Regular/Italic/Bold/Bold Italic | Weight & size | Yes | Yes | Yes | | **Color picker** | Quick swatches + RGB editor | Basic | Yes | Yes | Yes | | **Text alignment** | Left/Center/Right | No | Yes | Yes | Yes | | **Text size** | Any px value (no limit) | Yes | Yes | Yes | Yes | | **Live preview** | Yes | No | No | No | No | | **Dark mode support** | Auto | No | No | No | No | | **Visual effects** | No | No | Shadows, gradients | No | Text shadow | | **Actively maintained** | Yes (2026) | Limited (2025) | Yes (2026) | No (2024) | Yes (2026) | ### Where Google Fonts for Confluence Stands Out[​](#where-google-fonts-for-confluence-stands-out "Direct link to Where Google Fonts for Confluence Stands Out") **Largest font library** — 1,942+ Google Font families, more than any competitor. Every font in the Google Fonts catalog is available. **Fuzzy search** — Type part of a font name and find it instantly. No scrolling through a dropdown of 1,942 options. **Live preview with RGB color editor** — See your text styled in real-time with the selected font, size, and color. The color picker includes quick-select swatches and direct RGB editing for precise brand color matching. **Auto dark mode** — Styled text automatically adapts to Confluence's dark/light theme. Your text looks great in both modes without any extra work. **Free for small teams** — Full features available free for up to 10 users. ### Where We Could Improve[​](#where-we-could-improve "Direct link to Where We Could Improve") * **No visual effects** — Custom Fonts Pro offers shadows and gradients. We focus on clean typography rather than effects, but this is something we may add based on user feedback. * **Smaller install base** — At 15 active installs, we're the newest entrant. We're building trust through regular updates and responsive support. * **No Data Center version** — We're Cloud-only for now. If you're on Confluence Data Center, Webfonts by TNG is your best option. ## Honest Comparison: NGPILOT vs Skanda (Market Leader)[​](#honest-comparison-ngpilot-vs-skanda-market-leader "Direct link to Honest Comparison: NGPILOT vs Skanda (Market Leader)") Since Skanda's **Fonts for Confluence** has the most installs, here's a direct comparison: | | Google Fonts (NGPILOT) | Fonts for Confluence (Skanda) | | ------------------- | --------------------------- | ---------------------------------- | | **Fonts available** | 1,942+ | Google Fonts (count unknown) | | **User rating** | No reviews yet | 1.5/5 — users report broken access | | **Color picker** | Quick swatches + RGB editor | Basic | | **Font search** | Fuzzy search | No | | **Live preview** | Yes | No | | **Dark mode** | Auto-adapts | No | | **Pricing** | Free to 10 users | Free | | **Last updated** | 2025 | 2025 | | **Support** | Partner Supported | Community | The main tradeoff: Skanda is completely free with no user limits, but the poor reviews suggest reliability issues. Our app offers more features and a better experience, with a free tier for teams up to 10 users. ## Why Teams Choose Google Fonts for Confluence[​](#why-teams-choose-google-fonts-for-confluence "Direct link to Why Teams Choose Google Fonts for Confluence") * **1,942+ fonts at your fingertips** — the largest Google Fonts library available for Confluence Cloud * **Find fonts fast** — fuzzy search means no scrolling through endless lists * **See it before you save** — live preview with full color control including RGB editing * **Dark mode done right** — styled text adapts automatically to every reader's theme * **Fair pricing** — free for teams up to 10 users, then affordable paid tiers ## Related Posts[​](#related-posts "Direct link to Related Posts") * [Code Blocks for Confluence — Which Syntax Highlighting App Should You Choose?](/blog/code-blocks-confluence-monaco-editor.md) * [Markdown Editor for Confluence — Which App Should You Choose for Writing Docs?](/blog/confluence-markdown-editor-comparison.md) * [QR Code for Confluence — Which QR App Should Your Team Use?](/blog/confluence-qr-code-comparison.md) ## Get Started[​](#get-started "Direct link to Get Started") * Install Google Fonts for Confluence from the Atlassian Marketplace * [Read the full documentation](/docs/Google-Fonts-for-Confluence/usage.md) Have questions or feedback? Reach out to us at — we'd love to hear from you. Try Google Fonts for Confluence 1,942+ Google Font families with live preview, custom size/color/alignment — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236413/google-fonts-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=google-fonts-for-confluence) ## Related guides * [Can You Change the Font in Confluence? Custom Options](/blog/confluence-default-font-change-font.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [google-fonts](/blog/tags/google-fonts.md) * [typography](/blog/tags/typography.md) * [confluence](/blog/tags/confluence.md) * [custom-fonts](/blog/tags/custom-fonts.md) --- # Graphviz Charts in Confluence: draw\.io vs Graphviz vs Mermaid July 30, 2026 · 4 min read [NGPilot](https://ngpilot.com) Teams use Confluence to document architecture, processes, and organizational structures. But Confluence doesn't render graphs or charts natively — you need a marketplace app. We built **Graphviz Charts for Confluence** to bring the power of Graphviz and DOT language to Confluence pages. In this post, we compare it against every alternative. *** ## The Apps[​](#the-apps "Direct link to The Apps") | App | Rating | Installs | Vendor | | ----------------------------------------------- | ------ | -------- | ---------- | | draw\.io | 4.5 | 170,000+ | draw\.io | | **Graphviz Charts for Confluence** | 5.0 | New | NGPILOT | | Mermaid Plus Diagrams & AI Agent for Confluence | 5.0 | New | NGPILOT | | Gliffy Diagrams | 4.3 | 60,000+ | Gliffy | | Lucidchart | 4.2 | 40,000+ | Lucidchart | *** ## Feature Comparison[​](#feature-comparison "Direct link to Feature Comparison") ### draw\.io[​](#drawio "Direct link to draw.io") **What it does:** Full diagramming tool embedded in Confluence. **Strengths:** * 100+ diagram types * Free and open source * Large template library * Real-time collaboration **Weaknesses:** * Steep learning curve * Overkill for simple graphs * No DOT language support * Heavy on page load **Best for:** Complex diagrams, architecture, wireframes. *** ### Graphviz Charts for Confluence[​](#graphviz-charts-for-confluence "Direct link to Graphviz Charts for Confluence") **What it does:** Renders Graphviz DOT language directly in Confluence pages. **Strengths:** * Native DOT language support * Lightweight, fast rendering * Auto-layout algorithms (hierarchical, circular, random) * 12 built-in shapes * Inline in page content (no iframe) **Weaknesses:** * Requires DOT language knowledge * No visual editor * New app (no install history) **Best for:** Org charts, dependency graphs, flowcharts, network diagrams — especially if you already use DOT language or want auto-layout. *** ### Mermaid Plus Diagrams & AI Agent for Confluence[​](#mermaid-plus-diagrams--ai-agent-for-confluence "Direct link to Mermaid Plus Diagrams & AI Agent for Confluence") **What it does:** Renders Mermaid diagrams (flowcharts, sequence, class, etc.). **Strengths:** * 30 diagram types * Text-based syntax (like Graphviz) * Live preview * One-click templates **Weaknesses:** * Different syntax than Graphviz * No DOT language support * Some diagram types require specific Mermaid version **Best for:** Flowcharts, sequence diagrams, Gantt charts — if you prefer Mermaid syntax. *** ### Gliffy Diagrams[​](#gliffy-diagrams "Direct link to Gliffy Diagrams") **What it does:** Drag-and-drop diagramming tool. **Strengths:** * Visual editor * Good template library * Enterprise features **Weaknesses:** * Paid only (no free tier) * Slower than text-based tools * No code-based diagrams **Best for:** Teams that prefer visual editing over code. *** ### Lucidchart[​](#lucidchart "Direct link to Lucidchart") **What it does:** Cloud-based diagramming with Confluence integration. **Strengths:** * Real-time collaboration * Extensive template library * Enterprise security **Weaknesses:** * Expensive * External tool (not native) * Requires separate account **Best for:** Large enterprises already using Lucidchart. *** ## Head-to-Head: Graphviz Charts vs Alternatives[​](#head-to-head-graphviz-charts-vs-alternatives "Direct link to Head-to-Head: Graphviz Charts vs Alternatives") ### Graphviz Charts vs draw\.io[​](#graphviz-charts-vs-drawio "Direct link to Graphviz Charts vs draw.io") | Criteria | Graphviz Charts | draw\.io | | ------------------ | ----------------- | ---------------- | | **Syntax** | DOT language | Visual editor | | **Learning curve** | Moderate (DOT) | Steep (features) | | **Performance** | Fast | Slower | | **Best for** | Code-based graphs | Visual diagrams | **Verdict:** Use Graphviz Charts for auto-layout graphs. Use draw\.io for complex visual diagrams. ### Graphviz Charts vs Mermaid Plus[​](#graphviz-charts-vs-mermaid-plus "Direct link to Graphviz Charts vs Mermaid Plus") | Criteria | Graphviz Charts | Mermaid Plus | | ----------------- | ------------------------ | --------------------- | | **Syntax** | DOT language | Mermaid syntax | | **Diagram types** | Graph-focused | General-purpose | | **Auto-layout** | Yes (4 algorithms) | Limited | | **Best for** | Org charts, dependencies | Flowcharts, sequences | **Verdict:** Use Graphviz Charts for structured graphs with auto-layout. Use Mermaid Plus for general-purpose diagrams. *** ## Use Cases[​](#use-cases "Direct link to Use Cases") | Use Case | Recommended App | | -------------------- | --------------- | | Org chart | Graphviz Charts | | Architecture diagram | draw\.io | | Flowchart | Mermaid Plus | | Dependency graph | Graphviz Charts | | Sequence diagram | Mermaid Plus | | Network diagram | Graphviz Charts | | Wireframe | draw\.io | | Gantt chart | Mermaid Plus | *** ## Quick Start: Graphviz Charts[​](#quick-start-graphviz-charts "Direct link to Quick Start: Graphviz Charts") 1. Install from [Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237027/graphviz-charts-for-confluence) 2. Type `/graphviz` in any Confluence page 3. Enter DOT language code: ``` digraph G { A -> B -> C; B -> D; } ``` 4. Choose layout algorithm (dot, circo, fdp, random) 5. Save the page — graph renders automatically *** ## Frequently Asked Questions[​](#frequently-asked-questions "Direct link to Frequently Asked Questions") **Do I need to know DOT language?** Yes. Graphviz Charts uses DOT language syntax. If you're new, start with simple graphs and expand. **Can I use a visual editor?** No. Graphviz Charts is code-based. For visual editing, use draw\.io or Gliffy. **What layout algorithms are available?** dot (hierarchical), circo (circular), fdp (force-directed), random. **Can I export diagrams?** Yes. Right-click the rendered graph to save as PNG or SVG. **Does it work with Confluence Cloud?** Yes. Fully compatible with Confluence Cloud and Data Center. *** *This comparison is part of our [Confluence App Hub](/blog/best-confluence-apps-developers.md). See all comparisons →* Try Graphviz Charts for Confluence Render Graphviz DOT diagrams with live preview — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237380/graphviz-charts-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=graphviz-charts-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [confluence-apps](/blog/tags/confluence-apps.md) * [comparison](/blog/tags/comparison.md) * [graphviz](/blog/tags/graphviz.md) * [charts](/blog/tags/charts.md) --- # How to Change Fonts in Confluence (Google Fonts, Custom Typography & More) May 2, 2026 · 19 min read [NGPilot](https://ngpilot.com) **Custom fonts in Confluence** let you apply brand typography to your documentation. This guide covers **Google Fonts for Confluence** — 1,942+ font families, live preview, dark mode support, and customization options. Who should read this * Teams with brand guidelines needing custom typography * Marketing/HR wanting branded Confluence pages * Anyone wanting to change default Confluence fonts What you'll learn 1. How to add Google Fonts to Confluence 2. Choosing and applying font families 3. Customizing size, color, and alignment 4. Dark mode and theme considerations Google Fonts for Confluence gives you access to over 1,942 Google Fonts directly inside your Confluence pages. You can customize font family, weight, size, color, and alignment with a live preview that shows exactly how your text will look before you save. This step-by-step tutorial walks through everything: installing the app, configuring fonts, applying them across spaces, and maintaining a consistent typographic system that respects accessibility and brand standards. ## Why custom fonts matter in Confluence[​](#why-custom-fonts-matter-in-confluence "Direct link to Why custom fonts matter in Confluence") Before diving into the how-to, it helps to understand the practical reasons teams invest time in custom Confluence typography: * **Brand consistency.** If your company uses specific fonts in marketing materials, presentations, and product interfaces, extending those same typefaces into Confluence creates a unified experience. Employees consuming internal documentation feel the same brand presence they see externally. * **Readability.** Not all fonts are equal for on-screen reading. A well-chosen body font reduces eye strain during long documentation sessions. Heading fonts with strong visual weight make page structure instantly scannable. * **Professionalism.** Client-facing Confluence spaces (for agencies, consultancies, and B2B companies) benefit enormously from custom typography. When a client logs into your Confluence instance and sees polished, branded documentation, it reinforces credibility. * **Accessibility.** Certain fonts are specifically designed for readability, including for users with dyslexia or low vision. Choosing accessible fonts is not just a nice-to-have — for many organizations, it is a compliance requirement. Confluence does not provide native support for custom fonts on individual pages. The Google Fonts for Confluence app fills this gap by embedding a macro-based font engine directly into the Confluence editor. ## Prerequisites[​](#prerequisites "Direct link to Prerequisites") Before starting, make sure you have the following: * A **Confluence Cloud** site (the app is designed for Cloud instances) * **Edit permissions** on at least one Confluence space * Admin or app-installation permissions if you are the one installing the app (otherwise, ask your Confluence administrator) * A rough idea of which fonts you want to use — or at least a willingness to browse and experiment ## Step-by-step: Add custom fonts to Confluence[​](#step-by-step-add-custom-fonts-to-confluence "Direct link to Step-by-step: Add custom fonts to Confluence") ### Step 1: Install Google Fonts for Confluence[​](#step-1-install-google-fonts-for-confluence "Direct link to Step 1: Install Google Fonts for Confluence") The app is available on the Atlassian Marketplace. Installation takes under a minute. 1. Go to **Confluence Settings** by clicking the gear icon in the top-right corner of your Confluence site. 2. In the left sidebar, navigate to **Apps** and then click **Find new apps**. 3. In the search bar, type **"Google Fonts for Confluence"**. 4. When the app appears in the results, click **Get app** (or **Install**). 5. Follow the installation prompts. For Cloud instances, this is typically a single click confirming the installation. Once installed, the app is available on every page in your Confluence instance. There is no per-space installation — it works globally from the moment it is added. **Verification:** Open any Confluence page in edit mode. Type `/google fonts` in the editor slash-command menu. If you see **Google Fonts for Confluence** appear as an option, the installation was successful. ### Step 2: Configure your font settings[​](#step-2-configure-your-font-settings "Direct link to Step 2: Configure your font settings") This is where the actual typography work happens. The Google Fonts macro opens a configuration panel with multiple options and a live preview area. 1. Edit any Confluence page. 2. Type `/google fonts` in the editor and select **Google Fonts for Confluence** from the slash-command menu. 3. The configuration panel opens. You will see the following options: **Font Family:** A searchable dropdown containing all 1,942+ Google Fonts. Start typing a font name to filter the list. If you know the exact font you want (for example, "Inter" or "Playfair Display"), just type its name. If you are browsing, scroll through the list and click fonts to preview them. **Font Variant:** Choose from the available variants for the selected font. The options typically include: | Variant | Description | | --------------- | -------------------------------------------------- | | **Regular** | Default weight (400) for body text | | **Italic** | Italic style for emphasis | | **Bold** | Bold weight (700) for headings and strong emphasis | | **Bold Italic** | Combined bold and italic for maximum emphasis | Available variants depend on the selected font. Some fonts like "Roboto" offer many weights (100 through 900 plus italics), while display fonts may only have regular and bold. **Text Size:** Enter any font size in pixels. There is no enforced limit. Common ranges include: | Usage | Recommended Size | | ------------------- | ---------------- | | Body text | 14–18px | | Subheadings | 20–28px | | Page headings | 32–48px | | Display / hero text | 60–120px | **Text Color:** Use the built-in color picker to select a text color. Quick-select swatches provide common colors, and the full palette lets you fine-tune the exact shade by adjusting RGB values. **Text Alignment:** Choose from left, center, or right alignment for your styled text block. **Preview Text:** Type your actual content in the preview area to see how it renders with the selected font, size, color, and alignment — all in real time before you commit. 4. Once you are satisfied with the preview, click **Save** to insert the styled text block into your page. ### Step 3: Apply fonts across your Confluence pages[​](#step-3-apply-fonts-across-your-confluence-pages "Direct link to Step 3: Apply fonts across your Confluence pages") After configuring your first styled text block, the next step is applying consistent typography across your pages. The Google Fonts macro works per text block — it is not a global or space-level font setting. Consistency comes from using the same font choices on each macro instance across your pages. This is where planning matters more than tooling. **Start with a reference page.** Create a page in your space called "Typography Style Guide" (or similar). Use the Google Fonts macro to create examples of each font, size, and color your team should use. This becomes the single source of truth for typography in your space. **Apply fonts systematically.** Work through your most important pages first: 1. **Space home page** — This is the first thing visitors see. Use your heading font for the space title and key section headings. 2. **Navigation pages** — Parent pages that link to child content. Consistent typography here sets expectations for the rest of the space. 3. **High-traffic pages** — Pages your team references daily (runbooks, SOPs, dashboards). These benefit most from polished typography. 4. **Client-facing pages** — If clients access your Confluence instance, prioritize these for brand-compliant fonts. **Applying fonts per space vs across the entire site.** Because the macro is per-text-block, you choose how broadly to apply consistency: * **Per space** means you use different font choices in different spaces. Each space can have its own typographic identity. This gives you maximum flexibility, which is ideal when different teams or departments have distinct brand guidelines. * **Across the entire site** means using the same fonts consistently on every page in every space. To achieve this, you establish a shared style guide and apply it uniformly via the macro on each page. This is the right approach when your entire organization follows one brand identity. For most organizations, a hybrid approach works best: one primary font pairing used across the site, with individual spaces allowed to customize for their specific audience. For example, the engineering team might use a monospace-friendly font pairing while the marketing team uses a serif pairing that aligns with external brand materials. ### Step 4: Preview and test across themes[​](#step-4-preview-and-test-across-themes "Direct link to Step 4: Preview and test across themes") Before rolling out custom fonts to your entire team, test them thoroughly. The Google Fonts macro supports both light and dark mode in Confluence, and your text needs to be readable in both. **Dark mode testing checklist:** * Open your styled pages in Confluence's dark theme. Verify that text colors have sufficient contrast against the dark background. * A color that looks great on a white background (light gray, for instance) may be nearly invisible in dark mode. * The macro automatically adapts to the active theme, but custom text colors you select in the color picker need manual verification. **Accessibility testing:** * Check color contrast ratios. WCAG 2.1 requires a minimum contrast ratio of **4.5:1** for normal text and **3:1** for large text (18px+ or 14px+ bold). Use a contrast checker tool to verify your text and background combinations. * Test with screen magnification. Some decorative fonts become illegible when zoomed. * Verify that your font size is at least 14px for body text. Smaller sizes may be difficult to read, especially on high-DPI displays where rendering differs. **Cross-browser testing:** * Open your pages in Chrome, Firefox, Safari, and Edge. Google Fonts render consistently across modern browsers, but it is worth checking. * If team members use the Confluence mobile app, test on iOS and Android as well. Font rendering on mobile can differ slightly from desktop. ### Step 5: Publish and maintain[​](#step-5-publish-and-maintain "Direct link to Step 5: Publish and maintain") After testing, publish your pages and establish a system for maintaining typographic consistency. **Create a font style guide page.** Document the following: * Which fonts to use (heading font, body font, accent font) * Specific sizes for each usage (H1, H2, body text, captions, callouts) * Approved text colors with hex values * Which font variants are allowed (for example: "Use Inter Regular and Bold only. Do not use Light or Black weights.") * Examples of correctly styled content **Train your team.** Show colleagues how to use the `/google fonts` slash command. A 5-minute walkthrough during a team meeting is usually sufficient. Point them to the style guide page. **Re-editing existing styled text.** If you need to change a font on an existing block, click on the Google Fonts macro and select **Edit**. The configuration panel reopens with all your previous settings preserved. Make your changes, preview, and save. **Periodic review.** Every few months, review your font usage across the space. Look for drift — pages where someone used a different font or size than the standard. Gently correct these and point the author to the style guide. ## Font pairing recommendations[​](#font-pairing-recommendations "Direct link to Font pairing recommendations") Choosing fonts is one of the most impactful decisions you will make. The right pairing creates visual hierarchy, improves readability, and reinforces your brand. Here are six recommended pairings with use cases: | Heading Font | Body Font | Best For | Mood | | -------------------- | ----------------- | -------------------------------------------------------- | ----------------------- | | **Playfair Display** | **Source Sans 3** | Marketing, brand guidelines, client proposals | Elegant, editorial | | **Montserrat** | **Merriweather** | Long-form documentation, knowledge bases | Professional, readable | | **Poppins** | **Lato** | Modern tech companies, startups, product docs | Clean, contemporary | | **Oswald** | **Open Sans** | Internal dashboards, status reports, operations | Bold, utilitarian | | **Roboto Slab** | **Roboto** | Engineering docs, technical specifications | Structured, technical | | **DM Serif Display** | **DM Sans** | Executive summaries, board presentations, formal reports | Sophisticated, polished | ### How to choose the right pairing[​](#how-to-choose-the-right-pairing "Direct link to How to choose the right pairing") **Consider your audience.** Internal engineering documentation needs clarity and density — fonts like Roboto and Roboto Slab prioritize legibility at small sizes. Client-facing materials benefit from character and polish — Playfair Display paired with Source Sans 3 creates an editorial feel that communicates quality. **Limit to two fonts maximum.** A heading font and a body font is the standard recipe. Adding a third font for accents or callouts is acceptable, but going beyond three creates visual noise. The contrast between your two main fonts should be noticeable but not jarring. Pair a serif with a sans-serif, or a bold display font with a neutral body font. **Test at actual sizes.** A font that looks beautiful at 48px may fall apart at 14px. Use the live preview in the Google Fonts macro to test each font at the exact sizes you plan to use on your pages. Preview with real content — your actual headings and body text — not just the default placeholder text. ## Applying fonts per space vs across the entire site[​](#applying-fonts-per-space-vs-across-the-entire-site "Direct link to Applying fonts per space vs across the entire site") The Google Fonts for Confluence macro is a per-text-block tool — each macro instance styles one block of text on one page. There is no global toggle or admin setting that enforces fonts across a space or the entire site. Understanding this helps you make practical decisions about how to roll out custom typography. ### When to use different fonts per space[​](#when-to-use-different-fonts-per-space "Direct link to When to use different fonts per space") * **Multiple brands under one organization.** A holding company with distinct subsidiary brands needs different typography in each subsidiary's Confluence space. * **Departmental autonomy.** Engineering, design, marketing, and legal teams often have different documentation cultures. Letting each choose fonts that work for their content improves adoption. * **Client-specific spaces.** Agencies and consultancies that give clients access to Confluence can customize each client's space to match the client's brand rather than the agency's. * **Experimental projects.** A new initiative may want a distinct visual identity before deciding whether to adopt it organization-wide. ### When to use consistent fonts across the entire site[​](#when-to-use-consistent-fonts-across-the-entire-site "Direct link to When to use consistent fonts across the entire site") * **Strong single brand.** If your company has one brand identity and all documentation should reflect it, site-wide consistency is the goal. * **Compliance requirements.** Some regulated industries require uniform documentation standards. Site-level enforcement ensures no space deviates. * **Simplified maintenance.** One style guide, one set of font choices, one set of approved colors. When the brand updates, you update one reference page instead of hunting through every space. ### The practical approach[​](#the-practical-approach "Direct link to The practical approach") Because the macro is per-text-block, consistency comes from **process, not from a global setting**. The recommended approach: 1. Create a master typography style guide page at the site level. 2. Link to it from every space's home page. 3. Include copy-paste-ready examples using the Google Fonts macro so team members can see exactly what each styled text block should look like. 4. Periodically audit spaces for compliance with the style guide. This process-based approach is actually more flexible than a rigid site-wide setting, because it allows controlled exceptions when they are justified. ## Accessibility considerations[​](#accessibility-considerations "Direct link to Accessibility considerations") Custom fonts can improve or harm accessibility depending on the choices you make. Here are the key principles to follow: ### Choose accessible fonts[​](#choose-accessible-fonts "Direct link to Choose accessible fonts") Some fonts are specifically designed for readability across a wide range of users. These include: * **Open Sans, Lato, Roboto, Nunito** — Sans-serif fonts with clear letterforms and generous spacing. Excellent for body text. * **Atkinson Hyperlegible** — Designed specifically for low-vision users. Available on Google Fonts and one of the best choices for accessibility-first documentation. * **Lexie Readable** — Designed for readability by people with dyslexia. If your team includes neurodiverse members, this is worth considering. Avoid decorative or display fonts for body text. Fonts with extreme thin/thick contrast, tight letter spacing, or ambiguous characters (easily confused I/l/1 or O/0) create barriers for readers with visual impairments. ### Maintain sufficient color contrast[​](#maintain-sufficient-color-contrast "Direct link to Maintain sufficient color contrast") When using the color picker in the Google Fonts macro, always verify contrast ratios: * **Normal text (below 18px or below 14px bold):** Minimum 4.5:1 contrast ratio against the background. * **Large text (18px+ or 14px+ bold):** Minimum 3:1 contrast ratio. * **Enhanced (AAA level):** 7:1 for normal text, 4.5:1 for large text. Common pitfalls to avoid: * Light gray text on white backgrounds (fails contrast requirements in both light and dark themes). * Colored text on colored backgrounds without sufficient luminance difference. * Using color as the only means of conveying information — always pair color with text labels or patterns. ### Use appropriate font sizes[​](#use-appropriate-font-sizes "Direct link to Use appropriate font sizes") * Body text should be at least **14px**, with **16px** preferred for maximum readability. * Line height (controlled by the font's built-in metrics) should provide comfortable reading. Google Fonts generally have good built-in line heights, but very large or very small sizes may need adjustment in context. * Never use font sizes below **10px** for any content that users need to read. ### Test with assistive technology[​](#test-with-assistive-technology "Direct link to Test with assistive technology") If your Confluence pages need to be accessible to screen reader users, verify that the Google Fonts macro content is properly read by assistive technology. The macro renders styled text within the page content flow, so screen readers should process it normally. Test with your organization's preferred screen reader (VoiceOver, NVDA, or JAWS) to confirm. ## Working with brand guidelines[​](#working-with-brand-guidelines "Direct link to Working with brand guidelines") Many organizations have formal brand guidelines that specify exact typefaces, sizes, and colors. Here is how to implement them in Confluence using Google Fonts for Confluence. ### Match brand fonts to Google Fonts equivalents[​](#match-brand-fonts-to-google-fonts-equivalents "Direct link to Match brand fonts to Google Fonts equivalents") If your brand fonts are available on Google Fonts, use them directly — this is the ideal scenario. Many popular brand fonts like Roboto, Open Sans, Montserrat, and Lato are on Google Fonts. If your brand uses a proprietary font not on Google Fonts, find the closest Google Fonts equivalent: | Proprietary Font | Closest Google Font Equivalent | | -------------------------- | ------------------------------------------------------------- | | Helvetica / Neue Helvetica | **Inter** or **Arimo** | | Arial | **Arimo** | | Gotham | **Montserrat** or **Proxima Nova** (via similar weight/width) | | Futura | **Jost** or **Spartan** | | Garamond | **EB Garamond** or **Cormorant Garamond** | | Avenir | **Nunito Sans** or **Montserrat Light** | | Trade Gothic | **Barlow** or **Oswald** | These are not pixel-perfect matches, but they capture the same visual personality. For most internal documentation purposes, the differences are negligible. ### Implement brand colors[​](#implement-brand-colors "Direct link to Implement brand colors") Use the color picker in the Google Fonts macro to match your brand's exact hex colors. If your brand guidelines specify primary, secondary, and accent colors: * Use the **primary color** for main headings and important callouts. * Use the **secondary color** for subheadings and highlighted text. * Use the **accent color** sparingly for emphasis or to draw attention to specific text. ### Create branded page templates[​](#create-branded-page-templates "Direct link to Create branded page templates") Once you have your font family, size, color, and alignment dialed in, create Confluence page templates that include pre-styled Google Fonts macros. This lets team members create new pages that are automatically on-brand without needing to manually configure the macro every time. ## Performance best practices[​](#performance-best-practices "Direct link to Performance best practices") Adding external fonts to your pages has performance implications. Following these practices keeps your Confluence pages loading fast: 1. **Limit the number of fonts.** Each additional font family adds an HTTP request. Stick to 2-3 font families maximum per page. If you are using a heading font and a body font, that is two — and that is plenty. 2. **Limit font variants.** Only load the weights you actually use. If your headings use Bold (700) and body text uses Regular (400), you do not need Light (300), Medium (500), or Black (900). The Google Fonts macro loads only the variant you select, so this is handled automatically — but be mindful if you are using the macro multiple times on one page with different variants. 3. **Use variable fonts where possible.** Variable fonts contain all weights in a single file, reducing HTTP requests. Google Fonts is increasingly offering variable font versions. Look for fonts tagged as "Variable" when browsing. 4. **Preview before publishing.** Use the live preview in the macro to finalize your font choices before saving. This avoids the need to repeatedly edit and re-save, which also keeps your page history clean. For a deeper dive into performance considerations, see our [Google Fonts performance FAQ](/blog/faq-google-fonts-performance.md). ## Troubleshooting common issues[​](#troubleshooting-common-issues "Direct link to Troubleshooting common issues") ### Fonts not loading[​](#fonts-not-loading "Direct link to Fonts not loading") If your styled text appears in a system font instead of the selected Google Font: * Check your network connection. Google Fonts load from `fonts.googleapis.com`. If your corporate firewall blocks this domain, the fonts will not load. Contact your IT team to whitelist the Google Fonts CDN. * Verify the app is still installed. Go to **Confluence Settings > Apps > Manage apps** and confirm Google Fonts for Confluence is listed and enabled. ### Text looks different in edit mode vs published mode[​](#text-looks-different-in-edit-mode-vs-published-mode "Direct link to Text looks different in edit mode vs published mode") The live preview in the macro accurately reflects the published output. If you notice differences: * Clear your browser cache and reload the page. * Check whether your browser is applying its own font settings (some browsers allow custom font overrides in accessibility settings). * Verify you are not accidentally applying Confluence's built-in text formatting (bold, italic) on top of the macro's styling. ### Macro not appearing in slash command menu[​](#macro-not-appearing-in-slash-command-menu "Direct link to Macro not appearing in slash command menu") If typing `/google fonts` does not show the macro: * Confirm the app is installed (see above). * Make sure you are editing a page (the slash command menu only works in edit mode). * Try typing `/google` — sometimes the full phrase needs a moment to index after installation. ## Summary[​](#summary "Direct link to Summary") Adding custom fonts to Confluence transforms plain documentation into branded, readable, and professional content. With Google Fonts for Confluence, the process is straightforward: 1. **Install** the app from the Atlassian Marketplace. 2. **Configure** your font family, variant, size, color, and alignment using the macro's live preview. 3. **Apply** consistent typography across your spaces, starting with high-visibility pages. 4. **Preview** in both light and dark mode, verify accessibility, and test across browsers. 5. **Publish** with a documented style guide so your entire team maintains typographic consistency. The key to success is not the tool itself — it is the system you build around it. A clear font style guide, thoughtful font pairing, attention to accessibility, and regular maintenance will make your Confluence spaces look professional and stay readable for everyone. ## Related resources[​](#related-resources "Direct link to Related resources") * [Google Fonts for Confluence — User Guide](/apps/google-fonts-for-confluence.md) — full documentation * [Confluence Font Apps Comparison](/blog/confluence-font-apps-comparison.md) — Side-by-side comparison ## More Related Guides[​](#more-related-guides "Direct link to More Related Guides") * [Change font in Confluence](/blog/confluence-default-font-change-font.md) — Quick start guide * [Google Fonts alternatives](/blog/faq-google-fonts-confluence-alternatives.md) — Other font options * [Confluence typography best practices](/blog/confluence-font-apps-comparison.md) — Choosing the right fonts Try Google Fonts for Confluence 1,942+ Google Font families with live preview, custom size/color/alignment — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236413/google-fonts-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=google-fonts-for-confluence) ## Related guides * [Can You Change the Font in Confluence? Custom Options](/blog/confluence-default-font-change-font.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [google-fonts](/blog/tags/google-fonts.md) * [typography](/blog/tags/typography.md) * [custom-fonts](/blog/tags/custom-fonts.md) * [how-to](/blog/tags/how-to.md) --- # How to Add SVG Illustrations to Confluence Pages May 2, 2026 · 17 min read [NGPilot](https://ngpilot.com) Adding illustrations to Confluence pages transforms flat walls of text into engaging, professional content. Whether you are writing onboarding documentation, putting together a team wiki, or preparing a presentation, the right visual can communicate an idea faster than a paragraph of explanation. The challenge has always been finding high-quality illustrations that look good at any size, load quickly, and match your team's visual style. SVG (Scalable Vector Graphics) illustrations solve all of these problems. They scale perfectly to any resolution, they are lightweight, and they integrate cleanly into Confluence pages. Content Craft for Confluence brings a curated library of SVG illustrations directly into the Confluence editor, so you can browse, search, and insert professional illustrations without leaving your workflow. This tutorial shows you exactly how to add SVG illustrations to Confluence pages using Content Craft for Confluence. By the end, you will be able to transform any Confluence page from text-heavy to visually engaging in under a minute. ## What is Content Craft for Confluence?[​](#what-is-content-craft-for-confluence "Direct link to What is Content Craft for Confluence?") Content Craft for Confluence is an Atlassian Marketplace app that provides an in-editor SVG illustration gallery for Confluence. Instead of hunting through stock illustration sites, downloading files, and manually uploading them as attachments, Content Craft gives you a searchable library of ready-to-use SVG illustrations right inside the Confluence editor. The app is designed for teams that want to improve the visual quality of their Confluence content without hiring a designer or licensing expensive illustration packs. Every illustration in the gallery is optimized for web display, scales to any size without losing quality, and renders crisply on both standard and high-resolution displays. ### Key features[​](#key-features "Direct link to Key features") * **Curated SVG gallery** with hundreds of professional illustrations covering common business and technology themes * **Keyword search** that lets you filter illustrations by descriptive terms such as "team," "meeting," "security," "cloud," "analytics," and dozens more * **Category filters** organized on the right side of the gallery panel so you can browse by theme or topic * **One-click insertion** that places the selected SVG directly onto your Confluence page with no file upload required * **Confluence-native experience** that works inside the standard page editor, with no external tools or browser tabs needed The result is a workflow that looks like this: open a page, type a slash command, find an illustration, click to insert, publish. Under thirty seconds from start to finish. ## Step-by-step: Add SVG illustrations to Confluence[​](#step-by-step-add-svg-illustrations-to-confluence "Direct link to Step-by-step: Add SVG illustrations to Confluence") ### Step 1: Install Content Craft for Confluence[​](#step-1-install-content-craft-for-confluence "Direct link to Step 1: Install Content Craft for Confluence") Before you can insert SVG illustrations, you need to install the app from the Atlassian Marketplace. 1. Open **Confluence Settings** by clicking the gear icon in the top-right corner of Confluence. 2. Navigate to **Find new apps** under the "Apps" section in the left sidebar. 3. In the search bar, type **"Content Craft for Confluence"**. 4. Click **Get App** on the search result. 5. Follow the installation prompts to approve the app for your Confluence instance. The installation typically completes in under a minute. Once installed, the Content Craft macro is available on every page in every space across your Confluence instance. There is no per-space configuration or additional setup required. If your organization requires admin approval for new apps, submit a request to your Confluence administrator with a link to the app on the Atlassian Marketplace. After installation, verify the app is working by opening any page in edit mode and typing `/Content Craft` in the editor. If you see the macro appear in the dropdown, the installation was successful. ### Step 2: Insert the Content Craft macro[​](#step-2-insert-the-content-craft-macro "Direct link to Step 2: Insert the Content Craft macro") Once the app is installed, inserting an SVG illustration is as simple as adding any other macro in Confluence. 1. Open the Confluence page where you want to add an illustration, or create a new page. 2. Click **Edit** to open the page in the Confluence editor. 3. Place your cursor at the location on the page where you want the illustration to appear. 4. Type `/Content Craft for Confluence` in the editor. The macro appears in the dropdown list. 5. Click to select the macro. The SVG gallery panel opens. The gallery panel opens directly within the editor. You do not need to navigate to a separate tab, open a popup window, or leave the editing context. This keeps your workflow uninterrupted. ### Step 3: Browse or search the SVG gallery[​](#step-3-browse-or-search-the-svg-gallery "Direct link to Step 3: Browse or search the SVG gallery") The Content Craft gallery gives you two ways to find the right illustration: browsing by category and searching by keyword. **Searching by keyword** At the top of the gallery panel, you will find a search box. Type any keyword to filter the illustrations. The search supports a wide range of descriptive terms. For example: * **People and roles:** "team," "woman," "man," "child," "developer," "manager" * **Activities:** "meeting," "presentation," "collaboration," "brainstorming" * **Technology:** "cloud," "server," "security," "database," "analytics," "code" * **Business concepts:** "growth," "strategy," "innovation," "process," "workflow" The search results update in real time as you type. There is no need to press Enter or click a search button. This instant feedback makes it fast to experiment with different keywords until you find the illustration that fits your content. **Filtering by category** On the right side of the gallery panel, you will see category filters. These organize the SVG illustrations into themed groups so you can browse visually without needing a specific keyword in mind. Categories typically include groupings such as: * **People and teams** -- illustrations of individuals and groups collaborating, working, and communicating * **Technology and infrastructure** -- servers, cloud computing, networks, data centers, and security concepts * **Business and strategy** -- growth charts, planning sessions, goal setting, and process flows * **Education and learning** -- onboarding, training, documentation, and knowledge-sharing scenes * **Communication** -- presentations, meetings, email, chat, and feedback loops Click any category to see all illustrations in that group. You can combine category filtering with keyword search to narrow down results even further. ### Step 4: Select your SVG illustration[​](#step-4-select-your-svg-illustration "Direct link to Step 4: Select your SVG illustration") Once you have found an illustration that fits your content, click on it to select it. The gallery shows a preview of the illustration, confirming your choice before it is inserted onto the page. Take a moment to consider how the illustration will look in context. A few things to keep in mind: * **Placement.** Illustrations work well above a section heading to set the visual tone, beside a paragraph to break up text, or at the top of a page as a hero image. * **Relevance.** The illustration should directly relate to the content it accompanies. A "team collaboration" illustration above a section about cross-functional workflows makes sense. The same illustration above a section about database configuration does not. * **Consistency.** If you are adding multiple illustrations to a single page or across a set of related pages, try to use illustrations from the same visual style. Content Craft's gallery is curated for visual consistency, but mixing very different illustration styles on one page can feel disjointed. When you are satisfied with your selection, click the **Save** button to insert the SVG onto your Confluence page. ### Step 5: Save and publish the page[​](#step-5-save-and-publish-the-page "Direct link to Step 5: Save and publish the page") After clicking Save in the gallery panel, the SVG illustration appears on your page in the editor. You can now: * **Resize the illustration** by clicking it and dragging the corner handles to adjust its dimensions * **Reposition the illustration** by clicking and dragging it to a different location on the page * **Add alignment** using Confluence's text alignment options to center, left-align, or right-align the illustration * **Add more illustrations** by repeating the process if your page needs additional visuals When you are happy with the page layout, click **Publish** to make the page visible to your team. The SVG illustration renders at full quality on the published page, scaling cleanly to any screen size, from desktop monitors to mobile devices. If you need to change the illustration later, simply edit the page, select the existing SVG, delete it, and insert a new one from the Content Craft gallery. The process is the same as replacing any other content element on a Confluence page. ## Understanding the SVG gallery categories[​](#understanding-the-svg-gallery-categories "Direct link to Understanding the SVG gallery categories") Content Craft for Confluence organizes its illustration library into intuitive categories that map to common content types you find in Confluence spaces. Understanding these categories helps you find the right illustration quickly. ### People and collaboration[​](#people-and-collaboration "Direct link to People and collaboration") Illustrations in this category depict individuals and teams in professional settings. You will find scenes of people working together at whiteboards, having conversations in meeting rooms, collaborating on documents, and celebrating achievements. These illustrations are ideal for: * Team onboarding pages * Company culture documentation * HR and people-ops content * Project kickoff pages * Retrospective summaries ### Technology and infrastructure[​](#technology-and-infrastructure "Direct link to Technology and infrastructure") This category covers technical concepts rendered as clean, modern illustrations. Cloud computing, server racks, network diagrams, security shields, and code editors are all represented. Use these for: * Technical documentation * Architecture decision records * Infrastructure runbooks * Security policy pages * DevOps and deployment guides ### Business and growth[​](#business-and-growth "Direct link to Business and growth") Illustrations in the business category cover strategic concepts: charts going up, target icons, roadmap visuals, handshake scenes, and process diagrams. These work well on: * Quarterly planning pages * OKR and goal-tracking documents * Strategy and vision pages * Sales enablement content * Executive summary sections ### Education and documentation[​](#education-and-documentation "Direct link to Education and documentation") This group features illustrations related to learning, reading, writing, and knowledge sharing. Books, notebooks, graduation caps, and teaching scenes appear here. Perfect for: * Training materials * How-to guides and tutorials * Knowledge base articles * Learning and development content * Documentation home pages ### Communication and workflows[​](#communication-and-workflows "Direct link to Communication and workflows") Scenes of presentations, email, messaging, feedback loops, and process flows live in this category. They are a good fit for: * Communication guidelines * Process documentation * SOP pages * Meeting templates * Feedback and review workflows ## Use cases: When to use SVG illustrations in Confluence[​](#use-cases-when-to-use-svg-illustrations-in-confluence "Direct link to Use cases: When to use SVG illustrations in Confluence") Knowing how to insert an illustration is only half the skill. Knowing when and where to use them is what separates visually effective Confluence pages from cluttered ones. Here are the most impactful use cases. ### Technical documentation[​](#technical-documentation "Direct link to Technical documentation") Technical documentation pages in Confluence -- API references, architecture guides, deployment runbooks -- tend to be dense with text and code. Adding a single relevant illustration at the top of a documentation page or above a major section heading creates a visual anchor that helps readers orient themselves. For example, a page about your CI/CD pipeline could feature a technology-themed illustration of a deployment workflow at the top. The illustration does not replace the technical content; it gives readers an immediate visual cue about what the page covers before they start reading the details. Illustrations are especially useful on documentation home pages and index pages, where they help differentiate sections and make long lists of links more scannable. ### Employee onboarding[​](#employee-onboarding "Direct link to Employee onboarding") Onboarding is one of the most content-heavy processes in any organization. New hires encounter dozens of Confluence pages in their first week: company values, team introductions, tool setups, process walkthroughs, and policy documents. SVG illustrations make these pages feel welcoming instead of overwhelming. Use people and collaboration illustrations on team introduction pages, education-themed illustrations on training materials, and workflow illustrations on process guides. The visual variety helps new hires distinguish between different types of content and makes the onboarding experience feel more polished. ### Presentations and reports[​](#presentations-and-reports "Direct link to Presentations and reports") Many teams use Confluence as a presentation platform, sharing pages in meetings instead of slide decks. SVG illustrations elevate these pages from plain documents to presentation-ready content. A well-placed illustration on a quarterly review page, a project status update, or a strategy proposal adds professionalism without requiring design skills. Because SVG files are resolution-independent, the illustrations look crisp when displayed on a projector, a large monitor, or shared over a video call. There are no pixelation or blurriness issues that you sometimes get with low-resolution image uploads. ### Knowledge base articles[​](#knowledge-base-articles "Direct link to Knowledge base articles") Self-service knowledge bases live or die by their usability. When employees or customers come to a knowledge base, they are usually looking for a quick answer. Illustrations help in two ways: 1. They break up long articles into visually distinct sections, making the content feel less intimidating. 2. They provide visual cues about the topic of each article when browsing an index page with thumbnails. A knowledge base article about "how to reset your password" with a relevant illustration at the top is more approachable than the same article with nothing but text. Readers are more likely to start reading, and they perceive the content as more trustworthy and up to date. ### Project and sprint pages[​](#project-and-sprint-pages "Direct link to Project and sprint pages") Agile teams often maintain Confluence pages for sprint planning, retrospectives, and project overviews. Adding illustrations to these pages makes them more engaging during sprint ceremonies when the page is shared on screen. A retrospective page with a relevant illustration feels more intentional and less like an afterthought. For project overview pages, an illustration at the top sets the tone for the entire project. It gives the page a visual identity that team members recognize at a glance when scanning their Confluence dashboard or space overview. ## Why SVG instead of PNG or JPEG?[​](#why-svg-instead-of-png-or-jpeg "Direct link to Why SVG instead of PNG or JPEG?") You might wonder why Content Craft uses SVG specifically rather than raster formats like PNG or JPEG. There are several practical advantages. **Resolution independence.** SVG files render perfectly at any size. The same illustration looks crisp on a phone screen, a laptop display, a 4K monitor, and a projector. Raster images become blurry when scaled up or waste bandwidth when saved at unnecessarily high resolutions. **Small file size.** SVG illustrations are typically much smaller than equivalent-quality PNG or JPEG files. This means faster page loads in Confluence, which is especially noticeable on pages with multiple illustrations. **Style consistency.** Because SVGs are vector-based, their visual style remains consistent regardless of how Confluence renders them. Colors do not shift, edges stay clean, and the illustrations integrate naturally with Confluence's own UI elements. **Accessibility.** SVG content can be read by screen readers when properly tagged, making illustrations more accessible to users with visual impairments compared to raster images that require separate alt text. **No versioning issues.** SVG illustrations inserted through Content Craft are not file attachments that clutter your page's attachment list. They render inline as part of the macro, keeping your attachment manager clean and focused on actual uploaded files. ## Tips for effective illustration usage[​](#tips-for-effective-illustration-usage "Direct link to Tips for effective illustration usage") Adding illustrations is easy. Adding them effectively takes a bit of thought. These tips will help you get the most out of Content Craft's SVG gallery. ### Match the illustration to the content[​](#match-the-illustration-to-the-content "Direct link to Match the illustration to the content") Every illustration should serve the content it accompanies. Before inserting an SVG, ask yourself: does this visual reinforce the message of the section it sits in? If the answer is not a clear yes, consider a different illustration or no illustration at all. A well-placed illustration on a page with three illustrations is more effective than seven illustrations that do not relate to the surrounding text. ### Use illustrations as section dividers[​](#use-illustrations-as-section-dividers "Direct link to Use illustrations as section dividers") On long pages with multiple H2 sections, placing an illustration between sections creates a natural visual break. This technique works especially well on documentation pages and knowledge base articles where readers are likely to skim. The illustration acts as a landmark that helps readers orient themselves on the page. ### Maintain a consistent visual style[​](#maintain-a-consistent-visual-style "Direct link to Maintain a consistent visual style") If you are building a set of related pages -- for example, an onboarding series or a documentation space -- use illustrations from the same category or with the same visual treatment. Content Craft's gallery is curated for internal consistency, so sticking to illustrations from the same category (or the same handful of categories) ensures your pages feel cohesive. ### Do not over-illustrate[​](#do-not-over-illustrate "Direct link to Do not over-illustrate") Not every section needs an illustration. As a general rule, a page of 1,000 to 2,000 words benefits from one to three illustrations. Shorter pages might need only one. Over-illustrating a page makes it feel busy and can distract from the content itself. Let the text carry the substance; let the illustrations provide visual relief and context. ### Consider mobile rendering[​](#consider-mobile-rendering "Direct link to Consider mobile rendering") Many Confluence users read pages on mobile devices. SVG illustrations scale gracefully to smaller screens, but their placement matters. Avoid placing illustrations inside complex table layouts or multi-column layouts that might not render well on mobile. Single-column page layouts with illustrations placed above or between sections work best across all devices. ## Common questions about SVG in Confluence[​](#common-questions-about-svg-in-confluence "Direct link to Common questions about SVG in Confluence") ### Can I customize the colors of SVG illustrations from Content Craft?[​](#can-i-customize-the-colors-of-svg-illustrations-from-content-craft "Direct link to Can I customize the colors of SVG illustrations from Content Craft?") The illustrations from Content Craft's gallery come with a fixed visual style. If you need custom-colored illustrations, you can download SVG files from external sources and upload them as Confluence attachments. Content Craft focuses on providing a ready-to-use library so you do not have to spend time on customization. ### Do SVG illustrations slow down Confluence pages?[​](#do-svg-illustrations-slow-down-confluence-pages "Direct link to Do SVG illustrations slow down Confluence pages?") No. SVG files are typically smaller than equivalent raster images. Content Craft renders them inline through the macro, so they load efficiently. Pages with multiple SVG illustrations generally load faster than pages with the same number of PNG or JPEG attachments. ### Can I use Content Craft on Confluence Data Center?[​](#can-i-use-content-craft-on-confluence-data-center "Direct link to Can I use Content Craft on Confluence Data Center?") Content Craft for Confluence is available on the Atlassian Marketplace for Confluence Cloud. Check the marketplace listing for the latest information on platform support. ### Do I need design skills to use Content Craft?[​](#do-i-need-design-skills-to-use-content-craft "Direct link to Do I need design skills to use Content Craft?") Not at all. The gallery is designed for non-designers. You browse, search, click, and save. The illustrations are professionally designed and ready to use as-is. The entire workflow requires zero design knowledge. ### Can I use Content Craft illustrations in exported pages?[​](#can-i-use-content-craft-illustrations-in-exported-pages "Direct link to Can I use Content Craft illustrations in exported pages?") SVG illustrations inserted through Content Craft render as part of the page content. When you export a Confluence page to PDF or Word, the illustrations are included in the export. The quality of the export depends on Confluence's export engine, but SVG-based content generally exports cleanly. ## Troubleshooting common issues[​](#troubleshooting-common-issues "Direct link to Troubleshooting common issues") ### The macro does not appear in the slash command menu[​](#the-macro-does-not-appear-in-the-slash-command-menu "Direct link to The macro does not appear in the slash command menu") If typing `/Content Craft for Confluence` does not show the macro, the app may not be installed correctly. Go to Confluence Settings, then manage apps, and verify that Content Craft for Confluence appears in your installed apps list. If it does not, try reinstalling from the Atlassian Marketplace. If it does appear but the macro is still missing, check that the app is enabled (not disabled) in the app management panel. ### The gallery panel opens but shows no illustrations[​](#the-gallery-panel-opens-but-shows-no-illustrations "Direct link to The gallery panel opens but shows no illustrations") This can happen if your Confluence instance has strict network firewall rules that block external asset loading. Content Craft's gallery loads illustration data from its CDN. Ensure your network allows outbound connections to the app's asset domains. If the issue persists, contact NGPILOT support through the Atlassian Marketplace listing. ### The illustration looks blurry after publishing[​](#the-illustration-looks-blurry-after-publishing "Direct link to The illustration looks blurry after publishing") SVG illustrations should render crisply at any size. If an illustration appears blurry, it may have been inadvertently converted to a raster format by a third-party Confluence theme or customization. Try viewing the page in Confluence's default theme to confirm. If the illustration is crisp in the default theme, the issue is with your custom theme, not with Content Craft. ### I cannot resize the illustration after inserting it[​](#i-cannot-resize-the-illustration-after-inserting-it "Direct link to I cannot resize the illustration after inserting it") After inserting an SVG through Content Craft, click on the illustration to select it. Resize handles should appear at the corners and edges. If they do not appear, try publishing the page and then editing it again. The Confluence editor sometimes needs a publish cycle to fully render the macro's interactive elements. ## Related resources[​](#related-resources "Direct link to Related resources") * [Content Craft for Confluence -- Usage Guide](/apps/content-craft-for-confluence.md) -- full documentation covering all features, gallery navigation, and frequently asked questions about the app. * [Best Confluence Apps for Developers](/blog/best-confluence-apps-developers.md) -- a curated list of NGPILOT apps that make Confluence more powerful for development teams, including code blocks, diagrams, and content tools. * [FAQ: Using Plugins and Security in Confluence](/blog/faq-using-plugins-security.md) -- answers to common questions about app security, permissions, data privacy, and safe plugin usage in Confluence. Adding SVG illustrations to Confluence pages does not have to mean opening a separate design tool, downloading files, and uploading attachments. Content Craft for Confluence puts a searchable, categorized illustration gallery directly inside the Confluence editor. Install the app, type the slash command, find the right illustration, and publish. Your pages go from text-heavy to visually engaging in under a minute, and your team gets documentation, onboarding materials, and presentations that are actually pleasant to read. ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [svg](/blog/tags/svg.md) * [illustrations](/blog/tags/illustrations.md) * [content-craft](/blog/tags/content-craft.md) * [how-to](/blog/tags/how-to.md) * [design](/blog/tags/design.md) --- # Modern FAQ Themes & Reordering — Accordion vs Centered May 2, 2026 · 11 min read [NGPilot](https://ngpilot.com) FAQ sections are one of the most practical elements you can add to a Confluence page. Whether you are documenting product details, building an IT help desk resource, or writing an onboarding guide, a well-structured FAQ section lets readers find answers without scrolling through walls of text or pinging someone on Slack. The problem is that Confluence does not give you a built-in way to create FAQ sections. Teams typically resort to manual workarounds: bullet lists, tables, or toggles built from expand macros. These methods work, sort of, but they are tedious to maintain, hard to reorder, and look inconsistent from page to page. **Modern FAQ for Confluence** solves this by giving you a dedicated macro for building FAQ sections with drag-and-drop reordering, WYSIWYG editing, and two display themes. This guide walks through the entire process, provides ready-to-use templates, and shares best practices so your FAQ pages actually help people find what they need. ## Why FAQ sections matter in Confluence[​](#why-faq-sections-matter-in-confluence "Direct link to Why FAQ sections matter in Confluence") Knowledge bases live and die by how quickly readers can find answers. When a new hire lands on your onboarding space, they do not want to read a 3,000-word document end to end. They want to scan a list of questions, find the one that matches their situation, and read a concise answer. FAQ sections solve this by presenting information in a question-and-answer format that is: * **Scannable** — Readers can quickly find the question that matches their need * **Concise** — Each answer addresses exactly one question, no fluff * **Self-service** — Readers resolve their own issues without filing a ticket or sending a message For teams using Confluence as a knowledge base, FAQ sections reduce repetitive questions, shorten onboarding time, and keep documentation useful over time. ## Step-by-step tutorial: building an FAQ section[​](#step-by-step-tutorial-building-an-faq-section "Direct link to Step-by-step tutorial: building an FAQ section") ### Step 1: Install Modern FAQ for Confluence[​](#step-1-install-modern-faq-for-confluence "Direct link to Step 1: Install Modern FAQ for Confluence") Open the Atlassian Marketplace and search for **Modern FAQ for Confluence** by NGPILOT. Click **Get App** to install it on your Confluence Cloud instance. The installation takes a few seconds and requires admin permissions. ### Step 2: Insert the FAQ macro on a page[​](#step-2-insert-the-faq-macro-on-a-page "Direct link to Step 2: Insert the FAQ macro on a page") Open or create the Confluence page where you want the FAQ section. Click **Edit** to enter the page editor, then type `/Modern FAQ for Confluence` in the editor. Select the **Modern FAQ for Confluence** macro from the dropdown. The macro configuration panel opens. ### Step 3: Add your questions and answers[​](#step-3-add-your-questions-and-answers "Direct link to Step 3: Add your questions and answers") Inside the macro editor, you will see fields for questions and answers. Type your first question in the question field and your answer in the answer field. The answer editor is a full WYSIWYG editor, so you can: * Format text with bold, italic, and lists * Add hyperlinks to other Confluence pages or external URLs * Insert images to illustrate your answer Click the **+** button to add another question-and-answer pair. Click the **-** button to remove the last one. ### Step 4: Choose a display theme[​](#step-4-choose-a-display-theme "Direct link to Step 4: Choose a display theme") Modern FAQ offers two display themes: * **Centered theme** — All questions and answers are visible on the page in a clean, centered layout. Best for short FAQ sections where you want readers to see everything at a glance. * **Accordion theme** — Questions are listed with answers hidden behind a click. Readers click a question to expand the answer. Best for longer FAQ sections where showing all answers at once would make the page too long. Click the theme selector at the top right of the config page to switch between themes. Preview both to see which one works better for your content. ### Step 5: Reorder with drag and drop[​](#step-5-reorder-with-drag-and-drop "Direct link to Step 5: Reorder with drag and drop") After adding all your questions, you may want to reorder them. Put the most common or important questions first so readers find them without scrolling. With Modern FAQ, you can drag and drop questions into any order. No need to cut, paste, or re-enter content. Once you are happy with the order and content, click **OK** to save the macro, then publish or update the Confluence page. Your FAQ section is live. ## FAQ section templates[​](#faq-section-templates "Direct link to FAQ section templates") Starting from a blank page is hard. Here are three ready-to-use FAQ templates you can copy directly into Modern FAQ for Confluence. Open the macro editor, add a question-and-answer pair for each item, and paste the content below. ### Template 1: Product FAQ[​](#template-1-product-faq "Direct link to Template 1: Product FAQ") Use this template on product documentation pages, pricing pages, or landing pages in Confluence. **Q: What is included in the free plan?** A: The free plan includes access to core features for up to 5 users. You get basic reporting, standard integrations, and community support. Paid plans add advanced analytics, priority support, and custom workflows. **Q: Can I upgrade or downgrade my plan at any time?** A: Yes. You can change your plan at any time from the billing settings page. Upgrades take effect immediately. Downgrades take effect at the start of the next billing cycle. **Q: Which integrations are supported?** A: We integrate with Jira, Confluence, Slack, Microsoft Teams, GitHub, and Google Workspace. Custom integrations are available on the Enterprise plan via our REST API. **Q: Is my data encrypted?** A: Yes. All data is encrypted at rest using AES-256 and in transit using TLS 1.2 or higher. We undergo annual SOC 2 Type II audits. **Q: How do I request a feature?** A: Submit a feature request through the in-app feedback form or email our product team. We review all requests monthly and publish a public roadmap. ### Template 2: IT Help Desk FAQ[​](#template-2-it-help-desk-faq "Direct link to Template 2: IT Help Desk FAQ") Use this template on your internal IT support space in Confluence. **Q: How do I reset my password?** A: Go to the company login page and click **Forgot Password**. Enter your corporate email address and follow the instructions in the reset email. If you do not receive the email within 5 minutes, check your spam folder or contact IT support. **Q: How do I connect to the company VPN?** A: Download the VPN client from the IT downloads page. Install it using your admin credentials. Open the client, select the office location nearest to you, and sign in with your corporate username and password. If you are on macOS, you may need to approve the network extension in System Preferences. **Q: How do I request access to a specific tool or application?** A: Submit an access request through the IT Service Desk portal. Select the tool you need, provide a business justification, and choose your manager as the approver. Requests are typically processed within 24 hours. **Q: What should I do if my laptop is lost or stolen?** A: Immediately contact IT security at or call the IT helpline. We will remotely wipe the device and issue a replacement. File a police report if the device was stolen and forward the report number to IT. **Q: How do I set up multi-factor authentication?** A: Open the MFA enrollment page from the IT portal. Scan the QR code with your authenticator app (Google Authenticator or Microsoft Authenticator). Enter the 6-digit code to verify setup. Keep your backup codes in a safe place. ### Template 3: Onboarding FAQ[​](#template-3-onboarding-faq "Direct link to Template 3: Onboarding FAQ") Use this template on your new hire onboarding space in Confluence. **Q: What tools will I need on my first day?** A: You will receive a laptop pre-configured with your accounts. The key tools you will use are Confluence (documentation), Jira (project tracking), Slack (communication), and Google Workspace (email and calendar). Your onboarding buddy will help you log in to each one. **Q: Who is my onboarding buddy?** A: Your onboarding buddy is assigned by your hiring manager and listed in your welcome email. They are a current team member who can answer day-to-day questions, introduce you to colleagues, and help you navigate internal processes. **Q: How do I request time off?** A: Submit time-off requests through the HR portal at least 2 weeks in advance for planned leave. For sick leave, notify your manager via Slack or email on the day. Your manager will approve or discuss the request in the HR system. **Q: Where can I find the company holidays calendar?** A: The company holidays calendar is published on the HR space in Confluence and is also available in Google Calendar. Search for "Company Holidays" in the Google Calendar settings and click subscribe. **Q: How do I expense a purchase?** A: Submit expenses through the finance portal within 30 days of the purchase. Attach a receipt photo or PDF. Expenses under $50 are auto-approved. Larger expenses require your manager's approval and typically process within 5 business days. ## Best practices for FAQ sections[​](#best-practices-for-faq-sections "Direct link to Best practices for FAQ sections") A good FAQ section is more than a list of questions. Here are five tips to make yours genuinely useful. ### 1. Write questions the way people actually ask them[​](#1-write-questions-the-way-people-actually-ask-them "Direct link to 1. Write questions the way people actually ask them") Do not write " Regarding password reset procedures" as a question header. Write "How do I reset my password?" Use the language your readers use. If you have access to search logs or support ticket data, look at the exact phrasing people use when they ask questions, and mirror that in your FAQ. ### 2. Keep answers under 100 words[​](#2-keep-answers-under-100-words "Direct link to 2. Keep answers under 100 words") FAQ answers should be direct and actionable. If your answer requires more than 100 words, consider whether the question should be split into two, or whether the detailed answer belongs on a separate page with a link from the FAQ. The FAQ section is for quick answers, not deep dives. ### 3. Put the most important questions first[​](#3-put-the-most-important-questions-first "Direct link to 3. Put the most important questions first") Readers scan from the top. If the most common question is buried at position 12, people will scroll past it or give up. Use Modern FAQ's drag-and-drop reordering to surface the questions that matter most. Review your order quarterly based on support ticket volume or page analytics. ### 4. Use the Accordion theme for long FAQ sections[​](#4-use-the-accordion-theme-for-long-faq-sections "Direct link to 4. Use the Accordion theme for long FAQ sections") If you have more than 6 questions, the Centered theme can make the page feel overwhelming because all answers are visible at once. The Accordion theme keeps the page tidy by collapsing answers behind clicks. Readers scan the question list, click what interests them, and expand only the answer they need. For shorter sections of 3 to 5 questions, the Centered theme works well because everything fits on one screen. ### 5. Link to detailed pages from your answers[​](#5-link-to-detailed-pages-from-your-answers "Direct link to 5. Link to detailed pages from your answers") FAQ answers should be concise, but sometimes a reader needs more detail. Use hyperlinks inside your answers to point to full documentation pages. For example, an answer about VPN setup can link to the full network configuration guide. This keeps the FAQ scannable while still providing paths to deeper information. ## Modern FAQ vs building FAQ sections manually[​](#modern-faq-vs-building-faq-sections-manually "Direct link to Modern FAQ vs building FAQ sections manually") Some teams build FAQ sections using native Confluence macros instead of a dedicated app. Here is how the approaches compare. | Feature | Modern FAQ for Confluence | Manual approach (expand macros + tables) | | ---------------------------- | ---------------------------------------- | ---------------------------------------- | | **Setup time** | Under 2 minutes | 10-30 minutes per section | | **Display themes** | 2 built-in themes (Centered + Accordion) | None — you style manually | | **Reordering** | Drag and drop | Cut and paste content | | **Rich text in answers** | Full WYSIWYG editor | Limited to Confluence editor macros | | **Consistency across pages** | Same macro, same look everywhere | Depends on who builds each section | | **Maintenance effort** | Edit the macro, click OK | Edit individual expand macros one by one | The manual approach works for a single FAQ section that you set up once and never touch again. But if you maintain FAQ sections across multiple pages, or if non-technical editors need to update them, a dedicated macro saves significant time and keeps everything consistent. Modern FAQ for Confluence also handles edge cases that manual setups do not. Expand macros nested inside tables can break on mobile or in exports. The Modern FAQ macro renders correctly in both contexts because it is purpose-built for FAQ content. ## When to use FAQ sections vs Q\&A forums[​](#when-to-use-faq-sections-vs-qa-forums "Direct link to When to use FAQ sections vs Q\&A forums") FAQ sections and Q\&A forums serve different purposes in Confluence. FAQ sections are curated by editors — someone decides which questions appear and writes the answers. They are best for stable, well-known information like product features, IT procedures, and onboarding steps. Q\&A forums are open community spaces where anyone can ask a question, others can answer, and the best answer is upvoted. They are best for evolving topics where the answers change over time or where collective knowledge is needed. If you need both, consider pairing Modern FAQ for Confluence with Modern Questions for Confluence. Use FAQ sections on documentation pages for curated answers, and use the Q\&A forum for open-ended team discussions. For a deeper comparison of FAQ and Q\&A apps, see [FAQ and Q\&A Apps for Confluence Compared](/blog/faq-questions-confluence-comparison.md). ## Related resources[​](#related-resources "Direct link to Related resources") * [Modern FAQ for Confluence — documentation](/apps/modern-faq-for-confluence.md) — full usage guide with screenshots * [FAQ and Q\&A Apps for Confluence Compared](/blog/faq-questions-confluence-comparison.md) — detailed comparison of FAQ and Q\&A apps on the Atlassian Marketplace Try Modern FAQ for Confluence Accordion-style FAQ sections with drag-and-drop reordering and two themes — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236739/modern-faq-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-faq-for-confluence) ## Related guides * [Confluence Questions & Answers Template](/blog/confluence-questions-answers-template.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [faq](/blog/tags/faq.md) * [accordion](/blog/tags/accordion.md) * [how-to](/blog/tags/how-to.md) * [knowledge-base](/blog/tags/knowledge-base.md) --- # How to Choose a Markdown Editor for Confluence August 2, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer Confluence has no native Markdown editor. To write pages in Markdown you need a Marketplace app. The right choice depends on how your team works: occasional converters need a simple paste tool; engineering teams writing specs, docs, and equations daily need a full Markdown macro with live preview, math, and diagram support. What you'll learn 1. Why Confluence needs a Markdown app (and what happens without one) 2. The four categories of Markdown tools for Confluence 3. A decision framework for picking the right one 4. What features matter most for technical vs non-technical teams Developers, technical writers, and data scientists think in Markdown. READMEs, API docs, pull request descriptions, and design specs are all written in it. But Confluence — where most of that knowledge ends up living — has no native Markdown support. Pasting Markdown into the WYSIWYG editor produces broken tables, literal asterisks, and lost formatting. This guide walks through the options so you can pick the right Markdown approach for your team without trial and error. ## Why Markdown matters in Confluence[​](#why-markdown-matters-in-confluence "Direct link to Why Markdown matters in Confluence") Markdown is the de facto language of technical documentation. It is plain text, so it diffs cleanly in version control, reviews well in pull requests, and ports between tools. Teams that write in Markdown every day — engineers, data scientists, technical writers — expect to keep that workflow inside Confluence rather than switching to a slower WYSIWYG editor. The problem is that Confluence's editor is WYSIWYG only. There is no raw Markdown mode. When you paste Markdown content, it arrives as literal text: asterisks instead of bold, pipe characters instead of tables, backticks instead of code blocks. For teams migrating documentation from GitHub, Notion, or local `.md` files, this means rebuilding every page by hand. ## The four categories of Markdown tools[​](#the-four-categories-of-markdown-tools "Direct link to The four categories of Markdown tools") Not all Markdown solutions for Confluence are the same. They fall into four categories, each suited to a different use case. ### 1. Paste-and-convert tools[​](#1-paste-and-convert-tools "Direct link to 1. Paste-and-convert tools") These tools convert Markdown into Confluence storage format on paste. You paste your Markdown, the tool renders it as native Confluence content, and you continue editing in WYSIWYG. The Markdown source is not preserved — once converted, you edit the visual result. **Best for:** One-time migrations, occasional pastes, teams that mostly use WYSIWYG but sometimes need to bring in Markdown content. **Limitation:** No ongoing Markdown editing. If you need to update the content later, you edit it in the visual editor, not in Markdown. ### 2. Import tools[​](#2-import-tools "Direct link to 2. Import tools") These tools import `.md` files from GitHub, Notion, or your local machine and create Confluence pages from them. They are batch-oriented — good for migrating a whole docs site at once. **Best for:** Large migrations where you are moving dozens or hundreds of Markdown files into Confluence. **Limitation:** Like paste-and-convert, the Markdown is converted and the source is lost. Not suitable for ongoing Markdown authoring. ### 3. Full Markdown macros[​](#3-full-markdown-macros "Direct link to 3. Full Markdown macros") These tools add a dedicated Markdown macro to the Confluence editor. You insert the macro, write or paste Markdown into a code editor, see a live split preview, and save. The Markdown source is preserved — you can re-edit it any time. The best macros also render Mermaid diagrams, KaTeX/LaTeX math, and syntax-highlighted code inline. **Best for:** Engineering teams, technical writers, and data scientists who write in Markdown daily and need the full feature set (math, diagrams, code, tables). **Key features to look for:** * Live split preview (write on the left, see rendered output on the right) * Source preservation (re-edit the Markdown later) * Mermaid and diagram rendering inline * KaTeX / LaTeX / MathJax support for equations * 100+ code language syntax highlighting * GFM table support including alignment * WYSIWYG toggle for non-technical editors ### 4. External editors with Confluence sync[​](#4-external-editors-with-confluence-sync "Direct link to 4. External editors with Confluence sync") Some teams write Markdown in external editors (VS Code, Obsidian) and sync to Confluence via scripts or integrations. This is the most flexible but also the most complex — it requires maintaining a sync pipeline. **Best for:** Teams with strong DevOps capability who want full control over their Markdown toolchain. **Limitation:** High setup and maintenance overhead. Not practical for most teams. ## A decision framework[​](#a-decision-framework "Direct link to A decision framework") | If your team... | Choose... | Because... | | ------------------------------------------ | ---------------------------------- | -------------------------------------------------------------------- | | Writes docs in Markdown every day | **Full Markdown macro** | You need live preview, source preservation, and inline diagrams/math | | Migrates docs from GitHub/Notion once | **Import tool** | Batch conversion, no need for ongoing Markdown editing | | Occasionally pastes Markdown | **Paste-and-convert** | Quick one-off conversion without a macro | | Has DevOps capacity and wants full control | **External editor + sync** | Maximum flexibility, but high maintenance | | Mixes technical and non-technical editors | **Full macro with WYSIWYG toggle** | Engineers use Markdown, others use visual mode | ## What to check before choosing[​](#what-to-check-before-choosing "Direct link to What to check before choosing") Regardless of which category you pick, verify these before committing: 1. **Does the rendered output behave like native Confluence content?** It should be searchable, exportable to PDF/Word, and respect page permissions. 2. **Is the Markdown source preserved?** If you ever need to re-edit in Markdown, the source must be stored, not discarded on save. 3. **Does it support the syntax you need?** GFM tables, fenced code blocks, task lists, math equations, and Mermaid diagrams are common requirements for technical teams. 4. **Does it work in dark mode?** A good macro adapts to Confluence dark mode automatically. 5. **Is it built on Forge?** Forge apps store data on Atlassian infrastructure — more secure and more future-proof than Connect alternatives. (See our [Forge vs Connect guide](/blog/forge-vs-connect-atlassian-admins-2026.md) for why this matters.) ## Explore Markdown solutions[​](#explore-markdown-solutions "Direct link to Explore Markdown solutions") If you are looking for a full Markdown macro, explore our [content and editing solutions](/solutions.md) to see how Markdown fits into the broader Confluence workflow. You can also browse the [full app catalog](/apps.md) to compare Markdown tools side by side. ## Frequently Asked Questions[​](#frequently-asked-questions "Direct link to Frequently Asked Questions") ### Can I use Markdown in Confluence without an app?[​](#can-i-use-markdown-in-confluence-without-an-app "Direct link to Can I use Markdown in Confluence without an app?") No. Confluence has no native Markdown editor or Markdown rendering. You need a Marketplace app — either a paste-and-convert tool or a full Markdown macro — to write or display Markdown content in Confluence pages. ### Will my Markdown tables and code blocks render correctly?[​](#will-my-markdown-tables-and-code-blocks-render-correctly "Direct link to Will my Markdown tables and code blocks render correctly?") With a full Markdown macro, yes. GFM tables (including column alignment), fenced code blocks with language tags, task lists, and blockquotes all render correctly in the live preview. With paste-and-convert tools, the conversion is usually accurate but may lose some advanced formatting. ### Can I mix Markdown with Confluence macros?[​](#can-i-mix-markdown-with-confluence-macros "Direct link to Can I mix Markdown with Confluence macros?") With a full Markdown macro, the Markdown lives inside a single macro on the page. You can place other Confluence macros above, below, or alongside it, but you cannot embed Confluence macros inside the Markdown block itself. For most technical documentation use cases, this is not a limitation. *** *Explore [content and editing solutions](/solutions.md) or browse the [full app catalog](/apps.md) to find the right Markdown tool for your team.* Try Enhanced Markdown for Confluence Write Markdown with live split preview, Mermaid diagrams, KaTeX/LaTeX math, and 190+ code languages — all in one macro, free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=enhanced-markdown-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [comparison](/blog/tags/comparison.md) * [how-to](/blog/tags/how-to.md) --- # How to Create Architecture Diagrams in Confluence (3 Methods with Examples) May 2, 2026 · 14 min read [NGPilot](https://ngpilot.com) Architecture diagrams are the backbone of technical documentation. They show how services communicate, where data flows, and which infrastructure components underpin your system. When a new engineer joins your team, the first thing they look for is an architecture diagram. When something breaks in production, the incident response starts at the same diagram. Yet many teams store their architecture diagrams in external tools -- [draw.io](/blog/faq-excalidraw-vs-drawio-confluence.md), Lucidchart, or even desktop applications -- detached from the documentation where they matter most. Confluence is where your runbooks live, where architecture decision records are written, and where post-mortem discussions happen. Keeping your architecture diagrams inside Confluence eliminates context-switching and ensures diagrams evolve alongside the written documentation they illustrate. This guide walks through three ways to create architecture diagrams directly in Confluence, using NGPILOT apps designed for different workflows. Every Mermaid example is copy-paste ready, so you can insert it into a Confluence page and see the result immediately. ## Why Confluence is the right place for architecture diagrams[​](#why-confluence-is-the-right-place-for-architecture-diagrams "Direct link to Why Confluence is the right place for architecture diagrams") Before diving into the tools, it is worth understanding why embedding diagrams in Confluence matters more than linking to an external diagramming tool. **Single source of truth.** When architecture diagrams live on the same page as the design docs, ADRs, and runbooks that reference them, everything stays synchronized. You edit the diagram and the surrounding documentation in one place. **Access control built in.** Confluence space permissions already govern who can view and edit your documentation. Diagrams embedded as macros inherit those same permissions. No separate account provisioning or license management for an external diagramming service. **Search and discovery.** Confluence's full-text search indexes page content, including macro content. Team members searching for "payment service" or "Kubernetes cluster" will find the pages containing those diagrams. **No file attachment drift.** Exported PNG and SVG files attached to Confluence pages go stale the moment the architecture changes. Embedded macros always render the current version of the diagram. **Collaborative editing.** Multiple team members can edit a Confluence page and its embedded diagrams. Changes are tracked in the page history, making it easy to see when and how the architecture evolved. ## Step-by-step tutorial: Creating architecture diagrams in Confluence[​](#step-by-step-tutorial-creating-architecture-diagrams-in-confluence "Direct link to Step-by-step tutorial: Creating architecture diagrams in Confluence") ### Step 1 -- Choose your architecture diagram tool[​](#step-1----choose-your-architecture-diagram-tool "Direct link to Step 1 -- Choose your architecture diagram tool") Three NGPILOT apps support architecture diagrams in Confluence, each with a different approach: * **Mermaid Plus Diagrams & AI Agent for Confluence** -- Write architecture diagrams in text-based Mermaid syntax. Best for teams that want versionable, diffable diagrams they can maintain alongside code. Supports flowcharts, C4 diagrams, and the dedicated `architecture-beta` diagram type. * **Excalidraw Plus for Confluence** -- Draw architecture diagrams visually on a freeform canvas with drag-and-drop shapes. Ships with 220+ shape libraries including AWS, Azure, and GCP icon packs. Best for teams that prefer visual editing and want pixel-perfect cloud architecture diagrams. * **Diagram Duo for Confluence** -- Combines both Excalidraw and Mermaid in a single macro. Switch between a visual canvas and a text-based code editor depending on which part of the architecture you are documenting. Best for teams that want maximum flexibility in one app. ### Step 2 -- Install the app from Atlassian Marketplace[​](#step-2----install-the-app-from-atlassian-marketplace "Direct link to Step 2 -- Install the app from Atlassian Marketplace") Go to the [Atlassian Marketplace](https://marketplace.atlassian.com/) and search for your chosen app: * Search **Mermaid Plus Diagrams & AI Agent for Confluence** for the text-based workflow * Search **Excalidraw Plus for Confluence** for the visual drawing workflow * Search **Diagram Duo for Confluence** for the combined visual + text workflow Click **Get App** and follow the installation prompts. If your organization requires admin approval for marketplace apps, contact your Confluence administrator. All three apps support Confluence Cloud and Confluence Data Center. ### Step 3 -- Insert the macro on a Confluence page[​](#step-3----insert-the-macro-on-a-confluence-page "Direct link to Step 3 -- Insert the macro on a Confluence page") Open any Confluence page in edit mode and use the slash command for your app: * Type `/mermaid` and select **Mermaid Plus Diagrams & AI Agent for Confluence** * Type `/excalidraw` and select **Excalidraw Plus for Confluence** * For Diagram Duo, type `/excalidraw` or `/mermaid` to insert the respective editor The macro editor opens, and you can start building your diagram immediately. ### Step 4 -- Build your architecture diagram[​](#step-4----build-your-architecture-diagram "Direct link to Step 4 -- Build your architecture diagram") The workflow differs depending on which tool you chose: **With Mermaid Plus**, write or paste Mermaid syntax in the code editor. The live preview on the left renders your diagram in real time. Use subgraphs to group related services, and use the `architecture-beta` or `C4Context` diagram types for structured architecture views. **With Excalidraw Plus**, open the shape library panel and search for the cloud provider or infrastructure category you need. Drag AWS, Azure, or GCP shapes onto the canvas, connect them with arrows, and add labels. The freeform canvas lets you position elements exactly where you want them. **With Diagram Duo**, switch between the Excalidraw tab and the Mermaid tab as needed. Start with a visual sketch on the Excalidraw canvas, then formalize parts of the architecture in Mermaid syntax -- or work in whichever mode suits the current section of the diagram. ### Step 5 -- Save and share with your team[​](#step-5----save-and-share-with-your-team "Direct link to Step 5 -- Save and share with your team") Click **Save** on the macro to persist your diagram, then **Publish** the Confluence page. The diagram renders inline when anyone views the page. Team members with edit permissions can click the macro and select **Edit** to modify the architecture diagram directly. Diagrams support dark mode automatically. When a viewer has Confluence dark mode enabled, the diagram adapts its colors for readability. ## 3 Mermaid architecture diagram examples (copy-paste ready)[​](#3-mermaid-architecture-diagram-examples-copy-paste-ready "Direct link to 3 Mermaid architecture diagram examples (copy-paste ready)") These three examples cover the most common architecture diagram patterns. Copy the code block, paste it into the Mermaid Plus macro in Confluence, and adjust the service names and connections to match your system. ### Example 1 -- Microservices architecture[​](#example-1----microservices-architecture "Direct link to Example 1 -- Microservices architecture") This diagram shows a typical microservices deployment with an API gateway, multiple backend services, shared infrastructure, and asynchronous event-driven communication. Use this as a starting point for documenting any service-oriented architecture. ``` graph TB subgraph Clients Web[Web Application] Mobile[Mobile App] CLI[CLI Tools] end subgraph Gateway APIGW[API Gateway
Rate Limiting & Auth] end subgraph Services UserSvc[User Service] OrderSvc[Order Service] CatalogSvc[Catalog Service] PaymentSvc[Payment Service] NotifySvc[Notification Service] end subgraph Data Layer UserDB[(User DB
PostgreSQL)] OrderDB[(Order DB
PostgreSQL)] CatalogDB[(Catalog DB
MongoDB)] Redis[(Redis Cache)] end subgraph Messaging EventBus[Event Bus
Kafka] end subgraph External Stripe[Stripe API] SendGrid[SendGrid API] end Web --> APIGW Mobile --> APIGW CLI --> APIGW APIGW --> UserSvc APIGW --> OrderSvc APIGW --> CatalogSvc UserSvc --> UserDB UserSvc --> Redis OrderSvc --> OrderDB OrderSvc --> Redis OrderSvc --> PaymentSvc OrderSvc --> EventBus CatalogSvc --> CatalogDB CatalogSvc --> Redis PaymentSvc --> Stripe PaymentSvc --> EventBus EventBus --> NotifySvc NotifySvc --> SendGrid ``` **How to customize this diagram:** * Add or remove services in the `Services` subgraph to match your architecture * Change database labels to reflect your actual technology choices (MySQL, DynamoDB, Cosmos DB, etc.) * Add connection labels with arrow syntax: `OrderSvc -->|gRPC| PaymentSvc` * Use `style` directives to color-code services by team ownership or criticality ### Example 2 -- AWS cloud architecture[​](#example-2----aws-cloud-architecture "Direct link to Example 2 -- AWS cloud architecture") This diagram models a production AWS deployment with a VPC, public and private subnets, load balancing, container orchestration, and managed database services. It uses the Mermaid flowchart syntax with labeled subgraphs to represent AWS regions and VPCs. ``` graph TB subgraph AWS["AWS Cloud"] subgraph VPC["VPC 10.0.0.0/16"] subgraph Public["Public Subnet"] ALB[Application Load Balancer] NAT[NAT Gateway] Bastion[Bastion Host] end subgraph Private["Private Subnet"] subgraph ECS["ECS Cluster"] TaskA[API Service
Fargate Task] TaskB[Worker Service
Fargate Task] end end subgraph Data["Data Subnet"] RDS[(RDS PostgreSQL
Multi-AZ)] ElastiCache[(ElastiCache
Redis Cluster)] end end subgraph Global["Global Services"] Route53[Route 53
DNS] CloudFront[CloudFront
CDN] S3[S3 Bucket
Static Assets] SQS[SQS Queue] Secrets[Secrets Manager] end end Users[Users / Clients] --> Route53 Route53 --> CloudFront CloudFront --> ALB CloudFront --> S3 ALB --> TaskA TaskA --> ElastiCache TaskA --> RDS TaskA --> SQS TaskA --> Secrets SQS --> TaskB TaskB --> RDS TaskB --> Secrets NAT --> TaskA NAT --> TaskB ``` For more detailed AWS diagrams with precise icon representations, use [Excalidraw Plus for Confluence](/docs/Excalidraw-plus-for-Confluence/usage.md) with the AWS shape library. Excalidraw provides pixel-accurate AWS architecture icons that match the official AWS Architecture Center diagrams. ### Example 3 -- C4 model system context[​](#example-3----c4-model-system-context "Direct link to Example 3 -- C4 model system context") The C4 model provides four levels of architecture abstraction: Context, Container, Component, and Code. Mermaid supports C4 diagrams natively through the `C4Context` and `C4Container` diagram types. This example shows a system context diagram for a SaaS product. ``` C4Context title System Context Diagram - Order Management Platform Person(customer, "Customer", "Places orders and tracks deliveries") Person(admin, "Admin", "Manages products and monitors system health") Person(support, "Support Agent", "Handles customer inquiries and refunds") System(omp, "Order Management Platform", "Core platform handling orders, inventory, and payments") System_Ext(payment, "Payment Gateway", "Processes credit card and PayPal transactions") System_Ext(email, "Email Service", "Sends order confirmations and shipping notifications") System_Ext(wms, "Warehouse Management", "Tracks physical inventory and shipping") System_Ext(analytics, "Analytics Platform", "Collects events for business intelligence") Enterprise_Boundary(enterprise, "Organization Boundary") { System(bi, "BI Dashboard", "Internal reporting and metrics") } Rel(customer, omp, "Places orders via", "HTTPS/Web") Rel(admin, omp, "Manages catalog via", "HTTPS/Web") Rel(support, omp, "Looks up orders via", "HTTPS/Web") Rel(omp, payment, "Charges customers via", "REST API") Rel(omp, email, "Sends notifications via", "SMTP/API") Rel(omp, wms, "Syncs inventory via", "REST API") Rel(omp, analytics, "Publishes events via", "Kafka") Rel(bi, analytics, "Queries data from", "SQL") ``` **Tips for C4 diagrams in Mermaid:** * Start with `C4Context` for the broadest view, then drill into `C4Container` for individual system internals * Use `System_Ext` for external dependencies your team does not control * Use `Enterprise_Boundary` to distinguish internal and external systems * Add `Rel` connections with technology labels to document integration protocols ## Comparison: Mermaid vs Excalidraw vs Diagram Duo for architecture diagrams[​](#comparison-mermaid-vs-excalidraw-vs-diagram-duo-for-architecture-diagrams "Direct link to Comparison: Mermaid vs Excalidraw vs Diagram Duo for architecture diagrams") Each of the three tools has distinct strengths for architecture documentation. The right choice depends on your team's workflow and the type of architecture diagram you need. | Criteria | Mermaid Plus | Excalidraw Plus | Diagram Duo | | --------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | ----------------------------------------------------- | | **Input method** | Text syntax (code editor) | Visual canvas (drag and drop) | Both in one macro | | **Cloud provider shapes** | Text labels with subgraphs | 220+ shape libraries (AWS, Azure, GCP) | Both approaches available | | **C4 model support** | Native C4Context and C4Container types | Manual arrangement of shapes | Can combine C4 Mermaid with visual annotations | | **Auto-layout** | Yes -- Mermaid handles positioning | No -- manual placement | Mermaid tab auto-layouts; Excalidraw tab is manual | | **Version control / diffs** | Excellent -- text-based, easy to diff in page history | Limited -- binary diagram data | Mermaid parts are diffable; Excalidraw parts are not | | **Collaboration style** | Edit code and preview side by side | Direct visual manipulation on canvas | Choose mode per editing session | | **Learning curve** | Moderate -- need to learn Mermaid syntax | Low -- drag and drop is intuitive | Moderate -- learn both workflows | | **Best for** | Structured architecture docs, C4 diagrams, change-tracked diagrams | Cloud architecture diagrams with provider icons, whiteboard-style architecture sessions | Teams that need both structured and freeform diagrams | ### When to choose Mermaid Plus[​](#when-to-choose-mermaid-plus "Direct link to When to choose Mermaid Plus") Pick Mermaid Plus when your architecture diagrams are part of formal documentation that changes frequently and needs to be reviewed through diffs. The text-based approach means every change is visible in Confluence page history. It is also the best choice for C4 model diagrams, since Mermaid has native support for `C4Context` and `C4Container` syntax. Read the full documentation: [Mermaid Plus Diagrams & AI Agent for Confluence usage guide](/docs/Mermaid-Plus-for-Confluence/usage.md). ### When to choose Excalidraw Plus[​](#when-to-choose-excalidraw-plus "Direct link to When to choose Excalidraw Plus") Pick Excalidraw Plus when you need pixel-perfect cloud architecture diagrams that use official AWS, Azure, or GCP icons. The visual canvas is also better suited for architecture brainstorming sessions where the diagram evolves rapidly and team members need to move elements freely without worrying about syntax errors. Excalidraw Plus ships with 220+ shape libraries. For architecture diagrams specifically, the AWS Architecture, Azure Icons, Google Cloud Platform, Kubernetes, and Network Diagram libraries are the most relevant. Read the full documentation: [Excalidraw Plus for Confluence usage guide](/docs/Excalidraw-plus-for-Confluence/usage.md). ### When to choose Diagram Duo[​](#when-to-choose-diagram-duo "Direct link to When to choose Diagram Duo") Pick Diagram Duo when your team has mixed preferences -- some engineers want to write Mermaid code, others want to draw visually. Diagram Duo gives you both editors in a single macro, so you can start with an Excalidraw whiteboard sketch during a meeting, then formalize the architecture in Mermaid afterward. Or use Excalidraw for the cloud infrastructure layer and Mermaid for the service interaction layer, all on the same diagram. Read the full documentation: [Diagram Duo for Confluence usage guide](/docs/diagram-duo-for-confluence/usage.md). ## Best practices for architecture diagrams in Confluence[​](#best-practices-for-architecture-diagrams-in-confluence "Direct link to Best practices for architecture diagrams in Confluence") Regardless of which tool you choose, these best practices will help you create architecture diagrams that are clear, maintainable, and useful to your team. ### Start with the system context before diving into details[​](#start-with-the-system-context-before-diving-into-details "Direct link to Start with the system context before diving into details") The C4 model's philosophy is sound: begin with a context diagram that shows your system and its external dependencies, then progressively add detail. A context diagram fits on a single screen and gives readers the big picture before they encounter the complexity of container-level or component-level diagrams. ### Use consistent naming conventions[​](#use-consistent-naming-conventions "Direct link to Use consistent naming conventions") Establish a naming standard for services, databases, and external systems across all your architecture diagrams. If the payment service is called "Payment Service" in one diagram and "PaymentSvc" in another, readers will waste time wondering whether they are the same thing. Document your naming convention on a dedicated Confluence page and link to it from every architecture diagram. ### Color-code by domain or team ownership[​](#color-code-by-domain-or-team-ownership "Direct link to Color-code by domain or team ownership") Use colors to distinguish different ownership domains. For example, make all infrastructure components gray, all backend services blue, all data stores green, and all external integrations orange. This makes it immediately clear which parts of the architecture a given team owns and which cross team boundaries. In Mermaid, use the `style` directive to apply colors: ``` style APIGW fill:#4A90D9,stroke:#2C5F8A,color:#fff style OrderDB fill:#52B788,stroke:#2D6A4F,color:#fff style Stripe fill:#F4A261,stroke:#E76F51,color:#fff ``` In Excalidraw, select shapes and apply fill colors directly from the color picker. ### Keep diagrams to one level of abstraction[​](#keep-diagrams-to-one-level-of-abstraction "Direct link to Keep diagrams to one level of abstraction") Do not mix infrastructure details (subnets, load balancers) with application-level concepts (service boundaries, domain events) in the same diagram. If you need both views, create two diagrams and link between them on the Confluence page. A diagram that tries to show everything at once becomes unreadable. ### Add a legend[​](#add-a-legend "Direct link to Add a legend") Every architecture diagram should include a brief legend that explains the color coding, shape meanings, and line styles used. In Mermaid, add a note block at the bottom of the diagram. In Excalidraw, place the legend in the corner of the canvas. ### Version your diagrams with page history[​](#version-your-diagrams-with-page-history "Direct link to Version your diagrams with page history") One of the underappreciated benefits of embedding diagrams in Confluence is that page history tracks every change. When someone asks "when did we add the cache layer?" you can answer precisely by looking at the page history. Make it a habit to include a brief change description when you publish updates to architecture diagram pages. ### Link diagrams to architecture decision records[​](#link-diagrams-to-architecture-decision-records "Direct link to Link diagrams to architecture decision records") Create a two-way link between your architecture diagrams and the ADRs (Architecture Decision Records) that explain why the architecture looks the way it does. The diagram shows *what* the system looks like; the ADR explains *why*. Together, they give new team members the full picture. ### Schedule regular reviews[​](#schedule-regular-reviews "Direct link to Schedule regular reviews") Architecture diagrams drift from reality faster than most teams realize. Set a quarterly calendar reminder to review your key architecture diagrams against the actual system. This is especially important for teams practicing continuous deployment, where infrastructure changes can happen daily. ## Related resources[​](#related-resources "Direct link to Related resources") * [Mermaid Plus Diagrams & AI Agent for Confluence](/apps/mermaid-plus-for-confluence.md) -- full configuration guide with 30 diagram types, themes, and customizable settings * [Excalidraw Plus for Confluence](/apps/excalidraw-plus-for-confluence.md) -- visual drawing with 220+ shape libraries including AWS, Azure, and GCP icons * [Diagram Duo for Confluence](/apps/excalidraw-mermaid-diagrams-for-confluence.md) -- combined Mermaid + Excalidraw editor in one macro * [Confluence diagram tools compared](/blog/confluence-diagram-tools-comparison.md) -- side-by-side comparison of all NGPILOT diagramming apps for Confluence * [How to create flowcharts in Confluence](/blog/create-flowcharts-confluence.md) -- flowchart-specific tutorial with Mermaid and Excalidraw examples Architecture diagrams are the most referenced documents in any engineering organization. By creating and maintaining them directly in Confluence, you ensure they are always accessible, always up to date, and always connected to the documentation that gives them context. Pick the tool that matches your team's workflow -- text-based [Mermaid Plus](/apps/mermaid-plus-for-confluence.md), visual [Excalidraw Plus](/apps/excalidraw-plus-for-confluence.md), or the combined flexibility of [Diagram Duo](/apps/excalidraw-mermaid-diagrams-for-confluence.md) -- and start building architecture diagrams that your team will actually use. ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [architecture-diagram](/blog/tags/architecture-diagram.md) * [mermaid](/blog/tags/mermaid.md) * [excalidraw](/blog/tags/excalidraw.md) * [how-to](/blog/tags/how-to.md) * [diagrams](/blog/tags/diagrams.md) --- # Create UML Class Diagrams in Confluence — Free with Mermaid May 2, 2026 · 16 min read [NGPilot](https://ngpilot.com) Class diagrams are the standard way to model object-oriented systems. They show the classes in your codebase, their attributes and methods, and the relationships between them -- inheritance hierarchies, composition, aggregation, and simple associations. Whether you are documenting a domain model, onboarding new engineers onto a codebase, or collaborating on a design before writing a single line of code, a UML class diagram communicates structure faster than paragraphs of prose. If your team uses Confluence for technical documentation, embedding class diagrams directly on your pages keeps your design docs next to your architecture decisions, runbooks, and sprint planning notes. With Mermaid Plus Diagrams & AI Agent for Confluence, you can write class diagrams in plain text and render them instantly, no external drawing tool required. ## Why Create Class Diagrams in Confluence?[​](#why-create-class-diagrams-in-confluence "Direct link to Why Create Class Diagrams in Confluence?") Teams that embed diagrams inside Confluence instead of linking to external tools get several concrete benefits: **Diagrams evolve with documentation.** When your class diagram lives on the same page as the architecture decision record that explains why `PaymentService` depends on `PaymentGateway` instead of calling the gateway directly, both stay synchronized. Edit the diagram, publish the page, and everyone sees the latest version. **No stale images.** Exporting a PNG from a desktop diagramming tool and attaching it to a Confluence page guarantees that the image goes out of date the next time someone refactors a class. A Mermaid macro always renders the current code. **Text-based and version-friendly.** Mermaid class diagrams are plain text, which means they work with Confluence page history, diffs, and search. You can find every page that mentions `OrderRepository` by searching Confluence -- even if the term only appears inside a Mermaid macro. **Fast to create and iterate.** Typing `class User { +String name }` is faster than dragging boxes, aligning arrows, and resizing shapes in a visual editor. When you want to add a field or a method, you type it. When you want to change a relationship, you change one operator character. ## Step-by-Step Tutorial: Create Your First Class Diagram[​](#step-by-step-tutorial-create-your-first-class-diagram "Direct link to Step-by-Step Tutorial: Create Your First Class Diagram") Follow these five steps to go from a blank Confluence page to a fully rendered UML class diagram. ### Step 1 -- Install Mermaid Plus Diagrams & AI Agent for Confluence[​](#step-1----install-mermaid-plus-diagrams--ai-agent-for-confluence "Direct link to Step 1 -- Install Mermaid Plus Diagrams & AI Agent for Confluence") Head to the [Atlassian Marketplace](https://marketplace.atlassian.com/) and search for **Mermaid Plus Diagrams & AI Agent for Confluence**. Click **Get App** and follow the installation prompts. The app supports both Confluence Cloud and Confluence Data Center. If your organization requires admin approval for marketplace apps, send the link to your Confluence administrator. Once installed, the Mermaid Plus macro becomes available on every space in your Confluence instance. No per-space configuration required. ### Step 2 -- Insert the Mermaid Macro on a Confluence Page[​](#step-2----insert-the-mermaid-macro-on-a-confluence-page "Direct link to Step 2 -- Insert the Mermaid Macro on a Confluence Page") Open any Confluence page in edit mode. Type `/mermaid` in the editor and select **Mermaid Plus Diagrams & AI Agent for Confluence** from the dropdown. The configuration panel opens with a three-column layout: * **Left column**: Live Preview, which renders your diagram in real time as you type * **Middle column**: Quick Templates for all 30 supported diagram types * **Right column**: Settings (font, colors, theme, output size) and the Code Editor ### Step 3 -- Write the `classDiagram` Header and Define Classes[​](#step-3----write-the-classdiagram-header-and-define-classes "Direct link to step-3----write-the-classdiagram-header-and-define-classes") Start your class diagram with the `classDiagram` keyword. Then define classes using the `class` keyword followed by the class name and a block of attributes and methods in curly braces: ``` classDiagram class Animal { +String name +int age +makeSound() } ``` The `+` symbol before `name` and `age` means public visibility. You will learn more about visibility modifiers later in this guide. ### Step 4 -- Add Relationships Between Classes[​](#step-4----add-relationships-between-classes "Direct link to Step 4 -- Add Relationships Between Classes") Mermaid supports the full set of UML class relationship operators. To connect two classes, use an arrow operator between them: ``` classDiagram class Animal { +String name +makeSound() } class Dog { +String breed +fetch() } Animal <|-- Dog : inherits ``` The `<|--` operator creates an inheritance (generalization) arrow pointing from the subclass to the superclass. You will find a complete reference table for all relationship operators in the next section. ### Step 5 -- Save and Publish the Diagram[​](#step-5----save-and-publish-the-diagram "Direct link to Step 5 -- Save and Publish the Diagram") Check the live preview in the left column to verify the diagram renders correctly. Adjust the theme, colors, or output size in the right column if needed. When you are satisfied, click **Save** to insert the macro into the page, then **Publish** the Confluence page. To edit the diagram later, click on the rendered diagram in view mode and select **Edit**. All your code and settings are preserved. ## Mermaid Class Diagram Syntax Reference[​](#mermaid-class-diagram-syntax-reference "Direct link to Mermaid Class Diagram Syntax Reference") Before diving into the full examples, here is a quick-reference for the syntax elements you will use most often. ### Relationship Operators[​](#relationship-operators "Direct link to Relationship Operators") Relationships are the core of any class diagram. Mermaid supports all standard UML relationships: | Relationship | Syntax | Meaning | | ------------- | ---------------- | -------------------------------------------------- | | Inheritance | \`Parent < | -- Child\` | | Composition | `Whole *-- Part` | Part cannot exist without Whole (strong ownership) | | Aggregation | `Whole o-- Part` | Part can exist independently (weak ownership) | | Association | `A --> B` | A knows about B (navigable association) | | Bidirectional | `A -- B` | A and B know about each other | | Dependency | `A ..> B` | A depends on B (uses temporarily) | | Realization | \`Interface .. | > Class\` | You can add labels to any relationship by appending a colon and text: ``` Animal <|-- Dog : extends Order *-- LineItem : contains ``` ### Visibility Modifiers[​](#visibility-modifiers "Direct link to Visibility Modifiers") Visibility modifiers indicate the access level of class members: | Symbol | Visibility | Description | | ------ | ---------------- | ---------------------------------------------- | | `+` | Public | Accessible from any class | | `-` | Private | Accessible only within the class | | `#` | Protected | Accessible within the class and its subclasses | | `~` | Package/Internal | Accessible within the same package or module | Example: ``` classDiagram class User { +String email -String passwordHash #int failedLoginAttempts +login(password) bool -hashPassword(password) String #incrementFailedAttempts() } ``` ### Return Types and Parameter Types[​](#return-types-and-parameter-types "Direct link to Return Types and Parameter Types") Methods can specify parameter types and return types using several formats: ``` classDiagram class UserRepository { +findById(id: int) User +findAll() List~User~ +save(user: User) void +deleteById(id: int) bool } ``` ### Generics[​](#generics "Direct link to Generics") Mermaid supports generic types using the tilde `~` notation. This is useful for collections, repositories, and other parameterized types: ``` classDiagram class List~T~ { +add(item: T) void +get(index: int) T +size() int } class Map~K, V~ { +put(key: K, value: V) void +get(key: K) V +containsKey(key: K) bool } ``` When you use generics in relationship definitions, wrap the generic type in quotes to avoid parse errors: ``` List~User~ "List" ``` ### Annotations and Stereotypes[​](#annotations-and-stereotypes "Direct link to Annotations and Stereotypes") Mermaid supports class annotations (stereotypes) using the `<< >>` notation. This is commonly used to mark classes as interfaces, abstract classes, services, or enums: ``` classDiagram class Shape { <> +draw() void +area() double } class Drawable { <> +render(canvas: Canvas) void } class Color { <> RED GREEN BLUE } ``` You can also use the shorthand notation inline: ``` class Shape { <> } ``` ### Namespaces and Packages[​](#namespaces-and-packages "Direct link to Namespaces and Packages") When your class diagram grows beyond a handful of classes, namespaces help you organize related classes into logical groups. Mermaid namespaces draw a border around a group of classes and prefix their names: ``` classDiagram namespace PaymentDomain { class Payment { +BigDecimal amount +Currency currency +process() } class PaymentGateway { <> +charge(payment: Payment) Result +refund(payment: Payment) Result } } namespace UserDomain { class Account { +String accountId +getBalance() BigDecimal } } Account --> Payment : initiates ``` Namespaces are especially useful when you are modeling a domain-driven design with bounded contexts, or when you want to show how classes from different modules or packages relate to each other. ### Class Members Without Body[​](#class-members-without-body "Direct link to Class Members Without Body") For quick diagrams where you only need to show relationships, you can define class members inline without using a body block: ``` classDiagram Animal : +String name Animal : +makeSound() Dog : +String breed Animal <|-- Dog ``` This is equivalent to defining the class with a body block, but it keeps the code more compact for simple diagrams. ## 3 Copy-Paste Class Diagram Examples[​](#3-copy-paste-class-diagram-examples "Direct link to 3 Copy-Paste Class Diagram Examples") Below are three practical examples you can paste directly into the Mermaid Plus macro in Confluence. Each example demonstrates progressively more advanced Mermaid class diagram features. ### Example 1 -- Basic Class Diagram: Vehicle Hierarchy[​](#example-1----basic-class-diagram-vehicle-hierarchy "Direct link to Example 1 -- Basic Class Diagram: Vehicle Hierarchy") This example shows a simple inheritance hierarchy with abstract classes and concrete implementations. It is a good starting point for documenting any class hierarchy in your codebase. ``` classDiagram class Vehicle { <> +String make +String model +int year +startEngine() +stopEngine() +getInfo() String } class Car { +int numDoors +String trunkSize +openTrunk() +closeTrunk() } class Motorcycle { +String handlebarType +bool hasSidecar +popWheelie() } class Truck { +double payloadCapacity +int numAxles +loadCargo(weight: double) +unloadCargo() } class Engine { -int horsepower -String fuelType +ignite() +shutdown() } Vehicle <|-- Car : extends Vehicle <|-- Motorcycle : extends Vehicle <|-- Truck : extends Vehicle *-- Engine : has ``` This diagram covers three key concepts: 1. **Abstract classes** -- `Vehicle` is marked with `<>` and defines the common interface for all vehicle types 2. **Inheritance** -- `Car`, `Motorcycle`, and `Truck` all extend `Vehicle` using the `<|--` operator 3. **Composition** -- `Vehicle` has a composed `Engine` using the `*--` operator, meaning the engine cannot exist without the vehicle ### Example 2 -- Observer Design Pattern[​](#example-2----observer-design-pattern "Direct link to Example 2 -- Observer Design Pattern") Design patterns are one of the most common reasons teams create class diagrams. The Observer pattern is used everywhere: event systems, message queues, UI frameworks, and reactive programming. This diagram shows the full pattern with interfaces, concrete implementations, and the relationship between subject and observers. ``` classDiagram class Subject { <> +attach(observer: Observer) void +detach(observer: Observer) void +notifyObservers() void } class Observer { <> +update(data: any) void } class ConcreteSubject { -List~Observer~ observers -any state +attach(observer: Observer) void +detach(observer: Observer) void +notifyObservers() void +getState() any +setState(newState: any) void } class ConcreteObserverA { -any observedState +update(data: any) void +display() void } class ConcreteObserverB { -any observedState +update(data: any) void +log() void } class EventManager { -Map~String, List~Observer~~ listeners +subscribe(eventType: String, observer: Observer) void +unsubscribe(eventType: String, observer: Observer) void +notify(eventType: String, data: any) void } Subject <|.. ConcreteSubject : implements Observer <|.. ConcreteObserverA : implements Observer <|.. ConcreteObserverB : implements ConcreteSubject --> Observer : notifies EventManager --> Observer : manages Subject <|-- EventManager : extends ``` This diagram introduces several advanced features: 1. **Interface realization** -- `ConcreteSubject` implements `Subject` using the `..<|` operator (dashed line with open triangle) 2. **Generic collections** -- `List~Observer~` and `Map~String, List~Observer~~` show nested generics 3. **Dependencies and associations** -- `ConcreteSubject --> Observer` shows a navigable association (the subject holds references to observers) 4. **Multiple relationship types** -- Inheritance, realization, and association all appear in the same diagram Use this diagram as a template when documenting any event-driven or publish-subscribe architecture in your system. ### Example 3 -- Real-World Domain Model: E-Commerce System[​](#example-3----real-world-domain-model-e-commerce-system "Direct link to Example 3 -- Real-World Domain Model: E-Commerce System") This example models a realistic e-commerce domain with customers, orders, products, payments, and shipping. It demonstrates how to use namespaces, composition, aggregation, and cardinality labels in a single, comprehensive diagram. This is the kind of diagram you would include in a technical design document or architecture decision record. ``` classDiagram namespace Customers { class Customer { +String customerId +String email +String firstName +String lastName +placeOrder(items: List~Product~) Order +getOrderHistory() List~Order~ +updateProfile(data: Map~String, String~) void } class Address { +String street +String city +String state +String zipCode +String country +getFullAddress() String } class LoyaltyAccount { +int points +String tier +earnPoints(amount: double) void +redeemPoints(points: int) void } } namespace Orders { class Order { +String orderId +Date createdAt +String status +BigDecimal totalAmount +addItem(item: LineItem) void +removeItem(itemId: String) void +calculateTotal() BigDecimal +cancel() void } class LineItem { +String lineItemId +int quantity +BigDecimal unitPrice +getSubtotal() BigDecimal } class OrderStatus { <> PENDING CONFIRMED PROCESSING SHIPPED DELIVERED CANCELLED } } namespace Products { class Product { +String productId +String name +String description +BigDecimal price +int stockQuantity +isInStock() bool +reduceStock(qty: int) void } class Category { +String categoryId +String name +String description +getProducts() List~Product~ } class ProductVariant { +String variantId +String color +String size +BigDecimal priceAdjustment } } namespace Payments { class Payment { +String paymentId +BigDecimal amount +String method +String status +process() bool +refund() bool } class PaymentGateway { <> +charge(payment: Payment) Result +refund(paymentId: String) Result +verify(paymentId: String) Result } class StripeGateway { -String apiKey +charge(payment: Payment) Result +refund(paymentId: String) Result +verify(paymentId: String) Result } class PayPalGateway { -String clientId -String clientSecret +charge(payment: Payment) Result +refund(paymentId: String) Result +verify(paymentId: String) Result } } namespace Shipping { class Shipment { +String trackingNumber +String carrier +Date estimatedDelivery +String status +track() ShipmentStatus } } Customer "1" --> "*" Order : places Customer "1" --> "*" Address : has Customer "1" o-- "0..1" LoyaltyAccount : optionally has Order "1" *-- "*" LineItem : contains Order "1" --> "0..1" Payment : paid by Order "1" --> "0..1" Shipment : shipped via Order --> OrderStatus : has status LineItem "*" --> "1" Product : references Product "*" o-- "*" Category : categorized in Product "1" o-- "*" ProductVariant : has variants PaymentGateway <|.. StripeGateway : implements PaymentGateway <|.. PayPalGateway : implements Payment ..> PaymentGateway : processed through ``` This diagram demonstrates every major Mermaid class diagram feature: 1. **Namespaces** -- Five namespaces (`Customers`, `Orders`, `Products`, `Payments`, `Shipping`) group related classes into bounded contexts 2. **Cardinality labels** -- `"1"`, `"*"`, `"0..1"`, `"1..*"` labels on relationship lines show multiplicity 3. **Composition vs aggregation** -- `Order *-- LineItem` (composition, items cannot exist without the order) vs `Customer o-- LoyaltyAccount` (aggregation, account exists independently) 4. **Enumeration classes** -- `OrderStatus` is marked with `<>` and lists its values 5. **Interface realization** -- `StripeGateway` and `PayPalGateway` implement `PaymentGateway` 6. **Dependencies** -- `Payment ..> PaymentGateway` shows a transient dependency 7. **Generics** -- `List~Product~`, `Map~String, String~`, and other parameterized types throughout This is the level of detail you would use for a technical design document, a system architecture page, or an onboarding guide for new engineers joining the team. ## Tips for Building Effective Class Diagrams[​](#tips-for-building-effective-class-diagrams "Direct link to Tips for Building Effective Class Diagrams") ### Start Simple, Then Add Detail[​](#start-simple-then-add-detail "Direct link to Start Simple, Then Add Detail") Begin with class names and relationships only. Get the structure right first, then fill in attributes and methods. This two-pass approach prevents you from getting bogged down in details before the overall shape of the diagram is correct. ### Use Namespaces to Manage Complexity[​](#use-namespaces-to-manage-complexity "Direct link to Use Namespaces to Manage Complexity") Any diagram with more than six or seven classes benefits from namespaces. Group classes by module, package, or bounded context. This makes the diagram easier to read and mirrors how your code is actually organized. ### Be Consistent with Visibility[​](#be-consistent-with-visibility "Direct link to Be Consistent with Visibility") Pick a convention and stick to it. If you show public members with `+` in one class, show them in every class. Mixing conventions within a single diagram creates confusion about what is and is not accessible. ### Label Relationships[​](#label-relationships "Direct link to Label Relationships") Add labels to your relationship arrows, especially when the relationship is not immediately obvious from the class names alone. `Order "1" *-- "*" LineItem : contains` is clearer than `Order *-- LineItem`. ### Choose Composition Over Aggregation Deliberately[​](#choose-composition-over-aggregation-deliberately "Direct link to Choose Composition Over Aggregation Deliberately") Composition (`*--`) means the child cannot exist without the parent. Aggregation (`o--`) means it can. This distinction matters in your code: if deleting an `Order` should also delete its `LineItem` records, use composition. If deleting a `Customer` should not delete their `Address` (because the address might be shared), use aggregation. ### Keep Diagrams Focused[​](#keep-diagrams-focused "Direct link to Keep Diagrams Focused") A single class diagram does not need to show every class in your system. Focus on one subsystem or one bounded context per diagram. If you find yourself adding a fourth or fifth namespace, consider splitting the diagram into two pages and linking between them. ### Use Themes for Visual Consistency[​](#use-themes-for-visual-consistency "Direct link to Use Themes for Visual Consistency") Mermaid Plus Diagrams & AI Agent for Confluence offers four built-in themes: Default, Dark, Forest, and Neutral. Pick one theme for all class diagrams in a space and stick with it. Consistent visual style across pages makes your documentation feel polished and professional. The Default theme lets you customize node, text, border, line, and background colors to match your company brand. For detailed configuration options including font families, color pickers, and output sizes, refer to the [Mermaid Plus Diagrams & AI Agent for Confluence usage guide](/docs/Mermaid-Plus-for-Confluence/usage.md). ## Common Mistakes and How to Fix Them[​](#common-mistakes-and-how-to-fix-them "Direct link to Common Mistakes and How to Fix Them") **Missing class keyword.** Every class definition must start with `class`. Writing `User { +String name }` without the `class` keyword produces a parse error. The correct form is `class User { +String name }`. **Wrong arrow direction.** Inheritance arrows point from child to parent: `Parent <|-- Child`, not `Child --> Parent`. The open triangle always points at the superclass or interface. If your inheritance arrows look reversed, swap the sides of the operator. **Unquoted generics in relationships.** When using generic types in relationship lines, wrap the full type in quotes: `"List~User~"`. Without quotes, Mermaid may misparse the tilde characters. **Omitting return types.** While return types are optional in Mermaid, including them makes the diagram more useful as documentation. `+findById(id: int) User` is more informative than `+findById(id)`. **Overcrowding.** A class diagram with 15 classes and 30 relationships becomes unreadable. If your diagram has grown too large, split it by namespace, module, or feature area. Two focused diagrams are always better than one overwhelming diagram. **Forgetting to close body blocks.** Every `{` must have a matching `}`. If your diagram fails to render, check that every class body is properly closed. The live preview in Mermaid Plus will show you parse errors in real time, which makes this easy to catch. ## When to Use Class Diagrams vs Other Diagram Types[​](#when-to-use-class-diagrams-vs-other-diagram-types "Direct link to When to Use Class Diagrams vs Other Diagram Types") Class diagrams are not the right tool for every situation. Here is a quick guide to help you choose: * **Class diagram** -- Use when documenting static structure: class hierarchies, domain models, database entity relationships, and API contracts * **Sequence diagram** -- Use when documenting dynamic behavior: message flows between services, API request/response chains, and authentication flows. See [how to create sequence diagrams in Confluence](/blog/how-to-create-sequence-diagrams-confluence.md) * **Flowchart** -- Use when documenting processes: decision trees, approval workflows, and algorithmic logic. See [how to create flowcharts in Confluence](/blog/create-flowcharts-confluence.md) * **ER diagram** -- Use when documenting database schemas directly, without the object-oriented baggage of methods and visibility modifiers Many technical design documents benefit from combining multiple diagram types on the same Confluence page. A class diagram shows the structure, a sequence diagram shows how the classes interact at runtime, and a flowchart shows the business process that triggers the whole flow. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [All 30 Mermaid diagram types in Confluence](/blog/faq-mermaid-diagram-types-confluence.md) -- complete reference across every diagram type * [Mermaid Plus Diagrams & AI Agent for Confluence usage guide](/apps/mermaid-plus-for-confluence.md) -- configuration panel walkthrough, theme settings, font and color customization, and all 30 supported diagram types * [How to create sequence diagrams in Confluence](/blog/how-to-create-sequence-diagrams-confluence.md) -- document message flows between services with copy-paste Mermaid examples * [Mermaid syntax cheat sheet for Confluence](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md) -- quick reference for flowcharts, sequence diagrams, ER diagrams, and more * [How to create flowcharts in Confluence](/blog/create-flowcharts-confluence.md) -- process diagrams, decision trees, and workflow documentation with Mermaid Class diagrams are one of the most valuable tools in a software team's documentation arsenal. They capture the static structure of your system in a way that prose alone cannot. With Mermaid Plus Diagrams & AI Agent for Confluence, creating and maintaining class diagrams is as simple as writing text. Install the app, paste one of the examples above into a Confluence page, and start documenting your system's architecture where it belongs -- alongside everything else your team needs. ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [class-diagram](/blog/tags/class-diagram.md) * [uml](/blog/tags/uml.md) * [how-to](/blog/tags/how-to.md) * [diagrams](/blog/tags/diagrams.md) --- # ER Diagrams in Confluence: How to Add, Create, and Render Database Schemas May 2, 2026 · 21 min read [NGPilot](https://ngpilot.com) An **ER diagram** (entity-relationship diagram) visualizes a database schema — the tables, columns, primary and foreign keys, and the relationships between them. If your team documents data models, API contracts, or system architecture in Confluence, embedding ER diagrams directly on the page keeps the schema next to the prose instead of stranded in an external tool as a stale screenshot. Confluence has no built-in ER diagram support, so you add it with a Marketplace app. The approach below uses **[Mermaid Plus Diagrams & AI Agent for Confluence](/apps/mermaid-plus-for-confluence.md)**, which renders ER diagrams from plain text — meaning diagrams version, diff, and search alongside the rest of your documentation. What you'll learn 1. How to add an ER diagram to any Confluence page 2. The full Mermaid `erDiagram` syntax — entities, attributes, key types, cardinality 3. Three copy-paste examples (library, e-commerce, SaaS multi-tenant) 4. Common mistakes and how to fix them Entity-Relationship (ER) diagrams are the standard way to visualize database schemas. They show the tables in your database, the columns in each table, primary and foreign key constraints, and the relationships between tables -- one-to-one, one-to-many, and many-to-many. Whether you are designing a new database from scratch, documenting an existing schema for onboarding, or collaborating on a data model before writing migration scripts, an ER diagram communicates structure faster than any amount of prose. If your team uses Confluence for technical documentation, embedding ER diagrams directly on your pages keeps your data model documentation next to your architecture decision records, API specs, and sprint planning notes. With Mermaid Plus Diagrams & AI Agent for Confluence, you can write ER diagrams in plain text using the `erDiagram` syntax and render them instantly -- no external drawing tool, no exported PNGs, no stale images. This guide walks you through the full Mermaid `erDiagram` syntax, explains every relationship type and key constraint, and provides three copy-paste examples you can drop straight into a Confluence page. ## Why Create ER Diagrams in Confluence?[​](#why-create-er-diagrams-in-confluence "Direct link to Why Create ER Diagrams in Confluence?") Teams that embed database diagrams inside Confluence instead of linking to external tools see several concrete benefits: **Diagrams stay synchronized with documentation.** When your ER diagram lives on the same page as the data dictionary, migration plan, and API contract, all of these artifacts evolve together. Edit the diagram, publish the page, and every stakeholder sees the latest schema. **No stale images.** Exporting a PNG from a database design tool and attaching it to Confluence guarantees that the image drifts out of date the next time someone runs a migration. A Mermaid macro always renders the current code. If someone changes the schema, they change the Mermaid source on the page. **Text-based and searchable.** Mermaid ER diagrams are plain text, which means they integrate with Confluence page history, diffs, and full-text search. You can find every page that references the `orders` table by searching Confluence -- even if the table name only appears inside a Mermaid macro. **Fast to create and iterate.** Typing `CUSTOMER ||--o{ ORDER : places` is faster than dragging table shapes, drawing relationship lines, and adjusting layout in a visual editor. When you want to add a column, you type it. When you want to change a cardinality, you change one character. ## Step-by-Step Tutorial: Create Your First ER Diagram[​](#step-by-step-tutorial-create-your-first-er-diagram "Direct link to Step-by-Step Tutorial: Create Your First ER Diagram") Follow these five steps to go from a blank Confluence page to a fully rendered database schema diagram. ### Step 1 -- Install Mermaid Plus Diagrams & AI Agent for Confluence[​](#step-1----install-mermaid-plus-diagrams--ai-agent-for-confluence "Direct link to Step 1 -- Install Mermaid Plus Diagrams & AI Agent for Confluence") Head to the [Atlassian Marketplace](https://marketplace.atlassian.com/) and search for **Mermaid Plus Diagrams & AI Agent for Confluence**. Click **Get App** and follow the installation prompts. The app supports both Confluence Cloud and Confluence Data Center. If your organization requires admin approval for marketplace apps, send the link to your Confluence administrator. Once installed, the Mermaid Plus macro becomes available on every space in your Confluence instance. No per-space configuration required. ### Step 2 -- Insert the Mermaid Macro on a Confluence Page[​](#step-2----insert-the-mermaid-macro-on-a-confluence-page "Direct link to Step 2 -- Insert the Mermaid Macro on a Confluence Page") Open any Confluence page in edit mode. Type `/mermaid` in the editor and select **Mermaid Plus Diagrams & AI Agent for Confluence** from the dropdown. The configuration panel opens with a three-column layout: * **Left column**: Live Preview, which renders your diagram in real time as you type * **Middle column**: Quick Templates for all 30 supported diagram types, including ER diagrams * **Right column**: Settings (font, colors, theme, output size) and the Code Editor You can also click the **ER Diagram** template in the Quick Templates column to load a starter example into the editor. ### Step 3 -- Write the `erDiagram` Header and Define Entities[​](#step-3----write-the-erdiagram-header-and-define-entities "Direct link to step-3----write-the-erdiagram-header-and-define-entities") Start your ER diagram with the `erDiagram` keyword. Then define entities and their attributes. Each attribute can have a key type and a comment: ``` erDiagram CUSTOMER { int id PK string email UK string name date created_at } ``` The key types are `PK` (primary key), `FK` (foreign key), and `UK` (unique key). You will learn more about key types later in this guide. ### Step 4 -- Add Relationships Between Entities[​](#step-4----add-relationships-between-entities "Direct link to Step 4 -- Add Relationships Between Entities") Mermaid supports the full set of ER cardinality operators. To connect two entities, use a relationship line between them: ``` erDiagram CUSTOMER ||--o{ ORDER : places ``` The `||--o{` operator creates a one-to-many relationship: one customer places zero or more orders. You will find a complete reference table for all cardinality operators in the next section. ### Step 5 -- Save and Publish the Diagram[​](#step-5----save-and-publish-the-diagram "Direct link to Step 5 -- Save and Publish the Diagram") Check the live preview in the left column to verify the diagram renders correctly. Adjust the theme, colors, or output size in the right column if needed. When you are satisfied, click **Save** to insert the macro into the page, then **Publish** the Confluence page. To edit the diagram later, click on the rendered diagram in view mode and select **Edit**. All your code and settings are preserved. For a complete walkthrough of the configuration panel, themes, font families, color customization, and all 30 supported diagram types, see the [Mermaid Plus Diagrams & AI Agent for Confluence usage guide](/docs/Mermaid-Plus-for-Confluence/usage.md). ## Mermaid ER Diagram Syntax Reference[​](#mermaid-er-diagram-syntax-reference "Direct link to Mermaid ER Diagram Syntax Reference") Before diving into the full examples, here is a quick-reference for the syntax elements you will use most often. ### Entity Definitions[​](#entity-definitions "Direct link to Entity Definitions") An entity represents a table in your database. Define an entity by writing its name in uppercase (by convention) followed by a block of attributes in curly braces: ``` erDiagram PRODUCT { int id PK string name string description decimal price int stock_quantity int category_id FK } ``` Each attribute line follows this format: ``` type name [key_type] ["comment"] ``` * **type**: The data type (e.g., `int`, `string`, `decimal`, `date`, `boolean`, `uuid`, `text`, `timestamp`) * **name**: The column name * **key\_type** (optional): `PK` for primary key, `FK` for foreign key, `UK` for unique key * **comment** (optional): A quoted description of the column ### Key Types[​](#key-types "Direct link to Key Types") Key types mark special constraints on columns. Mermaid renders them with distinct visual indicators: | Key Type | Syntax | Description | | ----------- | ----------------- | ------------------------------------------------------ | | Primary Key | `int id PK` | Uniquely identifies each row. Only one per entity. | | Foreign Key | `int user_id FK` | References a primary key in another entity. | | Unique Key | `string email UK` | Enforces uniqueness but is not the primary identifier. | You can combine key types on the same column in some database designs, but Mermaid assigns one visual indicator per attribute line. For composite keys, mark each participating column separately. Example with all three key types: ``` erDiagram USER { int id PK string email UK string username UK string password_hash int organization_id FK timestamp created_at } ``` ### Relationship Cardinality[​](#relationship-cardinality "Direct link to Relationship Cardinality") Relationships are the core of any ER diagram. Mermaid uses a specific notation to express cardinality between two entities. The syntax consists of three parts: the left cardinality, the relationship line, and the right cardinality. #### Cardinality Symbols[​](#cardinality-symbols "Direct link to Cardinality Symbols") | Symbol | Meaning | | ------ | ------------------------------------ | | \` | | | \` | o\` | | \`} | \` | | `o{` | Zero or more (optional, may be none) | #### Common Relationship Patterns[​](#common-relationship-patterns "Direct link to Common Relationship Patterns") | Relationship | Syntax | Meaning | | ----------------------- | ------------ | ------------------------------------------------------ | | One-to-one (mandatory) | `\|\|--\|\|` | Each A has exactly one B, and each B has exactly one A | | One-to-one (optional) | `\|\|--o\|` | Each A has zero or one B | | One-to-many | `\|\|--o{` | One A has zero or more B's | | One-to-many (mandatory) | `\|\|--\|{` | One A has one or more B's | | Many-to-one | `}o--\|\|` | Many A's relate to one B | | Many-to-many | `}o--o{` | Many A's relate to many B's | You can add a label to any relationship by appending a colon and text after the second entity: ``` CUSTOMER ||--o{ ORDER : places PRODUCT ||--o{ ORDER_ITEM : "included in" ``` #### Full Cardinality Reference[​](#full-cardinality-reference "Direct link to Full Cardinality Reference") Here is every possible combination. The first character pair describes the left entity's cardinality, and the last pair describes the right entity's cardinality: | Left | Line | Right | Example | | ------ | ---- | ------ | ---------------------------- | | `\|\|` | `--` | `\|\|` | One to one (both mandatory) | | `\|\|` | `--` | `o\|` | One to zero-or-one | | `\|\|` | `--` | `\|{` | One to one-or-many | | `\|\|` | `--` | `o{` | One to zero-or-many | | `o\|` | `--` | `\|\|` | Zero-or-one to one | | `o\|` | `--` | `o\|` | Zero-or-one to zero-or-one | | `o\|` | `--` | `\|{` | Zero-or-one to one-or-many | | `o\|` | `--` | `o{` | Zero-or-one to zero-or-many | | `\|{` | `--` | `\|\|` | One-or-many to one | | `\|{` | `--` | `o\|` | One-or-many to zero-or-one | | `\|{` | `--` | `\|{` | One-or-many to one-or-many | | `\|{` | `--` | `o{` | One-or-many to zero-or-many | | `o{` | `--` | `\|\|` | Zero-or-many to one | | `o{` | `--` | `o\|` | Zero-or-many to zero-or-one | | `o{` | `--` | `\|{` | Zero-or-many to one-or-many | | `o{` | `--` | `o{` | Zero-or-many to zero-or-many | In practice, you will use `||--o{` (one-to-many) and `||--||` (one-to-one) most frequently. Many-to-many relationships (`}o--o{`) are typically resolved into a junction table in a normalized database schema. ### Attribute Data Types[​](#attribute-data-types "Direct link to Attribute Data Types") Mermaid supports a wide range of data types for ER diagram attributes. While these are not enforced by the diagram itself, they serve as documentation for your team: | Type | Usage | | ----------- | ----------------------------------------- | | `int` | Integer numbers | | `bigint` | Large integers | | `float` | Floating-point numbers | | `decimal` | Fixed-precision numbers (prices, amounts) | | `boolean` | True/false values | | `string` | Short text (VARCHAR) | | `text` | Long text (TEXT, CLOB) | | `date` | Date without time | | `timestamp` | Date and time | | `uuid` | Universally unique identifier | | `json` | JSON data | | `blob` | Binary data | ### Entity Name Conventions[​](#entity-name-conventions "Direct link to Entity Name Conventions") Mermaid ER diagrams use uppercase entity names by convention (e.g., `CUSTOMER`, `ORDER`, `LINE_ITEM`). This distinguishes entities from attributes and relationship labels. Use underscores for multi-word entity names since Mermaid does not support spaces in entity names: ``` LINE_ITEM ORDER_STATUS USER_SESSION ``` Relationship labels use lowercase with spaces, written after a colon: ``` CUSTOMER ||--o{ ORDER : places ``` ## 3 Copy-Paste ER Diagram Examples[​](#3-copy-paste-er-diagram-examples "Direct link to 3 Copy-Paste ER Diagram Examples") Below are three practical examples you can paste directly into the Mermaid Plus macro in Confluence. Each example demonstrates progressively more advanced Mermaid ER diagram features. ### Example 1 -- Basic ER Diagram: Library Management System[​](#example-1----basic-er-diagram-library-management-system "Direct link to Example 1 -- Basic ER Diagram: Library Management System") This example shows a simple library system with books, authors, members, and loans. It covers all three relationship types: one-to-one, one-to-many, and many-to-many. This is a good starting point for documenting any straightforward database schema. ``` erDiagram AUTHOR { int id PK string name string nationality date birth_date } BOOK { int id PK string title string isbn UK int publication_year int author_id FK int genre_id FK } GENRE { int id PK string name UK string description } MEMBER { int id PK string email UK string first_name string last_name string phone date membership_date } LOAN { int id PK int book_id FK int member_id FK date checkout_date date due_date date return_date } AUTHOR ||--o{ BOOK : writes GENRE ||--o{ BOOK : categorizes MEMBER ||--o{ LOAN : borrows BOOK ||--o{ LOAN : "is borrowed" ``` This diagram covers three key concepts: 1. **One-to-many relationships** -- Each author writes zero or more books (`AUTHOR ||--o{ BOOK`), each genre categorizes zero or more books, and each member has zero or more loans 2. **Primary and foreign keys** -- Every entity has a `PK` column, and relationship tables like `LOAN` have `FK` columns referencing `BOOK` and `MEMBER` 3. **Unique constraints** -- `isbn` on `BOOK` and `email` on `MEMBER` are marked `UK` to indicate uniqueness ### Example 2 -- E-Commerce Database Schema[​](#example-2----e-commerce-database-schema "Direct link to Example 2 -- E-Commerce Database Schema") This example models a realistic e-commerce database with customers, products, orders, payments, and shipping. It demonstrates how to handle many-to-many relationships through junction tables, composite foreign keys, and a variety of cardinality patterns. This is the kind of diagram you would include in a technical design document or database migration plan. ``` erDiagram CUSTOMER { int id PK string email UK string password_hash string first_name string last_name string phone timestamp created_at } ADDRESS { int id PK int customer_id FK string street_line_1 string street_line_2 string city string state string postal_code string country boolean is_default } PRODUCT { int id PK string name string description decimal price int stock_quantity string sku UK int category_id FK timestamp created_at timestamp updated_at } CATEGORY { int id PK string name UK string slug UK int parent_category_id FK string description } PRODUCT_TAG { int id PK string name UK } PRODUCT_TAG_MAP { int product_id FK int tag_id FK } ORDER { int id PK int customer_id FK string status decimal subtotal decimal tax_amount decimal shipping_cost decimal total_amount string shipping_address_snapshot timestamp created_at timestamp updated_at } ORDER_ITEM { int id PK int order_id FK int product_id FK int quantity decimal unit_price decimal line_total } PAYMENT { int id PK int order_id FK string payment_method string transaction_id UK decimal amount string status timestamp paid_at } SHIPMENT { int id PK int order_id FK string carrier string tracking_number UK string status timestamp shipped_at timestamp estimated_delivery timestamp delivered_at } REVIEW { int id PK int product_id FK int customer_id FK int rating string title string body timestamp created_at } WISHLIST { int id PK int customer_id FK int product_id FK timestamp added_at } CUSTOMER ||--o{ ADDRESS : has CUSTOMER ||--o{ ORDER : places CUSTOMER ||--o{ REVIEW : writes CUSTOMER ||--o{ WISHLIST : "adds to" CATEGORY ||--o{ CATEGORY : "sub-category of" CATEGORY ||--o{ PRODUCT : contains PRODUCT ||--o{ ORDER_ITEM : "included in" PRODUCT ||--o{ REVIEW : "receives" PRODUCT ||--o{ PRODUCT_TAG_MAP : tagged PRODUCT_TAG ||--o{ PRODUCT_TAG_MAP : applied ORDER ||--|{ ORDER_ITEM : contains ORDER ||--o| PAYMENT : "paid by" ORDER ||--o| SHIPMENT : "shipped via" ``` This diagram introduces several advanced features: 1. **Self-referencing relationship** -- `CATEGORY ||--o{ CATEGORY` models a hierarchical category tree where a category can have sub-categories 2. **Many-to-many via junction table** -- `PRODUCT_TAG_MAP` resolves the many-to-many relationship between `PRODUCT` and `PRODUCT_TAG` 3. **Mandatory one-to-many** -- `ORDER ||--|{ ORDER_ITEM` uses `|{` to indicate that every order must have at least one item 4. **Optional one-to-one** -- `ORDER ||--o| PAYMENT` uses `o|` to indicate that an order may or may not have a payment record (e.g., pending orders) 5. **Unique constraints on transactional data** -- `transaction_id` on `PAYMENT` and `tracking_number` on `SHIPMENT` are marked `UK` 6. **Snapshot fields** -- `shipping_address_snapshot` on `ORDER` demonstrates denormalization for audit purposes ### Example 3 -- SaaS Multi-Tenant Database Schema[​](#example-3----saas-multi-tenant-database-schema "Direct link to Example 3 -- SaaS Multi-Tenant Database Schema") This example models a multi-tenant SaaS application with organizations, users, roles, permissions, projects, and audit logs. It is the most complex of the three examples and demonstrates how to model row-level security patterns, polymorphic associations, and tenant isolation in a database schema. Use this diagram as a starting point when designing any B2B SaaS data model. ``` erDiagram ORGANIZATION { int id PK string name string slug UK string plan int max_users boolean is_active timestamp trial_ends_at timestamp created_at } USER { int id PK int organization_id FK string email UK string password_hash string first_name string last_name string avatar_url boolean is_active timestamp last_login_at timestamp created_at } ROLE { int id PK int organization_id FK string name string description boolean is_system } PERMISSION { int id PK string name UK string resource string action string description } USER_ROLE { int user_id FK int role_id FK timestamp assigned_at } ROLE_PERMISSION { int role_id FK int permission_id FK } PROJECT { int id PK int organization_id FK string name string key UK string description string status int owner_id FK timestamp created_at timestamp updated_at } PROJECT_MEMBER { int id PK int project_id FK int user_id FK string role timestamp joined_at } TASK { int id PK int project_id FK int assignee_id FK int reporter_id FK string title string description string status string priority string task_type int parent_task_id FK timestamp due_date timestamp created_at timestamp updated_at } TASK_COMMENT { int id PK int task_id FK int author_id FK text body timestamp created_at timestamp updated_at } TASK_ATTACHMENT { int id PK int task_id FK int uploaded_by FK string file_name string file_url int file_size string mime_type timestamp uploaded_at } AUDIT_LOG { int id PK int organization_id FK int actor_id FK string action string resource_type int resource_id json changes string ip_address timestamp performed_at } API_KEY { int id PK int organization_id FK int created_by FK string name string key_hash UK string prefix string[] scopes timestamp expires_at timestamp created_at } ORGANIZATION ||--|{ USER : employs ORGANIZATION ||--o{ ROLE : defines ORGANIZATION ||--o{ PROJECT : owns ORGANIZATION ||--o{ AUDIT_LOG : "logs for" ORGANIZATION ||--o{ API_KEY : "issues" USER ||--o{ USER_ROLE : has ROLE ||--o{ USER_ROLE : assigned ROLE ||--o{ ROLE_PERMISSION : grants PERMISSION ||--o{ ROLE_PERMISSION : "included in" PROJECT ||--o{ PROJECT_MEMBER : "has members" USER ||--o{ PROJECT_MEMBER : "joins" PROJECT ||--|{ TASK : contains USER ||--o{ TASK : assigned USER ||--o{ TASK : reported TASK ||--o{ TASK : "sub-task of" TASK ||--o{ TASK_COMMENT : has TASK ||--o{ TASK_ATTACHMENT : has USER ||--o{ TASK_COMMENT : authors USER ||--o{ TASK_ATTACHMENT : uploads USER ||--o{ AUDIT_LOG : performs USER ||--o{ API_KEY : creates ``` This diagram demonstrates every major Mermaid ER diagram feature in a production-ready context: 1. **Multi-tenant isolation** -- Every top-level entity has an `organization_id FK` column, enforcing tenant boundaries at the data layer 2. **Role-based access control (RBAC)** -- The `USER_ROLE`, `ROLE`, `ROLE_PERMISSION`, and `PERMISSION` entities form a complete RBAC model with many-to-many relationships resolved through junction tables 3. **Self-referencing hierarchy** -- `TASK ||--o{ TASK` allows tasks to have sub-tasks, modeling an unlimited nesting depth 4. **Multiple foreign keys to the same table** -- `TASK` has both `assignee_id FK` and `reporter_id FK` pointing to `USER`, with corresponding relationship lines 5. **Polymorphic audit trail** -- `AUDIT_LOG` uses `resource_type` and `resource_id` to track changes across any entity type, with a `json` column for change details 6. **API key management** -- `API_KEY` stores hashed keys with scope arrays and expiration, scoped to organizations 7. **Mandatory vs optional cardinality** -- `ORGANIZATION ||--|{ USER` (every org has at least one user) vs `ORGANIZATION ||--o{ API_KEY` (API keys are optional) ## Tips for Building Effective ER Diagrams[​](#tips-for-building-effective-er-diagrams "Direct link to Tips for Building Effective ER Diagrams") ### Normalize Before Diagramming[​](#normalize-before-diagramming "Direct link to Normalize Before Diagramming") Before writing a single line of Mermaid, make sure your schema follows at least third normal form (3NF). Each entity should represent one concept, each attribute should depend on the whole primary key, and there should be no transitive dependencies. ER diagrams are most useful when the underlying model is clean. ### Start with Entities, Then Add Relationships[​](#start-with-entities-then-add-relationships "Direct link to Start with Entities, Then Add Relationships") Begin by listing all your entities and their attributes. Get the column names and key types right first. Then add relationship lines between entities. This two-pass approach prevents you from getting lost in cardinality notation before the entities themselves are well-defined. ### Use Junction Tables for Many-to-Many[​](#use-junction-tables-for-many-to-many "Direct link to Use Junction Tables for Many-to-Many") Many-to-many relationships (`}o--o{`) are valid in Mermaid syntax, but in a relational database you always resolve them through a junction table. Instead of drawing a direct many-to-many line, create an intermediate entity with two foreign keys: ``` -- Instead of this: PRODUCT }o--o{ TAG : "tagged with" -- Do this: PRODUCT ||--o{ PRODUCT_TAG_MAP : tagged TAG ||--o{ PRODUCT_TAG_MAP : applied ``` This matches how the database actually implements the relationship and makes the diagram more useful as a reference for writing SQL. ### Label Every Relationship[​](#label-every-relationship "Direct link to Label Every Relationship") Add descriptive labels to your relationship lines. `CUSTOMER ||--o{ ORDER : places` is clearer than `CUSTOMER ||--o{ ORDER`. The label tells the reader what the relationship means in business terms, not just that a foreign key exists. ### Keep Diagrams Focused[​](#keep-diagrams-focused "Direct link to Keep Diagrams Focused") A single ER diagram does not need to show every table in your database. Focus on one subsystem or one feature area per diagram. If you find yourself adding more than 12-15 entities, consider splitting the diagram into multiple pages and linking between them. Two focused diagrams are always better than one overwhelming diagram. ### Be Consistent with Naming Conventions[​](#be-consistent-with-naming-conventions "Direct link to Be Consistent with Naming Conventions") Pick a naming convention and stick to it throughout the diagram. Common conventions include: * **Entity names**: UPPER\_SNAKE\_CASE (e.g., `ORDER_ITEM`, `USER_SESSION`) * **Attribute names**: snake\_case (e.g., `created_at`, `user_id`) * **Primary keys**: Always named `id` or `{entity_name}_id` * **Foreign keys**: Always named `{referenced_entity}_id` (e.g., `customer_id`, `order_id`) Consistent naming makes the diagram self-documenting and reduces the cognitive load on readers. ### Use Themes for Visual Consistency[​](#use-themes-for-visual-consistency "Direct link to Use Themes for Visual Consistency") Mermaid Plus Diagrams & AI Agent for Confluence offers four built-in themes: Default, Dark, Forest, and Neutral. Pick one theme for all ER diagrams in a space and stick with it. The Default theme lets you customize node, text, border, line, and background colors to match your company brand. Consistent visual style across pages makes your documentation feel polished and professional. For detailed configuration options including font families, color pickers, and output sizes, refer to the [Mermaid Plus Diagrams & AI Agent for Confluence usage guide](/docs/Mermaid-Plus-for-Confluence/usage.md). ## Common Mistakes and How to Fix Them[​](#common-mistakes-and-how-to-fix-them "Direct link to Common Mistakes and How to Fix Them") **Missing `erDiagram` header.** Every ER diagram must start with the `erDiagram` keyword on its own line. Writing entity definitions without this header produces a parse error. The correct form is: ``` erDiagram CUSTOMER ||--o{ ORDER : places ``` **Wrong cardinality direction.** The cardinality symbols closest to an entity describe that entity's role. In `CUSTOMER ||--o{ ORDER : places`, the `||` is next to `CUSTOMER` (exactly one customer) and `o{` is next to `ORDER` (zero or more orders). If your diagram looks reversed, swap the sides of the relationship line. **Spaces in entity names.** Mermaid does not support spaces in entity names. Use underscores instead: `ORDER_ITEM`, not `ORDER ITEM`. Relationship labels can contain spaces because they are written after the colon. **Missing foreign key annotations.** If a column references another table's primary key, mark it with `FK`. This makes the relationship visually explicit in the diagram and helps readers trace referential integrity without hunting through relationship lines. **Overcrowding.** An ER diagram with 20 entities and 40 relationships becomes unreadable. If your diagram has grown too large, split it by domain, subsystem, or feature area. Link the pages together so readers can navigate between focused views. **Forgetting to close attribute blocks.** Every `{` must have a matching `}`. If your diagram fails to render, check that every entity's attribute block is properly closed. The live preview in Mermaid Plus will show you parse errors in real time, which makes this easy to catch. ## ER Diagrams vs Class Diagrams vs Flowcharts[​](#er-diagrams-vs-class-diagrams-vs-flowcharts "Direct link to ER Diagrams vs Class Diagrams vs Flowcharts") ER diagrams are not the right tool for every situation. Here is a quick guide to help you choose the right diagram type: * **ER diagram** -- Use when documenting relational database schemas, data models, and table relationships. ER diagrams focus on tables, columns, key constraints, and cardinality. * **Class diagram** -- Use when documenting object-oriented systems, domain models, and API contracts with methods, visibility, and inheritance. See [how to create class diagrams in Confluence](/blog/how-to-create-class-diagrams-confluence.md). * **Flowchart** -- Use when documenting processes, decision trees, approval workflows, and algorithmic logic. See [how to create flowcharts in Confluence](/blog/create-flowcharts-confluence.md). Many technical design documents benefit from combining multiple diagram types on the same Confluence page. An ER diagram shows the data model, a class diagram shows the application layer, and a flowchart shows the business process that ties them together. ## Mermaid Syntax Cheat Sheet[​](#mermaid-syntax-cheat-sheet "Direct link to Mermaid Syntax Cheat Sheet") For a quick reference covering ER diagrams and all other Mermaid diagram types supported in Confluence, bookmark the [Mermaid syntax cheat sheet for Confluence](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md). It covers flowcharts, sequence diagrams, class diagrams, ER diagrams, Gantt charts, and more in a single-page reference. For the complete list of diagram types, see [all 30 Mermaid diagram types in Confluence](/blog/faq-mermaid-diagram-types-confluence.md). ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Mermaid Plus Diagrams & AI Agent for Confluence usage guide](/apps/mermaid-plus-for-confluence.md) -- configuration panel walkthrough, theme settings, font and color customization, and all 30 supported diagram types * [How to create class diagrams in Confluence](/blog/how-to-create-class-diagrams-confluence.md) -- document object-oriented systems with inheritance, composition, and generics using copy-paste Mermaid examples * [Mermaid syntax cheat sheet for Confluence](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md) -- quick reference for flowcharts, sequence diagrams, ER diagrams, Gantt charts, and more * [How to create flowcharts in Confluence](/blog/create-flowcharts-confluence.md) -- process diagrams, decision trees, and workflow documentation with Mermaid ER diagrams are one of the most valuable tools in a software team's documentation toolkit. They capture the data model of your system in a way that prose alone cannot match. With Mermaid Plus Diagrams & AI Agent for Confluence, creating and maintaining ER diagrams is as simple as writing text. Install the app, paste one of the examples above into a Confluence page, and start documenting your database schema where it belongs -- alongside everything else your team needs. ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [er-diagram](/blog/tags/er-diagram.md) * [database](/blog/tags/database.md) * [how-to](/blog/tags/how-to.md) * [diagrams](/blog/tags/diagrams.md) --- # Manual Toggles vs Modern FAQ for Confluence — 3 Methods Compared May 23, 2026 · 9 min read [NGPilot](https://ngpilot.com) FAQ pages are one of the most visited sections of any documentation site. In Confluence, they serve a specific purpose: giving your team or customers quick answers to the questions they ask most often, without making them read through pages of documentation. A well-structured FAQ page reduces repetitive questions in Slack channels, shortens onboarding time for new team members, and deflects support tickets before they are created. But Confluence does not have a built-in FAQ feature. Teams typically resort to manual workarounds — tables, toggle macros, or expand sections — that look cluttered and are hard to maintain. This guide shows you three methods to create professional FAQ pages in Confluence, from a quick manual setup to a fully featured FAQ macro. ## Method 1: Manual FAQ with Confluence Toggles (Quick but Limited)[​](#method-1-manual-faq-with-confluence-toggles-quick-but-limited "Direct link to Method 1: Manual FAQ with Confluence Toggles (Quick but Limited)") If you need a basic FAQ section on a single page and do not want to install anything, you can use Confluence's built-in toggle macro. Each question becomes a toggle heading, and the answer appears when a reader clicks to expand it. ### How to set it up[​](#how-to-set-it-up "Direct link to How to set it up") 1. Open your Confluence page in edit mode 2. Type `/toggle` and select **Toggle heading** 3. Type the question as the heading text 4. Add the answer inside the toggle body 5. Repeat for each FAQ item ### What it looks like[​](#what-it-looks-like "Direct link to What it looks like") Your page will show a series of collapsible headings. Readers click to expand each answer. This works for short FAQ sections with fewer than 10 questions. ### Limitations of the manual approach[​](#limitations-of-the-manual-approach "Direct link to Limitations of the manual approach") * **No reordering.** If you want to move a question, you have to cut and paste the entire toggle block. With 20+ questions, this becomes painful. * **Inconsistent styling.** Every toggle looks the same. You cannot distinguish between categories or highlight important answers. * **No search-friendly formatting.** Toggle content is collapsed by default and does not show up well in Confluence search results. * **Hard to maintain.** Adding, editing, or reorganizing questions means editing the raw page content. There is no dedicated FAQ management interface. The manual approach works for a quick 5-question FAQ on a project page. For anything your team will maintain long-term, a dedicated FAQ macro is a better investment. ## Method 2: Modern FAQ for Confluence (Recommended)[​](#method-2-modern-faq-for-confluence-recommended "Direct link to Method 2: Modern FAQ for Confluence (Recommended)") [Modern FAQ for Confluence](/docs/Modern-FAQ-for-Confluence/usage.md) is a dedicated FAQ macro that gives you drag-and-drop question management, two display themes, and a WYSIWYG editor for answers. It is designed specifically for teams that maintain FAQ pages as part of their documentation. ### Step-by-step: Create an FAQ section[​](#step-by-step-create-an-faq-section "Direct link to Step-by-step: Create an FAQ section") **Step 1 — Install Modern FAQ for Confluence** Go to the [Atlassian Marketplace](https://marketplace.atlassian.com/) and search for **Modern FAQ for Confluence**. Click **Get App** and follow the installation prompts. The app supports Confluence Cloud and Confluence Data Center. **Step 2 — Insert the FAQ macro** Open any Confluence page in edit mode. Type `/faq` and select **Modern FAQ for Confluence** from the macro dropdown. The FAQ editor appears on the page. **Step 3 — Add your questions and answers** Click **Add Question** to create your first FAQ item. Each item has two fields: * **Question** — the text that readers see in the FAQ list * **Answer** — a rich text editor where you can add formatted text, links, images, code blocks, and even other Confluence macros Add as many questions as you need. The editor shows a live preview of how the FAQ section will look when published. **Step 4 — Reorder with drag and drop** Click and drag any question to rearrange the order. This is particularly useful when you want to: * Move the most frequently asked questions to the top * Group questions by topic or category * Pin important announcements at the beginning of the list No cut-and-paste needed. Drag, drop, and the order updates instantly. **Step 5 — Choose a display theme** Modern FAQ offers two display themes: * **Centered** — questions are centered on the page with a clean, modern look. Best for product pages, landing pages, and customer-facing documentation. * **Accordion** — questions are listed with expand/collapse functionality. Best for technical documentation, internal wikis, and pages with many FAQ items. Select the theme in the macro settings. You can change it at any time without re-entering your content. **Step 6 — Save and publish** Click **Save** on the macro, then **Publish** the Confluence page. Your FAQ section is now live. Team members can view it immediately, and editors can click the macro to modify questions. ### FAQ page example[​](#faq-page-example "Direct link to FAQ page example") Here is a real-world example of how a product team structures their FAQ page in Confluence using Modern FAQ: **Product FAQ — API Integration** | # | Question | Answer Preview | | - | --------------------------------------------- | -------------------------------------------------------------- | | 1 | What authentication methods do you support? | We support OAuth 2.0 and API key authentication... | | 2 | What is the rate limit for API requests? | 1,000 requests per minute per API key... | | 3 | Do you have a sandbox environment? | Yes, use sandbox.api.example.com with your test credentials... | | 4 | How do I handle pagination in list endpoints? | Use the `cursor` parameter returned in each response... | | 5 | What response formats are available? | JSON is the default. XML is available on select endpoints... | With Modern FAQ, this content is managed through a dedicated editor — not as raw page elements. Adding a new question takes two clicks. Reordering takes a drag-and-drop. No risk of accidentally breaking the page layout. ### Why teams choose Modern FAQ over manual toggles[​](#why-teams-choose-modern-faq-over-manual-toggles "Direct link to Why teams choose Modern FAQ over manual toggles") | Feature | Manual Toggles | Modern FAQ | | ------------------ | ------------------------------- | ------------------------------ | | Add a question | Type `/toggle`, format manually | Click **Add Question** | | Reorder questions | Cut and paste blocks | Drag and drop | | Rich text answers | Yes (manual formatting) | Yes (WYSIWYG editor) | | Display themes | None — all look the same | Centered and Accordion | | Consistent styling | No — each toggle is independent | Yes — macro controls all items | | Edit interface | Inline on the page | Dedicated FAQ editor | | Maintenance effort | High for 10+ questions | Low regardless of count | ## Method 3: Template-Based FAQ Pages[​](#method-3-template-based-faq-pages "Direct link to Method 3: Template-Based FAQ Pages") If your team creates FAQ pages frequently — for example, every product release gets its own FAQ page — you can combine Modern FAQ with Confluence templates for a repeatable workflow. ### How to set up an FAQ template[​](#how-to-set-up-an-faq-template "Direct link to How to set up an FAQ template") 1. Go to **Space Settings > Templates** in your Confluence space 2. Create a new template 3. Add your standard page structure: title, introduction paragraph, and any boilerplate content 4. Insert the **Modern FAQ** macro into the template with placeholder questions 5. Save the template When someone creates a new page from this template, the FAQ macro is already in place with the placeholder content. They just edit the questions and answers to match the specific topic. This approach works well for teams that maintain: * Product release FAQ pages * Customer onboarding FAQ pages * IT help desk FAQ pages per service * Project-specific FAQ pages ## Best Practices for FAQ Pages in Confluence[​](#best-practices-for-faq-pages-in-confluence "Direct link to Best Practices for FAQ Pages in Confluence") Regardless of which method you choose, these practices will make your FAQ pages more useful. ### Source questions from real data[​](#source-questions-from-real-data "Direct link to Source questions from real data") The best FAQ pages answer questions people actually ask. Do not guess at what your users need. Instead: * **Check your support ticket data.** The most common ticket categories should become FAQ questions. * **Review Slack channel history.** Search for recurring questions in team channels. * **Ask customer-facing teams.** Sales, support, and customer success teams know what customers ask most often. * **Review Confluence search logs.** If your team searches for the same topic repeatedly, it belongs in an FAQ. ### Keep answers concise[​](#keep-answers-concise "Direct link to Keep answers concise") FAQ answers should be 2-4 sentences. If an answer needs a long explanation, link to a detailed documentation page instead. The FAQ page is for quick resolution, not comprehensive documentation. Bad: "To configure the API integration, first navigate to the settings page, then click on the integrations tab, then scroll down to the API section, then click the Add New Integration button, then enter your API key in the designated field..." Good: "Navigate to **Settings > Integrations > API** and click **Add New Integration**. Paste your API key and click **Save**. See the [API integration guide](#) for detailed setup instructions." ### Group by topic[​](#group-by-topic "Direct link to Group by topic") If your FAQ has more than 10 questions, group them by topic using section headers or separate FAQ macros: * **Getting Started** — account setup, first steps, basic concepts * **Features** — specific feature questions * **Troubleshooting** — common errors and fixes * **Billing** — pricing, invoices, plan changes Each group can have its own Modern FAQ macro on the same page, keeping the content organized and scannable. ### Update quarterly[​](#update-quarterly "Direct link to Update quarterly") FAQ content goes stale quickly. Set a quarterly reminder to review your FAQ pages: * Remove questions that are no longer relevant * Add new questions that have emerged * Update answers that reference changed features or processes * Check that all links still work ### Link to detailed docs[​](#link-to-detailed-docs "Direct link to Link to detailed docs") Every FAQ answer should either fully answer the question in 2-4 sentences or link to a page that does. Do not leave readers halfway to an answer. If the FAQ answer is "it depends" or requires context, the link to the full documentation is the answer. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Modern FAQ for Confluence](/apps/modern-faq-for-confluence.md) -- dedicated FAQ macro with drag-and-drop editing, two display themes, and WYSIWYG answer editing * [Modern Questions for Confluence](/apps/modern-questions-for-confluence.md) -- community Q\&A forum with voting, accepted answers, and topic tags * [FAQ and Q\&A Apps for Confluence Compared](/blog/faq-questions-confluence-comparison.md) -- side-by-side comparison of all FAQ and Q\&A apps on the Atlassian Marketplace * [How to Build FAQ Sections in Confluence](/blog/how-to-build-faq-sections-confluence.md) -- design patterns and content strategies for FAQ pages Try Modern FAQ for Confluence Accordion-style FAQ sections with drag-and-drop reordering and two themes — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236739/modern-faq-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-faq-for-confluence) ## Related guides * [Confluence Questions & Answers Template](/blog/confluence-questions-answers-template.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [faq](/blog/tags/faq.md) * [how-to](/blog/tags/how-to.md) * [knowledge-base](/blog/tags/knowledge-base.md) * [accordion](/blog/tags/accordion.md) * [questions](/blog/tags/questions.md) --- # How to Create a Flowchart in Jira — 3 Methods with Copy-Paste Examples September 13, 2026 · 6 min read [NGPilot](https://ngpilot.com) Jira is where the work happens — but the *process* behind the work usually lives in someone's head or in a stale Confluence page nobody opens. A flowchart on the Jira issue itself fixes that: bug triage paths, approval chains, and escalation procedures become visual, unambiguous, and impossible to miss. Jira Cloud gives you two ways to get there, and they serve different needs. This guide walks through both, then gives you three copy-paste Mermaid flowchart examples for the scenarios Jira teams hit most: bug triage, approval workflows, and incident escalation. **Quick answer:** Jira has no built-in flowchart *on issues*. The native whiteboard lets you draw flowchart shapes on a collaborative canvas — great for a one-off sketch, but the drawing lives outside the issue. To put a versioned, always-editable flowchart directly on a Jira issue, install [Mermaid Plus Diagrams for Jira](https://marketplace.atlassian.com/apps/2658777397/), open the panel on any issue, and paste Mermaid `flowchart` syntax — every example below is copy-paste ready. ## Method 1 — Native Whiteboards (Quick Sketches)[​](#method-1--native-whiteboards-quick-sketches "Direct link to Method 1 — Native Whiteboards (Quick Sketches)") Jira Cloud includes whiteboards: a collaborative canvas where you drag shapes, arrows, and sticky notes. For a flowchart, you place diamond and rectangle shapes manually and connect them. **Good for:** a live brainstorm or a one-off sketch during a meeting. **The limitation:** a whiteboard is a separate artifact. It is not attached to the issue whose process it describes, nobody stumbles across it while reading the ticket, and six months later nobody updates it — the classic stale-diagram problem. Dragging 15 shapes and aligning arrows by hand is also slow compared to editing a few lines of text. If your flowchart is a throwaway sketch, a whiteboard is the fastest path. If the flowchart *documents the process the issue follows*, it belongs on the issue — that's Method 2. ## Method 2 — Mermaid Flowcharts on the Issue (Recommended)[​](#method-2--mermaid-flowcharts-on-the-issue-recommended "Direct link to Method 2 — Mermaid Flowcharts on the Issue (Recommended)") [Mermaid Plus Diagrams for Jira](https://marketplace.atlassian.com/apps/2658777397/) adds a diagram panel to every Jira issue. You write the flowchart as Mermaid — plain text — and it renders live on the issue. **Why text beats drawing for process documentation:** * **Editing is trivial** — change a line of text, the diagram re-renders. No re-dragging shapes * **It lives on the issue** — anyone opening the ticket sees the flow immediately * **It versions with the discussion** — the process change and the diagram update land together * **Copy-paste from anywhere** — AI assistants, docs, or a teammate's issue: the syntax transfers intact ### Example 1 — Bug Triage Decision Tree[​](#example-1--bug-triage-decision-tree "Direct link to Example 1 — Bug Triage Decision Tree") The classic scenario: a bug report arrives, and every triager follows a slightly different path. Put the decision tree on the epic (or on your bug-template issue) so the path is identical for everyone: ``` flowchart TD A[Bug report arrives] --> B{Reproducible?} B -- No --> C[Request more info] C --> A B -- Yes --> D{Blocks release?} D -- Yes --> E[Priority: Critical] E --> F[Assign to on-call dev] D -- No --> G{Affects core flows?} G -- Yes --> H[Priority: High] G -- No --> I[Priority: Normal] H --> J[Schedule for current sprint] I --> K[Add to backlog for grooming] F --> L[Hotfix branch + immediate fix] ``` Every triager now follows the same tree, and the diagram sits on the epic where triage is tracked — not in a comment thread three clicks deep. ### Example 2 — Approval Workflow with Colored Stages[​](#example-2--approval-workflow-with-colored-stages "Direct link to Example 2 — Approval Workflow with Colored Stages") Process flows read much better when node colors carry meaning. `classDef` styles make stages scannable at a glance — here, a content approval chain with pending, in-review, and done states: ``` flowchart LR A[Draft created] --> B{Peer review} B -- Changes needed --> C[Revise draft] C --> B B -- Approved --> D{Legal review} D -- Rejected --> C D -- Cleared --> E[Publish] E --> F[Archive + notify] classDef pending fill:#FFF3CD,stroke:#B8860B,color:#000 classDef review fill:#E7F1FF,stroke:#2B6CB0,color:#000 classDef done fill:#D4EDDA,stroke:#2F855A,color:#000 class A,C pending class B,D review class E,F done ``` `flowchart LR` (left-right) suits workflows with few stages; switch to `TD` when the chain gets long — vertical layouts survive narrow screens better. ### Example 3 — Incident Escalation with Subgraphs[​](#example-3--incident-escalation-with-subgraphs "Direct link to Example 3 — Incident Escalation with Subgraphs") For incident runbooks, `subgraph` groups the flow into phases. This one shows detection → escalation → resolution for a production incident, ready to paste onto your incident-type issue or a postmortem template: ``` flowchart TD subgraph Detection A[Alert fires] --> B{On-call acknowledges\nwithin 5 min?} B -- No --> C[Auto-escalate to secondary] B -- Yes --> D[Triage the alert] end subgraph Escalation D --> E{Customer impact?} C --> E E -- Yes --> F[Open incident channel\npage incident commander] E -- No --> G[Fix in normal queue] end subgraph Resolution F --> H[Mitigate + communicate] H --> I[Postmortem within 48h] end ``` Paste it once onto your incident template issue, and every future incident starts with the current escalation path in view. ## Method 3 — Confluence for the Big Picture, Jira for the Point[​](#method-3--confluence-for-the-big-picture-jira-for-the-point "Direct link to Method 3 — Confluence for the Big Picture, Jira for the Point") When a process needs long-form context — multiple diagrams, tables, revision history — document it in Confluence with [Mermaid Plus Diagrams & AI Agent for Confluence](/blog/create-mermaid-diagrams-confluence.md), then attach a single focused flowchart to the Jira epic and link the two. The issue keeps the at-a-glance flow; the space page keeps the depth. This split mirrors how most teams already use the two tools, and it keeps either side from bloating. ## Which Method Should You Use?[​](#which-method-should-you-use "Direct link to Which Method Should You Use?") | Need | Use | | ------------------------------------- | --------------------------------------------- | | One-off sketch in a meeting | Native whiteboard | | Process doc that lives on the issue | Mermaid Plus Diagrams for Jira | | Deep documentation with many diagrams | Confluence page + summary diagram on the epic | For the second row — the one most teams need most of the time — the flow is: install the app, open the panel, paste one of the examples above, done in under a minute. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Create Mermaid diagrams on Jira issues](/blog/how-to-create-mermaid-diagrams-jira.md) -- the complete guide: sequence diagrams, class diagrams, and settings for Jira issues * [Mermaid Plus Diagrams for Jira](/apps/mermaid-plus-diagrams-for-jira.md) -- full documentation: configuration, themes, and all supported diagram types * [Jira diagram apps compared](/blog/jira-diagram-apps-comparison.md) -- how Mermaid Plus stacks up against other Jira diagramming options * [Gantt charts in Confluence](/blog/how-to-create-gantt-charts-confluence.md) -- timeline views for project plans alongside your process flows Flowcharts turn tribal process knowledge into something every teammate can follow. With Mermaid Plus Diagrams for Jira, the flowchart lives on the issue it documents, edits in seconds, and never goes stale. Install it, paste an example, and put your first process on the ticket today. ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [flowchart](/blog/tags/flowchart.md) * [diagrams](/blog/tags/diagrams.md) * [mermaid](/blog/tags/mermaid.md) * [how-to](/blog/tags/how-to.md) * [whiteboard](/blog/tags/whiteboard.md) --- # How to Create Gantt Charts in Confluence — Mermaid Examples May 2, 2026 · 15 min read [NGPilot](https://ngpilot.com) Gantt charts are one of the most widely used visual tools in project management. They give teams a clear, time-based view of who is doing what, when tasks start and end, and how dependencies chain together across a project lifecycle. Whether you are planning a software release, coordinating a marketing campaign, or managing a sprint backlog, a Gantt chart turns a flat task list into a timeline your whole team can read at a glance. Confluence is where many teams already store their project documentation, meeting notes, and decision records. Embedding Gantt charts directly on Confluence pages keeps your project visuals alongside the context your team needs, instead of burying timelines in a separate project management tool that nobody checks. With Mermaid Plus Diagrams & AI Agent for Confluence, you can write Gantt charts using plain text syntax and see them rendered instantly on the page. In this tutorial, you will learn how to create Gantt charts in Confluence using Mermaid syntax. Every example is copy-paste ready, so you can drop it straight into a Confluence page and start customizing it for your own projects. ## Why Gantt Charts in Confluence?[​](#why-gantt-charts-in-confluence "Direct link to Why Gantt Charts in Confluence?") Teams reach for Gantt charts when they need to visualize **when work happens and what depends on what**. Unlike a simple task list or a Kanban board, a Gantt chart places every task on a time axis, making it easy to spot scheduling conflicts, idle periods, and critical-path bottlenecks. This makes Gantt charts especially useful for: * **Project kickoffs** where stakeholders need to see the full timeline before approving scope * **Cross-team coordination** so engineering, design, QA, and marketing can align on handoff dates * **Status reporting** that gives executives a visual summary without digging through Jira boards * **Onboarding new team members** who need to understand the project cadence and upcoming milestones Confluence is the natural home for this kind of documentation. Your project briefs, architecture decision records, and retrospective notes already live there. Adding a rendered Gantt chart to the same page means the timeline is always one scroll away from the context that explains it. When dates change, you update the Mermaid code and republish. No exports, no screenshots, no broken image links. Mermaid's Gantt syntax is purpose-built for project timelines. It supports task dependencies, milestones, status indicators, sections, date exclusions, and custom date formats. With Mermaid Plus Diagrams & AI Agent for Confluence, you get a code editor right inside the Confluence page, with live preview and full version history. ## Step-by-Step: Create Your First Gantt Chart[​](#step-by-step-create-your-first-gantt-chart "Direct link to Step-by-Step: Create Your First Gantt Chart") Follow these steps to go from a blank Confluence page to a fully rendered Gantt chart. ### Step 1 -- Install a Mermaid macro for Confluence[​](#step-1----install-a-mermaid-macro-for-confluence "Direct link to Step 1 -- Install a Mermaid macro for Confluence") You have two options for rendering Mermaid Gantt charts in Confluence: **[Mermaid Plus Diagrams & AI Agent for Confluence](/docs/Mermaid-Plus-for-Confluence/usage.md)** (recommended) — dedicated Mermaid editor with 30 diagram types, live preview, templates, and customizable themes. Search for **Mermaid Plus** on the [Atlassian Marketplace](https://marketplace.atlassian.com/) and click **Get App**. **[Diagram Duo for Confluence](/docs/diagram-duo-for-confluence/usage.md)** — combines a Mermaid code editor with an Excalidraw visual canvas. If your team also creates architecture diagrams or flowcharts, Diagram Duo gives you both text-based and visual diagramming in one macro. Both apps support Confluence Cloud and Confluence Data Center. If your organization requires admin approval for Marketplace apps, contact your Confluence administrator. ### Step 2 -- Insert the Mermaid Macro[​](#step-2----insert-the-mermaid-macro "Direct link to Step 2 -- Insert the Mermaid Macro") Open any Confluence page in edit mode. Type `/mermaid` in the editor and select the macro from the dropdown. A code editor panel appears where you can write Mermaid syntax. ### Step 3 -- Write the `gantt` Header[​](#step-3----write-the-gantt-header "Direct link to step-3----write-the-gantt-header") Start every Gantt chart with the `gantt` keyword, then set your date format and add an optional title: ``` gantt title My First Gantt Chart dateFormat YYYY-MM-DD ``` The `dateFormat` directive tells Mermaid how to parse the dates you provide. `YYYY-MM-DD` is the most common format, but Mermaid also supports `MM/DD/YYYY`, `DD-MM-YYYY`, and others. The `title` appears at the top of the rendered chart. ### Step 4 -- Add Tasks and Milestones[​](#step-4----add-tasks-and-milestones "Direct link to Step 4 -- Add Tasks and Milestones") Define tasks with a task ID, display name, start date, and duration. Chain tasks together with the `after` keyword: ``` gantt title My First Gantt Chart dateFormat YYYY-MM-DD section Planning Requirements gathering :done, req, 2026-05-01, 10d Architecture design :active, arch, after req, 5d section Development Frontend build :dev-fe, after arch, 15d Backend API :dev-be, after arch, 12d Go-live milestone :milestone, launch, after dev-fe, 0d ``` Each task line follows this pattern: `taskID : status, taskID, startOrDependency, duration`. The status flags (`done`, `active`, or no flag for future) control how the bar appears in the rendered chart. Milestones use the `milestone` keyword and have zero duration. ### Step 5 -- Save and Publish[​](#step-5----save-and-publish "Direct link to Step 5 -- Save and Publish") Preview the Gantt chart inside the macro editor to verify it renders correctly. Check that dependencies flow in the right order and that your date format is consistent throughout. When you are happy with the result, click **Save** on the macro, then **Publish** the Confluence page. Your Gantt chart is now part of your living project documentation. ## Mermaid Gantt Syntax Reference[​](#mermaid-gantt-syntax-reference "Direct link to Mermaid Gantt Syntax Reference") Here is a quick-reference table for the most commonly used Gantt chart elements in Mermaid. Bookmark this section and come back to it whenever you need a syntax reminder. | Element | Syntax | Description | | --------------- | ------------------------------------------- | ------------------------------------------ | | Chart header | `gantt` | Starts a Gantt chart | | Title | `title My Chart` | Displays a title above the chart | | Date format | `dateFormat YYYY-MM-DD` | Sets how Mermaid parses your dates | | Axis format | `axisFormat %b %d` | Controls how dates appear on the time axis | | Section | `section Phase Name` | Groups tasks into labeled sections | | Task (basic) | `task1 : Task Name, 2026-01-01, 30d` | A task with start date and duration | | Task (with ID) | `task1 : Task Name, 2026-01-01, 30d` | Named task with ID for dependencies | | Task (end date) | `task1 : Task Name, 2026-01-01, 2026-01-31` | A task defined by start and end date | | Dependency | `task2 : Task Name, after task1, 14d` | Task starts after another task finishes | | Done status | `:done, task1, ...` | Marks task as completed (grayed out) | | Active status | `:active, task1, ...` | Marks task as in progress (highlighted) | | Milestone | `:milestone, m1, 2026-03-15, 0d` | A zero-duration diamond marker | | Exclusion | `excludes weekends` | Excludes named days from the timeline | | Comment | `%% This is a comment` | Inline comment, not rendered | | Critical path | `:crit, task1, ...` | Highlights task on the critical path | ## 3 Copy-Paste Gantt Chart Examples[​](#3-copy-paste-gantt-chart-examples "Direct link to 3 Copy-Paste Gantt Chart Examples") Below are three practical examples you can paste directly into the Mermaid Plus macro in Confluence. Each example demonstrates a different real-world project scenario. ### Example 1 -- Software Release Timeline[​](#example-1----software-release-timeline "Direct link to Example 1 -- Software Release Timeline") This Gantt chart models a typical software release cycle from design through production deployment. It uses sections to separate phases, status flags to show progress, and dependencies to enforce a realistic task order. ``` gantt title Software Release v2.0 Timeline dateFormat YYYY-MM-DD axisFormat %b %d section Design UX research :done, ux, 2026-04-01, 7d Wireframes :done, wire, after ux, 5d Visual design :done, vis, after wire, 7d section Development Frontend sprint 1 :active, fe1, 2026-04-21, 10d Frontend sprint 2 :fe2, after fe1, 10d Backend API :be, 2026-04-21, 14d Integration :int, after fe2, 5d section Testing QA regression :qa, after int, 7d User acceptance :uat, after qa, 5d Bug fixes :fix, after uat, 5d section Release Staging deploy :stage, after fix, 2d Production deploy :prod, after stage, 1d Post-release monitor :mon, after prod, 5d ``` Use this chart as a starting point for your own release planning. Add tasks for documentation updates, performance testing, or security audits as your release process requires. The `done`, `active`, and future states let readers see the current progress at a glance. ### Example 2 -- Marketing Campaign Launch[​](#example-2----marketing-campaign-launch "Direct link to Example 2 -- Marketing Campaign Launch") This example models a multi-channel marketing campaign with content creation, review cycles, and a hard launch date. It demonstrates how milestones mark key deadlines and how parallel tracks (blog content, email, social media) run concurrently. ``` gantt title Q3 Product Launch Campaign dateFormat YYYY-MM-DD axisFormat %b %d section Strategy Market research :done, research, 2026-06-01, 7d Campaign brief :done, brief, after research, 3d Messaging framework :done, msg, after brief, 4d section Content Blog post drafts :active, blog, after msg, 10d Video production :video, after msg, 14d Landing page copy :lp, after msg, 5d Email sequences :email, after msg, 7d section Review Legal review :legal, after blog, 5d Brand review :brand, after lp, 3d Revisions :rev, after legal, 3d section Launch Content freeze :milestone, freeze, after rev, 0d Social media schedule :social, after freeze, 3d Email blast setup :blast, after freeze, 2d Campaign go-live :milestone, launch, 2026-07-15, 0d section Post-Launch Performance report :report, after launch, 7d Retrospective :retro, after report, 1d ``` This chart highlights two important patterns. First, multiple tasks share the same dependency (`after msg`), which creates parallel tracks that start simultaneously. Second, the `milestone` keyword creates diamond markers on the timeline for events with zero duration, making launch dates and deadlines visually distinct from work tasks. ### Example 3 -- Sprint Planning[​](#example-3----sprint-planning "Direct link to Example 3 -- Sprint Planning") This example shows a two-week Agile sprint with stories grouped by epic. It uses compact durations and a Monday-to-Friday working pattern via the `excludes` keyword, which prevents weekends from inflating the timeline. ``` gantt title Sprint 14 — May 5-16 dateFormat YYYY-MM-DD axisFormat %b %d excludes weekends section Sprint Setup Sprint planning :done, plan, 2026-05-05, 1d Backlog refinement :done, refine, 2026-05-05, 1d section Epic: User Dashboard Dashboard API :active, api, 2026-05-06, 4d Dashboard UI :dash, after api, 3d Dashboard testing :dtest, after dash, 2d section Epic: Notifications Email templates :tmpl, 2026-05-06, 3d Notification service :notif, after tmpl, 3d Push integration :push, after notif, 2d section Sprint Close Code review :review, 2026-05-14, 1d Sprint demo :milestone, demo, 2026-05-16, 0d Retrospective :retro, after demo, 0d ``` The `excludes weekends` directive is essential for sprint timelines because it prevents Saturday and Sunday from appearing as working days. Mermaid automatically extends the task bars to account for excluded days, so a 3-day task starting on Friday will correctly span Friday, Monday, and Tuesday. ## Real-World Gantt Example: Product Launch Plan[​](#real-world-gantt-example-product-launch-plan "Direct link to Real-World Gantt Example: Product Launch Plan") The pattern most PMs actually need — a cross-functional launch with parallel tracks, handoffs, and a hard date. Notice the parallel sections (engineering and marketing run simultaneously) and the dependency chain in the launch section: ``` gantt title Q3 Product Launch — v2.0 dateFormat YYYY-MM-DD excludes weekends section Discovery Customer interviews :done, disc1, 2026-07-06, 10d Requirements doc :done, after disc1, 5d section Engineering API design :eng1, 2026-07-20, 8d Implementation :eng2, after eng1, 15d Internal QA :eng3, after eng2, 7d Bug bash week :crit, eng4, after eng3, 5d section Marketing Positioning + messaging :mkt1, 2026-07-27, 8d Launch page + docs :mkt2, after mkt1, 10d Beta customer previews :mkt3, after mkt2, 7d section Launch Go/No-go review :milestone, m1, 2026-09-14, 0d Production rollout :after m1, 2d Announcement + email :after m1, 1d ``` Three things worth copying from this example: `crit` flags the bug bash as the critical-path item, the `milestone` with `0d` duration renders as a diamond instead of a bar, and the two parallel sections show how Mermaid handles concurrent work tracks without extra syntax. For sprint-scale timelines (two weeks, task-granular), see [Mermaid diagrams for Jira sprint workflows](/blog/mermaid-diagrams-jira-sprint-workflows.md). ## Tips for Complex Gantt Charts[​](#tips-for-complex-gantt-charts "Direct link to Tips for Complex Gantt Charts") As your Gantt charts grow beyond ten or fifteen tasks, readability and maintainability become important. These tips help you keep large charts organized and accurate. ### Use Sections to Group Related Tasks[​](#use-sections-to-group-related-tasks "Direct link to Use Sections to Group Related Tasks") Sections are the primary organizational tool in Mermaid Gantt charts. They create labeled rows that visually separate phases, epics, or teams. Every task between two `section` declarations belongs to the same group. Use section names that match how your team talks about the work: "Phase 1", "Backend", "Epic: Search", or "Q3" are all good choices. ### Chain Dependencies Carefully[​](#chain-dependencies-carefully "Direct link to Chain Dependencies Carefully") The `after` keyword is powerful but can create confusing charts if used carelessly. Follow these guidelines: * **One dependency per task** is the most readable pattern. If a task depends on two predecessors, pick the one that finishes latest. * **Avoid circular dependencies.** If task B depends on task A, task A cannot depend on task B. Mermaid will fail to render the chart. * **Use task IDs that are short and descriptive.** IDs like `ux`, `fe1`, and `stage` are easier to read in dependency chains than `task1`, `task2`, `task3`. ### Exclude Non-Working Days[​](#exclude-non-working-days "Direct link to Exclude Non-Working Days") Use `excludes weekends` for charts that represent working-day timelines. You can also exclude specific dates like company holidays: ``` excludes weekends, 2026-07-04, 2026-12-25 ``` Mermaid adjusts all task durations automatically when exclusions are present. This prevents your chart from showing work happening on days when nobody is in the office. ### Use Milestones for Key Dates[​](#use-milestones-for-key-dates "Direct link to Use Milestones for Key Dates") Milestones are zero-duration events rendered as diamonds on the timeline. They are ideal for marking launch dates, approval deadlines, review gates, and external dependencies. A good rule of thumb is one milestone per phase of your project. Too many milestones make the chart noisy; too few make it hard to spot important dates. ### Use Status Flags Honestly[​](#use-status-flags-honestly "Direct link to Use Status Flags Honestly") Mermaid supports three task states: `done` (completed, grayed out), `active` (in progress, highlighted), and the default future state. Update these flags as your project progresses. An accurate Gantt chart is a useful communication tool. An outdated one erodes trust in the timeline. ### Keep Task Names Concise[​](#keep-task-names-concise "Direct link to Keep Task Names Concise") Long task names push the chart wider and reduce the space available for the time axis. Aim for two to four words per task name. If you need more detail, add a comment or link to a Jira ticket in a note on the Confluence page. ### Use the Critical Path Flag Sparingly[​](#use-the-critical-path-flag-sparingly "Direct link to Use the Critical Path Flag Sparingly") The `crit` status flag highlights a task in red, marking it as a critical-path item. This is useful for drawing attention to tasks that will delay the entire project if they slip. Reserve `crit` for the handful of tasks that truly block downstream work. Highlighting every task as critical defeats the purpose. ### Break Very Large Charts into Multiple Diagrams[​](#break-very-large-charts-into-multiple-diagrams "Direct link to Break Very Large Charts into Multiple Diagrams") If a single Gantt chart exceeds 25 to 30 tasks, consider splitting it into separate charts per phase or per team. Confluence supports multiple Mermaid macros on the same page, so you can show a high-level overview chart at the top, followed by detailed phase-specific charts below. Link them with a brief prose explanation of what each chart covers. ### Use Styling for Emphasis[​](#use-styling-for-emphasis "Direct link to Use Styling for Emphasis") Mermaid supports inline styling with the `style` keyword. You can change the color of specific task bars to call out risks, blockers, or stretch goals: ``` style fe1 fill:#ffcccc,stroke:#ff0000 ``` Apply styling judiciously. One or two highlighted tasks draw attention. Ten highlighted tasks create visual noise. ## Common Mistakes to Avoid[​](#common-mistakes-to-avoid "Direct link to Common Mistakes to Avoid") * **Forgetting the `gantt` keyword.** Every Gantt chart must start with `gantt` on its own line. Without it, Mermaid does not know what type of diagram to render. * **Inconsistent date formats.** If you set `dateFormat YYYY-MM-DD`, every date in the chart must follow that format. Mixing `2026-05-01` and `05/01/2026` will cause parse errors. * **Missing commas in task definitions.** Task lines require commas between the status, task ID, date, and duration. A missing comma is the most common syntax error in Mermaid Gantt charts. * **Using `after` with a task ID that does not exist.** The dependency target must match a task ID defined earlier in the chart. A typo in the task ID will produce a confusing error or an incorrect layout. * **Omitting the `0d` duration for milestones.** Milestones must have a duration of `0d`. Without it, Mermaid treats them as regular tasks with a one-day duration. * **Placing `title` after tasks.** The `title`, `dateFormat`, `axisFormat`, and `excludes` directives must appear before any task definitions. Putting them after a `section` or task line will cause a parse error. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [All 30 Mermaid diagram types in Confluence](/blog/faq-mermaid-diagram-types-confluence.md) -- complete reference across every diagram type * [Mermaid Plus Diagrams & AI Agent for Confluence usage guide](/apps/mermaid-plus-for-confluence.md) -- detailed configuration options, theme settings, and all 30 supported diagram types * [Excalidraw Plus for Confluence](/apps/excalidraw-plus-for-confluence.md) -- visual drawing with 220+ shape libraries for architecture and design diagrams * [Diagram Duo for Confluence](/apps/excalidraw-mermaid-diagrams-for-confluence.md) -- combined Mermaid + Excalidraw editor in one macro, ideal for teams that need both Gantt charts and visual diagrams * [Mermaid Syntax Cheat Sheet](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md) -- quick reference for all Mermaid diagram types supported in Confluence * [Confluence diagram tools compared](/blog/confluence-diagram-tools-comparison.md) -- side-by-side comparison of Mermaid, PlantUML, Draw\.io, and Lucidchart for Confluence * [Sequence diagrams in Confluence](/blog/how-to-create-sequence-diagrams-confluence.md) -- Mermaid sequence diagram examples for API and system interactions * [Mind maps from Markdown outlines](/blog/markdown-mind-map-confluence.md) -- turn planning notes into an interactive mind map, no drawing * [Architecture diagrams in Confluence](/blog/how-to-create-architecture-diagrams-confluence.md) -- three methods with copy-paste Mermaid examples * [Wireframes in Confluence](/blog/how-to-create-wireframes-confluence.md) -- low-fidelity UI mockups with the Excalidraw macro * [Excalidraw vs draw.io for Confluence](/blog/faq-excalidraw-vs-drawio-confluence.md) -- when a whiteboard canvas beats a code-based diagram tool Gantt charts are a practical, high-leverage addition to your Confluence documentation. A well-structured Mermaid Gantt chart takes minutes to create, lives alongside your project context, and stays current with a simple text edit. Install [Mermaid Plus](/apps/mermaid-plus-for-confluence.md) or [Diagram Duo](/apps/excalidraw-mermaid-diagrams-for-confluence.md), paste one of the examples above into a page, and start building your project timelines today. ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [gantt](/blog/tags/gantt.md) * [how-to](/blog/tags/how-to.md) * [diagrams](/blog/tags/diagrams.md) * [project-management](/blog/tags/project-management.md) --- # Create Jira Issue Templates — Import from GitHub, Markdown & Rich Text May 2, 2026 · 16 min read [NGPilot](https://ngpilot.com) Every team that uses Jira long enough runs into the same problem: inconsistent tickets. One developer files a detailed bug report with reproduction steps, environment details, and screenshots. Another submits a two-line summary with no context. Product managers write user stories that vary wildly in structure, making backlog grooming slower than it needs to be. Support teams log incidents using different formats depending on who is on shift. These inconsistencies compound over time and erode the reliability of your Jira data, making reports unreliable and sprint planning harder than necessary. Issue templates solve this by standardizing the structure and content of every new ticket. When you create a Jira issue template, every bug report follows the same format, every user story has the same sections, and every task includes the same checklists. The result is faster ticket creation, better reporting, and a shared understanding of what "done" looks like across the team. This tutorial walks you through the complete process of creating and using issue templates in Jira with **Modern Issue Templates for Jira**, a Forge-based app that supports rich text formatting, automatic template application, GitHub import, and multi-project sharing. By the end, you will have working templates for bug reports, user stories, and sprint tasks that apply automatically whenever someone creates an issue in your projects. ## Why use issue templates in Jira?[​](#why-use-issue-templates-in-jira "Direct link to Why use issue templates in Jira?") Before diving into the setup, it is worth understanding why issue templates are worth the investment. Teams that adopt templates consistently report four key benefits: * **Faster ticket creation.** Pre-filled fields mean less typing. Instead of starting from a blank screen, team members fill in the sections that matter and skip the boilerplate that the template already provides. * **Consistent descriptions.** Every bug report, feature request, or incident follows the same structure. This makes it dramatically easier for anyone reviewing the backlog to find the information they need without hunting through paragraphs of freeform text. * **Better reporting.** Standardized fields make JQL queries and dashboards more reliable. When every bug has an "Environment" section and every story has "Acceptance criteria," you can build filters and reports that actually work. * **Faster onboarding.** New team members see the expected format immediately. Templates encode institutional knowledge about what a good ticket looks like, so newcomers do not have to guess. ## Template types you should create[​](#template-types-you-should-create "Direct link to Template types you should create") Most teams need templates for the following issue types. Each serves a distinct purpose and benefits from a different structure: * **Bug report template** -- captures reproduction steps, expected vs. actual behavior, environment details, and severity assessment. This is the most commonly used template in engineering teams. * **User story template** -- structures feature requests around the problem statement, proposed solution, acceptance criteria, and out-of-scope items. Product managers and designers benefit most from this one. * **Task template** -- standardizes sprint tasks with clear descriptions, subtasks, and completion checklists. Useful for tracking work that supports a larger story or epic. * **Epic template** -- provides a high-level structure for initiatives that span multiple sprints, including goals, key results, affected teams, and milestone dates. * **Spike template** -- frames research and investigation work with a clear question to answer, time-boxed effort, and expected deliverable. Prevents open-ended research tickets that never close. You do not need to create all of these at once. Start with the one or two issue types your team uses most frequently and expand from there. ## Step-by-step: Create and use issue templates in Jira[​](#step-by-step-create-and-use-issue-templates-in-jira "Direct link to Step-by-step: Create and use issue templates in Jira") ### Step 1 -- Install Modern Issue Templates for Jira[​](#step-1----install-modern-issue-templates-for-jira "Direct link to Step 1 -- Install Modern Issue Templates for Jira") Head to the Atlassian Marketplace and search for **Modern Issue Templates for Jira**. Click **Get App** and follow the installation prompts. The app runs on Jira Cloud using the Forge platform, which means it installs quickly and does not require any server-side configuration. If your organization requires admin approval for marketplace apps, send the app link to your Jira administrator and request installation. The process typically takes under a minute once approved. After installation, access the template manager through the **Apps** menu in the top navigation of your Jira site. Select **Modern Issue Templates** from the dropdown. You will see the template management interface -- an empty table if this is your first time using the app, or a list of any existing templates. ### Step 2 -- Create your first issue template[​](#step-2----create-your-first-issue-template "Direct link to Step 2 -- Create your first issue template") From the template manager, click the **Create Template** button in the top-right corner. A modal opens with three fields: 1. **Template Name** -- a descriptive name that helps you and your team identify the template. Use clear names like "Bug Report" or "User Story -- Product Team" rather than generic labels. 2. **Summary** -- the text that will pre-fill the issue summary field when the template is applied. For a bug report, you might use `Bug: [brief description]`. For a user story, `Story: [feature name]`. 3. **Description** -- the rich text content that will pre-fill the issue description. This is where you define the structure, sections, and placeholders that make up the body of the template. Fill in all three fields and click **Save**. The template appears in your template table immediately. If you are creating a bug report template, the summary might be `Bug: [summary]` and the description would contain the structured format we will build in the next step. #### Importing templates from GitHub or files[​](#importing-templates-from-github-or-files "Direct link to Importing templates from GitHub or files") If your team already has issue templates stored elsewhere, you can skip manual creation and import them directly: * **From GitHub repository.** Click **Import Templates**, select the **From GitHub URL** tab, and paste a direct file URL such as `https://github.com/username/repo/blob/main/.github/ISSUE_TEMPLATE/bug_report.md`. The app fetches the file, extracts YAML frontmatter (name, title, labels), and converts the markdown body to rich text. * **From GitHub Gist.** Select the **From GitHub Gist** tab and paste a Gist URL. All markdown files in the Gist are imported as separate templates. * **From file.** Select the **From File** tab and upload a `.json` or `.md` file. JSON exports from this app are supported, as are standard markdown files with optional YAML frontmatter. GitHub import is particularly valuable for engineering teams that already maintain issue templates in their `.github/ISSUE_TEMPLATE/` directory. Rather than maintaining two separate sets of templates -- one in GitHub and one in Jira -- you can use the GitHub repository as the single source of truth and re-import whenever templates change. ### Step 3 -- Configure template fields and formatting[​](#step-3----configure-template-fields-and-formatting "Direct link to Step 3 -- Configure template fields and formatting") The description editor in Modern Issue Templates supports full rich text formatting. Use the toolbar to add structure that guides whoever fills in the ticket: **Formatting options available:** * Bold, italic, and strikethrough text for emphasis * Headings (H1 through H6) to organize sections * Bullet lists and numbered lists for steps and checklists * Code blocks with syntax highlighting for technical content * Links to external resources, internal Confluence pages, or other Jira issues * Tables for structured data like environment configurations or test matrices The goal is to create a template where the structure is obvious and the person creating the issue only needs to fill in the blanks. Well-formatted templates reduce cognitive load and produce better tickets. #### Inline editing for quick updates[​](#inline-editing-for-quick-updates "Direct link to Inline editing for quick updates") You can edit template summaries and descriptions directly in the template table without opening the full editor. Click on any summary cell to make it editable -- press Enter or click outside to save. Click on any description cell to open a compact rich text editor. This is useful for small adjustments like updating a section heading or fixing a typo without navigating to the full editor modal. ### Step 4 -- Assign templates to projects and issue types[​](#step-4----assign-templates-to-projects-and-issue-types "Direct link to Step 4 -- Assign templates to projects and issue types") Templates only work when they are connected to the projects and issue types where they should apply. To assign a template: 1. Click the **Assign to Project** button (the link icon) in the Actions column of the template table. 2. In the assignment dialog, select one or more projects from the dropdown. 3. Select the issue types that should use this template (Bug, Story, Task, etc.). 4. Click **Save**. Assigned projects appear as colored badges in the Projects column of the template table. If a template is assigned to more than three projects, you will see a "+N more" indicator. The recommended approach is to map each issue type to exactly one template per project. For example, in your main engineering project, the Bug issue type maps to the Bug Report template, the Story issue type maps to the User Story template, and the Task issue type maps to the Sprint Task template. This one-to-one mapping keeps things predictable and ensures every new issue gets a template. ### Step 5 -- Use templates when creating issues[​](#step-5----use-templates-when-creating-issues "Direct link to Step 5 -- Use templates when creating issues") Once templates are assigned, the automation kicks in. Here is how it works in practice: 1. Open the issue creation screen in Jira. 2. Select the project where your templates are assigned. 3. Select the issue type (Bug, Story, Task, etc.). 4. The app detects the matching template and automatically pre-fills the summary and description fields. 5. Fill in the issue-specific details -- the sections, steps, and information unique to this particular ticket. 6. Click **Create** to submit the issue with the full template content. The template respects any content the user has already entered. If a user starts typing in the description field before the template loads, the template will not overwrite their work. This prevents accidental data loss while still providing the structure for new, blank issues. When a user changes the issue type after the template has been applied, the app clears the pre-filled content and applies the new template that matches the updated issue type. This ensures the template always matches the selected issue type. ## Template examples with field structures[​](#template-examples-with-field-structures "Direct link to Template examples with field structures") The following three templates are designed to cover the most common issue types in Jira. You can copy these structures directly into Modern Issue Templates and customize them for your team. ### Bug report template[​](#bug-report-template "Direct link to Bug report template") This is the most widely used template in engineering teams. A well-structured bug report template ensures every defect has enough information for a developer to start investigating without asking clarifying questions. **Template Name:** Bug Report **Summary:** `Bug: [brief description of the issue]` **Description:** ``` ## Steps to Reproduce 1. 2. 3. ## Expected Result ## Actual Result ## Environment - Browser / OS: - App version: - Environment (dev / staging / production): ## Severity - [ ] Critical -- system down or data loss - [ ] High -- major feature broken - [ ] Medium -- feature partially broken, workaround available - [ ] Low -- minor visual or UX issue ## Attachments / Screenshots ## Additional Context ``` The bug report template captures the essential information a developer needs to reproduce and fix the defect. The "Steps to Reproduce" section uses a numbered list so the reporter can describe the exact sequence of actions. The "Environment" section ensures the developer knows where to look. The severity checklist gives the reporter a structured way to communicate urgency without guessing at a priority level. ### User story template[​](#user-story-template "Direct link to User story template") Product managers and designers benefit from a user story template that frames feature requests around user needs and measurable outcomes. **Template Name:** User Story **Summary:** `Story: [feature name]` **Description:** ``` ## User Story As a [type of user], I want to [action] so that [benefit]. ## Problem Statement ## Proposed Solution ## Acceptance Criteria - [ ] - [ ] - [ ] ## Design References ## Out of Scope ## Dependencies ``` The user story template starts with the classic "As a... I want to... so that..." format, which keeps the focus on user value rather than implementation details. The acceptance criteria checklist is critical because it defines the conditions that must be met for the story to be considered complete. The "Out of Scope" section prevents scope creep by explicitly calling out what this story does not cover. ### Sprint task template[​](#sprint-task-template "Direct link to Sprint task template") Sprint tasks are the granular work items that support larger stories and epics. A sprint task template ensures each piece of work has a clear description, definition of done, and relevant context. **Template Name:** Sprint Task **Summary:** `Task: [brief description]` **Description:** ``` ## Objective ## Parent Story / Epic ## Description ## Subtasks - [ ] - [ ] - [ ] ## Definition of Done - [ ] Code written and reviewed - [ ] Unit tests pass - [ ] Integration tests pass - [ ] Documentation updated - [ ] Deployed to staging ## Notes / Context ``` The sprint task template is designed for individual contributors who pick up work during a sprint. The "Parent Story / Epic" field links the task to its broader context, which is essential for backlog management. The "Definition of Done" checklist provides a standard set of completion criteria that can be customized per team. ## Rich text formatting tips for templates[​](#rich-text-formatting-tips-for-templates "Direct link to Rich text formatting tips for templates") The quality of your templates depends not just on the structure but on how the content is formatted. Modern Issue Templates provides a full rich text editor, and using it effectively makes your templates easier to fill in and more likely to be adopted. **Use headings to create clear sections.** H2 headings for major sections like "Steps to Reproduce" and H3 for subsections. This creates a visual hierarchy that makes the template scannable. **Use checklists for repeatable criteria.** Checkboxes (`- [ ]`) are supported in the editor and give reporters a clear, interactive way to mark off items. Use them for acceptance criteria, definition of done, severity assessment, and any other yes/no decisions. **Use code blocks for technical content.** If your template includes API payloads, SQL queries, or configuration snippets, wrap them in code blocks with the appropriate language tag for syntax highlighting. This makes the template content more readable and signals to the reporter where technical details should go. **Keep placeholder text obvious.** Use brackets like `[brief description]` or `[type of user]` to mark fields that the reporter needs to fill in. This distinguishes template instructions from permanent content and makes it clear what needs to be replaced. **Use tables for structured comparisons.** If your template includes environment details or test matrices, use tables to present the information in a compact, organized format. ## GitHub import for engineering teams[​](#github-import-for-engineering-teams "Direct link to GitHub import for engineering teams") For teams that already maintain issue templates in GitHub, the import feature eliminates duplicate work. Here is how to make the most of it: 1. **Store templates in your repository.** Keep templates in `.github/ISSUE_TEMPLATE/` alongside your code. This makes them reviewable through pull requests and version-controlled just like any other file in the repository. 2. **Use YAML frontmatter.** GitHub issue templates support YAML frontmatter at the top of the file. The app extracts the `name` field as the template name, the `title` field as the summary template, and the `labels` field for metadata. The body of the markdown file becomes the template description. 3. **Import and assign.** After importing, assign the templates to your Jira projects and issue types. The imported templates work exactly like manually created ones -- they support auto-apply rules, inline editing, and export. 4. **Re-import when templates change.** When your team updates a template in GitHub (after a pull request review), re-import it to update the Jira version. The app handles duplicate names by appending a number suffix, so you can rename the updated version and delete the old one. ## Best practices for managing templates[​](#best-practices-for-managing-templates "Direct link to Best practices for managing templates") ### Start with one project[​](#start-with-one-project "Direct link to Start with one project") Rolling out templates to every project simultaneously is tempting but risky. Differences in team workflows, custom fields, and issue type schemes mean that a template that works perfectly in one project may need adjustments in another. Start with your most active project or the team that has the strongest need for consistency. Validate the templates and auto-apply rules in that context, gather feedback, and iterate before expanding. ### Map every issue type to a template[​](#map-every-issue-type-to-a-template "Direct link to Map every issue type to a template") Do not leave any issue type without a corresponding template. If you have Bug, Story, Task, Epic, and Spike issue types, you should have at least five templates. When a team member creates an issue and no template applies, that is a gap in your system. Configure auto-apply rules for every issue type in every project where templates are active. ### Review templates quarterly[​](#review-templates-quarterly "Direct link to Review templates quarterly") Templates are not set-and-forget. As your team's processes evolve, your templates should evolve with them. Schedule a quarterly review where a project manager or team lead examines each active template and asks whether the format still matches the team's current workflow. Have new fields become important? Have some sections become unnecessary? Update the templates to reflect the current reality. ### Export templates as backups[​](#export-templates-as-backups "Direct link to Export templates as backups") Use the export feature to download your templates as a JSON file. This serves as a backup in case of accidental deletion and makes it easy to share template configurations between Jira instances. Select the templates you want to export using the checkboxes in the template table and click **Export Selected**. The file is named `templates-export-{timestamp}.json`. ### Clone templates for variations[​](#clone-templates-for-variations "Direct link to Clone templates for variations") If you need a slightly different version of an existing template (for example, a bug report template for mobile vs. web), use the **Clone** action to create a copy and modify it. This is faster than creating a new template from scratch and ensures consistency across variations. ## Troubleshooting common issues[​](#troubleshooting-common-issues "Direct link to Troubleshooting common issues") ### Template not applying automatically[​](#template-not-applying-automatically "Direct link to Template not applying automatically") Check three things: (1) Is the template assigned to the correct project? (2) Is the template assigned to the correct issue type? (3) Has the user already entered content in the description field? Templates only apply to blank fields to prevent overwriting user input. ### Import fails from GitHub[​](#import-fails-from-github "Direct link to Import fails from GitHub") Common causes include 404 errors (the file URL is incorrect or the file does not exist), 403 errors (the repository is private or requires authentication), and rate limiting (GitHub API has rate limits; wait a few minutes and try again). Make sure you are using a direct file URL, not a directory URL. ### Formatting lost after import[​](#formatting-lost-after-import "Direct link to Formatting lost after import") Markdown conversion preserves most formatting, but some complex HTML in markdown files may not convert perfectly. After importing, open the template in the editor and adjust any formatting that did not translate correctly. The rich text editor makes this quick. ## What to do next[​](#what-to-do-next "Direct link to What to do next") Now that you have issue templates configured for your Jira projects, here are the logical next steps to get even more value from your template system: * **Expand coverage.** Create templates for any remaining issue types that do not yet have one. Epics, spikes, and sub-tasks are common gaps. * **Share across projects.** Use the Assign to Project feature to roll your validated templates out to additional projects. * **Automate with Jira Automation.** Combine Modern Issue Templates with Jira's built-in automation rules to create workflows that trigger on template-applied issues. * **Gather feedback.** After your team has used the templates for a sprint or two, collect feedback on what works and what does not. Templates improve with iteration. For the complete feature documentation, visit the [Modern Issue Templates for Jira user guide](/docs/Modern-Issue-Templates-for-Jira/user-docs.md). ## Related resources[​](#related-resources "Direct link to Related resources") * [Modern Issue Templates for Jira -- documentation](/apps/modern-issue-templates-for-jira.md) -- full setup guide, feature reference, and troubleshooting * [Issue Templates for Jira — Which Template App?](/blog/jira-issue-templates-comparison.md) -- how the app compares against Deviniti, Templating.app, and other marketplace options * [Jira Issue Templates FAQ: Auto-Apply, Variables & Automation](/blog/faq-jira-issue-templates-automation.md) -- answers to common questions about template variables, GitHub import, and multi-project sharing * [Best Confluence apps for developers](/blog/best-confluence-apps-developers.md) -- complementary Confluence apps for developer productivity Try Modern Issue Templates for Jira Create issues from reusable templates with variables, GitHub import, and auto-apply — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/2564635381/modern-issue-templates-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-issue-templates-for-jira) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [issue-templates](/blog/tags/issue-templates.md) * [how-to](/blog/tags/how-to.md) * [jira-templates](/blog/tags/jira-templates.md) * [automation](/blog/tags/automation.md) --- # How to Create Math and Technical Animations in Confluence Using Manim May 2, 2026 · 23 min read [NGPilot](https://ngpilot.com) Mathematical concepts are inherently dynamic. A limit converges, a derivative emerges from shrinking secant lines, a matrix transformation rotates a vector through space. Static screenshots and LaTeX formulas capture the result but miss the process -- and for many students and colleagues, the process is where understanding lives. Animations bridge that gap. They show how equations transform, how geometric constructions unfold step by step, and how abstract algebra connects to visual intuition. Until recently, embedding math animations in documentation required a multi-tool workflow: write Python scripts with Manim, render MP4 files locally, upload them as attachments or embed them via external hosting, and hope nobody asked you to update them. Manim for Confluence eliminates that entire pipeline. You write animation code directly inside a Confluence macro, and the animation plays inline on the published page -- no file exports, no external hosting, no broken links when the video expires. In this tutorial, you will learn how to create math and technical animations in Confluence using Manim for Confluence. We cover the fundamentals of the Manim scene API, walk through the macro configuration, and build several copy-paste-ready examples including equation derivations, shape transformations, and geometric proofs. By the end, you will be able to embed rich, interactive animations directly in your Confluence documentation. ## What is Manim?[​](#what-is-manim "Direct link to What is Manim?") Manim is an open-source animation engine originally created by 3Blue1Brown (Grant Sanderson) for producing the math animations that power his YouTube channel. It provides a programmatic API for creating precise mathematical visualizations -- shapes, equations, graphs, transformations, and animated sequences -- all defined in code rather than drawn by hand. The engine has since grown into two active projects: the original Manim (often called ManimGL) and the community edition ManimCE. Both share the same core philosophy: describe what should appear on screen using code, and the engine handles rendering frames, interpolation, and timing. Manim for Confluence brings this capability directly into Confluence. Instead of rendering videos on your local machine, you write Manim-compatible scene code inside a macro editor on the Confluence page itself. The animation runs in the browser when someone views the page. This means your team's technical documentation, educational content, and internal wikis can include animated mathematical visualizations without any external tooling. ### Why animate math in Confluence?[​](#why-animate-math-in-confluence "Direct link to Why animate math in Confluence?") Static diagrams work well for simple concepts, but they fall short when you need to communicate movement, transformation, or sequential construction. Consider these scenarios where animations outperform static images: * **Education and training.** When onboarding new engineers or teaching mathematical concepts to non-specialists, an animation that shows a Fourier series converging to a square wave is far more effective than a series of still frames or a paragraph of text. * **Proof visualization.** Geometric proofs often involve construction steps -- draw a perpendicular, bisect an angle, rotate a triangle. An animation walks the viewer through each step in order, making the logical structure of the proof visible. * **Algorithm explanation.** Sorting algorithms, graph traversals, and matrix operations are easier to understand when you can watch the data structure change state over time. * **Design rationale.** When presenting architectural or mathematical design decisions in Confluence, an animated diagram can show why a particular approach works, not just that it works. Confluence is where your team already reads documentation. Putting animations there instead of linking to external videos or GIF attachments means the content is searchable, version-controlled, and always accessible alongside the surrounding context. ## Step-by-step tutorial: Creating math animations in Confluence[​](#step-by-step-tutorial-creating-math-animations-in-confluence "Direct link to Step-by-step tutorial: Creating math animations in Confluence") ### Step 1 -- Install Manim for Confluence[​](#step-1----install-manim-for-confluence "Direct link to Step 1 -- Install Manim for Confluence") Manim for Confluence is distributed through the Atlassian Marketplace. To install it: 1. Navigate to your Confluence site and click the **gear icon** (Settings) in the top right corner. 2. Select **Manage apps** from the left sidebar. 3. Click **Find new apps** and search for **Manim for Confluence**. 4. Click **Install** on the app listing and follow the prompts. You need Confluence Administrator permissions to install apps. Once installed, the macro is available on every page in your Confluence instance -- there is no per-space configuration needed. ### Step 2 -- Insert the Manim macro on a page[​](#step-2----insert-the-manim-macro-on-a-page "Direct link to Step 2 -- Insert the Manim macro on a page") Open or create a Confluence page and enter **Edit** mode. Click the **+** (Insert) button in the editor toolbar, or type `/` in the page body to open the macro browser. Search for **Manim** and select **Manim for Confluence** from the results. The macro configuration panel opens immediately. This panel has three main areas: * **Top bar** with Save, Cancel, and Help controls * **Toolbar** with canvas dimensions, background color picker, and template quick-start buttons * **Preview panel** showing a live render of your animation * **Code editor** at the bottom, powered by Monaco (the same editor engine as VS Code) ### Step 3 -- Write your animation code[​](#step-3----write-your-animation-code "Direct link to Step 3 -- Write your animation code") The code editor accepts Manim scene API code. All Manim exports are available as global variables -- you do not need to write import statements. The `scene` object is injected automatically. Here is the simplest possible animation: ``` const circle = new Circle({ radius: 1.5, color: BLUE }); await scene.play(new Create(circle)); await scene.wait(1); await scene.play(new FadeOut(circle)); ``` This code creates a blue circle, animates it being drawn onto the canvas, waits one second, then fades it out. The preview panel updates automatically as you type, so you can see the result immediately. If you are new to Manim, start with one of the built-in templates by clicking a template button in the toolbar. The templates include: * **Basic** -- Creates, transforms, and fades shapes (circle to square to triangle) * **Manim Logo** -- Recreates the Manim CE logo using grouped shapes and LaTeX * **Sine Curve** -- Animates a dot tracing a sine wave with a rotating circle * **Moving Angle** -- Animates an angle label using a ValueTracker * **Boolean Ops** -- Demonstrates union, intersection, and difference of ellipses * **Point Trace** -- A dot that leaves a visible trail as it moves Clicking a template loads its code into the editor and refreshes the preview instantly. This is the fastest way to learn the API -- load a template, modify a parameter, and watch how the animation changes. ### Step 4 -- Configure canvas and playback settings[​](#step-4----configure-canvas-and-playback-settings "Direct link to Step 4 -- Configure canvas and playback settings") The toolbar provides controls for the visual canvas: | Setting | Description | Default | | ----------- | -------------------------------------- | --------- | | Width (px) | Canvas width in pixels | 800 | | Height (px) | Canvas height in pixels | 450 | | Background | Color picker for the canvas background | `#1C1C1C` | Advanced settings control playback behavior: | Setting | Description | Default | | ------------------------ | ----------------------------------------------------------------------------- | -------------- | | Autoplay | Whether the animation starts automatically on page load | `true` | | Playback speed | Multiplier for animation speed (0.25x to 2x) | `1` | | Controls auto-hide delay | Milliseconds before player controls fade out | `2500` | | Controls position | Where player controls appear (top-left, top-right, bottom-left, bottom-right) | `bottom-right` | | Controls theme | Light or dark player controls | `dark` | Set the canvas dimensions to match your layout. A wide canvas (1000x450) works well for equation derivations that extend horizontally. A square canvas (600x600) is better for geometric constructions that need balanced vertical and horizontal space. ### Step 5 -- Save, publish, and share[​](#step-5----save-publish-and-share "Direct link to Step 5 -- Save, publish, and share") Click **Save** on the macro configuration panel to persist your animation code and settings. Then click **Publish** on the Confluence page. The animation renders inline wherever you placed the macro. Visitors do not need any plugins, extensions, or special browser settings. The animation runs entirely in the browser using standard web technologies. If autoplay is enabled, the animation starts as soon as the page loads. Otherwise, viewers use the playback controls overlaid on the canvas to play, pause, and scrub through the animation. To edit an existing animation, open the page in Edit mode, click the Manim macro block, click the **Edit** (pencil) icon, and the configuration panel reopens with your previously saved code and settings. ## The Manim scene API in Manim for Confluence[​](#the-manim-scene-api-in-manim-for-confluence "Direct link to The Manim scene API in Manim for Confluence") Manim for Confluence uses a browser-based rendering engine that implements the core Manim scene API. This section covers the key concepts and classes you will use when writing animations. ### Scene lifecycle[​](#scene-lifecycle "Direct link to Scene lifecycle") Every animation runs within a `scene` object that is provided automatically. You call `scene.play()` to execute animations and `scene.wait()` to pause between them. The `await` keyword is required before each `scene.play()` and `scene.wait()` call because animations execute asynchronously. ``` await scene.play(new Create(shape)); await scene.wait(0.5); await scene.play(new Transform(shape, target)); await scene.wait(1); ``` ### Mobject classes[​](#mobject-classes "Direct link to Mobject classes") Mobjects (mathematical objects) are the building blocks of Manim animations. Here are the most commonly used classes: | Class | Description | Example | | ------------- | -------------------------------------- | --------------------------------------------------------- | | `Circle` | A circle with configurable radius | `new Circle({ radius: 2, color: BLUE })` | | `Square` | A square with configurable side length | `new Square({ sideLength: 2, color: RED })` | | `Triangle` | An equilateral triangle | `new Triangle({ color: GREEN })` | | `Line` | A line segment between two points | `new Line([-3, 0, 0], [3, 0, 0])` | | `Arrow` | A line with an arrowhead | `new Arrow([-2, 1, 0], [2, 1, 0])` | | `MathTex` | LaTeX-rendered equation | `new MathTex("E = mc^2")` | | `Tex` | LaTeX-rendered text | `new Tex("Theorem 1")` | | `Text` | Plain text label | `new Text("Step 1")` | | `Dot` | A filled point | `new Dot([1, 2, 0])` | | `NumberPlane` | A coordinate grid | `new NumberPlane()` | | `Polygon` | A polygon from vertex coordinates | `new Polygon([0,0,0], [1,0,0], [1,1,0])` | | `Arc` | A partial circle arc | `new Arc({ radius: 1, startAngle: 0, angle: Math.PI/2 })` | All mobjects support common configuration options: `color`, `fillOpacity`, `strokeWidth`, and positioning methods like `.moveTo()`, `.shift()`, `.scale()`, and `.rotate()`. ### Animation classes[​](#animation-classes "Direct link to Animation classes") Animation classes define how mobjects appear, change, and disappear. Pass them to `scene.play()`: | Class | Description | | ---------------------- | --------------------------------------------------- | | `Create` | Draws the outline of a shape progressively | | `FadeIn` | Fades a mobject from transparent to visible | | `FadeOut` | Fades a mobject from visible to transparent | | `Transform` | Smoothly morphs one mobject into another | | `ReplacementTransform` | Like Transform, but replaces the source mobject | | `Write` | Animates text being written character by character | | `Indicate` | Flashes or highlights an existing mobject | | `GrowFromCenter` | Scales a mobject up from zero at its center | | `MoveToTarget` | Moves a mobject to a previously set target position | ### Coordinate system[​](#coordinate-system "Direct link to Coordinate system") Manim uses a coordinate system where the origin `(0, 0)` is at the center of the canvas. The x-axis extends left to right, and the y-axis extends bottom to top. Coordinates are specified as arrays: `[x, y, z]`. The z-coordinate is typically `0` for 2D animations. The visible range depends on the canvas aspect ratio. By default, the x-axis spans roughly from -7 to 7 and the y-axis from -4 to 4. Adjust the canvas dimensions in the toolbar if your animation needs more space in a particular direction. ## Copy-paste example 1: Equation derivation with LaTeX[​](#copy-paste-example-1-equation-derivation-with-latex "Direct link to Copy-paste example 1: Equation derivation with LaTeX") This example demonstrates an animated equation derivation. It shows the quadratic formula being derived step by step, with each transformation highlighted as it happens. This pattern is useful for educational content, lecture notes, and any documentation that walks through mathematical proofs. ``` // Animated quadratic formula derivation const eq1 = new MathTex( "ax^2 + bx + c = 0" ).moveTo([0, 2, 0]); const eq2 = new MathTex( "x^2 + {b \\over a}x + {c \\over a} = 0" ).moveTo([0, 0.5, 0]); const eq3 = new MathTex( "x^2 + {b \\over a}x = -{c \\over a}" ).moveTo([0, -1, 0]); const eq4 = new MathTex( "x^2 + {b \\over a}x + {b^2 \\over 4a^2} = {b^2 \\over 4a^2} - {c \\over a}" ).moveTo([0, -2.5, 0]); const eq5 = new MathTex( "\\left(x + {b \\over 2a}\\right)^2 = {b^2 - 4ac \\over 4a^2}" ).moveTo([0, -4, 0]); const title = new Text("Quadratic Formula Derivation", { color: YELLOW, fontSize: 28 }).moveTo([0, 3.5, 0]); // Animate step by step await scene.play(new Write(title)); await scene.wait(0.5); await scene.play(new Write(eq1)); await scene.wait(1); await scene.play(new Transform(eq1, eq2)); await scene.wait(1); await scene.play(new Transform(eq1, eq3)); await scene.wait(1); await scene.play(new Transform(eq1, eq4)); await scene.wait(1); await scene.play(new Transform(eq1, eq5)); await scene.wait(2); await scene.play(new FadeOut(eq1), new FadeOut(title)); ``` **How this works:** 1. Each equation step is defined as a `MathTex` object with LaTeX syntax. The `moveTo()` method positions each equation vertically. 2. `Write` animates the title appearing character by character. 3. `Transform` morphs one equation into the next, creating a smooth visual transition between derivation steps. 4. `scene.wait()` adds pauses between steps so viewers can read each equation before it transforms. 5. The final `FadeOut` cleans up the canvas. **Customization tips:** * Change the LaTeX strings to animate any equation derivation you need -- Taylor series, integration by parts, matrix decompositions. * Add `color` properties to highlight changed terms: `new MathTex("\\color{red}{b^2} \\over 4a^2")`. * Use `fontSize` in the `MathTex` constructor to scale equations up or down. * Position steps horizontally by adjusting the x-coordinate in `moveTo()` if you want to show the derivation left-to-right instead of top-to-bottom. ## Copy-paste example 2: Geometric proof animation[​](#copy-paste-example-2-geometric-proof-animation "Direct link to Copy-paste example 2: Geometric proof animation") This example animates a classic geometric construction: proving that the angles of a triangle sum to 180 degrees. It constructs a triangle, labels the angles, then visually folds the angles into a straight line. This is the kind of animation that makes abstract proofs tangible for students and reviewers. ``` // Geometric proof: Angles of a triangle sum to 180 degrees // Define triangle vertices const A = [-2, -1.5, 0]; const B = [2, -1.5, 0]; const C = [0, 2, 0]; // Create the triangle const triangle = new Polygon(A, B, C, { color: WHITE, strokeWidth: 3 }); // Create angle arcs at each vertex const angleA = new Arc({ radius: 0.5, startAngle: Math.atan2(B[1] - A[1], B[0] - A[0]), angle: 0.7, color: YELLOW }).moveTo([A[0] + 0.3, A[1] + 0.2, 0]); const angleB = new Arc({ radius: 0.5, startAngle: Math.atan2(C[1] - B[1], C[0] - B[0]), angle: 0.6, color: BLUE }).moveTo([B[0] - 0.3, B[1] + 0.2, 0]); const angleC = new Arc({ radius: 0.5, startAngle: Math.PI + Math.atan2(A[1] - C[1], A[0] - C[0]), angle: 0.8, color: RED }).moveTo([C[0] - 0.15, C[1] - 0.25, 0]); // Labels const labelA = new Text("a", { color: YELLOW, fontSize: 22 }) .moveTo([A[0] + 0.7, A[1] + 0.5, 0]); const labelB = new Text("b", { color: BLUE, fontSize: 22 }) .moveTo([B[0] - 0.7, B[1] + 0.5, 0]); const labelC = new Text("c", { color: RED, fontSize: 22 }) .moveTo([C[0] + 0.3, C[1] - 0.5, 0]); const vertexLabels = new Tex("A", { color: WHITE }) .moveTo([-2.4, -1.9, 0]); const vertexLabelB = new Tex("B", { color: WHITE }) .moveTo([2.4, -1.9, 0]); const vertexLabelC = new Tex("C", { color: WHITE }) .moveTo([0, 2.5, 0]); // Title const title = new Text("Angles in a Triangle Sum to 180\u00B0", { color: YELLOW, fontSize: 26 }).moveTo([0, 3.5, 0]); // Step 1: Draw the triangle await scene.play(new Write(title)); await scene.wait(0.5); await scene.play(new Create(triangle)); await scene.play( new FadeIn(vertexLabels), new FadeIn(vertexLabelB), new FadeIn(vertexLabelC) ); await scene.wait(0.5); // Step 2: Show the angles await scene.play( new Create(angleA), new Create(angleB), new Create(angleC) ); await scene.play( new FadeIn(labelA), new FadeIn(labelB), new FadeIn(labelC) ); await scene.wait(1); // Step 3: Show the straight line proof const straightLine = new Line([-3, -3, 0], [3, -3, 0], { color: WHITE, strokeWidth: 2 }); const proofAngle1 = new Arc({ radius: 0.5, startAngle: 0, angle: 0.7, color: YELLOW }).moveTo([-1.5, -3, 0]); const proofAngle2 = new Arc({ radius: 0.5, startAngle: 0.7, angle: 0.6, color: BLUE }).moveTo([0, -3, 0]); const proofAngle3 = new Arc({ radius: 0.5, startAngle: 1.3, angle: 0.8, color: RED }).moveTo([1.5, -3, 0]); const proofLabel = new Text("a + b + c = 180\u00B0", { color: GREEN, fontSize: 28 }).moveTo([0, -4, 0]); await scene.play(new Create(straightLine)); await scene.play( new Transform(angleA, proofAngle1), new Transform(angleB, proofAngle2), new Transform(angleC, proofAngle3) ); await scene.play( new Transform(labelA, new Text("a", { color: YELLOW, fontSize: 22 }).moveTo([-1.5, -3.5, 0])), new Transform(labelB, new Text("b", { color: BLUE, fontSize: 22 }).moveTo([0, -3.5, 0])), new Transform(labelC, new Text("c", { color: RED, fontSize: 22 }).moveTo([1.5, -3.5, 0])) ); await scene.wait(0.5); await scene.play(new Write(proofLabel)); await scene.wait(2); ``` **How this works:** 1. Three vertices define the triangle. The `Polygon` constructor connects them with line segments. 2. `Arc` objects represent the interior angles at each vertex, calculated using `Math.atan2` for proper positioning. 3. Text labels identify each angle with a distinct color. 4. The animation progresses through three phases: drawing the triangle, highlighting the angles, and then transforming those angles onto a straight line to demonstrate the 180-degree sum. 5. Color coding (yellow, blue, red) makes it easy to track which angle maps where during the transformation. **Customization tips:** * Change the vertex coordinates to animate different triangle shapes. * Adapt this pattern for other geometric proofs: the Pythagorean theorem, circle theorems, or congruence proofs. * Add `scene.play(new Indicate(mobject))` calls to highlight specific elements before transforming them. * Use `MathTex` for formal proof statements instead of plain `Text` for a more mathematical look. ## Additional animation patterns[​](#additional-animation-patterns "Direct link to Additional animation patterns") Beyond equations and geometric proofs, Manim for Confluence supports a wide range of technical animation patterns. Here are several you can adapt for your own documentation. ### Shape transformations[​](#shape-transformations "Direct link to Shape transformations") The template system includes a Basic template that demonstrates the core transformation workflow: creating a circle, morphing it into a square, then into a triangle. This pattern generalizes to any mobject-to-mobject transformation: ``` const circle = new Circle({ radius: 1.5, color: BLUE }); const square = new Square({ sideLength: 2.5, color: RED }); const triangle = new Triangle({ color: GREEN }); await scene.play(new Create(circle)); await scene.wait(0.5); await scene.play(new Transform(circle, square)); await scene.wait(0.5); await scene.play(new Transform(circle, triangle)); await scene.wait(1); ``` The `Transform` animation handles interpolation automatically -- it matches the vertices of the source and target mobjects and animates the transition between them. ### Graph and function plotting[​](#graph-and-function-plotting "Direct link to Graph and function plotting") Use `NumberPlane` to create a coordinate grid, then plot functions with parametric curves: ``` const axes = new NumberPlane({ xRange: [-5, 5, 1], yRange: [-3, 3, 1], backgroundLineColor: GREY, axisColor: WHITE }); const label = new Text("f(x) = sin(x)", { color: YELLOW, fontSize: 22 }).moveTo([0, 3, 0]); await scene.play(new Create(axes)); await scene.play(new Write(label)); // Trace the sine curve const curve = axes.plot(Math.sin, { color: BLUE, strokeWidth: 3 }); const dot = new Dot(axes.coordsToPoint(0, 0), { color: RED }); await scene.play(new Create(dot)); await scene.play(new Create(curve), new MoveToTarget(dot)); await scene.wait(2); ``` This pattern is useful for visualizing mathematical functions, comparing graphs, and demonstrating calculus concepts like derivatives and integrals. ### ValueTracker for parametric animation[​](#valuetracker-for-parametric-animation "Direct link to ValueTracker for parametric animation") ValueTracker is Manim's way of creating time-dependent animations. It drives a value from one number to another, and you can use that value to control the position, scale, rotation, or color of any mobject: ``` const tracker = new ValueTracker(0); const dot = new Dot([0, 0, 0], { color: YELLOW, radius: 0.15 }); const label = new MathTex("x = 0").moveTo([0, -2, 0]); // Animate x from -3 to 3 tracker.addValueChangeListener((val) => { const x = val; dot.moveTo([x, Math.sin(x), 0]); label.setText(`x = ${x.toFixed(2)}`); }); await scene.play(new Increment(tracker, -3, { runTime: 0.001 })); await scene.play(new Increment(tracker, 6, { runTime: 4 })); ``` The Moving Angle template in the toolbar uses this exact pattern. Load it to see a complete working example. ## Rendering and playback[​](#rendering-and-playback "Direct link to Rendering and playback") Understanding how the rendering pipeline works helps you optimize animations for the best viewer experience. ### Browser-based rendering[​](#browser-based-rendering "Direct link to Browser-based rendering") Manim for Confluence renders animations entirely in the browser. When a viewer loads a Confluence page containing a Manim macro, the browser downloads the scene code, executes it using a built-in rendering engine, and plays the resulting frames as a smooth animation. This approach has several advantages: * **No server-side rendering.** The animation does not need to be pre-rendered or converted to video. Changes to the code take effect immediately on the next page load. * **Cross-platform compatibility.** The animation works in any modern browser without plugins. Chrome, Firefox, Safari, and Edge are all supported. * **Responsive playback controls.** Viewers can play, pause, and scrub through the animation. If autoplay is disabled, the viewer decides when to start watching. ### Performance considerations[​](#performance-considerations "Direct link to Performance considerations") Complex animations with many mobjects or long run times can affect browser performance. Follow these guidelines to keep animations smooth: * **Limit mobject count.** Keep the number of simultaneous on-screen mobjects under 100 for optimal frame rates. If you need more elements, consider splitting the animation into multiple sequential phases. * **Minimize simultaneous animations.** Playing five `Transform` animations at once is more demanding than playing them sequentially. Use `scene.play()` with multiple animations only when they truly need to happen in parallel. * **Use appropriate canvas dimensions.** A 1000x450 canvas renders faster than a 4000x2000 canvas. Match the canvas size to the content, not the screen size. * **Keep animations short.** For educational content, 10 to 30 seconds is the sweet spot. Longer animations can be split across multiple macros on the same page. ### Playback settings[​](#playback-settings "Direct link to Playback settings") The advanced playback settings let you fine-tune the viewing experience: * **Autoplay** is ideal for embedded animations that support surrounding text. Viewers see the animation start automatically as they scroll to it. * **Disable autoplay** for interactive demonstrations where the viewer should read instructions first, then click play. * **Playback speed** at 0.5x is useful for complex animations where viewers need to study each frame. Use 1.5x or 2x for simple transitions that do not need real-time pacing. * **Controls position** matters for layout. Place controls at `bottom-right` for left-aligned text content, or `top-left` for right-aligned layouts. The goal is to keep controls visible without overlapping important animation content. ## Troubleshooting common issues[​](#troubleshooting-common-issues "Direct link to Troubleshooting common issues") When animations do not render as expected, check these common causes: **"Loading animation..." appears but nothing plays.** The macro has not been configured yet. Click the macro to open the editor, add animation code, and save. **The animation throws an error in the preview.** Open the browser console for details. The most common causes are typos in class names (for example, `Circel` instead of `Circle`) and missing `await` before `scene.play()` calls. Every `scene.play()` and `scene.wait()` must be preceded by `await`. **The preview does not update after code changes.** The preview refreshes automatically on code changes. If it appears stuck, change the canvas width by 1 pixel and change it back. This forces a full remount of the preview component. **The animation looks cut off or misaligned.** Check your canvas dimensions. If your mobjects extend beyond the default 800x450 canvas, increase the width and height in the toolbar. Also verify that your `moveTo()` coordinates are within the visible range. **LaTeX equations do not render correctly.** Ensure that your LaTeX syntax is valid. Common issues include unescaped special characters and mismatched braces. Test your LaTeX in the preview before publishing. For additional help, click the **?** (Help) button in the macro configuration panel. It opens the full [user documentation](/docs/Manim-for-Confluence/user-docs.md) inline, so you can reference it without leaving the editor. ## Best practices for math animations in Confluence[​](#best-practices-for-math-animations-in-confluence "Direct link to Best practices for math animations in Confluence") ### Start simple and iterate[​](#start-simple-and-iterate "Direct link to Start simple and iterate") Begin with a template or a minimal animation that demonstrates your core concept. Get the basic shape or equation on screen first, then add complexity incrementally. This iterative approach is faster than trying to write a complex animation in one pass, and the live preview makes it easy to verify each change. ### Annotate with text and labels[​](#annotate-with-text-and-labels "Direct link to Annotate with text and labels") Mathematical animations are most effective when each visual element is labeled. Use `Text` for plain labels, `Tex` for mathematical notation, and `MathTex` for formatted equations. Place labels near their associated mobjects using `moveTo()` or `nextTo()` positioning. ### Use color intentionally[​](#use-color-intentionally "Direct link to Use color intentionally") Color serves two purposes in math animations: distinguishing between elements and highlighting changes. Assign distinct colors to different mathematical objects (the triangle is white, the angles are yellow, blue, and red). Use bright colors like `YELLOW` or `GREEN` to draw attention to elements that are changing or being introduced. ### Keep animations focused[​](#keep-animations-focused "Direct link to Keep animations focused") Each animation should illustrate one concept. If you need to show multiple concepts, use separate macros on the same page rather than cramming everything into one long animation. A page with three 15-second animations is more effective than a page with one 45-second animation, because viewers can re-watch specific parts independently. ### Write descriptive page content around the animation[​](#write-descriptive-page-content-around-the-animation "Direct link to Write descriptive page content around the animation") The animation is a visual aid, not a replacement for written explanation. Surround each Manim macro with text that explains what the viewer is about to see, what to pay attention to, and what the result means. This gives context to viewers who skim the page and provides searchable text for Confluence's full-text index. ### Version your animations with page history[​](#version-your-animations-with-page-history "Direct link to Version your animations with page history") Because Manim animations are stored as code in the macro, Confluence page history tracks every change. When you update an animation, the previous version is preserved. This is especially useful in educational contexts where curriculum evolves over time -- you can always revert to a previous version if an update introduces confusion. ## Security and permissions[​](#security-and-permissions "Direct link to Security and permissions") Manim for Confluence is a Forge app, which means it runs inside Atlassian's sandboxed infrastructure. The animation code executes within a secure iframe in the viewer's browser. It cannot access Confluence page content, user data, or external network resources. This sandbox model ensures that embedding animation code on shared pages is safe for all viewers. For a deeper discussion of plugin security in Confluence, read our guide on [using plugins safely](/blog/faq-using-plugins-security.md). ## Who should use Manim for Confluence[​](#who-should-use-manim-for-confluence "Direct link to Who should use Manim for Confluence") Manim for Confluence is built for teams and individuals who communicate technical concepts through documentation: * **Engineering teams** documenting algorithms, data structures, and system behavior. An animation that shows a hash table resizing or a binary tree rebalancing is more effective than a static diagram. * **Educators and trainers** creating internal learning materials. Walk students through derivations, constructions, and proofs step by step. * **Data scientists and analysts** explaining statistical concepts. Animate confidence intervals converging, distributions transforming, and regression lines fitting. * **Product managers** communicating technical requirements. Show developers exactly how a mathematical model should behave rather than describing it in prose. * **Technical writers** enriching documentation with visual explanations. A 10-second animation can replace a full page of written description for spatial or dynamic concepts. Read our roundup of [the best Confluence apps for developers](/blog/best-confluence-apps-developers.md) to see how Manim for Confluence fits alongside other tools in a modern Confluence workflow. ## Related resources[​](#related-resources "Direct link to Related resources") * [Manim for Confluence user documentation](/apps/manim-for-confluence.md) -- complete configuration reference, toolbar options, and troubleshooting guide * [Best Confluence apps for developers](/blog/best-confluence-apps-developers.md) -- curated list of developer-focused Confluence apps * [Using plugins securely in Confluence](/blog/faq-using-plugins-security.md) -- security model and permissions for Confluence apps Mathematical animations turn abstract concepts into visual experiences. With Manim for Confluence, those experiences live directly in your documentation -- searchable, versioned, and accessible to everyone on your team. Install the app from the Atlassian Marketplace, paste one of the examples above into a Confluence page, and start bringing your technical content to life. Try Manim for Confluence Render animated math equations with the Manim engine — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1384425933/manim-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=manim-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [manim](/blog/tags/manim.md) * [animation](/blog/tags/animation.md) * [math](/blog/tags/math.md) * [how-to](/blog/tags/how-to.md) * [education](/blog/tags/education.md) --- # Create Mermaid Diagrams on Jira Issues — Flowcharts, Sequence & More May 2, 2026 · 18 min read [NGPilot](https://ngpilot.com) Jira issues are where your team tracks bugs, features, and tasks every day. But describing complex processes, API interactions, or system designs in plain text often leads to confusion and misalignment. Mermaid Plus Diagrams for Jira solves this by letting you create and embed Mermaid diagrams directly on any Jira issue, so the visual context lives exactly where the work happens. No external tools, no attached images that go stale, no switching between tabs. In this tutorial, you will learn how to install the app, create your first diagram on a Jira issue, and use the right diagram types for common Jira workflows. Every Mermaid example in this guide is copy-paste ready, so you can drop it straight into your issues and see results immediately. ## Why Add Diagrams to Jira Issues?[​](#why-add-diagrams-to-jira-issues "Direct link to Why Add Diagrams to Jira Issues?") Jira tickets are the single source of truth for your team's work. When you attach a diagram to an issue, you give everyone who views that ticket an immediate visual understanding of what is happening. Here are the scenarios where diagrams on Jira issues make the biggest impact: * **Bug reproduction steps** shown as a flowchart eliminate ambiguity about the exact path a user took to trigger the defect * **API flow documentation** as sequence diagrams helps frontend and backend engineers agree on request and response patterns without leaving the ticket * **Design discussions** illustrated with class diagrams or architecture diagrams keep technical conversations grounded in a shared visual model * **Sprint planning and grooming** benefits from Gantt charts and timelines that show dependencies and critical paths right on the epic or story * **Incident post-mortems** use fishbone (Ishikawa) diagrams to trace root causes directly on the incident ticket Without embedded diagrams, teams resort to describing flows in bullet points, linking to external diagramming tools, or attaching screenshots that become outdated the moment the code changes. Mermaid diagrams on Jira issues stay current because they are text-based and can be edited in seconds. ## What You Need Before You Start[​](#what-you-need-before-you-start "Direct link to What You Need Before You Start") * A Jira Cloud instance where you have permission to install apps (or ask your Jira admin to install the app) * The **Edit Issues** permission on the project where you want to create diagrams (viewing diagrams only requires view permission on the issue) * Basic familiarity with Mermaid syntax (this guide includes examples you can copy and modify, so no prior experience is strictly required) ## Step-by-Step: Create Your First Diagram on a Jira Issue[​](#step-by-step-create-your-first-diagram-on-a-jira-issue "Direct link to Step-by-Step: Create Your First Diagram on a Jira Issue") ### Step 1 -- Install Mermaid Plus Diagrams for Jira[​](#step-1----install-mermaid-plus-diagrams-for-jira "Direct link to Step 1 -- Install Mermaid Plus Diagrams for Jira") Head to the [Atlassian Marketplace](https://marketplace.atlassian.com/) and search for **Mermaid Plus Diagrams for Jira**. Click **Get App** and follow the installation prompts. The app is available for Jira Cloud. Once installed, the Mermaid Plus Diagrams panel becomes available on every issue in your Jira instance. If your organization requires admin approval for marketplace apps, send the app link to your Jira administrator and request installation. The process typically takes under a minute once approved. ### Step 2 -- Open the Mermaid Panel on a Jira Issue[​](#step-2----open-the-mermaid-panel-on-a-jira-issue "Direct link to Step 2 -- Open the Mermaid Panel on a Jira Issue") Navigate to any Jira issue where you want to add a diagram. Scroll to the area above the Activity section (comments, history, etc.) and look for the **Mermaid+ Diagrams** panel. Click the panel icon to activate it. If this is the first time you are using the panel on this issue, it will be empty. The panel is issue-specific, meaning each Jira issue has its own diagram. This keeps the visual context tightly coupled to the work being tracked. ### Step 3 -- Write Your Mermaid Diagram Code[​](#step-3----write-your-mermaid-diagram-code "Direct link to Step 3 -- Write Your Mermaid Diagram Code") Click the **+** (Create Diagram) button in the top-right corner of the panel. A fullscreen modal editor opens with a three-column layout: * **Left column**: Live Preview -- your diagram renders in real time as you type * **Middle column**: Quick Templates -- one-click starter code for all 30 supported diagram types * **Right column**: Settings and Code Editor -- write your Mermaid code, adjust font, colors, theme, and output size Start by clicking a Quick Template in the middle column if you want starter code, or type your Mermaid syntax directly into the code editor on the right. The live preview on the left updates instantly, so you can see the result of every edit without waiting. ### Step 4 -- Preview and Customize Your Diagram[​](#step-4----preview-and-customize-your-diagram "Direct link to Step 4 -- Preview and Customize Your Diagram") While you write or edit your code, the live preview on the left renders the diagram in real time. Use the settings panel to customize the appearance: **Font settings:** | Setting | Options | | ------- | ----------------------------------------- | | Family | Inter, Arial, Helvetica, Georgia, Courier | | Size | 12px, 14px (default), 16px, 18px, 20px | **Color settings:** Five customizable colors with visual color pickers let you match your company brand or improve readability: | Color | Affects | | ---------- | ------------------------------------------- | | Node | Background color of diagram nodes and boxes | | Text | Text color inside nodes | | Border | Border color of nodes | | Line | Edge and arrow line color | | Background | Diagram background color | **Theme:** Choose from four Mermaid built-in themes: Default (uses your custom colors), Dark, Forest, and Neutral. The Default theme respects your custom color settings. The other themes apply their own palettes for a polished look without manual tuning. **Output Size:** Control how large the diagram appears in the issue panel after saving. Options range from Small (0.5x) to X-Large (2x), with Medium (1x) as the default. You can also click the **?** button in the header to open the full syntax reference. Browse all 30 diagram types with descriptions and code examples. Hover over any code block and click the insert button to load it into the editor. ### Step 5 -- Save the Diagram to the Issue[​](#step-5----save-the-diagram-to-the-issue "Direct link to Step 5 -- Save the Diagram to the Issue") Once you are satisfied with the preview, click **Save**. The diagram is stored on the Jira issue and displayed in the Mermaid+ Diagrams panel. Anyone who can view the issue will see the rendered diagram. Anyone with **Edit Issues** permission can click the edit button (pencil icon) in the panel to reopen the editor and modify the diagram. All settings -- code, colors, font, theme, and output size -- are preserved when you re-edit. The diagram also adapts to Jira's dark or light mode automatically. When you save a diagram, the current Jira theme is recorded. If someone views the issue in a different theme later, text and background colors are adjusted for readability. For full documentation on all features, see the [Mermaid Plus Diagrams for Jira usage guide](/docs/Mermaid-plus-Diagrams-for-Jira/usage.md). ## Which Diagram Types Work Best on Jira Issues?[​](#which-diagram-types-work-best-on-jira-issues "Direct link to Which Diagram Types Work Best on Jira Issues?") Mermaid Plus Diagrams for Jira supports 30 diagram types. Not all of them are equally useful in the context of a Jira issue. Here are the diagram types that deliver the most value on Jira issues, along with guidance on when to use each one. ### Flowcharts for Bug Reproduction Steps[​](#flowcharts-for-bug-reproduction-steps "Direct link to Flowcharts for Bug Reproduction Steps") Flowcharts are the single most useful diagram type on Jira bug tickets. A well-structured flowchart shows the exact path a user took through the application to trigger the bug, including decision points, error branches, and loops. This eliminates the back-and-forth between QA and developers about "how did you get there?" Use flowcharts when: * Documenting step-by-step reproduction paths for bugs * Showing conditional logic in a feature request * Illustrating approval workflows and escalation paths * Mapping out process changes for improvement tickets Key flowchart features to know: * **Directions**: TD (top-down), BT (bottom-up), LR (left-right), RL (right-left) * **Node shapes**: `[Square]`, `(Rounded)`, `{Diamond}`, `((Circle))` * **Subgraphs**: Group related steps together visually ### Sequence Diagrams for API Flows[​](#sequence-diagrams-for-api-flows "Direct link to Sequence Diagrams for API Flows") Sequence diagrams show how participants communicate over time, making them ideal for documenting API interactions directly on backend or integration tickets. When a developer picks up a ticket about an API endpoint, a sequence diagram on that ticket tells them exactly which services are involved and in what order messages flow. Use sequence diagrams when: * Documenting request/response flows between services * Showing authentication and authorization sequences * Illustrating event-driven architectures and message queues * Describing retry logic, circuit breakers, and error handling flows ### Class Diagrams for Design Discussions[​](#class-diagrams-for-design-discussions "Direct link to Class Diagrams for Design Discussions") Class diagrams model object-oriented relationships, which makes them valuable on design-phase tickets where the team needs to agree on data structures, inheritance hierarchies, and composition patterns before implementation begins. Use class diagrams when: * Discussing database schema changes on a feature ticket * Reviewing data model proposals for new functionality * Documenting existing class hierarchies for refactoring tickets * Showing relationships between entities in a domain model ### Other Useful Diagram Types on Jira Issues[​](#other-useful-diagram-types-on-jira-issues "Direct link to Other Useful Diagram Types on Jira Issues") Beyond the big three, these diagram types also have practical applications on Jira issues: * **State diagrams** -- Show the lifecycle of an entity (order status, deployment states) on workflow-related tickets * **Gantt charts** -- Display timelines and dependencies on epic-level tickets * **Mind maps** -- Brainstorm feature scope or root causes on planning tickets * **ER diagrams** -- Document database schema changes on data migration tickets * **C4 diagrams** -- Illustrate system architecture on infrastructure or integration tickets ## 3 Copy-Paste Mermaid Examples for Jira Workflows[​](#3-copy-paste-mermaid-examples-for-jira-workflows "Direct link to 3 Copy-Paste Mermaid Examples for Jira Workflows") Below are three practical Mermaid examples designed for common Jira scenarios. Copy any of these into the Mermaid Plus Diagrams editor on a Jira issue and modify the labels to fit your situation. ### Example 1 -- Bug Reproduction Flowchart[​](#example-1----bug-reproduction-flowchart "Direct link to Example 1 -- Bug Reproduction Flowchart") This flowchart documents the exact steps a user takes to trigger a checkout bug. Paste this on a Bug-type Jira issue to give developers an instant visual reproduction path. ``` graph TD A[User opens product page] --> B{Item in stock?} B -->|Yes| C[Add to cart] B -->|No| D[Show out of stock message] D --> E[User clicks notify me] C --> F[Proceed to checkout] F --> G{Logged in?} G -->|Yes| H[Enter shipping info] G -->|No| I[Redirect to login] I --> J[User logs in] J --> H H --> K[Select payment method] K --> L[Click Place Order] L --> M{Payment succeeds?} M -->|Yes| N[Order confirmed] M -->|No| O[Payment declined error] O --> P[User retries with different card] P --> K ``` **Why this works on a Jira bug ticket:** The developer reading this bug can immediately trace the path from "user opens product page" through the decision points to the failure at "payment declined error." No ambiguity, no missing steps, no guessing. ### Example 2 -- API Integration Sequence Diagram[​](#example-2----api-integration-sequence-diagram "Direct link to Example 2 -- API Integration Sequence Diagram") This sequence diagram shows the interaction between a mobile app, API gateway, backend service, and database during a user profile update. Paste this on a Story or Task ticket that involves API development. ``` sequenceDiagram autonumber actor User participant App as Mobile App participant GW as API Gateway participant Auth as Auth Service participant SVC as Profile Service participant DB as Database User->>App: Update profile form App->>GW: PUT /api/v1/users/42/profile GW->>Auth: Validate JWT token Auth-->>GW: Token valid, user_id=42 GW->>SVC: Forward authenticated request SVC->>SVC: Validate input fields SVC->>DB: UPDATE users SET name=$1, email=$2 WHERE id=42 DB-->>SVC: 1 row updated alt Profile update succeeds SVC-->>GW: 200 {user: {id: 42, name: "Updated"}} GW-->>App: 200 OK App-->>User: Show success toast else Validation fails SVC-->>GW: 400 {errors: ["Email format invalid"]} GW-->>App: 400 Bad Request App-->>User: Highlight invalid fields else Database timeout SVC-->>GW: 503 Service Unavailable GW-->>App: 503 App-->>User: Show retry prompt end ``` **Why this works on a Jira story ticket:** When a developer picks up this story, they can see at a glance every service involved, the order of calls, and all three outcome branches (success, validation failure, database timeout). This is far more efficient than a paragraph describing "first the gateway validates the token, then forwards to the profile service, which updates the database, but if..." ### Example 3 -- Class Diagram for a Design Discussion[​](#example-3----class-diagram-for-a-design-discussion "Direct link to Example 3 -- Class Diagram for a Design Discussion") This class diagram shows a proposed data model for a notification system. Paste this on a design-phase ticket to give the team a concrete visual to discuss and refine. ``` classDiagram class User { +int id +String email +String name +getPreferences() NotificationPreference } class NotificationPreference { +int userId +boolean emailEnabled +boolean pushEnabled +boolean slackEnabled +String slackWebhookUrl } class Notification { +int id +int userId +String type +String title +String body +DateTime createdAt +boolean read +markAsRead() } class NotificationTemplate { +int id +String name +String subjectTemplate +String bodyTemplate +render(context) String } class NotificationChannel { <> +send(notification, preference) boolean } class EmailChannel { +send(notification, preference) boolean } class PushChannel { +send(notification, preference) boolean } class SlackChannel { +send(notification, preference) boolean } User "1" --> "1" NotificationPreference : has User "1" --> "*" Notification : receives Notification "*" --> "1" NotificationTemplate : uses NotificationChannel <|.. EmailChannel NotificationChannel <|.. PushChannel NotificationChannel <|.. SlackChannel ``` **Why this works on a Jira design ticket:** The team can review the class relationships, method signatures, and the interface-based channel abstraction without reading through a lengthy design document. Comments on the ticket can reference specific classes: "Should `NotificationTemplate.render()` return HTML or plain text?" This keeps the design discussion focused and productive. ## Mermaid Plus for Jira vs. Mermaid Plus Diagrams & AI Agent for Confluence[​](#mermaid-plus-for-jira-vs-mermaid-plus-diagrams--ai-agent-for-confluence "Direct link to Mermaid Plus for Jira vs. Mermaid Plus Diagrams & AI Agent for Confluence") If your team uses both Jira and Confluence, you might wonder how the Jira version compares to the Confluence version. Here is what is the same and what is different. ### What Is the Same[​](#what-is-the-same "Direct link to What Is the Same") * **Mermaid syntax**: Both apps use the same Mermaid.js syntax. Any diagram you create in one app will work in the other. * **30 diagram types**: Both apps support the full set of 30 diagram types including flowcharts, sequence diagrams, class diagrams, Gantt charts, mind maps, C4 diagrams, and more. * **Live preview**: Both apps render your diagram in real time as you type. * **Color customization**: Both apps offer five customizable colors (Node, Text, Border, Line, Background) with visual color pickers. * **Theme support**: Both apps support Default, Dark, Forest, and Neutral themes. * **Font customization**: Both apps let you choose font family and size. * **Syntax guide**: Both apps include a built-in syntax reference accessible from the editor. * **Quick templates**: Both apps provide one-click starter templates for all 30 diagram types. ### What Is Different[​](#what-is-different "Direct link to What Is Different") | Feature | Jira Version | Confluence Version | | ----------------- | ---------------------------------------------- | -------------------------------------------- | | Location | Issue panel above Activity section | Macro embedded in page content | | Diagram storage | Attached to the specific issue | Embedded in the Confluence page | | Permissions | Edit Issues permission required to create/edit | Page edit permission required | | Multiple diagrams | One diagram per issue panel | Multiple macros per page | | Context | Issue-centric (bug, story, task) | Page-centric (documentation, knowledge base) | | Viewing audience | Anyone who can view the issue | Anyone who can view the page | | Dark mode | Auto-adapts to Jira theme | Follows Confluence theme | ### When to Use Each[​](#when-to-use-each "Direct link to When to Use Each") Use **Mermaid Plus for Jira** when you need to attach visual context directly to a piece of work: a bug reproduction flow, an API design for a story, or a root-cause analysis on an incident. The diagram lives with the ticket and is part of the team's daily workflow. Use **Mermaid Plus Diagrams & AI Agent for Confluence** when you are writing long-form documentation, architecture decision records, onboarding guides, or runbooks. Confluence pages give you more space for narrative context alongside the diagram, and you can embed multiple diagrams on a single page. Many teams use both: Confluence for the authoritative design document, and Jira for the quick visual reference on the implementation ticket that links back to the Confluence page. ## Tips for Getting the Most Out of Diagrams on Jira Issues[​](#tips-for-getting-the-most-out-of-diagrams-on-jira-issues "Direct link to Tips for Getting the Most Out of Diagrams on Jira Issues") ### Start with a Quick Template[​](#start-with-a-quick-template "Direct link to Start with a Quick Template") The editor provides one-click starter templates for all 30 diagram types. Instead of writing Mermaid code from scratch, click a template, then modify the node labels and connections to match your scenario. This saves time and reduces syntax errors. ### Use the Syntax Guide for Reference[​](#use-the-syntax-guide-for-reference "Direct link to Use the Syntax Guide for Reference") Click the **?** button in the editor header to open the full syntax reference. Browse all 30 diagram types with descriptions and code examples. Hover over any code block and click the insert button to load it into your editor. This is especially useful when you need a less common diagram type and cannot remember the exact syntax. ### Keep Diagrams Focused[​](#keep-diagrams-focused "Direct link to Keep Diagrams Focused") A Jira issue diagram should answer one specific question: "How does this bug reproduce?" or "What does this API flow look like?" Resist the temptation to put everything into a single diagram. If you need to show multiple aspects of a system, create focused diagrams on separate issues and link them together. ### Choose the Right Output Size[​](#choose-the-right-output-size "Direct link to Choose the Right Output Size") Use the Output Size setting to control how large the diagram appears in the issue panel. For simple flowcharts with few nodes, Medium (1x) works well. For complex diagrams with many nodes and labels, consider Large (1.5x) or X-Large (2x) to ensure readability. ### Match Your Jira Theme[​](#match-your-jira-theme "Direct link to Match Your Jira Theme") If your team uses Jira in dark mode, select the Dark theme in the diagram settings. The diagram will render with high-contrast colors against a dark background. The Default theme uses your custom color settings and works best in light mode. The app also auto-adapts when viewers switch between dark and light mode. ### Use the Confluence Version for Related Documentation[​](#use-the-confluence-version-for-related-documentation "Direct link to Use the Confluence Version for Related Documentation") If a Jira issue needs extensive background documentation with multiple diagrams, create a Confluence page with the detailed explanation and embed multiple Mermaid diagrams there using [Mermaid Plus Diagrams & AI Agent for Confluence](/blog/create-mermaid-diagrams-confluence.md). Then add a single, focused summary diagram on the Jira issue and link to the Confluence page for the full picture. ## Performance and Technical Details[​](#performance-and-technical-details "Direct link to Performance and Technical Details") Diagrams rendered with Mermaid Plus Diagrams for Jira are designed to be fast. The rendering process works as follows: * **On save**: The Mermaid code is rendered to SVG and cached * **On issue load**: The cached SVG is displayed instantly -- no JavaScript rendering required * **During editing**: The Mermaid.js library is loaded only when the editor is open, not when viewing issues This means diagrams on Jira issues add zero performance overhead to normal issue viewing. The Mermaid.js library is only loaded when someone opens the editor to create or modify a diagram. ## Supported Diagram Types -- Complete List[​](#supported-diagram-types----complete-list "Direct link to Supported Diagram Types -- Complete List") Mermaid Plus Diagrams for Jira supports 30 diagram types. Here is the full list for reference: | Diagram Type | Keyword | Best Used For | | -------------------- | --------------------- | ----------------------------------------------------- | | Flowchart | `graph` / `flowchart` | Process flows, bug reproduction, decision trees | | Sequence Diagram | `sequenceDiagram` | API flows, service interactions, message protocols | | Class Diagram | `classDiagram` | Data models, OOP design, schema discussions | | State Diagram | `stateDiagram-v2` | Entity lifecycles, workflow states, deployment states | | ER Diagram | `erDiagram` | Database schemas, entity relationships | | User Journey | `journey` | UX flows, satisfaction mapping | | Gantt Chart | `gantt` | Project timelines, task dependencies | | Pie Chart | `pie` | Proportional data, time allocation | | Git Graph | `gitGraph` | Branch strategy, release workflows | | Mindmap | `mindmap` | Brainstorming, feature scoping | | Timeline | `timeline` | Milestones, release history | | Requirement Diagram | `requirementDiagram` | Requirements traceability | | C4 Diagram | `C4Context` | System architecture, service boundaries | | Quadrant Chart | `quadrantChart` | Priority matrices, analysis charts | | Sankey Diagram | `sankey-beta` | Flow volumes, resource allocation | | XY Chart | `xychart-beta` | Bar and line charts, metrics | | Block Diagram | `block-beta` | Component layouts, system blocks | | Packet Diagram | `packet-beta` | Network packet structures | | Kanban Board | `kanban` | Task board visualization | | Architecture Diagram | `architecture-beta` | Infrastructure and service architecture | | Radar Chart | `radar-beta` | Multi-axis comparisons | | TreeView | `treeView-beta` | File/folder structures | | Treemap | `treemap` | Hierarchical data visualization | | Ishikawa | `ishikawa` | Root cause analysis, fishbone diagrams | | Venn Diagram | `venn-beta` | Set relationships, team skill overlap | | ZenUML | `zenuml` | Alternative sequence diagram syntax | ## Common Questions[​](#common-questions "Direct link to Common Questions") ### Can multiple team members edit the same diagram?[​](#can-multiple-team-members-edit-the-same-diagram "Direct link to Can multiple team members edit the same diagram?") Only one person can edit a diagram at a time. However, anyone with Edit Issues permission can edit the diagram after the previous editor has finished. Changes are saved atomically, so there is no risk of partial edits. ### Do diagrams appear in Jira search results?[​](#do-diagrams-appear-in-jira-search-results "Direct link to Do diagrams appear in Jira search results?") Diagrams are rendered as visual content on the issue. The Mermaid code is stored with the issue and contributes to the issue's content. ### What happens if I delete a diagram?[​](#what-happens-if-i-delete-a-diagram "Direct link to What happens if I delete a diagram?") You can clear the diagram by editing it and removing the code. The diagram panel remains on the issue but shows an empty state, ready for a new diagram. ### Can I use Mermaid subgraphs?[​](#can-i-use-mermaid-subgraphs "Direct link to Can I use Mermaid subgraphs?") Yes. Subgraphs are fully supported and are especially useful for grouping related steps in a flowchart. Wrap nodes in `subgraph Name ... end` to create visual groupings. ### Does the app work with Jira Automation?[​](#does-the-app-work-with-jira-automation "Direct link to Does the app work with Jira Automation?") Diagrams are stored as part of the issue content. Jira Automation rules that reference issue fields will not directly interact with diagrams, but you can use automation rules to manage the issues that contain them. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Mermaid Plus Diagrams for Jira -- full documentation](/apps/mermaid-plus-diagrams-for-jira.md) -- detailed configuration, all settings, and complete syntax reference * [Create Mermaid diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md) -- the Confluence version of this guide, covering macros, page embedding, and Confluence-specific features * [Mermaid troubleshooting FAQ](/blog/faq-mermaid-troubleshooting.md) -- solutions for common rendering issues, syntax errors, and display problems * [How to create sequence diagrams in Confluence](/blog/how-to-create-sequence-diagrams-confluence.md) -- deep dive into sequence diagram syntax with five copy-paste examples * [How to create a flowchart in Jira](/blog/how-to-create-flowchart-in-jira.md) -- three methods compared, with copy-paste flowchart examples for bug triage, approvals, and incident escalation Adding diagrams to Jira issues takes a process that used to require external tools, exported images, and constant re-attachment, and turns it into a few seconds of typing in an editor that lives right on the issue. Install Mermaid Plus Diagrams for Jira, paste one of the examples from this guide onto your next bug or story, and give your team the visual context they need to move faster. Try Mermaid Plus Diagrams for Jira All 30 Mermaid diagram types embedded in Jira issues, with live preview and Quick Templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/2658777397/mermaid-plus-diagrams-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-diagrams-for-jira) ## Related guides * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [mermaid](/blog/tags/mermaid.md) * [diagrams](/blog/tags/diagrams.md) * [how-to](/blog/tags/how-to.md) * [jira-issues](/blog/tags/jira-issues.md) * [flowchart](/blog/tags/flowchart.md) --- # Create Mind Maps in Confluence — Free with Mermaid Plus May 2, 2026 · 12 min read [NGPilot](https://ngpilot.com) Mind maps are one of the most effective ways to capture ideas, organize thoughts, and brainstorm with a team. Unlike linear notes or bullet lists, mind maps radiate outward from a central topic, making it easy to see relationships between concepts at a glance. If your team already uses Confluence for documentation, meeting notes, and project planning, adding mind maps directly to your Confluence pages keeps brainstorming sessions alongside the rest of your team's knowledge. In this tutorial, you will learn how to create mind maps in Confluence using Mermaid syntax and the Mermaid Plus Diagrams & AI Agent for Confluence app. Every example is copy-paste ready, so you can drop it straight into a Confluence page and start organizing your ideas immediately. ## Why Mind Maps in Confluence?[​](#why-mind-maps-in-confluence "Direct link to Why Mind Maps in Confluence?") Teams reach for mind maps whenever they need to explore a topic from multiple angles without getting locked into a rigid structure. Mind maps are particularly useful for: * **Brainstorming sessions** where ideas flow freely and you need a visual way to capture and group them * **Project kickoffs** that map out goals, stakeholders, deliverables, risks, and timelines in a single view * **Meeting agenda planning** where you lay out discussion topics and subtopics before the meeting starts * **Technical architecture discussions** that explore different components, data flows, and integration points * **Knowledge base organization** where you plan the structure of a documentation space or wiki hierarchy Confluence is where much of this context already lives: product requirements, sprint plans, retrospective notes, and architecture decision records. Adding rendered mind maps directly on those pages means your brainstorming artifacts stay connected to the decisions and documentation they informed, rather than living in a separate diagramming tool that nobody revisits. Mermaid's `mindmap` diagram type produces clean, hierarchical mind maps from a simple indented text format. Combined with Mermaid Plus Diagrams & AI Agent for Confluence, you get a first-class editing experience right inside the Confluence editor. ## Step-by-Step: Create Your First Mind Map[​](#step-by-step-create-your-first-mind-map "Direct link to Step-by-Step: Create Your First Mind Map") Follow these steps to go from a blank Confluence page to a fully rendered mind map. ### Step 1 -- Install Mermaid Plus Diagrams & AI Agent for Confluence[​](#step-1----install-mermaid-plus-diagrams--ai-agent-for-confluence "Direct link to Step 1 -- Install Mermaid Plus Diagrams & AI Agent for Confluence") Head to the [Atlassian Marketplace](https://marketplace.atlassian.com/) and search for **Mermaid Plus Diagrams & AI Agent for Confluence**. Click **Get App** and follow the installation prompts. Once installed, the Mermaid Plus macro becomes available on every space in your Confluence instance. If your organization pre-approves apps, check with your Confluence admin first. The app supports both Confluence Cloud and Confluence Data Center. ### Step 2 -- Insert the Mermaid Macro[​](#step-2----insert-the-mermaid-macro "Direct link to Step 2 -- Insert the Mermaid Macro") Open any Confluence page in edit mode. Type `/mermaid` in the editor and select the **Mermaid Plus** macro from the dropdown. A code editor panel appears where you can write Mermaid syntax. ### Step 3 -- Write the `mindmap` Header[​](#step-3----write-the-mindmap-header "Direct link to step-3----write-the-mindmap-header") Start every mind map diagram with the `mindmap` keyword. Then define the root node, which represents the central topic of your mind map: ``` mindmap root((Central Topic)) ``` The `root` keyword followed by `((Central Topic))` creates a rounded node at the center of the mind map. This is the starting point from which all branches radiate outward. ### Step 4 -- Add Branches and Sub-Topics[​](#step-4----add-branches-and-sub-topics "Direct link to Step 4 -- Add Branches and Sub-Topics") Indent lines to create branches. Each level of indentation creates a deeper branch in the hierarchy. Use different node shapes to visually distinguish between types of content: ``` mindmap root((Project Alpha)) Planning Requirements Timeline Budget Design Wireframes Mockups Development Frontend Backend Testing ``` The indentation controls the hierarchy. In this example, "Planning," "Design," and "Development" are first-level branches from the root, while "Requirements," "Timeline," and "Budget" are second-level branches under "Planning." ### Step 5 -- Save and Publish[​](#step-5----save-and-publish "Direct link to Step 5 -- Save and Publish") Preview the mind map inside the macro editor to verify it renders correctly. When you are happy with the result, click **Save** on the macro, then **Publish** the Confluence page. The mind map is now part of your living documentation. ## Mermaid Mind Map Syntax Reference[​](#mermaid-mind-map-syntax-reference "Direct link to Mermaid Mind Map Syntax Reference") Here is a quick-reference for the syntax elements specific to Mermaid mind maps. Bookmark this section and come back to it whenever you need a syntax reminder. ### Node Shapes[​](#node-shapes "Direct link to Node Shapes") Different node shapes help you visually distinguish between categories, priorities, or types of content in your mind map: | Shape | Syntax | Description | | ----------------- | ----------- | ----------------------------------------------------------- | | Rounded (default) | `(Topic)` | Standard rounded rectangle | | Circle | `((Topic))` | Circle shape, often used for the root node | | Square | `[Topic]` | Square or rectangular box | | Bang / Explosion | `))Topic((` | Cloud or explosion shape, useful for highlighting key items | | Hexagon | `{{Topic}}` | Hexagonal shape for special categories | You can mix and match shapes within a single mind map to encode visual meaning: ``` mindmap root((Product Launch)) [Pre-Launch] ((Research)) ((Strategy)) [Launch] {{Marketing}} {{Sales Push}} [Post-Launch] ))Feedback(( ))Iteration(( ``` ### Indentation and Hierarchy[​](#indentation-and-hierarchy "Direct link to Indentation and Hierarchy") Indentation defines the parent-child relationships in your mind map. Each level of indentation creates a new tier of branches: * **No indent** -- the `root` keyword defines the central node * **2 spaces** -- first-level branches radiating from the root * **4 spaces** -- second-level branches (sub-topics) * **6 spaces** -- third-level branches (details) * **And so on** -- deeper nesting is supported but readability suffers beyond four levels Consistent indentation is critical. Mermaid parses indentation to determine the structure, so mixing tabs and spaces or using inconsistent indent widths will produce unexpected results. Stick to 2-space increments. ### Icons[​](#icons "Direct link to Icons") Mermaid mind maps support FontAwesome icons using the `fa:fa-icon-name` syntax. Place the icon reference before the node text: ``` mindmap root((Project Plan)) fa:fa-calendar Timeline fa:fa-flag Milestone 1 fa:fa-flag Milestone 2 fa:fa-users Team fa:fa-user Alice fa:fa-user Bob fa:fa-cog Technical fa:fa-code Frontend fa:fa-database Backend ``` Icons add visual cues that make mind maps easier to scan quickly. Use them sparingly for maximum impact -- an icon on every node can be overwhelming. ### Comments[​](#comments "Direct link to Comments") Use `%%` to add comments that are not rendered in the diagram: ``` %% This is a comment mindmap root((Ideas)) %% TODO: add more branches Branch A ``` Comments are useful for leaving notes for yourself or your team about planned additions or the reasoning behind a particular structure. ## 3 Copy-Paste Mind Map Examples[​](#3-copy-paste-mind-map-examples "Direct link to 3 Copy-Paste Mind Map Examples") Below are three practical examples you can paste directly into the Mermaid Plus macro in Confluence. Each example demonstrates a different real-world use case. ### Example 1 -- Product Planning Mind Map[​](#example-1----product-planning-mind-map "Direct link to Example 1 -- Product Planning Mind Map") This mind map organizes the key areas of a product planning session: user research, feature prioritization, design, engineering, and go-to-market strategy. Use it as a template for your next product kickoff. ``` mindmap root((Product Q3 Plan)) User Research Customer Interviews Survey Results Support Tickets Analysis Competitive Analysis Feature Prioritization Must Have User Authentication Dashboard Redesign Should Have Export to PDF Dark Mode Nice to Have Custom Themes API Playground Design Wireframes High-Fidelity Mockups Usability Testing Engineering Frontend React Migration Performance Optimization Backend API Versioning Database Sharding Infrastructure CI/CD Pipeline Monitoring Alerts Go-to-Market Launch Blog Post Email Campaign Webinar Social Media Plan ``` This mind map gives product managers, designers, and engineers a shared view of everything that goes into a quarterly plan. Each team can see where their work fits and how it connects to other workstreams. ### Example 2 -- Meeting Notes Organization Mind Map[​](#example-2----meeting-notes-organization-mind-map "Direct link to Example 2 -- Meeting Notes Organization Mind Map") Mind maps are an excellent format for organizing meeting notes by topic. This example shows how to structure notes from a sprint retrospective or team meeting: ``` mindmap root((Sprint Retrospective)) What Went Well Shipped Feature X on Time Reduced Bug Backlog by 30 Percent Pair Programming Sessions Improved Test Coverage What Could Improve Cross-Team Communication Missed Dependency on Team B Unclear API Contract Changes Estimation Accuracy Underestimated Migration Task Overestimated Documentation Code Review Turnaround PRs Waiting Over 48 Hours Need More Reviewers Action Items ((Setup Weekly Sync with Team B)) ((Implement PR SLA Policy)) ((Create Estimation Checklist)) ((Rotate Review Duties)) Metrics Velocity: 42 Points Bug Escape Rate: 5 Percent Deployment Frequency: 3 Per Week ``` The bang-shaped nodes `((...))` for action items make them stand out visually, so anyone reviewing the mind map can immediately spot the follow-up tasks. This format is far more scannable than a flat list of bullet points buried in a meeting-notes page. ### Example 3 -- Technical Architecture Brainstorm[​](#example-3----technical-architecture-brainstorm "Direct link to Example 3 -- Technical Architecture Brainstorm") This mind map maps out the components, data flows, and infrastructure decisions for a microservice architecture. Use it as a starting point for technical design discussions: ``` mindmap root((Microservice Architecture)) Services User Service Authentication Profile Management Preferences Order Service Cart Management Checkout Flow Order History Payment Service Stripe Integration Invoice Generation Refund Processing Notification Service Email Push Notifications SMS Data Layer PostgreSQL Users DB Orders DB Redis Session Cache Rate Limiting S3 File Uploads Report Exports Infrastructure Kubernetes Auto-Scaling Health Checks API Gateway Rate Limiting Authentication Proxy Request Routing CI/CD GitHub Actions Docker Registry Blue-Green Deployments Observability Logging Structured Logs Log Aggregation Monitoring Prometheus Metrics Grafana Dashboards Alerting PagerDuty Integration Slack Notifications Security OAuth 2.0 mTLS Between Services Secrets Management ``` This architecture mind map gives the entire engineering team a bird's-eye view of the system. New engineers can use it to understand the big picture before diving into specific services, and senior engineers can use it to identify gaps in the design during review sessions. ## Tips for Effective Mind Maps[​](#tips-for-effective-mind-maps "Direct link to Tips for Effective Mind Maps") A well-structured mind map communicates ideas clearly. A poorly structured one creates confusion. Here are practical tips to get the most out of mind maps in Confluence. ### Keep Branch Names Short and Descriptive[​](#keep-branch-names-short-and-descriptive "Direct link to Keep Branch Names Short and Descriptive") Each node in a mind map should be a short phrase, not a sentence. Aim for two to five words per node. If you find yourself writing long phrases, consider breaking the concept into a parent node with child nodes. "Customer Onboarding" is a good branch name. "Implement a new customer onboarding flow that includes email verification and profile setup" is not. ### Limit Hierarchy Depth[​](#limit-hierarchy-depth "Direct link to Limit Hierarchy Depth") Mind maps work best with three to four levels of depth. Beyond that, the diagram becomes hard to read and the visual hierarchy loses its impact. If you need more than four levels, consider breaking the mind map into multiple diagrams. Create one high-level mind map that links to more detailed mind maps on separate Confluence pages. ### Use Visual Hierarchy Intentionally[​](#use-visual-hierarchy-intentionally "Direct link to Use Visual Hierarchy Intentionally") Mix node shapes to encode meaning. For example, use `((...))` for the root topic, `[...]` for major categories, `(...)` for sub-topics, and `{{...}}` for action items or highlights. Establish a legend on your Confluence page so your team knows what each shape means. Consistency across mind maps helps everyone read them faster. ### Group Related Ideas Together[​](#group-related-ideas-together "Direct link to Group Related Ideas Together") During brainstorming sessions, ideas often come out in a random order. After the initial capture, reorganize the mind map so related ideas share a parent branch. This clustering is where much of the value of mind mapping comes from -- it reveals patterns and connections that are invisible in a flat list. ### Color and Style for Emphasis[​](#color-and-style-for-emphasis "Direct link to Color and Style for Emphasis") Mermaid supports styling directives that let you change the color of specific nodes. Use this to highlight priority items or draw attention to blockers: ``` style root fill:#f9f,stroke:#333,stroke-width:2px ``` Apply color sparingly. One or two highlighted branches draw attention. Highlighting everything is the same as highlighting nothing. ### Start with a Template[​](#start-with-a-template "Direct link to Start with a Template") Rather than creating mind maps from scratch every time, build a library of templates for recurring scenarios: sprint planning, retrospective notes, product kickoff, technical design review. Store these templates on a Confluence page in your team space so anyone can copy and customize them. ### Update Mind Maps as Projects Evolve[​](#update-mind-maps-as-projects-evolve "Direct link to Update Mind Maps as Projects Evolve") One of the biggest advantages of text-based mind maps in Confluence is how easy they are to update. When priorities shift or new ideas emerge, edit the Mermaid code and republish. Unlike image-based mind maps exported from a separate tool, Mermaid mind maps stay current with minimal effort. ## Common Mistakes to Avoid[​](#common-mistakes-to-avoid "Direct link to Common Mistakes to Avoid") * **Inconsistent indentation.** Mermaid mind maps rely on indentation to define hierarchy. Mixing tabs and spaces, or using inconsistent indent widths (e.g., 2 spaces on one line and 3 on the next), will break the structure. Configure your editor to use spaces and stick to a consistent 2-space increment. * **Too many top-level branches.** A mind map with 15 branches coming off the root becomes unreadable. Aim for 3 to 7 top-level branches. If you have more, group them into categories. * **Overusing icons.** Icons are helpful when used selectively. Placing an icon on every node makes the diagram noisy and defeats the purpose of visual emphasis. * **Skipping the root keyword.** The `root` keyword is required for Mermaid mind maps. Omitting it or misspelling it will prevent the diagram from rendering. * **Forgetting to publish after editing.** After modifying the Mermaid code in the macro, you must click **Save** on the macro and then **Publish** the Confluence page. The diagram will not update for other users until the page is published. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Mermaid Plus Diagrams & AI Agent for Confluence usage guide](/apps/mermaid-plus-for-confluence.md) -- detailed configuration options, theme settings, and all 30 supported diagram types * [Mermaid Syntax Cheat Sheet](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md) -- quick reference for all Mermaid diagram types supported in Confluence, including flowcharts, sequence diagrams, and ER diagrams * [Create Mermaid diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md) -- broader guide covering flowcharts, class diagrams, Gantt charts, and more * [Excalidraw Plus for Confluence](/apps/excalidraw-plus-for-confluence.md) -- hand-drawn style diagrams and whiteboarding for freeform brainstorming sessions Mind maps are a natural fit for Confluence pages where teams already collaborate on ideas and documentation. With Mermaid Plus Diagrams & AI Agent for Confluence, creating a mind map is as simple as writing indented text in the macro editor. No external tools, no exported images, no version-control headaches. Install Mermaid Plus Diagrams & AI Agent for Confluence, paste one of the examples above into a page, and start mapping out your next big idea today. ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [mindmap](/blog/tags/mindmap.md) * [how-to](/blog/tags/how-to.md) * [diagrams](/blog/tags/diagrams.md) * [brainstorming](/blog/tags/brainstorming.md) --- # Create Pie Charts in Confluence — Free with Mermaid Syntax May 2, 2026 · 18 min read [NGPilot](https://ngpilot.com) Pie charts are one of the simplest and most effective ways to communicate proportional data. Whether you are reporting survey results, breaking down a project budget, or showing how your team allocates time across activities, a pie chart turns a list of numbers into a visual that anyone can read in seconds. Confluence is where your team already stores reports, retrospectives, and planning documents, so embedding pie charts directly on those pages keeps your data alongside the context that explains it. With Mermaid Plus Diagrams & AI Agent for Confluence, you can create pie charts and other data visualizations using plain text syntax. No image exports, no spreadsheet screenshots, no broken attachments. You write the code once, and the chart renders directly on the Confluence page, updating whenever you edit the underlying data. In this tutorial, you will learn how to create pie charts in Confluence using Mermaid syntax, with copy-paste examples you can drop straight onto a page. You will also learn how to build timelines, quadrant charts, and Git graphs for the kinds of data that pie charts cannot represent. ## Why Pie Charts in Confluence?[​](#why-pie-charts-in-confluence "Direct link to Why Pie Charts in Confluence?") Teams use pie charts when they need to show **how a whole is divided into parts**. Unlike bar charts or line graphs, a pie chart emphasizes relative proportions rather than absolute values or trends over time. This makes pie charts the right choice for: * **Survey results** where you want to show how respondents distributed across answer options * **Budget breakdowns** that show how funding is allocated across departments or categories * **Time tracking** summaries that visualize how team members spent their hours in a sprint * **Market share reports** that compare your product's share against competitors * **Issue distribution** in Jira dashboards showing bugs versus features versus tech debt Confluence pages are the natural home for this data. Your retrospective notes, planning documents, and status reports already live there. Adding a rendered pie chart to the same page means stakeholders see the data visualization alongside the narrative that explains it. When the numbers change, you update the Mermaid code and republish. No re-exporting from Excel, no uploading new images, no stale charts. Mermaid's pie chart syntax is intentionally minimal. You define a title, list your categories with values, and Mermaid handles the math and rendering. With Mermaid Plus Diagrams & AI Agent for Confluence, you also get a live preview editor, theme customization, and output size controls to make your charts look polished on any Confluence page. ## Step-by-Step: Create Your First Pie Chart[​](#step-by-step-create-your-first-pie-chart "Direct link to Step-by-Step: Create Your First Pie Chart") Follow these steps to go from a blank Confluence page to a fully rendered pie chart. ### Step 1 -- Install Mermaid Plus Diagrams & AI Agent for Confluence[​](#step-1----install-mermaid-plus-diagrams--ai-agent-for-confluence "Direct link to Step 1 -- Install Mermaid Plus Diagrams & AI Agent for Confluence") Head to the Atlassian Marketplace and search for **Mermaid Plus Diagrams & AI Agent for Confluence**. Click **Get App** and follow the installation prompts. Once installed, the Mermaid Plus macro becomes available on every page in your Confluence instance. If your organization pre-approves apps, check with your Confluence admin first. The app supports both Confluence Cloud and Confluence Data Center. ### Step 2 -- Insert the Mermaid Macro[​](#step-2----insert-the-mermaid-macro "Direct link to Step 2 -- Insert the Mermaid Macro") Open any Confluence page in edit mode. Type `/mermaid` in the editor and select **Mermaid Plus Diagrams & AI Agent for Confluence** from the dropdown. The configuration panel opens with a three-column layout: live preview on the left, quick templates in the middle, and the code editor with settings on the right. ### Step 3 -- Write the Pie Chart Syntax[​](#step-3----write-the-pie-chart-syntax "Direct link to Step 3 -- Write the Pie Chart Syntax") Start every pie chart with the `pie` keyword, add a title, then list your data rows: ``` pie title Team Sprint Effort "Feature development" : 45 "Bug fixes" : 25 "Code reviews" : 15 "Meetings" : 10 "Documentation" : 5 ``` Each data row has a label in quotes and a numeric value separated by a colon. Mermaid treats the values as relative proportions and calculates the percentages automatically. You do not need to normalize your data to add up to 100. ### Step 4 -- Customize Labels and Colors[​](#step-4----customize-labels-and-colors "Direct link to Step 4 -- Customize Labels and Colors") Use clear, descriptive labels for each slice. The labels appear directly on the rendered chart, so they should be concise enough to read at a glance but specific enough to be meaningful. Adjust the Mermaid theme in the settings panel to change the color palette. Mermaid Plus offers four built-in themes: Default, Dark, Forest, and Neutral. Each theme applies its own color scheme to the pie slices automatically. ### Step 5 -- Save and Publish[​](#step-5----save-and-publish "Direct link to Step 5 -- Save and Publish") Preview the chart inside the macro editor to verify it renders correctly. Check that your labels are readable and that the proportions match your data. When you are happy with the result, click **Save** on the macro, then **Publish** the Confluence page. Your pie chart is now embedded in your documentation and will update whenever you re-edit the macro. ## Mermaid Pie Chart Syntax Reference[​](#mermaid-pie-chart-syntax-reference "Direct link to Mermaid Pie Chart Syntax Reference") Here is a quick-reference table for the pie chart syntax elements in Mermaid. Bookmark this section for whenever you need a syntax reminder. | Element | Syntax | Description | | ------------- | ---------------------- | --------------------------------- | | Chart keyword | `pie` | Starts a pie chart | | Title | `pie title My Chart` | Displays a title above the chart | | Data row | `"Label" : value` | One slice of the pie | | Multiple rows | Add rows on new lines | Each row becomes a separate slice | | Comment | `%% This is a comment` | Inline comment, not rendered | Key rules to remember: * The `pie` keyword must appear on its own line before any data * Labels must be wrapped in double quotes if they contain spaces * Values are positive numbers; Mermaid calculates percentages from the total * There is no hard limit on the number of slices, but readability degrades beyond 8 to 10 categories ## 3 Copy-Paste Pie Chart Examples[​](#3-copy-paste-pie-chart-examples "Direct link to 3 Copy-Paste Pie Chart Examples") Below are three practical examples you can paste directly into the Mermaid Plus macro in Confluence. Each example demonstrates a different real-world use case. ### Example 1 -- Basic Pie Chart: Team Sprint Effort[​](#example-1----basic-pie-chart-team-sprint-effort "Direct link to Example 1 -- Basic Pie Chart: Team Sprint Effort") This is a straightforward pie chart showing how a development team distributes effort across activity categories during a typical sprint. It works well on retrospective pages, sprint review documents, and team dashboards. ``` pie title Sprint 14 Effort Distribution "Feature development" : 40 "Bug fixes" : 20 "Code reviews" : 15 "Technical debt" : 10 "Meetings" : 10 "Documentation" : 5 ``` This chart communicates one key message at a glance: the majority of the sprint effort went toward feature development, with bug fixes as the second largest category. If you want to compare this sprint to the previous one, duplicate the macro on the same page, change the data, and let stakeholders compare the two charts side by side. When presenting to stakeholders who are not familiar with your team's day-to-day work, this kind of chart helps frame the conversation. A product manager can look at this and immediately ask whether the 10% allocated to technical debt is sufficient, or whether the 10% spent in meetings could be reduced. ### Example 2 -- Survey Results: Employee Satisfaction[​](#example-2----survey-results-employee-satisfaction "Direct link to Example 2 -- Survey Results: Employee Satisfaction") This example visualizes the results of an employee satisfaction survey with five response categories. It is useful on HR dashboard pages, team health check documents, and quarterly review reports. ``` pie title Employee Satisfaction Survey Q1 2026 "Very satisfied" : 142 "Satisfied" : 198 "Neutral" : 67 "Dissatisfied" : 31 "Very dissatisfied" : 12 ``` Notice that the raw survey counts are used directly as values. Mermaid sums them (142 + 198 + 67 + 31 + 12 = 450 total responses) and converts each count into a percentage of the total. This means you can paste your raw survey data without doing any pre-calculation. For survey data like this, pie charts work best when you have 5 to 7 response categories. If your survey has 15 options, consider grouping them into broader categories before charting, or use a bar chart instead. The pie chart format prioritizes relative proportion over precise comparison, so it shines when you want to show that "most respondents fell into these two categories." ### Example 3 -- Project Time Allocation: Quarterly Budget[​](#example-3----project-time-allocation-quarterly-budget "Direct link to Example 3 -- Project Time Allocation: Quarterly Budget") This example breaks down how a project team plans to allocate hours across work streams for the upcoming quarter. It fits naturally on project planning pages, budget proposals, and resource allocation documents. ``` pie title Q3 2026 Project Time Allocation "Backend development" : 350 "Frontend development" : 280 "QA and testing" : 200 "DevOps and infrastructure" : 150 "UX research and design" : 120 "Project management" : 100 ``` This chart uses larger numeric values representing planned person-hours for each work stream. The values do not need to be percentages; Mermaid normalizes them automatically. This approach is particularly useful for budget and resource planning because you can update a single number (for example, increasing QA from 200 to 250 hours) and immediately see how the proportional breakdown shifts. When presenting resource allocation to leadership, pair this chart with a brief table on the same Confluence page listing the absolute numbers alongside the visual. The pie chart tells the proportional story; the table provides the precision. ## Advanced Pie Chart Techniques[​](#advanced-pie-chart-techniques "Direct link to Advanced Pie Chart Techniques") Once you are comfortable with the basic syntax, these techniques help you get more out of pie charts in your Confluence documentation. ### Handling Many Categories[​](#handling-many-categories "Direct link to Handling Many Categories") When your data has more than 8 categories, pie charts become difficult to read. The slices get too narrow, labels overlap, and the visual communication breaks down. Here are two strategies: **Group small categories into "Other".** Combine any category below a threshold (for example, under 5%) into a single "Other" slice. This keeps the chart readable while preserving the overall proportions: ``` pie title Website Traffic Sources "Organic search" : 42 "Direct" : 25 "Social media" : 15 "Email campaigns" : 8 "Referral" : 6 "Other" : 4 ``` **Use multiple pie charts for comparison.** If you need to show detailed breakdowns for different groups, place separate pie charts side by side on the same Confluence page. Each chart stays clean with 4 to 6 slices, and readers compare them visually. ### Keeping Data Current[​](#keeping-data-current "Direct link to Keeping Data Current") One of the biggest advantages of Mermaid pie charts over pasted images is that the data lives as editable text on the Confluence page. When your numbers change, you click the macro, edit, update the values, and save. There is no external tool to open, no image to re-export, and no attachment to re-upload. For charts that update regularly (sprint summaries, monthly metrics, quarterly budgets), add a brief note above the macro indicating when the data was last updated. This helps readers trust that the chart reflects current information rather than a stale snapshot. ### Pairing Charts with Context[​](#pairing-charts-with-context "Direct link to Pairing Charts with Context") A pie chart on its own tells you what the proportions are. It does not explain why. On your Confluence page, add a brief paragraph above or below the chart explaining the key takeaway. For example: * "This sprint, feature development dropped from 50% to 40% due to an increase in bug fixes from the v2.0 release." * "Employee satisfaction improved compared to Q4 2025, with 'very satisfied' responses increasing from 28% to 32%." This combination of visual and narrative is more powerful than either element alone. The chart catches the reader's attention; the text provides the interpretation. ## Other Mermaid Data Visualization Types[​](#other-mermaid-data-visualization-types "Direct link to Other Mermaid Data Visualization Types") Pie charts are ideal for proportional data, but many datasets call for different visualization formats. Mermaid Plus Diagrams & AI Agent for Confluence supports 30 diagram types, several of which are specifically designed for data visualization. Here are three that complement pie charts in a Confluence documentation toolkit. ### Git Graph: Branch and Commit History[​](#git-graph-branch-and-commit-history "Direct link to Git Graph: Branch and Commit History") Git graphs visualize the history of a repository, showing branches, commits, and merges over time. They are useful on developer onboarding pages, release process documentation, and architecture decision records where you need to show how code flows through branches. ``` gitGraph commit id: "Initial setup" commit id: "Add auth module" branch feature/dashboard checkout feature/dashboard commit id: "Dashboard UI" commit id: "Dashboard API" checkout main branch hotfix/auth-bug commit id: "Fix token expiry" checkout main merge hotfix/auth-bug id: "Hotfix release" merge feature/dashboard id: "Dashboard release" commit id: "Version bump to 2.1" ``` This Git graph tells the story of a feature branch being developed in parallel with a hotfix. The merge points show exactly when each branch was integrated into main. For teams that document their branching strategy in Confluence, this kind of visual is far more effective than a text description. Git graphs work well alongside pie charts on release summary pages. Use a pie chart to show the distribution of commits by contributor or by file type, and a Git graph to show the branch topology. ### Timeline: Project Milestones and Events[​](#timeline-project-milestones-and-events "Direct link to Timeline: Project Milestones and Events") Timelines present chronological sequences of events, making them ideal for project milestones, product roadmaps, and historical summaries. Unlike Gantt charts, timelines do not show task duration; they highlight key moments in sequence. ``` timeline title Product Launch Timeline section Q1 2026 Market research complete : Jan 15 Competitive analysis published : Feb 1 Product requirements finalized : Feb 28 section Q2 2026 Design sprint completed : Apr 10 Alpha release : May 1 Beta program opens : May 15 section Q3 2026 Public launch : Jul 1 First update release : Aug 15 Customer feedback report : Sep 30 ``` Timelines are a natural companion to pie charts on planning pages. Use a pie chart to show how resources are allocated across phases, and a timeline to show when key milestones occur. Together, they give stakeholders both the "how much" and the "when" in a format that is easy to scan. ### Quadrant Chart: Prioritization Matrices[​](#quadrant-chart-prioritization-matrices "Direct link to Quadrant Chart: Prioritization Matrices") Quadrant charts plot items on a two-axis grid, dividing the space into four labeled quadrants. They are commonly used for prioritization matrices (impact vs. effort), risk assessments (likelihood vs. severity), and market analysis (growth vs. market share). ``` quadrantChart title Feature Prioritization Matrix x-axis Low Impact --> High Impact y-axis Low Effort --> High Effort quadrant-1 Quick Wins quadrant-2 Strategic Investments quadrant-3 Deprioritize quadrant-4 Fill-Ins "User onboarding flow" : [0.8, 0.3] "Dark mode toggle" : [0.4, 0.2] "API rate limiting" : [0.7, 0.6] "Mobile responsive nav" : [0.6, 0.4] "Bulk export feature" : [0.9, 0.7] "Keyboard shortcuts" : [0.3, 0.3] "SSO integration" : [0.85, 0.8] "Search improvements" : [0.75, 0.5] ``` Each item is plotted at coordinates between 0 and 1 on both axes. The quadrant labels give immediate context: items in "Quick Wins" are high-impact and low-effort, while items in "Strategic Investments" are high-impact but also high-effort. This chart type is a staple of product planning, and having it rendered directly on a Confluence page keeps the prioritization conversation grounded in a shared visual. Quadrant charts complement pie charts effectively. Use a pie chart to show how many features fall into each priority category, and a quadrant chart to show exactly which features sit where. The pie chart gives the aggregate view; the quadrant chart gives the item-level detail. ## Choosing the Right Chart Type[​](#choosing-the-right-chart-type "Direct link to Choosing the Right Chart Type") With multiple visualization options available, here is a quick guide to choosing the right chart for your data: | Data Type | Best Chart | Example Use Case | | ---------------------------- | -------------- | ---------------------------------------- | | Parts of a whole | Pie chart | Budget allocation, survey results | | Chronological events | Timeline | Product roadmap, release history | | Prioritization | Quadrant chart | Feature priority, risk assessment | | Branch and merge history | Git graph | Release process, branching strategy | | Task scheduling | Gantt chart | Sprint plan, project timeline | | Flow and decisions | Flowchart | Process documentation, approval workflow | | Comparison across categories | XY chart (bar) | Revenue by quarter, bugs by severity | If your data is about proportions and you have 3 to 8 categories, start with a pie chart. If you need to show change over time, reach for a timeline. If you need to prioritize a list of items against two criteria, use a quadrant chart. ## Tips for Effective Data Visualization in Confluence[​](#tips-for-effective-data-visualization-in-confluence "Direct link to Tips for Effective Data Visualization in Confluence") Regardless of which chart type you use, these practices will help your Confluence visualizations communicate clearly. **Keep it focused.** Each chart should answer one question. If you find yourself trying to show budget allocation and timeline and team distribution all in one chart, split them into separate diagrams. Three clear charts are better than one cluttered chart. **Use consistent colors across pages.** If "Bug fixes" is always represented by the same color across your team's charts, readers learn to recognize it instantly. Mermaid Plus themes help with this by applying consistent palettes, but you can also enforce consistency through team conventions documented on a shared Confluence page. **Label everything clearly.** Mermaid lets you add titles to every chart. Use them. A chart titled "Q3 Budget" is more useful than an untitled chart that readers have to infer the meaning of from surrounding text. For pie charts, make sure each slice label is descriptive and concise. **Update data regularly.** Charts that show stale data erode trust. If you are displaying sprint metrics in a pie chart, update it at the end of every sprint. If you are showing quarterly budget allocation, update it at the start of each quarter. The text-based nature of Mermaid makes this trivially easy compared to re-exporting images from other tools. **Place charts near their context.** A pie chart showing survey results should appear right next to the survey summary text, not buried at the bottom of a long page. Confluence's inline macro placement makes this straightforward. Insert the chart exactly where the reader will want to see it. **Use output size controls.** Mermaid Plus lets you control the displayed size of your chart (Small, Medium, Large, X-Large). A pie chart on a dashboard summary might work well at Small size, while a detailed quadrant chart used in a planning session might need Large or X-Large to keep labels readable. ## Common Mistakes to Avoid[​](#common-mistakes-to-avoid "Direct link to Common Mistakes to Avoid") * **Using too many slices.** A pie chart with 15 slices is unreadable. Group small categories or switch to a different chart type. * **Forgetting the `pie` keyword.** Every Mermaid pie chart must start with `pie` on its own line. Without it, Mermaid does not know what diagram type to render. * **Missing quotes around labels.** Labels that contain spaces must be wrapped in double quotes. Without quotes, Mermaid will fail to parse the data row. * **Using zero or negative values.** Mermaid pie chart values must be positive numbers. A zero value creates an invisible slice, and negative values will cause a rendering error. * **Omitting the title.** While technically optional, a chart without a title forces readers to guess what the data represents. Always include `pie title Your Descriptive Title`. * **Copying data without checking.** When pasting data from spreadsheets, verify that the numbers are correct and that no extra formatting characters were included. A stray dollar sign or comma in a number will break the syntax. ## Theme and Appearance Settings[​](#theme-and-appearance-settings "Direct link to Theme and Appearance Settings") Mermaid Plus Diagrams & AI Agent for Confluence gives you control over how your charts look on the page. In the configuration panel, you can adjust: * **Theme** -- Choose from Default, Dark, Forest, or Neutral to match your Confluence space's visual style. The Default theme uses your custom color settings, while other themes apply their own curated palettes. * **Font family** -- Select from Inter, Arial, Helvetica, Georgia, or Courier to match your organization's typography guidelines. * **Font size** -- Set to 12px, 14px (default), 16px, 18px, or 20px for optimal readability. * **Custom colors** -- Adjust node background, text color, border, line, and background colors using the visual color picker. * **Output size** -- Scale your chart to Small (0.5x), Medium (1x), Large (1.5x), or X-Large (2x) to fit the layout of your Confluence page. For pie charts, the theme setting is the most impactful because it controls the slice color palette. Experiment with different themes in the live preview to find the one that looks best with your data. Dark mode is automatically supported: when a reader views your Confluence page in dark mode, the chart adapts its text and background colors for readability. ## Performance and Reliability[​](#performance-and-reliability "Direct link to Performance and Reliability") Diagrams created with Mermaid Plus render instantly on page load using cached SVG. The Mermaid.js library is only loaded during configuration, not when viewing pages. This means your pie charts, timelines, and quadrant charts do not slow down Confluence page load times, even on pages with multiple diagrams. All settings and code are preserved when you re-edit an existing diagram. Click on any Mermaid Plus macro and select **Edit** to reopen the configuration panel with your previous code and settings intact. This makes iterative refinement straightforward: create a chart, publish the page, gather feedback, then come back and adjust the data or appearance without starting over. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Mermaid Plus Diagrams & AI Agent for Confluence usage guide](/apps/mermaid-plus-for-confluence.md) -- detailed configuration options, theme settings, and all 30 supported diagram types * [How to create Gantt charts in Confluence](/blog/how-to-create-gantt-charts-confluence.md) -- step-by-step tutorial for project timelines with dependencies, milestones, and status flags * [Mermaid Syntax Cheat Sheet for Confluence](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md) -- quick reference for all Mermaid diagram types with copy-paste examples * [Create Mermaid diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md) -- broader guide covering flowcharts, sequence diagrams, class diagrams, and more Pie charts are a practical, high-leverage addition to your Confluence documentation. A well-structured Mermaid pie chart takes seconds to create, lives alongside your written context, and stays current with a simple text edit. Install Mermaid Plus Diagrams & AI Agent for Confluence, paste one of the examples above into a page, and start visualizing your data where your team already works. ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [pie-chart](/blog/tags/pie-chart.md) * [data-visualization](/blog/tags/data-visualization.md) * [how-to](/blog/tags/how-to.md) * [charts](/blog/tags/charts.md) --- # How to Build a Release Timeline in Jira — 3 Methods with Copy-Paste Examples September 13, 2026 · 5 min read [NGPilot](https://ngpilot.com) A release date doesn't slip in one dramatic moment — it slips in six quiet ones: QA took two extra days, staging froze late, sign-off waited on legal. A release timeline pinned to the release epic makes those slips visible *while they're still cheap to fix*, because every stakeholder reads the same picture of what's next and what's blocked. Jira gives you three ways to build that picture. This guide walks through them, then gives three copy-paste Mermaid Gantt examples sized for real releases: a single version, a multi-team launch, and a launch-week sequence. **Quick answer:** To build a release timeline in Jira, install [Mermaid Plus Diagrams for Jira](https://marketplace.atlassian.com/apps/2658777397/), open the Mermaid panel on your release epic, and paste Mermaid `gantt` syntax — `dateFormat YYYY-MM-DD`, one task line per phase, `after` dependencies between them, and `milestone` for the launch date. Every example below is copy-paste ready. Jira Premium's Plans feature can auto-generate a timeline, but a Mermaid Gantt shows exactly the phases you choose and edits in seconds. ## Method 1 — Atlassian Plans (Native, Premium)[​](#method-1--atlassian-plans-native-premium "Direct link to Method 1 — Atlassian Plans (Native, Premium)") Jira Premium and Enterprise include Plans (formerly Advanced Roadmaps): set fix versions, link dependencies, and it generates a timeline view from your real backlog. **Good for:** portfolio-level views driven by live issue data, when your plan *is* the backlog. **The limitations:** it requires Premium (team-managed and Standard projects are out), the auto-generated view shows what the backlog implies rather than the curated phases you want stakeholders to see, and it can't be annotated — no launch-day callouts, no marketing rows, no "freeze" bands. If the release is cross-functional, the parts that don't live in Jira don't exist in the timeline. ## Method 2 — Mermaid Gantt on the Release Epic (Recommended)[​](#method-2--mermaid-gantt-on-the-release-epic-recommended "Direct link to Method 2 — Mermaid Gantt on the Release Epic (Recommended)") A Mermaid Gantt chart on the release epic is the curated source of truth: it shows the phases you decide matter, dependencies shift dates automatically when one phase moves, and editing is one line of text. ### Example 1 — Single Version Timeline[​](#example-1--single-version-timeline "Direct link to Example 1 — Single Version Timeline") The baseline every release needs. Phases with dependencies, the train date as a milestone — paste onto the fix-version issue and rename: ``` gantt dateFormat YYYY-MM-DD title Release 2.14 — October train section Development Feature freeze :done, feat, 2026-09-15, 5d Code complete :active, code, after feat, 4d section Hardening QA regression : qa, after code, 5d Bug fixes : fix, after qa, 3d section Release Staging deploy : stg, after fix, 2d Sign-off :milestone, sig, after stg, 0d Production rollout : prod, after sig, 1d Launch :milestone, launch, after prod, 0d ``` The `done` and `active` markers double as a status board — in review meetings the timeline shows progress without a separate slide. ### Example 2 — Multi-Team Launch with Parallel Tracks[​](#example-2--multi-team-launch-with-parallel-tracks "Direct link to Example 2 — Multi-Team Launch with Parallel Tracks") Cross-team releases need each team's track visible and the coupling points obvious. `subgraph` separates the tracks; the shared milestone is where they meet: ``` gantt dateFormat YYYY-MM-DD title Autumn launch — 3 tracks section Platform API v2 endpoints :p1, 2026-09-20, 12d Migration dry-run :p2, after p1, 3d section Web New checkout flow :w1, 2026-09-22, 10d E2E against API v2 :w2, after p2 w1, 3d section Mobile Store submission :m1, after w2, 4d section Launch Go/no-go review :crit, milestone, go, after m1, 0d Coordinated rollout :roll, after go, 2d ``` The `crit` flag colors the go/no-go review red — useful when a stakeholder asks which dates absolutely cannot move. ### Example 3 — Launch-Week Sequence[​](#example-3--launch-week-sequence "Direct link to Example 3 — Launch-Week Sequence") Launch week is its own timeline: marketing, support, and engineering in one view, hour-granular where it matters: ``` gantt dateFormat YYYY-MM-DD axisFormat %a %d title Launch week — 2.14 section Comms Blog + changelog draft :c1, 2026-10-12, 2d Customer email :c2, after c1, 1d section Support macros/runbook refresh :s1, 2026-10-12, 2d On-call briefing :milestone, s2, after s1, 0d section Engineering Feature flags on :e1, after s2, 1d Monitor + hotfix window:e2, after e1, 3d ``` `axisFormat %a %d` renders weekday names on the axis — small change, but launch-week reviews stop generating "wait, is that the 14th or the 15th?" questions. ## Method 3 — Confluence for the Full Plan, Jira for the Timeline[​](#method-3--confluence-for-the-full-plan-jira-for-the-timeline "Direct link to Method 3 — Confluence for the Full Plan, Jira for the Timeline") When the release needs risk registers, rollback plans, and comms plans around the timeline, build the full release plan in Confluence ([Mermaid Plus Diagrams & AI Agent for Confluence](/blog/how-to-create-gantt-charts-confluence.md) renders the same gantt syntax on pages), and keep the timeline itself on the release epic where engineers live. Link both ways — the epic is the daily view, the page is the archive. ## Which Method Should You Use?[​](#which-method-should-you-use "Direct link to Which Method Should You Use?") | Need | Use | | --------------------------------------------------- | -------------------------------------- | | Portfolio view generated from live backlog | Atlassian Plans (Premium) | | Curated release timeline stakeholders actually read | Mermaid Gantt on the release epic | | Full release plan with risks, rollback, comms | Confluence page + epic timeline linked | A release timeline earns its keep the first time a date slips and everyone already knows which three tasks move with it. Install Mermaid Plus Diagrams for Jira, paste Example 1 onto your current release epic, and let the dependencies do the rescheduling. ## Related Guides[​](#related-guides "Direct link to Related Guides") * [Mermaid diagrams for Jira sprint workflows](/blog/mermaid-diagrams-jira-sprint-workflows.md) -- the sprint-scale counterpart: task-granular timelines and the four diagram types sprint teams use * [Create Mermaid diagrams on Jira issues](/blog/how-to-create-mermaid-diagrams-jira.md) -- the complete guide to diagrams on Jira issues: sequence, class, and more * [Gantt charts in Confluence](/blog/how-to-create-gantt-charts-confluence.md) -- the Confluence version with three full project-plan examples ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [release](/blog/tags/release.md) * [timeline](/blog/tags/timeline.md) * [gantt](/blog/tags/gantt.md) * [mermaid](/blog/tags/mermaid.md) * [how-to](/blog/tags/how-to.md) * [project-management](/blog/tags/project-management.md) --- # How to Create Sequence Diagrams in Confluence (Mermaid Examples) May 2, 2026 · 13 min read [NGPilot](https://ngpilot.com) Sequence diagrams are one of the most practical tools in a software team's documentation toolkit. They show how objects, services, or actors interact over time, making them ideal for documenting API flows, authentication processes, microservice choreography, and error-handling logic. If your team uses Confluence for documentation, embedding sequence diagrams directly on your pages keeps architecture docs alongside everything else your team needs. In this tutorial, you will learn how to create sequence diagrams in Confluence using Mermaid syntax. Every example is copy-paste ready, so you can drop it straight into a Confluence page and see the result immediately. The examples use [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence), which renders the full Mermaid v12 syntax natively in Confluence Cloud — free to try from the Marketplace. ## Why Sequence Diagrams in Confluence?[​](#why-sequence-diagrams-in-confluence "Direct link to Why Sequence Diagrams in Confluence?") Teams choose sequence diagrams when they need to show **who talks to whom, and in what order**. Unlike flowcharts that emphasize decision branches, sequence diagrams focus on the temporal flow of messages between participants. This makes them especially useful for: * **Documenting API integrations** so frontend and backend engineers stay aligned on request and response patterns * **Onboarding new engineers** with visual walkthroughs of how a login, checkout, or data-sync process works end to end * **Design reviews** where the team needs to agree on service boundaries and message contracts before writing code * **Incident post-mortems** that trace the exact path a failed request took through the system Confluence is where most of this context already lives: runbooks, design docs, sprint retros, and architecture decision records. Adding rendered sequence diagrams directly on those pages eliminates the friction of linking out to external diagramming tools or attaching exported images that go stale the moment the code changes. Mermaid is the most popular text-to-diagram language, and with Mermaid Plus Diagrams & AI Agent for Confluence you get a first-class editing experience right inside the Confluence editor. ## Step-by-Step: Create Your First Sequence Diagram[​](#step-by-step-create-your-first-sequence-diagram "Direct link to Step-by-Step: Create Your First Sequence Diagram") Follow these steps to go from a blank Confluence page to a fully rendered sequence diagram. ### Step 1 — Install Mermaid Plus Diagrams & AI Agent for Confluence[​](#step-1--install-mermaid-plus-diagrams--ai-agent-for-confluence "Direct link to Step 1 — Install Mermaid Plus Diagrams & AI Agent for Confluence") Head to the [Mermaid Plus Diagrams & AI Agent for Confluence listing](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence) on the Atlassian Marketplace. Click **Get App** and follow the installation prompts. Once installed, the Mermaid Plus macro becomes available on every space in your Confluence instance. If your organization pre-approves apps, check with your Confluence admin first. The app supports Confluence Cloud and Confluence Data Center. ### Step 2 — Insert the Mermaid Macro[​](#step-2--insert-the-mermaid-macro "Direct link to Step 2 — Insert the Mermaid Macro") Open any Confluence page in edit mode. Type `/mermaid` in the editor and select the **Mermaid Plus** macro from the dropdown. A code editor panel appears where you can write Mermaid syntax. ### Step 3 — Write the `sequenceDiagram` Header[​](#step-3--write-the-sequencediagram-header "Direct link to step-3--write-the-sequencediagram-header") Start every sequence diagram with the `sequenceDiagram` keyword. Then declare your participants: ``` sequenceDiagram participant A as Alice participant B as Bob ``` The `participant` keyword defines who appears on the diagram. The `as` keyword lets you use a short alias in the code while displaying a friendlier name in the rendered diagram. ### Step 4 — Add Message Arrows[​](#step-4--add-message-arrows "Direct link to Step 4 — Add Message Arrows") Messages are the core of any sequence diagram. Use arrow operators to show communication between participants: ``` sequenceDiagram participant A as Alice participant B as Bob A->>B: Hello, can you help? B-->>A: Sure, what do you need? ``` The `->>` operator draws a solid arrow with a label. The `-->>` operator draws a dashed arrow, which is conventionally used for responses or asynchronous messages. ### Step 5 — Save and Publish[​](#step-5--save-and-publish "Direct link to Step 5 — Save and Publish") Preview the diagram inside the macro editor to verify it renders correctly. When you are happy with the result, click **Save** on the macro, then **Publish** the Confluence page. The diagram is now part of your living documentation. ## Mermaid Sequence Diagram Syntax Reference[​](#mermaid-sequence-diagram-syntax-reference "Direct link to Mermaid Sequence Diagram Syntax Reference") Here is a quick-reference table for the most commonly used sequence diagram elements. Bookmark this section and come back to it whenever you need a syntax reminder. | Element | Syntax | Description | | ------------------- | -------------------------------- | ----------------------------------------- | | Solid arrow | `A->>B: Message` | Synchronous request or direct message | | Dashed arrow | `A-->>B: Message` | Response, return value, or async message | | Open arrow (solid) | `A->B: Message` | Arrow without arrowhead fill | | Open arrow (dashed) | `A-->B: Message` | Dashed arrow without arrowhead fill | | Participant | `participant A as Alice` | Declare a named participant with an alias | | Actor | `actor User` | Stick-figure actor instead of a box | | Note (left) | `Note left of A: Text` | Note to the left of a participant | | Note (right) | `Note right of B: Text` | Note to the right of a participant | | Note (over) | `Note over A,B: Text` | Note spanning multiple participants | | Alt/Else block | `alt Condition ... else ... end` | Conditional branching | | Loop block | `loop Description ... end` | Repeated iteration | | Opt block | `opt Condition ... end` | Optional step | | Par block | `par ... and ... end` | Parallel execution | | Activate | `activate A` | Show activation bar on participant | | Deactivate | `deactivate A` | Remove activation bar | | Auto-number | `autonumber` | Number messages automatically | | Comment | `%% This is a comment` | Inline comment, not rendered | ## 5 Copy-Paste Sequence Diagram Examples[​](#5-copy-paste-sequence-diagram-examples "Direct link to 5 Copy-Paste Sequence Diagram Examples") Below are five practical examples you can paste directly into the Mermaid Plus macro in Confluence. Each example demonstrates a different real-world scenario. ### Example 1 — User Login Flow[​](#example-1--user-login-flow "Direct link to Example 1 — User Login Flow") This diagram shows a typical username/password login with a JWT token response. It covers the happy path and a failed-login branch. ``` sequenceDiagram autonumber actor User participant FE as Frontend App participant API as Auth Service participant DB as User Database participant Cache as Token Cache User->>FE: Enter credentials FE->>API: POST /auth/login {email, password} API->>DB: SELECT user WHERE email = ? DB-->>API: User record alt Valid credentials API->>API: Verify password hash API->>Cache: Store refresh token API-->>FE: 200 {access_token, refresh_token} FE-->>User: Redirect to dashboard else Invalid credentials API-->>FE: 401 Unauthorized FE-->>User: Show error message end ``` Use this diagram as a starting point for your own auth documentation. Add participants for SSO providers, multi-factor authentication services, or rate-limiting middleware as your architecture requires. ### Example 2 — API Request/Response[​](#example-2--api-requestresponse "Direct link to Example 2 — API Request/Response") A clean request-response pattern showing a REST API call with pagination. This pattern is useful for documenting public APIs that third-party developers consume. ``` sequenceDiagram autonumber participant Client as API Client participant GW as API Gateway participant SVC as Product Service participant DB as Database Client->>GW: GET /products?page=2&limit=20 GW->>GW: Validate API key & rate limit GW->>SVC: Forward request SVC->>DB: SELECT products OFFSET 20 LIMIT 20 DB-->>SVC: Result set (20 rows) SVC->>SVC: Map to DTOs SVC-->>GW: 200 {data, pagination: {page, total}} GW-->>Client: JSON response Note over Client,GW: Retry on 429 or 503 ``` Notice the `Note over Client,GW` spanning two participants. Use spanning notes to annotate cross-cutting concerns like retry policies or SLA boundaries. ### Example 3 — Microservice Communication[​](#example-3--microservice-communication "Direct link to Example 3 — Microservice Communication") Microservice architectures involve chains of service-to-service calls. This example models an e-commerce order-placement flow with synchronous calls and an asynchronous event emission. ``` sequenceDiagram autonumber participant Client participant OrderSvc as Order Service participant InventorySvc as Inventory Service participant PaymentSvc as Payment Service participant EventBus as Event Bus participant NotifySvc as Notification Service Client->>OrderSvc: POST /orders activate OrderSvc OrderSvc->>InventorySvc: POST /inventory/reserve activate InventorySvc InventorySvc-->>OrderSvc: 200 {reservation_id} deactivate InventorySvc OrderSvc->>PaymentSvc: POST /payments/charge activate PaymentSvc alt Payment succeeds PaymentSvc-->>OrderSvc: 200 {charge_id} deactivate PaymentSvc OrderSvc->>EventBus: publish order.created EventBus-->>NotifySvc: deliver event NotifySvc->>NotifySvc: Send confirmation email OrderSvc-->>Client: 201 {order_id, status: confirmed} else Payment fails PaymentSvc-->>OrderSvc: 402 Payment declined deactivate PaymentSvc OrderSvc->>InventorySvc: POST /inventory/release OrderSvc-->>Client: 402 {error: payment_declined} end deactivate OrderSvc ``` The `activate` and `deactivate` keywords render the vertical activation bars that show when each service is actively processing a request. This visual cue helps readers see which services are waiting and which are working at any point in the flow. ### Example 4 — Database Transaction[​](#example-4--database-transaction "Direct link to Example 4 — Database Transaction") This diagram illustrates a database transaction with a rollback on failure. It is useful for documenting data-integrity requirements in financial or inventory systems. ``` sequenceDiagram autonumber participant App as Application participant DB as Database App->>DB: BEGIN TRANSACTION activate DB App->>DB: UPDATE accounts SET balance = balance - 100 WHERE id = 42 DB-->>App: 1 row updated App->>DB: UPDATE accounts SET balance = balance + 100 WHERE id = 99 DB-->>App: 1 row updated App->>DB: INSERT INTO transfers (from, to, amount) VALUES (42, 99, 100) DB-->>App: 1 row inserted alt All statements succeed App->>DB: COMMIT DB-->>App: Transaction committed else Any statement fails App->>DB: ROLLBACK DB-->>App: Transaction rolled back Note right of App: No partial writes persisted end deactivate DB ``` ### Example 5 — Error Handling Flow[​](#example-5--error-handling-flow "Direct link to Example 5 — Error Handling Flow") Error-handling patterns are notoriously difficult to describe in prose. A sequence diagram makes the retry-and-circuit-breaker pattern immediately clear. ``` sequenceDiagram autonumber participant Client participant Retry as Retry Middleware participant CB as Circuit Breaker participant Service as Downstream Service Client->>Retry: Send request Retry->>CB: Forward request alt Service is healthy CB->>Service: Proxy request Service-->>CB: 200 OK CB-->>Retry: 200 OK Retry-->>Client: Success response else Service returns 5xx CB->>Service: Proxy request Service-->>CB: 503 Service Unavailable Note over CB: Record failure, increment count loop Retry up to 3 times with backoff Retry->>CB: Retry request CB->>Service: Proxy request Service-->>CB: Response end alt Retry succeeds CB-->>Retry: 200 OK Retry-->>Client: Success response else All retries exhausted CB->>CB: Open circuit CB-->>Retry: Circuit open error Retry-->>Client: 503 with fallback response end end ``` ## Real-World Sequence Diagrams (Copy-Paste)[​](#real-world-sequence-diagrams-copy-paste "Direct link to Real-World Sequence Diagrams (Copy-Paste)") These two patterns come up constantly in real repositories — the OAuth 2.0 authorization-code flow every SaaS integrates, and the CI/CD pipeline most platform teams document. Both are modeled on the flows as they're drawn in production runbooks, not toy examples. ### OAuth 2.0 Authorization Code flow[​](#oauth-20-authorization-code-flow "Direct link to OAuth 2.0 Authorization Code flow") The interaction every SSO integration follows — user, browser, your app, and the identity provider: ``` sequenceDiagram actor User participant Browser participant App as Your App participant IdP as Identity Provider User->>Browser: Clicks "Sign in with SSO" Browser->>App: GET /login App-->>Browser: 302 Redirect to IdP /authorize Browser->>IdP: Authorization request (client_id, scope, state) IdP->>User: Show login + consent screen User->>IdP: Authenticate and approve IdP-->>Browser: 302 Redirect with ?code=xyz Browser->>App: GET /callback?code=xyz App->>IdP: POST /token (code + client_secret) IdP-->>App: access_token + id_token App->>IdP: GET /userinfo (Bearer token) IdP-->>App: User claims (email, name) App-->>Browser: Session established Browser-->>User: Logged-in dashboard ``` ### CI/CD pipeline: from commit to production[​](#cicd-pipeline-from-commit-to-production "Direct link to CI/CD pipeline: from commit to production") The sequence a platform team pastes into its runbook — note the `alt` block for the gate check: ``` sequenceDiagram actor Dev as Developer participant GH as GitHub participant CI as CI Runner participant Reg as Container Registry participant CD as Deploy Service participant Prod as Production Dev->>GH: git push (feature branch) GH->>CI: Trigger workflow (push event) CI->>CI: Lint + unit tests alt tests pass CI->>Reg: docker push app:sha-abc123 Reg-->>CD: Image digest notification CD->>Prod: Rolling deploy (canary 10%) Prod-->>CD: Health checks green CD->>Prod: Promote to 100% CD-->>Dev: Deploy success notification else tests fail CI-->>Dev: Pipeline failed — test report end ``` ## Tips for Complex Sequence Diagrams[​](#tips-for-complex-sequence-diagrams "Direct link to Tips for Complex Sequence Diagrams") As your diagrams grow beyond five or six participants, readability can suffer. These tips help you keep large diagrams manageable. ### Use Alt and Else Blocks for Conditional Logic[​](#use-alt-and-else-blocks-for-conditional-logic "Direct link to Use Alt and Else Blocks for Conditional Logic") Wrap branching paths in `alt`/`else`/`end` blocks instead of drawing every possible combination linearly. This keeps the main flow visible and tucks edge cases into clearly labeled sections. ``` alt Order is in stock Inventory-->>Order: Reserve items else Order is out of stock Inventory-->>Order: Backorder items end ``` ### Add Loops for Retry Logic and Polling[​](#add-loops-for-retry-logic-and-polling "Direct link to Add Loops for Retry Logic and Polling") The `loop` keyword draws a labeled box around repeated steps. Use it for retry patterns, polling intervals, or batch processing loops. ``` loop Every 30 seconds Agent->>Server: GET /status Server-->>Agent: 200 {status: pending} end ``` ### Annotate with Notes Sparingly[​](#annotate-with-notes-sparingly "Direct link to Annotate with Notes Sparingly") Notes are helpful for explaining non-obvious business rules, but overusing them clutters the diagram. A good rule of thumb is one note per major section of the diagram. Place notes on the side with the most white space to avoid overlapping arrows. ### Auto-Number Messages[​](#auto-number-messages "Direct link to Auto-Number Messages") Add `autonumber` on the line immediately after `sequenceDiagram`. This numbers every message sequentially, which makes it easy to reference specific steps in a design review or Slack conversation ("let's talk about step 7 in the login diagram"). ### Keep Participant Names Short[​](#keep-participant-names-short "Direct link to Keep Participant Names Short") Long participant names squeeze the horizontal space available for arrows and labels. Use the `participant X as Long Name` pattern so the code remains readable while the rendered diagram stays compact. ### Break Large Diagrams into Smaller Ones[​](#break-large-diagrams-into-smaller-ones "Direct link to Break Large Diagrams into Smaller Ones") If a single diagram exceeds 20 to 25 messages, consider splitting it into two or more diagrams, each covering a distinct phase of the interaction. Link them together on the Confluence page with a brief prose explanation of what each diagram covers. ### Use Styling for Emphasis[​](#use-styling-for-emphasis "Direct link to Use Styling for Emphasis") Mermaid supports inline styling with the `style` keyword. You can highlight critical paths or error states by changing the background color of specific participants: ``` style OrderSvc fill:#ffcccc,stroke:#ff0000 ``` Apply styling judiciously. One or two highlighted participants draw attention; ten highlighted participants create noise. ## Common Mistakes to Avoid[​](#common-mistakes-to-avoid "Direct link to Common Mistakes to Avoid") * **Forgetting `end` keywords.** Every `alt`, `loop`, `opt`, or `par` block must be closed with `end`. Missing `end` is the most common Mermaid syntax error and produces confusing render failures. * **Mixing arrow types incorrectly.** `->>` and `-->>` are the correct operators. Typing a single dash or using `==>>` will cause a parse error. * **Omitting the colon before labels.** Every message arrow must include a colon and label: `A->>B: Label`. Without the colon, Mermaid cannot parse the line. * **Using reserved words as aliases.** Words like `end`, `loop`, and `alt` are reserved. If you need a participant named "End User", use `participant EU as End User`. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [All 30 Mermaid diagram types in Confluence](/blog/faq-mermaid-diagram-types-confluence.md) — complete reference across every diagram type * [Mermaid Plus Diagrams & AI Agent for Confluence usage guide](/apps/mermaid-plus-for-confluence.md) — detailed configuration options, theme settings, and all 30 supported diagram types * [Mermaid Syntax Cheat Sheet](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md) — quick reference for all Mermaid diagram types supported in Confluence * [Mermaid Troubleshooting FAQ](/blog/faq-mermaid-troubleshooting.md) — solutions for common rendering issues, syntax errors, and export problems * [Create Mermaid diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md) — broader guide covering flowcharts, class diagrams, Gantt charts, and more * [Confluence diagram tools compared](/blog/confluence-diagram-tools-comparison.md) — side-by-side comparison of Mermaid, PlantUML, Draw\.io, and Lucidchart for Confluence Sequence diagrams are a high-leverage investment in your team's documentation. A well-written Mermaid sequence diagram takes minutes to create, lives alongside your other Confluence content, and stays up to date with a simple text edit. Install Mermaid Plus Diagrams & AI Agent for Confluence, paste one of the examples above into a page, and start documenting your system interactions today. ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [sequence-diagram](/blog/tags/sequence-diagram.md) * [how-to](/blog/tags/how-to.md) * [diagrams](/blog/tags/diagrams.md) --- # Create State Diagrams in Confluence — Mermaid Syntax & Examples May 2, 2026 · 17 min read [NGPilot](https://ngpilot.com) State diagrams (also called state machine diagrams) model how a system transitions between discrete states in response to events. They are essential for documenting order lifecycles, user authentication flows, CI/CD pipelines, IoT device behavior, and any system where the current state determines what happens next. If your team uses Confluence for technical documentation, embedding state diagrams directly on your pages keeps your design decisions alongside runbooks, architecture decision records, and sprint planning notes. In this tutorial, you will learn how to create state diagrams in Confluence using the Mermaid `stateDiagram-v2` syntax. Every example is copy-paste ready, so you can drop it straight into a Confluence page and see the rendered result immediately. ## Why State Diagrams in Confluence?[​](#why-state-diagrams-in-confluence "Direct link to Why State Diagrams in Confluence?") Teams reach for state diagrams when they need to answer the question: "What states can this thing be in, and how does it move between them?" Unlike flowcharts that emphasize decision branches, or sequence diagrams that focus on message ordering, state diagrams focus on the lifecycle of a single entity. This makes them ideal for: * **Order and fulfillment systems** where an order moves through states like Placed, Paid, Shipped, Delivered, and Cancelled, and the valid transitions depend on the current state * **User authentication and session management** where a user account moves through Unverified, Active, Locked, and Suspended states based on login attempts, email verification, and admin actions * **CI/CD pipelines** where a build progresses through Triggered, Building, Testing, Deploying, and Completed or Failed states * **IoT and embedded systems** where a device switches between Idle, Processing, Error, and Maintenance states in response to sensor readings and timeouts * **Workflow engines** where a ticket or request follows a defined state machine with approval gates, escalation rules, and rollback paths Confluence is where this context already lives. Adding rendered state diagrams directly on those pages eliminates the friction of linking out to external diagramming tools or attaching exported images that go stale the moment the code changes. Mermaid is the most popular text-to-diagram language, and with Mermaid Plus Diagrams & AI Agent for Confluence you get a first-class editing experience right inside the Confluence editor. ## Step-by-Step: Create Your First State Diagram[​](#step-by-step-create-your-first-state-diagram "Direct link to Step-by-Step: Create Your First State Diagram") Follow these five steps to go from a blank Confluence page to a fully rendered state diagram. ### Step 1 -- Install Mermaid Plus Diagrams & AI Agent for Confluence[​](#step-1----install-mermaid-plus-diagrams--ai-agent-for-confluence "Direct link to Step 1 -- Install Mermaid Plus Diagrams & AI Agent for Confluence") Head to the [Atlassian Marketplace](https://marketplace.atlassian.com/) and search for **Mermaid Plus Diagrams & AI Agent for Confluence**. Click **Get App** and follow the installation prompts. Once installed, the Mermaid Plus macro becomes available on every space in your Confluence instance. The app supports both Confluence Cloud and Confluence Data Center. If your organization requires admin approval for marketplace apps, send the link to your Confluence administrator. ### Step 2 -- Insert the Mermaid Macro on a Confluence Page[​](#step-2----insert-the-mermaid-macro-on-a-confluence-page "Direct link to Step 2 -- Insert the Mermaid Macro on a Confluence Page") Open any Confluence page in edit mode. Type `/mermaid` in the editor and select **Mermaid Plus Diagrams & AI Agent for Confluence** from the dropdown. A configuration panel opens with a three-column layout: * **Left column**: Live Preview, which renders your diagram in real time as you type * **Middle column**: Quick Templates for all 30 supported diagram types * **Right column**: Settings (font, colors, theme, output size) and the Code Editor ### Step 3 -- Write the `stateDiagram-v2` Header and Define States[​](#step-3----write-the-statediagram-v2-header-and-define-states "Direct link to step-3----write-the-statediagram-v2-header-and-define-states") Start every state diagram with the `stateDiagram-v2` keyword. This is the updated version of the state diagram syntax and supports all modern features including composite states and notes. Define your states by name, and use `[*]` to mark the initial (start) and final (end) states: ``` stateDiagram-v2 [*] --> Idle Idle --> Processing Processing --> Done Done --> [*] ``` The `[*]` symbol on the left side of a transition marks the starting point. On the right side, it marks a terminal state. You can have multiple terminal states in a single diagram if your system has more than one end condition. ### Step 4 -- Add Transitions, Composite States, and Notes[​](#step-4----add-transitions-composite-states-and-notes "Direct link to Step 4 -- Add Transitions, Composite States, and Notes") This is where state diagrams get powerful. Label your transitions with trigger events, group related states into composite (nested) states, and annotate states with notes: ``` stateDiagram-v2 [*] --> Idle state Active { [*] --> Running Running --> Paused : pause Paused --> Running : resume } Idle --> Active : start Active --> Idle : stop Running --> Error : exception note right of Error Requires manual intervention to reset end note ``` ### Step 5 -- Save and Publish the Diagram[​](#step-5----save-and-publish-the-diagram "Direct link to Step 5 -- Save and Publish the Diagram") Check the live preview in the left column to verify the diagram renders correctly. Adjust the theme, colors, or output size in the right column if needed. When you are satisfied, click **Save** to insert the macro into the page, then **Publish** the Confluence page. To edit the diagram later, click on the rendered diagram in view mode and select **Edit**. All your code and settings are preserved. ## Mermaid State Diagram Syntax Reference[​](#mermaid-state-diagram-syntax-reference "Direct link to Mermaid State Diagram Syntax Reference") Before diving into the full examples, here is a quick-reference for the syntax elements you will use most often. ### Basic Elements[​](#basic-elements "Direct link to Basic Elements") | Element | Syntax | Description | | ------------------ | -------------------------------- | -------------------------------------------------------------------------------- | | State declaration | `StateName` | A state is created implicitly when referenced in a transition | | Start state | `[*]` | The black-circle initial pseudo-state | | End state | `[*]` | The bullseye final pseudo-state (same symbol, on the right side of a transition) | | Transition | `StateA --> StateB` | Arrow from StateA to StateB | | Labeled transition | `StateA --> StateB : event` | Arrow with an event or action label | | Composite state | `state "Name" { ... }` | A state containing nested sub-states | | Note | `note left/right of State` | Annotation attached to a state | | Note (multiline) | `note ... end note` | Multi-line note block | | Direction | `direction LR` or `direction TB` | Control layout direction inside a composite state | | Comment | `%% This is a comment` | Inline comment, not rendered | ### Transition Syntax[​](#transition-syntax "Direct link to Transition Syntax") Transitions are the backbone of any state diagram. The basic form is: ``` SourceState --> TargetState : trigger / action ``` The part after the colon is optional. You can include a trigger event, an action, or both separated by a slash. In practice, most teams use the label to describe what causes the transition: ``` Idle --> Processing : onTaskReceived Processing --> Done : onComplete Processing --> Error : onException Error --> Idle : onReset ``` You can also create self-transitions (a state transitioning to itself), which are useful for modeling retry logic or periodic updates: ``` Polling --> Polling : onTimeout ``` ### Composite (Nested) States[​](#composite-nested-states "Direct link to Composite (Nested) States") Composite states let you group related sub-states inside a parent state. This is essential for managing complexity in real-world state machines. The outer state defines shared behavior, while inner states define the details: ``` stateDiagram-v2 [*] --> Off state On { [*] --> Starting Starting --> Running : initialized Running --> Stopping : shutdown Stopping --> [*] } Off --> On : powerOn On --> Off : powerOff ``` Composite states can nest deeply. A composite state can contain other composite states, allowing you to model hierarchical state machines. However, keep nesting to two or three levels for readability. ### Fork and Join[​](#fork-and-join "Direct link to Fork and Join") Mermaid supports fork and join pseudo-states for modeling concurrent transitions. A fork splits one transition into multiple parallel transitions, and a join synchronizes multiple parallel transitions into one: ``` stateDiagram-v2 [*] --> Waiting state fork_state <<fork>> state join_state <<join>> Waiting --> fork_state fork_state --> StateA fork_state --> StateB StateA --> join_state StateB --> join_state join_state --> Finished Finished --> [*] ``` ### Direction Control[​](#direction-control "Direct link to Direction Control") By default, state diagrams render top-to-bottom. Inside composite states, you can change the direction using the `direction` keyword: ``` state On { direction LR [*] --> Starting Starting --> Running } ``` Valid directions are `LR` (left-to-right), `RL` (right-to-left), `TB` (top-to-bottom), and `BT` (bottom-to-top). Use `direction LR` inside composite states when the sub-states have a natural left-to-right progression. ### State Aliases[​](#state-aliases "Direct link to State Aliases") If a state name contains spaces or special characters, wrap it in quotes and optionally assign an alias: ``` state "Awaiting Approval" as AwaitApproval Idle --> AwaitApproval : submit AwaitApproval --> Approved : approve ``` ### Notes[​](#notes "Direct link to Notes") Notes add context without cluttering the diagram. Use them to explain non-obvious rules, timeout durations, or error conditions: ``` note left of Locked Account locks after 5 consecutive failed attempts end note ``` Notes can also span multiple lines using the `note` ... `end note` block syntax, which is useful for longer explanations. ### Concurrent States[​](#concurrent-states "Direct link to Concurrent States") You can model parallel regions inside a composite state by using the `--` separator between state groups: ``` stateDiagram-v2 [*] --> Active state Active { [*] --> TaskRunning TaskRunning --> TaskDone : finish -- [*] --> Monitoring Monitoring --> Alert : thresholdExceeded Alert --> Monitoring : resolved } Active --> [*] ``` Each region separated by `--` operates independently, which is how you represent truly concurrent behavior in a state machine. ## 3 Copy-Paste State Diagram Examples[​](#3-copy-paste-state-diagram-examples "Direct link to 3 Copy-Paste State Diagram Examples") Below are three practical examples you can paste directly into the Mermaid Plus macro in Confluence. Each example demonstrates a different real-world scenario with progressively more advanced features. ### Example 1 -- E-Commerce Order Lifecycle[​](#example-1----e-commerce-order-lifecycle "Direct link to Example 1 -- E-Commerce Order Lifecycle") This diagram models the complete lifecycle of an e-commerce order, from creation through fulfillment or cancellation. It covers the most common states and transitions that any online store needs to handle. ``` stateDiagram-v2 [*] --> Draft : customer creates cart Draft --> Submitted : checkout Submitted --> PaymentPending : validateOrder state PaymentPending { [*] --> AwaitingPayment AwaitingPayment --> PaymentSuccess : paymentApproved AwaitingPayment --> PaymentFailed : paymentDeclined PaymentFailed --> AwaitingPayment : retryPayment } PaymentPending --> Confirmed : paymentSuccess PaymentPending --> Cancelled : paymentTimeout Confirmed --> Processing : warehousePickup Processing --> Shipped : carrierPickedUp state Delivery { [*] --> InTransit InTransit --> OutForDelivery : atLocalFacility OutForDelivery --> Delivered : deliveryConfirmed OutForDelivery --> DeliveryFailed : deliveryException DeliveryFailed --> InTransit : reschedule } Shipped --> Delivery : trackingActive Delivery --> Completed : deliveryConfirmed Delivery --> Returned : returnRequested Completed --> [*] Cancelled --> [*] Returned --> Refunded : refundProcessed Refunded --> [*] note right of Processing Warehouse allocates inventory and prepares shipment end note note right of Cancelled Order can be cancelled before shipment only end note ``` This diagram demonstrates several key features: 1. **Composite states** -- `PaymentPending` and `Delivery` group related sub-states into logical phases of the order lifecycle 2. **Multiple terminal states** -- The order can end in `Completed`, `Cancelled`, or `Refunded` depending on the path taken 3. **Notes** -- Annotations on `Processing` and `Cancelled` explain business rules that are not obvious from the state names alone 4. **Self-transitions within composites** -- `PaymentFailed --> AwaitingPayment : retryPayment` shows a loop inside a composite state 5. **Cross-composite transitions** -- `Delivery --> Returned` shows a transition out of a composite state to an external state Use this diagram as a starting point for your own order management documentation. Add states for backorders, split shipments, partial refunds, or fraud review as your business requires. ### Example 2 -- User Authentication Flow[​](#example-2----user-authentication-flow "Direct link to Example 2 -- User Authentication Flow") This diagram models a user account state machine covering registration, email verification, login attempts, account locking, and administrative actions. It is representative of what you would document for a SaaS product's identity and access management system. ``` stateDiagram-v2 [*] --> Unregistered : userVisitsSignup Unregistered --> PendingVerification : submitRegistration PendingVerification --> Active : verifyEmail PendingVerification --> Unregistered : verificationExpired state Active { [*] --> LoggedOut LoggedOut --> LoggedIn : loginSuccess LoggedIn --> LoggedOut : logout state LoggedIn { [*] --> Browsing Browsing --> Editing : openEditor Editing --> Browsing : saveOrDiscard Browsing --> Idle : timeout Idle --> Browsing : resumeActivity } } LoggedOut --> Locked : failedAttemptLimit state Locked { [*] --> AutoLocked AutoLocked --> UnlockRequested : requestUnlock UnlockRequested --> Unlocked : adminApproves UnlockRequested --> AutoLocked : adminDenies } Locked --> Active : unlockSuccess Locked --> Suspended : lockTimeout Active --> Suspended : adminSuspends Suspended --> Active : adminReactivates Suspended --> Deleted : adminDeletes Deleted --> [*] note right of Locked Triggered after 5 consecutive failed login attempts end note note left of Suspended Account is frozen. User cannot log in. Admin action required. end note note right of PendingVerification Verification link expires after 24 hours end note ``` This diagram introduces: 1. **Nested composite states** -- `Active` contains `LoggedIn`, which itself contains `Browsing`, `Editing`, and `Idle`, demonstrating three levels of nesting 2. **Cross-state transitions** -- `LoggedOut --> Locked` crosses from inside `Active` into `Locked`, showing how state machines model events that move entities between major lifecycle phases 3. **Multiple notes** -- Notes on `Locked`, `Suspended`, and `PendingVerification` explain business rules without cluttering the transition labels 4. **Admin-driven transitions** -- Several transitions (`adminSuspends`, `adminReactivates`, `adminDeletes`) show that not all state changes are user-driven 5. **Timeout-based transitions** -- `verificationExpired` and `lockTimeout` model time-based state changes common in authentication systems ### Example 3 -- CI/CD Pipeline States[​](#example-3----cicd-pipeline-states "Direct link to Example 3 -- CI/CD Pipeline States") This diagram models a continuous integration and deployment pipeline, from code commit through build, test, deploy, and either success or failure. It is the kind of diagram you would include in a DevOps runbook or platform engineering documentation. ``` stateDiagram-v2 [*] --> Triggered : codePush / PRMerge / schedule state Build { direction LR [*] --> Queued Queued --> Building : agentAssigned Building --> BuildSuccess : exitCode0 Building --> BuildFailed : exitCodeNonZero } Triggered --> Build : pipelineStart state Test { [*] --> UnitTests UnitTests --> IntegrationTests : unitPass IntegrationTests --> E2ETests : integrationPass state E2ETests { [*] --> Provisioning Provisioning --> Running : environmentReady Running --> E2EPass : allTestsPass Running --> E2EFail : testFailure } } Build --> Test : buildSuccess Build --> Failed : buildFailed Test --> Deploy : allTestsPass Test --> Failed : testFailure state Deploy { direction LR [*] --> Staging Staging --> Canary : stagingHealthy Canary --> Production : canaryMetricsHealthy Canary --> Rollback : canaryMetricsDegraded Rollback --> Staging : rollbackComplete } Deploy --> Completed : deploySuccess Deploy --> Failed : deployFailure Failed --> [*] : pipelineTerminated Completed --> [*] state Cleanup { [*] --> TearingDown TearingDown --> Done : resourcesReleased } Completed --> Cleanup : autoCleanup Failed --> Cleanup : autoCleanup Cleanup --> [*] note right of Canary 5% traffic for 10 minutes. Rollback on error rate > 1% or p99 latency > 500ms end note note right of Failed Notifications sent to: - Commit author via Slack - #ci-alerts channel - PagerDuty (on-call) end note note left of Rollback Automatic rollback preserves the last known-good deployment end note ``` This diagram is the most complex of the three and demonstrates the full power of Mermaid state diagrams: 1. **Multiple composite states** -- `Build`, `Test`, `E2ETests`, `Deploy`, and `Cleanup` each encapsulate a distinct pipeline phase 2. **Direction control** -- `direction LR` inside `Build` and `Deploy` renders the sub-states horizontally for better readability when the sub-states are sequential 3. **Nested composites** -- `E2ETests` is a composite state nested inside the `Test` composite state, showing two levels of nesting 4. **Rollback loops** -- `Canary --> Rollback --> Staging` models a recovery loop within the deployment phase 5. **Shared cleanup path** -- Both `Completed` and `Failed` converge into `Cleanup`, demonstrating how state machines model shared teardown logic 6. **Multiple entry triggers** -- The `Triggered` state accepts three different triggers (`codePush`, `PRMerge`, `schedule`), showing how a state can respond to multiple events 7. **Rich notes** -- Notes on `Canary`, `Failed`, and `Rollback` explain operational policies and alerting rules ## Tips for Building Effective State Diagrams[​](#tips-for-building-effective-state-diagrams "Direct link to Tips for Building Effective State Diagrams") ### Start with the States, Then Add Transitions[​](#start-with-the-states-then-add-transitions "Direct link to Start with the States, Then Add Transitions") Begin by listing all the states your entity can be in. Write them as bullet points or a simple list first. Once you have the complete set, draw the transitions between them. This two-pass approach prevents you from missing edge-case states like `Error`, `TimedOut`, or `Cancelled`. ### Use Composite States to Manage Complexity[​](#use-composite-states-to-manage-complexity "Direct link to Use Composite States to Manage Complexity") Any state diagram with more than eight or ten flat states becomes hard to follow. Group related states into composite states. A good rule of thumb: if a set of states shares a common entry or exit transition, they belong in a composite state. ### Label Every Transition[​](#label-every-transition "Direct link to Label Every Transition") Unlabeled transitions (`Idle --> Running`) are ambiguous. What triggers the change? Always add a label (`Idle --> Running : onStartCommand`). The label should describe the event or condition that causes the transition. ### Include Error and Timeout States[​](#include-error-and-timeout-states "Direct link to Include Error and Timeout States") Real systems fail, time out, and get interrupted. Every state diagram should account for error paths and timeout transitions. If your diagram only shows the happy path, it is incomplete. Add `Error`, `Failed`, `TimedOut`, and `Cancelled` states alongside the normal flow. ### Use Notes for Business Rules[​](#use-notes-for-business-rules "Direct link to Use Notes for Business Rules") Notes are the right place for business rules that do not fit neatly into a transition label. Examples: timeout durations, retry limits, approval requirements, and notification rules. Keep notes short -- two or three lines at most. ### Keep the Diagram Focused on One Entity[​](#keep-the-diagram-focused-on-one-entity "Direct link to Keep the Diagram Focused on One Entity") A state diagram should model the lifecycle of a single entity: one order, one user account, one pipeline run. If you find yourself modeling interactions between two different entities, use a sequence diagram instead. See [how to create sequence diagrams in Confluence](/blog/how-to-create-sequence-diagrams-confluence.md) for that use case. ### Use Themes for Visual Consistency[​](#use-themes-for-visual-consistency "Direct link to Use Themes for Visual Consistency") Mermaid Plus Diagrams & AI Agent for Confluence offers four built-in themes: Default, Dark, Forest, and Neutral. Pick one theme for all state diagrams in a space and use it consistently. The Default theme lets you customize node, text, border, line, and background colors to match your company brand. For detailed configuration options, refer to the [Mermaid Plus Diagrams & AI Agent for Confluence usage guide](/docs/Mermaid-Plus-for-Confluence/usage.md). ## Common Mistakes and How to Fix Them[​](#common-mistakes-and-how-to-fix-them "Direct link to Common Mistakes and How to Fix Them") **Using `stateDiagram` instead of `stateDiagram-v2`.** The original `stateDiagram` keyword lacks support for composite states, notes, and direction control. Always use `stateDiagram-v2` for full feature support. **Forgetting `[*]` start and end markers.** Every state machine should have at least one start state (`[*]`) and at least one end state (a transition to `[*]`). Without them, the diagram has no clear entry or exit point, which makes the lifecycle ambiguous. **Missing transition labels.** An unlabeled transition tells the reader that the change happens, but not why. Always add a label: `Idle --> Running : onStart` is clearer than `Idle --> Running`. **Overcrowding with too many states.** A flat state diagram with 15 or more states becomes unreadable. Use composite states to group related sub-states. If the diagram is still too complex, split it into two diagrams: one showing the high-level lifecycle and another showing the details of a specific phase. **Inconsistent naming conventions.** Pick one naming style and stick with it. If your states are `PascalCase`, use `PascalCase` for all of them. Mixing `camelCase`, `snake_case`, and `PascalCase` in the same diagram looks unprofessional and makes the diagram harder to scan. **Notes that are too long.** A note should be a brief annotation, not a paragraph. If you need more than three lines to explain a state, the explanation belongs in the surrounding Confluence page text, not in the diagram itself. ## When to Use State Diagrams vs Other Diagram Types[​](#when-to-use-state-diagrams-vs-other-diagram-types "Direct link to When to Use State Diagrams vs Other Diagram Types") State diagrams are not the right tool for every situation. Here is a quick guide to help you choose the right diagram type for your documentation: * **State diagram** -- Use when documenting entity lifecycles, state machines, order statuses, and any system where the current state determines what transitions are valid * **Sequence diagram** -- Use when documenting message flows between services, API interactions, and step-by-step communication protocols. See [how to create sequence diagrams in Confluence](/blog/how-to-create-sequence-diagrams-confluence.md) * **Class diagram** -- Use when documenting static structure: class hierarchies, domain models, and object relationships. See [how to create class diagrams in Confluence](/blog/how-to-create-class-diagrams-confluence.md) * **Flowchart** -- Use when documenting processes, decision trees, and algorithmic logic with branching paths * **ER diagram** -- Use when documenting database schemas and entity relationships without behavioral semantics Many architecture documents benefit from combining diagram types. A state diagram shows what states an order can be in, a sequence diagram shows how the services communicate during each transition, and a class diagram shows the domain model that underpins the whole system. ## Advanced: Styling State Diagrams[​](#advanced-styling-state-diagrams "Direct link to Advanced: Styling State Diagrams") Mermaid supports inline styling with the `style` keyword. You can highlight critical states, error states, or the current state in a snapshot diagram by changing colors: ``` stateDiagram-v2 [*] --> Idle Idle --> Running Running --> Error Error --> Idle style Error fill:#ffcccc,stroke:#ff0000,stroke-width:2px style Running fill:#ccffcc,stroke:#00aa00,stroke-width:2px ``` Apply styling judiciously. One or two highlighted states draw attention to the most important parts of the diagram. Highlighting every state creates visual noise. You can also use the Mermaid Plus Diagrams & AI Agent for Confluence theme settings to control the overall color palette. The **Default** theme gives you five customizable color slots (node, text, border, line, and background) that apply across the entire diagram. This is a better approach than inline styles when you want consistent branding across all diagrams in a space. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Mermaid Plus Diagrams & AI Agent for Confluence usage guide](/apps/mermaid-plus-for-confluence.md) -- configuration panel walkthrough, theme settings, font and color customization, and all 30 supported diagram types * [How to create sequence diagrams in Confluence](/blog/how-to-create-sequence-diagrams-confluence.md) -- document message flows between services with copy-paste Mermaid examples * [Mermaid syntax cheat sheet for Confluence](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md) -- quick reference for all Mermaid diagram types supported in Confluence * [How to create class diagrams in Confluence](/blog/how-to-create-class-diagrams-confluence.md) -- document domain models and class hierarchies with Mermaid class diagrams State diagrams are one of the most effective ways to communicate the behavioral logic of your system. They capture the "what state is this in, and what happens next" question that prose alone struggles to answer clearly. With Mermaid Plus Diagrams & AI Agent for Confluence, creating and maintaining state diagrams is as simple as writing text. Install the app, paste one of the examples above into a Confluence page, and start documenting your system's state machines where they belong -- alongside everything else your team needs. ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [state-diagram](/blog/tags/state-diagram.md) * [how-to](/blog/tags/how-to.md) * [diagrams](/blog/tags/diagrams.md) * [software-design](/blog/tags/software-design.md) --- # How to Create Wireframes and UI Mockups in Confluence with Excalidraw Plus May 2, 2026 · 15 min read [NGPilot](https://ngpilot.com) Wireframes are the backbone of every user interface design process. They let product managers, designers, and engineers align on layout, content hierarchy, and interaction flow before writing a single line of code. With [Excalidraw Plus for Confluence](/docs/Excalidraw-plus-for-Confluence/usage.md), you can create wireframes and UI mockups directly inside your Confluence pages, keeping design artifacts next to requirements, user stories, and technical specs. This tutorial walks through the full wireframing workflow in Excalidraw Plus: from setting up a grid and building component patterns to prototyping multi-screen flows and collaborating with your team. By the end, you will have a repeatable process for producing professional wireframes without leaving Confluence. ## Why wireframe in Confluence?[​](#why-wireframe-in-confluence "Direct link to Why wireframe in Confluence?") Most teams already use Confluence for product requirements, sprint planning, and technical documentation. Storing wireframes in a separate design tool creates friction: links break, versions drift, and non-designers struggle to access files. Excalidraw Plus eliminates that gap by embedding a full drawing canvas into any Confluence page. Key advantages: * **Zero context switching**: Design and document in the same environment. Stakeholders view wireframes inline without opening external tools or downloading files. * **Automatic version history**: Confluence tracks page revisions, so every wireframe iteration is preserved and recoverable. * **Collaboration by default**: Anyone with page access can view the wireframe. Editors can open the Excalidraw canvas to suggest changes or add annotations. * **Export flexibility**: Export wireframes as PNG or SVG for presentations, or keep them as JSON backups for archival. ## Prerequisites[​](#prerequisites "Direct link to Prerequisites") Before you start, make sure you have the following: * A Confluence Cloud instance with admin or space-level permissions to install apps. * [Excalidraw Plus for Confluence](/docs/Excalidraw-plus-for-Confluence/usage.md) installed from the Atlassian Marketplace. * A Confluence page where you want to embed your wireframe (a product requirements page, epic description, or dedicated design spec page all work well). ## Step 1 -- Install Excalidraw Plus for Confluence[​](#step-1----install-excalidraw-plus-for-confluence "Direct link to Step 1 -- Install Excalidraw Plus for Confluence") If your team has not installed the app yet: 1. Log in to your Confluence instance as an administrator. 2. Navigate to the Atlassian Marketplace (or go to **Settings** then **Manage apps**). 3. Search for "Excalidraw Plus for Confluence". 4. Click **Get app** or **Try it free** and follow the installation wizard. The app installs a macro that you can insert on any Confluence page. No additional browser extensions or desktop software are required. ## Step 2 -- Insert the Excalidraw macro on a Confluence page[​](#step-2----insert-the-excalidraw-macro-on-a-confluence-page "Direct link to Step 2 -- Insert the Excalidraw macro on a Confluence page") Once the app is installed, adding a wireframe canvas takes seconds: 1. Open the Confluence page where you want the wireframe and click **Edit**. 2. Type `/excalidraw` in the editor body and select **Excalidraw Plus** from the macro dropdown. You can also click the **+** button in the toolbar, search for "Excalidraw Plus", and click to insert. 3. The Excalidraw editor opens inline on your page. You now have a full drawing canvas with shapes, text, arrows, freehand tools, and a library panel. The editor supports the full Excalidraw feature set: rectangles, diamonds, circles, arrows, lines, freehand pencil, text labels, and color styling. ## Step 3 -- Set up a layout grid for your wireframe[​](#step-3----set-up-a-layout-grid-for-your-wireframe "Direct link to Step 3 -- Set up a layout grid for your wireframe") Precision matters in wireframing. Misaligned elements distract reviewers and make layouts harder to interpret. Excalidraw Plus includes grid and snap features that keep your wireframes clean. ### Enable the grid[​](#enable-the-grid "Direct link to Enable the grid") 1. Open the Excalidraw editor on your page. 2. Toggle the **grid** option in the canvas settings. A dot-grid or line-grid overlay appears on the canvas. 3. Enable **snap to grid** so that shapes and text snap to grid intersections as you drag them. ### Choose your grid rhythm[​](#choose-your-grid-rhythm "Direct link to Choose your grid rhythm") For most web wireframes, a 12-column grid at 60-80 pixel column width works well. While Excalidraw does not enforce a specific column count, you can simulate one by: * Drawing thin vertical guide lines at equal intervals to mark column boundaries. * Grouping the guide lines together so they move as a single unit. * Locking the guide group to prevent accidental edits. For mobile wireframes, use a narrower canvas (roughly 375-428 pixels wide) and a 4-column grid. ### Tips for grid-based layouts[​](#tips-for-grid-based-layouts "Direct link to Tips for grid-based layouts") * **Consistent spacing**: Use the same gap between elements throughout the wireframe. A 16-pixel or 24-pixel spacing rhythm is standard in most design systems. * **Alignment**: Align text labels and shape edges to the same grid lines. This visual consistency makes wireframes easier to scan. * **Bounding boxes**: Draw a large rectangle to represent the browser viewport or mobile screen, then place all components inside it. This frames the wireframe and clarifies the intended canvas size. ## Step 4 -- Build wireframe components using shape libraries[​](#step-4----build-wireframe-components-using-shape-libraries "Direct link to Step 4 -- Build wireframe components using shape libraries") Excalidraw Plus provides a library panel with pre-made shapes. For wireframing, you will primarily use basic geometric shapes combined with text labels to represent UI components. Below are the core component patterns you can build. ### Buttons[​](#buttons "Direct link to Buttons") Buttons are the most common interactive element. To create a wireframe button: 1. Draw a **rounded rectangle** (use the rectangle tool, then adjust corner radius). 2. Add a **text label** centered inside the rectangle (for example, "Submit", "Cancel", "Add to Cart"). 3. Style the fill color to indicate button hierarchy: a solid fill for primary actions, a border-only outline for secondary actions, and a lighter fill for tertiary or ghost buttons. **Button variations to include in your wireframe library:** | Button type | Visual treatment | Use case | | ----------- | -------------------------------------------- | ---------------------------------- | | Primary | Solid fill, white text | Main CTA (Submit, Save, Confirm) | | Secondary | Border outline, dark text | Alternative actions (Cancel, Back) | | Destructive | Red solid fill | Dangerous actions (Delete, Remove) | | Icon button | Small square or circle with icon placeholder | Toolbar actions | | Toggle | Rounded rectangle that switches fill state | On/off settings | ### Form inputs[​](#form-inputs "Direct link to Form inputs") Forms are central to most applications. To wireframe a form field: 1. Draw a **rectangle** with a thin border to represent the input box. 2. Add a **small text label** above or to the left of the box (for example, "Email Address", "Password"). 3. Optionally draw a **thin line** inside the box to hint at placeholder text (for example, a faint ""). 4. For dropdowns, add a small **triangle** or chevron shape at the right edge of the input box. **Form input patterns:** | Input type | Wireframe representation | | ------------- | ------------------------------------------------------ | | Text input | Rectangle with label above | | Textarea | Taller rectangle with multiple faint lines inside | | Dropdown | Rectangle with small downward triangle at right | | Checkbox | Small square with optional checkmark line inside | | Radio button | Small circle with optional filled inner circle | | Toggle switch | Rounded rectangle with a small circle inside | | File upload | Dashed rectangle with an upward arrow icon placeholder | ### Navigation bars[​](#navigation-bars "Direct link to Navigation bars") Navigation bars establish the page structure. To create a top navigation wireframe: 1. Draw a **horizontal rectangle** spanning the full width of your viewport frame. 2. Add a **text label or logo placeholder** (a small rectangle) on the left side. 3. Add **text labels** for each nav item spaced evenly across the bar. 4. Optionally underline or bold one item to indicate the active page. For side navigation: 1. Draw a **vertical rectangle** along the left edge of the viewport. 2. Stack **small rectangles or text labels** vertically inside the sidebar to represent menu items. 3. Add **indentation** (offset text labels to the right) to indicate nested sub-items. ### Cards[​](#cards "Direct link to Cards") Cards are ubiquitous in modern UI design. To wireframe a card component: 1. Draw a **rounded rectangle** for the card container. 2. Add a **thin horizontal line** or spacing near the top to separate a header area. 3. Place a **smaller rectangle** or image placeholder in the upper portion for a thumbnail or hero image. 4. Add **text lines** below the image placeholder to represent a title (one thicker line) and description (two or three thinner lines). 5. Optionally add a **row of small shapes** at the bottom to represent action buttons or metadata (date, tags, author). **Card pattern layout (textual description):** ``` +--------------------------------------+ | [Image placeholder - gray rectangle]| | | +--------------------------------------+ | Title line (bold, single line) | | Description line 1 (thinner) | | Description line 2 (thinner) | +--------------------------------------+ | [Tag] [Tag] [Action btn] | +--------------------------------------+ ``` ### Modals and dialogs[​](#modals-and-dialogs "Direct link to Modals and dialogs") Modal overlays draw attention to critical actions. To wireframe a modal: 1. Draw a **semi-transparent rectangle** covering the full viewport to represent the backdrop overlay. 2. On top of it, draw a **centered rounded rectangle** for the modal container. 3. Add a **header row** with a title and an "X" close icon (a small circle or cross). 4. Add **content area** with text lines or form inputs. 5. Add a **footer row** with action buttons (for example, "Cancel" and "Confirm"). **Modal pattern layout:** ``` +============================================+ | Modal Title [X] | |--------------------------------------------| | | | Content area: text, form fields, | | or other components go here. | | | |--------------------------------------------| | [Cancel] [Confirm] | +============================================+ ``` ### Tables and data grids[​](#tables-and-data-grids "Direct link to Tables and data grids") For data-heavy interfaces, wireframe tables using: 1. A **large rectangle** as the table container. 2. A **darker or thicker row** at the top for column headers. 3. **Horizontal lines** dividing rows. 4. **Vertical lines** dividing columns. 5. Small **icon shapes** in header cells to indicate sortable columns (tiny triangles). ### Reusable component tips[​](#reusable-component-tips "Direct link to Reusable component tips") * **Group elements**: Select all shapes that make up a component (for example, the card rectangle, its image placeholder, and text lines), then group them. Grouped elements move and resize together. * **Duplicate for consistency**: Once you build one card, duplicate it to create additional cards with the same proportions. This maintains visual consistency across your wireframe. * **Save to library**: Save frequently used components to the Excalidraw library panel so you can drag them into future wireframes without rebuilding from scratch. * **Use consistent colors**: Limit your palette to 3-4 grayscale tones plus one accent color. Wireframes should be low-fidelity; color should indicate interaction states, not final visual design. ## Step 5 -- Create multi-screen wireframe flows[​](#step-5----create-multi-screen-wireframe-flows "Direct link to Step 5 -- Create multi-screen wireframe flows") A single screen rarely tells the full story. Most user workflows span multiple pages or states. Excalidraw Plus makes it easy to lay out multiple wireframe screens on a single canvas. ### Organize screens on the canvas[​](#organize-screens-on-the-canvas "Direct link to Organize screens on the canvas") 1. Space viewport frames horizontally (left to right) to represent the primary user flow. 2. Draw **arrows** between frames to indicate navigation or state transitions. 3. Label each arrow with the **trigger action** (for example, "User taps Submit", "System loads results", "Error state"). 4. Add **screen titles** above each viewport frame (for example, "Screen 1: Login", "Screen 2: Dashboard", "Screen 3: Error"). ### Annotate interaction details[​](#annotate-interaction-details "Direct link to Annotate interaction details") Use text callouts and arrows to explain interactions that are not obvious from the visual layout alone: * **Hover states**: Draw a small annotation box next to an element that says "On hover: tooltip appears" or "On hover: button changes to filled state." * **Error states**: Duplicate a form screen and add red-highlighted error messages below the relevant fields. Connect it to the normal state with a labeled arrow. * **Loading states**: Draw a skeleton screen or spinner placeholder to show what the user sees while data loads. ### Prototyping workflow tips[​](#prototyping-workflow-tips "Direct link to Prototyping workflow tips") While Excalidraw Plus does not generate clickable prototypes, you can simulate a prototyping workflow within Confluence: 1. **Create a dedicated wireframe page**: Use a parent page titled "Wireframes -- \[Feature Name]" and add child pages for each major flow. 2. **Link screens**: Use Confluence page links or anchor links to connect related wireframe pages, creating a navigable prototype experience. 3. **Embed multiple macros**: Place several Excalidraw macros on the same page, each containing a different screen or state. Add text descriptions between them to narrate the user journey. 4. **Review cycle**: Ask stakeholders to add comments directly on the Confluence page. Inline comments can reference specific wireframe screens by position or label. 5. **Version tracking**: Each time you publish the page, Confluence creates a revision. Use the page history to compare wireframe iterations over time. ## Wireframe fidelity levels[​](#wireframe-fidelity-levels "Direct link to Wireframe fidelity levels") Different stages of the design process call for different levels of detail. Excalidraw Plus supports the full spectrum. ### Low-fidelity wireframes[​](#low-fidelity-wireframes "Direct link to Low-fidelity wireframes") Best for early exploration and brainstorming. * Use **simple rectangles and lines** only. * Omit real text; use placeholder lines (gray bars) to represent content. * Focus on **layout and hierarchy**, not visual polish. * Build quickly to evaluate multiple layout options side by side. ### Medium-fidelity wireframes[​](#medium-fidelity-wireframes "Direct link to Medium-fidelity wireframes") Best for stakeholder reviews and requirements documentation. * Add **realistic text labels** (actual button copy, headings, form field names). * Include **component patterns** (proper button styles, navigation structure, card layouts). * Annotate with **interaction notes** and state descriptions. * Use **consistent spacing and alignment** via the grid. ### High-fidelity mockups[​](#high-fidelity-mockups "Direct link to High-fidelity mockups") Best for handoff to developers or visual designers. * Apply **realistic proportions** and pixel-accurate spacing. * Include **actual content** (real text, image placeholders with correct aspect ratios). * Use **grayscale plus one accent color** to distinguish interactive elements. * Add **detailed annotations** for animations, transitions, and responsive breakpoints. ## Wireframing best practices[​](#wireframing-best-practices "Direct link to Wireframing best practices") Keep these principles in mind as you build wireframes in Confluence: ### Start with content, not chrome[​](#start-with-content-not-chrome "Direct link to Start with content, not chrome") Before drawing navigation bars and footers, list the content that each screen needs to display. Arrange content blocks first, then wrap them in chrome (headers, sidebars, footers). This prevents the layout from dictating the content. ### Use real text, not lorem ipsum[​](#use-real-text-not-lorem-ipsum "Direct link to Use real text, not lorem ipsum") Realistic text helps stakeholders evaluate whether the layout accommodates actual content. If real copy is not available, use text that matches the expected length and tone. "Lorem ipsum" obscures content fit issues. ### Label everything[​](#label-everything "Direct link to Label everything") Add text labels to every interactive element, even in low-fidelity wireframes. Reviewers should never have to guess what a shape represents. A button that says "Primary CTA" is clearer than an unlabeled rectangle. ### Show multiple states[​](#show-multiple-states "Direct link to Show multiple states") Do not wireframe only the happy path. Include error states, empty states, loading states, and edge cases. This catches usability problems early and gives developers a complete picture of what to build. ### Keep wireframes separate from visual design[​](#keep-wireframes-separate-from-visual-design "Direct link to Keep wireframes separate from visual design") Wireframes communicate structure and interaction, not visual aesthetics. Avoid spending time on colors, fonts, or pixel-perfect alignment at the wireframe stage. Save visual refinement for a dedicated design tool or a later iteration. ### Organize your Confluence wireframe library[​](#organize-your-confluence-wireframe-library "Direct link to Organize your Confluence wireframe library") Over time, your team will accumulate a set of reusable wireframe components. Keep them organized: * Create a **Confluence space** or parent page dedicated to wireframe libraries. * Store frequently used Excalidraw component groups as **separate macro instances** that team members can copy. * Use **consistent naming conventions** for wireframe pages (for example, "Wireframe: \[Feature] -- \[Screen] -- \[State]"). * Tag wireframe pages with a common label so they are easy to find via Confluence search. ## Exporting and sharing wireframes[​](#exporting-and-sharing-wireframes "Direct link to Exporting and sharing wireframes") Excalidraw Plus supports multiple export formats: * **PNG**: Best for embedding wireframes in presentations, emails, or external documents. Use a transparent background if you plan to overlay the wireframe on other content. * **SVG**: Best for scalable wireframes that need to look crisp at any size. SVG is also editable in vector tools like Figma, Sketch, or Illustrator. * **JSON**: Use JSON export to create backups of your wireframes or to transfer them between Confluence instances. To export, click the menu icon in the Excalidraw editor and choose your preferred format. The exported file preserves all shapes, text, and styling. ## Common wireframe patterns for popular layouts[​](#common-wireframe-patterns-for-popular-layouts "Direct link to Common wireframe patterns for popular layouts") Here are textual descriptions of common layout patterns you can recreate in Excalidraw Plus. ### Dashboard layout[​](#dashboard-layout "Direct link to Dashboard layout") ``` +----------------------------------------------------------+ | [Logo] Nav Item 1 Nav Item 2 Nav Item 3 [Avatar] | +----------+-----------------------------------------------+ | | +----------+ +----------+ +----------+ | | Sidebar | | Metric | | Metric | | Metric | | | Menu | | Card 1 | | Card 2 | | Card 3 | | | Items | +----------+ +----------+ +----------+ | | | +-------------------------------------------+| | | | || | | | Chart / Data Visualization || | | | || | | +-------------------------------------------+| +----------+-----------------------------------------------+ ``` Build this by drawing a top navigation bar, a left sidebar with stacked text items, metric cards (small rounded rectangles with number labels), and a large chart area (a rectangle with grid lines to suggest a graph). ### E-commerce product page layout[​](#e-commerce-product-page-layout "Direct link to E-commerce product page layout") ``` +----------------------------------------------------------+ | [Logo] Home Categories Sale [Search] [Cart] | +----------------------------------------------------------+ | | | | [Product Image | Product Title | | Placeholder] | $XX.XX | | | [Variant selector] | | | [Quantity] [Add to Cart btn] | | | Description text lines... | +----------------------------------------------------------+ | Related Products | | [Card 1] [Card 2] [Card 3] [Card 4] | +----------------------------------------------------------+ ``` Use a split layout (two columns in the upper section) with an image placeholder on the left and product details on the right, followed by a full-width related products row. ### Settings page layout[​](#settings-page-layout "Direct link to Settings page layout") ``` +----------------------------------------------------------+ | [Logo] Dashboard Projects [Avatar] [Settings] | +----------+-----------------------------------------------+ | | Account Settings | | Profile | +-------------------------------------------+| | Security | | Field Label || | Notif. | | [Input field ] || | Billing | +-------------------------------------------+| | API Keys | | Field Label || | | | [Input field ] || | | +-------------------------------------------+| | | [Save Changes] | +----------+-----------------------------------------------+ ``` Draw a vertical sidebar with settings categories and a main content area with stacked form field patterns. ## Collaborating on wireframes in Confluence[​](#collaborating-on-wireframes-in-confluence "Direct link to Collaborating on wireframes in Confluence") One of the biggest advantages of wireframing inside Confluence is the collaboration workflow: 1. **Inline comments**: Team members can add Confluence comments directly on the page, referencing specific wireframe sections. Use @mentions to loop in designers, developers, or product managers. 2. **Page history**: Every save creates a new version. Compare versions to see what changed between iterations. This is especially useful during design reviews. 3. **Permissions**: Control who can edit the wireframe versus who can only view it using Confluence page restrictions. 4. **Integration with Jira**: Link wireframe pages to Jira epics or stories. Developers can open the wireframe directly from the issue, ensuring the design context is always accessible. 5. **Notifications**: When you update and republish the wireframe page, watchers receive a notification. This keeps stakeholders informed without manual status emails. ## Troubleshooting common issues[​](#troubleshooting-common-issues "Direct link to Troubleshooting common issues") | Issue | Solution | | ------------------------------------------ | -------------------------------------------------------------------------------------------------------- | | Wireframe does not render in page view | Click outside the Excalidraw editor, save the Confluence page, and wait for the sync confirmation. | | Shapes appear misaligned | Enable the grid and snap-to-grid, then reposition elements. | | Canvas is too small for multi-screen flows | Scroll to the edge of the canvas and drag outward. Excalidraw canvases expand infinitely. | | Exported PNG is blurry | Use SVG export instead, or increase the zoom level before exporting. | | Cannot find the macro in the editor | Confirm the app is installed under **Settings** then **Manage apps**. Try typing `/excalidraw` directly. | | Library panel is empty | Load a built-in library from the library menu, or create and save your own component groups. | ## Related resources[​](#related-resources "Direct link to Related resources") * [Excalidraw Plus for Confluence -- documentation](/apps/excalidraw-plus-for-confluence.md) * [Excalidraw best practices FAQ](/blog/faq-excalidraw-best-practices.md) * [Confluence whiteboard apps -- which one fits your team?](/blog/faq-confluence-whiteboard-apps.md) * [How to create architecture diagrams in Confluence](/blog/how-to-create-architecture-diagrams-confluence.md) * [How to create flowcharts in Confluence](/blog/create-flowcharts-confluence.md) * [Confluence diagram tools compared](/blog/confluence-diagram-tools-comparison.md) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [excalidraw](/blog/tags/excalidraw.md) * [wireframe](/blog/tags/wireframe.md) * [mockup](/blog/tags/mockup.md) * [how-to](/blog/tags/how-to.md) * [ui-design](/blog/tags/ui-design.md) --- # How to Evaluate an Atlassian Marketplace App: A Security Checklist August 2, 2026 · 10 min read [NGPilot](https://ngpilot.com) Quick Answer Before installing any Atlassian Marketplace app, run it through this checklist: verify **Cloud Fortified** status, confirm whether it is **Forge or Connect**, review the **OAuth scopes** it requests, read its **privacy and data handling disclosure**, and check its **install count, ratings, and release cadence**. Apps that pass all five are low-risk; apps that fail any of them deserve a closer look before they touch your production site. What you'll learn 1. The trust signals Atlassian exposes on every Marketplace listing 2. How to read an app's permission scopes before installing 3. Why Forge and Connect carry different security burdens 4. The questions to ask a vendor during a security review 5. A copy-paste checklist you can run on any app in under five minutes The Atlassian Marketplace has thousands of apps, and installing the wrong one can expose your Jira and Confluence data to a vendor you have never vetted. The good news is that Atlassian surfaces most of what you need to make a safe decision directly on each listing — if you know where to look. This guide is a practical checklist for evaluating any Marketplace app before it lands on your site, written for the admins who get asked "is this app okay to install?" and need to answer with confidence. ## The five trust signals on every Marketplace listing[​](#the-five-trust-signals-on-every-marketplace-listing "Direct link to The five trust signals on every Marketplace listing") Atlassian exposes a set of badges and disclosures on each app's Marketplace page. They are not decorative — each one tells you something specific about the app's security and reliability posture. Here is what each means and how much weight to give it. ### 1. Cloud Fortified[​](#1-cloud-fortified "Direct link to 1. Cloud Fortified") Cloud Fortified is Atlassian's trust tier for apps that go beyond baseline requirements. To earn it, an app must: * **Complete the Privacy and Security tab** on its Marketplace listing — a structured disclosure of its data handling, storage, and compliance practices, researched and designed around what enterprise buyers actually ask. * **Participate in the Marketplace Security Bug Bounty Program** (hosted on Bugcrowd), meaning security researchers can test the app for vulnerabilities and the vendor pays rewards for valid findings. Apps in the program display a green checkmark. * **Meet reliability requirements** around uptime and incident response. * **Meet support requirements** with defined response times. As of 2026, new Cloud Fortified designations require the app to be built on **Forge**. This is the single strongest trust signal on the Marketplace — if an app has it, a substantial part of your security review is already done. ### 2. Built on Forge (vs Connect)[​](#2-built-on-forge-vs-connect "Direct link to 2. Built on Forge (vs Connect)") The framework an app uses determines where its code runs and where your data goes. This matters more than most admins realize. * **Forge apps** run on Atlassian-managed infrastructure. The compute, storage, and UI all live inside Atlassian's platform. Permissions are declared in a manifest and enforced by the platform — an app literally cannot access data outside the scopes it requested and Atlassian approved. No vendor-controlled server processes your data. * **Connect apps** run on the vendor's own servers. The vendor is responsible for encryption, patching, access control, and breach response. Atlassian reviews Connect apps at submission, but ongoing security depends entirely on the vendor's maturity — which varies wildly across the ecosystem. For a deeper treatment of the architectural difference and the 2026 Connect penalty, see our [Forge vs Connect guide](/blog/forge-vs-connect-atlassian-admins-2026.md). The short version for security review: **Forge shifts the security burden to Atlassian; Connect leaves it with the vendor.** If you are evaluating an app that handles sensitive data and it is Connect-based, the vendor review is on you. ### 3. OAuth scopes and permissions[​](#3-oauth-scopes-and-permissions "Direct link to 3. OAuth scopes and permissions") At install time, every app presents the permissions it is requesting. This is not a formality — it is the most direct signal of what the app can actually do with your data. Look for: * **Scope granularity.** A diagraming app requesting only `read:confluence-content` and `write:confluence-content` is scoped appropriately. The same app requesting `read:jira-user` or admin-level scopes should prompt a question. * **Broad vs narrow.** Phrases like "access all data" or "full access" are red flags. Prefer apps that request the minimum scopes needed for their function — this is least-privilege access, and Atlassian enforces it for Forge apps. * **Egress declarations.** Forge apps must declare any external endpoints they call. If an app declares egress to a third-party analytics or AI service, that tells you where your data could go. If the scopes an app requests do not match what the app claims to do, stop and ask the vendor why. ### 4. Privacy policy and data handling disclosure[​](#4-privacy-policy-and-data-handling-disclosure "Direct link to 4. Privacy policy and data handling disclosure") The Privacy and Security tab on the Marketplace listing is where the vendor declares how the app handles your data: what it collects, where it is stored, how long it is retained, whether it is shared with third parties, and what happens on uninstall. Read it. Specifically check: * **Data storage location.** Is data stored on Atlassian (Forge), on the vendor's infrastructure (Connect), or transmitted to a third party? For regulated data, the answer determines whether the app is even eligible. * **Data retention.** Does the vendor delete your data on uninstall, or retain it? Retention after uninstall is a common compliance problem. * **Third-party sharing.** Does the app send data to analytics, advertising, or AI subprocessors? These should be named. * **Compliance claims.** SOC 2, GDPR, and ISO 27001 statements belong here if the vendor has them. An app with a missing or vague privacy disclosure is not necessarily malicious, but it is a signal that the vendor has not invested in the trust surface that security-conscious buyers expect. ### 5. Install count, ratings, and release cadence[​](#5-install-count-ratings-and-release-cadence "Direct link to 5. Install count, ratings, and release cadence") These are the social and operational signals: * **Install count and active users** indicate real-world adoption. An app with tens of thousands of installs has been stress-tested across environments; an app with single-digit installs is unproven. * **Star ratings and review count** reflect sustained quality, not just first impressions. Read the negative reviews — they often reveal the failure modes that matter (data loss, broken exports, support responsiveness). * **Release cadence** shows whether the vendor actively maintains the app. A app last updated two years ago is a maintenance risk; an app with regular releases is being invested in. Check the versions tab on the listing. ## A copy-paste checklist[​](#a-copy-paste-checklist "Direct link to A copy-paste checklist") Run this on any app before installing it on a production site. It takes about five minutes once you know where to look. * [ ] **Cloud Fortified?** If yes, much of the review is done. If no, proceed with the rest. * [ ] **Forge or Connect?** Prefer Forge for sensitive data. If Connect, plan a vendor review. * [ ] **Scopes match the function?** Reject apps requesting permissions broader than their purpose. * [ ] **Privacy and Security tab complete?** Check storage location, retention, and third-party sharing. * [ ] **Bug Bounty participant?** Look for the green checkmark — means the app is externally tested. * [ ] **Install count and ratings healthy?** Tens of thousands of installs and a 4+ rating is a strong signal. * [ ] **Recently updated?** Check the versions tab for a healthy release cadence. * [ ] **Vendor responsive?** For critical apps, send a pre-sales question and see how long they take. * [ ] **Data residency matches your requirements?** For regulated industries, confirm where data is stored. * [ ] **Clean uninstall?** Confirm the vendor's data retention policy on uninstall. ## Questions to ask a vendor during a security review[​](#questions-to-ask-a-vendor-during-a-security-review "Direct link to Questions to ask a vendor during a security review") For apps that will touch compliance-relevant data, a short vendor questionnaire is worth the effort. These questions cut through marketing copy: 1. Where exactly is our data stored, and who controls the infrastructure it sits on? 2. What subprocessors do you use, and for what purpose? 3. What is your incident response process and SLA? 4. Do you retain our data after uninstall, and for how long? 5. What scopes does the app request, and can you justify each one? 6. Are you Cloud Fortified, and if not, what is your timeline? 7. What is your vulnerability management process, and do you participate in the Bug Bounty Program? 8. How do you handle data residency for customers with regional requirements? A vendor that answers these clearly and quickly is one you can trust operationally. A vendor that hedges or takes weeks to respond is telling you something important about how they will behave when something goes wrong. ## How NGPILOT apps measure against this checklist[​](#how-ngpilot-apps-measure-against-this-checklist "Direct link to How NGPILOT apps measure against this checklist") Every NGPILOT app is built exclusively on Forge, which means the answer to the hardest security questions is built into the architecture: * **Data never leaves the Atlassian platform.** No NGPILOT-controlled servers process your data — compute and storage are Atlassian-managed. * **Permissions are scoped and platform-enforced.** Each app requests only the scopes it needs, declared in its manifest and enforced by Atlassian. * **No external data egress** to analytics, advertising, or AI subprocessors. * **Clean by design** — there is no vendor infrastructure to audit, patch, or worry about going offline independently of Atlassian. You can read the full security and data handling details on our [Trust Center](/trust.md), or browse the [app catalog](/apps.md) to see which apps fit the problems your team is solving. We also publish [scenario-based solutions](/solutions.md) if you would rather start from the problem you are trying to solve than from an app name. ## Frequently Asked Questions[​](#frequently-asked-questions "Direct link to Frequently Asked Questions") ### What is the most important thing to check before installing a Marketplace app?[​](#what-is-the-most-important-thing-to-check-before-installing-a-marketplace-app "Direct link to What is the most important thing to check before installing a Marketplace app?") If you check only one thing, check whether the app is **Cloud Fortified** — it bundles together privacy disclosure, bug bounty participation, and reliability/support requirements. If the app is not Cloud Fortified, the framework (Forge vs Connect) and the requested scopes are the next most important signals. ### Are paid apps safer than free apps?[​](#are-paid-apps-safer-than-free-apps "Direct link to Are paid apps safer than free apps?") Not necessarily. Safety is determined by the framework, scopes, and vendor practices — not the price tier. A free Forge app with narrow scopes can be safer than a paid Connect app with broad data access. Evaluate free apps with the same checklist. ### What is the Marketplace Security Bug Bounty Program?[​](#what-is-the-marketplace-security-bug-bounty-program "Direct link to What is the Marketplace Security Bug Bounty Program?") It is a program hosted on Bugcrowd where security researchers test Marketplace apps for vulnerabilities and vendors pay rewards for valid findings. Apps that participate display a green checkmark on their listing. It is a strong signal that the app is being externally stress-tested for security flaws. ### Can I install an app on a trial basis to evaluate it?[​](#can-i-install-an-app-on-a-trial-basis-to-evaluate-it "Direct link to Can I install an app on a trial basis to evaluate it?") Yes — every Marketplace app offers a free trial, and Atlassian provides a free tier (up to 10 users) for most apps. A trial lets you observe the app's behavior, scopes, and data handling in a non-production site before committing. Use the trial to run the checklist above against the live app. ### Where can I read Atlassian's official guidance on app security?[​](#where-can-i-read-atlassians-official-guidance-on-app-security "Direct link to Where can I read Atlassian's official guidance on app security?") Atlassian's [Marketplace trust portal](https://www.atlassian.com/trust/marketplace) covers the trust programs and badges, and the [Cloud Fortified security requirements](https://developer.atlassian.com/platform/marketplace/cloud-fortified-apps-program-security-requirements/) document the exact criteria an app must meet. *** *NGPILOT apps are built exclusively on Forge — no customer data leaves the Atlassian platform. Browse the [app catalog](/apps.md) or read our [Trust Center](/trust.md) for the full security and data handling details.* ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [atlassian](/blog/tags/atlassian.md) * [marketplace](/blog/tags/marketplace.md) * [security](/blog/tags/security.md) * [admin](/blog/tags/admin.md) * [explained](/blog/tags/explained.md) --- # How to Migrate Confluence Content — Server-to-Cloud, Space Moves & Format Conversion May 2, 2026 · 15 min read [NGPilot](https://ngpilot.com) Who should read this * **IT admins** running Server/Data Center → Cloud migrations * **Teams** reorganizing Confluence spaces after a reorg or M\&A * **Engineering** converting Confluence content to/from Markdown, HTML, or JSON What you'll learn 1. Which tool fits each scenario — CCMA, built-in XML, or Modern Importer Exporter 2. The 5 most common migration pitfalls (broken links, missing attachments, macro failures) and how to avoid each 3. How to choose an export format by fidelity vs portability 4. A copy-paste **migration checklist** for pre-migration, export, import, and validation Migrating Confluence content is something most teams eventually face. Whether you are moving from Confluence Server to Cloud, reorganizing spaces after a company merger, or splitting a monolithic workspace into focused team spaces, the process can feel overwhelming. Pages link to each other, attachments sit deep in page trees, permissions are inherited from parent spaces, and macros pull data from external sources. This guide walks through the entire Confluence content migration process from start to finish. You will learn how to plan your migration, choose the right tools for your scenario, export and import content without losing data, and validate the result. We cover both Atlassian's built-in export features and the **Modern Importer Exporter for Confluence** app for format-based migrations. ## Common Confluence Migration Scenarios[​](#common-confluence-migration-scenarios "Direct link to Common Confluence Migration Scenarios") Before diving into the how-to, it helps to understand the most common reasons teams migrate Confluence content. Each scenario has slightly different requirements: **Server or Data Center to Cloud migration.** Atlassian ended Server license sales in February 2024 and stopped supporting Server releases entirely. Many organizations are still mid-migration or planning their move. This is the highest-stakes migration scenario because it involves moving everything — spaces, users, apps, and custom configurations — to a completely different hosting model. **Space reorganization.** Teams grow, restructure, and rename departments. A space that once served one team might need to split into three. Pages buried five levels deep in a hierarchy need to move to a flatter structure. This is a content-only migration within the same instance. **Company mergers and acquisitions.** When two organizations merge, their Confluence instances often need to consolidate. This typically involves migrating content from one Confluence Cloud instance to another, or bringing an acquired company's Cloud content into the parent instance. **Backup and archival.** Not every migration is between live systems. Teams export content for compliance archives, offline review, or disaster recovery. The export format matters here — you want something portable that can be re-imported later. **Format conversion.** Sometimes the "migration" is really a format shift: converting Confluence pages to Markdown for a developer wiki, exporting to HTML for a static site, or importing Markdown documentation into Confluence. Each of these scenarios calls for a different combination of tools and techniques. The step-by-step process below works for all of them, with notes on where to adjust for your specific situation. ## Step-by-Step Confluence Content Migration[​](#step-by-step-confluence-content-migration "Direct link to Step-by-Step Confluence Content Migration") ### Step 1: Audit your source content[​](#step-1-audit-your-source-content "Direct link to Step 1: Audit your source content") Before exporting anything, take inventory of what you have. Open your Confluence instance and answer these questions: * **How many spaces need to move?** List every space that is in scope for the migration. Include personal spaces if they contain shared project documentation. * **How many pages are in each space?** You can find this in Space Settings under Content Tools. Spaces with thousands of pages need special handling — batch them in groups of 50 to 100. * **What attachments exist?** Attachments are the most commonly forgotten item in migrations. Count them, check their total file size, and note any unusually large files (videos, databases, high-resolution images). * **What permissions are configured?** Document space-level and page-level restrictions. You will need to reapply these after migration since most export tools do not carry permissions over. * **Which pages are stale?** Use Confluence's built-in Space Statistics or sort pages by "last modified" date. Pages untouched in over a year are candidates for archival rather than migration. * **What macros and integrations are used?** Macros like Jira Issue, Page Properties Report, and third-party macros from marketplace apps may not survive migration intact. Make a list of macro types in use so you can test them after import. **Pro tip:** Create a spreadsheet with columns for space name, page count, attachment count, last modified date, key macros, and migration priority. This becomes your migration plan. ### Step 2: Choose your migration tool[​](#step-2-choose-your-migration-tool "Direct link to Step 2: Choose your migration tool") The tool you choose depends on your migration scenario: **For Server/Data Center to Cloud migration:** Use Atlassian's official **Confluence Cloud Migration Assistant (CCMA)**. This is the only supported path for full instance migrations. CCMA handles spaces, users, groups, and app data. It is a server-side tool that runs on your existing Server or Data Center installation. **For space reorganization within the same instance:** Use Confluence's built-in **space export and import** (XML format). Go to Space Settings, then Content Tools, then Export. Choose XML export for full fidelity including page history, or HTML export for a readable snapshot. Then import into the target space. **For cross-instance content migration or format conversion:** Use **Modern Importer Exporter for Confluence**. This app supports export in ADF JSON, ADF XML, and HTML formats, and import from JSON, XML, HTML, and Markdown. It handles bulk operations across multiple spaces and provides progress tracking. For detailed instructions, see the [Modern Importer Exporter for Confluence documentation](/docs/Modern-Importer-Exporter-for-Confluence/user-docs.md). **For PDF or Word export needs:** If your migration target is a document archive rather than another Confluence instance, consider Scroll PDF Exporter or Scroll Word Exporter by K15t for professional document output with templates and branding. For a full comparison of available tools, see our [Import Export for Confluence Compared](/blog/confluence-import-export-comparison.md) post. ### Step 3: Export content from source[​](#step-3-export-content-from-source "Direct link to Step 3: Export content from source") Once you have chosen your tool and audited your content, it is time to export. The exact steps vary by tool, but the general process is the same. #### Using Confluence's built-in XML export[​](#using-confluences-built-in-xml-export "Direct link to Using Confluence's built-in XML export") 1. Navigate to **Space Settings** for the space you want to export. 2. Go to **Content Tools** and click **Export**. 3. Select **XML** for full fidelity (includes page content, metadata, and attachment references) or **HTML** for a readable copy. 4. Choose whether to include all pages or a custom selection. 5. Click **Export** and wait for the download to complete. The XML export produces a ZIP file containing the space's content in Confluence's internal XML format. This is the best option for importing into another Confluence instance because it preserves the most metadata. #### Using Modern Importer Exporter for Confluence[​](#using-modern-importer-exporter-for-confluence "Direct link to Using Modern Importer Exporter for Confluence") 1. Navigate to **Apps**, then **Modern Importer & Exporter for Confluence**. 2. On the **Export** tab, use the Space Selection dropdown to choose one or more source spaces. 3. Browse the content table and select the pages and blog posts you want to export. Use "Select All" for entire spaces, or pick individual pages. 4. Choose your export format: * **ADF JSON** — Best for re-importing to Confluence. Preserves the most formatting and structure. * **ADF XML** — Good for integration with XML-based systems or tools. * **HTML** — Best for viewing in browsers, publishing to static sites, or converting to other formats. 5. Click **Export** and monitor the progress indicator. Downloads start automatically when complete. 6. For large spaces, break the export into batches of 50 to 100 pages. The app organizes exported files by space in the resulting ZIP archive. **Important:** Neither built-in XML export nor Modern Importer Exporter includes attachments in their standard exports. For attachments, use Confluence's built-in space export with the "Include attachments" option, or download attachments separately. ### Step 4: Import to target instance[​](#step-4-import-to-target-instance "Direct link to Step 4: Import to target instance") With your exported files ready, import them into the target Confluence instance. #### Using Confluence's built-in XML import[​](#using-confluences-built-in-xml-import "Direct link to Using Confluence's built-in XML import") 1. On the target instance, go to **Administration** (gear icon), then **Import & Export**, then **Restore**. 2. Upload the ZIP file from your XML export. 3. Select the target space or choose to create a new space. 4. Review the import summary and click **Import**. 5. Wait for the import to complete. Large imports can take several minutes. #### Using Modern Importer Exporter for Confluence[​](#using-modern-importer-exporter-for-confluence-1 "Direct link to Using Modern Importer Exporter for Confluence") 1. On the target instance, navigate to **Apps**, then **Modern Importer & Exporter for Confluence**. 2. Switch to the **Import** tab. 3. Upload your export files. The app supports JSON, XML, HTML, and Markdown formats. 4. Select the target space from the dropdown. Make sure you have "Add Page" permission in that space. 5. Choose the import mode: * **Override** — Replaces existing content with the imported version. Use this when you want an exact copy. * **Append** — Adds imported content to the end of existing pages. Use this when merging content. 6. Click **Import** and monitor the progress. Review success and error counts when the operation completes. 7. For bulk imports, repeat in batches. The app handles conflict resolution by automatically renaming pages with duplicate titles. **For individual page imports:** You can also right-click any page or blog post and select **Export & Import** from the context menu. This is useful for quickly importing content to a specific page without navigating to the bulk import interface. ### Step 5: Validate and clean up[​](#step-5-validate-and-clean-up "Direct link to Step 5: Validate and clean up") After import, thorough validation is critical. Do not skip this step. **Check page hierarchy.** Verify that parent-child relationships are intact. Pages should appear in the correct order within the space tree. If pages are flattened or misplaced, move them manually or re-import. **Verify links.** Internal links between pages are the most common breakage point in migrations. Open several representative pages and click every link. Links that used absolute URLs (pointing to the old instance) will be broken. Links that used relative paths should still work within the same instance. **Inspect attachments.** If attachments were exported separately, verify they are linked correctly to their parent pages. Download a sample of attachments to confirm they open properly. **Test macros.** Open pages that use macros — especially Jira Issue macros, Page Properties Report macros, and third-party macros. Check that they render correctly and pull the expected data. **Review formatting.** Check tables, code blocks, collapsible sections, and multi-column layouts. These elements sometimes lose formatting during format conversion (for example, when converting HTML back to Confluence's native format). **Reapply permissions.** Since permissions are not preserved during export/import, reconfigure space-level restrictions and page-level restrictions based on the documentation from your audit in Step 1. **Update space settings.** Check space description, space logo, space color theme, and space sidebar configuration. These cosmetic settings are easy to overlook but affect how the space looks to users. ## Common Migration Pitfalls[​](#common-migration-pitfalls "Direct link to Common Migration Pitfalls") Even with careful planning, things go wrong. Here are the five most common issues teams encounter during Confluence migrations and how to fix them. ### Pitfall 1: Broken internal links[​](#pitfall-1-broken-internal-links "Direct link to Pitfall 1: Broken internal links") **The problem:** Pages in Confluence often link to each other using full URLs. When content moves to a new instance, those URLs point to the old server. Visitors see 404 errors instead of the linked page. **The fix:** Before migrating, identify pages with absolute internal links. After migration, use Confluence's search to find and update broken links. If you are migrating within the same instance (space reorganization), relative links will survive the move. For cross-instance migrations, consider using the Confluence REST API to do a bulk find-and-replace of the old base URL with the new one. ### Pitfall 2: Missing attachments[​](#pitfall-2-missing-attachments "Direct link to Pitfall 2: Missing attachments") **The problem:** Attachments are frequently left behind during migrations because many export tools handle page content only. Teams discover the issue weeks later when someone opens a page and sees broken image icons. **The fix:** Always export attachments separately. Confluence's built-in space export has an "Include attachments" checkbox — use it. If you are using Modern Importer Exporter for Confluence, supplement the content export with Confluence's native attachment export. Verify attachment counts match between source and target before considering the migration complete. ### Pitfall 3: Macro rendering failures[​](#pitfall-3-macro-rendering-failures "Direct link to Pitfall 3: Macro rendering failures") **The problem:** Macros that depend on external data (Jira issues, database queries, third-party integrations) may render as blank placeholders or error messages after migration. This happens when the target instance does not have the same apps installed, or when macro configurations reference IDs that do not exist in the new environment. **The fix:** Install all required marketplace apps on the target instance before importing content. For Jira macros, ensure the Jira integration is configured on the target instance. After migration, open each page that uses macros and verify they render correctly. Keep a list of pages with complex macros so you can check them systematically. ### Pitfall 4: Permission and access control gaps[​](#pitfall-4-permission-and-access-control-gaps "Direct link to Pitfall 4: Permission and access control gaps") **The problem:** After migration, users report they cannot access pages they previously could. This happens because permissions are not preserved during most export/import operations. In some cases, the space defaults to "Public" access, exposing sensitive content. **The fix:** Document all permission structures before migration using the audit spreadsheet from Step 1. Immediately after import, apply space-level restrictions first, then page-level restrictions. Consider temporarily restricting the entire migrated space to admins only, then opening access incrementally as you verify each section. ### Pitfall 5: Large space timeouts[​](#pitfall-5-large-space-timeouts "Direct link to Pitfall 5: Large space timeouts") **The problem:** Attempting to export or import an entire space with thousands of pages in one operation causes browser timeouts, server errors, or incomplete exports. The operation appears to hang or fails silently. **The fix:** Break large operations into batches. Modern Importer Exporter for Confluence recommends batches of 50 to 100 pages. Close other browser tabs to free memory. Use a wired internet connection for operations involving more than 1,000 pages. If using built-in XML export, try exporting specific page trees instead of the entire space. ## Confluence Migration Checklist[​](#confluence-migration-checklist "Direct link to Confluence Migration Checklist") Use this checklist to track your migration progress. Each item corresponds to a critical step in the process. ### Pre-migration[​](#pre-migration "Direct link to Pre-migration") * Inventory all spaces, page counts, and attachment counts * Identify stale content for archival (pages not modified in 12+ months) * Document all space-level and page-level permissions * List macros and third-party app integrations in use * Verify admin access on both source and target instances * Notify users of planned migration window * Create a backup of the target instance (in case you need to roll back) ### Export[​](#export "Direct link to Export") * Choose export tool based on migration scenario * Test export with a small sample (5 to 10 pages) * Verify the test export contains expected content and formatting * Export content in batches if spaces are large * Export attachments separately using Confluence's built-in tool * Save all export files in a dated, organized folder structure * Verify export file sizes match expected content volume ### Import[​](#import "Direct link to Import") * Install required marketplace apps on target instance * Configure Jira integration on target instance (if using Jira macros) * Test import with the small sample export * Verify test import: page hierarchy, formatting, links * Import content in batches * Import attachments * Record success/error counts for each batch ### Post-migration validation[​](#post-migration-validation "Direct link to Post-migration validation") * Verify page hierarchy in every migrated space * Spot-check internal links across 10+ representative pages * Verify a sample of attachments download and open correctly * Test macro rendering on pages that use complex macros * Review tables, code blocks, and layouts for formatting issues * Reapply space-level permissions from pre-migration documentation * Reapply page-level restrictions * Update space descriptions, logos, and sidebar configurations * Redirect old URLs to new locations (if cross-instance migration) * Communicate completion to users and provide links to migrated spaces ## Choosing the Right Format for Your Migration[​](#choosing-the-right-format-for-your-migration "Direct link to Choosing the Right Format for Your Migration") The export format you choose affects what survives the migration. Here is a quick guide: | Format | Best For | Fidelity | Re-importable | | ----------------------------- | ------------------------------------------------------- | ------------------------------------------ | -------------------------------------------------------------- | | **XML (Confluence built-in)** | Full space migration between Confluence instances | High — preserves metadata, page history | Yes, via Confluence's restore function | | **ADF JSON** | Content migration with Modern Importer Exporter | High — native Confluence document format | Yes, via Modern Importer Exporter import | | **ADF XML** | Integration with XML-based systems | High — full structure preserved | Yes, via Modern Importer Exporter import | | **HTML** | Web publishing, static site generation, offline viewing | Medium — complex layouts may be simplified | Yes, basic conversion back to Confluence format | | **Markdown** | Developer wikis, GitHub/GitLab integration | Low to medium — limited formatting support | Import only (cannot be exported from Modern Importer Exporter) | For the highest fidelity migration between Confluence instances, use either Confluence's built-in XML export or ADF JSON export with Modern Importer Exporter. For migrations where the target is not Confluence (a static site, a different wiki, or an archive), HTML or Markdown are more appropriate. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Modern Importer Exporter for Confluence Documentation](/apps/modern-importer-exporter-for-confluence.md) — Complete user guide for the import/export app, including bulk operations and format details. * [Import Export for Confluence Compared](/blog/confluence-import-export-comparison.md) — Side-by-side comparison of every Confluence import/export app on the Atlassian Marketplace, with feature breakdowns and honest pros and cons. * [Export Jira Issues to Excel/CSV](/blog/export-jira-issues-to-excel.md) — If your Confluence migration involves Jira-linked content, this guide covers exporting Jira issues for reference. * [Confluence import/export comparison](/blog/confluence-import-export-comparison.md) — Side-by-side feature comparison of import/export apps ## More Related Guides[​](#more-related-guides "Direct link to More Related Guides") * [How to add custom fonts in Confluence](/blog/how-to-add-custom-fonts-confluence.md) — Customize Confluence appearance * [Create flowcharts in Confluence](/blog/create-flowcharts-confluence.md) — Create diagrams * [Modern Importer documentation](/apps/modern-importer-exporter-for-confluence.md) — Complete feature guide *** Have questions about your Confluence migration? Reach out at — we help teams plan and execute content migrations every week. Try Modern Importer & Exporter for Confluence Bulk import/export between JSON, XML, HTML, and Markdown formats — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/977066696/modern-importer-exporter-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-importer-exporter-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [migration](/blog/tags/migration.md) * [import](/blog/tags/import.md) * [export](/blog/tags/export.md) * [how-to](/blog/tags/how-to.md) --- # How to Set Up Announcement Banners in Confluence and Jira May 23, 2026 · 7 min read [NGPilot](https://ngpilot.com) Announcement banners are the most visible communication channel in Atlassian products. They sit at the top of every page, impossible to miss. When you need to notify your entire organization about a maintenance window, a security alert, a policy change, or an upcoming event, banners guarantee visibility in a way that emails and Slack messages cannot. Both Confluence and Jira support announcement banners, but their native implementations are limited. This guide covers how to set up banners in both platforms using built-in features and marketplace apps, with practical tips for getting the most out of them. ## Confluence Announcement Banners[​](#confluence-announcement-banners "Direct link to Confluence Announcement Banners") ### Method 1: Native Confluence banner (basic)[​](#method-1-native-confluence-banner-basic "Direct link to Method 1: Native Confluence banner (basic)") Confluence Cloud does not have a global announcement banner feature comparable to Jira's. Space administrators can add a banner-like element using a few workarounds: **Option A — Use a page banner macro.** Some Confluence instances include a page banner or notification macro. Add it to the top of key pages to display a prominent message. The downside is that you need to add it to each page individually — there is no global banner that appears across all pages. **Option B — Use a global page template.** Create a page template that includes a styled information panel at the top. Teams using this template will see the banner content on every new page created from it. This works for new pages but does not affect existing content. **Option C — Use an app.** Several Confluence apps provide notification or banner functionality. These apps add a macro or panel that can display persistent messages across your Confluence space. ### Method 2: Using macros for prominent notifications[​](#method-2-using-macros-for-prominent-notifications "Direct link to Method 2: Using macros for prominent notifications") If your goal is to display a notice that stands out from regular page content, Confluence's built-in macros can help even without a dedicated banner feature: * **Info panel macro** — creates a blue highlighted panel for general information * **Warning panel macro** — creates a red highlighted panel for urgent notices * **Note panel macro** — creates a yellow highlighted panel for important reminders These macros work on individual pages. For organization-wide announcements, you would need to add them to the most-visited pages manually. ### Best practices for Confluence banners[​](#best-practices-for-confluence-banners "Direct link to Best practices for Confluence banners") * **Create a dedicated "Announcements" page** in each space and link to it from the space sidebar. Pin important announcements at the top. * **Use page restrictions** to control who can edit announcement pages, preventing accidental changes. * **Include dates** in every announcement so readers know whether the information is current. * **Archive old announcements** to a separate page to keep the active announcement page clean. ## Jira Announcement Banners[​](#jira-announcement-banners "Direct link to Jira Announcement Banners") ### Method 1: Native Jira banner[​](#method-1-native-jira-banner "Direct link to Method 1: Native Jira banner") Jira has a built-in announcement banner that appears at the top of every Jira page. Here is how to set it up: **For Jira Cloud:** 1. Go to **Settings** (gear icon) > **System** 2. Navigate to **User management** > **Announcement banner** 3. Enter your banner text in the message field 4. Choose visibility: **Public** (all users) or **Private** (logged-in users only) 5. Click **Set Banner** to activate The native banner supports plain text only. You cannot add formatting, links, images, or colors. **For Jira Data Center:** 1. Go to **Administration** > **System** 2. Select **Announcement Banner** from the left sidebar 3. Enter the announcement text 4. Choose the visibility level 5. Click **Update** to save ### Limitations of the native Jira banner[​](#limitations-of-the-native-jira-banner "Direct link to Limitations of the native Jira banner") The native Jira announcement banner has several constraints that make it difficult to manage for teams with frequent announcements: * **Plain text only** — no rich text formatting, no links, no images * **One banner at a time** — you can only have a single active announcement * **No scheduling** — banners must be manually enabled and disabled * **No dismissal** — users cannot dismiss a banner they have already seen * **No saved templates** — every new banner requires retyping the message * **Global only** — the same banner appears to every user on the instance ### Method 2: Modern Announcement Banner for Jira (recommended)[​](#method-2-modern-announcement-banner-for-jira-recommended "Direct link to Method 2: Modern Announcement Banner for Jira (recommended)") [Modern Announcement Banner for Jira](/docs/Modern-Announcement-Banner-for-Jira/user-docs.md) extends Jira's native banner with features that make it practical for ongoing use. Here is how to set it up: **Step 1 — Install the app** Go to the [Atlassian Marketplace](https://marketplace.atlassian.com/) and search for **Modern Announcement Banner for Jira**. Click **Get App** and follow the installation prompts. The app supports Jira Cloud. **Step 2 — Create your first announcement** After installation, go to the app configuration in your Jira administration panel. Click **Add Announcement** and enter: * **Message text** — the announcement content (plain text with emoji support) * **Visibility** — Public (all users) or Private (follows Jira privacy settings) * **Dismissible** — whether users can dismiss the banner after reading it **Step 3 — Enable the banner** Click **Enable** to activate the announcement. It appears at the top of every Jira page for all users (or restricted users, depending on your visibility setting). **Step 4 — Manage your announcement library** Unlike the native banner, Modern Announcement Banner lets you save multiple announcements. This is useful for: * **Maintenance windows** — prepare the announcement in advance, enable it when the window starts * **Recurring events** — save announcements for standing meetings or scheduled downtimes and reuse them * **Emergency responses** — keep pre-written security alert templates ready for quick activation Only one banner can be active at a time, but switching between saved announcements takes one click. ### Key features comparison[​](#key-features-comparison "Direct link to Key features comparison") | Feature | Native Jira Banner | Modern Announcement Banner | | ----------------------------- | -------------------- | ------------------------------------------ | | **Rich text formatting** | No (plain text only) | No (plain text with emojis) | | **Multiple saved banners** | No (one at a time) | Yes (library of saved announcements) | | **Dismissible by users** | No | Yes | | **Public/private visibility** | Yes | Yes | | **One-click switching** | No | Yes (switch between saved banners) | | **Banner history** | No | Saved in your announcement library | | **Setup time** | 1 minute | 2 minutes (first time), 1 click after that | | **Cost** | Free (built-in) | Paid with free trial | ## Best Practices for Announcement Banners[​](#best-practices-for-announcement-banners "Direct link to Best Practices for Announcement Banners") ### Keep messages short and actionable[​](#keep-messages-short-and-actionable "Direct link to Keep messages short and actionable") A banner that contains a wall of text gets ignored. Write banners that answer three questions in under 200 characters: * **What** is happening? * **When** is it happening? * **What** should users do? Bad: "Please be advised that the engineering team will be performing scheduled maintenance on the Jira and Confluence infrastructure this weekend. During this time, you may experience intermittent connectivity issues. We apologize for any inconvenience." Good: "Scheduled maintenance: Sat May 24, 2-6 AM UTC. Jira and Confluence may be unavailable. Save your work before 2 AM." ### Disable banners promptly[​](#disable-banners-promptly "Direct link to Disable banners promptly") An announcement banner that stays live for weeks after the event has passed trains users to ignore banners entirely. Set a calendar reminder to disable the banner when the announcement is no longer relevant. With [Modern Announcement Banner](/docs/Modern-Announcement-Banner-for-Jira/user-docs.md), you can prepare the "disable" action in advance by saving a blank announcement that you enable when the event passes. ### Use dismissible banners for non-critical notices[​](#use-dismissible-banners-for-non-critical-notices "Direct link to Use dismissible banners for non-critical notices") If an announcement is important but not critical (for example, "New feature available in the reporting dashboard"), make it dismissible. Users who have already seen it can dismiss it, reducing banner fatigue. Reserve non-dismissible banners for critical events like security incidents or mandatory policy changes. ### Reserve banners for truly important information[​](#reserve-banners-for-truly-important-information "Direct link to Reserve banners for truly important information") Announcement banners are a high-visibility, limited-use channel. If you use them for every minor update, users start treating them as visual noise. Use banners for: * Maintenance windows and outages * Security alerts and policy changes * Mandatory actions (password resets, compliance training) * Company-wide events Use other channels (Slack, email, Confluence pages) for everything else. ### Coordinate across platforms[​](#coordinate-across-platforms "Direct link to Coordinate across platforms") If you are announcing a maintenance window that affects both Jira and Confluence, post banners in both platforms. A user who only sees the Jira banner might assume Confluence is unaffected. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Modern Announcement Banner for Jira](/apps/modern-announcement-banner-for-jira.md) -- user guide with setup instructions, visibility settings, and dismissible banners * [Jira Announcement Banner FAQ](/blog/faq-jira-announcement-banner-customization.md) -- detailed FAQ about customization, scheduling, and best practices Try Modern Announcement Banner for Jira Rich-text announcement banners with scheduling and targeting — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/194301976/modern-announcement-banner-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-announcement-banner-for-jira) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [jira](/blog/tags/jira.md) * [announcement-banner](/blog/tags/announcement-banner.md) * [how-to](/blog/tags/how-to.md) * [customization](/blog/tags/customization.md) --- # How to Use ChatGPT in Confluence: AI-Powered Writing for Better Docs July 30, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer Confluence offers native AI features through Atlassian Intelligence for writing, summarizing, and translating content. Third-party apps integrate ChatGPT directly into the editor for inline AI assistance. What you'll learn 1. How to enable and use Atlassian Intelligence in Confluence 2. How to integrate ChatGPT via Marketplace apps 3. Prompt engineering techniques for better AI-generated content 4. How to use AI for summarization, translation, and content improvement Writing good documentation takes time. Between drafting, editing, formatting, and organizing, creating a single Confluence page can take hours. For teams with dozens of pages to maintain, this time adds up quickly. AI tools like ChatGPT can accelerate every stage of the documentation workflow — from initial drafts to final polish. This guide covers how to use AI in Confluence, from native features to third-party integrations. ## Why AI Matters for Confluence Documentation[​](#why-ai-matters-for-confluence-documentation "Direct link to Why AI Matters for Confluence Documentation") Documentation is essential but often neglected. Teams know they should write more, but the effort feels disproportionate to the perceived value. AI changes this equation: **Speed.** What takes an hour to write takes 10 minutes with AI assistance. The AI handles the first draft; you handle the refinement. **Consistency.** AI can maintain a consistent tone, format, and structure across pages. No more "this page sounds different from that page." **Accessibility.** AI translation makes content available to global teams without hiring translators. **Completeness.** AI can identify gaps in your documentation and suggest sections you missed. ## How to Use ChatGPT in Confluence: Step-by-Step[​](#how-to-use-chatgpt-in-confluence-step-by-step "Direct link to How to Use ChatGPT in Confluence: Step-by-Step") ### 1. Enable Atlassian Intelligence in Confluence[​](#1-enable-atlassian-intelligence-in-confluence "Direct link to 1. Enable Atlassian Intelligence in Confluence") Atlassian Intelligence is the native AI layer in Confluence. Here is how to enable it: 1. Go to **Site Administration > Products > Atlassian Intelligence** 2. Toggle on the features you want: * **Writing assistance** — draft, rewrite, expand, compress * **Summarization** — condense long content * **Translation** — convert pages to other languages * **Action items** — extract tasks from meeting notes 3. Assign permissions: * **All users** — everyone can use AI * **Specific groups** — only certain teams * **Admin only** — for controlled rollout **Pro tip:** Start with admin-only access, test thoroughly, then expand to all users. ### 2. Use AI to Draft and Edit Content[​](#2-use-ai-to-draft-and-edit-content "Direct link to 2. Use AI to Draft and Edit Content") Once enabled, AI appears as an option in the Confluence editor: **Drafting new content:** 1. Open a new Confluence page 2. Type your topic or paste an outline 3. Select the text and click the **AI icon** (sparkle icon) 4. Choose **Expand** or **Rewrite** to generate content 5. Review and edit the output **Editing existing content:** 1. Highlight the text you want to improve 2. Click the AI icon 3. Choose an action: * **Improve writing** — fix grammar, clarity, flow * **Make longer** — add detail and depth * **Make shorter** — condense for brevity * **Change tone** — formal, casual, technical **Example prompt for drafting:** ``` Write a step-by-step guide for setting up a Confluence space for a new project. Include sections on: space creation, page templates, permissions, and content organization. Target audience: project managers with basic Confluence experience. ``` ### 3. Summarize Long Pages and Threads[​](#3-summarize-long-pages-and-threads "Direct link to 3. Summarize Long Pages and Threads") Confluence pages can grow long, especially meeting notes, decision logs, and project updates. AI summarization condenses this content: **How to summarize:** 1. Open the page you want to summarize 2. Click the **AI icon** in the top toolbar 3. Select **Summarize this page** 4. AI generates a concise summary at the top **Best uses for summarization:** * Meeting notes — extract action items and decisions * Long project pages — get the current status * Comment threads — understand the consensus * Decision logs — see what was decided and why **Example: summarizing meeting notes** Before: > 45 minutes of discussion about deployment process, including vendor comparisons, pricing discussions, timeline disagreements, and final decision to proceed with Option B. After: > Decided: Proceed with Option B for deployment. Budget: $50k. Timeline: Q3 2026. Next steps: Vendor contract review by Friday. ### 4. Translate Content for Global Teams[​](#4-translate-content-for-global-teams "Direct link to 4. Translate Content for Global Teams") AI translation in Confluence converts pages while preserving formatting: **How to translate:** 1. Open the page to translate 2. Click the **AI icon** > **Translate** 3. Select the target language 4. AI generates the translated version 5. Review and save as a new page or overwrite **Languages supported:** * English, Spanish, French, German, Italian, Portuguese * Japanese, Korean, Chinese (Simplified) * And more via Atlassian Intelligence **Best practices:** * Always review translations for accuracy * Keep the original page as the source of truth * Use language-specific Confluence spaces for organized access * Test with a native speaker before publishing ### 5. Build a Prompt Library for Common Tasks[​](#5-build-a-prompt-library-for-common-tasks "Direct link to 5. Build a Prompt Library for Common Tasks") Create a shared Confluence page with tested prompts your team can reuse: **Prompt library structure:** ``` # AI Prompt Library ## Writing Prompts - [Technical guide template] - [Meeting notes template] - [Project status update template] ## Editing Prompts - [Improve clarity] - [Add detail] - [Simplify language] ## Analysis Prompts - [Summarize page] - [Extract action items] - [Identify gaps] ``` **Example prompts to include:** ``` Draft a Confluence page for [topic] with: - Introduction explaining why this matters - 3-5 main sections with headers - Step-by-step instructions where applicable - FAQ section with 5 common questions - Links to related Confluence pages Audience: [role] Tone: [formal/casual] Length: [short/medium/detailed] ``` ## FAQ[​](#faq "Direct link to FAQ") ### Does Confluence have built-in AI features?[​](#does-confluence-have-built-in-ai-features "Direct link to Does Confluence have built-in AI features?") Yes. Atlassian Intelligence provides native AI capabilities in Confluence including writing assistance, summarization, translation, and action item extraction. It is available on Premium and Enterprise plans. ### Can I use ChatGPT directly in Confluence?[​](#can-i-use-chatgpt-directly-in-confluence "Direct link to Can I use ChatGPT directly in Confluence?") Not natively, but Marketplace apps like AI Assistant for Confluence and ChatGPT for Confluence integrate OpenAI's API directly into the Confluence editor for inline AI assistance. ### Is AI-generated content accurate in Confluence?[​](#is-ai-generated-content-accurate-in-confluence "Direct link to Is AI-generated content accurate in Confluence?") AI-generated content should always be reviewed by a human. AI can produce factual errors, outdated information, or contextually inappropriate content. Use AI as a starting point, not a final product. ### How do I write good prompts for Confluence content?[​](#how-do-i-write-good-prompts-for-confluence-content "Direct link to How do I write good prompts for Confluence content?") Be specific about the audience, format, and goal. Instead of 'write about deployment,' use 'write a step-by-step guide for junior developers on deploying to staging, including rollback procedures.' ### Can AI help with Confluence page organization?[​](#can-ai-help-with-confluence-page-organization "Direct link to Can AI help with Confluence page organization?") Yes. AI can suggest page hierarchies, generate table of contents, identify related pages, and recommend tags based on content analysis. Use it to audit and improve your space structure. ## Related guides[​](#related-guides "Direct link to Related guides") * [How to Write Better Confluence Pages with AI Assistance](/blog/advanced-code-blocks-confluence.md) * [Confluence Page Templates: How to Create and Use Them](/blog/advanced-code-blocks-confluence.md) * [How to Organize Your Confluence Space for Easy Navigation](/blog/faq-confluence-dark-mode-apps.md) * [AI Meeting Notes in Confluence: Capture and Share Automatically](/blog/ai-meeting-notes-confluence.md) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [chatgpt](/blog/tags/chatgpt.md) * [ai](/blog/tags/ai.md) * [how-to](/blog/tags/how-to.md) * [documentation](/blog/tags/documentation.md) --- # How to Add Numbered Headings in Confluence (Auto-Number H1-H6) May 2, 2026 · 10 min read [NGPilot](https://ngpilot.com) If you have ever written a long Confluence page — a technical specification, an SOP, a project charter, or an onboarding guide — you know the problem. You add headings, rearrange sections, insert a new subsection, and suddenly every manual number is wrong. "Section 3.2" becomes "Section 4.2" because you added a new section above it, and you spend the next twenty minutes renumbering everything by hand. Numbered headings solve this. When your heading numbers are generated automatically, you can add, remove, and reorder sections freely without ever touching a number again. The numbering updates itself. This tutorial walks through how to set up automatic numbered headings in Confluence using **Modern Numbered Headings for Confluence**, an NGPILOT app that installs in seconds and works immediately — no configuration wizards, no macro nesting, no custom CSS. ## Why numbered headings matter for documentation[​](#why-numbered-headings-matter-for-documentation "Direct link to Why numbered headings matter for documentation") Numbered headings are not just cosmetic. They serve a practical purpose in any document that people reference, discuss, or review: * **Unambiguous references.** When someone says "see section 2.3.1," there is no confusion about which section they mean. Compare that to "see the third subsection under Risk Assessment" — which risk assessment? Which level? * **Easier navigation.** A table of contents with numbered headings lets readers jump directly to the section they need. Numbers also communicate the hierarchy at a glance: 2.3 is clearly a child of section 2. * **Professional appearance.** Technical documentation, legal documents, compliance reports, and formal proposals all use numbered headings as a standard convention. If your Confluence pages serve any of these purposes, numbered headings make them look polished. * **Cross-referencing.** In regulated environments (ISO, SOC 2, GDPR documentation), section numbers are required for traceability. Automated numbering ensures your cross-references stay accurate as the document evolves. Without an app, Confluence does not number headings natively. You can add numbers manually in the heading text, but every structural edit breaks them. That is where Modern Numbered Headings comes in. ## Step-by-step: Set up numbered headings in Confluence[​](#step-by-step-set-up-numbered-headings-in-confluence "Direct link to Step-by-step: Set up numbered headings in Confluence") ### Step 1: Install Modern Numbered Headings for Confluence[​](#step-1-install-modern-numbered-headings-for-confluence "Direct link to Step 1: Install Modern Numbered Headings for Confluence") 1. Go to **Confluence Settings** (the gear icon in the top-right corner). 2. Navigate to **Find new apps** (under the "Apps" section). 3. Search for **"Modern Numbered Headings"**. 4. Click **Install** and follow the prompts. The app installs globally and is available on every Confluence page immediately. No per-space configuration is needed. After installation, open any page that has headings. Look for the app icon (a clipboard symbol) in the page byline — the area just below the page title. If you see it, the installation was successful. ### Step 2: Open a Confluence page with headings[​](#step-2-open-a-confluence-page-with-headings "Direct link to Step 2: Open a Confluence page with headings") Open or create a Confluence page that uses multiple heading levels. A good test page should have at least an H1, several H2 sections, and a few H3 subsections. Example heading structure: ``` Project Deployment Guide (H1) Prerequisites (H2) System Requirements (H3) Access Credentials (H3) Installation (H2) Step 1: Download (H3) Step 2: Configure (H3) Troubleshooting (H2) ``` You do not need to add any numbers manually. The app will generate them. ### Step 3: Configure the numbering scheme[​](#step-3-configure-the-numbering-scheme "Direct link to Step 3: Configure the numbering scheme") Click the app icon in the page byline. A configuration modal opens with all available options. **Numbering style selection** lets you choose from five professional formats. The most common choice is **Decimal** (1, 1.1, 1.1.1), but you can pick any style that fits your document type. A live preview shows exactly how your headings will look with each scheme. **Heading level selection** lets you control which levels are numbered. For most documents, H1 through H3 is sufficient. For deeply nested technical specifications, you can extend numbering all the way to H6. **Display options** include a toggle for hierarchical indentation in the generated table of contents. Enable it for complex documents; disable it for simpler pages where you want a flat list. ### Step 4: Apply numbering to headings[​](#step-4-apply-numbering-to-headings "Direct link to Step 4: Apply numbering to headings") Once you have selected your numbering style and heading levels, click **Insert TOC** in the modal. The app does two things: 1. It inserts a formatted, numbered table of contents at the top of your page. 2. It adds the corresponding numbers to each heading in the document body. Every heading on the page gets numbered automatically based on the scheme you chose. If you later add a new H2 between sections 2 and 3, the app renumbers everything — section 3 becomes section 4, section 3.1 becomes 4.1, and so on. No manual intervention required. To update the numbering after editing your page, click the app icon, select **Remove TOC**, then click **Insert TOC** again with your desired settings. The entire process takes about five seconds. ### Step 5: Add a table of contents[​](#step-5-add-a-table-of-contents "Direct link to Step 5: Add a table of contents") The app generates its own numbered table of contents directly on the page. If you also want to use Confluence's built-in **Table of Contents** macro, the two work together seamlessly. To add Confluence's TOC macro: 1. Place your cursor at the top of the page, above your content. 2. Type `/toc` and select the **Table of Contents** macro. 3. Configure the macro to display the heading levels you want. 4. Save the page. The TOC macro will display your headings with their numbering intact, giving readers a navigable overview of the entire document. ## Numbering scheme reference[​](#numbering-scheme-reference "Direct link to Numbering scheme reference") Modern Numbered Headings supports five numbering styles. Each is suited to different document types. ### 1. Decimal (1, 1.1, 1.1.1)[​](#1-decimal-1-11-111 "Direct link to 1. Decimal (1, 1.1, 1.1.1)") The most widely used format. Clear, unambiguous, and familiar to anyone who has read technical documentation. ``` 1. Introduction 1.1. Overview 1.2. Scope 2. Architecture 2.1. Frontend 2.2. Backend ``` **Best for:** Technical documentation, user guides, SOPs, general business documents. ### 2. Roman Numerals (I, I.I, I.II)[​](#2-roman-numerals-i-ii-iii "Direct link to 2. Roman Numerals (I, I.I, I.II)") Formal and authoritative. Common in academic papers, executive summaries, and compliance documentation. ``` I. Executive Summary I.I. Key Findings I.II. Recommendations II. Detailed Analysis II.I. Methodology II.II. Results ``` **Best for:** Formal reports, academic papers, board presentations, compliance documents. ### 3. Alphabetic (A, A.A, A.B)[​](#3-alphabetic-a-aa-ab "Direct link to 3. Alphabetic (A, A.A, A.B)") Uses letters instead of numbers for the top level. Useful for procedures, checklists, and documents where numeric sections might be confused with ordered lists. ``` A. Planning Phase A.A. Requirements Gathering A.B. Resource Allocation B. Implementation Phase B.A. Development B.B. Testing ``` **Best for:** Procedures, checklists, project phases, structured lists. ### 4. Outline (1), 1.1), 1.1.1))[​](#4-outline-1-11-111 "Direct link to 4. Outline (1), 1.1), 1.1.1))") Uses closing parentheses instead of periods. A legal-standard format that is common in contracts, policy documents, and regulatory filings. ``` 1) Project Overview 1.1) Scope Definition 1.1.1) Deliverables 1.2) Timeline 2) Risk Assessment 2.1) Technical Risks 2.2) Business Risks ``` **Best for:** Legal documents, contracts, policies, regulatory filings, business reports. ### 5. Mixed (1, A, i, a)[​](#5-mixed-1-a-i-a "Direct link to 5. Mixed (1, A, i, a)") Each nesting level uses a different format: numbers at the top, then uppercase letters, then lowercase roman numerals, then lowercase letters. This is the traditional outline format taught in schools. ``` 1. System Architecture A. Frontend Components i. User Interface a. Navigation b. Content Display ii. Data Management B. Backend Services 2. Security Framework ``` **Best for:** Complex hierarchies, detailed specifications, academic outlines, technical standards. ## Tips for working with long documents[​](#tips-for-working-with-long-documents "Direct link to Tips for working with long documents") Long Confluence pages (50+ headings, thousands of words) need a bit more planning to keep organized. Here are practical tips: ### Break very long documents into multiple pages[​](#break-very-long-documents-into-multiple-pages "Direct link to Break very long documents into multiple pages") If your document exceeds roughly 5,000 words, consider splitting it into child pages under a parent page. Use Confluence's page hierarchy to maintain structure. Each child page gets its own numbered headings, and readers navigate between sections using the page tree. For example, instead of one giant "Deployment Guide" page: * **Deployment Guide** (parent page, overview) * **Prerequisites** (child page) * **Installation** (child page) * **Configuration** (child page) * **Troubleshooting** (child page) ### Always include a table of contents[​](#always-include-a-table-of-contents "Direct link to Always include a table of contents") For any page with more than four headings, a table of contents is essential. Place it at the top of the page so readers can scan the structure before scrolling. The app generates the TOC with numbered headings, giving readers an instant overview of the document's scope and depth. ### Maintain consistent heading hierarchy[​](#maintain-consistent-heading-hierarchy "Direct link to Maintain consistent heading hierarchy") Do not skip heading levels. If your page has an H1 followed immediately by an H3 (skipping H2), the numbering will look broken to readers and the hierarchy becomes confusing. Always step through levels sequentially: H1 > H2 > H3 > H4. Avoid using headings purely for visual styling. If you need larger text, use Confluence's paragraph formatting instead. Headings define document structure, and the numbering scheme depends on a clean hierarchy. ### Filter heading levels in the TOC[​](#filter-heading-levels-in-the-toc "Direct link to Filter heading levels in the TOC") Not every heading needs to appear in the table of contents. For long documents, including only H1 through H3 keeps the TOC compact and scannable. You can configure this in the app's modal by checking or unchecking heading levels. The deeper headings (H4, H5, H6) still get numbered in the document body — they just do not clutter the TOC. ### Update the TOC after structural edits[​](#update-the-toc-after-structural-edits "Direct link to Update the TOC after structural edits") After adding, removing, or reordering sections, click the app icon and re-insert the TOC. This takes just a few seconds and ensures the table of contents reflects the current page structure. The old TOC is removed cleanly with no leftover artifacts. ## Best practices for numbered headings in Confluence[​](#best-practices-for-numbered-headings-in-confluence "Direct link to Best practices for numbered headings in Confluence") Beyond the mechanics of the app, these practices will make your numbered documentation consistently professional and easy to maintain. ### 1. Choose one numbering scheme per document type[​](#1-choose-one-numbering-scheme-per-document-type "Direct link to 1. Choose one numbering scheme per document type") Pick a standard for each category of documentation your team produces. For example: * **Technical specs:** Decimal (1, 1.1, 1.1.1) * **Compliance documents:** Outline (1), 1.1), 1.1.1)) * **Project plans:** Alphabetic (A, A.A, A.B) Write the standard down in your team's style guide. Consistency across documents makes it easier for readers to navigate your Confluence space. ### 2. Start every numbered page with a clear title[​](#2-start-every-numbered-page-with-a-clear-title "Direct link to 2. Start every numbered page with a clear title") Use an H1 as the page title. This becomes the root of your numbering hierarchy. A page without a clear top-level heading produces confusing numbering — the first H2 gets numbered 0.1 or is orphaned entirely. ### 3. Keep heading text descriptive and concise[​](#3-keep-heading-text-descriptive-and-concise "Direct link to 3. Keep heading text descriptive and concise") Numbered headings like "3.2 Configuration" work well. Avoid vague headings like "3.2 Notes" or "3.2 Miscellaneous." Readers scanning the table of contents should understand the content of each section from the heading alone. Do not include the numbers manually in the heading text. The app adds them automatically. Writing "1.1 Overview" as the heading text would result in "1.1 1.1 Overview" — duplicated numbering. ### 4. Limit nesting to three or four levels[​](#4-limit-nesting-to-three-or-four-levels "Direct link to 4. Limit nesting to three or four levels") Deep nesting (H5, H6) makes documents harder to read and the table of contents unwieldy. If you find yourself routinely going beyond H4, consider whether the sub-content should be split into a separate child page. A three-level structure (H1 > H2 > H3) covers the vast majority of business and technical documents. Reserve four or more levels for genuinely complex specifications. ### 5. Review the TOC before publishing[​](#5-review-the-toc-before-publishing "Direct link to 5. Review the TOC before publishing") Before publishing or sharing a long Confluence page, glance at the generated table of contents. Look for: * Missing sections (a heading was accidentally deleted) * Duplicate headings (two sections with the same title) * Skipped levels (H1 followed by H3) * Uneven structure (one section with five subsections while others have none) The TOC is a structural x-ray of your document. Use it as a final quality check. ## Related resources[​](#related-resources "Direct link to Related resources") * [Modern Numbered Headings for Confluence — User Guide](/apps/modern-numbered-headings-for-confluence.md) — full documentation covering all features, troubleshooting, and frequently asked questions. * [Numbered Headings for Confluence — Which App?](/blog/confluence-numbered-headings-comparison.md) — a comparison of available numbered headings apps on the Atlassian Marketplace, including features, pricing, and ease of use. ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [numbered-headings](/blog/tags/numbered-headings.md) * [documentation](/blog/tags/documentation.md) * [how-to](/blog/tags/how-to.md) * [toc](/blog/tags/toc.md) --- # How to Use QR Codes in Confluence: Complete Guide May 2, 2026 · 11 min read [NGPilot](https://ngpilot.com) QR codes bridge the gap between physical and digital information. A printed QR code on a poster, equipment label, or business card lets someone open a web page, join a WiFi network, or save a contact without typing a single character. For teams using Confluence as their knowledge base, adding QR codes to pages turns static documents into interactive touchpoints. The challenge is that Confluence does not include built-in QR code generation. You either use a third-party QR generator website, download the image, and upload it manually — or you install a marketplace app that generates QR codes directly inside Confluence pages. The second option is faster, keeps your QR codes up to date when page URLs change, and avoids juggling image files. **QRCode for Confluence** by NGPILOT is a lightweight app that embeds QR codes directly into Confluence pages using a simple slash command. It supports URLs, plain text, email addresses, phone numbers, and any other string. You can customize the size, and the QR code renders inline on your page. This guide covers everything you need to know: how to install and use the app, what content types you can encode, creative ways teams use QR codes in Confluence, and best practices for making sure your QR codes actually get scanned. ## Step-by-step tutorial[​](#step-by-step-tutorial "Direct link to Step-by-step tutorial") ### Step 1: Install QRCode for Confluence[​](#step-1-install-qrcode-for-confluence "Direct link to Step 1: Install QRCode for Confluence") Open the Atlassian Marketplace and search for **QRCode for Confluence** by NGPILOT. Click **Get App** to install it on your Confluence Cloud instance. The installation takes a few seconds and requires Confluence admin permissions. The app is available on the Atlassian Marketplace. Check the listing for current pricing details. ### Step 2: Insert the QR Code macro[​](#step-2-insert-the-qr-code-macro "Direct link to Step 2: Insert the QR Code macro") Open or create the Confluence page where you want the QR code. Click **Edit** to enter the page editor, then type `/qrcode` in the slash command bar. Select **QRCode for Confluence** from the dropdown. The macro configuration panel appears where you can set the content and size. ### Step 3: Enter the QR code content[​](#step-3-enter-the-qr-code-content "Direct link to Step 3: Enter the QR code content") In the macro configuration panel, type or paste the content you want to encode. The macro accepts several content types: * **URLs** — Any web address, including Confluence page links, external websites, or file download links * **Plain text** — Short messages, instructions, or identifiers * **Email addresses** — Enter the email address directly * **Phone numbers** — Enter the phone number directly * **Any other string** — Any text content you want to encode For example, to encode a Confluence page URL, paste the full URL into the content field. ### Step 4: Customize the QR code[​](#step-4-customize-the-qr-code "Direct link to Step 4: Customize the QR code") The macro gives you a size option: * **Size** — Choose from five sizes: X-Small (compact), Small, Medium, Large (default), and X-Large. Use smaller sizes for inline badges next to text. Use larger sizes for posters and printed signs that need to be scanned from a distance. Preview the QR code in the configuration panel before saving. Check that the size fits the surrounding content. ### Step 5: Save and print[​](#step-5-save-and-print "Direct link to Step 5: Save and print") Click **OK** to insert the macro, then publish or update the Confluence page. The QR code renders inline on the page. To print the QR code, export the Confluence page to PDF or print it directly from the browser. You can also screenshot the QR code for use in external design tools like Canva or Adobe Illustrator. ## QR code content types reference[​](#qr-code-content-types-reference "Direct link to QR code content types reference") The table below summarizes the content types you can encode and suggested formats for each. | Content type | Suggested format | Example | What happens when scanned | | ------------------------ | ------------------ | -------------------------------------------------------------- | ---------------------------------------------------------- | | **Web URL** | `https://...` | `https://confluence.example.com/display/DOC/Setup+Guide` | Opens the URL in the device browser | | **Confluence page link** | Full page URL | `https://your-site.atlassian.net/wiki/spaces/TEAM/pages/12345` | Opens the Confluence page in the Confluence app or browser | | **Email address** | Email address text | `support@company.com` | Displays the email address for the user to act on | | **Phone number** | Phone number text | `+18005551234` | Displays the phone number for the user to act on | | **Plain text** | Any text | `Room 4B - Capacity 12 - Projector: Yes - Whiteboard: Yes` | Displays the text on screen | When entering content, use the full `https://` prefix for URLs for best scanning results. Shorter content produces cleaner, easier-to-scan QR codes. ## 5 creative uses for QR codes in Confluence[​](#5-creative-uses-for-qr-codes-in-confluence "Direct link to 5 creative uses for QR codes in Confluence") QR codes are not just for linking to web pages. Here are five ways teams use QR codes embedded in Confluence pages to connect physical spaces with digital information. ### 1. Equipment and asset labels[​](#1-equipment-and-asset-labels "Direct link to 1. Equipment and asset labels") Print Confluence pages with QR codes and attach them to physical assets. A server rack gets a label with a QR code linking to its configuration page. An office printer gets a label linking to the troubleshooting guide. A warehouse shelf gets a label linking to the inventory procedure. When someone needs information about that piece of equipment, they scan the QR code and the relevant Confluence page opens immediately. No searching, no guessing keywords, no asking colleagues which page has the right info. For this use case, use the X-Large size and print the QR code on a durable label or laminated sticker. Make sure the Confluence page is accessible to everyone who might scan it, including people outside your organization if the asset is in a shared space. ### 2. Event handouts and conference materials[​](#2-event-handouts-and-conference-materials "Direct link to 2. Event handouts and conference materials") Print QR codes on event flyers, conference name badges, or table tents that link to session notes, feedback forms, or detailed documentation stored in Confluence. Attendees scan the code during or after the event to access the resources. This approach eliminates the need to print long URLs on small pieces of paper, which nobody ever types correctly. It also lets you update the Confluence page after the event with additional resources, and everyone who scanned the QR code automatically sees the latest version. Use the Medium or Large size for event materials. Pair the QR code with a short text label underneath explaining what the code links to, such as "Scan for session notes" or "Scan to leave feedback." ### 3. Office signage and meeting room displays[​](#3-office-signage-and-meeting-room-displays "Direct link to 3. Office signage and meeting room displays") Post QR codes on meeting room doors, in common areas, or at reception desks. A meeting room door sign includes a QR code linking to the room booking page. A kitchen bulletin board includes a QR code linking to the office snack request form. A reception desk sign includes a QR code linking to the visitor check-in page. This use case works well because Confluence pages can be updated in real time. If the room booking policy changes, update the Confluence page and the printed QR code still works — it always points to the current version. For signs that will be scanned from a few feet away, use the Large or X-Large size. ### 4. Onboarding materials for new hires[​](#4-onboarding-materials-for-new-hires "Direct link to 4. Onboarding materials for new hires") Create an onboarding page in Confluence with QR codes linking to key resources: IT setup guides, team wikis, HR policies, benefits enrollment, and the company directory. Print this page and include it in the new hire welcome packet or post it at their desk. New hires scan each QR code with their phone and bookmark the pages they need. This is faster than sending a long email with 15 links, and it works even before they have set up their laptop and email. The QR codes on the printed page always link to the latest versions of each resource. Use the Small or Medium size for onboarding sheets that include multiple QR codes side by side. Label each one clearly so the new hire knows what each code links to. ### 5. Sharing links for guests and visitors[​](#5-sharing-links-for-guests-and-visitors "Direct link to 5. Sharing links for guests and visitors") Encode a guest WiFi password, onboarding link, or visitor check-in page URL as a QR code on a Confluence page and display the page at reception or in meeting rooms. When visitors arrive, they scan the QR code and their phone opens the linked page or displays the information. This removes the awkward interaction of asking for links or typing long URLs character by character. Visitors get the information they need in seconds. For this use case, use the URL of the relevant Confluence page or resource. Use a Large or X-Large size so visitors can scan from across the room. Place the QR code prominently at eye level. ## QR code best practices[​](#qr-code-best-practices "Direct link to QR code best practices") Generating a QR code is easy. Making sure people actually scan it and get to the right place takes a little more thought. Here are six best practices to follow. ### 1. Always include a text label[​](#1-always-include-a-text-label "Direct link to 1. Always include a text label") Never place a bare QR code on a page without explaining what it does. People are rightfully cautious about scanning unknown QR codes. A label like "Scan to open the IT setup guide" or "Scan to connect to guest WiFi" tells people what to expect and builds trust that the code is legitimate. The label should be concise — one line is ideal. Place it directly below or beside the QR code so it is visually associated with the code. ### 2. Ensure sufficient contrast[​](#2-ensure-sufficient-contrast "Direct link to 2. Ensure sufficient contrast") QR codes rely on contrast between the foreground modules and the background. The default black on white works best for reliable scanning. If you print the page, ensure the QR code maintains strong contrast on the printed medium. Light gray on white, or dark blue on dark gray, will cause scanning failures, especially in low light or on low-quality printers. Test your QR code by scanning it with your phone before printing in bulk. ### 3. Size the QR code for the scanning distance[​](#3-size-the-qr-code-for-the-scanning-distance "Direct link to 3. Size the QR code for the scanning distance") The size of the QR code should match the distance from which people will scan it. A QR code on a business card is scanned from a few inches away, so X-Small or Small works. A QR code on a wall poster needs to be scanned from several feet away, so Large or X-Large is necessary. As a general guideline, the minimum QR code width in inches should be roughly 0.1 times the expected scanning distance in inches. For example, if someone will scan from 2 feet (24 inches) away, the QR code should be at least 2.4 inches wide. Export the Confluence page to PDF and print at actual size to verify. ### 4. Test before you print[​](#4-test-before-you-print "Direct link to 4. Test before you print") Always test the QR code before printing it on physical materials. Open the Confluence page, scan the QR code with your phone, and verify that it resolves to the correct content. Check that the target page loads properly on mobile devices. If you are sharing WiFi credentials, test that the network connection actually works. Testing takes 30 seconds and prevents the frustration of printing 200 flyers with a QR code that points to the wrong page or a page that returns a 404 error. ### 5. Use short, stable URLs[​](#5-use-short-stable-urls "Direct link to 5. Use short, stable URLs") Long URLs create dense QR codes with many modules, which are harder to scan and more sensitive to printing imperfections. If possible, use short URLs. Confluence short links (the type you get from the Share button) are shorter than the full page URL displayed in the address bar. Also consider URL stability. If you reorganize your Confluence space and the page URL changes, the QR code will break. Use page IDs in the URL (which Confluence preserves during moves) rather than page title slugs (which change when the title changes). Or place the QR code on a parent page that is unlikely to be moved. ### 6. Keep the QR code area clean[​](#6-keep-the-qr-code-area-clean "Direct link to 6. Keep the QR code area clean") When designing printed materials, leave white space around the QR code. Do not overlay text, logos, or other graphics on top of the QR code. Do not crop the quiet zone (the white border around the QR code). A cluttered QR code may look fine on screen but fail to scan when printed. The quiet zone should be at least 4 modules wide on all sides. In practice, this means leaving a margin equal to roughly 10% of the QR code width as empty white space around the code. ## Related resources[​](#related-resources "Direct link to Related resources") * [QR Code for Confluence -- Which QR App?](/blog/confluence-qr-code-comparison.md) -- detailed comparison of all QR code apps on the Atlassian Marketplace, including features, pricing, and honest pros and cons * [Browse all NGPILOT apps](/docs/intro.md) -- explore the full catalog of Confluence and Jira apps by NGPILOT ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [qr-code](/blog/tags/qr-code.md) * [how-to](/blog/tags/how-to.md) * [printables](/blog/tags/printables.md) --- # Enhanced Markdown Setup Tutorial — Insert Macro, Modes & Publish May 6, 2026 · 4 min read [NGPilot](https://ngpilot.com) **Confluence Markdown** support lets developers write documentation in their preferred format. This guide covers how to add **Enhanced Markdown** to Confluence for raw Markdown editing, WYSIWYG preview, tables, code blocks, and more. Who should read this * Developers who prefer writing in Markdown * Technical writers needing to import Markdown files * Teams migrating from GitHub or other Markdown-based wikis What you'll learn 1. How to install and use Enhanced Markdown in Confluence 2. Raw Markdown mode vs WYSIWYG mode 3. Supported syntax: tables, code blocks, task lists 4. Comparison with Confluence's native editor ## Does Confluence support Markdown?[​](#does-confluence-support-markdown "Direct link to Does Confluence support Markdown?") No, Confluence does not natively support Markdown editing. The Confluence editor is a rich-text (WYSIWYG) editor. However, you can add Markdown support with a Marketplace app. ## Step-by-step: Write Markdown in Confluence[​](#step-by-step-write-markdown-in-confluence "Direct link to Step-by-step: Write Markdown in Confluence") ### Step 1: Install Enhanced Markdown[​](#step-1-install-enhanced-markdown "Direct link to Step 1: Install Enhanced Markdown") Go to [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?hosting=cloud\&tab=overview) on the Atlassian Marketplace and click **Get it now**. The app installs directly into your Confluence Cloud instance. Enhanced Markdown is free for up to 10 users. ### Step 2: Open a Confluence page[​](#step-2-open-a-confluence-page "Direct link to Step 2: Open a Confluence page") Navigate to the page where you want to write Markdown and click **Edit**. ### Step 3: Insert the macro[​](#step-3-insert-the-macro "Direct link to Step 3: Insert the macro") Type `/enhanced markdown` in the Confluence editor and select the **Enhanced Markdown** macro from the dropdown. ### Step 4: Write your Markdown[​](#step-4-write-your-markdown "Direct link to Step 4: Write your Markdown") The macro opens a Markdown editor. Write using standard Markdown syntax: ```` # Heading 1 ## Heading 2 This is a paragraph with **bold text**, *italic text*, and `inline code`. ### Lists - Unordered item 1 - Unordered item 2 - Nested item 1. Ordered item 1 2. Ordered item 2 ### Code blocks ```python def hello(): print("Hello, Confluence!") ```` ### Tables[​](#tables "Direct link to Tables") | Feature | Supported | | ----------- | --------- | | Headings | Yes | | Tables | Yes | | Code blocks | Yes | ### Task lists[​](#task-lists "Direct link to Task lists") * Install Enhanced Markdown * Write documentation * Share with team ``` Enhanced Markdown supports **CommonMark** and **GitHub Flavored Markdown (GFM)**, including: - Headings (H1–H6) - Bold, italic, strikethrough - Ordered and unordered lists - Fenced code blocks with syntax highlighting - Tables - Task lists (checkboxes) - Links and images - Blockquotes — see the [Confluence block quote guide](/blog/block-quote-confluence) for nesting and attribution - Horizontal rules ### Step 5: Switch to WYSIWYG mode Click the mode toggle to switch to **WYSIWYG mode**. In this mode you see the rendered result as you type — similar to Typora or Notion. You can also edit directly in WYSIWYG mode if you prefer. ### Step 6: Save Click **Publish** or **Save**. The Markdown content renders as standard Confluence content. This means: - **Exports work** — PDF and Word exports include the rendered content - **Search works** — Confluence search indexes the content - **Permissions work** — normal page permissions apply - **Mentions and links work** — @mentions and Confluence links render normally ## What about inline Markdown in the Confluence editor? Confluence's native editor does support a few Markdown shortcuts: - Type `#` + space at the start of a line for a heading - Type `-` + space for a bullet list - Type `1.` + space for a numbered list - Type `---` for a horizontal rule But these are limited shortcuts, not full Markdown editing. For full Markdown support (tables, code blocks, task lists), you need Enhanced Markdown. ## Enhanced Markdown vs native Confluence editor | Feature | Native Editor | Enhanced Markdown | |---------|--------------|-------------------| | Editing mode | WYSIWYG only | Raw Markdown + WYSIWYG | | Markdown tables | No | Yes | | Fenced code blocks | No | Yes | | Task lists (checkboxes) | Partial | Yes | | Syntax highlighting in code | No | Yes | | PlantUML diagrams | No | Yes | | Charts | No | Yes | | Copy-paste from GitHub | Stripped | Renders correctly | ## Use cases - **Developer documentation** — write docs in Markdown, the format developers know - **API documentation** — fenced code blocks with syntax highlighting for endpoints - **Knowledge base** — import existing Markdown files into Confluence - **Meeting notes** — quick Markdown formatting without reaching for the mouse - **README pages** — paste README.md content directly into Confluence ## Related resources - [Enhanced Markdown — marketplace](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?hosting=cloud&tab=overview) | [documentation](/apps/enhanced-markdown-for-confluence) - [Confluence Markdown vs WYSIWYG FAQ](/blog/faq-confluence-markdown-vs-wysiwyg) - [Confluence Markdown editor FAQ](/blog/faq-confluence-markdown-editor) - [Confluence Markdown editor comparison](/blog/confluence-markdown-editor-comparison) - [Best Confluence apps for developers](/blog/best-confluence-apps-developers) ## More Related Guides - [Markdown to Confluence converter](/blog/markdown-to-confluence-converter) — Import existing Markdown files - [Confluence Markdown tables guide](/blog/confluence-markdown-tables) — Create tables in Markdown - [Enhanced Markdown documentation](/apps/enhanced-markdown-for-confluence) — Complete feature guide ``` Try Enhanced Markdown for Confluence Write Markdown with live split preview, Mermaid diagrams, KaTeX/LaTeX math, and 190+ code languages — all in one macro, free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=enhanced-markdown-for-confluence) ## Related guides * [How to Write Markdown in Confluence](/blog/faq-confluence-markdown-editor.md) * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [tutorial](/blog/tags/tutorial.md) * [wysiwyg](/blog/tags/wysiwyg.md) * [enhanced-markdown](/blog/tags/enhanced-markdown.md) --- # Import Markdown into Confluence: Paste, GitHub, .md Files September 24, 2026 · 3 min read [NGPilot](https://ngpilot.com) Every team has Markdown lying around that Confluence needs: the README that became the service doc, the design doc drafted as a pull-request description, the runbook that lives in the repo. And every attempt to move it hits the same wall — Confluence's default editor does not parse Markdown. Paste a .md document and you get a wall of pipes, backticks, and asterisks that looks exactly like what it is: text nobody formatted. The macro route dissolves the wall. Paste the document into a Markdown macro that actually parses it, watch it render in the preview pane, publish. This page is the workflow, end to end. **Quick answer:** To import Markdown into Confluence, install [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence), insert its Markdown macro on the page, and paste your .md content into the source pane. GFM tables, code fences, Mermaid diagrams, and KaTeX math all render live in the split-pane preview — then publish. The source stays editable, so updates are text edits, not re-imports. Free for up to 10 users. ## The Three Sources This Covers[​](#the-three-sources-this-covers "Direct link to The Three Sources This Covers") **1. A README from GitHub.** Copy the rendered README's raw content (or `git cat-file` it, or open the raw view), paste into the macro. Tables, code fences, and links arrive intact — the document keeps its structure on the way in. **2. An .md file from anywhere.** Notion export, Obsidian note, a docs folder in the repo: open the file, select all, paste. Tools that export non-standard syntax need a quick cleanup pass first — after that it is one paste. **3. Drafts from other contexts.** The pull-request description that grew into a design doc, the incident timeline written in a text editor, the LLM-assisted draft. If it is Markdown, the paste is the same. ## What Survives the Paste[​](#what-survives-the-paste "Direct link to What Survives the Paste") | Content in your .md | What renders in Confluence | | ------------------------------------- | ------------------------------------------------ | | `# Headings`, lists, emphasis | Native Confluence structure | | GFM pipe tables | Real tables | | ` ```lang ` code fences | Highlighted blocks, 190+ languages, copy buttons | | ` ```mermaid ` / ` ```zenuml ` fences | Rendered diagrams | | ` ```katex ` / `$...$` math | Rendered equations | | Standard links and images | Links render; images follow Markdown link syntax | The closer the source is to a standard README, the closer to zero cleanup. Well-formed documents go in with no touch-ups at all. ## The Workflow on a Real Page[​](#the-workflow-on-a-real-page "Direct link to The Workflow on a Real Page") 1. `/markdown` on the target page → the macro's split pane opens. 2. Paste the document into the left pane — the right pane renders as it lands. 3. Scroll to check the long sections: **bidirectional scroll sync** keeps source and preview locked together, so on a 400-line document you are never hunting for where you are. 4. Fix the two or three spots every migration has (a table with a stray pipe, a fence missing its language tag) — each fix is visible in the preview instantly. 5. Publish. The published page keeps the Markdown as source. When the service's retry policy changes next quarter, you edit the sentence — you do not re-run an import. Install [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence) and move the first document over. Free for up to 10 users. ## Related Guides[​](#related-guides "Direct link to Related Guides") * [How to Write Markdown in Confluence](/blog/how-to-write-markdown-in-confluence.md) — the syntax reference for what you paste * [Confluence Markdown Tables](/blog/confluence-markdown-tables.md) — the table syntax in depth * [Markdown Meeting Notes Template for Confluence](/blog/markdown-meeting-notes-confluence.md) — if the document you are importing is a notes page, start from the template instead Try Enhanced Markdown for Confluence Write Markdown with live split preview, Mermaid diagrams, KaTeX/LaTeX math, and 190+ code languages — all in one macro, free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=enhanced-markdown-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [import](/blog/tags/import.md) * [migration](/blog/tags/migration.md) * [github](/blog/tags/github.md) * [how-to](/blog/tags/how-to.md) * [developer-tools](/blog/tags/developer-tools.md) --- # Jira Attachment Management Apps Compared: Bulk Downloader vs Attachment Reviewer May 2, 2026 · 11 min read [NGPilot](https://ngpilot.com) Jira issues accumulate attachments fast -- screenshots from QA, log files from production incidents, design mockups from product, contracts from legal. Before long, a single project can hold thousands of files across hundreds of issues. Two questions come up repeatedly: "How do I download all of these at once?" and "How do I make sure the right files -- and only the right files -- are attached?" NGPILOT builds two apps that address these questions from different angles. **Simple Bulk Attachment Downloader for Jira** handles bulk exports -- downloading many attachments in one organized ZIP. **Attachment Reviewer for Jira** handles inbound control -- enforcing file type and size policies on every upload. This post compares both in detail so you can decide which one your team needs (or whether you need both). ## The Attachment Management Problem in Jira[​](#the-attachment-management-problem-in-jira "Direct link to The Attachment Management Problem in Jira") Out of the box, Jira gives you basic attachment functionality. You can upload files to issues, view them, and download them one at a time. For small teams with a handful of issues, that works. But as projects scale, the gaps become painful: * **No bulk operations.** Need to download every attachment from 50 bug reports for an audit? You are clicking through 50 issues and downloading files one by one. There is no native "export all attachments" button. * **No upload guardrails.** Someone uploads a 200 MB video to a support ticket. Someone else attaches an .exe file to a production bug. Jira accepts everything by default. There is no built-in way to say "only allow PDFs and images in this project." * **No organization on export.** When you eventually download attachments for archiving or sharing, they land in your Downloads folder as a flat list. No folder structure, no connection to the issues they came from. * **Storage costs creep up.** Jira Cloud storage limits are tied to your plan. Unchecked large attachments eat into your quota, and there is no native mechanism to enforce size policies per project. These problems split into two categories: **outbound** (getting attachments out of Jira efficiently) and **inbound** (controlling what attachments go into Jira). That is exactly why we built two separate apps rather than one combined tool. Each does one job well. *** ## Simple Bulk Attachment Downloader for Jira[​](#simple-bulk-attachment-downloader-for-jira "Direct link to Simple Bulk Attachment Downloader for Jira") Simple Bulk Attachment Downloader for Jira is the outbound solution. It lives in the Jira issue navigator and lets you download all attachments from any set of search results as a single ZIP file. ### How It Works[​](#how-it-works "Direct link to How It Works") 1. **Run any search.** Use JQL, saved filters, or quick search to find the issues you care about. 2. **Click the app button.** A "Simple Bulk Attachments Downloader" button appears in the issue navigator toolbar. 3. **Review the summary.** The app shows how many issues were found, how many attachments will be downloaded, and the estimated total size. 4. **Download.** Click the download button and the app fetches all attachments in parallel, packages them into a ZIP, and sends it to your browser. No configuration required. The app works immediately after installation. ### Key Features[​](#key-features "Direct link to Key Features") **Parallel downloading.** The app uses concurrent downloads to fetch attachments 3-8x faster than downloading them one at a time. It automatically adjusts concurrency based on the number of files. **Organized ZIP structure.** Files are not dumped into a flat archive. Each issue gets its own folder named with the issue key and summary (for example, `PROJ-123 - Login page crash/screenshots`). Original filenames are preserved, and duplicate names are handled without overwriting. **JQL integration.** Any JQL query or saved filter works. Search by project, label, date range, fix version, assignee, or any other criteria. The app downloads attachments from exactly the issues your search returns. **Permission-aware.** The app only downloads attachments from issues you can access. If your Jira permissions restrict you to certain projects or issue types, those restrictions are respected. No data leaks through the download process. **Real-time progress.** As files download, you see live progress tracking. If any individual file fails, the app creates an error entry in the ZIP so you know what went wrong rather than silently skipping it. **Browser-native delivery.** The ZIP downloads through your browser's built-in download manager. No external storage, no cloud intermediary. Files go directly from Jira to your machine. ### Common Use Cases[​](#common-use-cases "Direct link to Common Use Cases") * **QA teams** downloading test evidence (screenshots, logs, video captures) from all test execution issues for compliance reporting * **Project managers** collecting deliverables and documents from all issues in a release or sprint for stakeholder review * **Support teams** archiving customer-provided files from resolved tickets before closing a milestone * **Development teams** packaging release artifacts, specs, and design assets tied to a specific version * **Auditors** exporting all attachments from issues flagged during a compliance review Learn more in the [Simple Bulk Attachment Downloader documentation](/docs/Simple-Bulk-Attachment-Downloader-for-Jira/user-docs.md). *** ## Attachment Reviewer for Jira[​](#attachment-reviewer-for-jira "Direct link to Attachment Reviewer for Jira") Attachment Reviewer for Jira is the inbound solution. It validates every file uploaded to your Jira issues against configurable policies and automatically removes non-compliant attachments. ### How It Works[​](#how-it-works-1 "Direct link to How It Works") 1. **A user uploads a file** to any Jira issue through the web interface, mobile app, or API. 2. **The app validates automatically.** Attachment Reviewer checks the file against the project's rules -- file type and file size. 3. **The file passes, warns, or fails.** Passed files stay. Failed files are removed immediately. Warned files stay but generate a notification. 4. **A comment is posted.** The issue gets a validation report comment explaining what happened. Everything happens in milliseconds. The user sees the result as a comment on the issue, usually before they navigate away. ### Key Features[​](#key-features-1 "Direct link to Key Features") **File type policies.** Two modes are available. **Whitelist mode** (recommended) allows only explicitly approved file extensions -- for example, pdf, docx, png, xlsx. Everything else is blocked. **Blacklist mode** allows all file types except those explicitly blocked. Whitelist is more secure; blacklist is more flexible. **Comprehensive default blocklist.** The app ships with a curated blocklist covering executables (exe, msi, bat, cmd), scripts (vbs, ps1, sh, bash), system files (sys, dll, drv), Java archives (jar, war, ear), mobile packages (apk, ipa, dmg), macro-enabled documents (docm, xlsm, pptm), and more. Blocked types always take precedence, even in blacklist mode. **File size enforcement.** Set a maximum file size (1 MB to 500 MB, default 25 MB) that hard-blocks oversized uploads. Set a separate warning threshold (default 10 MB) that allows the file but alerts the team. This two-tier system lets you discourage large attachments without breaking workflows that genuinely need them. **Project-level configuration.** Each Jira project has independent settings. Development projects can allow code files (js, py, java). Design projects can set higher size limits for images. Documentation projects can restrict to PDFs and office documents. General projects use the secure defaults. **Automatic removal and feedback.** When a file fails validation, it is deleted from the issue automatically. No manual cleanup needed. A validation report comment is posted with the file name, type, size, and the specific rule that was violated. Users know exactly what went wrong and how to fix it. **Zero content inspection.** The app only checks metadata -- file extension, MIME type, and file size. It does not read file contents. No data leaves Atlassian's infrastructure. The app runs on Atlassian Forge, which means it stays within Atlassian's secure cloud platform. ### Common Use Cases[​](#common-use-cases-1 "Direct link to Common Use Cases") * **Security-conscious organizations** blocking executables, scripts, and macro-enabled documents from being uploaded to any issue * **Storage management** enforcing file size limits per project to keep Jira storage usage under control * **Compliance teams** requiring that only approved file types are attached to audit-related issues * **Multi-project organizations** applying different rules per project -- strict for production issues, relaxed for internal tooling * **External collaboration** projects where outside users submit files and you need to enforce what file types are accepted Learn more in the [Attachment Reviewer for Jira documentation](/docs/Attachment-Reviewer-for-Jira/user-docs.md). *** ## Feature Comparison[​](#feature-comparison "Direct link to Feature Comparison") | Feature | Simple Bulk Attachment Downloader | Attachment Reviewer | | ----------------------------- | --------------------------------------- | ------------------------------------------- | | **Primary purpose** | Bulk export attachments from Jira | Enforce file policies on uploads | | **Direction** | Outbound (Jira to local machine) | Inbound (local machine to Jira) | | **Trigger** | Manual -- click from issue navigator | Automatic -- runs on every upload | | **JQL integration** | Yes -- download from any search results | Not applicable | | **File type filtering** | No -- downloads all attachments | Yes -- whitelist or blacklist modes | | **File size limits** | No -- downloads all sizes | Yes -- max size and warning threshold | | **Parallel processing** | Yes -- 3-8x faster concurrent downloads | Not applicable (single-file validation) | | **ZIP packaging** | Yes -- organized by issue folders | No | | **Permission awareness** | Yes -- respects Jira read permissions | Yes -- requires project admin for settings | | **Per-project configuration** | No -- works globally | Yes -- independent settings per project | | **Automatic enforcement** | No -- user-initiated action | Yes -- validates every upload automatically | | **Comment feedback** | No | Yes -- validation report on every upload | | **Configuration required** | None -- works after install | Minimal -- secure defaults work immediately | | **Platform** | Jira Cloud (Atlassian Forge) | Jira Cloud (Atlassian Forge) | | **Pricing** | See Atlassian Marketplace | See Atlassian Marketplace | *** ## When to Use Each App[​](#when-to-use-each-app "Direct link to When to Use Each App") The two apps solve different problems. Here are the scenarios where each one -- or both -- is the right choice. ### Use Simple Bulk Attachment Downloader When...[​](#use-simple-bulk-attachment-downloader-when "Direct link to Use Simple Bulk Attachment Downloader When...") **You need to archive project attachments.** A project is wrapping up and you need to download every file for long-term storage outside Jira. Run a search for all issues in the project, click download, and you have a complete, organized archive. **You are preparing for an audit.** Auditors want all supporting documents from issues tagged with a specific label. Search by label, download the ZIP, and share it with the audit team. The folder structure ties every file back to its issue. **You are migrating or backing up.** Before a major configuration change, project split, or data migration, you want a local copy of all attachments. One download gives you everything organized by issue. **Your team reviews deliverables in bulk.** A QA manager needs all test evidence from the last sprint. A product manager wants all design mockups from stories in the current release. Search, download, review locally. ### Use Attachment Reviewer When...[​](#use-attachment-reviewer-when "Direct link to Use Attachment Reviewer When...") **Security is a priority.** You do not want .exe files, shell scripts, or macro-enabled documents anywhere in your Jira instance. Set whitelist mode and only approved file types get through. The default blocklist handles the most common threats out of the box. **Storage costs are a concern.** Your Jira Cloud plan has storage limits and large attachments are consuming your quota. Set file size limits per project to prevent users from uploading files that do not belong in Jira. **You have external collaborators.** Customers, vendors, or contractors submit files through Jira Service Management or shared projects. Attachment Reviewer ensures only the file types you approve are accepted, regardless of who uploads them. **Compliance requires documented policies.** Your organization needs proof that file upload policies are enforced. Every validation creates an audit trail in the issue comments, showing what was allowed, warned, or blocked and why. **Different projects need different rules.** Your development projects need to allow code files. Your HR projects should only accept PDFs and images. Attachment Reviewer lets you configure rules independently per project. ### Use Both When...[​](#use-both-when "Direct link to Use Both When...") Many teams benefit from using both apps together. Attachment Reviewer keeps your Jira instance clean and secure by controlling what goes in. Simple Bulk Attachment Downloader gives you an efficient way to get everything out when you need it. A practical combined workflow: 1. **Attachment Reviewer** runs on every upload, ensuring only compliant files enter your Jira projects. 2. Over time, issues accumulate clean, policy-compliant attachments. 3. When you need to export -- for audits, archiving, migration, or sharing -- **Simple Bulk Attachment Downloader** pulls everything out in one organized ZIP. The result: your Jira instance stays clean, and exporting is always one click away. *** ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Simple Bulk Attachment Downloader -- User Guide](/apps/simple-bulk-attachment-downloader-for-jira.md) -- step-by-step instructions for bulk downloading Jira attachments * [Attachment Reviewer for Jira -- User Guide](/apps/attachment-reviewer-for-jira.md) -- configuration guide for file type and size policies * [How to Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) -- detailed walkthrough of the bulk download workflow * [Jira Attachment Permissions FAQ](/blog/faq-jira-attachments-permissions.md) -- common questions about who can see, upload, and download attachments * [Bulk Operations FAQ](/blog/faq-bulk-operations-jira.md) -- answers to common questions about bulk actions in Jira ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [comparison](/blog/tags/comparison.md) * [jira](/blog/tags/jira.md) * [attachments](/blog/tags/attachments.md) * [bulk](/blog/tags/bulk.md) * [export](/blog/tags/export.md) --- # Jira Backlog Grooming: The Complete Guide to Refining Stories July 29, 2026 · 7 min read [NGPilot](https://ngpilot.com) Quick Answer Backlog grooming is the process of refining, estimating, and prioritizing Jira stories so they are sprint-ready. A well-groomed backlog makes sprint planning fast and predictable. What you'll learn 1. How to set up a grooming cadence that keeps your backlog healthy 2. A template for writing acceptance criteria that eliminate ambiguity 3. The planning poker workflow for accurate story point estimation 4. How to rank stories so the highest-value work always comes first A messy backlog is the silent killer of Agile teams. Stories pile up without refinement, acceptance criteria are vague, and sprint planning becomes a guessing game. By the time the team realizes the backlog is broken, velocity has dropped and trust in the process has eroded. Backlog grooming — also called refinement — is the antidote. It is the ongoing process of reviewing, splitting, estimating, and prioritizing stories so the backlog is always sprint-ready. This guide covers a complete grooming workflow in Jira, from writing acceptance criteria to ranking by business value. ## Why Grooming Matters More Than Planning[​](#why-grooming-matters-more-than-planning "Direct link to Why Grooming Matters More Than Planning") Most teams focus on sprint planning, but grooming is where the real work happens. A well-groomed backlog makes planning fast — you drag stories into the sprint and go. A poorly groomed backlog turns planning into a 3-hour debate about what "done" means. **Signs your backlog needs grooming:** * Stories sit in the backlog for months without refinement * Sprint planning regularly runs over 2 hours * Stories are pulled into sprints with vague or missing acceptance criteria * The team frequently discovers mid-sprint that a story is bigger than expected * Velocity varies wildly between sprints **What good grooming looks like:** * Top 20-30 stories are fully refined (acceptance criteria, story points, dependencies) * New stories are refined within 1 week of creation * Sprint planning takes less than 2 hours * Velocity is predictable within a 10-15% range ## How to Groom the Jira Backlog: Step-by-Step[​](#how-to-groom-the-jira-backlog-step-by-step "Direct link to How to Groom the Jira Backlog: Step-by-Step") ### 1. Establish a Grooming Cadence[​](#1-establish-a-grooming-cadence "Direct link to 1. Establish a Grooming Cadence") Grooming is not a one-time event. It should happen 2-3 times per week, each session lasting 30-45 minutes. **Recommended schedule:** | Day | Focus | Duration | | ----------------- | ------------------------------------------- | -------- | | Tuesday | Review new stories, add acceptance criteria | 30 min | | Thursday | Estimate stories, rank backlog | 45 min | | Friday (optional) | Quick sanity check before sprint planning | 15 min | **Who attends:** * Product owner (presents priorities, answers questions) * Tech lead (helps refine technical details) * 2-3 developers (for estimation and feasibility input) * Scrum master (facilitates, keeps time) ### 2. Write Clear Acceptance Criteria[​](#2-write-clear-acceptance-criteria "Direct link to 2. Write Clear Acceptance Criteria") Acceptance criteria are the contract between the product owner and the development team. Without them, "done" is a matter of opinion. **Template for acceptance criteria:** ``` Given [context] When [action] Then [expected result] ``` **Example for a "User Login" story:** ``` Given a registered user with valid credentials When they enter their email and password and click "Log In" Then they are redirected to the dashboard within 2 seconds Given a registered user with an invalid password When they enter their email and wrong password and click "Log In" Then they see "Invalid credentials" and the login form remains Given a user with 5 consecutive failed login attempts When they attempt a 6th login Then their account is locked for 15 minutes and they see a lockout message ``` **Checklist for good acceptance criteria:** * Testable — can be verified by a developer or QA * Specific — no vague language like "should work" or "should be fast" * Complete — covers happy path, edge cases, and error states * Agreed upon — both product owner and team sign off ### 3. Estimate with Planning Poker[​](#3-estimate-with-planning-poker "Direct link to 3. Estimate with Planning Poker") Story points measure effort relative to complexity, not raw hours. Planning poker is the most common estimation technique. **How it works:** 1. Product owner reads the story and acceptance criteria 2. Each team member selects a story point card (1, 2, 3, 5, 8, 13, 21) 3. Everyone reveals their card simultaneously 4. If estimates vary widely, discuss why 5. Re-estimate until the team converges **Reference stories for calibration:** | Story | Points | Why | | ----------------------------------- | ------ | ----------------------------------------- | | Add a button to a form | 1 | Simple UI change, no logic | | Build a settings page with 5 fields | 3 | Moderate UI + validation | | Integrate with a third-party API | 5 | External dependency, error handling | | Refactor a core module | 8 | High complexity, risk of breaking changes | | Migrate a database schema | 13 | High risk, multiple systems affected | **When estimates diverge:** * The highest estimator explains their reasoning * The lowest estimator explains why they see it as simpler * Discussion often reveals hidden complexity or oversimplification * Re-estimate after discussion ### 4. Apply the INVEST Checklist[​](#4-apply-the-invest-checklist "Direct link to 4. Apply the INVEST Checklist") Before marking a story as sprint-ready, verify it passes the INVEST test: | Letter | Meaning | Question to Ask | | ------ | ----------- | ----------------------------------------------------------------- | | I | Independent | Can this story be developed without depending on other stories? | | N | Negotiable | Is the implementation approach flexible, or is it over-specified? | | V | Valuable | Does this story deliver value to the user or business? | | E | Estimable | Can the team estimate this story with reasonable confidence? | | S | Small | Can this story be completed in a single sprint? | | T | Testable | Are there clear acceptance criteria that can be verified? | **Stories that fail INVEST:** * "Implement the new design system" — too big, needs splitting * "Fix the bug" — not valuable (what is the user impact?) * "Use React 18" — not negotiable (implementation detail, not a story) * "Do the thing from the meeting" — not estimable (no acceptance criteria) ### 5. Rank by Value and Effort[​](#5-rank-by-value-and-effort "Direct link to 5. Rank by Value and Effort") Ranking ensures the most valuable work is always at the top of the backlog. Use a simple formula: **Priority Score = Business Value / Story Points** | Story | Business Value | Story Points | Priority Score | | -------------------- | -------------- | ------------ | -------------- | | Fix checkout bug | High (10) | 2 | 5.0 | | Add dark mode | Medium (5) | 8 | 0.625 | | Refactor auth module | High (10) | 13 | 0.77 | | Update documentation | Low (2) | 1 | 2.0 | The checkout bug ranks highest — high value, low effort. Dark mode ranks lowest — moderate value, high effort. **Ranking rules:** 1. Bugs with user impact always rank above features 2. Dependencies get ranked higher if they block other stories 3. Technical debt gets scheduled alongside features, not in a separate "tech debt sprint" ## FAQ[​](#faq "Direct link to FAQ") ### How often should I groom the Jira backlog?[​](#how-often-should-i-groom-the-jira-backlog "Direct link to How often should I groom the Jira backlog?") Groom 2-3 times per week for 30-45 minutes each. Weekly grooming is the minimum for teams running 2-week sprints. More frequent sessions keep the backlog healthy and make sprint planning faster. ### Who participates in backlog grooming?[​](#who-participates-in-backlog-grooming "Direct link to Who participates in backlog grooming?") The product owner leads grooming and presents priorities. The tech lead or senior developers help refine acceptance criteria and estimate complexity. The full team should attend at least once per week for estimation. ### What makes a good user story in Jira?[​](#what-makes-a-good-user-story-in-jira "Direct link to What makes a good user story in Jira?") A good user story follows the 'As a \[role], I want \[feature], so that \[benefit]' format, has clear acceptance criteria, is estimable in story points, and can be completed within a single sprint. ### How do I handle large epics in the backlog?[​](#how-do-i-handle-large-epics-in-the-backlog "Direct link to How do I handle large epics in the backlog?") Break epics into smaller stories that can be completed in one sprint. Use Jira's epic link field to group related stories. A story that takes more than 5 story points likely needs to be split. ### Should I delete stories from the backlog?[​](#should-i-delete-stories-from-the-backlog "Direct link to Should I delete stories from the backlog?") Do not delete — close them as 'Won't Do' or move them to a separate 'Icebox' project. This preserves history and prevents duplicate stories from being created later. ## Related guides[​](#related-guides "Direct link to Related guides") * [How to Plan Jira Sprints That Actually Work](/blog/plan-jira-sprints-that-actually-work.md) * [Jira JQL Cheat Sheet: 20 Queries Every Team Needs](/blog/jira-jql-cheat-sheet-common-queries.md) * [How to Set Up Jira Dashboards for Sprint Tracking](/blog/jira-dashboard-sprint-tracking-setup.md) * [Creating Jira Issues from Templates with Bulk Create](/blog/create-jira-issues-from-templates.md) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [backlog-grooming](/blog/tags/backlog-grooming.md) * [agile](/blog/tags/agile.md) * [how-to](/blog/tags/how-to.md) * [scrum](/blog/tags/scrum.md) --- # How to Add a Checklist to Jira — and Block Transitions Until Done September 18, 2026 · 5 min read [NGPilot](https://ngpilot.com) Every team has a definition of done. The problem is that in Jira, "done" is one button press — nothing checks whether the release notes were written, the tests passed, or the customer was notified. A checklist fixes the *remembering*; enforcement fixes the *skipping*. This guide covers three ways to add a checklist to Jira issues, from a two-minute bullet list to required items that physically block the Done transition. **Quick answer:** Jira has no native checklist panel. For enforcement — the part most teams actually want — install [Checklist Workflow Automation for Jira](https://marketplace.atlassian.com/apps/1795968238/), flag items as **required**, and have a Jira admin add the **Checklist required items complete** validator to the workflow's Done transition. From then on, Jira refuses to close an issue while any required item is unfinished. Free for up to 10 users. ## Method 1 — Bullets in the Description (Zero Setup, Zero Enforcement)[​](#method-1--bullets-in-the-description-zero-setup-zero-enforcement "Direct link to Method 1 — Bullets in the Description (Zero Setup, Zero Enforcement)") Type `- [ ] item` lines into the issue description or a comment. It renders as a list, anyone can edit it, and it takes thirty seconds. **Good for:** ad-hoc personal notes on a ticket. **What's missing:** nothing is checked automatically, nothing is searchable, and nothing prevents the issue from being closed with every box unticked. The checklist lives in free text, so JQL can't see it, reports can't count it, and a careless edit can delete it. It records intent; it enforces nothing. ## Method 2 — Subtasks (Visible, Heavyweight, Still Not Enforced)[​](#method-2--subtasks-visible-heavyweight-still-not-enforced "Direct link to Method 2 — Subtasks (Visible, Heavyweight, Still Not Enforced)") Create each checklist item as a subtask. You get per-item assignees and statuses, and the items show on the board. **Good for:** work that genuinely needs its own owner and lifecycle. **What's missing for a checklist:** subtasks are separate work items — one definition-of-done list becomes five board cards, five assignee pings, and a cluttered backlog. And Jira's standard workflow never blocks the parent's transition on subtask state: close the parent and Jira happily leaves subtasks open. Using subtasks as a checklist adds process weight without adding the one thing checklists are for — the guarantee that done means done. ## Method 3 — a Checklist Panel with Required Items (Recommended)[​](#method-3--a-checklist-panel-with-required-items-recommended "Direct link to Method 3 — a Checklist Panel with Required Items (Recommended)") [Checklist Workflow Automation for Jira](https://marketplace.atlassian.com/apps/1795968238/) adds a checklist panel to every issue: type tasks, press Enter, and flag any row as **required**. The checklist is stored on the issue itself — it survives moves, copies when you clone, and shows up in JQL. The part that changes team behavior is enforcement: 1. A Jira admin opens **Project settings → Workflows**, edits the workflow, and on the transition into Done adds the validator **Checklist required items complete** (category: *Forge apps*). 2. From then on, transitioning an issue with an unfinished required item is refused, with the offenders named: `Complete required checklist items before transitioning: "Book venue", …` 3. Optionally, the same transition gets the **Complete required checklist items** post function, which auto-completes required items after the transition — useful when the checklist documents *review steps* rather than work. Two rules make the enforcement predictable: only **exactly Done** satisfies a requirement (custom statuses like *Waiting on vendor* still block), and if the app ever can't read a checklist, the validator **fails open** — a broken app must never brick a workflow. ## A Definition-of-Done Checklist You Can Copy[​](#a-definition-of-done-checklist-you-can-copy "Direct link to A Definition-of-Done Checklist You Can Copy") Save this as a project template (the ⋯ menu on any issue) and apply it to new issues in one click: ``` Design review approved Test plan written Unit tests pass Integration tests pass Release notes updated Customer communication drafted Monitoring dashboard checked ``` Mark the first, second, and last items **required** and closing an issue without them becomes impossible. Prefer a spreadsheet? Import/export round-trips CSV with the nesting intact: ``` Item Text,Status,Order,Level Design review approved,Done,1,0 Test plan written,To Do,2,0 Unit tests pass,To Do,3,1 Integration tests pass,To Do,4,1 Release notes updated,To Do,5,0 ``` ## Find the Work That Isn't Actually Done[​](#find-the-work-that-isnt-actually-done "Direct link to Find the Work That Isn't Actually Done") The checklist is indexed for JQL, so "what's still owed before Done" becomes a saved filter or a dashboard gadget: ``` issue in hasIncompleteRequired() cwaIncompleteRequired > 0 AND assignee = currentUser() AND sprint in openSprints() cwaOverdueRequired > 0 ``` Pair it with overdue reminders — a daily sweep comments on issues where a required item is past its due date, mentioning the assignee, at most once every 7 days per issue. ## Which Method Should You Use?[​](#which-method-should-you-use "Direct link to Which Method Should You Use?") | Need | Use | | ----------------------------------------- | ----------------------------------------- | | Personal notes on one ticket | Description bullets | | Work with its own owner and board card | Subtasks | | A definition of done the team cannot skip | Checklist with required items + validator | For the third row — release checklists, incident response, onboarding steps — the setup cost is one workflow edit, and it pays back the first time Jira stops an issue from closing half-done. Install [Checklist Workflow Automation for Jira](https://marketplace.atlassian.com/apps/1795968238/), flag the non-negotiables as required, and make "done" mean done. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Create Jira issue templates](/blog/how-to-create-jira-issue-templates.md) — pair a checklist template with a structured issue body * [Export Jira issues to Excel](/blog/export-jira-issues-to-excel.md) — report on issues alongside their checklist counters * [How to Create a Component Hierarchy in Jira](/blog/jira-component-hierarchy.md) — give flat component lists a parent-child structure * [Checklist Workflow Automation for Jira](/apps/checklist-workflow-automation-for-jira.md) — full documentation: enforcement, templates, CSV, JQL, and audit log ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [checklist](/blog/tags/checklist.md) * [workflow](/blog/tags/workflow.md) * [how-to](/blog/tags/how-to.md) * [definition-of-done](/blog/tags/definition-of-done.md) * [process](/blog/tags/process.md) --- # How to Create a Component Hierarchy in Jira September 23, 2026 · 5 min read [NGPilot](https://ngpilot.com) Jira components were designed for a flat world: one list, no nesting, no structure. That works at ten components and collapses at fifty — when "SSO" sits next to "Platform" and "Mobile" with nothing expressing that it belongs under "Auth", which belongs under "Platform". Teams end up encoding the architecture in name prefixes and maintaining ever-growing `component in (...)` lists by hand. This guide covers three ways to get a component hierarchy in Jira, and what each one costs. **Quick answer:** Jira cannot nest components natively. [Component Hierarchy for Jira](https://marketplace.atlassian.com/apps/2232005585/) adds a parent-child tree per project: build it on a project page, pick a full path like `Platform/Auth/SSO` on each issue with a cascading picker, and search whole branches with one JQL function — `inComponentHierarchy("Auth")` — instead of maintained component lists. Every node is a real Jira component, so boards, releases, and reports keep working. ## Why a Flat Component List Stops Working[​](#why-a-flat-component-list-stops-working "Direct link to Why a Flat Component List Stops Working") The flat model fails in a specific, predictable way: the structure lives in people's heads, and every tool that needs it re-asks for it. A board filter wants the list of platform components. A report wants everything under Auth. A new subcomponent invalidates every one of those lists at once. Multiply by a few areas and a few teams, and "which components make up the platform?" becomes tribal knowledge with a shelf life. ## Method 1 — Naming Conventions (Free, Fragile)[​](#method-1--naming-conventions-free-fragile "Direct link to Method 1 — Naming Conventions (Free, Fragile)") Rename components into paths: `platform-auth-sso`, `platform-auth-oauth`, `mobile-auth-sso`. Sorting by name fakes a tree view, and the prefix tells humans where things belong. **Good for:** small projects that need a visible grouping and nothing more. **What's missing:** the hierarchy is in the string, and nothing queries it. There is no JQL for "everything starting with `platform-auth-` and everything under it" — you still enumerate members. Conventions also rot: one person types `Platform-auth`, another creates `platform-auth-sso-v2`, and every filter built on the prefix quietly misses issues. Structure by convention needs a curator, and curators move on. ## Method 2 — Labels or a Custom Field (Searchable, Unstructured)[​](#method-2--labels-or-a-custom-field-searchable-unstructured "Direct link to Method 2 — Labels or a Custom Field (Searchable, Unstructured)") Give issues a second axis: a label like `area-auth` or a single-select custom field "Subsystem". JQL can now filter on it. **Good for:** one level of grouping that only needs to answer "all issues in area X". **What's missing:** a flat field cannot answer path questions — "everything under Platform, at any depth" becomes another explicit list of values. There is no cascade (pick Auth and SSO must follow), no structure for a service catalog, and now you maintain two parallel truths: the components boards use, and the field reports use. They drift. ## Method 3 — a Real Component Tree (Recommended)[​](#method-3--a-real-component-tree-recommended "Direct link to Method 3 — a Real Component Tree (Recommended)") [Component Hierarchy for Jira](https://marketplace.atlassian.com/apps/2232005585/) adds the missing dimension on top of components, not instead of them: 1. **Build the tree** on the project page (project sidebar → **Apps** → **Component Hierarchy**): add root nodes, nest children as deep as needed, move subtrees, rename anything. Changes save automatically, and every node is a **real Jira component** — existing components with matching names are adopted, never duplicated. 2. **Pick a path on each issue.** The *Component Hierarchy* field is a cascading picker — level by level from roots to leaves — available on issues, create dialogs, transition screens, and JSM portal requests. Setting it adds the selected nodes' components to the issue automatically (it only ever adds). 3. **Search branches with one clause.** `inComponentHierarchy("Auth")` returns every issue whose path is `Auth` or starts with `Auth/`, at any depth: ``` inComponentHierarchy("Auth") AND status != Done inComponentHierarchy("Platform") AND assignee = currentUser() not inComponentHierarchy("Deprecated") ``` Two nodes sharing a name at different depths? Add the level: `inComponentHierarchy("Auth", 2)`. Because queries resolve through the tree, they stay correct as it evolves: rename a node and every issue shows the new name immediately; add a subcomponent tomorrow and every saved filter covering its parent already covers it. No more lists to maintain. ## Bulk-Build the Tree from CSV[​](#bulk-build-the-tree-from-csv "Direct link to Bulk-Build the Tree from CSV") For a project with an established component list, don't click the tree into existence — import it: ``` Name,Parent Platform, Auth,Platform SSO,Auth OAuth,Auth Mobile, ``` A blank `Parent` marks a root; every parent must be defined in its own row. Download the exact template from the project page, fill it in, and import — the import **replaces** the current tree (export first if you want a backup), and the **Sync components** button creates a Jira component for any node still missing one. ## Which Method Should You Use?[​](#which-method-should-you-use "Direct link to Which Method Should You Use?") | Need | Use | | ------------------------------------------------------------ | ---------------------------- | | A visible grouping on a handful of components | Naming conventions | | One flat "subsystem" axis for filtering | Label or single-select field | | A real tree: cascading picker, subtree JQL, service catalogs | Component Hierarchy for Jira | The third row is the one that survives growth: the tree stays the single source of structure, components stay the single source of truth for boards and reports, and branch queries cost one function call instead of a maintained list. Install [Component Hierarchy for Jira](https://marketplace.atlassian.com/apps/2232005585/), import your existing structure as CSV, and let `inComponentHierarchy()` replace the lists. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Build a Component Hierarchy in Jira](/solutions/component-hierarchy-in-jira.md) — the scenario guide: modeling, adoption paths, and search patterns * [How to Add a Checklist to Jira](/blog/jira-checklist.md) — another way to add missing structure to Jira issues * [Component Hierarchy for Jira](/apps/component-hierarchy-for-jira.md) — full documentation: the tree editor, the field, JQL, CSV import/export, and troubleshooting ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [components](/blog/tags/components.md) * [hierarchy](/blog/tags/hierarchy.md) * [jql](/blog/tags/jql.md) * [how-to](/blog/tags/how-to.md) * [project-structure](/blog/tags/project-structure.md) --- # How to Set Up Jira Dashboards for Sprint Tracking and Stakeholder Visibility July 29, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Jira dashboards provide real-time visibility into sprint health, velocity trends, and team performance. Configure gadgets, create JQL filters, and share dashboards with stakeholders. What you'll learn 1. How to create and configure a Jira dashboard from scratch 2. Which gadgets track sprint health vs long-term trends 3. How to set up JQL filters for custom dashboard views 4. How to share dashboards and set up email subscriptions A well-designed Jira dashboard gives your team instant visibility into sprint health, backlog status, and delivery trends. But most dashboards are either empty defaults or cluttered messes that nobody uses. This guide covers how to build dashboards that actually provide value — from sprint tracking to stakeholder reporting. ## Why Dashboards Matter[​](#why-dashboards-matter "Direct link to Why Dashboards Matter") Without a dashboard, teams rely on manual status updates, Excel spreadsheets, and hallway conversations to understand project health. This is slow, error-prone, and does not scale. **Benefits of a well-designed dashboard:** * Real-time sprint health (no more asking "are we on track?") * Velocity trends for better future planning * Stakeholder visibility without constant meetings * Early warning signs when sprints go off track * Historical data for process improvement ## How to Set Up a Jira Dashboard: Step-by-Step[​](#how-to-set-up-a-jira-dashboard-step-by-step "Direct link to How to Set Up a Jira Dashboard: Step-by-Step") ### 1. Create a New Dashboard[​](#1-create-a-new-dashboard "Direct link to 1. Create a New Dashboard") 1. Go to **Dashboards > Create dashboard** 2. Name it descriptively (e.g., "Team Alpha - Sprint Dashboard") 3. Set the owner (usually the scrum master or team lead) 4. Configure sharing: * **Private** — only you can see it * **Group** — share with a Jira group (e.g., "Engineering Team") * **Project** — share with everyone in a project * **Everyone** — public dashboard **Recommended:** Start private, share with your team, then expand to stakeholders as needed. ### 2. Add Sprint Health Gadgets[​](#2-add-sprint-health-gadgets "Direct link to 2. Add Sprint Health Gadgets") These gadgets show real-time sprint status: **Sprint Health Gadget:** * Shows open vs done issues in the current sprint * Color-coded by issue type * Updates automatically as issues move **Sprint Burndown Gadget:** * Tracks remaining work against ideal burndown * Flat line = blocked work * Steep drop = work not truly done **Sprint Cumulative Flow Gadget:** * Shows work moving through statuses over time * Identifies bottlenecks (when bands widen) * Tracks scope creep (when top band grows) **Configuration:** 1. Click **Add gadget** on your dashboard 2. Search for the gadget name 3. Select your board and sprint 4. Set refresh interval (5 minutes for active sprints) ### 3. Add Velocity and Reporting Gadgets[​](#3-add-velocity-and-reporting-gadgets "Direct link to 3. Add Velocity and Reporting Gadgets") These gadgets show long-term trends: **Velocity Chart Gadget:** * Shows completed story points per sprint * Use for capacity planning (average of last 5 sprints) * Compare committed vs completed **Version Report Gadget:** * Tracks progress toward a release * Shows estimated completion date * Identifies scope changes affecting the release **Created vs Resolved Gadget:** * Compares new issues created vs issues resolved * Growing gap = backlog expanding faster than delivery * Shrinking gap = team is catching up **Configuration:** 1. Add the gadget to your dashboard 2. Select the project and time range 3. Choose the metric (story points, issue count) 4. Set the date range (last 5 sprints for velocity, last 30 days for created vs resolved) ### 4. Configure Filter-Based Gadgets[​](#4-configure-filter-based-gadgets "Direct link to 4. Configure Filter-Based Gadgets") For custom views, create JQL filters and use them in gadgets: **Useful filters to create:** | Filter Name | JQL | Use Case | | ------------------- | -------------------------------------------------- | ------------------------- | | My Open Issues | assignee = currentUser() AND status != Done | Personal task list | | Blockers | priority = Blocker AND status != Done | Escalation tracking | | Unestimated Stories | issuetype = Story AND cf\[10002] IS EMPTY | Backlog grooming | | Ready for QA | status = "In Review" AND assignee != currentUser() | QA workload | | Aging Issues | updated ≤ -7d AND status != Done | Stale work identification | **Gadgets that use filters:** * **Filter Results** — tabular view of matching issues * **Two Dimensional Statistics** — group by two fields (e.g., assignee × status) * **Pie Chart** — distribution by a field (e.g., issues by priority) * **Bar Chart** — comparison by a field (e.g., issues by assignee) ### 5. Share and Subscribe to Dashboards[​](#5-share-and-subscribe-to-dashboards "Direct link to 5. Share and Subscribe to Dashboards") **Sharing:** * Share with your team's Jira group for sprint tracking * Share with stakeholders for visibility * Use "View as" to preview what others see **Email subscriptions:** 1. Go to your saved filter (not the dashboard) 2. Click **Details > New Subscription** 3. Set frequency: daily, weekly, or custom 4. Add recipients (Jira users or email addresses) 5. Jira emails a snapshot of matching issues on schedule **Pro tip:** Create a "Stakeholder Summary" dashboard with high-level gadgets (velocity, burndown, release progress) and subscribe stakeholders to a weekly email. They get visibility without logging into Jira. ## FAQ[​](#faq "Direct link to FAQ") ### How many gadgets should a Jira dashboard have?[​](#how-many-gadgets-should-a-jira-dashboard-have "Direct link to How many gadgets should a Jira dashboard have?") Aim for 6-10 gadgets per dashboard. Too many gadgets slow loading and overwhelm viewers. Group related gadgets logically: sprint health at the top, velocity trends in the middle, stakeholder summary at the bottom. ### What is the best gadget for tracking sprint progress?[​](#what-is-the-best-gadget-for-tracking-sprint-progress "Direct link to What is the best gadget for tracking sprint progress?") The Sprint Health gadget gives a real-time overview of open vs done issues. Pair it with the Sprint Burndown gadget to see if the team is on track. For longer trends, add the Sprint Cumulative Flow gadget. ### Can I share a Jira dashboard with non-Jira users?[​](#can-i-share-a-jira-dashboard-with-non-jira-users "Direct link to Can I share a Jira dashboard with non-Jira users?") Not directly. Non-Jira users cannot view dashboards. Workaround: export dashboard data to a Confluence page or use a reporting tool that integrates with Jira API to generate shareable reports. ### How do I create a JQL filter for a dashboard gadget?[​](#how-do-i-create-a-jql-filter-for-a-dashboard-gadget "Direct link to How do I create a JQL filter for a dashboard gadget?") Go to Issues > Advanced Search, write your JQL query, save it as a filter, then use that filter in any gadget that supports filter input. Saved filters can be shared with other users. ### Can I automate Jira dashboard emails?[​](#can-i-automate-jira-dashboard-emails "Direct link to Can I automate Jira dashboard emails?") Yes. Go to your saved filter > Details > New Subscription. Set the frequency (daily, weekly), add recipients, and Jira will email a snapshot of matching issues on schedule. This works for any saved filter, not just dashboards. ## Related guides[​](#related-guides "Direct link to Related guides") * [How to Plan Jira Sprints That Actually Work](/blog/plan-jira-sprints-that-actually-work.md) * [Jira JQL Cheat Sheet: 20 Queries Every Team Needs](/blog/jira-jql-cheat-sheet-common-queries.md) * [Export Jira Issues to Excel for Stakeholder Reporting](/blog/export-jira-issues-to-excel-csv-reporting.md) * [How to Set Up Jira Dashboards for Sprint Tracking](/blog/jira-dashboard-sprint-tracking-setup.md) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [dashboards](/blog/tags/dashboards.md) * [how-to](/blog/tags/how-to.md) * [reporting](/blog/tags/reporting.md) * [sprint-tracking](/blog/tags/sprint-tracking.md) --- # Best Diagram App for Jira — 2026 Comparison with Mermaid & Excalidraw April 18, 2026 · 7 min read [NGPilot](https://ngpilot.com) Every engineering team needs diagrams in Jira — architecture decisions on epics, bug reproduction flows on tickets, wireframes on stories. But Jira has no built-in diagramming. You either paste screenshots from external tools or install a marketplace app. We built two diagram apps for Jira: **Mermaid+ Diagrams for Jira** for text-based diagrams using Mermaid syntax (flowcharts, sequence diagrams, ER models, C4 architecture), and **Excalidraw Diagrams + Whiteboards for Jira** for freeform drawing with 229 built-in shape libraries. In this post we compare both against every alternative on the Atlassian Marketplace. ## Two Styles of Diagramming[​](#two-styles-of-diagramming "Direct link to Two Styles of Diagramming") **Text-based diagrams (Mermaid)** — You write code, the app renders a diagram. Fast for developers who think in code. Great for flowcharts, sequence diagrams, ER models, class diagrams, and architecture docs. The diagram is version-controllable text. **Freeform drawing (Excalidraw)** — You draw with a mouse or tablet. Great for whiteboarding sessions, wireframes, architecture sketches, and any diagram where you want creative freedom. Hand-drawn style keeps conversations focused on ideas instead of pixel perfection. Both have their place. Let's see what's available for each in Jira. *** ## What's Available on the Marketplace[​](#whats-available-on-the-marketplace "Direct link to What's Available on the Marketplace") The Jira diagram market is dominated by one player, with several smaller apps filling niches: | App | Vendor | Installs | Rating | Last Updated | Hosting | | ---------------------------------------------- | ------------- | --------------- | ------------------- | ------------ | ------------------- | | draw\.io Diagrams for Jira | Seibert Media | 9,602 | 3.8/5 (349 reviews) | Mar 2026 | Cloud + DC + Server | | Mermaid Charts & Diagrams for Jira | weweave | 544 | 4.0/5 (1 review) | Mar 2026 | Cloud | | Draw UI Wireframes/Mockup/Diagrams | DevSamurai | 426 | 3.8/5 (13 reviews) | Mar 2026 | Cloud | | Excalidraw Whiteboard for Jira Cloud | Fulstech | 111 | 3.5/5 (2 reviews) | Feb 2026 | Cloud | | Excalidraw Mermaid Diagrams for Jira | Simplify | 40 | — | Feb 2026 | Cloud | | **Mermaid+ Diagrams for Jira** | **NGPILOT** | **Coming soon** | — | **Apr 2026** | **Cloud** | | **Excalidraw Diagrams + Whiteboards for Jira** | **NGPILOT** | **Coming soon** | — | **Apr 2026** | **Cloud** | *Data from Atlassian Marketplace, April 2026.* **draw\.io** by Seibert Media is the clear market leader with 9,602 installs and a 3.8-star rating. It's been around for years, supports Cloud/DC/Server, and is Cloud Fortified. But it's a full-featured diagramming suite — heavier than what many teams need. **Mermaid Charts & Diagrams** by weweave is the only other Mermaid-based option. 544 installs, Cloud Fortified, with a 4.0-star rating from a single review. The Excalidraw space is small — Fulstech has 111 installs and Simplify has 40. Neither offers a comprehensive shape library or Mermaid integration alongside freeform drawing. *** ## Feature Comparison: Text-Based Diagram Apps[​](#feature-comparison-text-based-diagram-apps "Direct link to Feature Comparison: Text-Based Diagram Apps") For teams that prefer Mermaid-style text diagrams: | Feature | Mermaid+ (NGPILOT) | Mermaid Charts (weweave) | draw\.io (Seibert) | | ----------------------- | --------------------------------------------- | ------------------------ | ------------------ | | **Diagram engine** | Mermaid.js | Mermaid.js | Custom (draw\.io) | | **Diagram types** | 29 | 15+ | Full drawing | | **Live preview** | Yes | Yes | Yes | | **Quick templates** | 29 (one per type) | Limited | Templates | | **Syntax guide** | Built-in (29 examples) | No | No | | **Custom colors** | 5 (Node, Text, Border, Line, Bg) | Limited | Full | | **Font selection** | 5 families | Limited | Full | | **Theme support** | 4 themes (Default, Dark, Forest, Neutral) | Limited | Full | | **Dark mode** | Auto-adapts to Jira | No | Yes | | **Output size control** | 4 sizes | No | Yes | | **Cached rendering** | SVG cache, library loaded only during editing | No | No | | **Cloud Fortified** | No | Yes | Yes | ### Where Mermaid+ Stands Out[​](#where-mermaid-stands-out "Direct link to Where Mermaid+ Stands Out") **Most diagram types** — 30 Mermaid diagram types including flowchart, sequence, class, state, ER, C4 architecture, Gantt, mindmap, timeline, Git graph, pie chart, radar, Sankey, Kanban, and more. More than any other Mermaid-based Jira app. **Built-in syntax guide** — Click the **?** button to browse all 30 diagram types with descriptions and code examples. Insert any template directly into the editor. No need to look up Mermaid syntax externally. **Performance-first** — Diagrams render from cached SVG on issue load. The Mermaid.js library is only loaded during editing, not when viewing issues. Your Jira stays fast even with diagrams on every issue. **Dark mode that works** — Diagrams automatically adapt to Jira's dark/light theme. Text and background colors adjust for readability without manual configuration. **Full customization** — Five color pickers (node, text, border, line, background), five font families, four output sizes, and four Mermaid themes. ### Where We Could Improve[​](#where-we-could-improve "Direct link to Where We Could Improve") * **Not yet Cloud Fortified** — weweave's app and draw\.io have completed Atlassian's Cloud Fortified program. We're working toward this. * **New app** — Launching in 2026, no install base or review history yet. * **Text-only** — Mermaid is powerful but requires learning syntax. If your team prefers drawing visually, our Excalidraw app is the better fit. *** ## Feature Comparison: Freeform Drawing and Whiteboard Apps[​](#feature-comparison-freeform-drawing-and-whiteboard-apps "Direct link to Feature Comparison: Freeform Drawing and Whiteboard Apps") For teams that prefer visual drawing: | Feature | Excalidraw + Whiteboards (NGPILOT) | Excalidraw Whiteboard (Fulstech) | Excalidraw Mermaid (Simplify) | draw\.io (Seibert) | Draw UI (DevSamurai) | | ---------------------------- | ---------------------------------- | -------------------------------- | ----------------------------- | ------------------- | -------------------- | | **Drawing engine** | Excalidraw | Excalidraw | Excalidraw | draw\.io | Custom | | **Built-in shape libraries** | 229 | Limited | Limited | Extensive | 300+ UI components | | **Mermaid support** | Yes — generate diagrams from text | No | Yes | No | No | | **Hand-drawn style** | Yes | Yes | Yes | No (clean/polished) | No | | **Freehand drawing** | Yes | Yes | Yes | Yes | Limited | | **AWS/Azure/GCP shapes** | Yes | No | No | Yes | No | | **UML shapes** | Yes | No | No | Yes | Limited | | **Wireframe components** | Yes | No | No | Yes | Yes (300+) | | **Diagram saved as** | Issue attachment | Issue attachment | Issue attachment | Issue attachment | Issue attachment | | **Preview in issue panel** | Yes | Yes | Yes | Yes | Yes | | **Hosting** | Cloud | Cloud | Cloud | Cloud + DC + Server | Cloud | ### Where Excalidraw Diagrams + Whiteboards Stands Out[​](#where-excalidraw-diagrams--whiteboards-stands-out "Direct link to Where Excalidraw Diagrams + Whiteboards Stands Out") **229 bundled shape libraries** — The largest shape library collection of any Excalidraw-based Jira app. AWS, Azure, GCP, UML, networking, database, and more — all bundled and available offline. No internet connection needed for shapes. **Mermaid + freeform in one app** — Type a Mermaid definition and get a visual diagram on the canvas. Then move, resize, and style it alongside your freehand drawings. No other Excalidraw app offers this combination. **Hand-drawn aesthetic** — The Excalidraw style keeps diagrams looking approachable and focused on ideas. Great for architecture reviews, brainstorming, and early-stage design where polish isn't the priority. **Zero setup** — All 229 libraries are bundled with the app. No downloads, no internet required. Open the editor and start drawing. ### Where We Could Improve[​](#where-we-could-improve-1 "Direct link to Where We Could Improve") * **New app** — Launching in 2026 with no marketplace history yet. * **No Cloud Fortified status** — Still working through Atlassian's compliance program. * **No DC/Server support** — Cloud-only for now. draw\.io is the best option if you need Data Center or Server hosting. * **Not a full diagramming suite** — If you need the polished, presentation-ready diagrams that draw\.io produces, the hand-drawn Excalidraw style may not match. This is a deliberate tradeoff — speed and simplicity over polish. *** ## Honest Comparison: NGPILOT vs draw\.io (Market Leader)[​](#honest-comparison-ngpilot-vs-drawio-market-leader "Direct link to Honest Comparison: NGPILOT vs draw.io (Market Leader)") draw\.io dominates with 9,602 installs. Here's how our approach differs: | | draw\.io (Seibert) | Mermaid+ + Excalidraw (NGPILOT) | | ------------------- | -------------------------------------- | ------------------------------------------------- | | **Approach** | One full-featured diagramming suite | Two focused apps — text-based and freeform | | **Installs** | 9,602 | Coming soon | | **Rating** | 3.8/5 (349 reviews) | — | | **Hosting** | Cloud + DC + Server | Cloud | | **Cloud Fortified** | Yes | Not yet | | **Learning curve** | Medium — full editor to learn | Low — Mermaid syntax OR freeform drawing | | **Shape libraries** | Extensive built-in | 229 (Excalidraw) + 30 diagram templates (Mermaid) | | **Performance** | Full editor loads on each issue | Mermaid+: cached SVG, library only during editing | | **Best for** | Teams that want one app for everything | Teams that want fast, focused diagramming | The tradeoff is clear: draw\.io is the safe, established choice with the most features and broadest hosting support. Our apps are for teams that want something lighter and more focused — Mermaid for developers who think in code, Excalidraw for teams that want fast whiteboarding without the overhead of a full diagramming suite. Deciding the same question inside Confluence rather than Jira? See our [Excalidraw vs draw.io for Confluence comparison](/blog/faq-excalidraw-vs-drawio-confluence.md) — it covers whiteboarding vs structured diagramming, Mermaid support, and pricing side by side. *** ## Which App Do You Need?[​](#which-app-do-you-need "Direct link to Which App Do You Need?") | You need... | Use this | | ------------------------------------------- | ---------------------------------------------- | | Text-based diagrams from Mermaid syntax | **Mermaid+ Diagrams for Jira** | | Freeform drawing and whiteboarding | **Excalidraw Diagrams + Whiteboards for Jira** | | Both — code diagrams AND visual drawing | **Both apps together** | | Full-featured diagramming suite with polish | draw\.io by Seibert Media | | Wireframes and mockups specifically | Draw UI by DevSamurai | *** ## Related Posts[​](#related-posts "Direct link to Related Posts") * [How to Create Mermaid Diagrams in Confluence — Flowcharts, Sequence Diagrams & More](/blog/create-mermaid-diagrams-in-confluence.md) * [How to Use Excalidraw in Confluence for Whiteboarding and Diagrams](/blog/use-excalidraw-in-confluence-whiteboard-diagrams.md) ## Get Started[​](#get-started "Direct link to Get Started") * **Mermaid+ Diagrams for Jira** — Coming soon to the Atlassian Marketplace. [Read the docs](/docs/Mermaid-plus-Diagrams-for-Jira/usage.md) * **Excalidraw Diagrams + Whiteboards for Jira** — Coming soon to the Atlassian Marketplace. [Read the docs](/docs/Excalidraw-Diagrams-plus-Whiteboards-for-Jira/usage.md) Have questions or want early access? Reach out to us at — we'd love to hear from you. ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira-diagrams](/blog/tags/jira-diagrams.md) * [mermaid](/blog/tags/mermaid.md) * [excalidraw](/blog/tags/excalidraw.md) * [whiteboard](/blog/tags/whiteboard.md) * [flowchart](/blog/tags/flowchart.md) * [architecture-diagram](/blog/tags/architecture-diagram.md) * [jira-plugin](/blog/tags/jira-plugin.md) --- # Jira Export Limit: How to Export More Than 1,000 Issues (2026) September 2, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Jira Cloud's native export stops at 1,000 issues per export and only includes columns visible in the issue navigator. To export more: split your filter into JQL batches, use the REST API, or install [Simple Bulk Issues Excel CSV Export](https://marketplace.atlassian.com/apps/3818473739/simple-bulk-issues-excel-csv-export-for-jira?utm_source=ngpilot.com\&utm_medium=blog), which exports up to 5,000 issues per run in CSV, XLS, or XLSX — and tells you plainly when a result set was truncated. If you have ever exported a project for reporting, an audit, or a migration, you have probably run into Jira Cloud's export limit without being warned first: the export finishes, the file looks complete, and the row count quietly stops at 1,000. This article explains where that limit comes from, then compares the three practical ways to export larger issue sets in 2026. ## Why native Jira exports stop at 1,000 issues[​](#why-native-jira-exports-stop-at-1000-issues "Direct link to Why native Jira exports stop at 1,000 issues") Jira Cloud's issue navigator export is designed for quick, ad-hoc handoffs, not bulk data extraction. Atlassian documents the constraint: a native export includes at most 1,000 issues, and only the fields currently shown as columns in your navigator. Two consequences follow from how it is built: 1. **Column selection is indirect.** You have to add each field you want as a navigator column first — including every custom field. 2. **The cap is silent.** The exported file gives no indication that rows beyond 1,000 exist, so a truncated export looks exactly like a complete one. None of this is a bug — it is a scope decision. But for reporting, backup, or migration work, 1,000 rows is often a fraction of the real result set. ## Three ways to export more than 1,000 issues[​](#three-ways-to-export-more-than-1000-issues "Direct link to Three ways to export more than 1,000 issues") | Approach | Max issues | Formats | Custom fields | Effort | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | -------------- | --------------------- | ------------------ | | Native export + JQL splitting | 1,000 per batch | CSV | Add columns manually | Manual, repetitive | | [Simple Bulk Issues Excel CSV Export](https://marketplace.atlassian.com/apps/3818473739/simple-bulk-issues-excel-csv-export-for-jira?utm_source=ngpilot.com\&utm_medium=blog) | 5,000 per export | CSV, XLS, XLSX | Pick from a checklist | One-time setup | | Jira REST API (paginated search) | Effectively unbounded | JSON | Explicit field lists | Scripting required | ### Option 1: Split the export with JQL[​](#option-1-split-the-export-with-jql "Direct link to Option 1: Split the export with JQL") The zero-cost approach: divide a big result set into batches that each stay under 1,000 issues, then merge the files yourself. ``` project = ENG AND updated >= -30d project = ENG AND updated < -30d AND updated >= -60d ``` Works, but each batch means re-adding columns, re-exporting, and stitching CSVs together — and nothing tells you whether a batch itself overflowed. ### Option 2: A Marketplace export app[​](#option-2-a-marketplace-export-app "Direct link to Option 2: A Marketplace export app") [Simple Bulk Issues Excel CSV Export](https://marketplace.atlassian.com/apps/3818473739/simple-bulk-issues-excel-csv-export-for-jira?utm_source=ngpilot.com\&utm_medium=blog) runs from the issue navigator on whatever JQL you already have, and as of the September 2026 release: * **Exports up to 5,000 issues per run** (previously 1,000) * **Truncation is never silent** — if a filter matches more than 5,000 issues, the result message tells you exactly how many rows you got and suggests narrowing the filter * **Field selection is a checklist** — system fields, custom fields, and now the **Parent field**, exported as the parent issue key (for example `PROJ-123`) for subtask and hierarchy reporting * **CSV, XLS, and XLSX output** in a single download, with UTF-8 encoding handled correctly The full walkthrough — including JQL examples and field-selection tips — is in our [Jira to Excel export guide](/blog/export-jira-issues-to-excel.md). ### Option 3: The REST API[​](#option-3-the-rest-api "Direct link to Option 3: The REST API") For recurring, fully automated pipelines, the [enhanced search REST endpoint](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-search/) paginates arbitrarily large result sets with `nextPageToken`. It serves up to 5,000 issues per page, and it is the same endpoint Simple Bulk Issues uses under the hood. Choose this when exports need to run unattended; choose the app when a human needs a file now. ## What if your result set is bigger than 5,000?[​](#what-if-your-result-set-is-bigger-than-5000 "Direct link to What if your result set is bigger than 5,000?") No single export tool removes the ceiling entirely — at some point, splitting is the right answer. The difference is knowing where the edge is: * **Native export:** cuts at 1,000 rows without telling you * **Simple Bulk Issues:** cuts at 5,000 rows and tells you it did * **REST API:** no practical ceiling, but you own the scripting A filter that matches 12,000 issues exports cleanly as three batches — for example `created <= 2025-12-31`, the following six months, and `created > 2026-06-30`. ## Frequently Asked Questions[​](#frequently-asked-questions "Direct link to Frequently Asked Questions") ### What is the export limit in Jira Cloud?[​](#what-is-the-export-limit-in-jira-cloud "Direct link to What is the export limit in Jira Cloud?") Jira Cloud's native export from the issue navigator caps at 1,000 issues per export, and only includes the columns currently visible in your navigator. There is no native XLSX option — just CSV with all fields or CSV with current fields. ### How do I export more than 1,000 issues from Jira?[​](#how-do-i-export-more-than-1000-issues-from-jira "Direct link to How do I export more than 1,000 issues from Jira?") Three options: split the filter into JQL date or project ranges and export in batches; use a Marketplace app like Simple Bulk Issues Excel CSV Export (up to 5,000 issues per run in CSV, XLS, or XLSX); or script the paginated REST API for automated pipelines. ### How many issues can Simple Bulk Issues Export handle?[​](#how-many-issues-can-simple-bulk-issues-export-handle "Direct link to How many issues can Simple Bulk Issues Export handle?") Up to 5,000 issues per export as of September 2026 (raised from 1,000). If a filter matches more than 5,000, the app says so in the result message instead of silently cutting rows. ### Does the export include the Parent field?[​](#does-the-export-include-the-parent-field "Direct link to Does the export include the Parent field?") Yes. Simple Bulk Issues exports the Parent field as the parent issue key (for example PROJ-123), which keeps subtask and parent-child hierarchies intact in the exported file. *** More export troubleshooting — encoding, field mismatches, timeouts — is covered in our [Jira export FAQ](/blog/faq-exporting-jira-issues.md). ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [export](/blog/tags/export.md) * [excel](/blog/tags/excel.md) * [csv](/blog/tags/csv.md) * [jira-cloud](/blog/tags/jira-cloud.md) * [reporting](/blog/tags/reporting.md) --- # How to See Who Changed What in Jira — Field-Level Issue History September 23, 2026 · 5 min read [NGPilot](https://ngpilot.com) Every Jira issue keeps a diary. Status flips, priority bumps, reassignments, edited specs — Jira writes all of it down. The problem is reading it back: the built-in history turns a description edit into one unhelpful line, and "who changed this?" across forty issues becomes forty clicks or a REST script. This guide covers three ways to actually read Jira issue history, from the free built-in tab to field-level diffs and a cross-issue CSV report. **Quick answer:** Jira's History tab shows every change but collapses long-text edits to "Description updated" and only covers one issue at a time. For field-level answers — what exactly changed, across many issues, exportable for audits — install [Issue History Agent for Jira](https://marketplace.atlassian.com/apps/675742747/): a panel on every issue with word-level diffs, a JQL-driven multi-issue report, CSV export, and a Rovo agent that answers "what changed?" in plain language. Free for up to 10 users. ## Method 1 — the Built-in History Tab (Free, Shallow)[​](#method-1--the-built-in-history-tab-free-shallow "Direct link to Method 1 — the Built-in History Tab (Free, Shallow)") Open any issue, scroll to the **History** tab. Every change is there: who, when, and old → new values for simple fields like status, assignee, and priority. **Good for:** "when did this move to Done?" on a single issue with a short history. **What's missing:** long text fields are the blind spot — an edit that deletes three acceptance criteria shows as *Description updated*, with no before, no after, and no way to diff without leaving Jira. And the view is strictly per issue: there is no search across histories, no filter by field, and no export. The moment the question spans issues ("everything that offboarded admin touched"), the History tab becomes a manual tour. ## Method 2 — the REST Changelog API (Complete, Scripted)[​](#method-2--the-rest-changelog-api-complete-scripted "Direct link to Method 2 — the REST Changelog API (Complete, Scripted)") Jira's REST API exposes the full changelog, including values the UI hides: ``` curl -u email@example.com:API_TOKEN \ "https://your-site.atlassian.net/rest/api/3/issue/PROJ-42/changelog" ``` Each entry carries `items[]` with `field`, `fromString`, `toString`, author, and timestamp — the raw material for a complete answer. **Good for:** admins building a one-off audit extraction, or wiring change feeds into other tooling. **What's missing:** it is a script you now own — pagination, rate limits, and value formatting included. Every audit request becomes a rerun, and the output still needs a diff view for long text before anyone can read it. Powerful, but nobody wants this as their day-to-day interface. JQL offers partial help without any scripting: the `CHANGED` and `WAS` operators work on a fixed set of fields (`status`, `assignee`, `priority`, `fix version`, `sprint`): ``` status CHANGED AFTER -7d assignee CHANGED BY "former.admin@company.com" ``` **What's missing:** the field list is fixed — no JQL ever answers "whose description changed last month?", and the operators return issues, not the change values themselves. ## Method 3 — a History Panel with Diffs, Reports, and a Rovo Agent (Recommended)[​](#method-3--a-history-panel-with-diffs-reports-and-a-rovo-agent-recommended "Direct link to Method 3 — a History Panel with Diffs, Reports, and a Rovo Agent (Recommended)") [Issue History Agent for Jira](https://marketplace.atlassian.com/apps/675742747/) turns the changelog into something readable at three scopes: 1. **One issue** — a panel lists every field change newest-first: author, time, and exact before → after values, with paging for long histories. 2. **One edit** — long text changes get a focused diff with word-level highlighting, so "Description updated" becomes the three words that actually moved. 3. **A whole issue set** — the global report runs over any JQL filter, with date and field filters, and exports to a formula-safe CSV that spreadsheets cannot corrupt. Because the report is JQL-driven, audit-style questions are saved filters rather than projects: ``` project = FIN AND updated >= -30d # everything financial that moved this month assignee CHANGED BY "former.admin@company.com" # bulk-edit fallout, one table ``` There is also a fourth door: in **Rovo chat**, the Issue History agent answers plain-language questions — *"what changed recently on this issue?"*, *"who last edited the acceptance criteria?"* — from live Jira data, with sources. Every query runs as the asking user, so the agent only ever surfaces history the asker could already read, and the app holds a read-only scope and stores nothing. ## Find the Answer, Then Keep It[​](#find-the-answer-then-keep-it "Direct link to Find the Answer, Then Keep It") The CSV export is where history stops being a curiosity and becomes a record: issue key, field, author, timestamp, old value, new value — one row per change, ready for an audit pack, a change advisory board, or a post-incident review. Filter the report before exporting ("status changes on these 40 issues in the last 30 days") or the evidence becomes homework. ## Which Method Should You Use?[​](#which-method-should-you-use "Direct link to Which Method Should You Use?") | Need | Use | | ------------------------------------------------------------------- | ---------------------------- | | "When did this issue move to Done?" | Built-in History tab | | A one-off complete extraction for scripting | REST changelog API | | Field-level diffs, cross-issue reports, CSV, plain-language answers | Issue History Agent for Jira | For the third row — compliance evidence, dispute resolution, release retrospectives, and the everyday "who changed this?" — the setup cost is one install, and it pays back the first time a diff answers a question a changelog line couldn't. Install [Issue History Agent for Jira](https://marketplace.atlassian.com/apps/675742747/) and make the history readable where the work happens. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Track Issue History in Jira](/solutions/track-issue-history-in-jira.md) — the scenario guide: audit questions, diff reading, and permission-safe history * [How to View JSON in Jira](/blog/jira-json-viewer.md) — read the structured data other apps store on your issues * [Issue History Agent for Jira](/apps/issue-history-agent-for-jira.md) — full documentation: the panel, the report, CSV export, and the Rovo agent ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [issue-history](/blog/tags/issue-history.md) * [audit](/blog/tags/audit.md) * [changelog](/blog/tags/changelog.md) * [how-to](/blog/tags/how-to.md) * [compliance](/blog/tags/compliance.md) --- # Jira issue templates: best practices for consistent ticket creation April 24, 2026 · 3 min read [NGPilot](https://ngpilot.com) Inconsistent Jira tickets waste time during grooming, sprint planning, and reporting. Issue templates solve this by standardizing the fields, descriptions, and checklists that appear on every new ticket. This guide covers how to set up and get the most from [Modern Issue Templates for Jira](/docs/Modern-Issue-Templates-for-Jira/user-docs.md). ## Why use issue templates?[​](#why-use-issue-templates "Direct link to Why use issue templates?") * **Faster ticket creation**: Pre-filled fields mean less typing * **Consistent descriptions**: Every bug report, feature request, or incident follows the same structure * **Better reporting**: Standardized fields make JQL queries and dashboards more reliable * **Onboarding**: New team members see the expected format immediately ## Setting up your first template[​](#setting-up-your-first-template "Direct link to Setting up your first template") 1. Install [Modern Issue Templates for Jira](/docs/Modern-Issue-Templates-for-Jira/user-docs.md) from the Atlassian Marketplace 2. Create a new template and choose the issue type (Bug, Story, Task, etc.) 3. Pre-fill the fields you want: Summary format, Description, Priority, Labels, Components 4. Add rich formatting to the description — checklists, headers, code blocks ## Template design tips[​](#template-design-tips "Direct link to Template design tips") ### Bug report template[​](#bug-report-template "Direct link to Bug report template") Include these sections in every bug description: ``` ## Steps to reproduce 1. 2. 3. ## Expected behavior ## Actual behavior ## Environment ## Attachments / screenshots ``` ### Feature request template[​](#feature-request-template "Direct link to Feature request template") ``` ## Problem statement ## Proposed solution ## Acceptance criteria - [ ] - [ ] ## Out of scope ``` ### Incident template[​](#incident-template "Direct link to Incident template") ``` ## Incident summary ## Impact ## Timeline - Detected: - Acknowledged: - Resolved: ## Root cause ## Action items - [ ] ``` ## Auto-apply rules[​](#auto-apply-rules "Direct link to Auto-apply rules") Modern Issue Templates supports auto-apply rules that automatically apply a template when a user creates an issue in a specific project or issue type. This eliminates the need to manually select a template each time. **Recommended auto-apply setup:** * Map each issue type to its corresponding template * Set project-specific overrides when teams have different standards * Test with a single project before rolling out org-wide ## Import templates from GitHub[​](#import-templates-from-github "Direct link to Import templates from GitHub") If your team already uses GitHub issue templates (`.github/ISSUE_TEMPLATE/`), you can import them directly into Modern Issue Templates. This keeps your GitHub and Jira workflows aligned. ## Related resources[​](#related-resources "Direct link to Related resources") * [Modern Issue Templates for Jira — documentation](/apps/modern-issue-templates-for-jira.md) * [Issue Templates for Jira — Which Template App?](/blog/jira-issue-templates-comparison.md) — how the app compares against the other marketplace options * [Jira Issue Templates FAQ: Auto-Apply, Variables & Automation](/blog/faq-jira-issue-templates-automation.md) — common questions about variables, import, and automation * [Modern Announcement Banner for Jira](/apps/modern-announcement-banner-for-jira.md) — announce template changes to your team * [Simple Bulk Issues Excel CSV Export](/apps/simple-bulk-issues-excel-csv-export-for-jira.md) — export standardized issues for reporting * [Bulk operations in Jira FAQ](/blog/faq-bulk-operations-jira.md) Try Modern Issue Templates for Jira Create issues from reusable templates with variables, GitHub import, and auto-apply — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/2564635381/modern-issue-templates-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-issue-templates-for-jira) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [templates](/blog/tags/templates.md) * [best-practices](/blog/tags/best-practices.md) * [how-to](/blog/tags/how-to.md) --- # Issue Templates for Jira — Templating.app & Top Apps Compared April 18, 2026 · 8 min read [NGPilot](https://ngpilot.com) Every team has recurring issue types — bug reports with specific fields, user stories with acceptance criteria, onboarding checklists with sub-tasks. Creating each one from scratch wastes time and introduces inconsistency. Jira has no built-in issue templates. Over a dozen marketplace apps try to solve this. The market is fragmented but maturing — the leader has roughly 4,900 installs, and several apps now carry Cloud Fortified status. We built **Modern Issue Templates for Jira** to bring template creation, GitHub import, auto-application, and fill-in variables to Jira issues. In this post we compare it against the alternatives. ## Why Issue Templates Matter[​](#why-issue-templates-matter "Direct link to Why Issue Templates Matter") Without templates, your team faces two problems: * **Inconsistency** — One developer writes a detailed bug report with steps to reproduce. Another writes "it's broken." Same issue type, wildly different quality. * **Wasted time** — Your PM manually adds the same sub-task structure to every epic. Your support team re-types the same diagnostic checklist on every ticket. Issue templates solve both. Pre-fill the summary, description, sub-tasks, and fields so every issue starts with the right structure. Your team fills in the specifics instead of the boilerplate. ## What's Available on the Marketplace[​](#whats-available-on-the-marketplace "Direct link to What's Available on the Marketplace") The Jira template market is crowded but no single app dominates: | App | Vendor | Installs | Rating | Last Updated | Hosting | Cloud Fortified | | ---------------------------------------- | -------------- | -------- | ------------------- | ------------ | ----------------- | --------------- | | Issue Templates for Jira | Deviniti | 4,873 | 3.9/5 (125 reviews) | Jul 2026 | Cloud, DC | Yes | | Default Values for 'Create Issue' screen | Big Fig Tree | 2,527 | 4.1/5 (26 reviews) | Jun 2026 | Cloud | No | | Issue Templates Agent | Appsvio | 2,253 | 4.7/5 (49 reviews) | 2026 | Cloud | Yes | | Easy Issue Templates | AppLiger | 2,111 | 4.4/5 (79 reviews) | Jul 2026 | Cloud | Yes | | Issue Templates Pro | Narva Software | 2,103 | 4.2/5 (53 reviews) | Jul 2026 | Cloud | Yes | | Templating.app | Seibert | 1,167 | 4.8/5 (76 reviews) | 2026 | Cloud | Yes | | Smart Issue Templates | AppsDelivered | 394 | 4.9/5 (56 reviews) | 2026 | Cloud | No | | **Modern Issue Templates for Jira** | **NGPILOT** | **3** | **New (0 reviews)** | **Jul 2026** | **Cloud (Forge)** | **No** | *Data from Atlassian Marketplace, August 2026. Installs drift between crawls; treat counts as approximate.* **Deviniti's Issue Templates** leads with \~4,900 installs but carries the weakest rating in the top five (3.9★) — a familiar pattern in mature apps, where features shipped faster than the UX could absorb them. "Too complex to set up" recurs in the reviews. **Templating.app by Seibert** and **Smart Issue Templates by AppsDelivered** are the highest-rated apps in the category. **Issue Templates Agent by Appsvio** (4.7★) offers hierarchy templates plus Government Cloud support. **Easy Issue Templates by AppLiger** (4.4★) is a solid, actively developed mid-market option. **Narva Software's Issue Templates Pro** (4.2★) focuses on summary and description templates but doesn't offer full issue-structure templating. Unlike a year ago, **Cloud Fortified is no longer a gap in this category** — Deviniti, Appsvio, AppLiger, Narva, and Seibert all have it. We're working toward the same trust signals. ## Feature Comparison[​](#feature-comparison "Direct link to Feature Comparison") We compared the top apps that are actively maintained (updated in 2026): | Feature | Modern Issue Templates (NGPILOT) | Issue Templates (Deviniti) | Templating.app (Seibert) | Issue Templates Agent (Appsvio) | Easy Issue Templates (AppLiger) | Issue Templates Pro (Narva) | | --------------------------------------------- | --------------------------------------------------------- | -------------------------- | ------------------------ | ------------------------------- | ------------------------------- | --------------------------- | | **Create from scratch** | Yes | Yes | Yes | Yes | Yes | Yes | | **Import from file** | JSON, Markdown | No | No | Import/export | No | No | | **Import from GitHub** | Files + Gists | No | No | No | No | No | | **YAML frontmatter** | Yes (auto-extracted) | No | No | No | No | No | | **Assign to projects** | Yes | Yes | Yes | Yes | Yes | Yes | | **Assign to issue types** | Yes | Yes | Yes | Yes | Yes | Yes | | **Auto-apply on create** | Yes | Yes | Yes | Yes | Yes | Yes | | **Conflict detection** | Yes | No | No | No | No | No | | **Application log** | Yes (7-day) | No | No | No | No | No | | **Inline editing** | Yes | No | No | No | No | No | | **Hierarchy templates (Epic→Story→Sub-task)** | No | Yes | Yes | Yes | Yes | No | | **Markdown formatting** | Yes (auto-convert to rich text) | No | No | No | No | No | | **Variables** | Yes (`{{currentUser}}`, `{{today+7d}}`, `{{projectKey}}`) | Yes | Yes | Yes | Yes | Yes | | **Automation / API integration** | No | Yes | Yes | Yes | Yes | Yes | | **Forge-native (no Connect)** | Yes | No (hybrid) | No | Yes | Yes | Yes | | **ISO 27001 / SOC 2** | No | No | ISO 27001 | No | SOC 2 | SOC 2 | | **Cloud Fortified** | No | Yes | Yes | Yes | Yes | Yes | | **Actively maintained** | Jul 2026 (v2.8.0) | Jul 2026 | 2026 | 2026 | Jul 2026 | Jul 2026 | ### Where Modern Issue Templates Stands Out[​](#where-modern-issue-templates-stands-out "Direct link to Where Modern Issue Templates Stands Out") **Import from GitHub** — The only app that imports templates directly from GitHub repositories and Gists. Store your templates in version control, import them into Jira, and keep them in sync. Automatically extracts YAML frontmatter for structured metadata. **Multi-format file import** — Import templates from JSON or Markdown files. This is essential for teams migrating from other tools or maintaining a template library outside Jira. **Markdown to rich text** — Write templates in Markdown with YAML frontmatter, and the app converts them to Confluence-style rich text. Developers already write in Markdown — no need to learn a new editor. **Conflict-aware assignment** — Jira's UI Modifications API registers one context per project × issue-type pair. When you assign a template to a context another template already owns, a conflict dialog lists the clash before the prior template is disabled — no more silent "my template stopped working." **7-day application log** — Every time a template is applied, it's logged for a week, so you can see what fired, where, and when. **Fill-in variables with inline validation** — `{{currentUser}}`, `{{projectKey}}`, `{{today+7d}}` and friends. Typos get a red wavy underline with a "Did you mean?" hint before you ever save. **Inline editing** — Quick-edit template content directly in the list view. No need to open a separate editor for small changes. ### Where We Could Improve[​](#where-we-could-improve "Direct link to Where We Could Improve") We're early — a few installs and zero reviews against a leader with \~4,900 installs and years of market presence. Honest gaps: * **No hierarchy templates** — Deviniti, Appsvio, and AppLiger can re-create an Epic → Story → Sub-task tree from one template. We're issue-level only today; this is on the roadmap. * **No automation / API integration** — Several competitors expose templates to Jira Automation rules and external scripts. Templates currently fire only on the standard create-issue screen. * **No Cloud Fortified status** — We haven't been on the Marketplace long enough to apply. It's a real trust signal and a goal, not a claim. * **No ISO 27001 / SOC 2 certification yet** — Seibert and AppLiger have these. We'll pursue them as the product matures. * **No AI features** — Smart Issue Templates by AppsDelivered offers AI-powered hierarchy creation. We focus on developer-friendly workflows (GitHub import, Markdown) instead. ## Honest Comparison: NGPILOT vs Deviniti (Market Leader)[​](#honest-comparison-ngpilot-vs-deviniti-market-leader "Direct link to Honest Comparison: NGPILOT vs Deviniti (Market Leader)") Deviniti's Issue Templates for Jira has the most installs and the deepest feature set. Here's how we differ: | | Issue Templates (Deviniti) | Modern Issue Templates (NGPILOT) | | ----------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------ | | **Installs** | 4,873 | 3 | | **Rating** | 3.9/5 (125 reviews) | New (0 reviews) | | **Create from scratch** | Yes | Yes | | **File import** | No | JSON, Markdown | | **GitHub import** | No | Files + Gists | | **Hierarchy templates** | Yes | No | | **Variables** | Yes | Yes | | **Conflict detection** | No | Yes | | **Application log** | No | Yes (7-day) | | **Automation / API** | Yes | No | | **Inline editing** | No | Yes | | **Markdown support** | No | Yes (auto-convert) | | **Cloud Fortified** | Yes | No | | **Best for** | Teams needing hierarchy templates, automation, and enterprise governance | Developer teams using Git and Markdown who want conflict-safe auto-apply | Deviniti's app has more features for teams that need hierarchy templates, automation triggers, and project-level templating. Our app is for developer teams that already store templates in Git, want conflict-free auto-apply, and want to import templates into Jira without manual re-entry. ## Which App Do You Need?[​](#which-app-do-you-need "Direct link to Which App Do You Need?") | You need... | Use this | | ------------------------------------------------------------------- | ----------------------------------- | | The most-established option with hierarchy templates and automation | Issue Templates by Deviniti | | Full project/issue/board templates in one app | Templating.app by Seibert | | Simple default values on the create screen | Default Values by Big Fig Tree | | Hierarchy templates with a strong rating | Issue Templates Agent by Appsvio | | Summary and description templates with minimal setup | Issue Templates Pro by Narva | | Import templates from GitHub or Markdown files | **Modern Issue Templates for Jira** | | Conflict-safe auto-apply with a full application log | **Modern Issue Templates for Jira** | | Developer-friendly template workflow with Git integration | **Modern Issue Templates for Jira** | ## Related Posts[​](#related-posts "Direct link to Related Posts") * [How to Create Jira Issue Templates](/blog/how-to-create-jira-issue-templates.md) * [Jira Issue Templates: Best Practices](/blog/jira-issue-templates-best-practices.md) * [Diagram Apps for Jira — Which Diagramming Tool Should Your Team Use?](/blog/jira-diagram-apps-comparison.md) ## Get Started[​](#get-started "Direct link to Get Started") **Modern Issue Templates for Jira** is live on the Atlassian Marketplace — free for up to 10 users. [Install it now](https://marketplace.atlassian.com/apps/2564635381/modern-issue-templates-for-jira?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=issue-templates-comparison), or [read the docs](/docs/Modern-Issue-Templates-for-Jira/user-docs.md) first. Questions or feedback? Reach out to us at — we'd love to hear from you. Try Modern Issue Templates for Jira Create issues from reusable templates with variables, GitHub import, and auto-apply — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/2564635381/modern-issue-templates-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-issue-templates-for-jira) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [issue-templates](/blog/tags/issue-templates.md) * [jira-templates](/blog/tags/jira-templates.md) * [jira-automation](/blog/tags/jira-automation.md) * [project-templates](/blog/tags/project-templates.md) * [bug-template](/blog/tags/bug-template.md) * [user-story-template](/blog/tags/user-story-template.md) --- # Jira JQL Cheat Sheet: 20 Queries Every Team Needs July 29, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer JQL (Jira Query Language) lets you search for issues using fields, operators, and values. Master 20 essential queries to find issues fast, track sprint health, and build custom dashboards. What you'll learn 1. The JQL syntax basics that power every query 2. 20 copy-paste queries for common searches 3. How to use JQL functions for dynamic, date-aware filters 4. How to save and share filters for dashboards Jira's search is powerful, but most teams only scratch the surface. They type a few keywords into the search bar, get overwhelmed by results, and give up. JQL — Jira Query Language — is the key to unlocking precise, repeatable searches that find exactly what you need. This cheat sheet covers 20 essential JQL queries, from basic field searches to advanced functions. Each query is copy-paste ready. ## JQL Syntax Basics[​](#jql-syntax-basics "Direct link to JQL Syntax Basics") Every JQL query follows this structure: ``` field operator value [AND|OR field operator value ...] ``` **Fields** are properties of issues: * `status` — current workflow state * `assignee` — who it is assigned to * `priority` — High, Medium, Low, etc. * `created` — when the issue was created * `updated` — when the issue was last modified * `summary` — the issue title * `text` — full-text search across all fields **Operators** compare fields to values: * `=` / `!=` — equals / not equals * `>` / `<` / `>=` / `<=` — greater/less than (for dates and numbers) * `~` / `!~` — contains / does not contain (for text fields) * `in` — matches any value in a list * `is` — used with EMPTY **Values** are the data you are searching for: * Strings: `"in progress"` (quoted if multi-word) * Dates: `2026-07-01` or relative: `-7d` (7 days ago) * Functions: `currentUser()`, `now()`, `startOfWeek()` ## 10 Essential JQL Queries[​](#10-essential-jql-queries "Direct link to 10 Essential JQL Queries") ### 1. Find all issues assigned to me[​](#1-find-all-issues-assigned-to-me "Direct link to 1. Find all issues assigned to me") ``` assignee = currentUser() ``` ### 2. Find all open issues in a project[​](#2-find-all-open-issues-in-a-project "Direct link to 2. Find all open issues in a project") ``` project = MYPROJECT AND status != Done ``` ### 3. Find issues created in the last 7 days[​](#3-find-issues-created-in-the-last-7-days "Direct link to 3. Find issues created in the last 7 days") ``` created >= -7d ``` ### 4. Find high-priority bugs[​](#4-find-high-priority-bugs "Direct link to 4. Find high-priority bugs") ``` priority = High AND issuetype = Bug ``` ### 5. Find issues updated in the last 3 days[​](#5-find-issues-updated-in-the-last-3-days "Direct link to 5. Find issues updated in the last 3 days") ``` updated >= -3d ``` ### 6. Find issues with no assignee[​](#6-find-issues-with-no-assignee "Direct link to 6. Find issues with no assignee") ``` assignee IS EMPTY AND status != Done ``` ### 7. Find issues blocked by another issue[​](#7-find-issues-blocked-by-another-issue "Direct link to 7. Find issues blocked by another issue") ``` issue in linkedIssues("BLOCKER-123", "is blocked by") ``` ### 8. Find all stories in the current sprint[​](#8-find-all-stories-in-the-current-sprint "Direct link to 8. Find all stories in the current sprint") ``` sprint in openSprints() AND issuetype = Story ``` ### 9. Find issues due this week[​](#9-find-issues-due-this-week "Direct link to 9. Find issues due this week") ``` due >= startOfWeek() AND due <= endOfWeek() ``` ### 10. Find issues you reported[​](#10-find-issues-you-reported "Direct link to 10. Find issues you reported") ``` reporter = currentUser() ``` ## 10 Advanced JQL Queries[​](#10-advanced-jql-queries "Direct link to 10 Advanced JQL Queries") ### 11. Find issues with no comments[​](#11-find-issues-with-no-comments "Direct link to 11. Find issues with no comments") ``` comment IS EMPTY AND status != Done ``` ### 12. Find issues updated by someone else recently[​](#12-find-issues-updated-by-someone-else-recently "Direct link to 12. Find issues updated by someone else recently") ``` updated >= -1d AND assignee = currentUser() AND reporter != currentUser() ``` ### 13. Find all epics with open stories[​](#13-find-all-epics-with-open-stories "Direct link to 13. Find all epics with open stories") ``` issuetype = Epic AND issueFunction in hasSubTask("status != Done") ``` ### 14. Find issues with a specific label[​](#14-find-issues-with-a-specific-label "Direct link to 14. Find issues with a specific label") ``` labels = "needs-review" ``` ### 15. Find issues created this month[​](#15-find-issues-created-this-month "Direct link to 15. Find issues created this month") ``` created >= startOfMonth() ``` ### 16. Find issues with high story points[​](#16-find-issues-with-high-story-points "Direct link to 16. Find issues with high story points") ``` cf[10002] >= 8 ``` ### 17. Find issues not updated in 14 days[​](#17-find-issues-not-updated-in-14-days "Direct link to 17. Find issues not updated in 14 days") ``` updated <= -14d AND status != Done ``` ### 18. Find all sub-tasks of a specific issue[​](#18-find-all-sub-tasks-of-a-specific-issue "Direct link to 18. Find all sub-tasks of a specific issue") ``` parent = "PROJ-123" ``` ### 19. Find issues with a specific fix version[​](#19-find-issues-with-a-specific-fix-version "Direct link to 19. Find issues with a specific fix version") ``` fixVersion = "v2.1.0" ``` ### 20. Find issues in multiple projects[​](#20-find-issues-in-multiple-projects "Direct link to 20. Find issues in multiple projects") ``` project in (PROJECT_A, PROJECT_B) AND status = "In Progress" ``` ## How to Save and Share Filters[​](#how-to-save-and-share-filters "Direct link to How to Save and Share Filters") Once you have a useful query, save it as a filter: 1. Run your JQL query in the search bar 2. Click **Save as** in the top right 3. Name the filter (e.g., "My Open Issues") 4. Choose **Private** or **Shared** visibility 5. Click **Save** **Use saved filters in:** * Dashboards (Filter Results gadget) * Boards (configure board filter) * Subscriptions (daily email of matching issues) * Quick filters on your board ## FAQ[​](#faq "Direct link to FAQ") ### What is JQL in Jira?[​](#what-is-jql-in-jira "Direct link to What is JQL in Jira?") JQL stands for Jira Query Language. It is a structured query language used to search for issues in Jira. JQL uses fields (like status, assignee, priority), operators (like =, !=, >, <), and values to build precise search queries. ### How do I find all issues assigned to me?[​](#how-do-i-find-all-issues-assigned-to-me "Direct link to How do I find all issues assigned to me?") Use the query: assignee = currentUser(). This dynamically finds all issues assigned to the currently logged-in user regardless of project or status. ### How do I search for issues created in the last 7 days?[​](#how-do-i-search-for-issues-created-in-the-last-7-days "Direct link to How do I search for issues created in the last 7 days?") Use: created >= -7d. The -7d syntax means '7 days ago from today.' You can also use -1w for one week or -1m for one month. ### Can I use JQL in Jira dashboards?[​](#can-i-use-jql-in-jira-dashboards "Direct link to Can I use JQL in Jira dashboards?") Yes. Save a JQL query as a filter, then use the filter in dashboard gadgets like Filter Results, Assigned to Me, or Two Dimensional Statistics. The gadget re-runs the query automatically. ### What is the difference between JQL and SQL?[​](#what-is-the-difference-between-jql-and-sql "Direct link to What is the difference between JQL and SQL?") JQL is specifically designed for Jira issue searching and uses a simplified syntax. SQL is a general-purpose database language. JQL uses field names and operators rather than tables and joins. ## Related guides[​](#related-guides "Direct link to Related guides") * [How to Plan Jira Sprints That Actually Work](/blog/plan-jira-sprints-that-actually-work.md) * [How to Set Up Jira Dashboards for Sprint Tracking](/blog/jira-dashboard-sprint-tracking-setup.md) * [Export Jira Issues to Excel for Stakeholder Reporting](/blog/export-jira-issues-to-excel-csv-reporting.md) * [How to Export Jira Audit Logs for Compliance](/blog/export-jira-audit-logs-compliance.md) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [jql](/blog/tags/jql.md) * [how-to](/blog/tags/how-to.md) * [queries](/blog/tags/queries.md) * [reporting](/blog/tags/reporting.md) --- # How to View JSON in Jira — Fields, Entity Properties & Pasted Payloads September 18, 2026 · 4 min read [NGPilot](https://ngpilot.com) Half the debugging in a Jira-integrated stack ends at the same place: a wall of braces. A webhook payload pasted into a comment, a config blob in a custom field, entity properties an integration app quietly wrote onto the ticket — the JSON is *there*, on the issue, but reading it means scrolling and counting brackets. Here are three ways to actually read it, from free-but-painful to a proper graph view inside Jira. **Quick answer:** Install [JSON Graph Viewer & Visualizer for Jira](https://marketplace.atlassian.com/apps/1886661294/) and open any issue — the panel finds JSON in issue fields and entity properties automatically, and a Paste JSON tab accepts any raw payload. Each source renders as an interactive node graph you can expand, collapse, pan, and zoom, with a syntax-highlighted code view alongside. ## Method 1 — Read It Raw (the Default Pain)[​](#method-1--read-it-raw-the-default-pain "Direct link to Method 1 — Read It Raw (the Default Pain)") Jira shows long field values in a plain text view. For a short config object that's fine. For a real payload it means mentally tracking nesting depth across a scrolling wall of braces — and the failure mode is silent: you miscount a level and conclude the wrong node holds the value you need. **Good for:** a one-line `{"flag": true}`. Beyond that, you're doing in your head what a tree view does on screen. ## Method 2 — Browser Dev Tools (Developer-Only, Off-Ticket)[​](#method-2--browser-dev-tools-developer-only-off-ticket "Direct link to Method 2 — Browser Dev Tools (Developer-Only, Off-Ticket)") Anyone technical can open dev tools, run a `fetch` against the REST API, and eyeball the response in the console. It works, and it's the right move when you're already mid-debug. **What's missing:** it lives outside Jira, so it only works for *you*, right now. The JSON nobody else can see is the JSON that stays misunderstood — a support engineer, PM, or teammate opening the ticket tomorrow sees nothing. And a payload that only exists in a comment thread is one careless edit away from a broken bracket. ## Method 3 — a Graph Panel on the Issue (Recommended)[​](#method-3--a-graph-panel-on-the-issue-recommended "Direct link to Method 3 — a Graph Panel on the Issue (Recommended)") [JSON Graph Viewer & Visualizer for Jira](https://marketplace.atlassian.com/apps/1886661294/) adds a panel to every issue that turns JSON into an interactive node graph. It reads JSON from three sources: 1. **Issue fields** — the panel scans for fields whose content parses as JSON (REST payloads, API responses, config blobs). One match renders immediately; several matches get a dropdown. 2. **Issue properties** — the entity properties other apps store on the issue, normally invisible in the UI, rendered as graphs. 3. **Paste JSON** — a syntax-highlighted editor that graphs what you type, live. Paste a webhook payload or API response and fold everything you don't care about into collapsed `n items` nodes. The view-mode dropdown switches between **Code** (formatted and highlighted, like your editor), **Graph** (the node diagram), or **both side by side** — read the payload above, see its shape below. Everything renders in your browser with read-only access: nothing is stored or sent anywhere else, so customer payloads stay in your Jira session. ## A Payload to Try It On[​](#a-payload-to-try-it-on "Direct link to A Payload to Try It On") Paste this into the **Paste JSON** tab — it's the shape of a typical webhook body with a nested custom field: ``` { "issue": { "key": "PROJ-142", "fields": { "summary": "Checkout API returns 500 on empty cart", "priority": { "name": "High", "id": "2" }, "labels": ["backend", "payments"], "customfield_10123": { "service": "checkout-api", "environment": "prod", "traceId": "a1b2c3", "retries": 3 } } } } ``` In graph view, collapse `fields` and the whole subtree folds into one node — expand just `customfield_10123` when the config is what you're checking. That's the whole workflow: fold what you know, open what you're verifying. ## Which Method Should You Use?[​](#which-method-should-you-use "Direct link to Which Method Should You Use?") | Need | Use | | ------------------------------------------------------------------- | ----------------------- | | Check a two-line flag | Raw field view | | One-off debug in your own browser | Dev tools + REST API | | JSON that lives on the issue and must be readable by the whole team | JSON Graph Viewer panel | The third row is the one that compounds: the payload stays attached to the issue, everyone who opens the ticket sees the same readable structure, and nobody has to count braces at 3am. Install [JSON Graph Viewer & Visualizer for Jira](https://marketplace.atlassian.com/apps/1886661294/) and open your messiest integration ticket to see the difference. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Display JSON, XML and code in Confluence](/blog/display-json-xml-code-in-confluence.md) — the same problem on the documentation side * [JSON Schema viewer for Confluence](/blog/confluence-json-schema-viewer.md) — render schema definitions on Confluence pages * [How to See Who Changed What in Jira](/blog/jira-issue-history.md) — field-level issue history with word-level diffs and CSV export * [JSON Graph Viewer & Visualizer for Jira](/apps/json-graph-viewer-visualizer-for-jira.md) — full documentation: sources, view modes, and installation Try JSON Structure Viewer for Confluence Visualize JSON as interactive structure diagrams — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237254/json-structure-viewer-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=json-structure-viewer-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [json](/blog/tags/json.md) * [how-to](/blog/tags/how-to.md) * [api](/blog/tags/api.md) * [developer-tools](/blog/tags/developer-tools.md) --- # Jira Permissions Explained: How to Set Up Project Security Without Breaking Workflows July 29, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer Jira permissions control who can view, create, and modify issues. Use permission schemes, project roles, and issue-level security to balance access with data protection. What you'll learn 1. The difference between global, project, and issue-level permissions 2. How to create and configure permission schemes in Jira 3. How to set up project roles for flexible, role-based access control 4. How to restrict issue visibility with issue-level security 5. How to test and audit permissions to verify correct configuration Permissions in Jira control who can do what. Without proper configuration, either everyone can see everything (security risk) or the permissions are so locked down that work stops (productivity risk). The key is finding the balance: enough access for people to do their jobs, not so much that sensitive data is exposed. This guide covers how to configure Jira permissions without breaking workflows. ## Why Permissions Matter[​](#why-permissions-matter "Direct link to Why Permissions Matter") Permissions are not just a security checkbox. They directly impact: **Data security.** Sensitive projects (HR, Legal, Finance) should not be visible to the entire organization. Proper permissions prevent unauthorized access. **Workflow integrity.** Without role-based transitions, anyone can move issues through the workflow. This breaks process discipline and creates audit trail issues. **Compliance.** Many industries require access controls and audit trails. Jira permissions provide both when configured correctly. **User experience.** Too many projects in the sidebar overwhelm users. Proper permissions show only what is relevant to each person. ## How Jira Permissions Work[​](#how-jira-permissions-work "Direct link to How Jira Permissions Work") ### Global Permissions[​](#global-permissions "Direct link to Global Permissions") These apply across all projects: | Permission | What It Controls | | --------------------------------- | --------------------------------------------------------------- | | Jira System Administrators | Full admin access to Jira | | Jira Administrators | Project creation, user management | | Browse Users | Can search for and mention users | | Create Issues | Can create issues in any project (if project permissions allow) | | Manage Group Filter Subscriptions | Can manage shared filters | **Where to configure:** Jira Settings > System > Global Permissions ### Project Permissions[​](#project-permissions "Direct link to Project Permissions") These apply within a specific project: | Permission | What It Controls | | ----------------- | ----------------------------------------- | | Browse Projects | Can see the project in their project list | | Create Issues | Can create new issues | | Edit Issues | Can modify existing issues | | Resolve Issues | Can mark issues as resolved | | Close Issues | Can close resolved issues | | Delete Issues | Can delete issues (use with caution) | | Transition Issues | Can move issues through the workflow | | Assign Issues | Can assign issues to users | | Schedule Issues | Can set due dates | | Comment on Issues | Can add comments | | View Developers | Can see who is assigned to issues | **Where to configure:** Project Settings > Permissions ### Issue-Level Security[​](#issue-level-security "Direct link to Issue-Level Security") This controls who can see specific issues within a project: | Scheme | What It Does | | --------------------- | ---------------------------------------------------------------------- | | Issue Security Scheme | Restricts issue visibility based on reporter, assignee, group, or role | **Use cases:** * HR issues visible only to HR team * Security incidents visible only to security team * Executive issues visible only to management ## How to Set Up Jira Permissions: Step-by-Step[​](#how-to-set-up-jira-permissions-step-by-step "Direct link to How to Set Up Jira Permissions: Step-by-Step") ### 1. Create or Modify a Permission Scheme[​](#1-create-or-modify-a-permission-scheme "Direct link to 1. Create or Modify a Permission Scheme") **For existing projects:** 1. Go to **Project Settings > Permissions** 2. Review the current scheme 3. Add or remove permissions as needed 4. Save the scheme **For new projects:** 1. Go to **Jira Settings > Issues > Permission Schemes** 2. Click **Create Permission Scheme** 3. Name it (e.g., "Software Development Permissions") 4. Add permissions for each role 5. Assign the scheme to your project **Recommended permission matrix:** | Permission | Developer | QA | Product Owner | Stakeholder | | ----------------- | --------- | --- | ------------- | ----------- | | Browse Projects | Yes | Yes | Yes | Yes | | Create Issues | Yes | Yes | Yes | No | | Edit Issues | Yes | Yes | Yes | No | | Resolve Issues | Yes | Yes | Yes | No | | Transition Issues | Yes | Yes | Yes | No | | Comment on Issues | Yes | Yes | Yes | Yes | | Assign Issues | No | No | Yes | No | | Delete Issues | No | No | Admin only | No | ### 2. Set Up Project Roles[​](#2-set-up-project-roles "Direct link to 2. Set Up Project Roles") Roles are more flexible than groups because they are project-specific. **How to create roles:** 1. Go to **Jira Settings > Projects > Project Roles** 2. Click **Add Project Role** 3. Name the role (e.g., "Developer", "QA", "Product Owner") 4. Add a description **How to assign users to roles:** 1. Go to **Project Settings > People** 2. Click **Add People** 3. Select the user and role 4. Click **Add** **Recommended roles for software teams:** * **Developer** — can create, edit, transition issues * **QA** — can create, edit, resolve issues * **Product Owner** — can create, edit, assign, resolve issues * **Stakeholder** — can browse and comment only * **Scrum Master** — full access except delete ### 3. Configure Issue-Level Security[​](#3-configure-issue-level-security "Direct link to 3. Configure Issue-Level Security") For sensitive issues, use issue security schemes: **How to create an issue security scheme:** 1. Go to **Jira Settings > Issues > Issue Security Schemes** 2. Click **Add Issue Security Scheme** 3. Name it (e.g., "Confidential Issues") 4. Add security levels: * **Reporter Only** — only the reporter can see the issue * **Assignee and Reporter** — both can see, others cannot * **Specific Role** — only users in a role can see * **Specific Group** — only members of a group can see **How to apply issue security:** 1. Go to **Project Settings > Issue Security** 2. Select the scheme 3. Issues created in this project will follow the security rules ### 4. Test and Audit Permissions[​](#4-test-and-audit-permissions "Direct link to 4. Test and Audit Permissions") Before rolling out permission changes, verify they work: **Permission Helper:** 1. Go to **Project Settings > Permissions > Permission Helper** 2. Enter a username 3. Select an issue or operation 4. Jira shows whether the user has permission and which scheme grants it **Audit checklist:** * Can users outside the team see the project? * Can users create issues without proper fields? * Can users transition issues they should not? * Are sensitive issues hidden from unauthorized users? * Do stakeholders have read-only access as intended? ## FAQ[​](#faq "Direct link to FAQ") ### What is the difference between project roles and groups in Jira?[​](#what-is-the-difference-between-project-roles-and-groups-in-jira "Direct link to What is the difference between project roles and groups in Jira?") Groups are global — a user is either in the group or not, across all projects. Project roles are project-specific — a user can be a Developer in Project A and a Stakeholder in Project B. Roles are more flexible and recommended for permission schemes. ### How do I check what permissions a user has?[​](#how-do-i-check-what-permissions-a-user-has "Direct link to How do I check what permissions a user has?") Go to Project Settings > Permissions > Permission Helper. Enter the username and select an issue or operation. Jira shows whether the user has permission and which scheme grants it. ### Can I hide a project from certain users?[​](#can-i-hide-a-project-from-certain-users "Direct link to Can I hide a project from certain users?") Yes. Remove the 'Browse Projects' permission from the project permission scheme for the groups or roles you want to exclude. Users without this permission cannot see the project in their project list. ### What happens if a user has conflicting permissions?[​](#what-happens-if-a-user-has-conflicting-permissions "Direct link to What happens if a user has conflicting permissions?") Jira uses additive permissions — if a user has permission through any role or group, they have it. There is no 'deny' in permission schemes. To restrict access, remove the user from all roles and groups that grant the permission. ### How do I restrict issue transitions to specific roles?[​](#how-do-i-restrict-issue-transitions-to-specific-roles "Direct link to How do I restrict issue transitions to specific roles?") Go to Project Settings > Workflows > Edit. Click the transition (e.g., 'Start Progress'), add a permission condition, and specify the role (e.g., 'Developers'). Only users in that role can execute the transition. ## Related guides[​](#related-guides "Direct link to Related guides") * [How to Export Jira Audit Logs for Compliance](/blog/export-jira-audit-logs-compliance.md) * [Jira JQL Cheat Sheet: 20 Queries Every Team Needs](/blog/jira-jql-cheat-sheet-common-queries.md) * [How to Set Up Jira Dashboards for Sprint Tracking](/blog/jira-dashboard-sprint-tracking-setup.md) * [Jira Workflow Automation: How to Automate Repetitive Tasks](/blog/jira-workflow-automation-guide.md) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [permissions](/blog/tags/permissions.md) * [administration](/blog/tags/administration.md) * [how-to](/blog/tags/how-to.md) * [security](/blog/tags/security.md) --- # How to Run Jira Sprint Retrospectives That Drive Real Change July 29, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer Sprint retrospectives drive improvement when they produce specific, assigned action items tracked in Jira. Use structured formats, gather anonymous input, and follow up on actions every sprint. What you'll learn 1. How to choose the right retro format for your team's maturity and energy 2. Facilitation techniques that ensure every voice is heard 3. How to turn retro feedback into trackable Jira action items 4. Why most retros fail and how to build accountability into the process Sprint retrospectives are supposed to be the engine of continuous improvement. But for many teams, they devolve into the same complaints, the same vague commitments, and the same problems month after month. The retro becomes a ritual without results. The issue is not the concept — it is the execution. Without structure, facilitation, and follow-through, retros produce feelings but not changes. This guide fixes that. ## Why Most Retros Fail[​](#why-most-retros-fail "Direct link to Why Most Retros Fail") Before fixing the retro, understand why it breaks down: **No action items.** The team discusses problems but never defines specific, assigned, time-bound actions. Without accountability, nothing changes. **Same issues every retro.** If "too many meetings" or "unclear requirements" appears every sprint, the action items from previous retros were not effective. The team loses faith in the process. **One person dominates.** Without facilitation, the loudest voice sets the agenda. Introverts and junior team members stay silent, and the retro misses critical perspectives. **No psychological safety.** Team members will not share honest feedback if they fear retaliation. Retros must be a safe space, and the scrum master must protect that safety. **Retros are too long or too short.** Too short and issues are glossed over. Too long and energy drops. The timebox must match the sprint length and team size. ## How to Run a Sprint Retrospective: Step-by-Step[​](#how-to-run-a-sprint-retrospective-step-by-step "Direct link to How to Run a Sprint Retrospective: Step-by-Step") ### 1. Choose a Retro Format[​](#1-choose-a-retro-format "Direct link to 1. Choose a Retro Format") Different formats surface different insights. Pick one based on your team's needs: **Start/Stop/Continue** — Best for teams new to retros * What should we **start** doing? * What should we **stop** doing? * What should we **continue** doing? **4Ls (Liked, Learned, Lacked, Longed For)** — Best for reflection-focused teams * What did we **like** about this sprint? * What did we **learn**? * What did we **lack**? * What did we **long for**? **Sailboat** — Best for visual teams * **Wind** (what helped us move forward) * **Anchor** (what held us back) * **Rocks** (risks ahead) * **Island** (our goal) **Mad/Sad/Glad** — Best for emotional check-ins * What made us **mad**? * What made us **sad**? * What made us **glad**? **Recommendation:** Start with Start/Stop/Continue for simplicity. Graduate to 4Ls or Sailboat as the team matures. ### 2. Gather Anonymous Input (Pre-Retro)[​](#2-gather-anonymous-input-pre-retro "Direct link to 2. Gather Anonymous Input (Pre-Retro)") Do not start the retro cold. Collect input beforehand so the discussion is productive, not spend 20 minutes writing sticky notes. **Pre-retro survey (send 24 hours before):** 1. What went well this sprint? (1-2 items) 2. What could be improved? (1-2 items) 3. On a scale of 1-5, how productive was this sprint? 4. Anything you want to discuss that you would not say publicly? **Tools for anonymous input:** * Google Forms (simple, free) * Retrium (purpose-built for retros) * Miro or Mural (virtual sticky notes) * Jira comments on a dedicated retro ticket ### 3. Facilitate the Discussion[​](#3-facilitate-the-discussion "Direct link to 3. Facilitate the Discussion") The scrum master facilitates, not leads. Your job is to create space for the team, not to solve problems. **Facilitation rules:** 1. **Timebox each topic** — 5-10 minutes per item. Use a visible timer. 2. **Focus on root causes** — Ask "why" 5 times to get past symptoms. 3. **One conversation at a time** — No side discussions or device checking. 4. **Equal airtime** — If someone has not spoken in 10 minutes, invite them. 5. **No solutions during brainstorming** — Separate problem identification from problem solving. **Facilitation phrases:** * "Let's hear from someone who has not shared yet." * "Can you say more about that? What specifically caused it?" * "We have 2 minutes left on this topic — any final thoughts?" * "Let's move this to the parking lot and come back if we have time." ### 4. Create Actionable Items[​](#4-create-actionable-items "Direct link to 4. Create Actionable Items") This is where most retros fail. Every problem identified must produce a specific, assigned, time-bound action. **Action item template:** | Field | Value | | ---------- | ------------------------------------------------ | | Problem | "Standups run over 15 minutes" | | Action | "Implement async standup bot for status updates" | | Owner | @developer-name | | Due date | Before next sprint planning | | Jira issue | Create a task in the current sprint | **Rules for action items:** * Max 2-3 per retro — more is noise * Each action must have an owner and due date * Create a Jira issue for each action so it is trackable * Review progress at the start of every retro **Track retro actions in Jira:** * Create a "Retro Actions" epic per quarter * Link all retro action items to the epic * Use a saved filter: `parent = "RETRO-EPIC-1" AND status != Done` * Review this filter at the start of each retro ### 5. Track Action Items to Completion[​](#5-track-action-items-to-completion "Direct link to 5. Track Action Items to Completion") A retro without follow-up is just a meeting. Build accountability into the process. **Retro follow-up checklist:** * Review action items from last retro (5 minutes at start) * Celebrate completed items * Discuss incomplete items — why? What blocked them? * Update action items with new due dates if needed * Add new action items from current retro **If action items are consistently not completed:** * Reduce the number (go from 3 to 1) * Make actions smaller and more specific * Assign actions to people who have bandwidth * Escalate systemic blockers to management ## FAQ[​](#faq "Direct link to FAQ") ### How long should a sprint retrospective be?[​](#how-long-should-a-sprint-retrospective-be "Direct link to How long should a sprint retrospective be?") For a 2-week sprint, allocate 60-90 minutes. For a 1-week sprint, 30-45 minutes. The timebox should feel comfortable — too short and issues are glossed over, too long and energy drops. ### Who should attend the sprint retrospective?[​](#who-should-attend-the-sprint-retrospective "Direct link to Who should attend the sprint retrospective?") The full Scrum team: developers, product owner, and scrum master. Optionally include a stakeholder for the final 10 minutes if there are cross-team issues. Never include managers who might inhibit honest feedback. ### What if the team keeps identifying the same problems every retro?[​](#what-if-the-team-keeps-identifying-the-same-problems-every-retro "Direct link to What if the team keeps identifying the same problems every retro?") This signals that action items are not being completed or are not addressing root causes. Focus on fewer action items (max 2-3 per retro) and track them rigorously. If the same issue persists, escalate it outside the team. ### How do I handle conflict during retrospectives?[​](#how-do-i-handle-conflict-during-retrospectives "Direct link to How do I handle conflict during retrospectives?") Acknowledge the disagreement, timebox the discussion, and focus on facts not feelings. If conflict escalates, take a 5-minute break. The scrum master should mediate, not take sides. Document the disagreement and revisit offline if needed. ### Should retrospectives be anonymous?[​](#should-retrospectives-be-anonymous "Direct link to Should retrospectives be anonymous?") Anonymous input helps surface sensitive issues, especially in new or low-trust teams. As trust builds, transition to open discussion. Use anonymous pre-surveys combined with open in-meeting discussion for the best of both approaches. ## Related guides[​](#related-guides "Direct link to Related guides") * [How to Plan Jira Sprints That Actually Work](/blog/plan-jira-sprints-that-actually-work.md) * [Jira Backlog Grooming: The Complete Guide](/blog/jira-backlog-grooming-complete-guide.md) * [How to Set Up Jira Dashboards for Sprint Tracking](/blog/jira-dashboard-sprint-tracking-setup.md) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [retrospective](/blog/tags/retrospective.md) * [agile](/blog/tags/agile.md) * [scrum](/blog/tags/scrum.md) * [team-performance](/blog/tags/team-performance.md) --- # Jira vs Confluence: What Each Is Actually For (with Examples) August 2, 2026 · 9 min read [NGPilot](https://ngpilot.com) Quick Answer Jira and Confluence are two different Atlassian products that are often bought together but solve fundamentally different problems. **Jira tracks work** — issues, sprints, backlogs, and workflows. **Confluence documents knowledge** — pages, decisions, specs, and team context. They connect natively so an issue and the page explaining it stay linked. Use Jira for "what are we doing and who is doing it," and Confluence for "why are we doing it and how does it work." What you'll learn 1. The core purpose of each product (with a one-line definition you can repeat) 2. What Jira is good at and bad at 3. What Confluence is good at and bad at 4. How they connect natively 5. A practical decision guide: which tool for which task Jira and Confluence are the two products most people picture when they hear "Atlassian." They are frequently sold together, deeply integrated, and yet regularly confused — even by teams that use both every day. This guide explains what each is actually for, where each one shines and struggles, and how to decide which tool a given piece of work belongs in. The goal is to give you a mental model you can apply to any task, not a feature checklist. ## The one-line definitions[​](#the-one-line-definitions "Direct link to The one-line definitions") If you remember nothing else, remember these: * **Jira is a work tracker.** It answers "what needs to be done, who is doing it, and what state is it in?" * **Confluence is a knowledge base.** It answers "why are we doing this, how does it work, and what did we decide?" Everything else flows from that distinction. Jira is structured around **issues** that move through **workflows**; Confluence is structured around **pages** organized in **spaces**. Jira is transactional — each issue is a unit of work with a lifecycle. Confluence is documentary — each page is a unit of knowledge that persists and evolves. ## What Jira is good at[​](#what-jira-is-good-at "Direct link to What Jira is good at") Jira was built for software development and has expanded into general project, IT service, and operations work. Its strengths: * **Issue tracking with state.** Every piece of work is an issue with a status (To Do, In Progress, Done), an assignee, a priority, and a history. You always know where a piece of work stands. * **Workflows and automation.** Jira's workflow engine lets you define how issues move from creation to completion, with rules, conditions, and validators. You can automate transitions, assignments, and notifications based on events. * **Boards, backlogs, and sprints.** For agile teams, Jira provides Scrum and Kanban boards, prioritized backlogs, sprint planning, and velocity tracking. This is its heartland. * **Custom fields and queries.** Jira's custom fields and JQL (Jira Query Language) let you slice your work any way you need — by component, by customer, by severity, by any dimension you model. * **Reporting.** Burndown charts, sprint reports, cumulative flow diagrams, and control charts give you real visibility into how work is flowing. Jira is the system of record for *work in motion*. ## What Jira is bad at[​](#what-jira-is-bad-at "Direct link to What Jira is bad at") Jira's structure is its strength and its constraint: * **Long-form content is painful.** Writing a spec, a design doc, or an onboarding guide in a Jira description is a fight against the tool. The editor is minimal, there is no page hierarchy, and linking related documents together is awkward. * **Knowledge does not fit the issue model.** A decision record or an architecture overview is not a unit of work with a status — it is a reference that persists. Forcing it into an issue type distorts both the content and the workflow. * **Discovery is hard.** Finding "that page where we decided to use Postgres" in Jira is difficult because Jira is optimized for finding issues by status and field, not for browsing knowledge. ## What Confluence is good at[​](#what-confluence-is-good-at "Direct link to What Confluence is good at") Confluence is Atlassian's wiki and document collaboration product. Its strengths: * **Long-form, structured documents.** Pages with headings, tables, code blocks, diagrams, and embedded media — exactly what a spec, a runbook, or a knowledge base article needs. * **Hierarchical organization.** Spaces contain pages, which contain child pages, forming a navigable tree. You can organize documentation the way people actually browse it. * **Real-time collaboration.** Multiple people editing a page simultaneously, with comments, mentions, and page history. It is built for collective authorship. * **Search and discovery.** Full-text search across all spaces and pages, plus labels and the newer semantic search via Rovo, make knowledge findable in a way Jira cannot match. * **Templates and macros.** Meeting notes, decision records, retros, and how-to templates get teams started fast. Macros (like diagrams, code blocks, and FAQs) extend pages with structured content. Confluence is the system of record for *knowledge at rest*. ## What Confluence is bad at[​](#what-confluence-is-bad-at "Direct link to What Confluence is bad at") Confluence is a knowledge tool, not a work management tool: * **It cannot track work state.** Confluence has task lists, but they have no workflow, no boards, no reporting, and no automation. Trying to run a sprint from Confluence task lists collapses within a week. * **No backlog or prioritization engine.** There is no equivalent of Jira's backlog, no drag-to-rank, no sprint planning. If you need to prioritize and sequence work, Jira is the tool. * **Not built for transactions.** Confluence pages are edited occasionally and read often; they are not designed for high-frequency status updates the way Jira issues are. ## How they connect[​](#how-they-connect "Direct link to How they connect") The reason most teams buy both is that Jira and Confluence integrate natively, so the work and the knowledge behind it stay linked: * **Embed Jira issues in Confluence.** Paste a Jira issue key (like `PROJ-123`) into a Confluence page and it becomes a live card showing the issue's current status, assignee, and priority. When the issue moves to Done, the card updates automatically. * **Attach Confluence pages to Jira issues.** Link the design doc, the spec, or the runbook directly to the issue so the engineer picking up the ticket has the context they need in one click. * **Jira macro in Confluence.** Display a filtered list of issues on a Confluence page using JQL — useful for a project dashboard that shows open blockers, in-progress epics, or the current sprint. * **Linked spaces and projects.** A Confluence space can be associated with a Jira project, so searches and navigation cross between them. This integration is what makes the "Jira for work, Confluence for knowledge" split actually work in practice — the two stay in sync without manual duplication. ## A practical decision guide[​](#a-practical-decision-guide "Direct link to A practical decision guide") When a piece of information comes up, where does it go? Use this guide: | If the thing is... | Put it in... | Because | | -------------------------------------------- | -------------- | ------------------------------------------- | | A task, bug, or feature to be done | **Jira** | It has state, an assignee, and a lifecycle | | A meeting decision or rationale | **Confluence** | It is knowledge that persists, not work | | A sprint plan or backlog | **Jira** | That is Jira's core function | | A spec, design doc, or architecture overview | **Confluence** | Long-form structured content | | An onboarding guide or runbook | **Confluence** | Reference material people browse | | A support ticket or incident | **Jira (JSM)** | Transactional work with workflow | | A retrospective or post-mortem | **Confluence** | Documentary, read by the team over time | | A question and its accepted answer | **Confluence** | Knowledge that others will search for later | The rule of thumb: **if it has a status that changes, it belongs in Jira; if it is read more than it changes, it belongs in Confluence.** ## What this means for the apps you choose[​](#what-this-means-for-the-apps-you-choose "Direct link to What this means for the apps you choose") Understanding the Jira-vs-Confluence split also shapes which Marketplace apps you need, because most apps are product-specific. A diagraming app for Confluence does not put diagrams on Jira issues; a Jira issue template app does not template Confluence pages. When you are evaluating apps, start from the product where the problem lives: * **Content and authoring problems** — Markdown editing, code blocks, fonts, diagrams in documentation, FAQs, page formatting — these are Confluence problems, and they need Confluence apps. Browse our [Confluence app scenarios](/solutions.md) to see the common ones. * **Work and process problems** — issue templates, bulk export, attachment management, announcement banners — these are Jira problems, and they need Jira apps. Browse our [Jira app scenarios](/solutions.md) for the high-value ones. If you are unsure which product a problem lives in, the decision guide above will tell you — and from there, the right app category follows naturally. ## Frequently Asked Questions[​](#frequently-asked-questions "Direct link to Frequently Asked Questions") ### Is Jira or Confluence more important?[​](#is-jira-or-confluence-more-important "Direct link to Is Jira or Confluence more important?") Neither is more important — they solve different problems. A team that only tracks work needs Jira; a team that only documents needs Confluence. Most teams need both, because work without context leads to repeated mistakes, and context without tracked work leads to nothing getting done. The value is in using each for what it does best. ### Can I use Confluence instead of Jira?[​](#can-i-use-confluence-instead-of-jira "Direct link to Can I use Confluence instead of Jira?") You can, but you will outgrow it quickly. Confluence task lists work for a small team tracking a handful of action items, but they lack workflows, boards, backlogs, automation, and reporting. Once you have more than a few concurrent pieces of work, the lack of structure becomes painful. Jira exists precisely to solve that. ### Can I use Jira instead of Confluence?[​](#can-i-use-jira-instead-of-confluence "Direct link to Can I use Jira instead of Confluence?") You can stash documents as Jira attachments or in long issue descriptions, but it is a poor experience. Jira is not designed for browsing knowledge, authoring long-form content, or organizing a hierarchy of related documents. Teams that try usually end up with information scattered across issues that nobody can find. ### What is Jira Service Management, and is it different?[​](#what-is-jira-service-management-and-is-it-different "Direct link to What is Jira Service Management, and is it different?") Jira Service Management (JSM) is a Jira product configured for IT service and support workflows — ticketing, SLAs, queues, and a customer portal. It is still Jira underneath, optimized for service use cases. It pairs with Confluence as a knowledge base for self-service help articles. ### Are Jira and Confluence free?[​](#are-jira-and-confluence-free "Direct link to Are Jira and Confluence free?") Both have free Cloud plans for up to 10 users. The free tiers include core features and are genuinely usable for small teams. Paid plans add storage, advanced permissions, audit logging, and support. Most Marketplace apps, including all NGPILOT apps, are also free for up to 10 users on the same model. ### Where can I read Atlassian's official product pages?[​](#where-can-i-read-atlassians-official-product-pages "Direct link to Where can I read Atlassian's official product pages?") Atlassian's [Jira product page](https://www.atlassian.com/software/jira) and [Confluence product page](https://www.atlassian.com/software/confluence) cover features and pricing, and the [Atlassian Cloud documentation](https://support.atlassian.com/) has detailed user guides for both. *** *NGPILOT builds apps for both Jira and Confluence. Browse the [app catalog](/apps.md) or explore [solutions by scenario](/solutions.md) to find the tools that fit how your team works.* ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [atlassian](/blog/tags/atlassian.md) * [jira](/blog/tags/jira.md) * [confluence](/blog/tags/confluence.md) * [explained](/blog/tags/explained.md) * [comparison](/blog/tags/comparison.md) --- # Jira Workflow Automation: Complete Guide (2026) July 30, 2026 · 4 min read [NGPilot](https://ngpilot.com) Quick Answer Jira workflow automation uses rules with triggers, conditions, and actions to automate repetitive tasks. You can auto-assign issues, transition tickets based on status, send notifications, and update fields — all without code. Start with Jira's built-in automation rules, then scale to marketplace apps for complex workflows. ## What Is Jira Workflow Automation?[​](#what-is-jira-workflow-automation "Direct link to What Is Jira Workflow Automation?") Jira workflow automation eliminates manual steps by triggering actions based on events. Instead of manually assigning issues, updating statuses, or sending notifications, Jira does it automatically. ### Key Benefits[​](#key-benefits "Direct link to Key Benefits") | Benefit | Impact | | ------------------------- | -------------------------------- | | **Reduce manual work** | Save 5-10 hours/week per team | | **Eliminate human error** | Consistent, repeatable processes | | **Enforce compliance** | Automated checks and balances | | **Speed up delivery** | Faster issue resolution | *** ## Jira Automation Rules[​](#jira-automation-rules "Direct link to Jira Automation Rules") Jira's built-in automation engine lets you create rules without code. ### Rule Anatomy[​](#rule-anatomy "Direct link to Rule Anatomy") Every rule has three parts: ``` Trigger → Condition → Action ``` | Component | Purpose | Examples | | ------------- | ------------------------ | -------------------------------------------- | | **Trigger** | When does the rule run? | Issue created, status changed, field updated | | **Condition** | Should the rule proceed? | Issue type is Bug, priority is High | | **Action** | What happens? | Assign to user, transition issue, send email | ### How to Create a Rule[​](#how-to-create-a-rule "Direct link to How to Create a Rule") 1. Go to **Project Settings** → **Automation** 2. Click **Create rule** 3. Select a **Trigger** 4. Add **Conditions** (optional) 5. Add **Actions** 6. Name and enable the rule *** ## Common Automation Patterns[​](#common-automation-patterns "Direct link to Common Automation Patterns") ### 1. Auto-Assign Issues[​](#1-auto-assign-issues "Direct link to 1. Auto-Assign Issues") **Trigger:** Issue created **Condition:** None **Action:** Assign to project lead Use when: Issues are always triaged by one person. ### 2. Transition Parent When All Children Done[​](#2-transition-parent-when-all-children-done "Direct link to 2. Transition Parent When All Children Done") **Trigger:** Issue transitioned to Done **Condition:** All sub-tasks are Done **Action:** Transition parent to Done Use when: Epics or stories should auto-close after sub-tasks finish. ### 3. Notify on High Priority[​](#3-notify-on-high-priority "Direct link to 3. Notify on High Priority") **Trigger:** Issue created **Condition:** Priority = Highest **Action:** Send Slack/email to team lead Use when: Critical issues need immediate attention. ### 4. Auto-Close Stale Issues[​](#4-auto-close-stale-issues "Direct link to 4. Auto-Close Stale Issues") **Trigger:** Scheduled (daily) **Condition:** Status = To Do, updated > 30 days ago **Action:** Transition to Closed, add comment Use when: Backlog hygiene is neglected. ### 5. Clone Issue on Transition[​](#5-clone-issue-on-transition "Direct link to 5. Clone Issue on Transition") **Trigger:** Issue transitioned to Done **Condition:** Issue type = Bug **Action:** Create linked issue in QA project Use when: Bugs need verification after fix. *** ## Advanced Automation[​](#advanced-automation "Direct link to Advanced Automation") ### Multi-Branch Rules[​](#multi-branch-rules "Direct link to Multi-Branch Rules") Run multiple actions in parallel: ``` Trigger: Issue created ├── Branch: If issue type = Story │ ├── Action: Create sub-task "Design" │ └── Action: Create sub-task "Development" └── Branch: If issue type = Bug ├── Action: Assign to QA lead └── Action: Add "needs-investigation" label ``` ### Webhook Integration[​](#webhook-integration "Direct link to Webhook Integration") Connect Jira to external systems: | Integration | Use Case | | -------------- | -------------------------- | | **Slack** | Post messages to channels | | **GitHub** | Sync issues with PRs | | **Confluence** | Auto-create documentation | | **Custom API** | Trigger external workflows | ### Scheduled Rules[​](#scheduled-rules "Direct link to Scheduled Rules") Run rules on a schedule: | Schedule | Example | | -------------------- | -------------------- | | **Daily at 9am** | Send standup summary | | **Weekly on Monday** | Close stale issues | | **Monthly** | Generate reports | *** ## Jira Workflow Automation vs. Marketplace Apps[​](#jira-workflow-automation-vs-marketplace-apps "Direct link to Jira Workflow Automation vs. Marketplace Apps") | Feature | Jira Built-in | Marketplace Apps | | -------------- | ------------------ | ----------------- | | **Setup** | No code, GUI | Varies | | **Complexity** | Simple to moderate | Advanced | | **Cost** | Included | Per-user pricing | | **Triggers** | Limited set | Extended triggers | | **Actions** | Standard actions | Custom actions | ### When to Use Built-in[​](#when-to-use-built-in "Direct link to When to Use Built-in") * Simple assignment rules * Basic transitions * Email/Slack notifications * Field updates ### When to Use Marketplace Apps[​](#when-to-use-marketplace-apps "Direct link to When to Use Marketplace Apps") * Complex multi-project workflows * Approval chains * Time-based SLAs * Cross-project automation *** ## Best Practices[​](#best-practices "Direct link to Best Practices") 1. **Start simple**: Begin with one trigger + one action 2. **Test thoroughly**: Use the "Audit log" to verify rules 3. **Document rules**: Keep a list of active automations 4. **Review regularly**: Remove unused rules 5. **Use branches wisely**: Avoid overly complex logic *** ## Frequently Asked Questions[​](#frequently-asked-questions "Direct link to Frequently Asked Questions") **Can I automate across multiple projects?** Yes. Use "Multi-project" rules or webhooks to trigger actions across projects. **What's the difference between workflow triggers and automation triggers?** Workflow triggers are built into the workflow editor. Automation triggers are more flexible and support conditions. **Can I undo an automation?** No. Automation actions are permanent. Use the audit log to review what happened. **How many rules can I create?** Jira Cloud has limits based on your plan. Check your automation usage in **Automation** → **Usage**. **Can I use JQL in conditions?** Yes. Many conditions support JQL queries for flexible filtering. *** ## Related Guides[​](#related-guides "Direct link to Related Guides") * [Jira Workflow Automation Guide](/blog/jira-workflow-automation-guide.md) * [Create Jira Issue Templates for Consistent Workflows](/blog/create-jira-issue-templates-for-consistent-workflows.md) * [Jira Backlog Grooming Complete Guide](/blog/jira-backlog-grooming-complete-guide.md) * [Jira Dashboard Sprint Tracking Setup](/blog/jira-dashboard-sprint-tracking-setup.md) *** *This guide is part of our Jira admin series. Bookmark it for reference.* ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [jira-admin](/blog/tags/jira-admin.md) * [automation](/blog/tags/automation.md) * [workflows](/blog/tags/workflows.md) * [atlassian](/blog/tags/atlassian.md) --- # Jira Workflow Automation: How to Automate Repetitive Tasks and Save Hours July 29, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer Jira automation rules eliminate repetitive tasks like assignment, notifications, and status transitions. Use triggers, conditions, and actions to build rules without code. What you'll learn 1. How to identify which Jira tasks are good automation candidates 2. How to build automation rules using triggers, conditions, and actions 3. How to test, debug, and refine automation rules 4. How to scale automation across projects and teams Every Jira team has repetitive tasks: assigning bugs to the QA lead, transitioning issues when a pull request is merged, sending notifications when a sprint starts. These tasks follow consistent rules, which makes them perfect for automation. Jira's built-in automation engine lets you create rules without code. This guide covers how to identify automation candidates, build rules, and scale them across your organization. ## Why Automate Jira Workflows[​](#why-automate-jira-workflows "Direct link to Why Automate Jira Workflows") Manual processes are slow, error-prone, and do not scale. Automation fixes this: **Consistency.** Rules execute the same way every time. No more forgotten assignments or missed transitions. **Speed.** Automated actions happen instantly. No waiting for someone to manually update an issue. **Enforcement.** Automation ensures process compliance. If the rule says bugs go to QA, they go to QA — no exceptions. **Scale.** One rule can manage thousands of issues across multiple projects. Manual processes cannot. ## How to Identify Automation Candidates[​](#how-to-identify-automation-candidates "Direct link to How to Identify Automation Candidates") Look for tasks that meet these criteria: **High frequency.** If you do it more than once a day, automate it. **Consistent rules.** If the logic is "when X happens, do Y," it is a candidate. **Low judgment.** Tasks that do not require human decision-making are best for automation. **Time-consuming.** If it takes more than 2 minutes each time, automation saves significant time. **Common automation candidates:** | Task | Trigger | Action | | --------------------------- | --------------------------------- | ------------------------------------------- | | Assign bugs to QA lead | Issue created with type = Bug | Assign to @qa-lead | | Notify team on sprint start | Sprint started | Send Slack/email notification | | Move issue to "In Review" | Pull request merged | Transition to "In Review" | | Close stale issues | Updated > 30 days, status = Open | Transition to "Closed" | | Create sub-tasks | Story created with type = Feature | Create "Design" and "Code Review" sub-tasks | ## How to Create Jira Automation Rules: Step-by-Step[​](#how-to-create-jira-automation-rules-step-by-step "Direct link to How to Create Jira Automation Rules: Step-by-Step") ### 1. Access Jira Automation[​](#1-access-jira-automation "Direct link to 1. Access Jira Automation") 1. Go to **Project Settings > Automation** 2. Click **Create Rule** 3. Choose a trigger from the list 4. Add conditions to filter when the rule applies 5. Add actions to define what happens 6. Name and enable the rule ### 2. Choose a Trigger[​](#2-choose-a-trigger "Direct link to 2. Choose a Trigger") Triggers start the automation. Common triggers: | Trigger | When It Fires | | --------------------------- | --------------------------------------- | | Issue created | When a new issue is created | | Issue updated | When any field changes | | Status changed | When an issue transitions | | Sprint started/ended | When a sprint begins or completes | | Pull request created/merged | When linked to a Jira issue | | Schedule (cron) | At a specific time (daily, weekly) | | Webhook | When an external system sends a request | ### 3. Add Conditions[​](#3-add-conditions "Direct link to 3. Add Conditions") Conditions filter when the rule applies. Without conditions, the rule fires on every trigger. **Common conditions:** * **Issue type** = Bug, Story, Task * **Priority** = High, Medium, Low * **Status** = Open, In Progress, Done * **Project** = Specific project * **Field value** = Contains specific text **Example:** Only apply when issue type is Bug AND priority is High. ### 4. Add Actions[​](#4-add-actions "Direct link to 4. Add Actions") Actions define what happens when the trigger fires and conditions are met. **Common actions:** * **Assign issue** — to a user, role, or round-robin * **Transition issue** — move to a specific status * **Send notification** — email, Slack, or in-app * **Update field** — set priority, labels, components * **Create issue** — linked issue or sub-task * **Add comment** — automated note on the issue ### 5. Test and Refine[​](#5-test-and-refine "Direct link to 5. Test and Refine") Before enabling, test the rule: 1. Click **Run rule** with a test issue 2. Check the audit log for results 3. Verify the action was applied correctly 4. Adjust conditions if the rule fired incorrectly 5. Enable the rule when satisfied **Audit log location:** Project Settings > Automation > Audit Log ## 10 Useful Jira Automation Rules[​](#10-useful-jira-automation-rules "Direct link to 10 Useful Jira Automation Rules") ### 1. Auto-assign bugs to QA lead[​](#1-auto-assign-bugs-to-qa-lead "Direct link to 1. Auto-assign bugs to QA lead") ``` Trigger: Issue created Condition: Issue type = Bug Action: Assign to @qa-lead ``` ### 2. Notify team on sprint start[​](#2-notify-team-on-sprint-start "Direct link to 2. Notify team on sprint start") ``` Trigger: Sprint started Action: Send email to sprint-team@company.com ``` ### 3. Move to "In Review" when PR is merged[​](#3-move-to-in-review-when-pr-is-merged "Direct link to 3. Move to \"In Review\" when PR is merged") ``` Trigger: Pull request merged Action: Transition to "In Review" ``` ### 4. Close stale issues after 30 days[​](#4-close-stale-issues-after-30-days "Direct link to 4. Close stale issues after 30 days") ``` Trigger: Schedule (daily) Condition: Status = Open AND updated <= -30d Action: Transition to "Closed" + add comment "Auto-closed due to inactivity" ``` ### 5. Create sub-tasks for new stories[​](#5-create-sub-tasks-for-new-stories "Direct link to 5. Create sub-tasks for new stories") ``` Trigger: Issue created Condition: Issue type = Story Action: Create sub-task "Design Review" + Create sub-task "Code Review" ``` ### 6. Set priority based on summary keywords[​](#6-set-priority-based-on-summary-keywords "Direct link to 6. Set priority based on summary keywords") ``` Trigger: Issue created Condition: Summary contains "urgent" or "critical" Action: Set priority to "High" ``` ### 7. Notify reporter when issue is resolved[​](#7-notify-reporter-when-issue-is-resolved "Direct link to 7. Notify reporter when issue is resolved") ``` Trigger: Status changed to "Done" Action: Send email to reporter with resolution details ``` ### 8. Add label for specific components[​](#8-add-label-for-specific-components "Direct link to 8. Add label for specific components") ``` Trigger: Issue updated Condition: Component = "Backend" Action: Add label "backend-team" ``` ### 9. Transition parent when all sub-tasks are done[​](#9-transition-parent-when-all-sub-tasks-are-done "Direct link to 9. Transition parent when all sub-tasks are done") ``` Trigger: Sub-task transitioned to "Done" Condition: All sub-tasks of parent are "Done" Action: Transition parent to "Done" ``` ### 10. Weekly summary email[​](#10-weekly-summary-email "Direct link to 10. Weekly summary email") ``` Trigger: Schedule (weekly, Friday 4pm) Condition: Status = "In Progress" AND assignee = currentUser() Action: Send email with list of open issues ``` ## FAQ[​](#faq "Direct link to FAQ") ### What can I automate in Jira?[​](#what-can-i-automate-in-jira "Direct link to What can I automate in Jira?") You can automate issue assignment, status transitions, notifications, field updates, linked issue creation, sprint management, and more. Any action that follows a consistent rule can be automated. ### How do I create a Jira automation rule?[​](#how-do-i-create-a-jira-automation-rule "Direct link to How do I create a Jira automation rule?") Go to Project Settings > Automation > Create Rule. Select a trigger (e.g., issue created), add conditions (e.g., issue type = Bug), and add actions (e.g., assign to QA lead). Save and enable the rule. ### Can I automate across multiple Jira projects?[​](#can-i-automate-across-multiple-jira-projects "Direct link to Can I automate across multiple Jira projects?") Yes. Global automation rules apply to all projects. Project-specific rules only apply to that project. Use global rules for organization-wide standards, project rules for team-specific workflows. ### How do I debug a Jira automation rule that is not working?[​](#how-do-i-debug-a-jira-automation-rule-that-is-not-working "Direct link to How do I debug a Jira automation rule that is not working?") Go to Project Settings > Automation > Audit Log to see when rules fired and what actions were taken. Check for conditions that are not met, trigger issues, or permission problems. ### Are there limits to Jira automation rules?[​](#are-there-limits-to-jira-automation-rules "Direct link to Are there limits to Jira automation rules?") Jira Cloud has limits on the number of rules and executions per month based on your plan. Jira Server/Data Center has no hard limits but performance depends on your infrastructure. Monitor usage to avoid hitting limits. ## Related guides[​](#related-guides "Direct link to Related guides") * [How to Plan Jira Sprints That Actually Work](/blog/plan-jira-sprints-that-actually-work.md) * [How to Set Up Jira Dashboards for Sprint Tracking](/blog/jira-dashboard-sprint-tracking-setup.md) * [Jira Permissions Explained: Project Security Setup](/blog/jira-permissions-explained-project-security-setup.md) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [automation](/blog/tags/automation.md) * [workflow](/blog/tags/workflow.md) * [how-to](/blog/tags/how-to.md) * [productivity](/blog/tags/productivity.md) --- # Why Markdown Became the Documentation Format of the AI Era August 21, 2026 · 7 min read [NGPilot](https://ngpilot.com) In 2004, John Gruber released Markdown with a modest pitch: a text format that is easy to *read*, easy to *write*, and converts cleanly to HTML. Twenty years later his side project became the default language of technical documentation — GitHub renders it natively, Stack Overflow is built on it, Obsidian and Notion popularized it, and every major LLM speaks it fluently. The Verge called it "the default language of the AI era." That last part is the interesting one. Markdown didn't just survive the AI transition — it *locked in* because of it. This article walks through why, and what it means for how your team should write documentation inside Confluence. ## The two eras of Markdown[​](#the-two-eras-of-markdown "Direct link to The two eras of Markdown") ### Era 1: The network-effect years (2004–2022)[​](#era-1-the-network-effect-years-20042022 "Direct link to Era 1: The network-effect years (2004–2022)") Markdown's first victory was a simplicity bet that paid off. HTML was never meant to be hand-written; it was meant to be *generated*. Gruber's insight was that 90% of what people actually write — headings, emphasis, lists, links, code — needs about ten marks of punctuation, not a tag soup. The network effects did the rest: * **GitHub made it infrastructure.** READMEs, issues, pull requests, wikis — the world's largest code host chose Markdown as its lingua franca, which meant every developer already knew it. * **Stack Overflow made it culture.** Q\&A formatting in Markdown trained a generation of technical writers. * **Static-site generators made it publishing.** Jekyll, Hugo, and later Next.js content pipelines turned "a folder of .md files" into a professional website. By the early 2020s, "docs-as-code" wasn't an argument anymore — it was the default for any team that versioned anything. ### Era 2: The AI years (2022– )[​](#era-2-the-ai-years-2022- "Direct link to Era 2: The AI years (2022– )") Then something changed that Gruber couldn't have predicted: **the primary reader of documentation stopped being only human.** Every serious knowledge workflow now involves an LLM somewhere — answering questions from your docs, summarizing a runbook, generating release notes, indexing your wiki for retrieval. And LLMs have a strong format preference, for hard economic reasons: **Token economics.** Models read and write in tokens, and tokens cost money and context window. Markdown's minimal syntax means a document spends its token budget on *content*, not markup. One widely-cited analysis estimates Markdown uses roughly **40% fewer tokens** than the equivalent HTML — that's 40% more room in your context window for the actual answer. **Parseability without conversion.** A .docx file is a ZIP archive containing XML. Before a model can read it, something must unzip and convert it — each conversion is a chance to lose structure, tables, or code formatting. Markdown needs no conversion layer. What the model sees is what you wrote. **The corpus is already Markdown.** Models were trained heavily on GitHub, Stack Overflow, and technical documentation — one estimate puts Markdown-formatted content at roughly **85% of AI training corpora** for technical domains. Models don't just tolerate Markdown; they were raised on it. Ask any LLM to "write the docs" and Markdown is what comes out, unprompted. **Chat is a Markdown renderer.** The interface layer agrees. Every chat UI — ChatGPT, Claude, Copilot — renders Markdown natively. When a model answers with headings, lists, and code fences, it is speaking its native dialect. ## Why the alternatives lost[​](#why-the-alternatives-lost "Direct link to Why the alternatives lost") It's worth being precise about *why* each alternative failed, because teams still pick them by inertia: | Format | What went wrong in the AI era | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **.docx / .odt** | Binary ZIP+XML. No clean diffs ("binary file changed"), needs conversion before AI ingestion, merges are impossible. Great for legal contracts, wrong for living docs. | | **Plain .txt** | No structure at all — headings, lists, and code all look identical to a parser. The token efficiency is real but the signal is gone. Structure is what makes text *retrievable*. | | **.rtf** | The worst of both: verbose inline markup that's worse than HTML, supported by almost nothing modern. | | **HTML** | Fine to *publish*, painful to *author and diff*. And it pays the token tax — the model reads your `
` before it reads your sentence. | | **PDF** | A print layout frozen in time. Extracting structure back out of PDFs is a lossy research problem. | Markdown's niche turned out to be exactly the intersection machines and humans both need: **just enough structure to be unambiguous, not enough syntax to be noise.** ## What "AI-native documentation" actually requires[​](#what-ai-native-documentation-actually-requires "Direct link to What \"AI-native documentation\" actually requires") If your docs are going to be read as much by models as by teammates — retrieval-augmented answers, wiki copilots, automated release notes — the requirements stack looks like this: 1. **Plain-text Markdown core.** Versionable, diffable, token-efficient, conversion-free. 2. **Tables that carry data.** Markdown tables are the cheapest structured data format a model can read inline. 3. **Diagrams as code.** An image of an architecture diagram is invisible to a model. The same diagram as Mermaid text is fully readable — the model can explain it, update it, even generate it. 4. **Code with language annotations.** Fenced blocks with language tags drive both syntax highlighting for humans and correct parsing for machines. Most team wikis fail all four. Confluence's native editor — for all its strengths — stores content in a rich-text format that only fully lives inside Confluence. ## The Confluence gap, and how to close it[​](#the-confluence-gap-and-how-to-close-it "Direct link to The Confluence gap, and how to close it") Here's the tension: your engineering team lives in Markdown and Mermaid, but your company's knowledge lives in Confluence, where the native editor doesn't really speak either. That gap is exactly what our Confluence apps are built to bridge — each one covers a layer of the AI-native stack: * **[Enhanced Markdown for Confluence](/apps/enhanced-markdown-for-confluence.md)** — a full Markdown editor macro inside the page: WYSIWYG + source modes, syntax-highlighted code fences, LaTeX, and Mermaid v12 rendered from ` ```mermaid ` blocks. Your README workflow, inside your wiki. * **[Mermaid Plus Diagrams & AI Agent for Confluence](/apps/mermaid-plus-for-confluence.md)** — when a page needs the diagram without the full Markdown editor; 30 diagram types from plain text. * **[Modern Code Blocks for Confluence](/apps/modern-code-blocks-for-confluence.md)** — Monaco-based code blocks with themes and diff view, for pages where code is the centerpiece. * **[Modern Importer & Exporter](/apps/modern-importer-exporter-for-confluence.md)** — bulk-convert Markdown repos into native Confluence pages and back, so docs-as-code pipelines don't have to choose sides. The point isn't that Confluence is broken — it's that the *interface* between the Markdown world and the wiki world is now a solved problem. Your team can keep authoring in the format both humans and machines prefer, and the knowledge still lands where the company looks for it. ## The takeaway[​](#the-takeaway "Direct link to The takeaway") Markdown won twice: once on human ergonomics, once on machine economics. The second win is the durable one — as long as LLMs are in the loop, the format that costs fewer tokens, parses without conversion, and matches the training corpus has an unassailable position. If your documentation strategy still revolves around office formats and screenshot diagrams, the cheapest upgrade you'll ever make is moving the source of truth to Markdown + Mermaid — and bridging it into Confluence, where your organization actually collaborates. ## Related reading[​](#related-reading "Direct link to Related reading") * [Import Markdown into Confluence — 3 Methods Compared](/blog/markdown-to-confluence-converter.md) * [Write Markdown in Confluence with Mermaid, LaTeX & Code](/blog/write-markdown-confluence-mermaid-latex-code.md) * [Confluence Markdown editor FAQ](/blog/faq-confluence-markdown-editor.md) * [All 30 Mermaid diagram types in Confluence](/blog/faq-mermaid-diagram-types-confluence.md) * [Does Confluence support Mermaid?](/blog/does-confluence-support-mermaid.md) Try Enhanced Markdown for Confluence Write Markdown with live split preview, Mermaid diagrams, KaTeX/LaTeX math, and 190+ code languages — all in one macro, free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=enhanced-markdown-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [markdown](/blog/tags/markdown.md) * [ai](/blog/tags/ai.md) * [documentation](/blog/tags/documentation.md) * [confluence](/blog/tags/confluence.md) * [devtools](/blog/tags/devtools.md) --- # Markdown Code Blocks in Confluence — 190+ Languages September 24, 2026 · 4 min read [NGPilot](https://ngpilot.com) Every engineering page in Confluence eventually holds code — a curl from the runbook, the config that fixed the incident, the query the dashboard runs. And every one of those snippets has three natural enemies: the language dropdown in the macro dialog, the paste that loses its indentation, and the reader who cannot copy the thing without dragging across line numbers. Markdown fences solve all three, because they make the code block *text you type* instead of an object you configure. ` ```bash `, paste, ` ``` ` — done, highlighted, copyable. This guide shows the syntax, the theming behavior, and when fences beat the native macro. **Quick answer:** To add code blocks in Confluence with Markdown, install [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence) and use fenced blocks in its macro: ` ```java `, ` ```python `, ` ```bash ` — 190+ languages highlighted via highlight.js, GitHub light/dark themes that follow the page, and a copy button for every reader. Free for up to 10 users. ## The Syntax — One Fence, One Language Tag[​](#the-syntax--one-fence-one-language-tag "Direct link to The Syntax — One Fence, One Language Tag") The whole grammar is the fence tag: ```` ```bash pnpm install && forge deploy ``` ```` Three properties make this the fastest code-block route in Confluence: 1. **The tag selects the highlighter.** `java`, `python`, `sql`, `yaml`, `diff` — 190+ languages via highlight.js. No dropdown, no dialog, no mouse. 2. **It pastes clean from anywhere.** Code from a terminal, an editor, or a GitHub README carries its own fence — drop it in as-is. 3. **It stays portable.** Copy the fence back out and it works in a README, a PR description, or an LLM prompt. The block is text; the rendering is a property of the page, not the snippet. ## What the Render Gives Readers[​](#what-the-render-gives-readers "Direct link to What the Render Gives Readers") The published block is not just colored text: * **GitHub light and dark themes**, picked to match Confluence's palette — and the block follows the page theme automatically, so dark-mode readers get dark code instead of a white rectangle. * **A copy button on every block** — one click onto the clipboard, no gutter-number cleanup, works for read-only viewers. * **Live re-render while editing** — the split preview updates as you type, so a half-typed snippet never renders as a broken artifact. ## Copy-Paste Examples for the Four Usual Suspects[​](#copy-paste-examples-for-the-four-usual-suspects "Direct link to Copy-Paste Examples for the Four Usual Suspects") A runbook command (`bash`), a config (`yaml`), a query (`sql`), and a bug report (`diff`): ```` ```bash curl -s -H "Authorization: Bearer $TOKEN" \ https://api.example.com/v2/deployments?limit=5 ``` ```yaml service: replicas: 3 resources: requests: { cpu: "500m", memory: "512Mi" } ``` ```sql SELECT status, count(*) AS n FROM deployments WHERE created_at > now() - interval '7 days' GROUP BY status ORDER BY n DESC; ``` ```diff - timeout: 30 + timeout: 90 + retry: { max_attempts: 3 } ``` ```` The `diff` fence is the quiet hero — before/after config changes render red and green, which turns "we changed the timeout" into something a reader can see. ## Fences vs the Native Code Macro[​](#fences-vs-the-native-code-macro "Direct link to Fences vs the Native Code Macro") Both exist; they optimize for different moments: | Moment | Use | | ------------------------------------------ | ------------------------------------------ | | Page is code-heavy, authored like a README | Markdown fences — typing speed, no dialogs | | Single snippet on an otherwise-visual page | Native macro — no Markdown macro needed | | Snippet must live on GitHub too | Fences — same syntax in both places | | Before/after config change | `diff` fence — color-coded in one block | The honest rule: the native macro is fine for one block. The moment a page holds three snippets — or the snippet also lives in a repo — fences win, because the block is text and text travels. ## Runbook Snippet, Start to Finish[​](#runbook-snippet-start-to-finish "Direct link to Runbook Snippet, Start to Finish") The full loop, end to end: install [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence), type `/markdown` on the runbook page, paste the `bash` fence above, and republish. The next on-call reads highlighted, theme-correct, one-click-copyable code — and when the endpoint changes, you edit one line of text instead of re-screenshotting a block. Free for up to 10 users. ## Related Guides[​](#related-guides "Direct link to Related Guides") * [Advanced Code Block Features in Confluence](/blog/advanced-code-blocks-confluence.md) — the macro route: performance tuning and per-block options * [Display JSON, XML and Code in Confluence](/blog/display-json-xml-code-in-confluence.md) — structured payloads on documentation pages * [Markdown FAQ: Syntax, Tables & Code Blocks in Confluence](/blog/faq-confluence-markdown-editor.md) — the cluster's reference page Try Modern Code Blocks for Confluence Monaco editor, 85+ languages (JSON, XML, YAML, SQL), 50+ themes, diff view, and auto dark/light mode — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-code-blocks-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [code-block](/blog/tags/code-block.md) * [syntax-highlighting](/blog/tags/syntax-highlighting.md) * [how-to](/blog/tags/how-to.md) * [developer-tools](/blog/tags/developer-tools.md) --- # Math Equations in Confluence: LaTeX & KaTeX via Markdown September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) Ask an engineer to document an algorithm in Confluence and watch what happens to the math: `O(n log n)` typed as plain text, `x²` pasted from a character map, and — for anything real — a screenshot from an online equation editor, blurry and already out of date. Confluence has no native LaTeX support, so every formula becomes either a compromise or an image. It does not have to. With a Markdown macro on the page, Confluence renders real LaTeX — inline `$...$`, display `$$...$$`, fenced blocks with full `align` environments — and the equation stays text: searchable, theme-consistent, editable in seconds. This guide gives you the syntax and copy-paste examples for all three routes. **Quick answer:** To write math in Confluence, install [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence) and use its Markdown macro. Inline math goes in `$...$`, display equations in `$$...$$`, and fenced blocks — ` ```katex ` for fast CSS rendering or ` ```math ` for full LaTeX via bundled MathJax, including `\begin{align}` and AMS packages. All examples below are copy-paste ready. Free for up to 10 users. ## Why Equations-as-Images Fails Engineering Docs[​](#why-equations-as-images-fails-engineering-docs "Direct link to Why Equations-as-Images Fails Engineering Docs") A screenshot of a formula is where documentation goes to die: * **It is not text.** Search cannot find it, an AI assistant summarizing the space cannot read it, and a copy-paste into a ticket loses it. * **It is instantly stale.** The doc changes, the screenshot does not. Nobody re-runs the export toolchain for a sign flip. * **It looks wrong.** Different sizes, different fonts, white boxes on dark theme — every one a small tax on the reader's trust. Rendered math fixes all three at once, because it is *typeset text*. The formula participates in the page — it inherits the theme, it edits like everything else, and `grep`-style tools (and LLMs) can see it. ## Inline Math — the $...$ Workhorse[​](#inline-math--the--workhorse "Direct link to Inline Math — the $...$ Workhorse") Anything you would set in prose goes in single dollars. Here is a real spec sentence — paste it into the macro: ``` The p95 latency SLO is $300\,\text{ms}$ at the edge. The retry budget is $2n + 1$ attempts per request, and the scheduler stays $O(n \log n)$ with $k$ workers. ``` Inline math typesets everywhere Markdown flows — sentences, **table cells**, list items, even headings. That last part is the spec-doc unlock: a requirements table can carry `$O(n \log n)$` or `$p < 0.05$` beside the prose with no images and no alignment hacks. ## Display Equations — $$...$$ for the One That Matters[​](#display-equations---for-the-one-that-matters "Direct link to Display Equations — $$...$$ for the One That Matters") When the equation *is* the paragraph, double dollars center it. Say your section explains an availability SLO and what it implies: ``` A 99.9% availability SLO over a 30-day month allows $$ 2{,}592{,}000\,\text{s} \times (1 - 0.999) = 43.2\,\text{min} $$ of total downtime — everything else in the section is about spending it well. ``` That paragraph renders as: ![Display equation rendered in Confluence: a 99.9% SLO allows 43.2 minutes of downtime per month](/assets/images/tex-display-budget-4608e6333762d243f26f1bcd6be4ccaa.svg) Use display math for the one formula a section exists to explain, and keep it rare — a page where every line is a display equation reads like a textbook, not a spec. ## Fenced Blocks — KaTeX for Speed, MathJax for Full LaTeX[​](#fenced-blocks--katex-for-speed-mathjax-for-full-latex "Direct link to Fenced Blocks — KaTeX for Speed, MathJax for Full LaTeX") For multi-line work, the macro takes fenced blocks, and the fence keyword chooses the engine: | Fence | Engine | Use when | | --------------------------------------- | ------------------------- | ---------------------------------------------------------- | | ` ```katex ` | KaTeX (CSS-based) | Instant rendering, everyday equations | | ` ```math ` / ` ```tex ` / ` ```latex ` | MathJax (bundled, no CDN) | Full LaTeX grammar — `align`, AMS packages, exotic symbols | The aligned derivation is the workhorse: an error-budget check after an incident. Paste this into a ` ```math ` fence: ``` \begin{align} \text{monthly budget} &= 43.2\,\text{min} \quad (99.9\%\ \text{SLO}) \\ \text{Sep 18 outage} &= -31.6\,\text{min} \\ \text{remaining} &= 43.2 - 31.6 = 11.6\,\text{min} \\ \text{budget left} &\approx 27\% \;\Rightarrow\; \text{freeze risky deploys} \end{align} ``` And here is that block rendered on the page: ![Aligned derivation rendered in Confluence: error budget after an outage, ending at a deploy freeze](/assets/images/tex-error-budget-09d50e5874b9cb9e1601a1b2c8a241ba.svg) Every step on its own row, the relations running down one column — the derivation reads top-to-bottom like a whiteboard photo taken by someone organized. Swap in your own SLO numbers and it edits in plain text — no re-exporting anything when the outage math changes. ## Copy-Paste Starter Kit[​](#copy-paste-starter-kit "Direct link to Copy-Paste Starter Kit") Three patterns that cover most engineering docs: **SLO bound in a sentence** (inline): `Error rate stays below $0.1\%$ while the burn rate is $< 2\times$.` **Model quality** (KaTeX fence) — precision and F1 for an eval report: ``` P = \frac{TP}{TP + FP} \qquad F_1 = \frac{2 \cdot P \cdot R}{P + R} ``` ![Precision and F1 formulas rendered in Confluence](/assets/images/tex-precision-f1-b279206279b4754fb608ffba3811f52a.svg) **Aligned derivation** (MathJax fence): the error-budget block above — swap in your own numbers. All three survive copy-paste between pages, which is more than any screenshot can say. ## Which Route for Which Equation?[​](#which-route-for-which-equation "Direct link to Which Route for Which Equation?") | Need | Syntax | Renders via | | -------------------------------------------- | --------------------- | ------------- | | Symbol in a sentence, table cell, or heading | `$...$` | KaTeX inline | | The one centered formula of a section | `$$...$$` | KaTeX display | | Multi-line derivation with aligned operators | ` ```math ` + `align` | MathJax | | Quick common equations, fastest render | ` ```katex ` | KaTeX | The pattern to remember: dollars for prose, fences for blocks, `katex` for speed, `math` for the full LaTeX grammar. Install [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence), paste the `align` example into your next spec, and retire the screenshot pipeline. ## Related Guides[​](#related-guides "Direct link to Related Guides") * [How to Write Markdown in Confluence](/blog/how-to-write-markdown-in-confluence.md) — the base syntax the math lives inside * [Create Mermaid Diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md) — the same macro renders diagrams from fenced blocks * [Enhanced Markdown for Confluence](/apps/enhanced-markdown-for-confluence.md) — full app details: split preview, tables, code, math Try Enhanced Markdown for Confluence Write Markdown with live split preview, Mermaid diagrams, KaTeX/LaTeX math, and 190+ code languages — all in one macro, free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=enhanced-markdown-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [latex](/blog/tags/latex.md) * [katex](/blog/tags/katex.md) * [mathjax](/blog/tags/mathjax.md) * [math](/blog/tags/math.md) * [how-to](/blog/tags/how-to.md) * [engineering](/blog/tags/engineering.md) --- # Meeting Notes in Confluence with Markdown (Copy-Paste Template) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) Meeting notes fail in one of two directions: they are so informal that nobody can find the decision a month later, or so formal that nobody takes them at all. The Confluence editor quietly encourages the second — formatting dialogs are the enemy of live note-taking. Markdown flips it. In a split-pane editor, notes are keystrokes: two characters for a heading, pipes for a table row, backticks for a snippet — and the rendered page assembles itself in the right pane while you type. This guide ships the template and the habits that make notes pages worth opening later. **Quick answer:** To run meeting notes in Confluence with Markdown, install [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence), paste the template below into a Markdown macro, and take live notes in the split-pane view — headings for sections, tables for decisions and actions, code fences for snippets. Save it as a page template and every meeting starts structured. Free for up to 10 users. ## The Template[​](#the-template "Direct link to The Template") Paste this into the macro, save the page as a team template, and never invent structure again: ```` # Payment retry — design sync, 2026-09-24 ## Attendees - A. Chen (payments, owner) - R. Iyer (platform) - S. Okafor (support) ## Context Retry storms after the provider outage on 09-18; decide the retry policy. ## Decisions | # | Decision | Owner | |---|----------|-------| | D1 | Cap retries at 3 with exponential backoff | A. Chen | | D2 | Dead-letter after final failure, alert #payments | R. Iyer | ## Actions | Action | Owner | Due | Link | |--------|-------|-----|------| | Implement backoff cap | A. Chen | 09-26 | [PAY-4821](https://your.atlassian.net/browse/PAY-4821) | | Add dead-letter queue | R. Iyer | 09-29 | — | | Draft support comms | S. Okafor | 09-25 | — | ## Raw notes - 09-18 outage: provider hung 30s, our retry had no deadline (see postmortem) - Option A: circuit breaker — defer, needs platform review - Option B chosen: cap + backoff, smallest change that stops the storm ```sql -- failing query from the incident, for whoever picks up PAY-4821 SELECT id FROM retries WHERE attempts >= 3 AND status = 'pending'; ``` ```` Five sections, fixed order, ten minutes to fill. The code fence at the bottom is deliberate — the incident's failing query lives *in* the notes, highlighted and copyable, so the action item's owner never asks "which query was it?" ## Why the Split Pane Beats a Formatting Toolbar[​](#why-the-split-pane-beats-a-formatting-toolbar "Direct link to Why the Split Pane Beats a Formatting Toolbar") Live note-taking is a typing problem. Every formatting dialog is an interruption, and interrupted notes skip the boring-but-important rows. In the Markdown macro's split view: * `## Decisions` becomes a real heading as you type it — no style picker. * A table is pipes while talking: `| D1 | Cap retries at 3 | A. Chen |` lands as a rendered row. * **Bidirectional scroll sync** keeps source and preview aligned when the page grows past one screen. * Snippets paste as fences without leaving the keyboard. The right pane means the page looks finished *during* the meeting — which quietly changes who reads it afterwards. ## The Habits That Make Notes Worth Opening[​](#the-habits-that-make-notes-worth-opening "Direct link to The Habits That Make Notes Worth Opening") The template is the floor; these three habits are the actual system: 1. **Decisions get numbers** (D1, D2…). "The retry decision" is ambiguous across twenty pages; "D2 from payment-retry 09-24" is not. Cross-reference by ID. 2. **Actions get links the moment tickets exist.** The Link column starts as `—` and gains URLs before the meeting ends. An action without a link is a wish. 3. **Raw notes stay raw.** Dead ends, half-ideas, the option you rejected — they stay, chronologically, at the bottom. Next quarter, "why didn't we do circuit breakers?" deserves the real answer. ## Leveling Up: Diagrams and Mind Maps in the Same Page[​](#leveling-up-diagrams-and-mind-maps-in-the-same-page "Direct link to Leveling Up: Diagrams and Mind Maps in the Same Page") The same macro renders more than tables. A Mermaid fence gives a decision flow its picture; a mind map captures a brainstorm without a whiteboard photo. Both stay text — editable when the plan changes instead of frozen as an image. For the syntax, see [mind maps in Confluence with Markdown](/blog/markdown-mind-map-confluence.md) and [creating Mermaid diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md). ## Which Notes Format for Which Meeting?[​](#which-notes-format-for-which-meeting "Direct link to Which Notes Format for Which Meeting?") | Meeting | Format in the template | | ------------------------------ | ---------------------------------------------------------- | | Design sync / decision meeting | Full template — decisions and actions tables are the point | | Standup-adjacent syncs | Context + Actions only, five lines, done | | Incident war room | Raw notes first; decisions table filled at the close | | Brainstorm | Mind map fence + raw notes; decisions table stays empty | Install [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence), paste the template, and let the next meeting's page build itself while you type. Free for up to 10 users. ## Related Guides[​](#related-guides "Direct link to Related Guides") * [Mind Maps in Confluence with Markdown](/blog/markdown-mind-map-confluence.md) — the brainstorm capture that pairs with these notes * [Markdown Tables in Confluence](/blog/confluence-markdown-tables.md) — deep-dive on the decisions/actions table syntax * [How to Write Markdown in Confluence](/blog/how-to-write-markdown-in-confluence.md) — the base syntax guide Try Enhanced Markdown for Confluence Write Markdown with live split preview, Mermaid diagrams, KaTeX/LaTeX math, and 190+ code languages — all in one macro, free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=enhanced-markdown-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [meeting-notes](/blog/tags/meeting-notes.md) * [template](/blog/tags/template.md) * [how-to](/blog/tags/how-to.md) * [productivity](/blog/tags/productivity.md) * [engineering](/blog/tags/engineering.md) --- # From Markdown Notes to a Mind Map in Confluence — No Drawing September 18, 2026 · 4 min read [NGPilot](https://ngpilot.com) Meeting notes, project briefs, planning docs — most Confluence pages already start life as a Markdown-ish outline: a title, some headings, bullets underneath. A mind map is just that outline seen from above. This guide shows how to get from the outline you already have to an interactive mind map on the page, without drawing anything and without learning diagram syntax. **Quick answer:** Install [Markdown Mind Maps for Confluence](https://marketplace.atlassian.com/apps/588881414/), type **/mind map** on any page, and paste a Markdown outline — headings become branches, bullets become leaves, and a live preview renders the interactive map as you type. No canvas, no drag-and-drop, no syntax to learn. ## Why an Outline Beats a Canvas for Most Mind Maps[​](#why-an-outline-beats-a-canvas-for-most-mind-maps "Direct link to Why an Outline Beats a Canvas for Most Mind Maps") Drawing tools make you do the structuring twice: once in your head, once with your mouse. Dragging nodes, aligning branches, re-routing connectors after every edit — that's layout work, not thinking work. And a drawn mind map is a picture: six months later, nobody edits it, because changing one branch means re-arranging everything around it. A Markdown outline has none of those problems: * **You already know the syntax** — headings and bullets, the same thing you type every day * **Editing is text** — add a bullet, the map grows a leaf. No re-layout * **It stays diffable** — page history shows exactly which branch changed and when * **Content first** — the outline is reusable as plain text anywhere else: an issue description, an AI prompt, a doc skeleton If you want a *drawn* mind map — free-form, artistic, canvas-first — a whiteboard is the right tool. If you want a mind map that *is your document*, read on. ## How to Turn a Markdown Outline Into a Mind Map[​](#how-to-turn-a-markdown-outline-into-a-mind-map "Direct link to How to Turn a Markdown Outline Into a Mind Map") ### Step 1 — Insert the macro[​](#step-1--insert-the-macro "Direct link to Step 1 — Insert the macro") Edit a Confluence page, type **/mind map**, and select **Markdown Mind Maps for Confluence**. The editor opens with a Markdown pane on the left and a live preview on the right. ### Step 2 — Paste or type your outline[​](#step-2--paste-or-type-your-outline "Direct link to Step 2 — Paste or type your outline") The mapping is what you'd guess: ``` # Project Kickoff ## Vision - Launch fast - Measure everything ## Team - Backend: 2 engineers - Frontend: 1 engineer - Design: shared with platform ## Risks - Vendor API rate limits - Holiday freeze in December ``` * `#` title → the central topic * `##` headings → branches * bullets → leaves * `###` headings → sub-branches, nested as deep as your outline goes The preview updates as you type — type a `## Risks` heading and the branch is already there before you finish the sentence. ### Step 3 — Set how much readers see first[​](#step-3--set-how-much-readers-see-first "Direct link to Step 3 — Set how much readers see first") Two options matter on real pages: * **Initial expand** — Level 1–3 keeps big maps readable at a glance (readers click into branches); **Expand all** for small maps where the whole shape is the message. * **Alignment** — **Center** for the classic radial look; **Left** when the map should read like a document outline, which suits meeting notes and nested plans. ### Step 4 — Save[​](#step-4--save "Direct link to Step 4 — Save") Click **Save**, publish the page, and the interactive map renders inline. Readers click any node to expand or collapse its branch, and the map follows each reader's light/dark theme automatically — no per-reader configuration. ## Start From a Template When the Page Is Blank[​](#start-from-a-template-when-the-page-is-blank "Direct link to Start From a Template When the Page Is Blank") Ten built-in outlines cover the common planning motions — pick one from the options bar and trim it: Project Kickoff · Backlog · Brainstorm · API Design · Meeting Notes · Org Chart · Roadmap · Product Launch · Error Handling · Sprint Planning The **Sprint Planning** template, for example, arrives as goal → capacity → stories by priority → risks → definition of done. Deleting the parts you don't need is faster than typing the parts you do. ## Which Approach Should You Use?[​](#which-approach-should-you-use "Direct link to Which Approach Should You Use?") | Need | Use | | -------------------------------------------------------------------------- | -------------------------------------------------------------------- | | A mind map that *is* the page content, editable as text | Markdown Mind Maps (this guide) | | Free-form canvas sketching in a live session | Confluence whiteboard | | A mind map inside Mermaid code, alongside flowcharts and sequence diagrams | [Mermaid mindmap syntax](/blog/how-to-create-mindmaps-confluence.md) | All three produce a diagram — the difference is what you maintain afterward. Text-derived maps stay editable forever; drawn ones go stale. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Mermaid mind maps in Confluence](/blog/how-to-create-mindmaps-confluence.md) — the syntax-driven way, with node shapes and copy-paste examples * [Markdown Mind Maps for Confluence](/apps/markdown-mind-maps-for-confluence.md) — full documentation: options, templates, and limitations * [Create Mermaid diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md) — flowcharts, sequence diagrams, gantt charts and more * [Gantt charts in Confluence](/blog/how-to-create-gantt-charts-confluence.md) — turn the same planning notes into a timeline Your next mind map is already written — it's the outline sitting in your last meeting-notes page. Paste it into [Markdown Mind Maps for Confluence](https://marketplace.atlassian.com/apps/588881414/) and see it rendered in about the time it takes to install the app. Try Enhanced Markdown for Confluence Write Markdown with live split preview, Mermaid diagrams, KaTeX/LaTeX math, and 190+ code languages — all in one macro, free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=enhanced-markdown-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mindmap](/blog/tags/mindmap.md) * [markdown](/blog/tags/markdown.md) * [how-to](/blog/tags/how-to.md) * [diagrams](/blog/tags/diagrams.md) * [brainstorming](/blog/tags/brainstorming.md) --- # Import Markdown into Confluence — 3 Methods Compared (2026) May 10, 2026 · 5 min read [NGPilot](https://ngpilot.com) Who should read this * Development teams importing GitHub READMEs to Confluence * Documentation engineers migrating Markdown file sets * Anyone who wants to write Markdown directly in Confluence What you'll learn 1. Comparison of three Markdown import methods 2. How to choose the best tool for your use case 3. Step-by-step setup instructions Many teams have documentation in Markdown format (GitHub READMEs, API docs, developer guides) and need to bring it into Confluence. Confluence doesn't have a native Markdown import feature, but there are three ways to get Markdown content into Confluence pages. ## Method 1: Enhanced Markdown editor (recommended)[​](#method-1-enhanced-markdown-editor-recommended "Direct link to Method 1: Enhanced Markdown editor (recommended)") [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?hosting=cloud\&tab=overview) adds a Markdown editor directly into Confluence. You can write in Markdown or paste existing Markdown files, and the content renders as standard Confluence pages. ### How to import Markdown into Confluence[​](#how-to-import-markdown-into-confluence "Direct link to How to import Markdown into Confluence") 1. Install [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?hosting=cloud\&tab=overview) (free for up to 10 users) 2. Create a new Confluence page 3. Type `/enhanced markdown` in the editor and select the macro 4. **Paste your Markdown content** — supports CommonMark and GFM 5. Switch to WYSIWYG mode to preview the rendered result 6. Click **Publish** — the content becomes standard Confluence content ### What Markdown features are supported[​](#what-markdown-features-are-supported "Direct link to What Markdown features are supported") * **Headings** (H1–H6 with `#` syntax) * **Bold, italic, strikethrough** (`**bold**`, `*italic*`, `~~strike~~`) * **Lists** (ordered and unordered, nested) * **Fenced code blocks** with syntax highlighting (triple backticks + language) * **Tables** (pipe-separated with alignment) * **Task lists** (`- [ ]` and `- [x]`) * **Links and images** * **Blockquotes** (`>`) * **Horizontal rules** (`---`) * **PlantUML diagrams** inline * **Charts** inline Read the full tutorial: [How to write Markdown in Confluence](/blog/how-to-write-markdown-in-confluence.md). ## Method 2: Modern Importer Exporter[​](#method-2-modern-importer-exporter "Direct link to Method 2: Modern Importer Exporter") [Modern Importer Exporter for Confluence](https://marketplace.atlassian.com/apps/977066696/modern-importer-exporter-for-confluence?hosting=cloud\&tab=overview) handles bulk content migration, including converting Markdown files into Confluence pages. **Best for:** Migrating an entire documentation set from a Markdown-based system (GitHub wiki, GitBook, Hugo, Jekyll) into Confluence. Read more: [Confluence import/export comparison](/blog/confluence-import-export-comparison.md). ## Method 3: Copy-paste from GitHub[​](#method-3-copy-paste-from-github "Direct link to Method 3: Copy-paste from GitHub") For small amounts of content, you can copy Markdown text from GitHub and paste it into the Enhanced Markdown macro. This works well for: * Individual README files * Pull request descriptions with Markdown tables * Issue templates * Changelog entries ## Paste Markdown into Confluence without an app[​](#paste-markdown-into-confluence-without-an-app "Direct link to Paste Markdown into Confluence without an app") For a one-off snippet, Confluence has two built-in routes — useful to know, limited for real docs: * **Paste into the editor** — Confluence converts basic syntax on paste: headings, bold, lists, links. Tables and fenced code blocks routinely break or arrive as plain text. * **Insert > Markup** (type `/markup` in the editor) — a dialog that converts pasted Markdown or wiki markup into editor content. Handles more than paste does, but still drops advanced constructs like task lists and syntax-highlighted code. If you paste Markdown into Confluence regularly, both routes cost more than they save — the [Enhanced Markdown macro](#method-1-enhanced-markdown-editor-recommended) keeps the source editable and re-renders on save instead of converting once and losing the original. ## Markdown to Confluence converter comparison[​](#markdown-to-confluence-converter-comparison "Direct link to Markdown to Confluence converter comparison") | Method | Best For | Bulk Import | Live Editing | | ------------------------ | ----------------------------------- | ----------- | ------------ | | Enhanced Markdown | Writing & pasting Markdown in pages | No | Yes | | Modern Importer Exporter | Migrating entire doc sets | Yes | No | | Copy-paste | Small snippets | No | Yes | ## Why you need a Markdown solution for Confluence[​](#why-you-need-a-markdown-solution-for-confluence "Direct link to Why you need a Markdown solution for Confluence") Confluence's native editor is WYSIWYG only. If your team writes documentation in Markdown (which most developer teams do), you need a way to: 1. **Paste existing Markdown** without losing formatting 2. **Write new content in Markdown** without learning the visual editor 3. **Maintain Markdown compatibility** for teams that use both GitHub and Confluence Enhanced Markdown solves all three by adding a full Markdown editor inside every Confluence page. ## Can Confluence render Markdown natively?[​](#can-confluence-render-markdown-natively "Direct link to Can Confluence render Markdown natively?") No. Confluence does not have native Markdown rendering. The editor supports a few Markdown shortcuts (typing `#` + space for headings, `-` + space for bullets) but these are limited keyboard shortcuts, not full Markdown support. For complete Markdown support including tables, code blocks, and task lists, install [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?hosting=cloud\&tab=overview). ## Related resources[​](#related-resources "Direct link to Related resources") * [Enhanced Markdown — marketplace](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?hosting=cloud\&tab=overview) | [documentation](/apps/enhanced-markdown-for-confluence.md) * [How to write Markdown in Confluence](/blog/how-to-write-markdown-in-confluence.md) * [Confluence Markdown tables guide](/blog/confluence-markdown-tables.md) * [Confluence Markdown vs WYSIWYG FAQ](/blog/faq-confluence-markdown-vs-wysiwyg.md) * [Confluence Markdown editor comparison](/blog/confluence-markdown-editor-comparison.md) * [Confluence import/export comparison](/blog/confluence-import-export-comparison.md) ## More Related Guides[​](#more-related-guides "Direct link to More Related Guides") * [How to write Markdown in Confluence](/blog/how-to-write-markdown-in-confluence.md) — Write Markdown directly in Confluence * [Confluence Markdown tables](/blog/confluence-markdown-tables.md) — Create and format tables * [Enhanced Markdown documentation](/apps/enhanced-markdown-for-confluence.md) — Complete feature guide Try Enhanced Markdown for Confluence Write Markdown with live split preview, Mermaid diagrams, KaTeX/LaTeX math, and 190+ code languages — all in one macro, free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=enhanced-markdown-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [import](/blog/tags/import.md) * [converter](/blog/tags/converter.md) * [enhanced-markdown](/blog/tags/enhanced-markdown.md) * [import-export](/blog/tags/import-export.md) --- # Atlassian Marketplace App Selection Criteria for Enterprise August 2, 2026 · 7 min read [NGPilot](https://ngpilot.com) Quick Answer Enterprise teams evaluating Atlassian Marketplace apps should check ten criteria: Cloud Fortified status, Forge vs Connect framework, OAuth scopes, privacy disclosure, Bug Bounty participation, data residency, vendor viability, support SLA, adoption signals, and release cadence. This guide walks through each so your security and procurement teams can make confident decisions. What you'll learn 1. The 10 criteria every enterprise should check before approving an app 2. How to assess vendor viability and long-term risk 3. What documentation to request from vendors during procurement 4. A scoring rubric you can apply to any app in under 10 minutes Installing a Marketplace app in an enterprise Atlassian environment is not the same as installing a browser extension. The app gains access to your Jira issues, Confluence pages, and potentially your entire collaboration surface — so the evaluation process needs to be rigorous. This guide covers the ten criteria that security, procurement, and IT teams should check before approving any app for enterprise deployment. ## Why enterprise app selection matters[​](#why-enterprise-app-selection-matters "Direct link to Why enterprise app selection matters") In a small team, installing a risky app is a recoverable mistake — you uninstall it and move on. In an enterprise, the stakes are higher: * **Data exposure** — an app with broad scopes can read sensitive issues, compliance data, and customer information. * **Compliance liability** — apps that store data off-platform or share it with subprocessors can violate GDPR, HIPAA, or SOC 2 commitments. * **Operational risk** — an unmaintained app can break during Atlassian platform updates, disrupting workflows for thousands of users. * **Audit trail** — enterprises need to justify every app installation to auditors and security reviewers. A structured evaluation process turns "is this app okay?" from a gut-feeling decision into a repeatable, defensible assessment. ## The 10 enterprise evaluation criteria[​](#the-10-enterprise-evaluation-criteria "Direct link to The 10 enterprise evaluation criteria") ### 1. Cloud Fortified status[​](#1-cloud-fortified-status "Direct link to 1. Cloud Fortified status") Cloud Fortified is Atlassian's trust tier. Apps that earn it have completed the Privacy and Security disclosure tab, participate in the Bug Bounty Program, and meet reliability and support requirements. As of 2026, new Cloud Fortified designations require Forge. **If an app has this badge, a substantial part of your security review is already done.** ### 2. Forge vs Connect[​](#2-forge-vs-connect "Direct link to 2. Forge vs Connect") The framework determines where the app runs and who controls your data. **Forge apps** run on Atlassian infrastructure with platform-enforced permissions — your data never leaves the Atlassian tenant. **Connect apps** run on vendor-hosted servers, where the vendor is responsible for encryption, patching, and breach response. For enterprise deployment, prefer Forge. For a deeper treatment, see our [Forge vs Connect guide](/blog/forge-vs-connect-atlassian-admins-2026.md). ### 3. OAuth scopes and permissions[​](#3-oauth-scopes-and-permissions "Direct link to 3. OAuth scopes and permissions") Review the scopes the app requests at install time. The principle is least privilege: the app should request only the scopes it needs for its function. A diagraming app requesting only `read:confluence-content` and `write:confluence-content` is well-scoped. The same app requesting admin-level scopes or user management access is a red flag. **Reject apps whose scopes exceed their stated purpose.** ### 4. Privacy and data handling disclosure[​](#4-privacy-and-data-handling-disclosure "Direct link to 4. Privacy and data handling disclosure") The Privacy and Security tab on the Marketplace listing is where the vendor declares what data the app collects, where it is stored, how long it is retained, and whether it is shared with third parties. Check: * **Storage location** — Atlassian (Forge) vs vendor infrastructure (Connect) vs third-party subprocessor * **Data retention** — does the vendor delete data on uninstall? * **Third-party sharing** — analytics, AI, or advertising subprocessors must be named ### 5. Bug Bounty participation[​](#5-bug-bounty-participation "Direct link to 5. Bug Bounty participation") Apps in the Marketplace Security Bug Bounty Program (hosted on Bugcrowd) are externally tested by security researchers. The vendor pays rewards for valid vulnerability findings. This is an active, ongoing security practice — not a one-time certification. **Look for the green checkmark on the listing.** ### 6. Data residency[​](#6-data-residency "Direct link to 6. Data residency") For regulated industries and government customers, data residency is non-negotiable. Confirm where the app stores and processes data: * Forge apps store data on Atlassian infrastructure in the region your tenant is provisioned in * Connect apps may store data anywhere the vendor operates — check the privacy disclosure * Apps that transmit data to third countries may require additional Data Processing Agreements ### 7. Vendor viability[​](#7-vendor-viability "Direct link to 7. Vendor viability") An app is only as reliable as the company behind it. Assess: * **Company size and funding** — a vendor with 2 employees and no funding is a higher risk than an established company * **Years in business** — how long has the vendor been on the Marketplace? * **Response to reviews** — does the vendor actively respond to support tickets and negative reviews? * **Release cadence** — check the versions tab; a healthy app ships updates regularly * **Multiple apps** — vendors with several successful apps demonstrate sustained commitment ### 8. Support SLA[​](#8-support-sla "Direct link to 8. Support SLA") Enterprise teams need guaranteed response times. Check: * Does the vendor publish an SLA? * What is the response time for paid vs free tiers? * Is there a dedicated enterprise support channel? * How does the vendor handle severity-1 incidents? ### 9. Adoption signals[​](#9-adoption-signals "Direct link to 9. Adoption signals") Real-world adoption is a strong indicator of reliability: * **Install count** — thousands of installs means the app has been stress-tested * **Star rating** — look at the distribution, not just the average; read negative reviews for failure modes * **Enterprise customers** — does the vendor reference enterprise or government customers? * **Active user base** — is the app growing or declining? ### 10. Release cadence and maintenance[​](#10-release-cadence-and-maintenance "Direct link to 10. Release cadence and maintenance") Check the versions tab on the Marketplace listing: * **Recent updates** — has the app been updated in the last 6 months? * **Atlassian platform compatibility** — does it support the latest Cloud version? * **Changelog quality** — does the vendor document what changed in each release? * **Bug fix responsiveness** — are reported issues addressed in subsequent releases? An app that has not been updated in over a year is a maintenance risk — it may break on the next Atlassian platform update with no fix coming. ## A scoring rubric[​](#a-scoring-rubric "Direct link to A scoring rubric") Apply this simple scoring to any app: | Criterion | Pass (2) | Partial (1) | Fail (0) | | ------------------ | -------------------------- | -------------------- | --------------------- | | Cloud Fortified | Yes | On track | No | | Framework | Forge | Connect, scoped | Connect, broad scopes | | Scopes | Minimal, justified | Moderate | Excessive | | Privacy disclosure | Complete | Partial | Missing | | Bug Bounty | Yes | — | No | | Data residency | Matches requirements | — | Does not match | | Vendor viability | Established, active | Small but responsive | Unknown, inactive | | Support SLA | Published, enterprise | Email only | None | | Adoption | 1,000+ installs, 4+ stars | 100+ installs | Under 100 installs | | Release cadence | Updated under 3 months ago | Under 12 months | Over 12 months | **Score 16-20:** Low risk — approve with standard review. **Score 10-15:** Moderate risk — require vendor questionnaire. **Score under 10:** High risk — require executive sign-off or reject. ## Documentation to request from vendors[​](#documentation-to-request-from-vendors "Direct link to Documentation to request from vendors") For moderate-to-high risk apps, send this questionnaire: 1. Where is our data stored, and who controls the infrastructure? 2. What subprocessors do you use, and for what purpose? 3. What is your incident response SLA? 4. Do you retain data after uninstall, and for how long? 5. Can you justify each OAuth scope the app requests? 6. Are you Cloud Fortified, and if not, what is your timeline? 7. Do you have SOC 2, ISO 27001, or equivalent certifications? 8. How do you handle data residency for our region? ## Explore enterprise-ready apps[​](#explore-enterprise-ready-apps "Direct link to Explore enterprise-ready apps") All NGPILOT apps are built exclusively on Forge, store data on Atlassian infrastructure, and request only the scopes they need. Browse the [full catalog](/apps.md) or explore [solutions by scenario](/solutions.md) to find apps that meet enterprise requirements. Our [Trust Center](/trust.md) has the full security, privacy, and compliance details. ## Frequently Asked Questions[​](#frequently-asked-questions "Direct link to Frequently Asked Questions") ### How long should an enterprise app evaluation take?[​](#how-long-should-an-enterprise-app-evaluation-take "Direct link to How long should an enterprise app evaluation take?") With the scoring rubric above, a preliminary assessment takes under 10 minutes. A full vendor review with questionnaire responses typically takes 1-2 weeks, depending on vendor responsiveness. High-risk apps may require an additional security architecture review. ### Can we automate app evaluation?[​](#can-we-automate-app-evaluation "Direct link to Can we automate app evaluation?") Partially. Atlassian's Marketplace API exposes app metadata (install counts, ratings, Cloud Fortified status, scopes) that can be pulled programmatically. The qualitative criteria (privacy disclosure quality, vendor viability) still require human review. Some enterprises build internal app catalogs that pre-screen apps before they reach the evaluation stage. ### What if we need an app that fails several criteria?[​](#what-if-we-need-an-app-that-fails-several-criteria "Direct link to What if we need an app that fails several criteria?") Document the risk explicitly and require a compensating control: a data processing agreement, a stricter scope review, or a trial period in a sandbox environment. Sometimes the best option is to ask the vendor to address the gaps (e.g., pursue Cloud Fortified) before approval. *** *NGPILOT apps are built exclusively on Forge. Browse the [app catalog](/apps.md), explore [solutions](/solutions.md), or read our [Trust Center](/trust.md) for enterprise security details.* ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [atlassian](/blog/tags/atlassian.md) * [marketplace](/blog/tags/marketplace.md) * [enterprise](/blog/tags/enterprise.md) * [security](/blog/tags/security.md) * [procurement](/blog/tags/procurement.md) * [explained](/blog/tags/explained.md) --- # Mermaid 12 in Confluence & Jira: UML Use Case Diagrams and a New Look September 19, 2026 · 5 min read [NGPilot](https://ngpilot.com) Mermaid 12 is the biggest release the diagram language has had in years — and as of today it is live in all three NGPILOT diagram apps: **Enhanced Markdown for Confluence**, **Mermaid Plus Diagrams & AI Agent for Confluence**, and **Mermaid Plus Diagrams for Jira**. You get the headline feature immediately: **UML use case diagrams**, the diagram type Confluence and Jira teams have been asking for since requirements documents moved out of dedicated UML tools. **Quick answer:** Mermaid 12 adds UML use case diagrams (`usecase-beta`), a new default layout engine (ELK), and refreshed diagram styling — and all three NGPILOT diagram apps already run it. In [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence/), type a ` ```mermaid ` fence with `usecase-beta`; in [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/) and [Mermaid Plus Diagrams for Jira](https://marketplace.atlassian.com/apps/2658777397/mermaid-plus-diagrams-for-jira/), paste the same syntax into the diagram panel. Existing diagrams keep working unchanged. ## What's new in Mermaid 12[​](#whats-new-in-mermaid-12 "Direct link to What's new in Mermaid 12") | Change | What it means for your pages | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------- | | **UML use case diagrams** (`usecase-beta`) | The missing UML diagram type: actors, use cases, system boundaries, `include`/`extend`, notes — as text | | **ELK as the default layout engine** | Cleaner automatic layouts, especially for dense flowcharts and state machines | | **Refreshed default look** | New color palettes and styling for flowchart, state, and class diagrams | | **Backward compatible** | Existing diagram code renders unchanged; layout and colors may shift subtly | ## The headliner: use case diagrams as text[​](#the-headliner-use-case-diagrams-as-text "Direct link to The headliner: use case diagrams as text") A use case diagram answers one question: *who does what with the system, and what does what depend on what?* Until now, answering it in Confluence or Jira meant a drawing tool. With Mermaid 12 it's a code block — which means it's editable, diffable, and lives with the ticket or page it documents. Paste this into an Enhanced Markdown `mermaid` fence or a Mermaid Plus panel: ``` usecase-beta direction LR actor Customer actor Admin systemBoundary Store("Online Store") UC1("Browse Products") UC2("Checkout") end Customer --> UC1 Customer --> UC2 Admin --> UC2 UC2 ..> : include UC1 Admin --|> Customer note for UC1 "Available 24/7" ``` Reading it back: two actors, one system boundary, two use cases inside it. `UC2 ..> : include UC1` says checkout always includes browsing the catalog; `Admin --|> Customer` makes Admin a specialization of Customer. The note pins operational detail to the use case it belongs to. **Syntax pieces worth knowing:** * `actor Name` — a person or external system * `systemBoundary Id("Label") ... end` — groups the use cases of one system * `UC("Label")` — a use case (an ellipse in the render) * `-->` association, `..>` include, `--|>` generalization * `note for UC1 "text"` — annotation attached to a use case Because it's Mermaid — text, not a canvas — updating the flow when requirements change is a one-line edit, and the diagram re-renders with the page. ## What your existing diagrams will do[​](#what-your-existing-diagrams-will-do "Direct link to What your existing diagrams will do") Nothing dramatic, by design. Your flowcharts, sequence diagrams, gantt charts, and mind maps keep rendering exactly as before, syntactically. What you may notice: * **Layouts shift slightly** in dense graphs — ELK can route edges differently (usually better) * **Default colors are refreshed** — if your diagrams rely on default theming, they may read a touch differently; explicitly themed diagrams are unaffected * **The `-beta` suffix on `usecase-beta`** is Mermaid's convention for a new diagram type whose syntax may still evolve (the same path `architecture-beta` took) — safe to use, syntax may gain features before it stabilizes ## Where you get Mermaid 12[​](#where-you-get-mermaid-12 "Direct link to Where you get Mermaid 12") | App | Where the diagram lives | Try it | | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | ----------------------- | | [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence/) | Inline in any page, inside a ` ```mermaid ` fence, with live split preview | Free for up to 10 users | | [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/) | `/mermaid` macro with template picker and themes | Free for up to 10 users | | [Mermaid Plus Diagrams for Jira](https://marketplace.atlassian.com/apps/2658777397/mermaid-plus-diagrams-for-jira/) | Panel on every Jira issue — diagrams stay attached to the ticket | Free for up to 10 users | One syntax, three homes: the same `usecase-beta` block renders in Confluence pages, Confluence macros, and Jira issues. ## Common questions[​](#common-questions "Direct link to Common questions") **Why use case diagrams in a wiki and a tracker?** Because requirements live there. A use case diagram on the epic page or attached to the feature ticket gets seen in review; one exported from a UML tool gets stale in a drive nobody opens. **Can I combine this with the other Mermaid diagram types?** Yes — a page can hold a use case diagram for scope, a flowchart for the happy path, and a sequence diagram for one interaction, all from text. **Is `usecase-beta` final syntax?** It's beta by Mermaid's naming convention: feature-complete for actors, boundaries, include/extend, and notes, with syntax refinements possible before stabilization. Diagrams you build now may need small syntax touch-ups when it graduates — the usual trade for being early. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Create Mermaid diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md) — the step-by-step guide across all diagram families * [Mermaid diagrams on Jira issues](/blog/how-to-create-mermaid-diagrams-jira.md) — sequence, class, and settings for Jira panels * [All 30 Mermaid diagram types in Confluence](/blog/faq-mermaid-diagram-types-confluence.md) — the complete reference, now with use case diagrams joining the family * [Mermaid syntax cheat sheet](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md) — quick reference for every diagram type * [Paste Mermaid diagrams into Confluence](/blog/paste-mermaid-diagrams-into-confluence.md) — keeping repo Markdown and its Mermaid 12 fences intact when the docs live in Confluence * [Mermaid 12 release notes](https://github.com/mermaid-js/mermaid/releases) — the upstream changelog Mermaid 12 turns a UML modeling tool's job into a one-minute paste. Open a page or issue, drop in the `usecase-beta` example above, and your requirements have a diagram that edits as fast as the text around it. Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [jira](/blog/tags/jira.md) * [mermaid](/blog/tags/mermaid.md) * [diagrams](/blog/tags/diagrams.md) * [release-notes](/blog/tags/release-notes.md) * [use-case-diagram](/blog/tags/use-case-diagram.md) --- # Mermaid AI Agent for Confluence: Create, Update & Convert Diagrams by Chat October 7, 2026 · 5 min read [NGPilot](https://ngpilot.com) Confluence chat can write your page, summarize the thread, and answer questions about the space. What it couldn't do — until now — is draw. If you asked for "a flowchart of our deployment process," you got a text description of a flowchart, and someone still had to open an editor and build it. The AI agent in [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence) closes that gap: it creates, reads, updates, and converts Mermaid diagrams directly on Confluence pages and blog posts, from chat. **Quick answer:** Open Confluence chat on any page and describe the diagram — "make a sequence diagram of our login flow" renders a Mermaid diagram on the page. Follow-up prompts revise it in place, the agent can convert code blocks already on the page into rendered diagrams, and every diagram stays fully editable in the macro editor afterward. ## The four things the agent can do[​](#the-four-things-the-agent-can-do "Direct link to The four things the agent can do") | Verb | What you say | What happens | | ----------- | -------------------------------------------------- | ------------------------------------------------------------------- | | **Create** | "Make a flowchart of our deployment process" | A Mermaid diagram renders on the page, from your description | | **Read** | "What's in the architecture diagram on this page?" | The agent returns the diagram's source and version in chat | | **Update** | "Make this better" / "add a failure path" | The existing diagram is revised in place — macro settings preserved | | **Convert** | "Turn this code block into a diagram" | A Mermaid code block already on the page becomes a rendered diagram | The **convert** verb is the quiet workhorse: plenty of pages already carry Mermaid source in a code block, pasted from a repo or a PR review. Until now those blocks were dead text on the page — the agent turns each one into a living diagram without anyone re-pasting it into a macro. ## Walkthrough: from prompt to published diagram[​](#walkthrough-from-prompt-to-published-diagram "Direct link to Walkthrough: from prompt to published diagram") 1. **Install the app** from the [Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence) — free for up to 10 users. 2. **Open Confluence chat** on the page or blog post you're working on and describe what you need. Concrete prompts that work well: * *"Make a flowchart of our incident escalation path, from alert to postmortem."* * *"Draw a sequence diagram of the checkout service calling payments and inventory."* * *"Create an ER diagram for the orders and customers tables."* 3. **Iterate in chat.** Follow-ups like *"add a retry loop around the payment call"* or *"make this better"* update the diagram in place — you don't rebuild from scratch, and the macro's settings carry over. 4. **Verify the render.** The diagram lands on the page rendered, not as raw text — what you see in chat is what readers get. 5. **Fine-tune by hand if needed.** Click the diagram, select **Edit**, and the side-by-side editor opens: Mermaid source on one side, live preview on the other. ## Where you take over from the agent[​](#where-you-take-over-from-the-agent "Direct link to Where you take over from the agent") The agent is fast at first drafts and mechanical conversions. You stay in charge of the parts that need judgment: * **Exact layout and styling.** Themes, custom colors, and fonts are set in the macro editor — the same controls as before, unchanged. * **Sensitive diagrams.** For compliance or audit artifacts, review the source the same way you'd review any generated content. The source is plain Mermaid text, so the review is a diff, not a screenshot. * **Anything highly specific.** If the tenth revision still isn't right, editing the 5 lines of Mermaid directly is faster than describing the eleventh. That escape hatch is the point of the design: the agent and the editor share one source of truth. Nothing the agent produces is locked in, and nothing you hand-edit gets overwritten by chat later unless you ask for it. ## Not an agent-only app[​](#not-an-agent-only-app "Direct link to Not an agent-only app") The chat is one of two ways in. The classic editor is still there — type `/mermaid` in the editor, and you get: * **All 30 Mermaid v12 diagram types** — flowcharts, sequence, class, state, ER, Gantt, pie, C4, mindmaps, ZenUML, use case, and more * **A one-click template for every type**, so nobody starts from a blank canvas * **Live preview** as you type, so syntax errors surface before save * **Dark mode** that follows each reader's Confluence theme automatically * **Re-editable diagrams** — source and settings are fully preserved after saving Manual first, agent when you want speed. Both write the same kind of macro, so a diagram that started in chat is indistinguishable from one typed by hand. ## Prompts to try on your first day[​](#prompts-to-try-on-your-first-day "Direct link to Prompts to try on your first day") * *"Make a flowchart of our release checklist."* * *"Turn the API example in this page's code block into a sequence diagram."* * *"What does the current state diagram on this page say?"* * *"Add a decision node after the build step — if tests fail, go back to dev."* ## Related resources[​](#related-resources "Direct link to Related resources") * [Mermaid Plus Diagrams & AI Agent for Confluence](/apps/mermaid-plus-for-confluence.md) — full feature guide and documentation * [Excalidraw AI Agent for Confluence](/blog/excalidraw-ai-agent-confluence.md) — the canvas-side twin: create, edit, search, and convert whiteboards by chat * [How to create Mermaid diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md) — the step-by-step editor walkthrough * [draw.io vs Mermaid in Confluence](/blog/mermaid-vs-drawio-confluence.md) — when the source text stays the diagram, and when shapes win * [Best diagram tool for Confluence](/blog/confluence-diagram-tools-comparison.md) — Mermaid vs Excalidraw vs Graphviz * [All 30 Mermaid diagram types](/blog/faq-mermaid-diagram-types-confluence.md) — complete reference **Ready to try it?** [Install Mermaid Plus Diagrams & AI Agent for Confluence →](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence) — free for up to 10 users. Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [diagrams](/blog/tags/diagrams.md) * [ai](/blog/tags/ai.md) * [how-to](/blog/tags/how-to.md) * [agent](/blog/tags/agent.md) --- # API Sequence Diagrams in Confluence with Mermaid (Copy-Paste) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The integration doc says "the client calls the API, the API validates and responds" — four words, zero contracts, and the onboarding engineer asks "with what headers, in what order, and what if auth fails?" The code has the truth; the wiki has a paragraph. An API that can't be read as a transcript is an API nobody can safely operate. **Quick answer:** document API flows in Confluence as Mermaid — `sequenceDiagram` for request/response order, `packet-beta` for wire-format frames, ZenUML for branch-heavy async flows — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Each diagram type answers a different reader: what order, what's on the wire, what branches. This post gives you three copy-paste examples. ## Why an API doc is a transcript, not a paragraph[​](#why-an-api-doc-is-a-transcript-not-a-paragraph "Direct link to Why an API doc is a transcript, not a paragraph") Three readers need three views of the same integration, and Mermaid gives each its own shape: * **The order reader** needs a `sequenceDiagram` — who calls whom, in what order, with which payloads. The alt/else branches carry the failure behavior. * **The wire reader** needs a `packet` diagram — the actual byte layout of a frame, field widths and all. Good for protocols, TLS records, coarse protocol headers. * **The logic reader** needs ZenUML — the interaction as statement blocks, so branch-heavy async flows read like pseudocode. The point is the *shape matches the question*, and each shape is text the review can edit next to the code change that invalidates it. ## Copy-paste 1: the request trace as a sequence[​](#copy-paste-1-the-request-trace-as-a-sequence "Direct link to Copy-paste 1: the request trace as a sequence") An order placement across client → gateway → service → database, with the failure branch drawn (the runbook version): ``` sequenceDiagram participant C as Client participant G as Gateway participant S as Service participant DB as Database C->>G: POST /orders G->>G: auth + TLS check G->>S: forward with idempotency key alt validated S->>DB: INSERT order DB-->>S: 201 persisted S-->>C: 201 with order id else rejected S-->>C: 422 with errors end ``` ![Rendered Mermaid diagram](/assets/images/sequencediagram-f41ff61ce4cf5e778d1b97701ab7c2de.svg) Read it as a transcript: the client's POST reaches the gateway, the gateway authenticates, the service validates and the transaction is either committed (201) or rejected (422). The alt/else block is the runbook's "what happens on a bad payload" — callers trust a diagram that documents the failure too. ## Copy-paste 2: the wire frame as a packet diagram[​](#copy-paste-2-the-wire-frame-as-a-packet-diagram "Direct link to Copy-paste 2: the wire frame as a packet diagram") When the doc must show the *byte layout* — a protocol header, a TLS record, a coarse frame — the packet diagram puts field names over field widths, like a memory map of the on-wire format: ``` packet-beta title TCP segment 0-15: "Source port" 16-31: "Destination port" 32-63: "Sequence number" 64-95: "Acknowledgement" 96-127: "Flags" 128-158: "Window" 159-190: "Checksum + Urgent" ``` ![TCP segment](data:image/svg+xml;base64,PHN2ZyBpZD0ibXktc3ZnIiB3aWR0aD0iMTAwJSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgdmlld0JveD0iMCAwIDEwMjYgMzI5IiBzdHlsZT0ibWF4LXdpZHRoOiAxMDI2cHg7IGJhY2tncm91bmQtY29sb3I6IHdoaXRlOyIgcm9sZT0iZ3JhcGhpY3MtZG9jdW1lbnQgZG9jdW1lbnQiIGFyaWEtcm9sZWRlc2NyaXB0aW9uPSJwYWNrZXQiPjxzdHlsZT4jbXktc3Zne2ZvbnQtZmFtaWx5OiJ0cmVidWNoZXQgbXMiLHZlcmRhbmEsYXJpYWwsc2Fucy1zZXJpZjtmb250LXNpemU6MTZweDtmaWxsOiMzMzM7fUBrZXlmcmFtZXMgZWRnZS1hbmltYXRpb24tZnJhbWV7ZnJvbXtzdHJva2UtZGFzaG9mZnNldDowO319QGtleWZyYW1lcyBkYXNoe3Rve3N0cm9rZS1kYXNob2Zmc2V0OjA7fX0jbXktc3ZnIC5lZGdlLWFuaW1hdGlvbi1zbG93e3N0cm9rZS1kYXNoYXJyYXk6OSw1IWltcG9ydGFudDtzdHJva2UtZGFzaG9mZnNldDo5MDA7YW5pbWF0aW9uOmRhc2ggNTBzIGxpbmVhciBpbmZpbml0ZTtzdHJva2UtbGluZWNhcDpyb3VuZDt9I215LXN2ZyAuZWRnZS1hbmltYXRpb24tZmFzdHtzdHJva2UtZGFzaGFycmF5OjksNSFpbXBvcnRhbnQ7c3Ryb2tlLWRhc2hvZmZzZXQ6OTAwO2FuaW1hdGlvbjpkYXNoIDIwcyBsaW5lYXIgaW5maW5pdGU7c3Ryb2tlLWxpbmVjYXA6cm91bmQ7fSNteS1zdmcgLmVycm9yLWljb257ZmlsbDojNTUyMjIyO30jbXktc3ZnIC5lcnJvci10ZXh0e2ZpbGw6IzU1MjIyMjtzdHJva2U6IzU1MjIyMjt9I215LXN2ZyAuZWRnZS10aGlja25lc3Mtbm9ybWFse3N0cm9rZS13aWR0aDoxcHg7fSNteS1zdmcgLmVkZ2UtdGhpY2tuZXNzLXRoaWNre3N0cm9rZS13aWR0aDozLjVweDt9I215LXN2ZyAuZWRnZS1wYXR0ZXJuLXNvbGlke3N0cm9rZS1kYXNoYXJyYXk6MDt9I215LXN2ZyAuZWRnZS10aGlja25lc3MtaW52aXNpYmxle3N0cm9rZS13aWR0aDowO2ZpbGw6bm9uZTt9I215LXN2ZyAuZWRnZS1wYXR0ZXJuLWRhc2hlZHtzdHJva2UtZGFzaGFycmF5OjM7fSNteS1zdmcgLmVkZ2UtcGF0dGVybi1kb3R0ZWR7c3Ryb2tlLWRhc2hhcnJheToyO30jbXktc3ZnIC5tYXJrZXJ7ZmlsbDojMzMzMzMzO3N0cm9rZTojMzMzMzMzO30jbXktc3ZnIC5tYXJrZXIuY3Jvc3N7c3Ryb2tlOiMzMzMzMzM7fSNteS1zdmcgc3Zne2ZvbnQtZmFtaWx5OiJ0cmVidWNoZXQgbXMiLHZlcmRhbmEsYXJpYWwsc2Fucy1zZXJpZjtmb250LXNpemU6MTZweDt9I215LXN2ZyBwe21hcmdpbjowO30jbXktc3ZnIC5wYWNrZXRCeXRle2ZvbnQtc2l6ZToxMHB4O30jbXktc3ZnIC5wYWNrZXRCeXRlLnN0YXJ0e2ZpbGw6YmxhY2s7fSNteS1zdmcgLnBhY2tldEJ5dGUuZW5ke2ZpbGw6YmxhY2s7fSNteS1zdmcgLnBhY2tldExhYmVse2ZpbGw6YmxhY2s7Zm9udC1zaXplOjEycHg7fSNteS1zdmcgLnBhY2tldFRpdGxle2ZpbGw6YmxhY2s7Zm9udC1zaXplOjE0cHg7fSNteS1zdmcgLnBhY2tldEJsb2Nre3N0cm9rZTpibGFjaztzdHJva2Utd2lkdGg6MTtmaWxsOiNlZmVmZWY7fSNteS1zdmcgLm5vZGUgLm5lby1ub2Rle3N0cm9rZTojOTM3MERCO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcmVjdCwjbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLmNsdXN0ZXIgcmVjdCwjbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcG9seWdvbntzdHJva2U6IzkzNzBEQjtmaWx0ZXI6ZHJvcC1zaGFkb3coMXB4IDJweCAycHggcmdiYSgxODUsIDE4NSwgMTg1LCAxKSk7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uc3dpbWxhbmUuY2x1c3RlciByZWN0e2ZpbHRlcjpub25lO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcGF0aHtzdHJva2U6IzkzNzBEQjtzdHJva2Utd2lkdGg6MXB4O30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgLm91dGVyLXBhdGh7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgLm5lby1saW5lIHBhdGh7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOm5vbmU7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSBjaXJjbGV7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgY2lyY2xlIC5zdGF0ZS1zdGFydHtmaWxsOiMwMDAwMDA7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uaWNvbi1zaGFwZSAuaWNvbntmaWxsOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLmljb24tc2hhcGUgLmljb24tbmVvIHBhdGh7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIDpyb290ey0tbWVybWFpZC1mb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7fTwvc3R5bGU+PGcvPjxnPjxyZWN0IHg9IjEiIHk9IjE1IiB3aWR0aD0iNTA3IiBoZWlnaHQ9IjMyIiBjbGFzcz0icGFja2V0QmxvY2siLz48dGV4dCB4PSIyNTQuNSIgeT0iMzEiIGNsYXNzPSJwYWNrZXRMYWJlbCIgZG9taW5hbnQtYmFzZWxpbmU9Im1pZGRsZSIgdGV4dC1hbmNob3I9Im1pZGRsZSI+U291cmNlIHBvcnQ8L3RleHQ+PHRleHQgeD0iMSIgeT0iMTMiIGNsYXNzPSJwYWNrZXRCeXRlIHN0YXJ0IiBkb21pbmFudC1iYXNlbGluZT0iYXV0byIgdGV4dC1hbmNob3I9InN0YXJ0Ij4wPC90ZXh0Pjx0ZXh0IHg9IjUwOCIgeT0iMTMiIGNsYXNzPSJwYWNrZXRCeXRlIGVuZCIgZG9taW5hbnQtYmFzZWxpbmU9ImF1dG8iIHRleHQtYW5jaG9yPSJlbmQiPjE1PC90ZXh0PjxyZWN0IHg9IjUxMyIgeT0iMTUiIHdpZHRoPSI1MDciIGhlaWdodD0iMzIiIGNsYXNzPSJwYWNrZXRCbG9jayIvPjx0ZXh0IHg9Ijc2Ni41IiB5PSIzMSIgY2xhc3M9InBhY2tldExhYmVsIiBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIj5EZXN0aW5hdGlvbiBwb3J0PC90ZXh0Pjx0ZXh0IHg9IjUxMyIgeT0iMTMiIGNsYXNzPSJwYWNrZXRCeXRlIHN0YXJ0IiBkb21pbmFudC1iYXNlbGluZT0iYXV0byIgdGV4dC1hbmNob3I9InN0YXJ0Ij4xNjwvdGV4dD48dGV4dCB4PSIxMDIwIiB5PSIxMyIgY2xhc3M9InBhY2tldEJ5dGUgZW5kIiBkb21pbmFudC1iYXNlbGluZT0iYXV0byIgdGV4dC1hbmNob3I9ImVuZCI+MzE8L3RleHQ+PC9nPjxnPjxyZWN0IHg9IjEiIHk9IjYyIiB3aWR0aD0iMTAxOSIgaGVpZ2h0PSIzMiIgY2xhc3M9InBhY2tldEJsb2NrIi8+PHRleHQgeD0iNTEwLjUiIHk9Ijc4IiBjbGFzcz0icGFja2V0TGFiZWwiIGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiIHRleHQtYW5jaG9yPSJtaWRkbGUiPlNlcXVlbmNlIG51bWJlcjwvdGV4dD48dGV4dCB4PSIxIiB5PSI2MCIgY2xhc3M9InBhY2tldEJ5dGUgc3RhcnQiIGRvbWluYW50LWJhc2VsaW5lPSJhdXRvIiB0ZXh0LWFuY2hvcj0ic3RhcnQiPjMyPC90ZXh0Pjx0ZXh0IHg9IjEwMjAiIHk9IjYwIiBjbGFzcz0icGFja2V0Qnl0ZSBlbmQiIGRvbWluYW50LWJhc2VsaW5lPSJhdXRvIiB0ZXh0LWFuY2hvcj0iZW5kIj42MzwvdGV4dD48L2c+PGc+PHJlY3QgeD0iMSIgeT0iMTA5IiB3aWR0aD0iMTAxOSIgaGVpZ2h0PSIzMiIgY2xhc3M9InBhY2tldEJsb2NrIi8+PHRleHQgeD0iNTEwLjUiIHk9IjEyNSIgY2xhc3M9InBhY2tldExhYmVsIiBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIj5BY2tub3dsZWRnZW1lbnQ8L3RleHQ+PHRleHQgeD0iMSIgeT0iMTA3IiBjbGFzcz0icGFja2V0Qnl0ZSBzdGFydCIgZG9taW5hbnQtYmFzZWxpbmU9ImF1dG8iIHRleHQtYW5jaG9yPSJzdGFydCI+NjQ8L3RleHQ+PHRleHQgeD0iMTAyMCIgeT0iMTA3IiBjbGFzcz0icGFja2V0Qnl0ZSBlbmQiIGRvbWluYW50LWJhc2VsaW5lPSJhdXRvIiB0ZXh0LWFuY2hvcj0iZW5kIj45NTwvdGV4dD48L2c+PGc+PHJlY3QgeD0iMSIgeT0iMTU2IiB3aWR0aD0iMTAxOSIgaGVpZ2h0PSIzMiIgY2xhc3M9InBhY2tldEJsb2NrIi8+PHRleHQgeD0iNTEwLjUiIHk9IjE3MiIgY2xhc3M9InBhY2tldExhYmVsIiBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIj5GbGFnczwvdGV4dD48dGV4dCB4PSIxIiB5PSIxNTQiIGNsYXNzPSJwYWNrZXRCeXRlIHN0YXJ0IiBkb21pbmFudC1iYXNlbGluZT0iYXV0byIgdGV4dC1hbmNob3I9InN0YXJ0Ij45NjwvdGV4dD48dGV4dCB4PSIxMDIwIiB5PSIxNTQiIGNsYXNzPSJwYWNrZXRCeXRlIGVuZCIgZG9taW5hbnQtYmFzZWxpbmU9ImF1dG8iIHRleHQtYW5jaG9yPSJlbmQiPjEyNzwvdGV4dD48L2c+PGc+PHJlY3QgeD0iMSIgeT0iMjAzIiB3aWR0aD0iOTg3IiBoZWlnaHQ9IjMyIiBjbGFzcz0icGFja2V0QmxvY2siLz48dGV4dCB4PSI0OTQuNSIgeT0iMjE5IiBjbGFzcz0icGFja2V0TGFiZWwiIGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiIHRleHQtYW5jaG9yPSJtaWRkbGUiPldpbmRvdzwvdGV4dD48dGV4dCB4PSIxIiB5PSIyMDEiIGNsYXNzPSJwYWNrZXRCeXRlIHN0YXJ0IiBkb21pbmFudC1iYXNlbGluZT0iYXV0byIgdGV4dC1hbmNob3I9InN0YXJ0Ij4xMjg8L3RleHQ+PHRleHQgeD0iOTg4IiB5PSIyMDEiIGNsYXNzPSJwYWNrZXRCeXRlIGVuZCIgZG9taW5hbnQtYmFzZWxpbmU9ImF1dG8iIHRleHQtYW5jaG9yPSJlbmQiPjE1ODwvdGV4dD48cmVjdCB4PSI5OTMiIHk9IjIwMyIgd2lkdGg9IjI3IiBoZWlnaHQ9IjMyIiBjbGFzcz0icGFja2V0QmxvY2siLz48dGV4dCB4PSIxMDA2LjUiIHk9IjIxOSIgY2xhc3M9InBhY2tldExhYmVsIiBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIj5DaGVja3N1bSArIFVyZ2VudDwvdGV4dD48dGV4dCB4PSIxMDA2LjUiIHk9IjIwMSIgY2xhc3M9InBhY2tldEJ5dGUgc3RhcnQiIGRvbWluYW50LWJhc2VsaW5lPSJhdXRvIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIj4xNTk8L3RleHQ+PC9nPjxnPjxyZWN0IHg9IjEiIHk9IjI1MCIgd2lkdGg9Ijk4NyIgaGVpZ2h0PSIzMiIgY2xhc3M9InBhY2tldEJsb2NrIi8+PHRleHQgeD0iNDk0LjUiIHk9IjI2NiIgY2xhc3M9InBhY2tldExhYmVsIiBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIj5DaGVja3N1bSArIFVyZ2VudDwvdGV4dD48dGV4dCB4PSIxIiB5PSIyNDgiIGNsYXNzPSJwYWNrZXRCeXRlIHN0YXJ0IiBkb21pbmFudC1iYXNlbGluZT0iYXV0byIgdGV4dC1hbmNob3I9InN0YXJ0Ij4xNjA8L3RleHQ+PHRleHQgeD0iOTg4IiB5PSIyNDgiIGNsYXNzPSJwYWNrZXRCeXRlIGVuZCIgZG9taW5hbnQtYmFzZWxpbmU9ImF1dG8iIHRleHQtYW5jaG9yPSJlbmQiPjE5MDwvdGV4dD48L2c+PHRleHQgeD0iNTEzIiB5PSIzMDUuNSIgZG9taW5hbnQtYmFzZWxpbmU9Im1pZGRsZSIgdGV4dC1hbmNob3I9Im1pZGRsZSIgY2xhc3M9InBhY2tldFRpdGxlIj5UQ1Agc2VnbWVudDwvdGV4dD48L3N2Zz4=) Each field is named and sized; the reader sees the header layout without opening a packet decoder. For a custom protocol or a reverse-proxy header contract, this is the diagram that ends "where is the checksum" — forever. ## Copy-paste 3: branch-heavy flow as ZenUML[​](#copy-paste-3-branch-heavy-flow-as-zenuml "Direct link to Copy-paste 3: branch-heavy flow as ZenUML") ZenUML writes interactions as statement blocks — when the flow's *branching* is the story (auth, retries, timeouts), the blocks read like the pseudocode of the behavior: ``` zenuml title Login flow Actor User Participant API Database Creds User->API: login(email, pass) API->Creds: lookup hash alt creds match Creds-->API: hash verified API-->User: access token else creds miss Creds-->API: no such account API-->User: 401 invalid end ``` ![Login flow](/assets/images/login-flow-53a2d58c52b51d8cc4343c313eec283a.svg) Like the sequence alt, the branches are explicit — but written as blocks that diff well and read down a page. Team rule of thumb: sequence for ordering, packet for wire, ZenUML for "the interaction is basically a decision tree." All three coexist on the API runbook page. ## Choosing the API doc shape[​](#choosing-the-api-doc-shape "Direct link to Choosing the API doc shape") | The question | Diagram | When to use | | ------------------------------------------ | ------------- | ----------------------------------- | | In what order does the interaction happen? | **Sequence** | Request traces, multi-service calls | | What is on the wire, byte by byte? | **Packet** | Protocol headers, custom frames | | How do the branches behave? | **ZenUML** | Auth, retries, async decision trees | | Where should work wait vs flow? | **Flowchart** | Long-running work, queues | The API runbook's neighbors are on the same wiki: the **data shape** exchanged by the calls as an [ER schema](/blog/mermaid-er-diagram-database-schema-confluence.md) and the **deployment** the services run on as a [system architecture](/blog/mermaid-c4-system-architecture-confluence.md). ## FAQ[​](#faq "Direct link to FAQ") **Does Confluence have a built-in API sequence diagram tool?** No — Confluence has no native diagramming. Mermaid Plus Diagrams & AI Agent for Confluence renders `sequenceDiagram`, `packet-beta` and ZenUML from editable text with a live preview. **Sequence, packet or ZenUML for an API doc?** Sequence for request/response order, packet for the wire format, ZenUML for branch-heavy interactions that read best as blocks. An API runbook often holds all three. **How do I show failure handling in a sequence diagram?** Wrap the branch in `alt ... else ... end` — success in the alt body, failure in the else body. The runbook's error behavior becomes a drawn part of the flow. **Can I keep a long API sequence diagram readable?** Split by endpoint or critical path, limit participants to what that flow touches, and put invariants in `note` lines. Small clear transcripts beat a wide wall of arrows. Render every Mermaid diagram type — sequence, packet, ZenUML, ER, C4 and 24 more — in [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), free for up to 10 users. Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [sequence-diagram](/blog/tags/sequence-diagram.md) * [packet](/blog/tags/packet.md) * [zenuml](/blog/tags/zenuml.md) * [api](/blog/tags/api.md) * [how-to](/blog/tags/how-to.md) --- # System Architecture Diagrams in Confluence with Mermaid C4 September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The onboarding doc says "check the architecture diagram" and the architecture diagram shows a monolith from 2023 that the team decommissioned in the spring. Nobody is lying — the draw\.io file lives on one person's laptop, and the wiki holds a screenshot nobody owns. An architecture that only exists as a static export rots silently, because the thing you would edit is invisible to review. **Quick answer:** document system architecture in Confluence as Mermaid text — `C4Context` for the system in context, `architecture-beta` for the deployment, `block-beta` for the topology you want laid out precisely — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Every level stays an editable code block, so the wiki's architecture changes in the same review that changes the system. This post gives you three copy-paste examples. ## Why the diagram is the reviewable artifact[​](#why-the-diagram-is-the-reviewable-artifact "Direct link to Why the diagram is the reviewable artifact") An architecture decision is only alive while the diagram that encodes it is still linked to the change that should update it. Three properties make a Mermaid diagram survive contact with a moving system: * **It diffs.** A code block changes line-by-line; the review shows the one arrow that moved, instead of a squint-diff between two screenshots. * **It lives beside the content.** The context diagram sits in the same page as the architecture decision, not in a Draw\.io file in someone's drive. * **It renders where it is read.** The macro caches SVG at save, so the reader of a Confluence page gets a fast image and the editor gets the text. For teams adopting C4, the gradient that matters is *depth by ownership*: full context for everyone, containers for the service your team runs, and no CDN sub-boxes unless your team operates CDN config. ## Copy-paste 1: system context (C4Context)[​](#copy-paste-1-system-context-c4context "Direct link to Copy-paste 1: system context (C4Context)") The picture for the whole team — the system as one box among the actors and systems it talks to. This is the diagram for the space home page and for new-hire onboarding: ``` C4Context title System Context — Order Platform Person(customer, "Customer") System(orderApi, "Order API") SystemDb(orderDb, "Order Store") System(payment, "Payment Gateway") Rel(customer, orderApi, "places orders via HTTPS") Rel(orderApi, orderDb, "reads and writes") Rel(orderApi, payment, "authorizes payments") ``` ![System Context — Order Platform](/assets/images/system-context-order-platform-ab3e50722eabd7e0b460ef06db23862f.svg) Three nodes and three arrows carry the whole contract: who talks to the platform, which store holds truth, and which external party the money depends on. If a new system joins the picture (a fraud service, a webhook consumer), the update is one line in this block. ## Copy-paste 2: the service your team owns (architecture-beta)[​](#copy-paste-2-the-service-your-team-owns-architecture-beta "Direct link to Copy-paste 2: the service your team owns (architecture-beta)") Zoom in to the deployment around the service the team operates — load balancer in front, API behind it, database at the back. `architecture-beta` names the nodes with real infrastructure words rather than generic boxes: ``` architecture-beta group cloud(cloud)[Order Platform cluster] service lb(server)[Load Balancer] in cloud service api(server)[Order API] in cloud service db(server)[Order Store] in cloud lb:R -- L:api api:R -- L:db ``` ![Rendered Mermaid diagram](/assets/images/architecture-beta-a1abd73eb4efecdae64aebbb4b063609.svg) The `--` links read as "talks to" without direction barging into the layout, and the `group` wrapper marks the shared boundary — every box inside `cloud` is infrastructure the on-call team owns. This is the diagram for the runbook page and the incident-playbook attachment. ## Copy-paste 3: precise topology with block-beta[​](#copy-paste-3-precise-topology-with-block-beta "Direct link to Copy-paste 3: precise topology with block-beta") When the layout has to match the deployment exactly — frontend above API above database, with columns controlled — `block-beta` gives you explicit column rules instead of hoping the layout algorithm cooperates: ``` block-beta columns 1 block:clients columns 1 ui["Browser"] end block:apiSvc columns 2 api["Order API"] db(("Order Store")) end ui --> api api --> db ``` ![Rendered Mermaid diagram](/assets/images/block-beta-c26efbf295971091b63e29487234c776.svg) One change from the C4 pair: `columns` puts the store next to the API by construction, and the `db` cylinder is picked by the `(("…"))` shape. Use this level when the reviewer needs to *see* the deployment as it is configured, not as a generic graph. ## Keeping the three levels honest[​](#keeping-the-three-levels-honest "Direct link to Keeping the three levels honest") Context diagrams rot into lies because nothing links them to change. Two habits stop that: * **Put the diagram in the change.** The same PR or page edit that moves the API behind a new gateway updates the context diagram's one arrow. * **Let the coverage follow ownership.** Everyone sees context; only the owning team needs the container and the topology. A diagram nobody owns is a diagram nobody updates. A stale Mermaid block in Confluence at least sits where the change happens — the review reads the diff, someone fixes the line, and the wiki is honest again. That is the whole difference between architecture-as-export and architecture-as-text. ## Where this lives beside your other architecture content[​](#where-this-lives-beside-your-other-architecture-content "Direct link to Where this lives beside your other architecture content") This is the C4/system layer of the diagram family; the other layers are owned elsewhere. Keep the **system context + topology** on the architecture page (this post), the **class-level** structure of one service in [class diagrams](/blog/mermaid-class-diagram-document-codebase-confluence.md), and the **deployment-to-release history** as a [gitGraph](/blog/mermaid-gitgraph-jira-branch-history.md) on the release page. Same wiki, different zoom levels. ## FAQ[​](#faq "Direct link to FAQ") **Does Confluence have a built-in system architecture diagram tool?** No — Confluence has no native diagramming. Mermaid Plus Diagrams & AI Agent for Confluence renders C4 context, architecture and block diagrams from editable text with cached preview. **What is the C4 model and which levels belong in Confluence?** C4 = context, container, component, code. In Confluence keep context and container; component/code belong with the source repository. Mermaid draws the first two as text. **C4Context vs architecture vs block — when do I use which?** Context for who-plays-with-whom, architecture-beta for named infrastructure (load balancer → API → database), block-beta when you need exact layout with explicit columns. One page can hold all three. **How do I keep architecture diagrams from rotting?** Make the diagram the thing the review changes — editable text means the update ships with the change that moved the system. Render every Mermaid diagram type — C4, architecture, block, class, state and 24 more — in [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), free for up to 10 users. Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [architecture](/blog/tags/architecture.md) * [c4-model](/blog/tags/c-4-model.md) * [block-diagram](/blog/tags/block-diagram.md) * [how-to](/blog/tags/how-to.md) --- # Mermaid Charts for Confluence Dashboards: Pie & XY in One Post September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The quarterly review loads a 14-tab spreadsheet to answer one question — "where do we actually spend our engineering time?" — because the wiki charts are stale screenshots from last quarter and the numbers table nobody reads. A dashboard is not a spreadsheet: it is the two charts that answer the two questions people keep asking. **Quick answer:** build dashboard charts in Confluence with Mermaid `pie` and `xychart-beta` charts, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Pie for shares, XY for trends — both as editable text that refreshes like code. This post gives you three copy-paste examples: an effort-share pie, a weekly trend XY, and a dual-series release dashboard. ## The two questions a dashboard answers[​](#the-two-questions-a-dashboard-answers "Direct link to The two questions a dashboard answers") Every dashboard reduces to two questions, and each has a chart that answers it cleanly: * **What is the mix?** → a `pie` chart with a handful of categories * **How does it change?** → an `xychart-beta` chart, bars or lines, across time Pick the chart by the question, not by prettiness — a pie stuffed with twelve categories is unreadable, and a trend with a single static snapshot is misleading. Both Mermaid types stay text, so both refresh in the same edit as the report. ## Copy-paste 1: the share-of-effort pie[​](#copy-paste-1-the-share-of-effort-pie "Direct link to Copy-paste 1: the share-of-effort pie") Start with the mix question. Six categories is the sweet spot; the pie answers "what is our effort really made of" in one glance: ``` pie %% title: Engineering effort split "New features" : 40 "Bug fixes" : 25 "Tech debt" : 18 "Support" : 10 "Tooling" : 7 ``` ![Engineering effort split](data:image/svg+xml;base64,PHN2ZyBpZD0ibXktc3ZnIiB3aWR0aD0iMTAwJSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgdmlld0JveD0iMCAwIDYxMy4yODg1NzQyMTg3NSA0NTAiIHN0eWxlPSJtYXgtd2lkdGg6IDYxMy4yODlweDsgYmFja2dyb3VuZC1jb2xvcjogd2hpdGU7IiByb2xlPSJncmFwaGljcy1kb2N1bWVudCBkb2N1bWVudCIgYXJpYS1yb2xlZGVzY3JpcHRpb249InBpZSI+PHN0eWxlPiNteS1zdmd7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO2ZvbnQtc2l6ZToxNnB4O2ZpbGw6IzMzMzt9QGtleWZyYW1lcyBlZGdlLWFuaW1hdGlvbi1mcmFtZXtmcm9te3N0cm9rZS1kYXNob2Zmc2V0OjA7fX1Aa2V5ZnJhbWVzIGRhc2h7dG97c3Ryb2tlLWRhc2hvZmZzZXQ6MDt9fSNteS1zdmcgLmVkZ2UtYW5pbWF0aW9uLXNsb3d7c3Ryb2tlLWRhc2hhcnJheTo5LDUhaW1wb3J0YW50O3N0cm9rZS1kYXNob2Zmc2V0OjkwMDthbmltYXRpb246ZGFzaCA1MHMgbGluZWFyIGluZmluaXRlO3N0cm9rZS1saW5lY2FwOnJvdW5kO30jbXktc3ZnIC5lZGdlLWFuaW1hdGlvbi1mYXN0e3N0cm9rZS1kYXNoYXJyYXk6OSw1IWltcG9ydGFudDtzdHJva2UtZGFzaG9mZnNldDo5MDA7YW5pbWF0aW9uOmRhc2ggMjBzIGxpbmVhciBpbmZpbml0ZTtzdHJva2UtbGluZWNhcDpyb3VuZDt9I215LXN2ZyAuZXJyb3ItaWNvbntmaWxsOiM1NTIyMjI7fSNteS1zdmcgLmVycm9yLXRleHR7ZmlsbDojNTUyMjIyO3N0cm9rZTojNTUyMjIyO30jbXktc3ZnIC5lZGdlLXRoaWNrbmVzcy1ub3JtYWx7c3Ryb2tlLXdpZHRoOjFweDt9I215LXN2ZyAuZWRnZS10aGlja25lc3MtdGhpY2t7c3Ryb2tlLXdpZHRoOjMuNXB4O30jbXktc3ZnIC5lZGdlLXBhdHRlcm4tc29saWR7c3Ryb2tlLWRhc2hhcnJheTowO30jbXktc3ZnIC5lZGdlLXRoaWNrbmVzcy1pbnZpc2libGV7c3Ryb2tlLXdpZHRoOjA7ZmlsbDpub25lO30jbXktc3ZnIC5lZGdlLXBhdHRlcm4tZGFzaGVke3N0cm9rZS1kYXNoYXJyYXk6Mzt9I215LXN2ZyAuZWRnZS1wYXR0ZXJuLWRvdHRlZHtzdHJva2UtZGFzaGFycmF5OjI7fSNteS1zdmcgLm1hcmtlcntmaWxsOiMzMzMzMzM7c3Ryb2tlOiMzMzMzMzM7fSNteS1zdmcgLm1hcmtlci5jcm9zc3tzdHJva2U6IzMzMzMzMzt9I215LXN2ZyBzdmd7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO2ZvbnQtc2l6ZToxNnB4O30jbXktc3ZnIHB7bWFyZ2luOjA7fSNteS1zdmcgLnBpZUNpcmNsZXtzdHJva2U6YmxhY2s7c3Ryb2tlLXdpZHRoOjJweDtvcGFjaXR5OjAuNzt9I215LXN2ZyAucGllQ2lyY2xlLmhpZ2hsaWdodGVke3NjYWxlOjEuMDU7b3BhY2l0eToxO30jbXktc3ZnIC5waWVDaXJjbGUuaGlnaGxpZ2h0ZWRPbkhvdmVyOmhvdmVye3RyYW5zaXRpb24tZHVyYXRpb246MjUwbXM7c2NhbGU6MS4wNTtvcGFjaXR5OjE7fSNteS1zdmcgLnBpZU91dGVyQ2lyY2xle3N0cm9rZTpibGFjaztzdHJva2Utd2lkdGg6MnB4O2ZpbGw6bm9uZTt9I215LXN2ZyAucGllVGl0bGVUZXh0e3RleHQtYW5jaG9yOm1pZGRsZTtmb250LXNpemU6MjVweDtmaWxsOmJsYWNrO2ZvbnQtZmFtaWx5OiJ0cmVidWNoZXQgbXMiLHZlcmRhbmEsYXJpYWwsc2Fucy1zZXJpZjt9I215LXN2ZyAuc2xpY2V7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO2ZpbGw6IzMzMztmb250LXNpemU6MTdweDt9I215LXN2ZyAubGVnZW5kIHRleHR7ZmlsbDpibGFjaztmb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7Zm9udC1zaXplOjE3cHg7fSNteS1zdmcgLm5vZGUgLm5lby1ub2Rle3N0cm9rZTojOTM3MERCO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcmVjdCwjbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLmNsdXN0ZXIgcmVjdCwjbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcG9seWdvbntzdHJva2U6IzkzNzBEQjtmaWx0ZXI6ZHJvcC1zaGFkb3coMXB4IDJweCAycHggcmdiYSgxODUsIDE4NSwgMTg1LCAxKSk7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uc3dpbWxhbmUuY2x1c3RlciByZWN0e2ZpbHRlcjpub25lO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcGF0aHtzdHJva2U6IzkzNzBEQjtzdHJva2Utd2lkdGg6MXB4O30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgLm91dGVyLXBhdGh7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgLm5lby1saW5lIHBhdGh7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOm5vbmU7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSBjaXJjbGV7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgY2lyY2xlIC5zdGF0ZS1zdGFydHtmaWxsOiMwMDAwMDA7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uaWNvbi1zaGFwZSAuaWNvbntmaWxsOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLmljb24tc2hhcGUgLmljb24tbmVvIHBhdGh7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIDpyb290ey0tbWVybWFpZC1mb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7fTwvc3R5bGU+PGcvPjxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDIyNSwyMjUpIj48Zz48Y2lyY2xlIGN4PSIwIiBjeT0iMCIgcj0iMTg2IiBjbGFzcz0icGllT3V0ZXJDaXJjbGUiLz48cGF0aCBkPSJNMCwtMTg1QTE4NSwxODUsMCwwLDEsMTA4Ljc0LDE0OS42NjhMMCwwWiIgZmlsbD0iI0VDRUNGRiIgY2xhc3M9InBpZUNpcmNsZSIvPjxwYXRoIGQ9Ik0xMDguNzQsMTQ5LjY2OEExODUsMTg1LDAsMCwxLC0xNDkuNjY4LDEwOC43NEwwLDBaIiBmaWxsPSIjZmZmZmRlIiBjbGFzcz0icGllQ2lyY2xlIi8+PHBhdGggZD0iTS0xNDkuNjY4LDEwOC43NEExODUsMTg1LDAsMCwxLC0xNjIuMTE3LC04OS4xMjRMMCwwWiIgZmlsbD0iaHNsKDgwLCAxMDAlLCA1Ni4yNzQ1MDk4MDM5JSkiIGNsYXNzPSJwaWVDaXJjbGUiLz48cGF0aCBkPSJNLTE2Mi4xMTcsLTg5LjEyNEExODUsMTg1LDAsMCwxLC03OC43NjksLTE2Ny4zOTNMMCwwWiIgZmlsbD0iaHNsKDI0MCwgMTAwJSwgODYuMjc0NTA5ODAzOSUpIiBjbGFzcz0icGllQ2lyY2xlIi8+PHBhdGggZD0iTS03OC43NjksLTE2Ny4zOTNBMTg1LDE4NSwwLDAsMSwwLC0xODVMMCwwWiIgZmlsbD0iaHNsKDYwLCAxMDAlLCA2My41Mjk0MTE3NjQ3JSkiIGNsYXNzPSJwaWVDaXJjbGUiLz48dGV4dCB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMzEuOTU5MDkxNjM1OTUyNTUsLTQyLjg3NjEwNzk2OTUyMzk1KSIgY2xhc3M9InNsaWNlIiBzdHlsZT0idGV4dC1hbmNob3I6IG1pZGRsZTsiPjQwJTwvdGV4dD48dGV4dCB0cmFuc2Zvcm09InRyYW5zbGF0ZSgtMjEuNzA1MjgyMDI0MzMyMDI1LDEzNy4wNDE3NTcyNTc1NzUzNykiIGNsYXNzPSJzbGljZSIgc3R5bGU9InRleHQtYW5jaG9yOiBtaWRkbGU7Ij4yNSU8L3RleHQ+PHRleHQgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoLTEzOC40NzYyMDg1Njk0MjI2OCw4LjcxMjE4NDU4NDY5MjE5NykiIGNsYXNzPSJzbGljZSIgc3R5bGU9InRleHQtYW5jaG9yOiBtaWRkbGU7Ij4xOCU8L3RleHQ+PHRleHQgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoLTk0Ljk4MDkxMDk0NzYwNTYsLTEwMS4xNDQzOTcwNTQ3MjA4MykiIGNsYXNzPSJzbGljZSIgc3R5bGU9InRleHQtYW5jaG9yOiBtaWRkbGU7Ij4xMCU8L3RleHQ+PHRleHQgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoLTMwLjI2NzM3NDc0Mzc3MDM3LC0xMzUuNDA4NDUwNzE5MDAxMTcpIiBjbGFzcz0ic2xpY2UiIHN0eWxlPSJ0ZXh0LWFuY2hvcjogbWlkZGxlOyI+NyU8L3RleHQ+PC9nPjx0ZXh0IHg9IjAiIHk9Ii0yMDAiIGNsYXNzPSJwaWVUaXRsZVRleHQiLz48ZyBjbGFzcz0ibGVnZW5kIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgyMTYsLTU1KSI+PHJlY3Qgd2lkdGg9IjE4IiBoZWlnaHQ9IjE4IiBzdHlsZT0iZmlsbDogcmdiKDIzNiwgMjM2LCAyNTUpOyBzdHJva2U6IHJnYigyMzYsIDIzNiwgMjU1KTsiLz48dGV4dCB4PSIyMiIgeT0iMTQiPk5ldyBmZWF0dXJlczwvdGV4dD48L2c+PGcgY2xhc3M9ImxlZ2VuZCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMjE2LC0zMykiPjxyZWN0IHdpZHRoPSIxOCIgaGVpZ2h0PSIxOCIgc3R5bGU9ImZpbGw6IHJnYigyNTUsIDI1NSwgMjIyKTsgc3Ryb2tlOiByZ2IoMjU1LCAyNTUsIDIyMik7Ii8+PHRleHQgeD0iMjIiIHk9IjE0Ij5CdWcgZml4ZXM8L3RleHQ+PC9nPjxnIGNsYXNzPSJsZWdlbmQiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDIxNiwtMTEpIj48cmVjdCB3aWR0aD0iMTgiIGhlaWdodD0iMTgiIHN0eWxlPSJmaWxsOiByZ2IoMTgxLCAyNTUsIDMyKTsgc3Ryb2tlOiByZ2IoMTgxLCAyNTUsIDMyKTsiLz48dGV4dCB4PSIyMiIgeT0iMTQiPlRlY2ggZGVidDwvdGV4dD48L2c+PGcgY2xhc3M9ImxlZ2VuZCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMjE2LDExKSI+PHJlY3Qgd2lkdGg9IjE4IiBoZWlnaHQ9IjE4IiBzdHlsZT0iZmlsbDogcmdiKDE4NSwgMTg1LCAyNTUpOyBzdHJva2U6IHJnYigxODUsIDE4NSwgMjU1KTsiLz48dGV4dCB4PSIyMiIgeT0iMTQiPlN1cHBvcnQ8L3RleHQ+PC9nPjxnIGNsYXNzPSJsZWdlbmQiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDIxNiwzMykiPjxyZWN0IHdpZHRoPSIxOCIgaGVpZ2h0PSIxOCIgc3R5bGU9ImZpbGw6IHJnYigyNTUsIDI1NSwgNjkpOyBzdHJva2U6IHJnYigyNTUsIDI1NSwgNjkpOyIvPjx0ZXh0IHg9IjIyIiB5PSIxNCI+VG9vbGluZzwvdGV4dD48L2c+PC9nPjwvc3ZnPg==) One quote, one number per line, total sums to 100. The slice hiding behind the reset (`Tech debt: 18`) is exactly the conversation this chart is designed to start — "we planned zero, we spent eighteen". Two executives read the same chart and agree on the fact; the debate moves to what to do about it. ## Copy-paste 2: the weekly trend XY[​](#copy-paste-2-the-weekly-trend-xy "Direct link to Copy-paste 2: the weekly trend XY") Trends need an axis, which is what `xychart-beta` adds. Incident counts by week — the chart to pin in the reliability space: ``` xychart-beta %% title: Incidents per week title "Incidents per week" x-axis [2026-W36, 2026-W37, 2026-W38, 2026-W39] y-axis "Incidents" 0 --> 12 bar [3, 5, 2, 9] line [3, 5, 2, 9] ``` ![Incidents per week](data:image/svg+xml;base64,PHN2ZyBpZD0ibXktc3ZnIiB3aWR0aD0iMTAwJSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgc3R5bGU9Im1heC13aWR0aDogNzAwcHg7IGJhY2tncm91bmQtY29sb3I6IHdoaXRlOyIgdmlld0JveD0iMCAwIDcwMCA1MDAiIHJvbGU9ImdyYXBoaWNzLWRvY3VtZW50IGRvY3VtZW50IiBhcmlhLXJvbGVkZXNjcmlwdGlvbj0ieHljaGFydCI+PHN0eWxlPiNteS1zdmd7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO2ZvbnQtc2l6ZToxNnB4O2ZpbGw6IzMzMzt9QGtleWZyYW1lcyBlZGdlLWFuaW1hdGlvbi1mcmFtZXtmcm9te3N0cm9rZS1kYXNob2Zmc2V0OjA7fX1Aa2V5ZnJhbWVzIGRhc2h7dG97c3Ryb2tlLWRhc2hvZmZzZXQ6MDt9fSNteS1zdmcgLmVkZ2UtYW5pbWF0aW9uLXNsb3d7c3Ryb2tlLWRhc2hhcnJheTo5LDUhaW1wb3J0YW50O3N0cm9rZS1kYXNob2Zmc2V0OjkwMDthbmltYXRpb246ZGFzaCA1MHMgbGluZWFyIGluZmluaXRlO3N0cm9rZS1saW5lY2FwOnJvdW5kO30jbXktc3ZnIC5lZGdlLWFuaW1hdGlvbi1mYXN0e3N0cm9rZS1kYXNoYXJyYXk6OSw1IWltcG9ydGFudDtzdHJva2UtZGFzaG9mZnNldDo5MDA7YW5pbWF0aW9uOmRhc2ggMjBzIGxpbmVhciBpbmZpbml0ZTtzdHJva2UtbGluZWNhcDpyb3VuZDt9I215LXN2ZyAuZXJyb3ItaWNvbntmaWxsOiM1NTIyMjI7fSNteS1zdmcgLmVycm9yLXRleHR7ZmlsbDojNTUyMjIyO3N0cm9rZTojNTUyMjIyO30jbXktc3ZnIC5lZGdlLXRoaWNrbmVzcy1ub3JtYWx7c3Ryb2tlLXdpZHRoOjFweDt9I215LXN2ZyAuZWRnZS10aGlja25lc3MtdGhpY2t7c3Ryb2tlLXdpZHRoOjMuNXB4O30jbXktc3ZnIC5lZGdlLXBhdHRlcm4tc29saWR7c3Ryb2tlLWRhc2hhcnJheTowO30jbXktc3ZnIC5lZGdlLXRoaWNrbmVzcy1pbnZpc2libGV7c3Ryb2tlLXdpZHRoOjA7ZmlsbDpub25lO30jbXktc3ZnIC5lZGdlLXBhdHRlcm4tZGFzaGVke3N0cm9rZS1kYXNoYXJyYXk6Mzt9I215LXN2ZyAuZWRnZS1wYXR0ZXJuLWRvdHRlZHtzdHJva2UtZGFzaGFycmF5OjI7fSNteS1zdmcgLm1hcmtlcntmaWxsOiMzMzMzMzM7c3Ryb2tlOiMzMzMzMzM7fSNteS1zdmcgLm1hcmtlci5jcm9zc3tzdHJva2U6IzMzMzMzMzt9I215LXN2ZyBzdmd7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO2ZvbnQtc2l6ZToxNnB4O30jbXktc3ZnIHB7bWFyZ2luOjA7fSNteS1zdmcgLm5vZGUgLm5lby1ub2Rle3N0cm9rZTojOTM3MERCO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcmVjdCwjbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLmNsdXN0ZXIgcmVjdCwjbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcG9seWdvbntzdHJva2U6IzkzNzBEQjtmaWx0ZXI6ZHJvcC1zaGFkb3coMXB4IDJweCAycHggcmdiYSgxODUsIDE4NSwgMTg1LCAxKSk7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uc3dpbWxhbmUuY2x1c3RlciByZWN0e2ZpbHRlcjpub25lO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcGF0aHtzdHJva2U6IzkzNzBEQjtzdHJva2Utd2lkdGg6MXB4O30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgLm91dGVyLXBhdGh7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgLm5lby1saW5lIHBhdGh7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOm5vbmU7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSBjaXJjbGV7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgY2lyY2xlIC5zdGF0ZS1zdGFydHtmaWxsOiMwMDAwMDA7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uaWNvbi1zaGFwZSAuaWNvbntmaWxsOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLmljb24tc2hhcGUgLmljb24tbmVvIHBhdGh7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIDpyb290ey0tbWVybWFpZC1mb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7fTwvc3R5bGU+PGcvPjxnIGNsYXNzPSJtYWluIj48cmVjdCB3aWR0aD0iNzAwIiBoZWlnaHQ9IjUwMCIgY2xhc3M9ImJhY2tncm91bmQiIGZpbGw9IndoaXRlIi8+PGcgY2xhc3M9ImNoYXJ0LXRpdGxlIj48dGV4dCB4PSIwIiB5PSIwIiBmaWxsPSIjMTMxMzAwIiBmb250LXNpemU9IjIwIiBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgzNTAsIDIxLjUpIHJvdGF0ZSgwKSI+SW5jaWRlbnRzIHBlciB3ZWVrPC90ZXh0PjwvZz48ZyBjbGFzcz0icGxvdCI+PGcgY2xhc3M9ImJhci1wbG90LTAiPjxyZWN0IHg9IjYzLjg0MTc5ODc4MjM0ODYzIiB5PSIzNTciIHdpZHRoPSI5NSIgaGVpZ2h0PSIxMTAiIGZpbGw9IiNFQ0VDRkYiIHN0cm9rZT0iI0VDRUNGRiIgc3Ryb2tlLXdpZHRoPSIwIi8+PHJlY3QgeD0iMjQzLjM5NDUzMjUyMTU2NTgiIHk9IjI4OC45OTk5OTk5OTk5OTk5NCIgd2lkdGg9Ijk1IiBoZWlnaHQ9IjE3OC4wMDAwMDAwMDAwMDAwNiIgZmlsbD0iI0VDRUNGRiIgc3Ryb2tlPSIjRUNFQ0ZGIiBzdHJva2Utd2lkdGg9IjAiLz48cmVjdCB4PSI0MjIuOTQ3MjY2MjYwNzgyOSIgeT0iMzkxIiB3aWR0aD0iOTUiIGhlaWdodD0iNzYiIGZpbGw9IiNFQ0VDRkYiIHN0cm9rZT0iI0VDRUNGRiIgc3Ryb2tlLXdpZHRoPSIwIi8+PHJlY3QgeD0iNjAyLjUiIHk9IjE1MyIgd2lkdGg9Ijk1IiBoZWlnaHQ9IjMxNCIgZmlsbD0iI0VDRUNGRiIgc3Ryb2tlPSIjRUNFQ0ZGIiBzdHJva2Utd2lkdGg9IjAiLz48L2c+PGcgY2xhc3M9ImxpbmUtcGxvdC0xIj48cGF0aCBkPSJNMTExLjM0MiwzNTdMMjkwLjg5NSwyODlMNDcwLjQ0NywzOTFMNjUwLDE1MyIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjODQ5M0E2IiBzdHJva2Utd2lkdGg9IjIiLz48L2c+PC9nPjxnIGNsYXNzPSJib3R0b20tYXhpcyI+PGcgY2xhc3M9ImF4aXMtbGluZSI+PHBhdGggZD0iTSA2MS4zNDE3OTg3ODIzNDg2Myw0NjggTCA3MDAsNDY4IiBmaWxsPSJub25lIiBzdHJva2U9IiMxMzEzMDAiIHN0cm9rZS13aWR0aD0iMiIvPjwvZz48ZyBjbGFzcz0ibGFiZWwiPjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMxMzEzMDAiIGZvbnQtc2l6ZT0iMTQiIGRvbWluYW50LWJhc2VsaW5lPSJ0ZXh0LWJlZm9yZS1lZGdlIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMTEuMzQxNzk4NzgyMzQ4NjMsIDQ3OSkgcm90YXRlKDApIj4yMDI2LVczNjwvdGV4dD48dGV4dCB4PSIwIiB5PSIwIiBmaWxsPSIjMTMxMzAwIiBmb250LXNpemU9IjE0IiBkb21pbmFudC1iYXNlbGluZT0idGV4dC1iZWZvcmUtZWRnZSIgdGV4dC1hbmNob3I9Im1pZGRsZSIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMjkwLjg5NDUzMjUyMTU2NTgsIDQ3OSkgcm90YXRlKDApIj4yMDI2LVczNzwvdGV4dD48dGV4dCB4PSIwIiB5PSIwIiBmaWxsPSIjMTMxMzAwIiBmb250LXNpemU9IjE0IiBkb21pbmFudC1iYXNlbGluZT0idGV4dC1iZWZvcmUtZWRnZSIgdGV4dC1hbmNob3I9Im1pZGRsZSIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNDcwLjQ0NzI2NjI2MDc4MjksIDQ3OSkgcm90YXRlKDApIj4yMDI2LVczODwvdGV4dD48dGV4dCB4PSIwIiB5PSIwIiBmaWxsPSIjMTMxMzAwIiBmb250LXNpemU9IjE0IiBkb21pbmFudC1iYXNlbGluZT0idGV4dC1iZWZvcmUtZWRnZSIgdGV4dC1hbmNob3I9Im1pZGRsZSIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNjUwLCA0NzkpIHJvdGF0ZSgwKSI+MjAyNi1XMzk8L3RleHQ+PC9nPjxnIGNsYXNzPSJ0aWNrcyI+PHBhdGggZD0iTSAxMTEuMzQxNzk4NzgyMzQ4NjMsNDY5IEwgMTExLjM0MTc5ODc4MjM0ODYzLDQ3NCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjMTMxMzAwIiBzdHJva2Utd2lkdGg9IjIiLz48cGF0aCBkPSJNIDI5MC44OTQ1MzI1MjE1NjU4LDQ2OSBMIDI5MC44OTQ1MzI1MjE1NjU4LDQ3NCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjMTMxMzAwIiBzdHJva2Utd2lkdGg9IjIiLz48cGF0aCBkPSJNIDQ3MC40NDcyNjYyNjA3ODI5LDQ2OSBMIDQ3MC40NDcyNjYyNjA3ODI5LDQ3NCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjMTMxMzAwIiBzdHJva2Utd2lkdGg9IjIiLz48cGF0aCBkPSJNIDY1MCw0NjkgTCA2NTAsNDc0IiBmaWxsPSJub25lIiBzdHJva2U9IiMxMzEzMDAiIHN0cm9rZS13aWR0aD0iMiIvPjwvZz48L2c+PGcgY2xhc3M9ImxlZnQtYXhpcyI+PGcgY2xhc3M9ImF4aXNsLWxpbmUiPjxwYXRoIGQ9Ik0gNjAuMzQxNzk4NzgyMzQ4NjMsNDMgTCA2MC4zNDE3OTg3ODIzNDg2Myw0NjciIGZpbGw9Im5vbmUiIHN0cm9rZT0iIzEzMTMwMCIgc3Ryb2tlLXdpZHRoPSIyIi8+PC9nPjxnIGNsYXNzPSJsYWJlbCI+PHRleHQgeD0iMCIgeT0iMCIgZmlsbD0iIzEzMTMwMCIgZm9udC1zaXplPSIxNCIgZG9taW5hbnQtYmFzZWxpbmU9Im1pZGRsZSIgdGV4dC1hbmNob3I9ImVuZCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNDkuMzQxNzk4NzgyMzQ4NjMsIDUxKSByb3RhdGUoMCkiPjEyPC90ZXh0Pjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMxMzEzMDAiIGZvbnQtc2l6ZT0iMTQiIGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiIHRleHQtYW5jaG9yPSJlbmQiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDQ5LjM0MTc5ODc4MjM0ODYzLCA4NS4wMDAwMDAwMDAwMDAwMSkgcm90YXRlKDApIj4xMTwvdGV4dD48dGV4dCB4PSIwIiB5PSIwIiBmaWxsPSIjMTMxMzAwIiBmb250LXNpemU9IjE0IiBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiB0ZXh0LWFuY2hvcj0iZW5kIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSg0OS4zNDE3OTg3ODIzNDg2MywgMTE4Ljk5OTk5OTk5OTk5OTk5KSByb3RhdGUoMCkiPjEwPC90ZXh0Pjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMxMzEzMDAiIGZvbnQtc2l6ZT0iMTQiIGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiIHRleHQtYW5jaG9yPSJlbmQiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDQ5LjM0MTc5ODc4MjM0ODYzLCAxNTMpIHJvdGF0ZSgwKSI+OTwvdGV4dD48dGV4dCB4PSIwIiB5PSIwIiBmaWxsPSIjMTMxMzAwIiBmb250LXNpemU9IjE0IiBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiB0ZXh0LWFuY2hvcj0iZW5kIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSg0OS4zNDE3OTg3ODIzNDg2MywgMTg3LjAwMDAwMDAwMDAwMDAzKSByb3RhdGUoMCkiPjg8L3RleHQ+PHRleHQgeD0iMCIgeT0iMCIgZmlsbD0iIzEzMTMwMCIgZm9udC1zaXplPSIxNCIgZG9taW5hbnQtYmFzZWxpbmU9Im1pZGRsZSIgdGV4dC1hbmNob3I9ImVuZCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNDkuMzQxNzk4NzgyMzQ4NjMsIDIyMC45OTk5OTk5OTk5OTk5Nykgcm90YXRlKDApIj43PC90ZXh0Pjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMxMzEzMDAiIGZvbnQtc2l6ZT0iMTQiIGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiIHRleHQtYW5jaG9yPSJlbmQiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDQ5LjM0MTc5ODc4MjM0ODYzLCAyNTUpIHJvdGF0ZSgwKSI+NjwvdGV4dD48dGV4dCB4PSIwIiB5PSIwIiBmaWxsPSIjMTMxMzAwIiBmb250LXNpemU9IjE0IiBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiB0ZXh0LWFuY2hvcj0iZW5kIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSg0OS4zNDE3OTg3ODIzNDg2MywgMjg4Ljk5OTk5OTk5OTk5OTk0KSByb3RhdGUoMCkiPjU8L3RleHQ+PHRleHQgeD0iMCIgeT0iMCIgZmlsbD0iIzEzMTMwMCIgZm9udC1zaXplPSIxNCIgZG9taW5hbnQtYmFzZWxpbmU9Im1pZGRsZSIgdGV4dC1hbmNob3I9ImVuZCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNDkuMzQxNzk4NzgyMzQ4NjMsIDMyMy4wMDAwMDAwMDAwMDAwNikgcm90YXRlKDApIj40PC90ZXh0Pjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMxMzEzMDAiIGZvbnQtc2l6ZT0iMTQiIGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiIHRleHQtYW5jaG9yPSJlbmQiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDQ5LjM0MTc5ODc4MjM0ODYzLCAzNTcpIHJvdGF0ZSgwKSI+MzwvdGV4dD48dGV4dCB4PSIwIiB5PSIwIiBmaWxsPSIjMTMxMzAwIiBmb250LXNpemU9IjE0IiBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiB0ZXh0LWFuY2hvcj0iZW5kIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSg0OS4zNDE3OTg3ODIzNDg2MywgMzkxKSByb3RhdGUoMCkiPjI8L3RleHQ+PHRleHQgeD0iMCIgeT0iMCIgZmlsbD0iIzEzMTMwMCIgZm9udC1zaXplPSIxNCIgZG9taW5hbnQtYmFzZWxpbmU9Im1pZGRsZSIgdGV4dC1hbmNob3I9ImVuZCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNDkuMzQxNzk4NzgyMzQ4NjMsIDQyNSkgcm90YXRlKDApIj4xPC90ZXh0Pjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMxMzEzMDAiIGZvbnQtc2l6ZT0iMTQiIGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiIHRleHQtYW5jaG9yPSJlbmQiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDQ5LjM0MTc5ODc4MjM0ODYzLCA0NTkpIHJvdGF0ZSgwKSI+MDwvdGV4dD48L2c+PGcgY2xhc3M9InRpY2tzIj48cGF0aCBkPSJNIDU5LjM0MTc5ODc4MjM0ODYzLDUxIEwgNTQuMzQxNzk4NzgyMzQ4NjMsNTEiIGZpbGw9Im5vbmUiIHN0cm9rZT0iIzEzMTMwMCIgc3Ryb2tlLXdpZHRoPSIyIi8+PHBhdGggZD0iTSA1OS4zNDE3OTg3ODIzNDg2Myw4NS4wMDAwMDAwMDAwMDAwMSBMIDU0LjM0MTc5ODc4MjM0ODYzLDg1LjAwMDAwMDAwMDAwMDAxIiBmaWxsPSJub25lIiBzdHJva2U9IiMxMzEzMDAiIHN0cm9rZS13aWR0aD0iMiIvPjxwYXRoIGQ9Ik0gNTkuMzQxNzk4NzgyMzQ4NjMsMTE4Ljk5OTk5OTk5OTk5OTk5IEwgNTQuMzQxNzk4NzgyMzQ4NjMsMTE4Ljk5OTk5OTk5OTk5OTk5IiBmaWxsPSJub25lIiBzdHJva2U9IiMxMzEzMDAiIHN0cm9rZS13aWR0aD0iMiIvPjxwYXRoIGQ9Ik0gNTkuMzQxNzk4NzgyMzQ4NjMsMTUzIEwgNTQuMzQxNzk4NzgyMzQ4NjMsMTUzIiBmaWxsPSJub25lIiBzdHJva2U9IiMxMzEzMDAiIHN0cm9rZS13aWR0aD0iMiIvPjxwYXRoIGQ9Ik0gNTkuMzQxNzk4NzgyMzQ4NjMsMTg3LjAwMDAwMDAwMDAwMDAzIEwgNTQuMzQxNzk4NzgyMzQ4NjMsMTg3LjAwMDAwMDAwMDAwMDAzIiBmaWxsPSJub25lIiBzdHJva2U9IiMxMzEzMDAiIHN0cm9rZS13aWR0aD0iMiIvPjxwYXRoIGQ9Ik0gNTkuMzQxNzk4NzgyMzQ4NjMsMjIwLjk5OTk5OTk5OTk5OTk3IEwgNTQuMzQxNzk4NzgyMzQ4NjMsMjIwLjk5OTk5OTk5OTk5OTk3IiBmaWxsPSJub25lIiBzdHJva2U9IiMxMzEzMDAiIHN0cm9rZS13aWR0aD0iMiIvPjxwYXRoIGQ9Ik0gNTkuMzQxNzk4NzgyMzQ4NjMsMjU1IEwgNTQuMzQxNzk4NzgyMzQ4NjMsMjU1IiBmaWxsPSJub25lIiBzdHJva2U9IiMxMzEzMDAiIHN0cm9rZS13aWR0aD0iMiIvPjxwYXRoIGQ9Ik0gNTkuMzQxNzk4NzgyMzQ4NjMsMjg4Ljk5OTk5OTk5OTk5OTk0IEwgNTQuMzQxNzk4NzgyMzQ4NjMsMjg4Ljk5OTk5OTk5OTk5OTk0IiBmaWxsPSJub25lIiBzdHJva2U9IiMxMzEzMDAiIHN0cm9rZS13aWR0aD0iMiIvPjxwYXRoIGQ9Ik0gNTkuMzQxNzk4NzgyMzQ4NjMsMzIzLjAwMDAwMDAwMDAwMDA2IEwgNTQuMzQxNzk4NzgyMzQ4NjMsMzIzLjAwMDAwMDAwMDAwMDA2IiBmaWxsPSJub25lIiBzdHJva2U9IiMxMzEzMDAiIHN0cm9rZS13aWR0aD0iMiIvPjxwYXRoIGQ9Ik0gNTkuMzQxNzk4NzgyMzQ4NjMsMzU3IEwgNTQuMzQxNzk4NzgyMzQ4NjMsMzU3IiBmaWxsPSJub25lIiBzdHJva2U9IiMxMzEzMDAiIHN0cm9rZS13aWR0aD0iMiIvPjxwYXRoIGQ9Ik0gNTkuMzQxNzk4NzgyMzQ4NjMsMzkxIEwgNTQuMzQxNzk4NzgyMzQ4NjMsMzkxIiBmaWxsPSJub25lIiBzdHJva2U9IiMxMzEzMDAiIHN0cm9rZS13aWR0aD0iMiIvPjxwYXRoIGQ9Ik0gNTkuMzQxNzk4NzgyMzQ4NjMsNDI1IEwgNTQuMzQxNzk4NzgyMzQ4NjMsNDI1IiBmaWxsPSJub25lIiBzdHJva2U9IiMxMzEzMDAiIHN0cm9rZS13aWR0aD0iMiIvPjxwYXRoIGQ9Ik0gNTkuMzQxNzk4NzgyMzQ4NjMsNDU5IEwgNTQuMzQxNzk4NzgyMzQ4NjMsNDU5IiBmaWxsPSJub25lIiBzdHJva2U9IiMxMzEzMDAiIHN0cm9rZS13aWR0aD0iMiIvPjwvZz48ZyBjbGFzcz0idGl0bGUiPjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMxMzEzMDAiIGZvbnQtc2l6ZT0iMTYiIGRvbWluYW50LWJhc2VsaW5lPSJ0ZXh0LWJlZm9yZS1lZGdlIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSg1LCAyNTUpIHJvdGF0ZSgyNzApIj5JbmNpZGVudHM8L3RleHQ+PC9nPjwvZz48L2c+PGcgY2xhc3M9Im1lcm1haWQtdG1wLWdyb3VwIi8+PC9zdmc+) The same data as bars and a line overlaid: bars for the raw count, line for the trend your eye needs. The `W39: 9` spike is the arrow on this chart — the week a deploy went sideways. Because the chart is text, the next review reads the numbers, not a screenshot of them. ## Copy-paste 3: the dual-series release dashboard[​](#copy-paste-3-the-dual-series-release-dashboard "Direct link to Copy-paste 3: the dual-series release dashboard") Dashboards get nuanced: two numbers that must be read together. `xychart-beta` supports multiple series on one chart — bars for one metric, a line for the other, on a shared axis: ``` xychart-beta %% title: Bugs caught in staging vs leaked to production title "Bugs caught in staging vs leaked to production" x-axis [Sprint 1, Sprint 2, Sprint 3, Sprint 4, Sprint 5] y-axis "Bugs" 0 --> 16 bar [12, 13, 11, 15, 14] line [4, 3, 3, 2, 2] ``` ![Bugs caught in staging vs leaked to production](data:image/svg+xml;base64,PHN2ZyBpZD0ibXktc3ZnIiB3aWR0aD0iMTAwJSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgc3R5bGU9Im1heC13aWR0aDogNzAwcHg7IGJhY2tncm91bmQtY29sb3I6IHdoaXRlOyIgdmlld0JveD0iMCAwIDcwMCA1MDAiIHJvbGU9ImdyYXBoaWNzLWRvY3VtZW50IGRvY3VtZW50IiBhcmlhLXJvbGVkZXNjcmlwdGlvbj0ieHljaGFydCI+PHN0eWxlPiNteS1zdmd7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO2ZvbnQtc2l6ZToxNnB4O2ZpbGw6IzMzMzt9QGtleWZyYW1lcyBlZGdlLWFuaW1hdGlvbi1mcmFtZXtmcm9te3N0cm9rZS1kYXNob2Zmc2V0OjA7fX1Aa2V5ZnJhbWVzIGRhc2h7dG97c3Ryb2tlLWRhc2hvZmZzZXQ6MDt9fSNteS1zdmcgLmVkZ2UtYW5pbWF0aW9uLXNsb3d7c3Ryb2tlLWRhc2hhcnJheTo5LDUhaW1wb3J0YW50O3N0cm9rZS1kYXNob2Zmc2V0OjkwMDthbmltYXRpb246ZGFzaCA1MHMgbGluZWFyIGluZmluaXRlO3N0cm9rZS1saW5lY2FwOnJvdW5kO30jbXktc3ZnIC5lZGdlLWFuaW1hdGlvbi1mYXN0e3N0cm9rZS1kYXNoYXJyYXk6OSw1IWltcG9ydGFudDtzdHJva2UtZGFzaG9mZnNldDo5MDA7YW5pbWF0aW9uOmRhc2ggMjBzIGxpbmVhciBpbmZpbml0ZTtzdHJva2UtbGluZWNhcDpyb3VuZDt9I215LXN2ZyAuZXJyb3ItaWNvbntmaWxsOiM1NTIyMjI7fSNteS1zdmcgLmVycm9yLXRleHR7ZmlsbDojNTUyMjIyO3N0cm9rZTojNTUyMjIyO30jbXktc3ZnIC5lZGdlLXRoaWNrbmVzcy1ub3JtYWx7c3Ryb2tlLXdpZHRoOjFweDt9I215LXN2ZyAuZWRnZS10aGlja25lc3MtdGhpY2t7c3Ryb2tlLXdpZHRoOjMuNXB4O30jbXktc3ZnIC5lZGdlLXBhdHRlcm4tc29saWR7c3Ryb2tlLWRhc2hhcnJheTowO30jbXktc3ZnIC5lZGdlLXRoaWNrbmVzcy1pbnZpc2libGV7c3Ryb2tlLXdpZHRoOjA7ZmlsbDpub25lO30jbXktc3ZnIC5lZGdlLXBhdHRlcm4tZGFzaGVke3N0cm9rZS1kYXNoYXJyYXk6Mzt9I215LXN2ZyAuZWRnZS1wYXR0ZXJuLWRvdHRlZHtzdHJva2UtZGFzaGFycmF5OjI7fSNteS1zdmcgLm1hcmtlcntmaWxsOiMzMzMzMzM7c3Ryb2tlOiMzMzMzMzM7fSNteS1zdmcgLm1hcmtlci5jcm9zc3tzdHJva2U6IzMzMzMzMzt9I215LXN2ZyBzdmd7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO2ZvbnQtc2l6ZToxNnB4O30jbXktc3ZnIHB7bWFyZ2luOjA7fSNteS1zdmcgLm5vZGUgLm5lby1ub2Rle3N0cm9rZTojOTM3MERCO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcmVjdCwjbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLmNsdXN0ZXIgcmVjdCwjbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcG9seWdvbntzdHJva2U6IzkzNzBEQjtmaWx0ZXI6ZHJvcC1zaGFkb3coMXB4IDJweCAycHggcmdiYSgxODUsIDE4NSwgMTg1LCAxKSk7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uc3dpbWxhbmUuY2x1c3RlciByZWN0e2ZpbHRlcjpub25lO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcGF0aHtzdHJva2U6IzkzNzBEQjtzdHJva2Utd2lkdGg6MXB4O30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgLm91dGVyLXBhdGh7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgLm5lby1saW5lIHBhdGh7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOm5vbmU7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSBjaXJjbGV7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgY2lyY2xlIC5zdGF0ZS1zdGFydHtmaWxsOiMwMDAwMDA7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uaWNvbi1zaGFwZSAuaWNvbntmaWxsOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLmljb24tc2hhcGUgLmljb24tbmVvIHBhdGh7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIDpyb290ey0tbWVybWFpZC1mb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7fTwvc3R5bGU+PGcvPjxnIGNsYXNzPSJtYWluIj48cmVjdCB3aWR0aD0iNzAwIiBoZWlnaHQ9IjUwMCIgY2xhc3M9ImJhY2tncm91bmQiIGZpbGw9IndoaXRlIi8+PGcgY2xhc3M9ImNoYXJ0LXRpdGxlIj48dGV4dCB4PSIwIiB5PSIwIiBmaWxsPSIjMTMxMzAwIiBmb250LXNpemU9IjIwIiBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgzNTAsIDIxLjUpIHJvdGF0ZSgwKSI+QnVncyBjYXVnaHQgaW4gc3RhZ2luZyB2cyBsZWFrZWQgdG8gcHJvZHVjdGlvbjwvdGV4dD48L2c+PGcgY2xhc3M9InBsb3QiPjxnIGNsYXNzPSJiYXItcGxvdC0wIj48cmVjdCB4PSI2My4zOTE3OTg3ODIzNDg2NCIgeT0iMTUzIiB3aWR0aD0iNzcuODk5OTk5OTk5OTk5OTkiIGhlaWdodD0iMzE0IiBmaWxsPSIjRUNFQ0ZGIiBzdHJva2U9IiNFQ0VDRkYiIHN0cm9rZS13aWR0aD0iMCIvPjxyZWN0IHg9IjIwMi41NTYzNDkwODY3NjE1IiB5PSIxMjcuNSIgd2lkdGg9Ijc3Ljg5OTk5OTk5OTk5OTk5IiBoZWlnaHQ9IjMzOS41IiBmaWxsPSIjRUNFQ0ZGIiBzdHJva2U9IiNFQ0VDRkYiIHN0cm9rZS13aWR0aD0iMCIvPjxyZWN0IHg9IjM0MS43MjA4OTkzOTExNzQzIiB5PSIxNzguNSIgd2lkdGg9Ijc3Ljg5OTk5OTk5OTk5OTk5IiBoZWlnaHQ9IjI4OC41IiBmaWxsPSIjRUNFQ0ZGIiBzdHJva2U9IiNFQ0VDRkYiIHN0cm9rZS13aWR0aD0iMCIvPjxyZWN0IHg9IjQ4MC44ODU0NDk2OTU1ODcxNyIgeT0iNzYuNSIgd2lkdGg9Ijc3Ljg5OTk5OTk5OTk5OTk5IiBoZWlnaHQ9IjM5MC41IiBmaWxsPSIjRUNFQ0ZGIiBzdHJva2U9IiNFQ0VDRkYiIHN0cm9rZS13aWR0aD0iMCIvPjxyZWN0IHg9IjYyMC4wNSIgeT0iMTAyIiB3aWR0aD0iNzcuODk5OTk5OTk5OTk5OTkiIGhlaWdodD0iMzY1IiBmaWxsPSIjRUNFQ0ZGIiBzdHJva2U9IiNFQ0VDRkYiIHN0cm9rZS13aWR0aD0iMCIvPjwvZz48ZyBjbGFzcz0ibGluZS1wbG90LTEiPjxwYXRoIGQ9Ik0xMDIuMzQyLDM1N0wyNDEuNTA2LDM4Mi41TDM4MC42NzEsMzgyLjVMNTE5LjgzNSw0MDhMNjU5LDQwOCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjODQ5M0E2IiBzdHJva2Utd2lkdGg9IjIiLz48L2c+PC9nPjxnIGNsYXNzPSJib3R0b20tYXhpcyI+PGcgY2xhc3M9ImF4aXMtbGluZSI+PHBhdGggZD0iTSA2MS4zNDE3OTg3ODIzNDg2Myw0NjggTCA3MDAsNDY4IiBmaWxsPSJub25lIiBzdHJva2U9IiMxMzEzMDAiIHN0cm9rZS13aWR0aD0iMiIvPjwvZz48ZyBjbGFzcz0ibGFiZWwiPjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMxMzEzMDAiIGZvbnQtc2l6ZT0iMTQiIGRvbWluYW50LWJhc2VsaW5lPSJ0ZXh0LWJlZm9yZS1lZGdlIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMDIuMzQxNzk4NzgyMzQ4NjMsIDQ3OSkgcm90YXRlKDApIj5TcHJpbnQxPC90ZXh0Pjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMxMzEzMDAiIGZvbnQtc2l6ZT0iMTQiIGRvbWluYW50LWJhc2VsaW5lPSJ0ZXh0LWJlZm9yZS1lZGdlIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgyNDEuNTA2MzQ5MDg2NzYxNDcsIDQ3OSkgcm90YXRlKDApIj5TcHJpbnQyPC90ZXh0Pjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMxMzEzMDAiIGZvbnQtc2l6ZT0iMTQiIGRvbWluYW50LWJhc2VsaW5lPSJ0ZXh0LWJlZm9yZS1lZGdlIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgzODAuNjcwODk5MzkxMTc0MywgNDc5KSByb3RhdGUoMCkiPlNwcmludDM8L3RleHQ+PHRleHQgeD0iMCIgeT0iMCIgZmlsbD0iIzEzMTMwMCIgZm9udC1zaXplPSIxNCIgZG9taW5hbnQtYmFzZWxpbmU9InRleHQtYmVmb3JlLWVkZ2UiIHRleHQtYW5jaG9yPSJtaWRkbGUiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDUxOS44MzU0NDk2OTU1ODcyLCA0NzkpIHJvdGF0ZSgwKSI+U3ByaW50NDwvdGV4dD48dGV4dCB4PSIwIiB5PSIwIiBmaWxsPSIjMTMxMzAwIiBmb250LXNpemU9IjE0IiBkb21pbmFudC1iYXNlbGluZT0idGV4dC1iZWZvcmUtZWRnZSIgdGV4dC1hbmNob3I9Im1pZGRsZSIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNjU5LCA0NzkpIHJvdGF0ZSgwKSI+U3ByaW50NTwvdGV4dD48L2c+PGcgY2xhc3M9InRpY2tzIj48cGF0aCBkPSJNIDEwMi4zNDE3OTg3ODIzNDg2Myw0NjkgTCAxMDIuMzQxNzk4NzgyMzQ4NjMsNDc0IiBmaWxsPSJub25lIiBzdHJva2U9IiMxMzEzMDAiIHN0cm9rZS13aWR0aD0iMiIvPjxwYXRoIGQ9Ik0gMjQxLjUwNjM0OTA4Njc2MTQ3LDQ2OSBMIDI0MS41MDYzNDkwODY3NjE0Nyw0NzQiIGZpbGw9Im5vbmUiIHN0cm9rZT0iIzEzMTMwMCIgc3Ryb2tlLXdpZHRoPSIyIi8+PHBhdGggZD0iTSAzODAuNjcwODk5MzkxMTc0Myw0NjkgTCAzODAuNjcwODk5MzkxMTc0Myw0NzQiIGZpbGw9Im5vbmUiIHN0cm9rZT0iIzEzMTMwMCIgc3Ryb2tlLXdpZHRoPSIyIi8+PHBhdGggZD0iTSA1MTkuODM1NDQ5Njk1NTg3Miw0NjkgTCA1MTkuODM1NDQ5Njk1NTg3Miw0NzQiIGZpbGw9Im5vbmUiIHN0cm9rZT0iIzEzMTMwMCIgc3Ryb2tlLXdpZHRoPSIyIi8+PHBhdGggZD0iTSA2NTksNDY5IEwgNjU5LDQ3NCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjMTMxMzAwIiBzdHJva2Utd2lkdGg9IjIiLz48L2c+PC9nPjxnIGNsYXNzPSJsZWZ0LWF4aXMiPjxnIGNsYXNzPSJheGlzbC1saW5lIj48cGF0aCBkPSJNIDYwLjM0MTc5ODc4MjM0ODYzLDQzIEwgNjAuMzQxNzk4NzgyMzQ4NjMsNDY3IiBmaWxsPSJub25lIiBzdHJva2U9IiMxMzEzMDAiIHN0cm9rZS13aWR0aD0iMiIvPjwvZz48ZyBjbGFzcz0ibGFiZWwiPjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMxMzEzMDAiIGZvbnQtc2l6ZT0iMTQiIGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiIHRleHQtYW5jaG9yPSJlbmQiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDQ5LjM0MTc5ODc4MjM0ODYzLCA1MSkgcm90YXRlKDApIj4xNjwvdGV4dD48dGV4dCB4PSIwIiB5PSIwIiBmaWxsPSIjMTMxMzAwIiBmb250LXNpemU9IjE0IiBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiB0ZXh0LWFuY2hvcj0iZW5kIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSg0OS4zNDE3OTg3ODIzNDg2MywgMTAyKSByb3RhdGUoMCkiPjE0PC90ZXh0Pjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMxMzEzMDAiIGZvbnQtc2l6ZT0iMTQiIGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiIHRleHQtYW5jaG9yPSJlbmQiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDQ5LjM0MTc5ODc4MjM0ODYzLCAxNTMpIHJvdGF0ZSgwKSI+MTI8L3RleHQ+PHRleHQgeD0iMCIgeT0iMCIgZmlsbD0iIzEzMTMwMCIgZm9udC1zaXplPSIxNCIgZG9taW5hbnQtYmFzZWxpbmU9Im1pZGRsZSIgdGV4dC1hbmNob3I9ImVuZCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNDkuMzQxNzk4NzgyMzQ4NjMsIDIwNCkgcm90YXRlKDApIj4xMDwvdGV4dD48dGV4dCB4PSIwIiB5PSIwIiBmaWxsPSIjMTMxMzAwIiBmb250LXNpemU9IjE0IiBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiB0ZXh0LWFuY2hvcj0iZW5kIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSg0OS4zNDE3OTg3ODIzNDg2MywgMjU1KSByb3RhdGUoMCkiPjg8L3RleHQ+PHRleHQgeD0iMCIgeT0iMCIgZmlsbD0iIzEzMTMwMCIgZm9udC1zaXplPSIxNCIgZG9taW5hbnQtYmFzZWxpbmU9Im1pZGRsZSIgdGV4dC1hbmNob3I9ImVuZCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNDkuMzQxNzk4NzgyMzQ4NjMsIDMwNikgcm90YXRlKDApIj42PC90ZXh0Pjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMxMzEzMDAiIGZvbnQtc2l6ZT0iMTQiIGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiIHRleHQtYW5jaG9yPSJlbmQiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDQ5LjM0MTc5ODc4MjM0ODYzLCAzNTcpIHJvdGF0ZSgwKSI+NDwvdGV4dD48dGV4dCB4PSIwIiB5PSIwIiBmaWxsPSIjMTMxMzAwIiBmb250LXNpemU9IjE0IiBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiB0ZXh0LWFuY2hvcj0iZW5kIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSg0OS4zNDE3OTg3ODIzNDg2MywgNDA4KSByb3RhdGUoMCkiPjI8L3RleHQ+PHRleHQgeD0iMCIgeT0iMCIgZmlsbD0iIzEzMTMwMCIgZm9udC1zaXplPSIxNCIgZG9taW5hbnQtYmFzZWxpbmU9Im1pZGRsZSIgdGV4dC1hbmNob3I9ImVuZCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNDkuMzQxNzk4NzgyMzQ4NjMsIDQ1OSkgcm90YXRlKDApIj4wPC90ZXh0PjwvZz48ZyBjbGFzcz0idGlja3MiPjxwYXRoIGQ9Ik0gNTkuMzQxNzk4NzgyMzQ4NjMsNTEgTCA1NC4zNDE3OTg3ODIzNDg2Myw1MSIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjMTMxMzAwIiBzdHJva2Utd2lkdGg9IjIiLz48cGF0aCBkPSJNIDU5LjM0MTc5ODc4MjM0ODYzLDEwMiBMIDU0LjM0MTc5ODc4MjM0ODYzLDEwMiIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjMTMxMzAwIiBzdHJva2Utd2lkdGg9IjIiLz48cGF0aCBkPSJNIDU5LjM0MTc5ODc4MjM0ODYzLDE1MyBMIDU0LjM0MTc5ODc4MjM0ODYzLDE1MyIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjMTMxMzAwIiBzdHJva2Utd2lkdGg9IjIiLz48cGF0aCBkPSJNIDU5LjM0MTc5ODc4MjM0ODYzLDIwNCBMIDU0LjM0MTc5ODc4MjM0ODYzLDIwNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjMTMxMzAwIiBzdHJva2Utd2lkdGg9IjIiLz48cGF0aCBkPSJNIDU5LjM0MTc5ODc4MjM0ODYzLDI1NSBMIDU0LjM0MTc5ODc4MjM0ODYzLDI1NSIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjMTMxMzAwIiBzdHJva2Utd2lkdGg9IjIiLz48cGF0aCBkPSJNIDU5LjM0MTc5ODc4MjM0ODYzLDMwNiBMIDU0LjM0MTc5ODc4MjM0ODYzLDMwNiIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjMTMxMzAwIiBzdHJva2Utd2lkdGg9IjIiLz48cGF0aCBkPSJNIDU5LjM0MTc5ODc4MjM0ODYzLDM1NyBMIDU0LjM0MTc5ODc4MjM0ODYzLDM1NyIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjMTMxMzAwIiBzdHJva2Utd2lkdGg9IjIiLz48cGF0aCBkPSJNIDU5LjM0MTc5ODc4MjM0ODYzLDQwOCBMIDU0LjM0MTc5ODc4MjM0ODYzLDQwOCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjMTMxMzAwIiBzdHJva2Utd2lkdGg9IjIiLz48cGF0aCBkPSJNIDU5LjM0MTc5ODc4MjM0ODYzLDQ1OSBMIDU0LjM0MTc5ODc4MjM0ODYzLDQ1OSIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjMTMxMzAwIiBzdHJva2Utd2lkdGg9IjIiLz48L2c+PGcgY2xhc3M9InRpdGxlIj48dGV4dCB4PSIwIiB5PSIwIiBmaWxsPSIjMTMxMzAwIiBmb250LXNpemU9IjE2IiBkb21pbmFudC1iYXNlbGluZT0idGV4dC1iZWZvcmUtZWRnZSIgdGV4dC1hbmNob3I9Im1pZGRsZSIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNSwgMjU1KSByb3RhdGUoMjcwKSI+QnVnczwvdGV4dD48L2c+PC9nPjwvZz48ZyBjbGFzcz0ibWVybWFpZC10bXAtZ3JvdXAiLz48L3N2Zz4=) Bars for bugs caught in staging, line for the leaks that still reach production: the trend story — "the pipeline catches more nearly every sprint" — reads without a table. Same units, one axis, honest comparison; the shrinking gap between the two lines is the metric the release review cares about. This is the chart to keep beside the releases page each sprint. ## Charts that behave like the report[​](#charts-that-behave-like-the-report "Direct link to Charts that behave like the report") The durability trick is the same across every Mermaid type here: the chart is text, so it updates in the same gesture as the numbers it reports. In [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), edit a value in the live preview and the SVG redraws — press Enter, and the wiki chart matches the spreadsheet, no export step. When the quarterly review asks for the current numbers, the current numbers are already on the page, because the page's chart is the numbers. Screenshots rot on a schedule; text charts rot never, because every update is a diff. Keep the pie for the mix, the XY for the trend, and the dashboard will answer the two questions people actually ask. ## Where this lives beside your other Confluence diagrams[​](#where-this-lives-beside-your-other-confluence-diagrams "Direct link to Where this lives beside your other Confluence diagrams") Charts cover the numbers; diagrams cover the structures. Keep the pie and XY on the dashboard page (this post), the process that produces the numbers as a state diagram ([states & approval workflows](/blog/mermaid-state-diagram-workflow-confluence.md)), and the pipeline behind the release metrics as a flowchart ([CI/CD pipeline diagrams](/blog/mermaid-ci-cd-pipeline-diagram-confluence.md)). One space, three diagram types, and the numbers always fresh. ## FAQ[​](#faq "Direct link to FAQ") **Does Mermaid support pie charts and bar charts in Confluence?** Yes — Mermaid pie and xychart-beta (bars/lines) both render text to SVG. Mermaid Plus Diagrams & AI Agent for Confluence renders them live as you type. **When should I use a pie vs. an XY chart?** Pie for a share with few categories (under 6 reads best); XY for a trend or comparison across a category axis. Pick by the question the chart must answer. **How do I label slices or hide the pie legend?** Labels come from the quoted data lines; add `pie showData` to print percentages on the slices. The legend always shows category names (each slice has none unless you add showData). **Can I put multiple series on an XY chart?** Yes — xychart-beta supports multiple data series with a legend on a shared axis. Keep the series on the same unit so the comparison is honest (bars for one metric, line for another, same scale); example 3 shows a caught-vs-leaked pairing. Render every Mermaid diagram type — pie, XY, state, flowchart, class and 24 more — in [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), free for up to 10 users. Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [pie-chart](/blog/tags/pie-chart.md) * [xychart-beta](/blog/tags/xychart-beta.md) * [dashboard](/blog/tags/dashboard.md) * [how-to](/blog/tags/how-to.md) --- # CI/CD Pipeline Diagrams in Confluence with Mermaid (Copy-Paste) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) A build fails at 4pm, and the fix's pipeline takes 40 minutes to re-run from the top because someone decided every stage needs to re-validate. That wasted hour is not a code problem — it is a **documentation** problem. Nobody could see the pipeline's shape, so nobody saw the retry loop and the gate that would have caught the failure three stages earlier. **Quick answer:** put the pipeline's shape in Confluence as a Mermaid `flowchart`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Text-based, editable, diffable — a pipeline diagram that changes when your pipeline changes. This post gives you three copy-paste examples: the linear stage view, quality gates with retry loops, and the deploy-to-tag gitGraph that records what actually shipped. ## Why the pipeline's shape belongs in the wiki[​](#why-the-pipelines-shape-belongs-in-the-wiki "Direct link to Why the pipeline's shape belongs in the wiki") A diagram of your CI/CD pipeline is the answer to the three questions every teammate asks with a red build on screen: * **Where are we?** Which stage failed, and what came before it * **What gets rerun?** Do fixes restart the whole pipeline or just the failed stage * **Where does it stop?** What has to pass for a deploy to actually go out Text in a README answers these slowly. A diagram answers them at a glance — and because it is Mermaid text, it answers them *accurately*. When someone edits the pipeline, editing one arrow in the Confluence page keeps the doc honest. ## Copy-paste 1: the linear stage view[​](#copy-paste-1-the-linear-stage-view "Direct link to Copy-paste 1: the linear stage view") Start with the version that matches your pipeline dashboard: stages in a row, biggest gate near the end. This is the diagram to lead with in the space overview — everyone recognizes their own pipeline in it. ``` flowchart LR %% title: CI/CD pipeline — linear stage view A[Commit] --> B[Build] B --> C[Unit tests] C --> D[Integration tests] D --> E[Security scan] E --> F[Deploy to staging] F --> G{Approve release?} G -->|yes| H[Deploy to prod] G -->|no| I[Reject] ``` ![CI/CD pipeline — linear stage view](/assets/images/ci-cd-pipeline-linear-stage-view-cdbd595aae1c1890b45f78cbae079474.svg) Read left to right as one deploy cycle. The single decision at the end (`Approve release?`) is the human gate between staging and production — the box where a person, not a runner, picks what ships. ## Copy-paste 2: gates, retries and rollbacks[​](#copy-paste-2-gates-retries-and-rollbacks "Direct link to Copy-paste 2: gates, retries and rollbacks") Real pipelines branch. Flaky tests retry, security scans kill the build, and a bad prod deploy rolls back to the last good tag. Draw those forks and the diagram becomes the troubleshooting map the on-call reads: ``` flowchart TD %% title: CI/CD with quality gates and rollback A[Push to main] --> B[Build image] B --> C[Unit + integration tests] C -->|pass| D[Security scan] C -->|fail| C2[Attempt one retry] C2 --> C C2 -->|retry exhausted| F3[Block merge] D -->|vulnerabilities| F3 D -->|clean| E[Deploy to staging] E --> F{Smoke tests ok?} F -->|yes| G[Deploy to prod] F -->|no| H[Roll back to last release tag] G --> I[Tag release] ``` ![CI/CD with quality gates and rollback](/assets/images/ci-cd-with-quality-gates-and-rollback-c2a6f42ad0b88e79b0372abf49dd3e38.svg) Two decisions carry the whole story: the retry loop between tests and the scan (`C --> C2 --> C`), and the smoke-test fork after staging. The `Block merge` node is where a compliant pipeline *stops* — putting it in the diagram tells the reader the failure behavior as clearly as the success path. ## Copy-paste 3: deploy-to-tag as a gitGraph[​](#copy-paste-3-deploy-to-tag-as-a-gitgraph "Direct link to Copy-paste 3: deploy-to-tag as a gitGraph") The flowchart shows the pipeline *logic*. The gitGraph below shows the *history* — which commit became a release tag, and which hotfix rode straight to prod. Keep both: the flowchart in the docs page, the gitGraph beside the release notes. ``` gitGraph title Deploy-to-tag: v1.3 hotfix ridealong commit id: "v1.2" branch release/1.3 checkout release/1.3 branch hotfix/payment checkout hotfix/payment commit id: "fix: timeout" checkout release/1.3 merge hotfix/payment checkout main commit id: "feat: dashboard" checkout release/1.3 commit id: "release: v1.3" checkout main merge release/1.3 ``` ![Deploy-to-tag: v1.3 hotfix ridealong](/assets/images/deploy-to-tag-v1-3-hotfix-ridealong-01ff4af7309bc4488c78d81559882299.svg) This is the diagram to attach to a release page. When the postmortem asks "did the hotfix ride along cleanly?", one glance at the gitGraph answers it — the release line, the hotfix merge, the tag. ## Live vs. diagram: the tie to your actual pipeline[​](#live-vs-diagram-the-tie-to-your-actual-pipeline "Direct link to Live vs. diagram: the tie to your actual pipeline") Mermaid's value here is not "prettier docs" — it is that the diagram is *maintainable text*. In [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/) the macro is a code editor with a live preview: edit a stage name, add a gate, and the rendered SVG updates as you type. When your pipeline adds a stage (they always do), the wiki's diagram changes in the same edit that changes the pipeline — no screen-share screenshot to retake. Teams that keep a Mermaid pipeline diagram current report the same reflex as keeping a diagram next to a sprint board: someone spots the doc drift exactly one pipeline change after it happens, because the diagram is the shortest path from "we changed it" to "write it down". ## Where this lives beside your other DevOps diagrams[​](#where-this-lives-beside-your-other-devops-diagrams "Direct link to Where this lives beside your other DevOps diagrams") This is the pipeline half of the DevOps pair; the other half is the branch topology. Keep the **pipeline logic** as a flowchart on the space page (this post), the **branch/release history** as a gitGraph on the relevant issue or release page ([branches & releases in Jira](/blog/mermaid-gitgraph-jira-branch-history.md)), and the **release schedule** as a Gantt on the epic ([release timeline in Jira](/blog/how-to-create-release-timeline-jira.md)). Three diagram types, three questions, one Confluence space. ## FAQ[​](#faq "Direct link to FAQ") **Does Confluence have a built-in CI/CD diagram tool?** No — Confluence has no native diagramming. Mermaid Plus Diagrams & AI Agent for Confluence renders `flowchart` and `gitGraph` from editable code blocks with a live preview. **How do I show a quality gate in a Mermaid pipeline diagram?** Use a decision diamond on the arrows between stages — 'Security scan? → clean: deploy / vulnerabilities: block'. The reader sees the gate exactly where the pipeline gates. **Can a Mermaid pipeline diagram show retries and rollbacks?** Yes. Draw a retry as a node pointing back at the stage it retries, and a rollback as a path from the deploy stage back to the previous release tag. See example 2. **Should a pipeline diagram be a flowchart or a gitGraph?** Flowchart for pipeline logic (stages, gates, branches); gitGraph for release history (which commit became which tag). Most teams keep one of each. Render every Mermaid diagram type — flowcharts, gitGraph, Gantt, ER and 25 more — in [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), free for up to 10 users. Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [ci-cd](/blog/tags/ci-cd.md) * [devops](/blog/tags/devops.md) * [flowchart](/blog/tags/flowchart.md) * [gitgraph](/blog/tags/gitgraph.md) * [how-to](/blog/tags/how-to.md) --- # Document Your Codebase in Confluence with Mermaid Class Diagrams September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) Your team grows by two people. The new hires open the wiki and find the architecture doc: a screenshot of a whiteboard, dated 14 months ago, where `PaymentService` does everything except the thing the diagram says `OrderService` does. Day-1 onboarding just taught two people the wrong architecture. **Quick answer:** keep the architecture in Confluence as a Mermaid `class diagram`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/) and diffs like code. Classes, methods, interfaces, ownership — in editable text that updates when the code does. This post gives you three copy-paste examples: the onboarding service map, interface+implementation modules, and a request-flow sketch. ## Why the class diagram, not the screenshot[​](#why-the-class-diagram-not-the-screenshot "Direct link to Why the class diagram, not the screenshot") A screenshot is a moment; a Mermaid class diagram is a *living boundary map*. The readers you care about ask three questions that a screenshot answers badly: * **What do I call?** The public classes at each module's edge * **What implements it?** Where the interface points are, and who swaps in * **What breaks?** What an internal change leaks out of the module A class diagram answers these in visible text — and because it is Mermaid, the answer stays honest: move a class, and the diagram moves in the same edit. New hires learn the *current* shape by default, not the whiteboard from last year. ## Copy-paste 1: the onboarding service map[​](#copy-paste-1-the-onboarding-service-map "Direct link to Copy-paste 1: the onboarding service map") Start with the map a new hire wants: the services, their public side, and which service owns which data. Six classes, one owner per class, arrows only where code actually calls: ``` classDiagram %% title: Service ownership map — order flow class OrderService { +placeOrder(dto) Order +cancelOrder(id) void -orderRepo OrderRepository } class PaymentService { +charge(order) Receipt -paymentRepo } class InventoryService { +reserve(items) bool -stockRepo } class NotificationService { +send(event) void } OrderService --> PaymentService : charges OrderService --> InventoryService : reserves PaymentService --> NotificationService : emits ReceiptConfirmed ``` ![Service ownership map — order flow](/assets/images/service-ownership-map-order-flow-7592f0cabccdeafeef48da8eec4ea939.svg) Three relations carry the architecture: order charges payment, order reserves inventory, and payment *emits* an event (the dotted arrow tells a new hire "this is async"). Fields starting with `-` show the repo each service owns. That is the whole onboarding tour. ## Copy-paste 2: interfaces and implementations[​](#copy-paste-2-interfaces-and-implementations "Direct link to Copy-paste 2: interfaces and implementations") The moment a codebase gets a swappable piece — a payment provider, a storage backend, a notifier — the diagram must show *which* implementation is live. That is what inheritance arrows are for: ``` classDiagram %% title: Payment provider — interface and live implementation class PaymentProvider { <> +charge(amount) Receipt +refund(receipt) void } class StripeAdapter { +charge(amount) Receipt +refund(receipt) void } class BraintreeAdapter { +charge(amount) Receipt } class LegacyPayments { +charge(amount) Receipt +refund(receipt) void } PaymentProvider <|-- StripeAdapter : active PaymentProvider <|-- BraintreeAdapter : pilot PaymentProvider <|-- LegacyPayments : deprecated ``` ![Payment provider — interface and live implementation](/assets/images/payment-provider-interface-and-live-implementation-eb6063a4259afa83c50d0451b87605a0.svg) The `<>` stereotype plus three `<|--` arrows tell the whole deployment story: one interface, three adapters, exactly one marked `active`. When Braintree graduates from pilot, the diagram's edit is one label — and that edit lands in the same PR as the config change. ## Copy-paste 3: the request flow as a thin class diagram[​](#copy-paste-3-the-request-flow-as-a-thin-class-diagram "Direct link to Copy-paste 3: the request flow as a thin class diagram") Not every architecture question is "what owns what" — sometimes it is "what happens to this request". A class diagram handles that too, with the same classes the code uses but arrows as the call path: ``` classDiagram %% title: Public API request flow class ApiGateway { +handle(req) Response } class RequestValidator { +validate(req) errors } class AuthFilter { +authorize(token) identity } class OrdersController { +post(req) Order } class Orders ApiGateway --> RequestValidator : validate ApiGateway --> AuthFilter : authorize ApiGateway --> OrdersController : route OrdersController --> Orders : read/write ``` ![Public API request flow](/assets/images/public-api-request-flow-c672e4174a680666f65b0ab1027ef39c.svg) This reads like the stack trace developers paste in Slack, but as a *structure*. Pair it with example 1 in the same page — one diagram for who owns what, one for how a request walks through it. Together they cover onboarding and on-call. ## The diagram that keeps up with the code[​](#the-diagram-that-keeps-up-with-the-code "Direct link to The diagram that keeps up with the code") Mermaid class diagrams stay accurate exactly when you treat them as **reviewed text**, not as a one-time drawing. In [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), the macro shows the source below the rendered SVG, so the diagram can be reviewed in the same MR as the code that moves the boundary. A class that changes ownership changes the diagram in the same review that changed the code — the doc drift that rotted your old architecture diagram never gets a chance to start. That reviewed-text property is the whole point. A class diagram in a wiki that nobody can edit is a wall mural; a class diagram that *is* text is a living map. Keep the boundaries visible, the implementations marked, and the review in the same diff as the code, and the architecture the new hire learns on day one will still be true on day two hundred. ## Where this lives beside your other Confluence diagrams[​](#where-this-lives-beside-your-other-confluence-diagrams "Direct link to Where this lives beside your other Confluence diagrams") A class diagram documents the *shape* of the code; other Mermaid types cover the other halves of the story. Keep the class diagram on the architecture page (this post), the ownership and module boundaries), the pipeline that ships it as a flowchart ([CI/CD pipeline diagrams](/blog/mermaid-ci-cd-pipeline-diagram-confluence.md)), and the release history as a gitGraph next to the releases ([branches & releases in Jira](/blog/mermaid-gitgraph-jira-branch-history.md)). Three diagram types, three questions, one space that stays current. ## FAQ[​](#faq "Direct link to FAQ") **Can Mermaid render a real UML class diagram in Confluence?** Mermaid class diagrams support classes, attributes, methods, inheritance and composition with cardinality comments — close to UML class diagram syntax minus formal stereotypes. Enough to document structure without a UML toolchain. **How do I show interfaces and implementations?** Use an abstract 'interface' stereotype and inheritance arrows `<|--` — implementations point at the interface they implement. Example 2 shows three adapters under one PaymentProvider. **How do I avoid a huge unreadable class diagram?** Diagram boundaries, not internals: show the classes at each module's edge and keep internals to a doc comment or a second focused diagram. Readers prefer 8–15 classes per diagram even though Mermaid renders any size. **How do I keep the diagram matching the code?** Show the Mermaid source under the SVG (Mermaid Plus has that toggle) and review the diagram in the same pull request as the code that changes it — the class diagram then diffs like code. Render every Mermaid diagram type — class, flowchart, ER, gitGraph, Gantt and 24 more — in [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), free for up to 10 users. Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [class-diagram](/blog/tags/class-diagram.md) * [architecture](/blog/tags/architecture.md) * [docs](/blog/tags/docs.md) * [how-to](/blog/tags/how-to.md) --- # Decision Framework Diagrams in Confluence with Mermaid (Copy-Paste) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The meeting asks "who owns this feature?" and the answer is a Venn diagram by hand — drawn on a whiteboard, erased, redrawn, photographed, and lost. Two teams each built a piece of a shared workflow, and "the overlap" is exactly where the bugs and the SQL both landed. A decision framework is only useful while its picture survives the meeting; in Confluence as Mermaid text, it survives. **Quick answer:** put decision frameworks in Confluence as Mermaid — `venn-beta` for set overlap, `cynefin-beta` for which operating mode a situation needs, `quadrantChart` for which item goes first — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Each framework encodes a decision *shape*, and text keeps the picture attached to the decision record. This post gives you three copy-paste examples. ## Why decision pictures survive differently[​](#why-decision-pictures-survive-differently "Direct link to Why decision pictures survive differently") A whiteboard decision picture dies at cleanup; a spreadsheet of the same decision survives but says nothing visual. Mermaid text sits in the middle — the *shape* is preserved and the source is versionable: * **The overlap is first-class.** In a Venn diagram the intersection is the interesting part, and a union line names it explicitly. * **The framework travels with the record.** The Cynefin map sits next to the ADR it classified, so the reasoning is auditable. * **It draws from words.** Sets, unions, domains, coordinates — all plain text a review can read without opening a canvas app. Use a face-to-face whiteboard to *find* the shape, then move it to the wiki as text before the marker dries. ## Copy-paste 1: ownership overlap — Venn[​](#copy-paste-1-ownership-overlap--venn "Direct link to Copy-paste 1: ownership overlap — Venn") Who owns "the checkout shared by web + mobile + third-party SDK"? Three sets, and the labeled unions answer the overlap question: ``` venn-beta title Checkout ownership set Web set Mobile set SDKs union Web,Mobile["Shared checkout"] union Web,SDKs["Trusted client"] union Mobile,SDKs["Native payment"] ``` ![Checkout ownership](data:image/svg+xml;base64,PHN2ZyBpZD0ibXktc3ZnIiB3aWR0aD0iMTAwJSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgdmlld0JveD0iMCAwIDgwMCA0NTAiIHN0eWxlPSJtYXgtd2lkdGg6IDgwMHB4OyBiYWNrZ3JvdW5kLWNvbG9yOiB3aGl0ZTsiIHJvbGU9ImdyYXBoaWNzLWRvY3VtZW50IGRvY3VtZW50IiBhcmlhLXJvbGVkZXNjcmlwdGlvbj0idmVubiI+PHN0eWxlPiNteS1zdmd7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO2ZvbnQtc2l6ZToxNnB4O2ZpbGw6IzMzMzt9QGtleWZyYW1lcyBlZGdlLWFuaW1hdGlvbi1mcmFtZXtmcm9te3N0cm9rZS1kYXNob2Zmc2V0OjA7fX1Aa2V5ZnJhbWVzIGRhc2h7dG97c3Ryb2tlLWRhc2hvZmZzZXQ6MDt9fSNteS1zdmcgLmVkZ2UtYW5pbWF0aW9uLXNsb3d7c3Ryb2tlLWRhc2hhcnJheTo5LDUhaW1wb3J0YW50O3N0cm9rZS1kYXNob2Zmc2V0OjkwMDthbmltYXRpb246ZGFzaCA1MHMgbGluZWFyIGluZmluaXRlO3N0cm9rZS1saW5lY2FwOnJvdW5kO30jbXktc3ZnIC5lZGdlLWFuaW1hdGlvbi1mYXN0e3N0cm9rZS1kYXNoYXJyYXk6OSw1IWltcG9ydGFudDtzdHJva2UtZGFzaG9mZnNldDo5MDA7YW5pbWF0aW9uOmRhc2ggMjBzIGxpbmVhciBpbmZpbml0ZTtzdHJva2UtbGluZWNhcDpyb3VuZDt9I215LXN2ZyAuZXJyb3ItaWNvbntmaWxsOiM1NTIyMjI7fSNteS1zdmcgLmVycm9yLXRleHR7ZmlsbDojNTUyMjIyO3N0cm9rZTojNTUyMjIyO30jbXktc3ZnIC5lZGdlLXRoaWNrbmVzcy1ub3JtYWx7c3Ryb2tlLXdpZHRoOjFweDt9I215LXN2ZyAuZWRnZS10aGlja25lc3MtdGhpY2t7c3Ryb2tlLXdpZHRoOjMuNXB4O30jbXktc3ZnIC5lZGdlLXBhdHRlcm4tc29saWR7c3Ryb2tlLWRhc2hhcnJheTowO30jbXktc3ZnIC5lZGdlLXRoaWNrbmVzcy1pbnZpc2libGV7c3Ryb2tlLXdpZHRoOjA7ZmlsbDpub25lO30jbXktc3ZnIC5lZGdlLXBhdHRlcm4tZGFzaGVke3N0cm9rZS1kYXNoYXJyYXk6Mzt9I215LXN2ZyAuZWRnZS1wYXR0ZXJuLWRvdHRlZHtzdHJva2UtZGFzaGFycmF5OjI7fSNteS1zdmcgLm1hcmtlcntmaWxsOiMzMzMzMzM7c3Ryb2tlOiMzMzMzMzM7fSNteS1zdmcgLm1hcmtlci5jcm9zc3tzdHJva2U6IzMzMzMzMzt9I215LXN2ZyBzdmd7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO2ZvbnQtc2l6ZToxNnB4O30jbXktc3ZnIHB7bWFyZ2luOjA7fSNteS1zdmcgLnZlbm4tdGl0bGV7Zm9udC1zaXplOjMycHg7ZmlsbDojMzMzO2ZvbnQtZmFtaWx5OiJ0cmVidWNoZXQgbXMiLHZlcmRhbmEsYXJpYWwsc2Fucy1zZXJpZjt9I215LXN2ZyAudmVubi1jaXJjbGUgdGV4dHtmb250LXNpemU6NDhweDtmb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7fSNteS1zdmcgLnZlbm4taW50ZXJzZWN0aW9uIHRleHR7Zm9udC1zaXplOjQ4cHg7ZmlsbDojMzMzO2ZvbnQtZmFtaWx5OiJ0cmVidWNoZXQgbXMiLHZlcmRhbmEsYXJpYWwsc2Fucy1zZXJpZjt9I215LXN2ZyAudmVubi10ZXh0LW5vZGV7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO2NvbG9yOiMzMzM7fSNteS1zdmcgLm5vZGUgLm5lby1ub2Rle3N0cm9rZTojOTM3MERCO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcmVjdCwjbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLmNsdXN0ZXIgcmVjdCwjbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcG9seWdvbntzdHJva2U6IzkzNzBEQjtmaWx0ZXI6ZHJvcC1zaGFkb3coMXB4IDJweCAycHggcmdiYSgxODUsIDE4NSwgMTg1LCAxKSk7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uc3dpbWxhbmUuY2x1c3RlciByZWN0e2ZpbHRlcjpub25lO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcGF0aHtzdHJva2U6IzkzNzBEQjtzdHJva2Utd2lkdGg6MXB4O30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgLm91dGVyLXBhdGh7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgLm5lby1saW5lIHBhdGh7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOm5vbmU7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSBjaXJjbGV7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgY2lyY2xlIC5zdGF0ZS1zdGFydHtmaWxsOiMwMDAwMDA7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uaWNvbi1zaGFwZSAuaWNvbntmaWxsOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLmljb24tc2hhcGUgLmljb24tbmVvIHBhdGh7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIDpyb290ey0tbWVybWFpZC1mb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7fTwvc3R5bGU+PGcvPjx0ZXh0IGNsYXNzPSJ2ZW5uLXRpdGxlIiBmb250LXNpemU9IjE2cHgiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiIHg9IjUwJSIgeT0iMTYiIHN0eWxlPSJmaWxsOiByZ2IoNTEsIDUxLCA1MSk7Ij5DaGVja291dCBvd25lcnNoaXA8L3RleHQ+PGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMCwgMjQpIj48ZyBjbGFzcz0idmVubi1hcmVhIHZlbm4tY2lyY2xlIHZlbm4tc2V0LTAiIGRhdGEtdmVubi1zZXRzPSJXZWIiPjxwYXRoIGQ9Ik0gMzE4LjkwNDM1Njk5NzQ4NTYgMjgzLjIzMDg4Njk3NjQxMTIgJiMxMDttIC0xMjcuNzY5MTEzMDIzNTg4NzcgMCAmIzEwO2EgMTI3Ljc2OTExMzAyMzU4ODc3IDEyNy43NjkxMTMwMjM1ODg3NyAwIDEgMCAyNTUuNTM4MjI2MDQ3MTc3NTUgMCAmIzEwO2EgMTI3Ljc2OTExMzAyMzU4ODc3IDEyNy43NjkxMTMwMjM1ODg3NyAwIDEgMCAtMjU1LjUzODIyNjA0NzE3NzU1IDAiIHN0eWxlPSJmaWxsLW9wYWNpdHk6IDAuMTsgZmlsbDogcmdiKDgzLCA4MywgMjU1KTsgc3Ryb2tlOiByZ2IoODMsIDgzLCAyNTUpOyBzdHJva2Utd2lkdGg6IDIuNTsgc3Ryb2tlLW9wYWNpdHk6IDAuOTU7Ii8+PHRleHQgY2xhc3M9ImxhYmVsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBkeT0iLjM1ZW0iIHg9IjI3NiIgeT0iMzA3IiBzdHlsZT0iZmlsbDogcmdiKDAsIDAsIDE4NSk7IGZvbnQtc2l6ZTogMjRweDsiPjx0c3BhbiB4PSIyNzYiIHk9IjMwNyIgZHk9IjAuMzVlbSI+V2ViPC90c3Bhbj48L3RleHQ+PC9nPjxnIGNsYXNzPSJ2ZW5uLWFyZWEgdmVubi1jaXJjbGUgdmVubi1zZXQtMSIgZGF0YS12ZW5uLXNldHM9Ik1vYmlsZSI+PHBhdGggZD0iTSA0ODEuMDk1NjQzMDAyNTE0NCAyODMuMjMwODg2OTc2NDExMiAmIzEwO20gLTEyNy43NjkxMTMwMjM1ODg3NyAwICYjMTA7YSAxMjcuNzY5MTEzMDIzNTg4NzcgMTI3Ljc2OTExMzAyMzU4ODc3IDAgMSAwIDI1NS41MzgyMjYwNDcxNzc1NSAwICYjMTA7YSAxMjcuNzY5MTEzMDIzNTg4NzcgMTI3Ljc2OTExMzAyMzU4ODc3IDAgMSAwIC0yNTUuNTM4MjI2MDQ3MTc3NTUgMCIgc3R5bGU9ImZpbGwtb3BhY2l0eTogMC4xOyBmaWxsOiByZ2IoMjU1LCAyNTUsIDY5KTsgc3Ryb2tlOiByZ2IoMjU1LCAyNTUsIDY5KTsgc3Ryb2tlLXdpZHRoOiAyLjU7IHN0cm9rZS1vcGFjaXR5OiAwLjk1OyIvPjx0ZXh0IGNsYXNzPSJsYWJlbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZHk9Ii4zNWVtIiB4PSI1MjMiIHk9IjMwNyIgc3R5bGU9ImZpbGw6IHJnYigxNzEsIDE3MSwgMCk7IGZvbnQtc2l6ZTogMjRweDsiPjx0c3BhbiB4PSI1MjMiIHk9IjMwNyIgZHk9IjAuMzVlbSI+TW9iaWxlPC90c3Bhbj48L3RleHQ+PC9nPjxnIGNsYXNzPSJ2ZW5uLWFyZWEgdmVubi1jaXJjbGUgdmVubi1zZXQtMiIgZGF0YS12ZW5uLXNldHM9IlNES3MiPjxwYXRoIGQ9Ik0gNDAwIDE0Mi43NjkxMTMwMjM1ODg3NyAmIzEwO20gLTEyNy43NjkxMTMwMjM1ODg3NyAwICYjMTA7YSAxMjcuNzY5MTEzMDIzNTg4NzcgMTI3Ljc2OTExMzAyMzU4ODc3IDAgMSAwIDI1NS41MzgyMjYwNDcxNzc1NSAwICYjMTA7YSAxMjcuNzY5MTEzMDIzNTg4NzcgMTI3Ljc2OTExMzAyMzU4ODc3IDAgMSAwIC0yNTUuNTM4MjI2MDQ3MTc3NTUgMCIgc3R5bGU9ImZpbGwtb3BhY2l0eTogMC4xOyBmaWxsOiByZ2IoMTgxLCAyNTUsIDMyKTsgc3Ryb2tlOiByZ2IoMTgxLCAyNTUsIDMyKTsgc3Ryb2tlLXdpZHRoOiAyLjU7IHN0cm9rZS1vcGFjaXR5OiAwLjk1OyIvPjx0ZXh0IGNsYXNzPSJsYWJlbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZHk9Ii4zNWVtIiB4PSI0MDAiIHk9IjkzIiBzdHlsZT0iZmlsbDogcmdiKDg5LCAxMzQsIDApOyBmb250LXNpemU6IDI0cHg7Ij48dHNwYW4geD0iNDAwIiB5PSI5MyIgZHk9IjAuMzVlbSI+U0RLczwvdHNwYW4+PC90ZXh0PjwvZz48ZyBjbGFzcz0idmVubi1hcmVhIHZlbm4taW50ZXJzZWN0aW9uIiBkYXRhLXZlbm4tc2V0cz0iTW9iaWxlX1dlYiI+PHBhdGggZD0iTSA0MDAgMzgxLjk2NTA5MDQxNTk2NTczICYjMTA7QSAxMjcuNzY5MTEzMDIzNTg4NzcgMTI3Ljc2OTExMzAyMzU4ODc3IDAgMCAxIDQwMCAxODQuNDk2NjgzNTM2ODU2NzIgJiMxMDtBIDEyNy43NjkxMTMwMjM1ODg3NyAxMjcuNzY5MTEzMDIzNTg4NzcgMCAwIDEgNDAwIDM4MS45NjUwOTA0MTU5NjU3MyIgc3R5bGU9ImZpbGwtb3BhY2l0eTogMDsgZmlsbDogdHJhbnNwYXJlbnQ7Ii8+PHRleHQgY2xhc3M9ImxhYmVsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBkeT0iLjM1ZW0iIHg9IjM5OSIgeT0iMzEyIiBzdHlsZT0iZmlsbDogcmdiKDUxLCA1MSwgNTEpOyBmb250LXNpemU6IDI0cHg7Ij48dHNwYW4geD0iMzk5IiB5PSIzMTIiIGR5PSIwLjM1ZW0iPlNoYXJlZCBjaGVja291dDwvdHNwYW4+PC90ZXh0PjwvZz48ZyBjbGFzcz0idmVubi1hcmVhIHZlbm4taW50ZXJzZWN0aW9uIiBkYXRhLXZlbm4tc2V0cz0iU0RLc19XZWIiPjxwYXRoIGQ9Ik0gMjczLjk0NTg1MDA5NzY2NzcgMTYzLjYzMjg5ODI4MDIyMjc1ICYjMTA7QSAxMjcuNzY5MTEzMDIzNTg4NzcgMTI3Ljc2OTExMzAyMzU4ODc3IDAgMCAxIDQ0NC45NTg1MDY4OTk4MTc5IDI2Mi4zNjcxMDE3MTk3NzczICYjMTA7QSAxMjcuNzY5MTEzMDIzNTg4NzcgMTI3Ljc2OTExMzAyMzU4ODc3IDAgMCAxIDI3My45NDU4NTAwOTc2Njc3IDE2My42MzI4OTgyODAyMjI3NSIgc3R5bGU9ImZpbGwtb3BhY2l0eTogMDsgZmlsbDogdHJhbnNwYXJlbnQ7Ii8+PHRleHQgY2xhc3M9ImxhYmVsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBkeT0iLjM1ZW0iIHg9IjMzNCIgeT0iMTk4IiBzdHlsZT0iZmlsbDogcmdiKDUxLCA1MSwgNTEpOyBmb250LXNpemU6IDI0cHg7Ij48dHNwYW4geD0iMzM0IiB5PSIxOTgiIGR5PSIwLjM1ZW0iPlRydXN0ZWQgY2xpZW50PC90c3Bhbj48L3RleHQ+PC9nPjxnIGNsYXNzPSJ2ZW5uLWFyZWEgdmVubi1pbnRlcnNlY3Rpb24iIGRhdGEtdmVubi1zZXRzPSJNb2JpbGVfU0RLcyI+PHBhdGggZD0iTSAzNTUuMDQxNDkzMTAwMTgyMSAyNjIuMzY3MTAxNzE5Nzc3MyAmIzEwO0EgMTI3Ljc2OTExMzAyMzU4ODc3IDEyNy43NjkxMTMwMjM1ODg3NyAwIDAgMSA1MjYuMDU0MTQ5OTAyMzMyNCAxNjMuNjMyODk4MjgwMjIyNzUgJiMxMDtBIDEyNy43NjkxMTMwMjM1ODg3NyAxMjcuNzY5MTEzMDIzNTg4NzcgMCAwIDEgMzU1LjA0MTQ5MzEwMDE4MjEgMjYyLjM2NzEwMTcxOTc3NzMiIHN0eWxlPSJmaWxsLW9wYWNpdHk6IDA7IGZpbGw6IHRyYW5zcGFyZW50OyIvPjx0ZXh0IGNsYXNzPSJsYWJlbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZHk9Ii4zNWVtIiB4PSI0NjUiIHk9IjE5OCIgc3R5bGU9ImZpbGw6IHJnYig1MSwgNTEsIDUxKTsgZm9udC1zaXplOiAyNHB4OyI+PHRzcGFuIHg9IjQ2NSIgeT0iMTk4IiBkeT0iMC4zNWVtIj5OYXRpdmUgcGF5bWVudDwvdHNwYW4+PC90ZXh0PjwvZz48L2c+PC9zdmc+) Each union line names a *real* ownership pocket: "Shared checkout" (Web ∩ Mobile), "Trusted client" (Web ∩ SDKs), "Native payment" (Mobile ∩ SDKs). The decision record now says which team answers which intersection — the fugue state where bugs went unresolved is gone because the overlap has an owner and a name. ## Copy-paste 2: what mode does this problem need — Cynefin[​](#copy-paste-2-what-mode-does-this-problem-need--cynefin "Direct link to Copy-paste 2: what mode does this problem need — Cynefin") Cynefin classifies situations into five domains by how knowable they are, and each domain prescribes an operating mode: ``` cynefin-beta title Which mode does this problem need? complex "Run safe-to-fail experiments" complicated "Analyze with experts" clear "Apply best practice" chaotic "Stabilize first" confusion "Break the problem down" clear --> chaotic : "Complacency" chaotic --> complex : "Stabilized" ``` ![Which mode does this problem need?](data:image/svg+xml;base64,PHN2ZyBpZD0ibXktc3ZnIiB3aWR0aD0iMTAwJSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgc3R5bGU9Im1heC13aWR0aDogODgwcHg7IGJhY2tncm91bmQtY29sb3I6IHdoaXRlOyIgdmlld0JveD0iMCAwIDg4MCA2ODAiIHJvbGU9ImdyYXBoaWNzLWRvY3VtZW50IGRvY3VtZW50IiBhcmlhLXJvbGVkZXNjcmlwdGlvbj0iY3luZWZpbiI+PHN0eWxlPiNteS1zdmd7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO2ZvbnQtc2l6ZToxNnB4O2ZpbGw6IzMzMzt9QGtleWZyYW1lcyBlZGdlLWFuaW1hdGlvbi1mcmFtZXtmcm9te3N0cm9rZS1kYXNob2Zmc2V0OjA7fX1Aa2V5ZnJhbWVzIGRhc2h7dG97c3Ryb2tlLWRhc2hvZmZzZXQ6MDt9fSNteS1zdmcgLmVkZ2UtYW5pbWF0aW9uLXNsb3d7c3Ryb2tlLWRhc2hhcnJheTo5LDUhaW1wb3J0YW50O3N0cm9rZS1kYXNob2Zmc2V0OjkwMDthbmltYXRpb246ZGFzaCA1MHMgbGluZWFyIGluZmluaXRlO3N0cm9rZS1saW5lY2FwOnJvdW5kO30jbXktc3ZnIC5lZGdlLWFuaW1hdGlvbi1mYXN0e3N0cm9rZS1kYXNoYXJyYXk6OSw1IWltcG9ydGFudDtzdHJva2UtZGFzaG9mZnNldDo5MDA7YW5pbWF0aW9uOmRhc2ggMjBzIGxpbmVhciBpbmZpbml0ZTtzdHJva2UtbGluZWNhcDpyb3VuZDt9I215LXN2ZyAuZXJyb3ItaWNvbntmaWxsOiM1NTIyMjI7fSNteS1zdmcgLmVycm9yLXRleHR7ZmlsbDojNTUyMjIyO3N0cm9rZTojNTUyMjIyO30jbXktc3ZnIC5lZGdlLXRoaWNrbmVzcy1ub3JtYWx7c3Ryb2tlLXdpZHRoOjFweDt9I215LXN2ZyAuZWRnZS10aGlja25lc3MtdGhpY2t7c3Ryb2tlLXdpZHRoOjMuNXB4O30jbXktc3ZnIC5lZGdlLXBhdHRlcm4tc29saWR7c3Ryb2tlLWRhc2hhcnJheTowO30jbXktc3ZnIC5lZGdlLXRoaWNrbmVzcy1pbnZpc2libGV7c3Ryb2tlLXdpZHRoOjA7ZmlsbDpub25lO30jbXktc3ZnIC5lZGdlLXBhdHRlcm4tZGFzaGVke3N0cm9rZS1kYXNoYXJyYXk6Mzt9I215LXN2ZyAuZWRnZS1wYXR0ZXJuLWRvdHRlZHtzdHJva2UtZGFzaGFycmF5OjI7fSNteS1zdmcgLm1hcmtlcntmaWxsOiMzMzMzMzM7c3Ryb2tlOiMzMzMzMzM7fSNteS1zdmcgLm1hcmtlci5jcm9zc3tzdHJva2U6IzMzMzMzMzt9I215LXN2ZyBzdmd7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO2ZvbnQtc2l6ZToxNnB4O30jbXktc3ZnIHB7bWFyZ2luOjA7fSNteS1zdmcgLmN5bmVmaW5Eb21haW57c3Ryb2tlOm5vbmU7fSNteS1zdmcgLmN5bmVmaW5Eb21haW5MYWJlbHtmb250LXNpemU6MTZweDtmb250LXdlaWdodDpib2xkO2ZpbGw6IzEzMTMwMDt9I215LXN2ZyAuY3luZWZpblN1YnRpdGxle2ZvbnQtc2l6ZToxMXB4O2ZpbGw6IzMzMztmb250LXN0eWxlOml0YWxpYzt9I215LXN2ZyAuY3luZWZpbkl0ZW17ZmlsbC1vcGFjaXR5OjAuOTU7c3Ryb2tlOiMzMzMzMzM7c3Ryb2tlLXdpZHRoOjE7fSNteS1zdmcgLmN5bmVmaW5JdGVtVGV4dHtmb250LXNpemU6MTJweDtmaWxsOiMzMzM7fSNteS1zdmcgLmN5bmVmaW5JdGVtT3ZlcmZsb3d7ZmlsbC1vcGFjaXR5OjAuNjtzdHJva2U6IzMzMzMzMztzdHJva2Utd2lkdGg6MTtzdHJva2UtZGFzaGFycmF5OjMgMjt9I215LXN2ZyAuY3luZWZpbkJvdW5kYXJ5e3N0cm9rZTojMzMzMzMzO3N0cm9rZS13aWR0aDoyO3N0cm9rZS1kYXNoYXJyYXk6NiAzO30jbXktc3ZnIC5jeW5lZmluQ2xpZmZ7c3Ryb2tlOiM4QjAwMDA7c3Ryb2tlLXdpZHRoOjQ7fSNteS1zdmcgLmN5bmVmaW5Db25mdXNpb257c3Ryb2tlOiMzMzMzMzM7c3Ryb2tlLXdpZHRoOjEuNTtzdHJva2UtZGFzaGFycmF5OjQgMjt9I215LXN2ZyAuY3luZWZpbkFycm93TGluZXtzdHJva2U6IzMzMzMzMztzdHJva2Utd2lkdGg6MjtmaWxsOm5vbmU7fSNteS1zdmcgLmN5bmVmaW5BcnJvd0hlYWR7ZmlsbDojMzMzMzMzO3N0cm9rZTpub25lO30jbXktc3ZnIC5jeW5lZmluQXJyb3dMYWJlbHtmb250LXNpemU6MTFweDtmaWxsOiMzMzM7fSNteS1zdmcgLmN5bmVmaW5UaXRsZXtmb250LXNpemU6MThweDtmb250LXdlaWdodDpib2xkO2ZpbGw6IzEzMTMwMDt9I215LXN2ZyAubm9kZSAubmVvLW5vZGV7c3Ryb2tlOiM5MzcwREI7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSByZWN0LCNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uY2x1c3RlciByZWN0LCNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSBwb2x5Z29ue3N0cm9rZTojOTM3MERCO2ZpbHRlcjpkcm9wLXNoYWRvdygxcHggMnB4IDJweCByZ2JhKDE4NSwgMTg1LCAxODUsIDEpKTt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5zd2ltbGFuZS5jbHVzdGVyIHJlY3R7ZmlsdGVyOm5vbmU7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSBwYXRoe3N0cm9rZTojOTM3MERCO3N0cm9rZS13aWR0aDoxcHg7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSAub3V0ZXItcGF0aHtmaWx0ZXI6ZHJvcC1zaGFkb3coMXB4IDJweCAycHggcmdiYSgxODUsIDE4NSwgMTg1LCAxKSk7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSAubmVvLWxpbmUgcGF0aHtzdHJva2U6IzkzNzBEQjtmaWx0ZXI6bm9uZTt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIGNpcmNsZXtzdHJva2U6IzkzNzBEQjtmaWx0ZXI6ZHJvcC1zaGFkb3coMXB4IDJweCAycHggcmdiYSgxODUsIDE4NSwgMTg1LCAxKSk7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSBjaXJjbGUgLnN0YXRlLXN0YXJ0e2ZpbGw6IzAwMDAwMDt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5pY29uLXNoYXBlIC5pY29ue2ZpbGw6IzkzNzBEQjtmaWx0ZXI6ZHJvcC1zaGFkb3coMXB4IDJweCAycHggcmdiYSgxODUsIDE4NSwgMTg1LCAxKSk7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uaWNvbi1zaGFwZSAuaWNvbi1uZW8gcGF0aHtzdHJva2U6IzkzNzBEQjtmaWx0ZXI6ZHJvcC1zaGFkb3coMXB4IDJweCAycHggcmdiYSgxODUsIDE4NSwgMTg1LCAxKSk7fSNteS1zdmcgOnJvb3R7LS1tZXJtYWlkLWZvbnQtZmFtaWx5OiJ0cmVidWNoZXQgbXMiLHZlcmRhbmEsYXJpYWwsc2Fucy1zZXJpZjt9PC9zdHlsZT48Zy8+PGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNDAsIDQwKSI+PGcgY2xhc3M9ImN5bmVmaW4tYmFja2dyb3VuZHMiPjxyZWN0IGNsYXNzPSJjeW5lZmluRG9tYWluIiB4PSIwIiB5PSIwIiB3aWR0aD0iNDAwIiBoZWlnaHQ9IjMwMCIgZmlsbD0iI0U4RjVFOSIgZmlsbC1vcGFjaXR5PSIwLjQiIHN0cm9rZT0ibm9uZSIvPjxyZWN0IGNsYXNzPSJjeW5lZmluRG9tYWluIiB4PSI0MDAiIHk9IjAiIHdpZHRoPSI0MDAiIGhlaWdodD0iMzAwIiBmaWxsPSIjRTNGMkZEIiBmaWxsLW9wYWNpdHk9IjAuNCIgc3Ryb2tlPSJub25lIi8+PHJlY3QgY2xhc3M9ImN5bmVmaW5Eb21haW4iIHg9IjAiIHk9IjMwMCIgd2lkdGg9IjQwMCIgaGVpZ2h0PSIzMDAiIGZpbGw9IiNGQkU5RTciIGZpbGwtb3BhY2l0eT0iMC40IiBzdHJva2U9Im5vbmUiLz48cmVjdCBjbGFzcz0iY3luZWZpbkRvbWFpbiIgeD0iNDAwIiB5PSIzMDAiIHdpZHRoPSI0MDAiIGhlaWdodD0iMzAwIiBmaWxsPSIjRkZGOEUxIiBmaWxsLW9wYWNpdHk9IjAuNCIgc3Ryb2tlPSJub25lIi8+PC9nPjxnIGNsYXNzPSJjeW5lZmluLWJvdW5kYXJpZXMiPjxwYXRoIGNsYXNzPSJjeW5lZmluQm91bmRhcnkiIGQ9Ik00MDQuODU3NDcwMzI2MTI1NiwwIEM0MTUuMzI2MjM3OTA0ODM5Miw0Mi44NTcxNDI4NTcxNDI4NTQgMzgzLjkxMDE4NzA4MTQzMzgzLDQyLjg1NzE0Mjg1NzE0Mjg1NCAzOTQuMzc4OTU0NjYwMTQ3NDMsODUuNzE0Mjg1NzE0Mjg1NzEgQzM5MS40NzY1NzM0NzAwNDg2LDEyOC41NzE0Mjg1NzE0Mjg1NiA0MDMuNzE4ODk4MTY2OTAyMzYsMTI4LjU3MTQyODU3MTQyODU2IDQwMC44MTY1MTY5NzY4MDM1NCwxNzEuNDI4NTcxNDI4NTcxNDIgQzQwOS43NTY2MDM4NjIxNTg5NSwyMTQuMjg1NzE0Mjg1NzE0MjggMzkzLjYyMzU0NDMxMzk0NDksMjE0LjI4NTcxNDI4NTcxNDI4IDQwMi41NjM2MzExOTkzMDAzLDI1Ny4xNDI4NTcxNDI4NTcxIEMzOTQuMjAyMTk2MzAwMDI5NzUsMzAwIDQwMi4yODA0MjA3NTc4MzAxNCwzMDAgMzkzLjkxODk4NTg1ODU1OTYsMzQyLjg1NzE0Mjg1NzE0MjgzIEM0MDUuMTk1MDc5NTc1MjkyNzcsMzg1LjcxNDI4NTcxNDI4NTY3IDM4OS44MzIzMTU1MzE1NTkzLDM4NS43MTQyODU3MTQyODU2NyA0MDEuMTA4NDA5MjQ4MjkyNDUsNDI4LjU3MTQyODU3MTQyODU2IEMzOTYuMTA0MTQ4NzUxMTI0NzQsNDcxLjQyODU3MTQyODU3MTQgNDAzLjk4NjY0NDgzOTg2Nzk1LDQ3MS40Mjg1NzE0Mjg1NzE0IDM5OC45ODIzODQzNDI3MDAyNCw1MTQuMjg1NzE0Mjg1NzE0MiBDNDEwLjEwNTQ1MDI0NTU1MTc2LDU1Ny4xNDI4NTcxNDI4NTcxIDM5NC40MDMxMTYzODczMTUxLDU1Ny4xNDI4NTcxNDI4NTcxIDQwNS41MjYxODIyOTAxNjY2LDYwMCIgZmlsbD0ibm9uZSIvPjxwYXRoIGNsYXNzPSJjeW5lZmluQm91bmRhcnkiIGQ9Ik0wLDMwMy4xNDg1Nzk4NjU2OTQwNSBDNTcuMTQyODU3MTQyODU3MTQ2LDMxNS4xMDAzNzI3MzgyMDQ5IDU3LjE0Mjg1NzE0Mjg1NzE0NiwyODAuMDQ5ODUxNTE1MzMwNCAxMTQuMjg1NzE0Mjg1NzE0MjksMjkyLjAwMTY0NDM4Nzg0MTIgQzE3MS40Mjg1NzE0Mjg1NzE0NCwyODQuNTUwNTM3MDQ2MDQ1MDYgMTcxLjQyODU3MTQyODU3MTQ0LDMxNS40NDkzMzU0MjIzNjY4NiAyMjguNTcxNDI4NTcxNDI4NTgsMzA3Ljk5ODIyODA4MDU3MDcgQzI4NS43MTQyODU3MTQyODU3LDMwOC4xOTkzOTIzNDg1Mjc5IDI4NS43MTQyODU3MTQyODU3LDI5Ni4xNTQyODM0NDE2MDMyIDM0Mi44NTcxNDI4NTcxNDI5LDI5Ni4zNTU0NDc3MDk1NjA0IEM0MDAsMjkxLjEwODkxMDk3NTA0NjQ2IDQwMCwzMTAuOTk2NTEzMzY5NDkzMiA0NTcuMTQyODU3MTQyODU3MTcsMzA1Ljc0OTk3NjYzNDk3OTI1IEM1MTQuMjg1NzE0Mjg1NzE0MywzMDkuNTYwMTE3MzQzNDQwNjUgNTE0LjI4NTcxNDI4NTcxNDMsMjg5LjcxMDMxNDc0MTM1ODE2IDU3MS40Mjg1NzE0Mjg1NzE0LDI5My41MjA0NTU0NDk4MTk1NiBDNjI4LjU3MTQyODU3MTQyODcsMjgyLjg4OTQ1MTQzNTc2NzEgNjI4LjU3MTQyODU3MTQyODcsMzE3LjA0MjEyNTA4MDcxMjE0IDY4NS43MTQyODU3MTQyODU4LDMwNi40MTExMjEwNjY2NTk3IEM3NDIuODU3MTQyODU3MTQyOSwzMTAuMzQwMDkyMDQ3MTE3NjUgNzQyLjg1NzE0Mjg1NzE0MjksMjk0LjY4MTQxODI0NDcyNjk2IDgwMCwyOTguNjEwMzg5MjI1MTg0OSIgZmlsbD0ibm9uZSIvPjxwYXRoIGNsYXNzPSJjeW5lZmluQ2xpZmYiIGQ9Ik00MDAsMzAwIEM0MjQsMzYwIDM2NCw0NjUgNDEyLDUyNSBDMzc2LDU1NSA0MDcuMiw1ODUgNDAwLDYwMCIgZmlsbD0ibm9uZSIvPjwvZz48cGF0aCBjbGFzcz0iY3luZWZpbkNvbmZ1c2lvbiIgZD0iTTI4MCwzMDAgQTEyMCw5MCAwIDEsMSA1MjAsMzAwIEExMjAsOTAgMCAxLDEgMjgwLDMwMCBaIiBmaWxsPSIjRjNFNUY1IiBmaWxsLW9wYWNpdHk9IjAuNSIvPjxnIGNsYXNzPSJjeW5lZmluLWxhYmVscyI+PHRleHQgY2xhc3M9ImN5bmVmaW5Eb21haW5MYWJlbCIgeD0iMjAwIiB5PSIxMjAiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiPkNvbXBsZXg8L3RleHQ+PHRleHQgY2xhc3M9ImN5bmVmaW5Eb21haW5MYWJlbCIgeD0iNjAwIiB5PSIxMjAiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiPkNvbXBsaWNhdGVkPC90ZXh0Pjx0ZXh0IGNsYXNzPSJjeW5lZmluRG9tYWluTGFiZWwiIHg9IjIwMCIgeT0iNDIwIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIj5DaGFvdGljPC90ZXh0Pjx0ZXh0IGNsYXNzPSJjeW5lZmluRG9tYWluTGFiZWwiIHg9IjYwMCIgeT0iNDIwIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIj5DbGVhcjwvdGV4dD48dGV4dCBjbGFzcz0iY3luZWZpbkRvbWFpbkxhYmVsIiB4PSI0MDAiIHk9IjI5MCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZG9taW5hbnQtYmFzZWxpbmU9Im1pZGRsZSI+Q29uZnVzaW9uPC90ZXh0PjwvZz48ZyBjbGFzcz0iY3luZWZpbi1zdWJ0aXRsZXMiPjx0ZXh0IGNsYXNzPSJjeW5lZmluU3VidGl0bGUiIHg9IjIwMCIgeT0iMTQwIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIj5Qcm9iZSDihpIgU2Vuc2Ug4oaSIFJlc3BvbmQ8L3RleHQ+PHRleHQgY2xhc3M9ImN5bmVmaW5TdWJ0aXRsZSIgeD0iMjAwIiB5PSIxNTUiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiPkVtZXJnZW50IFByYWN0aWNlczwvdGV4dD48dGV4dCBjbGFzcz0iY3luZWZpblN1YnRpdGxlIiB4PSI2MDAiIHk9IjE0MCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZG9taW5hbnQtYmFzZWxpbmU9Im1pZGRsZSI+U2Vuc2Ug4oaSIEFuYWx5c2Ug4oaSIFJlc3BvbmQ8L3RleHQ+PHRleHQgY2xhc3M9ImN5bmVmaW5TdWJ0aXRsZSIgeD0iNjAwIiB5PSIxNTUiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiPkdvb2QgUHJhY3RpY2VzPC90ZXh0Pjx0ZXh0IGNsYXNzPSJjeW5lZmluU3VidGl0bGUiIHg9IjIwMCIgeT0iNDQwIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIj5BY3Qg4oaSIFNlbnNlIOKGkiBSZXNwb25kPC90ZXh0Pjx0ZXh0IGNsYXNzPSJjeW5lZmluU3VidGl0bGUiIHg9IjIwMCIgeT0iNDU1IiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIj5Ob3ZlbCBQcmFjdGljZXM8L3RleHQ+PHRleHQgY2xhc3M9ImN5bmVmaW5TdWJ0aXRsZSIgeD0iNjAwIiB5PSI0NDAiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiPlNlbnNlIOKGkiBDYXRlZ29yaXNlIOKGkiBSZXNwb25kPC90ZXh0Pjx0ZXh0IGNsYXNzPSJjeW5lZmluU3VidGl0bGUiIHg9IjYwMCIgeT0iNDU1IiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIj5CZXN0IFByYWN0aWNlczwvdGV4dD48dGV4dCBjbGFzcz0iY3luZWZpblN1YnRpdGxlIiB4PSI0MDAiIHk9IjMwOCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZG9taW5hbnQtYmFzZWxpbmU9Im1pZGRsZSI+RGlzb3JkZXI8L3RleHQ+PC9nPjxnIGNsYXNzPSJjeW5lZmluLWl0ZW1zIj48ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMTIuOTM0OTIxMjY0NjQ4NDQsIDE3NSkiPjxyZWN0IGNsYXNzPSJjeW5lZmluSXRlbSIgeD0iMCIgeT0iMCIgd2lkdGg9IjE3NC4xMzAxNTc0NzA3MDMxMiIgaGVpZ2h0PSIyNiIgcng9IjQiIHJ5PSI0IiBmaWxsPSIjRThGNUU5IiBmaWxsLW9wYWNpdHk9IjAuOTUiLz48dGV4dCBjbGFzcz0iY3luZWZpbkl0ZW1UZXh0IiB4PSI4Ny4wNjUwNzg3MzUzNTE1NiIgeT0iMTMiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGRvbWluYW50LWJhc2VsaW5lPSJjZW50cmFsIj5SdW4gc2FmZS10by1mYWlsIGV4cGVyaW1lbnRzPC90ZXh0PjwvZz48ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSg1MzIuNzY1Njg5ODQ5ODUzNSwgMTc1KSI+PHJlY3QgY2xhc3M9ImN5bmVmaW5JdGVtIiB4PSIwIiB5PSIwIiB3aWR0aD0iMTM0LjQ2ODYyMDMwMDI5Mjk3IiBoZWlnaHQ9IjI2IiByeD0iNCIgcnk9IjQiIGZpbGw9IiNFM0YyRkQiIGZpbGwtb3BhY2l0eT0iMC45NSIvPjx0ZXh0IGNsYXNzPSJjeW5lZmluSXRlbVRleHQiIHg9IjY3LjIzNDMxMDE1MDE0NjQ4IiB5PSIxMyIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZG9taW5hbnQtYmFzZWxpbmU9ImNlbnRyYWwiPkFuYWx5emUgd2l0aCBleHBlcnRzPC90ZXh0PjwvZz48ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxNTMuNjI4MDk3NTM0MTc5NywgNDc1KSI+PHJlY3QgY2xhc3M9ImN5bmVmaW5JdGVtIiB4PSIwIiB5PSIwIiB3aWR0aD0iOTIuNzQzODA0OTMxNjQwNjIiIGhlaWdodD0iMjYiIHJ4PSI0IiByeT0iNCIgZmlsbD0iI0ZCRTlFNyIgZmlsbC1vcGFjaXR5PSIwLjk1Ii8+PHRleHQgY2xhc3M9ImN5bmVmaW5JdGVtVGV4dCIgeD0iNDYuMzcxOTAyNDY1ODIwMzEiIHk9IjEzIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBkb21pbmFudC1iYXNlbGluZT0iY2VudHJhbCI+U3RhYmlsaXplIGZpcnN0PC90ZXh0PjwvZz48ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSg1MzcuMjI1NTQzOTc1ODMwMSwgNDc1KSI+PHJlY3QgY2xhc3M9ImN5bmVmaW5JdGVtIiB4PSIwIiB5PSIwIiB3aWR0aD0iMTI1LjU0ODkxMjA0ODMzOTg0IiBoZWlnaHQ9IjI2IiByeD0iNCIgcnk9IjQiIGZpbGw9IiNGRkY4RTEiIGZpbGwtb3BhY2l0eT0iMC45NSIvPjx0ZXh0IGNsYXNzPSJjeW5lZmluSXRlbVRleHQiIHg9IjYyLjc3NDQ1NjAyNDE2OTkyIiB5PSIxMyIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZG9taW5hbnQtYmFzZWxpbmU9ImNlbnRyYWwiPkFwcGx5IGJlc3QgcHJhY3RpY2U8L3RleHQ+PC9nPjxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDMyMy44MTkwOTk0MjYyNjk1MywgMzIyKSI+PHJlY3QgY2xhc3M9ImN5bmVmaW5JdGVtIiB4PSIwIiB5PSIwIiB3aWR0aD0iMTUyLjM2MTgwMTE0NzQ2MDk0IiBoZWlnaHQ9IjI2IiByeD0iNCIgcnk9IjQiIGZpbGw9IiNGM0U1RjUiIGZpbGwtb3BhY2l0eT0iMC45NSIvPjx0ZXh0IGNsYXNzPSJjeW5lZmluSXRlbVRleHQiIHg9Ijc2LjE4MDkwMDU3MzczMDQ3IiB5PSIxMyIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZG9taW5hbnQtYmFzZWxpbmU9ImNlbnRyYWwiPkJyZWFrIHRoZSBwcm9ibGVtIGRvd248L3RleHQ+PC9nPjwvZz48ZyBjbGFzcz0iY3luZWZpbi1hcnJvd3MiPjxwYXRoIGNsYXNzPSJjeW5lZmluQXJyb3dMaW5lIiBkPSJNNjAwLDQ1MCBRNDAwLDM5MCAyMDAsNDUwIiBmaWxsPSJub25lIiBtYXJrZXItZW5kPSJ1cmwoI2N5bmVmaW4tYXJyb3ctbXktc3ZnKSIvPjx0ZXh0IGNsYXNzPSJjeW5lZmluQXJyb3dMYWJlbCIgeD0iNDAwIiB5PSIzODQiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGRvbWluYW50LWJhc2VsaW5lPSJhdXRvIj5Db21wbGFjZW5jeTwvdGV4dD48cGF0aCBjbGFzcz0iY3luZWZpbkFycm93TGluZSIgZD0iTTIwMCw0NTAgUTI0NSwzMDAgMjAwLDE1MCIgZmlsbD0ibm9uZSIgbWFya2VyLWVuZD0idXJsKCNjeW5lZmluLWFycm93LW15LXN2ZykiLz48dGV4dCBjbGFzcz0iY3luZWZpbkFycm93TGFiZWwiIHg9IjI0NSIgeT0iMjk0IiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBkb21pbmFudC1iYXNlbGluZT0iYXV0byI+U3RhYmlsaXplZDwvdGV4dD48L2c+PHRleHQgY2xhc3M9ImN5bmVmaW5UaXRsZSIgeD0iNDAwIiB5PSItMjAiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiPldoaWNoIG1vZGUgZG9lcyB0aGlzIHByb2JsZW0gbmVlZD88L3RleHQ+PC9nPjxkZWZzPjxtYXJrZXIgaWQ9ImN5bmVmaW4tYXJyb3ctbXktc3ZnIiB2aWV3Qm94PSIwIDAgMTAgMTAiIHJlZlg9IjkiIHJlZlk9IjUiIG1hcmtlcldpZHRoPSI2IiBtYXJrZXJIZWlnaHQ9IjYiIG9yaWVudD0iYXV0by1zdGFydC1yZXZlcnNlIj48cGF0aCBkPSJNIDAgMCBMIDEwIDUgTCAwIDEwIHoiIGNsYXNzPSJjeW5lZmluQXJyb3dIZWFkIi8+PC9tYXJrZXI+PC9kZWZzPjwvc3ZnPg==) Read the diagram as a decision: a new outage is `chaotic` (stabilize first), once the network is back it moves to `complicated` (analyze the hypotheses with experts), and a repeat postmortem outcome lands in `clear` (apply the documented runbook). The transitions between domains are drawn, not implied — the map answers "which mode *now*" the way the team actually works. ## Copy-paste 3: which item first — quadrant[​](#copy-paste-3-which-item-first--quadrant "Direct link to Copy-paste 3: which item first — quadrant") When the decision is a ranking, the effort/impact quadrant is the framework. Pair it with the Venn when the ranking inputs overlap: ``` quadrantChart title What to tackle first x-axis Low Effort --> High Effort y-axis Low Impact --> High Impact quadrant-1 Ship now quadrant-2 Plan carefully quadrant-3 Defer quadrant-4 Skip "Shared checkout": [0.25, 0.2] "Trusted client": [0.35, 0.7] "Native payment": [0.6, 0.85] "SDK gold path": [0.85, 0.3] ``` ![What to tackle first](data:image/svg+xml;base64,PHN2ZyBpZD0ibXktc3ZnIiB3aWR0aD0iMTAwJSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgc3R5bGU9Im1heC13aWR0aDogNTAwcHg7IGJhY2tncm91bmQtY29sb3I6IHdoaXRlOyIgdmlld0JveD0iMCAwIDUwMCA1MDAiIHJvbGU9ImdyYXBoaWNzLWRvY3VtZW50IGRvY3VtZW50IiBhcmlhLXJvbGVkZXNjcmlwdGlvbj0icXVhZHJhbnRDaGFydCI+PHN0eWxlPiNteS1zdmd7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO2ZvbnQtc2l6ZToxNnB4O2ZpbGw6IzMzMzt9QGtleWZyYW1lcyBlZGdlLWFuaW1hdGlvbi1mcmFtZXtmcm9te3N0cm9rZS1kYXNob2Zmc2V0OjA7fX1Aa2V5ZnJhbWVzIGRhc2h7dG97c3Ryb2tlLWRhc2hvZmZzZXQ6MDt9fSNteS1zdmcgLmVkZ2UtYW5pbWF0aW9uLXNsb3d7c3Ryb2tlLWRhc2hhcnJheTo5LDUhaW1wb3J0YW50O3N0cm9rZS1kYXNob2Zmc2V0OjkwMDthbmltYXRpb246ZGFzaCA1MHMgbGluZWFyIGluZmluaXRlO3N0cm9rZS1saW5lY2FwOnJvdW5kO30jbXktc3ZnIC5lZGdlLWFuaW1hdGlvbi1mYXN0e3N0cm9rZS1kYXNoYXJyYXk6OSw1IWltcG9ydGFudDtzdHJva2UtZGFzaG9mZnNldDo5MDA7YW5pbWF0aW9uOmRhc2ggMjBzIGxpbmVhciBpbmZpbml0ZTtzdHJva2UtbGluZWNhcDpyb3VuZDt9I215LXN2ZyAuZXJyb3ItaWNvbntmaWxsOiM1NTIyMjI7fSNteS1zdmcgLmVycm9yLXRleHR7ZmlsbDojNTUyMjIyO3N0cm9rZTojNTUyMjIyO30jbXktc3ZnIC5lZGdlLXRoaWNrbmVzcy1ub3JtYWx7c3Ryb2tlLXdpZHRoOjFweDt9I215LXN2ZyAuZWRnZS10aGlja25lc3MtdGhpY2t7c3Ryb2tlLXdpZHRoOjMuNXB4O30jbXktc3ZnIC5lZGdlLXBhdHRlcm4tc29saWR7c3Ryb2tlLWRhc2hhcnJheTowO30jbXktc3ZnIC5lZGdlLXRoaWNrbmVzcy1pbnZpc2libGV7c3Ryb2tlLXdpZHRoOjA7ZmlsbDpub25lO30jbXktc3ZnIC5lZGdlLXBhdHRlcm4tZGFzaGVke3N0cm9rZS1kYXNoYXJyYXk6Mzt9I215LXN2ZyAuZWRnZS1wYXR0ZXJuLWRvdHRlZHtzdHJva2UtZGFzaGFycmF5OjI7fSNteS1zdmcgLm1hcmtlcntmaWxsOiMzMzMzMzM7c3Ryb2tlOiMzMzMzMzM7fSNteS1zdmcgLm1hcmtlci5jcm9zc3tzdHJva2U6IzMzMzMzMzt9I215LXN2ZyBzdmd7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO2ZvbnQtc2l6ZToxNnB4O30jbXktc3ZnIHB7bWFyZ2luOjA7fSNteS1zdmcgLm5vZGUgLm5lby1ub2Rle3N0cm9rZTojOTM3MERCO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcmVjdCwjbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLmNsdXN0ZXIgcmVjdCwjbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcG9seWdvbntzdHJva2U6IzkzNzBEQjtmaWx0ZXI6ZHJvcC1zaGFkb3coMXB4IDJweCAycHggcmdiYSgxODUsIDE4NSwgMTg1LCAxKSk7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uc3dpbWxhbmUuY2x1c3RlciByZWN0e2ZpbHRlcjpub25lO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcGF0aHtzdHJva2U6IzkzNzBEQjtzdHJva2Utd2lkdGg6MXB4O30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgLm91dGVyLXBhdGh7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgLm5lby1saW5lIHBhdGh7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOm5vbmU7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSBjaXJjbGV7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgY2lyY2xlIC5zdGF0ZS1zdGFydHtmaWxsOiMwMDAwMDA7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uaWNvbi1zaGFwZSAuaWNvbntmaWxsOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLmljb24tc2hhcGUgLmljb24tbmVvIHBhdGh7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIDpyb290ey0tbWVybWFpZC1mb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7fTwvc3R5bGU+PGcvPjxnIGNsYXNzPSJtYWluIj48ZyBjbGFzcz0icXVhZHJhbnRzIj48ZyBjbGFzcz0icXVhZHJhbnQiPjxyZWN0IHg9IjI2MyIgeT0iNDUiIHdpZHRoPSIyMzIiIGhlaWdodD0iMjEyIiBmaWxsPSIjRUNFQ0ZGIi8+PHRleHQgeD0iMCIgeT0iMCIgZmlsbD0iIzEzMTMwMCIgZm9udC1zaXplPSIxNiIgZG9taW5hbnQtYmFzZWxpbmU9ImhhbmdpbmciIHRleHQtYW5jaG9yPSJtaWRkbGUiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDM3OSwgNTApIHJvdGF0ZSgwKSI+U2hpcCBub3c8L3RleHQ+PC9nPjxnIGNsYXNzPSJxdWFkcmFudCI+PHJlY3QgeD0iMzEiIHk9IjQ1IiB3aWR0aD0iMjMyIiBoZWlnaHQ9IjIxMiIgZmlsbD0iI2YxZjFmZiIvPjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMwZTBlMDAiIGZvbnQtc2l6ZT0iMTYiIGRvbWluYW50LWJhc2VsaW5lPSJoYW5naW5nIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxNDcsIDUwKSByb3RhdGUoMCkiPlBsYW4gY2FyZWZ1bGx5PC90ZXh0PjwvZz48ZyBjbGFzcz0icXVhZHJhbnQiPjxyZWN0IHg9IjMxIiB5PSIyNTciIHdpZHRoPSIyMzIiIGhlaWdodD0iMjEyIiBmaWxsPSIjZjZmNmZmIi8+PHRleHQgeD0iMCIgeT0iMCIgZmlsbD0iIzA5MDkwMCIgZm9udC1zaXplPSIxNiIgZG9taW5hbnQtYmFzZWxpbmU9ImhhbmdpbmciIHRleHQtYW5jaG9yPSJtaWRkbGUiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDE0NywgMjYyKSByb3RhdGUoMCkiPkRlZmVyPC90ZXh0PjwvZz48ZyBjbGFzcz0icXVhZHJhbnQiPjxyZWN0IHg9IjI2MyIgeT0iMjU3IiB3aWR0aD0iMjMyIiBoZWlnaHQ9IjIxMiIgZmlsbD0iI2ZiZmJmZiIvPjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMwNDA0MDAiIGZvbnQtc2l6ZT0iMTYiIGRvbWluYW50LWJhc2VsaW5lPSJoYW5naW5nIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgzNzksIDI2Mikgcm90YXRlKDApIj5Ta2lwPC90ZXh0PjwvZz48L2c+PGcgY2xhc3M9ImJvcmRlciI+PGxpbmUgeDE9IjMwIiB5MT0iNDUiIHgyPSI0OTYiIHkyPSI0NSIgc3R5bGU9InN0cm9rZTogcmdiKDE5OSwgMTk5LCAyNDEpOyBzdHJva2Utd2lkdGg6IDI7Ii8+PGxpbmUgeDE9IjQ5NSIgeTE9IjQ2IiB4Mj0iNDk1IiB5Mj0iNDY4IiBzdHlsZT0ic3Ryb2tlOiByZ2IoMTk5LCAxOTksIDI0MSk7IHN0cm9rZS13aWR0aDogMjsiLz48bGluZSB4MT0iMzAiIHkxPSI0NjkiIHgyPSI0OTYiIHkyPSI0NjkiIHN0eWxlPSJzdHJva2U6IHJnYigxOTksIDE5OSwgMjQxKTsgc3Ryb2tlLXdpZHRoOiAyOyIvPjxsaW5lIHgxPSIzMSIgeTE9IjQ2IiB4Mj0iMzEiIHkyPSI0NjgiIHN0eWxlPSJzdHJva2U6IHJnYigxOTksIDE5OSwgMjQxKTsgc3Ryb2tlLXdpZHRoOiAyOyIvPjxsaW5lIHgxPSIyNjMiIHkxPSI0NiIgeDI9IjI2MyIgeTI9IjQ2OCIgc3R5bGU9InN0cm9rZTogcmdiKDE5OSwgMTk5LCAyNDEpOyBzdHJva2Utd2lkdGg6IDE7Ii8+PGxpbmUgeDE9IjMyIiB5MT0iMjU3IiB4Mj0iNDk0IiB5Mj0iMjU3IiBzdHlsZT0ic3Ryb2tlOiByZ2IoMTk5LCAxOTksIDI0MSk7IHN0cm9rZS13aWR0aDogMTsiLz48L2c+PGcgY2xhc3M9ImRhdGEtcG9pbnRzIj48ZyBjbGFzcz0iZGF0YS1wb2ludCI+PGNpcmNsZSBjeD0iNDI1LjQiIGN5PSIzNDEuNzk5OTk5OTk5OTk5OTUiIHI9IjUiIGZpbGw9ImhzbCgyNDAsIDEwMCUsIE5hTiUpIiBzdHJva2U9ImhzbCgyNDAsIDEwMCUsIE5hTiUpIiBzdHJva2Utd2lkdGg9IjBweCIvPjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMxMzEzMDAiIGZvbnQtc2l6ZT0iMTIiIGRvbWluYW50LWJhc2VsaW5lPSJoYW5naW5nIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSg0MjUuNCwgMzQ2Ljc5OTk5OTk5OTk5OTk1KSByb3RhdGUoMCkiPlNESyBnb2xkIHBhdGg8L3RleHQ+PC9nPjxnIGNsYXNzPSJkYXRhLXBvaW50Ij48Y2lyY2xlIGN4PSIzMDkuNCIgY3k9IjEwOC42MDAwMDAwMDAwMDAwMSIgcj0iNSIgZmlsbD0iaHNsKDI0MCwgMTAwJSwgTmFOJSkiIHN0cm9rZT0iaHNsKDI0MCwgMTAwJSwgTmFOJSkiIHN0cm9rZS13aWR0aD0iMHB4Ii8+PHRleHQgeD0iMCIgeT0iMCIgZmlsbD0iIzEzMTMwMCIgZm9udC1zaXplPSIxMiIgZG9taW5hbnQtYmFzZWxpbmU9ImhhbmdpbmciIHRleHQtYW5jaG9yPSJtaWRkbGUiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDMwOS40LCAxMTMuNjAwMDAwMDAwMDAwMDEpIHJvdGF0ZSgwKSI+TmF0aXZlIHBheW1lbnQ8L3RleHQ+PC9nPjxnIGNsYXNzPSJkYXRhLXBvaW50Ij48Y2lyY2xlIGN4PSIxOTMuNCIgY3k9IjE3Mi4yMDAwMDAwMDAwMDAwMiIgcj0iNSIgZmlsbD0iaHNsKDI0MCwgMTAwJSwgTmFOJSkiIHN0cm9rZT0iaHNsKDI0MCwgMTAwJSwgTmFOJSkiIHN0cm9rZS13aWR0aD0iMHB4Ii8+PHRleHQgeD0iMCIgeT0iMCIgZmlsbD0iIzEzMTMwMCIgZm9udC1zaXplPSIxMiIgZG9taW5hbnQtYmFzZWxpbmU9ImhhbmdpbmciIHRleHQtYW5jaG9yPSJtaWRkbGUiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDE5My40LCAxNzcuMjAwMDAwMDAwMDAwMDIpIHJvdGF0ZSgwKSI+VHJ1c3RlZCBjbGllbnQ8L3RleHQ+PC9nPjxnIGNsYXNzPSJkYXRhLXBvaW50Ij48Y2lyY2xlIGN4PSIxNDciIGN5PSIzODQuMjAwMDAwMDAwMDAwMDUiIHI9IjUiIGZpbGw9ImhzbCgyNDAsIDEwMCUsIE5hTiUpIiBzdHJva2U9ImhzbCgyNDAsIDEwMCUsIE5hTiUpIiBzdHJva2Utd2lkdGg9IjBweCIvPjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMxMzEzMDAiIGZvbnQtc2l6ZT0iMTIiIGRvbWluYW50LWJhc2VsaW5lPSJoYW5naW5nIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxNDcsIDM4OS4yMDAwMDAwMDAwMDAwNSkgcm90YXRlKDApIj5TaGFyZWQgY2hlY2tvdXQ8L3RleHQ+PC9nPjwvZz48ZyBjbGFzcz0ibGFiZWxzIj48ZyBjbGFzcz0ibGFiZWwiPjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMxMzEzMDAiIGZvbnQtc2l6ZT0iMTYiIGRvbWluYW50LWJhc2VsaW5lPSJoYW5naW5nIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxNDcsIDQ3OSkgcm90YXRlKDApIj5Mb3cgRWZmb3J0PC90ZXh0PjwvZz48ZyBjbGFzcz0ibGFiZWwiPjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMxMzEzMDAiIGZvbnQtc2l6ZT0iMTYiIGRvbWluYW50LWJhc2VsaW5lPSJoYW5naW5nIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgzNzksIDQ3OSkgcm90YXRlKDApIj5IaWdoIEVmZm9ydDwvdGV4dD48L2c+PGcgY2xhc3M9ImxhYmVsIj48dGV4dCB4PSIwIiB5PSIwIiBmaWxsPSIjMTMxMzAwIiBmb250LXNpemU9IjE2IiBkb21pbmFudC1iYXNlbGluZT0iaGFuZ2luZyIgdGV4dC1hbmNob3I9Im1pZGRsZSIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNSwgMzYzKSByb3RhdGUoLTkwKSI+TG93IEltcGFjdDwvdGV4dD48L2c+PGcgY2xhc3M9ImxhYmVsIj48dGV4dCB4PSIwIiB5PSIwIiBmaWxsPSIjMTMxMzAwIiBmb250LXNpemU9IjE2IiBkb21pbmFudC1iYXNlbGluZT0iaGFuZ2luZyIgdGV4dC1hbmNob3I9Im1pZGRsZSIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNSwgMTUxKSByb3RhdGUoLTkwKSI+SGlnaCBJbXBhY3Q8L3RleHQ+PC9nPjwvZz48ZyBjbGFzcz0idGl0bGUiPjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMxMzEzMDAiIGZvbnQtc2l6ZT0iMjAiIGRvbWluYW50LWJhc2VsaW5lPSJoYW5naW5nIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgyNTAsIDEwKSByb3RhdGUoMCkiPldoYXQgdG8gdGFja2xlIGZpcnN0PC90ZXh0PjwvZz48L2c+PC9zdmc+) This is the Venn above, re-asked: of the three ownership pockets, "Shared checkout" is low-effort low-impact (ship now, cheap win), "Trusted client" and "Native payment" are the big bets. One page, two questions answered — who owns the overlap (Venn) and what to build first (quadrant). ## Picking the framework[​](#picking-the-framework "Direct link to Picking the framework") | Question you're answering | Framework | Mermaid keyword | | ---------------------------------------- | ------------ | --------------- | | Who shares this concern / what overlaps? | **Venn** | `venn-beta` | | What mode does this situation need? | **Cynefin** | `cynefin-beta` | | Which item goes first? | **Quadrant** | `quadrantChart` | | How much flows through each stage? | **Sankey** | `sankey-beta` | The decision record's neighbors are on the same wiki: the **analysis** behind the choice as a [fishbone root cause analysis](/blog/mermaid-fishbone-root-cause-analysis-confluence.md) and the **owners** of the resulting work as a [responsibility swimlane](/blog/mermaid-process-flow-swimlane-diagram-confluence.md). ## FAQ[​](#faq "Direct link to FAQ") **Does Confluence have a built-in Venn or Cynefin diagram tool?** No — Confluence has no native framework diagramming. Mermaid Plus Diagrams & AI Agent for Confluence renders `venn-beta`, `cynefin-beta` and `quadrantChart` from editable text. **When do I use Venn vs Cynefin vs quadrant?** Venn for overlap, Cynefin for operating mode (how knowable is the situation), quadrant for sequencing (which first). They compose: classify with Cynefin, find overlaps with Venn, rank with the quadrant. **How do I show shared responsibility in a Venn diagram?** Define each set, then add `union A,B["label"]` lines — the labeled intersection is the shared-owner pocket. **What does Cynefin actually change about the decision?** It changes the *method*: best practice for clear, expert analysis for complicated, safe-to-fail experiments for complex, stabilization for chaotic. Drawing the domain is the decision aid. Render every Mermaid diagram type — venn, cynefin, quadrant, sankey, flowchart and 24 more — in [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), free for up to 10 users. Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [venn-diagram](/blog/tags/venn-diagram.md) * [cynefin](/blog/tags/cynefin.md) * [quadrant](/blog/tags/quadrant.md) * [decision](/blog/tags/decision.md) * [how-to](/blog/tags/how-to.md) --- # Mermaid Diagrams for Jira Sprint Workflows — Which Diagrams Actually Help the Standup July 23, 2026 · 9 min read [NGPilot](https://ngpilot.com) Who should read this * **Scrum masters and eng leads** who run standups from Jira * **Development teams** deciding which diagrams to maintain across a sprint * **Anyone** who wants to know which of Mermaid's 30 diagram types are actually useful for agile work What you'll learn 1. The four Mermaid diagram types a sprint team actually reaches for 2. How to embed each one inside a Jira issue, with copy-paste syntax 3. When a diagram belongs in Jira vs. Confluence 4. The full 30-type reference for less common needs Every team that adopts Jira diagrams hits the same moment: you discover Mermaid supports 30 diagram types, you get excited, and then you realize you have no idea which ones to actually use during a sprint. Most of them never get drawn. The diagrams that earn their keep are the ones that make a standup faster, an onboarding doc clearer, or a ticket unambiguous — and those are a small, repeatable subset. This post is the workflow guide we wish we'd had: the four diagram types a sprint team actually uses, each with a real scenario and copy-paste syntax you can drop straight into a Jira issue. The full 30-type reference follows, so the same page works as both a sprint playbook and a complete catalog. ![The Mermaid Plus Diagrams for Jira editor showing the Quick Templates panel and a flowchart in the preview.](/assets/images/editor-flowchart-48b53a3b376f1ca4aa586d33129f68f7.png) ## The four diagrams a sprint team actually uses[​](#the-four-diagrams-a-sprint-team-actually-uses "Direct link to The four diagrams a sprint team actually uses") ### 1. Flowchart — the definition-of-done diagram[​](#1-flowchart--the-definition-of-done-diagram "Direct link to 1. Flowchart — the definition-of-done diagram") Every team has a recurring "what does Done actually mean?" conversation. A flowchart pinned to the sprint's planning ticket removes the ambiguity: branches for code review, QA, security scan, and docs gate the path to Done. In Jira, the same flowchart on the workflow-transition screen reminds the engineer what's expected before they drag the ticket. Here's the Mermaid syntax for a typical definition-of-done: ``` flowchart TD A[Code complete] --> B{Peer reviewed?} B -- No --> A B -- Yes --> C{QA passed?} C -- No --> A C -- Yes --> D{Security scan clean?} D -- No --> A D -- Yes --> E[✅ Done] ``` Drop that into a Jira issue description and every engineer sees the same definition of Done. The decision diamonds (`{...}`) make the gates explicit; the loop back to "Code complete" makes rework obvious. **When to use it in Jira:** sprint planning tickets, workflow documentation, onboarding for new engineers who need to learn the process. ### 2. Gantt — the sprint timeline[​](#2-gantt--the-sprint-timeline "Direct link to 2. Gantt — the sprint timeline") A Gantt chart in the sprint planning issue shows which stories overlap, where the critical path is, and whether the sprint is actually feasible. Mermaid's Gantt syntax is dates or durations: ``` gantt title Sprint 47 timeline dateFormat YYYY-MM-DD section Backend API endpoint :a1, 2026-07-23, 3d DB migration :a2, after a1, 2d section Frontend Wire up UI :b1, 2026-07-24, 4d E2E tests :b2, after b1, 2d section Release Deploy to staging :milestone, 2026-08-01, 0d ``` The `section` keyword groups work by team or layer, which makes cross-team dependencies visible at a glance. Milestones (`:milestone`) mark ship dates. **When to use it in Jira:** the sprint planning epic, release-train tickets, any story where sequencing matters more than status. ### 3. Sequence diagram — the handoff diagram[​](#3-sequence-diagram--the-handoff-diagram "Direct link to 3. Sequence diagram — the handoff diagram") When a ticket spans two services or two teams, a sequence diagram is the clearest way to show who calls whom and in what order. It's the diagram that prevents the "I thought your service was going to call mine" conversation in production. ``` sequenceDiagram participant U as User participant W as Web App participant A as Auth Service participant D as Database U->>W: Login (email, password) W->>A: validate(credentials) A->>D: lookup user D-->>A: user record A-->>W: JWT token W-->>U: 200 OK + token ``` **When to use it in Jira:** integration stories, API-consumer tickets, bug reports where the reproduction path crosses service boundaries. ### 4. State diagram — the ticket-lifecycle diagram[​](#4-state-diagram--the-ticket-lifecycle-diagram "Direct link to 4. State diagram — the ticket-lifecycle diagram") For bugs and support tickets that bounce between states, a state diagram documents the allowed transitions and prevents invalid status moves. It's also the clearest way to explain a custom workflow to a new team member. ``` stateDiagram-v2 [*] --> Open Open --> InProgress: assign InProgress --> InReview: submit for review InReview --> InProgress: changes requested InReview --> Done: approved Done --> [*] Open --> Won'tFix: close Won'tFix --> [*] ``` **When to use it in Jira:** workflow-configuration tickets, documentation of custom Jira workflows, onboarding. ## How to embed a Mermaid diagram in a Jira issue[​](#how-to-embed-a-mermaid-diagram-in-a-jira-issue "Direct link to How to embed a Mermaid diagram in a Jira issue") ![The Mermaid Plus editor configuration panel inside a Jira issue, showing the code view, settings sidebar, and live preview.](/assets/images/editor-config-2795bd7f6ccb89362ba94b08eef85c98.png) ### 1. Install Mermaid Plus Diagrams for Jira[​](#1-install-mermaid-plus-diagrams-for-jira "Direct link to 1. Install Mermaid Plus Diagrams for Jira") Install [Mermaid Plus Diagrams for Jira](https://marketplace.atlassian.com/apps/2658777397/mermaid-plus-diagrams-for-jira) from the Atlassian Marketplace. It's free for up to 10 users and supports all 30 Mermaid diagram types with live preview. ### 2. Insert the macro[​](#2-insert-the-macro "Direct link to 2. Insert the macro") Open any Jira issue. Click into the description field or a comment, type `/mermaid`, and select the **Mermaid Plus** macro. The editor opens with a Quick Templates panel on the left, a code editor in the middle, and a live preview on the right. ### 3. Pick a template and customize[​](#3-pick-a-template-and-customize "Direct link to 3. Pick a template and customize") The Quick Templates panel lists all 30 diagram types. Click one to load a starter snippet into the code editor. Edit the syntax — the preview updates in real time, so you see exactly what the diagram will look like before you save. ### 4. Save[​](#4-save "Direct link to 4. Save") Click **Save**. The rendered diagram embeds into the Jira issue. Every viewer sees the same rendered image; they don't need the app installed in a viewer mode, and the diagram is included when the issue is exported. ![A rendered flowchart in Jira view mode, showing the diagram as readers see it after saving.](/assets/images/rendered-flowchart-21f1b72ff3440d4c02b6bf603a63f36a.png) ## Jira vs. Confluence: where does each diagram go?[​](#jira-vs-confluence-where-does-each-diagram-go "Direct link to Jira vs. Confluence: where does each diagram go?") A common question is whether a diagram belongs in the Jira ticket or in a linked Confluence page. The rule of thumb: | Diagram purpose | Put it in | Why | | ------------------------------------------------------------------------------- | ---------------------- | ----------------------------------------------- | | Specific to one ticket (this bug's repro path, this story's definition of done) | **Jira** | It travels with the ticket and stays in context | | Reused across tickets (the team's workflow, the system architecture) | **Confluence** | One source of truth, linked from many tickets | | Sprint timeline for this sprint only | **Jira** (sprint epic) | Ephemeral, lives with the sprint | | Sprint timeline pattern the team follows every sprint | **Confluence** | Durable reference | If you use [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence) alongside the Jira app, you can copy the same Mermaid syntax between both — the rendering is identical. ## The full 30 Mermaid diagram types (reference)[​](#the-full-30-mermaid-diagram-types-reference "Direct link to The full 30 Mermaid diagram types (reference)") Most sprint work uses the four types above. But Mermaid supports 30 types total, and the long tail matters for specific scenarios. Here's the complete list with one-line guidance on when each is useful: | Type | Best for | Sprint relevance | | -------------------------------------------------------- | ------------------------------------------------------- | --------------------- | | **Flowchart** | Processes, decisions, logic gates | ★★★ Core | | **Sequence** | Service interactions, API calls over time | ★★★ Core | | **Gantt** | Timelines, scheduling, dependencies | ★★★ Core | | **State** | Status transitions, lifecycles | ★★★ Core | | **Class** | Object-oriented design, data models | ★★ Architecture docs | | **ER** | Database schemas, entity relationships | ★★ Schema tickets | | **Mindmap** | Brainstorming, feature breakdown | ★★ Refinement | | **Pie** | Distribution (bug causes, time split) | ★ Retrospectives | | **Journey** | User experience maps | ★ Discovery | | **C4** | Architecture (Context, Container, Component) | ★★ System design | | **Architecture** | Box-and-line system diagrams | ★★ System design | | **Requirement** | Formal requirements (reqif) | ★ Compliance | | **GitGraph** | Branch and merge history | ★ Release docs | | **Timeline** | Chronological events | ★ Incident logs | | **Quadrant** | 2x2 prioritization matrices | ★ Planning | | **XYChart** | Numeric line/bar charts | ★ Metrics | | **Sankey** | Flow quantities between stages | ★ Bottleneck analysis | | **Block** | Block-based system layouts | ★ System design | | **Packet** | Network packet layouts | ★ Network docs | | **Radar** | Multi-axis capability comparison | ★ Tech radar | | **Treeview** | Hierarchical file/folder trees | ★ Repo docs | | **Venn** | Set overlaps | ★ Stakeholder mapping | | **Swimlane** | Cross-functional processes (team hand-offs) | ★ Process tickets | | **Cynefin** | Sense-making framework (5 decision domains) | ★ Strategy/retros | | **Railroad** | Syntax/grammar (EBNF) diagrams | ★ Language docs | | **Use case** | Actors and system capabilities (UML, new in Mermaid 12) | ★★ Requirements | | **Beta types** (ZenUML, kanban, treemap, fishbone, etc.) | Specialized | As needed | The types marked ★★★ are the ones that come up in standups and sprint planning. The rest are there when a specific ticket needs them. ## FAQ[​](#faq "Direct link to FAQ") ### Does Jira support Mermaid diagrams natively?[​](#does-jira-support-mermaid-diagrams-natively "Direct link to Does Jira support Mermaid diagrams natively?") No. Jira does not render Mermaid syntax out of the box. You need a Marketplace app like [Mermaid Plus Diagrams for Jira](https://marketplace.atlassian.com/apps/2658777397/mermaid-plus-diagrams-for-jira) to embed Mermaid diagrams in issue descriptions and comments with live preview. ### Can I use the same Mermaid diagram in Jira and Confluence?[​](#can-i-use-the-same-mermaid-diagram-in-jira-and-confluence "Direct link to Can I use the same Mermaid diagram in Jira and Confluence?") Yes. Mermaid syntax is portable. If you have Mermaid Plus for Jira and Mermaid Plus Diagrams & AI Agent for Confluence installed, you can copy the same syntax between a Jira issue and a Confluence page and get identical rendering. ### How many Mermaid diagram types are there?[​](#how-many-mermaid-diagram-types-are-there "Direct link to How many Mermaid diagram types are there?") Mermaid supports 30 diagram types, from flowcharts and sequence diagrams to Gantt charts, state diagrams, C4 architecture diagrams, and newer types like Sankey and radar charts. All 30 are available in Mermaid Plus Diagrams for Jira. ### Is Mermaid Plus Diagrams for Jira free?[​](#is-mermaid-plus-diagrams-for-jira-free "Direct link to Is Mermaid Plus Diagrams for Jira free?") Mermaid Plus Diagrams for Jira is free for up to 10 users. Beyond 10 users, standard Atlassian Marketplace licensing applies. A trial unlocks all features. ### Do Mermaid diagrams render in Jira exports?[​](#do-mermaid-diagrams-render-in-jira-exports "Direct link to Do Mermaid diagrams render in Jira exports?") Yes. Mermaid Plus pre-renders diagrams to cached images when you save, so they appear in Jira issue exports (including PDF and the bulk export tools) just like any other embedded image. ## Related guides[​](#related-guides "Direct link to Related guides") * [How to build a release timeline in Jira](/blog/how-to-create-release-timeline-jira.md) -- the release-scale counterpart: version milestones, multi-team tracks, and launch-week sequencing with copy-paste Gantt examples * [Create Mermaid diagrams on Jira issues](/blog/how-to-create-mermaid-diagrams-jira.md) -- the complete guide to diagrams on Jira issues * [Gantt charts in Confluence](/blog/how-to-create-gantt-charts-confluence.md) -- project-plan timelines on Confluence pages Try Mermaid Plus Diagrams for Jira All 30 Mermaid diagram types embedded in Jira issues, with live preview and Quick Templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/2658777397/mermaid-plus-diagrams-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-diagrams-for-jira) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [mermaid](/blog/tags/mermaid.md) * [diagrams](/blog/tags/diagrams.md) * [sprint](/blog/tags/sprint.md) * [workflow](/blog/tags/workflow.md) * [agile](/blog/tags/agile.md) * [how-to](/blog/tags/how-to.md) --- # Database Schema Diagrams in Confluence with Mermaid ER (Entity Relationship) — Copy-Paste September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The bug report says "orders show twice in the report" and the fix takes three days because nobody on the team is sure whether `order_lines` links to `orders` on `order_id` or `source_order_id`, and both columns exist. The schema is documented — in a `schema.md` that lists columns as bullets and a diagram that was last exported when the DB was two migrations younger. The join question is exactly the thing an ER diagram answers at a glance, and the thing a bulleted column list cannot answer at all. **Quick answer:** document the database schema in Confluence as a Mermaid `erDiagram`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Entities hold keys and attributes; relationship lines carry the cardinality and the join's noun. When the discussion turns to the domain model the code exposes, add a `classDiagram` on the same page. This post gives you three copy-paste examples. ## Why a schema needs a diagram, not a column list[​](#why-a-schema-needs-a-diagram-not-a-column-list "Direct link to Why a schema needs a diagram, not a column list") A column list tells you *what exists*. An ER diagram tells you *how it fits* — and the fit is where the bugs live: * **Which column is the join?** Two tables can share many columns; the diagram names the relationship ("places order"), and the cardinality markers say how many. * **Which side is 'many'?** Crow's-foot notation (`|`, `o`, `{`) encodes one-to-many directly — no counting rows to find out. * **What breaks first?** When a migration drops or renames a column, the review reads the ER diff and sees the impact before it ships. Because the diagram is text, it diffs and it reviews. The migration PR contains one line changed in the ER block, and the wiki stays honest with zero extra effort. ## Copy-paste 1: the core order tables[​](#copy-paste-1-the-core-order-tables "Direct link to Copy-paste 1: the core order tables") The shape every commerce team knows — customer, orders, order lines. Note how the relationship line names the join and the keys sit in the entities: ``` erDiagram CUSTOMER ||--o{ ORDER : places ORDER ||--|{ ORDER_LINE : contains ORDER ||--o{ PAYMENT : collects CUSTOMER { int id PK string email string name } ORDER { int id PK int customer_id FK datetime placed_at string status } ORDER_LINE { int id PK int order_id FK string sku int quantity int price_cents } PAYMENT { int id PK int order_id FK string method int amount_cents } ``` ![Rendered Mermaid diagram](/assets/images/erdiagram-a58f3a0ba531e68897de39345747e191.svg) The keys sitting inside the entities are the point: `ORDER.customer_id` is visible *in the same box* as the relationship that uses it, so the reader verifies the join against the column without scrolling to a separate key listing. ## Copy-paste 2: attribute mapping with keys on the table[​](#copy-paste-2-attribute-mapping-with-keys-on-the-table "Direct link to Copy-paste 2: attribute mapping with keys on the table") When the schema belongs to a broader system — users, teams, roles — group the entities and keep the relationship labels meaningful. The classic many-to-many through a join table: ``` erDiagram USER }o--o{ TEAM : "believes in" USER }o--o{ ROLE : "is granted" TEAM ||--o{ MEMBERSHIP : "enrolls" USER ||--o{ MEMBERSHIP : "owns" ROLE ||--o{ MEMBERSHIP : "scopes" ``` ![Rendered Mermaid diagram](/assets/images/erdiagram-2-5da2484f4edd89aef5f289cb188f64cc.svg) `USER }o--o{ TEAM` means many users belong to many teams — a relationship that only resolves through `MEMBERSHIP`. When a reviewer asks "how are users scoped?", the answer is the three lines of this diagram: users hold roles, and both flow through memberships. ## Copy-paste 3: when the discussion is the domain model[​](#copy-paste-3-when-the-discussion-is-the-domain-model "Direct link to Copy-paste 3: when the discussion is the domain model") Same store, different question. The debate is "should checkout live on the order or the payment?" — that is a *domain model* discussion, and a `classDiagram` shows the objects the code exposes rather than the tables that store them: ``` classDiagram class Customer { +String email +placeOrder() Order } class Order { +String status +addLine(sku, qty) +pay(method) Payment } class OrderLine { +String sku +int quantity } class Payment { +String method +int amountCents } Customer "1" --> "0..*" Order : places Order "1" --> "1..*" OrderLine : contains Order "1" --> "0..*" Payment : collects ``` ![Rendered Mermaid diagram](/assets/images/classdiagram-61b2ce53d35c4523ea716a5640e5e2b0.svg) Multiplicity on the arrows (`"1" --> "0..*"`) is the class-diagram answer to ER cardinality — the object version of the same truth. Keep both: `erDiagram` for the schema page, `classDiagram` for the design-discussion page, and cross-link them. ## Keeping the schema diagram honest[​](#keeping-the-schema-diagram-honest "Direct link to Keeping the schema diagram honest") Two habits keep an ER diagram from joining the pile of "this is outdated" docs: * **Ship it with the migration.** The ALTER TABLE and the one-line ER diff land in the same review. A diagram updated in the change that moves the schema cannot drift. * **Detail follows questions.** If joins only matter in the reporting team, keep the PAYMENT table's columns but skip the audit-log entity nobody queries. A diagram nobody reads is a diagram nobody corrects. The schema's other half is the API that exposes it; keep the request/response flow beside the tables with a [sequence diagram](/blog/how-to-create-sequence-diagrams-confluence.md), and the service that owns the tables documented with its [class structure](/blog/mermaid-class-diagram-document-codebase-confluence.md). ## FAQ[​](#faq "Direct link to FAQ") **Does Confluence have a built-in database ER diagram tool?** No — Confluence has no native diagramming. Mermaid Plus Diagrams & AI Agent for Confluence renders `erDiagram` from editable text with a cached live preview. **How do I show cardinality in a Mermaid ER diagram?** The line markers encode the count: `||` is exactly-one, `o{` is zero-to-many, `|{` is one-to-many. Read the marker at each end — the crow's-foot end is the 'many' side. **ER diagram or class diagram for a schema?** `erDiagram` for table/join truth; `classDiagram` for the domain model the code exposes. Most teams keep one of each, linked from the schema page. **How do I keep the schema diagram from drifting?** Update it in the same review that writes the migration — editable text in Confluence makes the diagram travel with the change. Render every Mermaid diagram type — ER, class, sequence, state, flowchart and 24 more — in [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), free for up to 10 users. Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [er-diagram](/blog/tags/er-diagram.md) * [database](/blog/tags/database.md) * [schema](/blog/tags/schema.md) * [class-diagram](/blog/tags/class-diagram.md) * [how-to](/blog/tags/how-to.md) --- # Root Cause Analysis in Confluence with Mermaid Fishbone + 5 Whys September 24, 2026 · 7 min read [NGPilot](https://ngpilot.com) A root cause analysis is only as good as the disagreement it survives. When the 'root cause' box on your postmortem template contains one sentence, the meeting spends an hour relitigating that sentence. A fishbone diagram and a 5 Whys chain move the argument onto a diagram: everyone sees which categories were considered, which branch was chosen, and exactly how the 'why' answers arrive at a root cause. Confluence is where RCA already happens — in the Root Cause Analysis template, in postmortems, in retros. The missing piece is a diagram that holds the reasoning. This guide shows you two copy-paste Mermaid diagrams: an `ishikawa` fishbone that maps every candidate cause category, and a `flowchart` 5-Whys drilldown that lands on one concrete fix. **Quick answer:** To run root cause analysis in Confluence, install [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence), open the RCA/postmortem page, and paste an `ishikawa` fishbone — the problem at the head, one branch per cause category (Platform, People, Process, Policy, Product, External). Then drill the winning branch with a `flowchart`-based 5 Whys, asking 'why' at each node until the answer is an assignable fix. Copy both examples below. The diagrams hold the reasoning so the review argues about fixes, not about what happened. ## Why a Whiteboard Fishbone Leaves a Gap[​](#why-a-whiteboard-fishbone-leaves-a-gap "Direct link to Why a Whiteboard Fishbone Leaves a Gap") Teams draw fishbones on whiteboards because the shape is useful — but the whiteboard drawing dies the moment it's transcribed. A photo in the meeting notes is not editable, it's not linked to the action items, and it doesn't survive the space rename. The RCA then lives as a text box with the fishbone's conclusion but none of its reasoning. A text-editable Mermaid fishbone on the Confluence page fixes all three: * **It stays editable** — the cause list is code; adding a cause is one line and a republish, not a redraw. * **It stays with the document** — the diagram is inside the postmortem, version-controlled with every edit, exported with the PDF. * **It links downstream** — the branch you drill with 5 Whys can point at the exact action item in the same page. The result is that the RCA page becomes the reasoning, not a summary of it. ## Copy-Paste Fishbone — Six Cause Categories[​](#copy-paste-fishbone--six-cause-categories "Direct link to Copy-Paste Fishbone — Six Cause Categories") Here is an `ishikawa` diagram sized for a software incident. Like the classic 6M fishbone, it uses six categories — but mapped to what a platform team actually has branches for. Swap the labels and causes for your own incident: ``` ishikawa direction XY title Why payments lagged 12 minutes Platform Database locked up Read replicas stalled People No on-call rotation Single bus factor Process No runbook Manual retry loop Policy No timeout on retries Alert threshold too high Product Client waits 30s by default External Payment provider degraded ``` ![Why payments lagged 12 minutes](/assets/images/why-payments-lagged-12-minutes-2ab7e0be95e262057d7bfd21a012f918.svg) Read it the way a fishbone is read: the head is the problem, each branch is a cause area, and the leaves are candidate causes. `direction XY` lays the spine out horizontally (the classic fishbone read); the default vertical is fine too, but horizontal reads best pasted under a 'Root Cause' heading. Notice what the diagram forces you to consider: the lock-up sits in **Platform**, but 'No timeout on retries' in **Policy** and 'Manual retry loop' in **Process** are different kinds of causes. A single-sentence 'root cause' box would collapse all three into one; the fishbone keeps the branches visible, which is exactly what a review needs to cross out options. ## The 5 Whys as a Flowchart[​](#the-5-whys-as-a-flowchart "Direct link to The 5 Whys as a Flowchart") The fishbone narrows the field. The 5 Whys picks a branch and drills it. As a Mermaid `flowchart`, each level asks 'why' about the previous answer, and the chain terminates the moment the answer is an assignable change: ``` flowchart TD %% title: The 5 Whys as a Flowchart Q1["Why did the checkout time out?"] --> A1["Payment provider was slow"] A1 --> Q2["Why was the provider slow?"] Q2 --> A2["Our retry called it twice, doubling queue load"] A2 --> Q3["Why did we retry on every failure?"] Q3 --> A3["The timeout policy treated timeouts like errors"] A3 --> Q4["Why did the policy treat them the same?"] Q4 --> A4["No retry governance for payment paths"] A4 --> R["Fix: add retry budget + fast-fail on checkout"] ``` ![The 5 Whys as a Flowchart](/assets/images/the-5-whys-as-a-flowchart-c9eff64661833e7d6691e48981d160b0.svg) The last node is not an explanation — it is a fix. That is the whole point of a 5 Whys in a postmortem: the drill stops when 'why' produces something you can assign. If the chain runs past five levels and the answer is still abstract ("lack of observability"), you drilled the wrong branch — go back to the fishbone and pick another. ## From Fishbone to Root Cause to Action Item[​](#from-fishbone-to-root-cause-to-action-item "Direct link to From Fishbone to Root Cause to Action Item") The two diagrams earn their place when they connect to a tracker. On the same postmortem page, one line under an **Action Items** heading ties the chain together: > Add a retry budget to payment checkout and fast-fail on timeouts (from [the 5 Whys chain above](#the-5-whys-as-a-flowchart): Policy branch → root cause #4). That anchor link is the point: the action item references the diagram node, the diagram shows the reasoning, and the postmortem stops being a report and becomes a decision log. Teams that do this find the review meeting shrinks, because there is nothing left to litigate — the candidates are on the board, crossed out or confirmed. ## Where It Sits Beside the Timeline Post[​](#where-it-sits-beside-the-timeline-post "Direct link to Where It Sits Beside the Timeline Post") The fishbone is the *analysis* half of a postmortem; the [incident timeline](/blog/mermaid-incident-postmortem-timeline-confluence.md) is the *facts* half. The reading order matters: timeline first (this is what happened), then fishbone + 5 Whys (here is why), then action items (here is the fix). | Postmortem stage | Diagram | Job | | ------------------------ | ------------------- | -------------------------------------------- | | What happened | `timeline` | Chronological facts, detection to resolution | | What was considered | `ishikawa` fishbone | Six cause categories, no stone unturned | | What is the actual cause | `flowchart` 5 Whys | Drill one branch to an assignable fix | | What we change | action item list | The fix as a tracked task | If the RCA page lives in Markdown instead of the WYSIWYG editor, the same fences render inside [Enhanced Markdown for Confluence](/apps/enhanced-markdown-for-confluence.md) — so teams writing incident reviews in Markdown get the same diagrams. ## Which Cause Categories for Software?[​](#which-cause-categories-for-software "Direct link to Which Cause Categories for Software?") | Category | What it holds | Software example | | -------- | ------------------------------------- | --------------------------------- | | Platform | Infrastructure, databases, networking | Database lock-up, replica lag | | People | Staffing, skills, rotation | On-call gaps, single bus factor | | Process | How work is defined run | Missing runbook, manual steps | | Policy | Rules, thresholds, budgets | No retry timeout, alert threshold | | Product | What the software does by default | Client waits 30s, no fast-fail | | External | Vendors, partners, third parties | Provider degradation, network | Classic 6M labels (Manpower, Method, Machine, Material, Measurement, Environment) suit manufacturing; the mapping above is the same structure renamed for platforms. Either set renders identically — the branch labels are just text. An RCA that survives a heated review is the one where the reasoning is on the page, not in someone's head. Install [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence), paste the fishbone and the 5 Whys into your next postmortem, and let the diagram end the argument instead of starting one. ## Related Guides[​](#related-guides "Direct link to Related Guides") * [Incident postmortem timeline in Confluence](/blog/mermaid-incident-postmortem-timeline-confluence.md) — the facts half of the postmortem: detection → escalation → resolution * [How to build a release timeline in Jira](/blog/how-to-create-release-timeline-jira.md) — the Gantt counterpart for planning-side timelines * [Mermaid diagrams for Jira sprint workflows](/blog/mermaid-diagrams-jira-sprint-workflows.md) — flowcharts and the diagram types teams use in retros Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [root-cause-analysis](/blog/tags/root-cause-analysis.md) * [fishbone](/blog/tags/fishbone.md) * [ishikawa](/blog/tags/ishikawa.md) * [5-whys](/blog/tags/5-whys.md) * [mermaid](/blog/tags/mermaid.md) * [confluence](/blog/tags/confluence.md) * [postmortem](/blog/tags/postmortem.md) * [how-to](/blog/tags/how-to.md) * [incident-management](/blog/tags/incident-management.md) --- # Visualize Git Branches & Releases Inside Jira with Mermaid GitGraph September 24, 2026 · 7 min read [NGPilot](https://ngpilot.com) Your team is mid-debug on a prod incident. A senior engineer asks *"which release shipped this commit, and why is it on the release branch when the PR said main?"* — and nobody can answer without switching between Jira, the git web UI, and a Slack thread. That context — commit history, branches, merge points, release versions — belongs *next to the issue*, not in a tool people have to leave Jira to open. **Quick answer:** paste a Mermaid `gitGraph` into the issue's [Mermaid Plus Diagrams for Jira](https://marketplace.atlassian.com/apps/2658777397/mermaid-plus-diagrams-for-jira/) panel and the branch history renders as a diagram right on the ticket — commits, branches, merges, and release tags, all in one editable text block. This post gives you three copy-paste examples: a trunk-based feature workflow, a hotfix outside the release window, and a branch-rule flowchart to keep behavior consistent. ## Why branch history belongs on the issue[​](#why-branch-history-belongs-on-the-issue "Direct link to Why branch history belongs on the issue") A Jira issue tracks *work*: what was asked, who owns it, what it did to the system. Once the PR merges, that story leaves the ticket — the work is closed, and the git history that actually changed the product lives somewhere else. The next person who opens the issue for a bug report gets a resolved ticket with no visible trace of what touched the codebase. A gitGraph closes that gap by putting the *change story* back on the ticket. Look at what a single `gitGraph` block answers at a glance: * Which branch introduced the change (and whether it touched `main` directly) * Where the merge point was — and therefore what a revert would roll back * When a release tag landed relative to the merge * Whether the work went in as one clean line or was rebased, split, and squashed Atlassian's own deep-dive on Mermaid text diagrams calls this the "diagram as conversation" — a graph you can point at in a review and say *"here is where it broke"*. ## Copy-paste 1: trunk-based feature workflow[​](#copy-paste-1-trunk-based-feature-workflow "Direct link to Copy-paste 1: trunk-based feature workflow") The first diagram is the everyday pattern: work on a short-lived branch, review, merge to main, then ride the release train. Paste this into the Mermaid Plus panel on the story's issue: ``` gitGraph title Trunk-based feature workflow commit id: "start" branch feature/payment-retry checkout feature/payment-retry commit id: "feat: retry with backoff" commit id: "fix: idempotency key" checkout main commit id: "chore: dep updates" merge feature/payment-retry commit id: "release: sprint 42" ``` ![Trunk-based feature workflow](/assets/images/trunk-based-feature-workflow-c7c6c844bb627a32087595c31b93cd4b.svg) Because it is text, this graph updates the way your git history actually does — a new commit is one line, a merge is one keyword. No dragging nodes, no re-connecting arrows. The four gitGraph verbs (`commit`, `branch`, `checkout`, `merge`) are the whole vocabulary. ## Copy-paste 2: a hotfix outside the release window[​](#copy-paste-2-a-hotfix-outside-the-release-window "Direct link to Copy-paste 2: a hotfix outside the release window") Production is broken and the fix cannot wait for the next release train. The reality of that moment is: patch `main`, branch a release line, and keep the fix flowing back into the trunk *and* the pending feature branch — so the bug stays fixed everywhere it matters. ``` gitGraph title Hotfix outside the release window commit id: "v2026-09" branch release/2026-10 checkout release/2026-10 branch hotfix/payment-timeout checkout hotfix/payment-timeout commit id: "fix: raise timeout 10s -> 60s" checkout release/2026-10 merge hotfix/payment-timeout checkout main merge hotfix/payment-timeout commit id: "release: v2026-09.2" ``` ![Hotfix outside the release window](/assets/images/hotfix-outside-the-release-window-7eb00245563d10be62e94f35361a20f9.svg) This is the diagram your postmortem will wish it had. When the incident review asks "was the fix on the release line *and* on main?", the graph answers in one glance — no git archaeology required. ## Copy-paste 3: the branch-rule flowchart[​](#copy-paste-3-the-branch-rule-flowchart "Direct link to Copy-paste 3: the branch-rule flowchart") A gitGraph shows *what happened*; a flowchart shows *the rules* — and a diagram is how a team agrees on those rules without a doc that nobody reads. A flowchart version of your branch strategy is the shared rulebook: [flowcharts are the most-used Mermaid type in Confluence and Jira](https://marketplace.atlassian.com/apps/2658777397/mermaid-plus-diagrams-for-jira/), and they read in code review as fast as they read on a whiteboard. ``` flowchart TD %% title: Branch rules PR to merge A[PR opened] --> B{Target branch?} B -->|main| C{Scope small enough?} B -->|feature/*| D[Review + run CI] C -->|Yes| D C -->|No| E[Open an epic] E --> E2[Track sub-branches on the epic] D --> F{CI green?} F -->|Yes| G[Squash merge] F -->|No| H[Fix on the branch] H --> D G --> I[PR closed] ``` ![Branch rules PR to merge](/assets/images/branch-rules-pr-to-merge-b978b165afe0dac1534908781f00fef4.svg) Use one gitGraph per feature or release to show history, and keep this single flowchart as the shared rulebook in the space home — so "how do we branch around here?" has one canonical image. ## Keeping the graph current (not a static screenshot)[​](#keeping-the-graph-current-not-a-static-screenshot "Direct link to Keeping the graph current (not a static screenshot)") The reason these work in practice is that the diagram is *editable text living on the issue*. A Mermaid panel in [Mermaid Plus Diagrams for Jira](https://marketplace.atlassian.com/apps/2658777397/mermaid-plus-diagrams-for-jira/) behaves like a mini code editor — paste the syntax, see the live preview, save, and the rendered SVG stays on the issue. When a PR merges after the diagram is saved: 1. Open the issue → click the diagram → Edit 2. Add or edit the commit lines (there is no merge that needs re-dragging) 3. Save — the graph re-renders with the new commit in place A screenshot in an old Confluence page goes stale the moment a branch merges. A gitGraph on the issue is current whenever someone thinks to update it — which is inevitable, because the ticket is where you look first when the bug lands. ## Where this lives beside the rest of your Jira diagrams[​](#where-this-lives-beside-the-rest-of-your-jira-diagrams "Direct link to Where this lives beside the rest of your Jira diagrams") This is the branching half of the DevOps picture; the other half is the pipeline. Keep your **release schedule** on the epic as a Gantt ([release timeline in Jira](/blog/how-to-create-release-timeline-jira.md)), your **branch history** on the feature issues as a gitGraph, and your **sprint cadence** separate — sprint workflow and release history are different plots on the same calendar ([sprint to release mapping](/blog/mermaid-diagrams-jira-sprint-workflows.md)). ## FAQ[​](#faq "Direct link to FAQ") **Does Jira show git branches automatically?** Jira's development information panel lists threads and PRs connected to an issue, but it is a flat list. A Mermaid gitGraph is the topology — branches, merges, and release tags as a diagram, not a feed. **Can I render a gitGraph inside a Jira issue?** Yes — Mermaid Plus Diagrams for Jira renders `gitGraph` in the issue's Mermaid panel. Paste the syntax, preview live, save, and everyone who opens the ticket sees the graph. **How do I show a release version in a gitGraph?** Label a commit on main with the version string (`commit id: v2026-09`), or split a release branch and merge fixes in — the hotfix example above shows both. **Is a gitGraph better than a flowchart for branch strategy?** Use a gitGraph for history (what happened) and a flowchart for the rulebook (what should happen). They complement each other; the flowchart in this guide is the rulebook half. Get the full 26-diagram set — flowcharts, sequence, ER, Gantt, C4, and yes, gitGraph — in [Mermaid Plus Diagrams for Jira](https://marketplace.atlassian.com/apps/2658777397/mermaid-plus-diagrams-for-jira/), free for up to 10 users. Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [git](/blog/tags/git.md) * [gitgraph](/blog/tags/gitgraph.md) * [mermaid](/blog/tags/mermaid.md) * [branching](/blog/tags/branching.md) * [release](/blog/tags/release.md) * [how-to](/blog/tags/how-to.md) --- # Build an Incident Postmortem Timeline in Confluence (Mermaid, Copy-Paste) September 24, 2026 · 8 min read [NGPilot](https://ngpilot.com) Every incident has a story hidden inside a pile of timestamps: alert fired at 09:42, nobody acknowledged until 09:47, an engineer escalated at 09:54, a workaround landed at 10:20, services healthy at 10:31. Individually the timestamps mean nothing. Laid out on a timeline, they tell the story — and the story is what a postmortem is for. Confluence is where incident postmortems already live. What Confluence does not give you is a native timeline. This guide shows you how to fill the Timeline section of an incident postmortem with a Mermaid diagram: one copy-paste timeline that visualizes detection → escalation → resolution, plus a sequence diagram that shows exactly how the failure propagated between services. **Quick answer:** To add an incident postmortem timeline to Confluence, install [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence), create the postmortem page, and paste a Mermaid `timeline` block into the Timeline section — one `section` per phase, one `Event : Description` line per fact. For the failure path, add a `sequenceDiagram` under 'What Actually Broke'. Both examples below are copy-paste ready. A timeline written live during the incident is worth more than one reconstructed afterwards. ## Why a Timeline Is the Backbone of an Incident Doc[​](#why-a-timeline-is-the-backbone-of-an-incident-doc "Direct link to Why a Timeline Is the Backbone of an Incident Doc") An incident postmortem has one job: make the failure boring to repeat. That only works if the causal sequence is legible. A wall of timestamps in a table forces the reader to reconstruct the order themselves — and everyone reconstructs it slightly differently. A timeline makes the sequence *the structure of the paragraph*, not the byproduct of one. A good incident timeline separates two things that postmortems routinely blur: 1. **The facts** — what happened, when, to whom. This is the timeline: strictly chronological, no opinion. 2. **The analysis** — why it happened, whether it could be prevented. That lives below, after the reader has seen the sequence. When a postmortem holds those apart, the debate moves from "that's not what happened" (a fight about facts) to "what do we change" (a fight about fixes). The timeline is what makes the first fight skippable. ## The Atlassian Postmortem Template, Anatomy[​](#the-atlassian-postmortem-template-anatomy "Direct link to The Atlassian Postmortem Template, Anatomy") Atlassian ships an incident postmortem template where a Timeline section is a first-class citizen. Its anatomy, paraphrased: * **Summary** — one-line severity and impact. * **Timeline** — chronological sequence of what happened, from detection to resolution. * **Root cause** — the technical and systemic reason. * **Impact** — affected services, customers, metrics. * **Action items** — what changes to prevent recurrence. If you have used it, you have already hit the gap: the Timeline section is an empty canvas. Teams default to a table, then restructure it three times because tables hide the shape of the incident. Mermaid fills that exact section with a rendered diagram, and the syntax is simple enough that an on-call engineer can update it in a war room. ## Copy-Paste Example — Detection to Resolution[​](#copy-paste-example--detection-to-resolution "Direct link to Copy-Paste Example — Detection to Resolution") Here is a timeline for a real-shaped page-degradation incident. One `section` per phase; each line is an event with a note. Paste it, then swap the content for your own timestamps: ``` timeline title Sev-2 page degradation — 2026-09-18 section Detection P95 latency > 4s alert (Prometheus) : 09:42 On-call acknowledges : 09:47 Ack missed the 3-minute SLO : 09:47 section Escalation Declared Sev-2, war room opened : 09:54 Incident comms posted : 09:58 section Mitigation Suspected config drift in LB rule : 10:05 Candidate config removed : 10:14 Latency back to baseline : 10:20 section Resolution Declared resolved, monitoring : 10:31 Postmortem drafted from this log : 18:00 ``` ![Sev-2 page degradation — 2026-09-18](/assets/images/sev-2-page-degradation-2026-09-18-c8cf5db4e8a641534b913a426ad4cbee.svg) Three things this diagram does that a table does not: * **The shape of the incident is visible instantly** — you can see the 5-minute gap between alert and acknowledgement without scanning a column. * **The mitigation phase is where it is on the page** — plan vs. response timelines separate cleanly because each `section` renders as its own horizontal band. * **It stays cheap to update mid-incident** — adding `10:26 : Failed cache reload` is one new line and a republish. ### Anatomy of the syntax[​](#anatomy-of-the-syntax "Direct link to Anatomy of the syntax") The `timeline` keyword opens the diagram. `title` sets the label. Each `section` is a phase, and each indented two-space line under a section is `Event : Description`: | Part | Meaning | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `section Detection` | New phase band on the timeline | | `P95 latency > 4s alert (Prometheus) : 09:42` | Event with a note — the event text first, the timestamp (or short period label) after the `:`. This `event : note : period` order is what Mermaid expects; leading with a bare time breaks the parser. | | Indentation of two spaces | Nesting under the section | Keep entries short — a phrase, not a sentence. The annotation is where the detail goes. Long event labels wrap and make the timeline tall instead of scannable. ## Adding a Sequence Diagram for the Failing Request[​](#adding-a-sequence-diagram-for-the-failing-request "Direct link to Adding a Sequence Diagram for the Failing Request") A timeline answers *what happened when*. It does not answer *why the user's request got slow* — that is a data-flow question, and it deserves a sequence diagram. Alongside the timeline, a `sequenceDiagram` showing the actual failure path makes the root-cause section write itself. ``` sequenceDiagram autonumber title Provider hang — missing retry deadline participant U as User participant G as API Gateway participant B as Billing Service participant P as Payment Provider U->>G: POST /v1/charge G->>B: forward request B->>P: call provider Note over P: Provider hangs — no response P-->>B: no reply within 30s deadline B->>P: retry (still hung) B-->>G: 504 after 60s G-->>U: 504 after 65s Note over U,P: Missing deadline on retry compounded latency ``` ![Provider hang — missing retry deadline](/assets/images/provider-hang-missing-retry-deadline-99ee2571d8e52ccbcc620f7119b8218e.svg) Read it as a story: the request enters, reaches the provider, the provider hangs, and — because the retry had no deadline — the response the user got took 65 seconds instead of failing fast. That single diagram carries the *mechanism* of the incident, which the timeline's `10:05 : Suspected config drift` note can't. Keep the sequence diagram minimal — five participants max, one failure path. A sequence diagram that models the whole system is a system diagram; a postmortem wants the *failing path*. ## Keep It Current During the Incident, Not Just After[​](#keep-it-current-during-the-incident-not-just-after "Direct link to Keep It Current During the Incident, Not Just After") Most postmortem timelines fail because they were written 48 hours after the incident from memory, Slack scroll, and monitoring exports. The gaps are where blame-creep grows. Instead, treat the timeline as a **living artifact inside the war room**: 1. Create the postmortem page *at* incident declaration, not at resolution. The template gives you the Timeline section already. 2. Append one line as each event happens — detection, handoffs, escalations, mitigation attempts, failed attempts too. 3. Freeze it the moment the incident closes. Do not polish the timeline afterwards; polish the analysis, and leave the facts as they were recorded. This is a habit, not a workflow feature. But one thing makes it *possible* in a war room instead of optional: the diagram is plain text. Pasted into [Mermaid Plus](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence), it edits in the browser in seconds and re-renders on republish. No dragging shapes, no waiting for the composite draw. Where timelines record plans and schedules — release trains, sprint milestones, project phases — the Gantt chart in Mermaid is the counterpart. A postmortem is the one doc where you want *events*, not durations, which is exactly what the `timeline` diagram gives you. For the planning-side version, see the [release timeline in Jira guide](/blog/how-to-create-release-timeline-jira.md). ## Which Diagram Fills Which Section?[​](#which-diagram-fills-which-section "Direct link to Which Diagram Fills Which Section?") | Postmortem section | Diagram | Why | | ------------------- | ------------------------------- | ----------------------------------------------- | | Timeline | `timeline` | Chronological facts, phases visible at a glance | | What actually broke | `sequenceDiagram` | The failing request's path between services | | Root cause analysis | `ishikawa` fishbone / flowchart | Drill into causes after the sequence is agreed | | Impact summary | `pie` or `xychart` | Metrics over time, resource share | The timeline and the sequence diagram cover this guide's scope; the fishbone/root-cause diagrams are the natural next step once the sequence is nailed down. An incident gets a second chance only if its postmortem is unambiguous. A timeline makes the facts impossible to misread, and the sequence diagram makes the mechanism impossible to hand-wave. Install [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence), drop the two examples into your next postmortem, and let the diagram do the arguing. ## Related Guides[​](#related-guides "Direct link to Related Guides") * [How to build a release timeline in Jira](/blog/how-to-create-release-timeline-jira.md) — the Gantt counterpart: version milestones, multi-team tracks, and launch sequencing * [Mermaid diagrams for Jira sprint workflows](/blog/mermaid-diagrams-jira-sprint-workflows.md) — sprint-scale timelines and the diagram types ops teams actually use * [Create Mermaid diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md) — the full guide to all 30 diagram types on Confluence pages Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [incident](/blog/tags/incident.md) * [postmortem](/blog/tags/postmortem.md) * [timeline](/blog/tags/timeline.md) * [mermaid](/blog/tags/mermaid.md) * [confluence](/blog/tags/confluence.md) * [incident-management](/blog/tags/incident-management.md) * [how-to](/blog/tags/how-to.md) * [devops](/blog/tags/devops.md) --- # Customer Journey Maps in Confluence with Mermaid (Copy-Paste) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The support team knows where refunds leak. The product team knows where onboarding drops. The sales team knows where the pricing page confuses. Three silos, three versions of the customer's experience — and the roadmap meeting spends an hour reconciling them instead of deciding what to fix. What is missing is a single picture with a score on every step. **Quick answer:** draw customer journeys in Confluence as Mermaid `journey` diagrams, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). A journey diagram puts every step in a row and every satisfaction score on one curve — the dips are visible, the actors are labeled, and the whole thing stays editable text. This post gives you three copy-paste examples: onboarding, a support ticket, and a checkout flow with a summary pie. ## Why a journey map lands where a flowchart can't[​](#why-a-journey-map-lands-where-a-flowchart-cant "Direct link to Why a journey map lands where a flowchart can't") A flowchart says "this is how the process runs". A journey map says "this is how the customer *experiences* each step of that process" — and the difference shows where the emotional cost is. A journey diagram answers three questions at once: * **What happens?** The steps, top to bottom * **Who touches it?** The actor on each step — customer, agent, system * **How does it feel?** The 0–5 satisfaction score that draws the curve That last row is what makes journey maps uncomfortable — and useful. A 1 next to "Verification required" is a line item; two minutes in the roadmap meeting, not a debate. Score every step and the dips schedule the work. ## Copy-paste 1: the onboarding journey[​](#copy-paste-1-the-onboarding-journey "Direct link to Copy-paste 1: the onboarding journey") Start with the journey every product team claims to care about: onboarding. Three task rows keep it scannable — the score curve is the hero: ``` journey %% title: New-user onboarding journey section Sign up Find the product: 3: Prospect Create account: 4: Prospect Email verification: 2: Prospect section First value Import data: 3: Prospect First report runs: 5: Prospect Admin invites team: 4: Prospect section Solidify Config settings: 2: Prospect Upgrade offered: 3: Prospect ``` ![New-user onboarding journey](/assets/images/new-user-onboarding-journey-ed96921f8d1c1ed1a07c0345054f28bc.svg) Five, four, three, two, five — the curve reads like an ECG: the dips at `Email verification` and `Config settings` are where the trial dies. This is the diagram to pin above the onboarding analysis; every drop has a product hypothesis next to it, and the fix lands in the same sprint review. ## Copy-paste 2: the support ticket journey[​](#copy-paste-2-the-support-ticket-journey "Direct link to Copy-paste 2: the support ticket journey") Support journeys have the clearest pain points because the agent sees every spike. Rows for the channel and the agent make them true to the real split: ``` journey %% title: Support ticket lifecycle section Self-serve Search help center: 3: Customer Submit ticket: 3: Customer section Agent First response: 2: Customer Diagnosis: 4: Agent Resolution: 4: Customer Follow-up survey: 4: Agent ``` ![Support ticket lifecycle](/assets/images/support-ticket-lifecycle-f909d5ab12a670aa680c9f7f7b77d4fe.svg) The `First response: 2` dip is the SLA problem wearing a costume — the customer marks the wait, not the answer. Split rows by actor (`Customer` vs `Agent`) and the async handoff points are visible: where the score line drops at the arrow between rows, that is where ownership changes hands. ## Copy-paste 3: checkout flow with a summary pie[​](#copy-paste-3-checkout-flow-with-a-summary-pie "Direct link to Copy-paste 3: checkout flow with a summary pie") The strongest journey pages pair the journey with a pie chart. The pie answers "where does the friction live?" (total time by section); the journey answers "why does it feel bad?" (scores inside each section): ``` journey %% title: Checkout flow — main path section Cart Review cart: 4: Customer Enter promo code: 3: Customer section Details Shipping address: 2: Customer Payment form: 3: Customer section Confirm Review order: 4: Customer Place order: 5: Customer Confirmation email: 5: Customer ``` ![Checkout flow — main path](/assets/images/checkout-flow-main-path-f49274599b67e610c967e21190597013.svg) ``` pie %% title: Where checkout time goes "Enter promo code" : 12 "Shipping address" : 30 "Payment form" : 25 "Re-verify email" : 18 "Confirmation wait" : 15 ``` ![Where checkout time goes](data:image/svg+xml;base64,PHN2ZyBpZD0ibXktc3ZnIiB3aWR0aD0iMTAwJSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgdmlld0JveD0iMCAwIDY0OS45MTE2MjEwOTM3NSA0NTAiIHN0eWxlPSJtYXgtd2lkdGg6IDY0OS45MTJweDsgYmFja2dyb3VuZC1jb2xvcjogd2hpdGU7IiByb2xlPSJncmFwaGljcy1kb2N1bWVudCBkb2N1bWVudCIgYXJpYS1yb2xlZGVzY3JpcHRpb249InBpZSI+PHN0eWxlPiNteS1zdmd7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO2ZvbnQtc2l6ZToxNnB4O2ZpbGw6IzMzMzt9QGtleWZyYW1lcyBlZGdlLWFuaW1hdGlvbi1mcmFtZXtmcm9te3N0cm9rZS1kYXNob2Zmc2V0OjA7fX1Aa2V5ZnJhbWVzIGRhc2h7dG97c3Ryb2tlLWRhc2hvZmZzZXQ6MDt9fSNteS1zdmcgLmVkZ2UtYW5pbWF0aW9uLXNsb3d7c3Ryb2tlLWRhc2hhcnJheTo5LDUhaW1wb3J0YW50O3N0cm9rZS1kYXNob2Zmc2V0OjkwMDthbmltYXRpb246ZGFzaCA1MHMgbGluZWFyIGluZmluaXRlO3N0cm9rZS1saW5lY2FwOnJvdW5kO30jbXktc3ZnIC5lZGdlLWFuaW1hdGlvbi1mYXN0e3N0cm9rZS1kYXNoYXJyYXk6OSw1IWltcG9ydGFudDtzdHJva2UtZGFzaG9mZnNldDo5MDA7YW5pbWF0aW9uOmRhc2ggMjBzIGxpbmVhciBpbmZpbml0ZTtzdHJva2UtbGluZWNhcDpyb3VuZDt9I215LXN2ZyAuZXJyb3ItaWNvbntmaWxsOiM1NTIyMjI7fSNteS1zdmcgLmVycm9yLXRleHR7ZmlsbDojNTUyMjIyO3N0cm9rZTojNTUyMjIyO30jbXktc3ZnIC5lZGdlLXRoaWNrbmVzcy1ub3JtYWx7c3Ryb2tlLXdpZHRoOjFweDt9I215LXN2ZyAuZWRnZS10aGlja25lc3MtdGhpY2t7c3Ryb2tlLXdpZHRoOjMuNXB4O30jbXktc3ZnIC5lZGdlLXBhdHRlcm4tc29saWR7c3Ryb2tlLWRhc2hhcnJheTowO30jbXktc3ZnIC5lZGdlLXRoaWNrbmVzcy1pbnZpc2libGV7c3Ryb2tlLXdpZHRoOjA7ZmlsbDpub25lO30jbXktc3ZnIC5lZGdlLXBhdHRlcm4tZGFzaGVke3N0cm9rZS1kYXNoYXJyYXk6Mzt9I215LXN2ZyAuZWRnZS1wYXR0ZXJuLWRvdHRlZHtzdHJva2UtZGFzaGFycmF5OjI7fSNteS1zdmcgLm1hcmtlcntmaWxsOiMzMzMzMzM7c3Ryb2tlOiMzMzMzMzM7fSNteS1zdmcgLm1hcmtlci5jcm9zc3tzdHJva2U6IzMzMzMzMzt9I215LXN2ZyBzdmd7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO2ZvbnQtc2l6ZToxNnB4O30jbXktc3ZnIHB7bWFyZ2luOjA7fSNteS1zdmcgLnBpZUNpcmNsZXtzdHJva2U6YmxhY2s7c3Ryb2tlLXdpZHRoOjJweDtvcGFjaXR5OjAuNzt9I215LXN2ZyAucGllQ2lyY2xlLmhpZ2hsaWdodGVke3NjYWxlOjEuMDU7b3BhY2l0eToxO30jbXktc3ZnIC5waWVDaXJjbGUuaGlnaGxpZ2h0ZWRPbkhvdmVyOmhvdmVye3RyYW5zaXRpb24tZHVyYXRpb246MjUwbXM7c2NhbGU6MS4wNTtvcGFjaXR5OjE7fSNteS1zdmcgLnBpZU91dGVyQ2lyY2xle3N0cm9rZTpibGFjaztzdHJva2Utd2lkdGg6MnB4O2ZpbGw6bm9uZTt9I215LXN2ZyAucGllVGl0bGVUZXh0e3RleHQtYW5jaG9yOm1pZGRsZTtmb250LXNpemU6MjVweDtmaWxsOmJsYWNrO2ZvbnQtZmFtaWx5OiJ0cmVidWNoZXQgbXMiLHZlcmRhbmEsYXJpYWwsc2Fucy1zZXJpZjt9I215LXN2ZyAuc2xpY2V7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO2ZpbGw6IzMzMztmb250LXNpemU6MTdweDt9I215LXN2ZyAubGVnZW5kIHRleHR7ZmlsbDpibGFjaztmb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7Zm9udC1zaXplOjE3cHg7fSNteS1zdmcgLm5vZGUgLm5lby1ub2Rle3N0cm9rZTojOTM3MERCO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcmVjdCwjbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLmNsdXN0ZXIgcmVjdCwjbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcG9seWdvbntzdHJva2U6IzkzNzBEQjtmaWx0ZXI6ZHJvcC1zaGFkb3coMXB4IDJweCAycHggcmdiYSgxODUsIDE4NSwgMTg1LCAxKSk7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uc3dpbWxhbmUuY2x1c3RlciByZWN0e2ZpbHRlcjpub25lO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcGF0aHtzdHJva2U6IzkzNzBEQjtzdHJva2Utd2lkdGg6MXB4O30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgLm91dGVyLXBhdGh7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgLm5lby1saW5lIHBhdGh7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOm5vbmU7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSBjaXJjbGV7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgY2lyY2xlIC5zdGF0ZS1zdGFydHtmaWxsOiMwMDAwMDA7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uaWNvbi1zaGFwZSAuaWNvbntmaWxsOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLmljb24tc2hhcGUgLmljb24tbmVvIHBhdGh7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIDpyb290ey0tbWVybWFpZC1mb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7fTwvc3R5bGU+PGcvPjxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDIyNSwyMjUpIj48Zz48Y2lyY2xlIGN4PSIwIiBjeT0iMCIgcj0iMTg2IiBjbGFzcz0icGllT3V0ZXJDaXJjbGUiLz48cGF0aCBkPSJNMCwtMTg1QTE4NSwxODUsMCwwLDEsMTI2LjY0MSwtMTM0Ljg1OUwwLDBaIiBmaWxsPSIjRUNFQ0ZGIiBjbGFzcz0icGllQ2lyY2xlIi8+PHBhdGggZD0iTTEyNi42NDEsLTEzNC44NTlBMTg1LDE4NSwwLDAsMSw4OS4xMjQsMTYyLjExN0wwLDBaIiBmaWxsPSIjZmZmZmRlIiBjbGFzcz0icGllQ2lyY2xlIi8+PHBhdGggZD0iTTg5LjEyNCwxNjIuMTE3QTE4NSwxODUsMCwwLDEsLTE2Mi4xMTcsODkuMTI0TDAsMFoiIGZpbGw9ImhzbCg4MCwgMTAwJSwgNTYuMjc0NTA5ODAzOSUpIiBjbGFzcz0icGllQ2lyY2xlIi8+PHBhdGggZD0iTS0xNjIuMTE3LDg5LjEyNEExODUsMTg1LDAsMCwxLC0xNDkuNjY4LC0xMDguNzRMMCwwWiIgZmlsbD0iaHNsKDI0MCwgMTAwJSwgODYuMjc0NTA5ODAzOSUpIiBjbGFzcz0icGllQ2lyY2xlIi8+PHBhdGggZD0iTS0xNDkuNjY4LC0xMDguNzRBMTg1LDE4NSwwLDAsMSwwLC0xODVMMCwwWiIgZmlsbD0iaHNsKDYwLCAxMDAlLCA2My41Mjk0MTE3NjQ3JSkiIGNsYXNzPSJwaWVDaXJjbGUiLz48dGV4dCB0cmFuc2Zvcm09InRyYW5zbGF0ZSg1MS4wNzcyODE2ODQ5OTkwODYsLTEyOS4wMDY0ODc0MTY5OTQ4NykiIGNsYXNzPSJzbGljZSIgc3R5bGU9InRleHQtYW5jaG9yOiBtaWRkbGU7Ij4xMiU8L3RleHQ+PHRleHQgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMTM3LjY1NTkxNDgwNzM4MzgsMTcuMzg5OTg2MTU3MDQ3MjQpIiBjbGFzcz0ic2xpY2UiIHN0eWxlPSJ0ZXh0LWFuY2hvcjogbWlkZGxlOyI+MzAlPC90ZXh0Pjx0ZXh0IHRyYW5zZm9ybT0idHJhbnNsYXRlKC0zOC43MTAwMTU5NjI5NDMwNywxMzMuMjQwNzQ4ODg3Njc1ODYpIiBjbGFzcz0ic2xpY2UiIHN0eWxlPSJ0ZXh0LWFuY2hvcjogbWlkZGxlOyI+MjUlPC90ZXh0Pjx0ZXh0IHRyYW5zZm9ybT0idHJhbnNsYXRlKC0xMzguNDc2MjA4NTY5NDIyNjgsLTguNzEyMTg0NTg0NjkyMTY2KSIgY2xhc3M9InNsaWNlIiBzdHlsZT0idGV4dC1hbmNob3I6IG1pZGRsZTsiPjE4JTwvdGV4dD48dGV4dCB0cmFuc2Zvcm09InRyYW5zbGF0ZSgtNjIuOTkxMTgxODM4ODYyMTMsLTEyMy42MjcxNTUyMzExMzYwMykiIGNsYXNzPSJzbGljZSIgc3R5bGU9InRleHQtYW5jaG9yOiBtaWRkbGU7Ij4xNSU8L3RleHQ+PC9nPjx0ZXh0IHg9IjAiIHk9Ii0yMDAiIGNsYXNzPSJwaWVUaXRsZVRleHQiLz48ZyBjbGFzcz0ibGVnZW5kIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgyMTYsLTU1KSI+PHJlY3Qgd2lkdGg9IjE4IiBoZWlnaHQ9IjE4IiBzdHlsZT0iZmlsbDogcmdiKDIzNiwgMjM2LCAyNTUpOyBzdHJva2U6IHJnYigyMzYsIDIzNiwgMjU1KTsiLz48dGV4dCB4PSIyMiIgeT0iMTQiPkVudGVyIHByb21vIGNvZGU8L3RleHQ+PC9nPjxnIGNsYXNzPSJsZWdlbmQiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDIxNiwtMzMpIj48cmVjdCB3aWR0aD0iMTgiIGhlaWdodD0iMTgiIHN0eWxlPSJmaWxsOiByZ2IoMjU1LCAyNTUsIDIyMik7IHN0cm9rZTogcmdiKDI1NSwgMjU1LCAyMjIpOyIvPjx0ZXh0IHg9IjIyIiB5PSIxNCI+U2hpcHBpbmcgYWRkcmVzczwvdGV4dD48L2c+PGcgY2xhc3M9ImxlZ2VuZCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMjE2LC0xMSkiPjxyZWN0IHdpZHRoPSIxOCIgaGVpZ2h0PSIxOCIgc3R5bGU9ImZpbGw6IHJnYigxODEsIDI1NSwgMzIpOyBzdHJva2U6IHJnYigxODEsIDI1NSwgMzIpOyIvPjx0ZXh0IHg9IjIyIiB5PSIxNCI+UGF5bWVudCBmb3JtPC90ZXh0PjwvZz48ZyBjbGFzcz0ibGVnZW5kIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgyMTYsMTEpIj48cmVjdCB3aWR0aD0iMTgiIGhlaWdodD0iMTgiIHN0eWxlPSJmaWxsOiByZ2IoMTg1LCAxODUsIDI1NSk7IHN0cm9rZTogcmdiKDE4NSwgMTg1LCAyNTUpOyIvPjx0ZXh0IHg9IjIyIiB5PSIxNCI+UmUtdmVyaWZ5IGVtYWlsPC90ZXh0PjwvZz48ZyBjbGFzcz0ibGVnZW5kIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgyMTYsMzMpIj48cmVjdCB3aWR0aD0iMTgiIGhlaWdodD0iMTgiIHN0eWxlPSJmaWxsOiByZ2IoMjU1LCAyNTUsIDY5KTsgc3Ryb2tlOiByZ2IoMjU1LCAyNTUsIDY5KTsiLz48dGV4dCB4PSIyMiIgeT0iMTQiPkNvbmZpcm1hdGlvbiB3YWl0PC90ZXh0PjwvZz48L2c+PC9zdmc+) `Shipping address: 2` with `30` units of time in the pie is a checkout leak — a form that re-asks what the account already knows. The pair of charts makes the fix obvious and the metric measurable: shorten the address step and the score line and the pie both move. ## The journey map that stays honest[​](#the-journey-map-that-stays-honest "Direct link to The journey map that stays honest") A journey map is only as good as its refresh cycle — customer experience drifts weekly. Mermaid keeps the map honest the same way it keeps every other diagram honest: it is text. In [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), the journey is a code block with a live preview: change a score after a support blitz, re-run a section after a product release, and the rendered diagram updates in the same edit. The map near the close of a sprint reflects the sprint that just happened, not the quarter from last year. Score consistently, keep one actor naming, and refresh the dips on a cadence — the journey map becomes the one artifact that keeps product, support and sales looking at the same curve. ## Where this lives beside your other Confluence diagrams[​](#where-this-lives-beside-your-other-confluence-diagrams "Direct link to Where this lives beside your other Confluence diagrams") Journey maps cover the experience; the other diagram types cover the mechanics. Keep the journey on the product page (this post), the workflow underneath it as a state diagram ([states & approval workflows](/blog/mermaid-state-diagram-workflow-confluence.md)), and the process it runs in as a flowchart ([CI/CD pipeline diagrams](/blog/mermaid-ci-cd-pipeline-diagram-confluence.md)). One space, three diagram types, and the same text-editable honesty throughout. ## FAQ[​](#faq "Direct link to FAQ") **What is a Mermaid journey diagram in Confluence?** A timeline-style chart with task rows and a satisfaction score line — each step is a labeled bar, the score curve shows where experience dips. Mermaid Plus Diagrams & AI Agent for Confluence renders it live from text. **How do I show who is involved in each step?** Add the actor at the end of the task line ('...: 3: Customer'). Rows of the same actor make self-serve vs agent-assisted steps obvious at a glance. **What score marks a pain point?** Any step scoring 1 or below is a pain point worth scheduling; a 2 with a steep drop is one conversation away. Keep the scale consistent across journeys so curves compare. **Can a journey diagram include a summary chart?** Yes — pair it with a Mermaid pie chart of time per section. The pie answers 'where does friction live', the journey answers 'why it feels bad'. Example 3 shows the pair. Render every Mermaid diagram type — journey, pie, state, flowchart, class and 24 more — in [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), free for up to 10 users. Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [journey](/blog/tags/journey.md) * [customer-experience](/blog/tags/customer-experience.md) * [product](/blog/tags/product.md) * [how-to](/blog/tags/how-to.md) --- # Kanban Board Diagrams in Confluence with Mermaid (Copy-Paste) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The sprint board on the wall shows 40 items in "In Progress" and the rulebook says "we limit WIP" and nobody agrees on what the limit is. The board is honest; the *documentation* is aspirational. A Kanban diagram in the wiki is the board as a spec — columns, limits, and the rework paths drawn so the workflow is a claim the team can argue with. **Quick answer:** document the team's board in Confluence as a Mermaid `kanban`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Columns as headings, work items as indented cards; the workflow *rules* (who may move what, when, including rework) as a `stateDiagram` on the same page. This post gives you three copy-paste examples. ## Why a board needs a diagram spec[​](#why-a-board-needs-a-diagram-spec "Direct link to Why a board needs a diagram spec") Jira already *is* a board — the diagram earns its place when it documents the *rules* the board encodes: * **The columns are a promise.** A diagram that shows "To Do → In Progress → Done" says how the team claims work flows; the real board either agrees or exposes drift. * **The WIP limit is a number.** Written on the column, the limit becomes reviewable — the diagram is the policy the wall occasionally breaks. * **The rework path is the honesty.** Every workflow has a "back to In Progress" move; drawn, it stops the diagram from being pure happy-path fiction. The kanban draws state; the state diagram draws the law. Both are text, so both update in the retro that changes the rule. ## Copy-paste 1: the team's board as kanban[​](#copy-paste-1-the-teams-board-as-kanban "Direct link to Copy-paste 1: the team's board as kanban") Columns first, then cards indented under them. Keep it to the states the work actually visits: ``` kanban To Do Payload migration Billing webhook Rate limiter In Progress Auth refresh [owner: Maya] In Review Audit log Done Healthcheck endpoint Helm chart ``` ![Rendered Mermaid diagram](/assets/images/kanban-2c315769a6fbbe1e595940f425b83b96.svg) The diagram is the board frozen as a spec: five states, six cards, one in flight. Keep the card list short — the value is documenting *what the columns mean* and *where the work binds*, not mirroring every Jira issue. ## Copy-paste 2: the workflow's law as a state diagram[​](#copy-paste-2-the-workflows-law-as-a-state-diagram "Direct link to Copy-paste 2: the workflow's law as a state diagram") The board is the snapshot; the state diagram is the rulebook — every transition, including the ones the happy-path diagram hides: ``` stateDiagram-v2 [*] --> ToDo ToDo --> InProgress: start InProgress --> InReview: submit InReview --> InProgress: rework InReview --> Done: approved InProgress --> ToDo: unblocked InProgress --> Done: direct merge Done --> [*] ``` ![Rendered Mermaid diagram](/assets/images/statediagram-v2-20145593c5f7b8a1daffd5b2ff23eb0f.svg) Read the edges that cross "leftward": `InReview → InProgress: rework` and `InProgress → ToDo: unblocked` — the reality of a board. The state diagram makes the workflow *enforceable-looking*: reviews can check whether the drawn transitions match the configured workflow, and the WIP debate starts from a shared picture. ## Copy-paste 3: WIP limits and the review gate[​](#copy-paste-3-wip-limits-and-the-review-gate "Direct link to Copy-paste 3: WIP limits and the review gate") Put the limit in the heading and draw the gate as a decision between two states. This is the board for the stricter workflow — code review as a real gate: ``` kanban To Do (WIP 5) Card A Card B Card C In Progress (WIP 3) Card D In Review (WIP 2) Card E Done Card F ``` ![Rendered Mermaid diagram](/assets/images/kanban-2-42b76af115cba279df6974836c7aa407.svg) The WIP limit lives in the column heading, so the *policy* is visible in the diagram, not implied. This is the version to pin on the planning room wall and the wiki's team page — it documents the limits the board is supposed to enforce. ## Board and rulebook on one page[​](#board-and-rulebook-on-one-page "Direct link to Board and rulebook on one page") The pair works like requirements and their coverage: * **Kanban = the snapshot.** What sits where, right now, labelled by owner. * **State diagram = the transitions.** Which moves are allowed, in both directions, with their guards. Keep both next to the sprint workflow guide and the **delivery timeline** of the same work, and update them in the retro that changes a limit. A board's rulebook belongs to the whole team; text in Confluence is how it stays owned. The workflow diagrams' siblings are on the wiki: the **quarter schedule** of the same work as a [Gantt roadmap](/blog/mermaid-roadmap-prioritization-charts-confluence.md) and the **process handoffs** between the team and others as [swimlanes](/blog/mermaid-process-flow-swimlane-diagram-confluence.md). ## FAQ[​](#faq "Direct link to FAQ") **Does Confluence have a built-in Kanban diagram tool?** No — Confluence has no native board diagramming. Mermaid Plus Diagrams & AI Agent for Confluence renders `kanban` and `stateDiagram-v2` from editable text with a live preview. **Kanban diagram or state diagram for a workflow?** Kanban for the board snapshot (columns + cards + WIP); state diagram for the transition rules (guards + rework paths). Keep both; the board is now, the state diagram is the law. **How do I show a WIP limit in a Mermaid Kanban?** Write it into the column heading — `In Progress (WIP 3)` — so the limit is part of the diagram's visible spec. **How do I draw rework in a workflow diagram?** Add the reverse transition explicitly (`InReview --> InProgress`) as a state-diagram edge. The drawn rework path is what keeps the diagram honest. Render every Mermaid diagram type — kanban, state, gantt, flowchart, swimlane and 24 more — in [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), free for up to 10 users. Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [kanban](/blog/tags/kanban.md) * [workflow](/blog/tags/workflow.md) * [state-diagram](/blog/tags/state-diagram.md) * [agile](/blog/tags/agile.md) * [how-to](/blog/tags/how-to.md) --- # Mind Maps & Hierarchy Diagrams in Confluence with Mermaid (Copy-Paste) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The kickoff note is 40 lines of indented bullets with three levels of bolded sub-points, and half the room is still asking "so what are we actually deciding today?" The other half is screenshotting a mind map someone whiteboarded in five minutes. The whiteboard died at cleanup; the bullets survived but nobody can navigate them. A mind map is the *readable* version of nested notes — and when it lives in Confluence as Mermaid text, it survives the meeting. **Quick answer:** turn nested notes into a Mermaid `mindmap` in Confluence, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). The indented text you already write becomes the branches; for concrete structures — folder layouts, project trees — use `treeView`; when item size matters and you want area instead of lines, use `treemap`. This post gives you three copy-paste examples. ## Why hierarchy needs a map, not nesting[​](#why-hierarchy-needs-a-map-not-nesting "Direct link to Why hierarchy needs a map, not nesting") Nested bullets encode hierarchy, but reading them *is* work: each level means re-indenting half a line and guessing which parent a sub-point belongs to. A hierarchy diagram removes the guesswork: * **The root shows the question.** One center node (or one root line) names what the whole tree is about — the map's thesis in a word. * **Branch depth is visible.** A fifth-level branch reads as a distraction at a glance, so maps self-report when they are too deep. * **It renders where it is read.** The macro caches SVG at save, so meeting attendees see a fast image and the note-taker edits the indented text. The winning property of a Mermaid map is that the *source is a list*: you can generate it from the bullets you already wrote, and editing means moving an indented line — not repositioning boxes in a canvas. ## Copy-paste 1: brainstorm as a mindmap[​](#copy-paste-1-brainstorm-as-a-mindmap "Direct link to Copy-paste 1: brainstorm as a mindmap") The meeting's output as a radial map. Indentation *is* the hierarchy — root, then branches, then leaves: ``` mindmap root((Q3 Go-to-market)) Positioning Target segment Message Pricing tier Channels Atlassian Marketplace Community posts Webinars Assets Landing page Docs update Case study Launch Date Owner list Rollout ``` ![Rendered Mermaid diagram](/assets/images/mindmap-1af81b779fa4575ad3e920a4ce929e53.svg) The root node names the decision ("Q3 go-to-market"), the four branches are the workstreams, and the leaves are the concrete items — the same content as 40 lines of bullets, but navigable in one glance. Add owner names as leaf labels ("Launch → Owner list") and the map doubles as a RACI chart. ## Copy-paste 2: a concrete structure as a treeView[​](#copy-paste-2-a-concrete-structure-as-a-treeview "Direct link to Copy-paste 2: a concrete structure as a treeView") When the hierarchy is a *real* thing — a repo, a folder, a doc tree — `treeView` draws it as rooted lines that read like a directory listing: ``` treeView-beta "order-platform" "src" "api" "routes.ts" "handlers.ts" "domain" "order.ts" "payment.ts" "test" "order.test.ts" "docs" "schema.md" "architecture.md" ``` ![Rendered Mermaid diagram](data:image/svg+xml;base64,PHN2ZyBpZD0ibXktc3ZnIiB3aWR0aD0iMTAwJSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgdmlld0JveD0iLTAuNSAwIDE3Mi4wMzEyNSA0MDYiIHN0eWxlPSJtYXgtd2lkdGg6IDE3Mi4wMzFweDsgYmFja2dyb3VuZC1jb2xvcjogd2hpdGU7IiByb2xlPSJncmFwaGljcy1kb2N1bWVudCBkb2N1bWVudCIgYXJpYS1yb2xlZGVzY3JpcHRpb249InRyZWVWaWV3Ij48c3R5bGU+I215LXN2Z3tmb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7Zm9udC1zaXplOjE2cHg7ZmlsbDojMzMzO31Aa2V5ZnJhbWVzIGVkZ2UtYW5pbWF0aW9uLWZyYW1le2Zyb217c3Ryb2tlLWRhc2hvZmZzZXQ6MDt9fUBrZXlmcmFtZXMgZGFzaHt0b3tzdHJva2UtZGFzaG9mZnNldDowO319I215LXN2ZyAuZWRnZS1hbmltYXRpb24tc2xvd3tzdHJva2UtZGFzaGFycmF5OjksNSFpbXBvcnRhbnQ7c3Ryb2tlLWRhc2hvZmZzZXQ6OTAwO2FuaW1hdGlvbjpkYXNoIDUwcyBsaW5lYXIgaW5maW5pdGU7c3Ryb2tlLWxpbmVjYXA6cm91bmQ7fSNteS1zdmcgLmVkZ2UtYW5pbWF0aW9uLWZhc3R7c3Ryb2tlLWRhc2hhcnJheTo5LDUhaW1wb3J0YW50O3N0cm9rZS1kYXNob2Zmc2V0OjkwMDthbmltYXRpb246ZGFzaCAyMHMgbGluZWFyIGluZmluaXRlO3N0cm9rZS1saW5lY2FwOnJvdW5kO30jbXktc3ZnIC5lcnJvci1pY29ue2ZpbGw6IzU1MjIyMjt9I215LXN2ZyAuZXJyb3ItdGV4dHtmaWxsOiM1NTIyMjI7c3Ryb2tlOiM1NTIyMjI7fSNteS1zdmcgLmVkZ2UtdGhpY2tuZXNzLW5vcm1hbHtzdHJva2Utd2lkdGg6MXB4O30jbXktc3ZnIC5lZGdlLXRoaWNrbmVzcy10aGlja3tzdHJva2Utd2lkdGg6My41cHg7fSNteS1zdmcgLmVkZ2UtcGF0dGVybi1zb2xpZHtzdHJva2UtZGFzaGFycmF5OjA7fSNteS1zdmcgLmVkZ2UtdGhpY2tuZXNzLWludmlzaWJsZXtzdHJva2Utd2lkdGg6MDtmaWxsOm5vbmU7fSNteS1zdmcgLmVkZ2UtcGF0dGVybi1kYXNoZWR7c3Ryb2tlLWRhc2hhcnJheTozO30jbXktc3ZnIC5lZGdlLXBhdHRlcm4tZG90dGVke3N0cm9rZS1kYXNoYXJyYXk6Mjt9I215LXN2ZyAubWFya2Vye2ZpbGw6IzMzMzMzMztzdHJva2U6IzMzMzMzMzt9I215LXN2ZyAubWFya2VyLmNyb3Nze3N0cm9rZTojMzMzMzMzO30jbXktc3ZnIHN2Z3tmb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7Zm9udC1zaXplOjE2cHg7fSNteS1zdmcgcHttYXJnaW46MDt9I215LXN2ZyAudHJlZVZpZXctbm9kZS1sYWJlbHtmb250LXNpemU6MTZweDtmaWxsOmJsYWNrO3doaXRlLXNwYWNlOnByZTt9I215LXN2ZyAudHJlZVZpZXctbm9kZS1kaXJ7Zm9udC13ZWlnaHQ6Ym9sZDt9I215LXN2ZyAudHJlZVZpZXctbm9kZS1saW5le3N0cm9rZTpibGFjazt9I215LXN2ZyAudHJlZVZpZXctbm9kZS1pY29ue2NvbG9yOiM1NDZlN2E7fSNteS1zdmcgLnRyZWVWaWV3LW5vZGUtZGVzY3JpcHRpb257Zm9udC1zaXplOjE2cHg7ZmlsbDojNmE5OTU1O2ZvbnQtc3R5bGU6aXRhbGljO3doaXRlLXNwYWNlOnByZTt9I215LXN2ZyAudHJlZVZpZXctaGlnaGxpZ2h0LWJne2ZpbGw6cmdiYSgyNTUsIDE5MywgNywgMC4xNSk7c3Ryb2tlOiNmZmMxMDc7c3Ryb2tlLXdpZHRoOjE7fSNteS1zdmcgLm5vZGUgLm5lby1ub2Rle3N0cm9rZTojOTM3MERCO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcmVjdCwjbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLmNsdXN0ZXIgcmVjdCwjbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcG9seWdvbntzdHJva2U6IzkzNzBEQjtmaWx0ZXI6ZHJvcC1zaGFkb3coMXB4IDJweCAycHggcmdiYSgxODUsIDE4NSwgMTg1LCAxKSk7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uc3dpbWxhbmUuY2x1c3RlciByZWN0e2ZpbHRlcjpub25lO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcGF0aHtzdHJva2U6IzkzNzBEQjtzdHJva2Utd2lkdGg6MXB4O30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgLm91dGVyLXBhdGh7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgLm5lby1saW5lIHBhdGh7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOm5vbmU7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSBjaXJjbGV7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgY2lyY2xlIC5zdGF0ZS1zdGFydHtmaWxsOiMwMDAwMDA7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uaWNvbi1zaGFwZSAuaWNvbntmaWxsOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLmljb24tc2hhcGUgLmljb24tbmVvIHBhdGh7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIDpyb290ey0tbWVybWFpZC1mb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7fTwvc3R5bGU+PGcvPjxnIGNsYXNzPSJ0cmVlLXZpZXciPjxnPjx0ZXh0IGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxhYmVsIHRyZWVWaWV3LW5vZGUtZGlyIiB4PSI1IiB5PSIxNC41Ij4vPC90ZXh0PjwvZz48bGluZSB4MT0iLTEwIiB5MT0iMTQuNSIgeDI9IjAiIHkyPSIxNC41IiBzdHJva2Utd2lkdGg9IjEiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxpbmUiLz48Zz48dGV4dCBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiBjbGFzcz0idHJlZVZpZXctbm9kZS1sYWJlbCIgeD0iMjAiIHk9IjQzLjUiPm9yZGVyLXBsYXRmb3JtPC90ZXh0PjwvZz48bGluZSB4MT0iNSIgeTE9IjQzLjUiIHgyPSIxNSIgeTI9IjQzLjUiIHN0cm9rZS13aWR0aD0iMSIgY2xhc3M9InRyZWVWaWV3LW5vZGUtbGluZSIvPjxnPjx0ZXh0IGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxhYmVsIiB4PSIzNSIgeT0iNzIuNSI+c3JjPC90ZXh0PjwvZz48bGluZSB4MT0iMjAiIHkxPSI3Mi41IiB4Mj0iMzAiIHkyPSI3Mi41IiBzdHJva2Utd2lkdGg9IjEiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxpbmUiLz48Zz48dGV4dCBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiBjbGFzcz0idHJlZVZpZXctbm9kZS1sYWJlbCIgeD0iNTAiIHk9IjEwMS41Ij5hcGk8L3RleHQ+PC9nPjxsaW5lIHgxPSIzNSIgeTE9IjEwMS41IiB4Mj0iNDUiIHkyPSIxMDEuNSIgc3Ryb2tlLXdpZHRoPSIxIiBjbGFzcz0idHJlZVZpZXctbm9kZS1saW5lIi8+PGc+PHRleHQgZG9taW5hbnQtYmFzZWxpbmU9Im1pZGRsZSIgY2xhc3M9InRyZWVWaWV3LW5vZGUtbGFiZWwiIHg9IjY1IiB5PSIxMzAuNSI+cm91dGVzLnRzPC90ZXh0PjwvZz48bGluZSB4MT0iNTAiIHkxPSIxMzAuNSIgeDI9IjYwIiB5Mj0iMTMwLjUiIHN0cm9rZS13aWR0aD0iMSIgY2xhc3M9InRyZWVWaWV3LW5vZGUtbGluZSIvPjxnPjx0ZXh0IGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxhYmVsIiB4PSI2NSIgeT0iMTU5LjUiPmhhbmRsZXJzLnRzPC90ZXh0PjwvZz48bGluZSB4MT0iNTAiIHkxPSIxNTkuNSIgeDI9IjYwIiB5Mj0iMTU5LjUiIHN0cm9rZS13aWR0aD0iMSIgY2xhc3M9InRyZWVWaWV3LW5vZGUtbGluZSIvPjxsaW5lIHgxPSI1MCIgeTE9IjExNiIgeDI9IjUwIiB5Mj0iMTYwIiBzdHJva2Utd2lkdGg9IjEiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxpbmUiLz48Zz48dGV4dCBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiBjbGFzcz0idHJlZVZpZXctbm9kZS1sYWJlbCIgeD0iNTAiIHk9IjE4OC41Ij5kb21haW48L3RleHQ+PC9nPjxsaW5lIHgxPSIzNSIgeTE9IjE4OC41IiB4Mj0iNDUiIHkyPSIxODguNSIgc3Ryb2tlLXdpZHRoPSIxIiBjbGFzcz0idHJlZVZpZXctbm9kZS1saW5lIi8+PGc+PHRleHQgZG9taW5hbnQtYmFzZWxpbmU9Im1pZGRsZSIgY2xhc3M9InRyZWVWaWV3LW5vZGUtbGFiZWwiIHg9IjY1IiB5PSIyMTcuNSI+b3JkZXIudHM8L3RleHQ+PC9nPjxsaW5lIHgxPSI1MCIgeTE9IjIxNy41IiB4Mj0iNjAiIHkyPSIyMTcuNSIgc3Ryb2tlLXdpZHRoPSIxIiBjbGFzcz0idHJlZVZpZXctbm9kZS1saW5lIi8+PGc+PHRleHQgZG9taW5hbnQtYmFzZWxpbmU9Im1pZGRsZSIgY2xhc3M9InRyZWVWaWV3LW5vZGUtbGFiZWwiIHg9IjY1IiB5PSIyNDYuNSI+cGF5bWVudC50czwvdGV4dD48L2c+PGxpbmUgeDE9IjUwIiB5MT0iMjQ2LjUiIHgyPSI2MCIgeTI9IjI0Ni41IiBzdHJva2Utd2lkdGg9IjEiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxpbmUiLz48bGluZSB4MT0iNTAiIHkxPSIyMDMiIHgyPSI1MCIgeTI9IjI0NyIgc3Ryb2tlLXdpZHRoPSIxIiBjbGFzcz0idHJlZVZpZXctbm9kZS1saW5lIi8+PGxpbmUgeDE9IjM1IiB5MT0iODciIHgyPSIzNSIgeTI9IjE4OSIgc3Ryb2tlLXdpZHRoPSIxIiBjbGFzcz0idHJlZVZpZXctbm9kZS1saW5lIi8+PGc+PHRleHQgZG9taW5hbnQtYmFzZWxpbmU9Im1pZGRsZSIgY2xhc3M9InRyZWVWaWV3LW5vZGUtbGFiZWwiIHg9IjM1IiB5PSIyNzUuNSI+dGVzdDwvdGV4dD48L2c+PGxpbmUgeDE9IjIwIiB5MT0iMjc1LjUiIHgyPSIzMCIgeTI9IjI3NS41IiBzdHJva2Utd2lkdGg9IjEiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxpbmUiLz48Zz48dGV4dCBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiBjbGFzcz0idHJlZVZpZXctbm9kZS1sYWJlbCIgeD0iNTAiIHk9IjMwNC41Ij5vcmRlci50ZXN0LnRzPC90ZXh0PjwvZz48bGluZSB4MT0iMzUiIHkxPSIzMDQuNSIgeDI9IjQ1IiB5Mj0iMzA0LjUiIHN0cm9rZS13aWR0aD0iMSIgY2xhc3M9InRyZWVWaWV3LW5vZGUtbGluZSIvPjxsaW5lIHgxPSIzNSIgeTE9IjI5MCIgeDI9IjM1IiB5Mj0iMzA1IiBzdHJva2Utd2lkdGg9IjEiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxpbmUiLz48Zz48dGV4dCBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiBjbGFzcz0idHJlZVZpZXctbm9kZS1sYWJlbCIgeD0iMzUiIHk9IjMzMy41Ij5kb2NzPC90ZXh0PjwvZz48bGluZSB4MT0iMjAiIHkxPSIzMzMuNSIgeDI9IjMwIiB5Mj0iMzMzLjUiIHN0cm9rZS13aWR0aD0iMSIgY2xhc3M9InRyZWVWaWV3LW5vZGUtbGluZSIvPjxnPjx0ZXh0IGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxhYmVsIiB4PSI1MCIgeT0iMzYyLjUiPnNjaGVtYS5tZDwvdGV4dD48L2c+PGxpbmUgeDE9IjM1IiB5MT0iMzYyLjUiIHgyPSI0NSIgeTI9IjM2Mi41IiBzdHJva2Utd2lkdGg9IjEiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxpbmUiLz48Zz48dGV4dCBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiBjbGFzcz0idHJlZVZpZXctbm9kZS1sYWJlbCIgeD0iNTAiIHk9IjM5MS41Ij5hcmNoaXRlY3R1cmUubWQ8L3RleHQ+PC9nPjxsaW5lIHgxPSIzNSIgeTE9IjM5MS41IiB4Mj0iNDUiIHkyPSIzOTEuNSIgc3Ryb2tlLXdpZHRoPSIxIiBjbGFzcz0idHJlZVZpZXctbm9kZS1saW5lIi8+PGxpbmUgeDE9IjM1IiB5MT0iMzQ4IiB4Mj0iMzUiIHkyPSIzOTIiIHN0cm9rZS13aWR0aD0iMSIgY2xhc3M9InRyZWVWaWV3LW5vZGUtbGluZSIvPjxsaW5lIHgxPSIyMCIgeTE9IjU4IiB4Mj0iMjAiIHkyPSIzMzQiIHN0cm9rZS13aWR0aD0iMSIgY2xhc3M9InRyZWVWaWV3LW5vZGUtbGluZSIvPjxsaW5lIHgxPSI1IiB5MT0iMjkiIHgyPSI1IiB5Mj0iNDQiIHN0cm9rZS13aWR0aD0iMSIgY2xhc3M9InRyZWVWaWV3LW5vZGUtbGluZSIvPjwvZz48L3N2Zz4=) Mindmap's radial layout is wrong for a repo — you want the tree hanging off one root, exactly like a `tree` command. Keep the treeView beside the repo README in Confluence, updated whenever a directory moves, so onboarding and PR comments reference the same structure. ## Copy-paste 3: where size matters — treemap[​](#copy-paste-3-where-size-matters--treemap "Direct link to Copy-paste 3: where size matters — treemap") When each item's *magnitude* is part of the message, treemap trades lines for area: bigger value, bigger block. Use it for allocation, spend, effort distribution: ``` treemap "Budget" "Infra" : 35 "Engineering" : 40 "Marketing" : 15 "Support" : 10 ``` ![Rendered Mermaid diagram](data:image/svg+xml;base64,PHN2ZyBpZD0ibXktc3ZnIiB3aWR0aD0iMTAwJSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgdmlld0JveD0iMiAyNyA5OTYgMzcxIiBzdHlsZT0ibWF4LXdpZHRoOiA5OTZweDsgYmFja2dyb3VuZC1jb2xvcjogd2hpdGU7IiBjbGFzcz0iZmxvd2NoYXJ0IiByb2xlPSJncmFwaGljcy1kb2N1bWVudCBkb2N1bWVudCIgYXJpYS1yb2xlZGVzY3JpcHRpb249InRyZWVtYXAiPjxzdHlsZT4jbXktc3Zne2ZvbnQtZmFtaWx5OiJ0cmVidWNoZXQgbXMiLHZlcmRhbmEsYXJpYWwsc2Fucy1zZXJpZjtmb250LXNpemU6MTZweDtmaWxsOiMzMzM7fUBrZXlmcmFtZXMgZWRnZS1hbmltYXRpb24tZnJhbWV7ZnJvbXtzdHJva2UtZGFzaG9mZnNldDowO319QGtleWZyYW1lcyBkYXNoe3Rve3N0cm9rZS1kYXNob2Zmc2V0OjA7fX0jbXktc3ZnIC5lZGdlLWFuaW1hdGlvbi1zbG93e3N0cm9rZS1kYXNoYXJyYXk6OSw1IWltcG9ydGFudDtzdHJva2UtZGFzaG9mZnNldDo5MDA7YW5pbWF0aW9uOmRhc2ggNTBzIGxpbmVhciBpbmZpbml0ZTtzdHJva2UtbGluZWNhcDpyb3VuZDt9I215LXN2ZyAuZWRnZS1hbmltYXRpb24tZmFzdHtzdHJva2UtZGFzaGFycmF5OjksNSFpbXBvcnRhbnQ7c3Ryb2tlLWRhc2hvZmZzZXQ6OTAwO2FuaW1hdGlvbjpkYXNoIDIwcyBsaW5lYXIgaW5maW5pdGU7c3Ryb2tlLWxpbmVjYXA6cm91bmQ7fSNteS1zdmcgLmVycm9yLWljb257ZmlsbDojNTUyMjIyO30jbXktc3ZnIC5lcnJvci10ZXh0e2ZpbGw6IzU1MjIyMjtzdHJva2U6IzU1MjIyMjt9I215LXN2ZyAuZWRnZS10aGlja25lc3Mtbm9ybWFse3N0cm9rZS13aWR0aDoxcHg7fSNteS1zdmcgLmVkZ2UtdGhpY2tuZXNzLXRoaWNre3N0cm9rZS13aWR0aDozLjVweDt9I215LXN2ZyAuZWRnZS1wYXR0ZXJuLXNvbGlke3N0cm9rZS1kYXNoYXJyYXk6MDt9I215LXN2ZyAuZWRnZS10aGlja25lc3MtaW52aXNpYmxle3N0cm9rZS13aWR0aDowO2ZpbGw6bm9uZTt9I215LXN2ZyAuZWRnZS1wYXR0ZXJuLWRhc2hlZHtzdHJva2UtZGFzaGFycmF5OjM7fSNteS1zdmcgLmVkZ2UtcGF0dGVybi1kb3R0ZWR7c3Ryb2tlLWRhc2hhcnJheToyO30jbXktc3ZnIC5tYXJrZXJ7ZmlsbDojMzMzMzMzO3N0cm9rZTojMzMzMzMzO30jbXktc3ZnIC5tYXJrZXIuY3Jvc3N7c3Ryb2tlOiMzMzMzMzM7fSNteS1zdmcgc3Zne2ZvbnQtZmFtaWx5OiJ0cmVidWNoZXQgbXMiLHZlcmRhbmEsYXJpYWwsc2Fucy1zZXJpZjtmb250LXNpemU6MTZweDt9I215LXN2ZyBwe21hcmdpbjowO30jbXktc3ZnIC50cmVlbWFwTm9kZS5zZWN0aW9ue3N0cm9rZTpibGFjaztzdHJva2Utd2lkdGg6MTtmaWxsOiNlZmVmZWY7fSNteS1zdmcgLnRyZWVtYXBOb2RlLmxlYWZ7c3Ryb2tlOmJsYWNrO3N0cm9rZS13aWR0aDoxO2ZpbGw6I2VmZWZlZjt9I215LXN2ZyAudHJlZW1hcExhYmVse2ZpbGw6IzMzMztmb250LXNpemU6MTJweDt9I215LXN2ZyAudHJlZW1hcFZhbHVle2ZpbGw6IzMzMztmb250LXNpemU6MTBweDt9I215LXN2ZyAudHJlZW1hcFRpdGxle2ZpbGw6IzMzMztmb250LXNpemU6MTRweDt9I215LXN2ZyAubm9kZSAubmVvLW5vZGV7c3Ryb2tlOiM5MzcwREI7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSByZWN0LCNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uY2x1c3RlciByZWN0LCNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSBwb2x5Z29ue3N0cm9rZTojOTM3MERCO2ZpbHRlcjpkcm9wLXNoYWRvdygxcHggMnB4IDJweCByZ2JhKDE4NSwgMTg1LCAxODUsIDEpKTt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5zd2ltbGFuZS5jbHVzdGVyIHJlY3R7ZmlsdGVyOm5vbmU7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSBwYXRoe3N0cm9rZTojOTM3MERCO3N0cm9rZS13aWR0aDoxcHg7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSAub3V0ZXItcGF0aHtmaWx0ZXI6ZHJvcC1zaGFkb3coMXB4IDJweCAycHggcmdiYSgxODUsIDE4NSwgMTg1LCAxKSk7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSAubmVvLWxpbmUgcGF0aHtzdHJva2U6IzkzNzBEQjtmaWx0ZXI6bm9uZTt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIGNpcmNsZXtzdHJva2U6IzkzNzBEQjtmaWx0ZXI6ZHJvcC1zaGFkb3coMXB4IDJweCAycHggcmdiYSgxODUsIDE4NSwgMTg1LCAxKSk7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSBjaXJjbGUgLnN0YXRlLXN0YXJ0e2ZpbGw6IzAwMDAwMDt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5pY29uLXNoYXBlIC5pY29ue2ZpbGw6IzkzNzBEQjtmaWx0ZXI6ZHJvcC1zaGFkb3coMXB4IDJweCAycHggcmdiYSgxODUsIDE4NSwgMTg1LCAxKSk7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uaWNvbi1zaGFwZSAuaWNvbi1uZW8gcGF0aHtzdHJva2U6IzkzNzBEQjtmaWx0ZXI6ZHJvcC1zaGFkb3coMXB4IDJweCAycHggcmdiYSgxODUsIDE4NSwgMTg1LCAxKSk7fSNteS1zdmcgOnJvb3R7LS1tZXJtYWlkLWZvbnQtZmFtaWx5OiJ0cmVidWNoZXQgbXMiLHZlcmRhbmEsYXJpYWwsc2Fucy1zZXJpZjt9PC9zdHlsZT48Zy8+PGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMCwgMCkiIGNsYXNzPSJ0cmVlbWFwQ29udGFpbmVyIj48ZyBjbGFzcz0idHJlZW1hcFNlY3Rpb24iIHRyYW5zZm9ybT0idHJhbnNsYXRlKDAsMCkiPjxyZWN0IHdpZHRoPSIxMDAwIiBoZWlnaHQ9IjI1IiBjbGFzcz0idHJlZW1hcFNlY3Rpb25IZWFkZXIiIGZpbGw9Im5vbmUiIGZpbGwtb3BhY2l0eT0iMC42IiBzdHJva2Utd2lkdGg9IjAuNiIgc3R5bGU9ImRpc3BsYXk6IG5vbmU7Ii8+PGNsaXBQYXRoIGlkPSJjbGlwLXNlY3Rpb24tbXktc3ZnLTAiPjxyZWN0IHdpZHRoPSI5ODgiIGhlaWdodD0iMjUiLz48L2NsaXBQYXRoPjxyZWN0IHdpZHRoPSIxMDAwIiBoZWlnaHQ9IjQwMCIgY2xhc3M9InRyZWVtYXBTZWN0aW9uIHNlY3Rpb24wIiBmaWxsPSJ0cmFuc3BhcmVudCIgZmlsbC1vcGFjaXR5PSIwLjYiIHN0cm9rZT0idHJhbnNwYXJlbnQiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLW9wYWNpdHk9IjAuNCIgc3R5bGU9ImRpc3BsYXk6IG5vbmU7Ii8+PHRleHQgY2xhc3M9InRyZWVtYXBTZWN0aW9uTGFiZWwiIHg9IjYiIHk9IjEyLjUiIGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiIGZvbnQtd2VpZ2h0PSJib2xkIiBjbGlwLXBhdGg9InVybCgjY2xpcC1zZWN0aW9uLW15LXN2Zy0wKSIgc3R5bGU9ImRpc3BsYXk6IG5vbmU7Ii8+PHRleHQgY2xhc3M9InRyZWVtYXBTZWN0aW9uVmFsdWUiIHg9Ijk5MCIgeT0iMTIuNSIgdGV4dC1hbmNob3I9ImVuZCIgZG9taW5hbnQtYmFzZWxpbmU9Im1pZGRsZSIgZm9udC1zdHlsZT0iaXRhbGljIiBzdHlsZT0iZGlzcGxheTogbm9uZTsiPjEwMDwvdGV4dD48L2c+PGcgY2xhc3M9InRyZWVtYXBTZWN0aW9uIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMCwzNSkiPjxyZWN0IHdpZHRoPSI5ODAiIGhlaWdodD0iMjUiIGNsYXNzPSJ0cmVlbWFwU2VjdGlvbkhlYWRlciIgZmlsbD0ibm9uZSIgZmlsbC1vcGFjaXR5PSIwLjYiIHN0cm9rZS13aWR0aD0iMC42IiBzdHlsZT0iIi8+PGNsaXBQYXRoIGlkPSJjbGlwLXNlY3Rpb24tbXktc3ZnLTEiPjxyZWN0IHdpZHRoPSI5NjgiIGhlaWdodD0iMjUiLz48L2NsaXBQYXRoPjxyZWN0IHdpZHRoPSI5ODAiIGhlaWdodD0iMzU1IiBjbGFzcz0idHJlZW1hcFNlY3Rpb24gc2VjdGlvbjEiIGZpbGw9ImhzbCgyNDAsIDEwMCUsIDc2LjI3NDUwOTgwMzklKSIgZmlsbC1vcGFjaXR5PSIwLjYiIHN0cm9rZT0iaHNsKDI0MCwgMTAwJSwgNjEuMjc0NTA5ODAzOSUpIiBzdHJva2Utd2lkdGg9IjIiIHN0cm9rZS1vcGFjaXR5PSIwLjQiIHN0eWxlPSI7Ii8+PHRleHQgY2xhc3M9InRyZWVtYXBTZWN0aW9uTGFiZWwiIHg9IjYiIHk9IjEyLjUiIGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiIGZvbnQtd2VpZ2h0PSJib2xkIiBjbGlwLXBhdGg9InVybCgjY2xpcC1zZWN0aW9uLW15LXN2Zy0xKSIgc3R5bGU9ImRvbWluYW50LWJhc2VsaW5lOiBtaWRkbGU7IGZvbnQtc2l6ZTogMTJweDsgZmlsbDojZmZmZmZmOyB3aGl0ZS1zcGFjZTogbm93cmFwOyBvdmVyZmxvdzogaGlkZGVuOyB0ZXh0LW92ZXJmbG93OiBlbGxpcHNpczsiPkJ1ZGdldDwvdGV4dD48dGV4dCBjbGFzcz0idHJlZW1hcFNlY3Rpb25WYWx1ZSIgeD0iOTcwIiB5PSIxMi41IiB0ZXh0LWFuY2hvcj0iZW5kIiBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiBmb250LXN0eWxlPSJpdGFsaWMiIHN0eWxlPSJ0ZXh0LWFuY2hvcjogZW5kOyBkb21pbmFudC1iYXNlbGluZTogbWlkZGxlOyBmb250LXNpemU6IDEwcHg7IGZpbGw6I2ZmZmZmZjsgd2hpdGUtc3BhY2U6IG5vd3JhcDsgb3ZlcmZsb3c6IGhpZGRlbjsgdGV4dC1vdmVyZmxvdzogZWxsaXBzaXM7Ij4xMDA8L3RleHQ+PC9nPjxnIGNsYXNzPSJ0cmVlbWFwTm9kZSB0cmVlbWFwTGVhZkdyb3VwIGxlYWYweCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMjAsNzApIj48cmVjdCB3aWR0aD0iMzc4IiBoZWlnaHQ9IjMxMCIgY2xhc3M9InRyZWVtYXBMZWFmIiBmaWxsPSJoc2woMjQwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSkiIHN0eWxlPSIiIGZpbGwtb3BhY2l0eT0iMC4zIiBzdHJva2U9ImhzbCgyNDAsIDEwMCUsIDc2LjI3NDUwOTgwMzklKSIgc3Ryb2tlLXdpZHRoPSIzIi8+PGNsaXBQYXRoIGlkPSJjbGlwLW15LXN2Zy0wIj48cmVjdCB3aWR0aD0iMzc0IiBoZWlnaHQ9IjMwNiIvPjwvY2xpcFBhdGg+PHRleHQgY2xhc3M9InRyZWVtYXBMYWJlbCIgeD0iMTg5IiB5PSIxNTUiIHN0eWxlPSJ0ZXh0LWFuY2hvcjogbWlkZGxlOyBkb21pbmFudC1iYXNlbGluZTogbWlkZGxlOyBmb250LXNpemU6IDM4cHg7ZmlsbDpibGFjazsiIGNsaXAtcGF0aD0idXJsKCNjbGlwLW15LXN2Zy0wKSI+RW5naW5lZXJpbmc8L3RleHQ+PHRleHQgY2xhc3M9InRyZWVtYXBWYWx1ZSIgeD0iMTg5IiB5PSIxNzYiIHN0eWxlPSJ0ZXh0LWFuY2hvcjogbWlkZGxlOyBkb21pbmFudC1iYXNlbGluZTogaGFuZ2luZzsgZm9udC1zaXplOiAyM3B4OyBmaWxsOiBibGFjazsiIGNsaXAtcGF0aD0idXJsKCNjbGlwLW15LXN2Zy0wKSI+NDA8L3RleHQ+PC9nPjxnIGNsYXNzPSJ0cmVlbWFwTm9kZSB0cmVlbWFwTGVhZkdyb3VwIGxlYWYxeCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNDA4LDcwKSI+PHJlY3Qgd2lkdGg9IjMzMCIgaGVpZ2h0PSIzMTAiIGNsYXNzPSJ0cmVlbWFwTGVhZiIgZmlsbD0iaHNsKDI0MCwgMTAwJSwgNzYuMjc0NTA5ODAzOSUpIiBzdHlsZT0iIiBmaWxsLW9wYWNpdHk9IjAuMyIgc3Ryb2tlPSJoc2woMjQwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSkiIHN0cm9rZS13aWR0aD0iMyIvPjxjbGlwUGF0aCBpZD0iY2xpcC1teS1zdmctMSI+PHJlY3Qgd2lkdGg9IjMyNiIgaGVpZ2h0PSIzMDYiLz48L2NsaXBQYXRoPjx0ZXh0IGNsYXNzPSJ0cmVlbWFwTGFiZWwiIHg9IjE2NSIgeT0iMTU1IiBzdHlsZT0idGV4dC1hbmNob3I6IG1pZGRsZTsgZG9taW5hbnQtYmFzZWxpbmU6IG1pZGRsZTsgZm9udC1zaXplOiAzOHB4O2ZpbGw6YmxhY2s7IiBjbGlwLXBhdGg9InVybCgjY2xpcC1teS1zdmctMSkiPkluZnJhPC90ZXh0Pjx0ZXh0IGNsYXNzPSJ0cmVlbWFwVmFsdWUiIHg9IjE2NSIgeT0iMTc2IiBzdHlsZT0idGV4dC1hbmNob3I6IG1pZGRsZTsgZG9taW5hbnQtYmFzZWxpbmU6IGhhbmdpbmc7IGZvbnQtc2l6ZTogMjNweDsgZmlsbDogYmxhY2s7IiBjbGlwLXBhdGg9InVybCgjY2xpcC1teS1zdmctMSkiPjM1PC90ZXh0PjwvZz48ZyBjbGFzcz0idHJlZW1hcE5vZGUgdHJlZW1hcExlYWZHcm91cCBsZWFmMngiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDc0OCw3MCkiPjxyZWN0IHdpZHRoPSIxMzUiIGhlaWdodD0iMzEwIiBjbGFzcz0idHJlZW1hcExlYWYiIGZpbGw9ImhzbCgyNDAsIDEwMCUsIDc2LjI3NDUwOTgwMzklKSIgc3R5bGU9IiIgZmlsbC1vcGFjaXR5PSIwLjMiIHN0cm9rZT0iaHNsKDI0MCwgMTAwJSwgNzYuMjc0NTA5ODAzOSUpIiBzdHJva2Utd2lkdGg9IjMiLz48Y2xpcFBhdGggaWQ9ImNsaXAtbXktc3ZnLTIiPjxyZWN0IHdpZHRoPSIxMzEiIGhlaWdodD0iMzA2Ii8+PC9jbGlwUGF0aD48dGV4dCBjbGFzcz0idHJlZW1hcExhYmVsIiB4PSI2Ny41IiB5PSIxNTUiIHN0eWxlPSJ0ZXh0LWFuY2hvcjogbWlkZGxlOyBkb21pbmFudC1iYXNlbGluZTogbWlkZGxlOyBmb250LXNpemU6IDI4cHg7IGZpbGw6IHJnYigyNTUsIDI1NSwgMjU1KTsiIGNsaXAtcGF0aD0idXJsKCNjbGlwLW15LXN2Zy0yKSI+TWFya2V0aW5nPC90ZXh0Pjx0ZXh0IGNsYXNzPSJ0cmVlbWFwVmFsdWUiIHg9IjY3LjUiIHk9IjE3MSIgc3R5bGU9InRleHQtYW5jaG9yOiBtaWRkbGU7IGRvbWluYW50LWJhc2VsaW5lOiBoYW5naW5nOyBmb250LXNpemU6IDE3cHg7IGZpbGw6IHJnYigyNTUsIDI1NSwgMjU1KTsiIGNsaXAtcGF0aD0idXJsKCNjbGlwLW15LXN2Zy0yKSI+MTU8L3RleHQ+PC9nPjxnIGNsYXNzPSJ0cmVlbWFwTm9kZSB0cmVlbWFwTGVhZkdyb3VwIGxlYWYzeCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoODkzLDcwKSI+PHJlY3Qgd2lkdGg9Ijg3IiBoZWlnaHQ9IjMxMCIgY2xhc3M9InRyZWVtYXBMZWFmIiBmaWxsPSJoc2woMjQwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSkiIHN0eWxlPSIiIGZpbGwtb3BhY2l0eT0iMC4zIiBzdHJva2U9ImhzbCgyNDAsIDEwMCUsIDc2LjI3NDUwOTgwMzklKSIgc3Ryb2tlLXdpZHRoPSIzIi8+PGNsaXBQYXRoIGlkPSJjbGlwLW15LXN2Zy0zIj48cmVjdCB3aWR0aD0iODMiIGhlaWdodD0iMzA2Ii8+PC9jbGlwUGF0aD48dGV4dCBjbGFzcz0idHJlZW1hcExhYmVsIiB4PSI0My41IiB5PSIxNTUiIHN0eWxlPSJ0ZXh0LWFuY2hvcjogbWlkZGxlOyBkb21pbmFudC1iYXNlbGluZTogbWlkZGxlOyBmb250LXNpemU6IDIycHg7IGZpbGw6IGJsYWNrOyIgY2xpcC1wYXRoPSJ1cmwoI2NsaXAtbXktc3ZnLTMpIj5TdXBwb3J0PC90ZXh0Pjx0ZXh0IGNsYXNzPSJ0cmVlbWFwVmFsdWUiIHg9IjQzLjUiIHk9IjE2OCIgc3R5bGU9InRleHQtYW5jaG9yOiBtaWRkbGU7IGRvbWluYW50LWJhc2VsaW5lOiBoYW5naW5nOyBmb250LXNpemU6IDEzcHg7IGZpbGw6IGJsYWNrOyIgY2xpcC1wYXRoPSJ1cmwoI2NsaXAtbXktc3ZnLTMpIj4xMDwvdGV4dD48L2c+PC9nPjwvc3ZnPg==) The treemap answers "where does the money actually go?" in one block: Engineering and Infra dominate, Support is a sliver. Mindmap would show the same four items as equal-width branches and hide the story. Choose the map by what the hierarchy *is*: idea (mindmap), structure (treeView), or magnitude (treemap). ## Turning notes into maps without a redraw[​](#turning-notes-into-maps-without-a-redraw "Direct link to Turning notes into maps without a redraw") Because Mermaid maps come from indented text, converting existing notes is mechanical: * **Reuse your bullets.** Each bullet level becomes an indentation level; the map builds itself. * **Split by domain at five levels.** Deeper subtrees get their own map and a link — a map of 25 nodes is read, a map of 60 is wallpaper. * **Put the owner in the leaf.** "Launch → Rollout → Maya" turns the map into an action list that survives the meeting. The hierarchy's companion diagrams live on the same pages: the **process** that consumes the decisions as a [state machine workflow](/blog/mermaid-state-diagram-workflow-confluence.md) and the **timeline** that schedules the work as a [release timeline](/blog/how-to-create-release-timeline-jira.md). ## FAQ[​](#faq "Direct link to FAQ") **Does Confluence have a built-in mind map tool?** No — Confluence has no native mind mapping. Mermaid Plus Diagrams & AI Agent for Confluence renders `mindmap`, `treeView` and `treemap` from indented text with a live preview. **Mindmap, treeView or treemap — which fits which job?** Mindmap for ideas (radial, branch-first), treeView for concrete hierarchies like a repo or folder tree, treemap when magnitude matters and area beats lines. **How do I turn meeting notes into a mind map?** Use the note's bullets as the map's indentation. Root = topic, branches = agenda headings, leaves = action items with owner names. **How many branches is too many?** Keep maps to 15–25 nodes; beyond that, split by domain — since it is text, splitting is copy-paste, not redraw. Render every Mermaid diagram type — mindmap, treeView, treemap, flowchart, ER and 24 more — in [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), free for up to 10 users. Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [mindmap](/blog/tags/mindmap.md) * [treeview](/blog/tags/treeview.md) * [treemap](/blog/tags/treemap.md) * [brainstorming](/blog/tags/brainstorming.md) * [how-to](/blog/tags/how-to.md) --- # Swimlane Process Diagrams in Confluence with Mermaid (Copy-Paste) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The ticket sits in "Waiting on customer" for a week and nobody noticed, because the handoff between first-line support and the dev team is a *tacit* step: Support marks it "escalated" in one field, Engineering is supposed to watch a filter, and the transfer never surfaces as its own action. That inert weekend is a process bug, and the fix is to see the handoff. A swimlane diagram makes the ownership transfer its own crossing arrow — invisible to everyone until it is drawn. **Quick answer:** map cross-functional processes in Confluence as Mermaid `swimlane-beta`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). One lane per actor, steps sequenced inside lanes, and the handoff is the arrow that crosses a lane boundary. When the interaction is a short request/response instead of long-running work, switch to a `sequenceDiagram`. This post gives you three copy-paste examples. ## Why the handoff is the whole point[​](#why-the-handoff-is-the-whole-point "Direct link to Why the handoff is the whole point") A flowchart shows *what happens in order*. A swimlane shows *who owns it at each moment* — and ownership transfer is where most process failures sit: * **Every step has exactly one owner.** If a step lists two teams, it is two steps; the swimlane forces that split. * **The crossing arrows are the SLA points.** The moment a ticket leaves Support and enters Engineering is when the clock should re-start its countdown. * **The gray lanes are people.** A lane named "Customer" makes it obvious that the process spends half its time with the customer — the queue insight a logic flowchart hides. When you read a swimlane, read the *boundaries crossed*, not the steps — the crossing is the risky part of the process. ## Copy-paste 1: support ticket routing[​](#copy-paste-1-support-ticket-routing "Direct link to Copy-paste 1: support ticket routing") The canonical swimlane: a ticket that moves through ownership, each lane holding its own steps and the boundaries showing who-when: ``` swimlane-beta LR subgraph Customer c1[Files a ticket] c2[Gets an answer] end subgraph Support s1[Screens and triages] s2[Answers or escalates] end subgraph Engineering e1[Fixes and patches] e2[Marks resolved] end c1 --> s1 s1 -->|answers| c2 s1 -->|escalates| e1 e1 --> e2 e2 --> c2 ``` ![Rendered Mermaid diagram](/assets/images/swimlane-beta-7f5abc1615d9fd75bbcc0bb57f5f1296.svg) Read the three crossings: `Support → Customer` (an answer), `Support → Engineering` (an escalation), `Engineering → Customer` (a resolution). If the escalation leg sat dormant for days, the diagram points at the exact boundary where the clock stalled — because the crossing is a visible arrow, not a field value. ## Copy-paste 2: approval workflow across roles[​](#copy-paste-2-approval-workflow-across-roles "Direct link to Copy-paste 2: approval workflow across roles") Approvals are the richest swimlane subject — every step changes owner, and the approval *is* a crossing. Map the purchase approval with handoffs labeled with what transfers: ``` swimlane-beta LR subgraph Requester r1[Submits request] r3[Receives decision] end subgraph Manager m1[Reviews] m2[Approves or returns] end subgraph Finance f1[Checks budget] f2[Records and pays] end r1 --> m1 m1 -->|returns| r3 m1 -->|forwards| f1 f1 -->|denies| r3 f1 --> f2 f2 --> r3 ``` ![Rendered Mermaid diagram](/assets/images/swimlane-beta-2-314b7a0aa063ddee28324388b02c13c5.svg) The return paths (`Manager → Requester`, `Finance → Requester`) are drawn, not implied — the diagram states that a deny is a first-class outcome. Every handoff carries the noun (the request, the decision, the payment), which is exactly the wording a process audit wants to check. ## Copy-paste 3: the interaction as a sequence[​](#copy-paste-3-the-interaction-as-a-sequence "Direct link to Copy-paste 3: the interaction as a sequence") When the process is a *conversation* — a request going back and forth — a sequence diagram is the right tool: time flows down, actors call out sideways, and the read is a transcript: ``` sequenceDiagram participant C as Customer participant S as Support participant E as Engineering C->>S: Ticket created S->>S: Triage and priority S->>E: Escalate (with notes) E->>S: Patch deployed S-->>C: Resolved with summary ``` ![Rendered Mermaid diagram](/assets/images/sequencediagram-f965d9a52ed2587783e83d6f46dd803d.svg) Same scenario as example 1, different read: the sequence diagram shows the *conversation* — who said what to whom, in what order — while the swimlane showed *ownership over time*. The rule of thumb: work that queues = swimlane; interaction that alternates = sequence. Keep both on the runbook page. ## Choosing between swimlane and sequence[​](#choosing-between-swimlane-and-sequence "Direct link to Choosing between swimlane and sequence") | Process shape | Diagram | Why | | ----------------------------------------- | ------------- | -------------------------------------------- | | Work passes through teams, held in queues | **Swimlane** | Ownership transfer and the queue are visible | | Actors exchange messages back and forth | **Sequence** | The transcript, in time order, is the point | | One actor decides, all steps internal | **Flowchart** | No ownership boundaries to draw | The three overlap less than they seem: if your process has no lane-crossing arrows, you likely need a flowchart; if it has no time-ordered conversation, you likely need the swimlane. The process's downstream neighbors are on the same wiki: the **decision points** inside the process as a [state machine](/blog/mermaid-state-diagram-workflow-confluence.md) and the **team workload** across the work as a [Kanban board](/blog/mermaid-kanban-board-workflow-confluence.md). ## FAQ[​](#faq "Direct link to FAQ") **Does Confluence have a built-in swimlane diagram tool?** No — Confluence has no native diagramming. Mermaid Plus Diagrams & AI Agent for Confluence renders `swimlane-beta` and `sequenceDiagram` from editable text with a live preview. **Swimlane or sequence diagram for a process?** Swimlane for long-running work moving through teams (queues, ownership), sequence for alternating request/response interactions. Mark the queue in the swimlane, the transcript in the sequence. **How do I show a handoff in a swimlane diagram?** The arrow that crosses a lane boundary is the handoff — label it with what transfers (ticket, approval, file) and the ownership change becomes a first-class step. **How do I avoid swimlane spaghetti?** Keep one step per lane per column, flow left to right, and collapse round-trips into a single labeled arrow. When every step crosses lanes, reconsider whether the lanes are right. Render every Mermaid diagram type — swimlane, sequence, flowchart, state, kanban and 24 more — in [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), free for up to 10 users. Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [swimlane](/blog/tags/swimlane.md) * [process](/blog/tags/process.md) * [flow](/blog/tags/flow.md) * [sequence-diagram](/blog/tags/sequence-diagram.md) * [how-to](/blog/tags/how-to.md) --- # Radar & Skill Matrix Charts in Confluence with Mermaid (Copy-Paste) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The team page says "we own the checkout" and the skills tab lists four words nobody updated. When the sprint needs a React engineer, the wiki can't say who is nearest. Meanwhile, the contributor guide links to a repo whose shape is a mystery ship in a fog of folders. Structure and capability both want *drawing* — and both draw from plain text. **Quick answer:** track capabilities and structure in Confluence as Mermaid — `radar-beta` for multi-axis comparison across profiles, `treeView-beta` for repo and structure maps, `railroad-ebnf-beta` for syntax and grammar diagrams — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Each chart answers a different "what's the shape": of the team, of the repo, of the language. This post gives you three copy-paste examples. ## Why capability and structure want drawing[​](#why-capability-and-structure-want-drawing "Direct link to Why capability and structure want drawing") Two kinds of knowledge docs die as lists but survive as shapes: * **A radar curve is a profile.** One curve per person, team, or option, scored across the same axes — the multi-dimensional comparison a bullet list blurs. * **A tree is a map.** Repo structure teaches by *neighbors*: what lives next to what, where the entry points are. * **A railroad track is a language.** Grammar reads best as a track with terminals and choices — legal input, drawn. All three are text under the hood, so each stays editable exactly where the wiki keeps the narrative that explains it. ## Copy-paste 1: the team's capability snapshot as radar[​](#copy-paste-1-the-teams-capability-snapshot-as-radar "Direct link to Copy-paste 1: the team's capability snapshot as radar") Axes once, then one curve per profile, `max 100` so scores mean the same thing across curves: ``` radar-beta axis Frontend, Backend, Data, DevOps curve Platform{80, 70, 55, 60} curve Data{45, 80, 90, 65} curve SRE{55, 70, 60, 90} max 100 ``` ![Rendered Mermaid diagram](data:image/svg+xml;base64,PHN2ZyBpZD0ibXktc3ZnIiB3aWR0aD0iMTAwJSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgc3R5bGU9Im1heC13aWR0aDogNzAwcHg7IGJhY2tncm91bmQtY29sb3I6IHdoaXRlOyIgdmlld0JveD0iMCAwIDcwMCA3MDAiIG92ZXJmbG93PSJ2aXNpYmxlIiByb2xlPSJncmFwaGljcy1kb2N1bWVudCBkb2N1bWVudCIgYXJpYS1yb2xlZGVzY3JpcHRpb249InJhZGFyIj48c3R5bGU+I215LXN2Z3tmb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7Zm9udC1zaXplOjE2cHg7ZmlsbDojMzMzO31Aa2V5ZnJhbWVzIGVkZ2UtYW5pbWF0aW9uLWZyYW1le2Zyb217c3Ryb2tlLWRhc2hvZmZzZXQ6MDt9fUBrZXlmcmFtZXMgZGFzaHt0b3tzdHJva2UtZGFzaG9mZnNldDowO319I215LXN2ZyAuZWRnZS1hbmltYXRpb24tc2xvd3tzdHJva2UtZGFzaGFycmF5OjksNSFpbXBvcnRhbnQ7c3Ryb2tlLWRhc2hvZmZzZXQ6OTAwO2FuaW1hdGlvbjpkYXNoIDUwcyBsaW5lYXIgaW5maW5pdGU7c3Ryb2tlLWxpbmVjYXA6cm91bmQ7fSNteS1zdmcgLmVkZ2UtYW5pbWF0aW9uLWZhc3R7c3Ryb2tlLWRhc2hhcnJheTo5LDUhaW1wb3J0YW50O3N0cm9rZS1kYXNob2Zmc2V0OjkwMDthbmltYXRpb246ZGFzaCAyMHMgbGluZWFyIGluZmluaXRlO3N0cm9rZS1saW5lY2FwOnJvdW5kO30jbXktc3ZnIC5lcnJvci1pY29ue2ZpbGw6IzU1MjIyMjt9I215LXN2ZyAuZXJyb3ItdGV4dHtmaWxsOiM1NTIyMjI7c3Ryb2tlOiM1NTIyMjI7fSNteS1zdmcgLmVkZ2UtdGhpY2tuZXNzLW5vcm1hbHtzdHJva2Utd2lkdGg6MXB4O30jbXktc3ZnIC5lZGdlLXRoaWNrbmVzcy10aGlja3tzdHJva2Utd2lkdGg6My41cHg7fSNteS1zdmcgLmVkZ2UtcGF0dGVybi1zb2xpZHtzdHJva2UtZGFzaGFycmF5OjA7fSNteS1zdmcgLmVkZ2UtdGhpY2tuZXNzLWludmlzaWJsZXtzdHJva2Utd2lkdGg6MDtmaWxsOm5vbmU7fSNteS1zdmcgLmVkZ2UtcGF0dGVybi1kYXNoZWR7c3Ryb2tlLWRhc2hhcnJheTozO30jbXktc3ZnIC5lZGdlLXBhdHRlcm4tZG90dGVke3N0cm9rZS1kYXNoYXJyYXk6Mjt9I215LXN2ZyAubWFya2Vye2ZpbGw6IzMzMzMzMztzdHJva2U6IzMzMzMzMzt9I215LXN2ZyAubWFya2VyLmNyb3Nze3N0cm9rZTojMzMzMzMzO30jbXktc3ZnIHN2Z3tmb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7Zm9udC1zaXplOjE2cHg7fSNteS1zdmcgcHttYXJnaW46MDt9I215LXN2ZyAucmFkYXJUaXRsZXtmb250LXNpemU6MTZweDtjb2xvcjojMzMzO2RvbWluYW50LWJhc2VsaW5lOmhhbmdpbmc7dGV4dC1hbmNob3I6bWlkZGxlO30jbXktc3ZnIC5yYWRhckF4aXNMaW5le3N0cm9rZTojMzMzMzMzO3N0cm9rZS13aWR0aDoyO30jbXktc3ZnIC5yYWRhckF4aXNMYWJlbHtmb250LXNpemU6MTJweDtjb2xvcjojMzMzMzMzO30jbXktc3ZnIC5yYWRhckdyYXRpY3VsZXtmaWxsOiNERURFREU7ZmlsbC1vcGFjaXR5OjAuMztzdHJva2U6I0RFREVERTtzdHJva2Utd2lkdGg6MTt9I215LXN2ZyAucmFkYXJMZWdlbmRUZXh0e3RleHQtYW5jaG9yOnN0YXJ0O2ZvbnQtc2l6ZToxMnB4O2RvbWluYW50LWJhc2VsaW5lOmhhbmdpbmc7fSNteS1zdmcgLnJhZGFyQ3VydmUtMHtjb2xvcjpoc2woMjQwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSk7ZmlsbDpoc2woMjQwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSk7ZmlsbC1vcGFjaXR5OjAuNTtzdHJva2U6aHNsKDI0MCwgMTAwJSwgNzYuMjc0NTA5ODAzOSUpO3N0cm9rZS13aWR0aDoyO30jbXktc3ZnIC5yYWRhckxlZ2VuZEJveC0we2ZpbGw6aHNsKDI0MCwgMTAwJSwgNzYuMjc0NTA5ODAzOSUpO2ZpbGwtb3BhY2l0eTowLjU7c3Ryb2tlOmhzbCgyNDAsIDEwMCUsIDc2LjI3NDUwOTgwMzklKTt9I215LXN2ZyAucmFkYXJDdXJ2ZS0xe2NvbG9yOmhzbCg2MCwgMTAwJSwgNzMuNTI5NDExNzY0NyUpO2ZpbGw6aHNsKDYwLCAxMDAlLCA3My41Mjk0MTE3NjQ3JSk7ZmlsbC1vcGFjaXR5OjAuNTtzdHJva2U6aHNsKDYwLCAxMDAlLCA3My41Mjk0MTE3NjQ3JSk7c3Ryb2tlLXdpZHRoOjI7fSNteS1zdmcgLnJhZGFyTGVnZW5kQm94LTF7ZmlsbDpoc2woNjAsIDEwMCUsIDczLjUyOTQxMTc2NDclKTtmaWxsLW9wYWNpdHk6MC41O3N0cm9rZTpoc2woNjAsIDEwMCUsIDczLjUyOTQxMTc2NDclKTt9I215LXN2ZyAucmFkYXJDdXJ2ZS0ye2NvbG9yOmhzbCg4MCwgMTAwJSwgNzYuMjc0NTA5ODAzOSUpO2ZpbGw6aHNsKDgwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSk7ZmlsbC1vcGFjaXR5OjAuNTtzdHJva2U6aHNsKDgwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSk7c3Ryb2tlLXdpZHRoOjI7fSNteS1zdmcgLnJhZGFyTGVnZW5kQm94LTJ7ZmlsbDpoc2woODAsIDEwMCUsIDc2LjI3NDUwOTgwMzklKTtmaWxsLW9wYWNpdHk6MC41O3N0cm9rZTpoc2woODAsIDEwMCUsIDc2LjI3NDUwOTgwMzklKTt9I215LXN2ZyAucmFkYXJDdXJ2ZS0ze2NvbG9yOmhzbCgyNzAsIDEwMCUsIDc2LjI3NDUwOTgwMzklKTtmaWxsOmhzbCgyNzAsIDEwMCUsIDc2LjI3NDUwOTgwMzklKTtmaWxsLW9wYWNpdHk6MC41O3N0cm9rZTpoc2woMjcwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSk7c3Ryb2tlLXdpZHRoOjI7fSNteS1zdmcgLnJhZGFyTGVnZW5kQm94LTN7ZmlsbDpoc2woMjcwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSk7ZmlsbC1vcGFjaXR5OjAuNTtzdHJva2U6aHNsKDI3MCwgMTAwJSwgNzYuMjc0NTA5ODAzOSUpO30jbXktc3ZnIC5yYWRhckN1cnZlLTR7Y29sb3I6aHNsKDMwMCwgMTAwJSwgNzYuMjc0NTA5ODAzOSUpO2ZpbGw6aHNsKDMwMCwgMTAwJSwgNzYuMjc0NTA5ODAzOSUpO2ZpbGwtb3BhY2l0eTowLjU7c3Ryb2tlOmhzbCgzMDAsIDEwMCUsIDc2LjI3NDUwOTgwMzklKTtzdHJva2Utd2lkdGg6Mjt9I215LXN2ZyAucmFkYXJMZWdlbmRCb3gtNHtmaWxsOmhzbCgzMDAsIDEwMCUsIDc2LjI3NDUwOTgwMzklKTtmaWxsLW9wYWNpdHk6MC41O3N0cm9rZTpoc2woMzAwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSk7fSNteS1zdmcgLnJhZGFyQ3VydmUtNXtjb2xvcjpoc2woMzMwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSk7ZmlsbDpoc2woMzMwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSk7ZmlsbC1vcGFjaXR5OjAuNTtzdHJva2U6aHNsKDMzMCwgMTAwJSwgNzYuMjc0NTA5ODAzOSUpO3N0cm9rZS13aWR0aDoyO30jbXktc3ZnIC5yYWRhckxlZ2VuZEJveC01e2ZpbGw6aHNsKDMzMCwgMTAwJSwgNzYuMjc0NTA5ODAzOSUpO2ZpbGwtb3BhY2l0eTowLjU7c3Ryb2tlOmhzbCgzMzAsIDEwMCUsIDc2LjI3NDUwOTgwMzklKTt9I215LXN2ZyAucmFkYXJDdXJ2ZS02e2NvbG9yOmhzbCgwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSk7ZmlsbDpoc2woMCwgMTAwJSwgNzYuMjc0NTA5ODAzOSUpO2ZpbGwtb3BhY2l0eTowLjU7c3Ryb2tlOmhzbCgwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSk7c3Ryb2tlLXdpZHRoOjI7fSNteS1zdmcgLnJhZGFyTGVnZW5kQm94LTZ7ZmlsbDpoc2woMCwgMTAwJSwgNzYuMjc0NTA5ODAzOSUpO2ZpbGwtb3BhY2l0eTowLjU7c3Ryb2tlOmhzbCgwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSk7fSNteS1zdmcgLnJhZGFyQ3VydmUtN3tjb2xvcjpoc2woMzAsIDEwMCUsIDc2LjI3NDUwOTgwMzklKTtmaWxsOmhzbCgzMCwgMTAwJSwgNzYuMjc0NTA5ODAzOSUpO2ZpbGwtb3BhY2l0eTowLjU7c3Ryb2tlOmhzbCgzMCwgMTAwJSwgNzYuMjc0NTA5ODAzOSUpO3N0cm9rZS13aWR0aDoyO30jbXktc3ZnIC5yYWRhckxlZ2VuZEJveC03e2ZpbGw6aHNsKDMwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSk7ZmlsbC1vcGFjaXR5OjAuNTtzdHJva2U6aHNsKDMwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSk7fSNteS1zdmcgLnJhZGFyQ3VydmUtOHtjb2xvcjpoc2woOTAsIDEwMCUsIDc2LjI3NDUwOTgwMzklKTtmaWxsOmhzbCg5MCwgMTAwJSwgNzYuMjc0NTA5ODAzOSUpO2ZpbGwtb3BhY2l0eTowLjU7c3Ryb2tlOmhzbCg5MCwgMTAwJSwgNzYuMjc0NTA5ODAzOSUpO3N0cm9rZS13aWR0aDoyO30jbXktc3ZnIC5yYWRhckxlZ2VuZEJveC04e2ZpbGw6aHNsKDkwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSk7ZmlsbC1vcGFjaXR5OjAuNTtzdHJva2U6aHNsKDkwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSk7fSNteS1zdmcgLnJhZGFyQ3VydmUtOXtjb2xvcjpoc2woMTUwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSk7ZmlsbDpoc2woMTUwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSk7ZmlsbC1vcGFjaXR5OjAuNTtzdHJva2U6aHNsKDE1MCwgMTAwJSwgNzYuMjc0NTA5ODAzOSUpO3N0cm9rZS13aWR0aDoyO30jbXktc3ZnIC5yYWRhckxlZ2VuZEJveC05e2ZpbGw6aHNsKDE1MCwgMTAwJSwgNzYuMjc0NTA5ODAzOSUpO2ZpbGwtb3BhY2l0eTowLjU7c3Ryb2tlOmhzbCgxNTAsIDEwMCUsIDc2LjI3NDUwOTgwMzklKTt9I215LXN2ZyAucmFkYXJDdXJ2ZS0xMHtjb2xvcjpoc2woMTgwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSk7ZmlsbDpoc2woMTgwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSk7ZmlsbC1vcGFjaXR5OjAuNTtzdHJva2U6aHNsKDE4MCwgMTAwJSwgNzYuMjc0NTA5ODAzOSUpO3N0cm9rZS13aWR0aDoyO30jbXktc3ZnIC5yYWRhckxlZ2VuZEJveC0xMHtmaWxsOmhzbCgxODAsIDEwMCUsIDc2LjI3NDUwOTgwMzklKTtmaWxsLW9wYWNpdHk6MC41O3N0cm9rZTpoc2woMTgwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSk7fSNteS1zdmcgLnJhZGFyQ3VydmUtMTF7Y29sb3I6aHNsKDIxMCwgMTAwJSwgNzYuMjc0NTA5ODAzOSUpO2ZpbGw6aHNsKDIxMCwgMTAwJSwgNzYuMjc0NTA5ODAzOSUpO2ZpbGwtb3BhY2l0eTowLjU7c3Ryb2tlOmhzbCgyMTAsIDEwMCUsIDc2LjI3NDUwOTgwMzklKTtzdHJva2Utd2lkdGg6Mjt9I215LXN2ZyAucmFkYXJMZWdlbmRCb3gtMTF7ZmlsbDpoc2woMjEwLCAxMDAlLCA3Ni4yNzQ1MDk4MDM5JSk7ZmlsbC1vcGFjaXR5OjAuNTtzdHJva2U6aHNsKDIxMCwgMTAwJSwgNzYuMjc0NTA5ODAzOSUpO30jbXktc3ZnIC5ub2RlIC5uZW8tbm9kZXtzdHJva2U6IzkzNzBEQjt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIHJlY3QsI215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5jbHVzdGVyIHJlY3QsI215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIHBvbHlnb257c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLnN3aW1sYW5lLmNsdXN0ZXIgcmVjdHtmaWx0ZXI6bm9uZTt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIHBhdGh7c3Ryb2tlOiM5MzcwREI7c3Ryb2tlLXdpZHRoOjFweDt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIC5vdXRlci1wYXRoe2ZpbHRlcjpkcm9wLXNoYWRvdygxcHggMnB4IDJweCByZ2JhKDE4NSwgMTg1LCAxODUsIDEpKTt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIC5uZW8tbGluZSBwYXRoe3N0cm9rZTojOTM3MERCO2ZpbHRlcjpub25lO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgY2lyY2xle3N0cm9rZTojOTM3MERCO2ZpbHRlcjpkcm9wLXNoYWRvdygxcHggMnB4IDJweCByZ2JhKDE4NSwgMTg1LCAxODUsIDEpKTt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIGNpcmNsZSAuc3RhdGUtc3RhcnR7ZmlsbDojMDAwMDAwO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLmljb24tc2hhcGUgLmljb257ZmlsbDojOTM3MERCO2ZpbHRlcjpkcm9wLXNoYWRvdygxcHggMnB4IDJweCByZ2JhKDE4NSwgMTg1LCAxODUsIDEpKTt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5pY29uLXNoYXBlIC5pY29uLW5lbyBwYXRoe3N0cm9rZTojOTM3MERCO2ZpbHRlcjpkcm9wLXNoYWRvdygxcHggMnB4IDJweCByZ2JhKDE4NSwgMTg1LCAxODUsIDEpKTt9I215LXN2ZyA6cm9vdHstLW1lcm1haWQtZm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO308L3N0eWxlPjxnLz48ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgzNTAsIDM1MCkiPjxjaXJjbGUgcj0iNjAiIGNsYXNzPSJyYWRhckdyYXRpY3VsZSIvPjxjaXJjbGUgcj0iMTIwIiBjbGFzcz0icmFkYXJHcmF0aWN1bGUiLz48Y2lyY2xlIHI9IjE4MCIgY2xhc3M9InJhZGFyR3JhdGljdWxlIi8+PGNpcmNsZSByPSIyNDAiIGNsYXNzPSJyYWRhckdyYXRpY3VsZSIvPjxjaXJjbGUgcj0iMzAwIiBjbGFzcz0icmFkYXJHcmF0aWN1bGUiLz48bGluZSB4MT0iMCIgeTE9IjAiIHgyPSIxLjgzNjk3MDE5ODcyMTAyOTdlLTE0IiB5Mj0iLTMwMCIgY2xhc3M9InJhZGFyQXhpc0xpbmUiLz48dGV4dCB4PSIxLjk1MzMxMTY0NDY0MDAyODVlLTE0IiB5PSItMzE5IiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBkb21pbmFudC1iYXNlbGluZT0iYXV0byIgY2xhc3M9InJhZGFyQXhpc0xhYmVsIj5Gcm9udGVuZDwvdGV4dD48bGluZSB4MT0iMCIgeTE9IjAiIHgyPSIzMDAiIHkyPSIwIiBjbGFzcz0icmFkYXJBeGlzTGluZSIvPjx0ZXh0IHg9IjMxOSIgeT0iMCIgdGV4dC1hbmNob3I9InN0YXJ0IiBkb21pbmFudC1iYXNlbGluZT0iY2VudHJhbCIgY2xhc3M9InJhZGFyQXhpc0xhYmVsIj5CYWNrZW5kPC90ZXh0PjxsaW5lIHgxPSIwIiB5MT0iMCIgeDI9IjEuODM2OTcwMTk4NzIxMDI5N2UtMTQiIHkyPSIzMDAiIGNsYXNzPSJyYWRhckF4aXNMaW5lIi8+PHRleHQgeD0iMS45NTMzMTE2NDQ2NDAwMjg1ZS0xNCIgeT0iMzE5IiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBkb21pbmFudC1iYXNlbGluZT0iaGFuZ2luZyIgY2xhc3M9InJhZGFyQXhpc0xhYmVsIj5EYXRhPC90ZXh0PjxsaW5lIHgxPSIwIiB5MT0iMCIgeDI9Ii0zMDAiIHkyPSIzLjY3Mzk0MDM5NzQ0MjA1OTVlLTE0IiBjbGFzcz0icmFkYXJBeGlzTGluZSIvPjx0ZXh0IHg9Ii0zMTkiIHk9IjMuOTA2NjIzMjg5MjgwMDU3ZS0xNCIgdGV4dC1hbmNob3I9ImVuZCIgZG9taW5hbnQtYmFzZWxpbmU9ImNlbnRyYWwiIGNsYXNzPSJyYWRhckF4aXNMYWJlbCI+RGV2T3BzPC90ZXh0PjxwYXRoIGQ9Ik0xLjQ2OTU3NjE1ODk3NjgyNGUtMTQsLTI0MCBDNjYuMzAwMDAwMDAwMDAwMDMsLTI0MCAyMTAsLTY4Ljg1MDAwMDAwMDAwMDAxIDIxMCwwIEMyMTAsNjguODUwMDAwMDAwMDAwMDEgNjYuMzAwMDAwMDAwMDAwMDMsMTY1IDEuMDEwMzMzNjA5Mjk2NTY2NGUtMTQsMTY1IEMtNjYuMywxNjUgLTE4MCw2OC44NTAwMDAwMDAwMDAwNCAtMTgwLDIuMjA0MzY0MjM4NDY1MjM1OGUtMTQgQy0xODAsLTY4Ljg0OTk5OTk5OTk5OTk4IC02Ni4zLC0yNDAgMS40Njk1NzYxNTg5NzY4MjRlLTE0LC0yNDAgWiIgY2xhc3M9InJhZGFyQ3VydmUtMCIvPjxwYXRoIGQ9Ik04LjI2NjM2NTg5NDI0NDYzNGUtMTUsLTEzNSBDNzMuOTUwMDAwMDAwMDAwMDIsLTEzNSAyNDAsLTY4Ljg1MDAwMDAwMDAwMDAxIDI0MCwwIEMyNDAsNjguODUwMDAwMDAwMDAwMDEgNzMuOTUwMDAwMDAwMDAwMDIsMjcwIDEuNjUzMjczMTc4ODQ4OTI2N2UtMTQsMjcwIEMtNzMuOTQ5OTk5OTk5OTk5OTksMjcwIC0xOTUsNjguODUwMDAwMDAwMDAwMDQgLTE5NSwyLjM4ODA2MTI1ODMzNzMzOWUtMTQgQy0xOTUsLTY4Ljg0OTk5OTk5OTk5OTk4IC03My45NDk5OTk5OTk5OTk5OSwtMTM1IDguMjY2MzY1ODk0MjQ0NjM0ZS0xNSwtMTM1IFoiIGNsYXNzPSJyYWRhckN1cnZlLTEiLz48cGF0aCBkPSJNMS4wMTAzMzM2MDkyOTY1NjY0ZS0xNCwtMTY1IEM4MS42MDAwMDAwMDAwMDAwMiwtMTY1IDIxMCwtNTguNjUwMDAwMDAwMDAwMDA2IDIxMCwwIEMyMTAsNTguNjUwMDAwMDAwMDAwMDA2IDgxLjYwMDAwMDAwMDAwMDAyLDE4MCAxLjEwMjE4MjExOTIzMjYxNzllLTE0LDE4MCBDLTgxLjYsMTgwIC0yNzAsNTguNjUwMDAwMDAwMDAwMDQgLTI3MCwzLjMwNjU0NjM1NzY5Nzg1MzRlLTE0IEMtMjcwLC01OC42NDk5OTk5OTk5OTk5NyAtODEuNiwtMTY1IDEuMDEwMzMzNjA5Mjk2NTY2NGUtMTQsLTE2NSBaIiBjbGFzcz0icmFkYXJDdXJ2ZS0yIi8+PGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMjYyLjUsIC0yNjIuNSkiPjxyZWN0IHdpZHRoPSIxMiIgaGVpZ2h0PSIxMiIgY2xhc3M9InJhZGFyTGVnZW5kQm94LTAiLz48dGV4dCB4PSIxNiIgeT0iMCIgY2xhc3M9InJhZGFyTGVnZW5kVGV4dCI+UGxhdGZvcm08L3RleHQ+PC9nPjxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDI2Mi41LCAtMjQyLjUpIj48cmVjdCB3aWR0aD0iMTIiIGhlaWdodD0iMTIiIGNsYXNzPSJyYWRhckxlZ2VuZEJveC0xIi8+PHRleHQgeD0iMTYiIHk9IjAiIGNsYXNzPSJyYWRhckxlZ2VuZFRleHQiPkRhdGE8L3RleHQ+PC9nPjxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDI2Mi41LCAtMjIyLjUpIj48cmVjdCB3aWR0aD0iMTIiIGhlaWdodD0iMTIiIGNsYXNzPSJyYWRhckxlZ2VuZEJveC0yIi8+PHRleHQgeD0iMTYiIHk9IjAiIGNsYXNzPSJyYWRhckxlZ2VuZFRleHQiPlNSRTwvdGV4dD48L2c+PHRleHQgY2xhc3M9InJhZGFyVGl0bGUiIHg9IjAiIHk9Ii0zNTAiLz48L2c+PC9zdmc+) Three curves, four axes, one glance: Platform owns the frontend rim, Data owns the data axis, SRE owns the ops corner — and the middle (Backend) is where everyone overlaps. The radar turns the "who is nearest to React" question into a spatial read, not a tab-search. ## Copy-paste 2: the repo as treeView[​](#copy-paste-2-the-repo-as-treeview "Direct link to Copy-paste 2: the repo as treeView") Structure maps for contributor guides and architecture pages — indented and readable at a glance: ``` treeView-beta "checkout-service" "src" "http" "orders" "payments" "domain" "models" "infra" "db" "deploy" "helm" ``` ![Rendered Mermaid diagram](data:image/svg+xml;base64,PHN2ZyBpZD0ibXktc3ZnIiB3aWR0aD0iMTAwJSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgdmlld0JveD0iLTAuNSAwIDE0Ni42NzE4NzUgMzQ4IiBzdHlsZT0ibWF4LXdpZHRoOiAxNDYuNjcycHg7IGJhY2tncm91bmQtY29sb3I6IHdoaXRlOyIgcm9sZT0iZ3JhcGhpY3MtZG9jdW1lbnQgZG9jdW1lbnQiIGFyaWEtcm9sZWRlc2NyaXB0aW9uPSJ0cmVlVmlldyI+PHN0eWxlPiNteS1zdmd7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO2ZvbnQtc2l6ZToxNnB4O2ZpbGw6IzMzMzt9QGtleWZyYW1lcyBlZGdlLWFuaW1hdGlvbi1mcmFtZXtmcm9te3N0cm9rZS1kYXNob2Zmc2V0OjA7fX1Aa2V5ZnJhbWVzIGRhc2h7dG97c3Ryb2tlLWRhc2hvZmZzZXQ6MDt9fSNteS1zdmcgLmVkZ2UtYW5pbWF0aW9uLXNsb3d7c3Ryb2tlLWRhc2hhcnJheTo5LDUhaW1wb3J0YW50O3N0cm9rZS1kYXNob2Zmc2V0OjkwMDthbmltYXRpb246ZGFzaCA1MHMgbGluZWFyIGluZmluaXRlO3N0cm9rZS1saW5lY2FwOnJvdW5kO30jbXktc3ZnIC5lZGdlLWFuaW1hdGlvbi1mYXN0e3N0cm9rZS1kYXNoYXJyYXk6OSw1IWltcG9ydGFudDtzdHJva2UtZGFzaG9mZnNldDo5MDA7YW5pbWF0aW9uOmRhc2ggMjBzIGxpbmVhciBpbmZpbml0ZTtzdHJva2UtbGluZWNhcDpyb3VuZDt9I215LXN2ZyAuZXJyb3ItaWNvbntmaWxsOiM1NTIyMjI7fSNteS1zdmcgLmVycm9yLXRleHR7ZmlsbDojNTUyMjIyO3N0cm9rZTojNTUyMjIyO30jbXktc3ZnIC5lZGdlLXRoaWNrbmVzcy1ub3JtYWx7c3Ryb2tlLXdpZHRoOjFweDt9I215LXN2ZyAuZWRnZS10aGlja25lc3MtdGhpY2t7c3Ryb2tlLXdpZHRoOjMuNXB4O30jbXktc3ZnIC5lZGdlLXBhdHRlcm4tc29saWR7c3Ryb2tlLWRhc2hhcnJheTowO30jbXktc3ZnIC5lZGdlLXRoaWNrbmVzcy1pbnZpc2libGV7c3Ryb2tlLXdpZHRoOjA7ZmlsbDpub25lO30jbXktc3ZnIC5lZGdlLXBhdHRlcm4tZGFzaGVke3N0cm9rZS1kYXNoYXJyYXk6Mzt9I215LXN2ZyAuZWRnZS1wYXR0ZXJuLWRvdHRlZHtzdHJva2UtZGFzaGFycmF5OjI7fSNteS1zdmcgLm1hcmtlcntmaWxsOiMzMzMzMzM7c3Ryb2tlOiMzMzMzMzM7fSNteS1zdmcgLm1hcmtlci5jcm9zc3tzdHJva2U6IzMzMzMzMzt9I215LXN2ZyBzdmd7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO2ZvbnQtc2l6ZToxNnB4O30jbXktc3ZnIHB7bWFyZ2luOjA7fSNteS1zdmcgLnRyZWVWaWV3LW5vZGUtbGFiZWx7Zm9udC1zaXplOjE2cHg7ZmlsbDpibGFjazt3aGl0ZS1zcGFjZTpwcmU7fSNteS1zdmcgLnRyZWVWaWV3LW5vZGUtZGlye2ZvbnQtd2VpZ2h0OmJvbGQ7fSNteS1zdmcgLnRyZWVWaWV3LW5vZGUtbGluZXtzdHJva2U6YmxhY2s7fSNteS1zdmcgLnRyZWVWaWV3LW5vZGUtaWNvbntjb2xvcjojNTQ2ZTdhO30jbXktc3ZnIC50cmVlVmlldy1ub2RlLWRlc2NyaXB0aW9ue2ZvbnQtc2l6ZToxNnB4O2ZpbGw6IzZhOTk1NTtmb250LXN0eWxlOml0YWxpYzt3aGl0ZS1zcGFjZTpwcmU7fSNteS1zdmcgLnRyZWVWaWV3LWhpZ2hsaWdodC1iZ3tmaWxsOnJnYmEoMjU1LCAxOTMsIDcsIDAuMTUpO3N0cm9rZTojZmZjMTA3O3N0cm9rZS13aWR0aDoxO30jbXktc3ZnIC5ub2RlIC5uZW8tbm9kZXtzdHJva2U6IzkzNzBEQjt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIHJlY3QsI215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5jbHVzdGVyIHJlY3QsI215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIHBvbHlnb257c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLnN3aW1sYW5lLmNsdXN0ZXIgcmVjdHtmaWx0ZXI6bm9uZTt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIHBhdGh7c3Ryb2tlOiM5MzcwREI7c3Ryb2tlLXdpZHRoOjFweDt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIC5vdXRlci1wYXRoe2ZpbHRlcjpkcm9wLXNoYWRvdygxcHggMnB4IDJweCByZ2JhKDE4NSwgMTg1LCAxODUsIDEpKTt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIC5uZW8tbGluZSBwYXRoe3N0cm9rZTojOTM3MERCO2ZpbHRlcjpub25lO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgY2lyY2xle3N0cm9rZTojOTM3MERCO2ZpbHRlcjpkcm9wLXNoYWRvdygxcHggMnB4IDJweCByZ2JhKDE4NSwgMTg1LCAxODUsIDEpKTt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIGNpcmNsZSAuc3RhdGUtc3RhcnR7ZmlsbDojMDAwMDAwO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLmljb24tc2hhcGUgLmljb257ZmlsbDojOTM3MERCO2ZpbHRlcjpkcm9wLXNoYWRvdygxcHggMnB4IDJweCByZ2JhKDE4NSwgMTg1LCAxODUsIDEpKTt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5pY29uLXNoYXBlIC5pY29uLW5lbyBwYXRoe3N0cm9rZTojOTM3MERCO2ZpbHRlcjpkcm9wLXNoYWRvdygxcHggMnB4IDJweCByZ2JhKDE4NSwgMTg1LCAxODUsIDEpKTt9I215LXN2ZyA6cm9vdHstLW1lcm1haWQtZm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO308L3N0eWxlPjxnLz48ZyBjbGFzcz0idHJlZS12aWV3Ij48Zz48dGV4dCBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiBjbGFzcz0idHJlZVZpZXctbm9kZS1sYWJlbCB0cmVlVmlldy1ub2RlLWRpciIgeD0iNSIgeT0iMTQuNSI+LzwvdGV4dD48L2c+PGxpbmUgeDE9Ii0xMCIgeTE9IjE0LjUiIHgyPSIwIiB5Mj0iMTQuNSIgc3Ryb2tlLXdpZHRoPSIxIiBjbGFzcz0idHJlZVZpZXctbm9kZS1saW5lIi8+PGc+PHRleHQgZG9taW5hbnQtYmFzZWxpbmU9Im1pZGRsZSIgY2xhc3M9InRyZWVWaWV3LW5vZGUtbGFiZWwiIHg9IjIwIiB5PSI0My41Ij5jaGVja291dC1zZXJ2aWNlPC90ZXh0PjwvZz48bGluZSB4MT0iNSIgeTE9IjQzLjUiIHgyPSIxNSIgeTI9IjQzLjUiIHN0cm9rZS13aWR0aD0iMSIgY2xhc3M9InRyZWVWaWV3LW5vZGUtbGluZSIvPjxnPjx0ZXh0IGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxhYmVsIiB4PSIzNSIgeT0iNzIuNSI+c3JjPC90ZXh0PjwvZz48bGluZSB4MT0iMjAiIHkxPSI3Mi41IiB4Mj0iMzAiIHkyPSI3Mi41IiBzdHJva2Utd2lkdGg9IjEiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxpbmUiLz48Zz48dGV4dCBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiBjbGFzcz0idHJlZVZpZXctbm9kZS1sYWJlbCIgeD0iNTAiIHk9IjEwMS41Ij5odHRwPC90ZXh0PjwvZz48bGluZSB4MT0iMzUiIHkxPSIxMDEuNSIgeDI9IjQ1IiB5Mj0iMTAxLjUiIHN0cm9rZS13aWR0aD0iMSIgY2xhc3M9InRyZWVWaWV3LW5vZGUtbGluZSIvPjxnPjx0ZXh0IGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxhYmVsIiB4PSI2NSIgeT0iMTMwLjUiPm9yZGVyczwvdGV4dD48L2c+PGxpbmUgeDE9IjUwIiB5MT0iMTMwLjUiIHgyPSI2MCIgeTI9IjEzMC41IiBzdHJva2Utd2lkdGg9IjEiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxpbmUiLz48Zz48dGV4dCBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiBjbGFzcz0idHJlZVZpZXctbm9kZS1sYWJlbCIgeD0iNjUiIHk9IjE1OS41Ij5wYXltZW50czwvdGV4dD48L2c+PGxpbmUgeDE9IjUwIiB5MT0iMTU5LjUiIHgyPSI2MCIgeTI9IjE1OS41IiBzdHJva2Utd2lkdGg9IjEiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxpbmUiLz48bGluZSB4MT0iNTAiIHkxPSIxMTYiIHgyPSI1MCIgeTI9IjE2MCIgc3Ryb2tlLXdpZHRoPSIxIiBjbGFzcz0idHJlZVZpZXctbm9kZS1saW5lIi8+PGc+PHRleHQgZG9taW5hbnQtYmFzZWxpbmU9Im1pZGRsZSIgY2xhc3M9InRyZWVWaWV3LW5vZGUtbGFiZWwiIHg9IjUwIiB5PSIxODguNSI+ZG9tYWluPC90ZXh0PjwvZz48bGluZSB4MT0iMzUiIHkxPSIxODguNSIgeDI9IjQ1IiB5Mj0iMTg4LjUiIHN0cm9rZS13aWR0aD0iMSIgY2xhc3M9InRyZWVWaWV3LW5vZGUtbGluZSIvPjxnPjx0ZXh0IGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxhYmVsIiB4PSI2NSIgeT0iMjE3LjUiPm1vZGVsczwvdGV4dD48L2c+PGxpbmUgeDE9IjUwIiB5MT0iMjE3LjUiIHgyPSI2MCIgeTI9IjIxNy41IiBzdHJva2Utd2lkdGg9IjEiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxpbmUiLz48bGluZSB4MT0iNTAiIHkxPSIyMDMiIHgyPSI1MCIgeTI9IjIxOCIgc3Ryb2tlLXdpZHRoPSIxIiBjbGFzcz0idHJlZVZpZXctbm9kZS1saW5lIi8+PGc+PHRleHQgZG9taW5hbnQtYmFzZWxpbmU9Im1pZGRsZSIgY2xhc3M9InRyZWVWaWV3LW5vZGUtbGFiZWwiIHg9IjUwIiB5PSIyNDYuNSI+aW5mcmE8L3RleHQ+PC9nPjxsaW5lIHgxPSIzNSIgeTE9IjI0Ni41IiB4Mj0iNDUiIHkyPSIyNDYuNSIgc3Ryb2tlLXdpZHRoPSIxIiBjbGFzcz0idHJlZVZpZXctbm9kZS1saW5lIi8+PGc+PHRleHQgZG9taW5hbnQtYmFzZWxpbmU9Im1pZGRsZSIgY2xhc3M9InRyZWVWaWV3LW5vZGUtbGFiZWwiIHg9IjY1IiB5PSIyNzUuNSI+ZGI8L3RleHQ+PC9nPjxsaW5lIHgxPSI1MCIgeTE9IjI3NS41IiB4Mj0iNjAiIHkyPSIyNzUuNSIgc3Ryb2tlLXdpZHRoPSIxIiBjbGFzcz0idHJlZVZpZXctbm9kZS1saW5lIi8+PGxpbmUgeDE9IjUwIiB5MT0iMjYxIiB4Mj0iNTAiIHkyPSIyNzYiIHN0cm9rZS13aWR0aD0iMSIgY2xhc3M9InRyZWVWaWV3LW5vZGUtbGluZSIvPjxsaW5lIHgxPSIzNSIgeTE9Ijg3IiB4Mj0iMzUiIHkyPSIyNDciIHN0cm9rZS13aWR0aD0iMSIgY2xhc3M9InRyZWVWaWV3LW5vZGUtbGluZSIvPjxnPjx0ZXh0IGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxhYmVsIiB4PSIzNSIgeT0iMzA0LjUiPmRlcGxveTwvdGV4dD48L2c+PGxpbmUgeDE9IjIwIiB5MT0iMzA0LjUiIHgyPSIzMCIgeTI9IjMwNC41IiBzdHJva2Utd2lkdGg9IjEiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxpbmUiLz48Zz48dGV4dCBkb21pbmFudC1iYXNlbGluZT0ibWlkZGxlIiBjbGFzcz0idHJlZVZpZXctbm9kZS1sYWJlbCIgeD0iNTAiIHk9IjMzMy41Ij5oZWxtPC90ZXh0PjwvZz48bGluZSB4MT0iMzUiIHkxPSIzMzMuNSIgeDI9IjQ1IiB5Mj0iMzMzLjUiIHN0cm9rZS13aWR0aD0iMSIgY2xhc3M9InRyZWVWaWV3LW5vZGUtbGluZSIvPjxsaW5lIHgxPSIzNSIgeTE9IjMxOSIgeDI9IjM1IiB5Mj0iMzM0IiBzdHJva2Utd2lkdGg9IjEiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxpbmUiLz48bGluZSB4MT0iMjAiIHkxPSI1OCIgeDI9IjIwIiB5Mj0iMzA1IiBzdHJva2Utd2lkdGg9IjEiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxpbmUiLz48bGluZSB4MT0iNSIgeTE9IjI5IiB4Mj0iNSIgeTI9IjQ0IiBzdHJva2Utd2lkdGg9IjEiIGNsYXNzPSJ0cmVlVmlldy1ub2RlLWxpbmUiLz48L2c+PC9zdmc+) The tree is a *map* — where the HTTP handlers live, where the domain models sit, where the Helm charts deploy from — without a single import line. Onboarding reads the structure before the code, and the tree is the first page of that reading. ## Copy-paste 3: a grammar as railroad[​](#copy-paste-3-a-grammar-as-railroad "Direct link to Copy-paste 3: a grammar as railroad") Syntax and grammar documentation reads best as tracks — terminals in quotes, `|` for choice, `*`/`+` for repetition: ``` railroad-ebnf-beta title "Order Request" order = "POST" path ( "?q=" query )? ; path = "/orders" ; query = [A-Za-z0-9]+ ; ``` ![Order Request](data:image/svg+xml;base64,PHN2ZyBpZD0ibXktc3ZnIiB3aWR0aD0iMTAwJSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgY2xhc3M9InJhaWxyb2FkLWRpYWdyYW0iIHN0eWxlPSJtYXgtd2lkdGg6IDQxMS43MjdweDsgYmFja2dyb3VuZC1jb2xvcjogd2hpdGU7IiB2aWV3Qm94PSIwIDAgNDExLjcyNjU2MjUgMjgxLjUiIHJvbGU9ImdyYXBoaWNzLWRvY3VtZW50IGRvY3VtZW50IiBhcmlhLXJvbGVkZXNjcmlwdGlvbj0icmFpbHJvYWRFYm5mIj48c3R5bGU+I215LXN2Z3tmb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7Zm9udC1zaXplOjE2cHg7ZmlsbDojMzMzO31Aa2V5ZnJhbWVzIGVkZ2UtYW5pbWF0aW9uLWZyYW1le2Zyb217c3Ryb2tlLWRhc2hvZmZzZXQ6MDt9fUBrZXlmcmFtZXMgZGFzaHt0b3tzdHJva2UtZGFzaG9mZnNldDowO319I215LXN2ZyAuZWRnZS1hbmltYXRpb24tc2xvd3tzdHJva2UtZGFzaGFycmF5OjksNSFpbXBvcnRhbnQ7c3Ryb2tlLWRhc2hvZmZzZXQ6OTAwO2FuaW1hdGlvbjpkYXNoIDUwcyBsaW5lYXIgaW5maW5pdGU7c3Ryb2tlLWxpbmVjYXA6cm91bmQ7fSNteS1zdmcgLmVkZ2UtYW5pbWF0aW9uLWZhc3R7c3Ryb2tlLWRhc2hhcnJheTo5LDUhaW1wb3J0YW50O3N0cm9rZS1kYXNob2Zmc2V0OjkwMDthbmltYXRpb246ZGFzaCAyMHMgbGluZWFyIGluZmluaXRlO3N0cm9rZS1saW5lY2FwOnJvdW5kO30jbXktc3ZnIC5lcnJvci1pY29ue2ZpbGw6IzU1MjIyMjt9I215LXN2ZyAuZXJyb3ItdGV4dHtmaWxsOiM1NTIyMjI7c3Ryb2tlOiM1NTIyMjI7fSNteS1zdmcgLmVkZ2UtdGhpY2tuZXNzLW5vcm1hbHtzdHJva2Utd2lkdGg6MXB4O30jbXktc3ZnIC5lZGdlLXRoaWNrbmVzcy10aGlja3tzdHJva2Utd2lkdGg6My41cHg7fSNteS1zdmcgLmVkZ2UtcGF0dGVybi1zb2xpZHtzdHJva2UtZGFzaGFycmF5OjA7fSNteS1zdmcgLmVkZ2UtdGhpY2tuZXNzLWludmlzaWJsZXtzdHJva2Utd2lkdGg6MDtmaWxsOm5vbmU7fSNteS1zdmcgLmVkZ2UtcGF0dGVybi1kYXNoZWR7c3Ryb2tlLWRhc2hhcnJheTozO30jbXktc3ZnIC5lZGdlLXBhdHRlcm4tZG90dGVke3N0cm9rZS1kYXNoYXJyYXk6Mjt9I215LXN2ZyAubWFya2Vye2ZpbGw6IzMzMzMzMztzdHJva2U6IzMzMzMzMzt9I215LXN2ZyAubWFya2VyLmNyb3Nze3N0cm9rZTojMzMzMzMzO30jbXktc3ZnIHN2Z3tmb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7Zm9udC1zaXplOjE2cHg7fSNteS1zdmcgcHttYXJnaW46MDt9I215LXN2ZyAucmFpbHJvYWQtZGlhZ3JhbXtmb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7Zm9udC1zaXplOjE2cHg7fSNteS1zdmcgLnJhaWxyb2FkLXRlcm1pbmFsIHJlY3R7ZmlsbDojZmZmZmRlO3N0cm9rZTpoc2woNjAsIDYwJSwgODMuNTI5NDExNzY0NyUpO3N0cm9rZS13aWR0aDoycHg7fSNteS1zdmcgLnJhaWxyb2FkLXRlcm1pbmFsIHRleHR7ZmlsbDojMDAwMDIxO2ZvbnQtZmFtaWx5OiJ0cmVidWNoZXQgbXMiLHZlcmRhbmEsYXJpYWwsc2Fucy1zZXJpZjtmb250LXNpemU6MTZweDt0ZXh0LWFuY2hvcjptaWRkbGU7ZG9taW5hbnQtYmFzZWxpbmU6bWlkZGxlO30jbXktc3ZnIC5yYWlscm9hZC1ub250ZXJtaW5hbCByZWN0e2ZpbGw6I0VDRUNGRjtzdHJva2U6aHNsKDI0MCwgNjAlLCA4Ni4yNzQ1MDk4MDM5JSk7c3Ryb2tlLXdpZHRoOjJweDt9I215LXN2ZyAucmFpbHJvYWQtbm9udGVybWluYWwgdGV4dHtmaWxsOiMxMzEzMDA7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO2ZvbnQtc2l6ZToxNnB4O3RleHQtYW5jaG9yOm1pZGRsZTtkb21pbmFudC1iYXNlbGluZTptaWRkbGU7fSNteS1zdmcgLnJhaWxyb2FkLWxpbmV7c3Ryb2tlOiMzMzMzMzM7c3Ryb2tlLXdpZHRoOjJweDtmaWxsOm5vbmU7fSNteS1zdmcgLnJhaWxyb2FkLXN0YXJ0IGNpcmNsZSwjbXktc3ZnIC5yYWlscm9hZC1lbmQgY2lyY2xle2ZpbGw6IzMzMzMzMzt9I215LXN2ZyAucmFpbHJvYWQtY29tbWVudCBlbGxpcHNle2ZpbGw6cmdiYSgyMzIsMjMyLDIzMiwgMC44KTtzdHJva2U6aHNsKDgwLCA2MCUsIDg2LjI3NDUwOTgwMzklKTtzdHJva2Utd2lkdGg6MnB4O30jbXktc3ZnIC5yYWlscm9hZC1jb21tZW50IHRleHR7ZmlsbDpyZ2IoNi4zMzMzMzMzMzM0LCAwLCAxOS4wMDAwMDAwMDAxKTtmb250LXN0eWxlOml0YWxpYztmb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7Zm9udC1zaXplOjE2cHg7dGV4dC1hbmNob3I6bWlkZGxlO2RvbWluYW50LWJhc2VsaW5lOm1pZGRsZTt9I215LXN2ZyAucmFpbHJvYWQtc3BlY2lhbCByZWN0e2ZpbGw6aHNsKDgwLCAxMDAlLCA5Ni4yNzQ1MDk4MDM5JSk7c3Ryb2tlOmhzbCg4MCwgNjAlLCA4Ni4yNzQ1MDk4MDM5JSk7c3Ryb2tlLXdpZHRoOjJweDtzdHJva2UtZGFzaGFycmF5OjUsMzt9I215LXN2ZyAucmFpbHJvYWQtc3BlY2lhbCB0ZXh0e2ZpbGw6IzEzMTMwMDtmb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7Zm9udC1zaXplOjE2cHg7dGV4dC1hbmNob3I6bWlkZGxlO2RvbWluYW50LWJhc2VsaW5lOm1pZGRsZTt9I215LXN2ZyAucmFpbHJvYWQtcnVsZS1uYW1le2ZvbnQtd2VpZ2h0OmJvbGQ7ZmlsbDojMzMzO2ZvbnQtZmFtaWx5OiJ0cmVidWNoZXQgbXMiLHZlcmRhbmEsYXJpYWwsc2Fucy1zZXJpZjtmb250LXNpemU6MTZweDt9I215LXN2ZyAubm9kZSAubmVvLW5vZGV7c3Ryb2tlOiM5MzcwREI7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSByZWN0LCNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uY2x1c3RlciByZWN0LCNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSBwb2x5Z29ue3N0cm9rZTojOTM3MERCO2ZpbHRlcjpkcm9wLXNoYWRvdygxcHggMnB4IDJweCByZ2JhKDE4NSwgMTg1LCAxODUsIDEpKTt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5zd2ltbGFuZS5jbHVzdGVyIHJlY3R7ZmlsdGVyOm5vbmU7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSBwYXRoe3N0cm9rZTojOTM3MERCO3N0cm9rZS13aWR0aDoxcHg7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSAub3V0ZXItcGF0aHtmaWx0ZXI6ZHJvcC1zaGFkb3coMXB4IDJweCAycHggcmdiYSgxODUsIDE4NSwgMTg1LCAxKSk7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSAubmVvLWxpbmUgcGF0aHtzdHJva2U6IzkzNzBEQjtmaWx0ZXI6bm9uZTt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIGNpcmNsZXtzdHJva2U6IzkzNzBEQjtmaWx0ZXI6ZHJvcC1zaGFkb3coMXB4IDJweCAycHggcmdiYSgxODUsIDE4NSwgMTg1LCAxKSk7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSBjaXJjbGUgLnN0YXRlLXN0YXJ0e2ZpbGw6IzAwMDAwMDt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5pY29uLXNoYXBlIC5pY29ue2ZpbGw6IzkzNzBEQjtmaWx0ZXI6ZHJvcC1zaGFkb3coMXB4IDJweCAycHggcmdiYSgxODUsIDE4NSwgMTg1LCAxKSk7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uaWNvbi1zaGFwZSAuaWNvbi1uZW8gcGF0aHtzdHJva2U6IzkzNzBEQjtmaWx0ZXI6ZHJvcC1zaGFkb3coMXB4IDJweCAycHggcmdiYSgxODUsIDE4NSwgMTg1LCAxKSk7fSNteS1zdmcgOnJvb3R7LS1tZXJtYWlkLWZvbnQtZmFtaWx5OiJ0cmVidWNoZXQgbXMiLHZlcmRhbmEsYXJpYWwsc2Fucy1zZXJpZjt9PC9zdHlsZT48Zy8+PGcgY2xhc3M9InJhaWxyb2FkLXJ1bGUiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDAsIDEwKSI+PGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoOTEuODc1LCAwKSI+PGcgY2xhc3M9InJhaWxyb2FkLXNlcXVlbmNlIj48ZyBjbGFzcz0icmFpbHJvYWQtdGVybWluYWwiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDAsIDIwKSI+PHJlY3QgeD0iMCIgeT0iMCIgd2lkdGg9IjU3LjM5ODQzNzUiIGhlaWdodD0iMzkiIHJ4PSIxMCIgcnk9IjEwIi8+PHRleHQgeD0iMjguNjk5MjE4NzUiIHk9IjE5LjUiPlBPU1Q8L3RleHQ+PC9nPjxwYXRoIGNsYXNzPSJyYWlscm9hZC1saW5lIiBkPSJNIDU3LjM5ODQzNzUgMzkuNSBMIDY3LjM5ODQzNzUgMzkuNSIvPjxnIGNsYXNzPSJyYWlscm9hZC1ub250ZXJtaW5hbCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNjcuMzk4NDM3NSwgMjApIj48cmVjdCB4PSIwIiB5PSIwIiB3aWR0aD0iNTIuNjY0MDYyNSIgaGVpZ2h0PSIzOSIvPjx0ZXh0IHg9IjI2LjMzMjAzMTI1IiB5PSIxOS41Ij5wYXRoPC90ZXh0PjwvZz48cGF0aCBjbGFzcz0icmFpbHJvYWQtbGluZSIgZD0iTSAxMjAuMDYyNSAzOS41IEwgMTMwLjA2MjUgMzkuNSIvPjxnIGNsYXNzPSJyYWlscm9hZC1vcHRpb25hbCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMTMwLjA2MjUsIDApIj48ZyBjbGFzcz0icmFpbHJvYWQtc2VxdWVuY2UiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDIwLCAyMCkiPjxnIGNsYXNzPSJyYWlscm9hZC10ZXJtaW5hbCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMCwgMCkiPjxyZWN0IHg9IjAiIHk9IjAiIHdpZHRoPSI0My4xODc1IiBoZWlnaHQ9IjM5IiByeD0iMTAiIHJ5PSIxMCIvPjx0ZXh0IHg9IjIxLjU5Mzc1IiB5PSIxOS41Ij4/cT08L3RleHQ+PC9nPjxwYXRoIGNsYXNzPSJyYWlscm9hZC1saW5lIiBkPSJNIDQzLjE4NzUgMTkuNSBMIDUzLjE4NzUgMTkuNSIvPjxnIGNsYXNzPSJyYWlscm9hZC1ub250ZXJtaW5hbCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNTMuMTg3NSwgMCkiPjxyZWN0IHg9IjAiIHk9IjAiIHdpZHRoPSI2MS42MDE1NjI1IiBoZWlnaHQ9IjM5Ii8+PHRleHQgeD0iMzAuODAwNzgxMjUiIHk9IjE5LjUiPnF1ZXJ5PC90ZXh0PjwvZz48L2c+PHBhdGggY2xhc3M9InJhaWxyb2FkLWxpbmUiIGQ9Ik0gMCAzOS41IEwgMjAgMzkuNSIvPjxwYXRoIGNsYXNzPSJyYWlscm9hZC1saW5lIiBkPSJNIDEzNC43ODkwNjI1IDM5LjUgTCAxNTQuNzg5MDYyNSAzOS41Ii8+PHBhdGggY2xhc3M9InJhaWxyb2FkLWxpbmUiIGQ9Ik0gMCAzOS41IEEgMTAgMTAgMCAwIDAgMTAgMjkuNSBMIDEwIDEwIEEgMTAgMTAgMCAwIDEgMjAgMCBMIDEzNC43ODkwNjI1IDAgQSAxMCAxMCAwIDAgMSAxNDQuNzg5MDYyNSAxMCBMIDE0NC43ODkwNjI1IDI5LjUgQSAxMCAxMCAwIDAgMCAxNTQuNzg5MDYyNSAzOS41Ii8+PC9nPjwvZz48L2c+PGcgY2xhc3M9InJhaWxyb2FkLXJ1bGUtbmFtZS1ncm91cCI+PHRleHQgY2xhc3M9InJhaWxyb2FkLXJ1bGUtbmFtZSIgeD0iMCIgeT0iMzkuNSI+b3JkZXIgPTwvdGV4dD48L2c+PGcgY2xhc3M9InJhaWxyb2FkLXN0YXJ0Ij48Y2lyY2xlIGN4PSI3MS44NzUiIGN5PSIzOS41IiByPSI1Ii8+PC9nPjxnIGNsYXNzPSJyYWlscm9hZC1lbmQiPjxjaXJjbGUgY3g9IjM4Ni43MjY1NjI1IiBjeT0iMzkuNSIgcj0iNSIvPjwvZz48cGF0aCBjbGFzcz0icmFpbHJvYWQtbGluZSIgZD0iTSA3Ni44NzUgMzkuNSBMIDkxLjg3NSAzOS41Ii8+PHBhdGggY2xhc3M9InJhaWxyb2FkLWxpbmUiIGQ9Ik0gMzc2LjcyNjU2MjUgMzkuNSBMIDM4MS43MjY1NjI1IDM5LjUiLz48L2c+PGcgY2xhc3M9InJhaWxyb2FkLXJ1bGUiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDAsIDk3KSI+PGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoODUuNjI1LCAwLjUpIj48ZyBjbGFzcz0icmFpbHJvYWQtdGVybWluYWwiPjxyZWN0IHg9IjAiIHk9IjAiIHdpZHRoPSI3NC4wNTQ2ODc1IiBoZWlnaHQ9IjM5IiByeD0iMTAiIHJ5PSIxMCIvPjx0ZXh0IHg9IjM3LjAyNzM0Mzc1IiB5PSIxOS41Ij4vb3JkZXJzPC90ZXh0PjwvZz48L2c+PGcgY2xhc3M9InJhaWxyb2FkLXJ1bGUtbmFtZS1ncm91cCI+PHRleHQgY2xhc3M9InJhaWxyb2FkLXJ1bGUtbmFtZSIgeD0iMCIgeT0iMjAiPnBhdGggPTwvdGV4dD48L2c+PGcgY2xhc3M9InJhaWxyb2FkLXN0YXJ0Ij48Y2lyY2xlIGN4PSI2NS42MjUiIGN5PSIyMCIgcj0iNSIvPjwvZz48ZyBjbGFzcz0icmFpbHJvYWQtZW5kIj48Y2lyY2xlIGN4PSIxNjkuNjc5Njg3NSIgY3k9IjIwIiByPSI1Ii8+PC9nPjxwYXRoIGNsYXNzPSJyYWlscm9hZC1saW5lIiBkPSJNIDcwLjYyNSAyMCBMIDg1LjYyNSAyMCIvPjxwYXRoIGNsYXNzPSJyYWlscm9hZC1saW5lIiBkPSJNIDE1OS42Nzk2ODc1IDIwIEwgMTY0LjY3OTY4NzUgMjAiLz48L2c+PGcgY2xhc3M9InJhaWxyb2FkLXJ1bGUiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDAsIDE2NC41KSI+PGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoOTMuNzAzMTI1LCAwKSI+PGcgY2xhc3M9InJhaWxyb2FkLXJlcGV0aXRpb24iPjxnIGNsYXNzPSJyYWlscm9hZC1vcHRpb25hbCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMjAsIDApIj48ZyBjbGFzcz0icmFpbHJvYWQtbm9udGVybWluYWwiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDIwLCAyMCkiPjxyZWN0IHg9IjAiIHk9IjAiIHdpZHRoPSI4OS42NTYyNSIgaGVpZ2h0PSIzOSIvPjx0ZXh0IHg9IjQ0LjgyODEyNSIgeT0iMTkuNSI+QS1aYS16MC05PC90ZXh0PjwvZz48cGF0aCBjbGFzcz0icmFpbHJvYWQtbGluZSIgZD0iTSAwIDM5LjUgTCAyMCAzOS41Ii8+PHBhdGggY2xhc3M9InJhaWxyb2FkLWxpbmUiIGQ9Ik0gMTA5LjY1NjI1IDM5LjUgTCAxMjkuNjU2MjUgMzkuNSIvPjxwYXRoIGNsYXNzPSJyYWlscm9hZC1saW5lIiBkPSJNIDAgMzkuNSBBIDEwIDEwIDAgMCAwIDEwIDI5LjUgTCAxMCAxMCBBIDEwIDEwIDAgMCAxIDIwIDAgTCAxMDkuNjU2MjUgMCBBIDEwIDEwIDAgMCAxIDExOS42NTYyNSAxMCBMIDExOS42NTYyNSAyOS41IEEgMTAgMTAgMCAwIDAgMTI5LjY1NjI1IDM5LjUiLz48L2c+PHBhdGggY2xhc3M9InJhaWxyb2FkLWxpbmUiIGQ9Ik0gMCAzOS41IEwgMjAgMzkuNSIvPjxwYXRoIGNsYXNzPSJyYWlscm9hZC1saW5lIiBkPSJNIDE0OS42NTYyNSAzOS41IEwgMTY5LjY1NjI1IDM5LjUiLz48cGF0aCBjbGFzcz0icmFpbHJvYWQtbGluZSIgZD0iTSAxNDkuNjU2MjUgMzkuNSBBIDEwIDEwIDAgMCAxIDE1OS42NTYyNSA0OS41IEwgMTU5LjY1NjI1IDY5IEEgMTAgMTAgMCAwIDEgMTQ5LjY1NjI1IDc5IEwgMjAgNzkgQSAxMCAxMCAwIDAgMSAxMCA2OSBMIDEwIDQ5LjUgQSAxMCAxMCAwIDAgMSAyMCAzOS41Ii8+PC9nPjwvZz48ZyBjbGFzcz0icmFpbHJvYWQtcnVsZS1uYW1lLWdyb3VwIj48dGV4dCBjbGFzcz0icmFpbHJvYWQtcnVsZS1uYW1lIiB4PSIwIiB5PSIzOS41Ij5xdWVyeSA9PC90ZXh0PjwvZz48ZyBjbGFzcz0icmFpbHJvYWQtc3RhcnQiPjxjaXJjbGUgY3g9IjczLjcwMzEyNSIgY3k9IjM5LjUiIHI9IjUiLz48L2c+PGcgY2xhc3M9InJhaWxyb2FkLWVuZCI+PGNpcmNsZSBjeD0iMjczLjM1OTM3NSIgY3k9IjM5LjUiIHI9IjUiLz48L2c+PHBhdGggY2xhc3M9InJhaWxyb2FkLWxpbmUiIGQ9Ik0gNzguNzAzMTI1IDM5LjUgTCA5My43MDMxMjUgMzkuNSIvPjxwYXRoIGNsYXNzPSJyYWlscm9hZC1saW5lIiBkPSJNIDI2My4zNTkzNzUgMzkuNSBMIDI2OC4zNTkzNzUgMzkuNSIvPjwvZz48L3N2Zz4=) The track shows the legal sentence: `POST /orders` optionally followed by a query parameter. Language designers and API authors put this next to the reference — a grammar that parses by eye beats a regex nobody dares to edit. ## Choosing the structure-and-capability shape[​](#choosing-the-structure-and-capability-shape "Direct link to Choosing the structure-and-capability shape") | The 'shape' of the doc | Diagram | Mermaid keyword | | ------------------------------ | ------------ | -------------------- | | Compare profiles along axes | **Radar** | `radar-beta` | | Show a tree / folder structure | **TreeView** | `treeView-beta` | | Show syntax / grammar | **Railroad** | `railroad-ebnf-beta` | | Show quantity flowing | **Sankey** | `sankey-beta` | Radar answers "how capable, across axes," treeView answers "what lives where," railroad answers "what is legal input." The docs neighbors are on the same wiki: the **capabilities** behind the roadmap as [prioritization charts](/blog/mermaid-roadmap-prioritization-charts-confluence.md) and the **team processes** the skills feed as [workflow swimlanes](/blog/mermaid-process-flow-swimlane-diagram-confluence.md). ## FAQ[​](#faq "Direct link to FAQ") **Does Confluence have a built-in radar or skill matrix tool?** No — Confluence has no native charting of this kind. Mermaid Plus Diagrams & AI Agent for Confluence renders `radar-beta`, `treeView-beta` and `railroad-ebnf-beta` from editable text with a live preview. **Radar, treeView or railroad — which does this doc need?** Radar for multi-axis comparison, treeView for structure, railroad for grammar. The material's shape chooses the tool. **How do I represent team skills in a radar chart?** Define `axis` dimensions, then one `curve` per profile with same-order scores and a fixed `max`. **When should I document a repo as treeView?** When the structure teaches the codebase — entry points, folder roles, client boundaries. Keep it a map, not a file dump. Render every Mermaid diagram type — radar, treeView, railroad, sankey, venn and 24 more — in [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), free for up to 10 users. Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [radar-chart](/blog/tags/radar-chart.md) * [treeview](/blog/tags/treeview.md) * [railroad](/blog/tags/railroad.md) * [skills](/blog/tags/skills.md) * [how-to](/blog/tags/how-to.md) --- # Requirements Traceability in Confluence with Mermaid Requirement Diagrams September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The feature ships with a test suite that validates four scenarios. The PRD lists seven requirements. The compliance review asks "which requirement is the encryption actually in scope for?" — and the answer is a spreadsheet cross-referenced by color, maintained by one person, last updated before the sprint began. Traceability does not scale as a spreadsheet; it scales as a diagram that *is* the trace. **Quick answer:** document requirements traceability in Confluence as Mermaid `requirementDiagram`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Each requirement connects to the elements that satisfy and verify it — the gaps read at a glance, and the whole thing stays editable text next to the PRD. This post gives you three copy-paste examples: a feature trace, a compliance control, and an epic-to-test gap review. ## Why traceability cannot live in a spreadsheet[​](#why-traceability-cannot-live-in-a-spreadsheet "Direct link to Why traceability cannot live in a spreadsheet") A requirements traceability matrix (RTM) answers one question: *does every requirement have something that satisfies it, and something that verifies it?* Spreadsheets answer it slowly and rot fast—colors shift, rows drift, and the "x" that means "covered" is a human's memory. A requirement diagram answers it structurally: * **What must exist?** The requirements, each a named block with its priority and verification class * **What delivers it?** The elements that satisfy each requirement * **What proves it?** The elements that verify it Draw those relations and the diagram becomes a coverage report you can read in one pass. A requirement with no `verifies` arrow is a test-writing ticket, visible without opening the test suite. ## Copy-paste 1: the feature trace[​](#copy-paste-1-the-feature-trace "Direct link to Copy-paste 1: the feature trace") Start with the unit every team recognizes — a feature and its requirements. Mermaid requirement blocks carry the metadata an RTM column set had: ``` requirementDiagram %% title: Payment retry feature — traceability requirement pay_retry { id: "REQ-1401" text: payment retry with backoff risk: medium verifymethod: test } requirement pay_log { id: "REQ-1402" text: retry attempts logged risk: low verifymethod: inspection } element retry_impl { type: implementation docref: PaymentService.retry() } element retry_test { type: "test" docref: retries_spec.mjs } element logger_impl { type: implementation docref: audit.ts } element logger_test { type: "test" docref: audit_log_spec.ts } retry_impl - satisfies -> pay_retry retry_test - verifies -> pay_retry logger_impl - satisfies -> pay_log logger_test - verifies -> pay_log ``` ![Payment retry feature — traceability](/assets/images/payment-retry-feature-traceability-5ffabadde98ab34c5a368f8670876cbb.svg) Each requirement names its `verifymethod` (`test` vs `inspection` — note it cannot be called `demo`), and each element points at a `docref` for the actual file. The quartet under `pay_retry` — implementation, test, requirement, link — is the entire audit trail of a feature line. ## Copy-paste 2: the compliance control[​](#copy-paste-2-the-compliance-control "Direct link to Copy-paste 2: the compliance control") Compliance reviews run on one question per control: "show me what implements this and what proves it". That is literally the structure of a requirement diagram: ``` requirementDiagram %% title: Data-at-rest encryption control requirement enc_control { id: "CTRL-2101" text: all customer data encrypted at rest risk: high verifymethod: analysis } requirement key_rotation { id: "CTRL-2102" text: keys rotated within 90 days risk: high verifymethod: test } element enc_impl { type: implementation docref: "storage-layer" } element enc_audit { type: architecture docref: "architecture-review-2026-09" } element rotation_test { type: "test" docref: rotation_policy_spec.js } element rotation_job { type: implementation docref: rotation_job.cron } enc_impl - satisfies -> enc_control enc_audit - verifies -> enc_control rotation_job - satisfies -> key_rotation rotation_test - verifies -> key_rotation ``` ![Data-at-rest encryption control](/assets/images/data-at-rest-encryption-control-22315d50edab5ca55094a492065f85c3.svg) The auditor reads one page: `CTRL-2101` is satisfied by the storage layer and verified by the architecture review; `CTRL-2102` is satisfied by the cron job and verified by the policy spec. Elements of different types surface the different proof kinds — an implementation satisfies, an architecture approval verifies. The spreadsheet melts into the diagram. ## Copy-paste 3: the epic-to-test gap review[​](#copy-paste-3-the-epic-to-test-gap-review "Direct link to Copy-paste 3: the epic-to-test gap review") The sharpest use is the sprint-boundary check: is every requirement of the epic satisfied *and* verified? The diagram makes the gaps the visual: ``` requirementDiagram %% title: Checkout epic — coverage at sprint boundary requirement cart_req { id: "REQ-2201" text: cart persists across sessions risk: medium verifymethod: test } requirement promo_req { id: "REQ-2202" text: promo codes apply before tax risk: high verifymethod: test } element cart_impl { type: implementation docref: "cart-store.ts" } element promo_impl { type: implementation docref: "pricing-engine.ts" } cart_impl - satisfies -> cart_req cart_impl - verifies -> cart_req promo_impl - satisfies -> promo_req ``` ![Checkout epic — coverage at sprint boundary](/assets/images/checkout-epic-coverage-at-sprint-boundary-0364f081468cf1582140a77243528dad.svg) Read the bottom right: `promo_req` is *satisfied* (the pricing engine implements it) but has no `verifies` arrow — the epic ships code for the high-risk requirement and no test proves it. That missing arrow is the conversation to have *before* the sprint closes, not after the incident. This is the diagram to refresh at every sprint boundary. ## Traceability as a habit, not an artifact[​](#traceability-as-a-habit-not-an-artifact "Direct link to Traceability as a habit, not an artifact") Like every Mermaid diagram, a requirement diagram is durable only when it is treated as living text. In [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), the requirement block sits next to the PRD it traces, edited in the same change that edits the PRD — requirement added, diagram row added; test written, `verifies` arrow added. The coverage report stops being a quarterly spreadsheet ceremony and becomes the diagram the whole team sees on the page. The discipline is the payoff: keep requirements and elements in two explicit lists, connect them with `satisfies`/`verifies`/`traces`, and read the holes. A requirements diagram that shows the gaps is worth more than a matrix that hides them. ## Where this lives beside your other Confluence diagrams[​](#where-this-lives-beside-your-other-confluence-diagrams "Direct link to Where this lives beside your other Confluence diagrams") Requirement diagrams cover the "what and how it's proven" half; the other types cover the rest. Keep the traceability on the PRD page (this post), the workflow that turns requirements into shippable work as a state diagram ([states & approval workflows](/blog/mermaid-state-diagram-workflow-confluence.md)), and the architectural surface the requirements touch as a class diagram ([class diagrams for your codebase](/blog/mermaid-class-diagram-document-codebase-confluence.md)). One space, three diagram types, and the coverage story always visible. ## FAQ[​](#faq "Direct link to FAQ") **What is a Mermaid requirement diagram in Confluence?** A structured chart of requirements connected to the elements that satisfy and verify them — a mini traceability matrix rendered from a text block. Mermaid Plus Diagrams & AI Agent for Confluence renders it live as you type. **How is traceability shown in a Mermaid requirement diagram?** A requirement sits above the elements that prove it, joined by 'satisfies', 'verifies', 'contains' and 'traces' relations. A requirement with no 'verifies' arrow is an untested line, visible in one pass. **Can it be used for compliance (data claims, PCI, SOC 2)?** Yes — model the control as a requirement and its implementation + evidence as elements with 'satisfies' and 'verifies'. A compliance review then reads one page instead of a spreadsheet. **How often should the requirement diagram be updated?** Update it in the same change that writes or changes a requirement — the diagram is the PRD's coverage report. If it lags a sprint, the untested-lines problem it was meant to reveal reappears. Render every Mermaid diagram type — requirement, class, state, pie, flowchart and 24 more — in [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), free for up to 10 users. Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [requirement-diagram](/blog/tags/requirement-diagram.md) * [traceability](/blog/tags/traceability.md) * [prd](/blog/tags/prd.md) * [how-to](/blog/tags/how-to.md) --- # Roadmap & Prioritization Charts in Confluence with Mermaid September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The quarter plan is a spreadsheet with thirty rows, color-coded by priority, sorted by a column half the team doesn't trust. The kickoff asks "what are we doing when — and why this first?" and the answer requires parsing three tabs. Planning outputs are *shapes*: schedules stack as bars, priorities sit on a 2x2, flows bundle as ribbons. The spreadsheet stores them poorly; Mermaid draws them as text. **Quick answer:** put the quarter plan in Confluence as Mermaid — `gantt` for when things happen, `quadrantChart` for which gets built first, `sankey-beta` for where the budget goes — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Three charts, three planning questions, one editable page. This post gives you three copy-paste examples. ## Why planning needs shapes, not sorted rows[​](#why-planning-needs-shapes-not-sorted-rows "Direct link to Why planning needs shapes, not sorted rows") Plans fail in the *distribution* — where the bars overlap, which item is top-left on effort/impact, how much flow is leaking to overrun. Three questions need three chart shapes: * **When?** → **Gantt.** Bars, sections, dependencies, milestones. The schedule is the answer. * **Which first?** → **Quadrant.** Every item plotted on effort vs impact. The top-left block is the shortlist. * **Where does it go?** → **Sankey.** Quantities flowing from source to use. The leak is the answer. All three are wrung out of the same planning input — items, dates or effort, and amounts — which means all three live on one roadmap page and update in the same pass. ## Copy-paste 1: the quarter's Gantt[​](#copy-paste-1-the-quarters-gantt "Direct link to Copy-paste 1: the quarter's Gantt") Sections group the workstreams; task lines carry durations; `after` links the blockers. Dates in the `YYYY-MM-DD` format Mermaid expects: ``` gantt title Q3 Roadmap dateFormat YYYY-MM-DD section Platform Orders API :a1, 2026-10-01, 15d Payments revamp :after a1, 20d section Data Reporting dash :b1, 2026-10-08, 18d Export refresh :after b1, 12d section Release Q3 launch :milestone, 2026-11-14, 0d ``` ![Q3 Roadmap](data:image/svg+xml;base64,PHN2ZyBpZD0ibXktc3ZnIiB3aWR0aD0iMTAwJSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgdmlld0JveD0iMCAwIDc4NCAyMjAiIHN0eWxlPSJtYXgtd2lkdGg6IDc4NHB4OyBiYWNrZ3JvdW5kLWNvbG9yOiB3aGl0ZTsiIHJvbGU9ImdyYXBoaWNzLWRvY3VtZW50IGRvY3VtZW50IiBhcmlhLXJvbGVkZXNjcmlwdGlvbj0iZ2FudHQiPjxzdHlsZT4jbXktc3Zne2ZvbnQtZmFtaWx5OiJ0cmVidWNoZXQgbXMiLHZlcmRhbmEsYXJpYWwsc2Fucy1zZXJpZjtmb250LXNpemU6MTZweDtmaWxsOiMzMzM7fUBrZXlmcmFtZXMgZWRnZS1hbmltYXRpb24tZnJhbWV7ZnJvbXtzdHJva2UtZGFzaG9mZnNldDowO319QGtleWZyYW1lcyBkYXNoe3Rve3N0cm9rZS1kYXNob2Zmc2V0OjA7fX0jbXktc3ZnIC5lZGdlLWFuaW1hdGlvbi1zbG93e3N0cm9rZS1kYXNoYXJyYXk6OSw1IWltcG9ydGFudDtzdHJva2UtZGFzaG9mZnNldDo5MDA7YW5pbWF0aW9uOmRhc2ggNTBzIGxpbmVhciBpbmZpbml0ZTtzdHJva2UtbGluZWNhcDpyb3VuZDt9I215LXN2ZyAuZWRnZS1hbmltYXRpb24tZmFzdHtzdHJva2UtZGFzaGFycmF5OjksNSFpbXBvcnRhbnQ7c3Ryb2tlLWRhc2hvZmZzZXQ6OTAwO2FuaW1hdGlvbjpkYXNoIDIwcyBsaW5lYXIgaW5maW5pdGU7c3Ryb2tlLWxpbmVjYXA6cm91bmQ7fSNteS1zdmcgLmVycm9yLWljb257ZmlsbDojNTUyMjIyO30jbXktc3ZnIC5lcnJvci10ZXh0e2ZpbGw6IzU1MjIyMjtzdHJva2U6IzU1MjIyMjt9I215LXN2ZyAuZWRnZS10aGlja25lc3Mtbm9ybWFse3N0cm9rZS13aWR0aDoxcHg7fSNteS1zdmcgLmVkZ2UtdGhpY2tuZXNzLXRoaWNre3N0cm9rZS13aWR0aDozLjVweDt9I215LXN2ZyAuZWRnZS1wYXR0ZXJuLXNvbGlke3N0cm9rZS1kYXNoYXJyYXk6MDt9I215LXN2ZyAuZWRnZS10aGlja25lc3MtaW52aXNpYmxle3N0cm9rZS13aWR0aDowO2ZpbGw6bm9uZTt9I215LXN2ZyAuZWRnZS1wYXR0ZXJuLWRhc2hlZHtzdHJva2UtZGFzaGFycmF5OjM7fSNteS1zdmcgLmVkZ2UtcGF0dGVybi1kb3R0ZWR7c3Ryb2tlLWRhc2hhcnJheToyO30jbXktc3ZnIC5tYXJrZXJ7ZmlsbDojMzMzMzMzO3N0cm9rZTojMzMzMzMzO30jbXktc3ZnIC5tYXJrZXIuY3Jvc3N7c3Ryb2tlOiMzMzMzMzM7fSNteS1zdmcgc3Zne2ZvbnQtZmFtaWx5OiJ0cmVidWNoZXQgbXMiLHZlcmRhbmEsYXJpYWwsc2Fucy1zZXJpZjtmb250LXNpemU6MTZweDt9I215LXN2ZyBwe21hcmdpbjowO30jbXktc3ZnIC5tZXJtYWlkLW1haW4tZm9udHtmb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7fSNteS1zdmcgLmV4Y2x1ZGUtcmFuZ2V7ZmlsbDojZWVlZWVlO30jbXktc3ZnIC5zZWN0aW9ue3N0cm9rZTpub25lO29wYWNpdHk6MC4yO30jbXktc3ZnIC5zZWN0aW9uMHtmaWxsOnJnYmEoMTAyLCAxMDIsIDI1NSwgMC40OSk7fSNteS1zdmcgLnNlY3Rpb24ye2ZpbGw6I2ZmZjQwMDt9I215LXN2ZyAuc2VjdGlvbjEsI215LXN2ZyAuc2VjdGlvbjN7ZmlsbDp3aGl0ZTtvcGFjaXR5OjAuMjt9I215LXN2ZyAuc2VjdGlvblRpdGxlMHtmaWxsOiMzMzM7fSNteS1zdmcgLnNlY3Rpb25UaXRsZTF7ZmlsbDojMzMzO30jbXktc3ZnIC5zZWN0aW9uVGl0bGUye2ZpbGw6IzMzMzt9I215LXN2ZyAuc2VjdGlvblRpdGxlM3tmaWxsOiMzMzM7fSNteS1zdmcgLnNlY3Rpb25UaXRsZXt0ZXh0LWFuY2hvcjpzdGFydDtmb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7fSNteS1zdmcgLmdyaWQgLnRpY2t7c3Ryb2tlOmxpZ2h0Z3JleTtvcGFjaXR5OjAuODtzaGFwZS1yZW5kZXJpbmc6Y3Jpc3BFZGdlczt9I215LXN2ZyAuZ3JpZCAudGljayB0ZXh0e2ZvbnQtZmFtaWx5OiJ0cmVidWNoZXQgbXMiLHZlcmRhbmEsYXJpYWwsc2Fucy1zZXJpZjtmaWxsOiMzMzM7fSNteS1zdmcgLmdyaWQgcGF0aHtzdHJva2Utd2lkdGg6MDt9I215LXN2ZyAudG9kYXl7ZmlsbDpub25lO3N0cm9rZTpyZWQ7c3Ryb2tlLXdpZHRoOjJweDt9I215LXN2ZyAudGFza3tzdHJva2Utd2lkdGg6Mjt9I215LXN2ZyAudGFza1RleHR7dGV4dC1hbmNob3I6bWlkZGxlO2ZvbnQtZmFtaWx5OiJ0cmVidWNoZXQgbXMiLHZlcmRhbmEsYXJpYWwsc2Fucy1zZXJpZjt9I215LXN2ZyAudGFza1RleHRPdXRzaWRlUmlnaHR7ZmlsbDpibGFjazt0ZXh0LWFuY2hvcjpzdGFydDtmb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7fSNteS1zdmcgLnRhc2tUZXh0T3V0c2lkZUxlZnR7ZmlsbDpibGFjazt0ZXh0LWFuY2hvcjplbmQ7fSNteS1zdmcgLnRhc2suY2xpY2thYmxle2N1cnNvcjpwb2ludGVyO30jbXktc3ZnIC50YXNrVGV4dC5jbGlja2FibGV7Y3Vyc29yOnBvaW50ZXI7ZmlsbDojMDAzMTYzIWltcG9ydGFudDtmb250LXdlaWdodDpib2xkO30jbXktc3ZnIC50YXNrVGV4dE91dHNpZGVMZWZ0LmNsaWNrYWJsZXtjdXJzb3I6cG9pbnRlcjtmaWxsOiMwMDMxNjMhaW1wb3J0YW50O2ZvbnQtd2VpZ2h0OmJvbGQ7fSNteS1zdmcgLnRhc2tUZXh0T3V0c2lkZVJpZ2h0LmNsaWNrYWJsZXtjdXJzb3I6cG9pbnRlcjtmaWxsOiMwMDMxNjMhaW1wb3J0YW50O2ZvbnQtd2VpZ2h0OmJvbGQ7fSNteS1zdmcgLnRhc2tUZXh0MCwjbXktc3ZnIC50YXNrVGV4dDEsI215LXN2ZyAudGFza1RleHQyLCNteS1zdmcgLnRhc2tUZXh0M3tmaWxsOndoaXRlO30jbXktc3ZnIC50YXNrMCwjbXktc3ZnIC50YXNrMSwjbXktc3ZnIC50YXNrMiwjbXktc3ZnIC50YXNrM3tmaWxsOiM4YTkwZGQ7c3Ryb2tlOiM1MzRmYmM7fSNteS1zdmcgLnRhc2tUZXh0T3V0c2lkZTAsI215LXN2ZyAudGFza1RleHRPdXRzaWRlMntmaWxsOmJsYWNrO30jbXktc3ZnIC50YXNrVGV4dE91dHNpZGUxLCNteS1zdmcgLnRhc2tUZXh0T3V0c2lkZTN7ZmlsbDpibGFjazt9I215LXN2ZyAuYWN0aXZlMCwjbXktc3ZnIC5hY3RpdmUxLCNteS1zdmcgLmFjdGl2ZTIsI215LXN2ZyAuYWN0aXZlM3tmaWxsOiNiZmM3ZmY7c3Ryb2tlOiM1MzRmYmM7fSNteS1zdmcgLmFjdGl2ZVRleHQwLCNteS1zdmcgLmFjdGl2ZVRleHQxLCNteS1zdmcgLmFjdGl2ZVRleHQyLCNteS1zdmcgLmFjdGl2ZVRleHQze2ZpbGw6YmxhY2shaW1wb3J0YW50O30jbXktc3ZnIC5kb25lMCwjbXktc3ZnIC5kb25lMSwjbXktc3ZnIC5kb25lMiwjbXktc3ZnIC5kb25lM3tzdHJva2U6Z3JleTtmaWxsOmxpZ2h0Z3JleTtzdHJva2Utd2lkdGg6Mjt9I215LXN2ZyAuZG9uZVRleHQwLCNteS1zdmcgLmRvbmVUZXh0MSwjbXktc3ZnIC5kb25lVGV4dDIsI215LXN2ZyAuZG9uZVRleHQze2ZpbGw6YmxhY2shaW1wb3J0YW50O30jbXktc3ZnIC5kb25lVGV4dDAudGFza1RleHRPdXRzaWRlTGVmdCwjbXktc3ZnIC5kb25lVGV4dDAudGFza1RleHRPdXRzaWRlUmlnaHQsI215LXN2ZyAuZG9uZVRleHQxLnRhc2tUZXh0T3V0c2lkZUxlZnQsI215LXN2ZyAuZG9uZVRleHQxLnRhc2tUZXh0T3V0c2lkZVJpZ2h0LCNteS1zdmcgLmRvbmVUZXh0Mi50YXNrVGV4dE91dHNpZGVMZWZ0LCNteS1zdmcgLmRvbmVUZXh0Mi50YXNrVGV4dE91dHNpZGVSaWdodCwjbXktc3ZnIC5kb25lVGV4dDMudGFza1RleHRPdXRzaWRlTGVmdCwjbXktc3ZnIC5kb25lVGV4dDMudGFza1RleHRPdXRzaWRlUmlnaHR7ZmlsbDpibGFjayFpbXBvcnRhbnQ7fSNteS1zdmcgLmNyaXQwLCNteS1zdmcgLmNyaXQxLCNteS1zdmcgLmNyaXQyLCNteS1zdmcgLmNyaXQze3N0cm9rZTojZmY4ODg4O2ZpbGw6cmVkO3N0cm9rZS13aWR0aDoyO30jbXktc3ZnIC5hY3RpdmVDcml0MCwjbXktc3ZnIC5hY3RpdmVDcml0MSwjbXktc3ZnIC5hY3RpdmVDcml0MiwjbXktc3ZnIC5hY3RpdmVDcml0M3tzdHJva2U6I2ZmODg4ODtmaWxsOiNiZmM3ZmY7c3Ryb2tlLXdpZHRoOjI7fSNteS1zdmcgLmRvbmVDcml0MCwjbXktc3ZnIC5kb25lQ3JpdDEsI215LXN2ZyAuZG9uZUNyaXQyLCNteS1zdmcgLmRvbmVDcml0M3tzdHJva2U6I2ZmODg4ODtmaWxsOmxpZ2h0Z3JleTtzdHJva2Utd2lkdGg6MjtjdXJzb3I6cG9pbnRlcjtzaGFwZS1yZW5kZXJpbmc6Y3Jpc3BFZGdlczt9I215LXN2ZyAubWlsZXN0b25le3RyYW5zZm9ybTpyb3RhdGUoNDVkZWcpIHNjYWxlKDAuOCwwLjgpO30jbXktc3ZnIC5taWxlc3RvbmVUZXh0e2ZvbnQtc3R5bGU6aXRhbGljO30jbXktc3ZnIC5kb25lQ3JpdFRleHQwLCNteS1zdmcgLmRvbmVDcml0VGV4dDEsI215LXN2ZyAuZG9uZUNyaXRUZXh0MiwjbXktc3ZnIC5kb25lQ3JpdFRleHQze2ZpbGw6YmxhY2shaW1wb3J0YW50O30jbXktc3ZnIC5kb25lQ3JpdFRleHQwLnRhc2tUZXh0T3V0c2lkZUxlZnQsI215LXN2ZyAuZG9uZUNyaXRUZXh0MC50YXNrVGV4dE91dHNpZGVSaWdodCwjbXktc3ZnIC5kb25lQ3JpdFRleHQxLnRhc2tUZXh0T3V0c2lkZUxlZnQsI215LXN2ZyAuZG9uZUNyaXRUZXh0MS50YXNrVGV4dE91dHNpZGVSaWdodCwjbXktc3ZnIC5kb25lQ3JpdFRleHQyLnRhc2tUZXh0T3V0c2lkZUxlZnQsI215LXN2ZyAuZG9uZUNyaXRUZXh0Mi50YXNrVGV4dE91dHNpZGVSaWdodCwjbXktc3ZnIC5kb25lQ3JpdFRleHQzLnRhc2tUZXh0T3V0c2lkZUxlZnQsI215LXN2ZyAuZG9uZUNyaXRUZXh0My50YXNrVGV4dE91dHNpZGVSaWdodHtmaWxsOmJsYWNrIWltcG9ydGFudDt9I215LXN2ZyAudmVydHtzdHJva2U6bmF2eTt9I215LXN2ZyAudmVydFRleHR7Zm9udC1zaXplOjE1cHg7dGV4dC1hbmNob3I6bWlkZGxlO2ZpbGw6bmF2eSFpbXBvcnRhbnQ7fSNteS1zdmcgLmFjdGl2ZUNyaXRUZXh0MCwjbXktc3ZnIC5hY3RpdmVDcml0VGV4dDEsI215LXN2ZyAuYWN0aXZlQ3JpdFRleHQyLCNteS1zdmcgLmFjdGl2ZUNyaXRUZXh0M3tmaWxsOmJsYWNrIWltcG9ydGFudDt9I215LXN2ZyAudGl0bGVUZXh0e3RleHQtYW5jaG9yOm1pZGRsZTtmb250LXNpemU6MThweDtmaWxsOiMzMzM7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO30jbXktc3ZnIC5ub2RlIC5uZW8tbm9kZXtzdHJva2U6IzkzNzBEQjt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIHJlY3QsI215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5jbHVzdGVyIHJlY3QsI215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIHBvbHlnb257c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLnN3aW1sYW5lLmNsdXN0ZXIgcmVjdHtmaWx0ZXI6bm9uZTt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIHBhdGh7c3Ryb2tlOiM5MzcwREI7c3Ryb2tlLXdpZHRoOjFweDt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIC5vdXRlci1wYXRoe2ZpbHRlcjpkcm9wLXNoYWRvdygxcHggMnB4IDJweCByZ2JhKDE4NSwgMTg1LCAxODUsIDEpKTt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIC5uZW8tbGluZSBwYXRoe3N0cm9rZTojOTM3MERCO2ZpbHRlcjpub25lO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgY2lyY2xle3N0cm9rZTojOTM3MERCO2ZpbHRlcjpkcm9wLXNoYWRvdygxcHggMnB4IDJweCByZ2JhKDE4NSwgMTg1LCAxODUsIDEpKTt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIGNpcmNsZSAuc3RhdGUtc3RhcnR7ZmlsbDojMDAwMDAwO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLmljb24tc2hhcGUgLmljb257ZmlsbDojOTM3MERCO2ZpbHRlcjpkcm9wLXNoYWRvdygxcHggMnB4IDJweCByZ2JhKDE4NSwgMTg1LCAxODUsIDEpKTt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5pY29uLXNoYXBlIC5pY29uLW5lbyBwYXRoe3N0cm9rZTojOTM3MERCO2ZpbHRlcjpkcm9wLXNoYWRvdygxcHggMnB4IDJweCByZ2JhKDE4NSwgMTg1LCAxODUsIDEpKTt9I215LXN2ZyA6cm9vdHstLW1lcm1haWQtZm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO308L3N0eWxlPjxnLz48ZyBjbGFzcz0iZ3JpZCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNzUsIDE3MCkiIGZpbGw9Im5vbmUiIGZvbnQtc2l6ZT0iMTAiIGZvbnQtZmFtaWx5PSJzYW5zLXNlcmlmIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIj48cGF0aCBjbGFzcz0iZG9tYWluIiBzdHJva2U9ImN1cnJlbnRDb2xvciIgZD0iTTAsLTEzNVYwSDYzNFYtMTM1Ii8+PGcgY2xhc3M9InRpY2siIG9wYWNpdHk9IjEiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDQzLDApIj48bGluZSBzdHJva2U9ImN1cnJlbnRDb2xvciIgeTI9Ii0xMzUiLz48dGV4dCBmaWxsPSIjMDAwIiB5PSIzIiBkeT0iMWVtIiBzdHJva2U9Im5vbmUiIGZvbnQtc2l6ZT0iMTAiIHN0eWxlPSJ0ZXh0LWFuY2hvcjogbWlkZGxlOyI+MjAyNi0xMC0wNDwvdGV4dD48L2c+PGcgY2xhc3M9InRpY2siIG9wYWNpdHk9IjEiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDE0NCwwKSI+PGxpbmUgc3Ryb2tlPSJjdXJyZW50Q29sb3IiIHkyPSItMTM1Ii8+PHRleHQgZmlsbD0iIzAwMCIgeT0iMyIgZHk9IjFlbSIgc3Ryb2tlPSJub25lIiBmb250LXNpemU9IjEwIiBzdHlsZT0idGV4dC1hbmNob3I6IG1pZGRsZTsiPjIwMjYtMTAtMTE8L3RleHQ+PC9nPjxnIGNsYXNzPSJ0aWNrIiBvcGFjaXR5PSIxIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgyNDUsMCkiPjxsaW5lIHN0cm9rZT0iY3VycmVudENvbG9yIiB5Mj0iLTEzNSIvPjx0ZXh0IGZpbGw9IiMwMDAiIHk9IjMiIGR5PSIxZW0iIHN0cm9rZT0ibm9uZSIgZm9udC1zaXplPSIxMCIgc3R5bGU9InRleHQtYW5jaG9yOiBtaWRkbGU7Ij4yMDI2LTEwLTE4PC90ZXh0PjwvZz48ZyBjbGFzcz0idGljayIgb3BhY2l0eT0iMSIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMzQ2LDApIj48bGluZSBzdHJva2U9ImN1cnJlbnRDb2xvciIgeTI9Ii0xMzUiLz48dGV4dCBmaWxsPSIjMDAwIiB5PSIzIiBkeT0iMWVtIiBzdHJva2U9Im5vbmUiIGZvbnQtc2l6ZT0iMTAiIHN0eWxlPSJ0ZXh0LWFuY2hvcjogbWlkZGxlOyI+MjAyNi0xMC0yNTwvdGV4dD48L2c+PGcgY2xhc3M9InRpY2siIG9wYWNpdHk9IjEiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDQ0NywwKSI+PGxpbmUgc3Ryb2tlPSJjdXJyZW50Q29sb3IiIHkyPSItMTM1Ii8+PHRleHQgZmlsbD0iIzAwMCIgeT0iMyIgZHk9IjFlbSIgc3Ryb2tlPSJub25lIiBmb250LXNpemU9IjEwIiBzdHlsZT0idGV4dC1hbmNob3I6IG1pZGRsZTsiPjIwMjYtMTEtMDE8L3RleHQ+PC9nPjxnIGNsYXNzPSJ0aWNrIiBvcGFjaXR5PSIxIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSg1NDgsMCkiPjxsaW5lIHN0cm9rZT0iY3VycmVudENvbG9yIiB5Mj0iLTEzNSIvPjx0ZXh0IGZpbGw9IiMwMDAiIHk9IjMiIGR5PSIxZW0iIHN0cm9rZT0ibm9uZSIgZm9udC1zaXplPSIxMCIgc3R5bGU9InRleHQtYW5jaG9yOiBtaWRkbGU7Ij4yMDI2LTExLTA4PC90ZXh0PjwvZz48L2c+PGc+PHJlY3QgeD0iMCIgeT0iNDgiIHdpZHRoPSI3NDYuNSIgaGVpZ2h0PSIyNCIgY2xhc3M9InNlY3Rpb24gc2VjdGlvbjAiLz48cmVjdCB4PSIwIiB5PSI5NiIgd2lkdGg9Ijc0Ni41IiBoZWlnaHQ9IjI0IiBjbGFzcz0ic2VjdGlvbiBzZWN0aW9uMSIvPjxyZWN0IHg9IjAiIHk9IjcyIiB3aWR0aD0iNzQ2LjUiIGhlaWdodD0iMjQiIGNsYXNzPSJzZWN0aW9uIHNlY3Rpb24wIi8+PHJlY3QgeD0iMCIgeT0iMTIwIiB3aWR0aD0iNzQ2LjUiIGhlaWdodD0iMjQiIGNsYXNzPSJzZWN0aW9uIHNlY3Rpb24xIi8+PHJlY3QgeD0iMCIgeT0iMTQ0IiB3aWR0aD0iNzQ2LjUiIGhlaWdodD0iMjQiIGNsYXNzPSJzZWN0aW9uIHNlY3Rpb24yIi8+PC9nPjxnPjxyZWN0IGlkPSJteS1zdmctYTEiIHJ4PSIzIiByeT0iMyIgeD0iNzUiIHk9IjUwIiB3aWR0aD0iMjE2IiBoZWlnaHQ9IjIwIiB0cmFuc2Zvcm0tb3JpZ2luPSIxODNweCA2MHB4IiBjbGFzcz0idGFzayB0YXNrMCIvPjxyZWN0IGlkPSJteS1zdmctYjEiIHJ4PSIzIiByeT0iMyIgeD0iMTc2IiB5PSI5OCIgd2lkdGg9IjI1OSIgaGVpZ2h0PSIyMCIgdHJhbnNmb3JtLW9yaWdpbj0iMzA1LjVweCAxMDhweCIgY2xhc3M9InRhc2sgdGFzazEiLz48cmVjdCBpZD0ibXktc3ZnLXRhc2sxIiByeD0iMyIgcnk9IjMiIHg9IjI5MSIgeT0iNzQiIHdpZHRoPSIyODgiIGhlaWdodD0iMjAiIHRyYW5zZm9ybS1vcmlnaW49IjQzNXB4IDg0cHgiIGNsYXNzPSJ0YXNrIHRhc2swIi8+PHJlY3QgaWQ9Im15LXN2Zy10YXNrMiIgcng9IjMiIHJ5PSIzIiB4PSI0MzUiIHk9IjEyMiIgd2lkdGg9IjE3MyIgaGVpZ2h0PSIyMCIgdHJhbnNmb3JtLW9yaWdpbj0iNTIxLjVweCAxMzJweCIgY2xhc3M9InRhc2sgdGFzazEiLz48cmVjdCBpZD0ibXktc3ZnLXRhc2szIiByeD0iMyIgcnk9IjMiIHg9IjY5OSIgeT0iMTQ2IiB3aWR0aD0iMjAiIGhlaWdodD0iMjAiIHRyYW5zZm9ybS1vcmlnaW49IjcwOXB4IDE1NnB4IiBjbGFzcz0idGFzayBtaWxlc3RvbmUgIHRhc2syIi8+PHRleHQgaWQ9Im15LXN2Zy1hMS10ZXh0IiBmb250LXNpemU9IjExIiB4PSIxODMiIHk9IjYzLjUiIGNsYXNzPSJ0YXNrVGV4dCB0YXNrVGV4dDAgIHdpZHRoLTUwLjkzNzUiPk9yZGVycyBBUEkgICAgICA8L3RleHQ+PHRleHQgaWQ9Im15LXN2Zy1iMS10ZXh0IiBmb250LXNpemU9IjExIiB4PSIzMDUuNSIgeT0iMTExLjUiIGNsYXNzPSJ0YXNrVGV4dCB0YXNrVGV4dDEgIHdpZHRoLTcyLjk4NDM3NSI+UmVwb3J0aW5nIGRhc2ggIDwvdGV4dD48dGV4dCBpZD0ibXktc3ZnLXRhc2sxLXRleHQiIGZvbnQtc2l6ZT0iMTEiIHg9IjQzNSIgeT0iODcuNSIgY2xhc3M9InRhc2tUZXh0IHRhc2tUZXh0MCAgd2lkdGgtODcuNjYzMDg1OTM3NSI+UGF5bWVudHMgcmV2YW1wIDwvdGV4dD48dGV4dCBpZD0ibXktc3ZnLXRhc2syLXRleHQiIGZvbnQtc2l6ZT0iMTEiIHg9IjUyMS41IiB5PSIxMzUuNSIgY2xhc3M9InRhc2tUZXh0IHRhc2tUZXh0MSAgd2lkdGgtNzAuNDY4NzUiPkV4cG9ydCByZWZyZXNoICA8L3RleHQ+PHRleHQgaWQ9Im15LXN2Zy10YXNrMy10ZXh0IiBmb250LXNpemU9IjExIiB4PSI2OTQiIHk9IjE1OS41IiBjbGFzcz0idGFza1RleHRPdXRzaWRlTGVmdCB0YXNrVGV4dE91dHNpZGUyICBtaWxlc3RvbmVUZXh0Ij5RMyBsYXVuY2ggICAgICAgPC90ZXh0PjwvZz48Zz48dGV4dCBkeT0iMGVtIiB4PSIxMCIgeT0iNzQiIGZvbnQtc2l6ZT0iMTEiIGNsYXNzPSJzZWN0aW9uVGl0bGUgc2VjdGlvblRpdGxlMCI+PHRzcGFuIGFsaWdubWVudC1iYXNlbGluZT0iY2VudHJhbCIgeD0iMTAiPlBsYXRmb3JtPC90c3Bhbj48L3RleHQ+PHRleHQgZHk9IjBlbSIgeD0iMTAiIHk9IjEyMiIgZm9udC1zaXplPSIxMSIgY2xhc3M9InNlY3Rpb25UaXRsZSBzZWN0aW9uVGl0bGUxIj48dHNwYW4gYWxpZ25tZW50LWJhc2VsaW5lPSJjZW50cmFsIiB4PSIxMCI+RGF0YTwvdHNwYW4+PC90ZXh0Pjx0ZXh0IGR5PSIwZW0iIHg9IjEwIiB5PSIxNTgiIGZvbnQtc2l6ZT0iMTEiIGNsYXNzPSJzZWN0aW9uVGl0bGUgc2VjdGlvblRpdGxlMiI+PHRzcGFuIGFsaWdubWVudC1iYXNlbGluZT0iY2VudHJhbCIgeD0iMTAiPlJlbGVhc2U8L3RzcGFuPjwvdGV4dD48L2c+PGcgY2xhc3M9InRvZGF5Ij48bGluZSB4MT0iLTE0IiB4Mj0iLTE0IiB5MT0iMjUiIHkyPSIxOTUiIGNsYXNzPSJ0b2RheSIvPjwvZz48dGV4dCB4PSIzOTIiIHk9IjI1IiBjbGFzcz0idGl0bGVUZXh0Ij5RMyBSb2FkbWFwPC90ZXh0Pjwvc3ZnPg==) The Gantt answers "when" at the planning kickoff: the API bars flow into release, the data track shares the same end-date window, and the `milestone` marks the drop-dead. When a date moves, the review changes one number and the bar redraws. ## Copy-paste 2: which first — effort impact quadrant[​](#copy-paste-2-which-first--effort-impact-quadrant "Direct link to Copy-paste 2: which first — effort impact quadrant") The 2x2 that replaces the color-coded column. Plot each candidate against effort (x) and impact (y); the top-left is the obvious first slice: ``` quadrantChart title Prioritize x-axis Low Effort --> High Effort y-axis Low Impact --> High Impact quadrant-1 Do now quadrant-2 Big bets quadrant-3 Fill-ins quadrant-4 Cut "Payment revamp": [0.65, 0.45] "Orders API": [0.55, 0.35] "Reporting dash": [0.4, 0.25] "Export refresh": [0.2, 0.15] ``` ![Prioritize](data:image/svg+xml;base64,PHN2ZyBpZD0ibXktc3ZnIiB3aWR0aD0iMTAwJSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgc3R5bGU9Im1heC13aWR0aDogNTAwcHg7IGJhY2tncm91bmQtY29sb3I6IHdoaXRlOyIgdmlld0JveD0iMCAwIDUwMCA1MDAiIHJvbGU9ImdyYXBoaWNzLWRvY3VtZW50IGRvY3VtZW50IiBhcmlhLXJvbGVkZXNjcmlwdGlvbj0icXVhZHJhbnRDaGFydCI+PHN0eWxlPiNteS1zdmd7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO2ZvbnQtc2l6ZToxNnB4O2ZpbGw6IzMzMzt9QGtleWZyYW1lcyBlZGdlLWFuaW1hdGlvbi1mcmFtZXtmcm9te3N0cm9rZS1kYXNob2Zmc2V0OjA7fX1Aa2V5ZnJhbWVzIGRhc2h7dG97c3Ryb2tlLWRhc2hvZmZzZXQ6MDt9fSNteS1zdmcgLmVkZ2UtYW5pbWF0aW9uLXNsb3d7c3Ryb2tlLWRhc2hhcnJheTo5LDUhaW1wb3J0YW50O3N0cm9rZS1kYXNob2Zmc2V0OjkwMDthbmltYXRpb246ZGFzaCA1MHMgbGluZWFyIGluZmluaXRlO3N0cm9rZS1saW5lY2FwOnJvdW5kO30jbXktc3ZnIC5lZGdlLWFuaW1hdGlvbi1mYXN0e3N0cm9rZS1kYXNoYXJyYXk6OSw1IWltcG9ydGFudDtzdHJva2UtZGFzaG9mZnNldDo5MDA7YW5pbWF0aW9uOmRhc2ggMjBzIGxpbmVhciBpbmZpbml0ZTtzdHJva2UtbGluZWNhcDpyb3VuZDt9I215LXN2ZyAuZXJyb3ItaWNvbntmaWxsOiM1NTIyMjI7fSNteS1zdmcgLmVycm9yLXRleHR7ZmlsbDojNTUyMjIyO3N0cm9rZTojNTUyMjIyO30jbXktc3ZnIC5lZGdlLXRoaWNrbmVzcy1ub3JtYWx7c3Ryb2tlLXdpZHRoOjFweDt9I215LXN2ZyAuZWRnZS10aGlja25lc3MtdGhpY2t7c3Ryb2tlLXdpZHRoOjMuNXB4O30jbXktc3ZnIC5lZGdlLXBhdHRlcm4tc29saWR7c3Ryb2tlLWRhc2hhcnJheTowO30jbXktc3ZnIC5lZGdlLXRoaWNrbmVzcy1pbnZpc2libGV7c3Ryb2tlLXdpZHRoOjA7ZmlsbDpub25lO30jbXktc3ZnIC5lZGdlLXBhdHRlcm4tZGFzaGVke3N0cm9rZS1kYXNoYXJyYXk6Mzt9I215LXN2ZyAuZWRnZS1wYXR0ZXJuLWRvdHRlZHtzdHJva2UtZGFzaGFycmF5OjI7fSNteS1zdmcgLm1hcmtlcntmaWxsOiMzMzMzMzM7c3Ryb2tlOiMzMzMzMzM7fSNteS1zdmcgLm1hcmtlci5jcm9zc3tzdHJva2U6IzMzMzMzMzt9I215LXN2ZyBzdmd7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO2ZvbnQtc2l6ZToxNnB4O30jbXktc3ZnIHB7bWFyZ2luOjA7fSNteS1zdmcgLm5vZGUgLm5lby1ub2Rle3N0cm9rZTojOTM3MERCO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcmVjdCwjbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLmNsdXN0ZXIgcmVjdCwjbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcG9seWdvbntzdHJva2U6IzkzNzBEQjtmaWx0ZXI6ZHJvcC1zaGFkb3coMXB4IDJweCAycHggcmdiYSgxODUsIDE4NSwgMTg1LCAxKSk7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uc3dpbWxhbmUuY2x1c3RlciByZWN0e2ZpbHRlcjpub25lO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgcGF0aHtzdHJva2U6IzkzNzBEQjtzdHJva2Utd2lkdGg6MXB4O30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgLm91dGVyLXBhdGh7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgLm5lby1saW5lIHBhdGh7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOm5vbmU7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0ubm9kZSBjaXJjbGV7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgY2lyY2xlIC5zdGF0ZS1zdGFydHtmaWxsOiMwMDAwMDA7fSNteS1zdmcgW2RhdGEtbG9vaz0ibmVvIl0uaWNvbi1zaGFwZSAuaWNvbntmaWxsOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLmljb24tc2hhcGUgLmljb24tbmVvIHBhdGh7c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIDpyb290ey0tbWVybWFpZC1mb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7fTwvc3R5bGU+PGcvPjxnIGNsYXNzPSJtYWluIj48ZyBjbGFzcz0icXVhZHJhbnRzIj48ZyBjbGFzcz0icXVhZHJhbnQiPjxyZWN0IHg9IjI2MyIgeT0iNDUiIHdpZHRoPSIyMzIiIGhlaWdodD0iMjEyIiBmaWxsPSIjRUNFQ0ZGIi8+PHRleHQgeD0iMCIgeT0iMCIgZmlsbD0iIzEzMTMwMCIgZm9udC1zaXplPSIxNiIgZG9taW5hbnQtYmFzZWxpbmU9ImhhbmdpbmciIHRleHQtYW5jaG9yPSJtaWRkbGUiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDM3OSwgNTApIHJvdGF0ZSgwKSI+RG8gbm93PC90ZXh0PjwvZz48ZyBjbGFzcz0icXVhZHJhbnQiPjxyZWN0IHg9IjMxIiB5PSI0NSIgd2lkdGg9IjIzMiIgaGVpZ2h0PSIyMTIiIGZpbGw9IiNmMWYxZmYiLz48dGV4dCB4PSIwIiB5PSIwIiBmaWxsPSIjMGUwZTAwIiBmb250LXNpemU9IjE2IiBkb21pbmFudC1iYXNlbGluZT0iaGFuZ2luZyIgdGV4dC1hbmNob3I9Im1pZGRsZSIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMTQ3LCA1MCkgcm90YXRlKDApIj5CaWcgYmV0czwvdGV4dD48L2c+PGcgY2xhc3M9InF1YWRyYW50Ij48cmVjdCB4PSIzMSIgeT0iMjU3IiB3aWR0aD0iMjMyIiBoZWlnaHQ9IjIxMiIgZmlsbD0iI2Y2ZjZmZiIvPjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMwOTA5MDAiIGZvbnQtc2l6ZT0iMTYiIGRvbWluYW50LWJhc2VsaW5lPSJoYW5naW5nIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxNDcsIDI2Mikgcm90YXRlKDApIj5GaWxsLWluczwvdGV4dD48L2c+PGcgY2xhc3M9InF1YWRyYW50Ij48cmVjdCB4PSIyNjMiIHk9IjI1NyIgd2lkdGg9IjIzMiIgaGVpZ2h0PSIyMTIiIGZpbGw9IiNmYmZiZmYiLz48dGV4dCB4PSIwIiB5PSIwIiBmaWxsPSIjMDQwNDAwIiBmb250LXNpemU9IjE2IiBkb21pbmFudC1iYXNlbGluZT0iaGFuZ2luZyIgdGV4dC1hbmNob3I9Im1pZGRsZSIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMzc5LCAyNjIpIHJvdGF0ZSgwKSI+Q3V0PC90ZXh0PjwvZz48L2c+PGcgY2xhc3M9ImJvcmRlciI+PGxpbmUgeDE9IjMwIiB5MT0iNDUiIHgyPSI0OTYiIHkyPSI0NSIgc3R5bGU9InN0cm9rZTogcmdiKDE5OSwgMTk5LCAyNDEpOyBzdHJva2Utd2lkdGg6IDI7Ii8+PGxpbmUgeDE9IjQ5NSIgeTE9IjQ2IiB4Mj0iNDk1IiB5Mj0iNDY4IiBzdHlsZT0ic3Ryb2tlOiByZ2IoMTk5LCAxOTksIDI0MSk7IHN0cm9rZS13aWR0aDogMjsiLz48bGluZSB4MT0iMzAiIHkxPSI0NjkiIHgyPSI0OTYiIHkyPSI0NjkiIHN0eWxlPSJzdHJva2U6IHJnYigxOTksIDE5OSwgMjQxKTsgc3Ryb2tlLXdpZHRoOiAyOyIvPjxsaW5lIHgxPSIzMSIgeTE9IjQ2IiB4Mj0iMzEiIHkyPSI0NjgiIHN0eWxlPSJzdHJva2U6IHJnYigxOTksIDE5OSwgMjQxKTsgc3Ryb2tlLXdpZHRoOiAyOyIvPjxsaW5lIHgxPSIyNjMiIHkxPSI0NiIgeDI9IjI2MyIgeTI9IjQ2OCIgc3R5bGU9InN0cm9rZTogcmdiKDE5OSwgMTk5LCAyNDEpOyBzdHJva2Utd2lkdGg6IDE7Ii8+PGxpbmUgeDE9IjMyIiB5MT0iMjU3IiB4Mj0iNDk0IiB5Mj0iMjU3IiBzdHlsZT0ic3Ryb2tlOiByZ2IoMTk5LCAxOTksIDI0MSk7IHN0cm9rZS13aWR0aDogMTsiLz48L2c+PGcgY2xhc3M9ImRhdGEtcG9pbnRzIj48ZyBjbGFzcz0iZGF0YS1wb2ludCI+PGNpcmNsZSBjeD0iMTIzLjgiIGN5PSI0MDUuNCIgcj0iNSIgZmlsbD0iaHNsKDI0MCwgMTAwJSwgTmFOJSkiIHN0cm9rZT0iaHNsKDI0MCwgMTAwJSwgTmFOJSkiIHN0cm9rZS13aWR0aD0iMHB4Ii8+PHRleHQgeD0iMCIgeT0iMCIgZmlsbD0iIzEzMTMwMCIgZm9udC1zaXplPSIxMiIgZG9taW5hbnQtYmFzZWxpbmU9ImhhbmdpbmciIHRleHQtYW5jaG9yPSJtaWRkbGUiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDEyMy44LCA0MTAuNCkgcm90YXRlKDApIj5FeHBvcnQgcmVmcmVzaDwvdGV4dD48L2c+PGcgY2xhc3M9ImRhdGEtcG9pbnQiPjxjaXJjbGUgY3g9IjIxNi42IiBjeT0iMzYzIiByPSI1IiBmaWxsPSJoc2woMjQwLCAxMDAlLCBOYU4lKSIgc3Ryb2tlPSJoc2woMjQwLCAxMDAlLCBOYU4lKSIgc3Ryb2tlLXdpZHRoPSIwcHgiLz48dGV4dCB4PSIwIiB5PSIwIiBmaWxsPSIjMTMxMzAwIiBmb250LXNpemU9IjEyIiBkb21pbmFudC1iYXNlbGluZT0iaGFuZ2luZyIgdGV4dC1hbmNob3I9Im1pZGRsZSIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMjE2LjYsIDM2OCkgcm90YXRlKDApIj5SZXBvcnRpbmcgZGFzaDwvdGV4dD48L2c+PGcgY2xhc3M9ImRhdGEtcG9pbnQiPjxjaXJjbGUgY3g9IjI4Ni4yIiBjeT0iMzIwLjYiIHI9IjUiIGZpbGw9ImhzbCgyNDAsIDEwMCUsIE5hTiUpIiBzdHJva2U9ImhzbCgyNDAsIDEwMCUsIE5hTiUpIiBzdHJva2Utd2lkdGg9IjBweCIvPjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMxMzEzMDAiIGZvbnQtc2l6ZT0iMTIiIGRvbWluYW50LWJhc2VsaW5lPSJoYW5naW5nIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgyODYuMiwgMzI1LjYpIHJvdGF0ZSgwKSI+T3JkZXJzIEFQSTwvdGV4dD48L2c+PGcgY2xhc3M9ImRhdGEtcG9pbnQiPjxjaXJjbGUgY3g9IjMzMi42IiBjeT0iMjc4LjIwMDAwMDAwMDAwMDA1IiByPSI1IiBmaWxsPSJoc2woMjQwLCAxMDAlLCBOYU4lKSIgc3Ryb2tlPSJoc2woMjQwLCAxMDAlLCBOYU4lKSIgc3Ryb2tlLXdpZHRoPSIwcHgiLz48dGV4dCB4PSIwIiB5PSIwIiBmaWxsPSIjMTMxMzAwIiBmb250LXNpemU9IjEyIiBkb21pbmFudC1iYXNlbGluZT0iaGFuZ2luZyIgdGV4dC1hbmNob3I9Im1pZGRsZSIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMzMyLjYsIDI4My4yMDAwMDAwMDAwMDAwNSkgcm90YXRlKDApIj5QYXltZW50IHJldmFtcDwvdGV4dD48L2c+PC9nPjxnIGNsYXNzPSJsYWJlbHMiPjxnIGNsYXNzPSJsYWJlbCI+PHRleHQgeD0iMCIgeT0iMCIgZmlsbD0iIzEzMTMwMCIgZm9udC1zaXplPSIxNiIgZG9taW5hbnQtYmFzZWxpbmU9ImhhbmdpbmciIHRleHQtYW5jaG9yPSJtaWRkbGUiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDE0NywgNDc5KSByb3RhdGUoMCkiPkxvdyBFZmZvcnQ8L3RleHQ+PC9nPjxnIGNsYXNzPSJsYWJlbCI+PHRleHQgeD0iMCIgeT0iMCIgZmlsbD0iIzEzMTMwMCIgZm9udC1zaXplPSIxNiIgZG9taW5hbnQtYmFzZWxpbmU9ImhhbmdpbmciIHRleHQtYW5jaG9yPSJtaWRkbGUiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDM3OSwgNDc5KSByb3RhdGUoMCkiPkhpZ2ggRWZmb3J0PC90ZXh0PjwvZz48ZyBjbGFzcz0ibGFiZWwiPjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMxMzEzMDAiIGZvbnQtc2l6ZT0iMTYiIGRvbWluYW50LWJhc2VsaW5lPSJoYW5naW5nIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSg1LCAzNjMpIHJvdGF0ZSgtOTApIj5Mb3cgSW1wYWN0PC90ZXh0PjwvZz48ZyBjbGFzcz0ibGFiZWwiPjx0ZXh0IHg9IjAiIHk9IjAiIGZpbGw9IiMxMzEzMDAiIGZvbnQtc2l6ZT0iMTYiIGRvbWluYW50LWJhc2VsaW5lPSJoYW5naW5nIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSg1LCAxNTEpIHJvdGF0ZSgtOTApIj5IaWdoIEltcGFjdDwvdGV4dD48L2c+PC9nPjxnIGNsYXNzPSJ0aXRsZSI+PHRleHQgeD0iMCIgeT0iMCIgZmlsbD0iIzEzMTMwMCIgZm9udC1zaXplPSIyMCIgZG9taW5hbnQtYmFzZWxpbmU9ImhhbmdpbmciIHRleHQtYW5jaG9yPSJtaWRkbGUiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDI1MCwgMTApIHJvdGF0ZSgwKSI+UHJpb3JpdGl6ZTwvdGV4dD48L2c+PC9nPjwvc3ZnPg==) Unread the labels for now — the *positions* are the decision: two items cluster low-effort (bottom half), one rides the borderline, and "Payment revamp" sits firmly in Do-now territory. The quadrant is the tie-breaker the sorted spreadsheet cannot provide, because it shows the *relationship* between effort and impact, not a ranking. ## Copy-paste 3: where the budget goes — Sankey[​](#copy-paste-3-where-the-budget-goes--sankey "Direct link to Copy-paste 3: where the budget goes — Sankey") Sankey ribbons show quantities moving from source to use, and the width of a ribbon is the magnitude — the leak is visually loud: ``` sankey-beta Budget,Engineering,120 Budget,Infra,80 Budget,Marketing,40 Infra,Hardware,30 Infra,Cloud,50 ``` ![Rendered Mermaid diagram](data:image/svg+xml;base64,PHN2ZyBpZD0ibXktc3ZnIiB3aWR0aD0iMTAwJSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgc3R5bGU9Im1heC13aWR0aDogNjAwcHg7IGJhY2tncm91bmQtY29sb3I6IHdoaXRlOyIgdmlld0JveD0iMCAwIDYwMCA0MDAiIHJvbGU9ImdyYXBoaWNzLWRvY3VtZW50IGRvY3VtZW50IiBhcmlhLXJvbGVkZXNjcmlwdGlvbj0ic2Fua2V5Ij48c3R5bGU+I215LXN2Z3tmb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7Zm9udC1zaXplOjE2cHg7ZmlsbDojMzMzO31Aa2V5ZnJhbWVzIGVkZ2UtYW5pbWF0aW9uLWZyYW1le2Zyb217c3Ryb2tlLWRhc2hvZmZzZXQ6MDt9fUBrZXlmcmFtZXMgZGFzaHt0b3tzdHJva2UtZGFzaG9mZnNldDowO319I215LXN2ZyAuZWRnZS1hbmltYXRpb24tc2xvd3tzdHJva2UtZGFzaGFycmF5OjksNSFpbXBvcnRhbnQ7c3Ryb2tlLWRhc2hvZmZzZXQ6OTAwO2FuaW1hdGlvbjpkYXNoIDUwcyBsaW5lYXIgaW5maW5pdGU7c3Ryb2tlLWxpbmVjYXA6cm91bmQ7fSNteS1zdmcgLmVkZ2UtYW5pbWF0aW9uLWZhc3R7c3Ryb2tlLWRhc2hhcnJheTo5LDUhaW1wb3J0YW50O3N0cm9rZS1kYXNob2Zmc2V0OjkwMDthbmltYXRpb246ZGFzaCAyMHMgbGluZWFyIGluZmluaXRlO3N0cm9rZS1saW5lY2FwOnJvdW5kO30jbXktc3ZnIC5lcnJvci1pY29ue2ZpbGw6IzU1MjIyMjt9I215LXN2ZyAuZXJyb3ItdGV4dHtmaWxsOiM1NTIyMjI7c3Ryb2tlOiM1NTIyMjI7fSNteS1zdmcgLmVkZ2UtdGhpY2tuZXNzLW5vcm1hbHtzdHJva2Utd2lkdGg6MXB4O30jbXktc3ZnIC5lZGdlLXRoaWNrbmVzcy10aGlja3tzdHJva2Utd2lkdGg6My41cHg7fSNteS1zdmcgLmVkZ2UtcGF0dGVybi1zb2xpZHtzdHJva2UtZGFzaGFycmF5OjA7fSNteS1zdmcgLmVkZ2UtdGhpY2tuZXNzLWludmlzaWJsZXtzdHJva2Utd2lkdGg6MDtmaWxsOm5vbmU7fSNteS1zdmcgLmVkZ2UtcGF0dGVybi1kYXNoZWR7c3Ryb2tlLWRhc2hhcnJheTozO30jbXktc3ZnIC5lZGdlLXBhdHRlcm4tZG90dGVke3N0cm9rZS1kYXNoYXJyYXk6Mjt9I215LXN2ZyAubWFya2Vye2ZpbGw6IzMzMzMzMztzdHJva2U6IzMzMzMzMzt9I215LXN2ZyAubWFya2VyLmNyb3Nze3N0cm9rZTojMzMzMzMzO30jbXktc3ZnIHN2Z3tmb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7Zm9udC1zaXplOjE2cHg7fSNteS1zdmcgcHttYXJnaW46MDt9I215LXN2ZyAubGFiZWx7Zm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO30jbXktc3ZnIC5ub2RlLWxhYmVsc3tmb250LWZhbWlseToidHJlYnVjaGV0IG1zIix2ZXJkYW5hLGFyaWFsLHNhbnMtc2VyaWY7fSNteS1zdmcgLnNhbmtleS1sYWJlbC1iZ3tzdHJva2U6I0VDRUNGRjtzdHJva2Utd2lkdGg6NHB4O3N0cm9rZS1saW5lam9pbjpyb3VuZDtwYWludC1vcmRlcjpzdHJva2U7fSNteS1zdmcgLnNhbmtleS1sYWJlbC1mZ3tmaWxsOiMzMzM7fSNteS1zdmcgLm5vZGUgcmVjdHtzaGFwZS1yZW5kZXJpbmc6Y3Jpc3BFZGdlczt9I215LXN2ZyAubGlua3tmaWxsOm5vbmU7c3Ryb2tlLW9wYWNpdHk6MC41O21peC1ibGVuZC1tb2RlOm11bHRpcGx5O30jbXktc3ZnIC5ub2RlIC5uZW8tbm9kZXtzdHJva2U6IzkzNzBEQjt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIHJlY3QsI215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5jbHVzdGVyIHJlY3QsI215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIHBvbHlnb257c3Ryb2tlOiM5MzcwREI7ZmlsdGVyOmRyb3Atc2hhZG93KDFweCAycHggMnB4IHJnYmEoMTg1LCAxODUsIDE4NSwgMSkpO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLnN3aW1sYW5lLmNsdXN0ZXIgcmVjdHtmaWx0ZXI6bm9uZTt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIHBhdGh7c3Ryb2tlOiM5MzcwREI7c3Ryb2tlLXdpZHRoOjFweDt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIC5vdXRlci1wYXRoe2ZpbHRlcjpkcm9wLXNoYWRvdygxcHggMnB4IDJweCByZ2JhKDE4NSwgMTg1LCAxODUsIDEpKTt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIC5uZW8tbGluZSBwYXRoe3N0cm9rZTojOTM3MERCO2ZpbHRlcjpub25lO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLm5vZGUgY2lyY2xle3N0cm9rZTojOTM3MERCO2ZpbHRlcjpkcm9wLXNoYWRvdygxcHggMnB4IDJweCByZ2JhKDE4NSwgMTg1LCAxODUsIDEpKTt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5ub2RlIGNpcmNsZSAuc3RhdGUtc3RhcnR7ZmlsbDojMDAwMDAwO30jbXktc3ZnIFtkYXRhLWxvb2s9Im5lbyJdLmljb24tc2hhcGUgLmljb257ZmlsbDojOTM3MERCO2ZpbHRlcjpkcm9wLXNoYWRvdygxcHggMnB4IDJweCByZ2JhKDE4NSwgMTg1LCAxODUsIDEpKTt9I215LXN2ZyBbZGF0YS1sb29rPSJuZW8iXS5pY29uLXNoYXBlIC5pY29uLW5lbyBwYXRoe3N0cm9rZTojOTM3MERCO2ZpbHRlcjpkcm9wLXNoYWRvdygxcHggMnB4IDJweCByZ2JhKDE4NSwgMTg1LCAxODUsIDEpKTt9I215LXN2ZyA6cm9vdHstLW1lcm1haWQtZm9udC1mYW1pbHk6InRyZWJ1Y2hldCBtcyIsdmVyZGFuYSxhcmlhbCxzYW5zLXNlcmlmO308L3N0eWxlPjxnLz48ZyBjbGFzcz0ibm9kZXMiPjxnIGNsYXNzPSJub2RlIiBpZD0ibm9kZS0xIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgwLDkuMzAwODAyNjc2NDg1MDA0KSIgeD0iMCIgeT0iOS4zMDA4MDI2NzY0ODUwMDQiPjxyZWN0IGhlaWdodD0iMzE5LjAwMDAwMDAwMDAwMDA2IiB3aWR0aD0iMTAiIGZpbGw9IiM0ZTc5YTciLz48L2c+PGcgY2xhc3M9Im5vZGUiIGlkPSJub2RlLTIiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDU5MCwwKSIgeD0iNTkwIiB5PSIwIj48cmVjdCBoZWlnaHQ9IjE1OS41IiB3aWR0aD0iMTAiIGZpbGw9IiNmMjhlMmMiLz48L2c+PGcgY2xhc3M9Im5vZGUiIGlkPSJub2RlLTMiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDI5NSwyNDkuNzEyOTg2ODkyOTY0NTgpIiB4PSIyOTUiIHk9IjI0OS43MTI5ODY4OTI5NjQ1OCI+PHJlY3QgaGVpZ2h0PSIxMDYuMzMzMzMzMzMzMzMzMzEiIHdpZHRoPSIxMCIgZmlsbD0iI2UxNTc1OSIvPjwvZz48ZyBjbGFzcz0ibm9kZSIgaWQ9Im5vZGUtNCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNTkwLDE4Ni41KSIgeD0iNTkwIiB5PSIxODYuNSI+PHJlY3QgaGVpZ2h0PSI1My4xNjY2NjY2NjY2NjY2MyIgd2lkdGg9IjEwIiBmaWxsPSIjNzZiN2IyIi8+PC9nPjxnIGNsYXNzPSJub2RlIiBpZD0ibm9kZS01IiB0cmFuc2Zvcm09InRyYW5zbGF0ZSg1OTAsMjY2LjY2NjY2NjY2NjY2NjYzKSIgeD0iNTkwIiB5PSIyNjYuNjY2NjY2NjY2NjY2NjMiPjxyZWN0IGhlaWdodD0iMzkuODc1IiB3aWR0aD0iMTAiIGZpbGw9IiM1OWExNGYiLz48L2c+PGcgY2xhc3M9Im5vZGUiIGlkPSJub2RlLTYiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDU5MCwzMzMuNTQxNjY2NjY2NjY2NjMpIiB4PSI1OTAiIHk9IjMzMy41NDE2NjY2NjY2NjY2MyI+PHJlY3QgaGVpZ2h0PSI2Ni40NTgzMzMzMzMzMzMzNyIgd2lkdGg9IjEwIiBmaWxsPSIjZWRjOTQ5Ii8+PC9nPjwvZz48ZyBjbGFzcz0ibm9kZS1sYWJlbHMiIGZvbnQtc2l6ZT0iMTQiPjx0ZXh0IHg9IjE2IiB5PSIxNjguODAwODAyNjc2NDg1IiBkeT0iMGVtIiB0ZXh0LWFuY2hvcj0ic3RhcnQiPkJ1ZGdldAoyNDA8L3RleHQ+PHRleHQgeD0iNTg0IiB5PSI3OS43NSIgZHk9IjBlbSIgdGV4dC1hbmNob3I9ImVuZCI+RW5naW5lZXJpbmcKMTIwPC90ZXh0Pjx0ZXh0IHg9IjMxMSIgeT0iMzAyLjg3OTY1MzU1OTYzMTI3IiBkeT0iMGVtIiB0ZXh0LWFuY2hvcj0ic3RhcnQiPkluZnJhCjgwPC90ZXh0Pjx0ZXh0IHg9IjU4NCIgeT0iMjEzLjA4MzMzMzMzMzMzMzMxIiBkeT0iMGVtIiB0ZXh0LWFuY2hvcj0iZW5kIj5NYXJrZXRpbmcKNDA8L3RleHQ+PHRleHQgeD0iNTg0IiB5PSIyODYuNjA0MTY2NjY2NjY2NjMiIGR5PSIwZW0iIHRleHQtYW5jaG9yPSJlbmQiPkhhcmR3YXJlCjMwPC90ZXh0Pjx0ZXh0IHg9IjU4NCIgeT0iMzY2Ljc3MDgzMzMzMzMzMzMiIGR5PSIwZW0iIHRleHQtYW5jaG9yPSJlbmQiPkNsb3VkCjUwPC90ZXh0PjwvZz48ZyBjbGFzcz0ibGlua3MiIGZpbGw9Im5vbmUiIHN0cm9rZS1vcGFjaXR5PSIwLjUiPjxnIGNsYXNzPSJsaW5rIiBzdHlsZT0ibWl4LWJsZW5kLW1vZGU6IG11bHRpcGx5OyI+PGxpbmVhckdyYWRpZW50IGlkPSJsaW5lYXJHcmFkaWVudC03IiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSIgeDE9IjEwIiB4Mj0iNTkwIj48c3RvcCBvZmZzZXQ9IjAlIiBzdG9wLWNvbG9yPSIjNGU3OWE3Ii8+PHN0b3Agb2Zmc2V0PSIxMDAlIiBzdG9wLWNvbG9yPSIjZjI4ZTJjIi8+PC9saW5lYXJHcmFkaWVudD48cGF0aCBkPSJNMTAsODkuMDUwODAyNjc2NDg1QzMwMCw4OS4wNTA4MDI2NzY0ODUsMzAwLDc5Ljc1LDU5MCw3OS43NSIgc3Ryb2tlPSJ1cmwoI2xpbmVhckdyYWRpZW50LTcpIiBzdHJva2Utd2lkdGg9IjE1OS41Ii8+PC9nPjxnIGNsYXNzPSJsaW5rIiBzdHlsZT0ibWl4LWJsZW5kLW1vZGU6IG11bHRpcGx5OyI+PGxpbmVhckdyYWRpZW50IGlkPSJsaW5lYXJHcmFkaWVudC04IiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSIgeDE9IjEwIiB4Mj0iMjk1Ij48c3RvcCBvZmZzZXQ9IjAlIiBzdG9wLWNvbG9yPSIjNGU3OWE3Ii8+PHN0b3Agb2Zmc2V0PSIxMDAlIiBzdG9wLWNvbG9yPSIjZTE1NzU5Ii8+PC9saW5lYXJHcmFkaWVudD48cGF0aCBkPSJNMTAsMjc1LjEzNDEzNjAwOTgxODM1QzE1Mi41LDI3NS4xMzQxMzYwMDk4MTgzNSwxNTIuNSwzMDIuODc5NjUzNTU5NjMxMjcsMjk1LDMwMi44Nzk2NTM1NTk2MzEyNyIgc3Ryb2tlPSJ1cmwoI2xpbmVhckdyYWRpZW50LTgpIiBzdHJva2Utd2lkdGg9IjEwNi4zMzMzMzMzMzMzMzMzMyIvPjwvZz48ZyBjbGFzcz0ibGluayIgc3R5bGU9Im1peC1ibGVuZC1tb2RlOiBtdWx0aXBseTsiPjxsaW5lYXJHcmFkaWVudCBpZD0ibGluZWFyR3JhZGllbnQtOSIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiIHgxPSIxMCIgeDI9IjU5MCI+PHN0b3Agb2Zmc2V0PSIwJSIgc3RvcC1jb2xvcj0iIzRlNzlhNyIvPjxzdG9wIG9mZnNldD0iMTAwJSIgc3RvcC1jb2xvcj0iIzc2YjdiMiIvPjwvbGluZWFyR3JhZGllbnQ+PHBhdGggZD0iTTEwLDE5NS4zODQxMzYwMDk4MTgzNUMzMDAsMTk1LjM4NDEzNjAwOTgxODM1LDMwMCwyMTMuMDgzMzMzMzMzMzMzMzQsNTkwLDIxMy4wODMzMzMzMzMzMzMzNCIgc3Ryb2tlPSJ1cmwoI2xpbmVhckdyYWRpZW50LTkpIiBzdHJva2Utd2lkdGg9IjUzLjE2NjY2NjY2NjY2NjY2NCIvPjwvZz48ZyBjbGFzcz0ibGluayIgc3R5bGU9Im1peC1ibGVuZC1tb2RlOiBtdWx0aXBseTsiPjxsaW5lYXJHcmFkaWVudCBpZD0ibGluZWFyR3JhZGllbnQtMTAiIGdyYWRpZW50VW5pdHM9InVzZXJTcGFjZU9uVXNlIiB4MT0iMzA1IiB4Mj0iNTkwIj48c3RvcCBvZmZzZXQ9IjAlIiBzdG9wLWNvbG9yPSIjZTE1NzU5Ii8+PHN0b3Agb2Zmc2V0PSIxMDAlIiBzdG9wLWNvbG9yPSIjNTlhMTRmIi8+PC9saW5lYXJHcmFkaWVudD48cGF0aCBkPSJNMzA1LDI2OS42NTA0ODY4OTI5NjQ2QzQ0Ny41LDI2OS42NTA0ODY4OTI5NjQ2LDQ0Ny41LDI4Ni42MDQxNjY2NjY2NjY2Myw1OTAsMjg2LjYwNDE2NjY2NjY2NjYzIiBzdHJva2U9InVybCgjbGluZWFyR3JhZGllbnQtMTApIiBzdHJva2Utd2lkdGg9IjM5Ljg3NSIvPjwvZz48ZyBjbGFzcz0ibGluayIgc3R5bGU9Im1peC1ibGVuZC1tb2RlOiBtdWx0aXBseTsiPjxsaW5lYXJHcmFkaWVudCBpZD0ibGluZWFyR3JhZGllbnQtMTEiIGdyYWRpZW50VW5pdHM9InVzZXJTcGFjZU9uVXNlIiB4MT0iMzA1IiB4Mj0iNTkwIj48c3RvcCBvZmZzZXQ9IjAlIiBzdG9wLWNvbG9yPSIjZTE1NzU5Ii8+PHN0b3Agb2Zmc2V0PSIxMDAlIiBzdG9wLWNvbG9yPSIjZWRjOTQ5Ii8+PC9saW5lYXJHcmFkaWVudD48cGF0aCBkPSJNMzA1LDMyMi44MTcxNTM1NTk2MzEyN0M0NDcuNSwzMjIuODE3MTUzNTU5NjMxMjcsNDQ3LjUsMzY2Ljc3MDgzMzMzMzMzMzMsNTkwLDM2Ni43NzA4MzMzMzMzMzMzIiBzdHJva2U9InVybCgjbGluZWFyR3JhZGllbnQtMTEpIiBzdHJva2Utd2lkdGg9IjY2LjQ1ODMzMzMzMzMzMzMzIi8+PC9nPjwvZz48L3N2Zz4=) Follow the widths: Engineering takes the largest slice, Infra splits into Hardware and Cloud, and the single thin Marketing ribbon is the whole marketing story. Sankey answers "where does the budget go without a legend" — the flow is sized by value, the way a pie chart shows proportion per slice. ## Building the roadmap page[​](#building-the-roadmap-page "Direct link to Building the roadmap page") The three charts are one planning cycle rendered three ways: 1. **Gantt from the calendar.** Sections = workstreams, bars = items, `after` = blockers. Update dates in the planning meeting. 2. **Quadrant from the debate.** Every item gets coordinates; the argument happens *over the plot*, not over a ranked list. 3. **Sankey from the ledger.** Amounts per line; the ribbons expose where priority-money actually flows. Keep the roadmap page's siblings close: the **decision records** behind the priorities as a [requirement traceability](/blog/mermaid-requirement-diagram-confluence.md) and the **sprint view** of the same work as a [Kanban board](/blog/mermaid-kanban-board-workflow-confluence.md). ## FAQ[​](#faq "Direct link to FAQ") **Does Confluence have a built-in Gantt or roadmap chart tool?** No — Confluence has no native charting of this kind. Mermaid Plus Diagrams & AI Agent for Confluence renders `gantt`, `quadrantChart` and `sankey-beta` from editable text with a live preview. **Gantt, quadrant or Sankey — which does this decision need?** Gantt = when (schedule, dependencies, milestones). Quadrant = which first (effort vs impact). Sankey = where it goes (quantity flows). One roadmap page holds all three. **How do I show dependencies in a Mermaid Gantt?** Reference an earlier task with `after ` or mark the critical path with `crit`. The dependency is drawn, not just implied by dates. **How do I keep the roadmap chart from going stale?** Edit it in the same meeting that changes the plan — text means the diff *is* the plan update, and the chart survives as the wiki's living record. Render every Mermaid diagram type — gantt, quadrant, sankey, pie, XY and 24 more — in [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), free for up to 10 users. Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [gantt](/blog/tags/gantt.md) * [quadrant](/blog/tags/quadrant.md) * [sankey](/blog/tags/sankey.md) * [roadmap](/blog/tags/roadmap.md) * [planning](/blog/tags/planning.md) * [how-to](/blog/tags/how-to.md) --- # Map States & Approval Workflows in Confluence with Mermaid September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The issue workflow lives in a wiki page that says "the approval chain is: team lead, then manager, then finance". The config says otherwise, the Jira post-function disagrees, and the incident report asks "who actually approved this?" — with three different answers on screen. A prose paragraph cannot hold a workflow; a diagram can, if it *is* the workflow. **Quick answer:** document state machines and approval chains in Confluence as Mermaid `stateDiagram-v2`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Every legal state, every transition, every human decision on a labeled arrow — in editable text that stays true. This post gives you three copy-paste examples: an issue lifecycle, a spending approval chain, and a retry loop with a timeout. ## Why a state diagram beats a static workflow picture[​](#why-a-state-diagram-beats-a-static-workflow-picture "Direct link to Why a state diagram beats a static workflow picture") A workflow drawn once as a flowchart is a picture of one run. A state diagram is the *definition* — it must answer the questions your process actually gets asked: * **What can this be?** The full set of legal states, no missing statuses * **Who moves it?** The actor on each transition, visible as the arrow label * **Where can it get stuck?** The transitions that loop back — retries, resubmissions, timeouts That last question is the one where prose fails hardest. "It should loop" is not a workflow definition; a drawn self-loop with a `retry` label is. State diagrams force you to draw the loops, and that is exactly where real processes hide. ## Copy-paste 1: the issue lifecycle[​](#copy-paste-1-the-issue-lifecycle "Direct link to Copy-paste 1: the issue lifecycle") Start with a lifecycle every team recognizes — the issue statuses and the moves between them. This is the diagram to put beside the "workflow" section of a space: ``` stateDiagram-v2 %% title: Issue lifecycle with verification [*] --> Open Open --> In Progress : assign In Progress --> In Review : link PR In Review --> In Progress : changes requested In Review --> Resolved : merge Resolved --> [*] ``` ![Issue lifecycle with verification](/assets/images/issue-lifecycle-with-verification-788699067eace7cab22b2c5e56b99ff2.svg) Six states, four transitions, one loop. The loop (`In Review --> In Progress : changes requested`) is the line prose would have buried as "and then, if needed, it goes back". In a state diagram it is a visible arrow — contributors see it, reviewers see it, the config owner checks it matches the Jira workflow. ## Copy-paste 2: the approval chain[​](#copy-paste-2-the-approval-chain "Direct link to Copy-paste 2: the approval chain") Approval chains are state machines where a human sits on each transition. Draw the chain top-down and mark the decision on each arrow — the reader can spot where a workflow waits on a person: ``` stateDiagram-v2 %% title: Spending approval chain [*] --> Draft Draft --> Submitted : submit Submitted --> TeamApproved : team lead approves Submitted --> Rejected : team lead rejects TeamApproved --> ManagerApproved : manager approves TeamApproved --> Rejected : manager rejects ManagerApproved --> FinanceApproved : finance approves ManagerApproved --> Rejected : finance rejects FinanceApproved --> Booked : post to ledger Rejected --> Draft : resubmit with changes Booked --> [*] ``` ![Spending approval chain](/assets/images/spending-approval-chain-a43050f8dcaf468b5637797039f3dda3.svg) The chain reads top-down like a ladder: each approval stage unlocks the next, and every rejection has a visible escape hatch (`Rejected --> Draft : resubmit`). When the config changes — a new approval stage, a skip rule for small amounts — the edit is one more row in the diagram, reviewed in the same change as the workflow config. ## Copy-paste 3: retries and timeouts[​](#copy-paste-3-retries-and-timeouts "Direct link to Copy-paste 3: retries and timeouts") Workflows that retry are where state diagrams earn their keep. A retry is not prose — it is a state with a loop that must eventually exit, or the process runs forever. Show the exit condition on the loop: ``` stateDiagram-v2 %% title: Job retry loop with backoff and timeout [*] --> Queued Queued --> Running : worker picks up Running --> Success : done Running --> Retrying : transient error Retrying --> Running : attempt 1..3, backoff 10s Retrying --> Failed : 3 attempts exhausted Failed --> Queued : reschedule Success --> [*] ``` ![Job retry loop with backoff and timeout](/assets/images/job-retry-loop-with-backoff-and-timeout-a1f3e446a7ee130248d86a419b0a630e.svg) The loop (`Running -- Retrying -- Running`) carries two facts prose usually loses: how many attempts, and what the backoff is. The `Failed --> Queued : reschedule` arrow shows the manual escape — the process does not die, it re-enters. On a page next to runbooks, this is the diagram the on-call reads first. ## The diagram that behaves like the workflow[​](#the-diagram-that-behaves-like-the-workflow "Direct link to The diagram that behaves like the workflow") A state diagram's real advantage is that it behaves like the thing it describes: it is editable text, so it can be reviewed, diffed, and kept honest. In [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), the macro shows the source beside the rendered SVG — the workflow owner reviews the diagram in the same change that updates the workflow config, and the wiki stops telling the three-part story that prompted this post. Keep the states exhaustive and the transitions labeled with actors, and the diagram becomes the single source of truth for "what state can this be in, and who moves it". That is the question every process owner wishes they could answer — now it is visible. ## Where this lives beside your other Confluence diagrams[​](#where-this-lives-beside-your-other-confluence-diagrams "Direct link to Where this lives beside your other Confluence diagrams") State diagrams cover the workflow half; the other diagram types cover the seams. Keep the state machine on the workflow page (this post), the step-by-step process as a flowchart ([CI/CD pipeline diagrams](/blog/mermaid-ci-cd-pipeline-diagram-confluence.md)), and the system structure as a class diagram on the architecture page ([class diagrams for your codebase](/blog/mermaid-class-diagram-document-codebase-confluence.md)). One space, four diagram types, each answering the question it is best at. ## FAQ[​](#faq "Direct link to FAQ") **What is the difference between a Mermaid state diagram and a flowchart?** A flowchart shows steps; a state diagram shows the states a thing can be in and the events that move it. For workflows with clear statuses, stateDiagram-v2 self-documents better — every transition must be explicit, so the diagram cannot hand-wave the loops. **Can a state diagram express concurrent or retrying states?** Yes. Group parallel statuses inside a composite (`state X { ... }`), and draw a retry as a transition back to an earlier state with a label like 'attempt 1..3, backoff 10s'. Example 3 shows a retry that exits after three attempts. **How do I document an approval chain?** Model each stage as a state and each approve/reject decision as a labeled transition. The ladder reads top-down, and the rejection escape hatch ('resubmit') is a visible arrow — example 2 shows a three-stage spend approval. **Do state diagrams replace flowcharts in Confluence?** No — they complement. Use a flowchart for step order, a state diagram for legal states and the actor on each move. Teams usually keep both: a flowchart for the happy path, a state diagram for the workflow definition. Render every Mermaid diagram type — state, flowchart, class, ER, gitGraph and 24 more — in [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), free for up to 10 users. Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [state-diagram](/blog/tags/state-diagram.md) * [workflow](/blog/tags/workflow.md) * [approval](/blog/tags/approval.md) * [how-to](/blog/tags/how-to.md) --- # draw\.io vs Mermaid in Confluence: Which Fits Your Docs? September 28, 2026 · 16 min read [NGPilot](https://ngpilot.com) Quick Answer draw\.io supports Mermaid now — so "does draw\.io do Mermaid?" is no longer the question. The question is **what the source becomes**. In [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), the Mermaid text stays the diagram: page history shows a text diff, an update is one line, and a Rovo agent can create, read, update or convert diagrams from chat. In draw\.io, Mermaid is an import step that turns the diagram into native draw\.io shapes, so you get full styling and shape-library freedom but the page holds shape data instead of reviewable text. On the AI side the difference is where the processing happens: Mermaid Plus runs on Atlassian Forge with Atlassian's own Rovo agent, so the diagram and the AI both stay inside the Atlassian trust boundary, covered by your existing Atlassian agreement. **Text-first docs → Mermaid Plus. Visual-first, icon-heavy or migration-heavy work → draw\.io.** What you'll learn 1. What changed when draw\.io added Mermaid support in 2026 2. Where the two tools genuinely differ, and where they do not 3. How the AI features compare — canvas generation vs a Rovo agent on the page 4. Where the diagram and the AI data live, and why that decides it for enterprise teams 5. A decision framework for Confluence and Jira teams Every Confluence team ends up choosing a diagram tool, and most start by asking the wrong question: does it support Mermaid? These days, two answers exist. [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/) is built around Mermaid — all 30 Mermaid v12 diagram types, a code editor with live preview, one-click templates for every type, and a Rovo AI agent that works on the page. draw\.io is the most-installed diagramming app on the Atlassian Marketplace, with deep shape libraries, whiteboarding, and a Mermaid importer added to its editor. Both are good tools. This guide compares how they behave in Confluence specifically — how a diagram is created, what is stored on the page, what happens when you need to change it six months later, and what it costs. ## draw\.io added Mermaid in 2026 — here is what actually changed[​](#drawio-added-mermaid-in-2026--here-is-what-actually-changed "Direct link to draw.io added Mermaid in 2026 — here is what actually changed") draw\.io ships Mermaid support in its editor: `Arrange > Insert > Mermaid`, or the `+` button in the toolbar. The diagram type is detected from the first keyword of your source, and draw\.io's documentation lists 29 supported Mermaid keywords — flowcharts, swimlanes, class, state, sequence, ZenUML, ER, requirement, C4, Gantt, journey, kanban, timeline, gitGraph, pie, XY, quadrant, radar, Sankey, treemap, mindmap, block, packet, architecture, Venn, Ishikawa, treeView, Wardley and event modeling. A type outside that list comes back as *unsupported diagram type*; a broken body comes back as a parse error pointing at the problem. The significant change landed in **July 2026**. Previously, inserting Mermaid flattened the diagram into an image — you could see it and nothing more. Now, by default, the Mermaid source is rendered with **native draw\.io shapes inside a Mermaid container group**, with the source attached to that group. That means: * **You can restyle it** with draw\.io's Style tools — fill and line colours, text colours, fonts, labels. Your edits override Mermaid styling and survive regeneration. * **You can move and resize** shapes and repath connectors inside the group. * **You can re-edit the source** — select a shape in the group, click the pen icon, change the Mermaid, click Apply to regenerate. * **You can lock it** with the padlock icon, or insert it as a single uneditable SVG image if you want a read-only diagram. * **You can pick the layout engine** — Dagre by default, with an ELK option for neater orthogonal connectors on large graphs. This is a real capability, and any comparison that still claims "draw\.io cannot do Mermaid" is out of date. It also narrows the gap: draw\.io can now hand you a Mermaid diagram *and* let you finish it as a polished visual artefact. ## The real difference: what the source becomes[​](#the-real-difference-what-the-source-becomes "Direct link to The real difference: what the source becomes") Here is the honest core of the comparison. Both tools accept the same text: ``` sequenceDiagram participant Docs as Confluence participant CI as CI pipeline participant Reg as Registry CI->>Reg: push image Reg-->>Docs: webhook updates page Docs->>Docs: rerender Mermaid diagram ``` What each tool does with it next is the whole story. **In Mermaid Plus, the text is the diagram.** The Mermaid source is stored as the macro's source. Page history shows a readable text diff, so you can see that someone added a `Docs->>Docs: rerender` arrow on a given date. Changing the diagram means changing a line and saving. The source is greppable, reviewable, and copy-pasteable into a pull request, a code review, or a chat with an AI assistant. **In draw\.io, the text becomes shapes.** The Mermaid source is used to generate native draw\.io shapes inside a container group. The source is still attached (that is the July 2026 improvement), but the diagram in the page is now shape and XML data. Your restyling, manual resizing and repathed connectors live alongside the generated geometry, and regenerating from source overrides geometry changes. Practically: you can style it freely, and you can still regenerate — but the page is no longer a text document, and a page-history diff is not a readable description of what changed. This is why the two tools attract different teams. If your diagrams are *artifacts of your documentation*, text-native wins. If your diagrams are *designs you will present and iterate on visually*, draw\.io's model wins. ## Mermaid Plus Diagrams & AI Agent for Confluence[​](#mermaid-plus-diagrams--ai-agent-for-confluence "Direct link to Mermaid Plus Diagrams & AI Agent for Confluence") [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/) is a Mermaid editor, not a general-purpose canvas. Everything about it follows from that. * **All 30 Mermaid v12 diagram types** — flowcharts, sequence, class, state, ER, Gantt, pie, C4, mindmaps, ZenUML, use case, journey, requirement, gitGraph, and the rest — each with a one-click Quick Template, so you start from working code instead of a blank canvas. * **Live preview beside the code** — syntax errors surface while you type rather than when a reader opens the page. * **Text-native storage** — the source is the document. Page history, diffs, copy-paste and "edit one line" all work the way your team expects from code. * **A Rovo AI agent that works on the page** — see the next section. * **Themes, custom colors and fonts**, and **automatic dark mode** so diagrams follow the reader's Confluence theme. * **Free for up to 10 users**, running on Atlassian Forge with no external rendering server. ### The Rovo agent: AI on the page, not just in the canvas[​](#the-rovo-agent-ai-on-the-page-not-just-in-the-canvas "Direct link to The Rovo agent: AI on the page, not just in the canvas") The agent shipped with the current version of the app and it is the part that has no draw\.io equivalent. Four capabilities, all operating on the page you are looking at: * **Create** — describe what you want ("make a flowchart of our deployment process") and the diagram renders in place on the page. * **Read** — ask for the source and version of a diagram and get it back in chat, so you can diff, copy or paste it into a repository. * **Update** — say "make this better" and the agent revises the diagram in place, preserving the macro's settings. * **Convert** — turn code blocks that are already on the page into rendered diagrams. This is the fix for the most common Confluence Mermaid failure: an AI assistant or a colleague pasted a Mermaid code block into the page and it stayed dead text. ## Privacy: the diagram and the AI both stay inside Atlassian[​](#privacy-the-diagram-and-the-ai-both-stay-inside-atlassian "Direct link to Privacy: the diagram and the AI both stay inside Atlassian") This is the part that decides the question for a lot of enterprise teams, so it is worth being precise rather than reassuring. **The diagram is Atlassian data, not vendor data.** Mermaid Plus runs on Atlassian Forge and stores the Mermaid source as native content on the Confluence page. It is searchable, permissioned by Confluence's own rules, and versioned by page history. There is no second copy in a vendor account, because there is no vendor account. **The agent is Atlassian's, not a bolted-on third-party AI.** Rovo is part of Atlassian Cloud and ships inside the platform, included with Standard, Premium and Enterprise plans. You do not sign a separate DPA with an AI vendor, create an account with one, or add one to your app inventory. The vendor whose AI you are evaluating is us — the app vendor — and the AI itself is Atlassian's. **Your inputs are not used to train anyone else's models.** Atlassian states that Rovo inputs and outputs are not used to train, fine-tune or improve third-party LLM models or services, that its third-party-hosted LLM partners operate under strict zero data retention agreements, and that no provider retains the data you submit or the responses you receive. Requests are sent per-request over an SSL-encrypted connection, processed for the response, and returned. **The agent inherits Confluence's permissions.** Rovo honours existing permissions, so it cannot read a page or act on content the person asking does not already have access to. Page restrictions apply to the agent exactly as they apply to the reader. **Admins keep the controls.** AI features are managed from Atlassian Administration, Rovo activity is visible in the audit log, and Rovo data can be pinned to the same region as your Jira and Confluence data. Cloud Enterprise organisations can go further and elect to use only Atlassian-hosted LLMs, which keeps inference inside the Atlassian Cloud boundary rather than routing it to an external provider. Two honest caveats, because a privacy section without them is just marketing. By default, Rovo routes requests to third-party-hosted model providers to generate the response — under the zero data retention terms above, and listed in Atlassian's public sub-processor list, so your security team can review exactly who is in the path. And Rovo retains chat and agent inputs and outputs for 30 days for safety and security purposes, while Atlassian may use de-identified, aggregated metadata to fine-tune open-source models that run inside Atlassian's own infrastructure — controllable through your organisation's data contribution settings. Contrast that with draw\.io, where AI generation (Smart Templates and a Generate tool that can call OpenAI, Claude or Gemini) is a feature of a third-party vendor's editor. draw\.io does offer a **zero egress** option on its Forge app, which is a genuinely strong control — but it is an **Advanced edition** feature, so it is an enterprise-tier purchase rather than the default posture. ## draw\.io for Confluence[​](#drawio-for-confluence "Direct link to draw.io for Confluence") draw\.io for Confluence is the most-installed and highest-rated diagramming app on the Atlassian Marketplace — rated 4.8/5 across more than 1,200 reviews — run by JGraph as a Platinum Marketplace Partner. It is a mature, general-purpose diagramming suite, and for a lot of work it is the right tool. Its strengths: * **Shape library depth** — AWS, Azure, Google Cloud, Cisco, IBM and other network and cloud icon sets, plus UML 2.5 and BPMN 2.0 libraries that Mermaid has no equivalent for. * **Whiteboarding in the same app** — a whiteboard editor for meetings and brainstorming alongside the diagram editor. * **Migration paths** — import from Visio (`.vsdx`), Gliffy and draw\.io XML; export to XML, PDF, SVG, PNG, HTML and CSV. * **Layout tooling** — auto-layout plus advanced layout containers, and an ELK option for Mermaid-generated graphs. * **AI generation inside the canvas** — Smart Templates and a Generate tool that can use OpenAI, Claude or Gemini to produce a starting diagram you then edit as shapes. * **Enterprise governance** — Standard and Advanced editions, a dedicated account manager, custom security reviews, and a zero-egress option on Advanced; the app is Atlassian Cloud Fortified. * **Broad platform support** — Confluence Cloud plus Server and Data Center, and an equivalent app for Jira. Where it costs you: it is a commercial license with per-user pricing from the first seat, the diagram is stored as XML shape data rather than text, and "make the diagram match the schema" is a manual re-import rather than a one-line edit. ## Side-by-side comparison[​](#side-by-side-comparison "Direct link to Side-by-side comparison") | Dimension | Mermaid Plus Diagrams & AI Agent | draw\.io for Confluence | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | | **What the source becomes** | The canonical text of the diagram, stored as-is | Native draw\.io shapes in a Mermaid container group | | **Diagram types** | All 30 Mermaid v12 types | draw\.io's own shape libraries plus 29 Mermaid keywords | | **Page history** | Readable text diffs | Shape/XML change history | | **Editing model** | Type code, live preview, save | Draw, drag, restyle; regenerate from source when needed | | **AI** | Rovo agent: create, read, update, convert on the page | Smart Templates and a Generate tool inside the canvas | | **Where the AI runs** | Atlassian Rovo, inside the platform; no third-party AI account, inputs not used to train third-party models, admin controls and audit logs | Vendor feature in a third-party app; zero egress available on the Advanced edition only | | **Templates** | One-click per diagram type | Smart Templates, AI-generated starters | | **Shape libraries** | Mermaid diagram types, themed and colorable | Deep cloud, network, UML 2.5, BPMN 2.0, org chart, floorplan | | **Whiteboarding** | No | Yes, separate whiteboard editor | | **Migration** | Paste Mermaid text | Visio `.vsdx`, Gliffy, XML import and export | | **Dark mode** | Automatic | Yes, selectable | | **Confluence / Jira** | Confluence and Jira apps | Confluence Cloud, Server, Data Center, and Jira | | **Pricing** | Free for up to 10 users | Commercial, per user, Standard and Advanced editions, free trial | | **Best for** | Text-first docs, doc-as-code, AI-generated diagrams | Visual-first diagrams, icon-heavy architecture, enterprise rollout | ## Decision framework: pick in 60 seconds[​](#decision-framework-pick-in-60-seconds "Direct link to Decision framework: pick in 60 seconds") 1. **Do your diagrams need to diff, review, or live in a repository?** → Yes: **Mermaid Plus**. Text-native is the only one of the two that gives you that. 2. **Do you need cloud provider icons, BPMN 2.0, or Visio migration?** → Yes: **draw\.io**. No Mermaid tool covers those stencil libraries. 3. **Do you want an agent to draft and revise diagrams from a sentence, in the page?** → Yes: **Mermaid Plus** (Rovo agent). draw\.io's AI works inside the canvas instead. 4. **Are you a team of 10 or fewer, or standardizing on one tool across thousands of users?** → 10 or fewer: **Mermaid Plus**, free. Thousands: compare total cost — draw\.io's per-user license against the tools you would otherwise buy for whiteboarding and diagrams. ## Many teams run both — and that is fine[​](#many-teams-run-both--and-that-is-fine "Direct link to Many teams run both — and that is fine") The two tools do not conflict; they are separate macros and can sit on the same page. The common pattern is a split by *kind* of diagram: Mermaid Plus for the diagrams that are generated or versioned — schemas, API sequences, CI/CD pipelines, state machines, Gantt timelines — and draw\.io for the diagrams that are designed — network topologies with vendor icons, BPMN process models, org charts, whiteboard sessions. If you want one tool that covers both modes instead of two apps, [Excalidraw plus Whiteboards for Confluence](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence/) gives you a freeform canvas with 220+ shape libraries plus Mermaid import. ## Frequently asked questions[​](#frequently-asked-questions "Direct link to Frequently asked questions") ### Can draw\.io do Mermaid diagrams in Confluence?[​](#can-drawio-do-mermaid-diagrams-in-confluence "Direct link to Can draw.io do Mermaid diagrams in Confluence?") Yes — `Arrange > Insert > Mermaid`, or `+` then Mermaid. draw\.io documents 29 supported Mermaid keywords, and since July 2026 the diagram is generated as native draw\.io shapes inside a Mermaid container group with the source attached, so you can restyle it, resize it, lock it, and re-open the source to regenerate. ### So what is the real difference between Mermaid and draw\.io in Confluence?[​](#so-what-is-the-real-difference-between-mermaid-and-drawio-in-confluence "Direct link to So what is the real difference between Mermaid and draw.io in Confluence?") What happens to the source. Mermaid Plus keeps the text as the diagram — text diffs in page history, one-line updates, greppable source. draw\.io converts Mermaid into native shapes, which buys styling and library freedom but makes the page shape data rather than a reviewable text document. ### Which one should a Confluence team choose in 2026?[​](#which-one-should-a-confluence-team-choose-in-2026 "Direct link to Which one should a Confluence team choose in 2026?") Text-first teams — doc-as-code, AI-generated diagrams, standard types like flowcharts, sequence, ER, Gantt and C4 — should use Mermaid Plus. Visual-first teams that need cloud icon sets, BPMN 2.0, UML 2.5, Visio migration, whiteboarding, or enterprise zero-egress support should use draw\.io. Plenty of teams install both and split by diagram type. ### Is Mermaid or draw\.io cheaper for Confluence?[​](#is-mermaid-or-drawio-cheaper-for-confluence "Direct link to Is Mermaid or draw.io cheaper for Confluence?") Mermaid Plus Diagrams & AI Agent for Confluence is free for up to 10 users. draw\.io for Confluence is a paid Marketplace app with Standard and Advanced editions and a free trial, priced per user from the first seat. Small teams pay nothing for Mermaid Plus; a large rollout is a real line item for draw\.io. ### Can I move my draw\.io diagrams to Mermaid Plus?[​](#can-i-move-my-drawio-diagrams-to-mermaid-plus "Direct link to Can I move my draw.io diagrams to Mermaid Plus?") Not automatically — a draw\.io diagram is XML, not text, so there is no reliable reverse conversion. The practical route is to regenerate diagrams as Mermaid source from whatever you already have (your schema, your OpenAPI spec, your pipeline config) and paste that in. ### Which has the better AI story for Confluence diagrams?[​](#which-has-the-better-ai-story-for-confluence-diagrams "Direct link to Which has the better AI story for Confluence diagrams?") draw\.io generates inside the canvas: Smart Templates and a Generate tool using OpenAI, Claude or Gemini, producing editable shapes. Mermaid Plus ships a Rovo agent that acts on the page — it creates a diagram from a sentence, reads the source back, revises it in place, and converts Mermaid code blocks already on the page into rendered diagrams. If your diagrams are generated by AI assistants, the convert capability is the one that matters most. ### Where does the diagram and the AI data actually live?[​](#where-does-the-diagram-and-the-ai-data-actually-live "Direct link to Where does the diagram and the AI data actually live?") Both inside Atlassian. Mermaid Plus is a Forge app that stores the Mermaid source as native content on the Confluence page — searchable, permissioned, and versioned like the rest of the page, with no copy sitting in a vendor account. The agent is Atlassian Rovo, part of the platform rather than a separate AI vendor you have to contract with. On the AI side, Atlassian states that Rovo inputs and outputs are not used to train, fine-tune or improve third-party LLM models or services; that its third-party-hosted LLM partners operate under strict zero data retention agreements; and that no provider retains the data you submit or the responses you receive. Rovo honours existing Confluence permissions, its activity shows up in the admin audit log, and Rovo data can be pinned to the same region as your Jira and Confluence data. Cloud Enterprise organisations can elect to use only Atlassian-hosted LLMs, which keeps inference inside the Atlassian Cloud boundary instead of routing it to an external provider. Two caveats worth knowing: by default requests are routed to third-party-hosted providers to generate the response, under those zero data retention terms and listed in Atlassian's public sub-processor list, so your security team can audit exactly who sits in the path. And Rovo retains chat and agent inputs and outputs for 30 days for safety and security, while Atlassian may use de-identified, aggregated metadata to fine-tune open-source models running inside Atlassian's own infrastructure — switchable through your organisation's data contribution settings. draw\.io's equivalent AI is a feature of a third-party vendor's editor. It does offer a **zero egress** option on its Forge app, which is a strong control, but only on the **Advanced edition**. *** *Compare the full set of Confluence diagram apps in the [app catalog](/apps.md), or see how Mermaid, Excalidraw and Graphviz divide the work in [Confluence diagram tools compared](/blog/confluence-diagram-tools-comparison.md).* Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [drawio](/blog/tags/drawio.md) * [draw-io](/blog/tags/draw-io.md) * [comparison](/blog/tags/comparison.md) * [diagrams](/blog/tags/diagrams.md) --- # Mermaid vs PlantUML vs Graphviz for Confluence: Which Diagram Tool to Choose August 2, 2026 · 7 min read [NGPilot](https://ngpilot.com) Quick Answer Mermaid, PlantUML, and Graphviz are the three most popular text-based diagramming languages. **Mermaid** is the easiest to learn and covers the widest range (30 diagram types). **PlantUML** excels at detailed UML with precise notation control. **Graphviz** is best for technical network and dependency graphs. Most Confluence teams should start with Mermaid and add Graphviz for network diagrams if needed. What you'll learn 1. The strengths and weaknesses of each tool 2. Which diagram types each one supports 3. How easy each is to learn and use 4. A practical recommendation for Confluence teams Text-based diagramming — writing a few lines of code that render into a diagram — is how modern teams keep diagrams in sync with their documentation. No more drawing boxes by hand in Visio, exporting screenshots, and pasting them into Confluence where they go stale. With text-based diagrams, you edit the source and the diagram redraws instantly. But there are three major text-based diagramming languages, and they are not interchangeable. Each has different strengths, different syntax, and different ideal use cases. This guide compares Mermaid, PlantUML, and Graphviz so you can choose the right one (or combination) for your Confluence team. ## Mermaid: the all-rounder[​](#mermaid-the-all-rounder "Direct link to Mermaid: the all-rounder") Mermaid is the most popular text-based diagramming language, and for good reason. It is easy to learn, supports the widest range of diagram types, and has the best ecosystem of Confluence integrations. **Strengths:** * **30 diagram types** — flowcharts, sequence, class, state, ER, Gantt, pie, C4, mindmaps, user journeys, and more * **Simple syntax** — a flowchart is literally `A --> B --> C` * **One-click templates** — every diagram type ships with a working starting point * **Live preview** — see the diagram render as you type * **Themes and dark mode** — customize colors, fonts, and auto-adapt to dark mode * **Best Confluence support** — dedicated macros with deep integration **Weaknesses:** * Less precise control over layout than Graphviz for complex graphs * UML notation is not as detailed as PlantUML for strict UML compliance * Very complex diagrams can become hard to read in the source **Best for:** Teams that need a wide variety of diagram types (flowcharts, Gantt charts, ER models, sequence diagrams) with an easy learning curve. This covers 90% of what most Confluence teams need. **Example syntax (flowchart):** ``` graph TD A[User Request] --> B{Authenticated?} B -->|Yes| C[Process Request] B -->|No| D[Redirect to Login] C --> E[Return Response] ``` ## PlantUML: the UML specialist[​](#plantuml-the-uml-specialist "Direct link to PlantUML: the UML specialist") PlantUML is the go-to for teams that need strict, detailed UML diagrams — particularly class diagrams, component diagrams, and sequence diagrams with precise notation. **Strengths:** * **Deepest UML support** — class, object, component, deployment, activity, state, and sequence diagrams with full UML 2.x notation * **Precise control** — detailed styling, skin parameters, and layout hints * **Rich syntax** — supports notes, grouping, partitions, and complex relationships * **Available in Markdown macros** — Enhanced Markdown for Confluence renders PlantUML inline **Weaknesses:** * **Steeper learning curve** — the syntax is more verbose and less intuitive than Mermaid * **Narrower scope** — focused on UML; less suited for flowcharts, Gantt charts, or mindmaps * **Fewer Confluence integrations** — typically rendered through a Markdown macro or a dedicated PlantUML server, not a standalone Confluence macro * **Server dependency** — traditional PlantUML requires a rendering server (though some macros handle this) **Best for:** Engineering teams that produce formal UML documentation — architecture specs, detailed class hierarchies, and component interaction diagrams — where UML compliance matters. **Example syntax (sequence diagram):** ``` @startuml actor User participant "Order Service" as OS participant "Payment Gateway" as PG User -> OS: Place order OS -> PG: Charge payment PG --> OS: Payment confirmed OS --> User: Order confirmed @enduml ``` ## Graphviz: the graph engine[​](#graphviz-the-graph-engine "Direct link to Graphviz: the graph engine") Graphviz (DOT language) is a layout engine for graphs where the structure matters more than the visual styling. It is unmatched for technical network diagrams, dependency graphs, and organizational charts with many nodes. **Strengths:** * **Superior automatic layout** — the Graphviz layout engine handles complex graphs with hundreds of nodes and produces clean, readable layouts * **Technical and precise** — ideal for dependency maps, call graphs, state machines, and network topologies * **DOT syntax** — compact and focused on nodes and edges * **Dedicated Confluence app** — Graphviz Charts for Confluence with live preview **Weaknesses:** * **Aesthetic style** — diagrams look technical and utilitarian, not polished or hand-drawn * **Limited diagram types** — primarily directed and undirected graphs; no native Gantt, pie, or mindmap support * **Less intuitive** — DOT syntax is straightforward but the layout engine's behavior can be unpredictable for custom positioning **Best for:** DevOps and infrastructure teams documenting network topologies, service dependencies, and system call graphs. Also strong for large organizational charts that auto-layout engines handle well. **Example syntax (dependency graph):** ``` digraph dependencies { API -> AuthService API -> Database AuthService -> Redis Database -> BackupService API -> MessageQueue MessageQueue -> Worker } ``` ## Side-by-side comparison[​](#side-by-side-comparison "Direct link to Side-by-side comparison") | Feature | Mermaid | PlantUML | Graphviz | | -------------------------- | ------------------------------- | ------------------------------ | --------------------------------- | | **Diagram types** | 29 (widest) | \~12 (UML-focused) | 2 (directed/undirected graphs) | | **Learning curve** | Easy | Moderate | Easy | | **Best at** | Flowcharts, Gantt, ER, mindmaps | Class, sequence, component UML | Network graphs, dependency maps | | **Layout control** | Moderate | Moderate | Strong (automatic) | | **Visual style** | Clean, modern, themeable | Formal UML | Technical, utilitarian | | **Dark mode** | Yes (auto) | Via skin params | Via color schemes | | **Confluence integration** | Dedicated macro (Mermaid Plus) | Via Markdown macro | Dedicated macro (Graphviz Charts) | | **Template library** | 29 one-click templates | Community examples | Limited | | **Free for ≤10 users** | Yes | Yes (via Enhanced Markdown) | Yes | ## Recommendation for Confluence teams[​](#recommendation-for-confluence-teams "Direct link to Recommendation for Confluence teams") **Start with Mermaid.** It covers the widest range of diagram types, has the easiest learning curve, and has the best Confluence integration (Mermaid Plus Diagrams & AI Agent for Confluence with 29 one-click templates). For most teams, Mermaid alone handles 90% of diagramming needs. **Add Graphviz if you do network/infrastructure diagrams.** DevOps and infrastructure teams benefit from Graphviz's superior auto-layout for complex dependency graphs and network topologies. Graphviz Charts for Confluence is a separate, complementary app. **Use PlantUML if you need strict UML.** If your architecture documentation requires formal UML 2.x notation — detailed class hierarchies, precise component diagrams — PlantUML (available via Enhanced Markdown for Confluence) is the right tool. For most teams, Mermaid's UML support is sufficient. **The practical combination many teams land on:** Mermaid Plus Diagrams & AI Agent for Confluence for flowcharts, ER, Gantt, and sequence diagrams + Graphviz Charts for Confluence for network and dependency graphs. This duo covers virtually every diagramming need in a typical engineering organization. ## Explore diagram solutions[​](#explore-diagram-solutions "Direct link to Explore diagram solutions") Browse our [diagram solutions](/solutions.md) to see how Mermaid, Excalidraw, and Graphviz fit together for Confluence teams, or compare the apps side by side in the [full catalog](/apps.md). If your team is choosing between a visual editor and text-based diagrams, read [draw.io vs Mermaid in Confluence](/blog/mermaid-vs-drawio-confluence.md) for the source-code argument that decides it. ## Frequently Asked Questions[​](#frequently-asked-questions "Direct link to Frequently Asked Questions") ### Can I convert between Mermaid and PlantUML?[​](#can-i-convert-between-mermaid-and-plantuml "Direct link to Can I convert between Mermaid and PlantUML?") Not directly. The syntaxes are different enough that there is no reliable automatic converter. If you switch tools, you rewrite the diagrams. This is why it is worth choosing the right tool upfront. ### Which tool has the best Confluence integration?[​](#which-tool-has-the-best-confluence-integration "Direct link to Which tool has the best Confluence integration?") Mermaid has the deepest Confluence integration through Mermaid Plus Diagrams & AI Agent for Confluence — a dedicated macro with live preview, 30 templates, themes, and dark mode. Graphviz Charts for Confluence offers a similar dedicated experience for DOT diagrams. PlantUML is typically rendered through a Markdown macro rather than a standalone diagramming macro. ### Do I need a separate server for any of these?[​](#do-i-need-a-separate-server-for-any-of-these "Direct link to Do I need a separate server for any of these?") No. All three can render entirely client-side or via Atlassian Forge compute — no external rendering server required. Avoid older PlantUML integrations that depend on a self-hosted PlantUML server. *** *Explore [diagram solutions](/solutions.md) or browse the [full app catalog](/apps.md) to compare Mermaid, Graphviz, and Excalidraw for Confluence.* Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [plantuml](/blog/tags/plantuml.md) * [graphviz](/blog/tags/graphviz.md) * [comparison](/blog/tags/comparison.md) * [diagrams](/blog/tags/diagrams.md) --- ## [Free Diagram Apps for Confluence — Excalidraw & Free-Tier Limits](/blog/confluence-free-diagram-plugin.md) May 10, 2026 · 4 min read [NGPilot](https://ngpilot.com) Need diagram tools for Confluence without paying for a large team? NGPILOT's three diagramming apps — Mermaid Plus, Excalidraw Plus, and Graphviz Charts — are all **free for up to 10 users**. This guide compares them so you can pick the right free diagram plugin for your Confluence. **Tags:** * [confluence](/blog/tags/confluence.md) * [diagrams](/blog/tags/diagrams.md) * [free](/blog/tags/free.md) * [mermaid](/blog/tags/mermaid.md) * [excalidraw](/blog/tags/excalidraw.md) * [graphviz](/blog/tags/graphviz.md) * [comparison](/blog/tags/comparison.md) [**Read more**](/blog/confluence-free-diagram-plugin.md) --- ## [Confluence Source Editor Compared — Free vs Pro](/blog/confluence-source-editor-comparison.md) May 2, 2026 · 11 min read [NGPilot](https://ngpilot.com) Confluence stores every page as XML in a format called "Confluence storage format." Most users never see it. But if you have ever tried to fix a broken macro, remove hidden formatting artifacts, or bulk-edit repetitive markup, you know the rich text editor alone is not enough. You need direct access to the underlying source. At NGPILOT, we built two apps for exactly this purpose: **Raw Storage Source Editor for Confluence** (free) and **Raw Storage Source Editor Pro for Confluence** (paid). Both let you open, view, and edit the raw XML behind any Confluence page. This post compares them feature by feature so you can pick the right one for your team. **Tags:** * [comparison](/blog/tags/comparison.md) * [confluence](/blog/tags/confluence.md) * [source-editor](/blog/tags/source-editor.md) * [developer-tools](/blog/tags/developer-tools.md) [**Read more**](/blog/confluence-source-editor-comparison.md) --- ## [Confluence Graphviz Diagrams: DOT Language FAQ & Examples](/blog/faq-graphviz-charts-confluence.md) May 2, 2026 · 16 min read [NGPilot](https://ngpilot.com) Graphviz has been the backbone of automated graph visualization for over three decades. Originally developed at AT\&T Labs, it powers dependency graphs in build systems, call graphs in profilers, and database schemas in ORMs -- anywhere that diagrams need to be generated from structured data rather than drawn by hand. Graphviz Charts for Confluence brings that same engine directly into your Confluence pages, letting you write DOT language descriptions and get polished, auto-laid-out diagrams without leaving your wiki. **Tags:** * [faq](/blog/tags/faq.md) * [confluence](/blog/tags/confluence.md) * [graphviz](/blog/tags/graphviz.md) * [dot](/blog/tags/dot.md) * [diagrams](/blog/tags/diagrams.md) * [charts](/blog/tags/charts.md) [**Read more**](/blog/faq-graphviz-charts-confluence.md) --- ## [ER Diagrams in Confluence: How to Add, Create, and Render Database Schemas](/blog/how-to-create-er-diagrams-confluence.md) May 2, 2026 · 21 min read [NGPilot](https://ngpilot.com) An **ER diagram** (entity-relationship diagram) visualizes a database schema — the tables, columns, primary and foreign keys, and the relationships between them. If your team documents data models, API contracts, or system architecture in Confluence, embedding ER diagrams directly on the page keeps the schema next to the prose instead of stranded in an external tool as a stale screenshot. Confluence has no built-in ER diagram support, so you add it with a Marketplace app. The approach below uses **[Mermaid Plus Diagrams & AI Agent for Confluence](/apps/mermaid-plus-for-confluence.md)**, which renders ER diagrams from plain text — meaning diagrams version, diff, and search alongside the rest of your documentation. What you'll learn 1. How to add an ER diagram to any Confluence page 2. The full Mermaid `erDiagram` syntax — entities, attributes, key types, cardinality 3. Three copy-paste examples (library, e-commerce, SaaS multi-tenant) 4. Common mistakes and how to fix them Entity-Relationship (ER) diagrams are the standard way to visualize database schemas. They show the tables in your database, the columns in each table, primary and foreign key constraints, and the relationships between tables -- one-to-one, one-to-many, and many-to-many. Whether you are designing a new database from scratch, documenting an existing schema for onboarding, or collaborating on a data model before writing migration scripts, an ER diagram communicates structure faster than any amount of prose. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [er-diagram](/blog/tags/er-diagram.md) * [database](/blog/tags/database.md) * [how-to](/blog/tags/how-to.md) * [diagrams](/blog/tags/diagrams.md) [**Read more**](/blog/how-to-create-er-diagrams-confluence.md) --- ## [How to Migrate Confluence Content — Server-to-Cloud, Space Moves & Format Conversion](/blog/how-to-migrate-confluence-content.md) May 2, 2026 · 15 min read [NGPilot](https://ngpilot.com) Who should read this * **IT admins** running Server/Data Center → Cloud migrations * **Teams** reorganizing Confluence spaces after a reorg or M\&A * **Engineering** converting Confluence content to/from Markdown, HTML, or JSON What you'll learn 1. Which tool fits each scenario — CCMA, built-in XML, or Modern Importer Exporter 2. The 5 most common migration pitfalls (broken links, missing attachments, macro failures) and how to avoid each 3. How to choose an export format by fidelity vs portability 4. A copy-paste **migration checklist** for pre-migration, export, import, and validation Migrating Confluence content is something most teams eventually face. Whether you are moving from Confluence Server to Cloud, reorganizing spaces after a company merger, or splitting a monolithic workspace into focused team spaces, the process can feel overwhelming. Pages link to each other, attachments sit deep in page trees, permissions are inherited from parent spaces, and macros pull data from external sources. This guide walks through the entire Confluence content migration process from start to finish. You will learn how to plan your migration, choose the right tools for your scenario, export and import content without losing data, and validate the result. We cover both Atlassian's built-in export features and the **Modern Importer Exporter for Confluence** app for format-based migrations. **Tags:** * [confluence](/blog/tags/confluence.md) * [migration](/blog/tags/migration.md) * [import](/blog/tags/import.md) * [export](/blog/tags/export.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/how-to-migrate-confluence-content.md) --- ## [How to Configure Google Fonts in Confluence (Step-by-Step)](/blog/configure-google-fonts-confluence.md) April 21, 2026 · 2 min read [NGPilot](https://ngpilot.com) Using custom fonts can dramatically improve readability and branding in Confluence. This guide shows how to use the Google Fonts for Confluence app to apply fonts, configure previews, and balance performance. **Tags:** * [confluence](/blog/tags/confluence.md) * [fonts](/blog/tags/fonts.md) * [google-fonts](/blog/tags/google-fonts.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/configure-google-fonts-confluence.md) --- ## [Jira Attachment Permissions FAQ: Download, Access & Troubleshoot](/blog/faq-jira-attachments-permissions.md) April 21, 2026 · 12 min read [NGPilot](https://ngpilot.com) **Tags:** * [faq](/blog/tags/faq.md) * [jira](/blog/tags/jira.md) * [attachments](/blog/tags/attachments.md) * [permissions](/blog/tags/permissions.md) * [troubleshooting](/blog/tags/troubleshooting.md) [**Read more**](/blog/faq-jira-attachments-permissions.md) --- ## [Best Diagram App for Jira — 2026 Comparison with Mermaid & Excalidraw](/blog/jira-diagram-apps-comparison.md) April 18, 2026 · 7 min read [NGPilot](https://ngpilot.com) Every engineering team needs diagrams in Jira — architecture decisions on epics, bug reproduction flows on tickets, wireframes on stories. But Jira has no built-in diagramming. You either paste screenshots from external tools or install a marketplace app. We built two diagram apps for Jira: **Mermaid+ Diagrams for Jira** for text-based diagrams using Mermaid syntax (flowcharts, sequence diagrams, ER models, C4 architecture), and **Excalidraw Diagrams + Whiteboards for Jira** for freeform drawing with 229 built-in shape libraries. In this post we compare both against every alternative on the Atlassian Marketplace. **Tags:** * [jira-diagrams](/blog/tags/jira-diagrams.md) * [mermaid](/blog/tags/mermaid.md) * [excalidraw](/blog/tags/excalidraw.md) * [whiteboard](/blog/tags/whiteboard.md) * [flowchart](/blog/tags/flowchart.md) * [architecture-diagram](/blog/tags/architecture-diagram.md) * [jira-plugin](/blog/tags/jira-plugin.md) [**Read more**](/blog/jira-diagram-apps-comparison.md) --- ## [API Sequence Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-api-sequence-diagram-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The integration doc says "the client calls the API, the API validates and responds" — four words, zero contracts, and the onboarding engineer asks "with what headers, in what order, and what if auth fails?" The code has the truth; the wiki has a paragraph. An API that can't be read as a transcript is an API nobody can safely operate. **Quick answer:** document API flows in Confluence as Mermaid — `sequenceDiagram` for request/response order, `packet-beta` for wire-format frames, ZenUML for branch-heavy async flows — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Each diagram type answers a different reader: what order, what's on the wire, what branches. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [sequence-diagram](/blog/tags/sequence-diagram.md) * [packet](/blog/tags/packet.md) * [zenuml](/blog/tags/zenuml.md) * [api](/blog/tags/api.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-api-sequence-diagram-confluence.md) --- ## [Customer Journey Maps in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-journey-diagram-customer-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The support team knows where refunds leak. The product team knows where onboarding drops. The sales team knows where the pricing page confuses. Three silos, three versions of the customer's experience — and the roadmap meeting spends an hour reconciling them instead of deciding what to fix. What is missing is a single picture with a score on every step. **Quick answer:** draw customer journeys in Confluence as Mermaid `journey` diagrams, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). A journey diagram puts every step in a row and every satisfaction score on one curve — the dips are visible, the actors are labeled, and the whole thing stays editable text. This post gives you three copy-paste examples: onboarding, a support ticket, and a checkout flow with a summary pie. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [journey](/blog/tags/journey.md) * [customer-experience](/blog/tags/customer-experience.md) * [product](/blog/tags/product.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-journey-diagram-customer-confluence.md) --- ## [Confluence Wiki Markup: How to View, Edit & Convert It](/blog/confluence-wiki-markup.md) September 23, 2026 · 6 min read [NGPilot](https://ngpilot.com) Every Confluence page has two faces: the one you see in the editor, and the one the database sees. The database face is the **storage format** — an XHTML document with macros as tags — and before it, Confluence stored pages as **wiki markup**: `h1. headings`, `*bold text*`, `{code}` blocks. People still search for wiki markup because half the internet's Confluence advice, every migration script, and a lot of content written before \~2017 speaks that language. And in 2026 the topic got urgent: Atlassian is retiring the legacy editor (full deprecation April 2026), and the new cloud editor **dropped the Markup macro** entirely. Here's how to view, edit, and convert what's actually stored — with or without admin rights. **Tags:** * [confluence](/blog/tags/confluence.md) * [wiki-markup](/blog/tags/wiki-markup.md) * [storage-format](/blog/tags/storage-format.md) * [how-to](/blog/tags/how-to.md) * [admin](/blog/tags/admin.md) * [migration](/blog/tags/migration.md) [**Read more**](/blog/confluence-wiki-markup.md) --- ## [Expand Macro for Confluence: Collapsible Sections Compared (Native vs Styled)](/blog/confluence-expand-macro.md) August 21, 2026 · 5 min read [NGPilot](https://ngpilot.com) Long pages die from scroll fatigue. Onboarding checklists, troubleshooting trees, API reference details, legal disclaimers — content that only some readers need some of the time is the canonical use case for collapsible sections. Confluence ships a native **expand macro** for exactly this, and for many pages it's enough. This guide covers how the native expand works, where teams typically outgrow it, and what a styled accordion macro adds — so you can pick per page, not per vendor. **Tags:** * [confluence](/blog/tags/confluence.md) * [macros](/blog/tags/macros.md) * [expand](/blog/tags/expand.md) * [accordion](/blog/tags/accordion.md) * [formatting](/blog/tags/formatting.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/confluence-expand-macro.md) --- ## [Mermaid vs PlantUML vs Graphviz for Confluence: Which Diagram Tool to Choose](/blog/mermaid-vs-plantuml-vs-graphviz-confluence.md) August 2, 2026 · 7 min read [NGPilot](https://ngpilot.com) Quick Answer Mermaid, PlantUML, and Graphviz are the three most popular text-based diagramming languages. **Mermaid** is the easiest to learn and covers the widest range (30 diagram types). **PlantUML** excels at detailed UML with precise notation control. **Graphviz** is best for technical network and dependency graphs. Most Confluence teams should start with Mermaid and add Graphviz for network diagrams if needed. What you'll learn 1. The strengths and weaknesses of each tool 2. Which diagram types each one supports 3. How easy each is to learn and use 4. A practical recommendation for Confluence teams Text-based diagramming — writing a few lines of code that render into a diagram — is how modern teams keep diagrams in sync with their documentation. No more drawing boxes by hand in Visio, exporting screenshots, and pasting them into Confluence where they go stale. With text-based diagrams, you edit the source and the diagram redraws instantly. But there are three major text-based diagramming languages, and they are not interchangeable. Each has different strengths, different syntax, and different ideal use cases. This guide compares Mermaid, PlantUML, and Graphviz so you can choose the right one (or combination) for your Confluence team. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [plantuml](/blog/tags/plantuml.md) * [graphviz](/blog/tags/graphviz.md) * [comparison](/blog/tags/comparison.md) * [diagrams](/blog/tags/diagrams.md) [**Read more**](/blog/mermaid-vs-plantuml-vs-graphviz-confluence.md) --- ## [Confluence Permissions: The Ultimate Guide (2026)](/blog/confluence-permissions-ultimate-guide-2026.md) July 30, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Confluence permissions control who can view, edit, and administer content. You manage permissions at three levels: **site admin** (global), **space admin** (space-level), and **page restrictions** (page-level). Understanding the inheritance hierarchy is key — lower-level settings always override higher-level ones. **Tags:** * [confluence](/blog/tags/confluence.md) * [confluence-admin](/blog/tags/confluence-admin.md) * [permissions](/blog/tags/permissions.md) * [security](/blog/tags/security.md) * [atlassian](/blog/tags/atlassian.md) [**Read more**](/blog/confluence-permissions-ultimate-guide-2026.md) --- ## [How to Export Jira Issues to Excel for Stakeholder Reporting](/blog/export-jira-issues-to-excel-csv-reporting.md) July 29, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer Export Jira issues to Excel or CSV for stakeholder reporting, custom analysis, and cross-project visibility. Use JQL queries to filter exactly the data you need. What you'll learn 1. How to use Jira's built-in export to CSV and Excel 2. How to customize which fields are included in exports 3. How to write JQL queries for targeted, filtered exports 4. How to schedule automated exports for regular reporting 5. How to build Excel reports from Jira export data Jira's built-in reports are useful, but stakeholders often want data in Excel. Whether it is a weekly status report, a velocity trend analysis, or a custom dashboard, Excel gives you full control over how Jira data is presented. This guide covers how to export Jira issues to Excel and CSV, from simple one-click exports to scheduled automated reports. **Tags:** * [jira](/blog/tags/jira.md) * [export](/blog/tags/export.md) * [excel](/blog/tags/excel.md) * [csv](/blog/tags/csv.md) * [reporting](/blog/tags/reporting.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/export-jira-issues-to-excel-csv-reporting.md) --- ## [How to Display JSON, XML, YAML & Code in Confluence (With Syntax Highlighting)](/blog/display-json-xml-code-in-confluence.md) July 23, 2026 · 10 min read [NGPilot](https://ngpilot.com) Who should read this * **Developer teams** documenting APIs, configs, and schemas in Confluence * **Tech writers** who need formatted code samples alongside prose * **Anyone** pasting JSON, XML, YAML, or SQL into Confluence and getting an unreadable wall of text What you'll learn 1. Why Confluence's built-in code block struggles with JSON, XML, and config files 2. How to embed syntax-highlighted code in 85+ languages using a Monaco-powered editor 3. Theme configuration, diff views, and screenshot-ready window chrome 4. When to use a code block vs. a visual JSON structure diagram The scenario every engineering team hits: you're documenting an API in Confluence, and the page needs to show a JSON response, an XML config, a YAML deployment manifest, and a SQL query — all on the same page. You paste each one into Confluence's built-in code block macro, publish, and the result is a wall of monochrome text. No syntax colors. No line numbers that work. JSON braces, XML tags, and YAML indentation all blur together. The reader has to copy-paste your snippet into VS Code just to understand it. The root problem is that Confluence's native code block uses a basic highlighter that wasn't built for the structured data formats modern teams actually work with. JSON, XML, YAML, and SQL each have specific visual conventions — matched braces, nested tags, indentation scopes — that a generic highlighter doesn't handle well. [**Modern Code Blocks for Confluence**](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence) solves this by bringing the Monaco Editor — the same engine that powers VS Code — into Confluence. It accurately highlights 85+ languages including JSON, XML, YAML, SQL, GraphQL, Terraform, Dockerfile, and every mainstream programming language. This guide walks through embedding formatted code and data formats in your Confluence pages. **Tags:** * [confluence](/blog/tags/confluence.md) * [json](/blog/tags/json.md) * [xml](/blog/tags/xml.md) * [yaml](/blog/tags/yaml.md) * [code-blocks](/blog/tags/code-blocks.md) * [syntax-highlighting](/blog/tags/syntax-highlighting.md) * [how-to](/blog/tags/how-to.md) * [api-documentation](/blog/tags/api-documentation.md) [**Read more**](/blog/display-json-xml-code-in-confluence.md) --- # Paste Mermaid Diagrams into Confluence — Now on Mermaid 12 September 28, 2026 · 9 min read [NGPilot](https://ngpilot.com) Quick Answer Confluence's editor is WYSIWYG and has no Mermaid renderer, so pasting a Markdown file that contains ` ```mermaid ` fences imports them as plain code blocks — the diagrams arrive dead. Paste into a Markdown macro instead: [**Enhanced Markdown for Confluence**](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence/) renders Mermaid 12 inline, so a whole README pastes in and the diagrams come alive. The v12 upgrade is what makes this newly worthwhile — **UML use case diagrams** now survive the paste, which is the diagram type requirements docs kept losing. What you'll learn 1. Why Mermaid dies on the way into Confluence, and where the fix lives 2. The paste workflow: repo Markdown in, rendered diagrams out 3. What Mermaid 12 changes — use case diagrams, refreshed layout, richer ZenUML 4. What happens to diagrams you already published The diagrams live in the repository. They were written in Mermaid, they are reviewed in pull requests next to the code they describe, and they are correct as of the last commit. The documentation, however, lives in Confluence — because that is where the rest of the team reads it. So somebody copies a Markdown file across, pastes it into a Confluence page, and the flowcharts, sequence diagrams and ER models arrive as grey boxes of unrendered code. Everyone has hit this. It is one of the most common Confluence complaints, and the usual workarounds are worse than the problem: export every diagram to PNG and re-upload them (now they rot), keep the diagrams in an external tool and paste links (readers need a second account, and the links break), or build a browser extension to force rendering on paste. There is a better answer, and Mermaid 12 makes it better still. ## Why Mermaid dies on the way into Confluence[​](#why-mermaid-dies-on-the-way-into-confluence "Direct link to Why Mermaid dies on the way into Confluence") Two separate problems, often confused: **Confluence cannot render Mermaid at all.** There is no built-in Mermaid support in the editor — no `/mermaid` macro, no diagram fence handling. Anything that looks like a diagram arrives as a code block. This is a product limitation, not a configuration mistake, and it is why [Mermaid rendering in Confluence needs an app](/blog/does-confluence-support-mermaid.md) rather than a setting. **The import path actively flattens your content.** When Markdown containing fenced diagrams is pasted or imported, the fence is treated as a code block and the page stores it as text. The information is not lost, but it is no longer a diagram — and nothing on the page will ever turn it back into one. This is why "just paste the Markdown" does not work, and why teams end up screenshotting their diagrams. ## The fix: paste into a Markdown macro[​](#the-fix-paste-into-a-markdown-macro "Direct link to The fix: paste into a Markdown macro") [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence/) is a Markdown editor that lives inside the page. Paste your file into it and the Quikdown engine renders everything as you type — headings, GFM tables, syntax-highlighted code, KaTeX and LaTeX math, and Mermaid diagrams. The workflow is three steps: 1. **Insert the macro.** Type `/enhanced markdown` in the Confluence editor and pick the app. You get a split view: Markdown source on the left, live preview on the right. 2. **Paste the whole file.** Not just the diagram — the entire document. Tables, code fences, math and diagrams all render in the preview, so the page keeps one consistent look instead of a mix of pasted screenshots and live text. 3. **Check the preview, then save.** Diagrams render as centered inline SVG and update live as you keep typing. On save, the Markdown is stored as standard Confluence storage format, so it participates in search, exports, page history and permissions like any other page content. Two properties matter for teams beyond the first paste. The Markdown stays **re-editable source on the page**, so updating a diagram later means changing a line — not re-importing the file. And because the rendering libraries are bundled locally rather than pulled from a CDN, the macro stays inside your Atlassian boundary, which matters when "Runs on Atlassian" is a procurement checkbox. ## What's new in Mermaid 12 for pasted docs[​](#whats-new-in-mermaid-12-for-pasted-docs "Direct link to What's new in Mermaid 12 for pasted docs") Enhanced Markdown now runs **Mermaid 12**, and for the paste workflow the headline is not cosmetic. **UML use case diagrams (`usecase-beta`).** This is the diagram type that requirements documents need and Markdown could not previously express. Actors, `systemBoundary` blocks, `include`/`extend` relationships and notes all render — so a requirements doc pasted from the repo arrives with its use case diagram intact instead of as an image or a footnote. **A refreshed default look.** Mermaid 12 changes the default layout engine and colour palettes, so flowcharts, state diagrams and class diagrams come out looking better with no code change. **Richer ZenUML.** ZenUML fences now support conditionals (`if/else`), loops (`while`), parallel blocks (`par`) and `try/catch` — useful when the sequence diagram you want is more than a straight list of messages. **Centered, live SVG.** Diagrams render centered inline and update as you edit, so a diagram that is too wide is obvious while you are writing rather than after you have pasted the whole file. The full Mermaid 12 picture, including the syntax for every new type, is in [Mermaid 12 in Confluence & Jira](/blog/mermaid-12-confluence-jira.md). ## Copy-paste: a requirements doc with a v12 use case diagram[​](#copy-paste-a-requirements-doc-with-a-v12-use-case-diagram "Direct link to Copy-paste: a requirements doc with a v12 use case diagram") This is the block to paste into the Markdown source. It is the use case diagram that could not be expressed in Markdown before v12: ```` ## Checkout use cases ```mermaid usecase-beta direction LR actor Customer actor Admin systemBoundary Store("Online Store") UC1("Browse Products") UC2("Checkout") end Customer --> UC1 Customer --> UC2 Admin --> UC2 UC2 ..> : include UC1 Admin --|> Customer note for UC1 "Available 24/7" ``` ```` The preview shows actors connected to use cases inside the system boundary, with the include relationship and the note in place. The surrounding Markdown — the `## Checkout use cases` heading, any tables, any code samples — renders in the same pane, so the requirement, its diagram and its examples arrive as one document. ## What happens to diagrams you already published[​](#what-happens-to-diagrams-you-already-published "Direct link to What happens to diagrams you already published") Nothing breaks. This matters enough to be precise: * **Existing Mermaid source keeps working unchanged.** You do not need to rewrite a single diagram. * **Flowchart, state and class diagrams may lay out slightly differently**, because Mermaid 12 uses a new default layout engine and refreshed styling. A diagram can end up looking better with no code change — but if you had fine-tuned a layout by nudging shapes, the new engine may not reproduce it exactly. * **Nothing is a stored image**, so there is no migration to run. The source is the document; re-render and you get the new look. If a diagram does come out differently, pin the old appearance by overriding the theme in the fence, or re-check the ones with hand-tuned geometry first — those are the only pages worth reviewing after the upgrade. ## When a dedicated diagram app is the better choice[​](#when-a-dedicated-diagram-app-is-the-better-choice "Direct link to When a dedicated diagram app is the better choice") Pasting Markdown is the right default for standard diagram types because the diagram arrives with the document that explains it. Reach for a dedicated Mermaid macro instead when you want: * **One-click templates** for every diagram type, so nobody starts from a blank fence * **Themes, custom colours and fonts** to match your brand * **An AI agent that works on the page** — draft a diagram from a sentence, revise it in place, or convert code blocks already on the page into rendered diagrams * **A diagram-only workflow** when the page has no Markdown to preserve Our [draw.io vs Mermaid in Confluence comparison](/blog/mermaid-vs-drawio-confluence.md) covers the text-native versus visual-editor trade-off in full, and [Confluence diagram tools compared](/blog/confluence-diagram-tools-comparison.md) maps Mermaid, Excalidraw and Graphviz to the job each does well. ## Frequently asked questions[​](#frequently-asked-questions "Direct link to Frequently asked questions") ### Why do Mermaid diagrams not render when I paste Markdown into Confluence?[​](#why-do-mermaid-diagrams-not-render-when-i-paste-markdown-into-confluence "Direct link to Why do Mermaid diagrams not render when I paste Markdown into Confluence?") Because Confluence's editor is WYSIWYG and has no Mermaid renderer, so a `mermaid` fence is imported as a plain code block and stays dead text. Paste into a Markdown macro that renders Mermaid instead — Enhanced Markdown for Confluence runs Mermaid 12, so flowcharts, sequence, class, state, ER, Gantt, pie, journey and the new UML use case diagrams all render in the live preview. ### What does Mermaid 12 add for pasted documentation?[​](#what-does-mermaid-12-add-for-pasted-documentation "Direct link to What does Mermaid 12 add for pasted documentation?") UML use case diagrams through the `usecase-beta` keyword — actors, `systemBoundary` blocks, `include`/`extend` relationships and notes — which is exactly the type requirements documents kept losing in the paste. Mermaid 12 also refreshes the default layout and colour palettes for flowchart, state and class diagrams, and ZenUML fences gain conditionals, loops, parallel blocks and `try/catch`. ### Will my existing diagrams break after the Mermaid 12 upgrade?[​](#will-my-existing-diagrams-break-after-the-mermaid-12-upgrade "Direct link to Will my existing diagrams break after the Mermaid 12 upgrade?") No. Existing Mermaid source keeps working unchanged. Flowchart, state and class diagrams may lay out slightly differently because Mermaid 12 uses a new default layout engine and refreshed styling, so a diagram can look better with no code change. Nothing needs rewriting, and because nothing is stored as an image there is no migration to run. ### Should I paste a whole Markdown file or convert it once?[​](#should-i-paste-a-whole-markdown-file-or-convert-it-once "Direct link to Should I paste a whole Markdown file or convert it once?") Paste it into the macro. That keeps the Markdown as re-editable source on the page, so you update a diagram by editing a line instead of re-importing the file. A one-time conversion makes more sense only when non-technical editors will maintain the page afterwards, since they get the WYSIWYG view instead of the source. ### Is a dedicated diagram app better than pasting Mermaid in Markdown?[​](#is-a-dedicated-diagram-app-better-than-pasting-mermaid-in-markdown "Direct link to Is a dedicated diagram app better than pasting Mermaid in Markdown?") For standard types, pasting is faster and brings the math and code blocks in the same document. A dedicated Mermaid macro wins when you want one-click templates per diagram type, themes and custom colours, or an AI agent that drafts and revises diagrams in place on the page. *** *Render every Mermaid 12 diagram type inside a Markdown document with [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence/) — free for up to 10 users.* Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [mermaid](/blog/tags/mermaid.md) * [mermaid-12](/blog/tags/mermaid-12.md) * [usecase-diagram](/blog/tags/usecase-diagram.md) * [how-to](/blog/tags/how-to.md) * [developer-tools](/blog/tags/developer-tools.md) --- # How to Plan Jira Sprints That Actually Work (Step-by-Step Guide) July 29, 2026 · 7 min read [NGPilot](https://ngpilot.com) Quick Answer Sprint planning in Jira requires grooming your backlog, calculating team capacity, and running a structured planning meeting. This guide covers the complete workflow from backlog refinement to daily sprint tracking. What you'll learn 1. How to groom and rank your Jira backlog so planning meetings are fast 2. A formula for calculating sprint capacity that accounts for real-world interruptions 3. The step-by-step sprint planning meeting format that keeps teams aligned 4. How to use burndown charts and board filters to track progress daily Sprint planning is where most Agile teams either build momentum or lose it. A poorly run planning meeting produces a sprint full of half-finished stories, scope creep, and a team that stops trusting the process. The problem is not Jira itself — it is how teams use Jira during planning. Without a structured workflow, the backlog becomes a dumping ground, story points become guesswork, and the sprint goal vanishes by Wednesday. This guide walks through a complete sprint planning workflow in Jira, from backlog grooming to daily tracking, so your team ships predictably every two weeks. ## Why Sprint Planning Fails in Most Teams[​](#why-sprint-planning-fails-in-most-teams "Direct link to Why Sprint Planning Fails in Most Teams") Before fixing the workflow, it helps to understand why planning breaks down: **The backlog is a graveyard.** Stories sit in the backlog for months without refinement. Acceptance criteria are vague. Story points are either missing or assigned once and never revisited. When planning day arrives, the team is guessing at what "done" looks like. **Capacity is treated as a constant.** Teams plan as if every developer works 8 focused hours every day. In reality, there are meetings, code reviews, production incidents, and PTO. Ignoring these leads to overcommitment. **The sprint goal is an afterthought.** If the sprint goal is just "complete all stories," it is not a goal — it is a wish. Without a unifying objective, the team optimizes for individual tickets instead of collective impact. **There is no mid-sprint checkpoint.** Planning happens once and then the team disappears into work. By the time problems surface, the sprint is already off track. ## Step-by-Step: How to Plan Jira Sprints That Work[​](#step-by-step-how-to-plan-jira-sprints-that-work "Direct link to Step-by-Step: How to Plan Jira Sprints That Work") ### 1. Set Up Your Jira Board for Sprint Planning[​](#1-set-up-your-jira-board-for-sprint-planning "Direct link to 1. Set Up Your Jira Board for Sprint Planning") Before you plan, make sure your board reflects reality. A cluttered board hides priorities and slows down the planning meeting. **Configure your columns** to match your workflow states. A typical setup: | Column | Status | WIP Limit | | ------------- | ----------- | --------- | | Backlog | To Do | None | | Ready for Dev | Ready | 5 | | In Progress | In Progress | 3 | | In Review | In Review | 3 | | Done | Done | None | **Add swimlanes** by assignee or epic so you can see who is overloaded and which epics are getting attention. **Create quick filters** for: * `storyPoints is EMPTY` — find unestimated stories * `created >= -7d` — see recently added items * `assignee != EMPTY AND status != Done` — active work per person These filters make grooming faster and give you visibility during the sprint. ### 2. Groom and Prioritize Your Backlog[​](#2-groom-and-prioritize-your-backlog "Direct link to 2. Groom and Prioritize Your Backlog") Grooming is not a one-time event. It should happen 1-2 times per week, ideally on a set day (Tuesday and Thursday work well for most teams). **For each story, verify:** * Clear acceptance criteria (the "Definition of Done" for this specific story) * Story points assigned (use planning poker or team consensus) * Dependencies identified and linked * Sprint-ready label applied if it is refined enough **Ranking formula** — prioritize stories by: 1. **Business value** (high / medium / low) 2. **Effort** (story points) 3. **Dependencies** (blockers get ranked higher) A quick way to rank: divide story points by business value. Lower ratio = higher priority. This surfaces high-value, low-effort stories first. ### 3. Calculate Sprint Capacity[​](#3-calculate-sprint-capacity "Direct link to 3. Calculate Sprint Capacity") Capacity is the maximum amount of work your team can realistically complete in the sprint. Calculate it before the planning meeting. **Formula:** ``` Sprint Capacity = (Team Members × Sprint Days × Focus Factor) - PTO - Known Interruptions ``` **Example for a 2-week sprint:** | Factor | Value | | ------------------- | ------------------------------------------------------- | | Team members | 5 | | Working days | 10 | | Focus factor | 70% (accounts for meetings, reviews, context switching) | | PTO | 2 days (1 developer on vacation) | | Known interruptions | 3 days (on-call rotation, tech debt sprint) | ``` Capacity = (5 × 10 × 0.70) - 2 - 3 = 30 story points ``` If your team's average velocity is 40 points, plan for 30 this sprint. It is better to under-promise and deliver than to overcommit and miss. ### 4. Run the Sprint Planning Meeting[​](#4-run-the-sprint-planning-meeting "Direct link to 4. Run the Sprint Planning Meeting") The planning meeting should take 2 hours max for a 2-week sprint. Here is the format: **Part 1: What can we do? (30 minutes)** * Product owner presents the top-priority stories * Team asks clarifying questions * Any story without clear acceptance criteria gets sent back for grooming **Part 2: How will we do it? (60 minutes)** * Team breaks stories into subtasks * Developers identify technical dependencies * Sprint goal is drafted (one sentence: "By the end of this sprint, we will...") **Part 3: Commit and confirm (30 minutes)** * Team reviews total story points against capacity * Sprint goal is finalized * Team commits to the scope — no mid-sprint additions without negotiation **Pro tip:** Use Jira's sprint planning view to drag stories from the backlog into the sprint. The built-in velocity chart shows your last 5 sprints for reference. ### 5. Track and Adapt During the Sprint[​](#5-track-and-adapt-during-the-sprint "Direct link to 5. Track and Adapt During the Sprint") Planning is only half the workflow. Daily tracking keeps the sprint on course. **Daily standup focus:** * What moved since yesterday? * What is blocked? * Are we on track for the sprint goal? **Burndown chart:** * A flat line means stories are stuck (not started or blocked) * A steep drop at the end means work was not truly done * An ideal burndown is a steady downward slope **Mid-sprint check (day 5):** * Review the burndown with the team * If velocity is lagging, consider moving low-priority stories out of the sprint * Never add stories without removing an equal amount of work ## When to Use This Workflow[​](#when-to-use-this-workflow "Direct link to When to Use This Workflow") | Scenario | Use This Approach | | ------------------------------------ | --------------------------------------------------- | | New Scrum team (less than 3 sprints) | Follow every step exactly | | Mature team with stable velocity | Skip detailed capacity calc, focus on sprint goal | | Kanban team (no sprints) | Adapt grooming and WIP limits, skip sprint planning | | Distributed team across time zones | Run async grooming in Jira, sync planning via video | ## FAQ[​](#faq "Direct link to FAQ") ### How long should a Jira sprint be?[​](#how-long-should-a-jira-sprint-be "Direct link to How long should a Jira sprint be?") Most teams use 2-week sprints. One-week sprints work for mature teams with tight feedback loops. Three or four-week sprints are rare and risk losing focus. Start with 2 weeks and adjust based on your team's velocity consistency. ### What is the difference between a sprint goal and a sprint commitment?[​](#what-is-the-difference-between-a-sprint-goal-and-a-sprint-commitment "Direct link to What is the difference between a sprint goal and a sprint commitment?") The sprint goal is the business objective the team wants to achieve — why this sprint matters. The commitment is the set of stories the team pulls in. A good sprint goal stays constant even if individual stories shift during the sprint. ### How many story points should a team plan per sprint?[​](#how-many-story-points-should-a-team-plan-per-sprint "Direct link to How many story points should a team plan per sprint?") There is no universal number. Base it on your team's historical velocity — the average story points completed over the last 3-5 sprints. If your team averages 40 points, plan around 40 for the next sprint, adjusting for known absences. ### What happens when the team cannot finish all sprint items?[​](#what-happens-when-the-team-cannot-finish-all-sprint-items "Direct link to What happens when the team cannot finish all sprint items?") Move incomplete stories back to the backlog. Do not carry them over automatically — re-evaluate priority. If stories consistently spill, the team is overcommitting. Reduce sprint scope by 10-15% until velocity stabilizes. ### Should I use story points or time estimates in Jira?[​](#should-i-use-story-points-or-time-estimates-in-jira "Direct link to Should I use story points or time estimates in Jira?") Story points are preferred for sprint planning because they measure effort relative to complexity, not raw hours. Time estimates (hours) work better for support or break-fix teams where work is measured in elapsed time. ## Related guides[​](#related-guides "Direct link to Related guides") * [How to Export Jira Issues to Excel for Stakeholder Reporting](/blog/export-jira-issues-to-excel-csv-reporting.md) * [Jira JQL Cheat Sheet: 20 Queries Every Team Needs](/blog/jira-jql-cheat-sheet-common-queries.md) * [How to Set Up Jira Dashboards for Sprint Tracking](/blog/jira-dashboard-sprint-tracking-setup.md) * [Creating Jira Issues from Templates with Bulk Create](/blog/create-jira-issues-from-templates.md) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [sprint-planning](/blog/tags/sprint-planning.md) * [agile](/blog/tags/agile.md) * [how-to](/blog/tags/how-to.md) * [project-management](/blog/tags/project-management.md) --- # RAG with Confluence: Build an AI Knowledge Base from Your Docs July 30, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer RAG (Retrieval-Augmented Generation) lets you query your Confluence knowledge base using natural language. It retrieves relevant pages and uses AI to generate accurate answers from your documentation. What you'll learn 1. How to prepare Confluence content for RAG indexing 2. How to choose the right RAG platform for your needs 3. How to index and configure your Confluence knowledge base 4. How to test, optimize, and deploy your RAG system Your team has hundreds of Confluence pages, but finding the right information still takes too long. Search returns too many results, keywords miss synonyms, and context gets lost across pages. RAG (Retrieval-Augmented Generation) changes this by combining search with AI generation. Instead of returning pages, it returns answers — synthesized from your Confluence content. This guide covers how to build a RAG system with Confluence. ## Why RAG Matters for Confluence[​](#why-rag-matters-for-confluence "Direct link to Why RAG Matters for Confluence") **Natural language queries.** Instead of guessing keywords, ask questions in plain English: "How do we handle production incidents?" or "What is our deployment process?" **Synthesized answers.** RAG combines information from multiple pages into a single, coherent answer. No more clicking through 5 pages to piece together a response. **Always current.** RAG indexes your live Confluence content. When you update a page, the knowledge base updates automatically. **Reduced support burden.** Teams can self-serve answers instead of asking the same questions repeatedly. This frees up senior team members for higher-value work. ## How to Build RAG with Confluence: Step-by-Step[​](#how-to-build-rag-with-confluence-step-by-step "Direct link to How to Build RAG with Confluence: Step-by-Step") ### 1. Prepare Your Confluence Content for RAG[​](#1-prepare-your-confluence-content-for-rag "Direct link to 1. Prepare Your Confluence Content for RAG") RAG quality depends on content quality. Before indexing, clean up your Confluence pages: **Content cleanup checklist:** * Remove outdated or inaccurate pages * Fix broken links and references * Add clear headings and structure * Include metadata (tags, labels, categories) * Remove duplicate content * Ensure consistent formatting **Content structure for RAG:** ``` # Clear, descriptive title ## Introduction paragraph (what this page covers) ## Main content sections with H2/H3 headers ## FAQ section with Q&A pairs ## Related pages section ``` **Best content types for RAG:** * How-to guides and tutorials * FAQ pages * Policy and procedure documents * Troubleshooting guides * Architecture and design documents * Onboarding materials **Content to exclude:** * Meeting notes (too informal, time-sensitive) * Decision logs (context-dependent) * Personal pages (not shared knowledge) * Draft pages (incomplete information) ### 2. Choose a RAG Platform or Tool[​](#2-choose-a-rag-platform-or-tool "Direct link to 2. Choose a RAG Platform or Tool") **Option A: Atlassian Intelligence (native)** * **Pros:** Built-in, no setup, respects permissions * **Cons:** Limited customization, requires Premium/Enterprise plan * **Best for:** Teams already on Atlassian Premium who want quick setup **Option B: Marketplace apps** | App | Features | Pricing | | ------ | ---------------------------- | -------------- | | Guru | AI search, verified answers | $15/user/month | | Tettra | AI Q\&A, content suggestions | $99/month | | Slab | AI search, knowledge base | $66/month | | Tettra | AI Q\&A, content suggestions | $99/month | **Option C: Custom RAG solution** * **Pros:** Full control, custom models, unlimited customization * **Cons:** Requires development effort, maintenance, hosting * **Best for:** Teams with specific requirements or sensitive data **Custom RAG stack:** * **Data source:** Confluence REST API * **Embedding:** OpenAI, Cohere, or open-source models * **Vector store:** Pinecone, Weaviate, or ChromaDB * **Orchestration:** LangChain, LlamaIndex * **Interface:** Web app, Slack bot, or CLI ### 3. Index Your Confluence Content[​](#3-index-your-confluence-content "Direct link to 3. Index Your Confluence Content") **Using Atlassian Intelligence:** 1. Go to **Site Administration > Atlassian Intelligence** 2. Enable **Knowledge base** feature 3. Select which spaces to index 4. Configure permissions (respect Confluence access) 5. Wait for initial indexing (varies by content size) **Using a custom RAG solution:** ``` # Example: Index Confluence pages with LangChain from langchain.document_loaders import ConfluenceLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain.embeddings import OpenAIEmbeddings from langchain.vectorstores import Pinecone # Load pages from Confluence loader = ConfluenceLoader( url="https://your-domain.atlassian.net", username="email@company.com", api_key="your-api-key" ) pages = loader.load(space_key="ENG") # Split into chunks splitter = RecursiveCharacterTextSplitter( chunk_size=1000, chunk_overlap=200 ) chunks = splitter.split_documents(pages) # Create embeddings and store embeddings = OpenAIEmbeddings() vectorstore = Pinecone.from_documents( chunks, embeddings, index_name="confluence-kb" ) ``` **Chunking strategy:** * **Chunk size:** 500-1000 tokens (balance between context and precision) * **Overlap:** 100-200 tokens (maintain context across chunks) * **Split by:** Headers first, then paragraphs, then sentences * **Metadata:** Include page title, space, URL, last updated ### 4. Test and Optimize Retrieval Quality[​](#4-test-and-optimize-retrieval-quality "Direct link to 4. Test and Optimize Retrieval Quality") **Testing checklist:** * Run 20-30 sample queries covering different topics * Evaluate answer accuracy (correct, partially correct, wrong) * Check if answers cite the right source pages * Test with edge cases (ambiguous queries, out-of-scope questions) * Verify permission filtering works correctly **Common issues and fixes:** | Issue | Cause | Fix | | ------------------ | ------------------- | ---------------------------------- | | Wrong answers | Poor chunking | Adjust chunk size and overlap | | Missing answers | Content not indexed | Check space/label filters | | Outdated answers | Stale content | Re-index more frequently | | Irrelevant results | Bad embeddings | Try different embedding model | | Slow responses | Large index | Optimize vector store, add filters | **Optimization parameters:** * **Top K:** Number of chunks to retrieve (start with 5, adjust based on quality) * **Similarity threshold:** Minimum match score (0.7-0.8 typical) * **Reranking:** Use a reranker model to improve relevance * **Hybrid search:** Combine keyword and semantic search ### 5. Deploy and Monitor Your AI Knowledge Base[​](#5-deploy-and-monitor-your-ai-knowledge-base "Direct link to 5. Deploy and Monitor Your AI Knowledge Base") **Deployment options:** * **Slack bot:** Team asks questions in Slack, bot responds with answers * **Web interface:** Standalone search page for the knowledge base * **Confluence integration:** AI assistant within Confluence itself * **API:** Custom applications that query the knowledge base **Monitoring and improvement:** * Track query logs to identify common questions * Monitor failed queries (no answer or wrong answer) * Collect user feedback on answer quality * Update content based on gaps identified * Re-index regularly as content changes **Metrics to track:** * Query volume (daily/weekly) * Answer accuracy (user ratings) * Failed query rate * Content freshness (average age of indexed pages) * User adoption (active users, queries per user) ## FAQ[​](#faq "Direct link to FAQ") ### What is RAG and why does it matter for Confluence?[​](#what-is-rag-and-why-does-it-matter-for-confluence "Direct link to What is RAG and why does it matter for Confluence?") RAG (Retrieval-Augmented Generation) combines search with AI generation. It retrieves relevant Confluence content, then uses an LLM to generate accurate answers. This makes your Confluence knowledge base searchable via natural language queries. ### Can I build RAG with Confluence without coding?[​](#can-i-build-rag-with-confluence-without-coding "Direct link to Can I build RAG with Confluence without coding?") Yes. Tools like Atlassian Intelligence, Guru, and Tettra provide no-code RAG solutions for Confluence. For custom requirements, you can build with LangChain, LlamaIndex, or similar frameworks. ### How accurate is RAG with Confluence content?[​](#how-accurate-is-rag-with-confluence-content "Direct link to How accurate is RAG with Confluence content?") Accuracy depends on content quality, chunking strategy, and embedding model. Well-structured Confluence pages typically yield 85-95% accuracy. Poorly organized content may need cleanup before indexing. ### What Confluence content works best for RAG?[​](#what-confluence-content-works-best-for-rag "Direct link to What Confluence content works best for RAG?") FAQ pages, how-to guides, policy documents, and troubleshooting guides work best. Meeting notes, decision logs, and informal pages may produce less reliable results. ### How do I handle sensitive Confluence content in RAG?[​](#how-do-i-handle-sensitive-confluence-content-in-rag "Direct link to How do I handle sensitive Confluence content in RAG?") Use RAG tools that respect Confluence permissions. Most enterprise solutions filter content based on the querying user's access rights, ensuring sensitive pages are only returned to authorized users. ## Related guides[​](#related-guides "Direct link to Related guides") * [How to Use ChatGPT in Confluence for Better Documentation](/blog/how-to-use-chatgpt-in-confluence.md) * [AI Meeting Notes in Confluence: Capture and Share Automatically](/blog/ai-meeting-notes-confluence.md) * [How to Organize Your Confluence Space for Easy Navigation](/blog/faq-confluence-dark-mode-apps.md) * [Confluence Page Templates: How to Create and Use Them](/blog/advanced-code-blocks-confluence.md) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [rag](/blog/tags/rag.md) * [ai](/blog/tags/ai.md) * [knowledge-base](/blog/tags/knowledge-base.md) * [how-to](/blog/tags/how-to.md) --- # How to Set Up Announcement Banners in Jira (Rich Text, Scheduling & Targeting) July 23, 2026 · 6 min read [NGPilot](https://ngpilot.com) Who should read this * **Jira admins** who need to broadcast maintenance windows, outages, or policy changes * **IT/ops teams** that want dismissible vs. persistent banner control * **Anyone** frustrated by Jira's plain-text native banner limitations What you'll learn 1. How to create a Jira announcement banner with rich text and emojis 2. Choosing dismissible vs. persistent banners (and when each fits) 3. Managing a library of announcements for quick reuse 4. How this compares to Jira's built-in banner and to Confluence banners The scenario every Jira admin hits: there's a maintenance window Saturday night, a security policy change, or an ongoing incident — and you need every person who opens Jira to see it immediately. Jira has a built-in announcement banner, but it's plain-text only, lives in a buried admin setting, and gives you one banner at a time with no library, no scheduling, and no way to let users dismiss it. [**Modern Announcement Banner for Jira**](https://marketplace.atlassian.com/apps/194301976/modern-announcement-banner-for-jira) fixes this: rich-text banners with emojis and custom colors, a dismissible option, a saved library of announcements you can switch between with one click, and instant enable/disable without deleting. This guide walks through setting it up. ## Why Jira's native announcement banner falls short[​](#why-jiras-native-announcement-banner-falls-short "Direct link to Why Jira's native announcement banner falls short") Jira ships with a built-in announcement banner (under *General Configuration → Announcement Banner*), but teams outgrow it fast for four reasons: 1. **Plain text only.** No formatting, no emojis, no links, no colors. A critical outage banner looks identical to a casual note. 2. **One banner at a time.** You can't keep a library of announcements. To switch from "maintenance Saturday" to "incident resolved," you copy the current text somewhere, paste the new text, and hope you saved the old one. 3. **Not dismissible.** Every user sees the banner until an admin removes it — even after they've read it a dozen times. There's no "I've seen this, let me close it" option. 4. **All-or-nothing visibility.** The native banner shows to everyone or no one. No per-project targeting. A dedicated banner app addresses all four: rich text, a saved library, dismissible option, and visibility control. ## Step-by-step: set up a Jira announcement banner[​](#step-by-step-set-up-a-jira-announcement-banner "Direct link to Step-by-step: set up a Jira announcement banner") ### 1. Install Modern Announcement Banner for Jira[​](#1-install-modern-announcement-banner-for-jira "Direct link to 1. Install Modern Announcement Banner for Jira") Install [Modern Announcement Banner for Jira](https://marketplace.atlassian.com/apps/194301976/modern-announcement-banner-for-jira) from the Atlassian Marketplace. It requires Jira administrator permissions to install and is free for up to 10 users. ### 2. Open the banner manager[​](#2-open-the-banner-manager "Direct link to 2. Open the banner manager") Log in to Jira as an administrator. Click the **Apps** (⚙️) More Actions icon in the top navigation and select **Modern Announcement Banner for Jira** from the left sidebar. The banner manager opens, showing your announcement library (empty on first use). ### 3. Create a new announcement[​](#3-create-a-new-announcement "Direct link to 3. Create a new announcement") Click **New announcement**. In the editor: * **Write your message** using rich text — bold, italics, links, and emojis. A maintenance banner might be: "⚙️ **Scheduled maintenance** Saturday 2:00–4:00 AM UTC. Jira may be briefly unavailable." * **Enabled** — check this to display the banner immediately on creation. * **Dismissible** — check this to let users close the banner once they've read it (good for one-time notices). Leave unchecked to keep it persistent (good for ongoing incidents). * **Visibility** — choose **Public** (all users) or **Private** (follows Jira's privacy settings). ### 4. Enable and publish[​](#4-enable-and-publish "Direct link to 4. Enable and publish") Click **Create**. If you checked Enabled, the banner appears immediately at the top of every Jira page. The design is clean and matches Jira's interface — non-intrusive, but unmissable. ### 5. Manage and switch announcements[​](#5-manage-and-switch-announcements "Direct link to 5. Manage and switch announcements") This is where the library pays off. Every announcement you create is saved in your history. Common scenarios: * **Maintenance window approaching** → enable the maintenance banner * **Window over** → disable it (one click, not deleted) or switch to the "maintenance complete" banner * **New incident** → switch to the incident banner * **Policy change** → enable the persistent (non-dismissible) policy banner You can switch between saved announcements with one click, and disable any banner instantly without losing it. This turns banner management from a copy-paste chore into a one-click operation. ## Dismissible vs. persistent banners: when to use each[​](#dismissible-vs-persistent-banners-when-to-use-each "Direct link to Dismissible vs. persistent banners: when to use each") The dismissible setting is the most important choice per banner: | Banner type | When to use | Behavior | | --------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------- | | **Dismissible** | One-time notices (scheduled maintenance, release notes, survey links) | Users close it after reading; won't see it again in their session | | **Persistent** | Ongoing situations (active incidents, policy changes, security alerts) | Stays visible to every user until an admin disables it | The rule of thumb: if the announcement is something users need to *act on repeatedly* (an ongoing outage), make it persistent. If it's something they need to see *once* (maintenance is this Saturday), make it dismissible so it stops cluttering their screen after they've acknowledged it. ## How this compares to Confluence announcement banners[​](#how-this-compares-to-confluence-announcement-banners "Direct link to How this compares to Confluence announcement banners") This app is for **Jira**. Confluence has its own native announcement banner (under *General Configuration → Announcement Banner* in Confluence, not Jira) which is similarly plain-text-only. If you need rich banners in Confluence too, that's a separate need — but the most common request is for Jira, where the whole engineering team sees the banner on every issue and board. ## FAQ[​](#faq "Direct link to FAQ") ### Does Jira have a built-in announcement banner?[​](#does-jira-have-a-built-in-announcement-banner "Direct link to Does Jira have a built-in announcement banner?") Yes — Jira has a native announcement banner under General Configuration. But it's plain-text only, gives you one banner at a time with no library, and isn't dismissible. For rich-text banners, a saved announcement library, and dismissible/persistent control, use a Marketplace app like Modern Announcement Banner for Jira. ### Can I make a Jira announcement banner dismissible?[​](#can-i-make-a-jira-announcement-banner-dismissible "Direct link to Can I make a Jira announcement banner dismissible?") Jira's native banner cannot be dismissed by users — it stays until an admin removes it. Modern Announcement Banner for Jira adds a dismissible option per banner, so users can close one-time notices after reading them while persistent banners (for ongoing incidents) remain. ### How do I schedule a Jira announcement banner?[​](#how-do-i-schedule-a-jira-announcement-banner "Direct link to How do I schedule a Jira announcement banner?") Jira's native banner has no scheduling — you must enable and disable it manually at the right times. Modern Announcement Banner for Jira lets you save a library of announcements and switch between them with one click, so you can prepare a maintenance banner in advance and enable it instantly when the window starts. ### Can I target a Jira banner to specific projects?[​](#can-i-target-a-jira-banner-to-specific-projects "Direct link to Can I target a Jira banner to specific projects?") The native banner is all-or-nothing (everyone or no one). Modern Announcement Banner for Jira offers visibility control (public or private, following Jira's privacy settings) for more targeted display. ### Is Modern Announcement Banner for Jira free?[​](#is-modern-announcement-banner-for-jira-free "Direct link to Is Modern Announcement Banner for Jira free?") Yes — Modern Announcement Banner for Jira is free for up to 10 users. Beyond 10 users, standard Atlassian Marketplace licensing applies. ## Related guides[​](#related-guides "Direct link to Related guides") Try Modern Announcement Banner for Jira Rich-text announcement banners with scheduling and targeting — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/194301976/modern-announcement-banner-for-jira?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=modern-announcement-banner-for-jira) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [announcement-banner](/blog/tags/announcement-banner.md) * [notification](/blog/tags/notification.md) * [how-to](/blog/tags/how-to.md) * [admin](/blog/tags/admin.md) --- ## 5[​](#5 "Direct link to 5") * [5-whys1](/blog/tags/5-whys.md) *** --- ## [Root Cause Analysis in Confluence with Mermaid Fishbone + 5 Whys](/blog/mermaid-fishbone-root-cause-analysis-confluence.md) September 24, 2026 · 7 min read [NGPilot](https://ngpilot.com) A root cause analysis is only as good as the disagreement it survives. When the 'root cause' box on your postmortem template contains one sentence, the meeting spends an hour relitigating that sentence. A fishbone diagram and a 5 Whys chain move the argument onto a diagram: everyone sees which categories were considered, which branch was chosen, and exactly how the 'why' answers arrive at a root cause. Confluence is where RCA already happens — in the Root Cause Analysis template, in postmortems, in retros. The missing piece is a diagram that holds the reasoning. This guide shows you two copy-paste Mermaid diagrams: an `ishikawa` fishbone that maps every candidate cause category, and a `flowchart` 5-Whys drilldown that lands on one concrete fix. **Tags:** * [root-cause-analysis](/blog/tags/root-cause-analysis.md) * [fishbone](/blog/tags/fishbone.md) * [ishikawa](/blog/tags/ishikawa.md) * [5-whys](/blog/tags/5-whys.md) * [mermaid](/blog/tags/mermaid.md) * [confluence](/blog/tags/confluence.md) * [postmortem](/blog/tags/postmortem.md) * [how-to](/blog/tags/how-to.md) * [incident-management](/blog/tags/incident-management.md) [**Read more**](/blog/mermaid-fishbone-root-cause-analysis-confluence.md) --- ## [Expand Macro for Confluence: Collapsible Sections Compared (Native vs Styled)](/blog/confluence-expand-macro.md) August 21, 2026 · 5 min read [NGPilot](https://ngpilot.com) Long pages die from scroll fatigue. Onboarding checklists, troubleshooting trees, API reference details, legal disclaimers — content that only some readers need some of the time is the canonical use case for collapsible sections. Confluence ships a native **expand macro** for exactly this, and for many pages it's enough. This guide covers how the native expand works, where teams typically outgrow it, and what a styled accordion macro adds — so you can pick per page, not per vendor. **Tags:** * [confluence](/blog/tags/confluence.md) * [macros](/blog/tags/macros.md) * [expand](/blog/tags/expand.md) * [accordion](/blog/tags/accordion.md) * [formatting](/blog/tags/formatting.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/confluence-expand-macro.md) --- ## [Confluence Wiki Markup: How to View, Edit & Convert It](/blog/confluence-wiki-markup.md) September 23, 2026 · 6 min read [NGPilot](https://ngpilot.com) Every Confluence page has two faces: the one you see in the editor, and the one the database sees. The database face is the **storage format** — an XHTML document with macros as tags — and before it, Confluence stored pages as **wiki markup**: `h1. headings`, `*bold text*`, `{code}` blocks. People still search for wiki markup because half the internet's Confluence advice, every migration script, and a lot of content written before \~2017 speaks that language. And in 2026 the topic got urgent: Atlassian is retiring the legacy editor (full deprecation April 2026), and the new cloud editor **dropped the Markup macro** entirely. Here's how to view, edit, and convert what's actually stored — with or without admin rights. **Tags:** * [confluence](/blog/tags/confluence.md) * [wiki-markup](/blog/tags/wiki-markup.md) * [storage-format](/blog/tags/storage-format.md) * [how-to](/blog/tags/how-to.md) * [admin](/blog/tags/admin.md) * [migration](/blog/tags/migration.md) [**Read more**](/blog/confluence-wiki-markup.md) --- ## [How to Export Jira Audit Logs for Compliance and Security Reviews](/blog/export-jira-audit-logs-compliance.md) July 29, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer Jira audit logs track who changed what, when, and where. Export logs to CSV or via REST API for compliance audits, security investigations, and change management documentation. What you'll learn 1. How to access and navigate the Jira audit log 2. How to filter audit entries by user, date, and action type 3. How to export audit data to CSV or via REST API 4. How to set up automated logging and retention policies 5. How to analyze audit data for compliance and security Audit logs are the paper trail of your Jira instance. They record who did what, when, and where — essential information for compliance audits, security investigations, and change management. Without proper audit logging, you cannot prove who deleted that issue, when permissions changed, or whether someone accessed restricted data. This guide covers how to access, export, and analyze Jira audit logs. **Tags:** * [jira](/blog/tags/jira.md) * [audit-logs](/blog/tags/audit-logs.md) * [compliance](/blog/tags/compliance.md) * [security](/blog/tags/security.md) * [how-to](/blog/tags/how-to.md) * [administration](/blog/tags/administration.md) [**Read more**](/blog/export-jira-audit-logs-compliance.md) --- ## [What Is Atlassian Government Cloud (AGC)? NGPILOT Apps Available (2026)](/blog/what-is-atlassian-government-cloud.md) July 30, 2026 · 3 min read [NGPilot](https://ngpilot.com) Quick Answer Atlassian Government Cloud (AGC) is a FedRAMP-authorized deployment of Confluence and Jira designed for U.S. government agencies and contractors. It meets FedRAMP Moderate baseline requirements for handling sensitive government data. NGPILOT has apps available on AGC for teams needing compliant diagramming and content tools. **Tags:** * [atlassian](/blog/tags/atlassian.md) * [government-cloud](/blog/tags/government-cloud.md) * [agc](/blog/tags/agc.md) * [fedramp](/blog/tags/fedramp.md) * [compliance](/blog/tags/compliance.md) * [confluence](/blog/tags/confluence.md) * [jira](/blog/tags/jira.md) [**Read more**](/blog/what-is-atlassian-government-cloud.md) --- ## [Excalidraw AI Agent for Confluence: Whiteboards You Can Talk To](/blog/excalidraw-ai-agent-confluence.md) October 10, 2026 · 7 min read [NGPilot](https://ngpilot.com) Confluence holds your team's diagrams in two worlds, and the two don't talk to each other. Text-defined diagrams — Mermaid and friends — are what AI speaks natively. They're source code, so a chat agent can read them, write them, and revise them. We shipped exactly that last week: [an AI agent for Mermaid in Confluence](/blog/mermaid-ai-agent-confluence.md). Whiteboards are the other world. Freeform shapes, hand-drawn lines, arrows you drag where they need to go — the format that's actually intuitive to put in front of people. Every team has one: the architecture board on the team page, the incident flow everyone references, the onboarding map. And AI couldn't touch any of it. Ask a chat agent for a change to a whiteboard and you'd get a text *description* of a change, and someone still had to open the canvas and do it by hand. That gap is why whiteboards go stale. Editing shapes one drag at a time is slow enough that nobody does it, and AI — the thing that was supposed to make maintenance cheap — had no way in. The AI agent in [Excalidraw Plus Whiteboards & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence) closes the gap: the whiteboard stays what it always was — visual, intuitive, for people — but now you can operate it in plain language, from Confluence chat. **Tags:** * [confluence](/blog/tags/confluence.md) * [excalidraw](/blog/tags/excalidraw.md) * [whiteboard](/blog/tags/whiteboard.md) * [diagrams](/blog/tags/diagrams.md) * [ai](/blog/tags/ai.md) * [agent](/blog/tags/agent.md) [**Read more**](/blog/excalidraw-ai-agent-confluence.md) --- ## [Kanban Board Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-kanban-board-workflow-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The sprint board on the wall shows 40 items in "In Progress" and the rulebook says "we limit WIP" and nobody agrees on what the limit is. The board is honest; the *documentation* is aspirational. A Kanban diagram in the wiki is the board as a spec — columns, limits, and the rework paths drawn so the workflow is a claim the team can argue with. **Quick answer:** document the team's board in Confluence as a Mermaid `kanban`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Columns as headings, work items as indented cards; the workflow *rules* (who may move what, when, including rework) as a `stateDiagram` on the same page. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [kanban](/blog/tags/kanban.md) * [workflow](/blog/tags/workflow.md) * [state-diagram](/blog/tags/state-diagram.md) * [agile](/blog/tags/agile.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-kanban-board-workflow-confluence.md) --- ## [Excalidraw AI Agent for Confluence: Whiteboards You Can Talk To](/blog/excalidraw-ai-agent-confluence.md) October 10, 2026 · 7 min read [NGPilot](https://ngpilot.com) Confluence holds your team's diagrams in two worlds, and the two don't talk to each other. Text-defined diagrams — Mermaid and friends — are what AI speaks natively. They're source code, so a chat agent can read them, write them, and revise them. We shipped exactly that last week: [an AI agent for Mermaid in Confluence](/blog/mermaid-ai-agent-confluence.md). Whiteboards are the other world. Freeform shapes, hand-drawn lines, arrows you drag where they need to go — the format that's actually intuitive to put in front of people. Every team has one: the architecture board on the team page, the incident flow everyone references, the onboarding map. And AI couldn't touch any of it. Ask a chat agent for a change to a whiteboard and you'd get a text *description* of a change, and someone still had to open the canvas and do it by hand. That gap is why whiteboards go stale. Editing shapes one drag at a time is slow enough that nobody does it, and AI — the thing that was supposed to make maintenance cheap — had no way in. The AI agent in [Excalidraw Plus Whiteboards & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence) closes the gap: the whiteboard stays what it always was — visual, intuitive, for people — but now you can operate it in plain language, from Confluence chat. **Tags:** * [confluence](/blog/tags/confluence.md) * [excalidraw](/blog/tags/excalidraw.md) * [whiteboard](/blog/tags/whiteboard.md) * [diagrams](/blog/tags/diagrams.md) * [ai](/blog/tags/ai.md) * [agent](/blog/tags/agent.md) [**Read more**](/blog/excalidraw-ai-agent-confluence.md) --- ## [How to Build an AI Chatbot for Confluence Knowledge Base](/blog/build-ai-chatbot-confluence-knowledge-base.md) July 30, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer Build an AI chatbot that answers questions from your Confluence knowledge base using no-code tools or custom development. Connect Confluence content, train the chatbot, and deploy to Slack or Teams. What you'll learn 1. How to choose the right chatbot platform for your needs 2. how to prepare and export Confluence content for chatbot ingestion 3. How to connect the chatbot to your Confluence data 4. How to train, test, and deploy your Confluence chatbot Teams waste hours searching Confluence for answers that already exist. A chatbot can bridge this gap by providing instant answers from your knowledge base, right where the team works. This guide covers how to build an AI chatbot for Confluence, from no-code solutions to custom development. **Tags:** * [confluence](/blog/tags/confluence.md) * [ai](/blog/tags/ai.md) * [chatbot](/blog/tags/chatbot.md) * [knowledge-base](/blog/tags/knowledge-base.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/build-ai-chatbot-confluence-knowledge-base.md) --- ## [How to Create Math and Technical Animations in Confluence Using Manim](/blog/how-to-create-math-animations-confluence.md) May 2, 2026 · 23 min read [NGPilot](https://ngpilot.com) Mathematical concepts are inherently dynamic. A limit converges, a derivative emerges from shrinking secant lines, a matrix transformation rotates a vector through space. Static screenshots and LaTeX formulas capture the result but miss the process -- and for many students and colleagues, the process is where understanding lives. Animations bridge that gap. They show how equations transform, how geometric constructions unfold step by step, and how abstract algebra connects to visual intuition. Until recently, embedding math animations in documentation required a multi-tool workflow: write Python scripts with Manim, render MP4 files locally, upload them as attachments or embed them via external hosting, and hope nobody asked you to update them. Manim for Confluence eliminates that entire pipeline. You write animation code directly inside a Confluence macro, and the animation plays inline on the published page -- no file exports, no external hosting, no broken links when the video expires. **Tags:** * [confluence](/blog/tags/confluence.md) * [manim](/blog/tags/manim.md) * [animation](/blog/tags/animation.md) * [math](/blog/tags/math.md) * [how-to](/blog/tags/how-to.md) * [education](/blog/tags/education.md) [**Read more**](/blog/how-to-create-math-animations-confluence.md) --- ## [How to Set Up Announcement Banners in Jira (Rich Text, Scheduling & Targeting)](/blog/set-up-announcement-banners-jira.md) July 23, 2026 · 6 min read [NGPilot](https://ngpilot.com) Who should read this * **Jira admins** who need to broadcast maintenance windows, outages, or policy changes * **IT/ops teams** that want dismissible vs. persistent banner control * **Anyone** frustrated by Jira's plain-text native banner limitations What you'll learn 1. How to create a Jira announcement banner with rich text and emojis 2. Choosing dismissible vs. persistent banners (and when each fits) 3. Managing a library of announcements for quick reuse 4. How this compares to Jira's built-in banner and to Confluence banners The scenario every Jira admin hits: there's a maintenance window Saturday night, a security policy change, or an ongoing incident — and you need every person who opens Jira to see it immediately. Jira has a built-in announcement banner, but it's plain-text only, lives in a buried admin setting, and gives you one banner at a time with no library, no scheduling, and no way to let users dismiss it. [**Modern Announcement Banner for Jira**](https://marketplace.atlassian.com/apps/194301976/modern-announcement-banner-for-jira) fixes this: rich-text banners with emojis and custom colors, a dismissible option, a saved library of announcements you can switch between with one click, and instant enable/disable without deleting. This guide walks through setting it up. **Tags:** * [jira](/blog/tags/jira.md) * [announcement-banner](/blog/tags/announcement-banner.md) * [notification](/blog/tags/notification.md) * [how-to](/blog/tags/how-to.md) * [admin](/blog/tags/admin.md) [**Read more**](/blog/set-up-announcement-banners-jira.md) --- ## [Confluence FAQ Macro & Q\&A Template: Add FAQ Sections to Pages](/blog/confluence-questions-answers-template.md) May 10, 2026 · 3 min read [NGPilot](https://ngpilot.com) Confluence is great for documentation, but it has no built-in **FAQ macro** or Q\&A tool. If you need FAQ pages, knowledge bases, or community-style Q\&A in Confluence, NGPILOT offers two purpose-built apps. **Tags:** * [confluence](/blog/tags/confluence.md) * [faq](/blog/tags/faq.md) * [questions](/blog/tags/questions.md) * [answers](/blog/tags/answers.md) * [template](/blog/tags/template.md) * [knowledge-base](/blog/tags/knowledge-base.md) * [macro](/blog/tags/macro.md) [**Read more**](/blog/confluence-questions-answers-template.md) --- ## [API Sequence Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-api-sequence-diagram-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The integration doc says "the client calls the API, the API validates and responds" — four words, zero contracts, and the onboarding engineer asks "with what headers, in what order, and what if auth fails?" The code has the truth; the wiki has a paragraph. An API that can't be read as a transcript is an API nobody can safely operate. **Quick answer:** document API flows in Confluence as Mermaid — `sequenceDiagram` for request/response order, `packet-beta` for wire-format frames, ZenUML for branch-heavy async flows — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Each diagram type answers a different reader: what order, what's on the wire, what branches. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [sequence-diagram](/blog/tags/sequence-diagram.md) * [packet](/blog/tags/packet.md) * [zenuml](/blog/tags/zenuml.md) * [api](/blog/tags/api.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-api-sequence-diagram-confluence.md) --- ## [How to Display JSON, XML, YAML & Code in Confluence (With Syntax Highlighting)](/blog/display-json-xml-code-in-confluence.md) July 23, 2026 · 10 min read [NGPilot](https://ngpilot.com) Who should read this * **Developer teams** documenting APIs, configs, and schemas in Confluence * **Tech writers** who need formatted code samples alongside prose * **Anyone** pasting JSON, XML, YAML, or SQL into Confluence and getting an unreadable wall of text What you'll learn 1. Why Confluence's built-in code block struggles with JSON, XML, and config files 2. How to embed syntax-highlighted code in 85+ languages using a Monaco-powered editor 3. Theme configuration, diff views, and screenshot-ready window chrome 4. When to use a code block vs. a visual JSON structure diagram The scenario every engineering team hits: you're documenting an API in Confluence, and the page needs to show a JSON response, an XML config, a YAML deployment manifest, and a SQL query — all on the same page. You paste each one into Confluence's built-in code block macro, publish, and the result is a wall of monochrome text. No syntax colors. No line numbers that work. JSON braces, XML tags, and YAML indentation all blur together. The reader has to copy-paste your snippet into VS Code just to understand it. The root problem is that Confluence's native code block uses a basic highlighter that wasn't built for the structured data formats modern teams actually work with. JSON, XML, YAML, and SQL each have specific visual conventions — matched braces, nested tags, indentation scopes — that a generic highlighter doesn't handle well. [**Modern Code Blocks for Confluence**](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence) solves this by bringing the Monaco Editor — the same engine that powers VS Code — into Confluence. It accurately highlights 85+ languages including JSON, XML, YAML, SQL, GraphQL, Terraform, Dockerfile, and every mainstream programming language. This guide walks through embedding formatted code and data formats in your Confluence pages. **Tags:** * [confluence](/blog/tags/confluence.md) * [json](/blog/tags/json.md) * [xml](/blog/tags/xml.md) * [yaml](/blog/tags/yaml.md) * [code-blocks](/blog/tags/code-blocks.md) * [syntax-highlighting](/blog/tags/syntax-highlighting.md) * [how-to](/blog/tags/how-to.md) * [api-documentation](/blog/tags/api-documentation.md) [**Read more**](/blog/display-json-xml-code-in-confluence.md) --- ## [Map States & Approval Workflows in Confluence with Mermaid](/blog/mermaid-state-diagram-workflow-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The issue workflow lives in a wiki page that says "the approval chain is: team lead, then manager, then finance". The config says otherwise, the Jira post-function disagrees, and the incident report asks "who actually approved this?" — with three different answers on screen. A prose paragraph cannot hold a workflow; a diagram can, if it *is* the workflow. **Quick answer:** document state machines and approval chains in Confluence as Mermaid `stateDiagram-v2`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Every legal state, every transition, every human decision on a labeled arrow — in editable text that stays true. This post gives you three copy-paste examples: an issue lifecycle, a spending approval chain, and a retry loop with a timeout. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [state-diagram](/blog/tags/state-diagram.md) * [workflow](/blog/tags/workflow.md) * [approval](/blog/tags/approval.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-state-diagram-workflow-confluence.md) --- ## [System Architecture Diagrams in Confluence with Mermaid C4](/blog/mermaid-c4-system-architecture-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The onboarding doc says "check the architecture diagram" and the architecture diagram shows a monolith from 2023 that the team decommissioned in the spring. Nobody is lying — the draw\.io file lives on one person's laptop, and the wiki holds a screenshot nobody owns. An architecture that only exists as a static export rots silently, because the thing you would edit is invisible to review. **Quick answer:** document system architecture in Confluence as Mermaid text — `C4Context` for the system in context, `architecture-beta` for the deployment, `block-beta` for the topology you want laid out precisely — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Every level stays an editable code block, so the wiki's architecture changes in the same review that changes the system. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [architecture](/blog/tags/architecture.md) * [c4-model](/blog/tags/c-4-model.md) * [block-diagram](/blog/tags/block-diagram.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-c4-system-architecture-confluence.md) --- ## [How to Create Architecture Diagrams in Confluence (3 Methods with Examples)](/blog/how-to-create-architecture-diagrams-confluence.md) May 2, 2026 · 14 min read [NGPilot](https://ngpilot.com) Architecture diagrams are the backbone of technical documentation. They show how services communicate, where data flows, and which infrastructure components underpin your system. When a new engineer joins your team, the first thing they look for is an architecture diagram. When something breaks in production, the incident response starts at the same diagram. Yet many teams store their architecture diagrams in external tools -- [draw.io](/blog/faq-excalidraw-vs-drawio-confluence.md), Lucidchart, or even desktop applications -- detached from the documentation where they matter most. Confluence is where your runbooks live, where architecture decision records are written, and where post-mortem discussions happen. Keeping your architecture diagrams inside Confluence eliminates context-switching and ensures diagrams evolve alongside the written documentation they illustrate. This guide walks through three ways to create architecture diagrams directly in Confluence, using NGPILOT apps designed for different workflows. Every Mermaid example is copy-paste ready, so you can insert it into a Confluence page and see the result immediately. **Tags:** * [confluence](/blog/tags/confluence.md) * [architecture-diagram](/blog/tags/architecture-diagram.md) * [mermaid](/blog/tags/mermaid.md) * [excalidraw](/blog/tags/excalidraw.md) * [how-to](/blog/tags/how-to.md) * [diagrams](/blog/tags/diagrams.md) [**Read more**](/blog/how-to-create-architecture-diagrams-confluence.md) --- ## [Forge vs Connect: What Atlassian Admins Need to Know in 2026](/blog/forge-vs-connect-atlassian-admins-2026.md) August 2, 2026 · 10 min read [NGPilot](https://ngpilot.com) Quick Answer Forge and Connect are the two frameworks Atlassian Marketplace apps can be built on. **Forge** runs on Atlassian's own infrastructure; **Connect** runs on vendor-hosted servers. Starting January 1, 2026, Atlassian applies a penalty to Connect apps in Marketplace rankings and requires Forge for new Cloud Fortified status. For admins evaluating apps in 2026, Forge is the safer, more future-proof choice where a capable option exists. What you'll learn 1. The real architectural difference between Forge and Connect 2. What the 2026 Connect penalty changes for app discovery and trust 3. How to tell which framework an app uses before you install it 4. A practical decision framework for evaluating apps in 2026 If you administer Jira or Confluence Cloud, every app you install from the Marketplace runs on one of two frameworks: **Forge** or **Connect**. For years the difference was mostly an implementation detail that admins could ignore. In 2026 that changed. The Connect penalty, the Cloud Fortified requirement, and Atlassian's clear strategic direction mean the framework an app uses now affects its security posture, its discoverability, and how long it will keep working. This guide explains what changed, why it matters, and how to make better app decisions because of it. **Tags:** * [atlassian](/blog/tags/atlassian.md) * [forge](/blog/tags/forge.md) * [connect](/blog/tags/connect.md) * [marketplace](/blog/tags/marketplace.md) * [explained](/blog/tags/explained.md) * [admin](/blog/tags/admin.md) [**Read more**](/blog/forge-vs-connect-atlassian-admins-2026.md) --- ## [Jira Attachment Management Apps Compared: Bulk Downloader vs Attachment Reviewer](/blog/jira-attachment-management-comparison.md) May 2, 2026 · 11 min read [NGPilot](https://ngpilot.com) Jira issues accumulate attachments fast -- screenshots from QA, log files from production incidents, design mockups from product, contracts from legal. Before long, a single project can hold thousands of files across hundreds of issues. Two questions come up repeatedly: "How do I download all of these at once?" and "How do I make sure the right files -- and only the right files -- are attached?" NGPILOT builds two apps that address these questions from different angles. **Simple Bulk Attachment Downloader for Jira** handles bulk exports -- downloading many attachments in one organized ZIP. **Attachment Reviewer for Jira** handles inbound control -- enforcing file type and size policies on every upload. This post compares both in detail so you can decide which one your team needs (or whether you need both). **Tags:** * [comparison](/blog/tags/comparison.md) * [jira](/blog/tags/jira.md) * [attachments](/blog/tags/attachments.md) * [bulk](/blog/tags/bulk.md) * [export](/blog/tags/export.md) [**Read more**](/blog/jira-attachment-management-comparison.md) --- ## [How to See Who Changed What in Jira — Field-Level Issue History](/blog/jira-issue-history.md) September 23, 2026 · 5 min read [NGPilot](https://ngpilot.com) Every Jira issue keeps a diary. Status flips, priority bumps, reassignments, edited specs — Jira writes all of it down. The problem is reading it back: the built-in history turns a description edit into one unhelpful line, and "who changed this?" across forty issues becomes forty clicks or a REST script. This guide covers three ways to actually read Jira issue history, from the free built-in tab to field-level diffs and a cross-issue CSV report. **Tags:** * [jira](/blog/tags/jira.md) * [issue-history](/blog/tags/issue-history.md) * [audit](/blog/tags/audit.md) * [changelog](/blog/tags/changelog.md) * [how-to](/blog/tags/how-to.md) * [compliance](/blog/tags/compliance.md) [**Read more**](/blog/jira-issue-history.md) --- ## [How to Export Jira Audit Logs for Compliance and Security Reviews](/blog/export-jira-audit-logs-compliance.md) July 29, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer Jira audit logs track who changed what, when, and where. Export logs to CSV or via REST API for compliance audits, security investigations, and change management documentation. What you'll learn 1. How to access and navigate the Jira audit log 2. How to filter audit entries by user, date, and action type 3. How to export audit data to CSV or via REST API 4. How to set up automated logging and retention policies 5. How to analyze audit data for compliance and security Audit logs are the paper trail of your Jira instance. They record who did what, when, and where — essential information for compliance audits, security investigations, and change management. Without proper audit logging, you cannot prove who deleted that issue, when permissions changed, or whether someone accessed restricted data. This guide covers how to access, export, and analyze Jira audit logs. **Tags:** * [jira](/blog/tags/jira.md) * [audit-logs](/blog/tags/audit-logs.md) * [compliance](/blog/tags/compliance.md) * [security](/blog/tags/security.md) * [how-to](/blog/tags/how-to.md) * [administration](/blog/tags/administration.md) [**Read more**](/blog/export-jira-audit-logs-compliance.md) --- ## [AI for Jira Workflows: Automate Triage, Assignment, and Prioritization](/blog/ai-for-jira-workflows-automate-triage-assignment.md) July 30, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer AI in Jira automates issue triage, assignment, and prioritization by analyzing content and historical patterns. Configure Atlassian Intelligence to suggest categories, assignees, and priorities automatically. What you'll learn 1. How to enable and configure AI features in Jira 2. How to set up AI-powered issue triage and categorization 3. How to configure intelligent assignment based on team capacity 4. How to enable AI prioritization suggestions Every new Jira issue needs decisions: What type is it? Who should work on it? How urgent is it? These decisions happen manually today, taking time and introducing inconsistency. AI can automate these decisions by analyzing issue content, historical patterns, and team context. This guide covers how to use AI for Jira workflow automation, from triage to assignment. **Tags:** * [jira](/blog/tags/jira.md) * [ai](/blog/tags/ai.md) * [automation](/blog/tags/automation.md) * [workflow](/blog/tags/workflow.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/ai-for-jira-workflows-automate-triage-assignment.md) --- ## [Jira Backlog Grooming: The Complete Guide to Refining Stories](/blog/jira-backlog-grooming-complete-guide.md) July 29, 2026 · 7 min read [NGPilot](https://ngpilot.com) Quick Answer Backlog grooming is the process of refining, estimating, and prioritizing Jira stories so they are sprint-ready. A well-groomed backlog makes sprint planning fast and predictable. What you'll learn 1. How to set up a grooming cadence that keeps your backlog healthy 2. A template for writing acceptance criteria that eliminate ambiguity 3. The planning poker workflow for accurate story point estimation 4. How to rank stories so the highest-value work always comes first A messy backlog is the silent killer of Agile teams. Stories pile up without refinement, acceptance criteria are vague, and sprint planning becomes a guessing game. By the time the team realizes the backlog is broken, velocity has dropped and trust in the process has eroded. Backlog grooming — also called refinement — is the antidote. It is the ongoing process of reviewing, splitting, estimating, and prioritizing stories so the backlog is always sprint-ready. This guide covers a complete grooming workflow in Jira, from writing acceptance criteria to ranking by business value. **Tags:** * [jira](/blog/tags/jira.md) * [backlog-grooming](/blog/tags/backlog-grooming.md) * [agile](/blog/tags/agile.md) * [how-to](/blog/tags/how-to.md) * [scrum](/blog/tags/scrum.md) [**Read more**](/blog/jira-backlog-grooming-complete-guide.md) --- ## [Best Confluence Import/Export Apps Compared — 2026 Guide](/blog/confluence-import-export-comparison.md) April 18, 2026 · 7 min read [NGPilot](https://ngpilot.com) Teams move content in and out of Confluence every day — migrating between instances, backing up documentation, importing from other tools, exporting for offline review. Confluence has basic PDF and HTML export built in, but it's limited. No bulk operations, no multi-format support, no structured import workflow. Over a dozen marketplace apps try to fill this gap, but most solve one narrow problem: PDF export, Word import, or Markdown conversion. We built **Modern Importer & Exporter for Confluence** to handle both directions — import and export — across multiple formats. In this post we compare it against every alternative on the Atlassian Marketplace. **Tags:** * [import](/blog/tags/import.md) * [export](/blog/tags/export.md) * [confluence](/blog/tags/confluence.md) * [migration](/blog/tags/migration.md) * [backup](/blog/tags/backup.md) * [markdown](/blog/tags/markdown.md) * [pdf](/blog/tags/pdf.md) * [word](/blog/tags/word.md) * [content-transfer](/blog/tags/content-transfer.md) [**Read more**](/blog/confluence-import-export-comparison.md) --- ## [QR Code for Confluence — Which QR App Should Your Team Use?](/blog/confluence-qr-code-comparison.md) April 18, 2026 · 5 min read [NGPilot](https://ngpilot.com) Teams print Confluence page links on posters, equipment labels, desk signs, and handouts. A QR code on a physical object that links to the relevant Confluence page saves everyone from typing long URLs. It's a small thing that removes friction in offices, warehouses, and events. But Confluence has no built-in QR code generation. A handful of marketplace apps fill this niche — it's a small market with roughly 130 total installs across all apps. We built **QRCode for Confluence** to let teams embed QR codes directly into pages with a simple `/qrcode` slash command. In this post we compare it against the alternatives. **Tags:** * [qr-code](/blog/tags/qr-code.md) * [qrcode](/blog/tags/qrcode.md) * [confluence](/blog/tags/confluence.md) * [barcode](/blog/tags/barcode.md) * [url-shortener](/blog/tags/url-shortener.md) * [printable-qr](/blog/tags/printable-qr.md) [**Read more**](/blog/confluence-qr-code-comparison.md) --- ## [Best Confluence Apps & Plugins in 2026 — Developer Tools Compared](/blog/best-confluence-apps-developers.md) May 10, 2026 · 7 min read [NGPilot](https://ngpilot.com) Developer teams use Confluence differently than marketing or HR. You document APIs, share architecture diagrams, write runbooks, and collaborate on code reviews. The default Confluence editor works, but it wasn't built for technical documentation. This guide covers the best Confluence apps for developers in 2026, organized by use case. We built several of these apps at NGPILOT, so we'll be transparent about where our apps fit and where competitors offer better solutions. **Tags:** * [comparison](/blog/tags/comparison.md) * [confluence](/blog/tags/confluence.md) * [developer-tools](/blog/tags/developer-tools.md) * [best-apps](/blog/tags/best-apps.md) * [code-blocks](/blog/tags/code-blocks.md) * [diagrams](/blog/tags/diagrams.md) * [markdown](/blog/tags/markdown.md) [**Read more**](/blog/best-confluence-apps-developers.md) --- ## [Jira issue templates: best practices for consistent ticket creation](/blog/jira-issue-templates-best-practices.md) April 24, 2026 · 3 min read [NGPilot](https://ngpilot.com) Inconsistent Jira tickets waste time during grooming, sprint planning, and reporting. Issue templates solve this by standardizing the fields, descriptions, and checklists that appear on every new ticket. This guide covers how to set up and get the most from [Modern Issue Templates for Jira](/docs/Modern-Issue-Templates-for-Jira/user-docs.md). **Tags:** * [jira](/blog/tags/jira.md) * [templates](/blog/tags/templates.md) * [best-practices](/blog/tags/best-practices.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/jira-issue-templates-best-practices.md) --- ## [System Architecture Diagrams in Confluence with Mermaid C4](/blog/mermaid-c4-system-architecture-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The onboarding doc says "check the architecture diagram" and the architecture diagram shows a monolith from 2023 that the team decommissioned in the spring. Nobody is lying — the draw\.io file lives on one person's laptop, and the wiki holds a screenshot nobody owns. An architecture that only exists as a static export rots silently, because the thing you would edit is invisible to review. **Quick answer:** document system architecture in Confluence as Mermaid text — `C4Context` for the system in context, `architecture-beta` for the deployment, `block-beta` for the topology you want laid out precisely — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Every level stays an editable code block, so the wiki's architecture changes in the same review that changes the system. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [architecture](/blog/tags/architecture.md) * [c4-model](/blog/tags/c-4-model.md) * [block-diagram](/blog/tags/block-diagram.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-c4-system-architecture-confluence.md) --- ## [How to Add a Block Quote in Confluence (3 Methods Compared)](/blog/block-quote-confluence.md) August 5, 2026 · 5 min read [NGPilot](https://ngpilot.com) A **block quote** sets a passage apart from the surrounding text — usually indented with a left border — to indicate that the words are quoted from another source. Confluence does not have a dedicated "quote block" button, but there are three reliable ways to create one. This guide walks through each and helps you pick the right one. What you'll learn 1. The native method (toolbar Indent) — no app required 2. The Markdown method (`>` syntax) — fastest for keyboard users 3. The panel macro method (Content Formatting) — most styling control 4. How to nest quotes and add attribution **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [formatting](/blog/tags/formatting.md) * [blockquote](/blog/tags/blockquote.md) * [enhanced-markdown](/blog/tags/enhanced-markdown.md) * [content-formatting](/blog/tags/content-formatting.md) [**Read more**](/blog/block-quote-confluence.md) --- ## [How to Make Text Bold or Strikethrough in Confluence (Ctrl+B, Toolbar & Markdown)](/blog/bold-text-confluence.md) August 11, 2026 · 3 min read [NGPilot](https://ngpilot.com) **Bold text** is one of the most common formatting actions in Confluence — for headings, callouts, and emphasis inside paragraphs. There are two ways to do it: the toolbar button / keyboard shortcut in the standard editor, and Markdown syntax inside [Enhanced Markdown for Confluence](/apps/enhanced-markdown-for-confluence.md). This guide covers both, plus the common "why isn't it working" cases. What you'll learn 1. The standard editor method — B button or Ctrl+B / Cmd+B 2. The Markdown method — `**bold**` syntax 3. Bold vs italic vs strikethrough 4. Fixing bold that renders as literal asterisks **Tags:** * [confluence](/blog/tags/confluence.md) * [formatting](/blog/tags/formatting.md) * [markdown](/blog/tags/markdown.md) * [bold](/blog/tags/bold.md) * [enhanced-markdown](/blog/tags/enhanced-markdown.md) * [keyboard-shortcuts](/blog/tags/keyboard-shortcuts.md) [**Read more**](/blog/bold-text-confluence.md) --- ## [Mind Maps & Hierarchy Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-mindmap-hierarchy-diagram-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The kickoff note is 40 lines of indented bullets with three levels of bolded sub-points, and half the room is still asking "so what are we actually deciding today?" The other half is screenshotting a mind map someone whiteboarded in five minutes. The whiteboard died at cleanup; the bullets survived but nobody can navigate them. A mind map is the *readable* version of nested notes — and when it lives in Confluence as Mermaid text, it survives the meeting. **Quick answer:** turn nested notes into a Mermaid `mindmap` in Confluence, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). The indented text you already write becomes the branches; for concrete structures — folder layouts, project trees — use `treeView`; when item size matters and you want area instead of lines, use `treemap`. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [mindmap](/blog/tags/mindmap.md) * [treeview](/blog/tags/treeview.md) * [treemap](/blog/tags/treemap.md) * [brainstorming](/blog/tags/brainstorming.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-mindmap-hierarchy-diagram-confluence.md) --- ## [Visualize Git Branches & Releases Inside Jira with Mermaid GitGraph](/blog/mermaid-gitgraph-jira-branch-history.md) September 24, 2026 · 7 min read [NGPilot](https://ngpilot.com) Your team is mid-debug on a prod incident. A senior engineer asks *"which release shipped this commit, and why is it on the release branch when the PR said main?"* — and nobody can answer without switching between Jira, the git web UI, and a Slack thread. That context — commit history, branches, merge points, release versions — belongs *next to the issue*, not in a tool people have to leave Jira to open. **Quick answer:** paste a Mermaid `gitGraph` into the issue's [Mermaid Plus Diagrams for Jira](https://marketplace.atlassian.com/apps/2658777397/mermaid-plus-diagrams-for-jira/) panel and the branch history renders as a diagram right on the ticket — commits, branches, merges, and release tags, all in one editable text block. This post gives you three copy-paste examples: a trunk-based feature workflow, a hotfix outside the release window, and a branch-rule flowchart to keep behavior consistent. **Tags:** * [jira](/blog/tags/jira.md) * [git](/blog/tags/git.md) * [gitgraph](/blog/tags/gitgraph.md) * [mermaid](/blog/tags/mermaid.md) * [branching](/blog/tags/branching.md) * [release](/blog/tags/release.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-gitgraph-jira-branch-history.md) --- ## [Issue Templates for Jira — Templating.app & Top Apps Compared](/blog/jira-issue-templates-comparison.md) April 18, 2026 · 8 min read [NGPilot](https://ngpilot.com) Every team has recurring issue types — bug reports with specific fields, user stories with acceptance criteria, onboarding checklists with sub-tasks. Creating each one from scratch wastes time and introduces inconsistency. Jira has no built-in issue templates. Over a dozen marketplace apps try to solve this. The market is fragmented but maturing — the leader has roughly 4,900 installs, and several apps now carry Cloud Fortified status. We built **Modern Issue Templates for Jira** to bring template creation, GitHub import, auto-application, and fill-in variables to Jira issues. In this post we compare it against the alternatives. **Tags:** * [issue-templates](/blog/tags/issue-templates.md) * [jira-templates](/blog/tags/jira-templates.md) * [jira-automation](/blog/tags/jira-automation.md) * [project-templates](/blog/tags/project-templates.md) * [bug-template](/blog/tags/bug-template.md) * [user-story-template](/blog/tags/user-story-template.md) [**Read more**](/blog/jira-issue-templates-comparison.md) --- ## [Jira Attachment Management Apps Compared: Bulk Downloader vs Attachment Reviewer](/blog/jira-attachment-management-comparison.md) May 2, 2026 · 11 min read [NGPilot](https://ngpilot.com) Jira issues accumulate attachments fast -- screenshots from QA, log files from production incidents, design mockups from product, contracts from legal. Before long, a single project can hold thousands of files across hundreds of issues. Two questions come up repeatedly: "How do I download all of these at once?" and "How do I make sure the right files -- and only the right files -- are attached?" NGPILOT builds two apps that address these questions from different angles. **Simple Bulk Attachment Downloader for Jira** handles bulk exports -- downloading many attachments in one organized ZIP. **Attachment Reviewer for Jira** handles inbound control -- enforcing file type and size policies on every upload. This post compares both in detail so you can decide which one your team needs (or whether you need both). **Tags:** * [comparison](/blog/tags/comparison.md) * [jira](/blog/tags/jira.md) * [attachments](/blog/tags/attachments.md) * [bulk](/blog/tags/bulk.md) * [export](/blog/tags/export.md) [**Read more**](/blog/jira-attachment-management-comparison.md) --- ## [System Architecture Diagrams in Confluence with Mermaid C4](/blog/mermaid-c4-system-architecture-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The onboarding doc says "check the architecture diagram" and the architecture diagram shows a monolith from 2023 that the team decommissioned in the spring. Nobody is lying — the draw\.io file lives on one person's laptop, and the wiki holds a screenshot nobody owns. An architecture that only exists as a static export rots silently, because the thing you would edit is invisible to review. **Quick answer:** document system architecture in Confluence as Mermaid text — `C4Context` for the system in context, `architecture-beta` for the deployment, `block-beta` for the topology you want laid out precisely — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Every level stays an editable code block, so the wiki's architecture changes in the same review that changes the system. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [architecture](/blog/tags/architecture.md) * [c4-model](/blog/tags/c-4-model.md) * [block-diagram](/blog/tags/block-diagram.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-c4-system-architecture-confluence.md) --- ## [FAQ: Widget Carousel for Confluence — Image Sliders, Banners & Dashboards](/blog/faq-confluence-widget-carousel.md) May 2, 2026 · 15 min read [NGPilot](https://ngpilot.com) Confluence pages are powerful containers for knowledge, documentation, and team collaboration. But when it comes to displaying visual content -- product screenshots, event photos, marketing banners, or process walkthroughs -- the standard page layout falls short. Images stacked vertically create long, scroll-heavy pages that are difficult to scan, and Confluence's built-in gallery macro only offers a static thumbnail grid with no interactive slideshow behavior. **Widget Carousel for Confluence** solves this by adding a fully interactive image carousel macro that you can embed on any Confluence page. You select images from page attachments or upload new ones directly, then display them in a customizable slider with configurable width options. The result is a polished, professional-looking carousel that transforms how visual content is presented in your Confluence workspace. This FAQ covers the most common questions teams have about Widget Carousel for Confluence -- from basic setup and content types to advanced configuration, responsive design, and how it compares to Confluence's native gallery macro. Whether you are building a company dashboard, a project landing page, or a team portal, this guide will help you get the most out of the carousel. **Tags:** * [faq](/blog/tags/faq.md) * [confluence](/blog/tags/confluence.md) * [carousel](/blog/tags/carousel.md) * [widget](/blog/tags/widget.md) * [dashboard](/blog/tags/dashboard.md) [**Read more**](/blog/faq-confluence-widget-carousel.md) --- ## [How to See Who Changed What in Jira — Field-Level Issue History](/blog/jira-issue-history.md) September 23, 2026 · 5 min read [NGPilot](https://ngpilot.com) Every Jira issue keeps a diary. Status flips, priority bumps, reassignments, edited specs — Jira writes all of it down. The problem is reading it back: the built-in history turns a description edit into one unhelpful line, and "who changed this?" across forty issues becomes forty clicks or a REST script. This guide covers three ways to actually read Jira issue history, from the free built-in tab to field-level diffs and a cross-issue CSV report. **Tags:** * [jira](/blog/tags/jira.md) * [issue-history](/blog/tags/issue-history.md) * [audit](/blog/tags/audit.md) * [changelog](/blog/tags/changelog.md) * [how-to](/blog/tags/how-to.md) * [compliance](/blog/tags/compliance.md) [**Read more**](/blog/jira-issue-history.md) --- ## [Graphviz Charts in Confluence: draw.io vs Graphviz vs Mermaid](/blog/graphviz-charts-confluence-comparison.md) July 30, 2026 · 4 min read [NGPilot](https://ngpilot.com) Teams use Confluence to document architecture, processes, and organizational structures. But Confluence doesn't render graphs or charts natively — you need a marketplace app. We built **Graphviz Charts for Confluence** to bring the power of Graphviz and DOT language to Confluence pages. In this post, we compare it against every alternative. **Tags:** * [confluence](/blog/tags/confluence.md) * [confluence-apps](/blog/tags/confluence-apps.md) * [comparison](/blog/tags/comparison.md) * [graphviz](/blog/tags/graphviz.md) * [charts](/blog/tags/charts.md) [**Read more**](/blog/graphviz-charts-confluence-comparison.md) --- ## [How to Build an AI Chatbot for Confluence Knowledge Base](/blog/build-ai-chatbot-confluence-knowledge-base.md) July 30, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer Build an AI chatbot that answers questions from your Confluence knowledge base using no-code tools or custom development. Connect Confluence content, train the chatbot, and deploy to Slack or Teams. What you'll learn 1. How to choose the right chatbot platform for your needs 2. how to prepare and export Confluence content for chatbot ingestion 3. How to connect the chatbot to your Confluence data 4. How to train, test, and deploy your Confluence chatbot Teams waste hours searching Confluence for answers that already exist. A chatbot can bridge this gap by providing instant answers from your knowledge base, right where the team works. This guide covers how to build an AI chatbot for Confluence, from no-code solutions to custom development. **Tags:** * [confluence](/blog/tags/confluence.md) * [ai](/blog/tags/ai.md) * [chatbot](/blog/tags/chatbot.md) * [knowledge-base](/blog/tags/knowledge-base.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/build-ai-chatbot-confluence-knowledge-base.md) --- ## [How to Use ChatGPT in Confluence: AI-Powered Writing for Better Docs](/blog/how-to-use-chatgpt-in-confluence.md) July 30, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer Confluence offers native AI features through Atlassian Intelligence for writing, summarizing, and translating content. Third-party apps integrate ChatGPT directly into the editor for inline AI assistance. What you'll learn 1. How to enable and use Atlassian Intelligence in Confluence 2. How to integrate ChatGPT via Marketplace apps 3. Prompt engineering techniques for better AI-generated content 4. How to use AI for summarization, translation, and content improvement Writing good documentation takes time. Between drafting, editing, formatting, and organizing, creating a single Confluence page can take hours. For teams with dozens of pages to maintain, this time adds up quickly. AI tools like ChatGPT can accelerate every stage of the documentation workflow — from initial drafts to final polish. This guide covers how to use AI in Confluence, from native features to third-party integrations. **Tags:** * [confluence](/blog/tags/confluence.md) * [chatgpt](/blog/tags/chatgpt.md) * [ai](/blog/tags/ai.md) * [how-to](/blog/tags/how-to.md) * [documentation](/blog/tags/documentation.md) [**Read more**](/blog/how-to-use-chatgpt-in-confluence.md) --- ## [Documenting Microservice Architectures in Confluence with Mermaid](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md) May 2, 2026 · 14 min read [NGPilot](https://ngpilot.com) Mermaid is the most popular text-based diagramming language for technical documentation. One line of code generates a flowchart. A few more produce a sequence diagram, ER diagram, or Gantt chart. Teams using Confluence can embed Mermaid diagrams directly on their pages, keeping diagrams alongside the documentation they illustrate. Who should read this * **Platform/backend engineers** documenting a microservice architecture * **Tech leads** keeping architecture docs in sync with code * **Anyone** who wants a copy-paste Mermaid syntax reference for Confluence **Tags:** * [faq](/blog/tags/faq.md) * [mermaid](/blog/tags/mermaid.md) * [confluence](/blog/tags/confluence.md) * [syntax](/blog/tags/syntax.md) * [cheat-sheet](/blog/tags/cheat-sheet.md) * [diagrams](/blog/tags/diagrams.md) [**Read more**](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md) --- ## [How to Add a Checklist to Jira — and Block Transitions Until Done](/blog/jira-checklist.md) September 18, 2026 · 5 min read [NGPilot](https://ngpilot.com) Every team has a definition of done. The problem is that in Jira, "done" is one button press — nothing checks whether the release notes were written, the tests passed, or the customer was notified. A checklist fixes the *remembering*; enforcement fixes the *skipping*. This guide covers three ways to add a checklist to Jira issues, from a two-minute bullet list to required items that physically block the Done transition. **Tags:** * [jira](/blog/tags/jira.md) * [checklist](/blog/tags/checklist.md) * [workflow](/blog/tags/workflow.md) * [how-to](/blog/tags/how-to.md) * [definition-of-done](/blog/tags/definition-of-done.md) * [process](/blog/tags/process.md) [**Read more**](/blog/jira-checklist.md) --- ## [CI/CD Pipeline Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-ci-cd-pipeline-diagram-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) A build fails at 4pm, and the fix's pipeline takes 40 minutes to re-run from the top because someone decided every stage needs to re-validate. That wasted hour is not a code problem — it is a **documentation** problem. Nobody could see the pipeline's shape, so nobody saw the retry loop and the gate that would have caught the failure three stages earlier. **Quick answer:** put the pipeline's shape in Confluence as a Mermaid `flowchart`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Text-based, editable, diffable — a pipeline diagram that changes when your pipeline changes. This post gives you three copy-paste examples: the linear stage view, quality gates with retry loops, and the deploy-to-tag gitGraph that records what actually shipped. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [ci-cd](/blog/tags/ci-cd.md) * [devops](/blog/tags/devops.md) * [flowchart](/blog/tags/flowchart.md) * [gitgraph](/blog/tags/gitgraph.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-ci-cd-pipeline-diagram-confluence.md) --- ## [Document Your Codebase in Confluence with Mermaid Class Diagrams](/blog/mermaid-class-diagram-document-codebase-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) Your team grows by two people. The new hires open the wiki and find the architecture doc: a screenshot of a whiteboard, dated 14 months ago, where `PaymentService` does everything except the thing the diagram says `OrderService` does. Day-1 onboarding just taught two people the wrong architecture. **Quick answer:** keep the architecture in Confluence as a Mermaid `class diagram`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/) and diffs like code. Classes, methods, interfaces, ownership — in editable text that updates when the code does. This post gives you three copy-paste examples: the onboarding service map, interface+implementation modules, and a request-flow sketch. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [class-diagram](/blog/tags/class-diagram.md) * [architecture](/blog/tags/architecture.md) * [docs](/blog/tags/docs.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-class-diagram-document-codebase-confluence.md) --- ## [Markdown Code Blocks in Confluence — 190+ Languages](/blog/markdown-code-block-confluence.md) September 24, 2026 · 4 min read [NGPilot](https://ngpilot.com) Every engineering page in Confluence eventually holds code — a curl from the runbook, the config that fixed the incident, the query the dashboard runs. And every one of those snippets has three natural enemies: the language dropdown in the macro dialog, the paste that loses its indentation, and the reader who cannot copy the thing without dragging across line numbers. Markdown fences solve all three, because they make the code block *text you type* instead of an object you configure. ` ```bash `, paste, ` ``` ` — done, highlighted, copyable. This guide shows the syntax, the theming behavior, and when fences beat the native macro. **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [code-block](/blog/tags/code-block.md) * [syntax-highlighting](/blog/tags/syntax-highlighting.md) * [how-to](/blog/tags/how-to.md) * [developer-tools](/blog/tags/developer-tools.md) [**Read more**](/blog/markdown-code-block-confluence.md) --- ## [Confluence Code Block Themes — Dark Mode, Monaco Editor & 85+ Languages](/blog/code-blocks-confluence-monaco-editor.md) April 18, 2026 · 5 min read [NGPilot](https://ngpilot.com) **Confluence code block themes** let you customize how code appears in your documentation. The built-in code macro offers limited theme support, but third-party apps bring dark mode, syntax highlighting, and VS Code-like editing to Confluence. This guide compares the best **Confluence code block** apps for syntax highlighting, including Modern Code Blocks, Better Code Macro, and Prism Syntax Highlighter. Learn which one fits your team's needs for **Confluence code block themes**, language support, and developer experience. **Tags:** * [code-blocks](/blog/tags/code-blocks.md) * [syntax-highlighting](/blog/tags/syntax-highlighting.md) * [confluence](/blog/tags/confluence.md) * [monaco-editor](/blog/tags/monaco-editor.md) * [developer-tools](/blog/tags/developer-tools.md) * [code-block-themes](/blog/tags/code-block-themes.md) * [dark-mode](/blog/tags/dark-mode.md) [**Read more**](/blog/code-blocks-confluence-monaco-editor.md) --- ## [How to Display JSON, XML, YAML & Code in Confluence (With Syntax Highlighting)](/blog/display-json-xml-code-in-confluence.md) July 23, 2026 · 10 min read [NGPilot](https://ngpilot.com) Who should read this * **Developer teams** documenting APIs, configs, and schemas in Confluence * **Tech writers** who need formatted code samples alongside prose * **Anyone** pasting JSON, XML, YAML, or SQL into Confluence and getting an unreadable wall of text What you'll learn 1. Why Confluence's built-in code block struggles with JSON, XML, and config files 2. How to embed syntax-highlighted code in 85+ languages using a Monaco-powered editor 3. Theme configuration, diff views, and screenshot-ready window chrome 4. When to use a code block vs. a visual JSON structure diagram The scenario every engineering team hits: you're documenting an API in Confluence, and the page needs to show a JSON response, an XML config, a YAML deployment manifest, and a SQL query — all on the same page. You paste each one into Confluence's built-in code block macro, publish, and the result is a wall of monochrome text. No syntax colors. No line numbers that work. JSON braces, XML tags, and YAML indentation all blur together. The reader has to copy-paste your snippet into VS Code just to understand it. The root problem is that Confluence's native code block uses a basic highlighter that wasn't built for the structured data formats modern teams actually work with. JSON, XML, YAML, and SQL each have specific visual conventions — matched braces, nested tags, indentation scopes — that a generic highlighter doesn't handle well. [**Modern Code Blocks for Confluence**](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence) solves this by bringing the Monaco Editor — the same engine that powers VS Code — into Confluence. It accurately highlights 85+ languages including JSON, XML, YAML, SQL, GraphQL, Terraform, Dockerfile, and every mainstream programming language. This guide walks through embedding formatted code and data formats in your Confluence pages. **Tags:** * [confluence](/blog/tags/confluence.md) * [json](/blog/tags/json.md) * [xml](/blog/tags/xml.md) * [yaml](/blog/tags/yaml.md) * [code-blocks](/blog/tags/code-blocks.md) * [syntax-highlighting](/blog/tags/syntax-highlighting.md) * [how-to](/blog/tags/how-to.md) * [api-documentation](/blog/tags/api-documentation.md) [**Read more**](/blog/display-json-xml-code-in-confluence.md) --- ## [AI Code Review in Confluence: Document and Share Code Reviews](/blog/ai-code-review-confluence.md) July 30, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer AI can help document code reviews in Confluence by summarizing changes, organizing findings, and extracting action items. Create templates, use AI to populate them, and build a searchable review knowledge base. What you'll learn 1. How to create code review templates in Confluence 2. How to use AI to summarize code changes and PRs 3. How to document review findings with AI assistance 4. How to extract and track action items from reviews Code reviews happen in pull requests, but the decisions and context often get lost. When someone asks "why did we implement it this way?" the answer is buried in a closed PR with hundreds of comments. Documenting code reviews in Confluence preserves this context. AI can automate the documentation, turning unstructured PR discussions into organized knowledge. This guide covers how to use AI for code review documentation. **Tags:** * [confluence](/blog/tags/confluence.md) * [ai](/blog/tags/ai.md) * [code-review](/blog/tags/code-review.md) * [how-to](/blog/tags/how-to.md) * [development](/blog/tags/development.md) [**Read more**](/blog/ai-code-review-confluence.md) --- ## [draw.io vs Mermaid in Confluence: Which Fits Your Docs?](/blog/mermaid-vs-drawio-confluence.md) September 28, 2026 · 16 min read [NGPilot](https://ngpilot.com) Quick Answer draw\.io supports Mermaid now — so "does draw\.io do Mermaid?" is no longer the question. The question is **what the source becomes**. In [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), the Mermaid text stays the diagram: page history shows a text diff, an update is one line, and a Rovo agent can create, read, update or convert diagrams from chat. In draw\.io, Mermaid is an import step that turns the diagram into native draw\.io shapes, so you get full styling and shape-library freedom but the page holds shape data instead of reviewable text. On the AI side the difference is where the processing happens: Mermaid Plus runs on Atlassian Forge with Atlassian's own Rovo agent, so the diagram and the AI both stay inside the Atlassian trust boundary, covered by your existing Atlassian agreement. **Text-first docs → Mermaid Plus. Visual-first, icon-heavy or migration-heavy work → draw\.io.** What you'll learn 1. What changed when draw\.io added Mermaid support in 2026 2. Where the two tools genuinely differ, and where they do not 3. How the AI features compare — canvas generation vs a Rovo agent on the page 4. Where the diagram and the AI data live, and why that decides it for enterprise teams 5. A decision framework for Confluence and Jira teams Every Confluence team ends up choosing a diagram tool, and most start by asking the wrong question: does it support Mermaid? These days, two answers exist. [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/) is built around Mermaid — all 30 Mermaid v12 diagram types, a code editor with live preview, one-click templates for every type, and a Rovo AI agent that works on the page. draw\.io is the most-installed diagramming app on the Atlassian Marketplace, with deep shape libraries, whiteboarding, and a Mermaid importer added to its editor. Both are good tools. This guide compares how they behave in Confluence specifically — how a diagram is created, what is stored on the page, what happens when you need to change it six months later, and what it costs. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [drawio](/blog/tags/drawio.md) * [draw-io](/blog/tags/draw-io.md) * [comparison](/blog/tags/comparison.md) * [diagrams](/blog/tags/diagrams.md) [**Read more**](/blog/mermaid-vs-drawio-confluence.md) --- ## [Running Design Whiteboarding Sessions in Confluence — Why We Picked Excalidraw over draw.io](/blog/faq-excalidraw-vs-drawio-confluence.md) May 2, 2026 · 13 min read [NGPilot](https://ngpilot.com) When teams need to add diagrams to Confluence, two tools come up again and again: **Excalidraw** and **draw\.io** (also known as diagrams.net). Both are popular Confluence diagram apps on the Atlassian Marketplace, but they take fundamentally different approaches to visual communication — and picking the wrong one wastes time and licensing budget. The short version: for **live whiteboarding, brainstorming, and freeform sketching**, Excalidraw wins. For **formal, finalized diagrams** (UML, network topology, BPMN), draw\.io is the better fit. Most teams end up needing both — and the rest of this post is the honest, feature-by-feature comparison so you can make the right call for your workflow. Who should read this * **Product/design teams** deciding between Excalidraw and draw\.io for whiteboarding * **Eng leads** choosing a diagramming tool for architecture sketches and UML * **Anyone** comparing the two for freeform vs structured diagramming **Tags:** * [faq](/blog/tags/faq.md) * [excalidraw](/blog/tags/excalidraw.md) * [confluence](/blog/tags/confluence.md) * [diagrams](/blog/tags/diagrams.md) * [comparison](/blog/tags/comparison.md) [**Read more**](/blog/faq-excalidraw-vs-drawio-confluence.md) --- ## [How to See Who Changed What in Jira — Field-Level Issue History](/blog/jira-issue-history.md) September 23, 2026 · 5 min read [NGPilot](https://ngpilot.com) Every Jira issue keeps a diary. Status flips, priority bumps, reassignments, edited specs — Jira writes all of it down. The problem is reading it back: the built-in history turns a description edit into one unhelpful line, and "who changed this?" across forty issues becomes forty clicks or a REST script. This guide covers three ways to actually read Jira issue history, from the free built-in tab to field-level diffs and a cross-issue CSV report. **Tags:** * [jira](/blog/tags/jira.md) * [issue-history](/blog/tags/issue-history.md) * [audit](/blog/tags/audit.md) * [changelog](/blog/tags/changelog.md) * [how-to](/blog/tags/how-to.md) * [compliance](/blog/tags/compliance.md) [**Read more**](/blog/jira-issue-history.md) --- ## [How to Create a Component Hierarchy in Jira](/blog/jira-component-hierarchy.md) September 23, 2026 · 5 min read [NGPilot](https://ngpilot.com) Jira components were designed for a flat world: one list, no nesting, no structure. That works at ten components and collapses at fifty — when "SSO" sits next to "Platform" and "Mobile" with nothing expressing that it belongs under "Auth", which belongs under "Platform". Teams end up encoding the architecture in name prefixes and maintaining ever-growing `component in (...)` lists by hand. This guide covers three ways to get a component hierarchy in Jira, and what each one costs. **Tags:** * [jira](/blog/tags/jira.md) * [components](/blog/tags/components.md) * [hierarchy](/blog/tags/hierarchy.md) * [jql](/blog/tags/jql.md) * [how-to](/blog/tags/how-to.md) * [project-structure](/blog/tags/project-structure.md) [**Read more**](/blog/jira-component-hierarchy.md) --- ## [Excalidraw AI Agent for Confluence: Whiteboards You Can Talk To](/blog/excalidraw-ai-agent-confluence.md) October 10, 2026 · 7 min read [NGPilot](https://ngpilot.com) Confluence holds your team's diagrams in two worlds, and the two don't talk to each other. Text-defined diagrams — Mermaid and friends — are what AI speaks natively. They're source code, so a chat agent can read them, write them, and revise them. We shipped exactly that last week: [an AI agent for Mermaid in Confluence](/blog/mermaid-ai-agent-confluence.md). Whiteboards are the other world. Freeform shapes, hand-drawn lines, arrows you drag where they need to go — the format that's actually intuitive to put in front of people. Every team has one: the architecture board on the team page, the incident flow everyone references, the onboarding map. And AI couldn't touch any of it. Ask a chat agent for a change to a whiteboard and you'd get a text *description* of a change, and someone still had to open the canvas and do it by hand. That gap is why whiteboards go stale. Editing shapes one drag at a time is slow enough that nobody does it, and AI — the thing that was supposed to make maintenance cheap — had no way in. The AI agent in [Excalidraw Plus Whiteboards & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence) closes the gap: the whiteboard stays what it always was — visual, intuitive, for people — but now you can operate it in plain language, from Confluence chat. **Tags:** * [confluence](/blog/tags/confluence.md) * [excalidraw](/blog/tags/excalidraw.md) * [whiteboard](/blog/tags/whiteboard.md) * [diagrams](/blog/tags/diagrams.md) * [ai](/blog/tags/ai.md) * [agent](/blog/tags/agent.md) [**Read more**](/blog/excalidraw-ai-agent-confluence.md) --- ## [Confluence Permissions: The Ultimate Guide (2026)](/blog/confluence-permissions-ultimate-guide-2026.md) July 30, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Confluence permissions control who can view, edit, and administer content. You manage permissions at three levels: **site admin** (global), **space admin** (space-level), and **page restrictions** (page-level). Understanding the inheritance hierarchy is key — lower-level settings always override higher-level ones. **Tags:** * [confluence](/blog/tags/confluence.md) * [confluence-admin](/blog/tags/confluence-admin.md) * [permissions](/blog/tags/permissions.md) * [security](/blog/tags/security.md) * [atlassian](/blog/tags/atlassian.md) [**Read more**](/blog/confluence-permissions-ultimate-guide-2026.md) --- ## [Graphviz Charts in Confluence: draw.io vs Graphviz vs Mermaid](/blog/graphviz-charts-confluence-comparison.md) July 30, 2026 · 4 min read [NGPilot](https://ngpilot.com) Teams use Confluence to document architecture, processes, and organizational structures. But Confluence doesn't render graphs or charts natively — you need a marketplace app. We built **Graphviz Charts for Confluence** to bring the power of Graphviz and DOT language to Confluence pages. In this post, we compare it against every alternative. **Tags:** * [confluence](/blog/tags/confluence.md) * [confluence-apps](/blog/tags/confluence-apps.md) * [comparison](/blog/tags/comparison.md) * [graphviz](/blog/tags/graphviz.md) * [charts](/blog/tags/charts.md) [**Read more**](/blog/graphviz-charts-confluence-comparison.md) --- ## [Enhanced Markdown vs Other Confluence Markdown Apps — Feature Matrix](/blog/confluence-markdown-editor-comparison.md) April 18, 2026 · 8 min read [NGPilot](https://ngpilot.com) Developers write in Markdown. Confluence doesn't. Every engineering team that moves from GitHub wikis, README files, or Hugo docs to Confluence hits the same wall — the rich text editor feels slow, and there's no way to write in the format they already know. Several marketplace apps bring Markdown to Confluence, but they take different approaches. Some embed Markdown as macros. Others import Markdown files. A few offer live editing. We built **Enhanced Markdown for Confluence** to give teams a full WYSIWYG Markdown editor with code highlighting, charts, UML diagrams, and table merging — all inside the Confluence page editor. In this post we compare it against every alternative. **Tags:** * [markdown](/blog/tags/markdown.md) * [markdown-editor](/blog/tags/markdown-editor.md) * [confluence](/blog/tags/confluence.md) * [wysiwyg](/blog/tags/wysiwyg.md) * [syntax-highlighting](/blog/tags/syntax-highlighting.md) * [plantuml](/blog/tags/plantuml.md) * [charts](/blog/tags/charts.md) * [confluence-markdown-editor](/blog/tags/confluence-markdown-editor.md) [**Read more**](/blog/confluence-markdown-editor-comparison.md) --- ## [How to Visualize Confluence Documentation with SVGs (No Design Skills Required)](/blog/visualize-confluence-documentation-with-svgs.md) May 27, 2025 · 2 min read [NGPilot](https://ngpilot.com) Tired of text-heavy Confluence pages? Discover how **1,300+ ready-to-use SVGs** across 25 professional categories can enhance your documentation - no design experience needed. **Tags:** * [confluence-tips](/blog/tags/confluence-tips.md) * [visual-documentation](/blog/tags/visual-documentation.md) * [svg-library](/blog/tags/svg-library.md) [**Read more**](/blog/visualize-confluence-documentation-with-svgs.md) --- ## [How to Create Gantt Charts in Confluence — Mermaid Examples](/blog/how-to-create-gantt-charts-confluence.md) May 2, 2026 · 15 min read [NGPilot](https://ngpilot.com) Gantt charts are one of the most widely used visual tools in project management. They give teams a clear, time-based view of who is doing what, when tasks start and end, and how dependencies chain together across a project lifecycle. Whether you are planning a software release, coordinating a marketing campaign, or managing a sprint backlog, a Gantt chart turns a flat task list into a timeline your whole team can read at a glance. Confluence is where many teams already store their project documentation, meeting notes, and decision records. Embedding Gantt charts directly on Confluence pages keeps your project visuals alongside the context your team needs, instead of burying timelines in a separate project management tool that nobody checks. With Mermaid Plus Diagrams & AI Agent for Confluence, you can write Gantt charts using plain text syntax and see them rendered instantly on the page. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [gantt](/blog/tags/gantt.md) * [how-to](/blog/tags/how-to.md) * [diagrams](/blog/tags/diagrams.md) * [project-management](/blog/tags/project-management.md) [**Read more**](/blog/how-to-create-gantt-charts-confluence.md) --- ## [Best Diagram Tool for Confluence — Mermaid vs Excalidraw vs Graphviz](/blog/confluence-diagram-tools-comparison.md) April 24, 2026 · 9 min read [NGPilot](https://ngpilot.com) Looking for the best **diagram tool for Confluence**? Confluence has no built-in diagramming, so every team adds a Marketplace app — but the right choice depends entirely on *what* you draw and *how* you prefer to work. This guide compares the three strongest options — [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?hosting=cloud\&tab=overview), [Excalidraw Plus Whiteboards & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence?hosting=cloud\&tab=overview), and [Graphviz Charts for Confluence](https://marketplace.atlassian.com/apps/1237380/graphviz-charts-for-confluence?hosting=cloud\&tab=overview) — so you can pick the diagram tool that fits your team instead of guessing. Quick answer For most Confluence teams, **Mermaid Plus** is the best diagram tool — it covers the widest range (30 diagram types), is the easiest to learn, and renders text into diagrams that version cleanly with your docs. Pick **Excalidraw Plus** if you need freehand whiteboarding and wireframes. Pick **Graphviz Charts** for dense network and dependency graphs. Many teams install more than one. What you'll learn 1. Which diagram tool fits each type of Confluence team 2. The strengths and trade-offs of Mermaid, Excalidraw, and Graphviz 3. Pricing, hosting, and integration differences 4. A decision framework so you can choose in under a minute **Tags:** * [confluence](/blog/tags/confluence.md) * [diagrams](/blog/tags/diagrams.md) * [mermaid](/blog/tags/mermaid.md) * [excalidraw](/blog/tags/excalidraw.md) * [graphviz](/blog/tags/graphviz.md) * [comparison](/blog/tags/comparison.md) * [excalidraw-vs-mermaid](/blog/tags/excalidraw-vs-mermaid.md) [**Read more**](/blog/confluence-diagram-tools-comparison.md) --- ## [Mermaid in Confluence Not Rendering? Fixes & FAQ](/blog/faq-mermaid-troubleshooting.md) April 21, 2026 · 13 min read [NGPilot](https://ngpilot.com) **Tags:** * [faq](/blog/tags/faq.md) * [mermaid](/blog/tags/mermaid.md) * [confluence](/blog/tags/confluence.md) * [diagrams](/blog/tags/diagrams.md) * [troubleshooting](/blog/tags/troubleshooting.md) [**Read more**](/blog/faq-mermaid-troubleshooting.md) --- ## [Excalidraw for Confluence — Which Whiteboard and Drawing App Fits Your Team?](/blog/use-excalidraw-in-confluence-whiteboard-diagrams.md) April 9, 2026 · 6 min read [NGPilot](https://ngpilot.com) **Excalidraw in Confluence** brings hand-drawn style diagrams and whiteboards to your wiki. This guide compares Excalidraw Plus vs draw\.io — features, libraries, and which fits your team's needs. Who should read this * Teams needing whiteboards and diagrams in Confluence * Users comparing Excalidraw vs draw\.io * Anyone adding visual collaboration to documentation What you'll learn 1. Excalidraw vs draw\.io comparison 2. Setting up Excalidraw in Confluence 3. Shape libraries and Mermaid integration 4. Best practices for team collaboration **Tags:** * [excalidraw](/blog/tags/excalidraw.md) * [diagrams](/blog/tags/diagrams.md) * [confluence](/blog/tags/confluence.md) [**Read more**](/blog/use-excalidraw-in-confluence-whiteboard-diagrams.md) --- ## [API Sequence Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-api-sequence-diagram-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The integration doc says "the client calls the API, the API validates and responds" — four words, zero contracts, and the onboarding engineer asks "with what headers, in what order, and what if auth fails?" The code has the truth; the wiki has a paragraph. An API that can't be read as a transcript is an API nobody can safely operate. **Quick answer:** document API flows in Confluence as Mermaid — `sequenceDiagram` for request/response order, `packet-beta` for wire-format frames, ZenUML for branch-heavy async flows — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Each diagram type answers a different reader: what order, what's on the wire, what branches. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [sequence-diagram](/blog/tags/sequence-diagram.md) * [packet](/blog/tags/packet.md) * [zenuml](/blog/tags/zenuml.md) * [api](/blog/tags/api.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-api-sequence-diagram-confluence.md) --- ## [Kanban Board Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-kanban-board-workflow-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The sprint board on the wall shows 40 items in "In Progress" and the rulebook says "we limit WIP" and nobody agrees on what the limit is. The board is honest; the *documentation* is aspirational. A Kanban diagram in the wiki is the board as a spec — columns, limits, and the rework paths drawn so the workflow is a claim the team can argue with. **Quick answer:** document the team's board in Confluence as a Mermaid `kanban`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Columns as headings, work items as indented cards; the workflow *rules* (who may move what, when, including rework) as a `stateDiagram` on the same page. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [kanban](/blog/tags/kanban.md) * [workflow](/blog/tags/workflow.md) * [state-diagram](/blog/tags/state-diagram.md) * [agile](/blog/tags/agile.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-kanban-board-workflow-confluence.md) --- ## [Mermaid 12 in Confluence & Jira: UML Use Case Diagrams and a New Look](/blog/mermaid-12-confluence-jira.md) September 19, 2026 · 5 min read [NGPilot](https://ngpilot.com) Mermaid 12 is the biggest release the diagram language has had in years — and as of today it is live in all three NGPILOT diagram apps: **Enhanced Markdown for Confluence**, **Mermaid Plus Diagrams & AI Agent for Confluence**, and **Mermaid Plus Diagrams for Jira**. You get the headline feature immediately: **UML use case diagrams**, the diagram type Confluence and Jira teams have been asking for since requirements documents moved out of dedicated UML tools. **Tags:** * [confluence](/blog/tags/confluence.md) * [jira](/blog/tags/jira.md) * [mermaid](/blog/tags/mermaid.md) * [diagrams](/blog/tags/diagrams.md) * [release-notes](/blog/tags/release-notes.md) * [use-case-diagram](/blog/tags/use-case-diagram.md) [**Read more**](/blog/mermaid-12-confluence-jira.md) --- ## [Build Modern Confluence Pages in 2026: Hero Sections & QR Codes](/blog/build-modern-confluence-pages-hero-articles-qr-forms.md) July 31, 2026 · 9 min read [NGPilot](https://ngpilot.com) Who should read this * **Confluence admins and space owners** who want their intranet, portal, or knowledge base to look professional * **Marketing and product teams** building landing pages, announcements, and product updates in Confluence * **Anyone** who has ever thought "I know what I want this page to look like — I just can't make Confluence do it" What you'll learn 1. How to make a Confluence page read like Medium (drop caps, clean typography, bilingual mode) 2. How to add a proper hero section with CTAs — something the native editor doesn't have 3. How to style tables without fighting the editor 4. How to add QR codes, collect survey responses, and define glossary terms inline — all without external tools Take a look at your most-visited Confluence page right now. Does it look like it belongs on the modern web — or does it look like internal documentation from 2015? If your answer is the latter, you're not alone. Teams across thousands of Confluence sites tell us the same story: "I know exactly what I want my page to look like. I just can't make Confluence do it." In this guide, we'll show you six concrete ways to level up your Confluence pages — from Medium-style reading layouts to interactive surveys — all without leaving your editor. **Tags:** * [confluence](/blog/tags/confluence.md) * [page-builder](/blog/tags/page-builder.md) * [macros](/blog/tags/macros.md) * [how-to](/blog/tags/how-to.md) * [productivity](/blog/tags/productivity.md) [**Read more**](/blog/build-modern-confluence-pages-hero-articles-qr-forms.md) --- ## [What Is Atlassian Government Cloud (AGC)? NGPILOT Apps Available (2026)](/blog/what-is-atlassian-government-cloud.md) July 30, 2026 · 3 min read [NGPilot](https://ngpilot.com) Quick Answer Atlassian Government Cloud (AGC) is a FedRAMP-authorized deployment of Confluence and Jira designed for U.S. government agencies and contractors. It meets FedRAMP Moderate baseline requirements for handling sensitive government data. NGPILOT has apps available on AGC for teams needing compliant diagramming and content tools. **Tags:** * [atlassian](/blog/tags/atlassian.md) * [government-cloud](/blog/tags/government-cloud.md) * [agc](/blog/tags/agc.md) * [fedramp](/blog/tags/fedramp.md) * [compliance](/blog/tags/compliance.md) * [confluence](/blog/tags/confluence.md) * [jira](/blog/tags/jira.md) [**Read more**](/blog/what-is-atlassian-government-cloud.md) --- ## [Can You Change the Font in Confluence? (Default Stack & Custom Font Options)](/blog/confluence-default-font-change-font.md) May 10, 2026 · 3 min read [NGPilot](https://ngpilot.com) Confluence uses a system font stack that looks different on every operating system. You can't change the default font globally, and Confluence offers no built-in way to use custom fonts on individual pages. This guide shows what font Confluence uses and how to add custom fonts. **Tags:** * [confluence](/blog/tags/confluence.md) * [fonts](/blog/tags/fonts.md) * [google-fonts](/blog/tags/google-fonts.md) * [typography](/blog/tags/typography.md) * [customization](/blog/tags/customization.md) [**Read more**](/blog/confluence-default-font-change-font.md) --- ## [Confluence Font Apps Compared: Google Fonts vs Custom Fonts Pro](/blog/confluence-font-apps-comparison.md) May 2, 2026 · 11 min read [NGPilot](https://ngpilot.com) Confluence ships with a fixed set of system fonts. For most teams that works fine, but if your company has brand guidelines, an accessibility requirement for specific typefaces, or simply wants documentation that looks polished and professional, the default typography falls short. The Atlassian Marketplace now offers several apps that let you use custom fonts on your Confluence pages. But with different feature sets, pricing models, and levels of maturity, choosing the right one takes more than a quick glance at star ratings. This post compares the leading Confluence custom font apps side by side so you can make an informed decision for your team. **Tags:** * [comparison](/blog/tags/comparison.md) * [confluence](/blog/tags/confluence.md) * [fonts](/blog/tags/fonts.md) * [google-fonts](/blog/tags/google-fonts.md) * [typography](/blog/tags/typography.md) [**Read more**](/blog/confluence-font-apps-comparison.md) --- ## [Confluence Custom Fonts FAQ: Change Fonts, Setup & Alternatives](/blog/faq-google-fonts-confluence-alternatives.md) May 2, 2026 · 15 min read [NGPilot](https://ngpilot.com) **Tags:** * [faq](/blog/tags/faq.md) * [google-fonts](/blog/tags/google-fonts.md) * [confluence](/blog/tags/confluence.md) * [typography](/blog/tags/typography.md) * [fonts](/blog/tags/fonts.md) [**Read more**](/blog/faq-google-fonts-confluence-alternatives.md) --- ## [Forge vs Connect: What Atlassian Admins Need to Know in 2026](/blog/forge-vs-connect-atlassian-admins-2026.md) August 2, 2026 · 10 min read [NGPilot](https://ngpilot.com) Quick Answer Forge and Connect are the two frameworks Atlassian Marketplace apps can be built on. **Forge** runs on Atlassian's own infrastructure; **Connect** runs on vendor-hosted servers. Starting January 1, 2026, Atlassian applies a penalty to Connect apps in Marketplace rankings and requires Forge for new Cloud Fortified status. For admins evaluating apps in 2026, Forge is the safer, more future-proof choice where a capable option exists. What you'll learn 1. The real architectural difference between Forge and Connect 2. What the 2026 Connect penalty changes for app discovery and trust 3. How to tell which framework an app uses before you install it 4. A practical decision framework for evaluating apps in 2026 If you administer Jira or Confluence Cloud, every app you install from the Marketplace runs on one of two frameworks: **Forge** or **Connect**. For years the difference was mostly an implementation detail that admins could ignore. In 2026 that changed. The Connect penalty, the Cloud Fortified requirement, and Atlassian's clear strategic direction mean the framework an app uses now affects its security posture, its discoverability, and how long it will keep working. This guide explains what changed, why it matters, and how to make better app decisions because of it. **Tags:** * [atlassian](/blog/tags/atlassian.md) * [forge](/blog/tags/forge.md) * [connect](/blog/tags/connect.md) * [marketplace](/blog/tags/marketplace.md) * [explained](/blog/tags/explained.md) * [admin](/blog/tags/admin.md) [**Read more**](/blog/forge-vs-connect-atlassian-admins-2026.md) --- ## [How to Add SVG Illustrations to Confluence Pages](/blog/how-to-add-svg-illustrations-confluence.md) May 2, 2026 · 17 min read [NGPilot](https://ngpilot.com) Adding illustrations to Confluence pages transforms flat walls of text into engaging, professional content. Whether you are writing onboarding documentation, putting together a team wiki, or preparing a presentation, the right visual can communicate an idea faster than a paragraph of explanation. The challenge has always been finding high-quality illustrations that look good at any size, load quickly, and match your team's visual style. SVG (Scalable Vector Graphics) illustrations solve all of these problems. They scale perfectly to any resolution, they are lightweight, and they integrate cleanly into Confluence pages. Content Craft for Confluence brings a curated library of SVG illustrations directly into the Confluence editor, so you can browse, search, and insert professional illustrations without leaving your workflow. This tutorial shows you exactly how to add SVG illustrations to Confluence pages using Content Craft for Confluence. By the end, you will be able to transform any Confluence page from text-heavy to visually engaging in under a minute. **Tags:** * [confluence](/blog/tags/confluence.md) * [svg](/blog/tags/svg.md) * [illustrations](/blog/tags/illustrations.md) * [content-craft](/blog/tags/content-craft.md) * [how-to](/blog/tags/how-to.md) * [design](/blog/tags/design.md) [**Read more**](/blog/how-to-add-svg-illustrations-confluence.md) --- ## [How to Add a Block Quote in Confluence (3 Methods Compared)](/blog/block-quote-confluence.md) August 5, 2026 · 5 min read [NGPilot](https://ngpilot.com) A **block quote** sets a passage apart from the surrounding text — usually indented with a left border — to indicate that the words are quoted from another source. Confluence does not have a dedicated "quote block" button, but there are three reliable ways to create one. This guide walks through each and helps you pick the right one. What you'll learn 1. The native method (toolbar Indent) — no app required 2. The Markdown method (`>` syntax) — fastest for keyboard users 3. The panel macro method (Content Formatting) — most styling control 4. How to nest quotes and add attribution **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [formatting](/blog/tags/formatting.md) * [blockquote](/blog/tags/blockquote.md) * [enhanced-markdown](/blog/tags/enhanced-markdown.md) * [content-formatting](/blog/tags/content-formatting.md) [**Read more**](/blog/block-quote-confluence.md) --- ## [Best Confluence Import/Export Apps Compared — 2026 Guide](/blog/confluence-import-export-comparison.md) April 18, 2026 · 7 min read [NGPilot](https://ngpilot.com) Teams move content in and out of Confluence every day — migrating between instances, backing up documentation, importing from other tools, exporting for offline review. Confluence has basic PDF and HTML export built in, but it's limited. No bulk operations, no multi-format support, no structured import workflow. Over a dozen marketplace apps try to fill this gap, but most solve one narrow problem: PDF export, Word import, or Markdown conversion. We built **Modern Importer & Exporter for Confluence** to handle both directions — import and export — across multiple formats. In this post we compare it against every alternative on the Atlassian Marketplace. **Tags:** * [import](/blog/tags/import.md) * [export](/blog/tags/export.md) * [confluence](/blog/tags/confluence.md) * [migration](/blog/tags/migration.md) * [backup](/blog/tags/backup.md) * [markdown](/blog/tags/markdown.md) * [pdf](/blog/tags/pdf.md) * [word](/blog/tags/word.md) * [content-transfer](/blog/tags/content-transfer.md) [**Read more**](/blog/confluence-import-export-comparison.md) --- ## [Import Markdown into Confluence — 3 Methods Compared (2026)](/blog/markdown-to-confluence-converter.md) May 10, 2026 · 5 min read [NGPilot](https://ngpilot.com) Who should read this * Development teams importing GitHub READMEs to Confluence * Documentation engineers migrating Markdown file sets * Anyone who wants to write Markdown directly in Confluence What you'll learn 1. Comparison of three Markdown import methods 2. How to choose the best tool for your use case 3. Step-by-step setup instructions Many teams have documentation in Markdown format (GitHub READMEs, API docs, developer guides) and need to bring it into Confluence. Confluence doesn't have a native Markdown import feature, but there are three ways to get Markdown content into Confluence pages. **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [import](/blog/tags/import.md) * [converter](/blog/tags/converter.md) * [enhanced-markdown](/blog/tags/enhanced-markdown.md) * [import-export](/blog/tags/import-export.md) [**Read more**](/blog/markdown-to-confluence-converter.md) --- ## [Jira Export Limit: How to Export More Than 1,000 Issues (2026)](/blog/jira-export-limit.md) September 2, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Jira Cloud's native export stops at 1,000 issues per export and only includes columns visible in the issue navigator. To export more: split your filter into JQL batches, use the REST API, or install [Simple Bulk Issues Excel CSV Export](https://marketplace.atlassian.com/apps/3818473739/simple-bulk-issues-excel-csv-export-for-jira?utm_source=ngpilot.com\&utm_medium=blog), which exports up to 5,000 issues per run in CSV, XLS, or XLSX — and tells you plainly when a result set was truncated. If you have ever exported a project for reporting, an audit, or a migration, you have probably run into Jira Cloud's export limit without being warned first: the export finishes, the file looks complete, and the row count quietly stops at 1,000. This article explains where that limit comes from, then compares the three practical ways to export larger issue sets in 2026. **Tags:** * [jira](/blog/tags/jira.md) * [export](/blog/tags/export.md) * [excel](/blog/tags/excel.md) * [csv](/blog/tags/csv.md) * [jira-cloud](/blog/tags/jira-cloud.md) * [reporting](/blog/tags/reporting.md) [**Read more**](/blog/jira-export-limit.md) --- ## [How to Change Fonts in Confluence (Google Fonts, Custom Typography & More)](/blog/how-to-add-custom-fonts-confluence.md) May 2, 2026 · 19 min read [NGPilot](https://ngpilot.com) **Custom fonts in Confluence** let you apply brand typography to your documentation. This guide covers **Google Fonts for Confluence** — 1,942+ font families, live preview, dark mode support, and customization options. Who should read this * Teams with brand guidelines needing custom typography * Marketing/HR wanting branded Confluence pages * Anyone wanting to change default Confluence fonts What you'll learn 1. How to add Google Fonts to Confluence 2. Choosing and applying font families 3. Customizing size, color, and alignment 4. Dark mode and theme considerations Google Fonts for Confluence gives you access to over 1,942 Google Fonts directly inside your Confluence pages. You can customize font family, weight, size, color, and alignment with a live preview that shows exactly how your text will look before you save. This step-by-step tutorial walks through everything: installing the app, configuring fonts, applying them across spaces, and maintaining a consistent typographic system that respects accessibility and brand standards. **Tags:** * [confluence](/blog/tags/confluence.md) * [google-fonts](/blog/tags/google-fonts.md) * [typography](/blog/tags/typography.md) * [custom-fonts](/blog/tags/custom-fonts.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/how-to-add-custom-fonts-confluence.md) --- ## [Customer Journey Maps in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-journey-diagram-customer-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The support team knows where refunds leak. The product team knows where onboarding drops. The sales team knows where the pricing page confuses. Three silos, three versions of the customer's experience — and the roadmap meeting spends an hour reconciling them instead of deciding what to fix. What is missing is a single picture with a score on every step. **Quick answer:** draw customer journeys in Confluence as Mermaid `journey` diagrams, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). A journey diagram puts every step in a row and every satisfaction score on one curve — the dips are visible, the actors are labeled, and the whole thing stays editable text. This post gives you three copy-paste examples: onboarding, a support ticket, and a checkout flow with a summary pie. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [journey](/blog/tags/journey.md) * [customer-experience](/blog/tags/customer-experience.md) * [product](/blog/tags/product.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-journey-diagram-customer-confluence.md) --- ## [How to Set Up Announcement Banners in Confluence and Jira](/blog/how-to-set-up-announcement-banners-confluence-jira.md) May 23, 2026 · 7 min read [NGPilot](https://ngpilot.com) Announcement banners are the most visible communication channel in Atlassian products. They sit at the top of every page, impossible to miss. When you need to notify your entire organization about a maintenance window, a security alert, a policy change, or an upcoming event, banners guarantee visibility in a way that emails and Slack messages cannot. Both Confluence and Jira support announcement banners, but their native implementations are limited. This guide covers how to set up banners in both platforms using built-in features and marketplace apps, with practical tips for getting the most out of them. **Tags:** * [confluence](/blog/tags/confluence.md) * [jira](/blog/tags/jira.md) * [announcement-banner](/blog/tags/announcement-banner.md) * [how-to](/blog/tags/how-to.md) * [customization](/blog/tags/customization.md) [**Read more**](/blog/how-to-set-up-announcement-banners-confluence-jira.md) --- ## [Decision Framework Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-decision-framework-diagrams-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The meeting asks "who owns this feature?" and the answer is a Venn diagram by hand — drawn on a whiteboard, erased, redrawn, photographed, and lost. Two teams each built a piece of a shared workflow, and "the overlap" is exactly where the bugs and the SQL both landed. A decision framework is only useful while its picture survives the meeting; in Confluence as Mermaid text, it survives. **Quick answer:** put decision frameworks in Confluence as Mermaid — `venn-beta` for set overlap, `cynefin-beta` for which operating mode a situation needs, `quadrantChart` for which item goes first — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Each framework encodes a decision *shape*, and text keeps the picture attached to the decision record. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [venn-diagram](/blog/tags/venn-diagram.md) * [cynefin](/blog/tags/cynefin.md) * [quadrant](/blog/tags/quadrant.md) * [decision](/blog/tags/decision.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-decision-framework-diagrams-confluence.md) --- ## [Dark Mode for Confluence Code Blocks — Setup Walkthrough](/blog/confluence-code-editor-syntax-highlighting.md) May 6, 2026 · 4 min read [NGPilot](https://ngpilot.com) Confluence's built-in code block macro is limited — it supports roughly 30 languages, has no dark theme, and lacks basic features like copy buttons and collapsible sections. If your team writes documentation with code snippets, you need something better. This guide shows how to add a VS Code-grade code editor to Confluence with syntax highlighting for 85+ languages, automatic dark/light theme detection, and one-click copy buttons. **Tags:** * [confluence](/blog/tags/confluence.md) * [code-blocks](/blog/tags/code-blocks.md) * [syntax-highlighting](/blog/tags/syntax-highlighting.md) * [dark-mode](/blog/tags/dark-mode.md) * [monaco-editor](/blog/tags/monaco-editor.md) * [developers](/blog/tags/developers.md) [**Read more**](/blog/confluence-code-editor-syntax-highlighting.md) --- ## [Mermaid Charts for Confluence Dashboards: Pie & XY in One Post](/blog/mermaid-charts-dashboard-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The quarterly review loads a 14-tab spreadsheet to answer one question — "where do we actually spend our engineering time?" — because the wiki charts are stale screenshots from last quarter and the numbers table nobody reads. A dashboard is not a spreadsheet: it is the two charts that answer the two questions people keep asking. **Quick answer:** build dashboard charts in Confluence with Mermaid `pie` and `xychart-beta` charts, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Pie for shares, XY for trends — both as editable text that refreshes like code. This post gives you three copy-paste examples: an effort-share pie, a weekly trend XY, and a dual-series release dashboard. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [pie-chart](/blog/tags/pie-chart.md) * [xychart-beta](/blog/tags/xychart-beta.md) * [dashboard](/blog/tags/dashboard.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-charts-dashboard-confluence.md) --- ## [How to Set Up Jira Dashboards for Sprint Tracking and Stakeholder Visibility](/blog/jira-dashboard-sprint-tracking-setup.md) July 29, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Jira dashboards provide real-time visibility into sprint health, velocity trends, and team performance. Configure gadgets, create JQL filters, and share dashboards with stakeholders. What you'll learn 1. How to create and configure a Jira dashboard from scratch 2. Which gadgets track sprint health vs long-term trends 3. How to set up JQL filters for custom dashboard views 4. How to share dashboards and set up email subscriptions A well-designed Jira dashboard gives your team instant visibility into sprint health, backlog status, and delivery trends. But most dashboards are either empty defaults or cluttered messes that nobody uses. This guide covers how to build dashboards that actually provide value — from sprint tracking to stakeholder reporting. **Tags:** * [jira](/blog/tags/jira.md) * [dashboards](/blog/tags/dashboards.md) * [how-to](/blog/tags/how-to.md) * [reporting](/blog/tags/reporting.md) * [sprint-tracking](/blog/tags/sprint-tracking.md) [**Read more**](/blog/jira-dashboard-sprint-tracking-setup.md) --- ## [Create Pie Charts in Confluence — Free with Mermaid Syntax](/blog/how-to-create-pie-charts-confluence.md) May 2, 2026 · 18 min read [NGPilot](https://ngpilot.com) Pie charts are one of the simplest and most effective ways to communicate proportional data. Whether you are reporting survey results, breaking down a project budget, or showing how your team allocates time across activities, a pie chart turns a list of numbers into a visual that anyone can read in seconds. Confluence is where your team already stores reports, retrospectives, and planning documents, so embedding pie charts directly on those pages keeps your data alongside the context that explains it. With Mermaid Plus Diagrams & AI Agent for Confluence, you can create pie charts and other data visualizations using plain text syntax. No image exports, no spreadsheet screenshots, no broken attachments. You write the code once, and the chart renders directly on the Confluence page, updating whenever you edit the underlying data. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [pie-chart](/blog/tags/pie-chart.md) * [data-visualization](/blog/tags/data-visualization.md) * [how-to](/blog/tags/how-to.md) * [charts](/blog/tags/charts.md) [**Read more**](/blog/how-to-create-pie-charts-confluence.md) --- ## [Database Schema Diagrams in Confluence with Mermaid ER (Entity Relationship) — Copy-Paste](/blog/mermaid-er-diagram-database-schema-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The bug report says "orders show twice in the report" and the fix takes three days because nobody on the team is sure whether `order_lines` links to `orders` on `order_id` or `source_order_id`, and both columns exist. The schema is documented — in a `schema.md` that lists columns as bullets and a diagram that was last exported when the DB was two migrations younger. The join question is exactly the thing an ER diagram answers at a glance, and the thing a bulleted column list cannot answer at all. **Quick answer:** document the database schema in Confluence as a Mermaid `erDiagram`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Entities hold keys and attributes; relationship lines carry the cardinality and the join's noun. When the discussion turns to the domain model the code exposes, add a `classDiagram` on the same page. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [er-diagram](/blog/tags/er-diagram.md) * [database](/blog/tags/database.md) * [schema](/blog/tags/schema.md) * [class-diagram](/blog/tags/class-diagram.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-er-diagram-database-schema-confluence.md) --- ## [Decision Framework Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-decision-framework-diagrams-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The meeting asks "who owns this feature?" and the answer is a Venn diagram by hand — drawn on a whiteboard, erased, redrawn, photographed, and lost. Two teams each built a piece of a shared workflow, and "the overlap" is exactly where the bugs and the SQL both landed. A decision framework is only useful while its picture survives the meeting; in Confluence as Mermaid text, it survives. **Quick answer:** put decision frameworks in Confluence as Mermaid — `venn-beta` for set overlap, `cynefin-beta` for which operating mode a situation needs, `quadrantChart` for which item goes first — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Each framework encodes a decision *shape*, and text keeps the picture attached to the decision record. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [venn-diagram](/blog/tags/venn-diagram.md) * [cynefin](/blog/tags/cynefin.md) * [quadrant](/blog/tags/quadrant.md) * [decision](/blog/tags/decision.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-decision-framework-diagrams-confluence.md) --- ## [How to Add a Checklist to Jira — and Block Transitions Until Done](/blog/jira-checklist.md) September 18, 2026 · 5 min read [NGPilot](https://ngpilot.com) Every team has a definition of done. The problem is that in Jira, "done" is one button press — nothing checks whether the release notes were written, the tests passed, or the customer was notified. A checklist fixes the *remembering*; enforcement fixes the *skipping*. This guide covers three ways to add a checklist to Jira issues, from a two-minute bullet list to required items that physically block the Done transition. **Tags:** * [jira](/blog/tags/jira.md) * [checklist](/blog/tags/checklist.md) * [workflow](/blog/tags/workflow.md) * [how-to](/blog/tags/how-to.md) * [definition-of-done](/blog/tags/definition-of-done.md) * [process](/blog/tags/process.md) [**Read more**](/blog/jira-checklist.md) --- ## [What Is Atlassian Isolated Cloud? NGPILOT Apps Available (2026)](/blog/what-is-atlassian-isolated-cloud.md) July 30, 2026 · 4 min read [NGPilot](https://ngpilot.com) Quick Answer Atlassian Isolated Cloud lets you deploy marketplace apps within your own dedicated Atlassian cloud instance — separate from other tenants. This provides enhanced data isolation while keeping the benefits of cloud (no server maintenance, automatic updates). NGPILOT has 6 apps certified for Isolated Cloud. **Tags:** * [atlassian](/blog/tags/atlassian.md) * [isolated-cloud](/blog/tags/isolated-cloud.md) * [confluence](/blog/tags/confluence.md) * [jira](/blog/tags/jira.md) * [deployment](/blog/tags/deployment.md) [**Read more**](/blog/what-is-atlassian-isolated-cloud.md) --- ## [How to Add SVG Illustrations to Confluence Pages](/blog/how-to-add-svg-illustrations-confluence.md) May 2, 2026 · 17 min read [NGPilot](https://ngpilot.com) Adding illustrations to Confluence pages transforms flat walls of text into engaging, professional content. Whether you are writing onboarding documentation, putting together a team wiki, or preparing a presentation, the right visual can communicate an idea faster than a paragraph of explanation. The challenge has always been finding high-quality illustrations that look good at any size, load quickly, and match your team's visual style. SVG (Scalable Vector Graphics) illustrations solve all of these problems. They scale perfectly to any resolution, they are lightweight, and they integrate cleanly into Confluence pages. Content Craft for Confluence brings a curated library of SVG illustrations directly into the Confluence editor, so you can browse, search, and insert professional illustrations without leaving your workflow. This tutorial shows you exactly how to add SVG illustrations to Confluence pages using Content Craft for Confluence. By the end, you will be able to transform any Confluence page from text-heavy to visually engaging in under a minute. **Tags:** * [confluence](/blog/tags/confluence.md) * [svg](/blog/tags/svg.md) * [illustrations](/blog/tags/illustrations.md) * [content-craft](/blog/tags/content-craft.md) * [how-to](/blog/tags/how-to.md) * [design](/blog/tags/design.md) [**Read more**](/blog/how-to-add-svg-illustrations-confluence.md) --- ## [Paste Mermaid Diagrams into Confluence — Now on Mermaid 12](/blog/paste-mermaid-diagrams-into-confluence.md) September 28, 2026 · 9 min read [NGPilot](https://ngpilot.com) Quick Answer Confluence's editor is WYSIWYG and has no Mermaid renderer, so pasting a Markdown file that contains ` ```mermaid ` fences imports them as plain code blocks — the diagrams arrive dead. Paste into a Markdown macro instead: [**Enhanced Markdown for Confluence**](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence/) renders Mermaid 12 inline, so a whole README pastes in and the diagrams come alive. The v12 upgrade is what makes this newly worthwhile — **UML use case diagrams** now survive the paste, which is the diagram type requirements docs kept losing. What you'll learn 1. Why Mermaid dies on the way into Confluence, and where the fix lives 2. The paste workflow: repo Markdown in, rendered diagrams out 3. What Mermaid 12 changes — use case diagrams, refreshed layout, richer ZenUML 4. What happens to diagrams you already published The diagrams live in the repository. They were written in Mermaid, they are reviewed in pull requests next to the code they describe, and they are correct as of the last commit. The documentation, however, lives in Confluence — because that is where the rest of the team reads it. So somebody copies a Markdown file across, pastes it into a Confluence page, and the flowcharts, sequence diagrams and ER models arrive as grey boxes of unrendered code. Everyone has hit this. It is one of the most common Confluence complaints, and the usual workarounds are worse than the problem: export every diagram to PNG and re-upload them (now they rot), keep the diagrams in an external tool and paste links (readers need a second account, and the links break), or build a browser extension to force rendering on paste. There is a better answer, and Mermaid 12 makes it better still. **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [mermaid](/blog/tags/mermaid.md) * [mermaid-12](/blog/tags/mermaid-12.md) * [usecase-diagram](/blog/tags/usecase-diagram.md) * [how-to](/blog/tags/how-to.md) * [developer-tools](/blog/tags/developer-tools.md) [**Read more**](/blog/paste-mermaid-diagrams-into-confluence.md) --- ## [Dark Mode for Confluence Code Blocks — Setup Walkthrough](/blog/confluence-code-editor-syntax-highlighting.md) May 6, 2026 · 4 min read [NGPilot](https://ngpilot.com) Confluence's built-in code block macro is limited — it supports roughly 30 languages, has no dark theme, and lacks basic features like copy buttons and collapsible sections. If your team writes documentation with code snippets, you need something better. This guide shows how to add a VS Code-grade code editor to Confluence with syntax highlighting for 85+ languages, automatic dark/light theme detection, and one-click copy buttons. **Tags:** * [confluence](/blog/tags/confluence.md) * [code-blocks](/blog/tags/code-blocks.md) * [syntax-highlighting](/blog/tags/syntax-highlighting.md) * [dark-mode](/blog/tags/dark-mode.md) * [monaco-editor](/blog/tags/monaco-editor.md) * [developers](/blog/tags/developers.md) [**Read more**](/blog/confluence-code-editor-syntax-highlighting.md) --- ## [AI Code Review in Confluence: Document and Share Code Reviews](/blog/ai-code-review-confluence.md) July 30, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer AI can help document code reviews in Confluence by summarizing changes, organizing findings, and extracting action items. Create templates, use AI to populate them, and build a searchable review knowledge base. What you'll learn 1. How to create code review templates in Confluence 2. How to use AI to summarize code changes and PRs 3. How to document review findings with AI assistance 4. How to extract and track action items from reviews Code reviews happen in pull requests, but the decisions and context often get lost. When someone asks "why did we implement it this way?" the answer is buried in a closed PR with hundreds of comments. Documenting code reviews in Confluence preserves this context. AI can automate the documentation, turning unstructured PR discussions into organized knowledge. This guide covers how to use AI for code review documentation. **Tags:** * [confluence](/blog/tags/confluence.md) * [ai](/blog/tags/ai.md) * [code-review](/blog/tags/code-review.md) * [how-to](/blog/tags/how-to.md) * [development](/blog/tags/development.md) [**Read more**](/blog/ai-code-review-confluence.md) --- ## [CI/CD Pipeline Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-ci-cd-pipeline-diagram-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) A build fails at 4pm, and the fix's pipeline takes 40 minutes to re-run from the top because someone decided every stage needs to re-validate. That wasted hour is not a code problem — it is a **documentation** problem. Nobody could see the pipeline's shape, so nobody saw the retry loop and the gate that would have caught the failure three stages earlier. **Quick answer:** put the pipeline's shape in Confluence as a Mermaid `flowchart`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Text-based, editable, diffable — a pipeline diagram that changes when your pipeline changes. This post gives you three copy-paste examples: the linear stage view, quality gates with retry loops, and the deploy-to-tag gitGraph that records what actually shipped. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [ci-cd](/blog/tags/ci-cd.md) * [devops](/blog/tags/devops.md) * [flowchart](/blog/tags/flowchart.md) * [gitgraph](/blog/tags/gitgraph.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-ci-cd-pipeline-diagram-confluence.md) --- ## [Why Markdown Became the Documentation Format of the AI Era](/blog/markdown-ai-era-documentation-format.md) August 21, 2026 · 7 min read [NGPilot](https://ngpilot.com) In 2004, John Gruber released Markdown with a modest pitch: a text format that is easy to *read*, easy to *write*, and converts cleanly to HTML. Twenty years later his side project became the default language of technical documentation — GitHub renders it natively, Stack Overflow is built on it, Obsidian and Notion popularized it, and every major LLM speaks it fluently. The Verge called it "the default language of the AI era." That last part is the interesting one. Markdown didn't just survive the AI transition — it *locked in* because of it. This article walks through why, and what it means for how your team should write documentation inside Confluence. **Tags:** * [markdown](/blog/tags/markdown.md) * [ai](/blog/tags/ai.md) * [documentation](/blog/tags/documentation.md) * [confluence](/blog/tags/confluence.md) * [devtools](/blog/tags/devtools.md) [**Read more**](/blog/markdown-ai-era-documentation-format.md) --- ## [All 30 Mermaid Diagram Types in Confluence: Complete Reference](/blog/faq-mermaid-diagram-types-confluence.md) May 2, 2026 · 21 min read [NGPilot](https://ngpilot.com) Mermaid supports **30 diagram types** — from flowcharts and sequence diagrams to C4 architecture, swimlanes, Gantt charts, ER diagrams, git graphs, and more. With [Mermaid Plus Diagrams & AI Agent for Confluence](/apps/mermaid-plus-for-confluence.md), all 30 render from plain text inside a single macro. This page is the complete reference: every type, its keyword, its category, when to use it, and worked examples for the ones a software team reaches for most. What you'll find here * **[The full 30-type table](#all-30-mermaid-diagram-types-at-a-glance)** — every type, keyword, and category at a glance * **[When to use each type](#when-to-use-each-mermaid-diagram-type)** — flowchart vs sequence vs C4 vs ER vs state vs Gantt, with examples * **[The types a sprint team actually uses](#the-diagram-types-a-sprint-team-actually-uses)** — practical playbook for Jira and Confluence * **[Beta types explained](#frequently-asked-questions)** — sankey, packet, architecture, radar, swimlane, use case, and more If you are deciding which diagram type fits your use case, jump to [When to use each Mermaid diagram type](#when-to-use-each-mermaid-diagram-type). For the quick reference table, see below. For installation and the macro basics, see [Create Mermaid diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md). **Tags:** * [faq](/blog/tags/faq.md) * [mermaid](/blog/tags/mermaid.md) * [confluence](/blog/tags/confluence.md) * [diagram-types](/blog/tags/diagram-types.md) * [documentation](/blog/tags/documentation.md) * [developers](/blog/tags/developers.md) [**Read more**](/blog/faq-mermaid-diagram-types-confluence.md) --- ## [Excalidraw AI Agent for Confluence: Whiteboards You Can Talk To](/blog/excalidraw-ai-agent-confluence.md) October 10, 2026 · 7 min read [NGPilot](https://ngpilot.com) Confluence holds your team's diagrams in two worlds, and the two don't talk to each other. Text-defined diagrams — Mermaid and friends — are what AI speaks natively. They're source code, so a chat agent can read them, write them, and revise them. We shipped exactly that last week: [an AI agent for Mermaid in Confluence](/blog/mermaid-ai-agent-confluence.md). Whiteboards are the other world. Freeform shapes, hand-drawn lines, arrows you drag where they need to go — the format that's actually intuitive to put in front of people. Every team has one: the architecture board on the team page, the incident flow everyone references, the onboarding map. And AI couldn't touch any of it. Ask a chat agent for a change to a whiteboard and you'd get a text *description* of a change, and someone still had to open the canvas and do it by hand. That gap is why whiteboards go stale. Editing shapes one drag at a time is slow enough that nobody does it, and AI — the thing that was supposed to make maintenance cheap — had no way in. The AI agent in [Excalidraw Plus Whiteboards & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence) closes the gap: the whiteboard stays what it always was — visual, intuitive, for people — but now you can operate it in plain language, from Confluence chat. **Tags:** * [confluence](/blog/tags/confluence.md) * [excalidraw](/blog/tags/excalidraw.md) * [whiteboard](/blog/tags/whiteboard.md) * [diagrams](/blog/tags/diagrams.md) * [ai](/blog/tags/ai.md) * [agent](/blog/tags/agent.md) [**Read more**](/blog/excalidraw-ai-agent-confluence.md) --- ## [Free Diagram Apps for Confluence — Excalidraw & Free-Tier Limits](/blog/confluence-free-diagram-plugin.md) May 10, 2026 · 4 min read [NGPilot](https://ngpilot.com) Need diagram tools for Confluence without paying for a large team? NGPILOT's three diagramming apps — Mermaid Plus, Excalidraw Plus, and Graphviz Charts — are all **free for up to 10 users**. This guide compares them so you can pick the right free diagram plugin for your Confluence. **Tags:** * [confluence](/blog/tags/confluence.md) * [diagrams](/blog/tags/diagrams.md) * [free](/blog/tags/free.md) * [mermaid](/blog/tags/mermaid.md) * [excalidraw](/blog/tags/excalidraw.md) * [graphviz](/blog/tags/graphviz.md) * [comparison](/blog/tags/comparison.md) [**Read more**](/blog/confluence-free-diagram-plugin.md) --- ## [ER Diagrams in Confluence: How to Add, Create, and Render Database Schemas](/blog/how-to-create-er-diagrams-confluence.md) May 2, 2026 · 21 min read [NGPilot](https://ngpilot.com) An **ER diagram** (entity-relationship diagram) visualizes a database schema — the tables, columns, primary and foreign keys, and the relationships between them. If your team documents data models, API contracts, or system architecture in Confluence, embedding ER diagrams directly on the page keeps the schema next to the prose instead of stranded in an external tool as a stale screenshot. Confluence has no built-in ER diagram support, so you add it with a Marketplace app. The approach below uses **[Mermaid Plus Diagrams & AI Agent for Confluence](/apps/mermaid-plus-for-confluence.md)**, which renders ER diagrams from plain text — meaning diagrams version, diff, and search alongside the rest of your documentation. What you'll learn 1. How to add an ER diagram to any Confluence page 2. The full Mermaid `erDiagram` syntax — entities, attributes, key types, cardinality 3. Three copy-paste examples (library, e-commerce, SaaS multi-tenant) 4. Common mistakes and how to fix them Entity-Relationship (ER) diagrams are the standard way to visualize database schemas. They show the tables in your database, the columns in each table, primary and foreign key constraints, and the relationships between tables -- one-to-one, one-to-many, and many-to-many. Whether you are designing a new database from scratch, documenting an existing schema for onboarding, or collaborating on a data model before writing migration scripts, an ER diagram communicates structure faster than any amount of prose. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [er-diagram](/blog/tags/er-diagram.md) * [database](/blog/tags/database.md) * [how-to](/blog/tags/how-to.md) * [diagrams](/blog/tags/diagrams.md) [**Read more**](/blog/how-to-create-er-diagrams-confluence.md) --- ## [Mermaid App Roundup for Confluence — Mermaid Plus vs Stratus vs weweave](/blog/create-mermaid-diagrams-in-confluence.md) April 12, 2026 · 6 min read [NGPilot](https://ngpilot.com) Engineering teams need diagrams in Confluence — flowcharts for runbooks, sequence diagrams for API docs, ER models for database schemas, architecture diagrams for design decisions. Writing diagrams as code (text-based syntax) is faster than drag-and-drop for developers. Mermaid is the most popular text-based diagram language. Several marketplace apps bring Mermaid to Confluence, plus the major visual diagramming tools (draw\.io, Gliffy, Lucidchart) also support it. We built **Mermaid Plus Diagrams & AI Agent for Confluence** to offer 30 diagram types with live preview, one-click templates, and a built-in syntax guide. In this post we compare it against every alternative. **Tags:** * [mermaid](/blog/tags/mermaid.md) * [diagrams](/blog/tags/diagrams.md) * [confluence](/blog/tags/confluence.md) [**Read more**](/blog/create-mermaid-diagrams-in-confluence.md) --- ## [Document Your Codebase in Confluence with Mermaid Class Diagrams](/blog/mermaid-class-diagram-document-codebase-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) Your team grows by two people. The new hires open the wiki and find the architecture doc: a screenshot of a whiteboard, dated 14 months ago, where `PaymentService` does everything except the thing the diagram says `OrderService` does. Day-1 onboarding just taught two people the wrong architecture. **Quick answer:** keep the architecture in Confluence as a Mermaid `class diagram`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/) and diffs like code. Classes, methods, interfaces, ownership — in editable text that updates when the code does. This post gives you three copy-paste examples: the onboarding service map, interface+implementation modules, and a request-flow sketch. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [class-diagram](/blog/tags/class-diagram.md) * [architecture](/blog/tags/architecture.md) * [docs](/blog/tags/docs.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-class-diagram-document-codebase-confluence.md) --- ## [FAQ: EPUB Reader for Confluence — Everything You Need to Know](/blog/faq-epub-reader-confluence.md) May 2, 2026 · 14 min read [NGPilot](https://ngpilot.com) **Tags:** * [faq](/blog/tags/faq.md) * [confluence](/blog/tags/confluence.md) * [epub](/blog/tags/epub.md) * [document-viewer](/blog/tags/document-viewer.md) * [reading](/blog/tags/reading.md) [**Read more**](/blog/faq-epub-reader-confluence.md) --- ## [Why Markdown Became the Documentation Format of the AI Era](/blog/markdown-ai-era-documentation-format.md) August 21, 2026 · 7 min read [NGPilot](https://ngpilot.com) In 2004, John Gruber released Markdown with a modest pitch: a text format that is easy to *read*, easy to *write*, and converts cleanly to HTML. Twenty years later his side project became the default language of technical documentation — GitHub renders it natively, Stack Overflow is built on it, Obsidian and Notion popularized it, and every major LLM speaks it fluently. The Verge called it "the default language of the AI era." That last part is the interesting one. Markdown didn't just survive the AI transition — it *locked in* because of it. This article walks through why, and what it means for how your team should write documentation inside Confluence. **Tags:** * [markdown](/blog/tags/markdown.md) * [ai](/blog/tags/ai.md) * [documentation](/blog/tags/documentation.md) * [confluence](/blog/tags/confluence.md) * [devtools](/blog/tags/devtools.md) [**Read more**](/blog/markdown-ai-era-documentation-format.md) --- ## [Confluence Graphviz Diagrams: DOT Language FAQ & Examples](/blog/faq-graphviz-charts-confluence.md) May 2, 2026 · 16 min read [NGPilot](https://ngpilot.com) Graphviz has been the backbone of automated graph visualization for over three decades. Originally developed at AT\&T Labs, it powers dependency graphs in build systems, call graphs in profilers, and database schemas in ORMs -- anywhere that diagrams need to be generated from structured data rather than drawn by hand. Graphviz Charts for Confluence brings that same engine directly into your Confluence pages, letting you write DOT language descriptions and get polished, auto-laid-out diagrams without leaving your wiki. **Tags:** * [faq](/blog/tags/faq.md) * [confluence](/blog/tags/confluence.md) * [graphviz](/blog/tags/graphviz.md) * [dot](/blog/tags/dot.md) * [diagrams](/blog/tags/diagrams.md) * [charts](/blog/tags/charts.md) [**Read more**](/blog/faq-graphviz-charts-confluence.md) --- ## [draw.io vs Mermaid in Confluence: Which Fits Your Docs?](/blog/mermaid-vs-drawio-confluence.md) September 28, 2026 · 16 min read [NGPilot](https://ngpilot.com) Quick Answer draw\.io supports Mermaid now — so "does draw\.io do Mermaid?" is no longer the question. The question is **what the source becomes**. In [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), the Mermaid text stays the diagram: page history shows a text diff, an update is one line, and a Rovo agent can create, read, update or convert diagrams from chat. In draw\.io, Mermaid is an import step that turns the diagram into native draw\.io shapes, so you get full styling and shape-library freedom but the page holds shape data instead of reviewable text. On the AI side the difference is where the processing happens: Mermaid Plus runs on Atlassian Forge with Atlassian's own Rovo agent, so the diagram and the AI both stay inside the Atlassian trust boundary, covered by your existing Atlassian agreement. **Text-first docs → Mermaid Plus. Visual-first, icon-heavy or migration-heavy work → draw\.io.** What you'll learn 1. What changed when draw\.io added Mermaid support in 2026 2. Where the two tools genuinely differ, and where they do not 3. How the AI features compare — canvas generation vs a Rovo agent on the page 4. Where the diagram and the AI data live, and why that decides it for enterprise teams 5. A decision framework for Confluence and Jira teams Every Confluence team ends up choosing a diagram tool, and most start by asking the wrong question: does it support Mermaid? These days, two answers exist. [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/) is built around Mermaid — all 30 Mermaid v12 diagram types, a code editor with live preview, one-click templates for every type, and a Rovo AI agent that works on the page. draw\.io is the most-installed diagramming app on the Atlassian Marketplace, with deep shape libraries, whiteboarding, and a Mermaid importer added to its editor. Both are good tools. This guide compares how they behave in Confluence specifically — how a diagram is created, what is stored on the page, what happens when you need to change it six months later, and what it costs. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [drawio](/blog/tags/drawio.md) * [draw-io](/blog/tags/draw-io.md) * [comparison](/blog/tags/comparison.md) * [diagrams](/blog/tags/diagrams.md) [**Read more**](/blog/mermaid-vs-drawio-confluence.md) --- ## [Drawing vs Diagramming in Confluence — Canvas vs Text vs Graph](/blog/confluence-drawing-diagramming-tools.md) May 6, 2026 · 5 min read [NGPilot](https://ngpilot.com) Adding diagrams to Confluence pages helps teams communicate architecture, processes, and workflows visually. This guide covers the three main approaches to creating diagrams in Confluence and helps you choose the right tool for your needs. **Tags:** * [confluence](/blog/tags/confluence.md) * [diagrams](/blog/tags/diagrams.md) * [drawing](/blog/tags/drawing.md) * [mermaid](/blog/tags/mermaid.md) * [excalidraw](/blog/tags/excalidraw.md) * [graphviz](/blog/tags/graphviz.md) * [comparison](/blog/tags/comparison.md) [**Read more**](/blog/confluence-drawing-diagramming-tools.md) --- ## [draw.io vs Mermaid in Confluence: Which Fits Your Docs?](/blog/mermaid-vs-drawio-confluence.md) September 28, 2026 · 16 min read [NGPilot](https://ngpilot.com) Quick Answer draw\.io supports Mermaid now — so "does draw\.io do Mermaid?" is no longer the question. The question is **what the source becomes**. In [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/), the Mermaid text stays the diagram: page history shows a text diff, an update is one line, and a Rovo agent can create, read, update or convert diagrams from chat. In draw\.io, Mermaid is an import step that turns the diagram into native draw\.io shapes, so you get full styling and shape-library freedom but the page holds shape data instead of reviewable text. On the AI side the difference is where the processing happens: Mermaid Plus runs on Atlassian Forge with Atlassian's own Rovo agent, so the diagram and the AI both stay inside the Atlassian trust boundary, covered by your existing Atlassian agreement. **Text-first docs → Mermaid Plus. Visual-first, icon-heavy or migration-heavy work → draw\.io.** What you'll learn 1. What changed when draw\.io added Mermaid support in 2026 2. Where the two tools genuinely differ, and where they do not 3. How the AI features compare — canvas generation vs a Rovo agent on the page 4. Where the diagram and the AI data live, and why that decides it for enterprise teams 5. A decision framework for Confluence and Jira teams Every Confluence team ends up choosing a diagram tool, and most start by asking the wrong question: does it support Mermaid? These days, two answers exist. [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/) is built around Mermaid — all 30 Mermaid v12 diagram types, a code editor with live preview, one-click templates for every type, and a Rovo AI agent that works on the page. draw\.io is the most-installed diagramming app on the Atlassian Marketplace, with deep shape libraries, whiteboarding, and a Mermaid importer added to its editor. Both are good tools. This guide compares how they behave in Confluence specifically — how a diagram is created, what is stored on the page, what happens when you need to change it six months later, and what it costs. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [drawio](/blog/tags/drawio.md) * [draw-io](/blog/tags/draw-io.md) * [comparison](/blog/tags/comparison.md) * [diagrams](/blog/tags/diagrams.md) [**Read more**](/blog/mermaid-vs-drawio-confluence.md) --- ## [How to Create Math and Technical Animations in Confluence Using Manim](/blog/how-to-create-math-animations-confluence.md) May 2, 2026 · 23 min read [NGPilot](https://ngpilot.com) Mathematical concepts are inherently dynamic. A limit converges, a derivative emerges from shrinking secant lines, a matrix transformation rotates a vector through space. Static screenshots and LaTeX formulas capture the result but miss the process -- and for many students and colleagues, the process is where understanding lives. Animations bridge that gap. They show how equations transform, how geometric constructions unfold step by step, and how abstract algebra connects to visual intuition. Until recently, embedding math animations in documentation required a multi-tool workflow: write Python scripts with Manim, render MP4 files locally, upload them as attachments or embed them via external hosting, and hope nobody asked you to update them. Manim for Confluence eliminates that entire pipeline. You write animation code directly inside a Confluence macro, and the animation plays inline on the published page -- no file exports, no external hosting, no broken links when the video expires. **Tags:** * [confluence](/blog/tags/confluence.md) * [manim](/blog/tags/manim.md) * [animation](/blog/tags/animation.md) * [math](/blog/tags/math.md) * [how-to](/blog/tags/how-to.md) * [education](/blog/tags/education.md) [**Read more**](/blog/how-to-create-math-animations-confluence.md) --- ## [Math Equations in Confluence: LaTeX & KaTeX via Markdown](/blog/markdown-math-equations-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) Ask an engineer to document an algorithm in Confluence and watch what happens to the math: `O(n log n)` typed as plain text, `x²` pasted from a character map, and — for anything real — a screenshot from an online equation editor, blurry and already out of date. Confluence has no native LaTeX support, so every formula becomes either a compromise or an image. It does not have to. With a Markdown macro on the page, Confluence renders real LaTeX — inline `$...$`, display `$$...$$`, fenced blocks with full `align` environments — and the equation stays text: searchable, theme-consistent, editable in seconds. This guide gives you the syntax and copy-paste examples for all three routes. **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [latex](/blog/tags/latex.md) * [katex](/blog/tags/katex.md) * [mathjax](/blog/tags/mathjax.md) * [math](/blog/tags/math.md) * [how-to](/blog/tags/how-to.md) * [engineering](/blog/tags/engineering.md) [**Read more**](/blog/markdown-math-equations-confluence.md) --- ## [Monospace in Confluence: How to Format Inline Code (Shortcuts & Markdown)](/blog/confluence-monospace.md) October 1, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Select the text and press **Ctrl+Shift+M** (Windows) or **Opt+Shift+M** (Mac) to apply inline code, or type `` `backticks` `` around text as you write — the Confluence Cloud editor autoformats them. Pasted Markdown keeps its backticks as literal characters, so paste into [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence/) instead, which renders inline code, code blocks, and diagrams from your Markdown source. Inline code — monospace text on a subtle background — is how you mark up variable names, file paths, key names, and short commands inside a sentence: set `MAX_RETRIES = 3`, edit `~/.zshrc`, or run `kubectl get pods`. Confluence Cloud has three ways to produce it, and each fits a different moment: formatting as you go, typing Markdown, or bringing Markdown in from your repo. What you'll learn 1. The keyboard shortcut — Ctrl+Shift+M, and the Mac split between Opt+Shift+M and Cmd+Shift+M 2. Backtick autoformatting while you type 3. The Markdown method for pasted content (Enhanced Markdown) 4. Inline code vs code block — which one to use where **Tags:** * [confluence](/blog/tags/confluence.md) * [formatting](/blog/tags/formatting.md) * [markdown](/blog/tags/markdown.md) * [monospace](/blog/tags/monospace.md) * [inline-code](/blog/tags/inline-code.md) * [enhanced-markdown](/blog/tags/enhanced-markdown.md) * [keyboard-shortcuts](/blog/tags/keyboard-shortcuts.md) [**Read more**](/blog/confluence-monospace.md) --- ## [Atlassian Marketplace App Selection Criteria for Enterprise](/blog/marketplace-app-selection-criteria-enterprise.md) August 2, 2026 · 7 min read [NGPilot](https://ngpilot.com) Quick Answer Enterprise teams evaluating Atlassian Marketplace apps should check ten criteria: Cloud Fortified status, Forge vs Connect framework, OAuth scopes, privacy disclosure, Bug Bounty participation, data residency, vendor viability, support SLA, adoption signals, and release cadence. This guide walks through each so your security and procurement teams can make confident decisions. What you'll learn 1. The 10 criteria every enterprise should check before approving an app 2. How to assess vendor viability and long-term risk 3. What documentation to request from vendors during procurement 4. A scoring rubric you can apply to any app in under 10 minutes Installing a Marketplace app in an enterprise Atlassian environment is not the same as installing a browser extension. The app gains access to your Jira issues, Confluence pages, and potentially your entire collaboration surface — so the evaluation process needs to be rigorous. This guide covers the ten criteria that security, procurement, and IT teams should check before approving any app for enterprise deployment. **Tags:** * [atlassian](/blog/tags/atlassian.md) * [marketplace](/blog/tags/marketplace.md) * [enterprise](/blog/tags/enterprise.md) * [security](/blog/tags/security.md) * [procurement](/blog/tags/procurement.md) * [explained](/blog/tags/explained.md) [**Read more**](/blog/marketplace-app-selection-criteria-enterprise.md) --- ## [FAQ: EPUB Reader for Confluence — Everything You Need to Know](/blog/faq-epub-reader-confluence.md) May 2, 2026 · 14 min read [NGPilot](https://ngpilot.com) **Tags:** * [faq](/blog/tags/faq.md) * [confluence](/blog/tags/confluence.md) * [epub](/blog/tags/epub.md) * [document-viewer](/blog/tags/document-viewer.md) * [reading](/blog/tags/reading.md) [**Read more**](/blog/faq-epub-reader-confluence.md) --- ## [Database Schema Diagrams in Confluence with Mermaid ER (Entity Relationship) — Copy-Paste](/blog/mermaid-er-diagram-database-schema-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The bug report says "orders show twice in the report" and the fix takes three days because nobody on the team is sure whether `order_lines` links to `orders` on `order_id` or `source_order_id`, and both columns exist. The schema is documented — in a `schema.md` that lists columns as bullets and a diagram that was last exported when the DB was two migrations younger. The join question is exactly the thing an ER diagram answers at a glance, and the thing a bulleted column list cannot answer at all. **Quick answer:** document the database schema in Confluence as a Mermaid `erDiagram`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Entities hold keys and attributes; relationship lines carry the cardinality and the join's noun. When the discussion turns to the domain model the code exposes, add a `classDiagram` on the same page. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [er-diagram](/blog/tags/er-diagram.md) * [database](/blog/tags/database.md) * [schema](/blog/tags/schema.md) * [class-diagram](/blog/tags/class-diagram.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-er-diagram-database-schema-confluence.md) --- ## [Excalidraw AI Agent for Confluence: Whiteboards You Can Talk To](/blog/excalidraw-ai-agent-confluence.md) October 10, 2026 · 7 min read [NGPilot](https://ngpilot.com) Confluence holds your team's diagrams in two worlds, and the two don't talk to each other. Text-defined diagrams — Mermaid and friends — are what AI speaks natively. They're source code, so a chat agent can read them, write them, and revise them. We shipped exactly that last week: [an AI agent for Mermaid in Confluence](/blog/mermaid-ai-agent-confluence.md). Whiteboards are the other world. Freeform shapes, hand-drawn lines, arrows you drag where they need to go — the format that's actually intuitive to put in front of people. Every team has one: the architecture board on the team page, the incident flow everyone references, the onboarding map. And AI couldn't touch any of it. Ask a chat agent for a change to a whiteboard and you'd get a text *description* of a change, and someone still had to open the canvas and do it by hand. That gap is why whiteboards go stale. Editing shapes one drag at a time is slow enough that nobody does it, and AI — the thing that was supposed to make maintenance cheap — had no way in. The AI agent in [Excalidraw Plus Whiteboards & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence) closes the gap: the whiteboard stays what it always was — visual, intuitive, for people — but now you can operate it in plain language, from Confluence chat. **Tags:** * [confluence](/blog/tags/confluence.md) * [excalidraw](/blog/tags/excalidraw.md) * [whiteboard](/blog/tags/whiteboard.md) * [diagrams](/blog/tags/diagrams.md) * [ai](/blog/tags/ai.md) * [agent](/blog/tags/agent.md) [**Read more**](/blog/excalidraw-ai-agent-confluence.md) --- ## [Best Diagram Tool for Confluence — Mermaid vs Excalidraw vs Graphviz](/blog/confluence-diagram-tools-comparison.md) April 24, 2026 · 9 min read [NGPilot](https://ngpilot.com) Looking for the best **diagram tool for Confluence**? Confluence has no built-in diagramming, so every team adds a Marketplace app — but the right choice depends entirely on *what* you draw and *how* you prefer to work. This guide compares the three strongest options — [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?hosting=cloud\&tab=overview), [Excalidraw Plus Whiteboards & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence?hosting=cloud\&tab=overview), and [Graphviz Charts for Confluence](https://marketplace.atlassian.com/apps/1237380/graphviz-charts-for-confluence?hosting=cloud\&tab=overview) — so you can pick the diagram tool that fits your team instead of guessing. Quick answer For most Confluence teams, **Mermaid Plus** is the best diagram tool — it covers the widest range (30 diagram types), is the easiest to learn, and renders text into diagrams that version cleanly with your docs. Pick **Excalidraw Plus** if you need freehand whiteboarding and wireframes. Pick **Graphviz Charts** for dense network and dependency graphs. Many teams install more than one. What you'll learn 1. Which diagram tool fits each type of Confluence team 2. The strengths and trade-offs of Mermaid, Excalidraw, and Graphviz 3. Pricing, hosting, and integration differences 4. A decision framework so you can choose in under a minute **Tags:** * [confluence](/blog/tags/confluence.md) * [diagrams](/blog/tags/diagrams.md) * [mermaid](/blog/tags/mermaid.md) * [excalidraw](/blog/tags/excalidraw.md) * [graphviz](/blog/tags/graphviz.md) * [comparison](/blog/tags/comparison.md) * [excalidraw-vs-mermaid](/blog/tags/excalidraw-vs-mermaid.md) [**Read more**](/blog/confluence-diagram-tools-comparison.md) --- ## [How to Add Excalidraw Whiteboards to Jira Issues (Setup Guide)](/blog/excalidraw-whiteboards-jira.md) April 21, 2026 · One min read [NGPilot](https://ngpilot.com) Excalidraw-powered whiteboards let teams sketch ideas directly inside Jira issues. This quick guide covers creating boards, saving snapshots, and sharing with team members. **Tags:** * [jira](/blog/tags/jira.md) * [excalidraw](/blog/tags/excalidraw.md) * [whiteboard](/blog/tags/whiteboard.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/excalidraw-whiteboards-jira.md) --- ## [Jira Export Limit: How to Export More Than 1,000 Issues (2026)](/blog/jira-export-limit.md) September 2, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Jira Cloud's native export stops at 1,000 issues per export and only includes columns visible in the issue navigator. To export more: split your filter into JQL batches, use the REST API, or install [Simple Bulk Issues Excel CSV Export](https://marketplace.atlassian.com/apps/3818473739/simple-bulk-issues-excel-csv-export-for-jira?utm_source=ngpilot.com\&utm_medium=blog), which exports up to 5,000 issues per run in CSV, XLS, or XLSX — and tells you plainly when a result set was truncated. If you have ever exported a project for reporting, an audit, or a migration, you have probably run into Jira Cloud's export limit without being warned first: the export finishes, the file looks complete, and the row count quietly stops at 1,000. This article explains where that limit comes from, then compares the three practical ways to export larger issue sets in 2026. **Tags:** * [jira](/blog/tags/jira.md) * [export](/blog/tags/export.md) * [excel](/blog/tags/excel.md) * [csv](/blog/tags/csv.md) * [jira-cloud](/blog/tags/jira-cloud.md) * [reporting](/blog/tags/reporting.md) [**Read more**](/blog/jira-export-limit.md) --- ## [Expand Macro for Confluence: Collapsible Sections Compared (Native vs Styled)](/blog/confluence-expand-macro.md) August 21, 2026 · 5 min read [NGPilot](https://ngpilot.com) Long pages die from scroll fatigue. Onboarding checklists, troubleshooting trees, API reference details, legal disclaimers — content that only some readers need some of the time is the canonical use case for collapsible sections. Confluence ships a native **expand macro** for exactly this, and for many pages it's enough. This guide covers how the native expand works, where teams typically outgrow it, and what a styled accordion macro adds — so you can pick per page, not per vendor. **Tags:** * [confluence](/blog/tags/confluence.md) * [macros](/blog/tags/macros.md) * [expand](/blog/tags/expand.md) * [accordion](/blog/tags/accordion.md) * [formatting](/blog/tags/formatting.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/confluence-expand-macro.md) --- ## [Forge vs Connect: What Atlassian Admins Need to Know in 2026](/blog/forge-vs-connect-atlassian-admins-2026.md) August 2, 2026 · 10 min read [NGPilot](https://ngpilot.com) Quick Answer Forge and Connect are the two frameworks Atlassian Marketplace apps can be built on. **Forge** runs on Atlassian's own infrastructure; **Connect** runs on vendor-hosted servers. Starting January 1, 2026, Atlassian applies a penalty to Connect apps in Marketplace rankings and requires Forge for new Cloud Fortified status. For admins evaluating apps in 2026, Forge is the safer, more future-proof choice where a capable option exists. What you'll learn 1. The real architectural difference between Forge and Connect 2. What the 2026 Connect penalty changes for app discovery and trust 3. How to tell which framework an app uses before you install it 4. A practical decision framework for evaluating apps in 2026 If you administer Jira or Confluence Cloud, every app you install from the Marketplace runs on one of two frameworks: **Forge** or **Connect**. For years the difference was mostly an implementation detail that admins could ignore. In 2026 that changed. The Connect penalty, the Cloud Fortified requirement, and Atlassian's clear strategic direction mean the framework an app uses now affects its security posture, its discoverability, and how long it will keep working. This guide explains what changed, why it matters, and how to make better app decisions because of it. **Tags:** * [atlassian](/blog/tags/atlassian.md) * [forge](/blog/tags/forge.md) * [connect](/blog/tags/connect.md) * [marketplace](/blog/tags/marketplace.md) * [explained](/blog/tags/explained.md) * [admin](/blog/tags/admin.md) [**Read more**](/blog/forge-vs-connect-atlassian-admins-2026.md) --- ## [Jira Export Limit: How to Export More Than 1,000 Issues (2026)](/blog/jira-export-limit.md) September 2, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Jira Cloud's native export stops at 1,000 issues per export and only includes columns visible in the issue navigator. To export more: split your filter into JQL batches, use the REST API, or install [Simple Bulk Issues Excel CSV Export](https://marketplace.atlassian.com/apps/3818473739/simple-bulk-issues-excel-csv-export-for-jira?utm_source=ngpilot.com\&utm_medium=blog), which exports up to 5,000 issues per run in CSV, XLS, or XLSX — and tells you plainly when a result set was truncated. If you have ever exported a project for reporting, an audit, or a migration, you have probably run into Jira Cloud's export limit without being warned first: the export finishes, the file looks complete, and the row count quietly stops at 1,000. This article explains where that limit comes from, then compares the three practical ways to export larger issue sets in 2026. **Tags:** * [jira](/blog/tags/jira.md) * [export](/blog/tags/export.md) * [excel](/blog/tags/excel.md) * [csv](/blog/tags/csv.md) * [jira-cloud](/blog/tags/jira-cloud.md) * [reporting](/blog/tags/reporting.md) [**Read more**](/blog/jira-export-limit.md) --- ## [Manual Toggles vs Modern FAQ for Confluence — 3 Methods Compared](/blog/how-to-create-faq-pages-confluence.md) May 23, 2026 · 9 min read [NGPilot](https://ngpilot.com) FAQ pages are one of the most visited sections of any documentation site. In Confluence, they serve a specific purpose: giving your team or customers quick answers to the questions they ask most often, without making them read through pages of documentation. A well-structured FAQ page reduces repetitive questions in Slack channels, shortens onboarding time for new team members, and deflects support tickets before they are created. But Confluence does not have a built-in FAQ feature. Teams typically resort to manual workarounds — tables, toggle macros, or expand sections — that look cluttered and are hard to maintain. This guide shows you three methods to create professional FAQ pages in Confluence, from a quick manual setup to a fully featured FAQ macro. **Tags:** * [confluence](/blog/tags/confluence.md) * [faq](/blog/tags/faq.md) * [how-to](/blog/tags/how-to.md) * [knowledge-base](/blog/tags/knowledge-base.md) * [accordion](/blog/tags/accordion.md) * [questions](/blog/tags/questions.md) [**Read more**](/blog/how-to-create-faq-pages-confluence.md) --- ## [Confluence Custom Fonts FAQ: Change Fonts, Setup & Alternatives](/blog/faq-google-fonts-confluence-alternatives.md) May 2, 2026 · 15 min read [NGPilot](https://ngpilot.com) **Tags:** * [faq](/blog/tags/faq.md) * [google-fonts](/blog/tags/google-fonts.md) * [confluence](/blog/tags/confluence.md) * [typography](/blog/tags/typography.md) * [fonts](/blog/tags/fonts.md) [**Read more**](/blog/faq-google-fonts-confluence-alternatives.md) --- ## [Excalidraw for Confluence & Jira: FAQ, Tips & Best Practices](/blog/faq-excalidraw-best-practices.md) April 21, 2026 · 11 min read [NGPilot](https://ngpilot.com) **Tags:** * [faq](/blog/tags/faq.md) * [excalidraw](/blog/tags/excalidraw.md) * [confluence](/blog/tags/confluence.md) * [jira](/blog/tags/jira.md) * [diagrams](/blog/tags/diagrams.md) [**Read more**](/blog/faq-excalidraw-best-practices.md) --- ## [What Is Atlassian Government Cloud (AGC)? NGPILOT Apps Available (2026)](/blog/what-is-atlassian-government-cloud.md) July 30, 2026 · 3 min read [NGPilot](https://ngpilot.com) Quick Answer Atlassian Government Cloud (AGC) is a FedRAMP-authorized deployment of Confluence and Jira designed for U.S. government agencies and contractors. It meets FedRAMP Moderate baseline requirements for handling sensitive government data. NGPILOT has apps available on AGC for teams needing compliant diagramming and content tools. **Tags:** * [atlassian](/blog/tags/atlassian.md) * [government-cloud](/blog/tags/government-cloud.md) * [agc](/blog/tags/agc.md) * [fedramp](/blog/tags/fedramp.md) * [compliance](/blog/tags/compliance.md) * [confluence](/blog/tags/confluence.md) * [jira](/blog/tags/jira.md) [**Read more**](/blog/what-is-atlassian-government-cloud.md) --- ## [Root Cause Analysis in Confluence with Mermaid Fishbone + 5 Whys](/blog/mermaid-fishbone-root-cause-analysis-confluence.md) September 24, 2026 · 7 min read [NGPilot](https://ngpilot.com) A root cause analysis is only as good as the disagreement it survives. When the 'root cause' box on your postmortem template contains one sentence, the meeting spends an hour relitigating that sentence. A fishbone diagram and a 5 Whys chain move the argument onto a diagram: everyone sees which categories were considered, which branch was chosen, and exactly how the 'why' answers arrive at a root cause. Confluence is where RCA already happens — in the Root Cause Analysis template, in postmortems, in retros. The missing piece is a diagram that holds the reasoning. This guide shows you two copy-paste Mermaid diagrams: an `ishikawa` fishbone that maps every candidate cause category, and a `flowchart` 5-Whys drilldown that lands on one concrete fix. **Tags:** * [root-cause-analysis](/blog/tags/root-cause-analysis.md) * [fishbone](/blog/tags/fishbone.md) * [ishikawa](/blog/tags/ishikawa.md) * [5-whys](/blog/tags/5-whys.md) * [mermaid](/blog/tags/mermaid.md) * [confluence](/blog/tags/confluence.md) * [postmortem](/blog/tags/postmortem.md) * [how-to](/blog/tags/how-to.md) * [incident-management](/blog/tags/incident-management.md) [**Read more**](/blog/mermaid-fishbone-root-cause-analysis-confluence.md) --- ## [Swimlane Process Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-process-flow-swimlane-diagram-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The ticket sits in "Waiting on customer" for a week and nobody noticed, because the handoff between first-line support and the dev team is a *tacit* step: Support marks it "escalated" in one field, Engineering is supposed to watch a filter, and the transfer never surfaces as its own action. That inert weekend is a process bug, and the fix is to see the handoff. A swimlane diagram makes the ownership transfer its own crossing arrow — invisible to everyone until it is drawn. **Quick answer:** map cross-functional processes in Confluence as Mermaid `swimlane-beta`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). One lane per actor, steps sequenced inside lanes, and the handoff is the arrow that crosses a lane boundary. When the interaction is a short request/response instead of long-running work, switch to a `sequenceDiagram`. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [swimlane](/blog/tags/swimlane.md) * [process](/blog/tags/process.md) * [flow](/blog/tags/flow.md) * [sequence-diagram](/blog/tags/sequence-diagram.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-process-flow-swimlane-diagram-confluence.md) --- ## [CI/CD Pipeline Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-ci-cd-pipeline-diagram-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) A build fails at 4pm, and the fix's pipeline takes 40 minutes to re-run from the top because someone decided every stage needs to re-validate. That wasted hour is not a code problem — it is a **documentation** problem. Nobody could see the pipeline's shape, so nobody saw the retry loop and the gate that would have caught the failure three stages earlier. **Quick answer:** put the pipeline's shape in Confluence as a Mermaid `flowchart`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Text-based, editable, diffable — a pipeline diagram that changes when your pipeline changes. This post gives you three copy-paste examples: the linear stage view, quality gates with retry loops, and the deploy-to-tag gitGraph that records what actually shipped. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [ci-cd](/blog/tags/ci-cd.md) * [devops](/blog/tags/devops.md) * [flowchart](/blog/tags/flowchart.md) * [gitgraph](/blog/tags/gitgraph.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-ci-cd-pipeline-diagram-confluence.md) --- ## [Does Confluence Support Mermaid? Setup Guide & Diagram Types](/blog/does-confluence-support-mermaid.md) May 6, 2026 · 4 min read [NGPilot](https://ngpilot.com) No, Confluence does not support Mermaid diagrams natively. There is no built-in macro or feature that renders Mermaid syntax in Confluence pages. To add Mermaid diagrams to Confluence, you need a Marketplace app. This guide covers how to set up Mermaid in Confluence and which diagram types you can create. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [diagrams](/blog/tags/diagrams.md) * [flowcharts](/blog/tags/flowcharts.md) * [sequence-diagram](/blog/tags/sequence-diagram.md) * [gantt](/blog/tags/gantt.md) * [mindmap](/blog/tags/mindmap.md) [**Read more**](/blog/does-confluence-support-mermaid.md) --- ## [Can You Change the Font in Confluence? (Default Stack & Custom Font Options)](/blog/confluence-default-font-change-font.md) May 10, 2026 · 3 min read [NGPilot](https://ngpilot.com) Confluence uses a system font stack that looks different on every operating system. You can't change the default font globally, and Confluence offers no built-in way to use custom fonts on individual pages. This guide shows what font Confluence uses and how to add custom fonts. **Tags:** * [confluence](/blog/tags/confluence.md) * [fonts](/blog/tags/fonts.md) * [google-fonts](/blog/tags/google-fonts.md) * [typography](/blog/tags/typography.md) * [customization](/blog/tags/customization.md) [**Read more**](/blog/confluence-default-font-change-font.md) --- ## [Forge vs Connect: What Atlassian Admins Need to Know in 2026](/blog/forge-vs-connect-atlassian-admins-2026.md) August 2, 2026 · 10 min read [NGPilot](https://ngpilot.com) Quick Answer Forge and Connect are the two frameworks Atlassian Marketplace apps can be built on. **Forge** runs on Atlassian's own infrastructure; **Connect** runs on vendor-hosted servers. Starting January 1, 2026, Atlassian applies a penalty to Connect apps in Marketplace rankings and requires Forge for new Cloud Fortified status. For admins evaluating apps in 2026, Forge is the safer, more future-proof choice where a capable option exists. What you'll learn 1. The real architectural difference between Forge and Connect 2. What the 2026 Connect penalty changes for app discovery and trust 3. How to tell which framework an app uses before you install it 4. A practical decision framework for evaluating apps in 2026 If you administer Jira or Confluence Cloud, every app you install from the Marketplace runs on one of two frameworks: **Forge** or **Connect**. For years the difference was mostly an implementation detail that admins could ignore. In 2026 that changed. The Connect penalty, the Cloud Fortified requirement, and Atlassian's clear strategic direction mean the framework an app uses now affects its security posture, its discoverability, and how long it will keep working. This guide explains what changed, why it matters, and how to make better app decisions because of it. **Tags:** * [atlassian](/blog/tags/atlassian.md) * [forge](/blog/tags/forge.md) * [connect](/blog/tags/connect.md) * [marketplace](/blog/tags/marketplace.md) * [explained](/blog/tags/explained.md) * [admin](/blog/tags/admin.md) [**Read more**](/blog/forge-vs-connect-atlassian-admins-2026.md) --- ## [Confluence Pagination: How to Paginate Pages and Tables (3 Methods)](/blog/confluence-pagination.md) October 4, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Confluence Cloud has no built-in pagination — pages render as one long scroll and tables render every row. The three working approaches: **split long content into a page series** and connect the parts with Previous/Next buttons ([Pagination Buttons for Confluence](https://marketplace.atlassian.com/apps/1237371/pagination-buttons-for-confluence/)), **chunk in-page** with tabs or expand sections, or **restructure** so the long table becomes linked category pages. What Confluence does paginate natively is search results and API responses — not your content. A 4,000-word runbook. A 300-row release checklist. A training doc with five chapters. Sooner or later every Confluence space hits the wall: the page that takes forever to scroll, buries the section the reader needs, and times out in the editor when someone tries to reorganize it. Pagination is the standard fix everywhere else on the web — and Confluence doesn't have it, a gap the community has flagged since 2018. Here's what actually works instead. What you'll learn 1. What Confluence paginates natively (search, API) and what it doesn't (pages, tables) 2. Method 1 — split into a page series with Prev/Next buttons 3. Method 2 — chunk in-page with tabs and expand sections 4. Method 3 — restructure long tables instead of paginating them **Tags:** * [confluence](/blog/tags/confluence.md) * [pagination](/blog/tags/pagination.md) * [macros](/blog/tags/macros.md) * [formatting](/blog/tags/formatting.md) * [page-structure](/blog/tags/page-structure.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/confluence-pagination.md) --- ## [Free Diagram Apps for Confluence — Excalidraw & Free-Tier Limits](/blog/confluence-free-diagram-plugin.md) May 10, 2026 · 4 min read [NGPilot](https://ngpilot.com) Need diagram tools for Confluence without paying for a large team? NGPILOT's three diagramming apps — Mermaid Plus, Excalidraw Plus, and Graphviz Charts — are all **free for up to 10 users**. This guide compares them so you can pick the right free diagram plugin for your Confluence. **Tags:** * [confluence](/blog/tags/confluence.md) * [diagrams](/blog/tags/diagrams.md) * [free](/blog/tags/free.md) * [mermaid](/blog/tags/mermaid.md) * [excalidraw](/blog/tags/excalidraw.md) * [graphviz](/blog/tags/graphviz.md) * [comparison](/blog/tags/comparison.md) [**Read more**](/blog/confluence-free-diagram-plugin.md) --- ## [Roadmap & Prioritization Charts in Confluence with Mermaid](/blog/mermaid-roadmap-prioritization-charts-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The quarter plan is a spreadsheet with thirty rows, color-coded by priority, sorted by a column half the team doesn't trust. The kickoff asks "what are we doing when — and why this first?" and the answer requires parsing three tabs. Planning outputs are *shapes*: schedules stack as bars, priorities sit on a 2x2, flows bundle as ribbons. The spreadsheet stores them poorly; Mermaid draws them as text. **Quick answer:** put the quarter plan in Confluence as Mermaid — `gantt` for when things happen, `quadrantChart` for which gets built first, `sankey-beta` for where the budget goes — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Three charts, three planning questions, one editable page. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [gantt](/blog/tags/gantt.md) * [quadrant](/blog/tags/quadrant.md) * [sankey](/blog/tags/sankey.md) * [roadmap](/blog/tags/roadmap.md) * [planning](/blog/tags/planning.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-roadmap-prioritization-charts-confluence.md) --- ## [Visualize Git Branches & Releases Inside Jira with Mermaid GitGraph](/blog/mermaid-gitgraph-jira-branch-history.md) September 24, 2026 · 7 min read [NGPilot](https://ngpilot.com) Your team is mid-debug on a prod incident. A senior engineer asks *"which release shipped this commit, and why is it on the release branch when the PR said main?"* — and nobody can answer without switching between Jira, the git web UI, and a Slack thread. That context — commit history, branches, merge points, release versions — belongs *next to the issue*, not in a tool people have to leave Jira to open. **Quick answer:** paste a Mermaid `gitGraph` into the issue's [Mermaid Plus Diagrams for Jira](https://marketplace.atlassian.com/apps/2658777397/mermaid-plus-diagrams-for-jira/) panel and the branch history renders as a diagram right on the ticket — commits, branches, merges, and release tags, all in one editable text block. This post gives you three copy-paste examples: a trunk-based feature workflow, a hotfix outside the release window, and a branch-rule flowchart to keep behavior consistent. **Tags:** * [jira](/blog/tags/jira.md) * [git](/blog/tags/git.md) * [gitgraph](/blog/tags/gitgraph.md) * [mermaid](/blog/tags/mermaid.md) * [branching](/blog/tags/branching.md) * [release](/blog/tags/release.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-gitgraph-jira-branch-history.md) --- ## [CI/CD Pipeline Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-ci-cd-pipeline-diagram-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) A build fails at 4pm, and the fix's pipeline takes 40 minutes to re-run from the top because someone decided every stage needs to re-validate. That wasted hour is not a code problem — it is a **documentation** problem. Nobody could see the pipeline's shape, so nobody saw the retry loop and the gate that would have caught the failure three stages earlier. **Quick answer:** put the pipeline's shape in Confluence as a Mermaid `flowchart`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Text-based, editable, diffable — a pipeline diagram that changes when your pipeline changes. This post gives you three copy-paste examples: the linear stage view, quality gates with retry loops, and the deploy-to-tag gitGraph that records what actually shipped. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [ci-cd](/blog/tags/ci-cd.md) * [devops](/blog/tags/devops.md) * [flowchart](/blog/tags/flowchart.md) * [gitgraph](/blog/tags/gitgraph.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-ci-cd-pipeline-diagram-confluence.md) --- ## [Import Markdown into Confluence: Paste, GitHub, .md Files](/blog/import-markdown-into-confluence.md) September 24, 2026 · 3 min read [NGPilot](https://ngpilot.com) Every team has Markdown lying around that Confluence needs: the README that became the service doc, the design doc drafted as a pull-request description, the runbook that lives in the repo. And every attempt to move it hits the same wall — Confluence's default editor does not parse Markdown. Paste a .md document and you get a wall of pipes, backticks, and asterisks that looks exactly like what it is: text nobody formatted. The macro route dissolves the wall. Paste the document into a Markdown macro that actually parses it, watch it render in the preview pane, publish. This page is the workflow, end to end. **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [import](/blog/tags/import.md) * [migration](/blog/tags/migration.md) * [github](/blog/tags/github.md) * [how-to](/blog/tags/how-to.md) * [developer-tools](/blog/tags/developer-tools.md) [**Read more**](/blog/import-markdown-into-confluence.md) --- ## [Can You Change the Font in Confluence? (Default Stack & Custom Font Options)](/blog/confluence-default-font-change-font.md) May 10, 2026 · 3 min read [NGPilot](https://ngpilot.com) Confluence uses a system font stack that looks different on every operating system. You can't change the default font globally, and Confluence offers no built-in way to use custom fonts on individual pages. This guide shows what font Confluence uses and how to add custom fonts. **Tags:** * [confluence](/blog/tags/confluence.md) * [fonts](/blog/tags/fonts.md) * [google-fonts](/blog/tags/google-fonts.md) * [typography](/blog/tags/typography.md) * [customization](/blog/tags/customization.md) [**Read more**](/blog/confluence-default-font-change-font.md) --- ## [What Is Atlassian Government Cloud (AGC)? NGPILOT Apps Available (2026)](/blog/what-is-atlassian-government-cloud.md) July 30, 2026 · 3 min read [NGPilot](https://ngpilot.com) Quick Answer Atlassian Government Cloud (AGC) is a FedRAMP-authorized deployment of Confluence and Jira designed for U.S. government agencies and contractors. It meets FedRAMP Moderate baseline requirements for handling sensitive government data. NGPILOT has apps available on AGC for teams needing compliant diagramming and content tools. **Tags:** * [atlassian](/blog/tags/atlassian.md) * [government-cloud](/blog/tags/government-cloud.md) * [agc](/blog/tags/agc.md) * [fedramp](/blog/tags/fedramp.md) * [compliance](/blog/tags/compliance.md) * [confluence](/blog/tags/confluence.md) * [jira](/blog/tags/jira.md) [**Read more**](/blog/what-is-atlassian-government-cloud.md) --- ## [Mermaid vs PlantUML vs Graphviz for Confluence: Which Diagram Tool to Choose](/blog/mermaid-vs-plantuml-vs-graphviz-confluence.md) August 2, 2026 · 7 min read [NGPilot](https://ngpilot.com) Quick Answer Mermaid, PlantUML, and Graphviz are the three most popular text-based diagramming languages. **Mermaid** is the easiest to learn and covers the widest range (30 diagram types). **PlantUML** excels at detailed UML with precise notation control. **Graphviz** is best for technical network and dependency graphs. Most Confluence teams should start with Mermaid and add Graphviz for network diagrams if needed. What you'll learn 1. The strengths and weaknesses of each tool 2. Which diagram types each one supports 3. How easy each is to learn and use 4. A practical recommendation for Confluence teams Text-based diagramming — writing a few lines of code that render into a diagram — is how modern teams keep diagrams in sync with their documentation. No more drawing boxes by hand in Visio, exporting screenshots, and pasting them into Confluence where they go stale. With text-based diagrams, you edit the source and the diagram redraws instantly. But there are three major text-based diagramming languages, and they are not interchangeable. Each has different strengths, different syntax, and different ideal use cases. This guide compares Mermaid, PlantUML, and Graphviz so you can choose the right one (or combination) for your Confluence team. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [plantuml](/blog/tags/plantuml.md) * [graphviz](/blog/tags/graphviz.md) * [comparison](/blog/tags/comparison.md) * [diagrams](/blog/tags/diagrams.md) [**Read more**](/blog/mermaid-vs-plantuml-vs-graphviz-confluence.md) --- ## [Best Numbered Headings App for Confluence — 2026 Comparison](/blog/confluence-numbered-headings-comparison.md) April 18, 2026 · 7 min read [NGPilot](https://ngpilot.com) Long Confluence pages need structure. When your documentation runs past ten headings, readers lose track of where they are. Numbered headings — like "1. Introduction", "1.1 Background", "2. Methods" — give every section a clear position in the hierarchy. Technical docs, legal documents, SOPs, and compliance reports all rely on them. Confluence doesn't number headings out of the box. A handful of marketplace apps fill this gap, but the market is small — Appfire's **Numbered Headings** dominates with 5,484 installs. We built **Modern Numbered Headings for Confluence** to bring a fresh approach with live preview, one-click TOC insertion, and five numbering styles. In this post we compare it against the alternatives. **Tags:** * [numbered-headings](/blog/tags/numbered-headings.md) * [table-of-contents](/blog/tags/table-of-contents.md) * [confluence](/blog/tags/confluence.md) * [documentation](/blog/tags/documentation.md) * [toc](/blog/tags/toc.md) * [heading-numbering](/blog/tags/heading-numbering.md) [**Read more**](/blog/confluence-numbered-headings-comparison.md) --- ## [How to Create a Component Hierarchy in Jira](/blog/jira-component-hierarchy.md) September 23, 2026 · 5 min read [NGPilot](https://ngpilot.com) Jira components were designed for a flat world: one list, no nesting, no structure. That works at ten components and collapses at fifty — when "SSO" sits next to "Platform" and "Mobile" with nothing expressing that it belongs under "Auth", which belongs under "Platform". Teams end up encoding the architecture in name prefixes and maintaining ever-growing `component in (...)` lists by hand. This guide covers three ways to get a component hierarchy in Jira, and what each one costs. **Tags:** * [jira](/blog/tags/jira.md) * [components](/blog/tags/components.md) * [hierarchy](/blog/tags/hierarchy.md) * [jql](/blog/tags/jql.md) * [how-to](/blog/tags/how-to.md) * [project-structure](/blog/tags/project-structure.md) [**Read more**](/blog/jira-component-hierarchy.md) --- ## [Mermaid AI Agent for Confluence: Create, Update & Convert Diagrams by Chat](/blog/mermaid-ai-agent-confluence.md) October 7, 2026 · 5 min read [NGPilot](https://ngpilot.com) Confluence chat can write your page, summarize the thread, and answer questions about the space. What it couldn't do — until now — is draw. If you asked for "a flowchart of our deployment process," you got a text description of a flowchart, and someone still had to open an editor and build it. The AI agent in [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence) closes that gap: it creates, reads, updates, and converts Mermaid diagrams directly on Confluence pages and blog posts, from chat. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [diagrams](/blog/tags/diagrams.md) * [ai](/blog/tags/ai.md) * [how-to](/blog/tags/how-to.md) * [agent](/blog/tags/agent.md) [**Read more**](/blog/mermaid-ai-agent-confluence.md) --- ## [How to Bulk Download All Jira Attachments (Step-by-Step Guide)](/blog/bulk-download-jira-attachments.md) April 21, 2026 · 2 min read [NGPilot](https://ngpilot.com) Collecting attachments from many Jira issues can be tedious. The Simple Bulk Attachment Downloader app automates parallel downloads and packages attachments by issue for easy sharing and archiving. **Tags:** * [jira](/blog/tags/jira.md) * [attachments](/blog/tags/attachments.md) * [bulk](/blog/tags/bulk.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/bulk-download-jira-attachments.md) --- ## [CI/CD Pipeline Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-ci-cd-pipeline-diagram-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) A build fails at 4pm, and the fix's pipeline takes 40 minutes to re-run from the top because someone decided every stage needs to re-validate. That wasted hour is not a code problem — it is a **documentation** problem. Nobody could see the pipeline's shape, so nobody saw the retry loop and the gate that would have caught the failure three stages earlier. **Quick answer:** put the pipeline's shape in Confluence as a Mermaid `flowchart`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Text-based, editable, diffable — a pipeline diagram that changes when your pipeline changes. This post gives you three copy-paste examples: the linear stage view, quality gates with retry loops, and the deploy-to-tag gitGraph that records what actually shipped. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [ci-cd](/blog/tags/ci-cd.md) * [devops](/blog/tags/devops.md) * [flowchart](/blog/tags/flowchart.md) * [gitgraph](/blog/tags/gitgraph.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-ci-cd-pipeline-diagram-confluence.md) --- ## [Swimlane Process Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-process-flow-swimlane-diagram-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The ticket sits in "Waiting on customer" for a week and nobody noticed, because the handoff between first-line support and the dev team is a *tacit* step: Support marks it "escalated" in one field, Engineering is supposed to watch a filter, and the transfer never surfaces as its own action. That inert weekend is a process bug, and the fix is to see the handoff. A swimlane diagram makes the ownership transfer its own crossing arrow — invisible to everyone until it is drawn. **Quick answer:** map cross-functional processes in Confluence as Mermaid `swimlane-beta`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). One lane per actor, steps sequenced inside lanes, and the handoff is the arrow that crosses a lane boundary. When the interaction is a short request/response instead of long-running work, switch to a `sequenceDiagram`. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [swimlane](/blog/tags/swimlane.md) * [process](/blog/tags/process.md) * [flow](/blog/tags/flow.md) * [sequence-diagram](/blog/tags/sequence-diagram.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-process-flow-swimlane-diagram-confluence.md) --- ## [How to Add a Checklist to Jira — and Block Transitions Until Done](/blog/jira-checklist.md) September 18, 2026 · 5 min read [NGPilot](https://ngpilot.com) Every team has a definition of done. The problem is that in Jira, "done" is one button press — nothing checks whether the release notes were written, the tests passed, or the customer was notified. A checklist fixes the *remembering*; enforcement fixes the *skipping*. This guide covers three ways to add a checklist to Jira issues, from a two-minute bullet list to required items that physically block the Done transition. **Tags:** * [jira](/blog/tags/jira.md) * [checklist](/blog/tags/checklist.md) * [workflow](/blog/tags/workflow.md) * [how-to](/blog/tags/how-to.md) * [definition-of-done](/blog/tags/definition-of-done.md) * [process](/blog/tags/process.md) [**Read more**](/blog/jira-checklist.md) --- ## [How to Use AI for Confluence Documentation Review](/blog/ai-for-confluence-documentation-review.md) July 30, 2026 · 7 min read [NGPilot](https://ngpilot.com) Quick Answer AI can automatically review Confluence documentation for quality issues, content gaps, and consistency problems. Run AI audits to identify outdated content, missing sections, and improvement opportunities. What you'll learn 1. How to run AI content audits on your Confluence spaces 2. How to identify content gaps with AI analysis 3. How to ensure consistency with AI style checking 4. How to create automated quality reports Documentation quality degrades over time. Pages get outdated, formats drift, and gaps emerge as the team and product evolve. Manual review is time-consuming and often inconsistent. AI can automate documentation review, identifying quality issues and improvement opportunities at scale. This guide covers how to use AI for Confluence documentation review, from audits to automated reports. **Tags:** * [confluence](/blog/tags/confluence.md) * [ai](/blog/tags/ai.md) * [documentation](/blog/tags/documentation.md) * [how-to](/blog/tags/how-to.md) * [quality](/blog/tags/quality.md) [**Read more**](/blog/ai-for-confluence-documentation-review.md) --- ## [How to Export Jira Audit Logs for Compliance and Security Reviews](/blog/export-jira-audit-logs-compliance.md) July 29, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer Jira audit logs track who changed what, when, and where. Export logs to CSV or via REST API for compliance audits, security investigations, and change management documentation. What you'll learn 1. How to access and navigate the Jira audit log 2. How to filter audit entries by user, date, and action type 3. How to export audit data to CSV or via REST API 4. How to set up automated logging and retention policies 5. How to analyze audit data for compliance and security Audit logs are the paper trail of your Jira instance. They record who did what, when, and where — essential information for compliance audits, security investigations, and change management. Without proper audit logging, you cannot prove who deleted that issue, when permissions changed, or whether someone accessed restricted data. This guide covers how to access, export, and analyze Jira audit logs. **Tags:** * [jira](/blog/tags/jira.md) * [audit-logs](/blog/tags/audit-logs.md) * [compliance](/blog/tags/compliance.md) * [security](/blog/tags/security.md) * [how-to](/blog/tags/how-to.md) * [administration](/blog/tags/administration.md) [**Read more**](/blog/export-jira-audit-logs-compliance.md) --- ## [How to Display JSON, XML, YAML & Code in Confluence (With Syntax Highlighting)](/blog/display-json-xml-code-in-confluence.md) July 23, 2026 · 10 min read [NGPilot](https://ngpilot.com) Who should read this * **Developer teams** documenting APIs, configs, and schemas in Confluence * **Tech writers** who need formatted code samples alongside prose * **Anyone** pasting JSON, XML, YAML, or SQL into Confluence and getting an unreadable wall of text What you'll learn 1. Why Confluence's built-in code block struggles with JSON, XML, and config files 2. How to embed syntax-highlighted code in 85+ languages using a Monaco-powered editor 3. Theme configuration, diff views, and screenshot-ready window chrome 4. When to use a code block vs. a visual JSON structure diagram The scenario every engineering team hits: you're documenting an API in Confluence, and the page needs to show a JSON response, an XML config, a YAML deployment manifest, and a SQL query — all on the same page. You paste each one into Confluence's built-in code block macro, publish, and the result is a wall of monochrome text. No syntax colors. No line numbers that work. JSON braces, XML tags, and YAML indentation all blur together. The reader has to copy-paste your snippet into VS Code just to understand it. The root problem is that Confluence's native code block uses a basic highlighter that wasn't built for the structured data formats modern teams actually work with. JSON, XML, YAML, and SQL each have specific visual conventions — matched braces, nested tags, indentation scopes — that a generic highlighter doesn't handle well. [**Modern Code Blocks for Confluence**](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence) solves this by bringing the Monaco Editor — the same engine that powers VS Code — into Confluence. It accurately highlights 85+ languages including JSON, XML, YAML, SQL, GraphQL, Terraform, Dockerfile, and every mainstream programming language. This guide walks through embedding formatted code and data formats in your Confluence pages. **Tags:** * [confluence](/blog/tags/confluence.md) * [json](/blog/tags/json.md) * [xml](/blog/tags/xml.md) * [yaml](/blog/tags/yaml.md) * [code-blocks](/blog/tags/code-blocks.md) * [syntax-highlighting](/blog/tags/syntax-highlighting.md) * [how-to](/blog/tags/how-to.md) * [api-documentation](/blog/tags/api-documentation.md) [**Read more**](/blog/display-json-xml-code-in-confluence.md) --- ## [Modern FAQ Themes & Reordering — Accordion vs Centered](/blog/how-to-build-faq-sections-confluence.md) May 2, 2026 · 11 min read [NGPilot](https://ngpilot.com) FAQ sections are one of the most practical elements you can add to a Confluence page. Whether you are documenting product details, building an IT help desk resource, or writing an onboarding guide, a well-structured FAQ section lets readers find answers without scrolling through walls of text or pinging someone on Slack. The problem is that Confluence does not give you a built-in way to create FAQ sections. Teams typically resort to manual workarounds: bullet lists, tables, or toggles built from expand macros. These methods work, sort of, but they are tedious to maintain, hard to reorder, and look inconsistent from page to page. **Modern FAQ for Confluence** solves this by giving you a dedicated macro for building FAQ sections with drag-and-drop reordering, WYSIWYG editing, and two display themes. This guide walks through the entire process, provides ready-to-use templates, and shares best practices so your FAQ pages actually help people find what they need. **Tags:** * [confluence](/blog/tags/confluence.md) * [faq](/blog/tags/faq.md) * [accordion](/blog/tags/accordion.md) * [how-to](/blog/tags/how-to.md) * [knowledge-base](/blog/tags/knowledge-base.md) [**Read more**](/blog/how-to-build-faq-sections-confluence.md) --- ## [How to Create Sequence Diagrams in Confluence (Mermaid Examples)](/blog/how-to-create-sequence-diagrams-confluence.md) May 2, 2026 · 13 min read [NGPilot](https://ngpilot.com) Sequence diagrams are one of the most practical tools in a software team's documentation toolkit. They show how objects, services, or actors interact over time, making them ideal for documenting API flows, authentication processes, microservice choreography, and error-handling logic. If your team uses Confluence for documentation, embedding sequence diagrams directly on your pages keeps architecture docs alongside everything else your team needs. In this tutorial, you will learn how to create sequence diagrams in Confluence using Mermaid syntax. Every example is copy-paste ready, so you can drop it straight into a Confluence page and see the result immediately. The examples use [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence), which renders the full Mermaid v12 syntax natively in Confluence Cloud — free to try from the Marketplace. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [sequence-diagram](/blog/tags/sequence-diagram.md) * [how-to](/blog/tags/how-to.md) * [diagrams](/blog/tags/diagrams.md) [**Read more**](/blog/how-to-create-sequence-diagrams-confluence.md) --- ## [How to Add SVG Illustrations to Confluence Pages](/blog/how-to-add-svg-illustrations-confluence.md) May 2, 2026 · 17 min read [NGPilot](https://ngpilot.com) Adding illustrations to Confluence pages transforms flat walls of text into engaging, professional content. Whether you are writing onboarding documentation, putting together a team wiki, or preparing a presentation, the right visual can communicate an idea faster than a paragraph of explanation. The challenge has always been finding high-quality illustrations that look good at any size, load quickly, and match your team's visual style. SVG (Scalable Vector Graphics) illustrations solve all of these problems. They scale perfectly to any resolution, they are lightweight, and they integrate cleanly into Confluence pages. Content Craft for Confluence brings a curated library of SVG illustrations directly into the Confluence editor, so you can browse, search, and insert professional illustrations without leaving your workflow. This tutorial shows you exactly how to add SVG illustrations to Confluence pages using Content Craft for Confluence. By the end, you will be able to transform any Confluence page from text-heavy to visually engaging in under a minute. **Tags:** * [confluence](/blog/tags/confluence.md) * [svg](/blog/tags/svg.md) * [illustrations](/blog/tags/illustrations.md) * [content-craft](/blog/tags/content-craft.md) * [how-to](/blog/tags/how-to.md) * [design](/blog/tags/design.md) [**Read more**](/blog/how-to-add-svg-illustrations-confluence.md) --- ## [Import Markdown into Confluence: Paste, GitHub, .md Files](/blog/import-markdown-into-confluence.md) September 24, 2026 · 3 min read [NGPilot](https://ngpilot.com) Every team has Markdown lying around that Confluence needs: the README that became the service doc, the design doc drafted as a pull-request description, the runbook that lives in the repo. And every attempt to move it hits the same wall — Confluence's default editor does not parse Markdown. Paste a .md document and you get a wall of pipes, backticks, and asterisks that looks exactly like what it is: text nobody formatted. The macro route dissolves the wall. Paste the document into a Markdown macro that actually parses it, watch it render in the preview pane, publish. This page is the workflow, end to end. **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [import](/blog/tags/import.md) * [migration](/blog/tags/migration.md) * [github](/blog/tags/github.md) * [how-to](/blog/tags/how-to.md) * [developer-tools](/blog/tags/developer-tools.md) [**Read more**](/blog/import-markdown-into-confluence.md) --- ## [Import Markdown into Confluence — 3 Methods Compared (2026)](/blog/markdown-to-confluence-converter.md) May 10, 2026 · 5 min read [NGPilot](https://ngpilot.com) Who should read this * Development teams importing GitHub READMEs to Confluence * Documentation engineers migrating Markdown file sets * Anyone who wants to write Markdown directly in Confluence What you'll learn 1. Comparison of three Markdown import methods 2. How to choose the best tool for your use case 3. Step-by-step setup instructions Many teams have documentation in Markdown format (GitHub READMEs, API docs, developer guides) and need to bring it into Confluence. Confluence doesn't have a native Markdown import feature, but there are three ways to get Markdown content into Confluence pages. **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [import](/blog/tags/import.md) * [converter](/blog/tags/converter.md) * [enhanced-markdown](/blog/tags/enhanced-markdown.md) * [import-export](/blog/tags/import-export.md) [**Read more**](/blog/markdown-to-confluence-converter.md) --- ## [Build an Incident Postmortem Timeline in Confluence (Mermaid, Copy-Paste)](/blog/mermaid-incident-postmortem-timeline-confluence.md) September 24, 2026 · 8 min read [NGPilot](https://ngpilot.com) Every incident has a story hidden inside a pile of timestamps: alert fired at 09:42, nobody acknowledged until 09:47, an engineer escalated at 09:54, a workaround landed at 10:20, services healthy at 10:31. Individually the timestamps mean nothing. Laid out on a timeline, they tell the story — and the story is what a postmortem is for. Confluence is where incident postmortems already live. What Confluence does not give you is a native timeline. This guide shows you how to fill the Timeline section of an incident postmortem with a Mermaid diagram: one copy-paste timeline that visualizes detection → escalation → resolution, plus a sequence diagram that shows exactly how the failure propagated between services. **Tags:** * [incident](/blog/tags/incident.md) * [postmortem](/blog/tags/postmortem.md) * [timeline](/blog/tags/timeline.md) * [mermaid](/blog/tags/mermaid.md) * [confluence](/blog/tags/confluence.md) * [incident-management](/blog/tags/incident-management.md) * [how-to](/blog/tags/how-to.md) * [devops](/blog/tags/devops.md) [**Read more**](/blog/mermaid-incident-postmortem-timeline-confluence.md) --- ## [Root Cause Analysis in Confluence with Mermaid Fishbone + 5 Whys](/blog/mermaid-fishbone-root-cause-analysis-confluence.md) September 24, 2026 · 7 min read [NGPilot](https://ngpilot.com) A root cause analysis is only as good as the disagreement it survives. When the 'root cause' box on your postmortem template contains one sentence, the meeting spends an hour relitigating that sentence. A fishbone diagram and a 5 Whys chain move the argument onto a diagram: everyone sees which categories were considered, which branch was chosen, and exactly how the 'why' answers arrive at a root cause. Confluence is where RCA already happens — in the Root Cause Analysis template, in postmortems, in retros. The missing piece is a diagram that holds the reasoning. This guide shows you two copy-paste Mermaid diagrams: an `ishikawa` fishbone that maps every candidate cause category, and a `flowchart` 5-Whys drilldown that lands on one concrete fix. **Tags:** * [root-cause-analysis](/blog/tags/root-cause-analysis.md) * [fishbone](/blog/tags/fishbone.md) * [ishikawa](/blog/tags/ishikawa.md) * [5-whys](/blog/tags/5-whys.md) * [mermaid](/blog/tags/mermaid.md) * [confluence](/blog/tags/confluence.md) * [postmortem](/blog/tags/postmortem.md) * [how-to](/blog/tags/how-to.md) * [incident-management](/blog/tags/incident-management.md) [**Read more**](/blog/mermaid-fishbone-root-cause-analysis-confluence.md) --- ## [Monospace in Confluence: How to Format Inline Code (Shortcuts & Markdown)](/blog/confluence-monospace.md) October 1, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Select the text and press **Ctrl+Shift+M** (Windows) or **Opt+Shift+M** (Mac) to apply inline code, or type `` `backticks` `` around text as you write — the Confluence Cloud editor autoformats them. Pasted Markdown keeps its backticks as literal characters, so paste into [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence/) instead, which renders inline code, code blocks, and diagrams from your Markdown source. Inline code — monospace text on a subtle background — is how you mark up variable names, file paths, key names, and short commands inside a sentence: set `MAX_RETRIES = 3`, edit `~/.zshrc`, or run `kubectl get pods`. Confluence Cloud has three ways to produce it, and each fits a different moment: formatting as you go, typing Markdown, or bringing Markdown in from your repo. What you'll learn 1. The keyboard shortcut — Ctrl+Shift+M, and the Mac split between Opt+Shift+M and Cmd+Shift+M 2. Backtick autoformatting while you type 3. The Markdown method for pasted content (Enhanced Markdown) 4. Inline code vs code block — which one to use where **Tags:** * [confluence](/blog/tags/confluence.md) * [formatting](/blog/tags/formatting.md) * [markdown](/blog/tags/markdown.md) * [monospace](/blog/tags/monospace.md) * [inline-code](/blog/tags/inline-code.md) * [enhanced-markdown](/blog/tags/enhanced-markdown.md) * [keyboard-shortcuts](/blog/tags/keyboard-shortcuts.md) [**Read more**](/blog/confluence-monospace.md) --- ## [Root Cause Analysis in Confluence with Mermaid Fishbone + 5 Whys](/blog/mermaid-fishbone-root-cause-analysis-confluence.md) September 24, 2026 · 7 min read [NGPilot](https://ngpilot.com) A root cause analysis is only as good as the disagreement it survives. When the 'root cause' box on your postmortem template contains one sentence, the meeting spends an hour relitigating that sentence. A fishbone diagram and a 5 Whys chain move the argument onto a diagram: everyone sees which categories were considered, which branch was chosen, and exactly how the 'why' answers arrive at a root cause. Confluence is where RCA already happens — in the Root Cause Analysis template, in postmortems, in retros. The missing piece is a diagram that holds the reasoning. This guide shows you two copy-paste Mermaid diagrams: an `ishikawa` fishbone that maps every candidate cause category, and a `flowchart` 5-Whys drilldown that lands on one concrete fix. **Tags:** * [root-cause-analysis](/blog/tags/root-cause-analysis.md) * [fishbone](/blog/tags/fishbone.md) * [ishikawa](/blog/tags/ishikawa.md) * [5-whys](/blog/tags/5-whys.md) * [mermaid](/blog/tags/mermaid.md) * [confluence](/blog/tags/confluence.md) * [postmortem](/blog/tags/postmortem.md) * [how-to](/blog/tags/how-to.md) * [incident-management](/blog/tags/incident-management.md) [**Read more**](/blog/mermaid-fishbone-root-cause-analysis-confluence.md) --- ## [What Is Atlassian Isolated Cloud? NGPILOT Apps Available (2026)](/blog/what-is-atlassian-isolated-cloud.md) July 30, 2026 · 4 min read [NGPilot](https://ngpilot.com) Quick Answer Atlassian Isolated Cloud lets you deploy marketplace apps within your own dedicated Atlassian cloud instance — separate from other tenants. This provides enhanced data isolation while keeping the benefits of cloud (no server maintenance, automatic updates). NGPILOT has 6 apps certified for Isolated Cloud. **Tags:** * [atlassian](/blog/tags/atlassian.md) * [isolated-cloud](/blog/tags/isolated-cloud.md) * [confluence](/blog/tags/confluence.md) * [jira](/blog/tags/jira.md) * [deployment](/blog/tags/deployment.md) [**Read more**](/blog/what-is-atlassian-isolated-cloud.md) --- ## [How to See Who Changed What in Jira — Field-Level Issue History](/blog/jira-issue-history.md) September 23, 2026 · 5 min read [NGPilot](https://ngpilot.com) Every Jira issue keeps a diary. Status flips, priority bumps, reassignments, edited specs — Jira writes all of it down. The problem is reading it back: the built-in history turns a description edit into one unhelpful line, and "who changed this?" across forty issues becomes forty clicks or a REST script. This guide covers three ways to actually read Jira issue history, from the free built-in tab to field-level diffs and a cross-issue CSV report. **Tags:** * [jira](/blog/tags/jira.md) * [issue-history](/blog/tags/issue-history.md) * [audit](/blog/tags/audit.md) * [changelog](/blog/tags/changelog.md) * [how-to](/blog/tags/how-to.md) * [compliance](/blog/tags/compliance.md) [**Read more**](/blog/jira-issue-history.md) --- ## [How to Create Jira Issue Templates for Consistent Team Workflows](/blog/create-jira-issue-templates-for-consistent-workflows.md) July 29, 2026 · 7 min read [NGPilot](https://ngpilot.com) Quick Answer Jira issue templates standardize how bugs, features, and tasks are reported. Create pre-filled templates with required fields and structured descriptions to eliminate incomplete issues. What you'll learn 1. How to identify and catalog your team's recurring issue types 2. How to create pre-filled templates that enforce required fields 3. How to use bulk create for batch issue generation from spreadsheets 4. How to train your team to use templates consistently Inconsistent issue reporting is a silent productivity killer. One developer writes a two-line bug report with no steps to reproduce. Another writes a three-paragraph feature request buried in technical jargon. The result: wasted time clarifying, misestimated work, and frustrated teams. Issue templates solve this by standardizing how work is described. Every bug report has the same structure. Every feature request includes the same fields. This guide shows how to create and enforce templates in Jira. **Tags:** * [jira](/blog/tags/jira.md) * [issue-templates](/blog/tags/issue-templates.md) * [how-to](/blog/tags/how-to.md) * [productivity](/blog/tags/productivity.md) * [standardization](/blog/tags/standardization.md) [**Read more**](/blog/create-jira-issue-templates-for-consistent-workflows.md) --- ## [Visualize Git Branches & Releases Inside Jira with Mermaid GitGraph](/blog/mermaid-gitgraph-jira-branch-history.md) September 24, 2026 · 7 min read [NGPilot](https://ngpilot.com) Your team is mid-debug on a prod incident. A senior engineer asks *"which release shipped this commit, and why is it on the release branch when the PR said main?"* — and nobody can answer without switching between Jira, the git web UI, and a Slack thread. That context — commit history, branches, merge points, release versions — belongs *next to the issue*, not in a tool people have to leave Jira to open. **Quick answer:** paste a Mermaid `gitGraph` into the issue's [Mermaid Plus Diagrams for Jira](https://marketplace.atlassian.com/apps/2658777397/mermaid-plus-diagrams-for-jira/) panel and the branch history renders as a diagram right on the ticket — commits, branches, merges, and release tags, all in one editable text block. This post gives you three copy-paste examples: a trunk-based feature workflow, a hotfix outside the release window, and a branch-rule flowchart to keep behavior consistent. **Tags:** * [jira](/blog/tags/jira.md) * [git](/blog/tags/git.md) * [gitgraph](/blog/tags/gitgraph.md) * [mermaid](/blog/tags/mermaid.md) * [branching](/blog/tags/branching.md) * [release](/blog/tags/release.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-gitgraph-jira-branch-history.md) --- ## [Jira Workflow Automation: Complete Guide (2026)](/blog/jira-workflow-automation-complete-guide-2026.md) July 30, 2026 · 4 min read [NGPilot](https://ngpilot.com) Quick Answer Jira workflow automation uses rules with triggers, conditions, and actions to automate repetitive tasks. You can auto-assign issues, transition tickets based on status, send notifications, and update fields — all without code. Start with Jira's built-in automation rules, then scale to marketplace apps for complex workflows. **Tags:** * [jira](/blog/tags/jira.md) * [jira-admin](/blog/tags/jira-admin.md) * [automation](/blog/tags/automation.md) * [workflows](/blog/tags/workflows.md) * [atlassian](/blog/tags/atlassian.md) [**Read more**](/blog/jira-workflow-automation-complete-guide-2026.md) --- ## [Jira Issue Templates FAQ: Auto-Apply, Variables & Automation](/blog/faq-jira-issue-templates-automation.md) May 2, 2026 · 12 min read [NGPilot](https://ngpilot.com) **Tags:** * [faq](/blog/tags/faq.md) * [jira](/blog/tags/jira.md) * [issue-templates](/blog/tags/issue-templates.md) * [automation](/blog/tags/automation.md) * [jira-automation](/blog/tags/jira-automation.md) [**Read more**](/blog/faq-jira-issue-templates-automation.md) --- ## [Jira Export Limit: How to Export More Than 1,000 Issues (2026)](/blog/jira-export-limit.md) September 2, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Jira Cloud's native export stops at 1,000 issues per export and only includes columns visible in the issue navigator. To export more: split your filter into JQL batches, use the REST API, or install [Simple Bulk Issues Excel CSV Export](https://marketplace.atlassian.com/apps/3818473739/simple-bulk-issues-excel-csv-export-for-jira?utm_source=ngpilot.com\&utm_medium=blog), which exports up to 5,000 issues per run in CSV, XLS, or XLSX — and tells you plainly when a result set was truncated. If you have ever exported a project for reporting, an audit, or a migration, you have probably run into Jira Cloud's export limit without being warned first: the export finishes, the file looks complete, and the row count quietly stops at 1,000. This article explains where that limit comes from, then compares the three practical ways to export larger issue sets in 2026. **Tags:** * [jira](/blog/tags/jira.md) * [export](/blog/tags/export.md) * [excel](/blog/tags/excel.md) * [csv](/blog/tags/csv.md) * [jira-cloud](/blog/tags/jira-cloud.md) * [reporting](/blog/tags/reporting.md) [**Read more**](/blog/jira-export-limit.md) --- ## [Best Diagram App for Jira — 2026 Comparison with Mermaid & Excalidraw](/blog/jira-diagram-apps-comparison.md) April 18, 2026 · 7 min read [NGPilot](https://ngpilot.com) Every engineering team needs diagrams in Jira — architecture decisions on epics, bug reproduction flows on tickets, wireframes on stories. But Jira has no built-in diagramming. You either paste screenshots from external tools or install a marketplace app. We built two diagram apps for Jira: **Mermaid+ Diagrams for Jira** for text-based diagrams using Mermaid syntax (flowcharts, sequence diagrams, ER models, C4 architecture), and **Excalidraw Diagrams + Whiteboards for Jira** for freeform drawing with 229 built-in shape libraries. In this post we compare both against every alternative on the Atlassian Marketplace. **Tags:** * [jira-diagrams](/blog/tags/jira-diagrams.md) * [mermaid](/blog/tags/mermaid.md) * [excalidraw](/blog/tags/excalidraw.md) * [whiteboard](/blog/tags/whiteboard.md) * [flowchart](/blog/tags/flowchart.md) * [architecture-diagram](/blog/tags/architecture-diagram.md) * [jira-plugin](/blog/tags/jira-plugin.md) [**Read more**](/blog/jira-diagram-apps-comparison.md) --- ## [Create Mermaid Diagrams on Jira Issues — Flowcharts, Sequence & More](/blog/how-to-create-mermaid-diagrams-jira.md) May 2, 2026 · 18 min read [NGPilot](https://ngpilot.com) Jira issues are where your team tracks bugs, features, and tasks every day. But describing complex processes, API interactions, or system designs in plain text often leads to confusion and misalignment. Mermaid Plus Diagrams for Jira solves this by letting you create and embed Mermaid diagrams directly on any Jira issue, so the visual context lives exactly where the work happens. No external tools, no attached images that go stale, no switching between tabs. **Tags:** * [jira](/blog/tags/jira.md) * [mermaid](/blog/tags/mermaid.md) * [diagrams](/blog/tags/diagrams.md) * [how-to](/blog/tags/how-to.md) * [jira-issues](/blog/tags/jira-issues.md) * [flowchart](/blog/tags/flowchart.md) [**Read more**](/blog/how-to-create-mermaid-diagrams-jira.md) --- ## [Best Diagram App for Jira — 2026 Comparison with Mermaid & Excalidraw](/blog/jira-diagram-apps-comparison.md) April 18, 2026 · 7 min read [NGPilot](https://ngpilot.com) Every engineering team needs diagrams in Jira — architecture decisions on epics, bug reproduction flows on tickets, wireframes on stories. But Jira has no built-in diagramming. You either paste screenshots from external tools or install a marketplace app. We built two diagram apps for Jira: **Mermaid+ Diagrams for Jira** for text-based diagrams using Mermaid syntax (flowcharts, sequence diagrams, ER models, C4 architecture), and **Excalidraw Diagrams + Whiteboards for Jira** for freeform drawing with 229 built-in shape libraries. In this post we compare both against every alternative on the Atlassian Marketplace. **Tags:** * [jira-diagrams](/blog/tags/jira-diagrams.md) * [mermaid](/blog/tags/mermaid.md) * [excalidraw](/blog/tags/excalidraw.md) * [whiteboard](/blog/tags/whiteboard.md) * [flowchart](/blog/tags/flowchart.md) * [architecture-diagram](/blog/tags/architecture-diagram.md) * [jira-plugin](/blog/tags/jira-plugin.md) [**Read more**](/blog/jira-diagram-apps-comparison.md) --- ## [Create Jira Issue Templates — Import from GitHub, Markdown & Rich Text](/blog/how-to-create-jira-issue-templates.md) May 2, 2026 · 16 min read [NGPilot](https://ngpilot.com) Every team that uses Jira long enough runs into the same problem: inconsistent tickets. One developer files a detailed bug report with reproduction steps, environment details, and screenshots. Another submits a two-line summary with no context. Product managers write user stories that vary wildly in structure, making backlog grooming slower than it needs to be. Support teams log incidents using different formats depending on who is on shift. These inconsistencies compound over time and erode the reliability of your Jira data, making reports unreliable and sprint planning harder than necessary. Issue templates solve this by standardizing the structure and content of every new ticket. When you create a Jira issue template, every bug report follows the same format, every user story has the same sections, and every task includes the same checklists. The result is faster ticket creation, better reporting, and a shared understanding of what "done" looks like across the team. **Tags:** * [jira](/blog/tags/jira.md) * [issue-templates](/blog/tags/issue-templates.md) * [how-to](/blog/tags/how-to.md) * [jira-templates](/blog/tags/jira-templates.md) * [automation](/blog/tags/automation.md) [**Read more**](/blog/how-to-create-jira-issue-templates.md) --- ## [How to Use AI for Jira Sprint Planning and Velocity Prediction](/blog/ai-for-jira-sprint-planning-velocity-prediction.md) July 30, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer AI can predict sprint velocity and forecast capacity by analyzing historical data. Use AI recommendations to plan realistic sprints, suggest optimal scope, and track prediction accuracy over time. What you'll learn 1. How to enable AI velocity prediction in Jira 2. How to use AI for capacity forecasting 3. How to get AI scope recommendations for sprint planning 4. How to track and improve AI prediction accuracy Sprint planning is part science, part guesswork. Teams estimate velocity based on gut feeling, leading to overcommitment or underutilization. AI can replace this guesswork with data-driven predictions. This guide covers how to use AI for Jira sprint planning, from velocity prediction to scope recommendations. **Tags:** * [jira](/blog/tags/jira.md) * [ai](/blog/tags/ai.md) * [sprint-planning](/blog/tags/sprint-planning.md) * [velocity](/blog/tags/velocity.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/ai-for-jira-sprint-planning-velocity-prediction.md) --- ## [How to Set Up Jira Dashboards for Sprint Tracking and Stakeholder Visibility](/blog/jira-dashboard-sprint-tracking-setup.md) July 29, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Jira dashboards provide real-time visibility into sprint health, velocity trends, and team performance. Configure gadgets, create JQL filters, and share dashboards with stakeholders. What you'll learn 1. How to create and configure a Jira dashboard from scratch 2. Which gadgets track sprint health vs long-term trends 3. How to set up JQL filters for custom dashboard views 4. How to share dashboards and set up email subscriptions A well-designed Jira dashboard gives your team instant visibility into sprint health, backlog status, and delivery trends. But most dashboards are either empty defaults or cluttered messes that nobody uses. This guide covers how to build dashboards that actually provide value — from sprint tracking to stakeholder reporting. **Tags:** * [jira](/blog/tags/jira.md) * [dashboards](/blog/tags/dashboards.md) * [how-to](/blog/tags/how-to.md) * [reporting](/blog/tags/reporting.md) * [sprint-tracking](/blog/tags/sprint-tracking.md) [**Read more**](/blog/jira-dashboard-sprint-tracking-setup.md) --- ## [How to Set Up Announcement Banners in Confluence and Jira](/blog/how-to-set-up-announcement-banners-confluence-jira.md) May 23, 2026 · 7 min read [NGPilot](https://ngpilot.com) Announcement banners are the most visible communication channel in Atlassian products. They sit at the top of every page, impossible to miss. When you need to notify your entire organization about a maintenance window, a security alert, a policy change, or an upcoming event, banners guarantee visibility in a way that emails and Slack messages cannot. Both Confluence and Jira support announcement banners, but their native implementations are limited. This guide covers how to set up banners in both platforms using built-in features and marketplace apps, with practical tips for getting the most out of them. **Tags:** * [confluence](/blog/tags/confluence.md) * [jira](/blog/tags/jira.md) * [announcement-banner](/blog/tags/announcement-banner.md) * [how-to](/blog/tags/how-to.md) * [customization](/blog/tags/customization.md) [**Read more**](/blog/how-to-set-up-announcement-banners-confluence-jira.md) --- ## [Jira Bulk Operations FAQ: Exports, Edits & Downloads](/blog/faq-bulk-operations-jira.md) April 21, 2026 · 10 min read [NGPilot](https://ngpilot.com) Managing a Jira instance at scale means sooner or later you will need to act on dozens, hundreds, or even thousands of issues at once. Whether you are migrating projects, cleaning up stale tickets, bulk-downloading attachments for an audit, or exporting an entire backlog for offline analysis, doing it one issue at a time is not realistic. Bulk operations let teams apply the same change across many issues simultaneously, saving hours of repetitive manual work and reducing the risk of inconsistency that comes with editing tickets individually. However, bulk operations carry real risk. A single misconfigured bulk edit can change the status, assignee, or custom field value of hundreds of issues in seconds, and Jira does not offer a one-click undo. That is why understanding the right tools, permissions, safeguards, and workflows is critical before you run any bulk job. This FAQ covers the most common questions teams ask when planning and executing bulk operations in Jira, from safety and rollback strategies to performance tuning and permission requirements. **Tags:** * [faq](/blog/tags/faq.md) * [jira](/blog/tags/jira.md) * [bulk](/blog/tags/bulk.md) * [export](/blog/tags/export.md) * [attachments](/blog/tags/attachments.md) [**Read more**](/blog/faq-bulk-operations-jira.md) --- ## [Customer Journey Maps in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-journey-diagram-customer-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The support team knows where refunds leak. The product team knows where onboarding drops. The sales team knows where the pricing page confuses. Three silos, three versions of the customer's experience — and the roadmap meeting spends an hour reconciling them instead of deciding what to fix. What is missing is a single picture with a score on every step. **Quick answer:** draw customer journeys in Confluence as Mermaid `journey` diagrams, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). A journey diagram puts every step in a row and every satisfaction score on one curve — the dips are visible, the actors are labeled, and the whole thing stays editable text. This post gives you three copy-paste examples: onboarding, a support ticket, and a checkout flow with a summary pie. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [journey](/blog/tags/journey.md) * [customer-experience](/blog/tags/customer-experience.md) * [product](/blog/tags/product.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-journey-diagram-customer-confluence.md) --- ## [How to Create a Component Hierarchy in Jira](/blog/jira-component-hierarchy.md) September 23, 2026 · 5 min read [NGPilot](https://ngpilot.com) Jira components were designed for a flat world: one list, no nesting, no structure. That works at ten components and collapses at fifty — when "SSO" sits next to "Platform" and "Mobile" with nothing expressing that it belongs under "Auth", which belongs under "Platform". Teams end up encoding the architecture in name prefixes and maintaining ever-growing `component in (...)` lists by hand. This guide covers three ways to get a component hierarchy in Jira, and what each one costs. **Tags:** * [jira](/blog/tags/jira.md) * [components](/blog/tags/components.md) * [hierarchy](/blog/tags/hierarchy.md) * [jql](/blog/tags/jql.md) * [how-to](/blog/tags/how-to.md) * [project-structure](/blog/tags/project-structure.md) [**Read more**](/blog/jira-component-hierarchy.md) --- ## [How to View JSON in Jira — Fields, Entity Properties & Pasted Payloads](/blog/jira-json-viewer.md) September 18, 2026 · 4 min read [NGPilot](https://ngpilot.com) Half the debugging in a Jira-integrated stack ends at the same place: a wall of braces. A webhook payload pasted into a comment, a config blob in a custom field, entity properties an integration app quietly wrote onto the ticket — the JSON is *there*, on the issue, but reading it means scrolling and counting brackets. Here are three ways to actually read it, from free-but-painful to a proper graph view inside Jira. **Tags:** * [jira](/blog/tags/jira.md) * [json](/blog/tags/json.md) * [how-to](/blog/tags/how-to.md) * [api](/blog/tags/api.md) * [developer-tools](/blog/tags/developer-tools.md) [**Read more**](/blog/jira-json-viewer.md) --- ## [JSON Formatting & Display in Confluence: Code Blocks vs Structure Viewer](/blog/confluence-json-schema-viewer.md) May 10, 2026 · 4 min read [NGPilot](https://ngpilot.com) Confluence's native code block macro renders JSON as plain text with no real formatting, no themes, and no copy button. There are two purpose-built apps that fix this, and each serves a different JSON display need: * **[Modern Code Blocks for Confluence](/docs/Modern-Code-Blocks-for-Confluence/user-docs.md)** — renders JSON as **syntax-highlighted code** with the Monaco editor (VS Code engine), 50+ themes, line numbers, copy button, and dark/light mode. **Best for API docs, snippets, and most JSON display.** * **[JSON Structure Viewer for Confluence](/docs/json-structure-viewer-for-confluence/usage.md)** — renders JSON as an **interactive collapsible tree** you can zoom and rotate. **Best for exploring large, deeply nested structures.** This guide compares the two so you can pick the right one for each page. **Tags:** * [confluence](/blog/tags/confluence.md) * [json](/blog/tags/json.md) * [json-schema](/blog/tags/json-schema.md) * [api-documentation](/blog/tags/api-documentation.md) * [code-blocks](/blog/tags/code-blocks.md) [**Read more**](/blog/confluence-json-schema-viewer.md) --- ## [Kanban Board Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-kanban-board-workflow-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The sprint board on the wall shows 40 items in "In Progress" and the rulebook says "we limit WIP" and nobody agrees on what the limit is. The board is honest; the *documentation* is aspirational. A Kanban diagram in the wiki is the board as a spec — columns, limits, and the rework paths drawn so the workflow is a claim the team can argue with. **Quick answer:** document the team's board in Confluence as a Mermaid `kanban`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Columns as headings, work items as indented cards; the workflow *rules* (who may move what, when, including rework) as a `stateDiagram` on the same page. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [kanban](/blog/tags/kanban.md) * [workflow](/blog/tags/workflow.md) * [state-diagram](/blog/tags/state-diagram.md) * [agile](/blog/tags/agile.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-kanban-board-workflow-confluence.md) --- ## [Math Equations in Confluence: LaTeX & KaTeX via Markdown](/blog/markdown-math-equations-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) Ask an engineer to document an algorithm in Confluence and watch what happens to the math: `O(n log n)` typed as plain text, `x²` pasted from a character map, and — for anything real — a screenshot from an online equation editor, blurry and already out of date. Confluence has no native LaTeX support, so every formula becomes either a compromise or an image. It does not have to. With a Markdown macro on the page, Confluence renders real LaTeX — inline `$...$`, display `$$...$$`, fenced blocks with full `align` environments — and the equation stays text: searchable, theme-consistent, editable in seconds. This guide gives you the syntax and copy-paste examples for all three routes. **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [latex](/blog/tags/latex.md) * [katex](/blog/tags/katex.md) * [mathjax](/blog/tags/mathjax.md) * [math](/blog/tags/math.md) * [how-to](/blog/tags/how-to.md) * [engineering](/blog/tags/engineering.md) [**Read more**](/blog/markdown-math-equations-confluence.md) --- ## [Monospace in Confluence: How to Format Inline Code (Shortcuts & Markdown)](/blog/confluence-monospace.md) October 1, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Select the text and press **Ctrl+Shift+M** (Windows) or **Opt+Shift+M** (Mac) to apply inline code, or type `` `backticks` `` around text as you write — the Confluence Cloud editor autoformats them. Pasted Markdown keeps its backticks as literal characters, so paste into [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence/) instead, which renders inline code, code blocks, and diagrams from your Markdown source. Inline code — monospace text on a subtle background — is how you mark up variable names, file paths, key names, and short commands inside a sentence: set `MAX_RETRIES = 3`, edit `~/.zshrc`, or run `kubectl get pods`. Confluence Cloud has three ways to produce it, and each fits a different moment: formatting as you go, typing Markdown, or bringing Markdown in from your repo. What you'll learn 1. The keyboard shortcut — Ctrl+Shift+M, and the Mac split between Opt+Shift+M and Cmd+Shift+M 2. Backtick autoformatting while you type 3. The Markdown method for pasted content (Enhanced Markdown) 4. Inline code vs code block — which one to use where **Tags:** * [confluence](/blog/tags/confluence.md) * [formatting](/blog/tags/formatting.md) * [markdown](/blog/tags/markdown.md) * [monospace](/blog/tags/monospace.md) * [inline-code](/blog/tags/inline-code.md) * [enhanced-markdown](/blog/tags/enhanced-markdown.md) * [keyboard-shortcuts](/blog/tags/keyboard-shortcuts.md) [**Read more**](/blog/confluence-monospace.md) --- ## [How to Build an AI Chatbot for Confluence Knowledge Base](/blog/build-ai-chatbot-confluence-knowledge-base.md) July 30, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer Build an AI chatbot that answers questions from your Confluence knowledge base using no-code tools or custom development. Connect Confluence content, train the chatbot, and deploy to Slack or Teams. What you'll learn 1. How to choose the right chatbot platform for your needs 2. how to prepare and export Confluence content for chatbot ingestion 3. How to connect the chatbot to your Confluence data 4. How to train, test, and deploy your Confluence chatbot Teams waste hours searching Confluence for answers that already exist. A chatbot can bridge this gap by providing instant answers from your knowledge base, right where the team works. This guide covers how to build an AI chatbot for Confluence, from no-code solutions to custom development. **Tags:** * [confluence](/blog/tags/confluence.md) * [ai](/blog/tags/ai.md) * [chatbot](/blog/tags/chatbot.md) * [knowledge-base](/blog/tags/knowledge-base.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/build-ai-chatbot-confluence-knowledge-base.md) --- ## [Math Equations in Confluence: LaTeX & KaTeX via Markdown](/blog/markdown-math-equations-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) Ask an engineer to document an algorithm in Confluence and watch what happens to the math: `O(n log n)` typed as plain text, `x²` pasted from a character map, and — for anything real — a screenshot from an online equation editor, blurry and already out of date. Confluence has no native LaTeX support, so every formula becomes either a compromise or an image. It does not have to. With a Markdown macro on the page, Confluence renders real LaTeX — inline `$...$`, display `$$...$$`, fenced blocks with full `align` environments — and the equation stays text: searchable, theme-consistent, editable in seconds. This guide gives you the syntax and copy-paste examples for all three routes. **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [latex](/blog/tags/latex.md) * [katex](/blog/tags/katex.md) * [mathjax](/blog/tags/mathjax.md) * [math](/blog/tags/math.md) * [how-to](/blog/tags/how-to.md) * [engineering](/blog/tags/engineering.md) [**Read more**](/blog/markdown-math-equations-confluence.md) --- ## [Tabs in Confluence: Native Layout Tabs vs Tabs Macros Compared](/blog/confluence-tabs-macro.md) August 21, 2026 · 4 min read [NGPilot](https://ngpilot.com) Tabs are the layout workhorse of product pages, API references, and comparison docs: they let one page hold three versions of the truth (per environment, per plan, per language) without tripling the scroll length. Confluence's answer to tabs has changed over the years, so this page sorts out what exists today and which to use when. **Tags:** * [confluence](/blog/tags/confluence.md) * [macros](/blog/tags/macros.md) * [tabs](/blog/tags/tabs.md) * [layout](/blog/tags/layout.md) * [formatting](/blog/tags/formatting.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/confluence-tabs-macro.md) --- ## [Confluence FAQ Macro & Q\&A Template: Add FAQ Sections to Pages](/blog/confluence-questions-answers-template.md) May 10, 2026 · 3 min read [NGPilot](https://ngpilot.com) Confluence is great for documentation, but it has no built-in **FAQ macro** or Q\&A tool. If you need FAQ pages, knowledge bases, or community-style Q\&A in Confluence, NGPILOT offers two purpose-built apps. **Tags:** * [confluence](/blog/tags/confluence.md) * [faq](/blog/tags/faq.md) * [questions](/blog/tags/questions.md) * [answers](/blog/tags/answers.md) * [template](/blog/tags/template.md) * [knowledge-base](/blog/tags/knowledge-base.md) * [macro](/blog/tags/macro.md) [**Read more**](/blog/confluence-questions-answers-template.md) --- ## [Confluence Pagination: How to Paginate Pages and Tables (3 Methods)](/blog/confluence-pagination.md) October 4, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Confluence Cloud has no built-in pagination — pages render as one long scroll and tables render every row. The three working approaches: **split long content into a page series** and connect the parts with Previous/Next buttons ([Pagination Buttons for Confluence](https://marketplace.atlassian.com/apps/1237371/pagination-buttons-for-confluence/)), **chunk in-page** with tabs or expand sections, or **restructure** so the long table becomes linked category pages. What Confluence does paginate natively is search results and API responses — not your content. A 4,000-word runbook. A 300-row release checklist. A training doc with five chapters. Sooner or later every Confluence space hits the wall: the page that takes forever to scroll, buries the section the reader needs, and times out in the editor when someone tries to reorganize it. Pagination is the standard fix everywhere else on the web — and Confluence doesn't have it, a gap the community has flagged since 2018. Here's what actually works instead. What you'll learn 1. What Confluence paginates natively (search, API) and what it doesn't (pages, tables) 2. Method 1 — split into a page series with Prev/Next buttons 3. Method 2 — chunk in-page with tabs and expand sections 4. Method 3 — restructure long tables instead of paginating them **Tags:** * [confluence](/blog/tags/confluence.md) * [pagination](/blog/tags/pagination.md) * [macros](/blog/tags/macros.md) * [formatting](/blog/tags/formatting.md) * [page-structure](/blog/tags/page-structure.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/confluence-pagination.md) --- ## [How to Create Math and Technical Animations in Confluence Using Manim](/blog/how-to-create-math-animations-confluence.md) May 2, 2026 · 23 min read [NGPilot](https://ngpilot.com) Mathematical concepts are inherently dynamic. A limit converges, a derivative emerges from shrinking secant lines, a matrix transformation rotates a vector through space. Static screenshots and LaTeX formulas capture the result but miss the process -- and for many students and colleagues, the process is where understanding lives. Animations bridge that gap. They show how equations transform, how geometric constructions unfold step by step, and how abstract algebra connects to visual intuition. Until recently, embedding math animations in documentation required a multi-tool workflow: write Python scripts with Manim, render MP4 files locally, upload them as attachments or embed them via external hosting, and hope nobody asked you to update them. Manim for Confluence eliminates that entire pipeline. You write animation code directly inside a Confluence macro, and the animation plays inline on the published page -- no file exports, no external hosting, no broken links when the video expires. **Tags:** * [confluence](/blog/tags/confluence.md) * [manim](/blog/tags/manim.md) * [animation](/blog/tags/animation.md) * [math](/blog/tags/math.md) * [how-to](/blog/tags/how-to.md) * [education](/blog/tags/education.md) [**Read more**](/blog/how-to-create-math-animations-confluence.md) --- ## [Monospace in Confluence: How to Format Inline Code (Shortcuts & Markdown)](/blog/confluence-monospace.md) October 1, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Select the text and press **Ctrl+Shift+M** (Windows) or **Opt+Shift+M** (Mac) to apply inline code, or type `` `backticks` `` around text as you write — the Confluence Cloud editor autoformats them. Pasted Markdown keeps its backticks as literal characters, so paste into [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence/) instead, which renders inline code, code blocks, and diagrams from your Markdown source. Inline code — monospace text on a subtle background — is how you mark up variable names, file paths, key names, and short commands inside a sentence: set `MAX_RETRIES = 3`, edit `~/.zshrc`, or run `kubectl get pods`. Confluence Cloud has three ways to produce it, and each fits a different moment: formatting as you go, typing Markdown, or bringing Markdown in from your repo. What you'll learn 1. The keyboard shortcut — Ctrl+Shift+M, and the Mac split between Opt+Shift+M and Cmd+Shift+M 2. Backtick autoformatting while you type 3. The Markdown method for pasted content (Enhanced Markdown) 4. Inline code vs code block — which one to use where **Tags:** * [confluence](/blog/tags/confluence.md) * [formatting](/blog/tags/formatting.md) * [markdown](/blog/tags/markdown.md) * [monospace](/blog/tags/monospace.md) * [inline-code](/blog/tags/inline-code.md) * [enhanced-markdown](/blog/tags/enhanced-markdown.md) * [keyboard-shortcuts](/blog/tags/keyboard-shortcuts.md) [**Read more**](/blog/confluence-monospace.md) --- ## [How to Write Markdown in Confluence — Syntax, Tables & Code Blocks](/blog/faq-confluence-markdown-editor.md) May 2, 2026 · 13 min read [NGPilot](https://ngpilot.com) Who should read this * **Developers and tech writers** who want to write Markdown in Confluence instead of the WYSIWYG editor * **Teams migrating** README files, docs repos, or API references into Confluence * **Anyone** who needs Mermaid diagrams or LaTeX math inside Markdown content What you'll learn 1. Whether Confluence supports Markdown natively (and why it doesn't) 2. How to write Markdown with live preview, including code blocks, tables, and Mermaid 3. How Markdown content behaves after publish (search, exports, permissions) 4. When to use Markdown vs. Confluence's native WYSIWYG editor Confluence's built-in editor is strictly WYSIWYG — there is no native Markdown editor. For teams who already write in Markdown (README files, docs repos, pull request descriptions), that means manually reformatting every doc through toolbar buttons, losing time and introducing inconsistencies. **Enhanced Markdown for Confluence** solves this by embedding a full Markdown editor with live split preview directly inside Confluence — and it renders Mermaid diagrams, KaTeX/LaTeX math, and 190+ code-highlighted languages, all in one macro. This FAQ answers the questions teams ask most often about writing Markdown in Confluence. **Tags:** * [faq](/blog/tags/faq.md) * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [markdown-editor](/blog/tags/markdown-editor.md) * [writing](/blog/tags/writing.md) [**Read more**](/blog/faq-confluence-markdown-editor.md) --- ## [How to Make Text Bold or Strikethrough in Confluence (Ctrl+B, Toolbar & Markdown)](/blog/bold-text-confluence.md) August 11, 2026 · 3 min read [NGPilot](https://ngpilot.com) **Bold text** is one of the most common formatting actions in Confluence — for headings, callouts, and emphasis inside paragraphs. There are two ways to do it: the toolbar button / keyboard shortcut in the standard editor, and Markdown syntax inside [Enhanced Markdown for Confluence](/apps/enhanced-markdown-for-confluence.md). This guide covers both, plus the common "why isn't it working" cases. What you'll learn 1. The standard editor method — B button or Ctrl+B / Cmd+B 2. The Markdown method — `**bold**` syntax 3. Bold vs italic vs strikethrough 4. Fixing bold that renders as literal asterisks **Tags:** * [confluence](/blog/tags/confluence.md) * [formatting](/blog/tags/formatting.md) * [markdown](/blog/tags/markdown.md) * [bold](/blog/tags/bold.md) * [enhanced-markdown](/blog/tags/enhanced-markdown.md) * [keyboard-shortcuts](/blog/tags/keyboard-shortcuts.md) [**Read more**](/blog/bold-text-confluence.md) --- ## [Best Confluence Import/Export Apps Compared — 2026 Guide](/blog/confluence-import-export-comparison.md) April 18, 2026 · 7 min read [NGPilot](https://ngpilot.com) Teams move content in and out of Confluence every day — migrating between instances, backing up documentation, importing from other tools, exporting for offline review. Confluence has basic PDF and HTML export built in, but it's limited. No bulk operations, no multi-format support, no structured import workflow. Over a dozen marketplace apps try to fill this gap, but most solve one narrow problem: PDF export, Word import, or Markdown conversion. We built **Modern Importer & Exporter for Confluence** to handle both directions — import and export — across multiple formats. In this post we compare it against every alternative on the Atlassian Marketplace. **Tags:** * [import](/blog/tags/import.md) * [export](/blog/tags/export.md) * [confluence](/blog/tags/confluence.md) * [migration](/blog/tags/migration.md) * [backup](/blog/tags/backup.md) * [markdown](/blog/tags/markdown.md) * [pdf](/blog/tags/pdf.md) * [word](/blog/tags/word.md) * [content-transfer](/blog/tags/content-transfer.md) [**Read more**](/blog/confluence-import-export-comparison.md) --- ## [Forge vs Connect: What Atlassian Admins Need to Know in 2026](/blog/forge-vs-connect-atlassian-admins-2026.md) August 2, 2026 · 10 min read [NGPilot](https://ngpilot.com) Quick Answer Forge and Connect are the two frameworks Atlassian Marketplace apps can be built on. **Forge** runs on Atlassian's own infrastructure; **Connect** runs on vendor-hosted servers. Starting January 1, 2026, Atlassian applies a penalty to Connect apps in Marketplace rankings and requires Forge for new Cloud Fortified status. For admins evaluating apps in 2026, Forge is the safer, more future-proof choice where a capable option exists. What you'll learn 1. The real architectural difference between Forge and Connect 2. What the 2026 Connect penalty changes for app discovery and trust 3. How to tell which framework an app uses before you install it 4. A practical decision framework for evaluating apps in 2026 If you administer Jira or Confluence Cloud, every app you install from the Marketplace runs on one of two frameworks: **Forge** or **Connect**. For years the difference was mostly an implementation detail that admins could ignore. In 2026 that changed. The Connect penalty, the Cloud Fortified requirement, and Atlassian's clear strategic direction mean the framework an app uses now affects its security posture, its discoverability, and how long it will keep working. This guide explains what changed, why it matters, and how to make better app decisions because of it. **Tags:** * [atlassian](/blog/tags/atlassian.md) * [forge](/blog/tags/forge.md) * [connect](/blog/tags/connect.md) * [marketplace](/blog/tags/marketplace.md) * [explained](/blog/tags/explained.md) * [admin](/blog/tags/admin.md) [**Read more**](/blog/forge-vs-connect-atlassian-admins-2026.md) --- ## [Math Equations in Confluence: LaTeX & KaTeX via Markdown](/blog/markdown-math-equations-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) Ask an engineer to document an algorithm in Confluence and watch what happens to the math: `O(n log n)` typed as plain text, `x²` pasted from a character map, and — for anything real — a screenshot from an online equation editor, blurry and already out of date. Confluence has no native LaTeX support, so every formula becomes either a compromise or an image. It does not have to. With a Markdown macro on the page, Confluence renders real LaTeX — inline `$...$`, display `$$...$$`, fenced blocks with full `align` environments — and the equation stays text: searchable, theme-consistent, editable in seconds. This guide gives you the syntax and copy-paste examples for all three routes. **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [latex](/blog/tags/latex.md) * [katex](/blog/tags/katex.md) * [mathjax](/blog/tags/mathjax.md) * [math](/blog/tags/math.md) * [how-to](/blog/tags/how-to.md) * [engineering](/blog/tags/engineering.md) [**Read more**](/blog/markdown-math-equations-confluence.md) --- ## [Math Equations in Confluence: LaTeX & KaTeX via Markdown](/blog/markdown-math-equations-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) Ask an engineer to document an algorithm in Confluence and watch what happens to the math: `O(n log n)` typed as plain text, `x²` pasted from a character map, and — for anything real — a screenshot from an online equation editor, blurry and already out of date. Confluence has no native LaTeX support, so every formula becomes either a compromise or an image. It does not have to. With a Markdown macro on the page, Confluence renders real LaTeX — inline `$...$`, display `$$...$$`, fenced blocks with full `align` environments — and the equation stays text: searchable, theme-consistent, editable in seconds. This guide gives you the syntax and copy-paste examples for all three routes. **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [latex](/blog/tags/latex.md) * [katex](/blog/tags/katex.md) * [mathjax](/blog/tags/mathjax.md) * [math](/blog/tags/math.md) * [how-to](/blog/tags/how-to.md) * [engineering](/blog/tags/engineering.md) [**Read more**](/blog/markdown-math-equations-confluence.md) --- ## [Meeting Notes in Confluence with Markdown (Copy-Paste Template)](/blog/markdown-meeting-notes-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) Meeting notes fail in one of two directions: they are so informal that nobody can find the decision a month later, or so formal that nobody takes them at all. The Confluence editor quietly encourages the second — formatting dialogs are the enemy of live note-taking. Markdown flips it. In a split-pane editor, notes are keystrokes: two characters for a heading, pipes for a table row, backticks for a snippet — and the rendered page assembles itself in the right pane while you type. This guide ships the template and the habits that make notes pages worth opening later. **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [meeting-notes](/blog/tags/meeting-notes.md) * [template](/blog/tags/template.md) * [how-to](/blog/tags/how-to.md) * [productivity](/blog/tags/productivity.md) * [engineering](/blog/tags/engineering.md) [**Read more**](/blog/markdown-meeting-notes-confluence.md) --- ## [Mermaid AI Agent for Confluence: Create, Update & Convert Diagrams by Chat](/blog/mermaid-ai-agent-confluence.md) October 7, 2026 · 5 min read [NGPilot](https://ngpilot.com) Confluence chat can write your page, summarize the thread, and answer questions about the space. What it couldn't do — until now — is draw. If you asked for "a flowchart of our deployment process," you got a text description of a flowchart, and someone still had to open an editor and build it. The AI agent in [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence) closes that gap: it creates, reads, updates, and converts Mermaid diagrams directly on Confluence pages and blog posts, from chat. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [diagrams](/blog/tags/diagrams.md) * [ai](/blog/tags/ai.md) * [how-to](/blog/tags/how-to.md) * [agent](/blog/tags/agent.md) [**Read more**](/blog/mermaid-ai-agent-confluence.md) --- ## [Paste Mermaid Diagrams into Confluence — Now on Mermaid 12](/blog/paste-mermaid-diagrams-into-confluence.md) September 28, 2026 · 9 min read [NGPilot](https://ngpilot.com) Quick Answer Confluence's editor is WYSIWYG and has no Mermaid renderer, so pasting a Markdown file that contains ` ```mermaid ` fences imports them as plain code blocks — the diagrams arrive dead. Paste into a Markdown macro instead: [**Enhanced Markdown for Confluence**](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence/) renders Mermaid 12 inline, so a whole README pastes in and the diagrams come alive. The v12 upgrade is what makes this newly worthwhile — **UML use case diagrams** now survive the paste, which is the diagram type requirements docs kept losing. What you'll learn 1. Why Mermaid dies on the way into Confluence, and where the fix lives 2. The paste workflow: repo Markdown in, rendered diagrams out 3. What Mermaid 12 changes — use case diagrams, refreshed layout, richer ZenUML 4. What happens to diagrams you already published The diagrams live in the repository. They were written in Mermaid, they are reviewed in pull requests next to the code they describe, and they are correct as of the last commit. The documentation, however, lives in Confluence — because that is where the rest of the team reads it. So somebody copies a Markdown file across, pastes it into a Confluence page, and the flowcharts, sequence diagrams and ER models arrive as grey boxes of unrendered code. Everyone has hit this. It is one of the most common Confluence complaints, and the usual workarounds are worse than the problem: export every diagram to PNG and re-upload them (now they rot), keep the diagrams in an external tool and paste links (readers need a second account, and the links break), or build a browser extension to force rendering on paste. There is a better answer, and Mermaid 12 makes it better still. **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [mermaid](/blog/tags/mermaid.md) * [mermaid-12](/blog/tags/mermaid-12.md) * [usecase-diagram](/blog/tags/usecase-diagram.md) * [how-to](/blog/tags/how-to.md) * [developer-tools](/blog/tags/developer-tools.md) [**Read more**](/blog/paste-mermaid-diagrams-into-confluence.md) --- ## [Root Cause Analysis in Confluence with Mermaid Fishbone + 5 Whys](/blog/mermaid-fishbone-root-cause-analysis-confluence.md) September 24, 2026 · 7 min read [NGPilot](https://ngpilot.com) A root cause analysis is only as good as the disagreement it survives. When the 'root cause' box on your postmortem template contains one sentence, the meeting spends an hour relitigating that sentence. A fishbone diagram and a 5 Whys chain move the argument onto a diagram: everyone sees which categories were considered, which branch was chosen, and exactly how the 'why' answers arrive at a root cause. Confluence is where RCA already happens — in the Root Cause Analysis template, in postmortems, in retros. The missing piece is a diagram that holds the reasoning. This guide shows you two copy-paste Mermaid diagrams: an `ishikawa` fishbone that maps every candidate cause category, and a `flowchart` 5-Whys drilldown that lands on one concrete fix. **Tags:** * [root-cause-analysis](/blog/tags/root-cause-analysis.md) * [fishbone](/blog/tags/fishbone.md) * [ishikawa](/blog/tags/ishikawa.md) * [5-whys](/blog/tags/5-whys.md) * [mermaid](/blog/tags/mermaid.md) * [confluence](/blog/tags/confluence.md) * [postmortem](/blog/tags/postmortem.md) * [how-to](/blog/tags/how-to.md) * [incident-management](/blog/tags/incident-management.md) [**Read more**](/blog/mermaid-fishbone-root-cause-analysis-confluence.md) --- ## [Map States & Approval Workflows in Confluence with Mermaid](/blog/mermaid-state-diagram-workflow-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The issue workflow lives in a wiki page that says "the approval chain is: team lead, then manager, then finance". The config says otherwise, the Jira post-function disagrees, and the incident report asks "who actually approved this?" — with three different answers on screen. A prose paragraph cannot hold a workflow; a diagram can, if it *is* the workflow. **Quick answer:** document state machines and approval chains in Confluence as Mermaid `stateDiagram-v2`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Every legal state, every transition, every human decision on a labeled arrow — in editable text that stays true. This post gives you three copy-paste examples: an issue lifecycle, a spending approval chain, and a retry loop with a timeout. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [state-diagram](/blog/tags/state-diagram.md) * [workflow](/blog/tags/workflow.md) * [approval](/blog/tags/approval.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-state-diagram-workflow-confluence.md) --- ## [Drawing vs Diagramming in Confluence — Canvas vs Text vs Graph](/blog/confluence-drawing-diagramming-tools.md) May 6, 2026 · 5 min read [NGPilot](https://ngpilot.com) Adding diagrams to Confluence pages helps teams communicate architecture, processes, and workflows visually. This guide covers the three main approaches to creating diagrams in Confluence and helps you choose the right tool for your needs. **Tags:** * [confluence](/blog/tags/confluence.md) * [diagrams](/blog/tags/diagrams.md) * [drawing](/blog/tags/drawing.md) * [mermaid](/blog/tags/mermaid.md) * [excalidraw](/blog/tags/excalidraw.md) * [graphviz](/blog/tags/graphviz.md) * [comparison](/blog/tags/comparison.md) [**Read more**](/blog/confluence-drawing-diagramming-tools.md) --- ## [Create Mind Maps in Confluence — Free with Mermaid Plus](/blog/how-to-create-mindmaps-confluence.md) May 2, 2026 · 12 min read [NGPilot](https://ngpilot.com) Mind maps are one of the most effective ways to capture ideas, organize thoughts, and brainstorm with a team. Unlike linear notes or bullet lists, mind maps radiate outward from a central topic, making it easy to see relationships between concepts at a glance. If your team already uses Confluence for documentation, meeting notes, and project planning, adding mind maps directly to your Confluence pages keeps brainstorming sessions alongside the rest of your team's knowledge. In this tutorial, you will learn how to create mind maps in Confluence using Mermaid syntax and the Mermaid Plus Diagrams & AI Agent for Confluence app. Every example is copy-paste ready, so you can drop it straight into a Confluence page and start organizing your ideas immediately. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [mindmap](/blog/tags/mindmap.md) * [how-to](/blog/tags/how-to.md) * [diagrams](/blog/tags/diagrams.md) * [brainstorming](/blog/tags/brainstorming.md) [**Read more**](/blog/how-to-create-mindmaps-confluence.md) --- ## [Import Markdown into Confluence: Paste, GitHub, .md Files](/blog/import-markdown-into-confluence.md) September 24, 2026 · 3 min read [NGPilot](https://ngpilot.com) Every team has Markdown lying around that Confluence needs: the README that became the service doc, the design doc drafted as a pull-request description, the runbook that lives in the repo. And every attempt to move it hits the same wall — Confluence's default editor does not parse Markdown. Paste a .md document and you get a wall of pipes, backticks, and asterisks that looks exactly like what it is: text nobody formatted. The macro route dissolves the wall. Paste the document into a Markdown macro that actually parses it, watch it render in the preview pane, publish. This page is the workflow, end to end. **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [import](/blog/tags/import.md) * [migration](/blog/tags/migration.md) * [github](/blog/tags/github.md) * [how-to](/blog/tags/how-to.md) * [developer-tools](/blog/tags/developer-tools.md) [**Read more**](/blog/import-markdown-into-confluence.md) --- ## [Mind Maps & Hierarchy Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-mindmap-hierarchy-diagram-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The kickoff note is 40 lines of indented bullets with three levels of bolded sub-points, and half the room is still asking "so what are we actually deciding today?" The other half is screenshotting a mind map someone whiteboarded in five minutes. The whiteboard died at cleanup; the bullets survived but nobody can navigate them. A mind map is the *readable* version of nested notes — and when it lives in Confluence as Mermaid text, it survives the meeting. **Quick answer:** turn nested notes into a Mermaid `mindmap` in Confluence, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). The indented text you already write becomes the branches; for concrete structures — folder layouts, project trees — use `treeView`; when item size matters and you want area instead of lines, use `treemap`. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [mindmap](/blog/tags/mindmap.md) * [treeview](/blog/tags/treeview.md) * [treemap](/blog/tags/treemap.md) * [brainstorming](/blog/tags/brainstorming.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-mindmap-hierarchy-diagram-confluence.md) --- ## [How to Create Wireframes and UI Mockups in Confluence with Excalidraw Plus](/blog/how-to-create-wireframes-confluence.md) May 2, 2026 · 15 min read [NGPilot](https://ngpilot.com) Wireframes are the backbone of every user interface design process. They let product managers, designers, and engineers align on layout, content hierarchy, and interaction flow before writing a single line of code. With [Excalidraw Plus for Confluence](/docs/Excalidraw-plus-for-Confluence/usage.md), you can create wireframes and UI mockups directly inside your Confluence pages, keeping design artifacts next to requirements, user stories, and technical specs. **Tags:** * [confluence](/blog/tags/confluence.md) * [excalidraw](/blog/tags/excalidraw.md) * [wireframe](/blog/tags/wireframe.md) * [mockup](/blog/tags/mockup.md) * [how-to](/blog/tags/how-to.md) * [ui-design](/blog/tags/ui-design.md) [**Read more**](/blog/how-to-create-wireframes-confluence.md) --- ## [Dark Mode for Confluence Code Blocks — Setup Walkthrough](/blog/confluence-code-editor-syntax-highlighting.md) May 6, 2026 · 4 min read [NGPilot](https://ngpilot.com) Confluence's built-in code block macro is limited — it supports roughly 30 languages, has no dark theme, and lacks basic features like copy buttons and collapsible sections. If your team writes documentation with code snippets, you need something better. This guide shows how to add a VS Code-grade code editor to Confluence with syntax highlighting for 85+ languages, automatic dark/light theme detection, and one-click copy buttons. **Tags:** * [confluence](/blog/tags/confluence.md) * [code-blocks](/blog/tags/code-blocks.md) * [syntax-highlighting](/blog/tags/syntax-highlighting.md) * [dark-mode](/blog/tags/dark-mode.md) * [monaco-editor](/blog/tags/monaco-editor.md) * [developers](/blog/tags/developers.md) [**Read more**](/blog/confluence-code-editor-syntax-highlighting.md) --- ## [Monospace in Confluence: How to Format Inline Code (Shortcuts & Markdown)](/blog/confluence-monospace.md) October 1, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Select the text and press **Ctrl+Shift+M** (Windows) or **Opt+Shift+M** (Mac) to apply inline code, or type `` `backticks` `` around text as you write — the Confluence Cloud editor autoformats them. Pasted Markdown keeps its backticks as literal characters, so paste into [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence/) instead, which renders inline code, code blocks, and diagrams from your Markdown source. Inline code — monospace text on a subtle background — is how you mark up variable names, file paths, key names, and short commands inside a sentence: set `MAX_RETRIES = 3`, edit `~/.zshrc`, or run `kubectl get pods`. Confluence Cloud has three ways to produce it, and each fits a different moment: formatting as you go, typing Markdown, or bringing Markdown in from your repo. What you'll learn 1. The keyboard shortcut — Ctrl+Shift+M, and the Mac split between Opt+Shift+M and Cmd+Shift+M 2. Backtick autoformatting while you type 3. The Markdown method for pasted content (Enhanced Markdown) 4. Inline code vs code block — which one to use where **Tags:** * [confluence](/blog/tags/confluence.md) * [formatting](/blog/tags/formatting.md) * [markdown](/blog/tags/markdown.md) * [monospace](/blog/tags/monospace.md) * [inline-code](/blog/tags/inline-code.md) * [enhanced-markdown](/blog/tags/enhanced-markdown.md) * [keyboard-shortcuts](/blog/tags/keyboard-shortcuts.md) [**Read more**](/blog/confluence-monospace.md) --- ## [Confluence Page Navigation FAQ: TOC, Numbered Headings & Structure](/blog/faq-confluence-page-navigation-apps.md) May 2, 2026 · 15 min read [NGPilot](https://ngpilot.com) Page navigation is one of those things that nobody notices when it works well and everyone complains about when it does not. In Confluence, where pages routinely grow to thousands of words — technical specifications, onboarding guides, compliance documentation, project charters — helping readers find the right section quickly is not a nice-to-have. It is the difference between a knowledge base that people use and one that people ignore. **Tags:** * [faq](/blog/tags/faq.md) * [confluence](/blog/tags/confluence.md) * [navigation](/blog/tags/navigation.md) * [toc](/blog/tags/toc.md) * [numbered-headings](/blog/tags/numbered-headings.md) [**Read more**](/blog/faq-confluence-page-navigation-apps.md) --- ## [How to Set Up Announcement Banners in Jira (Rich Text, Scheduling & Targeting)](/blog/set-up-announcement-banners-jira.md) July 23, 2026 · 6 min read [NGPilot](https://ngpilot.com) Who should read this * **Jira admins** who need to broadcast maintenance windows, outages, or policy changes * **IT/ops teams** that want dismissible vs. persistent banner control * **Anyone** frustrated by Jira's plain-text native banner limitations What you'll learn 1. How to create a Jira announcement banner with rich text and emojis 2. Choosing dismissible vs. persistent banners (and when each fits) 3. Managing a library of announcements for quick reuse 4. How this compares to Jira's built-in banner and to Confluence banners The scenario every Jira admin hits: there's a maintenance window Saturday night, a security policy change, or an ongoing incident — and you need every person who opens Jira to see it immediately. Jira has a built-in announcement banner, but it's plain-text only, lives in a buried admin setting, and gives you one banner at a time with no library, no scheduling, and no way to let users dismiss it. [**Modern Announcement Banner for Jira**](https://marketplace.atlassian.com/apps/194301976/modern-announcement-banner-for-jira) fixes this: rich-text banners with emojis and custom colors, a dismissible option, a saved library of announcements you can switch between with one click, and instant enable/disable without deleting. This guide walks through setting it up. **Tags:** * [jira](/blog/tags/jira.md) * [announcement-banner](/blog/tags/announcement-banner.md) * [notification](/blog/tags/notification.md) * [how-to](/blog/tags/how-to.md) * [admin](/blog/tags/admin.md) [**Read more**](/blog/set-up-announcement-banners-jira.md) --- ## [How to Auto-Number Headings in Confluence (H1–H6, With Live Preview)](/blog/auto-number-headings-confluence.md) July 23, 2026 · 6 min read [NGPilot](https://ngpilot.com) Who should read this * **Technical writers** building structured documentation in Confluence * **Compliance teams** who need formal numbered sections (1.1, 1.2, 1.2.1) * **Anyone** tired of manually typing and re-numbering headings when content moves What you'll learn 1. Why Confluence doesn't number headings natively (and why manual numbering breaks) 2. How to auto-number H1-H6 with 5 styles (Decimal, Roman, Alphabetic, …) 3. Choosing heading levels and hierarchical indentation 4. Maintaining numbering when you add, remove, or reorder sections The scenario every documentation team hits: you're writing a policy doc or technical spec in Confluence, and it needs numbered sections — `1. Introduction`, `1.1 Overview`, `1.2 Getting Started`, `2. Configuration`. So you type the numbers manually into each heading. Then product changes the structure: a section moves up, a new one gets inserted in the middle, and now every number below the change is wrong. You spend twenty minutes renumbering by hand, miss one, and the doc ships with `1.2` followed by `1.4`. Confluence has no native heading-numbering feature. Headings are just styled text — there's no automatic `1.1` / `1.2` scheme. [**Modern Numbered Headings for Confluence**](https://marketplace.atlassian.com/apps/2096741841/modern-numbered-headings-for-confluence) fixes this by generating numbered headings automatically from your H1-H6 structure, with a live preview and five numbering styles. When you reorder sections, the numbers update. This guide walks through setting it up. **Tags:** * [confluence](/blog/tags/confluence.md) * [numbered-headings](/blog/tags/numbered-headings.md) * [table-of-contents](/blog/tags/table-of-contents.md) * [how-to](/blog/tags/how-to.md) * [documentation](/blog/tags/documentation.md) [**Read more**](/blog/auto-number-headings-confluence.md) --- ## [API Sequence Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-api-sequence-diagram-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The integration doc says "the client calls the API, the API validates and responds" — four words, zero contracts, and the onboarding engineer asks "with what headers, in what order, and what if auth fails?" The code has the truth; the wiki has a paragraph. An API that can't be read as a transcript is an API nobody can safely operate. **Quick answer:** document API flows in Confluence as Mermaid — `sequenceDiagram` for request/response order, `packet-beta` for wire-format frames, ZenUML for branch-heavy async flows — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Each diagram type answers a different reader: what order, what's on the wire, what branches. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [sequence-diagram](/blog/tags/sequence-diagram.md) * [packet](/blog/tags/packet.md) * [zenuml](/blog/tags/zenuml.md) * [api](/blog/tags/api.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-api-sequence-diagram-confluence.md) --- ## [Build Modern Confluence Pages in 2026: Hero Sections & QR Codes](/blog/build-modern-confluence-pages-hero-articles-qr-forms.md) July 31, 2026 · 9 min read [NGPilot](https://ngpilot.com) Who should read this * **Confluence admins and space owners** who want their intranet, portal, or knowledge base to look professional * **Marketing and product teams** building landing pages, announcements, and product updates in Confluence * **Anyone** who has ever thought "I know what I want this page to look like — I just can't make Confluence do it" What you'll learn 1. How to make a Confluence page read like Medium (drop caps, clean typography, bilingual mode) 2. How to add a proper hero section with CTAs — something the native editor doesn't have 3. How to style tables without fighting the editor 4. How to add QR codes, collect survey responses, and define glossary terms inline — all without external tools Take a look at your most-visited Confluence page right now. Does it look like it belongs on the modern web — or does it look like internal documentation from 2015? If your answer is the latter, you're not alone. Teams across thousands of Confluence sites tell us the same story: "I know exactly what I want my page to look like. I just can't make Confluence do it." In this guide, we'll show you six concrete ways to level up your Confluence pages — from Medium-style reading layouts to interactive surveys — all without leaving your editor. **Tags:** * [confluence](/blog/tags/confluence.md) * [page-builder](/blog/tags/page-builder.md) * [macros](/blog/tags/macros.md) * [how-to](/blog/tags/how-to.md) * [productivity](/blog/tags/productivity.md) [**Read more**](/blog/build-modern-confluence-pages-hero-articles-qr-forms.md) --- ## [Confluence Pagination: How to Paginate Pages and Tables (3 Methods)](/blog/confluence-pagination.md) October 4, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Confluence Cloud has no built-in pagination — pages render as one long scroll and tables render every row. The three working approaches: **split long content into a page series** and connect the parts with Previous/Next buttons ([Pagination Buttons for Confluence](https://marketplace.atlassian.com/apps/1237371/pagination-buttons-for-confluence/)), **chunk in-page** with tabs or expand sections, or **restructure** so the long table becomes linked category pages. What Confluence does paginate natively is search results and API responses — not your content. A 4,000-word runbook. A 300-row release checklist. A training doc with five chapters. Sooner or later every Confluence space hits the wall: the page that takes forever to scroll, buries the section the reader needs, and times out in the editor when someone tries to reorganize it. Pagination is the standard fix everywhere else on the web — and Confluence doesn't have it, a gap the community has flagged since 2018. Here's what actually works instead. What you'll learn 1. What Confluence paginates natively (search, API) and what it doesn't (pages, tables) 2. Method 1 — split into a page series with Prev/Next buttons 3. Method 2 — chunk in-page with tabs and expand sections 4. Method 3 — restructure long tables instead of paginating them **Tags:** * [confluence](/blog/tags/confluence.md) * [pagination](/blog/tags/pagination.md) * [macros](/blog/tags/macros.md) * [formatting](/blog/tags/formatting.md) * [page-structure](/blog/tags/page-structure.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/confluence-pagination.md) --- ## [Confluence Pagination: How to Paginate Pages and Tables (3 Methods)](/blog/confluence-pagination.md) October 4, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Confluence Cloud has no built-in pagination — pages render as one long scroll and tables render every row. The three working approaches: **split long content into a page series** and connect the parts with Previous/Next buttons ([Pagination Buttons for Confluence](https://marketplace.atlassian.com/apps/1237371/pagination-buttons-for-confluence/)), **chunk in-page** with tabs or expand sections, or **restructure** so the long table becomes linked category pages. What Confluence does paginate natively is search results and API responses — not your content. A 4,000-word runbook. A 300-row release checklist. A training doc with five chapters. Sooner or later every Confluence space hits the wall: the page that takes forever to scroll, buries the section the reader needs, and times out in the editor when someone tries to reorganize it. Pagination is the standard fix everywhere else on the web — and Confluence doesn't have it, a gap the community has flagged since 2018. Here's what actually works instead. What you'll learn 1. What Confluence paginates natively (search, API) and what it doesn't (pages, tables) 2. Method 1 — split into a page series with Prev/Next buttons 3. Method 2 — chunk in-page with tabs and expand sections 4. Method 3 — restructure long tables instead of paginating them **Tags:** * [confluence](/blog/tags/confluence.md) * [pagination](/blog/tags/pagination.md) * [macros](/blog/tags/macros.md) * [formatting](/blog/tags/formatting.md) * [page-structure](/blog/tags/page-structure.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/confluence-pagination.md) --- ## [Best Confluence Import/Export Apps Compared — 2026 Guide](/blog/confluence-import-export-comparison.md) April 18, 2026 · 7 min read [NGPilot](https://ngpilot.com) Teams move content in and out of Confluence every day — migrating between instances, backing up documentation, importing from other tools, exporting for offline review. Confluence has basic PDF and HTML export built in, but it's limited. No bulk operations, no multi-format support, no structured import workflow. Over a dozen marketplace apps try to fill this gap, but most solve one narrow problem: PDF export, Word import, or Markdown conversion. We built **Modern Importer & Exporter for Confluence** to handle both directions — import and export — across multiple formats. In this post we compare it against every alternative on the Atlassian Marketplace. **Tags:** * [import](/blog/tags/import.md) * [export](/blog/tags/export.md) * [confluence](/blog/tags/confluence.md) * [migration](/blog/tags/migration.md) * [backup](/blog/tags/backup.md) * [markdown](/blog/tags/markdown.md) * [pdf](/blog/tags/pdf.md) * [word](/blog/tags/word.md) * [content-transfer](/blog/tags/content-transfer.md) [**Read more**](/blog/confluence-import-export-comparison.md) --- ## [Google Fonts for Confluence: Performance Impact & FAQ](/blog/faq-google-fonts-performance.md) April 21, 2026 · 10 min read [NGPilot](https://ngpilot.com) **Tags:** * [faq](/blog/tags/faq.md) * [google-fonts](/blog/tags/google-fonts.md) * [confluence](/blog/tags/confluence.md) * [typography](/blog/tags/typography.md) * [performance](/blog/tags/performance.md) [**Read more**](/blog/faq-google-fonts-performance.md) --- ## [Confluence Permissions: The Ultimate Guide (2026)](/blog/confluence-permissions-ultimate-guide-2026.md) July 30, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Confluence permissions control who can view, edit, and administer content. You manage permissions at three levels: **site admin** (global), **space admin** (space-level), and **page restrictions** (page-level). Understanding the inheritance hierarchy is key — lower-level settings always override higher-level ones. **Tags:** * [confluence](/blog/tags/confluence.md) * [confluence-admin](/blog/tags/confluence-admin.md) * [permissions](/blog/tags/permissions.md) * [security](/blog/tags/security.md) * [atlassian](/blog/tags/atlassian.md) [**Read more**](/blog/confluence-permissions-ultimate-guide-2026.md) --- ## [Mermaid Charts for Confluence Dashboards: Pie & XY in One Post](/blog/mermaid-charts-dashboard-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The quarterly review loads a 14-tab spreadsheet to answer one question — "where do we actually spend our engineering time?" — because the wiki charts are stale screenshots from last quarter and the numbers table nobody reads. A dashboard is not a spreadsheet: it is the two charts that answer the two questions people keep asking. **Quick answer:** build dashboard charts in Confluence with Mermaid `pie` and `xychart-beta` charts, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Pie for shares, XY for trends — both as editable text that refreshes like code. This post gives you three copy-paste examples: an effort-share pie, a weekly trend XY, and a dual-series release dashboard. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [pie-chart](/blog/tags/pie-chart.md) * [xychart-beta](/blog/tags/xychart-beta.md) * [dashboard](/blog/tags/dashboard.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-charts-dashboard-confluence.md) --- ## [Roadmap & Prioritization Charts in Confluence with Mermaid](/blog/mermaid-roadmap-prioritization-charts-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The quarter plan is a spreadsheet with thirty rows, color-coded by priority, sorted by a column half the team doesn't trust. The kickoff asks "what are we doing when — and why this first?" and the answer requires parsing three tabs. Planning outputs are *shapes*: schedules stack as bars, priorities sit on a 2x2, flows bundle as ribbons. The spreadsheet stores them poorly; Mermaid draws them as text. **Quick answer:** put the quarter plan in Confluence as Mermaid — `gantt` for when things happen, `quadrantChart` for which gets built first, `sankey-beta` for where the budget goes — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Three charts, three planning questions, one editable page. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [gantt](/blog/tags/gantt.md) * [quadrant](/blog/tags/quadrant.md) * [sankey](/blog/tags/sankey.md) * [roadmap](/blog/tags/roadmap.md) * [planning](/blog/tags/planning.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-roadmap-prioritization-charts-confluence.md) --- ## [Mermaid vs PlantUML vs Graphviz for Confluence: Which Diagram Tool to Choose](/blog/mermaid-vs-plantuml-vs-graphviz-confluence.md) August 2, 2026 · 7 min read [NGPilot](https://ngpilot.com) Quick Answer Mermaid, PlantUML, and Graphviz are the three most popular text-based diagramming languages. **Mermaid** is the easiest to learn and covers the widest range (30 diagram types). **PlantUML** excels at detailed UML with precise notation control. **Graphviz** is best for technical network and dependency graphs. Most Confluence teams should start with Mermaid and add Graphviz for network diagrams if needed. What you'll learn 1. The strengths and weaknesses of each tool 2. Which diagram types each one supports 3. How easy each is to learn and use 4. A practical recommendation for Confluence teams Text-based diagramming — writing a few lines of code that render into a diagram — is how modern teams keep diagrams in sync with their documentation. No more drawing boxes by hand in Visio, exporting screenshots, and pasting them into Confluence where they go stale. With text-based diagrams, you edit the source and the diagram redraws instantly. But there are three major text-based diagramming languages, and they are not interchangeable. Each has different strengths, different syntax, and different ideal use cases. This guide compares Mermaid, PlantUML, and Graphviz so you can choose the right one (or combination) for your Confluence team. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [plantuml](/blog/tags/plantuml.md) * [graphviz](/blog/tags/graphviz.md) * [comparison](/blog/tags/comparison.md) * [diagrams](/blog/tags/diagrams.md) [**Read more**](/blog/mermaid-vs-plantuml-vs-graphviz-confluence.md) --- ## [Root Cause Analysis in Confluence with Mermaid Fishbone + 5 Whys](/blog/mermaid-fishbone-root-cause-analysis-confluence.md) September 24, 2026 · 7 min read [NGPilot](https://ngpilot.com) A root cause analysis is only as good as the disagreement it survives. When the 'root cause' box on your postmortem template contains one sentence, the meeting spends an hour relitigating that sentence. A fishbone diagram and a 5 Whys chain move the argument onto a diagram: everyone sees which categories were considered, which branch was chosen, and exactly how the 'why' answers arrive at a root cause. Confluence is where RCA already happens — in the Root Cause Analysis template, in postmortems, in retros. The missing piece is a diagram that holds the reasoning. This guide shows you two copy-paste Mermaid diagrams: an `ishikawa` fishbone that maps every candidate cause category, and a `flowchart` 5-Whys drilldown that lands on one concrete fix. **Tags:** * [root-cause-analysis](/blog/tags/root-cause-analysis.md) * [fishbone](/blog/tags/fishbone.md) * [ishikawa](/blog/tags/ishikawa.md) * [5-whys](/blog/tags/5-whys.md) * [mermaid](/blog/tags/mermaid.md) * [confluence](/blog/tags/confluence.md) * [postmortem](/blog/tags/postmortem.md) * [how-to](/blog/tags/how-to.md) * [incident-management](/blog/tags/incident-management.md) [**Read more**](/blog/mermaid-fishbone-root-cause-analysis-confluence.md) --- ## [How to Edit the Confluence Storage Format (And When You'd Need To)](/blog/edit-confluence-storage-format-source-editor.md) July 23, 2026 · 7 min read [NGPilot](https://ngpilot.com) Who should read this * **Confluence admins** fixing broken pages, macros, or corrupted formatting * **Developers** migrating or bulk-editing page content via the storage format * **Power users** who need find-and-replace across a page's underlying XML What you'll learn 1. What the Confluence storage format is and why you'd edit it directly 2. How to open the raw XML of a page and make safe changes 3. Formatting, find-and-replace, and diffing changes before saving 4. When editing storage format is the right tool (and when it isn't) Most Confluence users never see it, but every page is stored as an XML document in Confluence's *storage format* — a specific XHTML dialect with custom tags for macros, layouts, and embeddings. The visual editor hides this. But sometimes the only way to fix a problem is to edit that XML directly: a macro is corrupted and won't render, a copy-paste introduced broken formatting, or you need to find-and-replace a URL across a long page that the visual editor can't reach. Confluence exposes the storage format through its REST API, but there's no built-in visual editor for it. [**Raw Storage Source Editor for Confluence**](https://marketplace.atlassian.com/apps/1237026) adds one — a Monaco-powered editor that opens the raw storage XML of any page, with format, find-and-replace, and (in the Pro edition) a diff view. This guide covers when and how to use it safely. **Tags:** * [confluence](/blog/tags/confluence.md) * [source-editor](/blog/tags/source-editor.md) * [storage-format](/blog/tags/storage-format.md) * [xml](/blog/tags/xml.md) * [how-to](/blog/tags/how-to.md) * [developer-tools](/blog/tags/developer-tools.md) * [power-user](/blog/tags/power-user.md) [**Read more**](/blog/edit-confluence-storage-format-source-editor.md) --- ## [Requirements Traceability in Confluence with Mermaid Requirement Diagrams](/blog/mermaid-requirement-diagram-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The feature ships with a test suite that validates four scenarios. The PRD lists seven requirements. The compliance review asks "which requirement is the encryption actually in scope for?" — and the answer is a spreadsheet cross-referenced by color, maintained by one person, last updated before the sprint began. Traceability does not scale as a spreadsheet; it scales as a diagram that *is* the trace. **Quick answer:** document requirements traceability in Confluence as Mermaid `requirementDiagram`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Each requirement connects to the elements that satisfy and verify it — the gaps read at a glance, and the whole thing stays editable text next to the PRD. This post gives you three copy-paste examples: a feature trace, a compliance control, and an epic-to-test gap review. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [requirement-diagram](/blog/tags/requirement-diagram.md) * [traceability](/blog/tags/traceability.md) * [prd](/blog/tags/prd.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-requirement-diagram-confluence.md) --- ## [QR Code for Confluence — Which QR App Should Your Team Use?](/blog/confluence-qr-code-comparison.md) April 18, 2026 · 5 min read [NGPilot](https://ngpilot.com) Teams print Confluence page links on posters, equipment labels, desk signs, and handouts. A QR code on a physical object that links to the relevant Confluence page saves everyone from typing long URLs. It's a small thing that removes friction in offices, warehouses, and events. But Confluence has no built-in QR code generation. A handful of marketplace apps fill this niche — it's a small market with roughly 130 total installs across all apps. We built **QRCode for Confluence** to let teams embed QR codes directly into pages with a simple `/qrcode` slash command. In this post we compare it against the alternatives. **Tags:** * [qr-code](/blog/tags/qr-code.md) * [qrcode](/blog/tags/qrcode.md) * [confluence](/blog/tags/confluence.md) * [barcode](/blog/tags/barcode.md) * [url-shortener](/blog/tags/url-shortener.md) * [printable-qr](/blog/tags/printable-qr.md) [**Read more**](/blog/confluence-qr-code-comparison.md) --- ## [How to Use QR Codes in Confluence: Complete Guide](/blog/how-to-use-qr-codes-confluence.md) May 2, 2026 · 11 min read [NGPilot](https://ngpilot.com) QR codes bridge the gap between physical and digital information. A printed QR code on a poster, equipment label, or business card lets someone open a web page, join a WiFi network, or save a contact without typing a single character. For teams using Confluence as their knowledge base, adding QR codes to pages turns static documents into interactive touchpoints. The challenge is that Confluence does not include built-in QR code generation. You either use a third-party QR generator website, download the image, and upload it manually — or you install a marketplace app that generates QR codes directly inside Confluence pages. The second option is faster, keeps your QR codes up to date when page URLs change, and avoids juggling image files. **QRCode for Confluence** by NGPILOT is a lightweight app that embeds QR codes directly into Confluence pages using a simple slash command. It supports URLs, plain text, email addresses, phone numbers, and any other string. You can customize the size, and the QR code renders inline on your page. This guide covers everything you need to know: how to install and use the app, what content types you can encode, creative ways teams use QR codes in Confluence, and best practices for making sure your QR codes actually get scanned. **Tags:** * [confluence](/blog/tags/confluence.md) * [qr-code](/blog/tags/qr-code.md) * [how-to](/blog/tags/how-to.md) * [printables](/blog/tags/printables.md) [**Read more**](/blog/how-to-use-qr-codes-confluence.md) --- ## [Swimlane Process Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-process-flow-swimlane-diagram-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The ticket sits in "Waiting on customer" for a week and nobody noticed, because the handoff between first-line support and the dev team is a *tacit* step: Support marks it "escalated" in one field, Engineering is supposed to watch a filter, and the transfer never surfaces as its own action. That inert weekend is a process bug, and the fix is to see the handoff. A swimlane diagram makes the ownership transfer its own crossing arrow — invisible to everyone until it is drawn. **Quick answer:** map cross-functional processes in Confluence as Mermaid `swimlane-beta`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). One lane per actor, steps sequenced inside lanes, and the handoff is the arrow that crosses a lane boundary. When the interaction is a short request/response instead of long-running work, switch to a `sequenceDiagram`. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [swimlane](/blog/tags/swimlane.md) * [process](/blog/tags/process.md) * [flow](/blog/tags/flow.md) * [sequence-diagram](/blog/tags/sequence-diagram.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-process-flow-swimlane-diagram-confluence.md) --- ## [Atlassian Marketplace App Selection Criteria for Enterprise](/blog/marketplace-app-selection-criteria-enterprise.md) August 2, 2026 · 7 min read [NGPilot](https://ngpilot.com) Quick Answer Enterprise teams evaluating Atlassian Marketplace apps should check ten criteria: Cloud Fortified status, Forge vs Connect framework, OAuth scopes, privacy disclosure, Bug Bounty participation, data residency, vendor viability, support SLA, adoption signals, and release cadence. This guide walks through each so your security and procurement teams can make confident decisions. What you'll learn 1. The 10 criteria every enterprise should check before approving an app 2. How to assess vendor viability and long-term risk 3. What documentation to request from vendors during procurement 4. A scoring rubric you can apply to any app in under 10 minutes Installing a Marketplace app in an enterprise Atlassian environment is not the same as installing a browser extension. The app gains access to your Jira issues, Confluence pages, and potentially your entire collaboration surface — so the evaluation process needs to be rigorous. This guide covers the ten criteria that security, procurement, and IT teams should check before approving any app for enterprise deployment. **Tags:** * [atlassian](/blog/tags/atlassian.md) * [marketplace](/blog/tags/marketplace.md) * [enterprise](/blog/tags/enterprise.md) * [security](/blog/tags/security.md) * [procurement](/blog/tags/procurement.md) * [explained](/blog/tags/explained.md) [**Read more**](/blog/marketplace-app-selection-criteria-enterprise.md) --- ## [Customer Journey Maps in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-journey-diagram-customer-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The support team knows where refunds leak. The product team knows where onboarding drops. The sales team knows where the pricing page confuses. Three silos, three versions of the customer's experience — and the roadmap meeting spends an hour reconciling them instead of deciding what to fix. What is missing is a single picture with a score on every step. **Quick answer:** draw customer journeys in Confluence as Mermaid `journey` diagrams, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). A journey diagram puts every step in a row and every satisfaction score on one curve — the dips are visible, the actors are labeled, and the whole thing stays editable text. This post gives you three copy-paste examples: onboarding, a support ticket, and a checkout flow with a summary pie. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [journey](/blog/tags/journey.md) * [customer-experience](/blog/tags/customer-experience.md) * [product](/blog/tags/product.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-journey-diagram-customer-confluence.md) --- ## [Meeting Notes in Confluence with Markdown (Copy-Paste Template)](/blog/markdown-meeting-notes-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) Meeting notes fail in one of two directions: they are so informal that nobody can find the decision a month later, or so formal that nobody takes them at all. The Confluence editor quietly encourages the second — formatting dialogs are the enemy of live note-taking. Markdown flips it. In a split-pane editor, notes are keystrokes: two characters for a heading, pipes for a table row, backticks for a snippet — and the rendered page assembles itself in the right pane while you type. This guide ships the template and the habits that make notes pages worth opening later. **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [meeting-notes](/blog/tags/meeting-notes.md) * [template](/blog/tags/template.md) * [how-to](/blog/tags/how-to.md) * [productivity](/blog/tags/productivity.md) * [engineering](/blog/tags/engineering.md) [**Read more**](/blog/markdown-meeting-notes-confluence.md) --- ## [How to Build a Release Timeline in Jira — 3 Methods with Copy-Paste Examples](/blog/how-to-create-release-timeline-jira.md) September 13, 2026 · 5 min read [NGPilot](https://ngpilot.com) A release date doesn't slip in one dramatic moment — it slips in six quiet ones: QA took two extra days, staging froze late, sign-off waited on legal. A release timeline pinned to the release epic makes those slips visible *while they're still cheap to fix*, because every stakeholder reads the same picture of what's next and what's blocked. Jira gives you three ways to build that picture. This guide walks through them, then gives three copy-paste Mermaid Gantt examples sized for real releases: a single version, a multi-team launch, and a launch-week sequence. **Tags:** * [jira](/blog/tags/jira.md) * [release](/blog/tags/release.md) * [timeline](/blog/tags/timeline.md) * [gantt](/blog/tags/gantt.md) * [mermaid](/blog/tags/mermaid.md) * [how-to](/blog/tags/how-to.md) * [project-management](/blog/tags/project-management.md) [**Read more**](/blog/how-to-create-release-timeline-jira.md) --- ## [How to Create a Component Hierarchy in Jira](/blog/jira-component-hierarchy.md) September 23, 2026 · 5 min read [NGPilot](https://ngpilot.com) Jira components were designed for a flat world: one list, no nesting, no structure. That works at ten components and collapses at fifty — when "SSO" sits next to "Platform" and "Mobile" with nothing expressing that it belongs under "Auth", which belongs under "Platform". Teams end up encoding the architecture in name prefixes and maintaining ever-growing `component in (...)` lists by hand. This guide covers three ways to get a component hierarchy in Jira, and what each one costs. **Tags:** * [jira](/blog/tags/jira.md) * [components](/blog/tags/components.md) * [hierarchy](/blog/tags/hierarchy.md) * [jql](/blog/tags/jql.md) * [how-to](/blog/tags/how-to.md) * [project-structure](/blog/tags/project-structure.md) [**Read more**](/blog/jira-component-hierarchy.md) --- ## [Issue Templates for Jira — Templating.app & Top Apps Compared](/blog/jira-issue-templates-comparison.md) April 18, 2026 · 8 min read [NGPilot](https://ngpilot.com) Every team has recurring issue types — bug reports with specific fields, user stories with acceptance criteria, onboarding checklists with sub-tasks. Creating each one from scratch wastes time and introduces inconsistency. Jira has no built-in issue templates. Over a dozen marketplace apps try to solve this. The market is fragmented but maturing — the leader has roughly 4,900 installs, and several apps now carry Cloud Fortified status. We built **Modern Issue Templates for Jira** to bring template creation, GitHub import, auto-application, and fill-in variables to Jira issues. In this post we compare it against the alternatives. **Tags:** * [issue-templates](/blog/tags/issue-templates.md) * [jira-templates](/blog/tags/jira-templates.md) * [jira-automation](/blog/tags/jira-automation.md) * [project-templates](/blog/tags/project-templates.md) * [bug-template](/blog/tags/bug-template.md) * [user-story-template](/blog/tags/user-story-template.md) [**Read more**](/blog/jira-issue-templates-comparison.md) --- ## [Modern FAQ vs Modern Questions for Confluence — Feature Comparison](/blog/faq-questions-confluence-comparison.md) April 18, 2026 · 6 min read [NGPilot](https://ngpilot.com) Teams need two types of knowledge sharing in Confluence: **structured FAQ sections** for pages, and **community Q\&A forums** for ongoing discussion. Confluence has no built-in solution for either. We built two apps to cover both needs — **Modern FAQ for Confluence** for polished, drag-and-drop FAQ sections, and **Modern Questions for Confluence** for structured Q\&A with voting and accepted answers. In this post we compare both against the alternatives on the Atlassian Marketplace. **Tags:** * [faq](/blog/tags/faq.md) * [questions](/blog/tags/questions.md) * [q-and-a](/blog/tags/q-and-a.md) * [confluence](/blog/tags/confluence.md) * [knowledge-base](/blog/tags/knowledge-base.md) * [accordion](/blog/tags/accordion.md) [**Read more**](/blog/faq-questions-confluence-comparison.md) --- ## [How to Use QR Codes in Confluence: Complete Guide](/blog/how-to-use-qr-codes-confluence.md) May 2, 2026 · 11 min read [NGPilot](https://ngpilot.com) QR codes bridge the gap between physical and digital information. A printed QR code on a poster, equipment label, or business card lets someone open a web page, join a WiFi network, or save a contact without typing a single character. For teams using Confluence as their knowledge base, adding QR codes to pages turns static documents into interactive touchpoints. The challenge is that Confluence does not include built-in QR code generation. You either use a third-party QR generator website, download the image, and upload it manually — or you install a marketplace app that generates QR codes directly inside Confluence pages. The second option is faster, keeps your QR codes up to date when page URLs change, and avoids juggling image files. **QRCode for Confluence** by NGPILOT is a lightweight app that embeds QR codes directly into Confluence pages using a simple slash command. It supports URLs, plain text, email addresses, phone numbers, and any other string. You can customize the size, and the QR code renders inline on your page. This guide covers everything you need to know: how to install and use the app, what content types you can encode, creative ways teams use QR codes in Confluence, and best practices for making sure your QR codes actually get scanned. **Tags:** * [confluence](/blog/tags/confluence.md) * [qr-code](/blog/tags/qr-code.md) * [how-to](/blog/tags/how-to.md) * [printables](/blog/tags/printables.md) [**Read more**](/blog/how-to-use-qr-codes-confluence.md) --- ## [QR Code for Confluence — Which QR App Should Your Team Use?](/blog/confluence-qr-code-comparison.md) April 18, 2026 · 5 min read [NGPilot](https://ngpilot.com) Teams print Confluence page links on posters, equipment labels, desk signs, and handouts. A QR code on a physical object that links to the relevant Confluence page saves everyone from typing long URLs. It's a small thing that removes friction in offices, warehouses, and events. But Confluence has no built-in QR code generation. A handful of marketplace apps fill this niche — it's a small market with roughly 130 total installs across all apps. We built **QRCode for Confluence** to let teams embed QR codes directly into pages with a simple `/qrcode` slash command. In this post we compare it against the alternatives. **Tags:** * [qr-code](/blog/tags/qr-code.md) * [qrcode](/blog/tags/qrcode.md) * [confluence](/blog/tags/confluence.md) * [barcode](/blog/tags/barcode.md) * [url-shortener](/blog/tags/url-shortener.md) * [printable-qr](/blog/tags/printable-qr.md) [**Read more**](/blog/confluence-qr-code-comparison.md) --- ## [Decision Framework Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-decision-framework-diagrams-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The meeting asks "who owns this feature?" and the answer is a Venn diagram by hand — drawn on a whiteboard, erased, redrawn, photographed, and lost. Two teams each built a piece of a shared workflow, and "the overlap" is exactly where the bugs and the SQL both landed. A decision framework is only useful while its picture survives the meeting; in Confluence as Mermaid text, it survives. **Quick answer:** put decision frameworks in Confluence as Mermaid — `venn-beta` for set overlap, `cynefin-beta` for which operating mode a situation needs, `quadrantChart` for which item goes first — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Each framework encodes a decision *shape*, and text keeps the picture attached to the decision record. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [venn-diagram](/blog/tags/venn-diagram.md) * [cynefin](/blog/tags/cynefin.md) * [quadrant](/blog/tags/quadrant.md) * [decision](/blog/tags/decision.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-decision-framework-diagrams-confluence.md) --- ## [How to Use AI for Confluence Documentation Review](/blog/ai-for-confluence-documentation-review.md) July 30, 2026 · 7 min read [NGPilot](https://ngpilot.com) Quick Answer AI can automatically review Confluence documentation for quality issues, content gaps, and consistency problems. Run AI audits to identify outdated content, missing sections, and improvement opportunities. What you'll learn 1. How to run AI content audits on your Confluence spaces 2. How to identify content gaps with AI analysis 3. How to ensure consistency with AI style checking 4. How to create automated quality reports Documentation quality degrades over time. Pages get outdated, formats drift, and gaps emerge as the team and product evolve. Manual review is time-consuming and often inconsistent. AI can automate documentation review, identifying quality issues and improvement opportunities at scale. This guide covers how to use AI for Confluence documentation review, from audits to automated reports. **Tags:** * [confluence](/blog/tags/confluence.md) * [ai](/blog/tags/ai.md) * [documentation](/blog/tags/documentation.md) * [how-to](/blog/tags/how-to.md) * [quality](/blog/tags/quality.md) [**Read more**](/blog/ai-for-confluence-documentation-review.md) --- ## [Jira JQL Cheat Sheet: 20 Queries Every Team Needs](/blog/jira-jql-cheat-sheet-common-queries.md) July 29, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer JQL (Jira Query Language) lets you search for issues using fields, operators, and values. Master 20 essential queries to find issues fast, track sprint health, and build custom dashboards. What you'll learn 1. The JQL syntax basics that power every query 2. 20 copy-paste queries for common searches 3. How to use JQL functions for dynamic, date-aware filters 4. How to save and share filters for dashboards Jira's search is powerful, but most teams only scratch the surface. They type a few keywords into the search bar, get overwhelmed by results, and give up. JQL — Jira Query Language — is the key to unlocking precise, repeatable searches that find exactly what you need. This cheat sheet covers 20 essential JQL queries, from basic field searches to advanced functions. Each query is copy-paste ready. **Tags:** * [jira](/blog/tags/jira.md) * [jql](/blog/tags/jql.md) * [how-to](/blog/tags/how-to.md) * [queries](/blog/tags/queries.md) * [reporting](/blog/tags/reporting.md) [**Read more**](/blog/jira-jql-cheat-sheet-common-queries.md) --- ## [Manual Toggles vs Modern FAQ for Confluence — 3 Methods Compared](/blog/how-to-create-faq-pages-confluence.md) May 23, 2026 · 9 min read [NGPilot](https://ngpilot.com) FAQ pages are one of the most visited sections of any documentation site. In Confluence, they serve a specific purpose: giving your team or customers quick answers to the questions they ask most often, without making them read through pages of documentation. A well-structured FAQ page reduces repetitive questions in Slack channels, shortens onboarding time for new team members, and deflects support tickets before they are created. But Confluence does not have a built-in FAQ feature. Teams typically resort to manual workarounds — tables, toggle macros, or expand sections — that look cluttered and are hard to maintain. This guide shows you three methods to create professional FAQ pages in Confluence, from a quick manual setup to a fully featured FAQ macro. **Tags:** * [confluence](/blog/tags/confluence.md) * [faq](/blog/tags/faq.md) * [how-to](/blog/tags/how-to.md) * [knowledge-base](/blog/tags/knowledge-base.md) * [accordion](/blog/tags/accordion.md) * [questions](/blog/tags/questions.md) [**Read more**](/blog/how-to-create-faq-pages-confluence.md) --- ## [Radar & Skill Matrix Charts in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-radar-skill-matrix-charts-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The team page says "we own the checkout" and the skills tab lists four words nobody updated. When the sprint needs a React engineer, the wiki can't say who is nearest. Meanwhile, the contributor guide links to a repo whose shape is a mystery ship in a fog of folders. Structure and capability both want *drawing* — and both draw from plain text. **Quick answer:** track capabilities and structure in Confluence as Mermaid — `radar-beta` for multi-axis comparison across profiles, `treeView-beta` for repo and structure maps, `railroad-ebnf-beta` for syntax and grammar diagrams — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Each chart answers a different "what's the shape": of the team, of the repo, of the language. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [radar-chart](/blog/tags/radar-chart.md) * [treeview](/blog/tags/treeview.md) * [railroad](/blog/tags/railroad.md) * [skills](/blog/tags/skills.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-radar-skill-matrix-charts-confluence.md) --- ## [RAG with Confluence: Build an AI Knowledge Base from Your Docs](/blog/rag-with-confluence-build-ai-knowledge-base.md) July 30, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer RAG (Retrieval-Augmented Generation) lets you query your Confluence knowledge base using natural language. It retrieves relevant pages and uses AI to generate accurate answers from your documentation. What you'll learn 1. How to prepare Confluence content for RAG indexing 2. How to choose the right RAG platform for your needs 3. How to index and configure your Confluence knowledge base 4. How to test, optimize, and deploy your RAG system Your team has hundreds of Confluence pages, but finding the right information still takes too long. Search returns too many results, keywords miss synonyms, and context gets lost across pages. RAG (Retrieval-Augmented Generation) changes this by combining search with AI generation. Instead of returning pages, it returns answers — synthesized from your Confluence content. This guide covers how to build a RAG system with Confluence. **Tags:** * [confluence](/blog/tags/confluence.md) * [rag](/blog/tags/rag.md) * [ai](/blog/tags/ai.md) * [knowledge-base](/blog/tags/knowledge-base.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/rag-with-confluence-build-ai-knowledge-base.md) --- ## [Radar & Skill Matrix Charts in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-radar-skill-matrix-charts-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The team page says "we own the checkout" and the skills tab lists four words nobody updated. When the sprint needs a React engineer, the wiki can't say who is nearest. Meanwhile, the contributor guide links to a repo whose shape is a mystery ship in a fog of folders. Structure and capability both want *drawing* — and both draw from plain text. **Quick answer:** track capabilities and structure in Confluence as Mermaid — `radar-beta` for multi-axis comparison across profiles, `treeView-beta` for repo and structure maps, `railroad-ebnf-beta` for syntax and grammar diagrams — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Each chart answers a different "what's the shape": of the team, of the repo, of the language. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [radar-chart](/blog/tags/radar-chart.md) * [treeview](/blog/tags/treeview.md) * [railroad](/blog/tags/railroad.md) * [skills](/blog/tags/skills.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-radar-skill-matrix-charts-confluence.md) --- ## [FAQ: EPUB Reader for Confluence — Everything You Need to Know](/blog/faq-epub-reader-confluence.md) May 2, 2026 · 14 min read [NGPilot](https://ngpilot.com) **Tags:** * [faq](/blog/tags/faq.md) * [confluence](/blog/tags/confluence.md) * [epub](/blog/tags/epub.md) * [document-viewer](/blog/tags/document-viewer.md) * [reading](/blog/tags/reading.md) [**Read more**](/blog/faq-epub-reader-confluence.md) --- ## [Visualize Git Branches & Releases Inside Jira with Mermaid GitGraph](/blog/mermaid-gitgraph-jira-branch-history.md) September 24, 2026 · 7 min read [NGPilot](https://ngpilot.com) Your team is mid-debug on a prod incident. A senior engineer asks *"which release shipped this commit, and why is it on the release branch when the PR said main?"* — and nobody can answer without switching between Jira, the git web UI, and a Slack thread. That context — commit history, branches, merge points, release versions — belongs *next to the issue*, not in a tool people have to leave Jira to open. **Quick answer:** paste a Mermaid `gitGraph` into the issue's [Mermaid Plus Diagrams for Jira](https://marketplace.atlassian.com/apps/2658777397/mermaid-plus-diagrams-for-jira/) panel and the branch history renders as a diagram right on the ticket — commits, branches, merges, and release tags, all in one editable text block. This post gives you three copy-paste examples: a trunk-based feature workflow, a hotfix outside the release window, and a branch-rule flowchart to keep behavior consistent. **Tags:** * [jira](/blog/tags/jira.md) * [git](/blog/tags/git.md) * [gitgraph](/blog/tags/gitgraph.md) * [mermaid](/blog/tags/mermaid.md) * [branching](/blog/tags/branching.md) * [release](/blog/tags/release.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-gitgraph-jira-branch-history.md) --- ## [Mermaid 12 in Confluence & Jira: UML Use Case Diagrams and a New Look](/blog/mermaid-12-confluence-jira.md) September 19, 2026 · 5 min read [NGPilot](https://ngpilot.com) Mermaid 12 is the biggest release the diagram language has had in years — and as of today it is live in all three NGPILOT diagram apps: **Enhanced Markdown for Confluence**, **Mermaid Plus Diagrams & AI Agent for Confluence**, and **Mermaid Plus Diagrams for Jira**. You get the headline feature immediately: **UML use case diagrams**, the diagram type Confluence and Jira teams have been asking for since requirements documents moved out of dedicated UML tools. **Tags:** * [confluence](/blog/tags/confluence.md) * [jira](/blog/tags/jira.md) * [mermaid](/blog/tags/mermaid.md) * [diagrams](/blog/tags/diagrams.md) * [release-notes](/blog/tags/release-notes.md) * [use-case-diagram](/blog/tags/use-case-diagram.md) [**Read more**](/blog/mermaid-12-confluence-jira.md) --- ## [Jira Export Limit: How to Export More Than 1,000 Issues (2026)](/blog/jira-export-limit.md) September 2, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Jira Cloud's native export stops at 1,000 issues per export and only includes columns visible in the issue navigator. To export more: split your filter into JQL batches, use the REST API, or install [Simple Bulk Issues Excel CSV Export](https://marketplace.atlassian.com/apps/3818473739/simple-bulk-issues-excel-csv-export-for-jira?utm_source=ngpilot.com\&utm_medium=blog), which exports up to 5,000 issues per run in CSV, XLS, or XLSX — and tells you plainly when a result set was truncated. If you have ever exported a project for reporting, an audit, or a migration, you have probably run into Jira Cloud's export limit without being warned first: the export finishes, the file looks complete, and the row count quietly stops at 1,000. This article explains where that limit comes from, then compares the three practical ways to export larger issue sets in 2026. **Tags:** * [jira](/blog/tags/jira.md) * [export](/blog/tags/export.md) * [excel](/blog/tags/excel.md) * [csv](/blog/tags/csv.md) * [jira-cloud](/blog/tags/jira-cloud.md) * [reporting](/blog/tags/reporting.md) [**Read more**](/blog/jira-export-limit.md) --- ## [Requirements Traceability in Confluence with Mermaid Requirement Diagrams](/blog/mermaid-requirement-diagram-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The feature ships with a test suite that validates four scenarios. The PRD lists seven requirements. The compliance review asks "which requirement is the encryption actually in scope for?" — and the answer is a spreadsheet cross-referenced by color, maintained by one person, last updated before the sprint began. Traceability does not scale as a spreadsheet; it scales as a diagram that *is* the trace. **Quick answer:** document requirements traceability in Confluence as Mermaid `requirementDiagram`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Each requirement connects to the elements that satisfy and verify it — the gaps read at a glance, and the whole thing stays editable text next to the PRD. This post gives you three copy-paste examples: a feature trace, a compliance control, and an epic-to-test gap review. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [requirement-diagram](/blog/tags/requirement-diagram.md) * [traceability](/blog/tags/traceability.md) * [prd](/blog/tags/prd.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-requirement-diagram-confluence.md) --- ## [How to Run Jira Sprint Retrospectives That Drive Real Change](/blog/jira-sprint-retrospectives-that-drive-change.md) July 29, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer Sprint retrospectives drive improvement when they produce specific, assigned action items tracked in Jira. Use structured formats, gather anonymous input, and follow up on actions every sprint. What you'll learn 1. How to choose the right retro format for your team's maturity and energy 2. Facilitation techniques that ensure every voice is heard 3. How to turn retro feedback into trackable Jira action items 4. Why most retros fail and how to build accountability into the process Sprint retrospectives are supposed to be the engine of continuous improvement. But for many teams, they devolve into the same complaints, the same vague commitments, and the same problems month after month. The retro becomes a ritual without results. The issue is not the concept — it is the execution. Without structure, facilitation, and follow-through, retros produce feelings but not changes. This guide fixes that. **Tags:** * [jira](/blog/tags/jira.md) * [retrospective](/blog/tags/retrospective.md) * [agile](/blog/tags/agile.md) * [scrum](/blog/tags/scrum.md) * [team-performance](/blog/tags/team-performance.md) [**Read more**](/blog/jira-sprint-retrospectives-that-drive-change.md) --- ## [Roadmap & Prioritization Charts in Confluence with Mermaid](/blog/mermaid-roadmap-prioritization-charts-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The quarter plan is a spreadsheet with thirty rows, color-coded by priority, sorted by a column half the team doesn't trust. The kickoff asks "what are we doing when — and why this first?" and the answer requires parsing three tabs. Planning outputs are *shapes*: schedules stack as bars, priorities sit on a 2x2, flows bundle as ribbons. The spreadsheet stores them poorly; Mermaid draws them as text. **Quick answer:** put the quarter plan in Confluence as Mermaid — `gantt` for when things happen, `quadrantChart` for which gets built first, `sankey-beta` for where the budget goes — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Three charts, three planning questions, one editable page. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [gantt](/blog/tags/gantt.md) * [quadrant](/blog/tags/quadrant.md) * [sankey](/blog/tags/sankey.md) * [roadmap](/blog/tags/roadmap.md) * [planning](/blog/tags/planning.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-roadmap-prioritization-charts-confluence.md) --- ## [Root Cause Analysis in Confluence with Mermaid Fishbone + 5 Whys](/blog/mermaid-fishbone-root-cause-analysis-confluence.md) September 24, 2026 · 7 min read [NGPilot](https://ngpilot.com) A root cause analysis is only as good as the disagreement it survives. When the 'root cause' box on your postmortem template contains one sentence, the meeting spends an hour relitigating that sentence. A fishbone diagram and a 5 Whys chain move the argument onto a diagram: everyone sees which categories were considered, which branch was chosen, and exactly how the 'why' answers arrive at a root cause. Confluence is where RCA already happens — in the Root Cause Analysis template, in postmortems, in retros. The missing piece is a diagram that holds the reasoning. This guide shows you two copy-paste Mermaid diagrams: an `ishikawa` fishbone that maps every candidate cause category, and a `flowchart` 5-Whys drilldown that lands on one concrete fix. **Tags:** * [root-cause-analysis](/blog/tags/root-cause-analysis.md) * [fishbone](/blog/tags/fishbone.md) * [ishikawa](/blog/tags/ishikawa.md) * [5-whys](/blog/tags/5-whys.md) * [mermaid](/blog/tags/mermaid.md) * [confluence](/blog/tags/confluence.md) * [postmortem](/blog/tags/postmortem.md) * [how-to](/blog/tags/how-to.md) * [incident-management](/blog/tags/incident-management.md) [**Read more**](/blog/mermaid-fishbone-root-cause-analysis-confluence.md) --- ## [What Is Atlassian Rovo? (And How It Differs from Atlassian Intelligence)](/blog/what-is-atlassian-rovo.md) August 2, 2026 · 12 min read [NGPilot](https://ngpilot.com) Quick Answer Atlassian Rovo is the cross-platform AI layer for Atlassian Cloud. It does three things: **Search** across Jira, Confluence, and connected SaaS tools; **Chat** that answers questions grounded in your organization's knowledge; and **Agents** that carry out multi-step tasks autonomously. It is different from Atlassian Intelligence, which is the in-product AI engine — Rovo uses that engine and extends it across your entire toolchain. What you'll learn 1. What Rovo actually does (Search, Chat, Agents, Studio) 2. The precise difference between Rovo and Atlassian Intelligence 3. Which data sources Rovo can reach 4. How Rovo Agents work and what they can do 5. Marketplace apps that ship their own Rovo agents 6. What Rovo means for admins and how to prepare your content for it If you have heard the name "Atlassian Rovo" and are not sure whether it is a new product, a rebrand of Atlassian Intelligence, or something your team should adopt, you are not alone. The naming overlap confuses most teams. This guide explains what Rovo is, how it relates to the AI features you may already be using, and what it changes for the people who administer Atlassian Cloud. **Tags:** * [atlassian](/blog/tags/atlassian.md) * [rovo](/blog/tags/rovo.md) * [ai](/blog/tags/ai.md) * [explained](/blog/tags/explained.md) * [admin](/blog/tags/admin.md) [**Read more**](/blog/what-is-atlassian-rovo.md) --- ## [Roadmap & Prioritization Charts in Confluence with Mermaid](/blog/mermaid-roadmap-prioritization-charts-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The quarter plan is a spreadsheet with thirty rows, color-coded by priority, sorted by a column half the team doesn't trust. The kickoff asks "what are we doing when — and why this first?" and the answer requires parsing three tabs. Planning outputs are *shapes*: schedules stack as bars, priorities sit on a 2x2, flows bundle as ribbons. The spreadsheet stores them poorly; Mermaid draws them as text. **Quick answer:** put the quarter plan in Confluence as Mermaid — `gantt` for when things happen, `quadrantChart` for which gets built first, `sankey-beta` for where the budget goes — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Three charts, three planning questions, one editable page. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [gantt](/blog/tags/gantt.md) * [quadrant](/blog/tags/quadrant.md) * [sankey](/blog/tags/sankey.md) * [roadmap](/blog/tags/roadmap.md) * [planning](/blog/tags/planning.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-roadmap-prioritization-charts-confluence.md) --- ## [Database Schema Diagrams in Confluence with Mermaid ER (Entity Relationship) — Copy-Paste](/blog/mermaid-er-diagram-database-schema-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The bug report says "orders show twice in the report" and the fix takes three days because nobody on the team is sure whether `order_lines` links to `orders` on `order_id` or `source_order_id`, and both columns exist. The schema is documented — in a `schema.md` that lists columns as bullets and a diagram that was last exported when the DB was two migrations younger. The join question is exactly the thing an ER diagram answers at a glance, and the thing a bulleted column list cannot answer at all. **Quick answer:** document the database schema in Confluence as a Mermaid `erDiagram`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Entities hold keys and attributes; relationship lines carry the cardinality and the join's noun. When the discussion turns to the domain model the code exposes, add a `classDiagram` on the same page. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [er-diagram](/blog/tags/er-diagram.md) * [database](/blog/tags/database.md) * [schema](/blog/tags/schema.md) * [class-diagram](/blog/tags/class-diagram.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-er-diagram-database-schema-confluence.md) --- ## [Jira Backlog Grooming: The Complete Guide to Refining Stories](/blog/jira-backlog-grooming-complete-guide.md) July 29, 2026 · 7 min read [NGPilot](https://ngpilot.com) Quick Answer Backlog grooming is the process of refining, estimating, and prioritizing Jira stories so they are sprint-ready. A well-groomed backlog makes sprint planning fast and predictable. What you'll learn 1. How to set up a grooming cadence that keeps your backlog healthy 2. A template for writing acceptance criteria that eliminate ambiguity 3. The planning poker workflow for accurate story point estimation 4. How to rank stories so the highest-value work always comes first A messy backlog is the silent killer of Agile teams. Stories pile up without refinement, acceptance criteria are vague, and sprint planning becomes a guessing game. By the time the team realizes the backlog is broken, velocity has dropped and trust in the process has eroded. Backlog grooming — also called refinement — is the antidote. It is the ongoing process of reviewing, splitting, estimating, and prioritizing stories so the backlog is always sprint-ready. This guide covers a complete grooming workflow in Jira, from writing acceptance criteria to ranking by business value. **Tags:** * [jira](/blog/tags/jira.md) * [backlog-grooming](/blog/tags/backlog-grooming.md) * [agile](/blog/tags/agile.md) * [how-to](/blog/tags/how-to.md) * [scrum](/blog/tags/scrum.md) [**Read more**](/blog/jira-backlog-grooming-complete-guide.md) --- ## [AI-Powered Confluence Search: Find Anything Fast](/blog/ai-powered-confluence-search.md) July 30, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer AI-powered Confluence search uses semantic understanding to find content even when keywords don't match. Ask questions in natural language and get relevant answers from your knowledge base. What you'll learn 1. How to enable and configure AI search in Confluence 2. How to write natural language queries for better results 3. How to use AI filters and facets to narrow search results 4. How to improve content discoverability with metadata Confluence search is powerful but often frustrating. You know the information exists, but your search queries don't find it. Keywords miss synonyms, related content uses different terminology, and results bury the answer under irrelevant pages. AI-powered search fixes this by understanding intent instead of just matching keywords. This guide covers how to use and optimize AI search in Confluence. **Tags:** * [confluence](/blog/tags/confluence.md) * [ai](/blog/tags/ai.md) * [search](/blog/tags/search.md) * [how-to](/blog/tags/how-to.md) * [productivity](/blog/tags/productivity.md) [**Read more**](/blog/ai-powered-confluence-search.md) --- ## [How to Evaluate an Atlassian Marketplace App: A Security Checklist](/blog/how-to-evaluate-atlassian-marketplace-app.md) August 2, 2026 · 10 min read [NGPilot](https://ngpilot.com) Quick Answer Before installing any Atlassian Marketplace app, run it through this checklist: verify **Cloud Fortified** status, confirm whether it is **Forge or Connect**, review the **OAuth scopes** it requests, read its **privacy and data handling disclosure**, and check its **install count, ratings, and release cadence**. Apps that pass all five are low-risk; apps that fail any of them deserve a closer look before they touch your production site. What you'll learn 1. The trust signals Atlassian exposes on every Marketplace listing 2. How to read an app's permission scopes before installing 3. Why Forge and Connect carry different security burdens 4. The questions to ask a vendor during a security review 5. A copy-paste checklist you can run on any app in under five minutes The Atlassian Marketplace has thousands of apps, and installing the wrong one can expose your Jira and Confluence data to a vendor you have never vetted. The good news is that Atlassian surfaces most of what you need to make a safe decision directly on each listing — if you know where to look. This guide is a practical checklist for evaluating any Marketplace app before it lands on your site, written for the admins who get asked "is this app okay to install?" and need to answer with confidence. **Tags:** * [atlassian](/blog/tags/atlassian.md) * [marketplace](/blog/tags/marketplace.md) * [security](/blog/tags/security.md) * [admin](/blog/tags/admin.md) * [explained](/blog/tags/explained.md) [**Read more**](/blog/how-to-evaluate-atlassian-marketplace-app.md) --- ## [API Sequence Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-api-sequence-diagram-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The integration doc says "the client calls the API, the API validates and responds" — four words, zero contracts, and the onboarding engineer asks "with what headers, in what order, and what if auth fails?" The code has the truth; the wiki has a paragraph. An API that can't be read as a transcript is an API nobody can safely operate. **Quick answer:** document API flows in Confluence as Mermaid — `sequenceDiagram` for request/response order, `packet-beta` for wire-format frames, ZenUML for branch-heavy async flows — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Each diagram type answers a different reader: what order, what's on the wire, what branches. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [sequence-diagram](/blog/tags/sequence-diagram.md) * [packet](/blog/tags/packet.md) * [zenuml](/blog/tags/zenuml.md) * [api](/blog/tags/api.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-api-sequence-diagram-confluence.md) --- ## [Radar & Skill Matrix Charts in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-radar-skill-matrix-charts-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The team page says "we own the checkout" and the skills tab lists four words nobody updated. When the sprint needs a React engineer, the wiki can't say who is nearest. Meanwhile, the contributor guide links to a repo whose shape is a mystery ship in a fog of folders. Structure and capability both want *drawing* — and both draw from plain text. **Quick answer:** track capabilities and structure in Confluence as Mermaid — `radar-beta` for multi-axis comparison across profiles, `treeView-beta` for repo and structure maps, `railroad-ebnf-beta` for syntax and grammar diagrams — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Each chart answers a different "what's the shape": of the team, of the repo, of the language. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [radar-chart](/blog/tags/radar-chart.md) * [treeview](/blog/tags/treeview.md) * [railroad](/blog/tags/railroad.md) * [skills](/blog/tags/skills.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-radar-skill-matrix-charts-confluence.md) --- ## [Create State Diagrams in Confluence — Mermaid Syntax & Examples](/blog/how-to-create-state-diagrams-confluence.md) May 2, 2026 · 17 min read [NGPilot](https://ngpilot.com) State diagrams (also called state machine diagrams) model how a system transitions between discrete states in response to events. They are essential for documenting order lifecycles, user authentication flows, CI/CD pipelines, IoT device behavior, and any system where the current state determines what happens next. If your team uses Confluence for technical documentation, embedding state diagrams directly on your pages keeps your design decisions alongside runbooks, architecture decision records, and sprint planning notes. In this tutorial, you will learn how to create state diagrams in Confluence using the Mermaid `stateDiagram-v2` syntax. Every example is copy-paste ready, so you can drop it straight into a Confluence page and see the rendered result immediately. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [state-diagram](/blog/tags/state-diagram.md) * [how-to](/blog/tags/how-to.md) * [diagrams](/blog/tags/diagrams.md) * [software-design](/blog/tags/software-design.md) [**Read more**](/blog/how-to-create-state-diagrams-confluence.md) --- ## [How to Edit the Confluence Storage Format (And When You'd Need To)](/blog/edit-confluence-storage-format-source-editor.md) July 23, 2026 · 7 min read [NGPilot](https://ngpilot.com) Who should read this * **Confluence admins** fixing broken pages, macros, or corrupted formatting * **Developers** migrating or bulk-editing page content via the storage format * **Power users** who need find-and-replace across a page's underlying XML What you'll learn 1. What the Confluence storage format is and why you'd edit it directly 2. How to open the raw XML of a page and make safe changes 3. Formatting, find-and-replace, and diffing changes before saving 4. When editing storage format is the right tool (and when it isn't) Most Confluence users never see it, but every page is stored as an XML document in Confluence's *storage format* — a specific XHTML dialect with custom tags for macros, layouts, and embeddings. The visual editor hides this. But sometimes the only way to fix a problem is to edit that XML directly: a macro is corrupted and won't render, a copy-paste introduced broken formatting, or you need to find-and-replace a URL across a long page that the visual editor can't reach. Confluence exposes the storage format through its REST API, but there's no built-in visual editor for it. [**Raw Storage Source Editor for Confluence**](https://marketplace.atlassian.com/apps/1237026) adds one — a Monaco-powered editor that opens the raw storage XML of any page, with format, find-and-replace, and (in the Pro edition) a diff view. This guide covers when and how to use it safely. **Tags:** * [confluence](/blog/tags/confluence.md) * [source-editor](/blog/tags/source-editor.md) * [storage-format](/blog/tags/storage-format.md) * [xml](/blog/tags/xml.md) * [how-to](/blog/tags/how-to.md) * [developer-tools](/blog/tags/developer-tools.md) * [power-user](/blog/tags/power-user.md) [**Read more**](/blog/edit-confluence-storage-format-source-editor.md) --- ## [Mermaid Diagrams for Jira Sprint Workflows — Which Diagrams Actually Help the Standup](/blog/mermaid-diagrams-jira-sprint-workflows.md) July 23, 2026 · 9 min read [NGPilot](https://ngpilot.com) Who should read this * **Scrum masters and eng leads** who run standups from Jira * **Development teams** deciding which diagrams to maintain across a sprint * **Anyone** who wants to know which of Mermaid's 30 diagram types are actually useful for agile work What you'll learn 1. The four Mermaid diagram types a sprint team actually reaches for 2. How to embed each one inside a Jira issue, with copy-paste syntax 3. When a diagram belongs in Jira vs. Confluence 4. The full 30-type reference for less common needs Every team that adopts Jira diagrams hits the same moment: you discover Mermaid supports 30 diagram types, you get excited, and then you realize you have no idea which ones to actually use during a sprint. Most of them never get drawn. The diagrams that earn their keep are the ones that make a standup faster, an onboarding doc clearer, or a ticket unambiguous — and those are a small, repeatable subset. This post is the workflow guide we wish we'd had: the four diagram types a sprint team actually uses, each with a real scenario and copy-paste syntax you can drop straight into a Jira issue. The full 30-type reference follows, so the same page works as both a sprint playbook and a complete catalog. **Tags:** * [jira](/blog/tags/jira.md) * [mermaid](/blog/tags/mermaid.md) * [diagrams](/blog/tags/diagrams.md) * [sprint](/blog/tags/sprint.md) * [workflow](/blog/tags/workflow.md) * [agile](/blog/tags/agile.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-diagrams-jira-sprint-workflows.md) --- ## [How to Use AI for Jira Sprint Planning and Velocity Prediction](/blog/ai-for-jira-sprint-planning-velocity-prediction.md) July 30, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer AI can predict sprint velocity and forecast capacity by analyzing historical data. Use AI recommendations to plan realistic sprints, suggest optimal scope, and track prediction accuracy over time. What you'll learn 1. How to enable AI velocity prediction in Jira 2. How to use AI for capacity forecasting 3. How to get AI scope recommendations for sprint planning 4. How to track and improve AI prediction accuracy Sprint planning is part science, part guesswork. Teams estimate velocity based on gut feeling, leading to overcommitment or underutilization. AI can replace this guesswork with data-driven predictions. This guide covers how to use AI for Jira sprint planning, from velocity prediction to scope recommendations. **Tags:** * [jira](/blog/tags/jira.md) * [ai](/blog/tags/ai.md) * [sprint-planning](/blog/tags/sprint-planning.md) * [velocity](/blog/tags/velocity.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/ai-for-jira-sprint-planning-velocity-prediction.md) --- ## [How to Set Up Jira Dashboards for Sprint Tracking and Stakeholder Visibility](/blog/jira-dashboard-sprint-tracking-setup.md) July 29, 2026 · 5 min read [NGPilot](https://ngpilot.com) Quick Answer Jira dashboards provide real-time visibility into sprint health, velocity trends, and team performance. Configure gadgets, create JQL filters, and share dashboards with stakeholders. What you'll learn 1. How to create and configure a Jira dashboard from scratch 2. Which gadgets track sprint health vs long-term trends 3. How to set up JQL filters for custom dashboard views 4. How to share dashboards and set up email subscriptions A well-designed Jira dashboard gives your team instant visibility into sprint health, backlog status, and delivery trends. But most dashboards are either empty defaults or cluttered messes that nobody uses. This guide covers how to build dashboards that actually provide value — from sprint tracking to stakeholder reporting. **Tags:** * [jira](/blog/tags/jira.md) * [dashboards](/blog/tags/dashboards.md) * [how-to](/blog/tags/how-to.md) * [reporting](/blog/tags/reporting.md) * [sprint-tracking](/blog/tags/sprint-tracking.md) [**Read more**](/blog/jira-dashboard-sprint-tracking-setup.md) --- ## [How to Create Jira Issue Templates for Consistent Team Workflows](/blog/create-jira-issue-templates-for-consistent-workflows.md) July 29, 2026 · 7 min read [NGPilot](https://ngpilot.com) Quick Answer Jira issue templates standardize how bugs, features, and tasks are reported. Create pre-filled templates with required fields and structured descriptions to eliminate incomplete issues. What you'll learn 1. How to identify and catalog your team's recurring issue types 2. How to create pre-filled templates that enforce required fields 3. How to use bulk create for batch issue generation from spreadsheets 4. How to train your team to use templates consistently Inconsistent issue reporting is a silent productivity killer. One developer writes a two-line bug report with no steps to reproduce. Another writes a three-paragraph feature request buried in technical jargon. The result: wasted time clarifying, misestimated work, and frustrated teams. Issue templates solve this by standardizing how work is described. Every bug report has the same structure. Every feature request includes the same fields. This guide shows how to create and enforce templates in Jira. **Tags:** * [jira](/blog/tags/jira.md) * [issue-templates](/blog/tags/issue-templates.md) * [how-to](/blog/tags/how-to.md) * [productivity](/blog/tags/productivity.md) * [standardization](/blog/tags/standardization.md) [**Read more**](/blog/create-jira-issue-templates-for-consistent-workflows.md) --- ## [Kanban Board Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-kanban-board-workflow-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The sprint board on the wall shows 40 items in "In Progress" and the rulebook says "we limit WIP" and nobody agrees on what the limit is. The board is honest; the *documentation* is aspirational. A Kanban diagram in the wiki is the board as a spec — columns, limits, and the rework paths drawn so the workflow is a claim the team can argue with. **Quick answer:** document the team's board in Confluence as a Mermaid `kanban`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Columns as headings, work items as indented cards; the workflow *rules* (who may move what, when, including rework) as a `stateDiagram` on the same page. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [kanban](/blog/tags/kanban.md) * [workflow](/blog/tags/workflow.md) * [state-diagram](/blog/tags/state-diagram.md) * [agile](/blog/tags/agile.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-kanban-board-workflow-confluence.md) --- ## [Confluence Wiki Markup: How to View, Edit & Convert It](/blog/confluence-wiki-markup.md) September 23, 2026 · 6 min read [NGPilot](https://ngpilot.com) Every Confluence page has two faces: the one you see in the editor, and the one the database sees. The database face is the **storage format** — an XHTML document with macros as tags — and before it, Confluence stored pages as **wiki markup**: `h1. headings`, `*bold text*`, `{code}` blocks. People still search for wiki markup because half the internet's Confluence advice, every migration script, and a lot of content written before \~2017 speaks that language. And in 2026 the topic got urgent: Atlassian is retiring the legacy editor (full deprecation April 2026), and the new cloud editor **dropped the Markup macro** entirely. Here's how to view, edit, and convert what's actually stored — with or without admin rights. **Tags:** * [confluence](/blog/tags/confluence.md) * [wiki-markup](/blog/tags/wiki-markup.md) * [storage-format](/blog/tags/storage-format.md) * [how-to](/blog/tags/how-to.md) * [admin](/blog/tags/admin.md) * [migration](/blog/tags/migration.md) [**Read more**](/blog/confluence-wiki-markup.md) --- ## [How to Add SVG Illustrations to Confluence Pages](/blog/how-to-add-svg-illustrations-confluence.md) May 2, 2026 · 17 min read [NGPilot](https://ngpilot.com) Adding illustrations to Confluence pages transforms flat walls of text into engaging, professional content. Whether you are writing onboarding documentation, putting together a team wiki, or preparing a presentation, the right visual can communicate an idea faster than a paragraph of explanation. The challenge has always been finding high-quality illustrations that look good at any size, load quickly, and match your team's visual style. SVG (Scalable Vector Graphics) illustrations solve all of these problems. They scale perfectly to any resolution, they are lightweight, and they integrate cleanly into Confluence pages. Content Craft for Confluence brings a curated library of SVG illustrations directly into the Confluence editor, so you can browse, search, and insert professional illustrations without leaving your workflow. This tutorial shows you exactly how to add SVG illustrations to Confluence pages using Content Craft for Confluence. By the end, you will be able to transform any Confluence page from text-heavy to visually engaging in under a minute. **Tags:** * [confluence](/blog/tags/confluence.md) * [svg](/blog/tags/svg.md) * [illustrations](/blog/tags/illustrations.md) * [content-craft](/blog/tags/content-craft.md) * [how-to](/blog/tags/how-to.md) * [design](/blog/tags/design.md) [**Read more**](/blog/how-to-add-svg-illustrations-confluence.md) --- ## [How to Visualize Confluence Documentation with SVGs (No Design Skills Required)](/blog/visualize-confluence-documentation-with-svgs.md) May 27, 2025 · 2 min read [NGPilot](https://ngpilot.com) Tired of text-heavy Confluence pages? Discover how **1,300+ ready-to-use SVGs** across 25 professional categories can enhance your documentation - no design experience needed. **Tags:** * [confluence-tips](/blog/tags/confluence-tips.md) * [visual-documentation](/blog/tags/visual-documentation.md) * [svg-library](/blog/tags/svg-library.md) [**Read more**](/blog/visualize-confluence-documentation-with-svgs.md) --- ## [Swimlane Process Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-process-flow-swimlane-diagram-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The ticket sits in "Waiting on customer" for a week and nobody noticed, because the handoff between first-line support and the dev team is a *tacit* step: Support marks it "escalated" in one field, Engineering is supposed to watch a filter, and the transfer never surfaces as its own action. That inert weekend is a process bug, and the fix is to see the handoff. A swimlane diagram makes the ownership transfer its own crossing arrow — invisible to everyone until it is drawn. **Quick answer:** map cross-functional processes in Confluence as Mermaid `swimlane-beta`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). One lane per actor, steps sequenced inside lanes, and the handoff is the arrow that crosses a lane boundary. When the interaction is a short request/response instead of long-running work, switch to a `sequenceDiagram`. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [swimlane](/blog/tags/swimlane.md) * [process](/blog/tags/process.md) * [flow](/blog/tags/flow.md) * [sequence-diagram](/blog/tags/sequence-diagram.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-process-flow-swimlane-diagram-confluence.md) --- ## [Documenting Microservice Architectures in Confluence with Mermaid](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md) May 2, 2026 · 14 min read [NGPilot](https://ngpilot.com) Mermaid is the most popular text-based diagramming language for technical documentation. One line of code generates a flowchart. A few more produce a sequence diagram, ER diagram, or Gantt chart. Teams using Confluence can embed Mermaid diagrams directly on their pages, keeping diagrams alongside the documentation they illustrate. Who should read this * **Platform/backend engineers** documenting a microservice architecture * **Tech leads** keeping architecture docs in sync with code * **Anyone** who wants a copy-paste Mermaid syntax reference for Confluence **Tags:** * [faq](/blog/tags/faq.md) * [mermaid](/blog/tags/mermaid.md) * [confluence](/blog/tags/confluence.md) * [syntax](/blog/tags/syntax.md) * [cheat-sheet](/blog/tags/cheat-sheet.md) * [diagrams](/blog/tags/diagrams.md) [**Read more**](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md) --- ## [Markdown Code Blocks in Confluence — 190+ Languages](/blog/markdown-code-block-confluence.md) September 24, 2026 · 4 min read [NGPilot](https://ngpilot.com) Every engineering page in Confluence eventually holds code — a curl from the runbook, the config that fixed the incident, the query the dashboard runs. And every one of those snippets has three natural enemies: the language dropdown in the macro dialog, the paste that loses its indentation, and the reader who cannot copy the thing without dragging across line numbers. Markdown fences solve all three, because they make the code block *text you type* instead of an object you configure. ` ```bash `, paste, ` ``` ` — done, highlighted, copyable. This guide shows the syntax, the theming behavior, and when fences beat the native macro. **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [code-block](/blog/tags/code-block.md) * [syntax-highlighting](/blog/tags/syntax-highlighting.md) * [how-to](/blog/tags/how-to.md) * [developer-tools](/blog/tags/developer-tools.md) [**Read more**](/blog/markdown-code-block-confluence.md) --- ## [How to Auto-Number Headings in Confluence (H1–H6, With Live Preview)](/blog/auto-number-headings-confluence.md) July 23, 2026 · 6 min read [NGPilot](https://ngpilot.com) Who should read this * **Technical writers** building structured documentation in Confluence * **Compliance teams** who need formal numbered sections (1.1, 1.2, 1.2.1) * **Anyone** tired of manually typing and re-numbering headings when content moves What you'll learn 1. Why Confluence doesn't number headings natively (and why manual numbering breaks) 2. How to auto-number H1-H6 with 5 styles (Decimal, Roman, Alphabetic, …) 3. Choosing heading levels and hierarchical indentation 4. Maintaining numbering when you add, remove, or reorder sections The scenario every documentation team hits: you're writing a policy doc or technical spec in Confluence, and it needs numbered sections — `1. Introduction`, `1.1 Overview`, `1.2 Getting Started`, `2. Configuration`. So you type the numbers manually into each heading. Then product changes the structure: a section moves up, a new one gets inserted in the middle, and now every number below the change is wrong. You spend twenty minutes renumbering by hand, miss one, and the doc ships with `1.2` followed by `1.4`. Confluence has no native heading-numbering feature. Headings are just styled text — there's no automatic `1.1` / `1.2` scheme. [**Modern Numbered Headings for Confluence**](https://marketplace.atlassian.com/apps/2096741841/modern-numbered-headings-for-confluence) fixes this by generating numbered headings automatically from your H1-H6 structure, with a live preview and five numbering styles. When you reorder sections, the numbers update. This guide walks through setting it up. **Tags:** * [confluence](/blog/tags/confluence.md) * [numbered-headings](/blog/tags/numbered-headings.md) * [table-of-contents](/blog/tags/table-of-contents.md) * [how-to](/blog/tags/how-to.md) * [documentation](/blog/tags/documentation.md) [**Read more**](/blog/auto-number-headings-confluence.md) --- ## [Markdown Tables in Confluence — Syntax Reference & Alignment](/blog/confluence-markdown-tables.md) May 6, 2026 · 4 min read [NGPilot](https://ngpilot.com) Confluence has a visual table editor, but it's slow for creating structured tables — you need to click to add rows and columns one at a time. If you write documentation in Markdown, you can create tables much faster with Markdown syntax. This guide shows how to create, format, and edit tables in Confluence using Markdown. **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [tables](/blog/tags/tables.md) * [formatting](/blog/tags/formatting.md) * [enhanced-markdown](/blog/tags/enhanced-markdown.md) [**Read more**](/blog/confluence-markdown-tables.md) --- ## [Tabs in Confluence: Native Layout Tabs vs Tabs Macros Compared](/blog/confluence-tabs-macro.md) August 21, 2026 · 4 min read [NGPilot](https://ngpilot.com) Tabs are the layout workhorse of product pages, API references, and comparison docs: they let one page hold three versions of the truth (per environment, per plan, per language) without tripling the scroll length. Confluence's answer to tabs has changed over the years, so this page sorts out what exists today and which to use when. **Tags:** * [confluence](/blog/tags/confluence.md) * [macros](/blog/tags/macros.md) * [tabs](/blog/tags/tabs.md) * [layout](/blog/tags/layout.md) * [formatting](/blog/tags/formatting.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/confluence-tabs-macro.md) --- ## [How to Run Jira Sprint Retrospectives That Drive Real Change](/blog/jira-sprint-retrospectives-that-drive-change.md) July 29, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer Sprint retrospectives drive improvement when they produce specific, assigned action items tracked in Jira. Use structured formats, gather anonymous input, and follow up on actions every sprint. What you'll learn 1. How to choose the right retro format for your team's maturity and energy 2. Facilitation techniques that ensure every voice is heard 3. How to turn retro feedback into trackable Jira action items 4. Why most retros fail and how to build accountability into the process Sprint retrospectives are supposed to be the engine of continuous improvement. But for many teams, they devolve into the same complaints, the same vague commitments, and the same problems month after month. The retro becomes a ritual without results. The issue is not the concept — it is the execution. Without structure, facilitation, and follow-through, retros produce feelings but not changes. This guide fixes that. **Tags:** * [jira](/blog/tags/jira.md) * [retrospective](/blog/tags/retrospective.md) * [agile](/blog/tags/agile.md) * [scrum](/blog/tags/scrum.md) * [team-performance](/blog/tags/team-performance.md) [**Read more**](/blog/jira-sprint-retrospectives-that-drive-change.md) --- ## [Meeting Notes in Confluence with Markdown (Copy-Paste Template)](/blog/markdown-meeting-notes-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) Meeting notes fail in one of two directions: they are so informal that nobody can find the decision a month later, or so formal that nobody takes them at all. The Confluence editor quietly encourages the second — formatting dialogs are the enemy of live note-taking. Markdown flips it. In a split-pane editor, notes are keystrokes: two characters for a heading, pipes for a table row, backticks for a snippet — and the rendered page assembles itself in the right pane while you type. This guide ships the template and the habits that make notes pages worth opening later. **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [meeting-notes](/blog/tags/meeting-notes.md) * [template](/blog/tags/template.md) * [how-to](/blog/tags/how-to.md) * [productivity](/blog/tags/productivity.md) * [engineering](/blog/tags/engineering.md) [**Read more**](/blog/markdown-meeting-notes-confluence.md) --- ## [Jira issue templates: best practices for consistent ticket creation](/blog/jira-issue-templates-best-practices.md) April 24, 2026 · 3 min read [NGPilot](https://ngpilot.com) Inconsistent Jira tickets waste time during grooming, sprint planning, and reporting. Issue templates solve this by standardizing the fields, descriptions, and checklists that appear on every new ticket. This guide covers how to set up and get the most from [Modern Issue Templates for Jira](/docs/Modern-Issue-Templates-for-Jira/user-docs.md). **Tags:** * [jira](/blog/tags/jira.md) * [templates](/blog/tags/templates.md) * [best-practices](/blog/tags/best-practices.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/jira-issue-templates-best-practices.md) --- ## [Confluence Dark Mode Apps FAQ: Themes, Fonts & Code Blocks](/blog/faq-confluence-dark-mode-apps.md) May 2, 2026 · 13 min read [NGPilot](https://ngpilot.com) Dark mode has moved from a developer preference to an expectation across every tool in the modern workspace. Confluence Cloud introduced a native dark mode toggle, which is a welcome step, but the reality of implementing a fully dark-themed Confluence experience is more nuanced than flipping a single switch. **Tags:** * [faq](/blog/tags/faq.md) * [confluence](/blog/tags/confluence.md) * [dark-mode](/blog/tags/dark-mode.md) * [themes](/blog/tags/themes.md) [**Read more**](/blog/faq-confluence-dark-mode-apps.md) --- ## [How to Write Better Jira Ticket Descriptions with AI](/blog/write-better-jira-ticket-descriptions-with-ai.md) July 30, 2026 · 7 min read [NGPilot](https://ngpilot.com) Quick Answer AI can expand brief Jira ticket summaries into detailed descriptions with acceptance criteria, edge cases, and technical context. This reduces back-and-forth and helps developers understand requirements faster. What you'll learn 1. How to define a ticket description standard for your team 2. How to use AI to expand brief descriptions into detailed tickets 3. How to generate acceptance criteria with AI assistance 4. How to add context with examples and edge cases The quality of a Jira ticket determines how quickly work gets done. A vague description like "fix the login bug" creates hours of back-and-forth. A detailed description with acceptance criteria, edge cases, and technical context lets developers start immediately. AI can transform brief summaries into comprehensive tickets. This guide covers how to use AI to write better Jira descriptions, from prompt templates to review workflows. **Tags:** * [jira](/blog/tags/jira.md) * [ai](/blog/tags/ai.md) * [ticket-descriptions](/blog/tags/ticket-descriptions.md) * [how-to](/blog/tags/how-to.md) * [productivity](/blog/tags/productivity.md) [**Read more**](/blog/write-better-jira-ticket-descriptions-with-ai.md) --- ## [Build an Incident Postmortem Timeline in Confluence (Mermaid, Copy-Paste)](/blog/mermaid-incident-postmortem-timeline-confluence.md) September 24, 2026 · 8 min read [NGPilot](https://ngpilot.com) Every incident has a story hidden inside a pile of timestamps: alert fired at 09:42, nobody acknowledged until 09:47, an engineer escalated at 09:54, a workaround landed at 10:20, services healthy at 10:31. Individually the timestamps mean nothing. Laid out on a timeline, they tell the story — and the story is what a postmortem is for. Confluence is where incident postmortems already live. What Confluence does not give you is a native timeline. This guide shows you how to fill the Timeline section of an incident postmortem with a Mermaid diagram: one copy-paste timeline that visualizes detection → escalation → resolution, plus a sequence diagram that shows exactly how the failure propagated between services. **Tags:** * [incident](/blog/tags/incident.md) * [postmortem](/blog/tags/postmortem.md) * [timeline](/blog/tags/timeline.md) * [mermaid](/blog/tags/mermaid.md) * [confluence](/blog/tags/confluence.md) * [incident-management](/blog/tags/incident-management.md) * [how-to](/blog/tags/how-to.md) * [devops](/blog/tags/devops.md) [**Read more**](/blog/mermaid-incident-postmortem-timeline-confluence.md) --- ## [Confluence Page Navigation FAQ: TOC, Numbered Headings & Structure](/blog/faq-confluence-page-navigation-apps.md) May 2, 2026 · 15 min read [NGPilot](https://ngpilot.com) Page navigation is one of those things that nobody notices when it works well and everyone complains about when it does not. In Confluence, where pages routinely grow to thousands of words — technical specifications, onboarding guides, compliance documentation, project charters — helping readers find the right section quickly is not a nice-to-have. It is the difference between a knowledge base that people use and one that people ignore. **Tags:** * [faq](/blog/tags/faq.md) * [confluence](/blog/tags/confluence.md) * [navigation](/blog/tags/navigation.md) * [toc](/blog/tags/toc.md) * [numbered-headings](/blog/tags/numbered-headings.md) [**Read more**](/blog/faq-confluence-page-navigation-apps.md) --- ## [Requirements Traceability in Confluence with Mermaid Requirement Diagrams](/blog/mermaid-requirement-diagram-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The feature ships with a test suite that validates four scenarios. The PRD lists seven requirements. The compliance review asks "which requirement is the encryption actually in scope for?" — and the answer is a spreadsheet cross-referenced by color, maintained by one person, last updated before the sprint began. Traceability does not scale as a spreadsheet; it scales as a diagram that *is* the trace. **Quick answer:** document requirements traceability in Confluence as Mermaid `requirementDiagram`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Each requirement connects to the elements that satisfy and verify it — the gaps read at a glance, and the whole thing stays editable text next to the PRD. This post gives you three copy-paste examples: a feature trace, a compliance control, and an epic-to-test gap review. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [requirement-diagram](/blog/tags/requirement-diagram.md) * [traceability](/blog/tags/traceability.md) * [prd](/blog/tags/prd.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-requirement-diagram-confluence.md) --- ## [Mind Maps & Hierarchy Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-mindmap-hierarchy-diagram-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The kickoff note is 40 lines of indented bullets with three levels of bolded sub-points, and half the room is still asking "so what are we actually deciding today?" The other half is screenshotting a mind map someone whiteboarded in five minutes. The whiteboard died at cleanup; the bullets survived but nobody can navigate them. A mind map is the *readable* version of nested notes — and when it lives in Confluence as Mermaid text, it survives the meeting. **Quick answer:** turn nested notes into a Mermaid `mindmap` in Confluence, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). The indented text you already write becomes the branches; for concrete structures — folder layouts, project trees — use `treeView`; when item size matters and you want area instead of lines, use `treemap`. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [mindmap](/blog/tags/mindmap.md) * [treeview](/blog/tags/treeview.md) * [treemap](/blog/tags/treemap.md) * [brainstorming](/blog/tags/brainstorming.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-mindmap-hierarchy-diagram-confluence.md) --- ## [Mind Maps & Hierarchy Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-mindmap-hierarchy-diagram-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The kickoff note is 40 lines of indented bullets with three levels of bolded sub-points, and half the room is still asking "so what are we actually deciding today?" The other half is screenshotting a mind map someone whiteboarded in five minutes. The whiteboard died at cleanup; the bullets survived but nobody can navigate them. A mind map is the *readable* version of nested notes — and when it lives in Confluence as Mermaid text, it survives the meeting. **Quick answer:** turn nested notes into a Mermaid `mindmap` in Confluence, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). The indented text you already write becomes the branches; for concrete structures — folder layouts, project trees — use `treeView`; when item size matters and you want area instead of lines, use `treemap`. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [mindmap](/blog/tags/mindmap.md) * [treeview](/blog/tags/treeview.md) * [treemap](/blog/tags/treemap.md) * [brainstorming](/blog/tags/brainstorming.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-mindmap-hierarchy-diagram-confluence.md) --- ## [Jira Attachment Permissions FAQ: Download, Access & Troubleshoot](/blog/faq-jira-attachments-permissions.md) April 21, 2026 · 12 min read [NGPilot](https://ngpilot.com) **Tags:** * [faq](/blog/tags/faq.md) * [jira](/blog/tags/jira.md) * [attachments](/blog/tags/attachments.md) * [permissions](/blog/tags/permissions.md) * [troubleshooting](/blog/tags/troubleshooting.md) [**Read more**](/blog/faq-jira-attachments-permissions.md) --- ## [Enhanced Markdown Setup Tutorial — Insert Macro, Modes & Publish](/blog/how-to-write-markdown-in-confluence.md) May 6, 2026 · 4 min read [NGPilot](https://ngpilot.com) **Confluence Markdown** support lets developers write documentation in their preferred format. This guide covers how to add **Enhanced Markdown** to Confluence for raw Markdown editing, WYSIWYG preview, tables, code blocks, and more. Who should read this * Developers who prefer writing in Markdown * Technical writers needing to import Markdown files * Teams migrating from GitHub or other Markdown-based wikis What you'll learn 1. How to install and use Enhanced Markdown in Confluence 2. Raw Markdown mode vs WYSIWYG mode 3. Supported syntax: tables, code blocks, task lists 4. Comparison with Confluence's native editor **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [tutorial](/blog/tags/tutorial.md) * [wysiwyg](/blog/tags/wysiwyg.md) * [enhanced-markdown](/blog/tags/enhanced-markdown.md) [**Read more**](/blog/how-to-write-markdown-in-confluence.md) --- ## [Can You Change the Font in Confluence? (Default Stack & Custom Font Options)](/blog/confluence-default-font-change-font.md) May 10, 2026 · 3 min read [NGPilot](https://ngpilot.com) Confluence uses a system font stack that looks different on every operating system. You can't change the default font globally, and Confluence offers no built-in way to use custom fonts on individual pages. This guide shows what font Confluence uses and how to add custom fonts. **Tags:** * [confluence](/blog/tags/confluence.md) * [fonts](/blog/tags/fonts.md) * [google-fonts](/blog/tags/google-fonts.md) * [typography](/blog/tags/typography.md) * [customization](/blog/tags/customization.md) [**Read more**](/blog/confluence-default-font-change-font.md) --- ## [How to Create Wireframes and UI Mockups in Confluence with Excalidraw Plus](/blog/how-to-create-wireframes-confluence.md) May 2, 2026 · 15 min read [NGPilot](https://ngpilot.com) Wireframes are the backbone of every user interface design process. They let product managers, designers, and engineers align on layout, content hierarchy, and interaction flow before writing a single line of code. With [Excalidraw Plus for Confluence](/docs/Excalidraw-plus-for-Confluence/usage.md), you can create wireframes and UI mockups directly inside your Confluence pages, keeping design artifacts next to requirements, user stories, and technical specs. **Tags:** * [confluence](/blog/tags/confluence.md) * [excalidraw](/blog/tags/excalidraw.md) * [wireframe](/blog/tags/wireframe.md) * [mockup](/blog/tags/mockup.md) * [how-to](/blog/tags/how-to.md) * [ui-design](/blog/tags/ui-design.md) [**Read more**](/blog/how-to-create-wireframes-confluence.md) --- ## [UML Use Case Diagrams in Confluence (Mermaid, Copy-Paste)](/blog/uml-use-case-diagram-confluence.md) September 24, 2026 · 4 min read [NGPilot](https://ngpilot.com) The use case diagram is the scope picture: actors on the outside, what the system does for them on the inside, and — the reason product and engineering fight — the line between them. In Confluence that picture usually comes from a diagramming tool export that goes stale the moment scope moves. Mermaid 12 added the syntax to render UML use case diagrams from text — `usecase-beta` — and Enhanced Markdown for Confluence renders it in the same macro as everything else on the page. This guide gives you the syntax and two copy-paste diagrams. **Tags:** * [confluence](/blog/tags/confluence.md) * [uml](/blog/tags/uml.md) * [use-case-diagram](/blog/tags/use-case-diagram.md) * [mermaid](/blog/tags/mermaid.md) * [markdown](/blog/tags/markdown.md) * [how-to](/blog/tags/how-to.md) * [engineering](/blog/tags/engineering.md) [**Read more**](/blog/uml-use-case-diagram-confluence.md) --- ## [QR Code for Confluence — Which QR App Should Your Team Use?](/blog/confluence-qr-code-comparison.md) April 18, 2026 · 5 min read [NGPilot](https://ngpilot.com) Teams print Confluence page links on posters, equipment labels, desk signs, and handouts. A QR code on a physical object that links to the relevant Confluence page saves everyone from typing long URLs. It's a small thing that removes friction in offices, warehouses, and events. But Confluence has no built-in QR code generation. A handful of marketplace apps fill this niche — it's a small market with roughly 130 total installs across all apps. We built **QRCode for Confluence** to let teams embed QR codes directly into pages with a simple `/qrcode` slash command. In this post we compare it against the alternatives. **Tags:** * [qr-code](/blog/tags/qr-code.md) * [qrcode](/blog/tags/qrcode.md) * [confluence](/blog/tags/confluence.md) * [barcode](/blog/tags/barcode.md) * [url-shortener](/blog/tags/url-shortener.md) * [printable-qr](/blog/tags/printable-qr.md) [**Read more**](/blog/confluence-qr-code-comparison.md) --- ## [UML Use Case Diagrams in Confluence (Mermaid, Copy-Paste)](/blog/uml-use-case-diagram-confluence.md) September 24, 2026 · 4 min read [NGPilot](https://ngpilot.com) The use case diagram is the scope picture: actors on the outside, what the system does for them on the inside, and — the reason product and engineering fight — the line between them. In Confluence that picture usually comes from a diagramming tool export that goes stale the moment scope moves. Mermaid 12 added the syntax to render UML use case diagrams from text — `usecase-beta` — and Enhanced Markdown for Confluence renders it in the same macro as everything else on the page. This guide gives you the syntax and two copy-paste diagrams. **Tags:** * [confluence](/blog/tags/confluence.md) * [uml](/blog/tags/uml.md) * [use-case-diagram](/blog/tags/use-case-diagram.md) * [mermaid](/blog/tags/mermaid.md) * [markdown](/blog/tags/markdown.md) * [how-to](/blog/tags/how-to.md) * [engineering](/blog/tags/engineering.md) [**Read more**](/blog/uml-use-case-diagram-confluence.md) --- ## [Paste Mermaid Diagrams into Confluence — Now on Mermaid 12](/blog/paste-mermaid-diagrams-into-confluence.md) September 28, 2026 · 9 min read [NGPilot](https://ngpilot.com) Quick Answer Confluence's editor is WYSIWYG and has no Mermaid renderer, so pasting a Markdown file that contains ` ```mermaid ` fences imports them as plain code blocks — the diagrams arrive dead. Paste into a Markdown macro instead: [**Enhanced Markdown for Confluence**](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence/) renders Mermaid 12 inline, so a whole README pastes in and the diagrams come alive. The v12 upgrade is what makes this newly worthwhile — **UML use case diagrams** now survive the paste, which is the diagram type requirements docs kept losing. What you'll learn 1. Why Mermaid dies on the way into Confluence, and where the fix lives 2. The paste workflow: repo Markdown in, rendered diagrams out 3. What Mermaid 12 changes — use case diagrams, refreshed layout, richer ZenUML 4. What happens to diagrams you already published The diagrams live in the repository. They were written in Mermaid, they are reviewed in pull requests next to the code they describe, and they are correct as of the last commit. The documentation, however, lives in Confluence — because that is where the rest of the team reads it. So somebody copies a Markdown file across, pastes it into a Confluence page, and the flowcharts, sequence diagrams and ER models arrive as grey boxes of unrendered code. Everyone has hit this. It is one of the most common Confluence complaints, and the usual workarounds are worse than the problem: export every diagram to PNG and re-upload them (now they rot), keep the diagrams in an external tool and paste links (readers need a second account, and the links break), or build a browser extension to force rendering on paste. There is a better answer, and Mermaid 12 makes it better still. **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [mermaid](/blog/tags/mermaid.md) * [mermaid-12](/blog/tags/mermaid-12.md) * [usecase-diagram](/blog/tags/usecase-diagram.md) * [how-to](/blog/tags/how-to.md) * [developer-tools](/blog/tags/developer-tools.md) [**Read more**](/blog/paste-mermaid-diagrams-into-confluence.md) --- ## [Issue Templates for Jira — Templating.app & Top Apps Compared](/blog/jira-issue-templates-comparison.md) April 18, 2026 · 8 min read [NGPilot](https://ngpilot.com) Every team has recurring issue types — bug reports with specific fields, user stories with acceptance criteria, onboarding checklists with sub-tasks. Creating each one from scratch wastes time and introduces inconsistency. Jira has no built-in issue templates. Over a dozen marketplace apps try to solve this. The market is fragmented but maturing — the leader has roughly 4,900 installs, and several apps now carry Cloud Fortified status. We built **Modern Issue Templates for Jira** to bring template creation, GitHub import, auto-application, and fill-in variables to Jira issues. In this post we compare it against the alternatives. **Tags:** * [issue-templates](/blog/tags/issue-templates.md) * [jira-templates](/blog/tags/jira-templates.md) * [jira-automation](/blog/tags/jira-automation.md) * [project-templates](/blog/tags/project-templates.md) * [bug-template](/blog/tags/bug-template.md) * [user-story-template](/blog/tags/user-story-template.md) [**Read more**](/blog/jira-issue-templates-comparison.md) --- ## [How to Use AI for Jira Sprint Planning and Velocity Prediction](/blog/ai-for-jira-sprint-planning-velocity-prediction.md) July 30, 2026 · 6 min read [NGPilot](https://ngpilot.com) Quick Answer AI can predict sprint velocity and forecast capacity by analyzing historical data. Use AI recommendations to plan realistic sprints, suggest optimal scope, and track prediction accuracy over time. What you'll learn 1. How to enable AI velocity prediction in Jira 2. How to use AI for capacity forecasting 3. How to get AI scope recommendations for sprint planning 4. How to track and improve AI prediction accuracy Sprint planning is part science, part guesswork. Teams estimate velocity based on gut feeling, leading to overcommitment or underutilization. AI can replace this guesswork with data-driven predictions. This guide covers how to use AI for Jira sprint planning, from velocity prediction to scope recommendations. **Tags:** * [jira](/blog/tags/jira.md) * [ai](/blog/tags/ai.md) * [sprint-planning](/blog/tags/sprint-planning.md) * [velocity](/blog/tags/velocity.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/ai-for-jira-sprint-planning-velocity-prediction.md) --- ## [Decision Framework Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-decision-framework-diagrams-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The meeting asks "who owns this feature?" and the answer is a Venn diagram by hand — drawn on a whiteboard, erased, redrawn, photographed, and lost. Two teams each built a piece of a shared workflow, and "the overlap" is exactly where the bugs and the SQL both landed. A decision framework is only useful while its picture survives the meeting; in Confluence as Mermaid text, it survives. **Quick answer:** put decision frameworks in Confluence as Mermaid — `venn-beta` for set overlap, `cynefin-beta` for which operating mode a situation needs, `quadrantChart` for which item goes first — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Each framework encodes a decision *shape*, and text keeps the picture attached to the decision record. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [venn-diagram](/blog/tags/venn-diagram.md) * [cynefin](/blog/tags/cynefin.md) * [quadrant](/blog/tags/quadrant.md) * [decision](/blog/tags/decision.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-decision-framework-diagrams-confluence.md) --- ## [How to Visualize Confluence Documentation with SVGs (No Design Skills Required)](/blog/visualize-confluence-documentation-with-svgs.md) May 27, 2025 · 2 min read [NGPilot](https://ngpilot.com) Tired of text-heavy Confluence pages? Discover how **1,300+ ready-to-use SVGs** across 25 professional categories can enhance your documentation - no design experience needed. **Tags:** * [confluence-tips](/blog/tags/confluence-tips.md) * [visual-documentation](/blog/tags/visual-documentation.md) * [svg-library](/blog/tags/svg-library.md) [**Read more**](/blog/visualize-confluence-documentation-with-svgs.md) --- ## [Excalidraw AI Agent for Confluence: Whiteboards You Can Talk To](/blog/excalidraw-ai-agent-confluence.md) October 10, 2026 · 7 min read [NGPilot](https://ngpilot.com) Confluence holds your team's diagrams in two worlds, and the two don't talk to each other. Text-defined diagrams — Mermaid and friends — are what AI speaks natively. They're source code, so a chat agent can read them, write them, and revise them. We shipped exactly that last week: [an AI agent for Mermaid in Confluence](/blog/mermaid-ai-agent-confluence.md). Whiteboards are the other world. Freeform shapes, hand-drawn lines, arrows you drag where they need to go — the format that's actually intuitive to put in front of people. Every team has one: the architecture board on the team page, the incident flow everyone references, the onboarding map. And AI couldn't touch any of it. Ask a chat agent for a change to a whiteboard and you'd get a text *description* of a change, and someone still had to open the canvas and do it by hand. That gap is why whiteboards go stale. Editing shapes one drag at a time is slow enough that nobody does it, and AI — the thing that was supposed to make maintenance cheap — had no way in. The AI agent in [Excalidraw Plus Whiteboards & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence) closes the gap: the whiteboard stays what it always was — visual, intuitive, for people — but now you can operate it in plain language, from Confluence chat. **Tags:** * [confluence](/blog/tags/confluence.md) * [excalidraw](/blog/tags/excalidraw.md) * [whiteboard](/blog/tags/whiteboard.md) * [diagrams](/blog/tags/diagrams.md) * [ai](/blog/tags/ai.md) * [agent](/blog/tags/agent.md) [**Read more**](/blog/excalidraw-ai-agent-confluence.md) --- ## [FAQ: Widget Carousel for Confluence — Image Sliders, Banners & Dashboards](/blog/faq-confluence-widget-carousel.md) May 2, 2026 · 15 min read [NGPilot](https://ngpilot.com) Confluence pages are powerful containers for knowledge, documentation, and team collaboration. But when it comes to displaying visual content -- product screenshots, event photos, marketing banners, or process walkthroughs -- the standard page layout falls short. Images stacked vertically create long, scroll-heavy pages that are difficult to scan, and Confluence's built-in gallery macro only offers a static thumbnail grid with no interactive slideshow behavior. **Widget Carousel for Confluence** solves this by adding a fully interactive image carousel macro that you can embed on any Confluence page. You select images from page attachments or upload new ones directly, then display them in a customizable slider with configurable width options. The result is a polished, professional-looking carousel that transforms how visual content is presented in your Confluence workspace. This FAQ covers the most common questions teams have about Widget Carousel for Confluence -- from basic setup and content types to advanced configuration, responsive design, and how it compares to Confluence's native gallery macro. Whether you are building a company dashboard, a project landing page, or a team portal, this guide will help you get the most out of the carousel. **Tags:** * [faq](/blog/tags/faq.md) * [confluence](/blog/tags/confluence.md) * [carousel](/blog/tags/carousel.md) * [widget](/blog/tags/widget.md) * [dashboard](/blog/tags/dashboard.md) [**Read more**](/blog/faq-confluence-widget-carousel.md) --- ## [Confluence Wiki Markup: How to View, Edit & Convert It](/blog/confluence-wiki-markup.md) September 23, 2026 · 6 min read [NGPilot](https://ngpilot.com) Every Confluence page has two faces: the one you see in the editor, and the one the database sees. The database face is the **storage format** — an XHTML document with macros as tags — and before it, Confluence stored pages as **wiki markup**: `h1. headings`, `*bold text*`, `{code}` blocks. People still search for wiki markup because half the internet's Confluence advice, every migration script, and a lot of content written before \~2017 speaks that language. And in 2026 the topic got urgent: Atlassian is retiring the legacy editor (full deprecation April 2026), and the new cloud editor **dropped the Markup macro** entirely. Here's how to view, edit, and convert what's actually stored — with or without admin rights. **Tags:** * [confluence](/blog/tags/confluence.md) * [wiki-markup](/blog/tags/wiki-markup.md) * [storage-format](/blog/tags/storage-format.md) * [how-to](/blog/tags/how-to.md) * [admin](/blog/tags/admin.md) * [migration](/blog/tags/migration.md) [**Read more**](/blog/confluence-wiki-markup.md) --- ## [How to Create Wireframes and UI Mockups in Confluence with Excalidraw Plus](/blog/how-to-create-wireframes-confluence.md) May 2, 2026 · 15 min read [NGPilot](https://ngpilot.com) Wireframes are the backbone of every user interface design process. They let product managers, designers, and engineers align on layout, content hierarchy, and interaction flow before writing a single line of code. With [Excalidraw Plus for Confluence](/docs/Excalidraw-plus-for-Confluence/usage.md), you can create wireframes and UI mockups directly inside your Confluence pages, keeping design artifacts next to requirements, user stories, and technical specs. **Tags:** * [confluence](/blog/tags/confluence.md) * [excalidraw](/blog/tags/excalidraw.md) * [wireframe](/blog/tags/wireframe.md) * [mockup](/blog/tags/mockup.md) * [how-to](/blog/tags/how-to.md) * [ui-design](/blog/tags/ui-design.md) [**Read more**](/blog/how-to-create-wireframes-confluence.md) --- ## [Best Confluence Import/Export Apps Compared — 2026 Guide](/blog/confluence-import-export-comparison.md) April 18, 2026 · 7 min read [NGPilot](https://ngpilot.com) Teams move content in and out of Confluence every day — migrating between instances, backing up documentation, importing from other tools, exporting for offline review. Confluence has basic PDF and HTML export built in, but it's limited. No bulk operations, no multi-format support, no structured import workflow. Over a dozen marketplace apps try to fill this gap, but most solve one narrow problem: PDF export, Word import, or Markdown conversion. We built **Modern Importer & Exporter for Confluence** to handle both directions — import and export — across multiple formats. In this post we compare it against every alternative on the Atlassian Marketplace. **Tags:** * [import](/blog/tags/import.md) * [export](/blog/tags/export.md) * [confluence](/blog/tags/confluence.md) * [migration](/blog/tags/migration.md) * [backup](/blog/tags/backup.md) * [markdown](/blog/tags/markdown.md) * [pdf](/blog/tags/pdf.md) * [word](/blog/tags/word.md) * [content-transfer](/blog/tags/content-transfer.md) [**Read more**](/blog/confluence-import-export-comparison.md) --- ## [Kanban Board Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-kanban-board-workflow-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The sprint board on the wall shows 40 items in "In Progress" and the rulebook says "we limit WIP" and nobody agrees on what the limit is. The board is honest; the *documentation* is aspirational. A Kanban diagram in the wiki is the board as a spec — columns, limits, and the rework paths drawn so the workflow is a claim the team can argue with. **Quick answer:** document the team's board in Confluence as a Mermaid `kanban`, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Columns as headings, work items as indented cards; the workflow *rules* (who may move what, when, including rework) as a `stateDiagram` on the same page. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [kanban](/blog/tags/kanban.md) * [workflow](/blog/tags/workflow.md) * [state-diagram](/blog/tags/state-diagram.md) * [agile](/blog/tags/agile.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-kanban-board-workflow-confluence.md) --- ## [Jira Workflow Automation: Complete Guide (2026)](/blog/jira-workflow-automation-complete-guide-2026.md) July 30, 2026 · 4 min read [NGPilot](https://ngpilot.com) Quick Answer Jira workflow automation uses rules with triggers, conditions, and actions to automate repetitive tasks. You can auto-assign issues, transition tickets based on status, send notifications, and update fields — all without code. Start with Jira's built-in automation rules, then scale to marketplace apps for complex workflows. **Tags:** * [jira](/blog/tags/jira.md) * [jira-admin](/blog/tags/jira-admin.md) * [automation](/blog/tags/automation.md) * [workflows](/blog/tags/workflows.md) * [atlassian](/blog/tags/atlassian.md) [**Read more**](/blog/jira-workflow-automation-complete-guide-2026.md) --- ## [How to Write Markdown in Confluence — Syntax, Tables & Code Blocks](/blog/faq-confluence-markdown-editor.md) May 2, 2026 · 13 min read [NGPilot](https://ngpilot.com) Who should read this * **Developers and tech writers** who want to write Markdown in Confluence instead of the WYSIWYG editor * **Teams migrating** README files, docs repos, or API references into Confluence * **Anyone** who needs Mermaid diagrams or LaTeX math inside Markdown content What you'll learn 1. Whether Confluence supports Markdown natively (and why it doesn't) 2. How to write Markdown with live preview, including code blocks, tables, and Mermaid 3. How Markdown content behaves after publish (search, exports, permissions) 4. When to use Markdown vs. Confluence's native WYSIWYG editor Confluence's built-in editor is strictly WYSIWYG — there is no native Markdown editor. For teams who already write in Markdown (README files, docs repos, pull request descriptions), that means manually reformatting every doc through toolbar buttons, losing time and introducing inconsistencies. **Enhanced Markdown for Confluence** solves this by embedding a full Markdown editor with live split preview directly inside Confluence — and it renders Mermaid diagrams, KaTeX/LaTeX math, and 190+ code-highlighted languages, all in one macro. This FAQ answers the questions teams ask most often about writing Markdown in Confluence. **Tags:** * [faq](/blog/tags/faq.md) * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [markdown-editor](/blog/tags/markdown-editor.md) * [writing](/blog/tags/writing.md) [**Read more**](/blog/faq-confluence-markdown-editor.md) --- ## [Enhanced Markdown Setup Tutorial — Insert Macro, Modes & Publish](/blog/how-to-write-markdown-in-confluence.md) May 6, 2026 · 4 min read [NGPilot](https://ngpilot.com) **Confluence Markdown** support lets developers write documentation in their preferred format. This guide covers how to add **Enhanced Markdown** to Confluence for raw Markdown editing, WYSIWYG preview, tables, code blocks, and more. Who should read this * Developers who prefer writing in Markdown * Technical writers needing to import Markdown files * Teams migrating from GitHub or other Markdown-based wikis What you'll learn 1. How to install and use Enhanced Markdown in Confluence 2. Raw Markdown mode vs WYSIWYG mode 3. Supported syntax: tables, code blocks, task lists 4. Comparison with Confluence's native editor **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [tutorial](/blog/tags/tutorial.md) * [wysiwyg](/blog/tags/wysiwyg.md) * [enhanced-markdown](/blog/tags/enhanced-markdown.md) [**Read more**](/blog/how-to-write-markdown-in-confluence.md) --- ## [How to Display JSON, XML, YAML & Code in Confluence (With Syntax Highlighting)](/blog/display-json-xml-code-in-confluence.md) July 23, 2026 · 10 min read [NGPilot](https://ngpilot.com) Who should read this * **Developer teams** documenting APIs, configs, and schemas in Confluence * **Tech writers** who need formatted code samples alongside prose * **Anyone** pasting JSON, XML, YAML, or SQL into Confluence and getting an unreadable wall of text What you'll learn 1. Why Confluence's built-in code block struggles with JSON, XML, and config files 2. How to embed syntax-highlighted code in 85+ languages using a Monaco-powered editor 3. Theme configuration, diff views, and screenshot-ready window chrome 4. When to use a code block vs. a visual JSON structure diagram The scenario every engineering team hits: you're documenting an API in Confluence, and the page needs to show a JSON response, an XML config, a YAML deployment manifest, and a SQL query — all on the same page. You paste each one into Confluence's built-in code block macro, publish, and the result is a wall of monochrome text. No syntax colors. No line numbers that work. JSON braces, XML tags, and YAML indentation all blur together. The reader has to copy-paste your snippet into VS Code just to understand it. The root problem is that Confluence's native code block uses a basic highlighter that wasn't built for the structured data formats modern teams actually work with. JSON, XML, YAML, and SQL each have specific visual conventions — matched braces, nested tags, indentation scopes — that a generic highlighter doesn't handle well. [**Modern Code Blocks for Confluence**](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence) solves this by bringing the Monaco Editor — the same engine that powers VS Code — into Confluence. It accurately highlights 85+ languages including JSON, XML, YAML, SQL, GraphQL, Terraform, Dockerfile, and every mainstream programming language. This guide walks through embedding formatted code and data formats in your Confluence pages. **Tags:** * [confluence](/blog/tags/confluence.md) * [json](/blog/tags/json.md) * [xml](/blog/tags/xml.md) * [yaml](/blog/tags/yaml.md) * [code-blocks](/blog/tags/code-blocks.md) * [syntax-highlighting](/blog/tags/syntax-highlighting.md) * [how-to](/blog/tags/how-to.md) * [api-documentation](/blog/tags/api-documentation.md) [**Read more**](/blog/display-json-xml-code-in-confluence.md) --- ## [Mermaid Charts for Confluence Dashboards: Pie & XY in One Post](/blog/mermaid-charts-dashboard-confluence.md) September 24, 2026 · 6 min read [NGPilot](https://ngpilot.com) The quarterly review loads a 14-tab spreadsheet to answer one question — "where do we actually spend our engineering time?" — because the wiki charts are stale screenshots from last quarter and the numbers table nobody reads. A dashboard is not a spreadsheet: it is the two charts that answer the two questions people keep asking. **Quick answer:** build dashboard charts in Confluence with Mermaid `pie` and `xychart-beta` charts, rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Pie for shares, XY for trends — both as editable text that refreshes like code. This post gives you three copy-paste examples: an effort-share pie, a weekly trend XY, and a dual-series release dashboard. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [pie-chart](/blog/tags/pie-chart.md) * [xychart-beta](/blog/tags/xychart-beta.md) * [dashboard](/blog/tags/dashboard.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-charts-dashboard-confluence.md) --- ## [How to Display JSON, XML, YAML & Code in Confluence (With Syntax Highlighting)](/blog/display-json-xml-code-in-confluence.md) July 23, 2026 · 10 min read [NGPilot](https://ngpilot.com) Who should read this * **Developer teams** documenting APIs, configs, and schemas in Confluence * **Tech writers** who need formatted code samples alongside prose * **Anyone** pasting JSON, XML, YAML, or SQL into Confluence and getting an unreadable wall of text What you'll learn 1. Why Confluence's built-in code block struggles with JSON, XML, and config files 2. How to embed syntax-highlighted code in 85+ languages using a Monaco-powered editor 3. Theme configuration, diff views, and screenshot-ready window chrome 4. When to use a code block vs. a visual JSON structure diagram The scenario every engineering team hits: you're documenting an API in Confluence, and the page needs to show a JSON response, an XML config, a YAML deployment manifest, and a SQL query — all on the same page. You paste each one into Confluence's built-in code block macro, publish, and the result is a wall of monochrome text. No syntax colors. No line numbers that work. JSON braces, XML tags, and YAML indentation all blur together. The reader has to copy-paste your snippet into VS Code just to understand it. The root problem is that Confluence's native code block uses a basic highlighter that wasn't built for the structured data formats modern teams actually work with. JSON, XML, YAML, and SQL each have specific visual conventions — matched braces, nested tags, indentation scopes — that a generic highlighter doesn't handle well. [**Modern Code Blocks for Confluence**](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence) solves this by bringing the Monaco Editor — the same engine that powers VS Code — into Confluence. It accurately highlights 85+ languages including JSON, XML, YAML, SQL, GraphQL, Terraform, Dockerfile, and every mainstream programming language. This guide walks through embedding formatted code and data formats in your Confluence pages. **Tags:** * [confluence](/blog/tags/confluence.md) * [json](/blog/tags/json.md) * [xml](/blog/tags/xml.md) * [yaml](/blog/tags/yaml.md) * [code-blocks](/blog/tags/code-blocks.md) * [syntax-highlighting](/blog/tags/syntax-highlighting.md) * [how-to](/blog/tags/how-to.md) * [api-documentation](/blog/tags/api-documentation.md) [**Read more**](/blog/display-json-xml-code-in-confluence.md) --- ## [API Sequence Diagrams in Confluence with Mermaid (Copy-Paste)](/blog/mermaid-api-sequence-diagram-confluence.md) September 24, 2026 · 5 min read [NGPilot](https://ngpilot.com) The integration doc says "the client calls the API, the API validates and responds" — four words, zero contracts, and the onboarding engineer asks "with what headers, in what order, and what if auth fails?" The code has the truth; the wiki has a paragraph. An API that can't be read as a transcript is an API nobody can safely operate. **Quick answer:** document API flows in Confluence as Mermaid — `sequenceDiagram` for request/response order, `packet-beta` for wire-format frames, ZenUML for branch-heavy async flows — rendered by [Mermaid Plus Diagrams & AI Agent for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence/). Each diagram type answers a different reader: what order, what's on the wire, what branches. This post gives you three copy-paste examples. **Tags:** * [confluence](/blog/tags/confluence.md) * [mermaid](/blog/tags/mermaid.md) * [sequence-diagram](/blog/tags/sequence-diagram.md) * [packet](/blog/tags/packet.md) * [zenuml](/blog/tags/zenuml.md) * [api](/blog/tags/api.md) * [how-to](/blog/tags/how-to.md) [**Read more**](/blog/mermaid-api-sequence-diagram-confluence.md) --- # UML Use Case Diagrams in Confluence (Mermaid, Copy-Paste) September 24, 2026 · 4 min read [NGPilot](https://ngpilot.com) The use case diagram is the scope picture: actors on the outside, what the system does for them on the inside, and — the reason product and engineering fight — the line between them. In Confluence that picture usually comes from a diagramming tool export that goes stale the moment scope moves. Mermaid 12 added the syntax to render UML use case diagrams from text — `usecase-beta` — and Enhanced Markdown for Confluence renders it in the same macro as everything else on the page. This guide gives you the syntax and two copy-paste diagrams. **Quick answer:** To draw a UML use case diagram in Confluence, install [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence) and use a ` ```usecase-beta ` fence in its Markdown macro. Actors, system boundaries, use cases, `include` and generalization arrows — all plain text, rendered live, editable forever. Free for up to 10 users. ## A Payments Platform, in Twelve Lines[​](#a-payments-platform-in-twelve-lines "Direct link to A Payments Platform, in Twelve Lines") Paste this into a ` ```usecase-beta ` fence: ```` ```usecase-beta direction LR actor Customer actor Merchant systemBoundary Platform("Payments Platform") UC1("Pay Invoice") UC2("Issue Refund") UC3("View Statement") end Customer --> UC1 Customer --> UC3 Merchant --> UC2 Merchant --> UC3 UC2 ..> : include UC1 ``` ```` ![UML use case diagram of a payments platform rendered in Confluence](/assets/images/usecase-checkout-218c65a3b666154e39065b3657eb7c5b.svg) What the syntax buys you: two actors, a labeled boundary, three use cases, and one `include` that says refunds always exercise the payment rail — the kind of scope statement that takes a paragraph of prose to say and survives scope changes as a one-line edit. ## The Syntax in One Table[​](#the-syntax-in-one-table "Direct link to The Syntax in One Table") | Token | Meaning | Example | | ------------------------------ | ------------------------------------ | ---------------------------------------------- | | `actor X` | An actor — person or external system | `actor Customer` | | `systemBoundary Name("Label")` | The system's edge, with a label | `systemBoundary Platform("Payments Platform")` | | `UC1("Label")` | A use case inside the boundary | `UC1("Pay Invoice")` | | `A --> UC` | Actor interacts with use case | `Customer --> UC1` | | `UC2 ..> : include UC1` | One use case always invokes another | refund includes payment | | \`Admin -- | > Guest\` | Generalization — role inheritance | | `note for UC1 "text"` | Attach a note to an element | `note for UC1 "Available 24/7"` | | `direction LR` | Layout direction | `LR` for wide diagrams | ## A Second Diagram — Roles and Compliance[​](#a-second-diagram--roles-and-compliance "Direct link to A Second Diagram — Roles and Compliance") The pattern that shows why generalization and notes matter — an admin console: ```` ```usecase-beta direction LR actor Admin actor Auditor actor Guest systemBoundary Console("Admin Console") UC1("Manage Users") UC2("Export Audit Log") UC3("View Dashboard") end Admin --|> Guest Admin --> UC1 Admin --> UC3 Auditor --> UC2 UC2 ..> : include UC3 note for UC2 "Exports require MFA" ``` ```` ![UML use case diagram of an admin console with generalization and a note](/assets/images/usecase-admin-19d53514cead9868d2f83772d5a55697.svg) `Admin --|> Guest` says admins inherit everything a guest can do — one line instead of drawing the guest's edges twice. The note pins the compliance constraint to the exact use case it constrains, where a reviewer will actually see it. ## Where Use Case Diagrams Fit Next to the Others[​](#where-use-case-diagrams-fit-next-to-the-others "Direct link to Where Use Case Diagrams Fit Next to the Others") | Question the reader asks | Diagram | In the same macro | | -------------------------------------- | --------------------------------------- | ----------------- | | What is in scope, and for whom? | Use case (`usecase-beta`) | yes | | How does a flow execute, step by step? | Sequence (`zenuml` / `sequenceDiagram`) | yes | | How do entities relate? | ER diagram | yes | | What is the decision logic? | Flowchart | yes | One macro renders all of them, so a design doc keeps its scope picture, its flow, and its data model as text on one page. Install [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence), paste the payments example, and adjust the boundary to your own scope. Free for up to 10 users. ## Related Guides[​](#related-guides "Direct link to Related Guides") * [ZenUML Sequence Diagrams in Confluence](/blog/zenuml-sequence-diagram-confluence.md) — the flow view that pairs with the scope view * [Mermaid 12 in Confluence and Jira](/blog/mermaid-12-confluence-jira.md) — what the newest Mermaid release adds * [Create Mermaid Diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md) — the full diagram family from the same macro ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [uml](/blog/tags/uml.md) * [use-case-diagram](/blog/tags/use-case-diagram.md) * [mermaid](/blog/tags/mermaid.md) * [markdown](/blog/tags/markdown.md) * [how-to](/blog/tags/how-to.md) * [engineering](/blog/tags/engineering.md) --- # Excalidraw for Confluence — Which Whiteboard and Drawing App Fits Your Team? April 9, 2026 · 6 min read [NGPilot](https://ngpilot.com) **Excalidraw in Confluence** brings hand-drawn style diagrams and whiteboards to your wiki. This guide compares Excalidraw Plus vs draw\.io — features, libraries, and which fits your team's needs. Who should read this * Teams needing whiteboards and diagrams in Confluence * Users comparing Excalidraw vs draw\.io * Anyone adding visual collaboration to documentation What you'll learn 1. Excalidraw vs draw\.io comparison 2. Setting up Excalidraw in Confluence 3. Shape libraries and Mermaid integration 4. Best practices for team collaboration ## Excalidraw vs Traditional Diagramming[​](#excalidraw-vs-traditional-diagramming "Direct link to Excalidraw vs Traditional Diagramming") **Excalidraw** uses a hand-drawn visual style that keeps conversations focused on ideas rather than pixel perfection. It's fast, intuitive, and works great for: * Architecture sketches and design discussions * Wireframes and mockups * Whiteboarding sessions * Brainstorming and mind mapping **Traditional tools** (draw\.io, Gliffy, Lucidchart) produce polished, presentation-ready diagrams with precise layouts. Better for formal documentation and external-facing materials. Both have their place. Let's see what's available. ## What's Available on the Marketplace[​](#whats-available-on-the-marketplace "Direct link to What's Available on the Marketplace") ### Excalidraw and Whiteboard Apps[​](#excalidraw-and-whiteboard-apps "Direct link to Excalidraw and Whiteboard Apps") | App | Vendor | Installs | Rating | Last Updated | Hosting | | ---------------------------------- | ------------------- | -------- | -------------------- | ------------ | --------- | | Excalidraw Diagrams for Confluence | Narva Software | 1,659 | 3.2/5 (10 reviews) | Apr 2026 | Cloud | | Advanced Whiteboards & Workflow | DevSamurai | 303 | 3.9/5 (20 reviews) | Feb 2026 | Cloud | | Miro Whiteboard for Confluence | resolution Reichert | 328 | 2.8/5 (4 reviews) | Apr 2024 | Cloud | | Excalidraw + Mermaid + PlantUML | Fulstech | 255 | 2.5/5 (4 reviews) | Feb 2026 | DC only | | Excalidraw for Confluence | XDevPod | 204 | 3.0/5 (3 reviews) | Jan 2026 | Cloud | | Tldraw whiteboard | P\&D VISION | 67 | 1.0/5 (1 review) | Jun 2025 | Cloud | | **Excalidraw Plus Whiteboards** | **NGPILOT** | **7** | **4.0/5 (1 review)** | **Apr 2026** | **Cloud** | ### Major Diagramming Apps (for reference)[​](#major-diagramming-apps-for-reference "Direct link to Major Diagramming Apps (for reference)") | App | Vendor | Installs | Rating | Hosting | Price (50 users/yr) | | -------------------- | ------- | -------- | --------------------- | ---------- | ------------------- | | draw\.io Diagrams | Seibert | 66,827 | 3.9/5 (1,197 reviews) | Cloud + DC | $975 | | Lucidchart Connector | Lucid | 27,558 | 2.8/5 (258 reviews) | Cloud + DC | Free\* | | Gliffy Diagrams | Gliffy | 17,768 | 3.6/5 (797 reviews) | Cloud + DC | Paid | \*Lucidchart Cloud connector is free but requires a separate Lucidchart subscription. *Data from Atlassian Marketplace, April 2026.* **draw\.io** dominates the entire diagram market with 66,827 installs. It's the safe, established choice with a full visual editor, but it's not Excalidraw-based and carries premium pricing. **Narva Software's Excalidraw Diagrams** (1,659 installs) leads the Excalidraw-specific category. Decent adoption but a 3.2-star rating suggests room for improvement. **The Excalidraw market is nascent** — no Excalidraw-specific app has crossed 2,000 installs. This is an opportunity for better tools. ## Feature Comparison: Excalidraw and Whiteboard Apps[​](#feature-comparison-excalidraw-and-whiteboard-apps "Direct link to Feature Comparison: Excalidraw and Whiteboard Apps") | Feature | Excalidraw Plus (NGPILOT) | Excalidraw Diagrams (Narva) | Excalidraw (XDevPod) | Excalidraw + Mermaid + PlantUML (Fulstech) | Advanced Whiteboards (DevSamurai) | Miro Whiteboard (resolution) | | --------------------------- | -------------------------------- | --------------------------- | --------------------- | ------------------------------------------ | --------------------------------- | ---------------------------- | | **Drawing engine** | Excalidraw | Excalidraw | Excalidraw | Excalidraw + Mermaid + PlantUML | Custom | Miro embed | | **Bundled shape libraries** | 229 (AWS, Azure, GCP, UML, etc.) | Limited | Limited | Limited | Built-in templates | Miro templates | | **Mermaid import** | Yes (text-to-diagram) | No | No | Yes | No | No | | **AI diagram generation** | No | No | Yes (text-to-diagram) | No | No | No | | **Hand-drawn style** | Yes | Yes | Yes | Yes | No (clean) | No (clean) | | **Freehand drawing** | Yes | Yes | Yes | Yes | Yes | Yes | | **Offline/no CDN** | Yes (all libraries bundled) | No | No | No | No | No (requires Miro) | | **Forge-based** | Yes (zero external egress) | No | No | No | No | No | | **Dark mode** | Yes | No | No | No | No | No | | **Preview in page** | Yes | Yes | Yes | Yes | Yes | Yes | | **Data Center support** | No | No | No | Yes | No | No | | **Price (50 users/yr)** | Paid (Atlassian billing) | Paid | Paid | Paid | Paid | Paid | ### Where Excalidraw Plus Stands Out[​](#where-excalidraw-plus-stands-out "Direct link to Where Excalidraw Plus Stands Out") **229 bundled shape libraries** — The largest shape library collection of any Excalidraw Confluence app. AWS, Azure, GCP, Kubernetes, UML, ERD, networking, database, and more — all bundled with the app, available offline. No internet connection needed. No CDN dependency. **Mermaid import** — Write a Mermaid definition and get a visual diagram on the canvas. Then move, resize, and style it alongside your freehand drawings. Only Fulstech offers similar functionality, but their app is DC-only. **Forge-based, zero egress** — Built on Atlassian's Forge platform. All data stays within Atlassian's infrastructure. No external servers, no data leaving the Atlassian ecosystem. Qualified for "Runs on Atlassian" designation. **Dark mode** — The editor adapts to Confluence's dark/light theme automatically. **Highest-rated Excalidraw app** — 4.0/5 from 1 review. Narva's app has 3.2 stars from 10 reviews. ### Where We Could Improve[​](#where-we-could-improve "Direct link to Where We Could Improve") * **7 installs** — We're brand new in a category where Narva has 1,659 installs and draw\.io has 66,827. Building trust takes time. * **No AI features** — XDevPod's Excalidraw app offers text-to-diagram AI generation without needing an OpenAI key. We focus on the core drawing experience. * **No Data Center support** — Cloud-only. Fulstech is the only Excalidraw option for DC users. * **No Miro integration** — If your team already uses Miro boards, resolution's Miro Whiteboard connector embeds them directly in Confluence. * **No BPMN/Process diagrams** — DevSamurai's Advanced Whiteboards includes business model canvases, Kanban boards, and retrospective boards beyond simple drawing. * **No Cloud Fortified status** — We're working toward this. ## Honest Comparison: NGPILOT vs Narva (Excalidraw Market Leader)[​](#honest-comparison-ngpilot-vs-narva-excalidraw-market-leader "Direct link to Honest Comparison: NGPILOT vs Narva (Excalidraw Market Leader)") | | Excalidraw Diagrams (Narva) | Excalidraw Plus (NGPILOT) | | ----------------------- | -------------------------------------------- | ------------------------------------------------------------------- | | **Installs** | 1,659 | 7 | | **Rating** | 3.2/5 (10 reviews) | 4.0/5 (1 review) | | **Shape libraries** | Limited | 229 (bundled, offline) | | **Mermaid import** | No | Yes | | **Forge-based** | No | Yes | | **Offline capable** | No (CDN dependent) | Yes (all libraries bundled) | | **Dark mode** | No | Yes | | **Actively maintained** | Yes (Apr 2026) | Yes (Apr 2026) | | **Best for** | Teams wanting basic Excalidraw in Confluence | Teams needing comprehensive shape libraries and Mermaid integration | Narva has the install base and first-mover advantage. Our app offers more shape libraries (229 vs limited), Mermaid import, Forge security, and offline capability. For teams that need more than basic Excalidraw drawing, the feature difference is significant. ## Which App Do You Need?[​](#which-app-do-you-need "Direct link to Which App Do You Need?") | You need... | Use this | | -------------------------------------------------------- | ---------------------------------------------- | | The dominant, full-featured diagramming suite | draw\.io by Seibert (66,827 installs) | | Polished presentation-ready diagrams | Gliffy by Gliffy (17,768 installs) | | Lucidchart integration | Lucidchart Connector by Lucid | | Basic Excalidraw in Confluence | Excalidraw Diagrams by Narva (1,659 installs) | | AI-generated diagrams | Excalidraw by XDevPod | | Miro boards embedded in Confluence | Miro Whiteboard by resolution | | Data Center Excalidraw support | Excalidraw + Mermaid + PlantUML by Fulstech | | Comprehensive shape libraries + Mermaid + Forge security | **Excalidraw Plus Whiteboards for Confluence** | ## Related Posts[​](#related-posts "Direct link to Related Posts") * [Mermaid Diagrams for Confluence — Which Text-Based Diagram App Should You Pick?](/blog/create-mermaid-diagrams-in-confluence.md) * [Diagram Apps for Jira — Which Diagramming Tool Should Your Team Use?](/blog/jira-diagram-apps-comparison.md) ## Get Started[​](#get-started "Direct link to Get Started") * Install **Excalidraw Plus Whiteboards for Confluence** from the [Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence) * [Read the full documentation](/docs/Excalidraw-plus-for-Confluence/usage.md) Have questions or feedback? Reach out to us at — we'd love to hear from you. Try Excalidraw Plus Whiteboards & AI Agent for Confluence Freeform whiteboards with 220+ shape libraries, plus a Rovo AI agent that draws and edits them from chat — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=excalidraw-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [excalidraw](/blog/tags/excalidraw.md) * [diagrams](/blog/tags/diagrams.md) * [confluence](/blog/tags/confluence.md) --- # How to Visualize Confluence Documentation with SVGs (No Design Skills Required) May 27, 2025 · 2 min read [NGPilot](https://ngpilot.com) Tired of text-heavy Confluence pages? Discover how **1,300+ ready-to-use SVGs** across 25 professional categories can enhance your documentation - no design experience needed. ### Why Visuals Matter in Confluence Docs[​](#why-visuals-matter-in-confluence-docs "Direct link to Why Visuals Matter in Confluence Docs") * Visual content improves information retention by 65% (Forrester) * Teams using visuals report faster task completion (Atlassian research) * Professional graphics boost content credibility ### How to Use Content Craft's SVG Library[​](#how-to-use-content-crafts-svg-library "Direct link to How to Use Content Craft's SVG Library") 1. **Install** the app from Atlassian Marketplace 2. **Insert Macro** at your desired content location 3. **Search & Filter** using category keywords: 🔍 *Example searches*: * "meeting workflow" (Business & Office) * "cloud infrastructure" (Tech & Programming) * "patient care" (Healthcare & Hospital) 4. **Select & Save** your chosen SVG 5. **Display** perfectly formatted graphics instantly ### Professional Use Cases Across 29 Categories[​](#professional-use-cases-across-29-categories "Direct link to Professional Use Cases Across 29 Categories") **Business & Office** 🏢 Create org charts with team role icons 📊 Visualize sales pipelines using workflow diagrams ✍️ Enhance process docs with meeting sequence graphics **Tech & Programming** 🌐 Map API architectures with server/network SVGs 🔧 Illustrate DevOps cycles using toolchain icons 💾 Explain database structures with system diagrams **Healthcare & Hospital** 🏥 Design patient guides with medical equipment SVGs ⚕️ Visualize treatment plans using healthcare icons 🧪 Create lab process flows with science illustrations **Education & School** 🎓 Build course materials with e-learning graphics 📚 Design study guides using classroom SVGs ✏️ Illustrate pedagogical methods with education diagrams **Lifestyle & Fun** ✈️ Enhance travel policies with transportation icons 🍔 Spruce up cafeteria docs with food service SVGs 🏋️ Create wellness programs using sports illustrations ### Why Teams Choose Content Craft[​](#why-teams-choose-content-craft "Direct link to Why Teams Choose Content Craft") ✅ **Search-First Design**: Find SVGs in 25 categories instantly ✅ **Brand-Safe**: Clean, professional styles matching Confluence UI ✅ **Zero Maintenance**: Always-available library (no broken links) ✅ **Enterprise-Ready**: Secure commercial use for all teams **Pro Tip**: Combine multiple SVGs from different categories to create comprehensive process visuals! [Content Craft: Free Business SVG Library for Confluence](https://marketplace.atlassian.com/apps/1237728/content-craft-for-confluence-notion-business-svg-library) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence-tips](/blog/tags/confluence-tips.md) * [visual-documentation](/blog/tags/visual-documentation.md) * [svg-library](/blog/tags/svg-library.md) --- # What Is Atlassian Government Cloud (AGC)? NGPILOT Apps Available (2026) July 30, 2026 · 3 min read [NGPilot](https://ngpilot.com) Quick Answer Atlassian Government Cloud (AGC) is a FedRAMP-authorized deployment of Confluence and Jira designed for U.S. government agencies and contractors. It meets FedRAMP Moderate baseline requirements for handling sensitive government data. NGPILOT has apps available on AGC for teams needing compliant diagramming and content tools. ## What Is Atlassian Government Cloud?[​](#what-is-atlassian-government-cloud "Direct link to What Is Atlassian Government Cloud?") Atlassian Government Cloud (AGC) is a **FedRAMP-authorized** version of Atlassian's cloud products (Confluence, Jira, Jira Service Management) designed specifically for U.S. government agencies and their contractors. ### Key Features[​](#key-features "Direct link to Key Features") | Feature | Details | | ------------------------- | ----------------------------------------- | | **FedRAMP Authorization** | FedRAMP Moderate baseline | | **Data Residency** | U.S. data centers only | | **Compliance** | FISMA, FIPS 140-2, CJIS | | **Security** | Enhanced encryption, access controls | | **Audit** | Continuous monitoring, annual assessments | ### Who Needs AGC?[​](#who-needs-agc "Direct link to Who Needs AGC?") * Federal agencies (DoD, civilian, intelligence) * State and local government * Government contractors (defense, IT, consulting) * Organizations handling CUI (Controlled Unclassified Information) * Any team requiring FedRAMP authorization *** ## AGC vs. Standard Cloud vs. Isolated Cloud[​](#agc-vs-standard-cloud-vs-isolated-cloud "Direct link to AGC vs. Standard Cloud vs. Isolated Cloud") | Feature | Standard Cloud | Isolated Cloud | Government Cloud | | ----------------- | -------------- | -------------- | ----------------- | | **FedRAMP** | No | No | Yes (Moderate) | | **Data Location** | Global | Configurable | U.S. only | | **Compliance** | SOC 2, ISO | SOC 2, ISO | FISMA, FIPS, CJIS | | **Price** | Standard | Premium | Premium | | **Availability** | All regions | Limited | U.S. government | *** ## NGPILOT Apps on AGC[​](#ngpilot-apps-on-agc "Direct link to NGPILOT Apps on AGC") NGPILOT has **1 app** available on Atlassian Government Cloud: | App | Platform | Use Case for Government | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ---------------------------------------------- | | [**Modern Code Blocks for Confluence**](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence?hosting=governmentcloud\&tab=overview) | Confluence | Syntax-highlighted code blocks with 50+ themes | *More NGPILOT apps are being certified for AGC. Check the [AGC collection](https://marketplace.atlassian.com/collections/atlassian-government-cloud) for updates.* *** ## Why NGPILOT on AGC?[​](#why-ngpilot-on-agc "Direct link to Why NGPILOT on AGC?") | Advantage | Details | | -------------------------- | ----------------------------------- | | **Forge-based** | Runs on Atlassian's secure platform | | **No external data calls** | Data stays within your instance | | **Lightweight** | Minimal attack surface | | **Free trials** | Test in your AGC environment first | *** ## How to Get Started with AGC[​](#how-to-get-started-with-agc "Direct link to How to Get Started with AGC") 1. **Check eligibility**: AGC is available to U.S. government agencies and contractors 2. **Contact Atlassian Sales**: Request AGC pricing and onboarding 3. **Deploy instance**: Atlassian provisions your government cloud environment 4. **Install apps**: Browse the [AGC collection](https://marketplace.atlassian.com/collections/atlassian-government-cloud) for certified apps *** ## Frequently Asked Questions[​](#frequently-asked-questions "Direct link to Frequently Asked Questions") **Is AGC FedRAMP authorized?** Yes. AGC holds FedRAMP Moderate authorization. **Can non-government organizations use AGC?** AGC is designed for government and contractors handling CUI. Contact Atlassian for eligibility. **What about ITAR or CJIS compliance?** AGC supports CJIS. For ITAR, contact Atlassian sales for specific requirements. **Are all marketplace apps on AGC?** No. Only apps certified for AGC are available. Check the [AGC collection](https://marketplace.atlassian.com/collections/atlassian-government-cloud). **Can I migrate from standard cloud to AGC?** Yes. Atlassian provides migration support. Contact sales for assistance. *** ## Related Guides[​](#related-guides "Direct link to Related Guides") * [What Is Atlassian Isolated Cloud?](/blog/what-is-atlassian-isolated-cloud.md) * [Best Confluence Apps for Developers (2026)](/blog/best-confluence-apps-developers.md) * [Confluence Permissions: Ultimate Guide](/blog/confluence-permissions-ultimate-guide-2026.md) * [Jira Workflow Automation: Complete Guide](/blog/jira-workflow-automation-complete-guide-2026.md) *** *Looking for isolated cloud (non-government)? See our [Isolated Cloud guide](/blog/what-is-atlassian-isolated-cloud.md).* ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [atlassian](/blog/tags/atlassian.md) * [government-cloud](/blog/tags/government-cloud.md) * [agc](/blog/tags/agc.md) * [fedramp](/blog/tags/fedramp.md) * [compliance](/blog/tags/compliance.md) * [confluence](/blog/tags/confluence.md) * [jira](/blog/tags/jira.md) --- # What Is Atlassian Isolated Cloud? NGPILOT Apps Available (2026) July 30, 2026 · 4 min read [NGPilot](https://ngpilot.com) Quick Answer Atlassian Isolated Cloud lets you deploy marketplace apps within your own dedicated Atlassian cloud instance — separate from other tenants. This provides enhanced data isolation while keeping the benefits of cloud (no server maintenance, automatic updates). NGPILOT has 6 apps certified for Isolated Cloud. ## What Is Atlassian Isolated Cloud?[​](#what-is-atlassian-isolated-cloud "Direct link to What Is Atlassian Isolated Cloud?") Atlassian Isolated Cloud is a deployment option for Confluence and Jira Cloud that gives you a **dedicated instance** rather than a shared multi-tenant environment. ### Standard Cloud vs. Isolated Cloud[​](#standard-cloud-vs-isolated-cloud "Direct link to Standard Cloud vs. Isolated Cloud") | Feature | Standard Cloud | Isolated Cloud | | ------------------ | ------------------------- | -------------------------------- | | **Infrastructure** | Shared across tenants | Dedicated to your organization | | **Data isolation** | Logical separation | Physical separation | | **Compliance** | SOC 2, ISO 27001 | Additional FedRAMP-ready options | | **Cost** | Included in cloud pricing | Premium pricing | | **Maintenance** | Atlassian managed | Atlassian managed | ### Who Needs Isolated Cloud?[​](#who-needs-isolated-cloud "Direct link to Who Needs Isolated Cloud?") * Government agencies with strict data requirements * Healthcare organizations handling PHI * Financial services with regulatory mandates * Enterprises with custom compliance policies *** ## NGPILOT Apps on Isolated Cloud[​](#ngpilot-apps-on-isolated-cloud "Direct link to NGPILOT Apps on Isolated Cloud") NGPILOT has **14 apps** certified for Atlassian Isolated Cloud: | # | App | Platform | | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | 1 | [**Modern Code Blocks for Confluence**](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence) | Confluence | | 2 | [**Excalidraw Diagrams plus Whiteboards for Jira**](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence) | Jira | | 3 | [**Mermaid Plus Diagrams for Jira**](https://marketplace.atlassian.com/apps/2658777397/mermaid-plus-diagrams-for-jira) | Jira | | 4 | [**Modern Questions for Confluence**](https://marketplace.atlassian.com/apps/3250836705/modern-questions-for-confluence) | Confluence | | 5 | [**Manim for Confluence**](https://marketplace.atlassian.com/apps/1384425933/manim-for-confluence) | Confluence | | 6 | [**Modern Issue Templates for Jira**](https://marketplace.atlassian.com/apps/2564635381/modern-issue-templates-for-jira) | Jira | | 7 | [**Simple Bulk Issues Excel/CSV Export for Jira**](https://marketplace.atlassian.com/apps/3818473739/simple-bulk-issues-excel-csv-export-for-jira) | Jira | | 8 | [**Simple Bulk Attachment Downloader for Jira**](https://marketplace.atlassian.com/apps/984902822/simple-bulk-attachment-downloader-for-jira) | Jira | | 9 | [**Content Craft: Free Business SVG Library**](https://marketplace.atlassian.com/apps/1237728/content-craft-free-business-svg-library-for-confluence) | Confluence | | 10 | [**Excalidraw Plus Whiteboards for Confluence**](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence) | Confluence | | 11 | [**Enhanced Markdown for Confluence**](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence) | Confluence | | 12 | [**Mermaid Plus Diagrams & AI Agent for Confluence**](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence) | Confluence | | 13 | [**Modern FAQ for Confluence**](https://marketplace.atlassian.com/apps/1236739/modern-faq-for-confluence) | Confluence | | 14 | [**Google Fonts for Confluence**](https://marketplace.atlassian.com/apps/1236413/google-fonts-for-confluence) | Confluence | *** ## How to Install NGPILOT Apps on Isolated Cloud[​](#how-to-install-ngpilot-apps-on-isolated-cloud "Direct link to How to Install NGPILOT Apps on Isolated Cloud") 1. Go to [Atlassian Marketplace - Isolated Cloud](https://marketplace.atlassian.com/collections/isolated-cloud) 2. Search for the app name 3. Click **Try it free** → Select your isolated instance 4. Approve installation in your admin console 5. App is ready to use *** ## Why Choose NGPILOT on Isolated Cloud?[​](#why-choose-ngpilot-on-isolated-cloud "Direct link to Why Choose NGPILOT on Isolated Cloud?") | Benefit | Details | | --------------------- | ----------------------------------------- | | **Forge-based** | Runs on Atlassian's secure Forge platform | | **No external calls** | Apps process data within your instance | | **Lightweight** | Minimal performance impact | | **Free trials** | Test before committing | *** ## Frequently Asked Questions[​](#frequently-asked-questions "Direct link to Frequently Asked Questions") **Is Isolated Cloud more expensive?** Yes. Isolated Cloud instances have premium pricing. Check Atlassian's pricing page for current rates. **Can I move from standard cloud to isolated cloud?** Yes. Atlassian provides migration paths. Contact Atlassian support for assistance. **Are all marketplace apps available on Isolated Cloud?** No. Only apps certified for Isolated Cloud are available. Check the [Isolated Cloud collection](https://marketplace.atlassian.com/collections/isolated-cloud) for the full list. **Do NGPILOT apps work on both standard and isolated cloud?** Yes. NGPILOT apps are certified for both standard and isolated cloud deployments. **What about data residency?** Isolated Cloud instances are deployed in specific regions. Check Atlassian's data residency options for available locations. *** ## Related Guides[​](#related-guides "Direct link to Related Guides") * [What Is Atlassian Government Cloud (AGC)?](/blog/what-is-atlassian-government-cloud.md) * [Best Confluence Apps for Developers (2026)](/blog/best-confluence-apps-developers.md) * [Mermaid Diagrams in Confluence: Complete Guide](/blog/create-mermaid-diagrams-in-confluence.md) * [Enhanced Markdown for Confluence: Feature Deep Dive](/blog/confluence-markdown-editor-comparison.md) *** *Looking for government cloud? See our [AGC guide](/blog/what-is-atlassian-government-cloud.md).* ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [atlassian](/blog/tags/atlassian.md) * [isolated-cloud](/blog/tags/isolated-cloud.md) * [confluence](/blog/tags/confluence.md) * [jira](/blog/tags/jira.md) * [deployment](/blog/tags/deployment.md) --- # What Is Atlassian Rovo? (And How It Differs from Atlassian Intelligence) August 2, 2026 · 12 min read [NGPilot](https://ngpilot.com) Quick Answer Atlassian Rovo is the cross-platform AI layer for Atlassian Cloud. It does three things: **Search** across Jira, Confluence, and connected SaaS tools; **Chat** that answers questions grounded in your organization's knowledge; and **Agents** that carry out multi-step tasks autonomously. It is different from Atlassian Intelligence, which is the in-product AI engine — Rovo uses that engine and extends it across your entire toolchain. What you'll learn 1. What Rovo actually does (Search, Chat, Agents, Studio) 2. The precise difference between Rovo and Atlassian Intelligence 3. Which data sources Rovo can reach 4. How Rovo Agents work and what they can do 5. Marketplace apps that ship their own Rovo agents 6. What Rovo means for admins and how to prepare your content for it If you have heard the name "Atlassian Rovo" and are not sure whether it is a new product, a rebrand of Atlassian Intelligence, or something your team should adopt, you are not alone. The naming overlap confuses most teams. This guide explains what Rovo is, how it relates to the AI features you may already be using, and what it changes for the people who administer Atlassian Cloud. ## Rovo in one paragraph[​](#rovo-in-one-paragraph "Direct link to Rovo in one paragraph") Rovo is Atlassian's **cross-platform generative AI product**. Instead of living inside a single app, it sits above Jira, Confluence, and Jira Service Management — and above connected external tools like Google Drive, SharePoint, and GitHub — and lets you search, ask questions, and automate work across all of them at once. Think of it as the AI layer that finally makes your sprawling knowledge findable and actionable, rather than another feature buried inside one product. Rovo is built on three pillars: * **Rovo Search** — semantic search across Atlassian content and connected SaaS sources. You ask a question in natural language and get answers with citations pointing to the exact page, issue, or document the answer came from. * **Rovo Chat** — a conversational interface that synthesizes answers from across your tools, so you can ask "what is the status of the Q3 migration?" and get a grounded answer pulling from Jira epics, Confluence decisions, and a linked Slack thread. * **Rovo Agents** — autonomous AI teammates that carry out multi-step tasks: triaging incoming issues, drafting release notes from completed tickets, compiling a weekly project status report from scattered sources. A fourth surface, **Rovo Studio**, is Atlassian's builder tool for composing custom agents, automations, and apps on top of the Rovo platform. ## Rovo vs Atlassian Intelligence: the key distinction[​](#rovo-vs-atlassian-intelligence-the-key-distinction "Direct link to Rovo vs Atlassian Intelligence: the key distinction") This is the most common point of confusion, so it is worth getting exactly right. **Atlassian Intelligence** is the *AI engine embedded inside individual products*. It is the feature that summarizes a Confluence page when you click a button, drafts a Jira comment from a prompt, or turns a rough issue description into structured acceptance criteria. It lives *inside* each product and acts on the content of that product. **Rovo** is the *cross-platform product* that sits above all of them. It uses Atlassian Intelligence as its underlying engine, but extends it in three ways: it searches across multiple products and external SaaS tools, it lets you chat about combined knowledge from all of them, and it runs agents that act across product boundaries. The simplest mental model: **Intelligence is the brain inside each app; Rovo is the colleague who has read everything across all your apps and can act on it.** | Aspect | Atlassian Intelligence | Atlassian Rovo | | ------------------- | ------------------------------------------- | ------------------------------------------------------ | | **Where it lives** | Inside each product (Jira, Confluence, JSM) | A standalone layer above all products | | **Scope** | Single product at a time | Cross-product + external SaaS tools | | **Core capability** | In-product AI (summarize, draft, transform) | Search, chat, and autonomous agents | | **Data reach** | The content of the product you're in | Atlassian + Google Drive, SharePoint, GitHub, and more | | **Relationship** | The underlying AI engine | Uses Intelligence and extends it across tools | If your team only ever works inside one product and only needs in-the-moment AI help, Intelligence may be enough. If your knowledge is spread across Jira, Confluence, and half a dozen SaaS tools and nobody can find anything, that is the problem Rovo solves. ## What Rovo can search[​](#what-rovo-can-search "Direct link to What Rovo can search") This is where Rovo's value becomes concrete. Rovo Search reaches: * **Atlassian products** — Jira issues, Confluence pages and spaces, Jira Service Management tickets and knowledge bases. * **External SaaS sources** — Google Drive, Gmail, Google Calendar, SharePoint, OneDrive, Microsoft Teams, Outlook, Azure DevOps, GitHub, GitLab, Box, Dropbox, Figma, Loom, Lucid, Miro, Smartsheet, DocuSign, Zendesk, and Compass. The practical impact is significant. A question like "where did we document the authentication redesign?" no longer requires knowing whether the answer is in a Confluence page, a Jira epic, a Google Doc, or a Figma file — Rovo searches all of them and returns a grounded answer with citations to the source. For admins, this means **content quality now matters across tools, not just inside Confluence**. A well-titled Jira issue and a clearly named Google Doc are both discoverable by Rovo; a vague one is invisible to semantic search no matter how powerful the model. ## How Rovo Agents work[​](#how-rovo-agents-work "Direct link to How Rovo Agents work") Rovo Agents are the most consequential part of the product, because they move AI from "answers questions" to "does work." An agent is given a **goal** and a set of **trusted data sources**, then executes the steps needed to achieve that goal — reading from the sources it was given, reasoning about what it found, and producing an output or taking an action. Crucially, agents are *grounded*: they work from your organization's actual knowledge rather than generating plausible-sounding guesses. That grounding is what makes them safe enough to delegate real work to. Typical use cases teams are running today: * **Issue triage** — an agent reads each incoming bug, categorizes it, suggests a priority, and assigns it based on the team's historical patterns. * **Status reporting** — an agent compiles a weekly project update by reading completed issues, open blockers, and related Confluence decisions, then drafts the report for a human to review. * **Knowledge synthesis** — an agent researches a topic across Jira, Confluence, and Google Drive and produces a briefing document with citations. * **Onboarding** — an agent answers new-hire questions by searching across policies, team pages, and historical decisions. Agents do not replace humans; they do the gathering and drafting that humans find tedious, leaving the judgment calls to people. The reduction in manual project work is real and measurable for teams that deploy them well. ## Agents that extend Rovo into your content[​](#agents-that-extend-rovo-into-your-content "Direct link to Agents that extend Rovo into your content") The agents above ship with Atlassian. A second category comes from the Marketplace: apps that are **built on Rovo agents**, so you install them once and the agent works inside the tool where the content already lives. We build three: * **[Mermaid Plus Diagrams & AI Agent for Confluence](/apps/mermaid-plus-for-confluence.md)** — a Rovo agent that creates, reads, updates, and converts Mermaid diagrams from Confluence chat. Ask for a flowchart and it renders on the page; follow-ups revise it in place. See [how the Mermaid agent works](/blog/mermaid-ai-agent-confluence.md). * **[Excalidraw Plus Whiteboards & AI Agent for Confluence](/apps/excalidraw-plus-for-confluence.md)** — the canvas-side counterpart, with a Rovo agent that draws whiteboards from a prompt, edits existing shapes by name ("rename Service A to Auth Service"), searches a space for boards, and converts Mermaid or PlantUML in either direction. See [how the Excalidraw agent works](/blog/excalidraw-ai-agent-confluence.md). * **[Issue History Agent for Jira](/apps/issue-history-agent-for-jira.md)** — a Rovo agent that answers plain-language questions about what changed on an issue — "what changed recently on this issue?" — against live Jira data, citing the changes it used. See [how to see who changed what in Jira](/blog/jira-issue-history.md). The pattern is the same in all three, and it is the part worth noticing: an agent scoped to one content type beats a general-purpose assistant on that content. "Draw this flow" is a precise instruction for an agent that only knows how to draw flows; handing it to a general assistant gets you a text description of a flowchart and a blank canvas. If your team documents with diagrams, adding one of these is a smaller step than deploying a custom agent. ## What Rovo means for admins[​](#what-rovo-means-for-admins "Direct link to What Rovo means for admins") If you administer Atlassian Cloud, Rovo changes three things about how you should think about your content and apps. **1. Content discoverability now depends on semantics, not navigation.** Historically, a page was findable if it was linked from the right place or titled with the exact keyword. With Rovo, a page is findable if its *meaning* matches the question being asked. That rewards clear, substantive writing and penalizes vague titles and thin content. The cleanup work you may have been putting off — fixing bad page titles, merging duplicate pages, writing real descriptions — now has direct ROI because Rovo surfaces well-written content and buries weak content. **2. Permissions are respected, which means permission hygiene matters more.** Rovo only returns answers a user is allowed to see — it inherits Atlassian's permission model. That is the right behavior, but it means broken or overly broad permissions produce wrong results: if a page is accidentally restricted, Rovo will not find it for people who need it; if a space is too open, Rovo may surface confidential content in answers. Auditing permissions becomes part of keeping AI useful. **3. Forge apps are more Rovo-friendly than Connect apps.** Rovo indexes content that lives as native Atlassian data. Forge apps store their data on the Atlassian platform — in Confluence storage format, Jira entities, or Atlassian-managed storage — so their content is discoverable to Rovo. Connect apps often store content on vendor-hosted servers outside Atlassian, where Rovo cannot reach it. If AI discoverability of your app content matters, this is one more reason to prefer Forge. (For a deeper treatment of the Forge vs Connect split, see our [Forge vs Connect guide](/blog/forge-vs-connect-atlassian-admins-2026.md).) ## Licensing and availability[​](#licensing-and-availability "Direct link to Licensing and availability") Rovo is included on **Standard, Premium, and Enterprise Cloud plans** for Jira, Confluence, Jira Service Management, and Teamwork Collections. AI is activated automatically on these plans — there is no separate Rovo license to procure for most Cloud customers. Some eligible plans are still in the process of gaining access as the rollout completes; if you do not see Rovo yet, it is likely on its way. For Data Center customers, Rovo Data Center connectors for Jira, Confluence, and JSM enable data synchronization so cloud AI features can work with on-premises content. ## A practical note for NGPILOT users[​](#a-practical-note-for-ngpilot-users "Direct link to A practical note for NGPILOT users") Every NGPILOT app is built on Forge, which means the content your team creates with them — diagrams rendered into Confluence pages, Markdown saved as native storage format, code blocks, FAQs, and structured content — lives as Atlassian data, not in an external vendor store. That is exactly the kind of content Rovo can index and ground its answers in. That is the passive half of the story. The active half is the three Rovo agents listed above: those apps do not merely produce content Rovo can read, they *are* agents Rovo drives, scoped to one content type each. If you use NGPILOT apps to document your processes and systems, you get both — findable output, and agents that maintain it. Browse the [app catalog](/apps.md) or explore [solutions by scenario](/solutions.md) to see how the apps fit the way your team works. ## Frequently Asked Questions[​](#frequently-asked-questions "Direct link to Frequently Asked Questions") ### Is Rovo the same as ChatGPT for Atlassian?[​](#is-rovo-the-same-as-chatgpt-for-atlassian "Direct link to Is Rovo the same as ChatGPT for Atlassian?") No. ChatGPT is a general-purpose chatbot with no access to your organization's data unless you explicitly connect it. Rovo is grounded in your Atlassian and connected SaaS content — every answer cites the source it came from, and permissions are respected so users only see what they are allowed to see. Rovo also runs agents that take action, not just answer questions. ### Do I need to pay extra for Rovo?[​](#do-i-need-to-pay-extra-for-rovo "Direct link to Do I need to pay extra for Rovo?") For most Cloud customers, no. Rovo is included on Standard, Premium, and Enterprise Cloud plans for Jira, Confluence, JSM, and Teamwork Collections, with AI activated automatically. If you are on a lower plan or Data Center, check your specific entitlement. ### Can Rovo replace our internal search tool?[​](#can-rovo-replace-our-internal-search-tool "Direct link to Can Rovo replace our internal search tool?") For many teams, yes. Rovo Search replaces keyword-matching search with semantic search that understands meaning and returns grounded answers with citations. It reaches both Atlassian content and external SaaS sources, which most internal search tools cannot. The main caveat is permissions: Rovo is only as accurate as your permission model is clean. ### Will Rovo agents make changes to my Jira or Confluence automatically?[​](#will-rovo-agents-make-changes-to-my-jira-or-confluence-automatically "Direct link to Will Rovo agents make changes to my Jira or Confluence automatically?") Agents can take actions like assigning issues or drafting content, but you control what they are allowed to do. Most teams start with read-and-draft agents (research, summarize, compile) and gradually grant write actions as trust builds. The grounding in your actual data is what keeps agents from going off the rails. ### Where can I read Atlassian's official Rovo documentation?[​](#where-can-i-read-atlassians-official-rovo-documentation "Direct link to Where can I read Atlassian's official Rovo documentation?") Atlassian's [Rovo product page](https://www.atlassian.com/software/rovo) covers the core capabilities, and the [Atlassian AI and Rovo community](https://community.atlassian.com/forums/Atlassian-AI-Rovo-discussions/) tracks real-world usage and updates. ### Are there Rovo agents I can add by installing an app?[​](#are-there-rovo-agents-i-can-add-by-installing-an-app "Direct link to Are there Rovo agents I can add by installing an app?") Yes. Beyond the agents Atlassian ships, some Marketplace apps are built on Rovo agents — install the app and the agent works inside the tool where the content already lives. We build three: [Mermaid Plus for Confluence](/apps/mermaid-plus-for-confluence.md) (create, read, update, and convert Mermaid diagrams from chat), [Excalidraw Plus for Confluence](/apps/excalidraw-plus-for-confluence.md) (draw, edit, search, and convert whiteboards from chat), and [Issue History Agent for Jira](/apps/issue-history-agent-for-jira.md) (answer "what changed?" on an issue). An agent scoped to one content type generally beats a general-purpose assistant on that content, because "draw this flow" is a precise instruction for an agent that only draws flows. *** *NGPILOT builds exclusively on Forge, so content created with NGPILOT apps is native Atlassian data — discoverable by Rovo. Browse the [app catalog](/apps.md) or learn about [how NGPILOT handles security and data](/trust.md).* ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [atlassian](/blog/tags/atlassian.md) * [rovo](/blog/tags/rovo.md) * [ai](/blog/tags/ai.md) * [explained](/blog/tags/explained.md) * [admin](/blog/tags/admin.md) --- # Whiteboarding Architecture Sessions in Jira & Confluence July 23, 2026 · 7 min read [NGPilot](https://ngpilot.com) Who should read this * **Engineering teams** that sketch architecture during planning and design reviews * **Tech leads** who want design decisions captured on the ticket, not lost in a photo * **Anyone** comparing freehand whiteboarding vs. text-based (Mermaid) diagramming What you'll learn 1. How to run an architecture whiteboarding session that stays attached to the Jira epic 2. When freehand sketching beats structured diagrams (and vice versa) 3. Using 229 cloud/UML/networking shape libraries inside Jira 4. How Excalidraw and Mermaid complement each other Every architecture review ends the same way: the team sketches a system on a whiteboard, someone takes a blurry phone photo, and the diagram is never seen again. The next sprint a new engineer joins, asks how the system fits together, and the whiteboard gets redrawn from memory — different every time. The fix is to capture the architecture sketch on the ticket it describes, editable by anyone on the team, versioned with the issue. That's what [**Excalidraw Diagrams plus Whiteboards for Jira**](https://marketplace.atlassian.com/apps/2139233994/excalidraw-diagrams-plus-whiteboards-for-jira) does: it adds a full drawing canvas to every Jira issue, with 229 bundled shape libraries and freehand drawing. The same experience is available in Confluence via [Excalidraw plus Whiteboards for Confluence](https://marketplace.atlassian.com/apps/123651/excalidraw-plus-whiteboards-for-confluence). This guide walks through running an architecture session that produces a saved, shareable diagram. ![The Excalidraw editor inside a Jira issue, showing the canvas with shape libraries and a diagram in progress.](/assets/images/h1-16698ec7c8717fc28c25511a382d0071.png) ## Freehand sketching vs. structured diagrams: when to use which[​](#freehand-sketching-vs-structured-diagrams-when-to-use-which "Direct link to Freehand sketching vs. structured diagrams: when to use which") Before the workflow, it's worth being clear about when freehand whiteboarding (Excalidraw) is the right tool and when text-based diagramming (Mermaid) is. They solve different problems: | You need… | Use | Why | | -------------------------------------------------------- | -------------------------------- | --------------------------------------------------------------------------- | | Rapid ideation, messy brainstorming, "thinking out loud" | **Excalidraw** (freehand) | No syntax to get right; the hand-drawn style signals "draft, not final" | | Precise, reproducible, version-controllable diagrams | **Mermaid** | Text-based, diffs cleanly, regenerates identically | | Cloud architecture with AWS/Azure/GCP icons | **Excalidraw** (shape libraries) | 229 bundled icon packs, drag-and-drop | | Service interaction sequences | **Mermaid** (sequence diagram) | Syntax enforces the ordering | | Wireframes for UI stories | **Excalidraw** | Freehand rectangles and text are faster than structured layout for early UI | The insight many teams miss: **Excalidraw can import Mermaid**. You can type or paste a Mermaid definition and the editor generates the visual diagram on the canvas, where you can then move, resize, and restyle the elements like any hand-drawn shape. That gives you the precision of Mermaid with the editability of freehand — best of both for architecture sessions where the diagram evolves during discussion. ## Step-by-step: capture an architecture sketch on a Jira epic[​](#step-by-step-capture-an-architecture-sketch-on-a-jira-epic "Direct link to Step-by-step: capture an architecture sketch on a Jira epic") ### 1. Install Excalidraw Diagrams plus Whiteboards for Jira[​](#1-install-excalidraw-diagrams-plus-whiteboards-for-jira "Direct link to 1. Install Excalidraw Diagrams plus Whiteboards for Jira") Install [Excalidraw Diagrams plus Whiteboards for Jira](https://marketplace.atlassian.com/apps/2139233994/excalidraw-diagrams-plus-whiteboards-for-jira) from the Marketplace. It's free for up to 10 users. Once installed, a whiteboard panel appears automatically on every Jira issue — no extra setup. ### 2. Open the epic and start the diagram[​](#2-open-the-epic-and-start-the-diagram "Direct link to 2. Open the epic and start the diagram") Open the epic or story where the architecture decision lives. In the right-side panel, find the **Excalidraw** section and click the **+** (Create Diagram) button. A full-screen editor opens with a blank canvas. ![Sketching a system architecture on the Excalidraw canvas inside Jira, with shapes and connectors.](/assets/images/h2-f20d6b65a626f2752584f7a41d5f1f38.png) ### 3. Sketch, drag shapes, or import Mermaid[​](#3-sketch-drag-shapes-or-import-mermaid "Direct link to 3. Sketch, drag shapes, or import Mermaid") You have three ways to build the diagram, and most architecture sessions use a mix: **Freehand sketch.** Use the toolbar to draw rectangles, arrows, and text. This is fastest for the initial "boxes and lines" pass during a discussion. The hand-drawn Excalidraw style intentionally signals that the diagram is a work in progress — which is the right signal during a design review. **Drag cloud shape libraries.** Open the library panel from the left sidebar and click **Browse libraries**. There are 229 bundled packs — AWS, Azure, GCP, UML, networking, and more. Add the ones relevant to your stack, then drag icons onto the canvas. This is how you turn a rough sketch into a recognizable architecture diagram ("that's an API Gateway, that's Lambda, that's RDS"). **Import Mermaid.** If part of the architecture is better expressed as text (a service-call sequence, a state machine), use the Mermaid tool from the toolbar. Type or paste the Mermaid definition and the diagram generates on the canvas. You can then reposition the generated elements alongside your freehand sketches. ### 4. Save the drawing to the issue[​](#4-save-the-drawing-to-the-issue "Direct link to 4. Save the drawing to the issue") Click **Save Drawing**. The editor closes and the diagram preview appears in the issue panel. The diagram is saved as an attachment on the issue, so it's visible to everyone who can see the issue — no app installation required for viewers. The preview shows up in Jira exports too, so the architecture travels with the epic when it's exported to PDF or a spreadsheet. ## When the diagram belongs in Confluence instead[​](#when-the-diagram-belongs-in-confluence-instead "Direct link to When the diagram belongs in Confluence instead") The same Excalidraw experience is available in Confluence via [Excalidraw plus Whiteboards for Confluence](https://marketplace.atlassian.com/apps/123651/excalidraw-plus-whiteboards-for-confluence). Use the Jira version when the diagram is specific to one ticket; use the Confluence version when the diagram is the team's durable reference architecture that many tickets will link to. | Scenario | Where the diagram lives | | ------------------------------------------ | ---------------------------------- | | Architecture for this specific epic | **Jira** (on the epic) | | The team's standing system architecture | **Confluence** (architecture page) | | Bug reproduction flowchart | **Jira** (on the bug) | | Onboarding diagram every new engineer sees | **Confluence** (onboarding space) | | Wireframe for one UI story | **Jira** (on the story) | | Design system component map | **Confluence** (design space) | The drawing format is compatible between the two apps, so you can start a sketch on a Jira story during refinement and later move the finalized version to a Confluence architecture page. ## Running the actual session: a repeatable workflow[​](#running-the-actual-session-a-repeatable-workflow "Direct link to Running the actual session: a repeatable workflow") Here's the cadence that turns a one-off sketch into a maintained artifact: 1. **During the design review** — sketch freehand on the epic's Excalidraw canvas. Don't worry about precision; the goal is to capture the discussion. 2. **End of the session** — a volunteer swaps rough boxes for cloud shape-library icons where it matters (AWS/Azure/GCP services). This takes 5 minutes and makes the diagram readable later. 3. **Any sequence or state logic** — convert those parts to Mermaid via the import tool, so they regenerate reliably and can be version-controlled. 4. **Save** — the diagram now lives on the epic permanently. Link to it from related stories. 5. **Next sprint** — when the architecture changes, open the epic, click **Edit Diagram**, and update. The history is preserved as issue attachments. This workflow solves the "redraw the whiteboard every time" problem: the architecture diagram is versioned with the epic it describes, and any engineer can open the epic and see the current design without asking. ## FAQ[​](#faq "Direct link to FAQ") ### Does Jira have a built-in whiteboard or diagram tool?[​](#does-jira-have-a-built-in-whiteboard-or-diagram-tool "Direct link to Does Jira have a built-in whiteboard or diagram tool?") No. Jira does not include a native whiteboard or freehand drawing tool. You need a Marketplace app like [Excalidraw Diagrams plus Whiteboards for Jira](https://marketplace.atlassian.com/apps/2139233994/excalidraw-diagrams-plus-whiteboards-for-jira) to add a drawing canvas to Jira issues. ### Can I use Excalidraw in both Jira and Confluence?[​](#can-i-use-excalidraw-in-both-jira-and-confluence "Direct link to Can I use Excalidraw in both Jira and Confluence?") Yes. NGPILOT ships two companion apps — Excalidraw Diagrams plus Whiteboards for Jira, and Excalidraw plus Whiteboards for Confluence. Both use the same drawing format, so diagrams can be moved between them. Use the Jira version for ticket-specific diagrams and the Confluence version for durable team reference pages. ### How many shape libraries are included?[​](#how-many-shape-libraries-are-included "Direct link to How many shape libraries are included?") 229 bundled shape libraries are included with the app — AWS, Azure, GCP, UML, networking, and many more. All libraries are bundled locally (no CDN calls), so they load instantly and work without an internet connection. ### Can Excalidraw generate diagrams from Mermaid syntax?[​](#can-excalidraw-generate-diagrams-from-mermaid-syntax "Direct link to Can Excalidraw generate diagrams from Mermaid syntax?") Yes. The editor includes a Mermaid tool that lets you type or paste a Mermaid definition (flowchart, ER diagram, sequence diagram, etc.) and generate the visual diagram on the canvas. The generated elements can then be moved, resized, and styled like any other shape. This combines the precision of Mermaid with the editability of freehand drawing. ### Is Excalidraw Diagrams plus Whiteboards for Jira free?[​](#is-excalidraw-diagrams-plus-whiteboards-for-jira-free "Direct link to Is Excalidraw Diagrams plus Whiteboards for Jira free?") The app is free for up to 10 users. Beyond 10 users, standard Atlassian Marketplace licensing applies. ## Related guides[​](#related-guides "Direct link to Related guides") Try Excalidraw Plus Whiteboards & AI Agent for Confluence Freeform whiteboards with 220+ shape libraries, plus a Rovo AI agent that draws and edits them from chat — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237651/excalidraw-plus-whiteboards-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=excalidraw-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [confluence](/blog/tags/confluence.md) * [excalidraw](/blog/tags/excalidraw.md) * [whiteboard](/blog/tags/whiteboard.md) * [architecture](/blog/tags/architecture.md) * [diagrams](/blog/tags/diagrams.md) * [how-to](/blog/tags/how-to.md) --- # How to Write Better Jira Ticket Descriptions with AI July 30, 2026 · 7 min read [NGPilot](https://ngpilot.com) Quick Answer AI can expand brief Jira ticket summaries into detailed descriptions with acceptance criteria, edge cases, and technical context. This reduces back-and-forth and helps developers understand requirements faster. What you'll learn 1. How to define a ticket description standard for your team 2. How to use AI to expand brief descriptions into detailed tickets 3. How to generate acceptance criteria with AI assistance 4. How to add context with examples and edge cases The quality of a Jira ticket determines how quickly work gets done. A vague description like "fix the login bug" creates hours of back-and-forth. A detailed description with acceptance criteria, edge cases, and technical context lets developers start immediately. AI can transform brief summaries into comprehensive tickets. This guide covers how to use AI to write better Jira descriptions, from prompt templates to review workflows. ## Why Ticket Descriptions Matter[​](#why-ticket-descriptions-matter "Direct link to Why Ticket Descriptions Matter") **Development speed.** Clear descriptions eliminate the need for clarification meetings. Developers can start coding immediately instead of guessing at requirements. **Quality.** Detailed acceptance criteria ensure nothing is missed. QA knows exactly what to test, and developers know exactly what to build. **Estimation.** Better descriptions lead to better estimates. When the team understands the scope, they can provide accurate story points. **Knowledge preservation.** Well-written tickets serve as documentation. New team members can understand past decisions by reading ticket history. ## How to Write Better Jira Descriptions with AI: Step-by-Step[​](#how-to-write-better-jira-descriptions-with-ai-step-by-step "Direct link to How to Write Better Jira Descriptions with AI: Step-by-Step") ### 1. Define Your Ticket Description Standard[​](#1-define-your-ticket-description-standard "Direct link to 1. Define Your Ticket Description Standard") Before using AI, establish what a good description looks like: **Bug report template:** ``` ## Bug Summary [One-sentence description of the bug] ## Steps to Reproduce 1. [Step 1] 2. [Step 2] 3. [Step 3] ## Expected Result [What should happen] ## Actual Result [What actually happens] ## Environment - Browser: [Chrome 125, Firefox 126] - OS: [Windows 11, macOS 14] - App Version: [2.3.1] ## Screenshots/Videos [Attach if applicable] ## Severity - [ ] Critical (system down) - [ ] High (major feature broken) - [ ] Medium (workaround exists) - [ ] Low (cosmetic) ``` **Feature request template:** ``` ## Feature Summary [One-sentence description] ## User Story As a [role], I want [feature] so that [benefit]. ## Business Value [Why this matters — quantify if possible] ## Acceptance Criteria - [ ] [Criterion 1] - [ ] [Criterion 2] - [ ] [Criterion 3] ## Technical Notes [Implementation considerations] ## Mockups/Wireframes [Attach if applicable] ``` ### 2. Use AI to Expand Brief Descriptions[​](#2-use-ai-to-expand-brief-descriptions "Direct link to 2. Use AI to Expand Brief Descriptions") Start with a short summary, then use AI to expand it: **Example input:** ``` Write a Jira feature ticket for: "Add dark mode to the settings page" Include: - User story - Acceptance criteria (at least 5) - Edge cases - Technical considerations - UI/UX requirements ``` **AI output:** ``` ## Feature Summary Add dark mode toggle to user settings page, allowing users to switch between light and dark themes. ## User Story As a user, I want to switch between light and dark themes so that I can use the app comfortably in different lighting conditions. ## Business Value - Reduces eye strain for users working in low-light environments - Aligns with industry standard (90% of top apps offer dark mode) - Expected to increase session duration by 10-15% ## Acceptance Criteria - [ ] Dark mode toggle appears in Settings > Appearance section - [ ] Toggle switches between Light, Dark, and System Default - [ ] Selection persists across sessions (saved to user preferences) - [ ] All pages respect the theme selection within 500ms - [ ] Images and icons adjust for dark background (no washed-out colors) - [ ] System Default option follows OS preference automatically ## Edge Cases - What happens if user switches theme while on a page with inline styles? - How does theme affect embedded content (iframes, third-party widgets)? - What about print stylesheets — should dark mode disable for print? ## Technical Considerations - Use CSS custom properties for theme colors - Consider prefers-color-scheme media query for system default - Test with screen readers for contrast accessibility (WCAG AA) - Ensure images have dark-friendly variants or transparent backgrounds ``` ### 3. Generate Acceptance Criteria with AI[​](#3-generate-acceptance-criteria-with-ai "Direct link to 3. Generate Acceptance Criteria with AI") AI excels at generating comprehensive acceptance criteria: **Prompt for acceptance criteria:** ``` Generate acceptance criteria for a Jira ticket about: "[your feature description]" Include: 1. Happy path scenarios 2. Error handling 3. Edge cases 4. Performance requirements 5. Accessibility requirements Format as checkboxes with clear, testable statements. ``` **Example:** ``` ## Acceptance Criteria ### Happy Path - [ ] User can toggle dark mode in Settings - [ ] Theme applies immediately without page refresh - [ ] Selection persists after logout and login - [ ] All text meets WCAG AA contrast ratio (4.5:1) ### Error Handling - [ ] If theme fails to load, default to light mode - [ ] Show error message if save fails, allow retry ### Edge Cases - [ ] System Default follows OS preference in real-time - [ ] Dark mode works with high contrast mode enabled - [ ] Theme applies to all Confluence pages, not just current space ### Performance - [ ] Theme switch completes within 500ms - [ ] No layout shift during theme transition ``` ### 4. Add Context with AI-Generated Examples[​](#4-add-context-with-ai-generated-examples "Direct link to 4. Add Context with AI-Generated Examples") Use AI to generate examples that clarify requirements: **Prompt for examples:** ``` Given this feature description: "[your description]" Generate: 1. 3 example inputs with expected outputs 2. 2 edge cases that developers might miss 3. 1 negative example (what the feature should NOT do) ``` **Example output:** ``` ## Examples ### Example 1: Basic toggle Input: User clicks dark mode toggle Output: Page switches to dark theme, toggle shows "Dark" state, save button appears ### Example 2: System default Input: User selects "System Default" and OS is in dark mode Output: App switches to dark theme, follows OS changes automatically ### Example 3: Persistence Input: User enables dark mode, logs out, logs back in Output: Dark mode is still enabled ### Edge Case: Rapid toggling Input: User rapidly clicks toggle 10 times Output: Final state is applied, no flickering or stuck state ### Negative Example Input: User enables dark mode Output: Embedded third-party content should NOT be forced into dark mode (respect their own theme) ``` ### 5. Review and Refine AI-Generated Descriptions[​](#5-review-and-refine-ai-generated-descriptions "Direct link to 5. Review and Refine AI-Generated Descriptions") AI is a starting point, not a final product. Review for: **Accuracy checklist:** * Technical details are correct * Acceptance criteria are testable * Edge cases are realistic * No hallucinated features or requirements * Alignment with project context **Quality checklist:** * Clear, concise language * Consistent formatting * Appropriate level of detail * No duplicate information * Links to related tickets **Team-specific checklist:** * Follows team's ticket template * Uses correct project and component fields * Includes story point estimate * Assigned to correct sprint ## FAQ[​](#faq "Direct link to FAQ") ### How can AI improve Jira ticket descriptions?[​](#how-can-ai-improve-jira-ticket-descriptions "Direct link to How can AI improve Jira ticket descriptions?") AI can expand brief summaries into detailed descriptions, generate acceptance criteria, identify edge cases, and ensure consistent formatting. This reduces back-and-forth between product and development teams. ### What should a good Jira ticket description include?[​](#what-should-a-good-jira-ticket-description-include "Direct link to What should a good Jira ticket description include?") A good description includes: clear summary, user story or business context, acceptance criteria, technical requirements, edge cases, and links to related tickets or documentation. ### Can AI write Jira tickets automatically?[​](#can-ai-write-jira-tickets-automatically "Direct link to Can AI write Jira tickets automatically?") AI can generate draft tickets from brief inputs, but human review is essential. Use AI to expand and refine your descriptions, not to replace the thinking process behind requirements. ### How do I write prompts for Jira descriptions?[​](#how-do-i-write-prompts-for-jira-descriptions "Direct link to How do I write prompts for Jira descriptions?") Be specific about the ticket type (bug, feature, task), the audience (developer, QA, designer), and the required sections. Include context about the project and existing patterns. ### What AI tools work with Jira for description writing?[​](#what-ai-tools-work-with-jira-for-description-writing "Direct link to What AI tools work with Jira for description writing?") Atlassian Intelligence provides native AI in Jira. Third-party apps like AI Assistant for Jira and ScriptRunner offer additional AI capabilities for description generation and enhancement. ## Related guides[​](#related-guides "Direct link to Related guides") * [How to Create Jira Issue Templates for Consistent Workflows](/blog/create-jira-issue-templates-for-consistent-workflows.md) * [Jira JQL Cheat Sheet: 20 Queries Every Team Needs](/blog/jira-jql-cheat-sheet-common-queries.md) * [How to Use ChatGPT in Confluence for Better Documentation](/blog/how-to-use-chatgpt-in-confluence.md) * [Jira Workflow Automation: How to Automate Repetitive Tasks](/blog/jira-workflow-automation-guide.md) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [jira](/blog/tags/jira.md) * [ai](/blog/tags/ai.md) * [ticket-descriptions](/blog/tags/ticket-descriptions.md) * [how-to](/blog/tags/how-to.md) * [productivity](/blog/tags/productivity.md) --- # Write Markdown in Confluence With Mermaid, LaTeX & Code — One Editor, Live Preview July 23, 2026 · 9 min read [NGPilot](https://ngpilot.com) Who should read this * **Engineering teams** who write docs in Markdown but live in Confluence * **Research/academic teams** who need LaTeX math equations inside wiki pages * **Anyone** tired of Markdown editors that drop Mermaid diagrams or render math as plain text What you'll learn 1. How to write Markdown in Confluence with a live split preview 2. Embedding Mermaid flowcharts and ZenUML sequence diagrams inside Markdown 3. Rendering KaTeX and full LaTeX (MathJax) math — inline, block, and fenced 4. GitHub-flavored tables, 190+ code languages, and dark mode The scenario every technical team hits: your engineering docs live in Markdown — READMEs, API references, design docs — and they contain diagrams (Mermaid), equations (LaTeX), and code samples. You paste that Markdown into Confluence, and it falls apart. The Mermaid code blocks render as plain text. The LaTeX equations show as raw `$...$` syntax. The code blocks lose their syntax highlighting. Confluence's native editor is WYSIWYG, not Markdown, and the import tools treat Markdown as a one-time conversion rather than something you edit live. [**Enhanced Markdown for Confluence**](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence) solves this with a Markdown editor that renders everything inline — Mermaid diagrams, KaTeX and LaTeX math, syntax-highlighted code, and GitHub-flavored tables — with a live split preview. It runs on the [Quikdown](https://github.com/deftio/quikdown) engine, so all rendering libraries are bundled locally (no external CDN dependencies, which matters for "Runs on Atlassian" compliance). This guide walks through writing Markdown in Confluence with diagrams, math, and code all rendering live. ![Split view editing in Enhanced Markdown — Markdown source on the left, live rendered preview on the right showing a Mermaid diagram, a highlighted code block, and a LaTeX formula.](/assets/images/split-view-2e97b86e7982297b78f9b8be82bd39dd.png) ## Why writing Markdown in Confluence is harder than it sounds[​](#why-writing-markdown-in-confluence-is-harder-than-it-sounds "Direct link to Why writing Markdown in Confluence is harder than it sounds") Confluence is a WYSIWYG editor — it stores pages in its own storage format, not Markdown. The native "Markdown import" is a one-way conversion: it transforms your Markdown into Confluence storage format once, and after that you edit the result in the visual editor. The Markdown source is gone. This breaks down for teams whose content *is* Markdown: * **Mermaid diagrams die at import.** When you paste Markdown containing ` ```mermaid ` fences, Confluence's importer treats them as plain code blocks. No diagram renders. (This is a [known community frustration](https://community.atlassian.com/forums/Confluence-questions/Copy-markdown-code-into-confluence-with-embedded-mermaid-code/qaq-p/3238848).) * **LaTeX math becomes raw text.** `$E = mc^2$` stays as the literal characters, not the rendered equation. * **No live preview.** You import blind, then discover rendering problems after publish. A Markdown *macro* — one that you edit and save as Markdown, with the rendered output generated on the fly — fixes all three. The Markdown source stays editable; diagrams, math, and code render live. ## Step-by-step: write Markdown with Mermaid, LaTeX, and code[​](#step-by-step-write-markdown-with-mermaid-latex-and-code "Direct link to Step-by-step: write Markdown with Mermaid, LaTeX, and code") ### 1. Install Enhanced Markdown for Confluence[​](#1-install-enhanced-markdown-for-confluence "Direct link to 1. Install Enhanced Markdown for Confluence") Install [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence) from the Marketplace. It's free for up to 10 users. ### 2. Insert the Markdown macro[​](#2-insert-the-markdown-macro "Direct link to 2. Insert the Markdown macro") Edit any Confluence page. Type `/enhanced markdown` and select the macro. The editor opens in **Split** mode by default — Markdown source on the left, live rendered preview on the right. ![Source view — full-width Markdown editing when you want maximum space to write.](/assets/images/source-view-7c281feba2073e03718b61677ed4e76d.png) ### 3. Write your Markdown with diagrams, math, and code[​](#3-write-your-markdown-with-diagrams-math-and-code "Direct link to 3. Write your Markdown with diagrams, math, and code") The editor renders the full Markdown feature set live. Here's what each looks like as you type: #### Code blocks with syntax highlighting[​](#code-blocks-with-syntax-highlighting "Direct link to Code blocks with syntax highlighting") Fenced code blocks highlight automatically across 190+ languages via highlight.js. GitHub light and dark themes match Confluence's color scheme: ```` ```python def fibonacci(n): a, b = 0, 1 for _ in range(n): a, b = b, a + b return a ``` ```` #### Mermaid diagrams[​](#mermaid-diagrams "Direct link to Mermaid diagrams") The full Mermaid v12 install is bundled — all 30 diagram types render inside your Markdown. Write a ` ```mermaid ` fence and the diagram appears in the live preview immediately: ```` ```mermaid flowchart LR A[Write Markdown] --> B{Preview looks right?} B -->|yes| C[Publish] B -->|no| A ``` ```` ZenUML sequence diagrams are also supported via ` ```zenuml ` fences, using the modern `Actor->Message` syntax. #### Math — KaTeX and LaTeX[​](#math--katex-and-latex "Direct link to Math — KaTeX and LaTeX") Three ways to render math, all client-side with no external service: **KaTeX** (fast, CSS-based) — use a ` ```katex ` fence: ```` ```katex \frac{d}{dx}\left(\int_{0}^{x} f(u)\,du\right)=f(x) ``` ```` **Full LaTeX / MathJax** — for heavier notation including `\begin{align}` and AMS packages, use ` ```math `, ` ```tex `, or ` ```latex ` fences: ```` ```math \begin{align} \nabla \times \vec{B} &= \mu_0 \vec{J} \\ \nabla \cdot \vec{E} &= \frac{\rho}{\varepsilon_0} \end{align} ``` ```` **Inline and display math** — `$E = mc^2$` renders inline, and `$$...$$` renders as a centered display equation. Both typeset in the live preview as you type. MathJax is bundled locally, so equations render without any CDN egress — important for security review and offline instances. #### GitHub-flavored tables[​](#github-flavored-tables "Direct link to GitHub-flavored tables") Standard pipe tables with column alignment: ``` | Feature | Status | Notes | | ------------- | :----: | ------------------ | | Split editor | ✅ | Default mode | | Scroll sync | ✅ | Bidirectional | | Mermaid | ✅ | Full v12 + ZenUML | | LaTeX | ✅ | KaTeX + MathJax | ``` ### 4. Switch between Source, Split, and Preview modes[​](#4-switch-between-source-split-and-preview-modes "Direct link to 4. Switch between Source, Split, and Preview modes") The header toggle switches between three modes: * **Source** — full-width Markdown editing (for writing speed) * **Split** — source + live preview with bidirectional scroll sync (for catching rendering issues) * **Preview** — full-width rendered output (for a final read before saving) ![Preview view — full-width rendered output for a final read before saving.](/assets/images/preview-view-9dce16fcdec6a49aec31424803d56ec4.png) Your mode choice is saved per macro — reopen the editor and the same mode comes back. Scroll sync in Split mode is bidirectional: scroll the source and the preview follows proportionally; scroll the preview and the source follows. ### 5. Save and publish[​](#5-save-and-publish "Direct link to 5. Save and publish") Click **Save**. The Markdown renders on the Confluence page. The output follows Confluence's light/dark theme automatically — code highlighting, diagrams, and math all switch palettes with the host page. Your Markdown source is preserved across edits (stored compressed), so reopening the macro brings back the exact source you wrote. ## Upload an existing Markdown file[​](#upload-an-existing-markdown-file "Direct link to Upload an existing Markdown file") If you have Markdown docs living outside Confluence — in a GitHub repo, a notes app, or exported from another system — click **Upload MD** in the header to import a `.md` or `.markdown` file directly into the editor. This is the fastest way to migrate an existing Markdown document into Confluence without losing diagrams or equations. ## Smart links inside the macro[​](#smart-links-inside-the-macro "Direct link to Smart links inside the macro") Links inside the Markdown macro behave the way you'd expect in Confluence: * **In-page anchors** (`#section`) scroll within the macro instead of navigating away * **Path-rooted links** (`/wiki/download/...`) resolve correctly through Confluence * **External links** open in a host-controlled tab Since v1.4.1, every heading in the macro automatically gets an anchor derived from its text, so long documents can carry their own table of contents: ``` ## Contents - [Installing](#installing) - [Configuring](#configuring) - [Troubleshooting](#troubleshooting) ``` Anchors are lowercase, with spaces replaced by hyphens. One wrinkle: punctuation is removed rather than converted, so `## API v2.0 (Beta)` is anchored as `#api-v20-beta`. The [navigation guide](/docs/Enhanced-Markdown-for-Confluence/navigation.md) covers the full rules and troubleshooting. ## When to use Markdown vs. Confluence's WYSIWYG editor[​](#when-to-use-markdown-vs-confluences-wysiwyg-editor "Direct link to When to use Markdown vs. Confluence's WYSIWYG editor") | You want to… | Use | | ---------------------------------------------------------------------- | --------------------------------- | | Write developer docs that live in Markdown anyway | **Enhanced Markdown** | | Render Mermaid diagrams, LaTeX math, and code in one block | **Enhanced Markdown** | | Migrate a Markdown repo (README, docs site) into Confluence | **Enhanced Markdown** (Upload MD) | | Build a page with mixed Confluence macros (Jira, statuses, task lists) | **Native WYSIWYG** | | Drag-and-drop layout with multiple columns | **Native WYSIWYG** | Many teams use both: Enhanced Markdown blocks for the technical-content portions of a page (code, diagrams, equations), and native Confluence macros around them for project management widgets. ## FAQ[​](#faq "Direct link to FAQ") ### Does Confluence support Markdown natively?[​](#does-confluence-support-markdown-natively "Direct link to Does Confluence support Markdown natively?") No. Confluence's native editor is WYSIWYG (rich text), and pages are stored in Confluence's storage format, not Markdown. Confluence has a Markdown import that converts Markdown to storage format once, but you can't edit Markdown live and see it render. To write and edit Markdown with live preview, you need a Marketplace app like Enhanced Markdown for Confluence. ### Can I render Mermaid diagrams inside Markdown in Confluence?[​](#can-i-render-mermaid-diagrams-inside-markdown-in-confluence "Direct link to Can I render Mermaid diagrams inside Markdown in Confluence?") Yes. Enhanced Markdown for Confluence bundles the full Mermaid v12 install (all 30 diagram types) and renders ` ```mermaid ` fences directly inside the Markdown editor with live preview. This is the key gap with Confluence's native Markdown import, which treats Mermaid fences as plain code. ### Does Enhanced Markdown support LaTeX math?[​](#does-enhanced-markdown-support-latex-math "Direct link to Does Enhanced Markdown support LaTeX math?") Yes, two ways. KaTeX provides fast CSS-based rendering for everyday equations (via ` ```katex ` fences or inline `$...$`). Full LaTeX with AMS packages and `\begin{align}` environments goes through a locally bundled MathJax (via ` ```math `, ` ```tex `, or ` ```latex ` fences). Inline `$...$` and display `$$...$$` math both render in the live preview. ### How many code languages does the syntax highlighting support?[​](#how-many-code-languages-does-the-syntax-highlighting-support "Direct link to How many code languages does the syntax highlighting support?") 190+ languages via highlight.js, with GitHub light and dark themes that match Confluence's color scheme. Languages include Python, JavaScript, TypeScript, Go, Rust, Java, SQL, YAML, JSON, Bash, and many more. ### Does the editor work offline / without external CDNs?[​](#does-the-editor-work-offline--without-external-cdns "Direct link to Does the editor work offline / without external CDNs?") Yes. All rendering libraries — Mermaid, KaTeX, MathJax, and highlight.js — are bundled locally with the app. The macro makes no external CDN calls, which is important for security review and for Atlassian's "Runs on Atlassian" compliance. ### Is Enhanced Markdown for Confluence free?[​](#is-enhanced-markdown-for-confluence-free "Direct link to Is Enhanced Markdown for Confluence free?") Enhanced Markdown for Confluence is free for up to 10 users. Beyond 10 users, standard Atlassian Marketplace licensing applies. ## Related guides[​](#related-guides "Direct link to Related guides") * [Paste Mermaid diagrams into Confluence](/blog/paste-mermaid-diagrams-into-confluence.md) — the paste workflow for repo Markdown, now that Mermaid 12 adds UML use case diagrams * [Import Markdown into Confluence](/blog/import-markdown-into-confluence.md) — paste, GitHub and `.md` file routes compared * [Mermaid 12 in Confluence & Jira](/blog/mermaid-12-confluence-jira.md) — what the version upgrade adds, including `usecase-beta` * [Does Confluence support Mermaid?](/blog/does-confluence-support-mermaid.md) — why the native editor cannot render diagrams Try Mermaid Plus Diagrams & AI Agent for Confluence All 30 Mermaid diagram types plus a Rovo AI agent, with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-ai-agent-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [mermaid](/blog/tags/mermaid.md) * [latex](/blog/tags/latex.md) * [katex](/blog/tags/katex.md) * [mathjax](/blog/tags/mathjax.md) * [how-to](/blog/tags/how-to.md) * [developer-tools](/blog/tags/developer-tools.md) --- # ZenUML Sequence Diagrams in Confluence: Copy-Paste Guide September 24, 2026 · 4 min read [NGPilot](https://ngpilot.com) Sequence diagrams die in Confluence in one of two ways: someone draws one in a diagramming tool, exports a PNG, pastes it into a page — and three sprints later the flow has changed but the image has not. Or someone writes the flow as prose ("the client calls the order service, and if payment is approved…"), which is accurate but impossible to read under time pressure. ZenUML splits the difference: the diagram *is* code, so it edits like code and renders like a diagram — branches, error paths, and parallel work included. This guide shows the syntax with copy-paste examples you can drop into Confluence today. **Quick answer:** To create ZenUML sequence diagrams in Confluence, install [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence) and use a ` ```zenuml ` fence in its Markdown macro. ZenUML renders UML sequence diagrams with real control flow — `if/else`, `try/catch`, `par`, `while` — in the browser, fully inside Confluence. Free for up to 10 users. ## The First Diagram — Checkout with a Branch[​](#the-first-diagram--checkout-with-a-branch "Direct link to The First Diagram — Checkout with a Branch") Paste this into a ` ```zenuml ` fence: ```` ```zenuml participant User participant Checkout participant PaymentProvider User->Checkout: submit order Checkout->PaymentProvider: charge card if (payment approved) { Checkout-->User: confirmation page } else { Checkout->PaymentProvider: retry with backoff Checkout-->User: "will confirm by email" } ``` ```` ![ZenUML checkout sequence with if/else branch rendered in Confluence](data:image/svg+xml;base64,PHN2ZyBpZD0iYmxvZy1zdmctYzVpOXZqbzNhbyIgd2lkdGg9IjEwMCUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgc3R5bGU9ImJhY2tncm91bmQtY29sb3I6IHdoaXRlOyBtYXgtd2lkdGg6IDU4OS41cHg7IiB2aWV3Qm94PSIwIDAgNTg5LjUgNDQxIiByb2xlPSJncmFwaGljcy1kb2N1bWVudCBkb2N1bWVudCIgYXJpYS1yb2xlZGVzY3JpcHRpb249InplbnVtbCI+PGRlZnM+CiAgPHN0eWxlPgogIC5mcmFtZS1ib3JkZXItb3V0ZXIgeyBmaWxsOiAjNjY2OyB9CiAgLmZyYW1lLWJvcmRlci1pbm5lciB7IGZpbGw6ICNmZmZmZmY7IH0KICAuZnJhbWUtaGVhZGVyLWJnIHsgZmlsbDogI2ZmZmZmZjsgfQogIC5mcmFtZS1oZWFkZXItbGluZSB7IHN0cm9rZTogIzY2Njsgc3Ryb2tlLXdpZHRoOiAxOyBzaGFwZS1yZW5kZXJpbmc6IGNyaXNwRWRnZXM7IH0KICAuZnJhbWUtdGl0bGUgeyBmb250LWZhbWlseTogSGVsdmV0aWNhLCBWZXJkYW5hLCBzZXJpZjsgZm9udC1zaXplOiAxNnB4OyBmb250LXdlaWdodDogNjAwOyBmaWxsOiAjMjIyOyB9CiAgLnBhcnRpY2lwYW50LWJveCB7IGZpbGw6ICNmZmZmZmY7IHN0cm9rZTogIzY2Njsgc3Ryb2tlLXdpZHRoOiAyOyB9CiAgLnBhcnRpY2lwYW50LWxhYmVsIHsgZm9udC1mYW1pbHk6IEhlbHZldGljYSwgVmVyZGFuYSwgc2VyaWY7IGZvbnQtc2l6ZTogMTZweDsgZmlsbDogIzIyMjsgfQogIC5wYXJ0aWNpcGFudC1pY29uIHsgY29sb3I6ICMyMjI7IH0KICAucGFydGljaXBhbnQtaWNvbiBbZmlsbD0iY3VycmVudENvbG9yIl06bm90KFtzdHJva2VdKSB7IHN0cm9rZTogIzY2Njsgc3Ryb2tlLXdpZHRoOiAxOyB9CiAgLmxpZmVsaW5lIHsgc3Ryb2tlOiAjNjY2OyBzdHJva2Utd2lkdGg6IDE7IH0KICAubWVzc2FnZS1saW5lIHsgc3Ryb2tlOiAjMDAwOyBzdHJva2Utd2lkdGg6IDI7IHNoYXBlLXJlbmRlcmluZzogY3Jpc3BFZGdlczsgfQogIC5tZXNzYWdlLWxhYmVsIHsgZm9udC1mYW1pbHk6IEhlbHZldGljYSwgVmVyZGFuYSwgc2VyaWY7IGZvbnQtc2l6ZTogMTRweDsgZmlsbDogIzIyMjsgfQogIC5hcnJvdy1oZWFkIHsgZmlsbDogIzAwMDsgc3Ryb2tlOiAjMDAwOyBzdHJva2Utd2lkdGg6IDI7IH0KICAuYXJyb3ctb3BlbiB7IGZpbGw6IG5vbmU7IH0KICAub2NjdXJyZW5jZSB7IGZpbGw6ICNkZWRlZGU7IHN0cm9rZTogIzY2Njsgc3Ryb2tlLXdpZHRoOiAyOyBzaGFwZS1yZW5kZXJpbmc6IGNyaXNwRWRnZXM7IH0KICAuZnJhZ21lbnQtYm9yZGVyIHsgZmlsbDogbm9uZTsgc3Ryb2tlOiAjNjY2OyBzdHJva2Utd2lkdGg6IDE7IHNoYXBlLXJlbmRlcmluZzogY3Jpc3BFZGdlczsgfQogIC5mcmFnbWVudC1oZWFkZXIgeyBmaWxsOiAjZGVkZWRlOyBmaWxsLW9wYWNpdHk6IDAuNDk4OyBzdHJva2U6IG5vbmU7IHNoYXBlLXJlbmRlcmluZzogY3Jpc3BFZGdlczsgfQogIC5mcmFnbWVudC1sYWJlbCB7IGZvbnQtZmFtaWx5OiBIZWx2ZXRpY2EsIFZlcmRhbmEsIHNlcmlmOyBmb250LXNpemU6IDE0cHg7IGZvbnQtd2VpZ2h0OiA2MDA7IGZpbGw6ICMwMDA7IH0KICAuZnJhZ21lbnQtY29uZGl0aW9uIHsgZm9udC1mYW1pbHk6IEhlbHZldGljYSwgVmVyZGFuYSwgc2VyaWY7IGZvbnQtc2l6ZTogMTRweDsgZmlsbDogIzAwMDsgfQogIC5mcmFnbWVudC1zZXBhcmF0b3IgeyBzdHJva2U6ICNlNWU3ZWI7IHN0cm9rZS13aWR0aDogMTsgc2hhcGUtcmVuZGVyaW5nOiBjcmlzcEVkZ2VzOyB9CiAgLmZyYWdtZW50LXNlY3Rpb24tbGFiZWwgeyBmb250LWZhbWlseTogSGVsdmV0aWNhLCBWZXJkYW5hLCBzZXJpZjsgZm9udC1zaXplOiAxNHB4OyBmaWxsOiAjMDAwOyB9CiAgLnJldHVybi1saW5lIHsgc3Ryb2tlOiAjMDAwOyBzdHJva2Utd2lkdGg6IDI7IHN0cm9rZS1kYXNoYXJyYXk6IDYsNDsgc2hhcGUtcmVuZGVyaW5nOiBjcmlzcEVkZ2VzOyB9CiAgLnJldHVybi1hcnJvdyB7IHN0cm9rZTogIzAwMDsgc3Ryb2tlLXdpZHRoOiAyOyBmaWxsOiBub25lOyB9CiAgLnJldHVybi1sYWJlbCB7IGZvbnQtZmFtaWx5OiBIZWx2ZXRpY2EsIFZlcmRhbmEsIHNlcmlmOyBmb250LXNpemU6IDE0cHg7IGZpbGw6ICMyMjI7IH0KICAucmV0dXJuLWljb24geyBmaWxsOiAjMjIyOyB9CiAgLmRpdmlkZXItbGluZSB7IHN0cm9rZTogI2FhYWEzMzsgc3Ryb2tlLXdpZHRoOiAxOyB9CiAgLmRpdmlkZXItYmcgeyBmaWxsOiAjZmZmNWFkOyBzdHJva2U6ICNhYWFhMzM7IHN0cm9rZS13aWR0aDogMTsgfQogIC5kaXZpZGVyLWxhYmVsIHsgZm9udC1mYW1pbHk6IEhlbHZldGljYSwgVmVyZGFuYSwgc2VyaWY7IGZvbnQtc2l6ZTogMTRweDsgZmlsbDogIzMzMzsgfQogIC5jb21tZW50LXRleHQgeyBmb250LWZhbWlseTogSGVsdmV0aWNhLCBWZXJkYW5hLCBzZXJpZjsgZm9udC1zaXplOiAxNHB4OyBmaWxsOiAjMzMzOyBvcGFjaXR5OiAwLjU7IH0KICAuc2VxLW51bWJlciB7IGZvbnQtZmFtaWx5OiBIZWx2ZXRpY2EsIFZlcmRhbmEsIHNlcmlmOyBmb250LXNpemU6IDEycHg7IGZvbnQtd2VpZ2h0OiAxMDA7IGZpbGw6ICM2YjcyODA7IH0KICAuZ3JvdXAtb3V0bGluZSB7IGZpbGw6IG5vbmU7IHN0cm9rZTogIzY2NjsgfQogIC5ncm91cC10aXRsZS1iZyB7IGZpbGw6ICNmZmZmZmY7IHN0cm9rZTogbm9uZTsgfQogIC5ncm91cC10aXRsZS10ZXh0IHsgZm9udC1mYW1pbHk6IEhlbHZldGljYSwgVmVyZGFuYSwgc2VyaWY7IGZvbnQtc2l6ZTogMTNweDsgZm9udC13ZWlnaHQ6IDQwMDsgZmlsbDogIzIyMjsgfQo8L3N0eWxlPgo8L2RlZnM+CjxyZWN0IGNsYXNzPSJmcmFtZS1ib3JkZXItb3V0ZXIiIHg9IjAiIHk9IjAiIHdpZHRoPSI1ODkuNSIgaGVpZ2h0PSI0NDEiIHJ4PSI0IiBmaWxsPSIjNjY2Ij48L3JlY3Q+CjxyZWN0IGNsYXNzPSJmcmFtZS1ib3JkZXItaW5uZXIiIHg9IjEiIHk9IjEiIHdpZHRoPSI1ODcuNSIgaGVpZ2h0PSI0MzkiIHJ4PSIzIiBmaWxsPSIjZmZmIj48L3JlY3Q+CjxsaW5lIGNsYXNzPSJmcmFtZS1oZWFkZXItbGluZSIgeDE9IjEiIHkxPSIzMy41IiB4Mj0iNTg4LjUiIHkyPSIzMy41Ij48L2xpbmU+Cgo8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgyMSwgMzQpIj4KPGxpbmUgeDE9IjUwLjUiIHkxPSI2OCIgeDI9IjUwLjUiIHkyPSI0MDYiIGNsYXNzPSJsaWZlbGluZSIgc3Ryb2tlLWRhc2hhcnJheT0iNSw1IiBzdHJva2UtZGFzaG9mZnNldD0iNSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48L2xpbmU+CjxsaW5lIHgxPSIxNTAuNSIgeTE9IjY4IiB4Mj0iMTUwLjUiIHkyPSI0MDYiIGNsYXNzPSJsaWZlbGluZSIgc3Ryb2tlLWRhc2hhcnJheT0iNSw1IiBzdHJva2UtZGFzaG9mZnNldD0iNSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48L2xpbmU+CjxsaW5lIHgxPSIzMzAuNSIgeTE9IjY4IiB4Mj0iMzMwLjUiIHkyPSI0MDYiIGNsYXNzPSJsaWZlbGluZSIgc3Ryb2tlLWRhc2hhcnJheT0iNSw1IiBzdHJva2UtZGFzaG9mZnNldD0iNSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48L2xpbmU+CjxsaW5lIHgxPSI0NzYuNSIgeTE9IjY4IiB4Mj0iNDc2LjUiIHkyPSI0MDYiIGNsYXNzPSJsaWZlbGluZSIgc3Ryb2tlLWRhc2hhcnJheT0iNSw1IiBzdHJva2UtZGFzaG9mZnNldD0iNSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48L2xpbmU+CjxnIGNsYXNzPSJwYXJ0aWNpcGFudCIgZGF0YS1wYXJ0aWNpcGFudD0icGFydGljaXBhbnQiPgogIDxyZWN0IHg9IjYuMDg5ODQzNzUiIHk9IjI5IiB3aWR0aD0iODcuODIwMzEyNSIgaGVpZ2h0PSIzOCIgcng9IjMiIGNsYXNzPSJwYXJ0aWNpcGFudC1ib3giPjwvcmVjdD4KICAKICAKICAKICA8dGV4dCB4PSI1MCIgeT0iNDcuNzUiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGRvbWluYW50LWJhc2VsaW5lPSJjZW50cmFsIiBjbGFzcz0icGFydGljaXBhbnQtbGFiZWwiPnBhcnRpY2lwYW50PC90ZXh0Pgo8L2c+CjxnIGNsYXNzPSJwYXJ0aWNpcGFudCIgZGF0YS1wYXJ0aWNpcGFudD0iVXNlciI+CiAgPHJlY3QgeD0iMTExIiB5PSIyOSIgd2lkdGg9Ijc4IiBoZWlnaHQ9IjM4IiByeD0iMyIgY2xhc3M9InBhcnRpY2lwYW50LWJveCI+PC9yZWN0PgogIAogIAogIAogIDx0ZXh0IHg9IjE1MCIgeT0iNDcuNzUiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGRvbWluYW50LWJhc2VsaW5lPSJjZW50cmFsIiBjbGFzcz0icGFydGljaXBhbnQtbGFiZWwiPlVzZXI8L3RleHQ+CjwvZz4KPGcgY2xhc3M9InBhcnRpY2lwYW50IiBkYXRhLXBhcnRpY2lwYW50PSJDaGVja291dCI+CiAgPHJlY3QgeD0iMjg5LjIwMzEyNSIgeT0iMjkiIHdpZHRoPSI4MS41OTM3NSIgaGVpZ2h0PSIzOCIgcng9IjMiIGNsYXNzPSJwYXJ0aWNpcGFudC1ib3giPjwvcmVjdD4KICAKICAKICAKICA8dGV4dCB4PSIzMzAiIHk9IjQ3Ljc1IiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBkb21pbmFudC1iYXNlbGluZT0iY2VudHJhbCIgY2xhc3M9InBhcnRpY2lwYW50LWxhYmVsIj5DaGVja291dDwvdGV4dD4KPC9nPgo8ZyBjbGFzcz0icGFydGljaXBhbnQiIGRhdGEtcGFydGljaXBhbnQ9IlBheW1lbnRQcm92aWRlciI+CiAgPHJlY3QgeD0iNDA3LjY0MDYyNSIgeT0iMjkiIHdpZHRoPSIxMzYuNzE4NzUiIGhlaWdodD0iMzgiIHJ4PSIzIiBjbGFzcz0icGFydGljaXBhbnQtYm94Ij48L3JlY3Q+CiAgCiAgCiAgCiAgPHRleHQgeD0iNDc2IiB5PSI0Ny43NSIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZG9taW5hbnQtYmFzZWxpbmU9ImNlbnRyYWwiIGNsYXNzPSJwYXJ0aWNpcGFudC1sYWJlbCI+UGF5bWVudFByb3ZpZGVyPC90ZXh0Pgo8L2c+CjxnIGNsYXNzPSJtZXNzYWdlIj4KICA8bGluZSB4MT0iMTUxIiB5MT0iODciIHgyPSIzMzAiIHkyPSI4NyIgY2xhc3M9Im1lc3NhZ2UtbGluZSI+PC9saW5lPgogIDxzdmcgeD0iMzIzIiB5PSI4MiIgd2lkdGg9IjciIGhlaWdodD0iMTAiIHZpZXdCb3g9IjAgMCA3IDkiIG92ZXJmbG93PSJ2aXNpYmxlIiBjbGFzcz0iYXJyb3ctaGVhZCBhcnJvdy1vcGVuIj4KICAgIDxnPgogICAgICA8cGF0aCBkPSJNMSAxLjI1IEw2LjE1IDQuNSBMMSA3Ljc1IiBzdHJva2U9IiMwMDAiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLXdpZHRoPSIyIiBmaWxsPSJub25lIj48L3BhdGg+CiAgICA8L2c+CiAgPC9zdmc+CiAgPHRleHQgeD0iMjM3IiB5PSI4NCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgY2xhc3M9Im1lc3NhZ2UtbGFiZWwiPnN1Ym1pdCBvcmRlcjwvdGV4dD4KICA8dGV4dCB4PSIxNDciIHk9Ijg0IiB0ZXh0LWFuY2hvcj0iZW5kIiBjbGFzcz0ic2VxLW51bWJlciI+MTwvdGV4dD4KPC9nPgo8ZyBjbGFzcz0ibWVzc2FnZSI+CiAgPGxpbmUgeDE9IjMzMSIgeTE9IjExOSIgeDI9IjQ3NiIgeTI9IjExOSIgY2xhc3M9Im1lc3NhZ2UtbGluZSI+PC9saW5lPgogIDxzdmcgeD0iNDY5IiB5PSIxMTQiIHdpZHRoPSI3IiBoZWlnaHQ9IjEwIiB2aWV3Qm94PSIwIDAgNyA5IiBvdmVyZmxvdz0idmlzaWJsZSIgY2xhc3M9ImFycm93LWhlYWQgYXJyb3ctb3BlbiI+CiAgICA8Zz4KICAgICAgPHBhdGggZD0iTTEgMS4yNSBMNi4xNSA0LjUgTDEgNy43NSIgc3Ryb2tlPSIjMDAwIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS13aWR0aD0iMiIgZmlsbD0ibm9uZSI+PC9wYXRoPgogICAgPC9nPgogIDwvc3ZnPgogIDx0ZXh0IHg9IjQwMCIgeT0iMTE2IiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBjbGFzcz0ibWVzc2FnZS1sYWJlbCI+Y2hhcmdlIGNhcmQ8L3RleHQ+CiAgPHRleHQgeD0iMzI3IiB5PSIxMTYiIHRleHQtYW5jaG9yPSJlbmQiIGNsYXNzPSJzZXEtbnVtYmVyIj4yPC90ZXh0Pgo8L2c+CjxnIGNsYXNzPSJtZXNzYWdlIj4KICA8bGluZSB4MT0iMzMxIiB5MT0iMjkwIiB4Mj0iNDc2IiB5Mj0iMjkwIiBjbGFzcz0ibWVzc2FnZS1saW5lIj48L2xpbmU+CiAgPHN2ZyB4PSI0NjkiIHk9IjI4NSIgd2lkdGg9IjciIGhlaWdodD0iMTAiIHZpZXdCb3g9IjAgMCA3IDkiIG92ZXJmbG93PSJ2aXNpYmxlIiBjbGFzcz0iYXJyb3ctaGVhZCBhcnJvdy1vcGVuIj4KICAgIDxnPgogICAgICA8cGF0aCBkPSJNMSAxLjI1IEw2LjE1IDQuNSBMMSA3Ljc1IiBzdHJva2U9IiMwMDAiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLXdpZHRoPSIyIiBmaWxsPSJub25lIj48L3BhdGg+CiAgICA8L2c+CiAgPC9zdmc+CiAgPHRleHQgeD0iNDAwIiB5PSIyODciIHRleHQtYW5jaG9yPSJtaWRkbGUiIGNsYXNzPSJtZXNzYWdlLWxhYmVsIj5yZXRyeSB3aXRoIGJhY2tvZmY8L3RleHQ+CiAgPHRleHQgeD0iMzI3IiB5PSIyODciIHRleHQtYW5jaG9yPSJlbmQiIGNsYXNzPSJzZXEtbnVtYmVyIj4zLjI8L3RleHQ+CjwvZz4KPGcgY2xhc3M9InJldHVybiI+CiAgPGxpbmUgeDE9IjMzMCIgeTE9IjIxMyIgeDI9IjE1MSIgeTI9IjIxMyIgY2xhc3M9InJldHVybi1saW5lIj48L2xpbmU+CiAgPHBvbHlsaW5lIHBvaW50cz0iMTU2LjE1LDIwOS43NSAxNTEsMjEzIDE1Ni4xNSwyMTYuMjUiIGZpbGw9Im5vbmUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgY2xhc3M9InJldHVybi1hcnJvdyI+PC9wb2x5bGluZT4KICA8dGV4dCB4PSIyNDQiIHk9IjIxMCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgY2xhc3M9InJldHVybi1sYWJlbCI+Y29uZmlybWF0aW9uIHBhZ2U8L3RleHQ+CiAgPHRleHQgeD0iMTQ3IiB5PSIyMTAiIHRleHQtYW5jaG9yPSJlbmQiIGNsYXNzPSJzZXEtbnVtYmVyIj4zLjE8L3RleHQ+CjwvZz4KPGcgY2xhc3M9InJldHVybiI+CiAgPGxpbmUgeDE9IjMzMCIgeTE9IjMyMiIgeDI9IjE1MSIgeTI9IjMyMiIgY2xhc3M9InJldHVybi1saW5lIj48L2xpbmU+CiAgPHBvbHlsaW5lIHBvaW50cz0iMTU2LjE1LDMxOC43NSAxNTEsMzIyIDE1Ni4xNSwzMjUuMjUiIGZpbGw9Im5vbmUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgY2xhc3M9InJldHVybi1hcnJvdyI+PC9wb2x5bGluZT4KICA8dGV4dCB4PSIyNDQiIHk9IjMxOSIgdGV4dC1hbmNob3I9Im1pZGRsZSIgY2xhc3M9InJldHVybi1sYWJlbCI+IndpbGwgY29uZmlybSBieSBlbWFpbCI8L3RleHQ+CiAgPHRleHQgeD0iMTQ3IiB5PSIzMTkiIHRleHQtYW5jaG9yPSJlbmQiIGNsYXNzPSJzZXEtbnVtYmVyIj4zLjM8L3RleHQ+CjwvZz4KPGcgY2xhc3M9ImZyYWdtZW50IGZyYWdtZW50LWFsdCI+CiAgPHJlY3QgeD0iOTAuNSIgeT0iMTM2LjUiIHdpZHRoPSI0NjYuNSIgaGVpZ2h0PSIyMTMiIHJ4PSI0IiBjbGFzcz0iZnJhZ21lbnQtYm9yZGVyIj48L3JlY3Q+CiAgPHJlY3QgeD0iOTEiIHk9IjEzNyIgd2lkdGg9IjQ2NS41IiBoZWlnaHQ9IjI1IiBjbGFzcz0iZnJhZ21lbnQtaGVhZGVyIj48L3JlY3Q+CiAgPHN2ZyB4PSI5NSIgeT0iMTM3IiB3aWR0aD0iMjAiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSI+CiAgICAgIDxwYXRoIGQ9Ik0xMiA4TDIwIDEyTDEyIDE2TDQgMTJMMTIgOFoiIHN0cm9rZT0iIzAwMCIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCI+PC9wYXRoPgogICAgPC9zdmc+CiAgPHRleHQgeD0iMTE3IiB5PSIxNDkiIGRvbWluYW50LWJhc2VsaW5lPSJjZW50cmFsIiBjbGFzcz0iZnJhZ21lbnQtbGFiZWwiPkFsdDwvdGV4dD4KICA8dGV4dCB4PSI4NyIgeT0iMTQ1IiB0ZXh0LWFuY2hvcj0iZW5kIiBkb21pbmFudC1iYXNlbGluZT0iY2VudHJhbCIgY2xhc3M9InNlcS1udW1iZXIiPjM8L3RleHQ+CiAgPGc+PHRleHQgeD0iOTEiIHk9IjE3NyIgY2xhc3M9ImZyYWdtZW50LWNvbmRpdGlvbiI+WzwvdGV4dD48dGV4dCB4PSI5OC44OSIgeT0iMTc3IiBjbGFzcz0iZnJhZ21lbnQtY29uZGl0aW9uIiBvcGFjaXR5PSIwLjY1Ij5wYXltZW50IGFwcHJvdmVkPC90ZXh0Pjx0ZXh0IHg9IjIxOC44NTQ4NDM3NSIgeT0iMTc3IiBjbGFzcz0iZnJhZ21lbnQtY29uZGl0aW9uIj5dPC90ZXh0PjwvZz4KICA8bGluZSB4MT0iOTEiIHkxPSIyMzguNSIgeDI9IjU1Ni41IiB5Mj0iMjM4LjUiIGNsYXNzPSJmcmFnbWVudC1zZXBhcmF0b3IiPjwvbGluZT4KICA8dGV4dCB4PSI5NSIgeT0iMjU0IiBjbGFzcz0iZnJhZ21lbnQtc2VjdGlvbi1sYWJlbCI+W2Vsc2VdPC90ZXh0Pgo8L2c+CjwvZz48L3N2Zz4=) What you get for six lines of logic: labeled participants, a synchronous call (`->`), returns (`-->`), and an `if/else` rendered as proper frames — auto-numbered, so a reader can follow the request/response pairing without guessing. ## The Syntax in One Table[​](#the-syntax-in-one-table "Direct link to The Syntax in One Table") | Token | Meaning | Example | | -------------------------- | ------------------------------- | ----------------------------------- | | `participant X` | Declare a participant | `participant Checkout` | | `@Actor X` / `@Database X` | Annotate the participant's role | `@Database PaymentDB` | | `A->B: msg` | Synchronous call | `Checkout->PaymentProvider: charge` | | `A-->B: msg` | Return / reply | `Checkout-->User: 201 Created` | | `if (x) { } else { }` | Branch frames | `if (approved) { ... }` | | `while (x) { }` | Loop frame | `while (retries left) { ... }` | | `par { } and { }` | Parallel blocks | fan-out and join | | `try { } catch (E) { }` | Error path | reservation failure | The annotators are worth adopting on day one: `@Actor Alice` and `@Database OrdersDB` change the participant's icon, so a reader sees who is a human and who is a store before reading a single message. ## Error Paths as First-Class Citizens[​](#error-paths-as-first-class-citizens "Direct link to Error Paths as First-Class Citizens") The example that sells most teams: an order flow where reservation can fail. In a drawing tool this is a second diagram to maintain; in ZenUML it is four lines: ```` ```zenuml participant Client participant OrderService participant InventoryService Client->OrderService: POST /orders OrderService->InventoryService: reserve(SKU-991, qty=2) try { InventoryService-->OrderService: reservation #R-4821 OrderService-->Client: 201 Created, order #A-1088 } catch (OutOfStockError) { OrderService-->Client: 409 Conflict, "insufficient stock" } ``` ```` ![ZenUML try/catch sequence diagram for an inventory reservation](data:image/svg+xml;base64,PHN2ZyBpZD0iYmxvZy1zdmctazdhc2hpbzVwa3AiIHdpZHRoPSIxMDAlIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHN0eWxlPSJiYWNrZ3JvdW5kLWNvbG9yOiB3aGl0ZTsgbWF4LXdpZHRoOiA3MDIuNXB4OyIgdmlld0JveD0iMCAwIDcwMi41IDQyMSIgcm9sZT0iZ3JhcGhpY3MtZG9jdW1lbnQgZG9jdW1lbnQiIGFyaWEtcm9sZWRlc2NyaXB0aW9uPSJ6ZW51bWwiPjxkZWZzPgogIDxzdHlsZT4KICAuZnJhbWUtYm9yZGVyLW91dGVyIHsgZmlsbDogIzY2NjsgfQogIC5mcmFtZS1ib3JkZXItaW5uZXIgeyBmaWxsOiAjZmZmZmZmOyB9CiAgLmZyYW1lLWhlYWRlci1iZyB7IGZpbGw6ICNmZmZmZmY7IH0KICAuZnJhbWUtaGVhZGVyLWxpbmUgeyBzdHJva2U6ICM2NjY7IHN0cm9rZS13aWR0aDogMTsgc2hhcGUtcmVuZGVyaW5nOiBjcmlzcEVkZ2VzOyB9CiAgLmZyYW1lLXRpdGxlIHsgZm9udC1mYW1pbHk6IEhlbHZldGljYSwgVmVyZGFuYSwgc2VyaWY7IGZvbnQtc2l6ZTogMTZweDsgZm9udC13ZWlnaHQ6IDYwMDsgZmlsbDogIzIyMjsgfQogIC5wYXJ0aWNpcGFudC1ib3ggeyBmaWxsOiAjZmZmZmZmOyBzdHJva2U6ICM2NjY7IHN0cm9rZS13aWR0aDogMjsgfQogIC5wYXJ0aWNpcGFudC1sYWJlbCB7IGZvbnQtZmFtaWx5OiBIZWx2ZXRpY2EsIFZlcmRhbmEsIHNlcmlmOyBmb250LXNpemU6IDE2cHg7IGZpbGw6ICMyMjI7IH0KICAucGFydGljaXBhbnQtaWNvbiB7IGNvbG9yOiAjMjIyOyB9CiAgLnBhcnRpY2lwYW50LWljb24gW2ZpbGw9ImN1cnJlbnRDb2xvciJdOm5vdChbc3Ryb2tlXSkgeyBzdHJva2U6ICM2NjY7IHN0cm9rZS13aWR0aDogMTsgfQogIC5saWZlbGluZSB7IHN0cm9rZTogIzY2Njsgc3Ryb2tlLXdpZHRoOiAxOyB9CiAgLm1lc3NhZ2UtbGluZSB7IHN0cm9rZTogIzAwMDsgc3Ryb2tlLXdpZHRoOiAyOyBzaGFwZS1yZW5kZXJpbmc6IGNyaXNwRWRnZXM7IH0KICAubWVzc2FnZS1sYWJlbCB7IGZvbnQtZmFtaWx5OiBIZWx2ZXRpY2EsIFZlcmRhbmEsIHNlcmlmOyBmb250LXNpemU6IDE0cHg7IGZpbGw6ICMyMjI7IH0KICAuYXJyb3ctaGVhZCB7IGZpbGw6ICMwMDA7IHN0cm9rZTogIzAwMDsgc3Ryb2tlLXdpZHRoOiAyOyB9CiAgLmFycm93LW9wZW4geyBmaWxsOiBub25lOyB9CiAgLm9jY3VycmVuY2UgeyBmaWxsOiAjZGVkZWRlOyBzdHJva2U6ICM2NjY7IHN0cm9rZS13aWR0aDogMjsgc2hhcGUtcmVuZGVyaW5nOiBjcmlzcEVkZ2VzOyB9CiAgLmZyYWdtZW50LWJvcmRlciB7IGZpbGw6IG5vbmU7IHN0cm9rZTogIzY2Njsgc3Ryb2tlLXdpZHRoOiAxOyBzaGFwZS1yZW5kZXJpbmc6IGNyaXNwRWRnZXM7IH0KICAuZnJhZ21lbnQtaGVhZGVyIHsgZmlsbDogI2RlZGVkZTsgZmlsbC1vcGFjaXR5OiAwLjQ5ODsgc3Ryb2tlOiBub25lOyBzaGFwZS1yZW5kZXJpbmc6IGNyaXNwRWRnZXM7IH0KICAuZnJhZ21lbnQtbGFiZWwgeyBmb250LWZhbWlseTogSGVsdmV0aWNhLCBWZXJkYW5hLCBzZXJpZjsgZm9udC1zaXplOiAxNHB4OyBmb250LXdlaWdodDogNjAwOyBmaWxsOiAjMDAwOyB9CiAgLmZyYWdtZW50LWNvbmRpdGlvbiB7IGZvbnQtZmFtaWx5OiBIZWx2ZXRpY2EsIFZlcmRhbmEsIHNlcmlmOyBmb250LXNpemU6IDE0cHg7IGZpbGw6ICMwMDA7IH0KICAuZnJhZ21lbnQtc2VwYXJhdG9yIHsgc3Ryb2tlOiAjZTVlN2ViOyBzdHJva2Utd2lkdGg6IDE7IHNoYXBlLXJlbmRlcmluZzogY3Jpc3BFZGdlczsgfQogIC5mcmFnbWVudC1zZWN0aW9uLWxhYmVsIHsgZm9udC1mYW1pbHk6IEhlbHZldGljYSwgVmVyZGFuYSwgc2VyaWY7IGZvbnQtc2l6ZTogMTRweDsgZmlsbDogIzAwMDsgfQogIC5yZXR1cm4tbGluZSB7IHN0cm9rZTogIzAwMDsgc3Ryb2tlLXdpZHRoOiAyOyBzdHJva2UtZGFzaGFycmF5OiA2LDQ7IHNoYXBlLXJlbmRlcmluZzogY3Jpc3BFZGdlczsgfQogIC5yZXR1cm4tYXJyb3cgeyBzdHJva2U6ICMwMDA7IHN0cm9rZS13aWR0aDogMjsgZmlsbDogbm9uZTsgfQogIC5yZXR1cm4tbGFiZWwgeyBmb250LWZhbWlseTogSGVsdmV0aWNhLCBWZXJkYW5hLCBzZXJpZjsgZm9udC1zaXplOiAxNHB4OyBmaWxsOiAjMjIyOyB9CiAgLnJldHVybi1pY29uIHsgZmlsbDogIzIyMjsgfQogIC5kaXZpZGVyLWxpbmUgeyBzdHJva2U6ICNhYWFhMzM7IHN0cm9rZS13aWR0aDogMTsgfQogIC5kaXZpZGVyLWJnIHsgZmlsbDogI2ZmZjVhZDsgc3Ryb2tlOiAjYWFhYTMzOyBzdHJva2Utd2lkdGg6IDE7IH0KICAuZGl2aWRlci1sYWJlbCB7IGZvbnQtZmFtaWx5OiBIZWx2ZXRpY2EsIFZlcmRhbmEsIHNlcmlmOyBmb250LXNpemU6IDE0cHg7IGZpbGw6ICMzMzM7IH0KICAuY29tbWVudC10ZXh0IHsgZm9udC1mYW1pbHk6IEhlbHZldGljYSwgVmVyZGFuYSwgc2VyaWY7IGZvbnQtc2l6ZTogMTRweDsgZmlsbDogIzMzMzsgb3BhY2l0eTogMC41OyB9CiAgLnNlcS1udW1iZXIgeyBmb250LWZhbWlseTogSGVsdmV0aWNhLCBWZXJkYW5hLCBzZXJpZjsgZm9udC1zaXplOiAxMnB4OyBmb250LXdlaWdodDogMTAwOyBmaWxsOiAjNmI3MjgwOyB9CiAgLmdyb3VwLW91dGxpbmUgeyBmaWxsOiBub25lOyBzdHJva2U6ICM2NjY7IH0KICAuZ3JvdXAtdGl0bGUtYmcgeyBmaWxsOiAjZmZmZmZmOyBzdHJva2U6IG5vbmU7IH0KICAuZ3JvdXAtdGl0bGUtdGV4dCB7IGZvbnQtZmFtaWx5OiBIZWx2ZXRpY2EsIFZlcmRhbmEsIHNlcmlmOyBmb250LXNpemU6IDEzcHg7IGZvbnQtd2VpZ2h0OiA0MDA7IGZpbGw6ICMyMjI7IH0KPC9zdHlsZT4KPC9kZWZzPgo8cmVjdCBjbGFzcz0iZnJhbWUtYm9yZGVyLW91dGVyIiB4PSIwIiB5PSIwIiB3aWR0aD0iNzAyLjUiIGhlaWdodD0iNDIxIiByeD0iNCIgZmlsbD0iIzY2NiI+PC9yZWN0Pgo8cmVjdCBjbGFzcz0iZnJhbWUtYm9yZGVyLWlubmVyIiB4PSIxIiB5PSIxIiB3aWR0aD0iNzAwLjUiIGhlaWdodD0iNDE5IiByeD0iMyIgZmlsbD0iI2ZmZiI+PC9yZWN0Pgo8bGluZSBjbGFzcz0iZnJhbWUtaGVhZGVyLWxpbmUiIHgxPSIxIiB5MT0iMzMuNSIgeDI9IjcwMS41IiB5Mj0iMzMuNSI+PC9saW5lPgoKPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMjEsIDM0KSI+CjxsaW5lIHgxPSI1MC41IiB5MT0iNjgiIHgyPSI1MC41IiB5Mj0iMzg2IiBjbGFzcz0ibGlmZWxpbmUiIHN0cm9rZS1kYXNoYXJyYXk9IjUsNSIgc3Ryb2tlLWRhc2hvZmZzZXQ9IjUiIHNoYXBlLXJlbmRlcmluZz0iY3Jpc3BFZGdlcyI+PC9saW5lPgo8bGluZSB4MT0iMTUwLjUiIHkxPSI2OCIgeDI9IjE1MC41IiB5Mj0iMzg2IiBjbGFzcz0ibGlmZWxpbmUiIHN0cm9rZS1kYXNoYXJyYXk9IjUsNSIgc3Ryb2tlLWRhc2hvZmZzZXQ9IjUiIHNoYXBlLXJlbmRlcmluZz0iY3Jpc3BFZGdlcyI+PC9saW5lPgo8bGluZSB4MT0iMzkzLjUiIHkxPSI2OCIgeDI9IjM5My41IiB5Mj0iMzg2IiBjbGFzcz0ibGlmZWxpbmUiIHN0cm9rZS1kYXNoYXJyYXk9IjUsNSIgc3Ryb2tlLWRhc2hvZmZzZXQ9IjUiIHNoYXBlLXJlbmRlcmluZz0iY3Jpc3BFZGdlcyI+PC9saW5lPgo8bGluZSB4MT0iNTkxLjUiIHkxPSI2OCIgeDI9IjU5MS41IiB5Mj0iMzg2IiBjbGFzcz0ibGlmZWxpbmUiIHN0cm9rZS1kYXNoYXJyYXk9IjUsNSIgc3Ryb2tlLWRhc2hvZmZzZXQ9IjUiIHNoYXBlLXJlbmRlcmluZz0iY3Jpc3BFZGdlcyI+PC9saW5lPgo8ZyBjbGFzcz0icGFydGljaXBhbnQiIGRhdGEtcGFydGljaXBhbnQ9InBhcnRpY2lwYW50Ij4KICA8cmVjdCB4PSI2LjA4OTg0Mzc1IiB5PSIyOSIgd2lkdGg9Ijg3LjgyMDMxMjUiIGhlaWdodD0iMzgiIHJ4PSIzIiBjbGFzcz0icGFydGljaXBhbnQtYm94Ij48L3JlY3Q+CiAgCiAgCiAgCiAgPHRleHQgeD0iNTAiIHk9IjQ3Ljc1IiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBkb21pbmFudC1iYXNlbGluZT0iY2VudHJhbCIgY2xhc3M9InBhcnRpY2lwYW50LWxhYmVsIj5wYXJ0aWNpcGFudDwvdGV4dD4KPC9nPgo8ZyBjbGFzcz0icGFydGljaXBhbnQiIGRhdGEtcGFydGljaXBhbnQ9IkNsaWVudCI+CiAgPHJlY3QgeD0iMTExIiB5PSIyOSIgd2lkdGg9Ijc4IiBoZWlnaHQ9IjM4IiByeD0iMyIgY2xhc3M9InBhcnRpY2lwYW50LWJveCI+PC9yZWN0PgogIAogIAogIAogIDx0ZXh0IHg9IjE1MCIgeT0iNDcuNzUiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGRvbWluYW50LWJhc2VsaW5lPSJjZW50cmFsIiBjbGFzcz0icGFydGljaXBhbnQtbGFiZWwiPkNsaWVudDwvdGV4dD4KPC9nPgo8ZyBjbGFzcz0icGFydGljaXBhbnQiIGRhdGEtcGFydGljaXBhbnQ9Ik9yZGVyU2VydmljZSI+CiAgPHJlY3QgeD0iMzM4Ljg3NSIgeT0iMjkiIHdpZHRoPSIxMDguMjUiIGhlaWdodD0iMzgiIHJ4PSIzIiBjbGFzcz0icGFydGljaXBhbnQtYm94Ij48L3JlY3Q+CiAgCiAgCiAgCiAgPHRleHQgeD0iMzkzIiB5PSI0Ny43NSIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZG9taW5hbnQtYmFzZWxpbmU9ImNlbnRyYWwiIGNsYXNzPSJwYXJ0aWNpcGFudC1sYWJlbCI+T3JkZXJTZXJ2aWNlPC90ZXh0Pgo8L2c+CjxnIGNsYXNzPSJwYXJ0aWNpcGFudCIgZGF0YS1wYXJ0aWNpcGFudD0iSW52ZW50b3J5U2VydmljZSI+CiAgPHJlY3QgeD0iNTI0LjQxNzk2ODc1IiB5PSIyOSIgd2lkdGg9IjEzMy4xNjQwNjI1IiBoZWlnaHQ9IjM4IiByeD0iMyIgY2xhc3M9InBhcnRpY2lwYW50LWJveCI+PC9yZWN0PgogIAogIAogIAogIDx0ZXh0IHg9IjU5MSIgeT0iNDcuNzUiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGRvbWluYW50LWJhc2VsaW5lPSJjZW50cmFsIiBjbGFzcz0icGFydGljaXBhbnQtbGFiZWwiPkludmVudG9yeVNlcnZpY2U8L3RleHQ+CjwvZz4KPGcgY2xhc3M9Im1lc3NhZ2UiPgogIDxsaW5lIHgxPSIxNTEiIHkxPSI4NyIgeDI9IjM5MyIgeTI9Ijg3IiBjbGFzcz0ibWVzc2FnZS1saW5lIj48L2xpbmU+CiAgPHN2ZyB4PSIzODYiIHk9IjgyIiB3aWR0aD0iNyIgaGVpZ2h0PSIxMCIgdmlld0JveD0iMCAwIDcgOSIgb3ZlcmZsb3c9InZpc2libGUiIGNsYXNzPSJhcnJvdy1oZWFkIGFycm93LW9wZW4iPgogICAgPGc+CiAgICAgIDxwYXRoIGQ9Ik0xIDEuMjUgTDYuMTUgNC41IEwxIDcuNzUiIHN0cm9rZT0iIzAwMCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2Utd2lkdGg9IjIiIGZpbGw9Im5vbmUiPjwvcGF0aD4KICAgIDwvZz4KICA8L3N2Zz4KICA8dGV4dCB4PSIyNjguNSIgeT0iODQiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGNsYXNzPSJtZXNzYWdlLWxhYmVsIj5QT1NUIC9vcmRlcnM8L3RleHQ+CiAgPHRleHQgeD0iMTQ3IiB5PSI4NCIgdGV4dC1hbmNob3I9ImVuZCIgY2xhc3M9InNlcS1udW1iZXIiPjE8L3RleHQ+CjwvZz4KPGcgY2xhc3M9Im1lc3NhZ2UiPgogIDxsaW5lIHgxPSIzOTQiIHkxPSIxMTkiIHgyPSI1OTEiIHkyPSIxMTkiIGNsYXNzPSJtZXNzYWdlLWxpbmUiPjwvbGluZT4KICA8c3ZnIHg9IjU4NCIgeT0iMTE0IiB3aWR0aD0iNyIgaGVpZ2h0PSIxMCIgdmlld0JveD0iMCAwIDcgOSIgb3ZlcmZsb3c9InZpc2libGUiIGNsYXNzPSJhcnJvdy1oZWFkIGFycm93LW9wZW4iPgogICAgPGc+CiAgICAgIDxwYXRoIGQ9Ik0xIDEuMjUgTDYuMTUgNC41IEwxIDcuNzUiIHN0cm9rZT0iIzAwMCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2Utd2lkdGg9IjIiIGZpbGw9Im5vbmUiPjwvcGF0aD4KICAgIDwvZz4KICA8L3N2Zz4KICA8dGV4dCB4PSI0ODkiIHk9IjExNiIgdGV4dC1hbmNob3I9Im1pZGRsZSIgY2xhc3M9Im1lc3NhZ2UtbGFiZWwiPnJlc2VydmUoU0tVLTk5MSwgcXR5PTIpPC90ZXh0PgogIDx0ZXh0IHg9IjM5MCIgeT0iMTE2IiB0ZXh0LWFuY2hvcj0iZW5kIiBjbGFzcz0ic2VxLW51bWJlciI+MjwvdGV4dD4KPC9nPgo8ZyBjbGFzcz0icmV0dXJuIj4KICA8bGluZSB4MT0iNTkxIiB5MT0iMTkzIiB4Mj0iMzk0IiB5Mj0iMTkzIiBjbGFzcz0icmV0dXJuLWxpbmUiPjwvbGluZT4KICA8cG9seWxpbmUgcG9pbnRzPSIzOTkuMTUsMTg5Ljc1IDM5NCwxOTMgMzk5LjE1LDE5Ni4yNSIgZmlsbD0ibm9uZSIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBjbGFzcz0icmV0dXJuLWFycm93Ij48L3BvbHlsaW5lPgogIDx0ZXh0IHg9IjQ5NiIgeT0iMTkwIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBjbGFzcz0icmV0dXJuLWxhYmVsIj5yZXNlcnZhdGlvbiAjUi00ODIxPC90ZXh0PgogIDx0ZXh0IHg9IjM5MCIgeT0iMTkwIiB0ZXh0LWFuY2hvcj0iZW5kIiBjbGFzcz0ic2VxLW51bWJlciI+My4xPC90ZXh0Pgo8L2c+CjxnIGNsYXNzPSJyZXR1cm4iPgogIDxsaW5lIHgxPSIzOTMiIHkxPSIyMjUiIHgyPSIxNTEiIHkyPSIyMjUiIGNsYXNzPSJyZXR1cm4tbGluZSI+PC9saW5lPgogIDxwb2x5bGluZSBwb2ludHM9IjE1Ni4xNSwyMjEuNzUgMTUxLDIyNSAxNTYuMTUsMjI4LjI1IiBmaWxsPSJub25lIiBzdHJva2UtbGluZWNhcD0icm91bmQiIGNsYXNzPSJyZXR1cm4tYXJyb3ciPjwvcG9seWxpbmU+CiAgPHRleHQgeD0iMjc1LjUiIHk9IjIyMiIgdGV4dC1hbmNob3I9Im1pZGRsZSIgY2xhc3M9InJldHVybi1sYWJlbCI+MjAxIENyZWF0ZWQsb3JkZXIgI0EtMTA4ODwvdGV4dD4KICA8dGV4dCB4PSIxNDciIHk9IjIyMiIgdGV4dC1hbmNob3I9ImVuZCIgY2xhc3M9InNlcS1udW1iZXIiPjMuMjwvdGV4dD4KPC9nPgo8ZyBjbGFzcz0icmV0dXJuIj4KICA8bGluZSB4MT0iMzkzIiB5MT0iMzAyIiB4Mj0iMTUxIiB5Mj0iMzAyIiBjbGFzcz0icmV0dXJuLWxpbmUiPjwvbGluZT4KICA8cG9seWxpbmUgcG9pbnRzPSIxNTYuMTUsMjk4Ljc1IDE1MSwzMDIgMTU2LjE1LDMwNS4yNSIgZmlsbD0ibm9uZSIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBjbGFzcz0icmV0dXJuLWFycm93Ij48L3BvbHlsaW5lPgogIDx0ZXh0IHg9IjI3NS41IiB5PSIyOTkiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGNsYXNzPSJyZXR1cm4tbGFiZWwiPjQwOSBDb25mbGljdCwiaW5zdWZmaWNpZW50IHN0b2NrIjwvdGV4dD4KICA8dGV4dCB4PSIxNDciIHk9IjI5OSIgdGV4dC1hbmNob3I9ImVuZCIgY2xhc3M9InNlcS1udW1iZXIiPjMuMzwvdGV4dD4KPC9nPgo8ZyBjbGFzcz0iZnJhZ21lbnQgZnJhZ21lbnQtdGNmIj4KICA8cmVjdCB4PSI5MC41IiB5PSIxMzYuNSIgd2lkdGg9IjU3OS41IiBoZWlnaHQ9IjE5MyIgcng9IjQiIGNsYXNzPSJmcmFnbWVudC1ib3JkZXIiPjwvcmVjdD4KICA8cmVjdCB4PSI5MSIgeT0iMTM3IiB3aWR0aD0iNTc4LjUiIGhlaWdodD0iMjUiIGNsYXNzPSJmcmFnbWVudC1oZWFkZXIiPjwvcmVjdD4KICA8c3ZnIHg9Ijk1IiB5PSIxMzciIHdpZHRoPSIyMCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDc2IDc2IiBmaWxsPSIjMDAwIiBzdHJva2U9Im5vbmUiPgogICAgICA8cGF0aCBkPSJNIDI2LDIyLjAwMDFMIDI3LDIxLjk5OThMIDI3LDI3TCAyNi4wMDAxLDI3LjAwMDNDIDIzLjIzODYsMjcuMDAwMyAyMS4wMDAxLDI5LjIzODkgMjEuMDAwMSwzMi4wMDAzTCAyMSw0Ni4wMDAyQyAyMSw0OC43NjE2IDIzLjIzODYsNTEuMDAwMiAyNS45OTk5LDUxLjAwMDJMIDI3LDUxLjAwMDJMIDI3LDQ3TCAzMy43NSw1My41TCAyNyw2MEwgMjcsNTZMIDI2LDU2QyAyMC40NzcxLDU2IDE2LDUxLjUyMjkgMTYsNDZMIDE2LDMyLjAwMDFDIDE2LDI2LjQ3NzMgMjAuNDc3MSwyMi4wMDAxIDI2LDIyLjAwMDEgWiBNIDMzLDI3TCA1OSwyN0wgNTksMzJMIDMzLDMyTCAzMywyNyBaIE0gMzYsMzVMIDU5LDM1TCA1OSw0MEwgMzYsNDBMIDM2LDM1IFogTSAzMyw0M0wgNTksNDNMIDU5LDQ4TCAzMyw0OEwgMzMsNDMgWiI+PC9wYXRoPgogICAgPC9zdmc+CiAgPHRleHQgeD0iMTE3IiB5PSIxNDkiIGRvbWluYW50LWJhc2VsaW5lPSJjZW50cmFsIiBjbGFzcz0iZnJhZ21lbnQtbGFiZWwiPlRyeTwvdGV4dD4KICA8dGV4dCB4PSI4NyIgeT0iMTQ1IiB0ZXh0LWFuY2hvcj0iZW5kIiBkb21pbmFudC1iYXNlbGluZT0iY2VudHJhbCIgY2xhc3M9InNlcS1udW1iZXIiPjM8L3RleHQ+CiAgPGxpbmUgeDE9IjkxIiB5MT0iMjUwLjUiIHgyPSI2NjkuNSIgeTI9IjI1MC41IiBjbGFzcz0iZnJhZ21lbnQtc2VwYXJhdG9yIj48L2xpbmU+CiAgPGcgb3BhY2l0eT0iMC42NSI+PHJlY3QgeD0iOTEiIHk9IjI1MSIgd2lkdGg9IjE1Mi45MzA2NjQwNjI1IiBoZWlnaHQ9IjIwIiBmaWxsPSIjZmZmIj48L3JlY3Q+PHRleHQgeD0iOTUiIHk9IjI2NiIgY2xhc3M9ImZyYWdtZW50LXNlY3Rpb24tbGFiZWwiIGZpbGw9IiMyMjIiPmNhdGNoPC90ZXh0Pjx0ZXh0IHg9IjEzNi40NjE5MTQwNjI1IiB5PSIyNjYiIGNsYXNzPSJmcmFnbWVudC1zZWN0aW9uLWxhYmVsIiBmaWxsPSIjMjIyIj5PdXRPZlN0b2NrRXJyb3I8L3RleHQ+PC9nPgo8L2c+CjwvZz48L3N2Zz4=) The happy path and the failure path live in the same block of text, review together in a PR, and — the actual point — get updated in the same commit when the API contract changes. ## Parallel Work with par/and[​](#parallel-work-with-parand "Direct link to Parallel Work with par/and") Batch jobs and fan-outs read cleanly with `par`: ```` ```zenuml participant Scheduler participant BillingService participant EmailService Scheduler->BillingService: run monthly invoices par { BillingService->BillingService: render PDF statements } and { BillingService->EmailService: queue invoice emails } BillingService-->Scheduler: 1,204 invoices, 3 failures ``` ```` ![ZenUML par block for parallel billing work](data:image/svg+xml;base64,PHN2ZyBpZD0iYmxvZy1zdmctb2pnODJycDZmMTkiIHdpZHRoPSIxMDAlIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHN0eWxlPSJiYWNrZ3JvdW5kLWNvbG9yOiB3aGl0ZTsgbWF4LXdpZHRoOiA3MzAuNXB4OyIgdmlld0JveD0iMCAwIDczMC41IDQzNiIgcm9sZT0iZ3JhcGhpY3MtZG9jdW1lbnQgZG9jdW1lbnQiIGFyaWEtcm9sZWRlc2NyaXB0aW9uPSJ6ZW51bWwiPjxkZWZzPgogIDxzdHlsZT4KICAuZnJhbWUtYm9yZGVyLW91dGVyIHsgZmlsbDogIzY2NjsgfQogIC5mcmFtZS1ib3JkZXItaW5uZXIgeyBmaWxsOiAjZmZmZmZmOyB9CiAgLmZyYW1lLWhlYWRlci1iZyB7IGZpbGw6ICNmZmZmZmY7IH0KICAuZnJhbWUtaGVhZGVyLWxpbmUgeyBzdHJva2U6ICM2NjY7IHN0cm9rZS13aWR0aDogMTsgc2hhcGUtcmVuZGVyaW5nOiBjcmlzcEVkZ2VzOyB9CiAgLmZyYW1lLXRpdGxlIHsgZm9udC1mYW1pbHk6IEhlbHZldGljYSwgVmVyZGFuYSwgc2VyaWY7IGZvbnQtc2l6ZTogMTZweDsgZm9udC13ZWlnaHQ6IDYwMDsgZmlsbDogIzIyMjsgfQogIC5wYXJ0aWNpcGFudC1ib3ggeyBmaWxsOiAjZmZmZmZmOyBzdHJva2U6ICM2NjY7IHN0cm9rZS13aWR0aDogMjsgfQogIC5wYXJ0aWNpcGFudC1sYWJlbCB7IGZvbnQtZmFtaWx5OiBIZWx2ZXRpY2EsIFZlcmRhbmEsIHNlcmlmOyBmb250LXNpemU6IDE2cHg7IGZpbGw6ICMyMjI7IH0KICAucGFydGljaXBhbnQtaWNvbiB7IGNvbG9yOiAjMjIyOyB9CiAgLnBhcnRpY2lwYW50LWljb24gW2ZpbGw9ImN1cnJlbnRDb2xvciJdOm5vdChbc3Ryb2tlXSkgeyBzdHJva2U6ICM2NjY7IHN0cm9rZS13aWR0aDogMTsgfQogIC5saWZlbGluZSB7IHN0cm9rZTogIzY2Njsgc3Ryb2tlLXdpZHRoOiAxOyB9CiAgLm1lc3NhZ2UtbGluZSB7IHN0cm9rZTogIzAwMDsgc3Ryb2tlLXdpZHRoOiAyOyBzaGFwZS1yZW5kZXJpbmc6IGNyaXNwRWRnZXM7IH0KICAubWVzc2FnZS1sYWJlbCB7IGZvbnQtZmFtaWx5OiBIZWx2ZXRpY2EsIFZlcmRhbmEsIHNlcmlmOyBmb250LXNpemU6IDE0cHg7IGZpbGw6ICMyMjI7IH0KICAuYXJyb3ctaGVhZCB7IGZpbGw6ICMwMDA7IHN0cm9rZTogIzAwMDsgc3Ryb2tlLXdpZHRoOiAyOyB9CiAgLmFycm93LW9wZW4geyBmaWxsOiBub25lOyB9CiAgLm9jY3VycmVuY2UgeyBmaWxsOiAjZGVkZWRlOyBzdHJva2U6ICM2NjY7IHN0cm9rZS13aWR0aDogMjsgc2hhcGUtcmVuZGVyaW5nOiBjcmlzcEVkZ2VzOyB9CiAgLmZyYWdtZW50LWJvcmRlciB7IGZpbGw6IG5vbmU7IHN0cm9rZTogIzY2Njsgc3Ryb2tlLXdpZHRoOiAxOyBzaGFwZS1yZW5kZXJpbmc6IGNyaXNwRWRnZXM7IH0KICAuZnJhZ21lbnQtaGVhZGVyIHsgZmlsbDogI2RlZGVkZTsgZmlsbC1vcGFjaXR5OiAwLjQ5ODsgc3Ryb2tlOiBub25lOyBzaGFwZS1yZW5kZXJpbmc6IGNyaXNwRWRnZXM7IH0KICAuZnJhZ21lbnQtbGFiZWwgeyBmb250LWZhbWlseTogSGVsdmV0aWNhLCBWZXJkYW5hLCBzZXJpZjsgZm9udC1zaXplOiAxNHB4OyBmb250LXdlaWdodDogNjAwOyBmaWxsOiAjMDAwOyB9CiAgLmZyYWdtZW50LWNvbmRpdGlvbiB7IGZvbnQtZmFtaWx5OiBIZWx2ZXRpY2EsIFZlcmRhbmEsIHNlcmlmOyBmb250LXNpemU6IDE0cHg7IGZpbGw6ICMwMDA7IH0KICAuZnJhZ21lbnQtc2VwYXJhdG9yIHsgc3Ryb2tlOiAjZTVlN2ViOyBzdHJva2Utd2lkdGg6IDE7IHNoYXBlLXJlbmRlcmluZzogY3Jpc3BFZGdlczsgfQogIC5mcmFnbWVudC1zZWN0aW9uLWxhYmVsIHsgZm9udC1mYW1pbHk6IEhlbHZldGljYSwgVmVyZGFuYSwgc2VyaWY7IGZvbnQtc2l6ZTogMTRweDsgZmlsbDogIzAwMDsgfQogIC5yZXR1cm4tbGluZSB7IHN0cm9rZTogIzAwMDsgc3Ryb2tlLXdpZHRoOiAyOyBzdHJva2UtZGFzaGFycmF5OiA2LDQ7IHNoYXBlLXJlbmRlcmluZzogY3Jpc3BFZGdlczsgfQogIC5yZXR1cm4tYXJyb3cgeyBzdHJva2U6ICMwMDA7IHN0cm9rZS13aWR0aDogMjsgZmlsbDogbm9uZTsgfQogIC5yZXR1cm4tbGFiZWwgeyBmb250LWZhbWlseTogSGVsdmV0aWNhLCBWZXJkYW5hLCBzZXJpZjsgZm9udC1zaXplOiAxNHB4OyBmaWxsOiAjMjIyOyB9CiAgLnJldHVybi1pY29uIHsgZmlsbDogIzIyMjsgfQogIC5kaXZpZGVyLWxpbmUgeyBzdHJva2U6ICNhYWFhMzM7IHN0cm9rZS13aWR0aDogMTsgfQogIC5kaXZpZGVyLWJnIHsgZmlsbDogI2ZmZjVhZDsgc3Ryb2tlOiAjYWFhYTMzOyBzdHJva2Utd2lkdGg6IDE7IH0KICAuZGl2aWRlci1sYWJlbCB7IGZvbnQtZmFtaWx5OiBIZWx2ZXRpY2EsIFZlcmRhbmEsIHNlcmlmOyBmb250LXNpemU6IDE0cHg7IGZpbGw6ICMzMzM7IH0KICAuY29tbWVudC10ZXh0IHsgZm9udC1mYW1pbHk6IEhlbHZldGljYSwgVmVyZGFuYSwgc2VyaWY7IGZvbnQtc2l6ZTogMTRweDsgZmlsbDogIzMzMzsgb3BhY2l0eTogMC41OyB9CiAgLnNlcS1udW1iZXIgeyBmb250LWZhbWlseTogSGVsdmV0aWNhLCBWZXJkYW5hLCBzZXJpZjsgZm9udC1zaXplOiAxMnB4OyBmb250LXdlaWdodDogMTAwOyBmaWxsOiAjNmI3MjgwOyB9CiAgLmdyb3VwLW91dGxpbmUgeyBmaWxsOiBub25lOyBzdHJva2U6ICM2NjY7IH0KICAuZ3JvdXAtdGl0bGUtYmcgeyBmaWxsOiAjZmZmZmZmOyBzdHJva2U6IG5vbmU7IH0KICAuZ3JvdXAtdGl0bGUtdGV4dCB7IGZvbnQtZmFtaWx5OiBIZWx2ZXRpY2EsIFZlcmRhbmEsIHNlcmlmOyBmb250LXNpemU6IDEzcHg7IGZvbnQtd2VpZ2h0OiA0MDA7IGZpbGw6ICMyMjI7IH0KPC9zdHlsZT4KPC9kZWZzPgo8cmVjdCBjbGFzcz0iZnJhbWUtYm9yZGVyLW91dGVyIiB4PSIwIiB5PSIwIiB3aWR0aD0iNzMwLjUiIGhlaWdodD0iNDM2IiByeD0iNCIgZmlsbD0iIzY2NiI+PC9yZWN0Pgo8cmVjdCBjbGFzcz0iZnJhbWUtYm9yZGVyLWlubmVyIiB4PSIxIiB5PSIxIiB3aWR0aD0iNzI4LjUiIGhlaWdodD0iNDM0IiByeD0iMyIgZmlsbD0iI2ZmZiI+PC9yZWN0Pgo8bGluZSBjbGFzcz0iZnJhbWUtaGVhZGVyLWxpbmUiIHgxPSIxIiB5MT0iMzMuNSIgeDI9IjcyOS41IiB5Mj0iMzMuNSI+PC9saW5lPgoKPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMjEsIDM0KSI+CjxsaW5lIHgxPSI1NiIgeTE9IjY4IiB4Mj0iNTYiIHkyPSI0MDEiIGNsYXNzPSJsaWZlbGluZSIgc3Ryb2tlLWRhc2hhcnJheT0iNSw1IiBzdHJva2UtZGFzaG9mZnNldD0iNSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48L2xpbmU+CjxsaW5lIHgxPSIxNjEuNSIgeTE9IjY4IiB4Mj0iMTYxLjUiIHkyPSI0MDEiIGNsYXNzPSJsaWZlbGluZSIgc3Ryb2tlLWRhc2hhcnJheT0iNSw1IiBzdHJva2UtZGFzaG9mZnNldD0iNSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48L2xpbmU+CjxsaW5lIHgxPSIyNjEuNSIgeTE9IjY4IiB4Mj0iMjYxLjUiIHkyPSI0MDEiIGNsYXNzPSJsaWZlbGluZSIgc3Ryb2tlLWRhc2hhcnJheT0iNSw1IiBzdHJva2UtZGFzaG9mZnNldD0iNSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48L2xpbmU+CjxsaW5lIHgxPSI0NTguNSIgeTE9IjY4IiB4Mj0iNDU4LjUiIHkyPSI0MDEiIGNsYXNzPSJsaWZlbGluZSIgc3Ryb2tlLWRhc2hhcnJheT0iNSw1IiBzdHJva2UtZGFzaG9mZnNldD0iNSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48L2xpbmU+CjxsaW5lIHgxPSI2MzIuNSIgeTE9IjY4IiB4Mj0iNjMyLjUiIHkyPSI0MDEiIGNsYXNzPSJsaWZlbGluZSIgc3Ryb2tlLWRhc2hhcnJheT0iNSw1IiBzdHJva2UtZGFzaG9mZnNldD0iNSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48L2xpbmU+CjxnIGNsYXNzPSJwYXJ0aWNpcGFudCBwYXJ0aWNpcGFudC1zdGFydGVyIiBkYXRhLXBhcnRpY2lwYW50PSJfU1RBUlRFUl8iPgogIDxyZWN0IHg9IjE2LjUiIHk9IjI5IiB3aWR0aD0iNzgiIGhlaWdodD0iMzgiIHJ4PSIzIiBjbGFzcz0icGFydGljaXBhbnQtYm94Ij48L3JlY3Q+CiAgPGcgY2xhc3M9InBhcnRpY2lwYW50LWljb24iIHRyYW5zZm9ybT0idHJhbnNsYXRlKDQxLjUsIDM2KSBzY2FsZSgxKSIgZmlsbD0ibm9uZSI+CiAgICA8Zz4KICAgIDxwYXRoIGQ9Ik0xNS41NDg5IDQuMTk3NzFDMTUuNTQ4OSA1LjE4NzczIDE1LjE0ODUgNi4xMzcyMSAxNC40MzU4IDYuODM3MjZDMTMuNzIzMSA3LjUzNzMxIDEyLjc1NjUgNy45MzA1OCAxMS43NDg2IDcuOTMwNThDMTAuNzQwNyA3LjkzMDU4IDkuNzc0MDMgNy41MzczMSA5LjA2MTMzIDYuODM3MjZDOC4zNDg2MyA2LjEzNzIxIDcuOTQ4MjQgNS4xODc3MyA3Ljk0ODI0IDQuMTk3NzFDNy45NDgyNCAzLjIwNzY4IDguMzQ4NjMgMi4yNTgyMiA5LjA2MTMzIDEuNTU4MThDOS43NzQwMyAwLjg1ODEyNiAxMC43NDA3IDAuNDY0ODQ0IDExLjc0ODYgMC40NjQ4NDRDMTIuNzU2NSAwLjQ2NDg0NCAxMy43MjMxIDAuODU4MTI2IDE0LjQzNTggMS41NTgxOEMxNS4xNDg1IDIuMjU4MjIgMTUuNTQ4OSAzLjIwNzY4IDE1LjU0ODkgNC4xOTc3MVoiIHN0cm9rZT0iY3VycmVudENvbG9yIj48L3BhdGg+CiAgICA8cGF0aCBkPSJNNi41NDg4MyAxMS4yMTUyTDE3LjIwMjUgMTEuMjA3M00xMS43NDcxIDguMDY2NDFWMTkuNTgwNlY4LjA2NjQxWk0xMS43NDcxIDE5LjQzODVMNi43OTc4OSAyMy41NzM4TDExLjc0NzEgMTkuNDM4NVpNMTEuNzU1MSAxOS40Mzg1TDE3LjE4NjQgMjMuMzA1NUwxMS43NTUxIDE5LjQzODVaIiBzdHJva2U9ImN1cnJlbnRDb2xvciI+PC9wYXRoPgogIDwvZz4KICA8L2c+CjwvZz4KPGcgY2xhc3M9InBhcnRpY2lwYW50IiBkYXRhLXBhcnRpY2lwYW50PSJwYXJ0aWNpcGFudCI+CiAgPHJlY3QgeD0iMTE3LjA4OTg0Mzc1IiB5PSIyOSIgd2lkdGg9Ijg3LjgyMDMxMjUiIGhlaWdodD0iMzgiIHJ4PSIzIiBjbGFzcz0icGFydGljaXBhbnQtYm94Ij48L3JlY3Q+CiAgCiAgCiAgCiAgPHRleHQgeD0iMTYxIiB5PSI0Ny43NSIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZG9taW5hbnQtYmFzZWxpbmU9ImNlbnRyYWwiIGNsYXNzPSJwYXJ0aWNpcGFudC1sYWJlbCI+cGFydGljaXBhbnQ8L3RleHQ+CjwvZz4KPGcgY2xhc3M9InBhcnRpY2lwYW50IiBkYXRhLXBhcnRpY2lwYW50PSJTY2hlZHVsZXIiPgogIDxyZWN0IHg9IjIxNy45NzY1NjI1IiB5PSIyOSIgd2lkdGg9Ijg2LjA0Njg3NSIgaGVpZ2h0PSIzOCIgcng9IjMiIGNsYXNzPSJwYXJ0aWNpcGFudC1ib3giPjwvcmVjdD4KICAKICAKICAKICA8dGV4dCB4PSIyNjEiIHk9IjQ3Ljc1IiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBkb21pbmFudC1iYXNlbGluZT0iY2VudHJhbCIgY2xhc3M9InBhcnRpY2lwYW50LWxhYmVsIj5TY2hlZHVsZXI8L3RleHQ+CjwvZz4KPGcgY2xhc3M9InBhcnRpY2lwYW50IiBkYXRhLXBhcnRpY2lwYW50PSJCaWxsaW5nU2VydmljZSI+CiAgPHJlY3QgeD0iNDAyLjk4MDQ2ODc1IiB5PSIyOSIgd2lkdGg9IjExMC4wMzkwNjI1IiBoZWlnaHQ9IjM4IiByeD0iMyIgY2xhc3M9InBhcnRpY2lwYW50LWJveCI+PC9yZWN0PgogIAogIAogIAogIDx0ZXh0IHg9IjQ1OCIgeT0iNDcuNzUiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGRvbWluYW50LWJhc2VsaW5lPSJjZW50cmFsIiBjbGFzcz0icGFydGljaXBhbnQtbGFiZWwiPkJpbGxpbmdTZXJ2aWNlPC90ZXh0Pgo8L2c+CjxnIGNsYXNzPSJwYXJ0aWNpcGFudCIgZGF0YS1wYXJ0aWNpcGFudD0iRW1haWxTZXJ2aWNlIj4KICA8cmVjdCB4PSI1NzguMzIwMzEyNSIgeT0iMjkiIHdpZHRoPSIxMDcuMzU5Mzc1IiBoZWlnaHQ9IjM4IiByeD0iMyIgY2xhc3M9InBhcnRpY2lwYW50LWJveCI+PC9yZWN0PgogIAogIAogIAogIDx0ZXh0IHg9IjYzMiIgeT0iNDcuNzUiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGRvbWluYW50LWJhc2VsaW5lPSJjZW50cmFsIiBjbGFzcz0icGFydGljaXBhbnQtbGFiZWwiPkVtYWlsU2VydmljZTwvdGV4dD4KPC9nPgo8cmVjdCB4PSI0OS41IiB5PSIyNjIiIHdpZHRoPSIxMyIgaGVpZ2h0PSI1MCIgcng9IjEiIGNsYXNzPSJvY2N1cnJlbmNlIiBkYXRhLXBhcnRpY2lwYW50PSJfU1RBUlRFUl8iPjwvcmVjdD4KPGcgY2xhc3M9Im1lc3NhZ2UiPgogIDxsaW5lIHgxPSIyNjIiIHkxPSI4NyIgeDI9IjQ1OCIgeTI9Ijg3IiBjbGFzcz0ibWVzc2FnZS1saW5lIj48L2xpbmU+CiAgPHN2ZyB4PSI0NTEiIHk9IjgyIiB3aWR0aD0iNyIgaGVpZ2h0PSIxMCIgdmlld0JveD0iMCAwIDcgOSIgb3ZlcmZsb3c9InZpc2libGUiIGNsYXNzPSJhcnJvdy1oZWFkIGFycm93LW9wZW4iPgogICAgPGc+CiAgICAgIDxwYXRoIGQ9Ik0xIDEuMjUgTDYuMTUgNC41IEwxIDcuNzUiIHN0cm9rZT0iIzAwMCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2Utd2lkdGg9IjIiIGZpbGw9Im5vbmUiPjwvcGF0aD4KICAgIDwvZz4KICA8L3N2Zz4KICA8dGV4dCB4PSIzNTYuNSIgeT0iODQiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGNsYXNzPSJtZXNzYWdlLWxhYmVsIj5ydW4gbW9udGhseSBpbnZvaWNlczwvdGV4dD4KICA8dGV4dCB4PSIyNTgiIHk9Ijg0IiB0ZXh0LWFuY2hvcj0iZW5kIiBjbGFzcz0ic2VxLW51bWJlciI+MTwvdGV4dD4KPC9nPgo8ZyBjbGFzcz0ibWVzc2FnZSI+CiAgPGxpbmUgeDE9IjQ1OSIgeTE9IjI5NCIgeDI9IjYzMiIgeTI9IjI5NCIgY2xhc3M9Im1lc3NhZ2UtbGluZSI+PC9saW5lPgogIDxzdmcgeD0iNjI1IiB5PSIyODkiIHdpZHRoPSI3IiBoZWlnaHQ9IjEwIiB2aWV3Qm94PSIwIDAgNyA5IiBvdmVyZmxvdz0idmlzaWJsZSIgY2xhc3M9ImFycm93LWhlYWQgYXJyb3ctb3BlbiI+CiAgICA8Zz4KICAgICAgPHBhdGggZD0iTTEgMS4yNSBMNi4xNSA0LjUgTDEgNy43NSIgc3Ryb2tlPSIjMDAwIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS13aWR0aD0iMiIgZmlsbD0ibm9uZSI+PC9wYXRoPgogICAgPC9nPgogIDwvc3ZnPgogIDx0ZXh0IHg9IjU0MiIgeT0iMjkxIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBjbGFzcz0ibWVzc2FnZS1sYWJlbCI+cXVldWUgaW52b2ljZSBlbWFpbHM8L3RleHQ+CiAgPHRleHQgeD0iNDU1IiB5PSIyOTEiIHRleHQtYW5jaG9yPSJlbmQiIGNsYXNzPSJzZXEtbnVtYmVyIj4zLjE8L3RleHQ+CjwvZz4KPGcgY2xhc3M9Im1lc3NhZ2Ugc2VsZi1jYWxsIj4KICA8c3ZnIHg9IjQ1OSIgeT0iMTY2IiB3aWR0aD0iMzAiIGhlaWdodD0iMjQiPgogICAgPHBhdGggZD0iTTAsMiBMMjYsMiBRMjgsMiAyOCw0IEwyOCwxMyBRMjgsMTUgMjYsMTUgTDEsMTUiIGZpbGw9Im5vbmUiIHN0cm9rZT0iIzAwMCIgc3Ryb2tlLXdpZHRoPSIyIj48L3BhdGg+CiAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgwLCAxMCkiPgogICAgICA8c3ZnIGhlaWdodD0iMTAiIHdpZHRoPSI3IiB2aWV3Qm94PSIwIDAgNyA5Ij4KICAgICAgICA8ZyB0cmFuc2Zvcm09InNjYWxlKC0xLCAxKSB0cmFuc2xhdGUoLTcsIDApIj4KICAgICAgICAgIDxwYXRoIGQ9Ik0xIDEuMjUgTDYuMTUgNC41IEwxIDcuNzUiIHN0cm9rZT0iIzAwMCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBmaWxsPSJub25lIiBzdHJva2Utd2lkdGg9IjIiPjwvcGF0aD4KICAgICAgICA8L2c+CiAgICAgIDwvc3ZnPgogICAgPC9nPgogIDwvc3ZnPgogIDx0ZXh0IHg9IjQ2NCIgeT0iMTYxIiB0ZXh0LWFuY2hvcj0ic3RhcnQiIGNsYXNzPSJtZXNzYWdlLWxhYmVsIj5yZW5kZXIgUERGIHN0YXRlbWVudHM8L3RleHQ+CiAgPHRleHQgeD0iNDU1IiB5PSIxNTgiIHRleHQtYW5jaG9yPSJlbmQiIGNsYXNzPSJzZXEtbnVtYmVyIj4yLjE8L3RleHQ+CjwvZz4KPGcgY2xhc3M9Im1lc3NhZ2Ugc2VsZi1jYWxsIj4KICA8c3ZnIHg9IjU2LjUiIHk9IjI0NyIgd2lkdGg9IjMwIiBoZWlnaHQ9IjI0Ij4KICAgIDxwYXRoIGQ9Ik0wLDIgTDI2LDIgUTI4LDIgMjgsNCBMMjgsMTMgUTI4LDE1IDI2LDE1IEwxNCwxNSIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjMDAwIiBzdHJva2Utd2lkdGg9IjIiPjwvcGF0aD4KICAgIDxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDcsIDEwKSI+CiAgICAgIDxzdmcgaGVpZ2h0PSIxMCIgd2lkdGg9IjciIHZpZXdCb3g9IjAgMCA3IDkiPgogICAgICAgIDxnIHRyYW5zZm9ybT0ic2NhbGUoLTEsIDEpIHRyYW5zbGF0ZSgtNywgMCkiPgogICAgICAgICAgPHBhdGggZD0iTTEgMS4yNSBMNi4xNSA0LjUgTDEgNy43NSBaIiBzdHJva2U9IiMwMDAiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgZmlsbD0iIzAwMCIgc3Ryb2tlLXdpZHRoPSIyIj48L3BhdGg+CiAgICAgICAgPC9nPgogICAgICA8L3N2Zz4KICAgIDwvZz4KICA8L3N2Zz4KICA8dGV4dCB4PSI2MS41IiB5PSIyNDUiIHRleHQtYW5jaG9yPSJzdGFydCIgY2xhc3M9Im1lc3NhZ2UtbGFiZWwiPmFuZDwvdGV4dD4KICA8dGV4dCB4PSI1Mi41IiB5PSIyNDUiIHRleHQtYW5jaG9yPSJlbmQiIGNsYXNzPSJzZXEtbnVtYmVyIj4zPC90ZXh0Pgo8L2c+CjxnIGNsYXNzPSJyZXR1cm4iPgogIDxsaW5lIHgxPSI0NTgiIHkxPSIzNDQiIHgyPSIyNjIiIHkyPSIzNDQiIGNsYXNzPSJyZXR1cm4tbGluZSI+PC9saW5lPgogIDxwb2x5bGluZSBwb2ludHM9IjI2Ny4xNSwzNDAuNzUgMjYyLDM0NCAyNjcuMTUsMzQ3LjI1IiBmaWxsPSJub25lIiBzdHJva2UtbGluZWNhcD0icm91bmQiIGNsYXNzPSJyZXR1cm4tYXJyb3ciPjwvcG9seWxpbmU+CiAgPHRleHQgeD0iMzYzLjUiIHk9IjM0MSIgdGV4dC1hbmNob3I9Im1pZGRsZSIgY2xhc3M9InJldHVybi1sYWJlbCI+MSwyMDQgaW52b2ljZXMsMyBmYWlsdXJlczwvdGV4dD4KICA8dGV4dCB4PSIyNTgiIHk9IjM0MSIgdGV4dC1hbmNob3I9ImVuZCIgY2xhc3M9InNlcS1udW1iZXIiPjQ8L3RleHQ+CjwvZz4KPGcgY2xhc3M9ImZyYWdtZW50IGZyYWdtZW50LXBhciI+CiAgPHJlY3QgeD0iLTkuNSIgeT0iMTA0LjUiIHdpZHRoPSI2NDIiIGhlaWdodD0iMTEyIiByeD0iNCIgY2xhc3M9ImZyYWdtZW50LWJvcmRlciI+PC9yZWN0PgogIDxyZWN0IHg9Ii05IiB5PSIxMDUiIHdpZHRoPSI2NDEiIGhlaWdodD0iMjUiIGNsYXNzPSJmcmFnbWVudC1oZWFkZXIiPjwvcmVjdD4KICA8c3ZnIHg9Ii01IiB5PSIxMDUiIHdpZHRoPSIyMCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIj4KICAgICAgPHBhdGggZD0iTTUgMTBIMTkiIHN0cm9rZT0iIzAwMCIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCI+PC9wYXRoPgogICAgICA8cGF0aCBkPSJNNSAxNEgxOSIgc3Ryb2tlPSIjMDAwIiBzdHJva2Utd2lkdGg9IjEuNSIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIj48L3BhdGg+CiAgICA8L3N2Zz4KICA8dGV4dCB4PSIxNyIgeT0iMTE3IiBkb21pbmFudC1iYXNlbGluZT0iY2VudHJhbCIgY2xhc3M9ImZyYWdtZW50LWxhYmVsIj5QYXI8L3RleHQ+CiAgPHRleHQgeD0iLTEzIiB5PSIxMTMiIHRleHQtYW5jaG9yPSJlbmQiIGRvbWluYW50LWJhc2VsaW5lPSJjZW50cmFsIiBjbGFzcz0ic2VxLW51bWJlciI+MjwvdGV4dD4KPC9nPgo8L2c+PC9zdmc+) `par` and `and` nest inside `if` and `try` too, so a real integration flow — branches, retries, parallel calls — stays one readable diagram instead of three screenshots stitched together. ## ZenUML or Mermaid sequenceDiagram?[​](#zenuml-or-mermaid-sequencediagram "Direct link to ZenUML or Mermaid sequenceDiagram?") Both render in the same macro; they optimize for different moments: | Situation | Reach for | | --------------------------------------------------------- | ------------------------------------ | | Simple request/response flow, documentation flavor | Mermaid `sequenceDiagram` | | Business logic with branches and error paths | ZenUML | | Diagram also lives in a GitHub README | Mermaid (GitHub renders it natively) | | Spec where the diagram must match the code's control flow | ZenUML | Install [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence), paste the checkout example into a ` ```zenuml ` fence, and watch the branch render while you type. Free for up to 10 users. ## Related Guides[​](#related-guides "Direct link to Related Guides") * [Create Mermaid Diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md) — the same macro's full diagram family * [Mermaid Sequence Diagrams in Confluence](/blog/mermaid-api-sequence-diagram-confluence.md) — the `sequenceDiagram` route for simpler flows * [How to Write Markdown in Confluence](/blog/how-to-write-markdown-in-confluence.md) — the base syntax everything lives in ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) * [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [confluence](/blog/tags/confluence.md) * [zenuml](/blog/tags/zenuml.md) * [sequence-diagram](/blog/tags/sequence-diagram.md) * [uml](/blog/tags/uml.md) * [mermaid](/blog/tags/mermaid.md) * [markdown](/blog/tags/markdown.md) * [how-to](/blog/tags/how-to.md) * [engineering](/blog/tags/engineering.md) --- [Skip to main content](#__docusaurus_skipToContent_fallback) [![NGPILOT Logo](/img/logo.svg)![NGPILOT Logo](/img/logo.svg)](/index.md) [Apps](/apps.md)[Solutions](/solutions.md)[Docs](/docs/intro.md)[Blogs](/blog.md)[Support](/support.md) [Atlassian Marketplace](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=navbar)[Contact us](mailto:support@ngpilot.com?subject=NGPILOT%20enquiry) Search # Search the documentation For Confluence * [Content Craft for Confluence](/docs/Content-Craft-for-Confluence/usage.md) * [Content Formatting Macros & Page Builder for Confluence](/docs/Content-Formatting-Macros-Page-Builder-for-Confluence/user-docs.md) * [Enhanced Markdown for Confluence](/docs/Enhanced-Markdown-for-Confluence/usage.md) * [EPUB Reader for Confluence](/docs/epub-reader-for-confluence/usage.md) * [Excalidraw & Mermaid Diagrams for Confluence](/docs/diagram-duo-for-confluence/usage.md) * [Excalidraw Plus Whiteboards & AI Agent for Confluence](/docs/Excalidraw-plus-for-Confluence/usage.md) * [Google Fonts for Confluence](/docs/Google-Fonts-for-Confluence/usage.md) * [Graphviz Charts for Confluence](/docs/Graphviz-Charts-for-Confluence/usage.md) * [JSON Structure Viewer for Confluence](/docs/json-structure-viewer-for-confluence/usage.md) * [Manim for Confluence](/docs/Manim-for-Confluence/user-docs.md) * [Markdown Mind Maps for Confluence](/docs/Markdown-Mind-Maps-for-Confluence/user-docs.md) * [Mermaid Plus Diagrams & AI Agent for Confluence](/docs/Mermaid-Plus-for-Confluence/usage.md) * [Modern Code Blocks for Confluence](/docs/Modern-Code-Blocks-for-Confluence/user-docs.md) * [Modern FAQ for Confluence](/docs/Modern-FAQ-for-Confluence/usage.md) * [Modern Importer & Exporter for Confluence](/docs/Modern-Importer-Exporter-for-Confluence/user-docs.md) * [Modern My Tasks for Confluence](/docs/Modern-My-Tasks-for-Confluence/user-docs.md) * [Modern Numbered Headings for Confluence](/docs/Modern-Numbered-Headings-for-Confluence/user-docs.md) * [Modern OpenAPI (Swagger) Integration for Confluence](/docs/Modern-OpenAPI-Swagger-Integration-for-Confluence/user-docs.md) * [Modern Questions for Confluence](/docs/Modern-Questions-for-Confluence/user-docs.md) * [Pagination Buttons for Confluence](/docs/Pagination-Buttons-for-Confluence/usage.md) * [PSD Attachments Viewer for Confluence](/docs/PSD-Attachments-Viewer-for-Confluence/user-docs.md) * [QR Code for Confluence](/docs/QRCode-for-Confluence/usage.md) * [Raw Storage Source Editor for Confluence (Free)](/docs/raw-storage-source-editor-for-Confluence/usage.md) * [Raw Storage Source Editor Pro for Confluence](/docs/raw-storage-source-editor-pro-for-Confluence/usage.md) * [Widget Carousel for Confluence](/docs/carousel-for-confluence/usage.md) For Jira * [Attachment Reviewer for Jira](/docs/Attachment-Reviewer-for-Jira/user-docs.md) * [Checklist Workflow Automation for Jira](/docs/Checklist-Workflow-Automation-for-Jira/user-docs.md) * [Component Hierarchy for Jira](/docs/Component-Hierarchy-for-Jira/user-docs.md) * [Excalidraw Diagrams plus Whiteboards for Jira](/docs/Excalidraw-Diagrams-plus-Whiteboards-for-Jira/usage.md) * [Issue History Agent for Jira](/docs/Issue-History-Agent-for-Jira/usage.md) * [JSON Graph Viewer & Visualizer for Jira](/docs/JSON-Graph-Viewer-Visualizer-for-Jira/user-docs.md) * [Mermaid Plus Diagrams for Jira](/docs/Mermaid-plus-Diagrams-for-Jira/usage.md) * [Modern Announcement Banner for Jira](/docs/Modern-Announcement-Banner-for-Jira/user-docs.md) * [Modern Issue Templates for Jira](/docs/Modern-Issue-Templates-for-Jira/user-docs.md) * [Simple Bulk Attachment Downloader for Jira](/docs/Simple-Bulk-Attachment-Downloader-for-Jira/user-docs.md) * [Simple Bulk Issues Excel CSV Export for Jira](/docs/Simple-Bulk-Issues-Excel-CSV-Export-for-Jira/user-docs.md) Resources * [Scenario Solutions](/solutions.md) * [Documentation](/docs/intro.md) * [Blog](/blog.md) * [Mermaid in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export to Excel](/blog/export-jira-issues-to-excel.md) * [Code Blocks Guide](/blog/code-blocks-confluence-monaco-editor.md) * [Markdown Guide](/blog/faq-confluence-markdown-editor.md) * [Diagram Tools Guide](/blog/confluence-diagram-tools-comparison.md) * [Bold & Formatting Guide](/blog/bold-text-confluence.md) * [Forge vs Connect](/blog/forge-vs-connect-atlassian-admins-2026.md) * [What is Atlassian Rovo?](/blog/what-is-atlassian-rovo.md) * [Evaluating a Marketplace App](/blog/how-to-evaluate-atlassian-marketplace-app.md) * [Jira vs Confluence](/blog/jira-vs-confluence.md) Company * [Atlassian Marketplace](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=footer) * [Atlassian Community](https://community.atlassian.com/forums/user/viewprofilepage/user-id/6175343) * [Privacy Policy](/docs/privacy-policy.md) * [EULA](/docs/eula.md) * [Security](/docs/security-policy.md) © 2026 NGPILOT, Inc. All rights reserved. --- Scenario Solutions # Start with the problem,
not the app 16 common Confluence & Jira scenarios — why they matter, how to solve them, and the NGPILOT apps that do the work. All free for up to 10 users. --- Confluence & Jira Solution # Put AI agents to work on your content A chat assistant can describe the change you want to a diagram or a changelog. It cannot make it. Scoped AI agents can — and the difference is one install, not a project. See the solutions[Browse all apps](/apps.md) --- Confluence Solution # Build polished pages, portals, and navigation in Confluence Intranets, marketing pages, and portal hubs in Confluence — learn how to structure, style, and navigate them without HTML or CSS. See the solutions[Browse all apps](/apps.md) --- Confluence Solution # Show code, JSON, and API docs in Confluence Confluence’s basic code macro is not enough for technical content. Learn how to present code, JSON, and OpenAPI specs so readers actually get it. See the solutions[Browse all apps](/apps.md) --- Jira Solution # Organize Jira Components into a Tree Jira components are a flat list — fine for three entries, unusable at fifty. Learn how to give components a parent-child tree and search whole branches with one JQL clause. See the solutions[Browse all apps](/apps.md) --- Confluence Solution # Use custom fonts and branding in Confluence Default Confluence typography makes every page look the same. Learn how to apply your brand’s fonts and visual style across your wiki. See the solutions[Browse all apps](/apps.md) --- Confluence Solution # Create diagrams in Confluence Diagrams turn abstract processes into something the whole team can see. Learn how to create them in Confluence — and the apps that make it effortless. See the solutions[Browse all apps](/apps.md) --- Jira Solution # Add diagrams to Jira issues Bugs, features, and epics are easier to understand with a picture. Learn how to add diagrams directly to Jira issues — no external tools. See the solutions[Browse all apps](/apps.md) --- Jira Solution # Export Jira issues to Excel or CSV Reporting, stakeholders, and audits need your Jira data somewhere Jira is not. Learn how to export issues to Excel and CSV without timeouts. See the solutions[Browse all apps](/apps.md) --- Jira Solution # Manage Jira attachments Attachments pile up, downloads take forever, and file rules go unenforced. Learn how to download and control Jira attachments at scale. See the solutions[Browse all apps](/apps.md) --- Confluence Solution # Add media and interactive elements to Confluence pages Static pages lose readers. Learn how to enrich Confluence pages with QR codes and interactive math animations that people actually engage with. See the solutions[Browse all apps](/apps.md) --- Confluence Solution # Migrate, back up, and organize Confluence content Confluence content grows without permission. Learn how to export, convert, and migrate it between spaces and formats without losing structure. See the solutions[Browse all apps](/apps.md) --- Jira Solution # Standardize Jira workflows with templates and banners Consistent tickets, clear communication. Learn how to standardize how your team creates issues and announces changes in Jira. See the solutions[Browse all apps](/apps.md) --- Confluence Solution # Run team knowledge with FAQs, Q\&A, and tasks in Confluence Stop re-answering the same questions and losing track of action items. Learn how to structure knowledge, Q\&A, and tasks in Confluence. See the solutions[Browse all apps](/apps.md) --- Jira Solution # Track Issue History in Jira Jira records every change, but reading that history means digging through changelogs and REST calls. Learn how to see who changed what on an issue — field by field, value by value — or just ask the Rovo agent. See the solutions[Browse all apps](/apps.md) --- Jira Solution # Visualize JSON in Jira Integration payloads, webhook data, and app state live on your issues as JSON. Learn how to read that JSON as an interactive graph instead of a wall of braces. See the solutions[Browse all apps](/apps.md) --- Confluence Solution # Write Markdown in Confluence Markdown is the language of documentation. Learn how to write it inside Confluence — with live preview, math, diagrams, and native page output. See the solutions[Browse all apps](/apps.md) --- FAQ ## Frequently Asked Questions How do I install a NGPILOT app?− Visit the NGPILOT vendor page on the Atlassian Marketplace, find the app you want, and click "Get it now." The app installs directly into your Confluence or Jira Cloud instance. No additional setup or configuration is required for most apps. Why isn't my app showing up after installation?+ First, ensure that your Confluence or Jira admin has completed the installation. Apps typically appear within a few minutes. If it doesn't show up, try refreshing the page or clearing your browser cache. Some apps require you to be a site administrator to complete the initial setup. Are NGPILOT apps really free?+ Yes — all NGPILOT apps are free for up to 10 users. Beyond 10 users, standard Atlassian Marketplace licensing applies. Every app also includes the built-in free trial that Atlassian provides for all Marketplace apps, so you can evaluate any app with your full team before committing. Do NGPILOT apps work with Confluence Data Center or Server?+ No. All NGPILOT apps are built exclusively for Confluence Cloud and Jira Cloud using Atlassian's Forge platform. They do not support Data Center or Server deployments. We chose Cloud-only to provide the best security, automatic updates, and zero-maintenance experience. How do I configure an app after installation?+ Most apps work out of the box with no configuration. If an app has settings, you'll find them in the app's configuration page within your Confluence or Jira admin console. Each app also has a detailed User Guide available on our Documentation page. Can I request a new feature or app?+ Absolutely. Send us an email at support\@ngpilot.com with your feature request. We prioritize features based on community demand and roadmap alignment. You can also upvote existing feature requests on the Atlassian Marketplace listing for each app. --- Customers ## Trusted by teams worldwide Organizations from 10 to 9,400 users across five continents — including Fortune-scale enterprises and global Atlassian partners — rely on NGPILOT apps in their daily workflows. 170+ organizations 20+ countries 13 enterprise teams (500+) 9,400 largest team size Sectors represented: Technology & SoftwareFinancial ServicesLife Sciences & BiopharmaReal EstateUtilities & Public SectorManufacturingConstructionDigital Agencies --- # Attachment Reviewer for Jira - User Guide ## Table of Contents[​](#table-of-contents "Direct link to Table of Contents") 1. [Introduction](#introduction) 2. [Getting Started](#getting-started) 3. [Configuration Guide](#configuration-guide) 4. [How Validation Works](#how-validation-works) 5. [Understanding Validation Results](#understanding-validation-results) 6. [Best Practices](#best-practices) 7. [Troubleshooting](#troubleshooting) 8. [FAQ](#faq) *** ## Introduction[​](#introduction "Direct link to Introduction") ### What is Attachment Reviewer?[​](#what-is-attachment-reviewer "Direct link to What is Attachment Reviewer?") Attachment Reviewer for Jira is an automated security and compliance tool that validates every file uploaded to your Jira issues. It helps you: * **Prevent security risks** by blocking dangerous file types (executables, scripts, etc.) * **Control storage costs** by enforcing file size limits * **Maintain compliance** with corporate file policies * **Keep projects organized** by standardizing allowed file types ### Key Benefits[​](#key-benefits "Direct link to Key Benefits") ✅ **Automatic Enforcement** - No manual reviews needed ✅ **Real-time Feedback** - Users know immediately if files are blocked ✅ **Project-Level Control** - Each project can have different rules ✅ **Secure by Default** - Pre-configured to block risky file types ✅ **User-Friendly** - Clear explanations when files are blocked *** ## Getting Started[​](#getting-started "Direct link to Getting Started") ### Installation[​](#installation "Direct link to Installation") 1. Visit the [Atlassian Marketplace](https://marketplace.atlassian.com) 2. Search for "Attachment Reviewer for Jira" 3. Click "Get it now" 4. Select your Jira site 5. Confirm installation 6. Wait for installation to complete (usually 1-2 minutes) ### First-Time Setup[​](#first-time-setup "Direct link to First-Time Setup") After installation, the app works immediately with secure default settings: * **File Types**: Whitelist mode with common business files allowed * **File Size**: 25MB maximum, 10MB warning threshold * **Validation**: Enabled for all projects You can customize these settings per project (see [Configuration Guide](#configuration-guide)). ### Accessing Settings[​](#accessing-settings "Direct link to Accessing Settings") **For Project Administrators:** 1. Navigate to your Jira project 2. Click **Project Settings** (gear icon in sidebar) 3. Scroll down to find **Attachment Reviewer** in the sidebar 4. Click to open the settings page **Required Permission:** You must be a Project Administrator to access settings. *** ## Configuration Guide[​](#configuration-guide "Direct link to Configuration Guide") ### Settings Overview[​](#settings-overview "Direct link to Settings Overview") The settings page has three main sections: 1. **File Type Rules** - Control which file types are allowed 2. **File Size Rules** - Set size limits for attachments 3. **Notification Settings** - Configure validation feedback ### File Type Rules[​](#file-type-rules "Direct link to File Type Rules") #### Validation Mode[​](#validation-mode "Direct link to Validation Mode") Choose how file types are controlled: **Whitelist Mode (Recommended)** * Only explicitly allowed file types can be uploaded * Most secure option * Default setting * Best for security-conscious organizations **Blacklist Mode** * All file types allowed except explicitly blocked ones * More flexible but less secure * Use when you need to allow many different file types #### Managing Allowed File Types[​](#managing-allowed-file-types "Direct link to Managing Allowed File Types") 1. Click the **Allowed Extensions** dropdown 2. Browse categories (Documents, Images, Archives, etc.) 3. Select file types you want to allow 4. Selected types appear as tags below the dropdown 5. Click the X on any tag to remove it **Default Allowed Types:** * Documents: pdf, doc, docx, txt, rtf, odt * Spreadsheets: xls, xlsx, csv, ods * Presentations: ppt, pptx, odp * Images: png, jpg, jpeg, gif, svg, webp, bmp * Archives: zip, rar, 7z, tar, gz * Data: json, xml, yaml, yml #### Managing Blocked File Types[​](#managing-blocked-file-types "Direct link to Managing Blocked File Types") 1. Click the **Blocked Extensions** dropdown 2. Select file types you want to block 3. Blocked types are always enforced, even in blacklist mode **Default Blocked Types (Security):** * Executables: exe, msi, bat, cmd, com, scr, pif * Scripts: vbs, js, ps1, sh, bash, zsh * System Files: sys, dll, drv, ocx * Java: jar, war, ear * Mobile Apps: apk, ipa, app, deb, rpm, dmg * Macro Documents: docm, xlsm, pptm, dotm, xltm, potm * Risky Files: torrent, iso, img, vhd, vmdk * Databases: mdb, accdb, db, sqlite, sqlite3 **Important:** Blocked types always take precedence over allowed types. ### File Size Rules[​](#file-size-rules "Direct link to File Size Rules") #### Maximum File Size[​](#maximum-file-size "Direct link to Maximum File Size") Set the absolute maximum file size allowed: * **Range:** 1 MB to 500 MB * **Default:** 25 MB * **Recommendation:** Set based on your storage capacity and typical file needs **Examples:** * Small projects: 10-25 MB * Standard projects: 25-50 MB * Media-heavy projects: 50-100 MB * Special cases: Up to 500 MB #### Warning Threshold[​](#warning-threshold "Direct link to Warning Threshold") Set a size that triggers a warning (but doesn't block): * **Range:** 1 MB to maximum size * **Default:** 10 MB * **Purpose:** Alert users about large files without blocking them **Use Case:** Warn users when files are larger than typical, encouraging them to consider if the file size is necessary. ### Notification Settings[​](#notification-settings "Direct link to Notification Settings") #### Comment on Success[​](#comment-on-success "Direct link to Comment on Success") **Default:** Disabled When enabled, posts a comment even when validation passes. Most users prefer to only see comments when there are issues. **Enable if:** * You want audit trails of all uploads * You need proof of validation for compliance * Your team wants confirmation of successful uploads **Disable if:** * You want to reduce comment noise * You only care about failures and warnings ### Saving Settings[​](#saving-settings "Direct link to Saving Settings") 1. Review all your configuration changes 2. Click **Save Settings** button at the bottom 3. Wait for confirmation message 4. Settings are now active for this project **Note:** Settings are saved per project. Other projects are not affected. ### Resetting to Defaults[​](#resetting-to-defaults "Direct link to Resetting to Defaults") If you want to start over: 1. Click **Reset to Defaults** button 2. Confirm the action 3. All settings return to secure defaults 4. Click **Save Settings** to apply *** ## How Validation Works[​](#how-validation-works "Direct link to How Validation Works") ### Validation Process[​](#validation-process "Direct link to Validation Process") When a user uploads an attachment to an issue: 1. **Upload Initiated** - User attaches file to issue 2. **Automatic Validation** - App checks file against project rules 3. **Decision Made** - File passes, warns, or fails validation 4. **Action Taken** - File kept or removed based on result 5. **Feedback Posted** - Comment added to issue with details ### Validation Checks[​](#validation-checks "Direct link to Validation Checks") The app performs these checks in order: #### 1. File Type Check (if enabled)[​](#1-file-type-check-if-enabled "Direct link to 1. File Type Check (if enabled)") **Blocked List Check:** * Is the file extension in the blocked list? * If YES → **FAIL** (file removed) * If NO → Continue to next check **Whitelist Mode Check:** * Is the file extension in the allowed list? * If NO → **FAIL** (file removed) * If YES → Continue to next check **Blacklist Mode:** * If not blocked, file type passes #### 2. File Size Check (if enabled)[​](#2-file-size-check-if-enabled "Direct link to 2. File Size Check (if enabled)") **Maximum Size Check:** * Is file larger than maximum size? * If YES → **FAIL** (file removed) * If NO → Continue to next check **Warning Threshold Check:** * Is file larger than warning threshold? * If YES → **WARN** (file kept, warning posted) * If NO → **PASS** ### What Happens to Failed Files[​](#what-happens-to-failed-files "Direct link to What Happens to Failed Files") When a file fails validation: 1. **File is Removed** - Attachment is automatically deleted 2. **Comment Posted** - Validation report added to issue 3. **User Notified** - User sees comment explaining why 4. **No Manual Action** - Everything happens automatically ### Validation Results[​](#validation-results "Direct link to Validation Results") Three possible outcomes: **✅ Passed** * File meets all requirements * File is kept on the issue * Comment posted only if "Comment on Success" is enabled **⚠️ Passed with Warnings** * File meets minimum requirements but has warnings * File is kept on the issue * Comment posted explaining warnings **❌ Failed** * File violates one or more rules * File is automatically removed * Comment posted explaining why (with "been removed" notice) *** ## Understanding Validation Results[​](#understanding-validation-results "Direct link to Understanding Validation Results") ### Validation Comment Format[​](#validation-comment-format "Direct link to Validation Comment Format") When validation occurs, a comment is posted with this information: ``` ### Attachment Validation Report File Name: example.exe File Type: application/x-msdownload File Size: 5.23 MB Validation Result: ❌ Failed (been removed) ``` ### Status Indicators[​](#status-indicators "Direct link to Status Indicators") **✅ Passed** * All validation checks passed * No issues found * File is safe to use **⚠️ Passed with Warnings** * File passed but has concerns * Example: File size exceeds warning threshold * File is kept but review recommended **❌ Failed** * File violated one or more rules * File has been removed automatically * User must upload a compliant file ### Common Failure Reasons[​](#common-failure-reasons "Direct link to Common Failure Reasons") **"File type '.exe' is blocked for security reasons"** * The file extension is in the blocked list * Solution: Don't upload executable files **"File type '.xyz' is not in the allowed list"** * Project uses whitelist mode * File type not in allowed list * Solution: Ask admin to add the file type or use an allowed format **"File size 30.5MB exceeds maximum allowed size of 25MB"** * File is too large * Solution: Compress the file or split into smaller files ### Warning Messages[​](#warning-messages "Direct link to Warning Messages") **"File size 15.2MB exceeds recommended size of 10MB"** * File is larger than recommended but still allowed * Consider if file size is necessary * File is kept on the issue *** ## Best Practices[​](#best-practices "Direct link to Best Practices") ### For Administrators[​](#for-administrators "Direct link to For Administrators") **Security Best Practices:** 1. **Use Whitelist Mode** - More secure than blacklist mode 2. **Keep Blocked List Updated** - Add new risky file types as needed 3. **Review Defaults** - The default blocked list is comprehensive 4. **Set Reasonable Size Limits** - Balance security and usability 5. **Document Your Policies** - Let users know what's allowed **Configuration Tips:** 1. **Start with Defaults** - They're secure and well-tested 2. **Customize Gradually** - Add file types as needed 3. **Test Changes** - Upload test files after changing settings 4. **Monitor Comments** - Watch for validation failures 5. **Adjust Based on Usage** - Refine rules based on team needs **Project-Specific Settings:** * **Development Projects**: May need code files (js, py, java) * **Design Projects**: May need larger image files * **Documentation Projects**: Focus on documents and PDFs * **General Projects**: Use default settings ### For Users[​](#for-users "Direct link to For Users") **Uploading Files:** 1. **Check File Type** - Ensure your file type is allowed 2. **Check File Size** - Keep files under the limit 3. **Read Validation Comments** - They explain what went wrong 4. **Ask Admin if Needed** - Request new file types if necessary 5. **Use Appropriate Formats** - Choose common, safe file types **If Your File is Blocked:** 1. **Read the Comment** - Understand why it was blocked 2. **Check File Type** - Is it a risky type (exe, bat, etc.)? 3. **Check File Size** - Is it too large? 4. **Convert if Possible** - Use an allowed format 5. **Contact Admin** - If you need an exception **Recommended File Formats:** * **Documents**: PDF (best), DOCX, TXT * **Spreadsheets**: XLSX, CSV * **Images**: PNG, JPG (compressed) * **Archives**: ZIP (most compatible) * **Data**: JSON, CSV, XML *** ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") ### Common Issues[​](#common-issues "Direct link to Common Issues") #### Issue: Settings page won't load[​](#issue-settings-page-wont-load "Direct link to Issue: Settings page won't load") **Possible Causes:** * Not a project administrator * App not installed properly * Browser cache issues **Solutions:** 1. Verify you have Project Admin permissions 2. Refresh the page (Ctrl+F5 or Cmd+Shift+R) 3. Clear browser cache 4. Try a different browser 5. Contact your Jira administrator #### Issue: Settings won't save[​](#issue-settings-wont-save "Direct link to Issue: Settings won't save") **Possible Causes:** * Invalid configuration * Network issues * Permission problems **Solutions:** 1. Check for error messages on the page 2. Ensure file size values are valid (1-500 MB) 3. Ensure warning size is less than maximum size 4. Check your internet connection 5. Try again in a few minutes #### Issue: Files are being blocked unexpectedly[​](#issue-files-are-being-blocked-unexpectedly "Direct link to Issue: Files are being blocked unexpectedly") **Possible Causes:** * File type not in allowed list (whitelist mode) * File type in blocked list * File size too large * Settings recently changed **Solutions:** 1. Check the validation comment for specific reason 2. Review project settings 3. Verify file extension is in allowed list 4. Check file size against limits 5. Contact project administrator #### Issue: Validation comments not appearing[​](#issue-validation-comments-not-appearing "Direct link to Issue: Validation comments not appearing") **Possible Causes:** * Validation passed with no warnings * "Comment on Success" is disabled * App permissions issue **Solutions:** 1. Check if file actually failed validation 2. Enable "Comment on Success" if you want all validations logged 3. Verify app has permission to post comments 4. Check Jira activity log #### Issue: Wrong files are being allowed[​](#issue-wrong-files-are-being-allowed "Direct link to Issue: Wrong files are being allowed") **Possible Causes:** * Blacklist mode is active * File type not in blocked list * Validation disabled **Solutions:** 1. Switch to whitelist mode for better security 2. Add problematic file types to blocked list 3. Verify validation is enabled 4. Check settings were saved properly ### Getting Help[​](#getting-help "Direct link to Getting Help") **Before Contacting Support:** 1. Check this user guide 2. Review the FAQ section 3. Verify your permissions 4. Try the troubleshooting steps above 5. Check the validation comments for clues **When Contacting Support:** Include this information: * Your Jira site URL * Project key * File that was blocked (name and extension) * Validation comment text * Screenshots of settings page * What you expected to happen * What actually happened **Support Channels:** * Email: * Documentation: *** ## FAQ[​](#faq "Direct link to FAQ") ### General Questions[​](#general-questions "Direct link to General Questions") **Q: Does this work with Jira Cloud?** A: Yes, this app is built specifically for Jira Cloud using Atlassian Forge. **Q: Does this work with Jira Server/Data Center?** A: No, this app is only for Jira Cloud. Forge apps don't support Server/Data Center. **Q: Is this app free?** A: Check the Atlassian Marketplace listing for current pricing information. **Q: Can I try it before buying?** A: Yes, most Forge apps offer a free trial period. Check the Marketplace listing. ### Configuration Questions[​](#configuration-questions "Direct link to Configuration Questions") **Q: Can different projects have different rules?** A: Yes! Each project has completely independent settings. **Q: Can I have different rules for different issue types?** A: Not currently. Rules apply to all issues in a project. **Q: What's the difference between whitelist and blacklist mode?** A: * **Whitelist**: Only allowed types can be uploaded (more secure) * **Blacklist**: Everything allowed except blocked types (more flexible) **Q: Can I add custom file extensions?** A: Yes, you can add any file extension to the allowed or blocked lists. **Q: How many file types can I allow?** A: No limit. You can select as many as needed. **Q: Can I import/export settings between projects?** A: Not currently. This feature is planned for a future release. ### Validation Questions[​](#validation-questions "Direct link to Validation Questions") **Q: What happens to files that fail validation?** A: They are automatically removed from the issue and a comment explains why. **Q: Can users override the validation?** A: No. Validation is enforced automatically to maintain security. **Q: Does this affect existing attachments?** A: No. Only new uploads are validated. Use the Scan Report feature (coming soon) to audit existing files. **Q: How fast is validation?** A: Very fast. Validation happens in milliseconds and doesn't slow down uploads. **Q: Can I see a history of blocked files?** A: Yes, check the issue comments. Each validation creates a comment. **Q: What if I need to upload a blocked file type?** A: Contact your project administrator to request the file type be added to the allowed list. ### Security Questions[​](#security-questions "Direct link to Security Questions") **Q: Is my data secure?** A: Yes. The app runs on Atlassian's secure Forge platform. No data leaves Atlassian's infrastructure. **Q: Does the app read file contents?** A: No. Only metadata (filename, size, MIME type) is checked. File contents are not accessed. **Q: What file types are blocked by default?** A: Executables, scripts, system files, mobile apps, macro-enabled documents, and other risky types. **Q: Can malware get through?** A: The app blocks known risky file types but doesn't scan for viruses. Use additional security tools for virus scanning. **Q: Is this GDPR compliant?** A: Yes. No personal data is collected or stored by the app. ### Technical Questions[​](#technical-questions "Direct link to Technical Questions") **Q: What permissions does the app need?** A: * `read:jira-work` - Read issue and attachment information * `write:jira-work` - Post comments and remove non-compliant files * `manage:jira-project` - Access project settings **Q: Does this work with the Jira mobile app?** A: Yes. Validation works regardless of how files are uploaded. **Q: Can I use this with automation rules?** A: Yes. The app works alongside Jira automation. **Q: Does this integrate with other apps?** A: The app works independently but doesn't conflict with other apps. **Q: How do I uninstall the app?** A: Go to Manage Apps in Jira settings and uninstall like any other app. ### Future Features[​](#future-features "Direct link to Future Features") **Q: Will there be a scan report feature?** A: Yes! Attachment scanning and audit reports are planned for a future release. **Q: Can you add content-based validation?** A: This is being considered for future releases. **Q: Will you support custom validation rules?** A: Advanced validation rules are planned for future releases. **Q: Can I get email notifications?** A: Not currently, but this may be added in the future. *** ## Appendix[​](#appendix "Direct link to Appendix") ### Default File Extensions by Category[​](#default-file-extensions-by-category "Direct link to Default File Extensions by Category") **Documents:** * pdf, doc, docx, txt, rtf, odt, pages **Spreadsheets:** * xls, xlsx, csv, ods, numbers **Presentations:** * ppt, pptx, odp, key **Images:** * png, jpg, jpeg, gif, bmp, svg, tiff, webp, ico **Audio:** * mp3, wav, flac, aac, ogg, m4a **Video:** * mp4, avi, mov, wmv, flv, webm, mkv **Archives:** * zip, rar, 7z, tar, gz, bz2, xz **Code:** * js, ts, py, java, cpp, c, cs, php, rb, go, rs, swift, kt, html, css, scss, json, xml, yaml, yml, sql **Blocked (Security):** * exe, msi, bat, cmd, com, scr, pif, vbs, ps1, sh, bash, zsh, sys, dll, drv, ocx, jar, war, ear, apk, ipa, app, deb, rpm, dmg, docm, xlsm, pptm, dotm, xltm, potm, torrent, iso, img, vhd, vmdk, mdb, accdb, db, sqlite, sqlite3 ### File Size Reference[​](#file-size-reference "Direct link to File Size Reference") * 1 MB = 1,024 KB = 1,048,576 bytes * 10 MB = Typical high-resolution photo * 25 MB = Default maximum (about 10 high-res photos) * 50 MB = Short video clip * 100 MB = Longer video or large dataset * 500 MB = Maximum allowed (very large files) ### Glossary[​](#glossary "Direct link to Glossary") **Attachment** - A file uploaded to a Jira issue **Validation** - The process of checking if a file meets project rules **Whitelist** - A list of explicitly allowed items (more secure) **Blacklist** - A list of explicitly blocked items (more flexible) **File Extension** - The suffix after the dot in a filename (e.g., .pdf, .jpg) **MIME Type** - Technical identifier for file type (e.g., application/pdf) **Forge** - Atlassian's cloud app development platform **Project Properties** - Jira's native storage for project-specific data *** *Last Updated: February 2026* *Version: 1.0.0* For the latest updates and information, visit the [Atlassian Marketplace](https://marketplace.atlassian.com). ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [Jira attachment management apps compared](/blog/jira-attachment-management-comparison.md) * [FAQ: Jira attachments and permissions](/blog/faq-jira-attachments-permissions.md) Was this helpful?👍 Yes👎 No --- # Usage ## Add carousel macro[​](#add-carousel-macro "Direct link to Add carousel macro") 1. Type "/widget" and select the Widget Carousel to insert ![Typing /widget in editor to find carousel macro](/assets/images/1-bb6ff201c50533be962914685e4ff051.png) 2. Or click the "+" button and select "Widget Carousel" ![Selecting Widget Carousel from insert menu](/assets/images/2-75fc89afa96476e232e224c929028140.png) ## Config macro[​](#config-macro "Direct link to Config macro") * Select images from page attachments or upload a new one ![Selecting images from page attachments](/assets/images/3-29dcad25ad7f91357febb308d8a9dec3.png) ![Uploading a new image to the carousel](/assets/images/4-989efffb2b4e1a9711429c15c4d8bf7a.png) ![Complete image selection for carousel](/assets/images/5-70bf727171525efe355638dae96d9af0.png) * Click "Save" button to save the macro. * Use macro edit buttons to choose macro width: default, wide, full width ![Carousel width configuration options](/assets/images/6-a2081f3080b205592a38220484744954.png) * Done, save the page. ![Image carousel displayed on the Confluence page](/assets/images/7-ba13a030414bd9020c5da4369c028b12.png) ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [Best Confluence apps for developers](/blog/best-confluence-apps-developers.md) Was this helpful?👍 Yes👎 No --- # Checklist Workflow Automation for Jira — User Guide ## Introduction[​](#introduction "Direct link to Introduction") Checklist Workflow Automation for Jira adds a checklist to every issue — and, unlike a plain checkbox list, it can **enforce** your process: mark an item as `required`, and Jira blocks the workflow transition until every required item is exactly **Done**. No workflow-editor rules to maintain, no scripts — the enforcement rule lives on the checklist items themselves. Everything runs natively in Jira Cloud (built 100% on Atlassian Forge). The checklist is stored on the issue itself, so it survives moves, shows up in JQL searches, and copies when you clone an issue. ## Quick start[​](#quick-start "Direct link to Quick start") 1. Install from the Atlassian Marketplace (try it free on your own site). 2. Open any issue — the checklist panel is on the issue's right side. 3. Type a task and press **Enter**. Keep typing to add more. 4. Toggle the flag on a row (or the header flag for the whole list) to mark items **required**. 5. Ask a Jira admin to attach the **validator** to your workflow's Done transition (see [Enforcement](#enforcement-blocking-transitions-until-required-items-are-done)). ## The checklist panel[​](#the-checklist-panel "Direct link to The checklist panel") ``` 2/5 ▓▓▓▓▓▓░░░░░░░░░░░ 40% [ ⋯ ] ────────────────────────────────────── ⚑ ☐ Book venue [date] ☐ Send invites Waiting [date] ☑ Reserve budget Done [ + Add a task, press Enter… ] ``` * **All-in-place editing** — click a task's text to edit it right in the row; no modal. Press Enter to save, Esc to cancel. * **Sub-tasks** — click a row's **wrench** and choose *Add sub-task* to nest items under it (up to two levels of sub-tasks); the progress bar and enforcement track the whole tree. * **Statuses** — six built-in statuses (To Do, In Progress, Blocked, Review, Done, Skipped) shown as colored lozenges. Projects can add their own — see [Project settings](#project-settings-the-checklist-admin-page). * **Due dates** — click the date chip: Today / Tomorrow / In 7 days, or pick any date. Overdue items show a red lozenge; due-within-2-days shows amber. * **Required flags** — the flag column marks items that gate the workflow. Blue flag = required and unfinished. * **Markdown** — item text renders markdown: bold, links, code, and more. * **Header controls** — the header checkbox completes/clears the whole list; the header flag marks everything required; the **⋯** menu holds templates, CSV import/export, **Clear all tasks** and more. Completed items stay in place with a strike-through, so the list order never jumps. ## Enforcement: blocking transitions until required items are done[​](#enforcement-blocking-transitions-until-required-items-are-done "Direct link to Enforcement: blocking transitions until required items are done") ### The one rule[​](#the-one-rule "Direct link to The one rule") > A transition is blocked ⟺ some item marked `required` is not exactly **Done**. **Skipped does not count** as done, and neither do any custom statuses. The same rule drives the workflow validator, JQL search, and overdue reminders — there is one definition of "not finished" everywhere. **Custom statuses never count as Done.** Projects can add their own statuses (e.g. *Waiting on vendor*) for bookkeeping; a required item sitting on a custom status still blocks the transition. Only exactly **Done** satisfies a requirement. ### Attaching enforcement to a workflow (Jira admin)[​](#attaching-enforcement-to-a-workflow-jira-admin "Direct link to Attaching enforcement to a workflow (Jira admin)") The validator and post function are standard Jira workflow elements — add them once per workflow, no ongoing configuration: **Validator — block the transition** 1. Go to **Project settings → Workflows** and edit your workflow. 2. On the transition that should be gated (typically the one into **Done**), choose **Validators → Add validator**. 3. Pick **Checklist required items complete** (category: *Forge apps*). While any required item is unfinished, the transition is refused with: `Complete required checklist items before transitioning: "Book venue", …` If the app cannot read a checklist (e.g. its data was deleted), the validator **fails open** — a broken app must never brick a workflow. **Post function — auto-complete on transition** 1. On the same (or any) transition, choose **Post functions → Add post function**. 2. Pick **Complete required checklist items**. After the transition runs, every **required** item is marked Done. Non-required items are never touched, and JQL counts refresh in the same step. ## Finding work with JQL[​](#finding-work-with-jql "Direct link to Finding work with JQL") ``` issue in hasIncompleteRequired() cwaIncompleteRequired > 0 cwaOverdueRequired > 0 cwaIncompleteRequired > 0 AND assignee = currentUser() AND sprint in openSprints() ``` * `hasIncompleteRequired()` — issues with at least one unfinished required item. * `cwaIncompleteRequired` / `cwaOverdueRequired` — indexed counters (support `ORDER BY`); they refresh on every panel edit and are self-corrected by the daily sweep. * The negation `issue NOT IN hasIncompleteRequired()` includes issues without a checklist at all. Save any of these as a filter for a **team QA board** or a dashboard gadget — e.g. "everything I still owe before Done". ## Overdue reminders[​](#overdue-reminders "Direct link to Overdue reminders") A daily sweep finds unresolved issues where a **required** item is past its due date and posts a comment mentioning the issue's assignee, listing the overdue items (unassigned issues still get the comment, without the mention). Each issue is reminded at most once per **7 days**; resolving the issue or finishing the items stops reminders automatically. ## Cloning issues[​](#cloning-issues "Direct link to Cloning issues") Cloning an issue copies the checklist — texts, required flags, sub-tasks, assignees, due dates — with every status reset to **To Do** (a clone means "do this work again"). Uses Jira's standard *Cloners* link; ordinary issue creation is unaffected. ## Templates and CSV[​](#templates-and-csv "Direct link to Templates and CSV") * **Templates** — save a checklist as a reusable project template and apply it to any issue in that project (the ⋯ menu). Sub-tasks are included: the whole nesting is saved and rebuilt on apply (statuses and due dates are not — templates are process, not state). Templates you no longer want can be deleted right in the apply picker (trash icon, click twice to confirm). Applied the wrong template? **⋯ → Clear all tasks** wipes the checklist in one step. * **CSV import/export** — bulk-edit in a spreadsheet. Import picks a .csv file (or pastes content straight from Excel); export downloads `checklist--.csv` the moment you pick it from the menu (if your browser blocks it, a dialog falls back to copy/paste). Columns: Item Text, Status, Order, Level — the Level column carries sub-task nesting, so exported files round-trip with sub-tasks under the right parents (statuses including custom ones restore too; unknown values fall back to To Do, and files without a Level column import as a flat list). ## Project settings: the Checklist Admin page[​](#project-settings-the-checklist-admin-page "Direct link to Project settings: the Checklist Admin page") Project admins open **Project settings → Checklist Admin**: * **Settings tab** * *Display mode* — `Both` (checkboxes + status column, the default), `Status` (complete items via the status menu; checkbox column hidden), or `Checkbox` (plain done/not-done; status column hidden). * *Mark new items as required by default* — new rows start required. * *Custom statuses* — add up to 10 project-specific statuses (label + color). Values are stable across renames, and custom statuses never satisfy a required item. Removing one keeps the stored data; affected items display as To Do until re-statused. * **Audit log tab** — an append-only record of who created, edited, completed, required or deleted items, and who applied templates or imports, with before/after detail. Entries are identified from Jira's server-side context, so they can't be spoofed from the client. ## FAQ[​](#faq "Direct link to FAQ") **Do required items block issue creation or other transitions?** No. Only transitions with the validator attached are gated, and the validator only inspects checklist items — it never blocks issue creation. **What happens to items when someone removes the app?** The checklist lives in a standard Jira issue property, so the data stays on the issue. Validators attached to workflows keep failing open (transitions pass). **Can different projects behave differently?** Yes — display mode, required-by-default and custom statuses are all per-project settings. **Does this work on team-managed projects?** Company-managed projects get the full enforcement flow (workflow validator / post function). Team-managed projects don't support Forge workflow rules, so there the app works as a checklist panel without transition gating. The panel detects this automatically and shows a warning banner on team-managed projects. **Which plan/tier do I need?** Any Jira Cloud plan. The app ships as one edition with all features included: free for up to 10 users, then from **$1.25 per user/month** (annual billing) — the per-user price decreases as your team grows. See the Marketplace listing for the full tier table. ## Limitations & notes[​](#limitations--notes "Direct link to Limitations & notes") * Checklists are compressed before storage; very large lists (hundreds of items) still eventually reach Jira's per-issue property cap — the panel warns and pauses adding before that point; delete or shorten items to get back under it. * On team-managed projects the panel shows a warning — workflow enforcement is company-managed only. * Overdue is evaluated against **UTC midnight** everywhere (validator, JQL, reminders); the panel's date label is browser-local. * The daily reminder sweep caps at 500 issues per day; anything beyond waits for the next day's run. * Mentions typed in item text are stored but rendered as plain identifiers; the reminder comment is a real Jira mention with a real notification. * There is no board-card progress bar yet — Forge doesn't let issue-property apps render on cards. Was this helpful?👍 Yes👎 No --- # Component Hierarchy for Jira — User Guide ## Introduction[​](#introduction "Direct link to Introduction") Jira components are a flat list — fine for small projects, but a poor fit for layered systems where "Auth" needs to sit under "Platform", and "SSO" under "Auth". Component Hierarchy for Jira adds a **parent-child tree** to your project's components: platforms, modules, and submodules arranged the way your product actually works. Every node in the tree **is a real Jira component**, so boards, releases, and reports keep working exactly as before. On top of the tree you get: * A **project page** where anyone on the team can build and edit the tree. * A **cascading picker** on each issue that stores a full path such as `Platform/Auth/SSO`. * A **JQL function** — `inComponentHierarchy("Auth")` — that returns every issue in a node *and all of its descendants*. * **CSV import/export** for bulk setup, plus **automatic syncing** between tree nodes and Jira components. *** ## Requirements[​](#requirements "Direct link to Requirements") * **Jira Cloud.** The app runs natively in Jira and Jira Service Management. * **Installing** requires Jira administrator rights. **Using** the project page, the issue field, and JQL requires no special permissions. * One project = one tree. Trees are stored per project and don't affect other projects. *** ## Installation[​](#installation "Direct link to Installation") 1. Go to **Apps → Manage your apps** in Jira. 2. Click **Find new apps** and search for **Component Hierarchy for Jira**. 3. Click **Install**. The custom field *Component Hierarchy* is created automatically. 4. Open any project and find **Component Hierarchy** under the project sidebar's **Apps** section to build your first tree. *** ## How to find the app[​](#how-to-find-the-app "Direct link to How to find the app") | Entry point | Where | | ----------- | ----------------------------------------------------------------------------------------------- | | Tree editor | Project sidebar → **Apps** → **Component Hierarchy** | | Issue field | Issue view, create screen, transitions, and JSM portal requests — field **Component Hierarchy** | | JQL search | Issue navigator → `inComponentHierarchy("NodeName")` | *** ## Building the tree (project page)[​](#building-the-tree-project-page "Direct link to Building the tree (project page)") Open the project page: **project sidebar → Apps → Component Hierarchy**. ### Add nodes[​](#add-nodes "Direct link to Add nodes") 1. Type the first node's name where it says **New root node name** and confirm — this creates a root. 2. Hover any row and click **＋** to add a child under it, type the **Child node name**, and confirm. 3. Repeat as deep as you need. Multiple roots are supported — e.g. `Platform` and `Auth` side by side. ### Row actions[​](#row-actions "Direct link to Row actions") | Icon | Action | What it does | | ---- | --------- | ----------------------------------------------------------------------------------- | | ＋ | Add child | Creates a child node under this row | | ✎ | Edit | Renames the node, or maps it to a different Jira component | | ⇌ | Move | Picks a new parent from the **Move to** list (available once the tree has 2+ nodes) | | 🗑 | Remove | Deletes the node **and everything under it** | ### Saving[​](#saving "Direct link to Saving") You don't need to press save — every change is stored automatically a moment after you make it. Node names must be unique within the project (children of different parents may share a name — see [JQL](#searching-with-jql)). *** ## Tree nodes are real Jira components[​](#tree-nodes-are-real-jira-components "Direct link to Tree nodes are real Jira components") * Creating a node creates a **Jira component with the same name**. * Components that already exist are **adopted** when names match — nothing is duplicated. * If some nodes don't have a matching component yet (e.g. after a CSV import), a **Sync components** button appears at the bottom toolbar — click it to create the missing ones. * When someone sets the field on an issue, the components for every node on the selected chain are **added to that issue's Components automatically** (the app only ever adds, never removes). Reports and boards that filter by component keep working. *** ## Picking a path on an issue[​](#picking-a-path-on-an-issue "Direct link to Picking a path on an issue") The **Component Hierarchy** field is a cascading picker: level by level, from roots down to leaves. 1. Open an issue (or the create dialog, a transition screen, or a JSM portal request). 2. In the **Component Hierarchy** field, pick the first level — you'll only see nodes that can follow your previous choice. 3. Stop at any level; the field stores the full path, e.g. `Platform/Auth/SSO`. 4. Leave it empty if the issue isn't tied to a node. After a node is renamed, issues show the new name automatically — values are linked to the tree, not frozen text. *** ## Searching with JQL[​](#searching-with-jql "Direct link to Searching with JQL") Open the issue navigator and use: ``` inComponentHierarchy("Auth") ``` This returns every issue whose path is `Auth` **or starts with `Auth/`** — the whole branch, at any depth. Combine it with anything else JQL offers: ``` inComponentHierarchy("Auth") AND status != Done inComponentHierarchy("Platform") AND assignee = currentUser() not inComponentHierarchy("Deprecated") ``` ### Same name at two depths? Use the level argument[​](#same-name-at-two-depths-use-the-level-argument "Direct link to Same name at two depths? Use the level argument") If your tree has two nodes called `Auth` (say, one under `Platform` and one under `Mobile`), add the node's depth as the second argument — a root is level 1, its children level 2: ``` inComponentHierarchy("Auth", 2) // the Auth directly under a root inComponentHierarchy("Auth", 3) // an Auth one level deeper ``` Searches stay correct after edits: results are recalculated automatically whenever the tree changes, so a renamed or moved node doesn't leave stale results behind. *** ## CSV import and export[​](#csv-import-and-export "Direct link to CSV import and export") The bottom toolbar on the project page has everything for bulk setup: | Control | What it does | | -------------------------------- | ------------------------------------------------------------ | | **Download template** | Downloads a CSV with the format `Name,Parent` | | File picker | Imports a CSV — **this replaces the whole tree** | | **Export CSV** / **Export JSON** | Download the current tree (disabled while the tree is empty) | To import: download the template, fill one row per node, and import. A blank `Parent` means the row is a root; a `Parent` value must match a node defined in another row. Quoted names with commas are supported. Every imported node gets its matching Jira component created (use **Sync components** if any are still missing). *** ## Tips & common workflows[​](#tips--common-workflows "Direct link to Tips & common workflows") * **Service catalogs** — model each service as a node and let agents file portal requests against `Catalog/Billing/Refunds` style paths. * **Layered architectures** — `Platform` / `Auth` / `SSO` mirrors how ownership actually nests, then `inComponentHierarchy` replaces fragile `component in (...)` lists. * **Bulk migration** — export a mature tree as JSON, tweak it, and re-import into a template project. * **Board filters** — swap long component lists for one `inComponentHierarchy("Platform")` clause; the filter keeps working as the tree grows. *** ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") **The field doesn't appear on my issues** → A Jira admin needs to add the *Component Hierarchy* field to the relevant screens (**Settings → Issues → Screens**), or check the field's context covers your project. **`inComponentHierarchy` returns nothing** → Check the node name spelling (matching is case-insensitive but otherwise exact), and confirm at least one issue has the field set. Issues only appear once their field value sits on or under that node. **Two nodes share a name and my search matches both** → Add the level argument: `inComponentHierarchy("Auth", 2)` targets the one at a specific depth (roots are level 1). **A node has no Jira component** → Click **Sync components** on the project page. It creates components for any node that's missing one. **Someone deleted a component in Jira directly** → The node stays in the tree; click **Sync components** to recreate the component. **My CSV import looks wrong** → The file must be `Name,Parent` with one node per row, parents defined in their own rows, and blank parent for roots. Remember importing **replaces** the current tree — export first if you need a backup. Was this helpful?👍 Yes👎 No --- # How to use Content Craft for Confluence 1. type `/Content Craft for Confluence` in the Confluence editor 2. Click to select a SVG illustration on the gallery 3. You can use searchbox to filter by keywords, such as: child, women, man, and etc 4. You can use the category filter on the right 5. After you get your preferred SVG, click it to select then click Save button ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [Best Confluence apps for developers](/blog/best-confluence-apps-developers.md) Was this helpful?👍 Yes👎 No --- # Content Formatting Macros & Page Builder for Confluence — User Guide ## Installation[​](#installation "Direct link to Installation") 1. Install **Content Formatting Macros & Page Builder for Confluence** from the Atlassian Marketplace 2. Once installed, the macros are available in the Confluence macro browser 3. The app detects your license tier automatically — Standard (free for teams ≤10) or Advanced. No configuration needed. *** ## Quick Start[​](#quick-start "Direct link to Quick Start") 1. Edit any Confluence page 2. Type `/` followed by what you want — `/button`, `/gallery`, `/tabs`, etc. — to find a macro fast. Or type `/modern` to see all 23 macros from this app at once. 3. Select a macro, configure it, and click **Save** 4. A live preview updates in real time as you change settings *** ## Editions — Free vs Paid[​](#editions--free-vs-paid "Direct link to Editions — Free vs Paid") Content Formatting Macros & Page Builder for Confluence comes in two editions, unlocked automatically by your Marketplace license. ### Standard[​](#standard "Direct link to Standard") Includes 16 macros — all the formatting blocks, page-builder macros (hero, pricing table, tabs, countdown, FAQ, and more), plus all 5 theme presets. * **Free for teams of 10 or fewer users** * Paid for larger teams ### Advanced[​](#advanced "Direct link to Advanced") Everything in Standard, plus 7 premium macros — Card Grid (with carousel), Team Showcase, Image Gallery (masonry + lightbox), QR Code, Annotation, Article (with bilingual mode), and Form (with submissions dashboard). Also unlocks the Theme Editor with custom color, font, spacing, and shadow controls. * **Paid license** > **What happens when someone on a Standard license views an Advanced macro?** They see a friendly "Upgrade Required" message. The rest of the page renders normally. *** ## Theme Editor[​](#theme-editor "Direct link to Theme Editor") Access the theme editor from the app's global page in Confluence. It controls the visual identity of **all** MCFB macros on your site. > **Requires Advanced license.** On the Standard tier, the Theme Editor page shows an upgrade prompt. ### Theme Presets[​](#theme-presets "Direct link to Theme Presets") | Preset | Primary Color | Border Radius | Feel | | ------- | -------------------- | -------------- | ---------------------------- | | Default | Blue (#0052CC) | Rounded (8px) | Clean and professional | | Dark | Dark tones | Rounded | Sleek dark mode | | Minimal | Gray | Sharp (0px) | Ultra-clean, no distractions | | Bold | Red (#E11D48) | Rounded | Strong visual impact | | Pastel | Light blue (#0891B2) | Pill (rounded) | Soft and friendly | ### Custom Settings[​](#custom-settings "Direct link to Custom Settings") | Setting | Options | Description | | ------------------ | -------------------------------------- | ------------------------------------------------------------- | | Primary Color | Color picker + 6 preset swatches | Accent color used across all macros | | Dark Primary Color | Color picker (optional) | Separate accent for dark mode; falls back to Primary if unset | | Border Radius | Sharp / Rounded / Pill | Corner rounding for buttons, cards, panels | | Font Family | 15 bundled Google Fonts + system stack | Base font for all macro text — fonts lazy-load on first use | | Spacing Scale | Compact / Normal / Comfortable | Controls padding and margins globally | | Shadow Intensity | None / Subtle / Medium | Drop shadow depth on cards and panels | ### Dark / Light Mode[​](#dark--light-mode "Direct link to Dark / Light Mode") MCFB automatically detects your Confluence theme (light or dark) and adjusts all colors accordingly. No manual configuration needed. *** ## Macros[​](#macros "Direct link to Macros") ### Button `[Standard]`[​](#button-standard "Direct link to button-standard") A customizable call-to-action button with link support. | Setting | Options | Default | | ---------------- | -------------------------------------------- | ------------- | | Button Text | Free text (required) | "Click me" | | URL | Any URL | — | | Button Style | Primary / Secondary / Outline / Ghost / Link | Primary | | Size | Small / Medium / Large | Medium | | Alignment | Left / Center / Right | Left | | Background Color | Color picker | #0052CC | | Text Color | Color picker | #FFFFFF | | Border Radius | Custom (e.g., "8px") | Theme default | | Animation | None / Hover Lift / Pulse / Bounce / Glow | None | | Link Behavior | Same Window / New Window | Same Window | *** ### Button Group `[Standard]`[​](#button-group-standard "Direct link to button-group-standard") A row, column, or wrapping set of buttons — use it to group related actions (Submit/Cancel, pager Prev/Next, social links). **Layout**: | Setting | Options | Default | | ------------ | ----------------------------------------- | ------- | | Layout | Row / Column / Wrap | Row | | Size | Small / Medium / Large | Medium | | Alignment | Left / Center / Right | Left | | Spacing | Tight / Normal / Loose | Normal | | Button Width | Auto / Full | Auto | | Animation | None / Hover Lift / Pulse / Bounce / Glow | None | **Per Button** (up to 10): same settings as the standalone Button (text, URL, style, colors, radius). *** ### Status `[Standard]`[​](#status-standard "Direct link to status-standard") A colored status badge/label. | Setting | Options | Default | | ------------- | ----------------------- | ------- | | Label | Free text (required) | "To Do" | | Color | Color picker | #FF5630 | | Size | Small / Medium / Large | Medium | | Border Radius | Rounded / Pill / Square | Pill | *** ### Divider `[Standard]`[​](#divider-standard "Direct link to divider-standard") A visual separator with optional text or icon in the center. | Setting | Options | Default | | ---------- | ------------------------------------ | ---------- | | Type | Line / With Text / With Icon | Line | | Alignment | Left / Center / Right | Center | | Full Width | Toggle | On | | Width | 50–1200px slider | Full width | | Color | Color picker | #DFE1E6 | | Thickness | 1–10px slider | 1px | | Text | Free text (for "With Text") | — | | Icon | Emoji or character (for "With Icon") | — | | Icon Size | 14 / 18 / 24 / 32 / 42 / 64px | — | *** ### Title `[Standard]`[​](#title-standard "Direct link to title-standard") A styled heading with a full rich text editor. | Setting | Options | Default | | ------------------ | --------------------------- | ------------ | | Title Text | Rich text editor (required) | "Your Title" | | Heading Level | H1 / H2 / H3 / H4 | H2 | | Alignment | Left / Center / Right | Left | | Font Size | 12–72px slider | 24px | | Font Weight | 100–900 slider | 600 | | Color | Color picker | #172B4D | | Custom Line Height | Toggle + 1–3 slider | Off | *** ### Panel `[Standard]`[​](#panel-standard "Direct link to panel-standard") A colored callout panel with accent border. **Bodied** — drop rich text content inside via the Confluence editor. | Setting | Options | Default | | ---------------- | ------------------------------------------------ | ----------------- | | Style | Info / Warning / Success / Error / Note / Custom | Info | | Title | Free text | — | | Icon | Lucide icon picker (search by name) | Per-style default | | Border Position | Left Accent / Top Accent / Full Border | Left Accent | | Border Radius | 0–20px slider | 4px | | Border Color | Color picker (Custom style) | #0065FF | | Background Color | Color picker (Custom style) | #DEEBFF | | Text Color | Color picker (Custom style) | #172B4D | *** ### Expand `[Standard]`[​](#expand-standard "Direct link to expand-standard") A collapsible accordion with one or more sections. Drag to reorder sections, rich text per section. **Per Section** (no fixed limit): | Setting | Description | | -------------- | ------------------------------------------------------------------------------------ | | Title | Section heading (required) | | Icon | Emoji or character per section | | Content | Rich text editor — bold, italic, underline, headings, lists, links, blockquote, code | | Initially Open | Toggle — section starts expanded | **Layout & Behavior**: | Setting | Options | Default | | ------------------- | ------------------------------------------------- | ------------- | | Design Style | Simple / Bordered / Shadowed / Gradient / Minimal | Simple | | Animation | On / Off (smooth expand/collapse) | On | | Animation Speed | 100–1000ms slider | 300ms | | Chevron Position | Left / Right | Right | | Content Padding | 0–32px slider | 16px | | Accent Color | Color picker | Theme primary | | Allow Multiple Open | Toggle — off = accordion (only one section open) | Off | *** ### Progress `[Standard]`[​](#progress-standard "Direct link to progress-standard") One or more progress bars showing completion status. | Setting | Options | Default | | ------------ | ------------------------------ | ------- | | Style | Edged / Rounded / Circular | Rounded | | Size | Small / Medium / Large | Medium | | Height | 4–40px slider (overrides Size) | 12px | | Alignment | Left / Center / Right | Left | | Shadow | Toggle | Off | | Show Overall | Toggle (avg of all bars) | Off | **Per bar** (up to 5 bars): Title, Value (65), Max (100), Type (Percentage/Number), Primary Color, Secondary Color. *** ### Countdown `[Standard]`[​](#countdown-standard "Direct link to countdown-standard") A live countdown timer to a target date. | Setting | Options | Default | | ---------------------------------------------- | -------------------------------- | --------------- | | Target Date & Time | Date/time picker | 7 days from now | | Style | Box / Circle / Gauges | Box | | Size | Small / Medium / Large / X-Large | Medium | | Primary Color | Color picker | #0052CC | | Digit Animation | None / Slide / Fade | None | | Show Labels / Days / Hours / Minutes / Seconds | Toggles | On | *** ### Background `[Standard]`[​](#background-standard "Direct link to background-standard") A colored, gradient, or image background section that wraps rich text. Use it to break a page into visually distinct sections. | Setting | Options | Default | | ---------------- | --------------------------------- | ------------- | | Background Type | Color / Gradient / Image | Color | | Background Value | Color, gradient CSS, or image URL | Theme primary | | Overlay Color | Color picker (image backgrounds) | #000000 | | Overlay Opacity | 0–100% (image backgrounds) | 0% | | Min Height | Pixels | 200 | | Padding | Pixels | 24 | *** ### Tabs `[Standard]`[​](#tabs-standard "Direct link to tabs-standard") Organize content in switchable tabs with rich text support. **Per Tab** (up to 8 tabs): Title, Content Heading, Description, Tab Content (rich text), Image, Background Color, Image Fit/Position/Size, Overlay. **Layout Settings**: Tab Position (Top/Left/Right), Style (Line/Pills/Card), Preset (Simple/Card/Image Left/Image Top/Image Background), Alignment, Show Underline, Hover Effect (None/Lift/Scale). *** ### Hero Section `[Standard]`[​](#hero-section-standard "Direct link to hero-section-standard") A large banner area with title, subtitle, and call-to-action buttons. **Content**: Title (required), Subtitle, Title/Subtitle Alignment, Min Height (150–600px). **Background**: Type (Color/Gradient/Image), Color, Gradient CSS, Image, Overlay Opacity/Color. **CTA**: Primary/Secondary CTA Label and URL, CTA Style, Horizontal/Vertical Alignment. *** ### FAQ Section `[Standard]`[​](#faq-section-standard "Direct link to faq-section-standard") An accordion-style FAQ section with search, filtering, and SEO-friendly structured data. **Questions** (up to 20, drag to reorder): Question (required), Answer (rich text), Category, Initially Open. **Options**: Section Title, Style (Simple/Collapse/Centered/Bordered/Shadowed), Enable Search, Allow Multiple Open, Show Category Filter. **Features**: Search highlights matching text, Expand/Collapse All toggle, Schema.org FAQPage JSON-LD for SEO. *** ### Pricing Table `[Standard]`[​](#pricing-table-standard "Direct link to pricing-table-standard") A pricing plan comparison with highlighted tiers. **Per Plan** (up to 5): Name (required), Price, Period, Description, Features list, CTA Label, CTA URL, Highlight toggle. **Layout**: Columns (2/3/4), Highlight Color. Highlighted plans show a "Popular" badge. *** ### Numbered Headings `[Standard]`[​](#numbered-headings-standard "Direct link to numbered-headings-standard") Auto-numbers headings (H1–H6) using CSS counters — independent counter scope per macro. | Setting | Options | Default | | ------------------ | ---------------------------------------------------------------------- | ------- | | H1–H6 Scheme | Decimal / Upper Alpha / Lower Alpha / Upper Roman / Lower Roman / None | Decimal | | Separator | `.`, `-`, `/`, `_`, `(`, `)`, or any 1–4 char combo | `.` | | Trailing Separator | Show after last number (e.g. `1.1.`) | Off | **Templates**: 9 presets — Standard Decimal, Legal, Outline, Roman Formal, Alphabetic Index, MLA Classic, Parenthesized, Scientific, Modern Minimal. *** ### Table `[Standard]`[​](#table-standard "Direct link to table-standard") Styled tables with preset styles, zebra striping, colored headers, and first-column emphasis. | Setting | Options | Default | | --------------------------- | ------------------------------------- | ------------- | | Columns | 1–8, add/remove inline | 3 | | Rows | Up to 50, drag-to-reorder | 2 | | Style | Striped / Bordered / Minimal / Modern | Striped | | Header background | Any hex (optional override) | Theme default | | First column as row headers | On / Off | Off | **Templates**: 4 presets — Comparison Matrix, Spec Sheet, Data Table, Schedule. *** ### Card Grid `[Advanced]`[​](#card-grid-advanced "Direct link to card-grid-advanced") A responsive grid of content cards with optional images and CTAs. | Setting | Options | Default | | -------------- | --------------------------- | ------- | | Columns | 1 / 2 / 3 / 4 | 3 | | Card Style | Basic / Outlined / Elevated | Basic | | Image Position | Top / Left | Top | **Per Card** (up to 12): Title, Description, Image URL, CTA Label, CTA URL. *** ### Team Showcase `[Advanced]`[​](#team-showcase-advanced "Direct link to team-showcase-advanced") A grid of team-member cards — avatar, name, role, bio, social links. | Setting | Options | Default | | ------------ | ------------------------------------------- | -------- | | Columns | 1 / 2 / 3 / 4 | 3 | | Card Style | Basic / Outlined / Elevated | Outlined | | Avatar Shape | Circle / Rounded / Square | Circle | | Avatar Size | Small (48px) / Medium (72px) / Large (96px) | Medium | | Alignment | Left / Center | Center | Each member supports name, avatar (or auto-colored initials), rich-text bio, department, location, email, social links. Up to 20 members per macro. *** ### Image Gallery `[Advanced]`[​](#image-gallery-advanced "Direct link to image-gallery-advanced") A photo gallery with grid or masonry layouts, hover effects, and a built-in lightbox. | Setting | Options | Default | | ------------ | --------------------------- | ------- | | Layout | Grid / Masonry | Grid | | Columns | 1 / 2 / 3 / 4 | 3 | | Hover effect | None / Zoom / Lift / Darken | None | | Lightbox | On / Off | On | All images stored as base64 — no external URLs (Runs on Atlassian compliant). True browser fullscreen via Fullscreen API. Up to 30 images per macro. *** ### QR Code `[Advanced]`[​](#qr-code-advanced "Direct link to qr-code-advanced") A scannable QR code generator with 7 content types and optional logo overlay. | Setting | Options | Default | | ---------------- | ----------------------------------------------- | ------- | | Content type | URL / Text / Email / Phone / SMS / WiFi / vCard | URL | | Size | 128–512px | 256px | | Error correction | L / M / Q / H | Q | | Logo overlay | Optional upload | None | 100% client-side generation — no network calls. When logo overlay is present, ECC auto-locks to H (30% recovery). *** ### Annotation `[Advanced]`[​](#annotation-advanced "Direct link to annotation-advanced") Inline annotations for terms, definitions, and callouts — rendered by @forge/react (UI Kit) with native Tooltip component. | Setting | Options | Default | | -------------- | ----------------------------------------------------- | ------- | | Term (trigger) | Any inline text | — | | Body | Plain text on hover | — | | Term style | Plain / Bold / Italic / Underline / Highlight / Badge | Plain | | Position | Top / Bottom / Left / Right / Auto / Follow mouse | Top | | Delay | 0–1500ms | 300ms | **Templates**: 6 presets — Acronym, Definition, Hint, Citation, Highlight, Badge. *** ### Article `[Advanced]`[​](#article-advanced "Direct link to article-advanced") A long-form reading macro with drop caps, typography templates, and bilingual mode. | Setting | Options | Default | | -------------- | -------------------------------------------------- | ------------ | | Template | Medium / Quora / Substack / NYT / GitHub / Minimal | Medium | | Font family | 15 bundled open-source families | Per template | | Drop cap | On / Off | Per template | | Bilingual mode | On / Off | Off | **Bilingual mode**: pairs a Native rich-text editor with a Translation editor per paragraph. *** ### Form `[Advanced]`[​](#form-advanced "Direct link to form-advanced") Collect survey responses, feedback, RSVPs — the only macro with server-side persistence. | Setting | Options | Default | | ------------------ | ---------------------------------------------------------------------------------- | ------------- | | Form title | Any string | Untitled form | | Field types | Short text / Long text / Dropdown / Checkboxes / Star rating / Email / Date picker | Short text | | Submit button text | Any string | Submit | **Where submissions go**: Form Submissions space page (apps menu in your space). Space admins only. Export CSV, delete rows inline. *** ## Form Submissions (Space Admin Page)[​](#form-submissions-space-admin-page "Direct link to Form Submissions (Space Admin Page)") A dedicated space page for viewing collected form submissions. > **Requires Advanced license.** On the Standard tier, the Form Submissions page shows an upgrade prompt. **Layout:** two-pane. Left lists every form with submission count badge. Right shows a sortable table. **Actions:** Export CSV, Delete per-row with confirmation, Refresh. *** ## Tips[​](#tips "Direct link to Tips") * **Live Preview**: Every macro config panel shows a real-time preview on the right side * **Templates**: Every macro opens with a "Start from a template" link — 76+ built-in presets * **Upgrade for more**: Standard includes 16 macros (free for teams ≤10). Advanced unlocks 7 premium macros + Theme Editor * **Theme Consistency**: Set brand colors once in the Theme Editor — all macros inherit * **Dark Mode**: All macros automatically adapt to Confluence's dark/light theme *** ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * (Coming soon) ## Related Apps[​](#related-apps "Direct link to Related Apps") Content Formatting Macros & Page Builder for Confluence works great alongside other NGPILOT apps. Here are apps that complement specific features: * [Modern Code Blocks for Confluence](/docs/Modern-Code-Blocks-for-Confluence/user-docs.md) — Syntax-highlighted code blocks with Monaco editor, 85+ languages, diff view * [Modern FAQ for Confluence](/docs/Modern-FAQ-for-Confluence/usage.md) — Dedicated FAQ accordion sections with search * [Modern Numbered Headings for Confluence](/docs/Modern-Numbered-Headings-for-Confluence/user-docs.md) — Auto-number H1–H6 headings with 9 presets * [QRCode for Confluence](/docs/QRCode-for-Confluence/usage.md) — Standalone QR code macro * [Google Fonts for Confluence](/docs/Google-Fonts-for-Confluence/usage.md) — 1942+ Google Fonts as a macro * [Enhanced Markdown for Confluence](/docs/Enhanced-Markdown-for-Confluence/usage.md) — WYSIWYG Markdown editing with charts and UML * [Excalidraw plus for Confluence](/docs/Excalidraw-plus-for-Confluence/usage.md) — Freeform whiteboard drawings and diagrams * [Mermaid Plus Diagrams & AI Agent for Confluence](/docs/Mermaid-Plus-for-Confluence/usage.md) — 30 diagram types with live preview ### Cited by[​](#cited-by "Direct link to Cited by") Content Formatting Macros & Page Builder for Confluence is referenced in the following guides: * [Enhanced Markdown for Confluence](/docs/Enhanced-Markdown-for-Confluence/usage.md) — Enhanced Markdown includes a live HTML preview that can render Content Formatting Macros & Page Builder macros for testing * [Modern FAQ for Confluence](/docs/Modern-FAQ-for-Confluence/usage.md) — The FAQ macro in Content Formatting Macros & Page Builder was inspired by Modern FAQ's design ## Support[​](#support "Direct link to Support") For issues or feature requests, please visit the app's listing on the Atlassian Marketplace. Was this helpful?👍 Yes👎 No --- # Usage ## Insert and edit Excalidraw diagrams[​](#insert-and-edit-excalidraw-diagrams "Direct link to Insert and edit Excalidraw diagrams") 1. Type "/excalidraw" and select the macro to insert ![Inserting Excalidraw macro via slash command](/assets/images/1-8fdb0b3a4787f31a31c9beb2c5ad81ba.png) 2. Excalidraw editor ![Excalidraw editor canvas](/assets/images/2-7875de86e75ef2c6611f30c8d8a444a0.png) ## Insert and edit Mermaid diagrams[​](#insert-and-edit-mermaid-diagrams "Direct link to Insert and edit Mermaid diagrams") 1. Type "/mermaid" and select the macro to insert ![Inserting Mermaid macro via slash command](/assets/images/3-4e1e07b34a2b6e332fc507bdad0585ed.png) 2. Mermaid Live editor ![Mermaid live editor with code and preview](/assets/images/4-4eb6a041fe31f9f13e458475a9a50b62.png) ## Click "Save" button to save the macro[​](#click-save-button-to-save-the-macro "Direct link to Click \"Save\" button to save the macro") ![Saving the diagram macro](/assets/images/5-724d9b7cdd2a0874b05a194792ee6191.png) ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [How to create architecture diagrams in Confluence](/blog/how-to-create-architecture-diagrams-confluence.md) * [How to create flowcharts in Confluence](/blog/create-flowcharts-confluence.md) * [Confluence diagram tools comparison](/blog/confluence-diagram-tools-comparison.md) Was this helpful?👍 Yes👎 No --- # Linking and Navigation inside the Markdown Macro A long page inside an Enhanced Markdown macro needs a way in: a contents list at the top, a "back to top" link, or a cross-reference from one section to another. This page explains how in-page links work inside the macro, how to build a table of contents, and the few heading shapes that need extra care. Version In-page anchor navigation was improved in **v1.4.1** (2026-10-10). If a link below does nothing on your page, update the macro to the latest version and save it once. *** ## The Short Version[​](#the-short-version "Direct link to The Short Version") Link to a heading with a plain `#` anchor, using the heading text lowercased with spaces replaced by hyphens: ``` Jump to [Getting Started](#getting-started) ``` Clicking it scrolls the page so that heading sits just below Confluence's sticky toolbar. No page reload, and the browser back button still works. Three rules cover most cases: 1. **The anchor is the heading text, lowercased, spaces to hyphens.** `#Getting Started` does not work — write `#getting-started`. 2. **Targets must be headings in the same macro.** A link cannot jump to a heading in normal page content, a different macro, or another page. 3. **Punctuation is dropped, not turned into hyphens.** `## API v2.0 (Beta)` becomes `#api-v20-beta` — see [Punctuation disappears](#punctuation-disappears-why-some-anchors-look-wrong). *** ## How Heading Anchors Are Generated[​](#how-heading-anchors-are-generated "Direct link to How Heading Anchors Are Generated") The macro reads each heading's text and derives its anchor automatically — you never write anchor ids by hand. Understanding the exact rule is what makes the awkward cases predictable. The rule runs in four steps: 1. Take the heading's visible text, with inline formatting markers removed 2. Lowercase it 3. Remove every character that is not a letter, digit, whitespace, or hyphen 4. Collapse each run of whitespace into a single hyphen Note that step 3 is **Unicode-aware**. Letters and digits from any script survive — CJK, Cyrillic, accented Latin, and so on all work as anchors. This is why a heading written in Chinese produces a usable anchor rather than an empty one: | Heading in the source | Anchor to link to | | --------------------- | ----------------- | | `## 系统要求` | `#系统要求` | | `## Configuration` | `#configuration` | | `## Ünïcödé Tëst` | `#ünïcödé-tëst` | If a heading contains nothing but punctuation, it falls back to the anchor `section`. Give such headings real words instead. *** ## Worked Examples[​](#worked-examples "Direct link to Worked Examples") ### A table of contents[​](#a-table-of-contents "Direct link to A table of contents") The most common reason to link is a contents list. Write it as an ordinary list of links near the top of the macro, and anchor each item to the heading below it: ``` ## Contents - [Overview](#overview) - [Installing the client](#installing-the-client) - [Configuring the server](#configuring-the-server) - [Troubleshooting](#troubleshooting) ## Overview ... ## Installing the client ... ## Configuring the server ... ## Troubleshooting ... ``` Each list item is just a normal Markdown link. Keep the link text identical to the heading so the two stay easy to keep in sync as the document grows. ### Back-to-top links[​](#back-to-top-links "Direct link to Back-to-top links") The same mechanism in reverse. Add an inline link wherever a reader might want to return to the contents: ``` ## Configuring the server ...long section... [↑ Back to contents](#contents) ``` For this to work, the contents heading itself must exist — `## Contents` gives you `#contents`. Anchoring to a heading you have not written is the most common cause of a link that silently does nothing. ### Cross-referencing another section[​](#cross-referencing-another-section "Direct link to Cross-referencing another section") Link the readable way, using the section's own heading text: ``` If authentication fails, see [Configuring the server](#configuring-the-server). ``` Prefer this over an invented anchor name like `#server-config`. If you later rename the heading, a link written from the heading text is the one a reader can still reason about, and it fails loudly in review rather than silently at click time. *** ## Punctuation Disappears (Why Some Anchors Look Wrong)[​](#punctuation-disappears-why-some-anchors-look-wrong "Direct link to Punctuation Disappears (Why Some Anchors Look Wrong)") Because step 3 removes punctuation instead of converting it, some anchors are not what you would guess. These are the shapes that catch people out: | Heading | Anchor | Note | | ---------------------- | ------------------ | --------------------------------------------- | | `## Getting Started` | `#getting-started` | The normal case | | `## Getting Started!` | `#getting-started` | Trailing `!` dropped | | `## What's New?` | `#whats-new` | Apostrophe dropped, no hyphen | | `## Step 1: Install` | `#step-1-install` | Colon dropped, space becomes the hyphen | | `## API v2.0 (Beta)` | `#api-v20-beta` | The `.` vanishes — it is `v20`, not `v2-0` | | `## Deploy & Rollback` | `#deploy-rollback` | Standalone `&` joins the words with no hyphen | | `## config.yaml` | `#configyaml` | Dots dropped, so `yaml` runs into `config` | The reliable habit is to **derive the anchor from the heading text mechanically** — lowercase it and put hyphens where the spaces were — rather than guessing. For a heading with awkward punctuation, check the link once in the rendered page before you rely on it. If you want anchors that survive punctuation exactly, simplify the heading text. `## API v2.0 (Beta)` and `## API v2 Beta` are both fine; the second gives a predictable `#api-v2-beta`. *** ## Duplicate Headings[​](#duplicate-headings "Direct link to Duplicate Headings") Two headings with the same text cannot share an anchor. The macro keeps them distinct by appending a counter, in document order: ``` ## Notes ...first... ## Notes ...second... ``` The first is `#notes` and the second is `#notes-1`. A third would be `#notes-2`. This makes duplicate headings safe but unpredictable to link to — a reader cannot tell which "Notes" they will land on, and inserting a section above silently renumbers them. Where possible, give repeated sections distinct headings (`## Notes for macOS`, `## Notes for Windows`) and link each one directly. *** ## Limits Worth Knowing[​](#limits-worth-knowing "Direct link to Limits Worth Knowing") **Anchors reach headings inside the same macro only.** The macro renders inside its own frame, so its list of anchors covers only the headings it rendered. An anchor pointing at a heading in normal page content, in a second Markdown macro, or in a table elsewhere on the page will not resolve. If you need to reference something outside the macro, link to the page rather than the heading, or move that content inside the macro. **Cross-page links open in a new tab.** A link to another Confluence page opens in its own tab, controlled by Confluence. This is deliberate: it prevents a link in a rendered document from silently navigating a reader away from a page they may have been reading for a while. **Anchors are assigned on save, not on the host page.** The anchors belong to the macro's rendered output, so the set is determined by the macro's own headings. Editing the surrounding page does not change them. *** ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") **A link does nothing when clicked.** Check, in order: 1. **Does the target heading exist in the same macro?** This is the most common cause. An anchor with no matching heading is simply ignored. 2. **Is the anchor lowercased?** Headings render with capital letters, but anchors are matched in lowercase. `[X](#Getting-Started)` fails; `[X](#getting-started)` works. 3. **Is the anchor derived from the heading text?** Re-derive it: lowercase the heading, spaces to hyphens, punctuation removed. If the heading contains punctuation, verify against the table above. 4. **Is the macro on v1.4.1 or later?** Older versions did not assign anchors at all. Update and save the macro once. **The jump lands on the wrong section.** Almost always a duplicate heading. Check for repeated headings — the second one is `#notes-1`, not `#notes`. Rename them to tell them apart. **The heading is hidden behind the toolbar.** It should not be — the macro offsets the scroll so the target clears Confluence's sticky toolbar. If it is still obscured on your page, confirm the macro is fully rendered (scroll through it once) and try again. **An anchor works in the editor preview but not on the page.** Save the macro. Anchors are assigned when the content is rendered and saved, so an unsaved edit will not have them yet. *** ## Related[​](#related "Direct link to Related") * [Enhanced Markdown for Confluence — User Guide](/docs/Enhanced-Markdown-for-Confluence/usage.md) * [Modern Numbered Headings for Confluence](/docs/Modern-Numbered-Headings-for-Confluence/user-docs.md) — numbered headings and outline navigation for content built with Confluence's own editor, useful when a page mixes both kinds of content ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [Markdown Editor for Confluence — Which App Should You Choose?](/blog/confluence-markdown-editor-comparison.md) * [Confluence Markdown vs WYSIWYG: Which Should You Use?](/blog/faq-confluence-markdown-vs-wysiwyg.md) ## Support[​](#support "Direct link to Support") For issues or feature requests, please visit the app's listing on the Atlassian Marketplace. Was this helpful?👍 Yes👎 No --- # Enhanced Markdown for Confluence — User Guide ## Overview[​](#overview "Direct link to Overview") Enhanced Markdown for Confluence brings a fast, lightweight Markdown editor to your Confluence pages. Write in Markdown with a live split preview, syntax-highlighted code blocks, Mermaid and ZenUML diagrams, KaTeX and MathJax math, GitHub-flavored tables, and bidirectional scroll sync between source and preview. The editor runs on the [Quikdown](https://github.com/deftio/quikdown) engine — small bundle, no cluttered toolbar, all rendering libraries bundled locally so it works reliably inside Confluence without external CDN dependencies. ## In This Guide[​](#in-this-guide "Direct link to In This Guide") * [Linking and Navigation inside the Markdown Macro](/docs/Enhanced-Markdown-for-Confluence/navigation.md) — build a table of contents, link between sections, and get in-page anchors right. Start here if links in your macro do nothing when clicked. ## Getting Started[​](#getting-started "Direct link to Getting Started") ### Inserting a Markdown Block[​](#inserting-a-markdown-block "Direct link to Inserting a Markdown Block") 1. Edit a Confluence page 2. Type `/enhanced markdown` in the editor and select **Enhanced Markdown for Confluence** 3. The editor opens where you can compose your Markdown content 4. Write, paste, or upload a `.md` file 5. Click **Save** to render it on the page ### Re-editing[​](#re-editing "Direct link to Re-editing") Click on an existing Enhanced Markdown macro and select **Edit** to reopen the editor. Your Markdown source is preserved across edits — content is stored compressed, and existing macros continue to render without migration. *** ## Features[​](#features "Direct link to Features") ### Three View Modes[​](#three-view-modes "Direct link to Three View Modes") Pick a mode from the header to match how you want to work: * **Source** — full-width Markdown editing * **Split** — source on the left, rendered preview on the right (default) * **Preview** — full-width rendered preview, no editing chrome Your choice is saved per macro — reopen the editor and the same mode comes back. ### Live Preview with Scroll Sync[​](#live-preview-with-scroll-sync "Direct link to Live Preview with Scroll Sync") In **Split** mode, scrolling one pane moves the other proportionally. Scroll the source and the preview follows; scroll the preview and the source follows. Sync is bidirectional and avoids feedback loops, so long documents stay easy to navigate. Sync is proportional rather than line-accurate: the two panes are mapped by relative scroll position, not by matching headings. If your source and preview differ a lot in height — a long code block, a tall diagram, a wide table — the panes can drift out of alignment. Keeping headings roughly aligned between the two keeps them in step. ### Code Syntax Highlighting[​](#code-syntax-highlighting "Direct link to Code Syntax Highlighting") Fenced code blocks are highlighted automatically across 190+ languages via highlight.js, with GitHub light and dark themes that match Confluence's color scheme. ```` ```python def greet(name): return f"Hello, {name}!" ``` ```` ```` ```bash pnpm install && forge deploy ```` ````` ### Mermaid Diagrams Render flowcharts, sequence diagrams, Gantt charts, class diagrams, state diagrams, ER diagrams, pie charts, journey maps, UML use case diagrams, and more — powered by Mermaid 12. ````md ```mermaid graph LR A[Write] -->|preview| B[Review] B --> C{Looks good?} C -->|yes| D[Publish] C -->|no| A ````` ````` Diagrams render as centered SVG inline in the page and update live as you edit. #### UML Use Case Diagrams (new in Mermaid 12) Mermaid 12 adds UML use case diagrams via the `usecase-beta` fence keyword. Actors, system boundaries, `include`/`extend` relationships, and notes are all supported: ````md ```mermaid usecase-beta direction LR actor Customer actor Admin systemBoundary Store("Online Store") UC1("Browse Products") UC2("Checkout") end Customer --> UC1 Customer --> UC2 Admin --> UC2 UC2 ..> : include UC1 Admin --|> Customer note for UC1 "Available 24/7" ``` ````` ![UML use case diagram rendered by Mermaid 12 — Customer and Admin actors connected to Browse Products and Checkout use cases inside an Online Store system boundary, with an include relationship and an Available 24/7 note.](/assets/images/usecase-beta-c9ff8176b24fa75a45716b55ec6ade04.png) Mermaid 12 also refreshes the default look of flowchart, state, and class diagrams (new layout engine and color palettes). Existing diagrams keep working — they may simply lay out slightly differently than before. ### ZenUML Sequence Diagrams[​](#zenuml-sequence-diagrams "Direct link to ZenUML Sequence Diagrams") Use ZenUML's modern `Actor->Message` syntax for sequence diagrams. ```` ```zenuml participant User participant Editor User->Editor: type markdown Editor-->User: live preview ``` ```` ZenUML fences render directly, including conditionals (`if/else`), loops (`while`), parallel blocks (`par`), and `try/catch`. Like all diagrams, they are centered in the preview. ### Math — KaTeX and MathJax[​](#math--katex-and-mathjax "Direct link to Math — KaTeX and MathJax") Render math three ways: * **KaTeX fences** for fast CSS-based rendering: ```` ```katex E = mc^2 ``` ```` * **MathJax fences** (`math`, `tex`, or `latex`) for full LaTeX including `\begin{align}` and AMS packages: ```` ```math \begin{align} \nabla \times \vec{B} &= \mu_0 \vec{J} \end{align} ``` ```` * **Inline math** with `$...$` and display math with `$$...$$`, typeset in both source and preview: ``` Euler's identity $e^{i\pi} + 1 = 0$ appears mid-sentence. ``` MathJax is bundled locally — no CDN egress required by the macro. ### GitHub-Flavored Tables[​](#github-flavored-tables "Direct link to GitHub-Flavored Tables") Standard pipe tables render with column alignment: ``` | Feature | Status | | ------------- | :----: | | Split editor | ✅ | | Scroll sync | ✅ | ``` ### Upload a Markdown File[​](#upload-a-markdown-file "Direct link to Upload a Markdown File") Click **Upload MD** in the header to import an existing `.md` or `.markdown` file directly into the editor. Useful for migrating notes from another system or pasting in a doc that lives outside Confluence. ### Dark Mode[​](#dark-mode "Direct link to Dark Mode") The editor and rendered output follow Confluence's theme automatically — code highlighting, diagrams, and math all switch palettes with the host page. No toggle needed. ### Smart Links[​](#smart-links "Direct link to Smart Links") Links inside the macro behave the way you'd expect: * **In-page anchors** (`#section`) scroll within the macro instead of navigating away * **Path-rooted links** (`/wiki/download/...`) open correctly through Confluence rather than 404'ing inside the iframe * **External links** open in a host-controlled tab Every heading in the macro gets an anchor derived from its text, so you can build a table of contents or cross-reference sections with ordinary Markdown links: ``` ## Contents - [Installing the client](#installing-the-client) - [Configuring the server](#configuring-the-server) ## Installing the client ... ``` Headings with punctuation need care — `## API v2.0 (Beta)` is anchored as `#api-v20-beta`, not `#api-v2.0-(beta)`. For the full anchor rules and troubleshooting, see [Linking and Navigation inside the Markdown Macro](/docs/Enhanced-Markdown-for-Confluence/navigation.md). *** ## Tips[​](#tips "Direct link to Tips") * Use **Split** mode while drafting to catch rendering issues early, then switch to **Preview** for a final read * Keep one diagram per fence — multiple Mermaid blocks work, but a single block per diagram keeps source diffs clean * For long documents, scroll sync is most useful when source and preview have similar structure (headings roughly aligned) * Upload MD is the fastest way to migrate an existing Markdown doc into Confluence * Existing macros from earlier versions continue to render unchanged — no migration step required *** ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [Markdown Editor for Confluence — Which App Should You Choose?](/blog/confluence-markdown-editor-comparison.md) * [Confluence Markdown vs WYSIWYG: Which Should You Use?](/blog/faq-confluence-markdown-vs-wysiwyg.md) ## Support[​](#support "Direct link to Support") For issues or feature requests, please visit the app's listing on the Atlassian Marketplace. Was this helpful?👍 Yes👎 No --- # User Guide This guide will walk you through the features and usage of the EPUB Reader for Confluence app. This app allows you to embed and read EPUB files directly within your Confluence pages. ## Installation[​](#installation "Direct link to Installation") The EPUB Reader for Confluence must be installed by your Confluence administrator from the Atlassian Marketplace. Once installed, it will be available as a macro on any Confluence page. ## How to Use[​](#how-to-use "Direct link to How to Use") ### 1. Add the Macro to a Page[​](#1-add-the-macro-to-a-page "Direct link to 1. Add the Macro to a Page") 1. While editing a Confluence page, type `/epub` or click the `+` button in the editor toolbar and search for "EPUB Reader for Confluence". 2. Select the macro to add it to your page. This will open the configuration panel. ### 2. Configure the Macro[​](#2-configure-the-macro "Direct link to 2. Configure the Macro") The configuration panel allows you to select which EPUB file to display. * **Select an Existing EPUB:** If you have already attached EPUB files to your Confluence page, they will be listed here. Click on a file to select it. * **Upload a New EPUB:** If you need to add a new file, click the **Upload EPUB File** button to upload it directly from your computer. The new file will be automatically selected. * **Set a Custom Title (Optional):** You can provide a custom title for the reader. If you leave this field blank, the EPUB's filename will be used as the title. ![EPUB configuration panel for selecting files and setting title](/assets/images/config-a68ef81278e628e4040ee4a0fc47a874.png) Once you have selected a file, click **Save** to add the macro to your page. ### 3. View the EPUB on the Page[​](#3-view-the-epub-on-the-page "Direct link to 3. View the EPUB on the Page") After saving, the macro will appear on your Confluence page as a card displaying the EPUB's title and a **Read** button. ![EPUB macro displayed as a card with Read button](/assets/images/macro-329fa2f675ecd151a9ec7ab6443cea98.png) ### 4. Read the EPUB[​](#4-read-the-epub "Direct link to 4. Read the EPUB") Click the **Read** button to open the EPUB reader in a full-screen view. ![Full-screen EPUB reader with navigation toolbar](/assets/images/reading-0e47a9e664bad7d413d7b693f041f348.png) The reader interface includes: * **Top Toolbar:** * **Menu Icon:** Opens the table of contents, allowing you to jump to any chapter. * **Settings Icon:** Opens the reading settings, where you can switch between **Light** and **Dark** themes and adjust the **Font Size**. * **X Icon:** Closes the reader and returns you to the Confluence page. * **Navigation:** * Use the **<** and **>** arrow buttons on the sides of the screen to navigate between pages. * You can also use the `Left Arrow` and `Right Arrow` keys on your keyboard. * **Bottom Toolbar:** * Displays your reading progress as a percentage. * A visual progress bar. * **Previous** and **Next** buttons for page navigation. ## Features[​](#features "Direct link to Features") * Embed EPUB files directly into Confluence pages. * Upload and manage EPUB attachments from the macro configuration. * A clean, intuitive reader interface. * Customizable reading experience with light/dark themes and adjustable font sizes. * Table of contents for easy navigation. * Reading progress is saved, so you can pick up where ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [Best Confluence apps for developers](/blog/best-confluence-apps-developers.md) * [Confluence page navigation FAQ](/blog/faq-confluence-page-navigation-apps.md) Was this helpful?👍 Yes👎 No --- # EULA ## Preamble[​](#preamble "Direct link to Preamble") NGPILOT (hereinafter referred to as "Vendor") is the software vendor for Confluence and other products and services on the Atlassian Marketplace (hereinafter referred to as the "Software") and independently develops the Software for sale on the Atlassian Marketplace. Vendor's Software is available only from the Atlassian Marketplace at market.atlassian.com and Vendor has the right to grant sublicenses for use of the Software through the Atlassian Marketplace. The following terms apply to the contractual relationship between Vendor and the sublicensee (hereinafter referred to as "Buyer") for use of the Software on the Atlassian Marketplace (hereinafter referred to as the "License"). This agreement (hereinafter referred to as the "Agreement") sets out the license terms for the Software and the terms under which Buyer may use it. The term "Buyer" also includes its employees, agents, affiliates and subcontractors. The terms of this Agreement apply when Buyer first downloads, installs or uses the Software, whichever occurs first. Buyer requires a current valid license key or active subscription to use and continue to use the Products. If Buyer does not agree to the terms of this Agreement, Buyer may not download, install or use the Software or any services related thereto. The Software is protected by international copyright laws. The right to use the Software is subject to this Agreement and the Atlassian Cloud Service Terms. Any conflicting, deviating or additional terms proposed by Buyer shall not become part of this Agreement unless Supplier expressly agrees to their validity in writing. This preamble and the terms contained therein are also part of this Agreement. ## 1. Purpose[​](#1-purpose "Direct link to 1. Purpose") 1.1 This Agreement grants the right to use the Software and obtain Maintenance Services. An overview of the current Software offered by Supplier on the Atlassian Marketplace can be found in the Software Listing on the Atlassian Marketplace (hereinafter referred to as the "Document"). 1.2 The Services related to the Software are primarily provided within the Atlassian Cloud environment (hereinafter referred to as the "Atlassian Cloud"). Neither Licensor nor Supplier has direct access to Buyer's data, except for a short period of time to provide Cloud Services. This includes content creation, editing and storage and all other data generated by Buyer using the Software in the Atlassian Cloud (hereinafter referred to as the "Application Data"). The Hosting Services are provided by Licensor (hereinafter referred to as the "Hosting Provider"). Most provisions here regarding the availability of the Services refer to the Hosting Provider. Supplier has no influence on the Atlassian Cloud. Please refer to the Atlassian Cloud Service Terms for Core Features. 1.3 This Agreement covers the latest version of the Software, from the beginning of the Agreement until the end of the Agreement (see Section 3). 1.4 Other services, including but not limited to installation, guidance, training, customization or any other services for the Software, are not part of this Agreement. If Supplier provides such services, they shall be agreed separately in writing. ## 2. Right to Use, Multiple Use and Network Use[​](#2-right-to-use-multiple-use-and-network-use "Direct link to 2. Right to Use, Multiple Use and Network Use") 2.1 The Supplier grants the Buyer a non-exclusive, non-transferable sublicense to a) use the Software; and b) use the Cloud Services, obtained from approved sources, for the direct benefit of the Supplier during the term of this Agreement and in accordance with the license specifically obtained by the Buyer (see Section 3) and as provided in this EULA (collectively, the “Right to Use”). “Cloud Services” means the hosting of the Software or parts thereof by a hosting service provider as a software-as-a-service to the Buyer. 2.2 These Rights to Use may only be exercised by the maximum number of Users for which the Buyer has licenses for the Atlassian core software (e.g. Confluence and/or Jira). In this case, the Trello upgrade is completely free of charge. 2.3 It is prohibited to provide the Software to more Users than the number agreed in the contract. If the number of Users exceeds the number agreed in the contract, a plan with a higher number of Users must be purchased. The Buyer agrees to pay the difference via a new transaction (upgrade) in the Atlassian Marketplace. 2.4 The Supplier shall ensure that the Hosting Service Provider keeps the Cloud Services available to central data processing systems that are not part of the Atlassian Cloud (see § 1.2) (hereinafter referred to as the “Server”). 2.5 All application data remain on the Atlassian Cloud. The Software is a JavaScript program that runs in the User’s web browser. Therefore, the Supplier and all its partners and subcontractors cannot access static application data at any time. 2.6 Unaffected. 2.6 When the Cloud Services are executed and the Supplier needs to temporarily process the application data, the Supplier shall ensure that the Hosting Service Provider has available processing capacity. The Software will be provided in accordance with Atlassian availability standards. 2.7 In most cases, the interconnection point for the Software and the Application Data is the User’s web browser. For very rare server-side activities, it is the exit router in the Licensor’s data center. The Supplier assumes no liability for the quality of the necessary hardware and software used by the Buyer and the telecommunication connection between the Buyer and the Supplier up to the interconnection point. In particular for the browser software, the Supplier requires the Buyer to use the latest versions of the mainstream Internet browsers and at least the web browsers required for the Atlassian core products. ## 3. Term[​](#3-term "Direct link to 3. Term") The Buyer may select the term of the Agreement according to the options available on the Atlassian Marketplace. Unless either party terminates the Agreement at the end of the term (the "Term"), the Term will automatically extend to the term initially selected. The rights of the parties to terminate the Agreement for good cause remain unaffected. The Agreement may be terminated by clicking the corresponding button "Cancel Subscription" for this Software in the Basic Software Management. Initially, the Buyer is entitled to test the Software free of charge for 30 days (subject to change by Atlassian). During this period, the Supplier is not obliged to provide any support or maintenance services. During this period, the Supplier assumes no liability, to the extent permitted by law. ## 4. Resale, Transfer or Sublicense[​](#4-resale-transfer-or-sublicense "Direct link to 4. Resale, Transfer or Sublicense") The Buyer may not transfer, sell, rent, lease, sublicense, relicense or assign the Software in any way. In particular, the Buyer is not entitled to transfer access to the Software to third parties other than as provided for in the Atlassian Marketplace Terms. The Buyer shall take the necessary precautions to ensure that the Software and/or Application Data cannot be accessed by unauthorized third parties. ## 5. Open Source Software[​](#5-open-source-software "Direct link to 5. Open Source Software") If Open Source Software is used in Supplier’s products, it will not materially or adversely affect Buyer’s ability to exercise its rights to use the Software. ## 6. Cloud Services[​](#6-cloud-services "Direct link to 6. Cloud Services") Buyer shall not intentionally (a) interfere with other customers’ access to or use of the Cloud Services, or interfere with their security; (b) facilitate attacks on or disruption of the Cloud Services, including denial of service attacks, unauthorized access, penetration testing, scraping or distribution of malware; (c) cause an abnormal surge or increase in Buyer’s use of the Cloud Services that would negatively impact the operation of the Cloud Services, or (d) submit any information not contemplated in the applicable Documentation. ## 7. Ownership[​](#7-ownership "Direct link to 7. Ownership") Buyer does not acquire any right or license to use the Software during the Term other than the license granted under this License, and in particular does not become the owner of the marketing materials, any software or electronic media, intellectual property, methods, strategies, research and designs. Supplier and/or Licensor reserve the right to use in any manner any programming tools, skills, content, methods, strategies and techniques acquired or used in the performance of their duties under this License. Ownership of application data created using the Software remains with the author of such content. ## 8. Maintenance Services[​](#8-maintenance-services "Direct link to 8. Maintenance Services") In summary, Vendor provides the following Software Services to Buyer free of charge during the Term: Buyer will receive Software updates (Updates) in the manner defined by Atlassian when Licensor releases Updates; and Vendor shall provide Buyer with technical support for Software troubleshooting and error (as defined in Section 10.2) resolution as set forth in Section 10.1 (“Software Maintenance”) through the support channels listed in Section 9 during the support hours set forth in Section 11.3. Full details of these Services are set out in Sections 12, 13 and 14 below. Vendor has the right to have these Services provided by third parties (“Support Providers”). These Services are provided by Licensor. ## 9. Official Support Channels[​](#9-official-support-channels "Direct link to 9. Official Support Channels") The Supplier ensures that the following support channels are available from the Support Provider: Publicly accessible documentation Publicly accessible help desk for registering new support tickets Direct email support via The Supplier strives to make the Services easily available via email, chat, Atlassian forums, Supplier forums, social media and other channels during the Support Hours specified in paragraph 11.3 below. However, availability is at the sole discretion of the Supplier. ## 10. Included Services[​](#10-included-services "Direct link to 10. Included Services") 10.1 The Supplier provides the following services together with the Support Provider during the Support Hours (please see clauses 12, 13 and 14 for full details of these services): Investigation of Software issues, Analysis of Errors (as defined in clause 10.2) and investigation of the root cause of reported issues (Root Cause Analysis) The above limited services constitute the entire obligation of the Supplier to provide Support Services. In addition, the Supplier is not obliged to provide further services. In particular, the Supplier is not obliged to provide installation, customization, programming, consulting and training services. If the Supplier provides such services, they shall be paid for separately and agreed separately in writing. If the Additional Services are provided free of charge, this does not imply any future obligations. If the Additional Services are provided free of charge, the liability of the Supplier is excluded to the extent permitted by law. 10.2 The Supplier shall use reasonable efforts to resolve documented reproducible errors in the Software (Software Maintenance) together with the Support Provider using qualified personnel and in accordance with generally accepted industry standards. The Supplier is not responsible for the success of the error resolution and does not provide any guarantee for this. The Supplier's only obligation with respect to error resolution is to use reasonable efforts together with the Support Provider to provide the Software Maintenance as provided for in this License. For the purposes of this License, an "Error" is a material non-conformity between the functionality of the Software and the Software documentation reported by the Buyer, which does not occur due to user error. An Error is not considered an Error if the Licensor cannot reproduce it. The non-conformity must result in a permanent and significant loss of functionality. In such cases, the parties shall endeavour to agree on the actions to be taken. Such an agreement may also be reached between the Buyer and the Support Provider acting on behalf of the Supplier. 10.3 The Supplier is not required to perform Software maintenance for the Buyer (without prejudice to the obligation to pay the agreed purchase price for the Software), in particular: If the Error was caused by unauthorized modifications or changes to the Software (server and client); If the current or previous Software version and the delivered Error Solution are not installed, unless the delivered Error Solution version contains the Error; For a Software version that was released some time before the Buyer reported the Error (e.g. more than one month). This timeline depends on whether and how Atlassian allows the Buyer to keep the instance in the Atlassian Cloud updated (“Release Track”). If the error is caused by unauthorized use of the software or improper operation, except when the software is used in accordance with the user documentation; For software provided by the supplier that is no longer developed or supported (terminated status), is intended for testing purposes and is therefore an unfinished version of the software (beta), created as a final test version (candidate version), and/or a development version (development version) or used as a free version; For any hardware defects; When the software is used for hardware, software (not limited to but in particular not current web browsers) and operating system environments not specified in the user documentation; Interruptions caused by force majeure or similar circumstances; Changes made to the software by the buyer in violation of this agreement; Changes made to the software by the supplier's technical personnel other than the licensor without the supplier's prior written consent. If the supplier or support provider provides such services, this shall be agreed in writing and paid separately. 10.4 The buyer shall be aware that neither the supplier nor the hosting provider stores any application data and therefore the buyer shall take adequate data backup measures to ensure that any data to be restored is stored in a machine-readable format and can be restored by the buyer with minimal effort. Atlassian provides the following guides for Atlassian's Jira Cloud backups and Confluence Cloud backups. ## 11. Error Reporting, Obligation to Cooperate, and Support Hours[​](#11-error-reporting-obligation-to-cooperate-and-support-hours "Direct link to 11. Error Reporting, Obligation to Cooperate, and Support Hours") 11.1 The Buyer must immediately report any errors that may occur with a detailed description of the problem using the support channels listed in clause 9. 11.2 For the execution of the contractual services, cooperation by the Buyer must be complete and punctual. The obligation to cooperate includes the following items in particular: The Buyer must observe all applicable laws and regulations. It is prohibited to transfer data or content to the Vendor's Servers that violate legal provisions or infringe third-party property rights or copyrights, or other rights of third parties. When reporting an error, all documentation, log files, and other information relevant to troubleshooting shall be made available without delay; Only data free from computer viruses or other harmful code may be transmitted; The Buyer may use no software, technologies, or procedures in connection with the use of the contractual Software that is capable of affecting its operation, security, and availability. 11.3 To transmit error reports, the Buyer can reach the Support Provider during support hours on workdays between 09:00 and 17:00 (GMT). Workdays include Monday to Friday, except for all public holidays in England, in addition to the following days: 24 December and 31 December. The Vendor reserves the right to change support times as needed. 11.4 The support cases’ processing, considering the reaction and solution times specified in clauses 13, 14, shall be carried out during the support hours specified in paragraph 11.3. ## 12. Error Classification Levels[​](#12-error-classification-levels "Direct link to 12. Error Classification Levels") 12.1 In the case of error reports, the Vendor shall make sure that the Support Provider uses reasonable endeavors to ensure that the processing of the support cases is carried out within the response and resolution times specified in clauses 13, 14. The response and resolution times depend on the classification level; the following error classification levels apply: Priority 1: Critical error. The use of the whole or a material part of the Software is impossible or significantly restricted. A significant limitation exists where the whole or a material part of the Software no longer works, and no functional workaround can be achieved (“significant limitation”). Priority 2: Other disturbances. Any other problems with the Software. 12.2 The Vendor shall make sure that the Support Provider uses reasonable endeavors to handle all support cases within the time periods set out below. Priority 1 errors are given priority over priority 2 errors, irrespective of the time they were registered in the support system. ## 13. Response Time[​](#13-response-time "Direct link to 13. Response Time") 13.1 The response time is the period between the reporting of an error and the first action by the support provider. This period starts from the receipt of the corresponding support request through the official support channels according to clause 9 within the support times stipulated in clause 11.3 and runs only during the agreed support times. If a message appears outside the agreed support times, the response time starts from the next support period. 13.2 The supplier shall ensure that the support provider makes reasonable efforts within the following response times depending on the error level: priority 1: 4 hours, priority 2: 8 hours. 13.3 The response times are the supplier's stated wishes. In particular, with regard to clause 12.2, the supplier does not guarantee compliance with the stipulated response times. Failure to comply with these response times does not constitute any right for the buyer to reduce the price, demand compensation, terminate the agreement or seek any other form of compensation. ## 14. Resolution Time[​](#14-resolution-time "Direct link to 14. Resolution Time") 14.1 The resolution time is the maximum time after the start of the work on the support case until the error is resolved by troubleshooting or a workaround is implemented. 14.2 The Supplier shall ensure that the Support Provider makes all reasonable business efforts to achieve the following resolution times depending on the level of error classification: Priority 1: 16 hours, Priority 2: 40 hours. 14.3 The response times are the Supplier's target resolution times on the average of the last 5 incidents of that priority. Resolution times for any particular incident will vary. In particular, with respect to clause 12.2, the Supplier does not guarantee compliance with the stated average response times. Failure to comply with these response times does not constitute any right for the Buyer to reduce the price, request a refund, terminate the Agreement or seek any other form of compensation. ## 15. Limitation of Liability[​](#15-limitation-of-liability "Direct link to 15. Limitation of Liability") The Seller shall be liable for damages arising out of this Agreement, regardless of actual or legal reasons, only in accordance with the following provisions: 15.1 In the event of intent or loss of life or personal injury, the Seller shall be liable without limitation in accordance with the statutory provisions. 15.2 If the Seller negligently breaches an essential contractual obligation, liability shall in all cases be limited to the damages foreseeable at the time of entering into the Agreement up to a maximum of the total amount of all damages per year equal to 100% of the purchase price paid by the Buyer in that calendar year, provided that the Buyer can prove the damages. An essential obligation shall always exist if the obligation is essential for the proper performance of the Agreement and the Buyer trusts and can reasonably rely on it. This limitation of liability also applies to data loss and data corruption. An essential contractual obligation in the context of this Agreement is any obligation the fulfillment of which is necessary to enable the proper performance of the Agreement and the compliance of which the other party to the Agreement regularly relies on. 15.3 Liability is excluded in the case of negligent breach of other non-essential contractual obligations and (where authorized by applicable law) indirect and/or consequential damages (including, but not limited to, special damages, even if the Seller was aware of the possibility of such special damages); loss of profit; loss of anticipated savings; loss of business opportunities; loss of goodwill; loss or corruption of data. 15.4 The Supplier will indemnify and hold harmless the Buyer from any claims, actions or proceedings arising out of the Supplier’s infringement or infringement of any third party’s trademark, copyright, patent or other intellectual property rights relating to the Software. The maximum amount of damages that the Supplier shall be liable for shall be limited to Section 15.2. 15.5 The Supplier shall not be liable if the loss of Application Data is caused by the Buyer’s failure to perform data backups to ensure that the Buyer is able to restore the lost data with reasonable efforts. 15.6 The Buyer will indemnify and hold harmless the Seller from any claims, actions or proceedings arising out of (i) the Buyer’s breach of applicable data protection laws; and/or (ii) infringement of intellectual property rights. ## 16. Fees[​](#16-fees "Direct link to 16. Fees") All costs for the Software are defined in the Atlassian Marketplace. In the Atlassian Marketplace, the Buyer purchases and pays directly unless they work with an Atlassian Solution Partner. ## 17. Defects[​](#17-defects "Direct link to 17. Defects") In case of a defect (which is not an ‘error’) of the Software, the Vendor shall in its sole discretion remedy the defect immediately or to deliver a replacement free of defects if the Buyer notifies the Vendor of the defect. Claims based on a defect shall become statute-barred within one year of the Software being provided by the Vendor. ## 18. Warranty[​](#18-warranty "Direct link to 18. Warranty") 18.1 The Vendor guarantees that the Software has the quality as defined in this Agreement during the Term. 18.2 The Vendor also guarantees that it is entitled to grant the sublicence in accordance with this Licence. 18.3 The Vendor does not accept any additional guarantees. All other conditions, warranties, or other terms which might have effect between the parties or be implied or incorporated into this Licence, whether by statute, common law, or otherwise, are hereby excluded, including the implied conditions, warranties, or other terms as to the satisfactory quality, fitness for purpose or the use of reasonable skill and care. 18.4 Warranty claims shall become statute-barred within one year of the Software being provided by the Vendor. ## 19. Quotation for Marketing Purposes[​](#19-quotation-for-marketing-purposes "Direct link to 19. Quotation for Marketing Purposes") The Vendor is entitled to use the Buyer's name, including its logo, as a reference for advertising purposes. The Buyer can send an email to at any time. By receipt of this Email, the Vendor shall endeavor to cease future use within one week. ## 20. Export and Import Control[​](#20-export-and-import-control "Direct link to 20. Export and Import Control") The licence and services under this Agreement may be subject to export and import restrictions in certain countries. The Buyer shall comply with the applicable export and import control regulations. The performance of the Agreement by the Vendor is subject to the provision that there are no obstacles to performance due to national and international export and import law provisions or any other statutory provisions. ## 21. Termination[​](#21-termination "Direct link to 21. Termination") The Vendor shall be entitled to terminate the obligation of providing the Software Maintenance (clause 8) without notice if, in particular: the Buyer breaches their obligations under this Agreement and if, despite an appropriate grace period with a rejection warning, they do not put an end to the breach or demonstrate that appropriate measures have been taken to suitably prevent the repetition of the breach of contract in the future. ## 22. Miscellaneous[​](#22-miscellaneous "Direct link to 22. Miscellaneous") The Vendor is not responsible or liable for any failure or delay in the performance of its obligations under this Agreement arising out of or caused by, directly or indirectly, forces beyond its control, including, without limitation, strikes, work stoppages, accidents, acts of war or terrorism, epidemics, pandemics or an outbreak of infectious disease, quarantines, national or regional emergencies, civil or military disturbances, nuclear or natural catastrophes or acts of God, and interruptions, loss or malfunctions of utilities, communications or computer (software and hardware) services (“Force Majeure”); it being understood that the Vendor is to use commercially reasonable efforts that are consistent with accepted practices in the software industry to resume performance as soon as practicable under the circumstances. All agreements are contained within this contract. Should a provision of this Agreement be or become invalid, all other provisions shall remain unaffected. Such an invalid provision shall be replaced with a provision in line with the intention that the parties could reasonably attribute to the Agreement at the time of entering into said Agreement. --- # Excalidraw Diagrams plus Whiteboards — User Guide Related blog post: [Using Excalidraw whiteboards in Jira: quick setup and tips](/blog/excalidraw-whiteboards-jira.md) ## What is Excalidraw Diagrams plus Whiteboards?[​](#what-is-excalidraw-diagrams-plus-whiteboards "Direct link to What is Excalidraw Diagrams plus Whiteboards?") Excalidraw Diagrams plus Whiteboards adds a diagram editor to every Jira issue. You can create flowcharts, architecture diagrams, wireframes, ER models, mind maps, and more — all without leaving Jira. Diagrams are saved as attachments on the issue, and a preview is shown directly in the issue panel. *** ## Requirements[​](#requirements "Direct link to Requirements") * A Jira Cloud instance * A Jira administrator must install the app from the Atlassian Marketplace * To create or edit diagrams, you need the **Edit Issues** permission on the issue * Anyone with view access to the issue can see the diagram preview *** ## Installation[​](#installation "Direct link to Installation") 1. Go to **Jira Settings** → **Manage apps**. 2. Click **Find new apps** and search for **Excalidraw Diagrams plus Whiteboards**. 3. Click **Install** and confirm. 4. The app appears automatically on all issues — no additional setup required. *** ## How to Find the App[​](#how-to-find-the-app "Direct link to How to Find the App") Open any Jira issue and look at the right-side panel. The **Excalidraw Diagrams plus Whiteboards** panel appears below the issue details. * If no diagram exists yet, users with edit permission see a **Create Diagram** button (with a **+** icon). * If a diagram exists, all users see the SVG preview. Users with edit permission also see an **Edit Diagram** button (with a pencil icon). *** ## Using the App[​](#using-the-app "Direct link to Using the App") ### Creating a Diagram[​](#creating-a-diagram "Direct link to Creating a Diagram") 1. Open a Jira issue. 2. In the right-side panel, find the **Excalidraw Diagrams plus Whiteboards** section. 3. Click the **+** (Create Diagram) button. 4. A full-screen editor opens with a blank canvas. 5. Draw your diagram using the toolbar — shapes, text, arrows, lines, and freehand drawing are all available. 6. When finished, click **Save Drawing**. The editor closes and the diagram preview appears in the panel. ### Editing an Existing Diagram[​](#editing-an-existing-diagram "Direct link to Editing an Existing Diagram") 1. Open the issue that has a diagram. 2. Click the pencil **Edit Diagram** button in the panel. 3. The full-screen editor opens with the existing diagram loaded. 4. Make your changes and click **Save Drawing**. ### Cancelling Edits[​](#cancelling-edits "Direct link to Cancelling Edits") To close the editor without saving, click **Cancel**. Any unsaved changes are discarded. ### Using Shape Libraries[​](#using-shape-libraries "Direct link to Using Shape Libraries") The editor includes 229 bundled shape libraries with icons for AWS, Azure, GCP, UML, networking, and more. 1. Open the editor. 2. Open the **library panel** from the left sidebar. 3. Click **Browse libraries** to open the library browser. 4. In the library browser you can: * **Search** by name or description using the search box * **Sort** by Name, Created date, or Updated date using the sort buttons * **Preview** any library by clicking its thumbnail image * **Add** a library by clicking the blue **+** button on the right 5. Once added, the library shapes appear in your library panel and can be dragged onto the canvas. ### Generating Diagrams from Mermaid Syntax[​](#generating-diagrams-from-mermaid-syntax "Direct link to Generating Diagrams from Mermaid Syntax") The editor supports Mermaid, a text-based diagram language. This lets you type a definition and get a visual diagram instantly. 1. Open the editor. 2. From the toolbar, use the Mermaid diagram tool. 3. Type or paste your Mermaid definition (e.g., a flowchart or ER diagram). 4. The diagram is generated and placed on the canvas. 5. You can then move, resize, and style the generated elements like any other shape. *** ## Tips & Common Workflows[​](#tips--common-workflows "Direct link to Tips & Common Workflows") * **Architecture decisions** — Open the relevant epic and sketch the proposed architecture. The diagram stays attached to the issue for the team to reference. * **Bug reproduction flows** — Draw a step-by-step flowchart showing how to reproduce a bug, directly on the bug issue. * **Wireframe reviews** — Sketch a quick wireframe on a story issue so designers and developers can discuss it in context. * **Reuse libraries** — Once you add a shape library in one diagram, it stays available in the editor for that issue. Add the libraries you use most (AWS, UML, etc.) on your first diagram. *** ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") **The panel shows "No diagram has been added to this issue yet" but I can't see a create button.** → You don't have the Edit Issues permission on this issue. Ask a project administrator to grant you permission, or ask someone with access to create the diagram. **The diagram preview doesn't update after saving.** → The panel refreshes automatically when the editor closes. Try reloading the issue page. If the preview still doesn't show, check that the attachment `excalidraw-diagram.json` still exists on the issue (Issue → Attachments). **The editor opens but shows a blank canvas instead of the existing diagram.** → The diagram attachment may have been deleted manually. Check the issue's attachments section. If the attachment is missing, the editor will start with a blank canvas. **A library fails to load.** → All 229 libraries are bundled with the app and require no internet connection. If a library doesn't load, try closing and reopening the editor. If the issue persists, try removing and re-adding the library from the library browser. **The app shows a license warning.** → The app requires an active license. Contact your Jira administrator to subscribe on the Atlassian Marketplace. ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [How to create architecture diagrams in Confluence](/blog/how-to-create-architecture-diagrams-confluence.md) * [Excalidraw best practices FAQ](/blog/faq-excalidraw-best-practices.md) * [Confluence whiteboard apps FAQ](/blog/faq-confluence-whiteboard-apps.md) Was this helpful?👍 Yes👎 No --- # Usage Excalidraw Plus for Confluence is a powerful macro app that brings the collaborative diagramming capabilities of Excalidraw directly into your Confluence pages. ## Getting Started[​](#getting-started "Direct link to Getting Started") ### Installation[​](#installation "Direct link to Installation") 1. Log in to your Confluence instance as an admin 2. Go to the Atlassian Marketplace 3. Search for "Excalidraw Plus for Confluence" 4. Click "Get app" or "Try it free" 5. Follow the installation wizard instructions ### Adding Excalidraw to Your Page[​](#adding-excalidraw-to-your-page "Direct link to Adding Excalidraw to Your Page") There are two ways to add an Excalidraw diagram: 1. Using the toolbar: * Click the `+` button in your Confluence editor * Search for "Excalidraw Plus" * Click to insert the macro 2. Using the slash command: * Type `/` in your Confluence editor * Type "Excalidraw" * Press Enter ## Core Features[​](#core-features "Direct link to Core Features") ### Drawing Tools[​](#drawing-tools "Direct link to Drawing Tools") * **Shapes**: Rectangle, Circle, Diamond, Arrow, Line * **Freehand Drawing**: Pencil tool for sketching * **Text**: Add text annotations and labels * **Library**: Pre-made components and shapes ### Styling Options[​](#styling-options "Direct link to Styling Options") * **Colors**: Custom color picker for fills and strokes * **Line Styles**: Solid, dashed, dotted * **Text Formatting**: Font size, alignment, and style * **Opacity**: Adjust transparency of elements ## Working with Diagrams[​](#working-with-diagrams "Direct link to Working with Diagrams") ### Saving Your Work[​](#saving-your-work "Direct link to Saving Your Work") The diagram automatically saves as you work. To ensure all changes are preserved: 1. Click outside the Excalidraw editor 2. Save the Confluence page 3. Wait for the sync confirmation ### Viewing Results[​](#viewing-results "Direct link to Viewing Results") Your diagrams will appear: * In view mode of the Confluence page * In PDF exports * In page previews ### Export Options[​](#export-options "Direct link to Export Options") 1. Click the menu icon (⋮) in the Excalidraw editor 2. Choose from multiple export formats: * PNG * SVG * JSON (for backup) ## Tips and Best Practices[​](#tips-and-best-practices "Direct link to Tips and Best Practices") * Use the grid feature for precise alignment * Group related elements together * Leverage the library for consistent diagrams * Save frequently used components to your library ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [Excalidraw for Confluence & Jira: FAQ, Tips & Best Practices](/blog/faq-excalidraw-best-practices.md) * [Excalidraw for Confluence — Which Whiteboard App Fits Your Team?](/blog/use-excalidraw-in-confluence-whiteboard-diagrams.md) * [Confluence diagram tools compared: Mermaid vs Excalidraw vs Graphviz](/blog/confluence-diagram-tools-comparison.md) * [How to Add Excalidraw Whiteboards to Jira Issues](/blog/excalidraw-whiteboards-jira.md) ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") If you encounter issues: 1. Refresh the page 2. Clear browser cache 3. Contact support through the Marketplace listing ## Support and Resources[​](#support-and-resources "Direct link to Support and Resources") * [Official Documentation](https://excalidraw.com/docs) * [Community Forum](https://community.atlassian.com) * [Video Tutorials](https://youtube.com/excalidraw) * [NGPilot Service](mailto:service@ngpilot.com) Was this helpful?👍 Yes👎 No --- # Google Fonts for Confluence — User Guide Related blog post: [How to configure Google Fonts in Confluence](/blog/configure-google-fonts-confluence.md) ## Overview[​](#overview "Direct link to Overview") Google Fonts for Confluence lets you display text using any of the 1942+ Google Fonts directly on your Confluence pages. Customize font family, variant, size, color, and alignment with a live preview. ## Getting Started[​](#getting-started "Direct link to Getting Started") ### Inserting Google Fonts Text[​](#inserting-google-fonts-text "Direct link to Inserting Google Fonts Text") 1. Edit a Confluence page 2. Type `/google fonts` in the editor and select **Google Fonts for Confluence** 3. The configuration panel opens with font options and a live preview 4. Choose your font, style, and text 5. Click **Save** to insert the styled text ### Re-editing[​](#re-editing "Direct link to Re-editing") Click on an existing Google Fonts macro and select **Edit** to reopen the configuration panel. All your settings are preserved. *** ## Configuration Options[​](#configuration-options "Direct link to Configuration Options") ### Font Family[​](#font-family "Direct link to Font Family") Search and select from 1942+ Google Fonts. Use the search dropdown to quickly find your preferred font. ### Font Variant[​](#font-variant "Direct link to Font Variant") Choose from available variants for the selected font: | Variant | Description | | --------------- | ----------------- | | **Regular** | Default weight | | **Italic** | Italic style | | **Bold** | Bold weight | | **Bold Italic** | Bold italic style | Available variants depend on the selected font family. ### Text Size[​](#text-size "Direct link to Text Size") Enter any font size in pixels using the numeric input field. There is no enforced limit — common ranges: | Usage | Recommended Size | | -------------- | ---------------- | | Body text | 14–18px | | Headings | 24–48px | | Display / Hero | 60–120px | ### Text Color[​](#text-color "Direct link to Text Color") Pick a text color using the built-in color picker. Choose from quick-select swatches for common colors, or switch to the palette to fine-tune the exact shade and edit RGB values directly. ### Text Alignment[​](#text-alignment "Direct link to Text Alignment") | Option | Alignment | | ---------- | ----------------------- | | **Left** | Align text to the left | | **Center** | Center the text | | **Right** | Align text to the right | ### Preview Text[​](#preview-text "Direct link to Preview Text") Type your content in the preview area to see how it looks with the selected font and settings in real-time. *** ## Dark Mode Support[​](#dark-mode-support "Direct link to Dark Mode Support") The macro automatically adapts to Confluence's dark/light theme for comfortable reading in both modes. *** ## Tips[​](#tips "Direct link to Tips") * Use the search box to quickly filter fonts by name * Preview your text at different sizes before saving * Use bold or italic variants for emphasis within your content * Combine custom colors with Google Fonts for branded text styling *** ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [How to configure Google Fonts in Confluence](/blog/configure-google-fonts-confluence.md) * [Google Fonts for Confluence: Performance Impact & FAQ](/blog/faq-google-fonts-performance.md) * [Google Fonts for Confluence — Which Custom Typography App Fits Your Team?](/blog/google-fonts-confluence-custom-typography.md) ## Support[​](#support "Direct link to Support") For issues or feature requests, please visit the app's listing on the Atlassian Marketplace. Was this helpful?👍 Yes👎 No --- # Usage It's a macro app, so you can use it by two ways: * from the Confluence editor toolbar +, then search `Graphviz Charts for Confluence` * type `/` inside the Confluence editor, then type `Graphviz Charts for Confluence` You can click edit icon to config it: ![Clicking edit icon to configure Graphviz chart](/assets/images/highlight1-80ef454659d0fb5f8425632012948994.png) Here's the result after configured: ![Rendered Graphviz chart result](/assets/images/highlight2-b04140970d4a297af0ed47232c924636.png) Yes! You can use editor's alignment to layout the graphviz image: ![Aligning Graphviz chart using editor alignment options](/assets/images/highlight3-dee246c6aaa9f517fd3441892e4ad2d0.png) It's has fullsize layout engine support, here's the docs you can refer: [layouts](https://graphviz.org/docs/layouts/) and this is a dot language reference [dot language](https://graphviz.org/doc/info/lang.html) ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [How to create flowcharts in Confluence](/blog/create-flowcharts-confluence.md) * [Confluence diagram tools comparison](/blog/confluence-diagram-tools-comparison.md) * [How to create architecture diagrams in Confluence](/blog/how-to-create-architecture-diagrams-confluence.md) Was this helpful?👍 Yes👎 No --- # Welcome to NGPILOT Apps NGPILOT builds **simple, intuitive apps for Confluence and Jira** that help teams diagram, write, format, and manage content more effectively. All apps are available on the [Atlassian Marketplace](https://marketplace.atlassian.com/vendors/1226848/) with free trials. ## Confluence Apps[​](#confluence-apps "Direct link to Confluence Apps") ### Diagramming & Visualization[​](#diagramming--visualization "Direct link to Diagramming & Visualization") * [**Mermaid Plus Diagrams & AI Agent for Confluence**](/docs/Mermaid-Plus-for-Confluence/usage.md) — Create flowcharts, sequence diagrams, Gantt charts and 20+ diagram types with built-in templates and live preview * [**Excalidraw Plus for Confluence**](/docs/Excalidraw-plus-for-Confluence/usage.md) — Freeform whiteboard drawing with 220+ shape libraries * [**Excalidraw & Mermaid Visual Editor**](/docs/diagram-duo-for-confluence/usage.md) — Combine freeform drawing and structured Mermaid diagrams in one macro * [**Graphviz Charts for Confluence**](/docs/Graphviz-Charts-for-Confluence/usage.md) — Generate professional Graphviz flowcharts and network diagrams * [**Markdown Mind Maps for Confluence**](/docs/Markdown-Mind-Maps-for-Confluence/user-docs.md) — Turn Markdown headings into interactive mind maps * [**JSON Structure Viewer**](/docs/json-structure-viewer-for-confluence/usage.md) — Transform JSON into visual tree diagrams ### Content Editing[​](#content-editing "Direct link to Content Editing") * [**Enhanced Markdown for Confluence**](/docs/Enhanced-Markdown-for-Confluence/usage.md) — WYSIWYG Markdown editing with live preview, charts and UML support * [**Modern Code Blocks for Confluence**](/docs/Modern-Code-Blocks-for-Confluence/user-docs.md) — Syntax highlighting for 85+ languages with Monaco editor and auto dark/light theme * [**Content Formatting Macros & Page Builder**](/docs/Content-Formatting-Macros-Page-Builder-for-Confluence/user-docs.md) — Build marketing pages, portals, and intranets with 23 macros — hero, pricing, tabs, cards, and templates * [**Google Fonts for Confluence**](/docs/Google-Fonts-for-Confluence/usage.md) — Apply 1942+ Google fonts to Confluence pages * [**Raw Storage Source Editor Pro**](/docs/raw-storage-source-editor-pro-for-Confluence/usage.md) — Directly edit Confluence raw storage format * [**Raw Storage Source Editor Free**](/docs/raw-storage-source-editor-for-Confluence/usage.md) — Free version of the source editor ### Content Management[​](#content-management "Direct link to Content Management") * [**Modern FAQ for Confluence**](/docs/Modern-FAQ-for-Confluence/usage.md) — Build customizable FAQ sections * [**Modern Numbered Headings**](/docs/Modern-Numbered-Headings-for-Confluence/user-docs.md) — Auto-generate numbered headings and table of contents * [**Modern My Tasks**](/docs/Modern-My-Tasks-for-Confluence/user-docs.md) — Inline task management with smart filtering * [**Modern Questions**](/docs/Modern-Questions-for-Confluence/user-docs.md) — Structured Q\&A experience with voting and accepted answers * [**Modern Importer Exporter**](/docs/Modern-Importer-Exporter-for-Confluence/user-docs.md) — Enterprise content migration and backup * [**Pagination Buttons**](/docs/Pagination-Buttons-for-Confluence/usage.md) — Previous/Next navigation between pages ### Media & Embeds[​](#media--embeds "Direct link to Media & Embeds") * [**Widget Carousel**](/docs/carousel-for-confluence/usage.md) — Image carousels for banners and showcases * [**Content Craft for Confluence**](/docs/Content-Craft-for-Confluence/usage.md) — 1,300+ Notion-style SVG illustrations for business, tech, and lifestyle * [**Modern OpenAPI (Swagger) Integration**](/docs/Modern-OpenAPI-Swagger-Integration-for-Confluence/user-docs.md) — Render OpenAPI and Swagger specifications with an interactive, theme-aware viewer * [**PSD Attachments Viewer**](/docs/PSD-Attachments-Viewer-for-Confluence/user-docs.md) — View PSD files directly in Confluence * [**QRCode for Confluence**](/docs/QRCode-for-Confluence/usage.md) — Embed QR codes into pages * [**EPUB Reader for Confluence**](/docs/epub-reader-for-confluence/usage.md) — Read EPUB files inside Confluence * [**Manim for Confluence**](/docs/Manim-for-Confluence/user-docs.md) — Mathematical animations using the Manim engine ## Jira Apps[​](#jira-apps "Direct link to Jira Apps") * [**Excalidraw Diagrams plus Whiteboards for Jira**](/docs/Excalidraw-Diagrams-plus-Whiteboards-for-Jira/usage.md) — Add Excalidraw whiteboards to every Jira issue * [**Mermaid Plus Diagrams for Jira**](/docs/Mermaid-plus-Diagrams-for-Jira/usage.md) — 30 Mermaid diagram types with live preview in Jira issues * [**Simple Bulk Attachment Downloader**](/docs/Simple-Bulk-Attachment-Downloader-for-Jira/user-docs.md) — Download all attachments from search results as ZIP * [**Simple Bulk Issues Excel CSV Export**](/docs/Simple-Bulk-Issues-Excel-CSV-Export-for-Jira/user-docs.md) — Export filtered Jira issues to Excel or CSV * [**Issue History Agent for Jira**](/docs/Issue-History-Agent-for-Jira/usage.md) — Field-level change history with word-level diffs, a JQL report with CSV export, and a Rovo-chat agent that answers "what changed?" * [**Attachment Reviewer for Jira**](/docs/Attachment-Reviewer-for-Jira/user-docs.md) — Enforce file type and size policies on uploads * [**Modern Issue Templates for Jira**](/docs/Modern-Issue-Templates-for-Jira/user-docs.md) — Create and auto-apply issue templates * [**Modern Announcement Banner for Jira**](/docs/Modern-Announcement-Banner-for-Jira/user-docs.md) — Manage announcement banners in Jira * [**Checklist Workflow Automation for Jira**](/docs/Checklist-Workflow-Automation-for-Jira/user-docs.md) — Task checklists with templates, auto-apply, and assignee reminders * [**JSON Graph Viewer & Visualizer for Jira**](/docs/JSON-Graph-Viewer-Visualizer-for-Jira/user-docs.md) — Visualize JSON fields, entity properties, or pasted payloads as interactive graphs on the issue * [**Component Hierarchy for Jira**](/docs/Component-Hierarchy-for-Jira/user-docs.md) — Parent-child component trees with subtree-wide JQL search ## Getting Started[​](#getting-started "Direct link to Getting Started") 1. Browse the app you need from the sidebar or the lists above 2. Read the installation and configuration guide 3. Install from the [Atlassian Marketplace](https://marketplace.atlassian.com/vendors/1226848/) — all apps offer free trials For support, contact us at --- # Issue History Agent for Jira — User Guide ## Overview[​](#overview "Direct link to Overview") Jira shows a change history per issue, but it is slow to read and impossible to compare across issues. Issue History gives you three ways to answer "what changed?": * **Issue panel** — a compact, newest-first change list on every issue, with a focused word-level diff for long text fields such as Description. * **Report** — one table of field changes across a whole JQL-filtered set of issues, with date and field filters and CSV export. * **Rovo agent** — ask "what changed recently on this issue?" in Rovo chat and get a plain-language answer backed by live Jira data. The app is read-only: it requests only `read:jira-work`, never writes to your Jira data, and stores nothing. ## Issue Panel[​](#issue-panel "Direct link to Issue Panel") ### Viewing an Issue's Change History[​](#viewing-an-issues-change-history "Direct link to Viewing an Issue's Change History") 1. Open any Jira issue 2. Find the **Issue History** panel (usually above the Activity section) 3. The panel lists the most recent field changes, newest first — each entry shows who changed what, when, and the before → after values 4. Use the pagination control to page back through long histories; already-seen pages are cached locally, so paging back is instant ### Reading a Word-Level Diff[​](#reading-a-word-level-diff "Direct link to Reading a Word-Level Diff") For long text fields (for example Description), a single inline line rarely tells you what actually changed. Entries with substantial edits show a **View diff** button that opens a focused before/after comparison with word-level highlighting — you see exactly which words were added or removed, not just two wall-of-text versions. ## Report[​](#report "Direct link to Report") The report is a Jira **global page**: find **Issue History Report** in the Jira Apps menu. 1. Enter a JQL query (the default is `updated >= -7d ORDER BY updated DESC`, capped at 100 issues) 2. The report loads each issue's change history in bulk and shows one row per field change: when, issue, author, field, from → to 3. Narrow the result with the **date range** and **field** filters — filtering re-slices the loaded data instantly without re-querying Jira 4. Click **Export CSV** to download the filtered rows (formula-injection-safe, opens cleanly in Excel and Google Sheets) The bulk history walk is capped (1,000 changes per batch, up to 20 pages). Very large result sets are marked as truncated rather than silently cut off. ## Rovo Agent[​](#rovo-agent "Direct link to Rovo Agent") In **Rovo chat**, pick the **Issue History** agent and ask in plain language: * *"What changed recently on this issue?"* (in an issue context) * *"Show me the last time the Status field was edited on LEO-9"* * *"Summarise this issue and its recent activity"* The agent answers from live Jira data via three tools — change history, field-change diff, and issue snapshot — and shows the sources it used. ### Using the Tools in Your Own Studio Agents[​](#using-the-tools-in-your-own-studio-agents "Direct link to Using the Tools in Your Own Studio Agents") The app also publishes its tools through **Rovo MCP** (Preview). In Rovo Studio, add tools from the connected app "Issue History MCP" to any custom agent you build, and that agent gains the same read access to change history. ## Permissions and Privacy[​](#permissions-and-privacy "Direct link to Permissions and Privacy") * The app requests only `read:jira-work` and cannot modify anything. * Every query runs **as you**: the agent and panels can only ever show issues you already have permission to see. * No change data is stored outside your Jira site; the report holds its working set in memory for the current page view only. ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") **The app shows a license warning.** → The app requires an active license. Contact your Jira administrator to subscribe on the Atlassian Marketplace. **The panel or agent says it cannot load data for an issue.** → Check that you can open the issue yourself — the app never shows data your own account cannot see. **The report is marked as truncated.** → The JQL matched more history than the built-in cap. Narrow the query (shorter date range, tighter JQL) and export what loaded. Was this helpful?👍 Yes👎 No --- # JSON Graph Viewer & Visualizer for Jira — User Guide ## What is JSON Graph Viewer & Visualizer for Jira?[​](#what-is-json-graph-viewer--visualizer-for-jira "Direct link to What is JSON Graph Viewer & Visualizer for Jira?") JSON Graph Viewer & Visualizer for Jira is an issue panel that turns JSON into an interactive node graph. Instead of scrolling through a wall of braces, you see objects, arrays and values as connected nodes you can expand, collapse, pan and zoom — right inside the Jira issue view. The panel can load JSON from three places: 1. **Issue fields** — any field whose content is JSON (a REST payload, an API response or a config blob stored in a custom field). 2. **Issue properties** — structured JSON that other apps store on the issue as entity properties. 3. **Paste JSON** — type or paste any raw JSON, and it renders instantly. This works on every issue, even one with no JSON fields at all. *** ## Requirements[​](#requirements "Direct link to Requirements") * Jira Cloud. * Installing requires a Jira administrator. * The app asks for **read-only access** to work items. It cannot change any issue data, and JSON is rendered in your browser — nothing is stored or sent anywhere else. *** ## Installation[​](#installation "Direct link to Installation") 1. Go to **Apps** → **Manage apps** (Jira administration). 2. Choose **Find new apps** and search for **JSON Graph Viewer & Visualizer for Jira**. 3. Click **Install** and approve the read-only permission. 4. There is nothing to configure — open any issue and the panel is ready. *** ## Opening the Panel[​](#opening-the-panel "Direct link to Opening the Panel") Open any issue, and find **JSON Graph Viewer** in the issue view panels. The panel opens with three tabs at the top: **Issue fields**, **Issue properties** and **Paste JSON**. *** ## The Three JSON Sources[​](#the-three-json-sources "Direct link to The Three JSON Sources") ### Issue fields[​](#issue-fields "Direct link to Issue fields") The panel scans the issue's fields for content that parses as JSON. * One match: it renders immediately, with the field name shown above the graph. * Several matches: a dropdown appears so you can switch between them without leaving the panel. ### Issue properties[​](#issue-properties "Direct link to Issue properties") Apps often store structured JSON on an issue as entity properties (for example integration state or cached API data). Switch to the **Issue properties** tab to see those JSON blobs as graphs. If several exist, the same dropdown picker lets you move between them. ### Paste JSON[​](#paste-json "Direct link to Paste JSON") The **Paste JSON** tab gives you a syntax-highlighted editor. Type or paste raw JSON — a REST response from your browser dev tools, an API example, a webhook payload — and the graph updates as you type. A fresh panel starts with a small demo so you can see how it works before using your own data. If the text isn't valid JSON, the panel tells you instead of rendering nothing: > *That isn't valid JSON. Check the syntax and try again.* *** ## Code, Graph, or Both[​](#code-graph-or-both "Direct link to Code, Graph, or Both") A view-mode dropdown in the corner of the panel switches between: | Mode | What you get | | ---------------- | ------------------------------------------------------------ | | **Code** | The JSON formatted and syntax-highlighted, like your editor | | **Graph** | The interactive node diagram | | **Code + Graph** | Both, side by side — edit or read above, see the shape below | In graph view you can: * **Pan** — drag the canvas. * **Zoom** — the **−** and **+** buttons, or **Fit** to frame the whole graph. * **Collapse and expand** nodes — click a node's collapse control to fold an object or array into a single *n items* node and back. *** ## Themes[​](#themes "Direct link to Themes") The panel follows your Jira appearance: choose light or dark in your Jira profile and the graph, code view and controls switch with it. *** ## FAQ[​](#faq "Direct link to FAQ") **Nothing shows under "Issue fields" — is it broken?** No JSON-parseable field exists on that issue. Use the **Paste JSON** tab, or add a field that holds JSON (the panel picks it up automatically next time). **Can the app change my issue data?** No. It requests read-only access, and rendering happens in your browser. **Does pasting send my JSON to a server?** No. Pasted JSON is parsed and drawn locally in your browser session. **Where do issue properties come from?** Other apps write them through Jira's entity-properties API. If the tab is empty, no app has stored JSON on that issue yet. Was this helpful?👍 Yes👎 No --- # Usage ## How to insert macro[​](#how-to-insert-macro "Direct link to How to insert macro") Type /json and select "JSON Structure Viewer" ![Typing /json in Confluence editor to find the macro](/assets/images/1-b618ca7b373418beb47e5f26947bbc45.png) Or click the "+" button and select "JSON Structure Viewer", the editor will open. ![Selecting JSON Structure Viewer from the insert menu](/assets/images/2-3af7eba101bcf1e015fc471d9c100114.png) ## Editor[​](#editor "Direct link to Editor") An empty editor: ![Empty JSON editor panel](/assets/images/3-d29d16ec169496aff96442b2bcdfa1e1.webp) Input or paste your json code in the left editor panel, then the preview will show in right panel ![Pasting JSON in the editor with live preview](/assets/images/4-e4d4b1b52be4396ffe6cc87bfe40f885.webp) Click the "Save" button on bottom right to save the macro. ![Save button location in the editor](/assets/images/5-edcc14ae4c6ef98153f14285b3b2ae08.png) ## Preview mode[​](#preview-mode "Direct link to Preview mode") After you save the macro, you can click the image to open preview mode, then use the bottom tool bar to zoom in/out or rotate ![Preview mode with zoom and rotate toolbar](/assets/images/6-5e410ea9bb26e4215c0eec588fd71803.webp) ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [How to embed and visualize JSON in Confluence](/blog/embed-json-confluence.md) * [Best Confluence apps for developers](/blog/best-confluence-apps-developers.md) * [Advanced code blocks in Confluence](/blog/advanced-code-blocks-confluence.md) Was this helpful?👍 Yes👎 No --- # Manim for Confluence — User Documentation ## What is Manim for Confluence?[​](#what-is-manim-for-confluence "Direct link to What is Manim for Confluence?") Manim for Confluence is a Confluence macro that lets you embed live mathematical animations directly in any Confluence page. You write animation code using the Manim scene API, configure the canvas, and the animation renders right inside your page — no external tools, no exports, no uploads. *** ## Installation[​](#installation "Direct link to Installation") Manim for Confluence is installed from the Atlassian Marketplace. 1. In your Confluence site, go to **Settings** (gear icon, top right). 2. Select **Manage apps** from the left sidebar. 3. Click **Find new apps** and search for **Manim for Confluence**. 4. Click **Install** on the app listing and follow the prompts. 5. Once installed, the macro is immediately available on all pages in your site — no per-space setup required. > You need Confluence Administrator permissions to install apps. *** ## Adding the Macro to a Page[​](#adding-the-macro-to-a-page "Direct link to Adding the Macro to a Page") Manim for Confluence registers as a **Confluence macro**. Here's how to find and insert it: 1. Open or create a Confluence page and enter **Edit** mode. 2. Click the **+** (Insert) button in the editor toolbar, or type `/` in the page body to open the macro browser. 3. Search for **Manim** and select **Manim for Confluence** from the results. 4. The macro configuration panel opens automatically — see the next section for how to configure it. 5. Click **Save** in the config panel to insert the macro, then publish your page. The animation will render inline on the published page wherever you placed the macro. *** ## Configuring the Macro[​](#configuring-the-macro "Direct link to Configuring the Macro") When you insert the macro (or click the macro on an existing page and choose **Edit**), the full-screen configuration panel opens. It has three main areas: ### Top Bar[​](#top-bar "Direct link to Top Bar") | Control | Description | | -------- | ------------------------------------------------------------------- | | Logo | Identifies the app — no action. | | ? (Help) | Opens the user documentation in a popup panel inline. | | Cancel | Closes the config panel without saving any changes. | | Save | Saves your configuration and inserts/updates the macro on the page. | *** ### Toolbar[​](#toolbar "Direct link to Toolbar") The toolbar sits below the top bar and gives you quick access to the most common settings. | Control | Description | | ----------- | -------------------------------------------------------------------------- | | Width (px) | Canvas width in pixels. Default: 800. Range: 100–10000. | | Height (px) | Canvas height in pixels. Default: 450. Range: 100–1000. | | Background | Colour picker for the canvas background. Default: `#1C1C1C` (near-black). | | Templates | Quick-start buttons that load a ready-made animation into the code editor. | **Available templates:** * **Basic** — Creates, transforms, and fades shapes (circle → square → triangle). * **Manim Logo** — Recreates the Manim CE logo using grouped shapes and LaTeX. * **Sine Curve** — Animates a dot tracing a sine wave with a rotating circle. * **Moving Angle** — Animates an angle label using a ValueTracker. * **Boolean Ops** — Demonstrates union, intersection, and difference of ellipses. * **Point Trace** — A dot that leaves a visible trail as it moves. Clicking a template immediately loads its code into the editor and refreshes the preview. *** ### Preview Panel[​](#preview-panel "Direct link to Preview Panel") The preview panel shows a live render of your animation as you configure it. It updates automatically whenever you change the canvas size, background colour, or code. Use it to verify your animation looks correct before saving. *** ### Code Editor[​](#code-editor "Direct link to Code Editor") The bottom half of the config panel is a full Monaco code editor (the same engine as VS Code) with JavaScript syntax highlighting. Write your animation using the Manim scene API. All Manim exports are available as global variables — you do not need to import anything. The `scene` object is injected automatically. **Basic example:** ``` const circle = new Circle({ radius: 1.5, color: BLUE }); await scene.play(new Create(circle)); await scene.wait(1); await scene.play(new FadeOut(circle)); ``` The editor supports standard keyboard shortcuts (Ctrl/Cmd+Z for undo, etc.). *** ## Advanced Settings[​](#advanced-settings "Direct link to Advanced Settings") Advanced settings are not currently exposed in the toolbar UI but are stored in the macro configuration. They control playback behaviour: | Setting | Description | Default | | ------------------------ | ------------------------------------------------------------------------------------------------ | -------------- | | Autoplay | Whether the animation plays automatically when the page loads. | `true` | | Playback speed | Multiplier for animation speed (0.25×, 0.5×, 1×, 1.5×, 2×). | `1` | | Controls auto-hide delay | Milliseconds before player controls fade out. `0` = always visible. | `2500` | | Controls position | Where the player controls appear on the canvas (top-left, top-right, bottom-left, bottom-right). | `bottom-right` | | Controls theme | Light or dark player controls. | `dark` | *** ## Viewing the Animation on a Page[​](#viewing-the-animation-on-a-page "Direct link to Viewing the Animation on a Page") Once the macro is saved and the page is published, the animation renders automatically in the page body. Visitors do not need any plugins or extensions — the animation runs entirely in the browser. If autoplay is enabled, the animation starts as soon as the page loads. Otherwise, use the player controls overlaid on the canvas to play, pause, or scrub through the animation. *** ## Editing an Existing Macro[​](#editing-an-existing-macro "Direct link to Editing an Existing Macro") 1. Open the Confluence page in **Edit** mode. 2. Click on the Manim macro block in the page body. 3. Click the **Edit** (pencil) icon that appears. 4. The configuration panel reopens with your previously saved settings. 5. Make your changes and click **Save**. *** ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") **The animation doesn't appear on the page.** Make sure the page has been published after saving the macro. The animation only renders on the published view, not in the editor preview. **I see "Loading animation…" but nothing plays.** This usually means the macro hasn't been configured yet. Click the macro to edit it, add some code, and save. **My code throws an error in the preview.** Check the browser console for details. Common causes are typos in class names (e.g. `Circel` instead of `Circle`) or missing `await` before `scene.play()` calls. **The preview doesn't update after I change the code.** The preview refreshes automatically on code changes. If it appears stuck, try changing the canvas width by 1px and back — this forces a full remount. **I can't open external links from the help popup.** Forge apps run in a sandboxed iframe that blocks new tabs. The help button intentionally opens docs inline in a popup for this reason. ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [Best Confluence apps for developers](/blog/best-confluence-apps-developers.md) * [Mermaid syntax cheat sheet for Confluence](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md) Was this helpful?👍 Yes👎 No --- # Markdown Mind Maps for Confluence — User Guide ## Introduction[​](#introduction "Direct link to Introduction") Markdown Mind Maps turns a plain Markdown outline into an **interactive mind map** directly on a Confluence page. You don't draw anything — you type headings and bullets, and the structure becomes branches and leaves you can expand, collapse, and click through. It's the fastest way to go from notes to a diagram: **no canvas, no drag-and-drop, no learning curve**. Titles become the central topic, `##` headings become branches, and bullets become leaves. Because the Markdown is always the source of truth, your plan stays editable, diffable, and git-friendly. Everything runs natively in Confluence Cloud (built 100% on Atlassian Forge) with the open-source markmap engine. The map follows Confluence light/dark mode automatically. ## Quick start[​](#quick-start "Direct link to Quick start") 1. Install from the Atlassian Marketplace (try it free on your own site). 2. Edit a Confluence page, type **/mind map**, and select **Markdown Mind Maps for Confluence**. 3. Paste or type a Markdown outline. The live preview renders the map as you type. 4. Click **Save** — the interactive mind map appears on the page where the macro sits. ## The editor[​](#the-editor "Direct link to The editor") The configuration dialog splits into a Markdown editor on the left and a **live preview** on the right. The preview updates as you type, so a `## Help` heading immediately grows a branch. A minimal outline: ``` # Project Kickoff ## Vision - Launch fast - Measure everything ## Goals ### Q1 - Ship MVP ``` Renders as a map whose center is *Project Kickoff*, with *Vision* and *Goals* as branches, *Q1* as a sub-branch, and the bullets as leaves. ## Options[​](#options "Direct link to Options") The options bar across the top of the editor controls how the map is built: * **Template** — insert one of ten ready-made outlines instead of starting from a blank page. The current outline is replaced when you pick one. * Project Kickoff, Backlog, Brainstorm, API Design, Meeting Notes, Org Chart, Roadmap, Product Launch, Error Handling, Sprint Planning * **Theme** — `Auto` (match Confluence light/dark mode), `Light`, or `Dark`. Auto follows each reader's theme. * **Initial expand** — how much of the map to expand when the page loads: **Expand all**, or Level 1 through Level 5. Levels control how much complexity readers see first. * **Alignment** — `Center` (classic radial mind map) or `Left` (left-aligned, reads more like a document outline). * **Height** — `Auto`, or a fixed `400 / 600 / 800 / 1000 px`. Auto lets the map size itself to its content; a fixed height gives the macro a stable box on the page. The preview always auto-sizes to show the whole map — the **Height** option only affects the saved macro on the page. ## On the page[​](#on-the-page "Direct link to On the page") The saved macro is the same interactive mind map, rendered inline where you placed it: * **Click any node** to expand or collapse its branch. * The map **follows the reader's theme** — light or dark mode — without any extra configuration. * It renders at full width beside your page content and updates the moment you save changes. ## Templates[​](#templates "Direct link to Templates") Ten built-in outlines cover common planning motions — start from one and trim it to your own content: * **Project Kickoff** — vision, goals, scope, risks, team, timeline. * **Backlog** — now/next/later buckets, bugs, tech debt. * **Brainstorm** — multiple idea branches with problem, ideas, owner. * **API Design** — design goals, resources, auth scopes, errors, open questions. * **Meeting Notes** — attendees, updates, decisions, action items. * **Org Chart** — leadership, product engineering, platform, teams. * **Roadmap** — now/next/later with quarters attached to each. * **Product Launch** — focus areas, product, audience, channels, timeline, metrics. * **Error Handling** — error categories, handling by layer (UI/API/data), monitoring. * **Sprint Planning** — goal, capacity, stories by priority, risks, definition of done. ## FAQ[​](#faq "Direct link to FAQ") **Do I need to draw anything?** No. You write Markdown (headings + bullets) and get an interactive mind map. There is no canvas, no shape palette, and no drag-to-connect workflow. **Can I edit the map after saving?** Yes. Double-click the macro to reopen the editor — your Markdown source is preserved, so you continue exactly where you left off, then Save to update the page. **Does it work in dark mode?** Yes. With the default **Auto** theme, the map matches each reader's Confluence light/dark mode. You can also pin a map to Light or Dark regardless of the reader's theme. **How do I control how much of a big map is shown first?** Use **Initial expand**. Set it to a low level (1–3) so readers see the high-level shape first, then click into branches. Set **Expand all** when you want the full tree visible immediately. **Can I use lists as well as headings?** Yes — bullets become leaves in the map. Any level of `#` headings becomes a branch, so `###` level nesting works too. ## Limitations & notes[​](#limitations--notes "Direct link to Limitations & notes") * Markdown is compressed and stored inside the macro. Very large outlines (tens of thousands of compressed characters) hit Confluence's macro size limit — the editor warns before saving; shorten labels, reduce bullet levels, or split the content into two macros. * The page (non-edit) view is intentionally read-focused: zoom and pan are disabled, so the map fills its container cleanly. Interaction on the page is click-to-expand/collapse. * The mind map renders inline on the page; it does not create a separate Confluence attachment or external diagram file. Was this helpful?👍 Yes👎 No --- # Mermaid+ Diagrams for Jira — User Guide Related blog post: [Mermaid 12 in Confluence & Jira: UML use case diagrams](/blog/mermaid-12-confluence-jira.md) ## Overview[​](#overview "Direct link to Overview") Mermaid+ Diagrams for Jira lets you create beautiful diagrams directly on Jira issues using Mermaid syntax. Choose from 30 diagram types, customize colors and fonts, and preview your diagram live before saving. Each diagram is stored on the issue and visible to everyone who can view it. ## Getting Started[​](#getting-started "Direct link to Getting Started") ### Adding a Diagram to an Issue[​](#adding-a-diagram-to-an-issue "Direct link to Adding a Diagram to an Issue") 1. Open any Jira issue 2. Find the **Mermaid+ Diagrams** panel above the Activity section and click the panel icon to add it 3. Click the **+** (Create Diagram) button in the top-right of the panel 4. The editor opens in a fullscreen modal with a three-column layout: * **Left**: Live Preview * **Middle**: Quick Templates * **Right**: Settings + Code Editor 5. Write or paste your Mermaid code in the editor 6. Click **Save** — the diagram is stored on the issue and displayed in the panel ### Editing an Existing Diagram[​](#editing-an-existing-diagram "Direct link to Editing an Existing Diagram") Click the **✏️** (Edit Diagram) button in the top-right of the panel to reopen the editor. All your settings and code are preserved. ### Permissions[​](#permissions "Direct link to Permissions") * **View**: Anyone who can view the issue can see the diagram * **Edit/Create**: Only users with **Edit Issues** permission can create or modify diagrams *** ## Editor[​](#editor "Direct link to Editor") ### Live Preview[​](#live-preview "Direct link to Live Preview") The left column renders your diagram in real-time as you type. Any changes to code or settings are reflected immediately. ### Quick Templates[​](#quick-templates "Direct link to Quick Templates") The middle column provides one-click templates for all 30 supported diagram types. Click any template to load its starter code into the editor. ### Syntax Guide[​](#syntax-guide "Direct link to Syntax Guide") Click the **?** button in the header to open the full syntax reference. Browse 30 diagram types with descriptions and code examples. Hover over any code block and click the insert button to load it into the editor. *** ## Settings[​](#settings "Direct link to Settings") ### Font[​](#font "Direct link to Font") * **Family** — Choose from Inter, Arial, Helvetica, Georgia, or Courier * **Size** — 12px, 14px (default), 16px, 18px, 20px ### Colors[​](#colors "Direct link to Colors") Five customizable colors with visual color pickers: | Color | Affects | | ---------- | --------------------------------------- | | **Node** | Background color of diagram nodes/boxes | | **Text** | Text color inside nodes | | **Border** | Border color of nodes | | **Line** | Edge/arrow line color | | **Bg** | Diagram background color | ### Theme[​](#theme "Direct link to Theme") Mermaid built-in themes: | Theme | Description | | ----------- | ------------------------------------------ | | **Default** | Clean light theme with customizable colors | | **Dark** | Dark background with high-contrast text | | **Forest** | Green-tinted natural color palette | | **Neutral** | Grayscale minimal theme | > Note: The Default theme uses your custom color settings. Other themes apply their own color palette. ### Output Size[​](#output-size "Direct link to Output Size") Controls the displayed size of the diagram in the issue panel: | Size | Scale | | ------- | ------------ | | Small | 0.5x | | Medium | 1x (default) | | Large | 1.5x | | X-Large | 2x | *** ## Dark Mode Support[​](#dark-mode-support "Direct link to Dark Mode Support") The diagram automatically adapts to Jira's dark/light mode: * When you save a diagram, the current Jira theme is recorded * When the issue loads, if the theme has changed, text and background colors are adjusted for readability * The editor preview also adapts to dark mode *** ## Supported Diagram Types[​](#supported-diagram-types "Direct link to Supported Diagram Types") ### Flowchart[​](#flowchart "Direct link to Flowchart") Directed graph diagrams with nodes, arrows, and subgraphs. ``` graph TD A[Start] -->|Yes| B[Process] B --> C{Decision} C -->|Option 1| D[Result 1] C -->|Option 2| E[Result 2] ``` **Directions**: TD (top-down), BT (bottom-up), LR (left-right), RL (right-left) **Node shapes**: `[Square]`, `(Rounded)`, `{Diamond}`, `((Circle))` ### Swimlane[​](#swimlane "Direct link to Swimlane") Cross-functional process diagrams (swimlanes) showing hand-offs between teams or actors. Each top-level `subgraph` becomes a lane; nodes and edges use standard flowchart syntax. Optionally set a direction (`TB`, `LR`, `BT`, `RL`) after the keyword. ``` swimlane-beta LR subgraph Customer order[Place order] receive[Receive delivery] end subgraph Sales review[Review order] confirm[Confirm and invoice] end order --> review review --> confirm confirm --> receive ``` ### Sequence Diagram[​](#sequence-diagram "Direct link to Sequence Diagram") Interaction diagrams showing messages between participants. ``` sequenceDiagram participant Alice participant Bob Alice->>Bob: Hello Bob Bob-->>Alice: Hi Alice ``` ### Class Diagram[​](#class-diagram "Direct link to Class Diagram") Object-oriented class relationships with inheritance, composition, and visibility. ``` classDiagram Animal <|-- Duck Animal : +int age class Duck { +String beakColor +swim() } ``` ### State Diagram[​](#state-diagram "Direct link to State Diagram") Finite state machines with transitions between states. ``` stateDiagram-v2 [*] --> Idle Idle --> Processing Processing --> Done Done --> [*] ``` ### Entity Relationship Diagram[​](#entity-relationship-diagram "Direct link to Entity Relationship Diagram") Database schema diagrams with entity relationships. ``` erDiagram CUSTOMER ||--o{ ORDER : places ORDER ||--|{ LINE-ITEM : contains ``` ### User Journey[​](#user-journey "Direct link to User Journey") Task satisfaction maps with sentiment scores (1–5). ``` journey title My working day section Morning Make tea: 5: Me Do work: 3: Me ``` ### Gantt Chart[​](#gantt-chart "Direct link to Gantt Chart") Project schedule charts with tasks, dependencies, and milestones. ``` gantt title Project Plan dateFormat YYYY-MM-DD section Phase 1 Research :a1, 2024-01-01, 30d Design :after a1, 20d ``` ### Pie Chart[​](#pie-chart "Direct link to Pie Chart") Proportional data visualization. ``` pie title Time Allocation "Development" : 45 "Testing" : 30 "Meetings" : 25 ``` ### Git Graph[​](#git-graph "Direct link to Git Graph") Git branch and commit history visualization. ``` gitGraph commit branch develop checkout develop commit checkout main merge develop commit ``` ### Mindmap[​](#mindmap "Direct link to Mindmap") Hierarchical tree diagrams for brainstorming. ``` mindmap root((Central Topic)) Branch A Sub-topic 1 Branch B Sub-topic 2 ``` ### Timeline[​](#timeline "Direct link to Timeline") Chronological event sequences. ``` timeline title History section 2020 Event A : Description section 2021 Event B : Description ``` ### Requirement Diagram[​](#requirement-diagram "Direct link to Requirement Diagram") Requirements traceability diagrams linking requirements to elements. ``` requirementDiagram requirement test_req { id: 1 text: the test text. risk: high verifymethod: test } element test_entity { type: simulation } test_entity - satisfies -> test_req ``` ### C4 Diagram[​](#c4-diagram "Direct link to C4 Diagram") Software architecture diagrams following the C4 model. ``` C4Context title System Context Person(user, "User") System(app, "Application") Rel(user, app, "Uses") ``` ### Quadrant Chart[​](#quadrant-chart "Direct link to Quadrant Chart") Two-axis categorization charts. ``` quadrantChart title Analysis x-axis Low --> High y-axis Low --> High quadrant-1 Expand quadrant-2 Promote Item A: [0.3, 0.6] Item B: [0.7, 0.4] ``` ### Cynefin[​](#cynefin "Direct link to Cynefin") Dave Snowden's sense-making framework that categorizes problems into five domains: `clear`, `complicated`, `complex`, `chaotic`, and `confusion` (center). Each domain holds quoted-string items; optional top-level transitions show how situations move between domains. ``` cynefin-beta title Where does this problem sit? complex "Probe - run safe-to-fail experiments" complicated "Analyze - apply expert knowledge" clear "Respond - apply best practice" chaotic "Act - stabilize first" confusion "Break the problem down" clear --> chaotic : "Complacency" chaotic --> complex : "Stabilized" ``` ### Sankey Diagram[​](#sankey-diagram "Direct link to Sankey Diagram") Flow diagrams showing quantities through a system. ``` sankey-beta Source,Target,100 Source,Other,50 ``` ### XY Chart[​](#xy-chart "Direct link to XY Chart") Bar and line charts. ``` xychart-beta title "Revenue" x-axis [Q1, Q2, Q3, Q4] y-axis "USD" 0 --> 100 bar [30, 45, 60, 80] line [32, 48, 62, 78] ``` ### Block Diagram[​](#block-diagram "Direct link to Block Diagram") Block diagrams with columns layout. ``` block-beta columns 1 db(("DB")) block:ID A["Block A"] B["Block B"] end ID --> db ``` ### Packet Diagram[​](#packet-diagram "Direct link to Packet Diagram") Network packet structure diagrams. ``` packet-beta 0-15: "Source Port" 16-31: "Destination Port" 32-63: "Sequence Number" ``` ### Kanban Board[​](#kanban-board "Direct link to Kanban Board") Board-style task organization. ``` kanban To Do Task 1 In Progress Task 2 Done Task 3 ``` ### Architecture Diagram[​](#architecture-diagram "Direct link to Architecture Diagram") Infrastructure and service architecture. ``` architecture-beta group api(cloud)[API] service db(database)[Database] in api service server(server)[Server] in api db:L -- R:server ``` ### Radar Chart[​](#radar-chart "Direct link to Radar Chart") Multi-axis comparison charts. ``` radar-beta axis Math, Science, English curve Alice{85, 90, 80} curve Bob{70, 75, 85} max 100 ``` ### TreeView[​](#treeview "Direct link to TreeView") File/folder tree visualization. ``` treeView-beta "root" "src" "index.ts" "test" "index.test.ts" ``` ### Treemap[​](#treemap "Direct link to Treemap") Hierarchical data as nested rectangles. ``` treemap "Category A" "Item 1" : 10 "Item 2" : 20 ``` ### Ishikawa (Fishbone)[​](#ishikawa-fishbone "Direct link to Ishikawa (Fishbone)") Cause-and-effect diagrams. ``` ishikawa Problem Statement Category A Cause 1 Category B Cause 2 ``` ### Venn Diagram[​](#venn-diagram "Direct link to Venn Diagram") Set relationship diagrams. ``` venn-beta title "Team Skills" set Frontend set Backend union Frontend,Backend["Fullstack"] ``` ### ZenUML[​](#zenuml "Direct link to ZenUML") Sequence diagrams using ZenUML syntax with participant types. ``` zenuml title Service Flow Actor User Database API User->API: Request API->User: Response ``` ### Railroad[​](#railroad "Direct link to Railroad") Syntax/grammar (railroad) diagrams for technical writers and language designers. Ships the EBNF variant — terminals in quotes, `|` choice, `?` optional, `*` zero-or-more, `+` one-or-more, `( )` grouping. One rule per statement, each ending with `;`. ``` railroad-ebnf-beta title "Arithmetic Expression Grammar" expression = term ( ( "+" | "-" ) term )* ; term = factor ( ( "*" | "/" ) factor )* ; factor = number | "(" expression ")" ; number = digit+ ; digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ; ``` *** ## Tips[​](#tips "Direct link to Tips") * Use the **Syntax Guide** (**?** button) to quickly find the right syntax for any diagram type * Start with a **Quick Template** and modify it to fit your needs * Use **Dark** or **Forest** themes for issues viewed in dark-themed Jira spaces * Adjust **Output Size** to control how large the diagram appears in the panel * All settings are preserved when you re-edit an existing diagram *** ## Performance[​](#performance "Direct link to Performance") Diagrams render instantly on issue load using cached SVG. The Mermaid.js library is only loaded during editing — not when viewing issues. This keeps your Jira issues fast. *** ## Support[​](#support "Direct link to Support") For issues or feature requests, please visit the app's listing on the Atlassian Marketplace. Was this helpful?👍 Yes👎 No --- # Mermaid Plus Diagrams & AI Agent for Confluence — User Guide Related blog post: [Create Mermaid diagrams in Confluence: a step-by-step guide](/blog/create-mermaid-diagrams-confluence.md) · [Mermaid 12 in Confluence & Jira: UML use case diagrams](/blog/mermaid-12-confluence-jira.md) ## Overview[​](#overview "Direct link to Overview") Mermaid Plus Diagrams & AI Agent for Confluence lets you create beautiful diagrams directly in Confluence pages using Mermaid syntax. Choose from 30 Mermaid v12 diagram types, customize colors and fonts, and preview your diagram live before saving. A Rovo AI agent can also create, read, update, and convert diagrams from chat — see [Rovo AI Agent](#rovo-ai-agent). ## Getting Started[​](#getting-started "Direct link to Getting Started") ### Inserting a Diagram[​](#inserting-a-diagram "Direct link to Inserting a Diagram") 1. Edit a Confluence page 2. Type `/mermaid` in the editor and select **Mermaid Plus Diagrams & AI Agent for Confluence** 3. The configuration panel opens with a three-column layout: * **Left**: Live Preview * **Middle**: Quick Templates * **Right**: Settings + Code Editor 4. Write or paste your Mermaid code in the editor 5. Click **Save** to insert the diagram ### Re-editing a Diagram[​](#re-editing-a-diagram "Direct link to Re-editing a Diagram") Click on an existing diagram macro and select **Edit** to reopen the configuration panel. All your settings and code are preserved. *** ## Configuration Panel[​](#configuration-panel "Direct link to Configuration Panel") ### Live Preview[​](#live-preview "Direct link to Live Preview") The left column renders your diagram in real-time as you type. Any changes to code or settings are reflected immediately. ### Quick Templates[​](#quick-templates "Direct link to Quick Templates") The middle column provides one-click templates for all 30 supported diagram types. Click any template to load its code into the editor. ### Syntax Guide[​](#syntax-guide "Direct link to Syntax Guide") Click the **Help** button in the header to open the full syntax reference. Browse 30 diagram types with descriptions and code examples. Hover over any code block and click the insert button to load it into the editor. *** ## Settings[​](#settings "Direct link to Settings") ### Font[​](#font "Direct link to Font") * **Family** — Choose from Inter, Arial, Helvetica, Georgia, or Courier * **Size** — 12px, 14px (default), 16px, 18px, 20px ### Colors[​](#colors "Direct link to Colors") Five customizable colors with visual color pickers: | Color | Affects | | ---------- | --------------------------------------- | | **Node** | Background color of diagram nodes/boxes | | **Text** | Text color inside nodes | | **Border** | Border color of nodes | | **Line** | Edge/arrow line color | | **Bg** | Diagram background color | ### Theme[​](#theme "Direct link to Theme") Mermaid built-in themes: | Theme | Description | | ----------- | ------------------------------------------ | | **Default** | Clean light theme with customizable colors | | **Dark** | Dark background with high-contrast text | | **Forest** | Green-tinted natural color palette | | **Neutral** | Grayscale minimal theme | > Note: The Default theme uses your custom color settings. Other themes apply their own color palette. ### Output Size[​](#output-size "Direct link to Output Size") Controls the displayed size of the diagram in the Confluence page: | Size | Scale | | ------- | ------------ | | Small | 0.5x | | Medium | 1x (default) | | Large | 1.5x | | X-Large | 2x | *** ## Dark Mode Support[​](#dark-mode-support "Direct link to Dark Mode Support") The macro automatically adapts to Confluence's dark/light mode: * When you save a diagram, the current Confluence theme is recorded * When the page loads, if the theme has changed, text and background colors are adjusted for readability * The config preview also adapts to dark mode *** ## Supported Diagram Types[​](#supported-diagram-types "Direct link to Supported Diagram Types") ### Flowchart[​](#flowchart "Direct link to Flowchart") Directed graph diagrams with nodes, arrows, and subgraphs. ``` graph TD A[Start] -->|Yes| B[Process] B --> C{Decision} C -->|Option 1| D[Result 1] C -->|Option 2| E[Result 2] ``` **Directions**: TD (top-down), BT (bottom-up), LR (left-right), RL (right-left) **Node shapes**: `[Square]`, `(Rounded)`, `{Diamond}`, `((Circle))` ### Swimlane[​](#swimlane "Direct link to Swimlane") Cross-functional process diagrams (swimlanes) showing hand-offs between teams or actors. Each top-level `subgraph` becomes a lane; nodes and edges use standard flowchart syntax. Optionally set a direction (`TB`, `LR`, `BT`, `RL`) after the keyword. ``` swimlane-beta LR subgraph Customer order[Place order] receive[Receive delivery] end subgraph Sales review[Review order] confirm[Confirm and invoice] end order --> review review --> confirm confirm --> receive ``` ### Sequence Diagram[​](#sequence-diagram "Direct link to Sequence Diagram") Interaction diagrams showing messages between participants. ``` sequenceDiagram participant Alice participant Bob Alice->>Bob: Hello Bob Bob-->>Alice: Hi Alice ``` **Arrow types**: `->>` (solid), `-->>` (dashed), `--)` (async) ### Class Diagram[​](#class-diagram "Direct link to Class Diagram") Object-oriented class relationships with inheritance, composition, and visibility. ``` classDiagram Animal <|-- Duck Animal : +int age class Duck { +String beakColor +swim() } ``` ### State Diagram[​](#state-diagram "Direct link to State Diagram") Finite state machines with transitions between states. ``` stateDiagram-v2 [*] --> Idle Idle --> Processing Processing --> Done Done --> [*] ``` ### Entity Relationship Diagram[​](#entity-relationship-diagram "Direct link to Entity Relationship Diagram") Database schema diagrams with entity relationships. ``` erDiagram CUSTOMER ||--o{ ORDER : places ORDER ||--|{ LINE-ITEM : contains ``` ### User Journey[​](#user-journey "Direct link to User Journey") Task satisfaction maps with sentiment scores (1–5). ``` journey title My working day section Morning Make tea: 5: Me Do work: 3: Me section Evening Go home: 5: Me ``` ### Gantt Chart[​](#gantt-chart "Direct link to Gantt Chart") Project schedule charts with tasks, dependencies, and milestones. ``` gantt title Project Plan dateFormat YYYY-MM-DD section Phase 1 Research :a1, 2024-01-01, 30d Design :after a1, 20d ``` ### Pie Chart[​](#pie-chart "Direct link to Pie Chart") Proportional data visualization. ``` pie title Time Allocation "Development" : 45 "Testing" : 30 "Meetings" : 25 ``` ### Git Graph[​](#git-graph "Direct link to Git Graph") Git branch and commit history visualization. ``` gitGraph commit branch develop checkout develop commit checkout main merge develop commit ``` ### Mindmap[​](#mindmap "Direct link to Mindmap") Hierarchical tree diagrams for brainstorming. ``` mindmap root((Central Topic)) Branch A Sub-topic 1 Sub-topic 2 Branch B Sub-topic 3 ``` ### Timeline[​](#timeline "Direct link to Timeline") Chronological event sequences. ``` timeline title History section 2020 Event A : Description section 2021 Event B : Description ``` ### Requirement Diagram[​](#requirement-diagram "Direct link to Requirement Diagram") Requirements traceability diagrams linking requirements to elements. ``` requirementDiagram requirement test_req { id: 1 text: the test text. risk: high verifymethod: test } element test_entity { type: simulation } test_entity - satisfies -> test_req ``` ### C4 Diagram[​](#c4-diagram "Direct link to C4 Diagram") Software architecture diagrams following the C4 model. ``` C4Context title System Context Person(user, "User") System(app, "Application") Rel(user, app, "Uses") ``` ### Quadrant Chart[​](#quadrant-chart "Direct link to Quadrant Chart") Two-axis categorization charts. ``` quadrantChart title Analysis x-axis Low --> High y-axis Low --> High quadrant-1 Expand quadrant-2 Promote quadrant-3 Re-evaluate quadrant-4 Improve Item A: [0.3, 0.6] Item B: [0.7, 0.4] ``` ### Cynefin[​](#cynefin "Direct link to Cynefin") Dave Snowden's sense-making framework that categorizes problems into five domains: `clear`, `complicated`, `complex`, `chaotic`, and `confusion` (center). Each domain holds quoted-string items; optional top-level transitions show how situations move between domains. ``` cynefin-beta title Where does this problem sit? complex "Probe - run safe-to-fail experiments" complicated "Analyze - apply expert knowledge" clear "Respond - apply best practice" chaotic "Act - stabilize first" confusion "Break the problem down" clear --> chaotic : "Complacency" chaotic --> complex : "Stabilized" ``` ### Sankey Diagram[​](#sankey-diagram "Direct link to Sankey Diagram") Flow diagrams showing quantities through a system. ``` sankey-beta Source,Target,100 Source,Other,50 Other,Target,30 ``` ### XY Chart[​](#xy-chart "Direct link to XY Chart") Bar and line charts. ``` xychart-beta title "Revenue" x-axis [Q1, Q2, Q3, Q4] y-axis "USD" 0 --> 100 bar [30, 45, 60, 80] line [32, 48, 62, 78] ``` ### Block Diagram[​](#block-diagram "Direct link to Block Diagram") Block diagrams with columns layout. ``` block-beta columns 1 db(("DB")) block:ID A["Block A"] B["Block B"] end ID --> db ``` ### Packet Diagram[​](#packet-diagram "Direct link to Packet Diagram") Network packet structure diagrams. ``` packet-beta 0-15: "Source Port" 16-31: "Destination Port" 32-63: "Sequence Number" ``` ### Kanban Board[​](#kanban-board "Direct link to Kanban Board") Board-style task organization. ``` kanban To Do Task 1 Task 2 In Progress Task 3 Done Task 4 ``` ### Architecture Diagram[​](#architecture-diagram "Direct link to Architecture Diagram") Infrastructure and service architecture. ``` architecture-beta group api(cloud)[API] service db(database)[Database] in api service server(server)[Server] in api db:L -- R:server ``` ### Radar Chart[​](#radar-chart "Direct link to Radar Chart") Multi-axis comparison charts. ``` radar-beta axis Math, Science, English curve Alice{85, 90, 80} curve Bob{70, 75, 85} max 100 ``` ### TreeView[​](#treeview "Direct link to TreeView") File/folder tree visualization. ``` treeView-beta "root" "src" "index.ts" "test" "index.test.ts" ``` ### Treemap[​](#treemap "Direct link to Treemap") Hierarchical data as nested rectangles. ``` treemap "Category A" "Item 1" : 10 "Item 2" : 20 "Category B" "Item 3" : 15 ``` ### Ishikawa (Fishbone)[​](#ishikawa-fishbone "Direct link to Ishikawa (Fishbone)") Cause-and-effect diagrams. ``` ishikawa Problem Statement Category A Cause 1 Cause 2 Category B Cause 3 ``` ### Venn Diagram[​](#venn-diagram "Direct link to Venn Diagram") Set relationship diagrams. ``` venn-beta title "Team Skills" set Frontend set Backend union Frontend,Backend["Fullstack"] ``` ### ZenUML[​](#zenuml "Direct link to ZenUML") Sequence diagrams using ZenUML syntax with participant types. ``` zenuml title Service Flow Actor User Database API User->API: Request API->User: Response ``` **Participant types**: `Actor`, `Database`, `Participant` ### Railroad[​](#railroad "Direct link to Railroad") Syntax/grammar (railroad) diagrams for technical writers and language designers. Ships the EBNF variant — terminals in quotes, `|` choice, `?` optional, `*` zero-or-more, `+` one-or-more, `( )` grouping. One rule per statement, each ending with `;`. ``` railroad-ebnf-beta title "Arithmetic Expression Grammar" expression = term ( ( "+" | "-" ) term )* ; term = factor ( ( "*" | "/" ) factor )* ; factor = number | "(" expression ")" ; number = digit+ ; digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ; ``` *** ## Rovo AI Agent[​](#rovo-ai-agent "Direct link to Rovo AI Agent") The app ships a Rovo agent that works with diagrams on Confluence pages and blog posts. Open the agent chat and ask in plain language: | Capability | Example prompt | What happens | | ----------- | -------------------------------------------- | -------------------------------------------------------------- | | **Create** | "Make a flowchart of our deployment process" | A rendered diagram is added in place | | **Read** | "What does this diagram show?" | The diagram source and version come back in chat | | **Update** | "Make this better" | The diagram is revised in place — macro settings are preserved | | **Convert** | "Turn this into a diagram" | Code blocks already on the page become rendered diagrams | The agent edits the same macros you would edit by hand, so anything it changes stays a normal, re-editable diagram. *** ## Tips[​](#tips "Direct link to Tips") * Use the **Syntax Guide** (Help button) to quickly find the right syntax for any diagram type * Start with a **Quick Template** and modify it to fit your needs * Use **Dark** or **Forest** themes for diagrams in dark-themed Confluence spaces * Adjust **Output Size** to control how large the diagram appears on the page * All settings are preserved when you re-edit an existing diagram *** ## Performance[​](#performance "Direct link to Performance") Diagrams render instantly on page load using cached SVG. The Mermaid.js library is only loaded during configuration — not when viewing pages. This keeps your Confluence pages fast. *** ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [Create Mermaid diagrams in Confluence: a step-by-step guide](/blog/create-mermaid-diagrams-confluence.md) * [Mermaid in Confluence Not Rendering? Fixes & FAQ](/blog/faq-mermaid-troubleshooting.md) * [Confluence diagram tools compared: Mermaid vs Excalidraw vs Graphviz](/blog/confluence-diagram-tools-comparison.md) * [How to create flowcharts in Confluence](/blog/create-flowcharts-confluence.md) ## Support[​](#support "Direct link to Support") For issues or feature requests, please visit the app's listing on the Atlassian Marketplace. Was this helpful?👍 Yes👎 No --- # Modern Announcement Banner for Jira - User Documentation ## Overview[​](#overview "Direct link to Overview") Modern Announcement Banner for Jira allows administrators to create and manage announcement banners that appear at the top of Jira. Keep your team informed about important updates, maintenance windows, policy changes, or any other critical information. ## Features[​](#features "Direct link to Features") ### Core Functionality[​](#core-functionality "Direct link to Core Functionality") * **Create Unlimited Announcements** - Save multiple announcement messages for quick reuse * **Instant Enable/Disable** - Turn announcements on or off without deleting them * **Dismissible Banners** - Let users close banners or keep them persistent * **Visibility Control** - Choose between public and private visibility * **Announcement History** - Keep a library of saved announcements * **One-Click Switching** - Quickly switch between saved announcements ### User Experience[​](#user-experience "Direct link to User Experience") * Banners appear at the top of every Jira page * Clean, non-intrusive design matches Jira's interface * Dismissible banners can be closed by users * Persistent banners remain visible until disabled by admin ## Getting Started[​](#getting-started "Direct link to Getting Started") ### Prerequisites[​](#prerequisites "Direct link to Prerequisites") * Jira Cloud instance * Jira Administrator permissions * Modern Announcement Banner app installed from Atlassian Marketplace ### Accessing the App[​](#accessing-the-app "Direct link to Accessing the App") 1. Log in to Jira as an administrator 2. Click the Apps **More Actions** icon (⚙️) in the top navigation 3. Select **Manage Apps** from the dropdown 4. Click **Modern Announcement Banner for Jira** in the left sidebar ## Creating Announcements[​](#creating-announcements "Direct link to Creating Announcements") ### Create a New Announcement[​](#create-a-new-announcement "Direct link to Create a New Announcement") 1. Click the **New announcement** button 2. Enter your announcement message in the text area 3. Configure settings: * **Enabled** - Check to display the banner immediately * **Dismissible** - Check to allow users to close the banner * **Visibility** - Choose Public or Private 4. Click **Create** ### Announcement Settings Explained[​](#announcement-settings-explained "Direct link to Announcement Settings Explained") **Enabled** * ✅ Checked: Banner displays immediately on all Jira pages * ☐ Unchecked: Banner is saved but not displayed **Dismissible** * ✅ Checked: Users can close the banner (won't see it again in their session) * ☐ Unchecked: Banner remains visible until admin disables it **Visibility** * **Public**: Banner visible to all users * **Private**: Banner follows Jira's privacy settings ### Message Guidelines[​](#message-guidelines "Direct link to Message Guidelines") **Best Practices:** * Keep messages concise (under 200 characters recommended) * Use clear, actionable language * Include relevant dates/times for time-sensitive announcements * Avoid technical jargon when possible **Examples:** * ✅ "Scheduled maintenance: Jira will be unavailable Saturday 2-4 AM EST" * ✅ "New policy: All issues must include time estimates starting Monday" * ✅ "Welcome to the new Jira workspace! Check out our getting started guide" * ❌ "System update" (too vague) * ❌ "URGENT!!!! READ THIS NOW!!!!" (too aggressive) **Limitations:** * Plain text only (no HTML or formatting) * No images or links * No rich text formatting ## Managing Announcements[​](#managing-announcements "Direct link to Managing Announcements") ### View All Announcements[​](#view-all-announcements "Direct link to View All Announcements") The main interface displays a table with all your saved announcements: | Column | Description | | --------------- | ---------------------------------- | | **Message** | The announcement text | | **Visibility** | Public or Private | | **Status** | Enabled (green) or Disabled (gray) | | **Dismissible** | Yes or No | | **Actions** | Edit and Enable buttons | ### Edit an Announcement[​](#edit-an-announcement "Direct link to Edit an Announcement") 1. Click **Edit** on the announcement you want to modify 2. Update the message or settings 3. Click **Save** **Note:** Changes take effect immediately if the announcement is enabled. ### Enable a Saved Announcement[​](#enable-a-saved-announcement "Direct link to Enable a Saved Announcement") 1. Find the announcement in the table 2. Click **Enable** 3. The banner appears immediately on all Jira pages **Important:** Only one announcement can be active at a time. Enabling a new announcement automatically disables the current one. ### Disable an Announcement[​](#disable-an-announcement "Direct link to Disable an Announcement") 1. Edit the announcement 2. Uncheck **Enabled** 3. Click **Save** The banner is removed from all Jira pages immediately. ### Delete an Announcement[​](#delete-an-announcement "Direct link to Delete an Announcement") Currently, announcements cannot be deleted. You can disable them to remove them from view while keeping them in your history for future use. ## Use Cases[​](#use-cases "Direct link to Use Cases") ### System Maintenance Notifications[​](#system-maintenance-notifications "Direct link to System Maintenance Notifications") **Scenario:** Scheduled maintenance window **Example:** ``` Message: "Scheduled maintenance: Jira will be unavailable Saturday, Jan 15, 2-4 AM EST. Plan accordingly." Enabled: ✅ Dismissible: ☐ (Keep visible) Visibility: Public ``` **Timing:** * Enable 1 week before maintenance * Update with countdown as date approaches * Disable after maintenance completes ### Policy Updates[​](#policy-updates "Direct link to Policy Updates") **Scenario:** New team policy announcement **Example:** ``` Message: "New policy effective Feb 1: All bugs must include reproduction steps. See wiki for details." Enabled: ✅ Dismissible: ✅ (Users can dismiss after reading) Visibility: Public ``` ### Event Notifications[​](#event-notifications "Direct link to Event Notifications") **Scenario:** Company event or deadline **Example:** ``` Message: "Reminder: Q1 planning submissions due Friday, Jan 20. Submit your proposals in Confluence." Enabled: ✅ Dismissible: ✅ Visibility: Public ``` ### Emergency Alerts[​](#emergency-alerts "Direct link to Emergency Alerts") **Scenario:** Urgent issue affecting team **Example:** ``` Message: "URGENT: Production incident in progress. All hands on deck. Check #incident-response Slack." Enabled: ✅ Dismissible: ☐ (Keep visible) Visibility: Public ``` ### Onboarding Messages[​](#onboarding-messages "Direct link to Onboarding Messages") **Scenario:** Welcome message for new team members **Example:** ``` Message: "Welcome to Jira! New to the team? Check out our onboarding guide in Confluence." Enabled: ✅ Dismissible: ✅ Visibility: Public ``` ## Tips & Best Practices[​](#tips--best-practices "Direct link to Tips & Best Practices") ### Message Writing[​](#message-writing "Direct link to Message Writing") 1. **Be Concise** - Users scan banners quickly 2. **Be Specific** - Include dates, times, and actions 3. **Be Clear** - Avoid ambiguity or technical jargon 4. **Be Actionable** - Tell users what to do or where to go ### Banner Management[​](#banner-management "Direct link to Banner Management") 1. **Save Templates** - Create reusable announcements for common scenarios 2. **Update Regularly** - Keep time-sensitive announcements current 3. **Use Dismissible Wisely** - One-time announcements should be dismissible 4. **Test First** - Preview how your message looks before enabling ### Timing[​](#timing "Direct link to Timing") 1. **Advance Notice** - Enable maintenance announcements well in advance 2. **Remove Promptly** - Disable announcements when no longer relevant 3. **Avoid Banner Fatigue** - Don't keep banners up too long 4. **Coordinate** - Align with other communication channels ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") ### Banner Not Appearing[​](#banner-not-appearing "Direct link to Banner Not Appearing") **Possible Causes:** * Announcement is not enabled * Browser cache needs clearing * User has dismissed a dismissible banner **Solutions:** 1. Verify announcement is enabled in the admin interface 2. Ask users to refresh their browser (Ctrl+F5 or Cmd+Shift+R) 3. For dismissible banners, users need to clear cookies or use incognito mode ### Changes Not Showing[​](#changes-not-showing "Direct link to Changes Not Showing") **Solution:** * Changes take effect immediately * Users may need to refresh their browser * Check that you clicked "Save" after editing ### Can't Create Announcement[​](#cant-create-announcement "Direct link to Can't Create Announcement") **Possible Causes:** * License issue * Permission issue * Network connectivity **Solutions:** 1. Verify you have a valid license 2. Confirm you have Jira Administrator permissions 3. Check browser console for errors 4. Contact support if issue persists ### Multiple Banners Showing[​](#multiple-banners-showing "Direct link to Multiple Banners Showing") **Note:** This shouldn't happen - only one banner can be active at a time. **If it occurs:** 1. Disable all announcements 2. Enable only the one you want 3. Contact support if issue persists ## Frequently Asked Questions[​](#frequently-asked-questions "Direct link to Frequently Asked Questions") **Q: How many announcements can I create?** A: Unlimited. You can save as many announcements as you need. **Q: Can I schedule announcements to enable/disable automatically?** A: Not in the current version. You must manually enable/disable announcements. **Q: Will the banner show on mobile?** A: Yes, banners appear on all Jira interfaces including mobile. **Q: Can I target specific users or groups?** A: Not directly. Use the Public/Private visibility setting, but targeting specific users isn't supported. **Q: What happens if I uninstall the app?** A: Your saved announcements are preserved in Forge storage. If you reinstall, they'll still be there. **Q: Can I use emojis in announcements?** A: Yes, emojis are supported as they're part of plain text. **Q: Is there an API?** A: The app uses Jira's announcement banner API. There's no separate API for the app itself. **Q: Can I see who dismissed a banner?** A: No, dismissal is handled client-side and not tracked. ## Support[​](#support "Direct link to Support") ### Getting Help[​](#getting-help "Direct link to Getting Help") **Support Email:** ### Reporting Issues[​](#reporting-issues "Direct link to Reporting Issues") When reporting issues, please include: 1. Jira Cloud URL 2. Steps to reproduce 3. Expected vs actual behavior 4. Screenshots if applicable 5. Browser and version ### Feature Requests[​](#feature-requests "Direct link to Feature Requests") We welcome feature requests! Please submit them via: * Support email () * Atlassian Marketplace reviews * Community forum ## Changelog[​](#changelog "Direct link to Changelog") ### Version 1.0.0 (Initial Release)[​](#version-100-initial-release "Direct link to Version 1.0.0 (Initial Release)") * Create and manage announcement banners * Enable/disable functionality * Dismissible banner option * Public/private visibility control * Announcement history management * Simple admin interface ## Privacy & Security[​](#privacy--security "Direct link to Privacy & Security") ### Data Storage[​](#data-storage "Direct link to Data Storage") * Announcements are stored in Forge secure storage * No data is sent to external servers * Data is encrypted at rest ### Permissions[​](#permissions "Direct link to Permissions") * App requires `manage:jira-configuration` scope * Only Jira administrators can access the app * Users cannot modify announcements ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [Jira announcement banner customization FAQ](/blog/faq-jira-announcement-banner-customization.md) * [Best Confluence apps for developers](/blog/best-confluence-apps-developers.md) Was this helpful?👍 Yes👎 No --- # Modern Code Blocks for Confluence — User Guide Related blog post: [Advanced code blocks in Confluence with Modern Code Blocks](/blog/advanced-code-blocks-confluence.md) ## Overview[​](#overview "Direct link to Overview") **Modern Code Blocks for Confluence** is a Forge app that inserts beautifully rendered code snippets with syntax highlighting powered by the Monaco Editor (the same engine behind VS Code). It supports 85+ languages, automatic dark/light theme matching, optional 50+ premium themes, a diff view for comparing two versions of a code sample side by side, and optional terminal-style window chrome (macOS / Windows) to make snippets feel screenshot-ready. The app ships in two editions — see [Editions](#editions) below. *** ## Editions[​](#editions "Direct link to Editions") | | Standard | Advanced | | ------------------------------------------------------------- | -------- | -------- | | Syntax highlighting (85+ languages) | ✅ | ✅ | | Auto light/dark + 4 built-in themes | ✅ | ✅ | | **50+ premium themes** (Monokai, Dracula, Nord, Solarized, …) | — | ✅ | | **Diff View** (raw patch + inline render modes) | — | ✅ | | Separate diff theme | — | ✅ | | **Window Chrome** (macOS / Windows title bar) | — | ✅ | Both editions are installed by the same Marketplace listing. The edition a site receives is controlled by the license tier purchased in the Atlassian Marketplace. **Trial licenses unlock all Advanced features** for the duration of the trial. If a Standard user opens a code block that was configured with Advanced features (e.g. a diff block created during a trial), the block shows an upgrade prompt instead of the diff — no broken rendering. *** ## Installing[​](#installing "Direct link to Installing") Install the app from the Atlassian Marketplace. Once installed, the macro is available in the Confluence macro browser under the name **Modern Code Blocks for Confluence**. *** ## Getting Started[​](#getting-started "Direct link to Getting Started") ### Inserting a Code Block[​](#inserting-a-code-block "Direct link to Inserting a Code Block") 1. Edit a Confluence page 2. Type `/code` or `/modern` in the editor and select **Modern Code Blocks for Confluence** 3. The configuration panel opens — write or paste your code in the Monaco editor on the left 4. Adjust settings in the sidebar on the right 5. Click **Save** The rendered code block appears inline on the page. ### Re-editing a Code Block[​](#re-editing-a-code-block "Direct link to Re-editing a Code Block") Click on an existing code block and select **Edit** to reopen the configuration panel. All your code and settings are preserved. *** ## Configuration Options[​](#configuration-options "Direct link to Configuration Options") | Option | Description | Default | Values | | -------------------------------- | ----------------------------------------------- | ---------- | -------------------------------------------------- | | **View Mode** | Single code block, or diff view (Advanced only) | Single | Single, Diff *(Advanced)* | | **Language** | Syntax highlighting language | Plain Text | 85+ languages (see list below) | | **Theme** | Color theme for the code block | Auto | Auto, 4 built-ins, 50+ premium themes *(Advanced)* | | **Render Mode** *(Diff only)* | How the diff is rendered to readers | Raw | Raw, Inline | | **Max Height** | Maximum block height in pixels before scrolling | 600 | 100–5000 | | **Font Size** | Code font size in pixels | 14 | 8–32 | | **Line Numbers** | Line number display mode | On | On, Off, Relative | | **Word Wrap** | Wrap long lines | On | On, Off | | **Show Minimap** | Show a code minimap overview | Off | On / Off | | **Window Style** *(Single only)* | Terminal-style window chrome around the block | None | None, macOS, Windows *(Advanced)* | When **View Mode = Diff**, the Theme selector controls the diff theme independently from any single-view blocks on the same page. ### Theme Behavior[​](#theme-behavior "Direct link to Theme Behavior") * **Auto** — automatically matches the reader's Confluence theme (light or dark). When Confluence is in dark mode, the code block renders in VS Code Dark; in light mode, it uses VS Code Light. * **Light** — always uses the VS Code Light theme. * **Dark** — always uses the VS Code Dark theme. * **High Contrast** — always uses the High Contrast Black theme. * **Premium themes** *(Advanced)* — 50+ curated themes including Monokai, Dracula, Nord, Solarized Light/Dark, GitHub Dark, One Dark Pro, Material, Cobalt2, and more. Themes are bundled with the app (no CDN calls) and lazy-loaded on first use. For Standard users, premium theme selections are visible in the dropdown but revert silently to Auto if chosen — no error. ### Diff View (Advanced)[​](#diff-view-advanced "Direct link to Diff View (Advanced)") Diff View lets you embed a code change — a `.patch` / `.diff` file, or pasted unified diff — rendered as a colored, line-by-line comparison. Useful for migration guides, changelogs, and refactoring notes. **To configure a diff block:** 1. Set **View Mode** to **Diff** 2. Either paste a unified diff into the editor, or click **Upload .patch / .diff** to load a file 3. Pick a **Render Mode** (see below) 4. Optionally choose a separate **Theme** for the diff 5. Click **Save** **Render Modes:** * **Raw** — the patch text rendered as-is, with `+` lines green and `-` lines red (GitHub-style). * **Inline** — the patch parsed and re-rendered as a single interleaved view: unchanged lines, then removed lines in red, then added lines in green — the layout `git diff` produces. The macro view itself has no toolbar — the author's chosen render mode is what every reader sees, so the block renders consistently for everyone. ### Window Chrome (Advanced)[​](#window-chrome-advanced "Direct link to Window Chrome (Advanced)") Window Chrome wraps your single-view code block in an optional OS-style title bar — the same look popularized by [carbon.now.sh](https://carbon.now.sh) and [ray.so](https://ray.so). It makes snippets feel screenshot-ready and visually distinct on the page. **To configure window chrome:** 1. Set **View Mode** to **Single** (chrome is not available in Diff mode) 2. Pick a **Window Style**: * **None** — no chrome (default) * **macOS** — three traffic-light buttons (red / yellow / green) on the left * **Windows** — three caption buttons (minimize / maximize / close) on the right 3. Click **Save** The title bar shows a filename **auto-derived from your selected language** — for example, `main.js` for JavaScript, `script.sh` for Shell, `Dockerfile` for Dockerfile. No manual title entry needed. The chrome palette adapts to your code theme automatically: light title bar for light themes (Solarized Light, GitHub Light), dark title bar for dark themes (Monokai, Dracula, VS Code Dark). For Standard users, the macOS and Windows options appear disabled in the dropdown under an "Enabled in Advanced Edition" group. Existing blocks saved with chrome render without it for Standard viewers — no broken UI, just the plain code block. ### Auto-Height[​](#auto-height "Direct link to Auto-Height") Code blocks automatically expand to fit their content, up to the configured **Max Height**. If the code is shorter than the max height, the block shrinks to fit — no unnecessary whitespace. If the code exceeds the max height, vertical scrolling is enabled. *** ## Supported Languages[​](#supported-languages "Direct link to Supported Languages") The app supports syntax highlighting for the following languages: ABAP, Apex, Azure CLI, Batch, Bicep, Cameligo, Clojure, CoffeeScript, C++, C#, CSP, CSS, Cypher, Dart, Dockerfile, ECL, Elixir, Flow9, FreeMarker, F#, Go, GraphQL, Handlebars, HCL, HTML, INI, Java, JavaScript, JSON, Julia, Kotlin, Less, Lexon, Liquid, Lua, M3, Markdown, MDX, MIPS, MS DAX, MySQL, Objective-C, Pascal, Pascaligo, Perl, PostgreSQL, PHP, PLA, Postiats, Power Query, PowerShell, Protocol Buffers, Pug, Python, Q#, R, Razor, Redis, Redshift, reStructuredText, Ruby, Rust, SB, Scala, Scheme, SCSS, Shell / Bash, Solidity, Sophia, SPARQL, SQL, ST, Swift, SystemVerilog, Tcl, Terraform, Twig, TypeSpec, TypeScript, Visual Basic, Verilog, WGSL, XML, YAML. *** ## Font[​](#font "Direct link to Font") The code block uses a monospace font stack optimized for code readability and ligature support: > JetBrains Mono, Fira Code, Source Code Pro, Cascadia Code, Consolas, Courier New Font ligatures are enabled by default. Supported browsers will render combined characters like `=>`, `!==`, and `>=` as single glyphs when using a ligature-capable font (e.g., JetBrains Mono, Fira Code). *** ## Keyboard Shortcuts[​](#keyboard-shortcuts "Direct link to Keyboard Shortcuts") The configuration editor supports standard Monaco Editor shortcuts: | Shortcut | Action | | ---------------------- | --------------------- | | `Ctrl/Cmd + Z` | Undo | | `Ctrl/Cmd + Shift + Z` | Redo | | `Ctrl/Cmd + C` | Copy | | `Ctrl/Cmd + X` | Cut | | `Ctrl/Cmd + V` | Paste | | `Ctrl/Cmd + F` | Find | | `Ctrl/Cmd + H` | Find and Replace | | `Ctrl/Cmd + A` | Select All | | `Tab` | Insert tab (2 spaces) | *** ## Getting Help[​](#getting-help "Direct link to Getting Help") Click the **?** icon in the top-right corner of the configuration panel to open the online documentation. *** ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [Code Blocks for Confluence — Which Syntax Highlighting App?](/blog/code-blocks-confluence-monaco-editor.md) * [Advanced code blocks in Confluence with Modern Code Blocks](/blog/advanced-code-blocks-confluence.md) * [Confluence Code Blocks: Performance Tips & Monaco Editor FAQ](/blog/faq-code-blocks-performance.md) ## Support[​](#support "Direct link to Support") For issues or feature requests, please visit the app's listing on the Atlassian Marketplace. Was this helpful?👍 Yes👎 No --- # How to use Modern FAQ for Confluence 1. type `/Modern FAQ for Confluence` in the Confluence editor 2. Choose a theme (default for the first theme) by clicking the image on the right top of the config page 3. Type into your question title and answer one by one. Click `+` to add new one, `-` to remove the latest one 4. Click `OK` after you finish your config, `Cancel` to discard your changes. 5. Drag-n-Drop to sort FAQ items ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [How to build FAQ sections in Confluence](/blog/how-to-build-faq-sections-confluence.md) * [Confluence page navigation FAQ](/blog/faq-confluence-page-navigation-apps.md) Was this helpful?👍 Yes👎 No --- # Modern Importer & Exporter for Confluence - User Guide ## Table of Contents[​](#table-of-contents "Direct link to Table of Contents") * [Introduction](#introduction) * [Features Overview](#features-overview) * [Getting Started](#getting-started) * [Export Content](#export-content) * [Import Content](#import-content) * [Supported Formats](#supported-formats) * [Best Practices](#best-practices) * [Troubleshooting](#troubleshooting) * [FAQ](#faq) ## Introduction[​](#introduction "Direct link to Introduction") **Modern Importer & Exporter for Confluence** makes it easy to export and import your Confluence content. Export pages with their images included, import Word documents, spreadsheets, or entire folder structures, and choose from multiple formats — all with a native Confluence look and feel. ### Key Benefits[​](#key-benefits "Direct link to Key Benefits") * **Images and attachments included** — exports bundle images alongside your content * **Multi-format export** — choose Word, Markdown, HTML, JSON, or XML (or all at once) * **Word and spreadsheet import** — import DOCX, XLSX, CSV, Markdown, HTML, and JSON files * **Folder import** — drag a ZIP to import whole folder structures with hierarchy preserved * **Native Confluence experience** — redesigned with Atlaskit components, dark mode support * **Step-by-step wizard** — guided 3-step flow for both import and export * **Real-time feedback** — track progress and see per-file results ## Features Overview[​](#features-overview "Direct link to Features Overview") ### Export[​](#export "Direct link to Export") * Browse and select pages from any space * Export to one format or bundle multiple formats in a single ZIP * Images are downloaded and included in the export * Organized by space with a manifest file listing everything exported ### Import[​](#import "Direct link to Import") * Drag and drop files or a ZIP archive * Folder structures are preserved with a tree preview * 3-step wizard: upload files, choose target space, review and confirm * Per-file success/error results ### Two Ways to Access[​](#two-ways-to-access "Direct link to Two Ways to Access") * **Global Page**: Apps > Modern Importer & Exporter — full wizard experience * **Content Action**: Right-click any page or blog post — quick single-item export/import ## Getting Started[​](#getting-started "Direct link to Getting Started") ### Installation[​](#installation "Direct link to Installation") 1. Install from the Atlassian Marketplace 2. The app appears in two places: * **Global Page**: Apps > Modern Importer & Exporter for Confluence * **Content Action**: Right-click menu on any page or blog post ### First Use[​](#first-use "Direct link to First Use") 1. Navigate to **Apps** > **Modern Importer & Exporter for Confluence** 2. You'll see tabs for **Export** and **Import** 3. Try a small test export to get familiar with the flow ## Export Content[​](#export-content "Direct link to Export Content") ### From the Global Page[​](#from-the-global-page "Direct link to From the Global Page") #### Step 1: Select a Space[​](#step-1-select-a-space "Direct link to Step 1: Select a Space") 1. Choose a space from the dropdown 2. Browse the content table showing pages and blog posts 3. Check the items you want to export #### Step 2: Choose Formats[​](#step-2-choose-formats "Direct link to Step 2: Choose Formats") 1. Select one or more export formats: * **Word (DOCX)** — for editing in Word, Pages, or Google Docs * **Markdown** — for technical docs and GitHub wikis * **HTML** — for web publishing * **JSON** — for data processing or Confluence re-import 2. Multiple formats are bundled together in one ZIP #### Step 3: Export[​](#step-3-export "Direct link to Step 3: Export") 1. Click **Export** 2. Progress is shown inline 3. The ZIP downloads automatically when done 4. Open the ZIP to find content organized by space, with images in an `attachments/` folder ### What's in the Export ZIP[​](#whats-in-the-export-zip "Direct link to What's in the Export ZIP") ``` confluence-export-SpaceName-formats-date.zip ├── MARKDOWN/ │ └── SpaceName/ │ ├── Page-Title.md │ └── attachments/ │ └── image.png ├── DOCX/ │ └── SpaceName/ │ └── Page-Title.docx ├── ADF-JSON/ │ └── SpaceName/ │ └── Page-Title.json └── export-manifest.json ``` ### From the Content Action (Quick Export)[​](#from-the-content-action-quick-export "Direct link to From the Content Action (Quick Export)") 1. Right-click any page or blog post 2. Select **Modern Importer & Exporter** 3. Choose your format and click Export 4. Download starts automatically ## Import Content[​](#import-content "Direct link to Import Content") ### From the Global Page[​](#from-the-global-page-1 "Direct link to From the Global Page") #### Step 1: Upload Files[​](#step-1-upload-files "Direct link to Step 1: Upload Files") 1. Switch to the **Import** tab 2. Drag files or a ZIP onto the drop zone, or click to browse 3. For ZIP files, you'll see a folder tree preview 4. Supported formats: JSON, Markdown, HTML #### Step 2: Choose Target Space[​](#step-2-choose-target-space "Direct link to Step 2: Choose Target Space") 1. Select the Confluence space to import into 2. Review the list of files to be imported #### Step 3: Review and Confirm[​](#step-3-review-and-confirm "Direct link to Step 3: Review and Confirm") 1. See a summary of what will be imported 2. Click **Import** 3. Watch per-file results (success or error for each item) ### From the Content Action (Quick Import)[​](#from-the-content-action-quick-import "Direct link to From the Content Action (Quick Import)") 1. Right-click the target page or blog post 2. Select **Modern Importer & Exporter** 3. Switch to the Import tab 4. Upload a file and choose import mode: * **Override** — replace existing content * **Append** — add imported content at the end 5. Click **Import** ## Supported Formats[​](#supported-formats "Direct link to Supported Formats") ### Export Formats[​](#export-formats "Direct link to Export Formats") | Format | File Extension | Best For | | --------------- | -------------- | ---------------------------------------------------- | | **Word (DOCX)** | `.docx` | Editing in Word, Pages, Google Docs | | **Markdown** | `.md` | Technical docs, GitHub wikis, static sites | | **HTML** | `.html` | Web publishing, email templates | | **JSON (ADF)** | `.json` | Backups, data processing, re-importing to Confluence | | **XML** | `.xml` | Data interchange, structured content processing | ### Import Formats[​](#import-formats "Direct link to Import Formats") | Format | Notes | | ---------------- | ------------------------------------------------- | | **Word (DOCX)** | Headings, lists, tables, images preserved | | **Markdown** | Basic formatting converted to Confluence format | | **HTML** | Web content converted to Confluence format | | **JSON (ADF)** | Best compatibility — native Confluence format | | **XML** | Structured content converted to Confluence format | | **Excel (XLSX)** | Spreadsheet rows imported as table data | | **CSV** | Comma-separated data imported as table content | | **ZIP** | Bundle of files — folder structure preserved | ### What Gets Preserved[​](#what-gets-preserved "Direct link to What Gets Preserved") * Headings, paragraphs, lists (ordered and unordered, including nested) * Tables with rows and cells * Bold, italic, and other text formatting * Links and images (including inline images from Word documents) * Panels and info blocks * Folder hierarchy (when importing ZIP archives) ## Best Practices[​](#best-practices "Direct link to Best Practices") ### Before Exporting[​](#before-exporting "Direct link to Before Exporting") * Start with a small test export (5-10 pages) * Check that you have access to the source spaces * Choose formats based on your use case: * Re-importing to Confluence? Use JSON * Editing in Word? Use DOCX * Publishing online? Use HTML or Markdown ### Before Importing[​](#before-importing "Direct link to Before Importing") * Back up existing content if using override mode * Test with a non-critical space first * Use JSON format for best compatibility * Keep individual files under 10 MB ### For Large Operations[​](#for-large-operations "Direct link to For Large Operations") * Export in batches of 50-100 pages * Export each space separately for better organization * Close other browser tabs during large operations * Use a stable internet connection ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") ### Export Issues[​](#export-issues "Direct link to Export Issues") **Export fails with "Permission denied"** * Verify you have read access to the selected spaces * Check space permissions in Confluence settings **Images missing from export** * Ensure the page actually has attached images * Check that images are Confluence attachments (not external URLs) * The export manifest includes attachment debug info — check `export-manifest.json` **Downloaded ZIP is corrupted** * Retry the export * Check your internet connection * Try exporting a single format instead of multiple **DOCX looks wrong in Word/Pages** * Body text should render at 11pt — if not, ensure you're using the latest app version * Complex macros and layouts may be simplified ### Import Issues[​](#import-issues "Direct link to Import Issues") **Import fails with "Invalid format"** * Verify the file format is supported (JSON, Markdown, HTML) * Check the file isn't corrupted * For ZIP imports, ensure files inside are in supported formats **Content looks different after import** * Some formatting may not translate perfectly from Markdown/HTML * JSON (ADF) format gives the best results for Confluence re-import ## FAQ[​](#faq "Direct link to FAQ") **Can I export images and attachments?** Yes. Images attached to Confluence pages are downloaded and bundled in an `attachments/` folder inside the export ZIP for all formats. **Can I import folder structures?** Yes. Upload a ZIP file and the folder hierarchy is preserved. You'll see a tree preview before confirming the import. **What's the maximum number of pages I can export at once?** We recommend batches of 50-100 pages for optimal performance. Larger batches may be slower but will complete. **Can I export from multiple spaces at once?** Yes. Select content from multiple spaces and export everything together. The ZIP is organized by space. **Are page permissions preserved?** No. Permissions are not exported/imported. Set permissions manually after importing. **Does it work in dark mode?** Yes. The app follows your Confluence theme — light or dark. **Can I cancel an export/import?** Currently operations run to completion. Plan exports in manageable batches. *** **Version**: 3.1.0 **Last Updated**: May 2026 Was this helpful?👍 Yes👎 No --- # Modern Issue Templates for Jira - User Guide ## Introduction[​](#introduction "Direct link to Introduction") Modern Issue Templates for Jira is a powerful Forge app that helps Jira administrators create, manage, and automatically apply issue templates across projects. With support for rich text formatting, multi-source imports (JSON, Markdown, GitHub), and automatic template application, you can standardize issue creation and improve team productivity. ## Editions[​](#editions "Direct link to Editions") Modern Issue Templates is sold in two editions on the Atlassian Marketplace. Cloud per-user pricing — free up to 10 users, then a per-user monthly rate that scales down as the team grows (see `pricing.csv` for the full tier breakdown). | Capability | Standard (incl. Free ≤10u) | Advanced | | ------------------------------------------------------------------------ | -------------------------- | -------- | | Template CRUD, rich-text editor, inline editing | ✓ | ✓ | | GitHub / Markdown / JSON import + export | ✓ | ✓ | | Starter Template Library (22 templates) | ✓ | ✓ | | Variables (`{{currentUser}}`, `{{today+7d}}`, etc.) + inline validation | ✓ | ✓ | | Single + multi-project assignment, conflict detection, re-enable | ✓ | ✓ | | **Multi-field pre-fill** (labels, due date, components, customfield\_\*) | — | ✓ | | **Full application log** (last 50, status filter, CSV export) | — | ✓ | | **`{{customfield.X}}` variables** (roadmap — see issue #5) | — | planned | **Pricing** (representative per-user rates — full tiers on the Marketplace listing): | User tier | Standard | Advanced | | --------- | ---------- | ---------- | | 0–10 | Free | Free | | 1–100 | $0.40/user | $0.88/user | | 101–250 | $0.30/user | $0.77/user | | 1001–2500 | $0.15/user | $0.53/user | **Standard users** keep all currently-shipped features except multi-field pre-fill config and the full app log depth. Standard preserves existing field configs on templates (they round-trip through the editor unchanged) but does not auto-apply them at create time. **Advanced users** see everything. The Advanced lozenge in the UI marks gated sections. Development / unlicensed installs (e.g., `forge tunnel`) behave as Advanced — all features available. Real enforcement happens at the Marketplace listing level, not client-side. ## Getting Started[​](#getting-started "Direct link to Getting Started") ### Accessing the Template Manager[​](#accessing-the-template-manager "Direct link to Accessing the Template Manager") 1. Navigate to your Jira site 2. Click on the **Apps** menu in the top navigation 3. Select **Modern Issue Templates** from the dropdown 4. You'll see the template management interface with a table of all your templates ### Understanding the Interface[​](#understanding-the-interface "Direct link to Understanding the Interface") The template manager displays your templates in a table with the following columns: * **Checkbox**: Select templates for bulk export * **Name**: The template's display name * **Summary**: The template text for the issue summary field (editable inline) * **Description**: A preview of the template description (editable inline) * **Projects**: Project keys where this template is assigned * **Actions**: Quick action buttons (Edit, Clone, Delete, Assign) ## Creating Templates[​](#creating-templates "Direct link to Creating Templates") ### Quick Start: Starter Template Library[​](#quick-start-starter-template-library "Direct link to Quick Start: Starter Template Library") New installs can skip authoring from scratch by importing from the curated **Starter Template Library**: 22 pre-built templates across 5 categories (Software Engineering, Operations, Product, Team & People, General). Every template ships with summary + description pre-filled and uses variables like `{{currentUser}}`, `{{today}}`, and `{{projectKey}}` to demonstrate the variable system out of the box. 1. Click **Starter Library** in the template manager toolbar (visible in both the empty state and the table view) 2. Filter by category using the buttons at the top, or browse all 22 templates 3. Select the templates you want — use **Select all visible** to grab an entire category 4. Click **Import N templates** 5. Imported templates appear in your table with no project or issue-type assignments — assign them as needed Imported templates are fully editable. Treat them as a starting point, not a finished product. ### Method 1: Create from Scratch[​](#method-1-create-from-scratch "Direct link to Method 1: Create from Scratch") 1. Click the **Create Template** button in the top-right corner 2. Fill in the template details: * **Template Name**: A descriptive name for your template * **Summary**: The text that will pre-fill the issue summary field * **Description**: Rich text content for the issue description 3. Use the rich text editor toolbar to format your description: * Bold, italic, strikethrough text * Headings (H1-H6) * Bullet and numbered lists * Code blocks with syntax highlighting * Links and more 4. Click **Save** to create the template ### Method 2: Import from File[​](#method-2-import-from-file "Direct link to Method 2: Import from File") You can import templates from JSON or Markdown files: 1. Click the **Import Templates** button 2. Select the **From File** tab 3. Click **Choose File** and select your `.json` or `.md` file 4. The app will parse the file and create templates automatically 5. Templates with duplicate names will be renamed with a number suffix (e.g., "Bug Report (2)") **Supported Formats**: * **JSON**: Export files from this app or custom JSON with template structure * **Markdown**: Standard markdown files with optional YAML frontmatter ### Method 3: Import from GitHub[​](#method-3-import-from-github "Direct link to Method 3: Import from GitHub") Import templates directly from GitHub. A single **From GitHub URL** tab handles both repository files and Gists — the app detects the URL type automatically. 1. Click **Import Templates** 2. Select the **From GitHub URL** tab 3. Paste a URL: * **Repository file** — e.g. `https://github.com/username/repo/blob/main/.github/ISSUE_TEMPLATE/bug_report.md` (imports that single file) * **Gist** — e.g. `https://gist.github.com/username/abc123def456` (imports all markdown files in the Gist) 4. Click **Fetch** to import **GitHub Template Features**: * Automatically extracts YAML frontmatter metadata * Converts markdown formatting to rich text * Supports GitHub issue template format * Handles multiple files in a single Gist ## Editing Templates[​](#editing-templates "Direct link to Editing Templates") ### Quick Inline Editing[​](#quick-inline-editing "Direct link to Quick Inline Editing") For fast updates, you can edit templates directly in the table: #### Edit Summary[​](#edit-summary "Direct link to Edit Summary") 1. Click on any summary cell in the table 2. The text becomes editable 3. Make your changes 4. Press **Enter** or click outside to save #### Edit Description[​](#edit-description "Direct link to Edit Description") 1. Click on any description cell in the table 2. A rich text editor appears 3. Make your formatting changes using the toolbar 4. Click outside the editor to save ### Full Template Editor[​](#full-template-editor "Direct link to Full Template Editor") For comprehensive edits: 1. Click the **Edit** button (pencil icon) in the Actions column 2. The template modal opens with all fields 3. Edit the name, summary, and description 4. Click **Save** to apply changes The modal closes immediately while saving happens in the background for a smooth experience. ## Managing Templates[​](#managing-templates "Direct link to Managing Templates") ### Clone a Template[​](#clone-a-template "Direct link to Clone a Template") To create a copy of an existing template: 1. Click the **Clone** button (copy icon) in the Actions column 2. A duplicate template is created with "(Copy)" appended to the name 3. Edit the cloned template as needed ### Delete a Template[​](#delete-a-template "Direct link to Delete a Template") To remove a template: 1. Click the **Delete** button (trash icon) in the Actions column 2. Confirm the deletion in the dialog 3. The template is permanently removed ### Select All Templates[​](#select-all-templates "Direct link to Select All Templates") Use the checkbox in the table header to quickly select or deselect all templates for bulk operations. ## Assigning Templates to Projects[​](#assigning-templates-to-projects "Direct link to Assigning Templates to Projects") Templates must be assigned to projects and issue types to work automatically. ### Assign a Template[​](#assign-a-template "Direct link to Assign a Template") 1. Click the **Assign to Project** button (link icon) in the Actions column 2. In the assignment dialog: * **Select Projects**: Choose one or more projects from the dropdown * **Select Issue Types**: Choose which issue types should use this template 3. Click **Save** ### View Assignments[​](#view-assignments "Direct link to View Assignments") Assigned projects appear as colored badges in the **Projects** column. If a template is assigned to more than 3 projects, you'll see "+N more" indicator. ### How Assignment Works[​](#how-assignment-works "Direct link to How Assignment Works") When a user creates an issue: * The app checks the selected project and issue type * If a matching template exists, it automatically pre-fills the summary and description * Users can still edit the pre-filled content before creating the issue ### Conflict Detection & Re-enable[​](#conflict-detection--re-enable "Direct link to Conflict Detection & Re-enable") Each project × issue-type context can be owned by exactly one template's auto-apply. When you assign a template to a context another template already owns: 1. **Conflict dialog** opens listing every conflicting template with the specific contexts at stake 2. On confirm, the **losing template's assignment is marked as disabled** (the prior UIM is deleted; a `disabledAssignments` entry is recorded pointing at the winner) 3. The winning template takes over auto-apply immediately Disabled templates surface in three places: * **Row tint** — templates with at least one disabled assignment get a subtle warning background in the table * **Re-enable button** in the Actions column (refresh icon) — only enabled when the template has disabled assignments; tooltip lists every disabled context with the template that replaced it * **Filter dropdown** (top-left of the toolbar) — switch between *All*, *Active only*, and *Has disabled* when at least one disabled assignment exists **Re-enable flow** is symmetric to assign: clicking the re-enable button runs the conflict check again. If a new conflict is found (someone else still owns one of the contexts), the dialog shows it. On confirm, all the template's disabled entries clear and auto-apply resumes. **Automatic cleanup:** if a winning template is deleted, every `disabledAssignments` entry pointing at it cascades clear — the prior losers silently become active again without needing a manual re-enable. Editing a template's projects/issue-types also auto-clears disabled entries for contexts that are no longer in its assignment matrix. ## Exporting Templates[​](#exporting-templates "Direct link to Exporting Templates") ### Export Selected Templates[​](#export-selected-templates "Direct link to Export Selected Templates") 1. Select templates using the checkboxes in the first column 2. The **Export Selected (N)** button appears showing the count 3. Click the button to download a JSON file 4. The file is named `templates-export-{timestamp}.json` 5. Use this file to back up templates or share with other Jira instances ## Markdown and Formatting[​](#markdown-and-formatting "Direct link to Markdown and Formatting") ### Markdown Support[​](#markdown-support "Direct link to Markdown Support") When importing markdown files, the app converts markdown syntax to rich text: * `**bold**` → **bold text** * `*italic*` → *italic text* * `~~strikethrough~~` → ~~strikethrough text~~ * `` `code` `` → `inline code` * `# Heading` → Heading levels 1-6 * `- item` or `* item` → Bullet lists * `1. item` → Numbered lists * ` ```code``` ` → Code blocks with syntax highlighting * `[text](url)` → Clickable links * `> quote` → Blockquotes ### YAML Frontmatter[​](#yaml-frontmatter "Direct link to YAML Frontmatter") GitHub issue templates often include YAML frontmatter at the top: ``` --- name: Bug Report title: "Bug: " labels: ["bug"] assignees: ["maintainer"] --- ## Description Describe the bug... ``` The app automatically extracts: * `name` → Template name * `title` → Summary template * `labels` → Mapped to issue types when possible * `assignees` → Stored as metadata ## Template Variables[​](#template-variables "Direct link to Template Variables") Templates support dynamic variables using `{{variable}}` syntax. Variables are substituted at apply time — when a user creates an issue, the variable placeholders are replaced with real values. ### Supported Variables[​](#supported-variables "Direct link to Supported Variables") | Variable | Description | Example output | | ---------------------- | ----------------------------------------- | -------------------- | | `{{currentUser}}` | Display name of the current user | Alice Lee | | `{{currentUserEmail}}` | Email of the current user | | | `{{currentUserKey}}` | Atlassian account ID | 5abc123 | | `{{today}}` | Today's date (YYYY-MM-DD) | 2026-06-25 | | `{{now}}` | Current timestamp (ISO) | 2026-06-25T12:30:45Z | | `{{date}}` | Today's date (locale format) | 6/25/2026 | | `{{time}}` | Current time (locale format) | 12:30:45 PM | | `{{projectKey}}` | Project key of the issue being created | ENG | | `{{projectName}}` | Project name of the issue being created | Engineering | | `{{issueType}}` | Issue type name | Bug | | `{{issueKey}}` | Issue key (available on edit, not create) | ENG-42 | | `{{reporter}}` | Reporter's display name | Bob | | `{{reporterEmail}}` | Reporter's email | | ### Date Offsets[​](#date-offsets "Direct link to Date Offsets") Date variables support arithmetic offsets for due dates and SLA windows: | Syntax | Effect | Example | | -------------- | ---------------- | ---------- | | `{{today+7d}}` | Add 7 days | 2026-07-02 | | `{{today-1d}}` | Subtract 1 day | 2026-06-24 | | `{{today+2w}}` | Add 2 weeks | 2026-07-09 | | `{{today-1M}}` | Subtract 1 month | 2026-05-25 | | `{{today+1y}}` | Add 1 year | 2027-06-25 | Supported units: `d` (days), `w` (weeks), `M` (months), `y` (years). Offsets work on `today`, `date`, and `now`. ### Variable Validation[​](#variable-validation "Direct link to Variable Validation") The template editor provides real-time validation: * **Description editor** — invalid variables get a red wavy underline. Hover for details and "Did you mean?" suggestions. * **Summary field** — a SectionMessage error appears below the field showing the first issue. Common mistakes the validator catches: | Mistake | Fix | | ----------------------------------------- | ---------------------------------------- | | `{{todiya}}` (typo) | Suggests `{{today}}` | | `{{today+7x}}` (bad unit) | "Invalid unit 'x' (use d, w, M, or y)" | | `{{today+7}}` (missing unit) | "Offset needs a unit (d/w/M/y)" | | `{{currentUser+7d}}` (offset on non-date) | "Variable does not support date offsets" | At apply time, any unresolved variable renders as `⚠️[unknown:name]` in the issue fields so failures are visible. ### HTML Comments[​](#html-comments "Direct link to HTML Comments") HTML comments (``) and ` ` entities are automatically stripped during import to ensure clean template content. ## Template Fields (Multi-Field Pre-Fill)[​](#template-fields-multi-field-pre-fill "Direct link to Template Fields (Multi-Field Pre-Fill)") > **Advanced edition only.** Standard users can read existing field configs but the editor section is hidden, and templates do not auto-apply fields at create time. Standard's Summary + Description auto-apply still works unchanged. Existing field configs are preserved on the template record (no data destruction on downgrade). In addition to summary and description, templates can declare a `fields` map that pre-fills other Jira fields at create time. This is how the Sprint Retro Action Item starter template sets its 7-day due date, and how Bug Report auto-tags issues with the `bug` label. The Fields editor in the template modal pairs a field picker (filtered to unused IDs) with a value input. Each row shows a hint explaining what to enter — option fields (priority, components) take a name resolved via Jira lookup; accountId fields (assignee, reporter) take an accountId or `{{currentUserKey}}`; direct fields (duedate, labels) take the literal value. ### Supported Field Types[​](#supported-field-types "Direct link to Supported Field Types") | Field | Example value | Behavior | | --------------------------------------- | ---------------------- | ------------------------------------------------------------------------- | | `labels` | `['bug', 'frontend']` | Tag-picker UI with Jira label suggestions; direct setValue — string array | | `duedate` | `'{{today+7d}}'` | Variable-resolved to `yyyy-MM-dd`, direct setValue | | `environment` | `'Production'` | Direct setValue — free text | | `priority` | `'High'` | Name → ID lookup, then setValue (Classic projects only) | | `components`, `fixVersions`, `versions` | `['API', 'UI']` | Name → ID lookup (project-scoped), then setValue (Classic only) | | `assignee`, `reporter` | `'{{currentUserKey}}'` | AccountId setValue; named values trigger a user search | | `customfield_*` | any | Direct setValue; user must know the custom field ID | Variables in field values use the same `{{...}}` syntax as summary/description and are resolved at apply time. ### Project-Type Differences[​](#project-type-differences "Direct link to Project-Type Differences") The apply loop is **project-type-agnostic** — it tries to setValue every declared field and silently skips any that don't exist in the current create dialog. In practice: * **Team-managed projects**: `priority`, `components`, `fixVersions`, `versions`, `environment` are not exposed by the UI Modifications API. Templates declaring them still work — those fields are skipped, and the rest apply normally. * **Classic projects**: all supported fields are available. This means a single template (e.g. Bug Report with `labels: ['bug']` + `priority: 'High'`) works across both project types without per-type configuration. ### Platform-Blocked Fields[​](#platform-blocked-fields "Direct link to Platform-Blocked Fields") Some fields visible in the Create Issue dialog **cannot** be set via UI Modifications — Jira's API rejects the write. Templates should not declare these: * `parent` (sub-task context only) * `startdate` (Team-managed next-gen) * `attachment` (requires multipart upload — no setValue path) * `issuelinks` / Linked work items * `team`, issue color * `status` (takes a transitionId, not settable on Global Create) ### Starter Templates with Fields[​](#starter-templates-with-fields "Direct link to Starter Templates with Fields") Nine starter library templates ship with `fields` pre-configured: | Template | Fields | | ------------------------ | ------------------------------------------------------------- | | Bug Report | `labels: ['bug']` | | Feature Request | `labels: ['feature-request']` | | RFC | `labels: ['rfc']` | | Tech Debt Item | `labels: ['tech-debt']` | | Incident Report | `labels: ['incident', 'postmortem']` | | Sprint Retro Action Item | `duedate: '{{today+7d}}'`, `labels: ['retro', 'action-item']` | | Onboarding Task | `labels: ['onboarding']` | | Offboarding Task | `labels: ['offboarding']` | | PTO Request | `labels: ['pto']` | Importing these from the Starter Library is the easiest way to see multi-field pre-fill in action. Authoring custom `fields` on new templates is currently JSON-only — a guided authoring UI is on the roadmap. ## Automatic Template Application[​](#automatic-template-application "Direct link to Automatic Template Application") ### How It Works[​](#how-it-works "Direct link to How It Works") Once templates are assigned to projects and issue types: 1. User opens the issue creation screen 2. Selects a project and issue type 3. The app automatically finds a matching template 4. Summary, description, and any declared `fields` (labels, due date, etc.) are pre-filled 5. User can edit the content before creating the issue ### When Templates Apply[​](#when-templates-apply "Direct link to When Templates Apply") Templates apply when: * A matching project and issue type combination exists * The summary, description, and declared fields are empty (no user-entered content) or still hold the template's last-applied values (idempotency check) ### When Templates Don't Apply[​](#when-templates-dont-apply "Direct link to When Templates Don't Apply") Templates are skipped (and the skip is logged) when: * No matching template exists for the project/issue type * The user has already typed content into the summary or description * The template was already applied to this dialog instance (idempotency — prevents clobbering edits on cancel-and-reopen) > **Note:** Changing the issue type or project after the initial auto-apply does **not** re-trigger the template. To apply a different template, the user must cancel and reopen the create-issue dialog. ### Sub-task Creation Limitation[​](#sub-task-creation-limitation "Direct link to Sub-task Creation Limitation") Auto-apply **does not fire when creating sub-tasks**. Jira Cloud's global Create dialog only lists top-level issue types (Epic, Task, Story) — sub-tasks are created inline from a parent issue or via issue conversion, neither of which opens the create dialog that UI Modifications can intercept. This is a Jira platform constraint, not an app configuration issue, and cannot be worked around. ### Application Log[​](#application-log "Direct link to Application Log") > **Depth is Advanced-gated.** Standard users see the most recent 10 entries (status only). Advanced users see the most recent 50 entries plus status filter and CSV export. The plan indicator at the top of the modal shows which tier's view is active. Admins can audit template behavior via the **Application Log** button on the template manager: 1. Open the template manager (Apps → Modern Issue Templates) 2. Click **Application Log** in the toolbar 3. Each entry shows: * Template name * Status: `applied` (green), `skipped` (blue), or `failed` (red) * Timestamp * Project key and issue type * Reason for the decision (e.g., "Field(s) already contain user-entered content") The log retains up to 7 days of history, capped at 50 entries (FIFO) on read for Advanced users. Standard users see the 10 most recent entries. Use it to debug "why didn't my template apply?" or audit template usage across the team. A `failed` status with a reason like `setValue rejected for: labels` or `setValue rejected for: description` means Jira refused one of the field writes (typically a `FIELD_VALIDATION_FAILED` error — e.g. a label that doesn't exist yet, or an option name that doesn't match). The browser console will show the specific field ID that rejected the write, and the full `Field apply result:` diagnostic breaks down every declared field as applied / failed / skipped. ### Storage Reconcile Banner[​](#storage-reconcile-banner "Direct link to Storage Reconcile Banner") In rare cases (typically after a reinstall or a partial data loss), the template records in Forge storage can drift from the Jira-side UI Modification entries that actually drive auto-apply. On page load the app cross-references the two and surfaces a **reconcile banner** at the top of the template table when mismatches are detected. The banner explains what was found (orphan UIMs whose template no longer exists, or template records whose UIM is missing) and offers a one-click action to clean up the orphaned side. This is the third layer of orphan prevention — the read path is self-healing (Layer 1), the write path deletes overlaps before creating new entries (Layer 2), and the reconcile banner catches anything that slipped through (Layer 3). ### Graceful Degradation[​](#graceful-degradation "Direct link to Graceful Degradation") If anything fails during auto-apply (network error, malformed template, resolver exception), the app logs the failure and lets the user continue creating their issue normally. Template errors never block the issue creation flow. ## Tips and Best Practices[​](#tips-and-best-practices "Direct link to Tips and Best Practices") ### Template Naming[​](#template-naming "Direct link to Template Naming") * Use clear, descriptive names like "Bug Report" or "Feature Request" * Avoid special characters that might cause issues * Keep names concise for better table display ### Summary Templates[​](#summary-templates "Direct link to Summary Templates") * Keep summaries short and focused * Use placeholders like `Bug: [describe issue]` to guide users * Avoid overly long summary templates ### Description Templates[​](#description-templates "Direct link to Description Templates") * Use headings to structure the template * Include clear instructions for each section * Use bullet points for checklists * Add code blocks for technical templates * Keep formatting simple and readable ### Project Assignment[​](#project-assignment "Direct link to Project Assignment") * Assign templates to specific projects for better organization * Use different templates for different issue types * Review and update assignments regularly ### Import Best Practices[​](#import-best-practices "Direct link to Import Best Practices") * Test imports with a single file first * Review imported templates before assigning to projects * Use GitHub imports to leverage community templates * Export templates regularly as backups ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") ### Template Not Applying Automatically[​](#template-not-applying-automatically "Direct link to Template Not Applying Automatically") **Check**: * Is the template assigned to the correct project? * Is the template assigned to the correct issue type? * Have you deployed the latest version of the app? ### Import Fails from GitHub[​](#import-fails-from-github "Direct link to Import Fails from GitHub") **Common Issues**: * **404 Error**: Check the URL is correct and the file exists * **403 Error**: The repository might be private or require authentication * **Rate Limiting**: GitHub API has rate limits; wait a few minutes and try again * **Invalid URL**: Ensure you're using a direct file URL, not a directory ### Formatting Lost After Import[​](#formatting-lost-after-import "Direct link to Formatting Lost After Import") * Markdown conversion preserves most formatting * Some complex HTML in markdown may not convert perfectly * Edit the template after import to adjust formatting ### Duplicate Template Names[​](#duplicate-template-names "Direct link to Duplicate Template Names") * The app automatically adds `(1)`, `(2)`, etc. to duplicate names during import * Rename templates after import if needed * Use unique names when creating templates manually ## Advanced Features[​](#advanced-features "Direct link to Advanced Features") ### Batch Operations[​](#batch-operations "Direct link to Batch Operations") * Select multiple templates with checkboxes * Export selected templates in one operation * Use select all checkbox for bulk selection ### Template Versioning (Manual)[​](#template-versioning-manual "Direct link to Template Versioning (Manual)") This app does not have built-in version history. To preserve previous versions of a template: * Export templates to JSON before making major changes * Keep backup JSON files of important templates * Clone templates to create variations before editing ### GitHub Integration[​](#github-integration "Direct link to GitHub Integration") * Import community templates from public repositories * Share your templates via GitHub Gists * Keep templates in version control alongside your code ## Known Limitations[​](#known-limitations "Direct link to Known Limitations") The following are **not** currently supported. If you need them, please raise an issue. * **Parent/epic context in templates** — `{{parent.*}}` variables are not supported. Jira Cloud's Create dialog doesn't expose sub-task creation, so templates cannot read parent-issue fields at apply time. See "Sub-task Creation Limitation" above. * **Custom field variables** (`{{customfield.X}}`) — not yet implemented. Tracked in [issue #5](https://github.com/universeroc/Modern-Issue-Templates-for-Jira/issues/5); planned as a Cycle 6 Advanced anchor. * **Live preview** — there is no rendered preview pane while editing a template. * **Bulk apply to existing issues** — templates only apply to *new* issues created via the standard create-issue screen. * **Template version history** — see "Template Versioning (Manual)" above. * **Hierarchy templates** — generating epic → story → subtask structures from a single template is not supported. * **REST API / webhooks** — templates cannot be applied from external automation tools. * **Re-trigger on field change** — changing the project or issue type after the first auto-apply does not re-apply a different template. * **Data Center / Server** — Cloud-only. ### Auto-Apply Context[​](#auto-apply-context "Direct link to Auto-Apply Context") The auto-apply UI Modification registers one context per project × issue-type pair. Selecting a project in the assignment modal is required before issue types can be selected — the issue-type list is fetched per project. ## Support and Feedback[​](#support-and-feedback "Direct link to Support and Feedback") If you encounter issues or have suggestions: 1. Check this guide for troubleshooting steps 2. Review the app logs in Forge CLI if you're a developer 3. Contact your Jira administrator for assistance 4. Report bugs or request features through your organization's support channels *** **Version**: 1.5 **Last Updated**: July 2026 ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [FAQ: Jira issue templates automation](/blog/faq-jira-issue-templates-automation.md) * [Best Confluence apps for developers](/blog/best-confluence-apps-developers.md) Was this helpful?👍 Yes👎 No --- # Modern My Tasks - User Guide ## Getting Started[​](#getting-started "Direct link to Getting Started") ### Accessing the App[​](#accessing-the-app "Direct link to Accessing the App") 1. Log in to your Confluence instance 2. Click on the **Apps** menu in the top navigation 3. Select **Modern My Tasks** ## Understanding the Interface[​](#understanding-the-interface "Direct link to Understanding the Interface") ### Task Table[​](#task-table "Direct link to Task Table") The main interface displays all your tasks in a sortable, paginated table with the following columns: * **Checkbox**: Mark individual tasks as complete/incomplete * **Task**: The task title (click to edit inline) * **Creator**: User who created the task * **Assignee**: Users assigned to the task (click to edit) * **Due Date**: Task deadline (click to edit) * **Source**: Link to the page or blog post containing the task ### Filtering Tabs[​](#filtering-tabs "Direct link to Filtering Tabs") #### All Tasks[​](#all-tasks "Direct link to All Tasks") Shows every task across your Confluence instance, both complete and incomplete. Use this for a complete overview of all work. #### I Created[​](#i-created "Direct link to I Created") Displays only incomplete tasks that you created. Perfect for tracking deliverables you've assigned to others. #### Assigned to Me[​](#assigned-to-me "Direct link to Assigned to Me") Shows incomplete tasks assigned to you. Your personal to-do list for focused work. #### Completed[​](#completed "Direct link to Completed") Archive of all completed tasks. Review what's been accomplished or reopen tasks if needed. ## Working with Tasks[​](#working-with-tasks "Direct link to Working with Tasks") ### Viewing Tasks[​](#viewing-tasks "Direct link to Viewing Tasks") * **Sort**: Click any column header to sort by that field * **Navigate**: Use pagination controls at the bottom to browse multiple pages * **Jump to Source**: Click the "View" button to open the page containing the task ### Editing Task Titles[​](#editing-task-titles "Direct link to Editing Task Titles") 1. Click on the task title text 2. Edit the text in the input field 3. Press Enter or click outside to save 4. A spinner appears briefly while saving ### Managing Assignees[​](#managing-assignees "Direct link to Managing Assignees") 1. Click on the assignee field (or "Click to assign" placeholder) 2. Search for users in the picker 3. Select one or multiple users 4. Press Enter or click outside to save 5. Assignees appear as avatars with names ### Setting Due Dates[​](#setting-due-dates "Direct link to Setting Due Dates") 1. Click on the due date field (or "Set due date" placeholder) 2. Select a date from the calendar picker 3. The date saves automatically 4. Dates display in your locale format ### Completing Tasks[​](#completing-tasks "Direct link to Completing Tasks") **Single Task:** 1. Check the checkbox next to the task 2. The task updates immediately 3. Uncheck to mark as incomplete **Bulk Complete:** 1. Click the checkbox in the table header 2. All incomplete tasks are marked complete at once 3. Great for end-of-sprint cleanup ## Tips & Best Practices[​](#tips--best-practices "Direct link to Tips & Best Practices") ### Efficient Task Management[​](#efficient-task-management "Direct link to Efficient Task Management") * Use the "Assigned to Me" tab as your daily to-do list * Check "I Created" regularly to follow up on delegated work * Review "Completed" weekly to track progress * Sort by Due Date to prioritize urgent tasks ### Inline Editing[​](#inline-editing "Direct link to Inline Editing") * All edits save automatically - no save button needed * Watch for the spinner to confirm your changes are saving * If an edit fails, you'll see an error message at the top ### Keyboard Navigation[​](#keyboard-navigation "Direct link to Keyboard Navigation") * Press Enter to confirm inline edits * Press Escape to cancel inline edits * Tab through fields for quick editing ### Working Across Spaces[​](#working-across-spaces "Direct link to Working Across Spaces") * Tasks from all spaces you have access to appear in the list * Use the Source column to identify which space a task belongs to * Click "View" to jump directly to the source page ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") ### Tasks Not Appearing[​](#tasks-not-appearing "Direct link to Tasks Not Appearing") * Newly created tasks require a page reload to appear * Ensure you have permission to view the pages containing the tasks * Refresh the page to reload task data * Check that tasks are properly created in Confluence pages ### Cannot Edit Tasks[​](#cannot-edit-tasks "Direct link to Cannot Edit Tasks") * Verify you have edit permissions for the source page * Ensure the task still exists in the source page * Try refreshing the page ### Assignee Not Showing[​](#assignee-not-showing "Direct link to Assignee Not Showing") * Confirm the user has access to your Confluence instance * Check that the user mention exists in the task * App users are filtered out automatically ### Due Date Issues[​](#due-date-issues "Direct link to Due Date Issues") * Dates display in your browser's locale format * Ensure you select a valid date in the picker * Check the source page to verify the date was saved ## Permissions[​](#permissions "Direct link to Permissions") ### What You Can See[​](#what-you-can-see "Direct link to What You Can See") You can only see tasks from pages and blog posts you have permission to view in Confluence. ### What You Can Edit[​](#what-you-can-edit "Direct link to What You Can Edit") You can only edit tasks in pages where you have edit permissions. ### User Privacy[​](#user-privacy "Direct link to User Privacy") The app respects all Confluence user permissions and privacy settings. ## Frequently Asked Questions[​](#frequently-asked-questions "Direct link to Frequently Asked Questions") **Q: Can I create new tasks from this app?** A: Not currently. Create tasks in Confluence pages. After creating a task, reload the Modern My Tasks page to see it appear in your list. **Q: Do changes sync back to the source page?** A: Yes! All edits update the task in the original page or blog post. **Q: Can I delete tasks?** A: Delete tasks from the source page. They'll be removed from this view automatically. **Q: How often does the task list refresh?** A: The list refreshes automatically after each edit. Click the Refresh button for manual updates. **Q: Can I export my task list?** A: Not currently. Use Confluence's native export features on individual pages. **Q: Does this work with Confluence Cloud and Data Center?** A: This app is built for Confluence Cloud using Forge. ## Support[​](#support "Direct link to Support") Need help? Have feedback? * Contact your Confluence administrator * Report issues to * Check for app updates in the Atlassian Marketplace ## Version[​](#version "Direct link to Version") Current Version: 1.0.0 ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [Best Confluence apps for developers](/blog/best-confluence-apps-developers.md) * [FAQ: Confluence plugins security](/blog/faq-using-plugins-security.md) Was this helpful?👍 Yes👎 No --- # User Guide - Modern Numbered Headings for Confluence > **Complete guide to creating professional table of contents with multiple numbering styles** ## Table of Contents[​](#table-of-contents "Direct link to Table of Contents") 1. [Getting Started](#getting-started) 2. [Basic Usage](#basic-usage) 3. [Numbering Styles](#numbering-styles) 4. [Advanced Features](#advanced-features) 5. [Best Practices](#best-practices) 6. [Troubleshooting](#troubleshooting) 7. [FAQ](#faq) ## Getting Started[​](#getting-started "Direct link to Getting Started") ### Installation[​](#installation "Direct link to Installation") 1. **From Atlassian Marketplace**: * Go to **Confluence Settings** → **Find new apps** * Search for **"Modern Numbered Headings"** * Click **"Install"** and follow the prompts 2. **Verify Installation**: * Open any Confluence page with headings * Look for the app icon (📋) in the page byline under the title * If you see the icon, installation was successful! ### First Time Setup[​](#first-time-setup "Direct link to First Time Setup") No setup required! The app works immediately after installation. ## Basic Usage[​](#basic-usage "Direct link to Basic Usage") ### Step 1: Open the App[​](#step-1-open-the-app "Direct link to Step 1: Open the App") 1. **Navigate** to any Confluence page that contains headings 2. **Look for the app icon** (📋) in the page byline section (under the page title) 3. **Click the icon** to open the configuration modal ### Step 2: Configure Your TOC[​](#step-2-configure-your-toc "Direct link to Step 2: Configure Your TOC") The large modal interface provides all configuration options: #### **Numbering Style Selection**[​](#numbering-style-selection "Direct link to numbering-style-selection") * Choose from 5 professional numbering styles * See live examples of each style format * Select the style that best fits your document type #### **Heading Level Selection**[​](#heading-level-selection "Direct link to heading-level-selection") * Choose which heading levels to include (H1-H6) * Use checkboxes to select any combination * Only headings present on your page will be processed #### **Display Options**[​](#display-options "Direct link to display-options") * **Enable Indentation**: Toggle hierarchical indentation on/off * **Live Preview**: See exactly how your TOC will look ### Step 3: Preview and Apply[​](#step-3-preview-and-apply "Direct link to Step 3: Preview and Apply") 1. **Review the preview** to see your TOC formatting 2. **Make adjustments** if needed (style, levels, indentation) 3. **Click "Insert TOC"** to add it to your page 4. **Page automatically reloads** to show the new TOC ### Step 4: Navigate and Manage[​](#step-4-navigate-and-manage "Direct link to Step 4: Navigate and Manage") * **Click any TOC entry** to scroll to that section * **Remove TOC**: Click the app icon again and select "Remove TOC" * **Update TOC**: Remove and re-insert with new settings ## Numbering Styles[​](#numbering-styles "Direct link to Numbering Styles") ### 1. Decimal Style (Default)[​](#1-decimal-style-default "Direct link to 1. Decimal Style (Default)") **Format**: `1. 1.1. 1.2.` **Best For**: Technical documentation, general use **Example**: ``` 1. Introduction 1.1. Overview 1.2. Getting Started 2. Configuration 2.1. Basic Setup 2.2. Advanced Options ``` ### 2. Roman Numerals[​](#2-roman-numerals "Direct link to 2. Roman Numerals") **Format**: `I. I.I. I.II.` **Best For**: Formal documents, academic papers **Example**: ``` I. Executive Summary I.I. Key Findings I.II. Recommendations II. Detailed Analysis II.I. Methodology II.II. Results ``` ### 3. Alphabetic Style[​](#3-alphabetic-style "Direct link to 3. Alphabetic Style") **Format**: `A. A.A. A.B.` **Best For**: Structured lists, procedures **Example**: ``` A. Planning Phase A.A. Requirements Gathering A.B. Resource Allocation B. Implementation Phase B.A. Development B.B. Testing ``` ### 4. Outline Style[​](#4-outline-style "Direct link to 4. Outline Style") **Format**: `1) 1.1) 1.1.1)` **Best For**: Business reports, legal documents **Example**: ``` 1) Project Overview 1.1) Scope Definition 1.1.1) Deliverables 1.2) Timeline 2) Risk Assessment 2.1) Technical Risks 2.2) Business Risks ``` ### 5. Mixed Style[​](#5-mixed-style "Direct link to 5. Mixed Style") **Format**: `1. A. i. a.` **Best For**: Complex hierarchies, detailed specifications **Example**: ``` 1. System Architecture A. Frontend Components i. User Interface a. Navigation b. Content Display ii. Data Management B. Backend Services 2. Security Framework ``` ## Advanced Features[​](#advanced-features "Direct link to Advanced Features") ### Heading Level Filtering[​](#heading-level-filtering "Direct link to Heading Level Filtering") **Purpose**: Control which heading levels appear in your TOC **How to Use**: 1. In the configuration modal, find "Include Levels" 2. Check/uncheck heading levels (H1-H6) 3. Preview updates automatically 4. Only selected levels will appear in the TOC **Best Practices**: * **H1-H3**: Good for most documents * **H1-H2**: Executive summaries, brief documents * **H1-H6**: Comprehensive technical documentation * **H2-H4**: Skip main title, focus on sections ### Indentation Control[​](#indentation-control "Direct link to Indentation Control") **Purpose**: Control visual hierarchy in your TOC **Options**: * **Enabled**: Hierarchical indentation with proper spacing * **Disabled**: Flat list without indentation **When to Use**: * **Enable**: Complex documents with multiple levels * **Disable**: Simple documents, space-constrained layouts ### Live Preview[​](#live-preview "Direct link to Live Preview") **Features**: * **Real-time Updates**: Changes appear instantly * **Accurate Formatting**: Exactly matches final result * **Heading Count**: Shows total number of headings * **Truncated Display**: Shows first 8 items for performance ### Smart Duplicate Prevention[​](#smart-duplicate-prevention "Direct link to Smart Duplicate Prevention") **How it Works**: * App detects existing TOCs using invisible markers * "Insert TOC" button disabled when TOC already exists * "Remove TOC" button disabled when no TOC present * Clear status indicators show current state ### Magic Marker System[​](#magic-marker-system "Direct link to Magic Marker System") **Technology**: * Uses invisible unicode characters as boundaries * Completely invisible to users * Bulletproof TOC detection and removal * No interference with page content **Benefits**: * **Reliable Detection**: Never fails to find TOCs * **Clean Removal**: Removes all TOC elements perfectly * **No Artifacts**: No leftover formatting or text * **Future-Proof**: Works regardless of content changes ## Best Practices[​](#best-practices "Direct link to Best Practices") ### Document Structure[​](#document-structure "Direct link to Document Structure") #### **Good Heading Structure**:[​](#good-heading-structure "Direct link to good-heading-structure") ``` # Main Title (H1) ## Section 1 (H2) ### Subsection 1.1 (H3) ### Subsection 1.2 (H3) ## Section 2 (H2) ### Subsection 2.1 (H3) #### Detail 2.1.1 (H4) ``` #### **Avoid**:[​](#avoid "Direct link to avoid") * Skipping heading levels (H1 → H3) * Using headings for styling only * Empty headings * Duplicate heading text ### Numbering Style Selection[​](#numbering-style-selection-1 "Direct link to Numbering Style Selection") #### **Choose Based on Document Type**:[​](#choose-based-on-document-type "Direct link to choose-based-on-document-type") **Technical Documentation**: * ✅ Decimal (1. 1.1. 1.2.) * ✅ Outline (1) 1.1) 1.1.1)) **Business Reports**: * ✅ Decimal (1. 1.1. 1.2.) * ✅ Roman (I. I.I. I.II.) * ✅ Outline (1) 1.1) 1.1.1)) **Academic Papers**: * ✅ Roman (I. I.I. I.II.) * ✅ Decimal (1. 1.1. 1.2.) **Legal Documents**: * ✅ Outline (1) 1.1) 1.1.1)) * ✅ Mixed (1. A. i. a.) **Procedures/Checklists**: * ✅ Alphabetic (A. A.A. A.B.) * ✅ Decimal (1. 1.1. 1.2.) ### TOC Placement[​](#toc-placement "Direct link to TOC Placement") #### **Best Practices**:[​](#best-practices-1 "Direct link to best-practices-1") * **Top of Page**: Most common and expected location * **After Introduction**: For documents with executive summary * **Before Main Content**: Skip preliminary sections #### **Avoid**:[​](#avoid-1 "Direct link to avoid-1") * Multiple TOCs on same page * TOC in the middle of content * TOC at the very end ### Maintenance[​](#maintenance "Direct link to Maintenance") #### **When to Update TOC**:[​](#when-to-update-toc "Direct link to when-to-update-toc") * Added new sections * Removed sections * Changed heading text * Restructured document #### **How to Update**:[​](#how-to-update "Direct link to how-to-update") 1. Click app icon 2. Click "Remove TOC" 3. Make your content changes 4. Click app icon again 5. Click "Insert TOC" with new settings ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") ### Common Issues[​](#common-issues "Direct link to Common Issues") #### **App Icon Not Visible**[​](#app-icon-not-visible "Direct link to app-icon-not-visible") **Possible Causes**: * Page has no headings * App not installed properly * Browser cache issues **Solutions**: 1. **Check for headings**: Ensure page has H1-H6 headings 2. **Refresh page**: Clear browser cache and reload 3. **Check installation**: Verify app is installed in Confluence settings 4. **Contact admin**: May need admin permissions #### **TOC Not Inserting**[​](#toc-not-inserting "Direct link to toc-not-inserting") **Possible Causes**: * No headings selected * TOC already exists * Insufficient permissions **Solutions**: 1. **Select heading levels**: Ensure at least one level is checked 2. **Check for existing TOC**: Remove existing TOC first 3. **Verify permissions**: Ensure you can edit the page 4. **Try different browser**: Test in incognito/private mode #### **Navigation Links Not Working**[​](#navigation-links-not-working "Direct link to navigation-links-not-working") **Possible Causes**: * Page modified after TOC insertion * Browser compatibility issues * Confluence caching **Solutions**: 1. **Update TOC**: Remove and re-insert TOC 2. **Clear cache**: Refresh page and clear browser cache 3. **Check browser**: Ensure modern browser version 4. **Wait for sync**: Allow Confluence to process changes #### **Formatting Issues**[​](#formatting-issues "Direct link to formatting-issues") **Possible Causes**: * Confluence theme conflicts * Custom CSS interference * Browser rendering differences **Solutions**: 1. **Try different style**: Test with decimal numbering 2. **Disable custom CSS**: Temporarily disable page customizations 3. **Test in different browser**: Verify cross-browser compatibility 4. **Contact support**: Report persistent formatting issues ### Error Messages[​](#error-messages "Direct link to Error Messages") #### **"No headings found on this page"**[​](#no-headings-found-on-this-page "Direct link to no-headings-found-on-this-page") * **Cause**: Page contains no H1-H6 headings * **Solution**: Add headings to your page content #### **"No headings selected"**[​](#no-headings-selected "Direct link to no-headings-selected") * **Cause**: All heading level checkboxes are unchecked * **Solution**: Select at least one heading level #### **"TOC Already Inserted"**[​](#toc-already-inserted "Direct link to toc-already-inserted") * **Cause**: Page already contains a TOC * **Solution**: Remove existing TOC before inserting new one #### **"Failed to update page"**[​](#failed-to-update-page "Direct link to failed-to-update-page") * **Cause**: Insufficient permissions or network issues * **Solution**: Check edit permissions and network connection ### Performance Issues[​](#performance-issues "Direct link to Performance Issues") #### **Slow Loading**[​](#slow-loading "Direct link to slow-loading") * **Clear browser cache** * **Check network connection** * **Try in incognito mode** * **Contact support if persistent** #### **Large Documents**[​](#large-documents "Direct link to large-documents") * **App optimized for 50+ headings** * **Preview shows first 8 items for performance** * **Full TOC still generated correctly** * **Consider breaking very large documents into sections** ## FAQ[​](#faq "Direct link to FAQ") ### General Questions[​](#general-questions "Direct link to General Questions") #### **Q: Is the app free?**[​](#q-is-the-app-free "Direct link to q-is-the-app-free") A: Yes, there's a free tier with basic decimal numbering. Professional features require a paid subscription. #### **Q: Does it work on mobile?**[​](#q-does-it-work-on-mobile "Direct link to q-does-it-work-on-mobile") A: Yes, the app is fully responsive and works on tablets and mobile devices. #### **Q: Can I customize the TOC title?**[​](#q-can-i-customize-the-toc-title "Direct link to q-can-i-customize-the-toc-title") A: Currently, the TOC uses a standard format. Custom titles are planned for future releases. #### **Q: Does it work with Confluence templates?**[​](#q-does-it-work-with-confluence-templates "Direct link to q-does-it-work-with-confluence-templates") A: Yes, the app works with any Confluence page regardless of template. ### Technical Questions[​](#technical-questions "Direct link to Technical Questions") #### **Q: How does the magic marker system work?**[​](#q-how-does-the-magic-marker-system-work "Direct link to q-how-does-the-magic-marker-system-work") A: It uses invisible unicode characters to mark TOC boundaries, making detection and removal bulletproof. #### **Q: Does the app store my data?**[​](#q-does-the-app-store-my-data "Direct link to q-does-the-app-store-my-data") A: No, the app processes content in real-time only. No data is stored externally. #### **Q: Is it GDPR compliant?**[​](#q-is-it-gdpr-compliant "Direct link to q-is-it-gdpr-compliant") A: Yes, the app doesn't collect or store personal data, making it fully GDPR compliant. #### **Q: What permissions does it need?**[​](#q-what-permissions-does-it-need "Direct link to q-what-permissions-does-it-need") A: The app needs read/write permissions for Confluence content to insert and remove TOCs. ### Feature Questions[​](#feature-questions "Direct link to Feature Questions") #### **Q: Can I have multiple TOCs on one page?**[​](#q-can-i-have-multiple-tocs-on-one-page "Direct link to q-can-i-have-multiple-tocs-on-one-page") A: No, the app prevents duplicate TOCs to maintain document clarity. #### **Q: Can I change numbering style after insertion?**[​](#q-can-i-change-numbering-style-after-insertion "Direct link to q-can-i-change-numbering-style-after-insertion") A: Yes, remove the existing TOC and insert a new one with different settings. #### **Q: Does it work with all heading levels?**[​](#q-does-it-work-with-all-heading-levels "Direct link to q-does-it-work-with-all-heading-levels") A: Yes, the app supports H1 through H6 headings with full nesting. #### **Q: Can I exclude certain headings?**[​](#q-can-i-exclude-certain-headings "Direct link to q-can-i-exclude-certain-headings") A: Currently, you can exclude by level (H1-H6). Individual heading exclusion is planned for future releases. ### Troubleshooting Questions[​](#troubleshooting-questions "Direct link to Troubleshooting Questions") #### **Q: What if the TOC doesn't appear after insertion?**[​](#q-what-if-the-toc-doesnt-appear-after-insertion "Direct link to q-what-if-the-toc-doesnt-appear-after-insertion") A: The page automatically reloads after insertion. If it doesn't appear, try refreshing manually. #### **Q: What if navigation links don't work?**[​](#q-what-if-navigation-links-dont-work "Direct link to q-what-if-navigation-links-dont-work") A: This usually indicates the page was modified after TOC insertion. Remove and re-insert the TOC. #### **Q: Can I undo TOC insertion?**[​](#q-can-i-undo-toc-insertion "Direct link to q-can-i-undo-toc-insertion") A: Yes, click the app icon and select "Remove TOC" to cleanly remove it. #### **Q: What if I see formatting issues?**[​](#q-what-if-i-see-formatting-issues "Direct link to q-what-if-i-see-formatting-issues") A: Try a different numbering style or contact support with specific details about the issue. ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [How to use numbered headings in Confluence](/blog/how-to-use-numbered-headings-confluence.md) * [Confluence page navigation FAQ](/blog/faq-confluence-page-navigation-apps.md) Was this helpful?👍 Yes👎 No --- # Modern OpenAPI (Swagger) Integration for Confluence — User Guide ## Overview[​](#overview "Direct link to Overview") **Modern OpenAPI (Swagger) Integration for Confluence** is a Confluence app that renders interactive API documentation directly on your pages. Paste an OpenAPI 3.x or Swagger 2.x specification in YAML or JSON format, and the app displays a polished, navigable view of your API endpoints, parameters, request/response examples, and data models — all inside Confluence. *** ## Requirements[​](#requirements "Direct link to Requirements") * Confluence Cloud * Any Confluence user can insert and configure the macro on a page * A site admin must install the app from the Atlassian Marketplace *** ## Installation[​](#installation "Direct link to Installation") 1. Go to **Settings** → **Manage apps** (site admin required). 2. Click **Find new apps** and search for **Modern OpenAPI (Swagger) Integration for Confluence**. 3. Click **Install**. 4. Once installed, the macro is available to all users on the site. *** ## How to Find the App[​](#how-to-find-the-app "Direct link to How to Find the App") The app appears as a macro in the Confluence editor. 1. Edit any Confluence page. 2. Type `/` or click the **+** (Insert) menu. 3. Search for **Modern OpenAPI (Swagger) Integration for Confluence**. 4. Select it to insert the macro. *** ## Using the App[​](#using-the-app "Direct link to Using the App") ### Configuring the macro[​](#configuring-the-macro "Direct link to Configuring the macro") When you insert or edit the macro, a full-screen configuration panel opens with a code editor on the left and controls in the top bar. 1. **Paste your spec** — Paste an OpenAPI 3.x or Swagger 2.x spec in YAML or JSON format into the editor. 2. **Format** — Click the **Format** button to auto-format and indent your spec. 3. **Validation** — The spec is validated automatically as you type. A green badge confirms it is valid; a red badge shows the error. 4. **Set viewer options** — Configure how the documentation displays (see table below). 5. Click **Save** to publish. ### Viewer options[​](#viewer-options "Direct link to Viewer options") These settings control how the API documentation appears to readers. | Setting | Description | Options | Default | | ---------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------- | | Expansion | How much of the documentation is expanded when the page loads | Tags (collapse to tag groups), All (expand everything), None (fully collapsed) | Tags | | Models | How data models (schemas) are displayed by default | Example (shows sample values), Schema (shows the type structure) | Example | | Tag filter | Shows a search box that filters API operations by tag name | On or Off | Off | info The Tag filter searches by tag name (e.g., "pet", "store", "user") — it does not search endpoint paths or descriptions. ### Viewing the documentation[​](#viewing-the-documentation "Direct link to Viewing the documentation") After saving, the macro renders a full interactive API documentation view on the Confluence page. Readers can: * **Expand and collapse** sections to browse endpoints * **View request and response examples** for each operation * **Explore data models** and switch between example and schema views * **Use the tag filter** (if enabled) to quickly find operations by tag The viewer automatically matches your Confluence theme — light or dark mode. *** ## Tips & Common Workflows[​](#tips--common-workflows "Direct link to Tips & Common Workflows") * **Start with a small spec** — Paste a minimal OpenAPI spec first to verify it works, then expand with more endpoints. * **Use YAML for readability** — YAML specs are easier to read and edit in the code editor. JSON is also fully supported. * **Tag your operations** — Use meaningful `tags` in your spec so the tag filter becomes useful for navigating large APIs. * **Set Expansion to "None"** for very large specs — This keeps the page tidy and lets readers open only the sections they need. *** ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") **Symptom:** Macro shows "No spec configured" : The macro was inserted but no spec was saved. Edit the macro and paste your OpenAPI spec. **Symptom:** Red badge says "Invalid spec" : The pasted content is not valid YAML or JSON, or does not follow the OpenAPI/Swagger format. Check for indentation errors in YAML or missing brackets in JSON. **Symptom:** Macro shows "Failed to load spec" : The stored spec may be corrupted. Edit the macro, clear the editor, and paste the spec again. **Symptom:** Tag filter returns no results : The filter matches tag names only (case-sensitive). Check that the text you type matches a tag name defined in your spec's `tags` section. **Symptom:** Spec is too large to save : The maximum spec size is 1024 KB raw. Consider splitting a large spec into smaller, focused documents. Was this helpful?👍 Yes👎 No --- # Modern Questions for Confluence — User Guide ## What is Modern Questions for Confluence?[​](#what-is-modern-questions-for-confluence "Direct link to What is Modern Questions for Confluence?") Modern Questions brings a structured question-and-answer experience to Confluence. Team members can post questions, write answers, vote on the best responses, and mark an accepted answer — all without leaving Confluence. It works both within individual spaces and across your entire site, making it easy to capture and surface institutional knowledge. *** ## Requirements[​](#requirements "Direct link to Requirements") * A Confluence Cloud site with the app installed. * Installation requires Confluence administrator access. * An active Atlassian Marketplace license is required to use the app. *** ## Installation[​](#installation "Direct link to Installation") 1. Go to **Settings** → **Manage apps** in Confluence. 2. Click **Find new apps** and search for **Modern Questions for Confluence**. 3. Click **Install** and follow the prompts. 4. Once installed, the app is available site-wide and within individual spaces. *** ## How to Find the App[​](#how-to-find-the-app "Direct link to How to Find the App") The app appears in two places in Confluence: | Where | How to get there | | -------------- | --------------------------------------------------------------- | | Site-wide Q\&A | Top navigation → **Apps** → **Modern Questions for Confluence** | | Space Q\&A | Open any space → left sidebar → **Apps** → **Modern Questions** | The site-wide view shows questions from all spaces. The space view shows only questions posted within that space. *** ## Using the App[​](#using-the-app "Direct link to Using the App") ### Browsing Questions[​](#browsing-questions "Direct link to Browsing Questions") When you open the app you see a table of questions with columns for status, title, votes, answer count, date, and author. * Click the **▶** chevron on any row to expand it and read the full question and its answers. * Click a column header (**Votes**, **Answers**, **Date**) to sort the table. * The table shows 10 questions per page; use the pagination controls at the bottom to navigate. ### Filtering and Searching[​](#filtering-and-searching "Direct link to Filtering and Searching") Use the toolbar at the top to narrow down the list: | Control | What it does | | ------------------------------------------ | ------------------------------------------------ | | **All / Open / Answered** buttons | Filter by question status | | Search field + **Search** button | Filter by keyword in question titles | | **Clear** button | Remove the active keyword search | | **My Questions** button | Show only questions you posted | | Topic chips (e.g. "Design", "Engineering") | Filter by topic — click again to deselect | | **Clear filters** button | Reset all active filters at once | | Author avatar (in the table) | Click any author's name to filter by that person | ### Asking a Question[​](#asking-a-question "Direct link to Asking a Question") 1. Click **Ask a Question** in the toolbar. 2. Enter a **Title** — a short, clear summary of what you want to know. 3. Write a detailed description in the editor. You can use formatting, lists, code blocks, and links. 4. Optionally assign one or more **Topics** using the topic picker (select existing topics or type a name and click **+ Add** to create a new one). 5. Click **Submit Question**. The question appears in the list immediately. ### Answering a Question[​](#answering-a-question "Direct link to Answering a Question") 1. Expand a question by clicking its **▶** chevron. 2. Click **Add Answer** at the bottom of the expanded panel. 3. Write your answer in the editor. 4. Click **Post Answer**. ### Voting[​](#voting "Direct link to Voting") You can vote on both questions and answers using the **▲** (upvote) and **▼** (downvote) buttons. The vote count is shown between the two buttons. ### Accepting an Answer[​](#accepting-an-answer "Direct link to Accepting an Answer") If you are the author of a question, you can mark the best answer as accepted: 1. Expand your question. 2. Find the answer you want to accept. 3. Click **✓ Accept** next to that answer. The answer moves to the top of the list and is labelled **✓ Accepted Answer**. The question status changes to **ACCEPTED**. Click **✓ Accepted** again to remove the accepted status. ### Editing and Deleting Your Content[​](#editing-and-deleting-your-content "Direct link to Editing and Deleting Your Content") You can edit or delete your own questions and answers. **Questions:** Expand the question and click **Edit** or **Delete** in the action row. When editing, you can update the title, body, and topics. Click **Save** to confirm or **Cancel** to discard. **Quick title rename:** If you are the question author, you can click directly on the question title in the table to edit it inline without expanding the row. **Answers:** Expand the question, find your answer, and click **Edit** or **Delete**. ### Notifications[​](#notifications "Direct link to Notifications") The bell icon (🔔) in the toolbar shows a badge when you have unread notifications. * **New answer** — someone answered a question you posted. * **Answer accepted** — your answer was accepted by the question author. Click the bell to open the notification panel. All notifications are marked as read automatically when you open the panel. *** ## Configuration[​](#configuration "Direct link to Configuration") Administrators can control who is allowed to view, ask, and answer questions. Settings exist at two independent levels — space and global: | Settings page | Who can access | How to get there | | ------------------- | ------------------------------ | ------------------------------------------------------------------------------ | | **Space settings** | Space administrators | Open a space → **Space Settings** → **Apps** → **Modern Questions Settings** | | **Global settings** | Confluence site administrators | Top-right cog → **Settings** → **Apps** → **Modern Questions Global Settings** | Space settings apply only to questions posted within that space. Global settings apply to the site-wide Q\&A view (accessible from the top navigation **Apps** menu). Each scope is configured independently — changing one does not affect the other. ### Permissions[​](#permissions "Direct link to Permissions") Both the space settings page and the global settings page have the same three permission controls: | Permission | What it controls | | -------------- | -------------------------------------------- | | Who can view | Who can see the Q\&A list and read questions | | Who can ask | Who can post new questions | | Who can answer | Who can post answers | Each permission can be set to one of: | Option | Behaviour | | ----------------------- | ------------------------------------------------------- | | **Everyone** | All logged-in users | | **Selected users only** | Only the specific users you choose from the user picker | Click **Save permissions** to apply your changes. ### Topics[​](#topics "Direct link to Topics") Both settings pages have a **Topics** section. Topics created in space settings are scoped to that space; topics created in global settings are scoped to the site-wide view. They are separate lists. * **Rename a topic:** Click the topic name to edit it inline, then press Enter or click away to save. * **Delete a topic:** Click **Delete** next to the topic. This removes the topic from all questions it was attached to within that scope. New topics can also be created directly from the question form or the topic picker when asking or editing a question. *** ## Tips & Common Workflows[​](#tips--common-workflows "Direct link to Tips & Common Workflows") * **Find answers fast:** Use the **Answered** filter combined with a keyword search to quickly locate questions that already have accepted answers. * **Organise by team or project:** Create topics that match your team names or project codes, then use the topic chips in the toolbar to browse questions by area. * **Restrict a space:** If a space is used by a specific team, go to that space's **Modern Questions Settings** and set "Who can view" to **Selected users only** to keep it private. * **Follow up on your questions:** Check the notification bell regularly — it tells you when someone has answered your question or when your answer has been accepted. *** ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") **"Access Restricted" message appears instead of the Q\&A list** → The administrator has restricted viewing for this scope. Contact your space admin or Confluence admin to request access. **"Answering is restricted by administrator settings" appears** → Your account does not have permission to post answers in this scope. Contact the space or site admin. **Ask a Question button is greyed out** → You do not have permission to post questions in this scope, or the app settings are still loading. Wait a moment and try again, or contact your admin. **No questions appear after searching** → The search matches question titles only. Try a shorter or different keyword, or click **Clear filters** to reset all filters. **Notification bell shows a badge but the panel is empty** → The notifications were already marked as read in a previous session. The badge resets when you open the panel. ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [How to build FAQ sections in Confluence](/blog/how-to-build-faq-sections-confluence.md) * [Best Confluence apps for developers](/blog/best-confluence-apps-developers.md) Was this helpful?👍 Yes👎 No --- # Usage It's a macro app, so you can use it by two ways: * from the Confluence editor toolbar +, then search `Pagination Buttons for Confluence` * type `/` inside the Confluence editor, then type `Pagination Buttons for Confluence` This is the default UI after embedded into Confluence page: ![Default pagination buttons on a Confluence page](/assets/images/highlight1-ec1bf8e2b91e7a6d941fb5d5d5fc5105.png) You can click edit icon to config it: ![Clicking edit icon to configure pagination buttons](/assets/images/highlight2-9a108a824be1b0cf4380c50a9efef460.png) ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [Confluence page navigation FAQ](/blog/faq-confluence-page-navigation-apps.md) * [How to use numbered headings in Confluence](/blog/how-to-use-numbered-headings-confluence.md) Was this helpful?👍 Yes👎 No --- # Privacy Policy **Last updated:** May 19, 2026 NGPILOT, Inc. ("NGPILOT," "we," "us," or "our") operates a suite of applications ("Apps") available on the Atlassian Marketplace for Confluence and Jira. This Privacy Policy explains how we collect, use, store, and share information when you use our Apps, and how you can contact us about your privacy. ## 1. Data We Collect and Access[​](#1-data-we-collect-and-access "Direct link to 1. Data We Collect and Access") Our Apps are built entirely on **Atlassian Forge** and run within Atlassian's cloud infrastructure. This means: ### What We Access[​](#what-we-access "Direct link to What We Access") To provide App functionality, our Apps may access the following data through Atlassian's APIs: * **Confluence data:** Page content, space metadata, attachments, user-generated content (e.g., diagrams, code blocks, markdown, formatted text, templates, FAQs) * **Jira data:** Issue content, issue attachments, project metadata, custom fields, issue templates * **User context:** Display name, avatar, and account identifier provided by Atlassian's platform to render user-specific features ### What We Do NOT Collect[​](#what-we-do-not-collect "Direct link to What We Do NOT Collect") * Passwords or authentication credentials * Payment or billing information (handled by Atlassian) * Personal information beyond what Atlassian's platform provides through standard user context * Data unrelated to the App's functionality ### How Data Is Accessed[​](#how-data-is-accessed "Direct link to How Data Is Accessed") All data access occurs through Atlassian's official, permission-scoped Forge APIs. Our Apps only request the minimum scopes required for their functionality (principle of least privilege). Access is authenticated and authorized on every request. ## 2. How Data Is Used[​](#2-how-data-is-used "Direct link to 2. How Data Is Used") Data accessed by our Apps is used solely to provide the App's intended functionality. For example: * Rendering and displaying content (diagrams, code blocks, markdown, fonts, templates) * Processing and converting content between formats (import/export) * Generating visual elements (QR codes, charts, announcements) * Organizing and presenting information (FAQs, tables, task lists, questions) All data processing occurs within the Atlassian Forge runtime environment. **No data is sent to, processed by, or stored on any external servers, third-party APIs, or AI services outside of Atlassian's infrastructure.** ## 3. Data Storage and Retention[​](#3-data-storage-and-retention "Direct link to 3. Data Storage and Retention") ### Where Data Is Stored[​](#where-data-is-stored "Direct link to Where Data Is Stored") * **App configuration and user preferences:** Stored in Atlassian Forge Storage or Confluence/Jira Entity Properties, which reside within the customer's Atlassian cloud tenant * **Content created by the App:** Stored within the customer's Confluence or Jira instance as standard content * **No external storage:** We do not store any customer data on our own servers or any third-party infrastructure ### Data Residency[​](#data-residency "Direct link to Data Residency") Because our Apps run on Atlassian Forge, data residency follows the customer's Atlassian site configuration. Data remains in the Atlassian region selected by the customer's organization. For details, see [Atlassian's Data Residency documentation](https://www.atlassian.com/trust/data-residency). ### Retention[​](#retention "Direct link to Retention") Data stored within the customer's Atlassian instance is retained according to the customer's own data retention policies. When an App is uninstalled, any App-specific data stored in Forge Storage or Entity Properties is removed in accordance with Atlassian's app uninstallation procedures. ## 4. Third Parties and Subprocessors[​](#4-third-parties-and-subprocessors "Direct link to 4. Third Parties and Subprocessors") ### Atlassian[​](#atlassian "Direct link to Atlassian") Atlassian Corporation Plc is our sole platform provider. Atlassian hosts, secures, and operates the infrastructure on which our Apps run, including: * Atlassian Forge (compute runtime) * Forge Storage (key-value storage) * Atlassian Cloud (Confluence, Jira, and platform services) Atlassian's privacy practices are governed by their own [Privacy Policy](https://www.atlassian.com/legal/privacy-policy). ### No Other Third Parties[​](#no-other-third-parties "Direct link to No Other Third Parties") We do not share, send, or make available any customer data to any other third parties, subprocessors, analytics services, or advertising networks. ## 5. Data Sharing[​](#5-data-sharing "Direct link to 5. Data Sharing") We do not sell, rent, trade, or otherwise share personal data with third parties for their own use, except: * As required by applicable law, regulation, or legal process * To protect the rights, safety, or property of NGPILOT, our users, or the public * With the user's explicit consent ## 6. Your Rights and Choices[​](#6-your-rights-and-choices "Direct link to 6. Your Rights and Choices") Depending on your jurisdiction, you may have the following rights regarding your personal data: * **Access:** Request a copy of the personal data we hold about you * **Correction:** Request correction of inaccurate personal data * **Deletion:** Request deletion of your personal data * **Objection:** Object to the processing of your personal data * **Data portability:** Request your data in a structured, machine-readable format Since our Apps run on Atlassian Forge and most data resides in your Atlassian instance, many of these requests can be fulfilled directly through your Atlassian administration tools. For any requests specific to our Apps, please contact us using the details below. We aim to respond to all privacy-related requests within **30 days**. ## 7. Children's Privacy[​](#7-childrens-privacy "Direct link to 7. Children's Privacy") Our Apps are not directed to anyone under the age of 13. We do not knowingly collect personal information from children under 13. ## 8. Changes to This Privacy Policy[​](#8-changes-to-this-privacy-policy "Direct link to 8. Changes to This Privacy Policy") We may update this Privacy Policy from time to time. When we make changes, we will: * Update the "Last updated" date at the top of this page * Post the revised policy on this page * For material changes, provide notification through appropriate channels (e.g., App update notes, email) Changes become effective immediately upon posting. Continued use of our Apps after changes constitutes acceptance of the updated policy. ## 9. Contact Us[​](#9-contact-us "Direct link to 9. Contact Us") For any questions, concerns, or requests related to this Privacy Policy or our data practices: * **Email:** * **Support Portal:** We will respond to privacy-related inquiries within **30 days**. --- # User Docs PSD Attachments Viewer for Confluence is a macro app. You can use it by typing `/PSD Attachments Viewer for Confluence` in editor. > Make sure you have already .psd attachments attached into this page It will show the config UI page with a filter to show only .psd type attachments. Each attachment item has a radio button, you can and only can select one for each macro block. After you select one and click the save button, the config UI page will close and the macro UI will render your .psd attachment file in the page. ![PSD attachment viewer filter showing only .psd files](/assets/images/highlight1-7eec5a790c4917f8beeeefecad6b392f.png) ![PSD attachment viewer macro with radio button selection](/assets/images/highlight2-e02646347b3b9618050ae1fa1b2b53f5.png) ![PSD attachment file rendered and displayed in Confluence page](/assets/images/highlight3-76711e80e6d3481310ce7e2cded81af4.png) ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [Best Confluence apps for developers](/blog/best-confluence-apps-developers.md) Was this helpful?👍 Yes👎 No --- # QRCode for Confluence — User Guide ## Overview[​](#overview "Direct link to Overview") QRCode for Confluence lets you embed QR codes directly into Confluence pages and blog posts. Generate a QR code from any text or URL and display it inline on your page. ## Getting Started[​](#getting-started "Direct link to Getting Started") ### Inserting a QR Code[​](#inserting-a-qr-code "Direct link to Inserting a QR Code") 1. Edit a Confluence page 2. Type `/qrcode` in the editor and select **QRCode for Confluence** 3. Enter the text or URL you want to encode 4. Choose a size 5. Click **Save** to insert the QR code ### Re-editing[​](#re-editing "Direct link to Re-editing") Click on an existing QR code macro and select **Edit** to change the content or size. Your settings are preserved. *** ## Configuration Options[​](#configuration-options "Direct link to Configuration Options") ### Text / URL[​](#text--url "Direct link to Text / URL") Enter any text or URL to encode into the QR code. This can be a website URL, plain text, email address, phone number, or any string. ### Size[​](#size "Direct link to Size") | Size | Description | | ----------- | ------------------------------------------- | | **X-Small** | Compact QR code for tight layouts | | **Small** | Small QR code | | **Medium** | Standard size | | **Large** | Large QR code (default) | | **X-Large** | Extra-large QR code for maximum readability | *** ## Tips[​](#tips "Direct link to Tips") * Use the **Large** or **X-Large** size for QR codes that will be scanned from a distance (e.g., printed pages, posters) * Encode URLs with the full `https://` prefix for best scanning results * Keep the encoded text short — shorter content produces cleaner, easier-to-scan QR codes *** ## Support[​](#support "Direct link to Support") For issues or feature requests, please visit the app's listing on the Atlassian Marketplace. ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [How to use QR codes in Confluence](/blog/how-to-use-qr-codes-confluence.md) * [Best Confluence apps for developers](/blog/best-confluence-apps-developers.md) Was this helpful?👍 Yes👎 No --- # Usage ## How to open the editor[​](#how-to-open-the-editor "Direct link to How to open the editor") Click the "More actions" button and choose the menu item "Source Editor for Confluence" ![Opening the source editor from More actions menu](/assets/images/1-b6a4876795f21236f18849bf3b0ff6e4.png) The editor like this: ![Source editor interface](/assets/images/2-d420678799090f103185e4d0bf0a5d76.png) Then you can edit the raw storage of Confluence page. ## Format document[​](#format-document "Direct link to Format document") If you think the document is messy and want it to look clearer, you can use the "Format Document" function in the right-click menu. ![Right-click menu with Format Document option](/assets/images/3-feb01f953ac855870087e47b6550058c.png) ## Other functions[​](#other-functions "Direct link to Other functions") Use "F1" or "Ctrl+p" or "Command+p" to open command palette and see all editor functions ![Command palette opened with keyboard shortcut](/assets/images/4-c9fb664bbc5235706ca23a4299932968.png) ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [Confluence source editor comparison (Free vs Pro)](/blog/confluence-source-editor-comparison.md) * [Best Confluence apps for developers](/blog/best-confluence-apps-developers.md) Was this helpful?👍 Yes👎 No --- # Usage ## How to open the editor[​](#how-to-open-the-editor "Direct link to How to open the editor") Click the "More actions" button and choose the menu item **"Source Editor Pro for Confluence"**. ![Opening the source editor from More actions menu](/assets/images/1-5a33a97583ef383e7ed4b1aa3e054f24.png) Then you can edit the raw *storage format* (XML) of the Confluence page directly. > ⚠️ Editing storage format is powerful but dangerous. Please make sure you know what you are doing, or test on a sample page first. *** ## Top toolbar[​](#top-toolbar "Direct link to Top toolbar") ![Source editor toolbar with theme, find, and word wrap options](/assets/images/2-885f65240dee243b5dc667ffa3bb8d54.png) At the top‑right of the editor you will see a small toolbar: * **Theme** * Click the 🎨 palette icon to switch between editor themes. * Available themes: **Light**, **Dark**, and **High Contrast**. * Your preference is saved and will be remembered next time. * **Find** * Click the 🔍 icon to open the *Find* panel, similar to using `Ctrl+F` in the browser. * You can also simply use the `Ctrl+F` / `Cmd+F` shortcut inside the editor. * In **Diff View**, find will search in the **modified (right)** side. * **Toggle word wrap** * Click the text‑wrap icon to turn automatic word wrapping on or off. * When enabled, long lines will wrap to reduce horizontal scrolling; when disabled, long lines stay on a single row and you may need to scroll horizontally. * This button is only visible in normal edit mode. In **Diff View**, lines are always shown without wrapping to make differences easier to compare. *** ## Diff View[​](#diff-view "Direct link to Diff View") ![Diff view comparing original and edited content](/assets/images/6-e91bf52a121993698a9b4ab96a5b0b3e.png) When you change the XML, a **"Diff View"** button appears at the bottom‑right of the window. * Click **Diff View** to open a side‑by‑side comparison: * **Left side**: original content when the page was loaded. * **Right side**: your current changes. * You can continue editing only on the **right** side. * Click **Edit Mode** to go back to the normal single‑editor view. * The **Find** button still works in Diff View and searches on the right (modified) panel. This helps you review what will actually be saved back to Confluence. *** ## Format document[​](#format-document "Direct link to Format document") If you think the document is messy and want it to look clearer, you can use the **"Format Document"** function in the right‑click menu of the editor. ![Right-click menu with Format Document option](/assets/images/3-0080c038f3ae4fd77db578a2ad0aa471.png) The editor will automatically re‑indent and tidy up the XML structure to make it easier to read. If the XML structure is invalid, formatting may fail. In that case, fix the errors first and then try formatting again. *** ## Save & Cancel[​](#save--cancel "Direct link to Save & Cancel") At the bottom‑right of the editor: * **Save** * After a successful save, the Confluence page is reloaded and the editor is closed. * The button is disabled when: * There are no changes, * Or the editor is still loading, * Or a save operation is already in progress, * Or loading the source failed. * **Cancel** * Closes the editor **without saving** any changes. *** ## Other functions[​](#other-functions "Direct link to Other functions") Use `F1`, `Ctrl+P` (Windows / Linux) or `Cmd+P` (macOS) to open the **command palette** of the editor and see all available Monaco commands. ![Command palette opened with F1 shortcut](/assets/images/4-689cf9ab8504fe966cbde848539e72a3.png) Here you can trigger advanced actions such as: * More search / replace options. * Go to line / symbol. * Toggle minimap, render whitespace, etc. Most Monaco features work normally inside this Source Editor. ## Related Blog Posts[​](#related-blog-posts "Direct link to Related Blog Posts") * [Confluence source editor comparison (Free vs Pro)](/blog/confluence-source-editor-comparison.md) * [Advanced code blocks in Confluence](/blog/advanced-code-blocks-confluence.md) * [Best Confluence apps for developers](/blog/best-confluence-apps-developers.md) Was this helpful?👍 Yes👎 No --- # Security Policy **Last updated:** May 19, 2026 NGPILOT, Inc. ("NGPILOT," "we," "us," or "our") is committed to protecting the security of our customers' data. This Security Policy describes the technical and organizational measures we implement to secure our Atlassian Marketplace applications and related systems. ## 1. Architecture Overview[​](#1-architecture-overview "Direct link to 1. Architecture Overview") All NGPILOT Apps are built on **Atlassian Forge**, Atlassian's serverless development platform. This means: * Our Apps execute within Atlassian's managed cloud infrastructure * All data processing occurs within the customer's Atlassian cloud tenant * No data is transmitted to, stored on, or processed by any external servers or infrastructure outside of Atlassian * Our Apps use only Atlassian's permission-scoped APIs with the minimum required access (principle of least privilege) This "Runs on Atlassian" architecture significantly reduces the security surface area, as Atlassian manages the underlying infrastructure, networking, and platform security. ## 2. Data Storage and Encryption[​](#2-data-storage-and-encryption "Direct link to 2. Data Storage and Encryption") ### Data at Rest[​](#data-at-rest "Direct link to Data at Rest") * Customer data accessed or generated by our Apps is stored within the customer's Atlassian cloud instance (Confluence, Jira, or Forge Storage) * Atlassian encrypts data at rest using **AES-256** encryption * We do not maintain any separate databases, file storage, or external backups of customer data ### Data in Transit[​](#data-in-transit "Direct link to Data in Transit") * All communication between our Apps and Atlassian services is encrypted using **TLS 1.2 or higher** * Atlassian enforces HSTS (HTTP Strict Transport Security) on all connections * No data is transmitted outside of Atlassian's infrastructure ### Secrets Management[​](#secrets-management "Direct link to Secrets Management") * API keys, OAuth tokens, and other secrets are stored in Atlassian Forge Secure Storage * Secrets are never hardcoded in source code, committed to repositories, or included in logs or URLs * Secret rotation is performed following Atlassian's recommended practices ## 3. Access Control[​](#3-access-control "Direct link to 3. Access Control") ### App-Level Access[​](#app-level-access "Direct link to App-Level Access") * Our Apps use Atlassian Forge's scope-based permission model, requesting only the minimum scopes necessary for each App's functionality * Access is authenticated and authorized on every API request * Users can review and control App permissions through their Atlassian administration console ### Organizational Access[​](#organizational-access "Direct link to Organizational Access") * Access to development tools, source code repositories, and Atlassian Marketplace accounts requires **multi-factor authentication (MFA)** * Access is granted on a need-to-know basis using the principle of least privilege * Unique, strong credentials are required for all systems * Access is reviewed periodically and revoked when no longer needed ## 4. Development Security[​](#4-development-security "Direct link to 4. Development Security") ### Secure Development Lifecycle[​](#secure-development-lifecycle "Direct link to Secure Development Lifecycle") * **Peer code reviews** are required for all changes before merging to production * **Pull requests** are mandatory for deploying to production environments * Code changes are deployed through Atlassian Forge's secure deployment pipeline, which includes app signing and verification ### Code Quality and Testing[​](#code-quality-and-testing "Direct link to Code Quality and Testing") * Automated testing is integrated into the development process * Source code is analyzed for security vulnerabilities during development * We follow secure coding practices aligned with the **OWASP Top 10** guidelines ### Dependency Management[​](#dependency-management "Direct link to Dependency Management") * Third-party libraries are regularly reviewed and updated * Libraries with known critical or high-severity vulnerabilities are promptly remediated * We maintain awareness of vulnerability disclosures for all dependencies ## 5. Vulnerability Management[​](#5-vulnerability-management "Direct link to 5. Vulnerability Management") ### Security Bug Fix Policy[​](#security-bug-fix-policy "Direct link to Security Bug Fix Policy") We adhere to Atlassian's Marketplace Security Bug Fix Policy: | Severity | Resolution Timeframe | | -------- | ------------------------ | | Critical | Within 10 calendar days | | High | Within 4 calendar weeks | | Medium | Within 12 calendar weeks | | Low | Within 25 calendar weeks | ### Reporting Vulnerabilities[​](#reporting-vulnerabilities "Direct link to Reporting Vulnerabilities") We welcome and encourage responsible disclosure of security vulnerabilities: * **Email:** * **Support Portal:** We commit to: * Acknowledging vulnerability reports within **5 business days** * Providing an initial assessment and severity classification within **10 business days** * Keeping reporters informed of remediation progress * Not taking legal action against good-faith security researchers ### Vulnerability Scanning[​](#vulnerability-scanning "Direct link to Vulnerability Scanning") * We perform regular vulnerability assessments of our App code * Dependencies are scanned for known vulnerabilities (Software Composition Analysis) * Static code analysis is applied to identify potential security issues ## 6. Incident Response[​](#6-incident-response "Direct link to 6. Incident Response") ### Incident Detection and Reporting[​](#incident-detection-and-reporting "Direct link to Incident Detection and Reporting") * Security incidents may be detected through monitoring, customer reports, or third-party notification * All personnel are trained to report suspected security deviations immediately ### Incident Handling Process[​](#incident-handling-process "Direct link to Incident Handling Process") Our incident response follows these stages: 1. **Detection and Triage:** Identify and classify the incident based on severity and scope 2. **Containment:** Take immediate action to prevent further impact 3. **Investigation:** Determine the root cause, affected systems, and scope of impact 4. **Remediation:** Implement fixes to resolve the vulnerability or issue 5. **Notification:** Notify affected customers and Atlassian as appropriate 6. **Post-Mortem:** Conduct a review to identify improvements and prevent recurrence ### Notification[​](#notification "Direct link to Notification") * We will notify Atlassian of security incidents through the appropriate Atlassian security channels (ECOHELP) as required by the Marketplace Partner Agreement * Affected customers will be notified via email or through our support portal within **72 hours** of confirmed impact * Notifications will include the nature of the incident, what data was affected, and remediation steps taken ## 7. Monitoring and Logging[​](#7-monitoring-and-logging "Direct link to 7. Monitoring and Logging") * Access to development and deployment systems is logged and monitored * Failed authentication attempts and access control changes are tracked * Logs are retained for a minimum of **12 months** where applicable * Atlassian provides platform-level monitoring and logging for the Forge runtime environment ## 8. Business Continuity[​](#8-business-continuity "Direct link to 8. Business Continuity") Because our Apps run on Atlassian Forge, business continuity for the underlying infrastructure is managed by Atlassian, including: * Redundant infrastructure across availability zones * Automated failover and recovery * Regular backup and disaster recovery procedures For our development and deployment processes, we maintain: * Source code in distributed version control with full history * Documented deployment procedures * Ability to roll back to previous App versions through the Atlassian Marketplace ## 9. Compliance and Certifications[​](#9-compliance-and-certifications "Direct link to 9. Compliance and Certifications") ### Atlassian Platform Compliance[​](#atlassian-platform-compliance "Direct link to Atlassian Platform Compliance") Our Apps benefit from Atlassian's compliance certifications, including: * SOC 2 Type II * SOC 1 (SSAE 18 / ISAE 3402) * ISO/IEC 27001 * CSA STAR For full details, see [Atlassian Trust & Compliance](https://www.atlassian.com/trust/compliance). ### NGPILOT Compliance[​](#ngpilot-compliance "Direct link to NGPILOT Compliance") We are committed to maintaining security best practices as a Marketplace partner. We regularly review and update our security measures in alignment with Atlassian's Security Guidelines for Marketplace Partners. ## 10. Human Resources Security[​](#10-human-resources-security "Direct link to 10. Human Resources Security") * Personnel with access to development systems undergo security awareness training * Security responsibilities are clearly defined and communicated * Access to systems is promptly revoked upon role change or departure ## 11. Policy Review and Updates[​](#11-policy-review-and-updates "Direct link to 11. Policy Review and Updates") This Security Policy is reviewed at least annually and updated as needed to reflect changes in our practices, technology, or regulatory requirements. Material changes will be communicated through appropriate channels. ## 12. Contact[​](#12-contact "Direct link to 12. Contact") For security-related questions, concerns, or vulnerability reports: * **Email:** * **Support Portal:** We aim to respond to security inquiries within **5 business days**. --- # Simple Bulk Attachment Downloader - User Guide Related blog post: [Bulk download Jira attachments in one click](/blog/bulk-download-jira-attachments.md) Welcome to Simple Bulk Attachment Downloader! This guide will help you quickly download all attachments from your Jira issues in just a few clicks. ## 🚀 Quick Start[​](#-quick-start "Direct link to 🚀 Quick Start") ### What This App Does[​](#what-this-app-does "Direct link to What This App Does") * **Downloads all attachments** from Jira search results as a single ZIP file * **Organizes files automatically** by issue in clean folder structure * **Works 3x faster** with parallel downloading technology * **Integrates seamlessly** with Jira's issue navigator ### Before You Begin[​](#before-you-begin "Direct link to Before You Begin") * Ensure you have the app installed in your Jira instance * You need **read access** to the issues containing attachments you want to download * The app works with any Jira search results or saved filters *** ## 📋 How to Use[​](#-how-to-use "Direct link to 📋 How to Use") ### Step 1: Navigate to Your Issues[​](#step-1-navigate-to-your-issues "Direct link to Step 1: Navigate to Your Issues") 1. Go to **Issues** → **Search for Issues** in Jira 2. Use any search method: * **Quick Search**: Type keywords in the search bar * **JQL Query**: Use advanced Jira Query Language * **Saved Filters**: Select from your existing filters * **Project Browse**: Browse issues by project ### Step 2: Find the App[​](#step-2-find-the-app "Direct link to Step 2: Find the App") 1. Once you have your search results displayed, look for the **Simple Bulk Attachments Downloader** button 2. The button appears in the **issue navigator toolbar** (top of the search results) 3. Click the **Simple Bulk Attachments Downloader** button ![Screenshot: App Button Location](/assets/images/highlight1-cb35803d57e441e09f0b77405b5b8eb9.png) ### Step 3: Review Attachment Summary[​](#step-3-review-attachment-summary "Direct link to Step 3: Review Attachment Summary") The app will automatically analyze your search results and show: * **Issues found**: Total number of issues in your search * **Total attachments**: Number of files that will be downloaded * **Total size**: Estimated download size in MB * **Filter context**: Shows the JQL query being used ![Screenshot: Analysis Results](/assets/images/highlight2-8f5a4a4475804d848fda60b92532a023.png) ### Step 4: Download Attachments[​](#step-4-download-attachments "Direct link to Step 4: Download Attachments") 1. Click the **Download X Attachments as ZIP** button 2. Watch the **real-time progress** as files are downloaded in parallel 3. Your browser will automatically start downloading the ZIP file when complete ### Step 5: Access Your Files[​](#step-5-access-your-files "Direct link to Step 5: Access Your Files") 1. Open the downloaded ZIP file (usually in your Downloads folder) 2. Files are organized in folders by issue: `ISSUE-123 - Issue Summary` 3. Each folder contains all attachments from that specific issue ![Screenshot: ZIP File Structure](/assets/images/highlight3-fa8c6e45d4bf41e6f4fdb04c8ce31487.png) *** ## 🎯 Use Cases[​](#-use-cases "Direct link to 🎯 Use Cases") ### For Project Managers[​](#for-project-managers "Direct link to For Project Managers") **Collecting Deliverables** * Search for issues in your project: `project = "MY-PROJECT"` * Download all deliverables, documents, and assets in one go * Share organized folders with stakeholders ### For QA Teams[​](#for-qa-teams "Direct link to For QA Teams") **Gathering Test Evidence** * Filter by test execution issues: `labels = "test-execution"` * Download all screenshots, logs, and test artifacts * Archive evidence for compliance or reporting ### For Support Teams[​](#for-support-teams "Direct link to For Support Teams") **Case File Management** * Search support tickets: `project = "SUPPORT" AND created >= -30d` * Download customer-provided files, logs, and screenshots * Create organized case archives ### For Development Teams[​](#for-development-teams "Direct link to For Development Teams") **Release Preparation** * Filter by release version: `fixVersion = "1.2.0"` * Download all documentation, specs, and assets * Package release artifacts efficiently *** ## ⚡ Advanced Features[​](#-advanced-features "Direct link to ⚡ Advanced Features") ### Smart Parallel Downloads[​](#smart-parallel-downloads "Direct link to Smart Parallel Downloads") * **3-8x faster** than manual downloading * **Automatic concurrency control** optimizes speed based on file count * **Progress tracking** shows real-time download status * **Error handling** creates error files for failed downloads ### Intelligent Organization[​](#intelligent-organization "Direct link to Intelligent Organization") * **Folder structure**: `Issue-Key - Issue Summary/attachments` * **Original filenames** preserved * **Duplicate handling** maintains all files even with same names * **Clean naming** removes invalid characters for file system compatibility ### Seamless Integration[​](#seamless-integration "Direct link to Seamless Integration") * **Works with any JQL query** or saved filter * **No configuration required** - works immediately after installation * **Respects permissions** - only downloads attachments you can access * **Browser-native downloads** - uses your browser's download manager *** ## 🔧 Troubleshooting[​](#-troubleshooting "Direct link to 🔧 Troubleshooting") ### No Attachments Found[​](#no-attachments-found "Direct link to No Attachments Found") **Problem**: App shows "0 attachments" even though you see attachments in issues **Solutions**: 1. **Refresh the analysis** - Click "Refresh Analysis" button 2. **Check permissions** - Ensure you can view the attachments in individual issues 3. **Verify search results** - Make sure your search actually returns the expected issues ### Download Fails or Stops[​](#download-fails-or-stops "Direct link to Download Fails or Stops") **Problem**: Download progress stops or ZIP file is incomplete **Solutions**: 1. **Check network connection** - Ensure stable internet connection 2. **Try smaller batches** - Narrow your search to fewer issues 3. **Browser storage** - Clear browser cache and try again 4. **File size limits** - Very large downloads (>1GB) may timeout ### ZIP File Won't Open[​](#zip-file-wont-open "Direct link to ZIP File Won't Open") **Problem**: Downloaded ZIP file appears corrupted or won't extract **Solutions**: 1. **Re-download** - Try downloading again 2. **Different extraction tool** - Try a different ZIP utility 3. **Check file size** - Ensure download completed fully 4. **Browser issues** - Try a different browser ### App Button Missing[​](#app-button-missing "Direct link to App Button Missing") **Problem**: Can't find the Simple Bulk Attachments Downloader button **Solutions**: 1. **Check installation** - Verify app is installed in your Jira instance 2. **Refresh page** - Reload the issue navigator page 3. **Check permissions** - Ensure you have access to use Forge apps 4. **Contact admin** - Your Jira admin may need to enable the app *** ## 📊 Performance Tips[​](#-performance-tips "Direct link to 📊 Performance Tips") ### Optimize Download Speed[​](#optimize-download-speed "Direct link to Optimize Download Speed") * **Stable connection**: Use wired internet when possible for large downloads * **Close other tabs**: Reduce browser memory usage during downloads * **Batch processing**: For 100+ attachments, consider filtering by date ranges ### Manage Large Downloads[​](#manage-large-downloads "Direct link to Manage Large Downloads") * **Size estimation**: Check total size before downloading * **Storage space**: Ensure adequate disk space (ZIP files are compressed) * **Time planning**: Large downloads may take several minutes ### Best Practices[​](#best-practices "Direct link to Best Practices") * **Regular cleanup**: Delete old ZIP files to save disk space * **Organized searches**: Use specific JQL queries to get exactly what you need * **Permission check**: Verify access before starting large downloads *** ## 🆘 Support[​](#-support "Direct link to 🆘 Support") ### Getting Help[​](#getting-help "Direct link to Getting Help") * **Documentation**: Check this user guide first * **Jira Admin**: Contact your Jira administrator for installation issues * **App Support**: Use the support channels provided in the Atlassian Marketplace ### Reporting Issues[​](#reporting-issues "Direct link to Reporting Issues") When reporting problems, please include: * **Jira version** and **browser type** * **Search query** or filter used * **Number of issues** and **attachments** involved * **Error messages** or **screenshots** of the problem * **Steps to reproduce** the issue ### Feature Requests[​](#feature-requests "Direct link to Feature Requests") We're always improving! Suggest new features through: * **Marketplace reviews** - Leave feedback on the app listing * **Support channels** - Contact us through official support * **Community forums** - Discuss with other users *** ## 🎉 Tips for Success[​](#-tips-for-success "Direct link to 🎉 Tips for Success") ### Maximize Efficiency[​](#maximize-efficiency "Direct link to Maximize Efficiency") 1. **Use saved filters** for recurring download needs 2. **Combine with JQL** for precise attachment targeting 3. **Schedule regular downloads** for ongoing projects 4. **Share ZIP files** directly with team members ### Organize Your Workflow[​](#organize-your-workflow "Direct link to Organize Your Workflow") 1. **Create naming conventions** for your searches 2. **Use date ranges** to manage file volumes 3. **Archive old downloads** to keep workspace clean 4. **Document your processes** for team consistency ### Power User Tricks[​](#power-user-tricks "Direct link to Power User Tricks") 1. **Bookmark complex JQL queries** for quick access 2. **Use labels and components** to categorize attachments 3. **Combine with Jira automation** for advanced workflows 4. **Export attachment lists** before downloading for planning *** ## 📈 What's Next?[​](#-whats-next "Direct link to 📈 What's Next?") ### Upcoming Features[​](#upcoming-features "Direct link to Upcoming Features") * **Custom folder structures** - Choose your own organization * **Selective downloads** - Pick specific attachments * **Scheduled downloads** - Automatic recurring downloads * **Integration APIs** - Connect with other tools ### Stay Updated[​](#stay-updated "Direct link to Stay Updated") * **App updates** are automatic through Atlassian Marketplace * **New features** will appear in your existing installation * **Release notes** available in the marketplace listing *** **Happy downloading! 🎉** Was this helpful?👍 Yes👎 No --- # User Guide - Simple Bulk Issues Excel CSV Export for Jira Looking for the how-to walkthrough? Read the [complete guide: Export Jira issues to Excel/CSV](/blog/export-jira-issues-to-excel.md) — JQL examples, recommended field sets per use case, and best practices for recurring exports. ## Overview[​](#overview "Direct link to Overview") The Simple Bulk Issues Excel CSV Export app allows you to export filtered Jira issues to Excel (XLS/XLSX) or CSV formats with complete control over which fields to include. This guide will walk you through all the features and functionality. ## Getting Started[​](#getting-started "Direct link to Getting Started") ### Prerequisites[​](#prerequisites "Direct link to Prerequisites") * Jira Cloud instance * App installed and licensed * Appropriate permissions to view issues you want to export ### Accessing the Export Function[​](#accessing-the-export-function "Direct link to Accessing the Export Function") ![Screenshot: App Button Location](/assets/images/highlight1-807bb8bc0c497c576b35d9f19d1c0925.png) 1. Navigate to **Issues** > **Search for Issues** in Jira 2. Apply your desired filters using JQL or the visual filter interface 3. Once you have your filtered results, look for the **"Simple Bulk Issues Excel CSV Export for Jira"** action button 4. Click the action button to open the export dialog ## Using the Export Dialog[​](#using-the-export-dialog "Direct link to Using the Export Dialog") ![Screenshot: Configure](/assets/images/highlight2-fe20c4336d0b884ba630101fc1a14dff.png) ### Main Interface[​](#main-interface "Direct link to Main Interface") The export dialog consists of several key sections: #### Current Filter Display[​](#current-filter-display "Direct link to Current Filter Display") * Shows the JQL query that will be used for the export * Reflects your current filter settings from the issue navigator #### Field Selection Panel[​](#field-selection-panel "Direct link to Field Selection Panel") The field selection is the core feature that sets this app apart: **Quick Selection Buttons:** * **Select Default**: Chooses commonly used fields (Key, Summary, Status, Assignee, Reporter, Priority, Issue Type, Created, Updated, Project) * **Select All**: Selects all available fields * **Clear All**: Deselects all fields * **Field Counter**: Shows how many fields are currently selected **Available Fields:** * System fields (built-in Jira fields) * Custom fields (marked with "Custom" label) * Fields are sorted with system fields first, then custom fields alphabetically #### Export Options[​](#export-options "Direct link to Export Options") Three format options are available: * **CSV**: Comma-separated values, compatible with most spreadsheet applications * **XLS**: Legacy Excel format, compatible with older Excel versions * **XLSX**: Modern Excel format with better performance and features ![Screenshot: Export](/assets/images/highlight3-ff6197f0d5d3381ddadc53286d5ba6b7.png) ## Field Types and Data Handling[​](#field-types-and-data-handling "Direct link to Field Types and Data Handling") ### Supported Field Types[​](#supported-field-types "Direct link to Supported Field Types") The app intelligently handles various Jira field types: #### Basic Text Fields[​](#basic-text-fields "Direct link to Basic Text Fields") * **Key**: Issue key (e.g., PROJ-123) * **Summary**: Issue title * **Description**: Full description text (ADF converted to plain text) #### User Fields[​](#user-fields "Direct link to User Fields") * **Assignee**: Display name of assigned user * **Reporter**: Display name of issue creator * **Watchers**: List of users watching the issue #### Date/Time Fields[​](#datetime-fields "Direct link to Date/Time Fields") * **Created**: Issue creation date * **Updated**: Last modification date * **Due Date**: Target completion date * **Resolution Date**: When issue was resolved #### Selection Fields[​](#selection-fields "Direct link to Selection Fields") * **Status**: Current issue status * **Priority**: Issue priority level * **Issue Type**: Type of issue (Bug, Story, Task, etc.) * **Resolution**: How the issue was resolved #### Multi-Value Fields[​](#multi-value-fields "Direct link to Multi-Value Fields") * **Labels**: Comma-separated list of labels * **Components**: Project components * **Fix Versions**: Target release versions * **Affects Versions**: Versions where issue was found #### Custom Fields[​](#custom-fields "Direct link to Custom Fields") * Text fields * Number fields * Date fields * Select lists (single and multi-select) * User picker fields * And many more... ### Data Formatting[​](#data-formatting "Direct link to Data Formatting") The app applies intelligent formatting to ensure data is readable in spreadsheets: * **Dates**: Formatted as locale-appropriate date strings * **Users**: Shows display names rather than usernames * **Multi-select fields**: Values separated by commas * **Rich text**: ADF (Atlassian Document Format) converted to plain text * **Empty values**: Shown as blank cells ## Export Process[​](#export-process "Direct link to Export Process") ### Step-by-Step Export[​](#step-by-step-export "Direct link to Step-by-Step Export") 1. **Filter Issues**: Use Jira's issue navigator to filter issues 2. **Open Export Dialog**: Click the export action button 3. **Select Fields**: Choose which fields to include using checkboxes 4. **Choose Format**: Select CSV, XLS, or XLSX 5. **Start Export**: Click the appropriate export button 6. **Download**: File downloads automatically with timestamped filename ### Export Limitations[​](#export-limitations "Direct link to Export Limitations") * **Maximum Issues**: Up to 1,000 issues per export * **Performance**: Large exports may take a few moments to process * **Permissions**: Only exports issues you have permission to view * **Field Availability**: Only shows fields available in your Jira instance ### File Naming Convention[​](#file-naming-convention "Direct link to File Naming Convention") Exported files use the following naming pattern: ``` jira-issues-export-YYYY-MM-DD-HH-MM-SS.[format] ``` Example: `jira-issues-export-2024-01-15-14-30-25.xlsx` ## Tips and Best Practices[​](#tips-and-best-practices "Direct link to Tips and Best Practices") ### Optimizing Your Exports[​](#optimizing-your-exports "Direct link to Optimizing Your Exports") 1. **Filter First**: Always filter your issues before exporting to get exactly what you need 2. **Select Relevant Fields**: Only include fields you actually need to keep file sizes manageable 3. **Use Default Fields**: The default field selection covers most common use cases 4. **Test with Small Sets**: Try exporting a small number of issues first to verify field selection ### Common Use Cases[​](#common-use-cases "Direct link to Common Use Cases") #### Project Status Report[​](#project-status-report "Direct link to Project Status Report") **Recommended Fields:** * Key, Summary, Status, Assignee, Priority, Due Date, Progress #### Bug Analysis[​](#bug-analysis "Direct link to Bug Analysis") **Recommended Fields:** * Key, Summary, Issue Type, Status, Priority, Reporter, Created, Affects Versions #### Sprint Planning[​](#sprint-planning "Direct link to Sprint Planning") **Recommended Fields:** * Key, Summary, Story Points, Status, Assignee, Labels, Sprint #### Compliance Audit[​](#compliance-audit "Direct link to Compliance Audit") **Recommended Fields:** * Key, Summary, Created, Updated, Reporter, Assignee, Status, Resolution Date ### Working with Exported Data[​](#working-with-exported-data "Direct link to Working with Exported Data") #### Excel Tips[​](#excel-tips "Direct link to Excel Tips") * Use Excel's **Filter** feature to further analyze data * Create **Pivot Tables** for summary reports * Use **Conditional Formatting** to highlight important issues * **Freeze** the top row for easier scrolling #### CSV Tips[​](#csv-tips "Direct link to CSV Tips") * Open in Excel, Google Sheets, or any spreadsheet application * Use **Text to Columns** if formatting needs adjustment * CSV format is ideal for importing into other systems ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") ### Common Issues[​](#common-issues "Direct link to Common Issues") #### "No issues found matching the filter criteria"[​](#no-issues-found-matching-the-filter-criteria "Direct link to \"No issues found matching the filter criteria\"") * **Cause**: Your current filter returns no results * **Solution**: Adjust your filter in the issue navigator before exporting #### "Failed to load fields"[​](#failed-to-load-fields "Direct link to \"Failed to load fields\"") * **Cause**: Network connectivity or permissions issue * **Solution**: Refresh the page and try again, or contact your Jira administrator #### "Your license for this app is not active"[​](#your-license-for-this-app-is-not-active "Direct link to \"Your license for this app is not active\"") * **Cause**: App license has expired or is not properly configured * **Solution**: Contact your Jira administrator to renew or configure the license #### Export button is disabled[​](#export-button-is-disabled "Direct link to Export button is disabled") * **Cause**: No fields selected or app is still loading * **Solution**: Select at least one field and wait for the field list to load ### Performance Considerations[​](#performance-considerations "Direct link to Performance Considerations") * Large exports (500+ issues) may take 30-60 seconds * Complex custom fields may slow down processing * Network speed affects download time for large files ### Getting Help[​](#getting-help "Direct link to Getting Help") If you encounter issues not covered in this guide: 1. Check your Jira permissions 2. Verify the app license is active 3. Try with a smaller set of issues 4. Contact your Jira administrator 5. Reach out to app support with specific error messages ## Advanced Usage[​](#advanced-usage "Direct link to Advanced Usage") ### JQL Integration[​](#jql-integration "Direct link to JQL Integration") The app works seamlessly with any JQL query. Some advanced examples: ``` # Export all bugs created in the last 30 days project = "MYPROJECT" AND issuetype = Bug AND created >= -30d # Export issues assigned to specific users assignee in (john.doe, jane.smith) AND status != Closed # Export issues with specific custom field values "Custom Field Name" = "Specific Value" AND project = "MYPROJECT" ``` ### Automation Integration[​](#automation-integration "Direct link to Automation Integration") While the app requires manual triggering, you can: * Create saved filters for regular exports * Use Jira dashboards to quickly access common filter combinations * Document export procedures for team members ## Data Privacy and Security[​](#data-privacy-and-security "Direct link to Data Privacy and Security") * All data processing happens within Atlassian's infrastructure * No issue data is transmitted to external servers * Exported files are downloaded directly to your device * The app respects all Jira permissions and security settings ## Version History and Updates[​](#version-history-and-updates "Direct link to Version History and Updates") The app is regularly updated with new features and improvements. Updates are automatically applied to your Jira instance without requiring reinstallation. Was this helpful?👍 Yes👎 No ---