Skip to content
reetwizamatya:~$

Markdown showcase

This page is the cheat sheet. Every feature below works in .md and .mdx unless noted.

Text formatting

Section titled “Text formatting”

Bold, italic, both, inline code, strikethrough, and a link.

Blockquotes are supported and render with a left border and muted text.

They can span multiple paragraphs.

Task list:

  • Finished
  • Not yet
  • Maybe never

Definition list (via HTML, works in .md too):

SLI
A carefully defined quantitative measure of some aspect of service.
SLO
A target value or range for an SLI.

Asides / callouts

Section titled “Asides / callouts”

Aside is Starlight’s callout component. Four variants + optional title.

Markdown fallback (works in plain .md):

:::note[Optional title]
Note body.
:::


:::tip
Tip body.
:::


:::caution
Caution body.
:::


:::danger
Danger body.
:::

Badges

Section titled “Badges”
Default Note Tip Danger Caution Success Large

Use badges inline in headings, table cells, or as sidebar.badge in frontmatter.

Cards & CardGrid

Section titled “Cards & CardGrid”

Reliable

Idempotent deploys, self-healing services, and boring alerts.

Reproducible

Everything from a git repo — infra, config, and runbooks.

Observable

Structured logs, RED metrics, and traceable request paths.

Secure

Least privilege by default, secrets pulled at runtime.

Link cards & buttons

Section titled “Link cards & buttons”
Kubernetes → Security → RBAC basics Least-privilege service accounts, verified with kubectl auth can-i.
Read the About page GitHub

Tabs

Section titled “Tabs”
Terminal window
npm install @astrojs/starlight

Tabs can be synchronized across the page by giving them the same syncKey:

pnpm dev
pnpm build

Steps

Section titled “Steps”

  1. First step — Starlight numbers these automatically.

  2. Second step — with code inside:

    Terminal window
    git init

  3. Third step — with a nested aside:

FileTree

Section titled “FileTree”
  • Directorysrc/
    • Directoryassets/
      • Directoryheroes/
        • kubernetes.svg the current page
    • Directorycontent/
      • Directorydocs/
        • Directorykubernetes/
          • Directorysecurity/
            • …
          • Directorynetworking/
            • …

Icons

Section titled “Icons”

Starlight ships hundreds of icons — the same set as astro-icon:

Code blocks (expressive-code)

Section titled “Code blocks (expressive-code)”

Titles + line numbers + marked lines

Section titled “Titles + line numbers + marked lines”
src/lib/retry.ts
export async function retry<T>(fn: () => Promise<T>, tries = 3): Promise<T> {
  let lastErr: unknown;
  for (let i = 0; i < tries; i++) {
    try {
      return await fn();
    } catch (err) {
      lastErr = err;
      await new Promise(r => setTimeout(r, 2 ** i * 100));
    }
  }
  throw lastErr;
}

Diff / insertions & deletions

Section titled “Diff / insertions & deletions”
deployment.yaml
apiVersion: apps/v1
kind: Deployment
spec:
  replicas: 1
  replicas: 3
  strategy: { type: Recreate }
  strategy:
    type: RollingUpdate

Terminal frame

Section titled “Terminal frame”
deploy.sh
kubectl apply -f k8s/
kubectl -n prod rollout status deploy/api --timeout=2m

Word / regex highlighting

Section titled “Word / regex highlighting”
main.tf
resource "azurerm_kubernetes_cluster" "aks" {
  name                = var.name
  location            = var.location
  resource_group_name = var.resource_group_name
  dns_prefix          = var.name
}

Collapsed sections (expressive-code)

Section titled “Collapsed sections (expressive-code)”
server.ts
export function createServer() {
  const app = express();


  // boilerplate you rarely care about
  app.use(cors());
  app.use(json());
  app.use(cookieParser());
  app.use((req, _, next) => {
    req.id = crypto.randomUUID();
    next();
  });
  app.use(pinoHttp(logger));
  app.use(rateLimiter);


  app.get('/', (_, res) => res.send('ok'));
  return app;
}

Mermaid diagrams

Section titled “Mermaid diagrams”

Fenced ```mermaid blocks render server-side to SVG (zero client JS).

flowchart LR
  Dev[Developer] -->|git push| GH[(GitHub)]
  GH --> CI[GitHub Actions]
  CI --> Reg[(Container Registry)]
  CI --> Argo[Argo CD]
  Argo -->|sync| K8s[Kubernetes cluster]

Sequence:

sequenceDiagram
  participant U as User
  participant API as API
  participant DB as Postgres
  U->>API: POST /orders
  API->>DB: INSERT ...
  DB-->>API: ok
  API-->>U: 201 Created

Tables

Section titled “Tables”

Standard GFM tables, sortable in your head:

FeatureAstroStarlightNotes
Images✅✅via astro:assets
MDX✅✅Components inside markdown
Search➖✅Pagefind built-in
i18n✅✅Locale-aware sidebar

Details / disclosure

Section titled “Details / disclosure”

Native HTML <details> works in markdown:

Click to reveal the punchline

You can hide long code, appendices, or Q&A behind a summary. Perfect for optional context.

Terminal window
echo "surprise"

Math (KaTeX-style expressions in prose)

Section titled “Math (KaTeX-style expressions in prose)”

Math via KaTeX requires an integration — this site ships with the standard Starlight setup, so prefer inline code for formulas that don’t need typesetting:

  • Latency budget: p99 <= 250ms
  • Error budget: SLO = 99.9% → 43m 12s/month
  • Little’s Law: L = λ · W

For teams that need full math typesetting, add remark-math + rehype-katex and use $…$ / $$…$$.

Everything together

Section titled “Everything together”