The rules

  1. Code, Mermaid, stage diagrams, tables, links

13. Code, Mermaid, stage diagrams, tables, links

Highlighted words: ==text==#

Two = on each side mark a phrase to stand out, in a heading or in body text:

markdown
## Five things ==to keep==

Every team was green; ==the customer still waited==.

It renders as <span class="hl">…</span>, so a theme decides the look: the built-in themes underline it with a band of the accent colour, and AceMQ Pro sweeps the band in as the slide arrives. It nests (==**bold** words==), stays on one line, and leaves code, a single = and === alone. Plain-text copies of a title (the tab, the teleprompter, search) drop the marks.

Code from files, highlighted lines, callouts and tabs#

These work on slides and in documents (labs, articles, guides).

Code from a file. An include of anything that is not .md / .adoc becomes a code block, highlighted by the file's extension:

markdown
<!-- include: src/App.java -->                     the whole file
<!-- include: src/App.java lines=5-10 -->          lines 5 to 10 (also 5-, -10, 5-10,20-24)
<!-- include: src/App.java tag=retry -->           between tag::retry[] and end::retry[]
<!-- include: src/App.java tag=retry hl=3-6 title=Java lang=java -->

Fence attributes. After the language of a code fence:

markdown
```java title="Retry.java" hl="3,5-6" linenos start=12

title= shows in the code block's header bar (documents), hl= highlights lines (counted from the first line shown), linenos shows line numbers, from start= (default 1). Copy never copies the numbers.

The language may be left out or written the pandoc way; all of these read the same: ```xml title="config.csproj", ``` title="config.csproj" (no language: the title's extension names it, .csproj → xml, .go → go, Dockerfile → dockerfile), ```{.xml title="config.csproj"} and ```xml {title="config.csproj"}.

Callouts. End a code line with <N>, bare or as its comment (// <1>, # <1>, -- <1>, <!-- 1 -->), and write the explanations right after the block, one <N> text line each:

markdown
```java
var key = order.id();                     // <1>
sleep(Duration.ofSeconds(30));            // <2>
```
<1> The order id is the idempotency key.
<2> One retry only, thirty seconds later.

The markers become numbered badges (and leave the code, so Copy copies clean code); hovering a badge or its line lights up both. si check reports a marker without a line and a line without a marker.

Tabs. <!-- tabs --> turns the code blocks that follow it (with their callouts, up to the first other block) into one group of tabs, labelled by title= or the language:

markdown
<!-- tabs -->
<!-- include: code/Retry.java tag=retry title=Java -->
<!-- include: code/retry.py tag=retry title=Python -->
```bash title="curl"
curl -X POST localhost:8082/orders/4711/pay
```

In a document, choosing a tab switches every group on the page that has a tab with the same label, and the choice is remembered for the next page. On a slide the group switches on its own. Print shows every tab, labelled. ← / → move between tabs.

Code and diffs from git. Paste a GitHub permalink (on GitHub: the file, then Copy permalink), or name the repo, path and commit:

markdown
<!-- code: https://github.com/acme/app/blob/3f2a9c1/src/App.java#L5-L10 -->
<!-- code: https://github.com/acme/app/blob/3f2a9c1/src/App.java tag=retry hl=2 -->
<!-- code: path=src/App.java ref=3f2a9c1 tag=retry -->        repo: from the front matter
<!-- code: repo=../app path=src/App.java ref=HEAD -->         a local clone (git show)
<!-- diff: https://github.com/acme/app/commit/3f2a9c1 path=src/App.java -->
<!-- diff: https://github.com/acme/app/compare/v1.1...v1.2 path=src/ -->
<!-- diff: repo=../app ref=v1.1..v1.2 path=src/App.java -->

Slides in a document. A document (lab, article, guide page) can show a deck, or some of its slides, playable in place:

markdown
<!-- slides: ../decks/talk.md -->                     the whole deck
<!-- slides: ../decks/talk.md 23-24 -->               slides 23 to 24 (or one: 23)
<!-- slides: ../decks/talk.md#live-a-first-broker --> the slide with that heading id

The deck is rendered when the page is built, self-contained in a frame of the deck's aspect: click it, then the arrow keys step through slides and build steps; canvases animate. The caption names the deck. si check reports a missing deck, a range past its end and an unknown heading id. On a slide this directive is a problem (decks do not nest).

AsciiDoc maps onto the same features: include::App.java[lines=5..10], include::App.java[tag=retry] (tags=a;b), .Retry.java before a listing (the title), [source,java,highlight=3;5..6] and %linenums; <1> callouts are written the same way.