8 posts tagged with "documentation"

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.

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.

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.

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 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.

Mermaid supports 29 diagram types — from flowcharts and sequence diagrams to C4 architecture, swimlanes, Gantt charts, ER diagrams, git graphs, and more. With Mermaid Plus for Confluence, all 29 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.

If you are deciding which diagram type fits your use case, jump to 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.

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.

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.

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.