# Quarkdown: From Data to Tables and Diagrams

> Part 5 of the Quarkdown series: generate tables, read CSV files, plot XY charts and embed Mermaid diagrams — data-driven, right inside the document.

Source: https://www.jpkc.com/db/en/blog/quarkdown-daten-diagramme/

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](https://www.jpkc.com/db/en/blog/quarkdown-layout/), 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](https://www.jpkc.com/db/en/blog/quarkdown-funktionen-skripting/) a table is generated programmatically:

```markdown
.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:

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

```markdown
.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:

```markdown
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:

```markdown
.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:

```markdown
.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 …

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

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

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

With `caption` the diagram is additionally [numbered](https://quarkdown.com/wiki/numbering) 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](https://mermaid.js.org/intro/) interoperability:

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

## Further reading

The layout fundamentals for this are in [part 4: Stacks, Containers, Boxes & Grids](https://www.jpkc.com/db/en/blog/quarkdown-layout/). Next up is **academic writing**: TeX formulae, bibliography, cross-references, footnotes and the paper library. The complete reference for tables and diagrams is in the [official wiki](https://quarkdown.com/wiki).