Style Guide

This page is a grab-bag of examples you can copy/paste when writing docs. Most sections show:

1. The Markdown/MDX you type
2. The rendered result

Note

Use .md for normal Markdown pages. Use .mdx when you want to import and render components like <Tabs /> or <CardGrid />.

Headings

## Heading 2
### Heading 3
#### Heading 4

Emphasis, Inline Code, Links

**Bold**, _italic_, and `inline code`.

[Internal link](/getting-started/overview/)
[External link](https://starlight.astro.build/)

Bold, italic, and inline code.

Internal link External link

Lists

- Unordered item
- Another item

1. Ordered item
2. Another item

- [x] Completed task
- [ ] Incomplete task

• Unordered item
• Another item

1. Ordered item
2. Another item

• Completed task
• Incomplete task

Quotes

> A blockquote is useful for short callouts or quoting text.

A blockquote is useful for short callouts or quoting text.

Callouts (Admonitions)

:::note
Use notes for extra context.
:::

:::tip
Use tips for helpful shortcuts.
:::

:::caution
Use caution when a mistake could cause problems.
:::

:::danger
Use danger for high-risk actions.
:::

Note

Use notes for extra context.

Tip

Use tips for helpful shortcuts.

Caution

Use caution when a mistake could cause problems.

Danger

Use danger for high-risk actions.

Tables

| Column | Type | Notes |
|--------|------|-------|
| `id`   | UUID | Primary key |
| `name` | text | Display name |
| `ts`   | time | Server time |

Column	Type	Notes
id	UUID	Primary key
name	text	Display name
ts	time	Server time

Code Blocks

Shell (bash)

# List files
ls -la

# Run the dev server
npm run dev

PowerShell

# List files
Get-ChildItem -Force

# Search text
rg -n "Platform Services" src

JSON / YAML / Diff

{
  "service": "m2",
  "enabled": true
}

service: m2
enabled: true

oldValue: false
oldValue: true

Diagrams

ASCII Diagram (works everywhere)

┌──────────────┐     ┌──────────────┐
│   Frontend    │ --> │   Backend     │
└──────────────┘     └──────────────┘
        |                   |
        v                   v
   ┌────────┐         ┌────────┐
   │  Cache  │         │   DB    │
   └────────┘         └────────┘

Tip

If you want Mermaid diagrams (flowcharts/sequence diagrams), we can add a Mermaid integration later. Right now, ```mermaid blocks would render as plain code.

Images

In MDX (import from src/assets)

import ilsLogo from '../../../assets/ils-logo.webp';

<img src={ilsLogo} alt="ILS logo" width="180" />

In Markdown (from public/)

![Alt text](/images/your-image.png)

Starlight Components (MDX Only)

Cards

A Card

Cards are great for landing pages and quick navigation.

Another Card

You can put links inside: Go to Overview

Buttons

Get Started

Technical Docs

Tabs

Bash

npm run dev

PowerShell

npm run dev

Steps

1. Open the page you want to edit in src/content/docs/....
2. Write content in Markdown.
3. Use callouts, tables, and code blocks as needed.

File Tree

• Directorysrc/

  • Directorycontent/

    • Directorydocs/

      • Directorygetting-started/

        • overview.md
  • Directorystyles/

    • custom.css
• astro.config.mjs

Badges and Asides

Badges: Beta Deprecated

Aside (component)

This is the <Aside /> component (different from :::note), useful in MDX.