# Knowledge bases

Knowledge bases and technical documentation are among the **most demanding test cases** for any Confluence add‑on. Pages are often extremely long, mixing prose, code examples, screenshots, diagrams, and sometimes mathematical notation. Without strong structure, they quickly become difficult to scan and intimidating for casual readers. Users resort to browser search (`Ctrl+F`) rather than navigating logically structured sections.

As documentation grows, **maintaining consistency across hundreds of pages** becomes challenging. Different authors introduce their own conventions for tips, warnings, FAQs, and examples; the same concepts are worded differently in various places. External tools like Just Add+ or standalone PlantUML apps may be used for specific embedding needs, further fragmenting the experience. Over time, this makes it harder to reorganize or refactor documentation.

Capable’s Formatting, Diagrams, Markdown, Images, and Search capabilities are specifically designed to bring this **diverse content under a single “governed” umbrella**, while still giving technical writers the expressive power they need.

---

## [#](#how-capable-formatting-helps)How Capable Formatting helps

Capable Formatting tackles documentation problems on two fronts: **structure and emphasis**. Structurally, macros like Tabs, Panels, and accordions (expanders) allow authors to break long content into digestible chunks without spreading it across multiple pages. A common pattern is to have a “Concept / How‑to / FAQ / Troubleshooting” tab set at the top of a product or feature page, with each tab focusing on a different aspect. While Tabs are in beta and should be used judiciously, even a few high‑value tabs can significantly improve navigation for readers.

For emphasis, macros like **Callouts, Alerts, and Tooltips** can highlight warnings, best practices, and definitions within a dense page. For instance, all “Caution” messages can be implemented using a standard Alert style, while “Pro tips” use a different Panel variant. This not only makes pages easier to skim, but also gives documentation leads a way to enforce visual consistency by defining which macro styles should be used for each type of note.

Technical writers also benefit from Capable’s **Markdown, Code, and LaTeX macros**, which allow them to embed code samples, API references, and mathematical formulas in a way that is both editable and nicely formatted. Combined with diagrams for architecture and flows, these tools make Capable an attractive consolidation target for teams currently relying on a patchwork of Just Add+, PlantUML, and diagramming apps.

---

## [#](#key-features-and-macros-to-highlight)Key features and macros to highlight

One original recommendation is to define **canonical page types**—for example, “Concept,” “How‑to,” “Runbook,” and “FAQ”—each with its own macro conventions (which callout colors, which sections, where diagrams go). The use case page can then show how these templates plug into higher‑level structures like a product documentation hub, where Cards and Banners link to each major area.

The macro selection should also anticipate **migration from legacy formatting packs**. For example, if an organization is replacing Aura or Mosaic, the use case page can note that most Aura Cards, Panels, and LaTeX macros can be migrated automatically to Capable equivalents. This lowers the barrier to standardizing on Capable conventions.

### [#](#footnotes)Footnotes

Use footnotes to add supporting detail, citations, or extra context without interrupting the main reading flow.

![Footnotes macro in Confluence](https://help.gocapable.com/images/69281112-9de8-40fe-88a6-cfaafda993c9.webp)

---

### [#](#tabs)Tabs

Use tabs to segment dense documentation into clear Concept, How‑to, FAQ, and Troubleshooting sections.

Getting startedGuidelinesTroubleshootingAbout us

Welcome aboard!

You can include formatting, tables and images, panels etc.

ℹ️

Here is a panel

| **Table** | **Table** | **Table** |
| --------- | --------- | --------- |

This is some cards - we are working to align the styling.

[![Banana](https://images.unsplash.com/photo-1528825871115-3581a5387919?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=M3w2MDM1MTR8MHwxfHNlYXJjaHwxfHxiYW5hbmF8ZW58MHx8fHwxNzU0MTY2OTY1fDA&ixlib=rb-4.1.0&q=80&w=1080)BananaBananas are soft, yellow and sweet - great with porridge oats.](https://www.gocapable.com)

[![Mango](https://images.unsplash.com/photo-1551649001-9c071b61f26c?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=M3w2MDM1MTR8MHwxfHNlYXJjaHwxOHx8bWFuZ298ZW58MHx8fHwxNzU0MTcwNDI1fDA&ixlib=rb-4.1.0&q=80&w=1080)MangoMangoes are a tropical fruit which are very sweet. Try it with pineapple.](https://www.gocapable.com)

[![Orange](https://images.unsplash.com/photo-1592187270271-9a4b84faa228?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=M3w2MDM1MTR8MHwxfHNlYXJjaHw3fHxvcmFuZ2V8ZW58MHx8fHwxNzU0MTY3NTMyfDA&ixlib=rb-4.1.0&q=80&w=1080)OrangeOranges are a round citrus fruit - great for breakfast, ideally juiced!](https://www.gocapable.com)

You can include macros like diagrams within tabs too!

We’re a small, cross‑functional team focused on making complex tasks simple. Our aim is to deliver clear, reliable solutions that help people get work done with confidence.

---

### [#](#panels-alerts-callouts)Panels/Alerts/Callouts

Use panels, alerts, and callouts to highlight warnings, tips, best practices, and other important guidance consistently.

Built-in panels:

ℹ️

This is an info.

⚠️

This is a warning panel.

❌

This is an error panel.

Custom panels:

---

### [#](#code-macros)Code macros

Use code macros for syntax‑highlighted examples and for documentation imported from repositories or templates.

![image-20260409-212350.png](https://help.gocapable.com/images/ae61fdb7-8b55-4483-b64a-aabae29aa944.webp)

---

### [#](#latex-math)LaTeX Math

Use LaTeX Math to present equations clearly in technical, engineering, or scientific documentation.

x2+y2=1y=1−x2\\begin{align\*} x^2 + y^2 &= 1 \\\\ y &= \\sqrt{1 - x^2} \\end{align\*}x2+y2y​\=1\=1−x2​​

---

### [#](#diagram-macros-suite-or-diagram-app-required)Diagram macros (suite or diagram app required)

Use diagram macros to embed architecture, sequence, workflow, and process diagrams directly alongside the relevant explanation.

![Sankey](https://help.gocapable.com/images/att1248657477.svg)

---

## [#](#example-knowledge-structures)Example knowledge structures

To make documentation patterns concrete, the use case page should outline three archetypal structures: **Product documentation hub**, **API reference overview**, and **Internal runbook library**.

| **Knowledge structure**   | **Layout & macro highlights**                                                                                                               |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Product documentation hub | Hub page with Banner and Cards for each area (“Getting started,” “User guides,” “Admin docs”); Cards link to concept/how‑to templates       |
| API reference overview    | TOC + Tabs for “Overview, Authentication, Endpoints, Errors”; Code/Markdown for examples; LaTeX for formulas; diagrams for flows            |
| Runbook library           | Index page with Cards by system or severity; each runbook uses standard sections (Symptoms, Diagnosis, Resolution) with Panels and Diagrams |

Each structure benefits from **consistent tagging and naming conventions**, which Capable’s Search explorer can leverage to filter by product, version, or domain. For example, all runbooks might include a “Runbook” label and system name, making it easy to build a dynamic index page.

The documentation use case page should also show how these structures can be **published externally** via Capable Sites or Scroll Viewport integrations, preserving macros like Banners, Cards, and Buttons to create customer‑facing help centers that reuse the same content.

---

## [#](#implementation-tips)Implementation tips

First, invest in **page templates with built‑in macros**, not just style guides. For example, a “Runbook” template might pre‑populate sections with Panels labeled “Symptoms,” “Checks,” “Workaround,” and “Permanent fix,” plus placeholders for diagrams. This makes it easy for engineers to fill in content without worrying about design. Templates should live in a clearly labeled “Documentation templates” space or section and be linked from the use case page.

Second, align macros with **documentation governance**. Use Approvals to enforce review of high‑risk content (e.g., security procedures, compliance policies), and Calendars to schedule periodic reviews. Publishing rules can ensure that only approved versions appear in official knowledge base spaces. The use case page can outline a simple “draft → review → published” flow that documentation teams can adopt without needing Comala‑level workflow complexity.

Third, plan **macro migration** explicitly. For organizations using Just Add+ to embed Markdown, LaTeX, and diagrams, Capable offers migration tooling that can convert many macros to Capable equivalents. The use case page should recommend running a macro inventory, mapping each macro family to Capable alternatives, and then updating templates and style guides to reflect the new patterns.