From 4f4371be443ffdd6ea725b2219a8660a9d91254a Mon Sep 17 00:00:00 2001 From: Hans Pagel Date: Thu, 23 Apr 2026 12:07:03 +0200 Subject: [PATCH 1/8] feat: AGENTS.md --- AGENTS.md | 34 ++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 35 insertions(+) create mode 100644 AGENTS.md create mode 120000 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..48884a9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,34 @@ +# 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 Markdown/MDX files under `docs/` 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 Markdown via `filepath` (paths relative to repo root, e.g. `docs/content/quickstart.md`). +- `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 Usage and Examples sections. +- `siteConfig` controls branding, theme, custom domain/subdomain, `head` injection (scripts/styles/meta), and redirects. + +Adding a new page: create the Markdown file under `docs/content/`, then add a route entry in `scalar.config.json` pointing at it. 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/`. + +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 new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file From 9833f310b17832ef29671ec3e4c5c0dc35359903 Mon Sep 17 00:00:00 2001 From: Hans Pagel Date: Thu, 23 Apr 2026 12:09:43 +0200 Subject: [PATCH 2/8] chore: update scalar docs skill --- .../SKILL.md} | 9 ++++++--- skills-lock.json | 10 ++++++++++ 2 files changed, 16 insertions(+), 3 deletions(-) rename .agents/skills/{scalar-docs-config-skill.mdc => scalar-docs/SKILL.md} (97%) create mode 100644 skills-lock.json diff --git a/.agents/skills/scalar-docs-config-skill.mdc b/.agents/skills/scalar-docs/SKILL.md similarity index 97% rename from .agents/skills/scalar-docs-config-skill.mdc rename to .agents/skills/scalar-docs/SKILL.md index 7cf2fe9..eec2a6d 100644 --- a/.agents/skills/scalar-docs-config-skill.mdc +++ b/.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/skills-lock.json b/skills-lock.json new file mode 100644 index 0000000..e51e083 --- /dev/null +++ b/skills-lock.json @@ -0,0 +1,10 @@ +{ + "version": 1, + "skills": { + "scalar-docs": { + "source": "scalar/scalar", + "sourceType": "github", + "computedHash": "11e11f9e8732d0873886e9290243f76d0188fc3cf2ce8674e595056a614073a5" + } + } +} From c6b9bf893853665a05eb4c4a08726a80a7bde776 Mon Sep 17 00:00:00 2001 From: Hans Pagel Date: Thu, 23 Apr 2026 13:25:18 +0200 Subject: [PATCH 3/8] feat: mdx everything, new sitemap --- .../{api-references.md => api-references.mdx} | 0 docs/content/components/button.mdx | 3 + docs/content/components/callout.mdx | 3 + docs/content/components/embed.mdx | 3 + docs/content/components/fineprint.mdx | 3 + docs/content/components/image.mdx | 3 + docs/content/components/math.mdx | 3 + docs/content/components/page-link.mdx | 3 + docs/content/components/tabs.mdx | 3 + docs/content/development.md | 24 ---- docs/content/layouts/minimal.mdx | 3 + docs/content/layouts/no-sidebar.mdx | 3 + docs/content/layouts/no-toc.mdx | 3 + docs/content/layouts/search-in-header.mdx | 3 + docs/content/quickstart.md | 57 --------- docs/content/quickstart.mdx | 26 ++++ scalar.config.json | 111 +++++++++++++++--- 17 files changed, 157 insertions(+), 97 deletions(-) rename docs/content/{api-references.md => api-references.mdx} (100%) create mode 100644 docs/content/components/button.mdx create mode 100644 docs/content/components/callout.mdx create mode 100644 docs/content/components/embed.mdx create mode 100644 docs/content/components/fineprint.mdx create mode 100644 docs/content/components/image.mdx create mode 100644 docs/content/components/math.mdx create mode 100644 docs/content/components/page-link.mdx create mode 100644 docs/content/components/tabs.mdx delete mode 100644 docs/content/development.md create mode 100644 docs/content/layouts/minimal.mdx create mode 100644 docs/content/layouts/no-sidebar.mdx create mode 100644 docs/content/layouts/no-toc.mdx create mode 100644 docs/content/layouts/search-in-header.mdx delete mode 100644 docs/content/quickstart.md create mode 100644 docs/content/quickstart.mdx diff --git a/docs/content/api-references.md b/docs/content/api-references.mdx similarity index 100% rename from docs/content/api-references.md rename to docs/content/api-references.mdx diff --git a/docs/content/components/button.mdx b/docs/content/components/button.mdx new file mode 100644 index 0000000..997640e --- /dev/null +++ b/docs/content/components/button.mdx @@ -0,0 +1,3 @@ +# Button + +TODO diff --git a/docs/content/components/callout.mdx b/docs/content/components/callout.mdx new file mode 100644 index 0000000..328721b --- /dev/null +++ b/docs/content/components/callout.mdx @@ -0,0 +1,3 @@ +# Callout + +TODO diff --git a/docs/content/components/embed.mdx b/docs/content/components/embed.mdx new file mode 100644 index 0000000..63deb29 --- /dev/null +++ b/docs/content/components/embed.mdx @@ -0,0 +1,3 @@ +# Embed + +TODO diff --git a/docs/content/components/fineprint.mdx b/docs/content/components/fineprint.mdx new file mode 100644 index 0000000..298beaf --- /dev/null +++ b/docs/content/components/fineprint.mdx @@ -0,0 +1,3 @@ +# Fineprint + +TODO diff --git a/docs/content/components/image.mdx b/docs/content/components/image.mdx new file mode 100644 index 0000000..17e3d62 --- /dev/null +++ b/docs/content/components/image.mdx @@ -0,0 +1,3 @@ +# Image + +TODO diff --git a/docs/content/components/math.mdx b/docs/content/components/math.mdx new file mode 100644 index 0000000..4043398 --- /dev/null +++ b/docs/content/components/math.mdx @@ -0,0 +1,3 @@ +# Math + +TODO diff --git a/docs/content/components/page-link.mdx b/docs/content/components/page-link.mdx new file mode 100644 index 0000000..ba6b09a --- /dev/null +++ b/docs/content/components/page-link.mdx @@ -0,0 +1,3 @@ +# PageLink + +TODO diff --git a/docs/content/components/tabs.mdx b/docs/content/components/tabs.mdx new file mode 100644 index 0000000..bad236a --- /dev/null +++ b/docs/content/components/tabs.mdx @@ -0,0 +1,3 @@ +# Tabs + +TODO diff --git a/docs/content/development.md b/docs/content/development.md deleted file mode 100644 index 8ba4613..0000000 --- a/docs/content/development.md +++ /dev/null @@ -1,24 +0,0 @@ -# Development - -## Local Preview - -Run `@scalar/cli project preview` to start a local development server with live reload. - -## Port - -The default port is `7970`. Override with `--port`: - -```sh -npx @scalar/cli project preview --port 3000 -``` - -If the port is in use, the CLI selects another automatically. - -## Configuration - -The CLI looks for `scalar.config.json` in the current directory by default. To use a different config: - -```sh -npx @scalar/cli project preview my-scalar-config.json -npx @scalar/cli project preview ../some-other-directory/scalar.config.json -``` diff --git a/docs/content/layouts/minimal.mdx b/docs/content/layouts/minimal.mdx new file mode 100644 index 0000000..50bb50a --- /dev/null +++ b/docs/content/layouts/minimal.mdx @@ -0,0 +1,3 @@ +# Minimal + +TODO diff --git a/docs/content/layouts/no-sidebar.mdx b/docs/content/layouts/no-sidebar.mdx new file mode 100644 index 0000000..8a76d6c --- /dev/null +++ b/docs/content/layouts/no-sidebar.mdx @@ -0,0 +1,3 @@ +# No Sidebar + +TODO diff --git a/docs/content/layouts/no-toc.mdx b/docs/content/layouts/no-toc.mdx new file mode 100644 index 0000000..4f72b67 --- /dev/null +++ b/docs/content/layouts/no-toc.mdx @@ -0,0 +1,3 @@ +# No TOC + +TODO diff --git a/docs/content/layouts/search-in-header.mdx b/docs/content/layouts/search-in-header.mdx new file mode 100644 index 0000000..a48c7fa --- /dev/null +++ b/docs/content/layouts/search-in-header.mdx @@ -0,0 +1,3 @@ +# Search in Header + +TODO diff --git a/docs/content/quickstart.md b/docs/content/quickstart.md deleted file mode 100644 index bc80996..0000000 --- a/docs/content/quickstart.md +++ /dev/null @@ -1,57 +0,0 @@ -# Quickstart - -This is the Scalar Docs Starter Kit — a ready-to-use template for building beautiful documentation. Fork it, clone it, and make it your own. Everything here is meant to be modified, extended, or replaced to fit your project. - -## 1. Preview Your Docs - -Run a local development server to see your changes in real-time: - -```bash -npx @scalar/cli project preview -``` - -This starts a live preview at `http://localhost:7971` where every edit you make is instantly visible. - -Read more about [Development](development.md). - -## 2. Include OpenAPI Documents - -Drop your OpenAPI files into `docs/api-reference/`, and add them to `@scalar.config.json` to have them automatically become interactive API references. - -The starter kit includes an example OpenAPI document to show you how it works. - -Read more about [API References](api-references.md) - -## 3. Customize Everything - -Make it yours with themes, custom CSS, and MDX. Configure your documentation structure, navigation, and styling through `scalar.config.json`. - -## 4. Publish Your Docs - -First, authenticate with your Scalar account: - -```bash -npx @scalar/cli auth login -``` - -Then publish your documentation: - -```bash -npx @scalar/cli project publish -``` - -Your site will be available at `.apidocumentation.com`. - -## Stuck? - -Check whether your `scalar.config.json` is valid: - -```bash -npx @scalar/cli project check-config -``` - -We're here to help: - -- [Email support@scalar.com](mailto:support@scalar.com) -- [Chat with us on Discord](https://discord.gg/scalar) -- [Schedule a call](https://scalar.cal.com/scalar/chat-with-scalar) diff --git a/docs/content/quickstart.mdx b/docs/content/quickstart.mdx new file mode 100644 index 0000000..514017b --- /dev/null +++ b/docs/content/quickstart.mdx @@ -0,0 +1,26 @@ +# Quickstart + +Welcome to the Scalar Docs Starter Kit — a template for deploying beautiful documentation from a GitHub repository. Every page is MDX by default: mix Markdown with JSX expressions (this page rendered in {new Date().getFullYear()}) and drop in components anywhere. Fork it, edit the files under `docs/content/`, and make it yours. + +## Explore + +- [**API References**](api-references) — add OpenAPI documents from a file, the Scalar Registry, or a URL +- [**Components**](components/callout) — Callout, Button, Tabs, and every other component you can drop into MDX +- [**Layouts**](layouts/no-toc) — hide the sidebar, move search, or build a fully custom landing page + +## Preview locally + +```bash +npx @scalar/cli@latest project preview +``` + +Starts a dev server at `http://localhost:7971` with live reload. + +## Publish + +```bash +npx @scalar/cli@latest auth login +npx @scalar/cli@latest project publish +``` + +Your site will be available at `.apidocumentation.com`. diff --git a/scalar.config.json b/scalar.config.json index 5d83994..574f32c 100644 --- a/scalar.config.json +++ b/scalar.config.json @@ -19,32 +19,111 @@ "children": { "/": { "type": "page", - "filepath": "docs/content/quickstart.md", + "filepath": "docs/content/quickstart.mdx", "title": "Quickstart", "icon": "phosphor/regular/fast-forward" }, - "/usage": { + "/api-references": { + "type": "page", + "filepath": "docs/content/api-references.mdx", + "title": "API References", + "icon": "phosphor/regular/notebook" + }, + "/components": { + "type": "group", + "title": "Components", + "mode": "flat", + "children": { + "/callout": { + "type": "page", + "filepath": "docs/content/components/callout.mdx", + "title": "Callout", + "icon": "phosphor/regular/megaphone" + }, + "/button": { + "type": "page", + "filepath": "docs/content/components/button.mdx", + "title": "Button", + "icon": "phosphor/regular/cursor-click" + }, + "/embed": { + "type": "page", + "filepath": "docs/content/components/embed.mdx", + "title": "Embed", + "icon": "phosphor/regular/video" + }, + "/image": { + "type": "page", + "filepath": "docs/content/components/image.mdx", + "title": "Image", + "icon": "phosphor/regular/image" + }, + "/fineprint": { + "type": "page", + "filepath": "docs/content/components/fineprint.mdx", + "title": "Fineprint", + "icon": "phosphor/regular/text-aa" + }, + "/math": { + "type": "page", + "filepath": "docs/content/components/math.mdx", + "title": "Math", + "icon": "phosphor/regular/function" + }, + "/page-link": { + "type": "page", + "filepath": "docs/content/components/page-link.mdx", + "title": "PageLink", + "icon": "phosphor/regular/link" + }, + "/tabs": { + "type": "page", + "filepath": "docs/content/components/tabs.mdx", + "title": "Tabs", + "icon": "phosphor/regular/squares-four" + } + } + }, + "/layouts": { "type": "group", - "title": "Usage", + "title": "Layouts", "mode": "flat", "children": { - "/development": { + "/no-toc": { "type": "page", - "filepath": "docs/content/development.md", - "title": "Development", - "icon": "phosphor/regular/code" + "filepath": "docs/content/layouts/no-toc.mdx", + "title": "No TOC", + "icon": "phosphor/regular/list-dashes", + "layout": { "toc": false } }, - "/api-references": { + "/no-sidebar": { "type": "page", - "filepath": "docs/content/api-references.md", - "title": "API References", - "icon": "phosphor/regular/notebook" + "filepath": "docs/content/layouts/no-sidebar.mdx", + "title": "No Sidebar", + "icon": "phosphor/regular/sidebar-simple", + "layout": { "sidebar": false } }, - "/documentation": { - "title": "Full Documentation", - "icon": "phosphor/regular/book", - "url": "https://scalar.com/products/docs/getting-started", - "type": "link" + "/search-in-header": { + "type": "page", + "filepath": "docs/content/layouts/search-in-header.mdx", + "title": "Search in Header", + "icon": "phosphor/regular/magnifying-glass", + "layout": { "search": { "position": "header" } } + }, + "/minimal": { + "type": "page", + "filepath": "docs/content/layouts/minimal.mdx", + "title": "Minimal", + "icon": "phosphor/regular/square", + "layout": { + "toc": false, + "header": false, + "sidebar": false, + "tabs": false, + "pageTitle": false, + "pageActions": false, + "search": { "enabled": false } + } } } }, From 65f2a90ae9f1f9b2ab156132659110a5531c1acd Mon Sep 17 00:00:00 2001 From: Hans Pagel Date: Thu, 23 Apr 2026 13:34:34 +0200 Subject: [PATCH 4/8] feat: components --- docs/content/components/button.mdx | 28 ++++++++++++++++++- docs/content/components/callout.mdx | 37 ++++++++++++++++++++++++- docs/content/components/embed.mdx | 20 +++++++++++++- docs/content/components/fineprint.mdx | 14 +++++++++- docs/content/components/image.mdx | 24 ++++++++++++++++- docs/content/components/math.mdx | 21 ++++++++++++++- docs/content/components/page-link.mdx | 23 +++++++++++++++- docs/content/components/tabs.mdx | 39 ++++++++++++++++++++++++++- 8 files changed, 198 insertions(+), 8 deletions(-) diff --git a/docs/content/components/button.mdx b/docs/content/components/button.mdx index 997640e..65bb749 100644 --- a/docs/content/components/button.mdx +++ b/docs/content/components/button.mdx @@ -1,3 +1,29 @@ +import { Button } from 'scalar-mdx-components' + # Button -TODO +A call-to-action link styled as a button. Always opens in a new tab. + +## Usage + + + +## 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 + + + + diff --git a/docs/content/components/callout.mdx b/docs/content/components/callout.mdx index 328721b..6c2f124 100644 --- a/docs/content/components/callout.mdx +++ b/docs/content/components/callout.mdx @@ -1,3 +1,38 @@ +import { Callout } from 'scalar-mdx-components' + # Callout -TODO +Highlight a block of content with a typed banner. Use sparingly — one or two per page. + +## Usage + + + This is the simplest possible 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 + + + Neutral information the reader may want to know. + + + + Something to be careful about — non-blocking. + + + + Something destructive or blocking. Read before proceeding. + + + + A happy confirmation or positive note. + + +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 index 63deb29..adaed7e 100644 --- a/docs/content/components/embed.mdx +++ b/docs/content/components/embed.mdx @@ -1,3 +1,21 @@ +import { Embed } from 'scalar-mdx-components' + # Embed -TODO +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 + + + +## 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 + + diff --git a/docs/content/components/fineprint.mdx b/docs/content/components/fineprint.mdx index 298beaf..c0688d9 100644 --- a/docs/content/components/fineprint.mdx +++ b/docs/content/components/fineprint.mdx @@ -1,3 +1,15 @@ # Fineprint -TODO +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 `` directly — no `import` needed. + +## Usage + + + This is fine print. Subject to change without notice. + + +## 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 `` element that doesn't have an MDX wrapper yet. diff --git a/docs/content/components/image.mdx b/docs/content/components/image.mdx index 17e3d62..d187e10 100644 --- a/docs/content/components/image.mdx +++ b/docs/content/components/image.mdx @@ -1,3 +1,25 @@ +import { Image } from 'scalar-mdx-components' + # Image -TODO +Display an image with optional caption, dark-mode source, and sizing. + +## Usage + +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 + +Mountain lake at sunset diff --git a/docs/content/components/math.mdx b/docs/content/components/math.mdx index 4043398..1a036cd 100644 --- a/docs/content/components/math.mdx +++ b/docs/content/components/math.mdx @@ -1,3 +1,22 @@ +import { Math } from 'scalar-mdx-components' + # Math -TODO +Render LaTeX equations with [KaTeX](https://katex.org/). + +## Usage + + + +## 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 + + + + diff --git a/docs/content/components/page-link.mdx b/docs/content/components/page-link.mdx index ba6b09a..3e99f60 100644 --- a/docs/content/components/page-link.mdx +++ b/docs/content/components/page-link.mdx @@ -1,3 +1,24 @@ +import { PageLink } from 'scalar-mdx-components' + # PageLink -TODO +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 + + + +## 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 + + + + diff --git a/docs/content/components/tabs.mdx b/docs/content/components/tabs.mdx index bad236a..9c39fc7 100644 --- a/docs/content/components/tabs.mdx +++ b/docs/content/components/tabs.mdx @@ -1,3 +1,40 @@ +import { Tabs, Tab } from 'scalar-mdx-components' + # Tabs -TODO +Group related content — typically code samples in different languages — behind a tab switcher. + +## Usage + + + + ```js + const users = await fetch('/api/users').then((r) => r.json()) + ``` + + + ```python + import requests + users = requests.get('/api/users').json() + ``` + + + ```bash + curl https://api.example.com/users + ``` + + + +## Props + +### `` + +| Prop | Type | Description | +| --------- | -------- | ---------------------------------------------------------------------------------- | +| `default` | `string` | Title of the tab to open by default. Matches case-insensitively. First tab if omitted. | + +### `` + +| Prop | Type | Description | +| ------- | -------- | ----------- | +| `title` | `string` | Tab label. | From 0c033548133d52121b25af5b9e9290d6e1422086 Mon Sep 17 00:00:00 2001 From: Hans Pagel Date: Thu, 23 Apr 2026 13:38:10 +0200 Subject: [PATCH 5/8] feat: layouts --- docs/content/layouts/minimal.mdx | 26 +++++++++++++++++++- docs/content/layouts/no-sidebar.mdx | 16 +++++++++++- docs/content/layouts/no-toc.mdx | 30 ++++++++++++++++++++++- docs/content/layouts/search-in-header.mdx | 14 ++++++++++- docs/content/quickstart.mdx | 6 ++--- 5 files changed, 85 insertions(+), 7 deletions(-) diff --git a/docs/content/layouts/minimal.mdx b/docs/content/layouts/minimal.mdx index 50bb50a..b7a0b78 100644 --- a/docs/content/layouts/minimal.mdx +++ b/docs/content/layouts/minimal.mdx @@ -1,3 +1,27 @@ # Minimal -TODO +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 index 8a76d6c..b32296d 100644 --- a/docs/content/layouts/no-sidebar.mdx +++ b/docs/content/layouts/no-sidebar.mdx @@ -1,3 +1,17 @@ # No Sidebar -TODO +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. diff --git a/docs/content/layouts/no-toc.mdx b/docs/content/layouts/no-toc.mdx index 4f72b67..e38f046 100644 --- a/docs/content/layouts/no-toc.mdx +++ b/docs/content/layouts/no-toc.mdx @@ -1,3 +1,31 @@ # No TOC -TODO +Hides the right-hand table of contents. Use on long scrolling pages, landing pages, or anywhere the TOC would be noise. + +## Config + +```json +{ + "type": "page", + "filepath": "docs/content/layouts/no-toc.mdx", + "layout": { "toc": false } +} +``` + +Drop the `layout` block into the route for any page you want to behave this way. + +## Verify + +This page has several headings below. On every other page they'd populate the right-hand TOC. Here that column is empty. + +## First extra heading + +Filler text. + +## Second extra heading + +More filler text. + +## Third extra heading + +Still more filler text. diff --git a/docs/content/layouts/search-in-header.mdx b/docs/content/layouts/search-in-header.mdx index a48c7fa..a9dd138 100644 --- a/docs/content/layouts/search-in-header.mdx +++ b/docs/content/layouts/search-in-header.mdx @@ -1,3 +1,15 @@ # Search in Header -TODO +Moves the search input from the sidebar into the top bar. Use when your audience expects search up top, or when the header feels empty. + +## Config + +```json +{ + "type": "page", + "filepath": "docs/content/layouts/search-in-header.mdx", + "layout": { "search": { "position": "header" } } +} +``` + +`position` accepts `"sidebar"` (default) or `"header"`. Drop the `layout` block into the route for any page you want to behave this way. diff --git a/docs/content/quickstart.mdx b/docs/content/quickstart.mdx index 514017b..3c33cb3 100644 --- a/docs/content/quickstart.mdx +++ b/docs/content/quickstart.mdx @@ -4,9 +4,9 @@ Welcome to the Scalar Docs Starter Kit — a template for deploying beautiful do ## Explore -- [**API References**](api-references) — add OpenAPI documents from a file, the Scalar Registry, or a URL -- [**Components**](components/callout) — Callout, Button, Tabs, and every other component you can drop into MDX -- [**Layouts**](layouts/no-toc) — hide the sidebar, move search, or build a fully custom landing page +- [**Layouts:**](layouts/no-toc) hide the sidebar, move search, or build a fully custom landing page +- [**Components:**](components/callout) Callout, Button, Tabs, and every other component you can drop into MDX +- [**API References:**](api-references) add OpenAPI documents from a file, the Scalar Registry, or a URL ## Preview locally From 253215d0d76171f45dbb500fb063c33fb7e9ce9b Mon Sep 17 00:00:00 2001 From: Hans Pagel Date: Thu, 23 Apr 2026 13:41:53 +0200 Subject: [PATCH 6/8] feat: minor tweaks --- docs/content/layouts/minimal.mdx | 4 +++- docs/content/layouts/search-in-header.mdx | 6 +++++- scalar.config.json | 7 ++++++- 3 files changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/content/layouts/minimal.mdx b/docs/content/layouts/minimal.mdx index b7a0b78..e75eb29 100644 --- a/docs/content/layouts/minimal.mdx +++ b/docs/content/layouts/minimal.mdx @@ -19,7 +19,9 @@ With everything off there's no built-in way back, so link somewhere manually: "tabs": false, "pageTitle": false, "pageActions": false, - "search": { "enabled": false } + "search": { + "enabled": false + } } } ``` diff --git a/docs/content/layouts/search-in-header.mdx b/docs/content/layouts/search-in-header.mdx index a9dd138..260fdd1 100644 --- a/docs/content/layouts/search-in-header.mdx +++ b/docs/content/layouts/search-in-header.mdx @@ -8,7 +8,11 @@ Moves the search input from the sidebar into the top bar. Use when your audience { "type": "page", "filepath": "docs/content/layouts/search-in-header.mdx", - "layout": { "search": { "position": "header" } } + "layout": { + "search": { + "position": "header" + } + } } ``` diff --git a/scalar.config.json b/scalar.config.json index 574f32c..23db419 100644 --- a/scalar.config.json +++ b/scalar.config.json @@ -108,7 +108,12 @@ "filepath": "docs/content/layouts/search-in-header.mdx", "title": "Search in Header", "icon": "phosphor/regular/magnifying-glass", - "layout": { "search": { "position": "header" } } + "layout": { + "header": true, + "search": { + "position": "header" + } + } }, "/minimal": { "type": "page", From 360d251b999446002cc8b339ceae126a0a026630 Mon Sep 17 00:00:00 2001 From: Hans Pagel Date: Thu, 23 Apr 2026 13:51:14 +0200 Subject: [PATCH 7/8] feat: some more tweaks --- AGENTS.md | 11 +++++++---- README.md | 12 ++++++++---- docs/content/components/button.mdx | 2 +- docs/content/components/page-link.mdx | 2 +- scalar.config.json | 4 ++++ 5 files changed, 21 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 48884a9..ffa97dd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ ## 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 Markdown/MDX files under `docs/` and OpenAPI documents under `docs/api-reference/`. +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 @@ -20,12 +20,15 @@ CI (`.github/workflows/validate-scalar-configuration.yml`) runs `check-config` o 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 Markdown via `filepath` (paths relative to repo root, e.g. `docs/content/quickstart.md`). +- `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 Usage and Examples sections. +- `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 the Markdown file under `docs/content/`, then add a route entry in `scalar.config.json` pointing at it. 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/`. +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. diff --git a/README.md b/README.md index a4375e8..aed59ca 100644 --- 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 ``, ` - diff --git a/docs/content/components/page-link.mdx b/docs/content/components/page-link.mdx index 3e99f60..5b3784b 100644 --- a/docs/content/components/page-link.mdx +++ b/docs/content/components/page-link.mdx @@ -6,7 +6,7 @@ Link to another page in this documentation. Preferred over a plain Markdown link ## Usage - + ## Props diff --git a/scalar.config.json b/scalar.config.json index 23db419..601e85f 100644 --- a/scalar.config.json +++ b/scalar.config.json @@ -12,6 +12,10 @@ } }, "navigation": { + "header": [ + { "type": "link", "title": "Log in", "to": "https://dashboard.scalar.com/login" }, + { "type": "link", "title": "Register", "style": "button", "icon": "phosphor/regular/user-plus", "to": "https://dashboard.scalar.com/register" } + ], "routes": { "/": { "type": "group", From f4963a88441210eb2050978268ec249b57f29c41 Mon Sep 17 00:00:00 2001 From: Hans Pagel Date: Fri, 24 Apr 2026 09:11:13 +0200 Subject: [PATCH 8/8] feat: add links to github and the documentation --- scalar.config.json | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/scalar.config.json b/scalar.config.json index 601e85f..c1889ba 100644 --- a/scalar.config.json +++ b/scalar.config.json @@ -33,6 +33,18 @@ "title": "API References", "icon": "phosphor/regular/notebook" }, + "/documentation": { + "type": "link", + "title": "Documentation", + "url": "https://scalar.com/products/docs/getting-started", + "icon": "phosphor/regular/book-open" + }, + "/github": { + "type": "link", + "title": "GitHub", + "url": "https://github.com/scalar/starter", + "icon": "phosphor/regular/github-logo" + }, "/components": { "type": "group", "title": "Components",