@ascii-graphs/renderer-confluence

Render any ASCII Graphs CellGrid as a native Confluence Cloud document in Atlassian Document Format (ADF). No Marketplace app, image upload, or external hosting is needed. Every chart supports native text colors with mode: "richText". The default is a monochrome code block; icicle partitions also support filled tables.

import { bar, layout } from "@ascii-graphs/core";
import { renderConfluence } from "@ascii-graphs/renderer-confluence";

const grid = layout(
  bar({
    title: "Deployments by region",
    data: [
      { label: "Europe", value: 42 },
      { label: "Americas", value: 31 },
    ],
  }),
  { width: 56, charset: "unicode" },
);

const document = renderConfluence(grid, { mode: "richText" });

renderConfluence returns a JSON-serializable object with type: "doc", version: 1, and a content array. Labels remain literal ADF text, including quotes, Markdown fences, and HTML characters. Without options, the chart is a plain-text codeBlock with wrapping explicitly disabled and line numbers hidden.

Options

| Option | Default | Meaning | | ------------ | ---------------- | ------------------------------------------------------------------------------ | | mode | "codeBlock" | "codeBlock" or colored "richText" for any grid; "table" for icicle bands | | theme | Semantic palette | Text colors in rich-text mode; band backgrounds in table mode; six-digit hex | | tableWidth | 960 | Table width in pixels, an integer from 48 to 1800 |

theme requires mode: "richText" or mode: "table"; it is rejected in the default mode so a request for colors cannot silently produce a plain snippet. tableWidth requires mode: "table".

| accessibility | Content after the chart | | ------------------ | --------------------------------------------------------- | | "both" (default) | Visible description, table caption, and native data table | | "description" | Visible description | | "table" | Table caption and native data table | | "none" | Chart only |

The table uses the grid's semantic source data, so full labels and values remain available even when the visual chart is narrow. Missing values become empty cells; zero remains 0. These are visible alternatives, not hidden ARIA content.

Colors for every chart

const document = renderConfluence(grid, {
  mode: "richText",
  theme: { series1: "#2563EB", positive: "#0F766E" },
  accessibility: "both",
});

Rich-text mode reads each cell's semantic foreground and bold style, so it works with bars, lines, heatmaps, trees, maps, partitions, and every other chart. It does not require band metadata or chart-specific options. Adjacent cells with the same style become a single text run with native textColor and strong marks. Rows use hardBreak; spaces become non-breaking spaces to avoid HTML whitespace collapse. Trailing whitespace is trimmed as in the text renderer.

The theme supports muted, accent, positive, negative, and series1–series4. Unstyled cells retain the page's text color. Descriptions and source tables use the same accessibility options as the other modes.

Layout tradeoff: ADF does not allow textColor together with inline code or inside a code block. Rich text preserves glyphs and row breaks, but Confluence controls its fonts and wrapping, so exact monospace alignment is not guaranteed. Use the default code-block mode when exact text geometry matters more than color. For both exact geometry and color, a separate image workflow is needed. Check the rendered page before relying on rich-text alignment.

The colored line-chart request is ready for the JSON bridge.

Native filled capacity bands

import { layout, partition } from "@ascii-graphs/core";
import { renderConfluence } from "@ascii-graphs/renderer-confluence";

const capacity = layout(
  partition({
    mode: "icicle",
    root: {
      label: "Capacity",
      value: 100,
      color: "positive",
      children: [
        {
          label: "Allocated",
          value: 60,
          color: "series2",
          children: [{ label: "Used", value: 35, color: "series3" }],
        },
        { label: "Reserve", value: 40, color: "muted" },
      ],
    },
  }),
  { width: 100 },
);

const document = renderConfluence(capacity, {
  mode: "table",
  tableWidth: 1000,
  theme: {
    positive: "#8ED04E",
    series2: "#B8A1FF",
    series3: "#FFE44D",
    muted: "#FFFFFF",
  },
});

This uses native tableCell.attrs.background, merged cells, explicit column widths, and centered paragraphs. It reads CellGrid.bands supplied by the core layout, never attempts to reconstruct values from ASCII glyphs. The band boundaries share the grid's horizontal scale, including leading, intermediate, and trailing unused space. Each hierarchy level becomes one table row.

Labels and the optional title remain complete even when the text chart would truncate them. labelAlign from the partition controls left, center, or right alignment. Black or white label text is selected for contrast against each background. Gaps have no background override or text. Zero-width nodes remain in the source data table, and a chart with no visible bands keeps its textual empty state instead of emitting an invalid empty table.

The default backgrounds use the same semantic palette as the HTML renderer. Any of muted, accent, positive, negative, and series1–series4 can be overridden with a six-digit hex value. CSS names, variables, and arbitrary CSS are not accepted. The chart table and optional source data table are separate; accessibility: "none" removes only the extra description and source table.

Supported scope: table mode currently requires an icicle partition grid with band metadata. Other chart types throw a helpful error in this mode; continue using mode: "richText" for their colors or mode: "codeBlock" for plain text. Existing plain exports are unchanged.

Appearance: this is a native table rendering with solid backgrounds, not a colored code block or a pixel-identical copy of the HTML chart. Confluence controls fonts, cell padding, borders, label wrapping, and theme mapping. Column widths use displayMode: "fixed"; narrow columns and long labels can still encounter editor constraints. Increase grid resolution or table width when needed, and verify the saved page in the intended Confluence client.

The colored compute-capacity request is ready for the JSON bridge.

Send through an LLM's Confluence tool

For Atlassian Rovo's createConfluencePage or updateConfluencePage, pass contentFormat: "adf" and body: JSON.stringify(document) alongside the tool's site and page/space arguments. Code-block mode gives explicit control over wrapping; a Markdown-only connector may not preserve that setting.

For the Confluence Cloud REST API v2, the same document goes in a different envelope:

const body = {
  representation: "atlas_doc_format",
  value: JSON.stringify(document),
};
// Include `body` with the other required fields in a page create/update request.

The renderer does not authenticate, make network calls, or publish pages. When updating an existing page, read and preserve its current document and merge the generated content nodes into the intended section. Sending this chart-only document as the entire page body would replace the page's other content.

Limits and compatibility

• This targets Confluence Cloud ADF, not Data Center storage XML or wiki markup.
• Code-block mode preserves text and Unicode shapes, without color. Rich-text mode colors any chart's glyphs; table mode maps icicle band colors to native cell backgrounds. None embeds ANSI, HTML styling, or interactivity. Exact appearance depends on Confluence.
• Snippets are editable text snapshots. Keep the chart specification in your workflow and regenerate the output when data changes; editing the companion table does not automatically redraw the chart.
• If a connector rewrites the ADF or a viewer ignores snippet attributes, verify wrapping is off. Start with 48–64 columns for typical documentation pages.
• This package generates the documented ADF structure. Local tests do not replace a round-trip rendering check in your Confluence site.

For an exact image of the HTML colors and typography, a separate integration could render the existing HTML to a PNG and attach it, or use a Forge macro for custom rendering. Neither is implemented here.

See the Confluence integration guide for a JSON-only LLM workflow and API examples.

References: ADF codeBlock, ADF table cells, ADF table sizing, ADF text color, ADF inline code, Cloud page API, Cloud code snippets.