mcpField
S
scalar-docs

scalar-docs

github.com/scalar開発16.3k576 回インストール今日更新
リポジトリ

scalar-docs について

scalar-docsは、Scalar Docsの設定を作成、編集、検証するためのリファレンススキルです。プロジェクトのドキュメントサイトを管理する開発者向けに、`scalar.config.json`のナビゲーション、APIリファレンス、サイト設定、バージョン管理とCLIコマンドを解説します。

主な機能

  1. 01scalar.config.jsonの構造を解説
  2. 02ページ、グループ、APIリファレンスのルート設定
  3. 03サイトテーマ、ドメイン、アセットの設定
  4. 04バージョン別ドキュメントのナビゲーション
  5. 05CLIによる初期化、検証、プレビュー

活用シーン

  1. 01プロジェクト用のScalar Docs設定を作成
  2. 02ドキュメントのナビゲーションとページレイアウトを調整
  3. 03OpenAPIリファレンスページを設定
  4. 04Docs 1.0の設定を2.0へ移行

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/scalar/scalar --skill scalar-docs

インストール後、Claude Code で/scalar-docsを入力して読み込まれたか確認します。

詳細

Scalar Docs 設定スキル — scalar.config.json

Scalar Docs の中心となる設定ファイル scalar.config.json の作成と更新に関するリファレンスです。任意のプロジェクトで Docs 設定を作成、編集、検証する際に使用します。

概要

  • ファイル：scalar.config.json（または scalar.config.json5）
  • 場所：デフォルトではリポジトリのルート。パスは Scalar Dashboard で変更できます
  • スキーマ：https://registry.scalar.com/@scalar/schemas/config — json.schemaDownload.enable が true の場合、VS Code/Cursor でオートコンプリートを有効にします
  • バージョン：最新の形式では "scalar": "2.0.0" を使用します

クイックスタート

最小限の設定を作成します：

npx @scalar/cli project init

最小限の構造：

{
  "$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"
      }
    }
  }
}

設定を検証します：npx @scalar/cli project check-config

ルートプロパティ

プロパティ型説明
$schemastringエディターでのオートコンプリートと検証に使用する JSON Schema URL
scalarstring設定バージョン。「2.0.0」を使用します
infoobjectプロジェクトのメタデータ（タイトル、説明）
navigationobjectナビゲーション構造（ヘッダー、ルート、サイドバー、タブ）
versionsobject複数バージョンのナビゲーション。バージョン管理されたドキュメントでは navigation の代わりに使用します
siteConfigobjectサイトレベルの設定（ドメイン、テーマ、head、ロゴ、ルーティング）
assetsDirstring設定ルートからアセットフォルダーまでの相対パス

info

サイト全体に表示されるプロジェクトのメタデータ：

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

navigation

すべてのナビゲーションは navigation.routes に記述します。各ルートのキーが URL パスで、その値が設定オブジェクトです。

navigation.header

トップバーのリンクです。type: "spacer" を使うと、その前の項目が左側に、その後の項目が右側に配置されます。

"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 }
]

プロパティ：title、type（"link" | "spacer"）、to、style（"button" | "link"）、icon、newTab

ヘッダーは、この配列に項目が1つ以上ある場合にのみ表示され、ロゴもここに配置されます。{ "type": "spacer" } だけでも、ロゴのみのヘッダーを表示できます。

navigation.sidebar

サイドバーの下部にあるリンクです：

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

セクションにすばやくアクセスするためのタブです：

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

タブとヘッダーは連携して動作しますが、どちらか一方だけでも使用できます。ヘッダーがなくタブだけがある場合、ロゴはタブバーに表示されます。

ルートの種類
ページ（type: "page"）

ファイルの Markdown/MDX コンテンツです：

"/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 }
}

レイアウト：toc（デフォルトは true）、sidebar（デフォルトは true）。

非表示のページ： showInSidebar: false に設定すると、直接 URL からはアクセスできる状態を保ちながら、ページをサイドバーに表示しないようにできます。

OpenAPI（type: "openapi"）

ファイル、Registry、または URL から取得する API リファレンスです：

ファイル：

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

Registry：

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

URL：

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

表示モード：folder（デフォルト）、flat、nested。

単一ページモード： singlePage: true に設定すると、各操作の個別ページを作成せず、すべての操作を1つのページに表示します：

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

API リファレンスのオプション（認証、テーマなど）は config オブジェクトに記述します。API Reference の設定と同じオプションを使用できます。

グループ（type: "group"）

子要素を含む折りたたみ可能なセクションです：

"/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" }
  }
}

モード：flat、nested、folder（デフォルト）。

フォルダーのランディングページ： page プロパティを追加すると、フォルダーをクリックしたときにページへ移動できます：

"/company": {
  "type": "group",
  "title": "Company",
  "mode": "folder",
  "page": { "type": "page", "title": "About Us", "filepath": "docs/company/index.md" },
  "children": {
    "/team": { "type": "page", "title": "Our Team", "filepath": "docs/company/team.md" }
  }
}

デフォルトの開閉状態： open: true を使うと、フォルダーをデフォルトで展開できます。

リンク（type: "link"）

外部 URL です：

"/github": {
  "type": "link",
  "title": "GitHub",
  "url": "https://github.com/org/repo",
  "icon": "phosphor/regular/github-logo"
}

siteConfig

branding

ロゴ — 単一の URL、またはモードごとに指定します。

"logo": "https://example.com/logo.svg"
// or
"logo": {
  "darkMode": "https://example.com/logo-dark.svg",
  "lightMode": "https://example.com/logo-light.svg"
}

ロゴは、サイトで最初に表示される領域にレンダリングされます。ヘッダー（navigation.header に項目がある場合）→ タブ（navigation.tabs があり、ヘッダーがない場合）→ サイドバー（どちらもない場合）の順です。layout によってこれらすべてを非表示にしたページでは、ロゴはレンダリングされません。logo が設定されていない場合は、同じ場所に info.title がレンダリングされます。

テーマ — 次のいずれかです：default、alternate、moon、purple、solarized、bluePlanet、deepSpace、saturn、kepler、mars、laserwave、none

"theme": "purple"

ソーシャルカード — og.imageTemplate にプロジェクト内の TSX/JSX テンプレートを指定すると、自動生成される共有画像を置き換えられます。パスは設定ファイルからの相対パスで、プロジェクト内に収める必要があります。

"og": {
  "imageTemplate": "./og/card.tsx"
}

テンプレートでは、{ title, description?, breadcrumb?, path, colors, logo, mode } を受け取って JSX を返す純粋関数をデフォルトエクスポートします。Satori によって描画されるため、使用できるのは Flexbox のみで、スタイルはインラインのみ、パッケージはインポートできません。siteConfig.head.meta の og:image を設定すると、サイト全体でこのテンプレートより優先されます。

domain

サブドメイン（無料）：https://<subdomain>.apidocumentation.com

"subdomain": "your-docs"

カスタムドメイン（Pro）：https://docs.example.com

"customDomain": "docs.example.com"

サブパス — 同じドメインで複数のプロジェクトを運用する場合：

"subpath": "/guides"
layout
"layout": {
  "toc": true,
  "header": true
}
head

スクリプト、スタイル、メタタグ、リンクを挿入します。

"head": {
  "title": "My Documentation",
  "meta": [
    { "name": "description", "content": "API documentation" },
    { "property": "og:image", "content": "https://example.com/og.png" }
  ],
  "styles": [{ "path": "docs/assets/custom.css", "tagPosition": "head" }],
  "scripts": [{ "path": "docs/assets/analytics.js", "tagPosition": "bodyClose" }],
  "links": [{ "rel": "icon", "href": "/favicon.png" }]
}

scripts と styles のパスは設定ファイルのルートからの相対パスです。links（ファビコン）のパスはルート相対パス（/favicon.png）です。

tagPosition："head" | "bodyOpen" | "bodyClose"。

footer
"footer": {
  "filepath": "docs/footer.html"
}
rss

変更履歴やブログの RSS フィードを公開して、読者が購読できるようにします。<path>/rss.xml に書き出されます。たとえば、/changelog にある変更履歴のフィードは /changelog/rss.xml に公開されます。

"rss": {
  "path": "/changelog",
  "title": "Scalar Changelog",
  "description": "Every Scalar release, as a feed"
}
プロパティ型必須説明
pathstringはい変更履歴のルート。例：/changelog。.. セグメントは使用できません
titlestringいいえフィードのタイトル。デフォルトはサイトタイトルに Changelog を加えたものです
descriptionstringいいえフィードの説明
entriesstringいいえheadings（デフォルト）または pages — 詳細は以下を参照

複数のフィードを公開するには、rss にこれらのオブジェクトのリストを設定します。それぞれに固有の path が必要で、<path>/rss.xml に書き出されます。

"rss": [
  { "path": "/changelog", "title": "Scalar Changelog" },
  { "path": "/blog", "title": "Scalar Blog" }
]

エントリーは、path のページまたはその配下のページにある日付付き見出し（## 1.2.0 (2026-07-24)）から作成され、新しい順にまとめられます。最上位の日付付き見出しレベルのみがエントリーの開始位置になります。それより下の見出し（日付の有無は問いません）は、直前のリリースにまとめられます。非表示のページはスキップされます。すべてのページで <link rel="alternate" type="application/rss+xml"> タグを使ってフィードを通知し、path 配下のページのヘッダーには購読ボタンが表示されます。

ブログにする場合は、entries に pages を設定します。すると、フロントマターに date（date: 2026-07-24）がある path 配下の各ページが、ページタイトルを使った項目になります。date のないページ（インデックスや下書き）はスキップされます。変更履歴にはデフォルトの headings を使用してください。

routing

リダイレクト：

"routing": {
  "redirects": [
    { "from": "/old-path", "to": "/new-path" },
    { "from": "/old-path/:wildcard", "to": "/new-path" },
    { "from": "/old-path/:pathMatch(.*)*", "to": "/new-path" }
  ]
}

パスパターン：

"routing": {
  "guidePathPattern": "/docs/:slug",
  "referencePathPattern": "/api/:slug"
}

assetsDir

アセットフォルダーへの相対パスです。アセットはサイトのルートから配信されます。

"assetsDir": "docs/assets"

Markdown では、![Image](/screenshot.png) または ![Image](../assets/screenshot.png) を使用します。

siteConfig.head では、スクリプトとスタイルには設定ファイルのルートからの完全な相対パスを、リンクにはルート相対パスを使用します。

Docs 1.0 からの移行

Docs 1.0 では guides と references の配列を使用していました。Docs 2.0 では navigation.routes を使用します。

アップグレード：

npx @scalar/cli project upgrade

結果を確認します：

npx @scalar/cli project preview

CLI コマンド

コマンド説明
npx @scalar/cli project initscalar.config.json を作成します
npx @scalar/cli project check-config設定を検証します
npx @scalar/cli project previewローカルでプレビューします（ポート 7970）
npx @scalar/cli project publishローカルファイルから公開します
npx @scalar/cli project publish --githubリンク済みの GitHub リポジトリから公開します
npx @scalar/cli project upgradeDocs 1.0 から移行します

バージョン

複数バージョンのドキュメントを作成するには、navigation の代わりに versions を使用します。

キーが default のバージョンは必須です。このバージョンがデフォルトで表示されます。追加のバージョン（例：v1）には任意の識別子を使用でき、バージョンセレクターに表示されます。各バージョンの routes 内では、サイドバーに正しく表示されるよう、ページを最上位の group で囲みます。

{
  "scalar": "2.0.0",
  "versions": {
    "default": {
      "title": "Version 2.0",
      "routes": {
        "/": {
          "type": "group",
          "title": "Documentation",
          "children": {
            "/": { "type": "page", "title": "Intro", "filepath": "docs/v2/intro.md" },
            "/api": { "type": "openapi", "title": "API", "filepath": "docs/v2/openapi.yaml" }
          }
        }
      }
    },
    "v1": {
      "title": "Version 1.0",
      "routes": {
        "/": {
          "type": "group",
          "title": "Documentation",
          "children": {
            "/": { "type": "page", "title": "Intro", "filepath": "docs/v1/intro.md" },
            "/api": { "type": "openapi", "title": "API", "filepath": "docs/v1/openapi.yaml" }
          }
        }
      }
    }
  }
}

各バージョンのエントリーでは、title、routes（必須）、header、sidebar、tabs を指定できます。

よくあるパターン

同じドメインで複数のプロジェクトを公開する場合： 同じ customDomain または subdomain を使用し、リポジトリごとに異なる subpath を設定します。

MDX： filepath に .mdx 拡張子を使用します。構造は Markdown ページと同じです。

ページの目次を非表示にする場合： そのルートに "layout": { "toc": false } を設定します。

API Reference の認証： openapi ルートの下に authentication を含む config を追加します（API Reference の設定と同じオプションです）。

カスタムドメインの DNS： CNAME ホスト docs → dns.scalar.com（DNS のみ、プロキシなし）。

参考資料

コメント

Markdown 対応