Guides

Validation

The plugin checks every chart while parsing and adds the problems to meta.issues, so you can reject a document before publishing it:

import { parseMarkdown } from "comark";
import charts from "comark-charts";

const { meta } = await parseMarkdown(markdown, { plugins: [charts()] });
if (meta.issues.length) throw new Error(meta.issues.join("\n"));

Each issue names its chart by its position in the document and says how to fix it:

`::chart` 2: row 3 has `41 kB` in `size`, which isn't a number. Write the number alone, such as `1200` or `1,200`, and put the unit in the header, such as `size (ms)`.

It reports unknown props and types, columns that x or y name but the table doesn't have, cells that aren't numbers, tables without rows or with unnamed or repeated columns, an x value that appears twice, content besides the table and its annotations, and data that doesn't fit the type: a line or an area of one row, a scatter without numbers on x, a dumbbell with one column, a pie or a waterfall with several, and a pie with a negative number or nothing but zeros.

Annotations are checked too: a missing or unknown at, a series the chart doesn't draw, and the mark, color, and side, as comark-annotate checks them on screenshots.

Rendering never throws. A cell that isn't a number is left out, a mark it can't place is left out, a type that doesn't fit falls back to the default, a pie or a waterfall draws its first column, and a chart with nothing to draw shows its content as it is. comark-linter reports the same issues with their line numbers.

Size

A chart keeps the size its text was set for, sized to fit its card with room for its labels, rather than stretching to the column, so labels read the same in every chart. Values sit on the marks when they fit; on crowded or stacked bars, or with negative numbers, the value axis reads them instead. Lines name their series at their ends unless the ends sit close together, and then a legend does. No row is ever dropped: a long sideways chart grows taller. A narrower column scrolls it sideways, and print shrinks it to the page. A chart with marks shrinks to fit instead, since its marks sit at percentages of the chart.

Renderers

The parse plugin draws every chart, so Vega runs where you parse, on the server or at build time, and never in the browser. Each renderer only places the SVG it wrote:

The Vue, React, and Svelte components add the styles when they mount; to load them with your CSS instead, so a server-rendered page doesn't shift, import comark-charts/style.css. Marks come from comark-annotate, which renders only to HTML, so the other renderers draw the chart without them.

Charts are static: there are no tooltips, and the Data table holds every number. To check documents without drawing them, as comark-linter does, pass charts({ draw: false }).