Tables and diagrams

Not every part of an article is prose or code. A comparison between three options wants a table, and a resolution order or a request path wants a diagram. Both are written as ordinary markdown, and neither is routed through the code pipeline.

Tables

Tables use pipe syntax: a header row, a delimiter row, then one row per record. The outer pipes are optional, and the columns do not have to line up in the source.

1| Annotation | Applies to | Effect |
2| --- | --- | --- |
3| `!mark` | One line | Highlights the line |
4| `!diff +` | One line | Marks the line as inserted |
5| `!word-wrap` | The block | Wraps long lines in place |

Annotation	Applies to	Effect
`!mark`	One line	Highlights the line
`!diff +`	One line	Marks the line as inserted
`!word-wrap`	The block	Wraps long lines in place

Inline markdown works inside cells, so a cell can carry code, emphasis, or a link. A cell cannot carry a block: no paragraphs, lists, or fenced code. A table that needs those is usually a set of headed sections instead.

Column alignment

Colons in the delimiter row set alignment per column. :--- aligns to the start, :---: centres, and ---: aligns to the end. A column with no colons is start-aligned.

1| Package manager | Install | Exec |
2| :--- | :---: | ---: |
3| Yarn | `add` | `dlx` |
4| pnpm | `add` | `dlx` |
5| npm | `install` | `npx` |

Package manager	Install	Exec
Yarn	`add`	`dlx`
pnpm	`add`	`dlx`
npm	`install`	`npx`

Width

A table wider than the article column scrolls sideways rather than crushing its cells, and header cells do not wrap. Short column headings and short cells therefore read better than a table that has to be scrolled to be understood.

Diagrams

A fenced block tagged mermaid is rendered as a diagram. The body is Mermaid source, which covers flowcharts, sequence diagrams, state diagrams, class diagrams, and entity relationship diagrams among others.

1```mermaid
2flowchart LR
3  mdx[MDX file] --> remark[remark plugins]
4  remark --> codehike[CodeHike]
5  codehike --> page[Rendered page]
6```

Diagrams are worth reaching for when the subject is a shape: an architecture, a dependency graph, a workflow, or a set of state transitions. A diagram that restates a two-item list is noise.

How the site treats them

A mermaid fence is claimed before CodeHike sees it. Code annotations such as !mark and !diff therefore have no meaning inside one, and a diagram carries none of the code-block chrome: no language label, no line numbers, and no copy button.

Colours come from the site theme rather than from Mermaid's own palettes, so a diagram takes on the theme family of the section it sits in and follows light and dark along with the rest of the page. Node and edge styles written into the diagram itself still win, which is the point of writing them.

The drawing happens in the browser, and the library is fetched only for pages that contain a diagram. If the source does not parse, the page prints it as text rather than failing.