diff --git a/README.md b/README.md
index 3eb1827..8704b9a 100644
--- a/README.md
+++ b/README.md
@@ -117,6 +117,15 @@ localized; links resolve back to GitLab.
 > to the document's `h2`–`h5` headings (which receive slug `id`s). This also works
 > for markdown embedded via `<GitlabFile>` and for release notes.
 
+<!-- -->
+
+> **Alerts:** GitLab alert blockquotes are rendered as themed callouts. A blockquote
+> whose first line is `> [!note]`, `> [!tip]`, `> [!important]`, `> [!caution]`, or
+> `> [!warning]` becomes a `<div>` carrying both `gitlab-md-alert*` hook classes and
+> the Docusaurus/Infima `alert alert--<variant>` classes (so it inherits theme colors).
+> Type matching is case-insensitive; add text after the marker for a custom title, e.g.
+> `> [!warning] Data deletion`. This also works for `<GitlabFile>` markdown and release notes.
+
 ### `<GitlabReleases>`
 
 A list of releases with notes, dates, and asset links.
@@ -233,6 +242,8 @@ into your `src/css/custom.css` and edit freely. The class names you can target:
 | `gitlab-release-notes` / `gitlab-release-assets` | release body + asset links |
 | `gitlab-readme` | rendered README / markdown file |
 | `gitlab-md-toc` | generated `[[_TOC_]]` table of contents (`<nav>`) |
+| `gitlab-md-alert` / `gitlab-md-alert--<type>` | alert callout container + per-type modifier (also gets Infima `alert alert--<variant>`) |
+| `gitlab-md-alert-title` | alert title row |
 | `gitlab-fallback` | error fallback box |
 | `gitlab-code` / `gitlab-code-title` / `gitlab-code-pre` | code file embed |
 
diff --git a/docs/superpowers/plans/2026-06-29-gitlab-alerts.md b/docs/superpowers/plans/2026-06-29-gitlab-alerts.md
new file mode 100644
index 0000000..40c09a3
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-29-gitlab-alerts.md
@@ -0,0 +1,514 @@
+# GitLab Markdown Alerts Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Render GitLab Markdown alerts (`> [!note]`, `[!tip]`, `[!important]`, `[!caution]`, `[!warning]`) as themed callout boxes everywhere `renderMarkdown` is used.
+
+**Architecture:** A new rehype plugin `rehypeGitlabAlerts` (in `src/gitlab/alerts.ts`) runs **after** `rehype-sanitize` in the `renderMarkdown` pipeline — the same slot as `rehypeGitlabToc`. It walks `blockquote` nodes, detects a leading `[!type]` marker (case-insensitive, with optional same-line custom title), and rewrites the blockquote into a `<div>` carrying both stable `gitlab-md-alert*` hook classes and Docusaurus/Infima `alert alert--<variant>` classes, with a title paragraph prepended. Post-sanitize execution means injected classes survive and the body is already safe.
+
+**Tech Stack:** TypeScript (ESM, explicit `.js` imports), unified/rehype, `unist-util-visit`, Vitest. No new dependencies.
+
+---
+
+## File Structure
+
+- **Create** `src/gitlab/alerts.ts` — the `rehypeGitlabAlerts` plugin plus pure helpers `ALERT_TYPES` and `buildAlertTitle`.
+- **Create** `src/gitlab/alerts.test.ts` — unit/behavior tests via `renderMarkdown`.
+- **Modify** `src/gitlab/markdown.ts` — import and `.use(rehypeGitlabAlerts)` after `rehypeGitlabToc`.
+- **Modify** `README.md` — document the syntax and add class-table rows.
+- **Create** `examples/site/docs/components/alerts.mdx` — example page (rendered via `<GitlabReadme>`/`<GitlabFile>` content; here a static doc page demonstrating the markdown is sufficient).
+
+Reference pattern: `src/gitlab/toc.ts` and `src/gitlab/toc.test.ts`.
+
+---
+
+### Task 1: Plugin scaffold + first passing alert (note)
+
+**Files:**
+- Create: `src/gitlab/alerts.ts`
+- Create: `src/gitlab/alerts.test.ts`
+- Modify: `src/gitlab/markdown.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/gitlab/alerts.test.ts`:
+
+```ts
+import { describe, it, expect } from "vitest";
+import { renderMarkdown } from "./markdown";
+
+describe("rehypeGitlabAlerts", () => {
+  it("renders a [!note] blockquote as an Infima alert div", async () => {
+    const md = "> [!note]\n> The following information is useful.\n";
+    const html = await renderMarkdown(md, {});
+
+    expect(html).toContain(
+      'class="gitlab-md-alert gitlab-md-alert--note alert alert--secondary"',
+    );
+    expect(html).toContain('role="alert"');
+    expect(html).toContain('<p class="gitlab-md-alert-title">Note</p>');
+    expect(html).toContain("<p>The following information is useful.</p>");
+    expect(html).not.toContain("[!note]");
+    expect(html).not.toContain("<blockquote>");
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run src/gitlab/alerts.test.ts`
+Expected: FAIL — `renderMarkdown` does not yet transform alerts (output still contains `<blockquote>` / `[!note]`).
+
+- [ ] **Step 3: Create the plugin**
+
+Create `src/gitlab/alerts.ts`:
+
+```ts
+import type { Root, Element, ElementContent } from "hast";
+import { visit } from "unist-util-visit";
+
+interface AlertType {
+  defaultTitle: string;
+  infimaClass: string;
+}
+
+/** GitLab alert type → default title + Docusaurus/Infima theme variant class. */
+export const ALERT_TYPES: Record<string, AlertType> = {
+  note: { defaultTitle: "Note", infimaClass: "alert--secondary" },
+  tip: { defaultTitle: "Tip", infimaClass: "alert--success" },
+  important: { defaultTitle: "Important", infimaClass: "alert--info" },
+  caution: { defaultTitle: "Caution", infimaClass: "alert--warning" },
+  warning: { defaultTitle: "Warning", infimaClass: "alert--danger" },
+};
+
+// Leading `[!type]` marker plus an optional same-line custom title.
+// `[^\S\r\n]` = horizontal whitespace only (so we never cross into the body line).
+const MARKER_RE =
+  /^[^\S\r\n]*\[!(note|tip|important|caution|warning)\][^\S\r\n]*([^\r\n]*)/i;
+
+/** Build the `<p class="gitlab-md-alert-title">…</p>` title node. */
+export function buildAlertTitle(title: string): Element {
+  return {
+    type: "element",
+    tagName: "p",
+    properties: { className: ["gitlab-md-alert-title"] },
+    children: [{ type: "text", value: title }],
+  };
+}
+
+/**
+ * Rehype plugin. Must run AFTER rehype-sanitize so the classes/structure it
+ * injects are not stripped and the alert body is already sanitized.
+ */
+export function rehypeGitlabAlerts() {
+  return (tree: Root) => {
+    visit(tree, "element", (node: Element) => {
+      if (node.tagName !== "blockquote") return;
+
+      const para = node.children.find(
+        (c): c is Element => c.type === "element" && c.tagName === "p",
+      );
+      if (!para) return;
+
+      const first = para.children[0];
+      if (!first || first.type !== "text") return;
+
+      const match = MARKER_RE.exec(first.value);
+      if (!match) return;
+
+      const type = match[1].toLowerCase();
+      const spec = ALERT_TYPES[type];
+      if (!spec) return;
+
+      const customTitle = match[2].trim();
+      const title = customTitle.length > 0 ? customTitle : spec.defaultTitle;
+
+      // Strip the marker (+ same-line title + the trailing newline) from the body.
+      first.value = first.value.slice(match[0].length).replace(/^\r?\n/, "");
+      if (first.value.length === 0) para.children.shift();
+      if (para.children.length === 0) {
+        node.children = node.children.filter((c) => c !== para);
+      }
+
+      node.tagName = "div";
+      node.properties = {
+        className: [
+          "gitlab-md-alert",
+          `gitlab-md-alert--${type}`,
+          "alert",
+          spec.infimaClass,
+        ],
+        role: "alert",
+      };
+      node.children.unshift(buildAlertTitle(title) as ElementContent);
+    });
+  };
+}
+```
+
+- [ ] **Step 4: Wire the plugin into the pipeline**
+
+In `src/gitlab/markdown.ts`, add the import near the existing toc import (line ~10):
+
+```ts
+import { rehypeGitlabAlerts } from "./alerts.js";
+```
+
+And add the `.use` immediately after `.use(rehypeGitlabToc)` (line ~42):
+
+```ts
+    .use(rehypeGitlabToc)
+    .use(rehypeGitlabAlerts)
+    .use(collect)
+```
+
+- [ ] **Step 5: Run test to verify it passes**
+
+Run: `npx vitest run src/gitlab/alerts.test.ts`
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/gitlab/alerts.ts src/gitlab/alerts.test.ts src/gitlab/markdown.ts
+git commit -m "feat: render GitLab [!type] blockquote alerts"
+```
+
+---
+
+### Task 2: All five types map to correct classes and default titles
+
+**Files:**
+- Modify: `src/gitlab/alerts.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Add inside the `describe` block in `src/gitlab/alerts.test.ts`:
+
+```ts
+  it.each([
+    ["note", "alert--secondary", "Note"],
+    ["tip", "alert--success", "Tip"],
+    ["important", "alert--info", "Important"],
+    ["caution", "alert--warning", "Caution"],
+    ["warning", "alert--danger", "Warning"],
+  ])("maps [!%s] to %s with default title %s", async (type, infima, title) => {
+    const html = await renderMarkdown(`> [!${type}]\n> Body text.\n`, {});
+    expect(html).toContain(
+      `class="gitlab-md-alert gitlab-md-alert--${type} alert ${infima}"`,
+    );
+    expect(html).toContain(`<p class="gitlab-md-alert-title">${title}</p>`);
+    expect(html).toContain("<p>Body text.</p>");
+  });
+```
+
+- [ ] **Step 2: Run tests**
+
+Run: `npx vitest run src/gitlab/alerts.test.ts`
+Expected: PASS (the Task 1 implementation already handles all five types).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/gitlab/alerts.test.ts
+git commit -m "test: cover all five alert types and Infima class mapping"
+```
+
+---
+
+### Task 3: Custom title override + empty custom title
+
+**Files:**
+- Modify: `src/gitlab/alerts.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Add inside the `describe` block:
+
+```ts
+  it("uses a same-line custom title when present", async () => {
+    const md = "> [!warning] Data deletion\n> This is destructive.\n";
+    const html = await renderMarkdown(md, {});
+    expect(html).toContain('class="gitlab-md-alert gitlab-md-alert--warning alert alert--danger"');
+    expect(html).toContain('<p class="gitlab-md-alert-title">Data deletion</p>');
+    expect(html).toContain("<p>This is destructive.</p>");
+    expect(html).not.toContain("Data deletion</p><p>Data deletion");
+  });
+
+  it("falls back to the default title when the custom title is blank", async () => {
+    const html = await renderMarkdown("> [!tip]   \n> Tip body.\n", {});
+    expect(html).toContain('<p class="gitlab-md-alert-title">Tip</p>');
+    expect(html).toContain("<p>Tip body.</p>");
+  });
+```
+
+- [ ] **Step 2: Run tests**
+
+Run: `npx vitest run src/gitlab/alerts.test.ts`
+Expected: PASS (the regex captures the custom title; blank trims to the default).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/gitlab/alerts.test.ts
+git commit -m "test: cover custom and blank alert titles"
+```
+
+---
+
+### Task 4: Case-insensitive marker matching
+
+**Files:**
+- Modify: `src/gitlab/alerts.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Add inside the `describe` block:
+
+```ts
+  it.each(["[!NOTE]", "[!Note]", "[!nOtE]"])(
+    "matches %s case-insensitively and normalizes to note",
+    async (marker) => {
+      const html = await renderMarkdown(`> ${marker}\n> Body.\n`, {});
+      expect(html).toContain(
+        'class="gitlab-md-alert gitlab-md-alert--note alert alert--secondary"',
+      );
+      expect(html).toContain('<p class="gitlab-md-alert-title">Note</p>');
+    },
+  );
+```
+
+- [ ] **Step 2: Run tests**
+
+Run: `npx vitest run src/gitlab/alerts.test.ts`
+Expected: PASS (regex has the `i` flag; `type` is lowercased).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/gitlab/alerts.test.ts
+git commit -m "test: cover case-insensitive alert markers"
+```
+
+---
+
+### Task 5: Non-transform cases stay plain blockquotes
+
+**Files:**
+- Modify: `src/gitlab/alerts.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Add inside the `describe` block:
+
+```ts
+  it("leaves an unknown alert type as a plain blockquote", async () => {
+    const html = await renderMarkdown("> [!foo]\n> Body.\n", {});
+    expect(html).toContain("<blockquote>");
+    expect(html).not.toContain("gitlab-md-alert");
+  });
+
+  it("leaves an ordinary blockquote untouched", async () => {
+    const html = await renderMarkdown("> Just a quote.\n", {});
+    expect(html).toContain("<blockquote>");
+    expect(html).not.toContain("gitlab-md-alert");
+  });
+
+  it("does not transform when the marker is not at the line start", async () => {
+    const html = await renderMarkdown("> see [!note] here\n", {});
+    expect(html).toContain("<blockquote>");
+    expect(html).not.toContain("gitlab-md-alert");
+  });
+```
+
+- [ ] **Step 2: Run tests**
+
+Run: `npx vitest run src/gitlab/alerts.test.ts`
+Expected: PASS (`[!foo]` fails the regex; plain quote has no marker; anchored `^` rejects mid-line markers).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/gitlab/alerts.test.ts
+git commit -m "test: leave non-alert blockquotes untouched"
+```
+
+---
+
+### Task 6: Edge cases — empty body, rich body, multiple alerts
+
+**Files:**
+- Modify: `src/gitlab/alerts.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Add inside the `describe` block:
+
+```ts
+  it("renders a marker-only alert with no stray empty paragraph", async () => {
+    const html = await renderMarkdown("> [!important]\n", {});
+    expect(html).toContain('class="gitlab-md-alert gitlab-md-alert--important alert alert--info"');
+    expect(html).toContain('<p class="gitlab-md-alert-title">Important</p>');
+    expect(html).not.toMatch(/<p><\/p>/);
+  });
+
+  it("preserves inline markdown inside the alert body", async () => {
+    const md = "> [!note]\n> Read **this** and [docs](https://x.test).\n";
+    const html = await renderMarkdown(md, {});
+    expect(html).toContain("<strong>this</strong>");
+    expect(html).toContain('href="https://x.test"');
+  });
+
+  it("transforms multiple alerts in one document independently", async () => {
+    const md = "> [!tip]\n> First.\n\n> [!warning]\n> Second.\n";
+    const html = await renderMarkdown(md, {});
+    expect(html).toContain("gitlab-md-alert--tip");
+    expect(html).toContain("gitlab-md-alert--warning");
+    expect(html).toContain("<p>First.</p>");
+    expect(html).toContain("<p>Second.</p>");
+  });
+```
+
+- [ ] **Step 2: Run tests**
+
+Run: `npx vitest run src/gitlab/alerts.test.ts`
+Expected: PASS (empty paragraph is dropped; body nodes are preserved; `visit` handles every blockquote).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/gitlab/alerts.test.ts
+git commit -m "test: cover empty-body, rich-body, and multiple alerts"
+```
+
+---
+
+### Task 7: Security — XSS in title escaped + coexistence with TOC
+
+**Files:**
+- Modify: `src/gitlab/alerts.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Add inside the `describe` block:
+
+```ts
+  it("escapes HTML in a custom title and runs no handlers", async () => {
+    const md = '> [!warning] <img src=x onerror="alert(1)">\n> Body.\n';
+    const html = await renderMarkdown(md, {});
+    expect(html).not.toContain("onerror");
+    expect(html).not.toContain("alert(1)");
+    // Title text is inserted as an escaped text node.
+    expect(html).toContain("gitlab-md-alert-title");
+  });
+
+  it("applies both the TOC and alert transforms in one document", async () => {
+    const md = "[[_TOC_]]\n\n## Heading\n\n> [!note]\n> Note body.\n";
+    const html = await renderMarkdown(md, {});
+    expect(html).toContain('<nav class="gitlab-md-toc">');
+    expect(html).toContain("gitlab-md-alert--note");
+  });
+```
+
+- [ ] **Step 2: Run tests**
+
+Run: `npx vitest run src/gitlab/alerts.test.ts`
+Expected: PASS. Note: the raw `<img>` in the title is sanitized away *before* our plugin runs, and whatever leading text remains is re-emitted as an escaped text node, so no handler survives.
+
+- [ ] **Step 3: Run the full suite and typecheck**
+
+Run: `npx vitest run && npm run typecheck`
+Expected: PASS (no regressions, including the existing `markdown.test.ts` XSS test).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/gitlab/alerts.test.ts
+git commit -m "test: escape XSS in alert titles and coexist with TOC"
+```
+
+---
+
+### Task 8: Documentation
+
+**Files:**
+- Modify: `README.md`
+- Create: `examples/site/docs/components/alerts.mdx`
+
+- [ ] **Step 1: Add the alerts note to the `<GitlabReadme>` section**
+
+In `README.md`, immediately after the `[[_TOC_]]` blockquote note (ends at line ~118), add:
+
+```markdown
+
+> **Alerts:** GitLab alert blockquotes are rendered as themed callouts. A blockquote
+> whose first line is `> [!note]`, `> [!tip]`, `> [!important]`, `> [!caution]`, or
+> `> [!warning]` becomes a `<div>` carrying both `gitlab-md-alert*` hook classes and
+> the Docusaurus/Infima `alert alert--<variant>` classes (so it inherits theme colors).
+> Type matching is case-insensitive; add text after the marker for a custom title, e.g.
+> `> [!warning] Data deletion`. This also works for `<GitlabFile>` markdown and release notes.
+```
+
+- [ ] **Step 2: Add class-table rows**
+
+In `README.md`, after the `gitlab-md-toc` row (line ~235), add:
+
+```markdown
+| `gitlab-md-alert` / `gitlab-md-alert--<type>` | alert callout container + per-type modifier (also gets Infima `alert alert--<variant>`) |
+| `gitlab-md-alert-title` | alert title row |
+```
+
+- [ ] **Step 3: Create the example page**
+
+Create `examples/site/docs/components/alerts.mdx`:
+
+```mdx
+---
+title: Markdown alerts
+---
+
+# Markdown alerts
+
+GitLab alert blockquotes embedded via `<GitlabReadme>` or `<GitlabFile>` render as
+themed callouts. The source markdown looks like this:
+
+```markdown
+> [!note]
+> The following information is useful.
+
+> [!tip]
+> Tip of the day.
+
+> [!important]
+> This is something important you should know.
+
+> [!caution]
+> You need to be very careful about the following.
+
+> [!warning] Data deletion
+> The following instructions will make your data unrecoverable.
+```
+
+Type matching is case-insensitive, and any text after the marker becomes a custom title.
+```
+
+- [ ] **Step 4: Verify docs build is unaffected**
+
+Run: `npx vitest run && npm run typecheck`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add README.md examples/site/docs/components/alerts.mdx
+git commit -m "docs: document GitLab markdown alerts"
+```
+
+---
+
+## Self-Review Notes
+
+- **Spec coverage:** five types (Tasks 1–2), case-insensitivity (Task 4), custom/blank titles (Task 3), Infima + hook classes (Tasks 1–2), pipeline wiring post-sanitize (Task 1), security/XSS + TOC coexistence (Task 7), edge cases incl. marker-only/rich body/multiple/non-transform (Tasks 5–6), docs + class table + example page (Task 8). `>>>` is explicitly out of scope per the spec.
+- **No placeholders:** every code and test step is complete and copy-pasteable.
+- **Type consistency:** `ALERT_TYPES`, `buildAlertTitle`, `rehypeGitlabAlerts`, and the four-class output (`gitlab-md-alert`, `gitlab-md-alert--<type>`, `alert`, `alert--<variant>`) are used identically across all tasks.
+```
diff --git a/docs/superpowers/specs/2026-06-29-gitlab-alerts-design.md b/docs/superpowers/specs/2026-06-29-gitlab-alerts-design.md
new file mode 100644
index 0000000..a7ffd7f
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-29-gitlab-alerts-design.md
@@ -0,0 +1,162 @@
+# GitLab Markdown Alerts — Design
+
+**Status:** Approved
+**Date:** 2026-06-29
+
+## Summary
+
+Add support for GitLab's [Markdown *alerts*](https://docs.gitlab.com/user/markdown/#alerts) to
+the markdown rendering pipeline, mirroring how the `[[_TOC_]]` marker is already handled. An alert
+is a blockquote whose first line is a type marker — `> [!note]`, `> [!tip]`, `> [!important]`,
+`> [!caution]`, `> [!warning]` — optionally followed by a custom title on the same line. The
+rendered output is a styled callout box that reuses the Docusaurus/Infima theme `alert` classes so
+it inherits theme colors with no bundled CSS.
+
+This applies everywhere `renderMarkdown` is used (README, file markdown, release notes).
+
+## Scope
+
+**In scope**
+
+- The five GitLab alert types via the `> [!type]` single-blockquote syntax.
+- Case-insensitive type matching (`[!note]`, `[!NOTE]`, `[!Note]` all map to the same alert).
+- Custom title override on the marker line (`> [!warning] Data deletion`).
+- Default title = capitalized type name when no custom title is given.
+
+**Out of scope (deferred)**
+
+- GitLab's `>>>` multiline blockquote fence syntax. This is not standard Markdown — `remark-parse`
+  does not recognize `>>>` as a blockquote — so it would require a pre-parse text transform with its
+  own edge cases (nesting, lists inside the fence). Deferred to a later iteration; every alert form
+  in this spec is a normal Markdown blockquote detectable on the tree.
+- Bundled CSS / SVG icons. Styling is left to the consumer's theme (see Class mapping).
+
+## Approach
+
+A custom **rehype** plugin, `rehypeGitlabAlerts`, in a new file `src/gitlab/alerts.ts`, wired into
+`renderMarkdown` immediately **after** `rehype-sanitize` — the same pipeline slot
+`rehypeGitlabToc` occupies. Running post-sanitize means:
+
+- the alert body is already sanitized;
+- the classes, `role`, and title node we inject cannot be stripped by the sanitize schema (no schema
+  changes needed);
+- the security posture matches the TOC feature exactly.
+
+Alternatives considered and rejected:
+
+- **`remark-github-blockquote-alert`** (off-the-shelf): GitHub-flavored (uppercase only), no
+  custom-title support, emits non-Infima classes, runs pre-sanitize. Does not match GitLab semantics
+  or the Infima-class goal.
+- **Custom remark (mdast) plugin, pre-sanitize**: would require allow-listing every injected class
+  and attribute in the sanitize schema — the exact fragility the TOC plugin avoided by going
+  post-sanitize.
+
+## Class mapping & output structure
+
+Each GitLab type maps to an Infima theme variant (so it picks up theme colors for free) and also
+carries a stable `gitlab-md-alert--<type>` hook class for consumers that want to target GitLab
+semantics directly.
+
+| GitLab type | Default title | Infima variant class |
+|---|---|---|
+| `note` | Note | `alert--secondary` |
+| `tip` | Tip | `alert--success` |
+| `important` | Important | `alert--info` |
+| `caution` | Caution | `alert--warning` |
+| `warning` | Warning | `alert--danger` |
+
+The matched `<blockquote>` is rewritten **in place** to a `<div>` (Infima `.alert` is a div),
+preserving its already-sanitized body. Example for `> [!warning] Data deletion`:
+
+```html
+<div class="gitlab-md-alert gitlab-md-alert--warning alert alert--danger" role="alert">
+  <p class="gitlab-md-alert-title">Data deletion</p>
+  <p>The following instructions will make your data unrecoverable.</p>
+</div>
+```
+
+Title text = custom title if present, else the capitalized default from the table. Both the GitLab
+hook classes and the Infima classes are emitted.
+
+## Detection & rewrite logic (`src/gitlab/alerts.ts`)
+
+`rehypeGitlabAlerts()` returns a transform that visits `blockquote` elements:
+
+1. Find the first child that is a `<p>`. Read its leading text — the concatenation of leading text
+   nodes up to the first newline / `<br>`.
+2. Match `^\s*\[!(note|tip|important|caution|warning)\]([^\n]*)` **case-insensitively** against that
+   leading text.
+   - No match, or an unknown type → **leave the blockquote untouched** (stays a plain blockquote).
+3. On match:
+   - `type` = lowercased capture; `customTitle` = trimmed remainder (may be empty).
+   - **Strip the marker** (plus any custom-title text and its trailing newline / `<br>`) from the
+     paragraph's leading content, leaving the real body. If that leaves the first paragraph empty,
+     drop it.
+   - Mutate the node: `tagName = "div"`, set `className` to the four classes from the table, set
+     `role="alert"`.
+   - Prepend `<p class="gitlab-md-alert-title">{title}</p>`.
+
+Pure, unit-testable helpers mirror `toc.ts`:
+
+- `ALERT_TYPES`: a map of `type → { defaultTitle, infimaClass }`.
+- a small builder for the title node.
+
+### Edge cases
+
+- Marker-only blockquote (no body) → alert with just a title; no stray empty paragraph.
+- Custom title containing inline markdown → reduced to plain text.
+- Multiple blockquotes in one document → each handled independently.
+- Marker not at the paragraph start (text before `[!note]`) → no transform.
+- Unknown type (`[!foo]`) → no transform.
+
+## Pipeline wiring & security
+
+In `src/gitlab/markdown.ts`, add one step after the sanitize/TOC steps:
+
+```js
+.use(rehypeRaw)
+.use(rehypeSanitize)
+.use(rehypeGitlabToc)
+.use(rehypeGitlabAlerts)   // new, post-sanitize
+.use(collect)
+.use(rehypeStringify)
+```
+
+**Security:** post-sanitize, the body is already clean. The plugin only (a) restructures existing
+nodes, (b) adds static, hard-coded classes and `role`, and (c) inserts the title as a hast **text
+node**, which is escaped on stringify. A title such as `> [!warning] <img src=x onerror=alert(1)>`
+becomes inert escaped text. No schema changes and no new `dangerouslySetInnerHTML` paths. The
+existing XSS regression test in `markdown.test.ts` stays green, and an alert-specific XSS test is
+added.
+
+## Testing (`src/gitlab/alerts.test.ts`) — TDD, write tests first
+
+Behavior-level tests through `renderMarkdown`, plus direct unit tests of the plugin and helpers.
+Thorough coverage is a priority:
+
+- All five types → correct `gitlab-md-alert--<type>` + Infima class + default title (one test each).
+- Case-insensitivity: `[!NOTE]`, `[!Note]`, `[!note]` all produce the note alert.
+- Custom title: `> [!warning] Data deletion` → title "Data deletion", danger variant.
+- Empty custom title: `> [!tip]` alone → default "Tip" title.
+- Marker-only blockquote (no body) → alert with title, no empty stray paragraph.
+- Body markdown preserved: bold / links / lists inside the alert survive and render.
+- Unknown type `[!foo]` → untouched plain `<blockquote>`, no alert classes.
+- Non-alert blockquote (plain quote) → untouched.
+- Marker not at start (text before `[!note]`) → no transform.
+- Multiple alerts in one document → each transformed independently.
+- XSS in custom title → escaped, no executable HTML.
+- TOC + alert coexistence → both transforms apply in the same document.
+- `role="alert"` present on output.
+- Pure-helper unit tests for the `ALERT_TYPES` mapping and the title-node builder.
+
+## Documentation
+
+- Add a GitLab alerts section to `README.md` documenting the syntax, the five types, custom titles,
+  and the emitted classes; add `gitlab-md-alert`, `gitlab-md-alert--<type>`, and
+  `gitlab-md-alert-title` rows to the README class table.
+- Add an example page under `examples/site/docs/` demonstrating each alert type.
+
+## Verification
+
+After implementation: `npx vitest run` and `npm run typecheck` (per CLAUDE.md). The e2e build is not
+required for this change but may be run if the pipeline wiring is touched in unexpected ways.
diff --git a/examples/gitlab/docs/gitlab.mdx b/examples/gitlab/docs/gitlab.mdx
index 1152aa5..075ce1b 100644
--- a/examples/gitlab/docs/gitlab.mdx
+++ b/examples/gitlab/docs/gitlab.mdx
@@ -22,6 +22,6 @@ title: gitlab
 
 <GitlabFile project="gitlab-org/gitlab" path="GITALY_SERVER_VERSION" />
 
-> The `gitlab-org/gitlab` README is intentionally not embedded here — it is very
-> large and references hundreds of assets. Use [`<GitlabFile>`](./client-go.mdx)
-> to embed specific files instead.
+## README
+
+<GitlabReadme project="gitlab-org/gitlab" />
diff --git a/examples/site/docs/components/alerts.mdx b/examples/site/docs/components/alerts.mdx
new file mode 100644
index 0000000..527ab0f
--- /dev/null
+++ b/examples/site/docs/components/alerts.mdx
@@ -0,0 +1,33 @@
+---
+title: Markdown alerts
+---
+
+# Markdown alerts
+
+When a GitLab README or file embedded via `<GitlabReadme>` or `<GitlabFile>` (or a
+release's notes) contains an *alert* blockquote, it is rendered at build time as a
+themed callout that reuses your theme's Infima `alert` classes.
+
+The alert source — written in the GitLab project, not on this page — looks like this:
+
+```markdown
+> [!note]
+> The following information is useful.
+
+> [!tip]
+> Tip of the day.
+
+> [!important]
+> This is something important you should know.
+
+> [!caution]
+> You need to be very careful about the following.
+
+> [!warning] Data deletion
+> The following instructions will make your data unrecoverable.
+```
+
+Type matching is case-insensitive, and any text after the marker becomes a custom
+title (for example, `Data deletion` above). Each alert renders as a
+`<div class="gitlab-md-alert gitlab-md-alert--<type> alert alert--<variant>">`, so it
+inherits your theme's callout colors.
diff --git a/src/gitlab/alerts.test.ts b/src/gitlab/alerts.test.ts
new file mode 100644
index 0000000..3022524
--- /dev/null
+++ b/src/gitlab/alerts.test.ts
@@ -0,0 +1,130 @@
+import { describe, it, expect } from "vitest";
+import { renderMarkdown } from "./markdown";
+
+describe("rehypeGitlabAlerts", () => {
+  it("renders a [!note] blockquote as an Infima alert div", async () => {
+    const md = "> [!note]\n> The following information is useful.\n";
+    const html = await renderMarkdown(md, {});
+
+    expect(html).toContain(
+      'class="gitlab-md-alert gitlab-md-alert--note alert alert--secondary"',
+    );
+    expect(html).toContain('role="alert"');
+    expect(html).toContain('<p class="gitlab-md-alert-title">Note</p>');
+    expect(html).toContain("<p>The following information is useful.</p>");
+    expect(html).not.toContain("[!note]");
+    expect(html).not.toContain("<blockquote>");
+  });
+
+  it("reduces an inline-formatted custom title to plain text without leaking markup", async () => {
+    const md = "> [!note] **Bold Title**\n> Body text.\n";
+    const html = await renderMarkdown(md, {});
+    expect(html).toContain('<p class="gitlab-md-alert-title">Bold Title</p>');
+    expect(html).toContain("<p>Body text.</p>");
+    expect(html).not.toContain("<strong>");
+  });
+
+  it("does not leave a stray <br> when the marker line has trailing whitespace", async () => {
+    const md = "> [!note]   \n> Body text.\n";
+    const html = await renderMarkdown(md, {});
+    expect(html).toContain('<p class="gitlab-md-alert-title">Note</p>');
+    expect(html).toContain("<p>Body text.</p>");
+    expect(html).not.toContain("<br>");
+  });
+
+  it.each([
+    ["note", "alert--secondary", "Note"],
+    ["tip", "alert--success", "Tip"],
+    ["important", "alert--info", "Important"],
+    ["caution", "alert--warning", "Caution"],
+    ["warning", "alert--danger", "Warning"],
+  ])("maps [!%s] to %s with default title %s", async (type, infima, title) => {
+    const html = await renderMarkdown(`> [!${type}]\n> Body text.\n`, {});
+    expect(html).toContain(
+      `class="gitlab-md-alert gitlab-md-alert--${type} alert ${infima}"`,
+    );
+    expect(html).toContain(`<p class="gitlab-md-alert-title">${title}</p>`);
+    expect(html).toContain("<p>Body text.</p>");
+  });
+
+  it("uses a same-line custom title when present", async () => {
+    const md = "> [!warning] Data deletion\n> This is destructive.\n";
+    const html = await renderMarkdown(md, {});
+    expect(html).toContain('class="gitlab-md-alert gitlab-md-alert--warning alert alert--danger"');
+    expect(html).toContain('<p class="gitlab-md-alert-title">Data deletion</p>');
+    expect(html).toContain("<p>This is destructive.</p>");
+  });
+
+  it("falls back to the default title when the custom title is blank", async () => {
+    const html = await renderMarkdown("> [!tip]   \n> Tip body.\n", {});
+    expect(html).toContain('<p class="gitlab-md-alert-title">Tip</p>');
+    expect(html).toContain("<p>Tip body.</p>");
+  });
+
+  it.each(["[!NOTE]", "[!Note]", "[!nOtE]"])(
+    "matches %s case-insensitively and normalizes to note",
+    async (marker) => {
+      const html = await renderMarkdown(`> ${marker}\n> Body.\n`, {});
+      expect(html).toContain(
+        'class="gitlab-md-alert gitlab-md-alert--note alert alert--secondary"',
+      );
+      expect(html).toContain('<p class="gitlab-md-alert-title">Note</p>');
+    },
+  );
+
+  it("leaves an unknown alert type as a plain blockquote", async () => {
+    const html = await renderMarkdown("> [!foo]\n> Body.\n", {});
+    expect(html).toContain("<blockquote>");
+    expect(html).not.toContain("gitlab-md-alert");
+  });
+
+  it("leaves an ordinary blockquote untouched", async () => {
+    const html = await renderMarkdown("> Just a quote.\n", {});
+    expect(html).toContain("<blockquote>");
+    expect(html).not.toContain("gitlab-md-alert");
+  });
+
+  it("does not transform when the marker is not at the line start", async () => {
+    const html = await renderMarkdown("> see [!note] here\n", {});
+    expect(html).toContain("<blockquote>");
+    expect(html).not.toContain("gitlab-md-alert");
+  });
+
+  it("renders a marker-only alert with no stray empty paragraph", async () => {
+    const html = await renderMarkdown("> [!important]\n", {});
+    expect(html).toContain('class="gitlab-md-alert gitlab-md-alert--important alert alert--info"');
+    expect(html).toContain('<p class="gitlab-md-alert-title">Important</p>');
+    expect(html).not.toMatch(/<p><\/p>/);
+  });
+
+  it("preserves inline markdown inside the alert body", async () => {
+    const md = "> [!note]\n> Read **this** and [docs](https://x.test).\n";
+    const html = await renderMarkdown(md, {});
+    expect(html).toContain("<strong>this</strong>");
+    expect(html).toContain('href="https://x.test"');
+  });
+
+  it("transforms multiple alerts in one document independently", async () => {
+    const md = "> [!tip]\n> First.\n\n> [!warning]\n> Second.\n";
+    const html = await renderMarkdown(md, {});
+    expect(html).toContain("gitlab-md-alert--tip");
+    expect(html).toContain("gitlab-md-alert--warning");
+    expect(html).toContain("<p>First.</p>");
+    expect(html).toContain("<p>Second.</p>");
+  });
+
+  it("escapes HTML in a custom title and runs no handlers", async () => {
+    const md = '> [!warning] <img src=x onerror="alert(1)">\n> Body.\n';
+    const html = await renderMarkdown(md, {});
+    expect(html).not.toContain("onerror");
+    expect(html).not.toContain("alert(1)");
+    expect(html).toContain("gitlab-md-alert-title");
+  });
+
+  it("applies both the TOC and alert transforms in one document", async () => {
+    const md = "[[_TOC_]]\n\n## Heading\n\n> [!note]\n> Note body.\n";
+    const html = await renderMarkdown(md, {});
+    expect(html).toContain('<nav class="gitlab-md-toc">');
+    expect(html).toContain("gitlab-md-alert--note");
+  });
+});
diff --git a/src/gitlab/alerts.ts b/src/gitlab/alerts.ts
new file mode 100644
index 0000000..0284216
--- /dev/null
+++ b/src/gitlab/alerts.ts
@@ -0,0 +1,118 @@
+import type { Root, Element, ElementContent } from "hast";
+import { toString } from "hast-util-to-string";
+import { visit } from "unist-util-visit";
+
+interface AlertType {
+  defaultTitle: string;
+  infimaClass: string;
+}
+
+/** GitLab alert type → default title + Docusaurus/Infima theme variant class. */
+export const ALERT_TYPES: Record<string, AlertType> = {
+  note: { defaultTitle: "Note", infimaClass: "alert--secondary" },
+  tip: { defaultTitle: "Tip", infimaClass: "alert--success" },
+  important: { defaultTitle: "Important", infimaClass: "alert--info" },
+  caution: { defaultTitle: "Caution", infimaClass: "alert--warning" },
+  warning: { defaultTitle: "Warning", infimaClass: "alert--danger" },
+};
+
+// Leading `[!type]` marker (case-insensitive), with optional surrounding horizontal whitespace.
+const MARKER_RE = /^[^\S\r\n]*\[!(note|tip|important|caution|warning)\][^\S\r\n]*/i;
+
+/** Build the `<p class="gitlab-md-alert-title">…</p>` title node. */
+export function buildAlertTitle(title: string): ElementContent {
+  return {
+    type: "element",
+    tagName: "p",
+    properties: { className: ["gitlab-md-alert-title"] },
+    children: [{ type: "text", value: title }],
+  };
+}
+
+/**
+ * Rehype plugin. Must run AFTER rehype-sanitize so the classes/structure it
+ * injects are not stripped and the alert body is already sanitized.
+ */
+export function rehypeGitlabAlerts() {
+  return (tree: Root) => {
+    visit(tree, "element", (node: Element) => {
+      if (node.tagName !== "blockquote") return;
+
+      const para = node.children.find(
+        (c): c is Element => c.type === "element" && c.tagName === "p",
+      );
+      if (!para) return;
+
+      const first = para.children[0];
+      if (!first || first.type !== "text") return;
+
+      const match = MARKER_RE.exec(first.value);
+      if (!match) return;
+
+      const type = match[1].toLowerCase();
+      const spec = ALERT_TYPES[type];
+      if (!spec) return;
+
+      // Strip the marker from the first text node; what remains is the start of
+      // the title line (which may continue across following inline nodes).
+      first.value = first.value.slice(match[0].length);
+
+      // Collect the rest of the first line as the plain-text title and keep
+      // everything after the first line break as the alert body.
+      const titleParts: string[] = [];
+      const body: ElementContent[] = [];
+      let inBody = false;
+      let justCrossedBreak = false;
+      for (const child of para.children) {
+        if (inBody) {
+          // A `<br>` ending the title line is followed by a text node whose
+          // leading line break belongs to the dropped break, not the body.
+          if (justCrossedBreak && child.type === "text") {
+            child.value = child.value.replace(/^\r?\n/, "");
+          }
+          justCrossedBreak = false;
+          body.push(child);
+          continue;
+        }
+        if (child.type === "element" && child.tagName === "br") {
+          inBody = true; // drop the break that ends the title line
+          justCrossedBreak = true;
+          continue;
+        }
+        if (child.type === "text") {
+          const nl = child.value.indexOf("\n");
+          if (nl === -1) {
+            titleParts.push(child.value);
+          } else {
+            titleParts.push(child.value.slice(0, nl));
+            const rest = child.value.slice(nl + 1);
+            if (rest.length > 0) body.push({ type: "text", value: rest });
+            inBody = true;
+          }
+        } else {
+          // Inline element on the title line → flatten to its text content.
+          titleParts.push(toString(child));
+        }
+      }
+
+      const customTitle = titleParts.join("").trim();
+      const title = customTitle.length > 0 ? customTitle : spec.defaultTitle;
+
+      para.children = body;
+      // Drop the now-empty paragraph entirely.
+      node.children = node.children.filter((c) => c !== para || body.length > 0);
+
+      node.tagName = "div";
+      node.properties = {
+        className: [
+          "gitlab-md-alert",
+          `gitlab-md-alert--${type}`,
+          "alert",
+          spec.infimaClass,
+        ],
+        role: "alert",
+      };
+      node.children.unshift(buildAlertTitle(title));
+    });
+  };
+}
diff --git a/src/gitlab/markdown.ts b/src/gitlab/markdown.ts
index ff48947..ba030f4 100644
--- a/src/gitlab/markdown.ts
+++ b/src/gitlab/markdown.ts
@@ -7,6 +7,7 @@ import remarkParse from "remark-parse";
 import remarkRehype from "remark-rehype";
 import { unified } from "unified";
 import { visit } from "unist-util-visit";
+import { rehypeGitlabAlerts } from "./alerts.js";
 import { rehypeGitlabToc, TOC_PLACEHOLDER } from "./toc.js";
 
 export interface RenderOptions {
@@ -40,6 +41,7 @@ export async function renderMarkdown(md: string, opts: RenderOptions): Promise<s
     .use(rehypeRaw)
     .use(rehypeSanitize)
     .use(rehypeGitlabToc)
+    .use(rehypeGitlabAlerts)
     .use(collect)
     .use(rehypeStringify);