Example Guide

This page is a quick reference for writing content on this site: markdown, Kroki diagrams, tabbed blocks, interactive tables, and code snippets.

Markdown basics

Text can be bold, italic, or strikethrough.

Tip

Use Starlight asides for tips, notes, and cautions.

Named note

You can give asides a custom title.

Custom blocks configured on this site:

Advantages

Advantage callout (:::success).

Disadvantages

Disadvantage callout (:::warn).

Info

Info callout (:::info).

Diagrams (Kroki)

Fence with the diagram language (or kroki type=…). These render at build time.

Diagrams.net (Draw.io)

For architecture diagrams authored in Draw.io, paste the uncompressed XML into a diagramsnet block.

Also works: mermaid, graphviz, excalidraw, structurizr, diagramsnet, c4 / c4plantuml, vega / vegalite, goat, and the types below. Point PUBLIC_KROKI_SERVER_URL at a core that has the diagramsnet companion enabled.

Supported diagram types

Fence with the language in Fence. Friendly names c4, vega-lite, and drawio are remapped to Kroki’s API types.

Category	Diagram	Fence
UML	Block diagram	blockdiag
UML	Sequence diagram	plantuml, mermaid, seqdiag
UML	Activity diagram	plantuml, mermaid, actdiag
UML	Network diagram	nwdiag
UML	Use case diagram	plantuml
UML	Class diagram	plantuml, mermaid
UML	State diagram	plantuml, mermaid
UML	Object diagram	plantuml
UML	Deployment diagram	plantuml
UML	Timing diagram	plantuml, wavedrom
UML	Entity relationship diagram	erd, plantuml, mermaid
C4	C4 context diagram	c4plantuml / c4
C4	C4 container diagram	c4plantuml / c4
C4	C4 component diagram	c4plantuml / c4
C4	Software architecture (Structurizr DSL)	structurizr
C4	System landscape diagram	structurizr
C4	System context diagram	structurizr
C4	Container diagram	structurizr
C4	Component diagram	structurizr
C4	Dynamic diagram	structurizr
C4	Deployment diagram	structurizr
Diagram	Object oriented graph	graphviz / dot, d2
Diagram	Work breakdown structure	plantuml
Diagram	Mind map diagram	plantuml, mermaid
Diagram	Gantt diagram	mermaid, plantuml
Diagram	Ditaa diagram	ditaa
Diagram	Packet diagram	packetdiag
Diagram	Rack diagram	rackdiag
Diagram	Digital timing diagram (waveform)	wavedrom
Diagram	BPMN diagram	bpmn
Diagram	Bytefield diagram	bytefield
Diagram	HDL component diagram	symbolator
Diagram	Excalidraw	excalidraw
Diagram	diagrams.net	diagramsnet / drawio
Diagram	WireViz	wireviz
Diagram	GoAT	goat
Visualization	Bar charts	vegalite / vega
Visualization	Line and area charts	vegalite / vega
Visualization	Circular charts	vegalite / vega
Visualization	Scatter plots	vegalite / vega
Visualization	Distributions	vegalite / vega
Visualization	Geographic maps	vegalite / vega
Visualization	Tree diagrams	vegalite / vega
Visualization	Network diagrams	vegalite / vega
Visualization	Heatmaps	vegalite / vega
Visualization	Word clouds	vegalite / vega
Visualization	Beeswarm plots	vegalite / vega

HTML diagrams (renderhtml)

Use a renderhtml fence when the diagram is authored as HTML/CSS/SVG and must be rendered, not shown as source. A normal html fence stays a highlighted code block.

Client

→

API

→

Database

Starlight content styles are skipped inside the block (not-content), so inner layout, lists, and headings keep the diagram’s own CSS.

Tabbed content (group-container)

Use this for any markdown — tables, lists, prose — not just code. Outer fences need more colons than inner ones so nesting parses correctly.

Directive	Role
:::::group-container … :::::	Outer tab group
::::group-item[Title] … ::::	One tab (+ body)
{active} on an item	Default selected tab (first if omitted)

Example (outer :::::, items ::::):

Short note for the Alpha tab.

• One
• Two

Content for Beta. Nested code or tables go here.

See Company Apply for a real page: level tabs (SDE 1/2/3) each holding a large table.

Nesting rule

Container directives close at the first matching fence of the same length. Nesting pattern:

:::::outer
::::mid
:::inner
…
:::
::::
:::::

Rule: outer fences use more colons than inner ones.

Interactive tables (data-table)

Wrap a normal markdown table in :::data-table to add:

• Search across all columns
• Sort any column (click the header; chevrons show direction)
• Pagination (rows per page control)

Links inside cells (e.g. company names) are preserved.

Company	Category	Locations	Est. Comp (LPA)
Acme	Product	Remote	40–60L
Globex	HFT	Bengaluru	55–80L
Initech	Fintech	Mumbai	30–45L
Umbrella	Services	Pan-India	18–28L

Options

Attributes on the opening fence:

Attribute	Default	Effect
searchable	on	Set searchable=false to hide search
sortable	on	Set sortable=false to disable column sort
paging	on	Set paging=false for a full list
perPage	25	Rows per page (e.g. perPage=50)

:::data-table{perPage=50}

| Name | Score |
|------|-------|
| A    | 10    |

:::

Numeric-looking columns (headers matching comp, salary, ctc, lpa, package) sort by the lower bound of ranges like 140–220L.

Nested with content tabs

Put data-table inside group-item with enough colons:

:::::group-container
::::group-item[SDE 3]{active}
:::data-table
| Company | …
| …
:::
::::
:::::

Code snippets (Expressive Code)

Code fences use Expressive Code. Meta options go after the language on the opening fence.

Tabbed code groups

Wrap multiple fences in :::group (alias :::code-group) to show them as tabs instead of a long scroll. Tab labels use each fence’s title="…", or the language name.

abc.js

export function greet(name) {
  return `Hello, ${name}!`;
}

xyz.java

public class Greeter {
  public static String greet(String name) {
    return "Hello, " + name + "!";
  }
}

greet.ts

export function greet(name: string): string {
  return `Hello, ${name}!`;
}

You can also label tabs with bracket meta: ```js [abc.js].

Title and frame

src/lib/greet.ts

export function greet(name: string) {
  return `Hello, ${name}!`;
}

Install deps

bun install
bun run build

Line numbers

Line numbers are on by default for js, ts, html, java, and python. Toggle per block:

console.log("line 1");
console.log("line 2");
console.log("line 3");

// No gutter numbers on this block
console.log("still highlighted");

// Continues as if this file started at line 40
export const PORT = 4321;

Highlight lines (mark)

Neutral highlight — draw attention without implying add/remove.

```js {2-3} showLineNumbers

function add(a, b) {
  const sum = a + b;
  return sum;
}

Explicit form:

const answer = 42;
console.log(answer);

Insert / delete lines (ins / del)

Green = inserted, red = deleted — useful for before/after diffs.

function total(items) {
  let sum = 0;
  for (const item of items) sum += item.price;
  for (const item of items) sum += item.price * item.qty;
  return sum;
}

Labeled markers:

type User = {
  id: string;
  name: string;
  email: string;
  role: "admin" | "member";
};

Diff language

Or use a classic diff fence:

export function createUser(input) {
  return db.insert(input);
  const user = validate(input);
  return db.insert(user);
}

Highlight text (inline markers)

Mark words or phrases inside lines:

// TODO: handle empty list
const bug = list[0];
const fixed = list.at(0);

Regular expressions also work: mark=/handle\w+/.

Collapsible sections

Hide boilerplate; readers expand when needed.

import { createServer } from "node:http";
import { readFile } from "node:fs/promises";
import path from "node:path";
import { fileURLToPath } from "node:url";

export async function handler(req, res) {
  res.writeHead(200, { "Content-Type": "text/plain" });
  res.end("ok");
}

createServer(handler).listen(3000);
console.log("listening on :3000");
process.on("SIGTERM", () => process.exit(0));

Word wrap and long lines

const url = "https://api.example.com/v1/users?include=profile,settings&sort=createdAt&order=desc&limit=50";

Combining options

Most meta flags can be combined on one fence:

```ts title="cache.ts" showLineNumbers mark={5-7} collapse={1-2}

cache.ts

import type { Cache } from "./types";
import { redis } from "./client";

export async function getCachedUser(id: string): Promise<Cache | null> {
  const key = `user:${id}`;
  const raw = await redis.get(key);
  return raw ? JSON.parse(raw) : null;
}

Quick meta cheat sheet

Meta	Effect
:::group … :::	Tabbed code fences
:::code-group	Same as :::group
:::::group-container + ::::group-item[Title]	Tabbed content (markdown body)
group-item[…]{active}	Default open content tab
:::data-table … :::	Sortable / searchable / paged table
:::data-table{perPage=50}	Rows per page (and other flags above)
Language renderhtml	Render HTML/SVG (not a code block)
Language html	Highlighted HTML source
title="file.ts"	Filename / code-tab title
frame="terminal"	Terminal-style frame
showLineNumbers / =false	Toggle line numbers
startLineNumber=N	Start numbering at N
{2,4-6} or mark={…}	Neutral line highlight
ins={…} / del={…}	Added / removed lines
ins={"label":3-4}	Labeled insert/delete
"phrase" / mark="phrase"	Inline text highlight
collapse={1-5,10-12}	Collapsible ranges
wrap	Soft-wrap long lines
Language diff	+ / - line prefixes

Further reading

• Company Apply — content tabs + data tables in production usage
• Expressive Code — text & line markers
• Expressive Code — line numbers
• Expressive Code — collapsible sections
• Diátaxis — how-to guides