Quarkdown: From Data to Tables and Diagrams

Maintaining a table by hand in Markdown is busywork; the moment the data changes, you start over. Diagrams aren't possible in plain Markdown at all — you export images from another tool and hope they stay current. Quarkdown flips this: data is the source, tables and diagrams are the automatically generated result. After the layout from part 4, it now gets data-driven.

Generating tables

You don't necessarily have to type tables cell by cell. .table combines several tables column-wise — together with a loop a table is generated programmatically:

.table
    .repeat {3}
        n:
        | Column .n |
        |-----------|
        | Cell .n:1 |
        | Cell .n:2 |

The counterpart is .tablebyrows: optional headers plus a list of rows. Ideal when your data is already a list:

.var {headers}
   - Name
   - Age
   - City

.tablebyrows {.headers}
    - - John
      - 25
      - NY
    - - Lisa
      - 32
      - LA

Reading CSV directly

It gets genuinely practical with .csv {path}: Quarkdown loads a CSV file and turns it into a table — the first row is always the header.

.csv {assets/people.csv} caption:{People data.}

With mode:{markdown} Quarkdown interprets cell content as inline Quarkdown — then formatting and function calls are allowed in the cells:

Name,  Favorite drink, Age
Alice, Coffee,         .subtract {2026} {1995}
Bob,   *Pepsi*,        .subtract {2026} {2001}

So the table computes its ages itself at compile time. Loaded CSV tables can then be processed further — for instance extracting single columns (useful for charting in a moment).

Reading files

.csv is just a special case of the more general principle: Quarkdown can read files. .read {path} returns the text content, optionally limited to a line range (lines:{3..8}, including open ranges like ..8 or 3..). This shines combined with other functions — for example loading a code snippet from the real source file into a code block instead of copying it:

.code
    .read {assets/point.ts}

That keeps your document in sync with the code it shows — an underrated advantage for technical documentation.

XY charts

For 2D line and bar charts there's .xychart (built internally on Mermaid). The Y values come from the body — as a static list, from a loop, or directly from a CSV column:

.xychart bars:{yes} x:{Months} y:{Revenue} yrange:{100..}
    - 250
    - 500
    - 350
    - 450

The trick is the seamless connection to scripting and data. A computed curve comes straight out of a loop with math functions …

.xychart
    .repeat {100}
        .1::pow {2}::divide {100}

… and a chart from real business data pulls its values from the columns of a CSV:

.xychart
    .tablecolumn {2}
        .csv {assets/sales.csv}

With caption the diagram is additionally numbered as a figure — more on that in the part about academic writing.

Mermaid diagrams

For everything else — flowcharts, sequence, class and pie diagrams — .mermaid brings full Mermaid interoperability:

.mermaid
    flowchart TD
        A([Start]) --> B[Login]
        B --> C{Correct?}
        C -- Yes --> D[Dashboard]
        C -- No --> E[Error message]

Here too Quarkdown's core principle applies: function calls are allowed in the Mermaid code. You can use variables, compute values, or load the diagram code from a file via .read {chart.mmd}. With caption the Mermaid diagram is also numbered as a figure.

FAQ

Do I need to know Mermaid to use diagrams?

Not for .xychart — that's pure Quarkdown with parameters and a list of values. For free-form diagram types (flowchart, sequence, class) you need Mermaid syntax; but it's well documented and you can start small.

Where does the data for a chart come from?

From four sources that mix freely: a static list, a loop (computationally generated), the columns of a CSV table, or a variable. Exactly this interlocking of data and scripting is Quarkdown's strength over pure markup languages.

Do CSV tables stay in sync with the source file?

Yes. .csv re-reads the file at compile time — change the CSV and the table changes on the next build automatically. The same applies to .read-loaded code snippets.