Markdown Gallery

A single-page reference for everything you can use when authoring documentation on this site. Use it as a copy-paste catalogue when you can’t remember the exact syntax for an admonition, a tabbed example, or a stepped procedure.

For the rules about which of these to use and how the build enforces them, see Frontmatter and Build Rules.

Frontmatter

Every document starts with a YAML frontmatter block:

---
title: "Document Title"
description: "Single sentence (40–300 chars) describing what this page is."
tags: [domain, category, topic]
domain: <domain-name>
maturity: published
author: "Your Name"
---

title, description, and author are required and enforced at build time. Valid domain values: product, domain, system, vision, roadmap, process, technology, legal, decisions, about, notes.

Headings

## H2 — Top-level section in the body

### H3

#### H4

Do not start the body with an # H1 — Starlight already renders the frontmatter title as the page H1.

Emphasis

Syntax	Output
**bold**	bold
*italic*	italic
***bold-italic***	bold-italic
~strike~	strike
`inline code`	inline code
<ins>underline</ins>	underline
<sub>subscript</sub>	subscript
<sup>superscript</sup>	superscript

Use sparingly. Keyboard shortcuts use <kbd>: Ctrl + Shift + P.

Lists

Bulleted with -, numbered with 1. (the renderer numbers automatically), and two-space indentation for nesting.

• Item one
• Item two
  • Nested item
  • Another nested item
• Item three

1. Step one
2. Step two
3. Step three

Blockquotes

> Quotation text.
>
> Second paragraph of the quote.

Railway Oriented Programming — Every operation returns Result<T>. Success flows through map and flatMap; failure short-circuits through the pipeline.

Admonitions (Asides)

Starlight provides four aside types. The triple-colon shorthand works in .md files; the <Aside> component works in .mdx files.

Triple-colon shorthand (.md files)

:::note
Useful information that users should know, even when skimming content.
:::

:::tip[Convention]
Helpful advice. Custom title in square brackets.
:::

:::caution
Urgent info that needs immediate user attention to avoid problems.
:::

:::danger
Advises about risks or negative outcomes of certain actions.
:::

<Aside> component (.mdx files)

Note

Default aside — use for supplementary information that doesn’t fit the main flow.

Convention

All universe implementations extend AbstractScopedUniverse and are scoped by tenant.

Breaking Change

The ItemSupply value object was promoted to a full entity in MVP2. Existing API consumers must update their response parsing.

Security

Never commit AWS credentials or 1Password tokens to source control. Use op run for secret injection in local development.

Code Blocks

Syntax-highlighted code with optional titles, line highlighting, and diff markers.

ItemService.kt

class ItemService(private val universe: ItemUniverse) {

    suspend fun findById(id: UUID): Result<Item> =
        universe.findById(id)

    suspend fun create(input: ItemInput): Result<Item>  // new
    suspend fun create(input: ItemDTO): Result<Item>     // removed
}

proxy.ts

export async function middleware(request: NextRequest) {
  const token = request.cookies.get('session')?.value;
  if (!token) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
  return NextResponse.next();
}

Every fenced block should declare a language. Use text for prose-like blocks (file trees, pseudocode) rather than leaving the tag off.

Tabs (.mdx files only)

Kotlin

val result: Result<Item> = universe.findById(id)
result.fold(
    onSuccess = { item -> respond(item) },
    onFailure = { error -> respondError(error) }
)

SQL

SELECT * FROM item_bitemporal
WHERE e_id = :eId
  AND effective_from <= :asOf
  AND (effective_to IS NULL OR effective_to > :asOf)
ORDER BY recorded_at DESC
LIMIT 1;

curl

curl -s -X GET \
  "https://dev.api.arda.cards/v1/item/item/${ITEM_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Tenant-ID: ${TENANT_ID}" | jq .

Cards and Link Cards (.mdx files only)

<Card> is presentational; <LinkCard> makes the whole card clickable. Both are wrapped in <CardGrid> for layout.

Product

Point-in-time description of Arda’s products: markets, personas, features, offerings.

Domain

Knowledge and concepts about material flow, operations science, and the information model.

Information Model Structured representation of the concepts and entities that model the domain.

Steps (.mdx files only)

1. Create a branch from main using the naming convention username/branch-name.

2. Write content in Markdown or MDX under the appropriate src/content/docs/ subdirectory.

3. Add frontmatter with at minimum title, description, author.

4. Preview locally with make dev — changes reflect instantly.

5. Open a PR — a preview deployment is generated automatically.

Tables

Markdown tables work everywhere when cells are simple:

Entity	Module	Domain	Status
Item	item-data-authority	Reference Data	Published
KanbanCard	kanban-card	Resources	Published
BusinessAffiliate	business-affiliate	Reference Data	MVP2
PurchaseOrder	purchase-order	Procurement	MVP2

When cells need to contain pipes, JSX expressions, or multi-line content in an .mdx file, switch to HTML <table>.

Inline formatting

• Bold text for emphasis
• Italic text for terms on first use
• inline code for identifiers, file names, CLI commands
• Strikethrough for deprecated items
• External link and internal link

PlantUML diagrams

Fenced code blocks with the plantuml language tag are rendered as inline SVG images at build time by the remark-plantuml plugin.

Pair every diagram with a 1–3 sentence prose summary so AI assistants (which rarely consume images) can read the same content their humans see.

See the PlantUML guide for sequence/class diagram conventions, named-color rules, and validation.

Draw.io diagrams

Draw.io diagrams are committed as exported *.drawio.svg or *.drawio.png files alongside the page that uses them, then referenced with standard Markdown image syntax (or <img> for SVG inside .mdx).

![Platform structure](./assets/platform-structure.drawio.svg)

The repo’s src/assets/ directory has working examples.

Definition-style content

Use bold terms followed by colon-prefixed descriptions for glossary-like entries.

Effective Time : The business-validity time axis. When a fact was true in the real world.

Recorded Time : The system-record time axis. When the system learned about the fact.

Bitemporal Coordinate : A pair of (effective, recorded) timestamps that uniquely identifies a point in the two-dimensional time space.

Footnotes

Bitemporal persistence¹ enables full audit history without destructive updates.

Horizontal rule

Use four asterisks for section breaks (Arda convention — distinguishes them from the three-dash frontmatter delimiter):

---

MDX-specific notes

• Use <Aside> instead of :::tip shorthand in .mdx files.
• Avoid bare curly braces in prose — wrap {foo} in backticks to disambiguate from JSX expressions.
• Use numeric HTML entities (≥) or direct Unicode (≥); named entities (≥) are rejected by the MDX parser.

The repo’s knowledge-base/mdx-gotchas.md has the full list.

General syntax rules

• Single blank lines before and after headings, lists, blockquotes, and paragraphs.
• Use - for bulleted lists.
• Use spaces only (no tabs); 2 spaces per indentation level.
• Use --- (three hyphens) for horizontal rules inside a section; use **** (four asterisks) for major section breaks.

Footnotes

1. See Allen, J.F. (1983) “Maintaining Knowledge about Temporal Intervals” for the theoretical foundation. ↩