scalar · hanspagel · May 21, 2026 · Apr 23, 2026 · Apr 23, 2026 · Apr 23, 2026
diff --git a/.agents/skills/scalar-docs-config-skill.mdc → .agents/skills/scalar-docs/SKILL.md b/.agents/skills/scalar-docs-config-skill.mdc → .agents/skills/scalar-docs/SKILL.md
@@ -1,8 +1,8 @@
 ---
-description: Skill for writing and updating scalar.config.json — Scalar Docs configuration reference for users and LLMs
-globs: scalar.config.json, scalar.config.json5
-alwaysApply: false
+name: scalar-docs
+description: Skill for writing and updating scalar.config.json — Scalar Docs configuration reference for users and LLMs.
 ---
+
 # Scalar Docs Configuration Skill — scalar.config.json
 
 Reference for writing and updating `scalar.config.json`, the central configuration file for [Scalar Docs](https://docs.scalar.com). Use this when creating, editing, or validating Docs configuration for any project.
@@ -128,12 +128,15 @@ Markdown/MDX content from a file:
   "filepath": "docs/getting-started.md",
   "description": "Optional SEO description",
   "icon": "phosphor/regular/rocket",
+  "showInSidebar": true,
   "layout": { "toc": true, "sidebar": true }
 }
 ```
 
 Layout: `toc` (default `true`), `sidebar` (default `true`).
 
+**Hidden pages:** Set `showInSidebar: false` to hide a page from the sidebar while keeping it accessible via its direct URL.
+
 #### OpenAPI (`type: "openapi"`)
 
 API reference from file, Registry, or URL:

diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,37 @@
+# AGENTS.md
+
+## Repository purpose
+
+The Scalar Docs Starter Kit — a configuration-only documentation project deployed via Scalar Docs GitHub Sync. There is no build system, no package.json, and no source code. All behavior is driven by `scalar.config.json` plus MDX files under `docs/content/` (the starter is MDX-by-default; `.md` still works) and OpenAPI documents under `docs/api-reference/`.
+
+## Commands
+
+All tooling runs through the Scalar CLI (`npx @scalar/cli`). There is no install step.
+
+- `npx @scalar/cli project preview` — local dev server at `http://localhost:7971` with live reload
+- `npx @scalar/cli project check-config` — validate `scalar.config.json` (this is what CI runs)
+- `npx @scalar/cli project publish` — publish current local files to Scalar
+- `npx @scalar/cli project upgrade` — migrate a Docs 1.0 config to 2.0
+
+CI (`.github/workflows/validate-scalar-configuration.yml`) runs `check-config` on any push/PR that touches `scalar.config.json` or `docs/**`. Run `check-config` locally before committing changes to those paths.
+
+## Architecture
+
+Everything is orchestrated by `scalar.config.json`:
+
+- `navigation.routes` is the single source of truth for sitemap and sidebar. Each key is a URL path; each value has a `type` of `page`, `openapi`, `group`, or `link`.
+- `type: "page"` routes reference MDX via `filepath` (paths relative to repo root, e.g. `docs/content/quickstart.mdx`).
+- `type: "openapi"` routes reference OpenAPI documents via `filepath`, or pull from the Scalar Registry (`namespace` + `slug`), or a remote `url`.
+- `type: "group"` nests children and supports `mode`: `folder` (default), `flat`, or `nested`. `mode: "flat"` hoists children into the parent level without a collapsible wrapper — used in this repo for the Components, Layouts, and Examples sections.
+- `siteConfig` controls branding, theme, custom domain/subdomain, `head` injection (scripts/styles/meta), and redirects.
+- Page-level `layout` overrides (`toc`, `sidebar`, `header`, `tabs`, `pageTitle`, `pageActions`, `search`) live on the route entry, not in the MDX. See the Layouts gallery for live examples.
+
+Adding a new page: create a `.mdx` file under `docs/content/`, then add a route entry in `scalar.config.json` pointing at it. `docs/content/components/` and `docs/content/layouts/` are galleries — don't add unrelated pages there; put new top-level content next to `quickstart.mdx`. Adding a new API reference: drop the OpenAPI document under `docs/api-reference/` and add a `type: "openapi"` route. The file path in `filepath` is relative to the repo root, not to `docs/`.
+
+MDX components from `scalar-mdx-components` (`Callout`, `Button`, `Tabs`, `PageLink`, etc.) currently need explicit imports at the top of each page — the CLI's MDX pipeline does not auto-inject them. The Components gallery pages demonstrate the pattern.
+
+The config schema is fetched from `https://registry.scalar.com/@scalar/schemas/config` (see `$schema`). `.vscode/settings.json` whitelists this host so VS Code autocompletes and validates the config inline — keep that whitelist when editing VS Code settings.
+
+## Scalar config reference
+
+`.agents/skills/scalar-docs-config-skill.mdc` is a comprehensive, up-to-date reference for every field in `scalar.config.json` (route types, header/sidebar/tabs, theming, domains, `head` injection, redirects, migration from 1.0). Consult it before editing the config rather than guessing field names — it is the authoritative local reference and more specific than the public docs.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 [![Twitter](https://img.shields.io/twitter/follow/scalar)](https://x.com/scalar)
 [![Discord](https://img.shields.io/discord/1135330207960678410?style=flat&color=5865F2)](https://discord.gg/scalar)
 
-Welcome to the Scalar Docs Starter Kit! Deploy Markdown and OpenAPI documents from GitHub.
+Welcome to the Scalar Docs Starter Kit! Deploy MDX and OpenAPI documents from GitHub.
 
 ## Preview
 
@@ -36,11 +36,15 @@ This repository includes a GitHub Action workflow that automatically validates t
 ```
 starter/
 ├── docs/
-│   ├── api-reference/      # OpenAPI documents
-│   └── guides/             # Free-form text
-├── scalar.config.json      # Configuration
+│   ├── api-reference/          # OpenAPI documents
+│   └── content/                # MDX pages (.mdx by default; .md still works)
+│       ├── components/         # Gallery — one page per Scalar MDX component
+│       └── layouts/            # Gallery — per-page layout overrides
+├── scalar.config.json          # Configuration
 ```
 
+Pages are `.mdx` by default, so you can mix Markdown with JSX expressions and drop in components like `<Callout>`, `<Button>`, or `<Tabs>`. Browse the Components and Layouts galleries in the preview for live examples.
+
 ## Configuration
 
 All project configuration is managed through the [`scalar.config.json`](./scalar.config.json) file. This file controls:

diff --git a/docs/content/api-references.md → docs/content/api-references.mdx b/docs/content/api-references.md → docs/content/api-references.mdx
diff --git a/docs/content/components/button.mdx b/docs/content/components/button.mdx
@@ -0,0 +1,29 @@
+import { Button } from 'scalar-mdx-components'
+
+# Button
+
+A call-to-action link styled as a button. Always opens in a new tab.
+
+## Usage
+
+<Button href="https://scalar.com">
+  Get Started
+</Button>
+
+## Props
+
+| Prop   | Type     | Description                                                    |
+| ------ | -------- | -------------------------------------------------------------- |
+| `href` | `string` | Destination URL.                                               |
+| `icon` | `string` | Optional icon identifier (e.g. `line/arrow-right`).            |
+| `title`| `string` | Alternative to nested text content.                            |
+
+## Variants
+
+<Button href="https://scalar.com">
+  Plain
+</Button>
+
+<Button href="https://scalar.com" icon="line/arrow-right">
+  With icon
+</Button>
diff --git a/docs/content/components/callout.mdx b/docs/content/components/callout.mdx
@@ -0,0 +1,38 @@
+import { Callout } from 'scalar-mdx-components'
+
+# Callout
+
+Highlight a block of content with a typed banner. Use sparingly — one or two per page.
+
+## Usage
+
+<Callout type="info">
+  This is the simplest possible callout.
+</Callout>
+
+## Props
+
+| Prop   | Type                                                               | Description                                          |
+| ------ | ------------------------------------------------------------------ | ---------------------------------------------------- |
+| `type` | `'info' \| 'warning' \| 'danger' \| 'success' \| 'neutral'`        | Controls color and icon. Defaults to `neutral`.      |
+| `icon` | `string`                                                           | Override the default icon for this type.             |
+
+## Variants
+
+<Callout type="info">
+  Neutral information the reader may want to know.
+</Callout>
+
+<Callout type="warning">
+  Something to be careful about — non-blocking.
+</Callout>
+
+<Callout type="danger">
+  Something destructive or blocking. Read before proceeding.
+</Callout>
+
+<Callout type="success">
+  A happy confirmation or positive note.
+</Callout>
+
+Markdown works inside the body — use `code`, **bold**, [links](https://scalar.com), and lists freely.
diff --git a/docs/content/components/embed.mdx b/docs/content/components/embed.mdx
@@ -0,0 +1,21 @@
+import { Embed } from 'scalar-mdx-components'
+
+# Embed
+
+Drop any iframe-embeddable URL — video, demo, widget — directly into the page. Anything a provider allows to be framed (YouTube, Vimeo, Loom, CodeSandbox, Figma, …) works.
+
+## Usage
+
+<Embed src="https://www.youtube.com/embed/dQw4w9WgXcQ" alt="Example video" />
+
+## Props
+
+| Prop      | Type     | Description                                                                  |
+| --------- | -------- | ---------------------------------------------------------------------------- |
+| `src`     | `string` | URL to embed. Use the provider's **embed** URL, not the share/watch URL.     |
+| `alt`     | `string` | Accessible title for the iframe.                                             |
+| `caption` | `string` | Optional caption shown below the iframe.                                     |
+
+## Variants
+
+<Embed src="https://www.youtube.com/embed/dQw4w9WgXcQ" alt="YouTube example" caption="With a caption." />
diff --git a/docs/content/components/fineprint.mdx b/docs/content/components/fineprint.mdx
@@ -0,0 +1,15 @@
+# Fineprint
+
+Render small legal-style text for disclaimers, terms-like footnotes, or version badges.
+
+Unlike the other components in this gallery, Fineprint is a **custom element**, not a React/MDX component. Use the lowercase tag `<scalar-fineprint>` directly — no `import` needed.
+
+## Usage
+
+<scalar-fineprint>
+  This is fine print. Subject to change without notice.
+</scalar-fineprint>
+
+## Why is this one different?
+
+Most components ship a React wrapper exported from `scalar-mdx-components`. Fineprint is implemented only as a server-rendered custom element, so you write it as HTML in your MDX and Scalar's server-side pipeline renders it. This is also how you'd use any other `<scalar-*>` element that doesn't have an MDX wrapper yet.
diff --git a/docs/content/components/image.mdx b/docs/content/components/image.mdx
@@ -0,0 +1,25 @@
+import { Image } from 'scalar-mdx-components'
+
+# Image
+
+Display an image with optional caption, dark-mode source, and sizing.
+
+## Usage
+
+<Image src="https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=800" alt="A beautiful landscape" />
+
+## Props
+
+| Prop       | Type                | Description                                    |
+| ---------- | ------------------- | ---------------------------------------------- |
+| `src`      | `string`            | Image URL.                                     |
+| `alt`      | `string`            | Alt text for accessibility.                    |
+| `caption`  | `string`            | Optional caption shown below the image.        |
+| `src-dark` | `string`            | Alternative source rendered in dark mode.      |
+| `href`     | `string`            | Wrap the image in a link.                      |
+| `width`    | `string \| number`  | HTML `width` attribute.                        |
+| `height`   | `string \| number`  | HTML `height` attribute.                       |
+
+## Variants
+
+<Image src="https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=800" alt="Mountain lake at sunset" caption="With a caption." />
diff --git a/docs/content/components/math.mdx b/docs/content/components/math.mdx
@@ -0,0 +1,22 @@
+import { Math } from 'scalar-mdx-components'
+
+# Math
+
+Render LaTeX equations with [KaTeX](https://katex.org/).
+
+## Usage
+
+<Math equation="E = mc^2" />
+
+## Props
+
+| Prop       | Type     | Description                                                            |
+| ---------- | -------- | ---------------------------------------------------------------------- |
+| `equation` | `string` | The LaTeX expression. Alternatively, put the expression in the body.   |
+| `caption`  | `string` | Optional caption shown below the rendered equation.                    |
+
+## Variants
+
+<Math equation="E = mc^2" caption="Einstein's mass–energy equivalence" />
+
+<Math equation="\sum_{i=1}^{n} i = \frac{n(n+1)}{2}" caption="Sum of the first n natural numbers" />
diff --git a/docs/content/components/page-link.mdx b/docs/content/components/page-link.mdx
@@ -0,0 +1,24 @@
+import { PageLink } from 'scalar-mdx-components'
+
+# PageLink
+
+Link to another page in this documentation. Preferred over a plain Markdown link — the title and description stay in sync with the target page's metadata.
+
+## Usage
+
+<PageLink filepath="api-references.mdx" />
+
+## Props
+
+| Prop          | Type     | Description                                                                                      |
+| ------------- | -------- | ------------------------------------------------------------------------------------------------ |
+| `filepath`    | `string` | Path to another MDX/Markdown page, relative to the content root (e.g. `components/tabs`).        |
+| `uid`         | `string` | Alternative to `filepath` for editor-managed docs.                                               |
+| `title`       | `string` | Override the target page's title.                                                                |
+| `description` | `string` | Override the target page's description.                                                          |
+
+## Variants
+
+<PageLink filepath="api-references" />
+
+<PageLink title="Custom title" description="Custom description overrides the target page's metadata" filepath="components/tabs" />
diff --git a/docs/content/components/tabs.mdx b/docs/content/components/tabs.mdx
@@ -0,0 +1,40 @@
+import { Tabs, Tab } from 'scalar-mdx-components'
+
+# Tabs
+
+Group related content — typically code samples in different languages — behind a tab switcher.
+
+## Usage
+
+<Tabs default="JavaScript">
+  <Tab title="JavaScript">
+    ```js
+    const users = await fetch('/api/users').then((r) => r.json())
+    ```
+  </Tab>
+  <Tab title="Python">
+    ```python
+    import requests
+    users = requests.get('/api/users').json()
+    ```
+  </Tab>
+  <Tab title="cURL">
+    ```bash
+    curl https://api.example.com/users
+    ```
+  </Tab>
+</Tabs>
+
+## Props
+
+### `<Tabs>`
+
+| Prop      | Type     | Description                                                                        |
+| --------- | -------- | ---------------------------------------------------------------------------------- |
+| `default` | `string` | Title of the tab to open by default. Matches case-insensitively. First tab if omitted. |
+
+### `<Tab>`
+
+| Prop    | Type     | Description |
+| ------- | -------- | ----------- |
+| `title` | `string` | Tab label.  |
diff --git a/docs/content/development.md b/docs/content/development.md
diff --git a/docs/content/layouts/minimal.mdx b/docs/content/layouts/minimal.mdx
@@ -0,0 +1,29 @@
+# Minimal
+
+Hides every piece of chrome: header, sidebar, tabs, TOC, page title, page actions, and search. Use for fully custom landing pages, marketing pages, or embeddable standalone docs.
+
+With everything off there's no built-in way back, so link somewhere manually:
+
+[← Back to Quickstart](/)
+
+## Config
+
+```json
+{
+  "type": "page",
+  "filepath": "docs/content/layouts/minimal.mdx",
+  "layout": {
+    "toc": false,
+    "header": false,
+    "sidebar": false,
+    "tabs": false,
+    "pageTitle": false,
+    "pageActions": false,
+    "search": {
+      "enabled": false
+    }
+  }
+}
+```
+
+Drop the `layout` block into the route for any page you want to behave this way.
diff --git a/docs/content/layouts/no-sidebar.mdx b/docs/content/layouts/no-sidebar.mdx
@@ -0,0 +1,17 @@
+# No Sidebar
+
+Hides the left navigation sidebar on this page only. Use for marketing pages or anything that wants full-width content.
+
+This is a page-level opt-out — the sidebar returns on every other page in the site.
+
+## Config
+
+```json
+{
+  "type": "page",
+  "filepath": "docs/content/layouts/no-sidebar.mdx",
+  "layout": { "sidebar": false }
+}
+```
+
+Drop the `layout` block into the route for any page you want to behave this way.