Style Guide

A reference page showing what’s available when writing course content. Not part of the course — it’s here so you can see the options and pick.

The question you asked: highlighting “At Lintel”

Three custom variants below, plus the zero-CSS baseline. Pick one and I’ll apply it across every page.

Baseline — built-in aside, no custom CSS

Variant A — tinted panel `panel` (default)

Variant B — left rule only `rule`

Variant C — bordered card `card`

With a custom title

How it’s written — plain markdown inside, works in .md files with no imports:

:::case
Support costs **$6.40 per ticket** across ~12,000 tickets a month.
:::

:::case[Custom title]{variant="rule"}
Tables, lists and **bold** all work inside.
:::

Starlight’s own asides can’t take a custom class — Aside.astro hardcodes its class list — so these are rendered by a small Sätteri mdast plugin at src/plugins/satteri-callouts.mjs instead. (Not a remark plugin: Astro 7 made Sätteri the default Markdown processor, and markdown.remarkPlugins now requires swapping the whole pipeline over to unified.)

Question blocks

Every topic ends with one. Uses the same left-rule treatment as Variant B, so the questions read as a quiet recurring fixture rather than competing with the diagram above them.

Written as:

:::questions
1. First question.
2. Second question.
:::

The title defaults to “Check your understanding” — no heading needed. One trade-off: because it is no longer an ## heading, it does not appear in the page’s right-hand table of contents. Say the word and I will restore the heading above the block.

Built-in asides

Four variants, available in plain .md with no imports.

Cards

Card

A titled box with an optional icon. Good for parallel items of equal weight.

With an icon

Icons come from Starlight’s built-in set.

Link cards

The Lintel CaseThe fixed facts every topic draws on.

Module 1 — Start hereWhat an architect is accountable for.

Link buttons

Start Module 1 Read the case Capstone

Steps

Useful for the capstone instructions — numbered, visually connected.

Write the context and business-value brief.
Draw the system context diagram.
Map the stakeholders.
Write the architecture charter last.

Tabs

Good for showing the same idea from different stakeholders’ angles.

Cost per ticket, unit economics, and whether the $1.2M is defensible.

Badges

Inline status markers: Module 1 Capstone Assumption Blocked Note

File tree

Directorysrc/content/docs/handbook/
- 00-the-lintel-case.md
- Directory01-the-architects-work/
  - 01-start-here.md
  - Directory02-working-context/
    01-what-architecture-actually-is.md
    02-why-the-job-exists.md highlighted
  - Directory03-ai-paradigm-shift/
    …
  - 04-capstone.md

Code blocks

With a title and highlighted lines:

integrations: [
  mermaid({ autoTheme: true }),
  starlight({ /* mermaid must come first */ }),
]

With a diff:

starlight({ title: 'Architect Role & Mindset' }),
mermaid({ autoTheme: true }), starlight({ title: 'Architect Role & Mindset' }),

Diagrams

Mermaid renders inline via the astro-mermaid integration.

graph LR
  BD["Business driver"] --> QA["Quality requirement"]
  QA --> AD["Architecture decision"]
  AD --> SS["System structure"]

Diagrams follow the light/dark theme automatically.

Tables

Person	Role	Can block?
Lena Fischer	Security & Compliance	Yes — formally
Ivan Petrov	Principal Engineer	Yes — informally
Dev Raghunathan	CFO	Controls budget

Text elements

Normal prose with bold, italic, inline code, and links.

A blockquote. Useful for stating the single idea a topic turns on.

Bulleted list
Second item
- Nested item

Numbered list
Second item

Horizontal rule below:

That’s the full set. Tell me which Lintel variant you want and I’ll apply it everywhere the phrase appears.