Scalar DocsCAUTION

Scalar is an open-source API platform: 🌐 Modern REST API Client 📖 Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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.

## Overview

- **File**: `scalar.config.json` (or `scalar.config.json5`)
- **Location**: Repository root by default; path can be overridden in [Scalar Dashboard](https://dashboard.scalar.com/)
- **Schema**: `https://registry.scalar.com/@scalar/schemas/config` — enables autocomplete in VS Code/Cursor when `json.schemaDownload.enable` is true
- **Version**: Use `"scalar": "2.0.0"` for the latest format

## Quick Start

Create a minimal config:

```bash
npx @scalar/cli project init
```

Minimal structure:

```json
{
  "$schema": "https://registry.scalar.com/@scalar/schemas/config",
  "scalar": "2.0.0",
  "info": {
    "title": "My Documentation",
    "description": "The best documentation you've read today"
  },
  "navigation": {
    "routes": {
      "/": {
        "title": "Introduction",
        "type": "page",
        "filepath": "docs/introduction.md"
      }
    }
  }
}
```

Validate config: `npx @scalar/cli project check-config`

---

## Root Properties

| Property     | Type     | Description                                                                 |
| ------------ | -------- | --------------------------------------------------------------------------- |
| `$schema`    | `string` | JSON Schema URL for editor autocomplete and validation                      |
| `scalar`     | `string` | Configuration version. Use `"2.0.0"`                                       |
| `info`       | `object` | Project metadata (title, description)                                       |
| `navigation` | `object` | Navigation structure (header, routes, sidebar, tabs)                        |
| `versions`   | `object` | Multi-version navigation. Use instead of `navigation` for versioned docs    |
| `siteConfig` | `object` | Site-level settings (domain, theme, head, logo, routing)                    |
| `assetsDir`  | `string` | Relative path to assets folder from config root                             |

---

## info

Project metadata displayed across the site:

```json
{
  "info": {
    "title": "My Documentation",
    "description": "Comprehensive guides for our API"
  }
}
```

---

## navigation

All navigation is in `navigation.routes`. Each route key is the URL path; the value is a config object.

### navigation.header

Links in the top bar. Use `type: "spacer"` to push items before it left and after it right.

```json
"header": [
  { "type": "link", "title": "Home", "to": "/" },
  { "type": "spacer" },
  { "type": "link", "title": "Log in", "to": "https://dashboard.example.com/login", "newTab": true },
  { "type": "link", "title": "Register", "style": "button", "icon": "phosphor/regular/user-plus", "to": "https://...", "newTab": true }
]
```

Properties: `title`, `type` (`"link"` | `"spacer"`), `to`, `style` (`"button"` | `"link"`), `icon`, `newTab`

The header only renders when this array has at least one item, and it is where the logo goes. A lone `{ "type": "spacer" }` is enough to get a header with just the logo.

### navigation.sidebar

Links at the bottom of the sidebar:

```json
"sidebar": [
  { "title": "Log in", "to": "https://...", "newTab": true }
]
```

### navigation.tabs

Tabs for quick access to sections:

```json
"tabs": [
  { "title": "API", "to": "/api", "icon": "phosphor/regular/plug" }
]
```

Tabs and a header work together, and neither requires the other. With tabs but no header, the logo renders in the tab bar.

### Route Types

#### Page (`type: "page"`)

Markdown/MDX content from a file:

```json
"/getting-started": {
  "type": "page",
  "title": "Getting Started",
  "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:

**File:**
```json
"/api": {
  "type": "openapi",
  "title": "My API",
  "filepath": "docs/api-reference/openapi.yaml",
  "icon": "phosphor/regular/plug"
}
```

**Registry:**
```json
"/api": {
  "type": "openapi",
  "title": "My API",
  "namespace": "my-organization",
  "slug": "your-api"
}
```

**URL:**
```json
"/api": {
  "type": "openapi",
  "title": "My API",
  "url": "https://example.com/openapi.json"
}
```

Display modes: `folder` (default), `flat`, `nested`.

**Single page mode:** Set `singlePage: true` to render all operations on a single page instead of creating separate pages for each operation:

```json
"/api": {
  "type": "openapi",
  "title": "My API",
  "filepath": "docs/api-reference/openapi.yaml",
  "singlePage": true
}
```

API Reference options (authentication, theme, etc.) go in a `config` object — same options as the [API Reference configuration](https://docs.scalar.com/configuration).

#### Group (`type: "group"`)

Collapsible section with children:

```json
"/products": {
  "type": "group",
  "title": "Products",
  "mode": "flat",
  "icon": "phosphor/regular/package",
  "children": {
    "/docs": { "type": "page", "title": "Documentation", "filepath": "docs/documentation.md" },
    "/api": { "type": "openapi", "title": "API Reference", "filepath": "openapi.yaml" }
  }
}
```

Modes: `flat`, `nested`, `folder` (default).

**Folder landing pages:** Add a `page` property to make clicking the folder navigate to a page:

```json
"/company": {
  "type": "group",
  "title": "Company",
  "mode": "folder",
  "page": { "type": "pa

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (6)

.agents/skills/scalar-design-system

.claude/skills

CLAUDE.md

import { validate } from '../../../../src/index'

import { validate } from '../../../../src/index'

import { validate } from '../../../../src/index'

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Scalar Docs](https://modelsatlas.com/skills/scalar/scalar-docs/badge.svg)](https://modelsatlas.com/skills/scalar/scalar-docs/)

Not your listing, or something out of date? Claim or update your listing.