holocron

Holocron

Holocron のドキュメントは頻繁に変更されます。古い学習データや リポジトリ内の相対パスに依存しないでください。まず公開ドキュメントを取得してから、 検索してください。

関連ドキュメントページ

利用可能なすべてのページを確認するには、https://holocron.so/sitemap.xml を取得してください。ページ URL の末尾に .md を追加すると、生の Markdown を取得できます。curl の出力を head、tail、sed -n、または切り詰める コマンドに決してパイプしないでください。毎回、出力全体を読んでください。

curl -s https://holocron.so/sitemap.xml
curl -s https://holocron.so/docs/quickstart.md

ユーザーが特定のワークフローについて質問した場合は、該当するページを直接取得してください。

• 概要: https://holocron.so/llms.txt
• クイックスタート: https://holocron.so/docs/quickstart.md
• Holocron とは: https://holocron.so/docs/what-is-holocron.md
• ページの作成: https://holocron.so/docs/create/pages.md
• MDX 構文: https://holocron.so/docs/create/mdx.md
• ローカルインポート: https://holocron.so/docs/create/local-imports.md
• リダイレクト: https://holocron.so/docs/create/redirects.md
• docs.json の設定: https://holocron.so/docs/organize/docs-json.md
• 設定スキーマ: https://holocron.so/docs.json
• ナビゲーション: https://holocron.so/docs/organize/navigation.md
• テーマのカスタマイズ: https://holocron.so/docs/customize/theme.md
• アイコン: https://holocron.so/docs/customize/icons.md
• カスタムエントリー（Spiceflow）: https://holocron.so/docs/custom-entry.md
• Spiceflow の統合: https://holocron.so/docs/spiceflow.md
• Cloudflare へのデプロイ: https://holocron.so/docs/deploy/cloudflare.md
• Node へのデプロイ: https://holocron.so/docs/deploy/node.md
• Holocron へのデプロイ: https://holocron.so/docs/deploy/holocron.md
• AI アシスタント向けドキュメント: https://holocron.so/docs/ai/assistant.md
• Bleed: https://holocron.so/docs/customize/bleed.md
• レイアウトとページモード: https://holocron.so/docs/customize/layout.md

curl -fsSL https://holocron.so/docs/quickstart.md
curl -fsSL https://holocron.so/docs/organize/docs-json.md

新しいプロジェクトのスキャフォールディング

CLI を使って、動作するテンプレートで新しいドキュメントサイトを作成します。

npx -y "@holocron.so/cli" create --name "My Docs" my-docs --skip-auth

--skip-auth フラグを指定すると、クラウドのセットアップと AI チャットのセットアップをスキップします（エージェントやローカルのみでの使用に適しています）。テンプレートには vite.config.ts、docs.jsonc、サンプルページ、 タブ、アンカー、アイコンを含むナビゲーションが含まれます。

スキャフォールディングの後、開発サーバーを起動します。

cd my-docs
pnpm install
pnpm dev

docs.json の基本

Holocron は docs.json、docs.jsonc、または holocron.jsonc を読み込みます。手作業で記述する場合は、 コメントと末尾のカンマを使えるため、保守しやすい docs.jsonc を推奨します。

一般的でない設定フィールドを追加する前に、必ずスキーマを取得してください。

curl -fsSL https://holocron.so/docs.json

シンプルな docs.jsonc の例：

{
  "$schema": "https://holocron.so/docs.json",
  "name": "Acme",
  "description": "Documentation for Acme.",
  "colors": { "primary": "#6366f1" },
  "icons": { "library": "lucide" },
  "navigation": {
    "groups": [
      {
        "group": "Getting Started",
        "icon": "lucide:rocket",
        "pages": ["index", "docs/quickstart"]
      },
      {
        "group": "Guides",
        "icon": "lucide:map",
        "pages": ["docs/install", "docs/deploy"]
      }
    ],
    "global": {
      "anchors": [
        { "anchor": "GitHub", "href": "https://github.com/example/docs", "icon": "lucide:github" },
        { "anchor": "Changelog", "href": "https://github.com/example/docs/releases", "icon": "lucide:newspaper" }
      ]
    }
  }
}

navigation.pages のページスラッグは MDX ファイルに対応します。docs/quickstart を読み込むと docs/quickstart.mdx が読み込まれ、docs/install を読み込むと docs/install.mdx が読み込まれます。

ナビバーのリンクと CTA

アプリのルート（ログイン、ダッシュボード、サインアップ）は navbar と、 リンクチェックを通過するように knownPaths に指定します。

"navbar": {
  "links": [{ "label": "Log in", "href": "/login" }, { "label": "Dashboard", "href": "/dashboard" }],
  "primary": { "type": "button", "label": "Start free trial", "href": "/signup" }
},
"knownPaths": ["/login", "/signup", "/dashboard"]

スラッグは短く保ちます。ドキュメントは /docs 配下に置きます

短いスラッグを優先します。 サイドバーの各グループに合わせてページを細かくネストしないでください。

後からランディングページ、ツール、製品をドキュメントの URL と競合させずにルートに配置できるよう、情報ドキュメントは docs/ 配下に置きます。

  URL                         file
  /                        ►  index.mdx          (home, product, landing)
  /pricing                 ►  pricing.mdx        (not a docs page)
  /docs/quickstart         ►  docs/quickstart.mdx
  /docs/sdk                ►  docs/sdk.mdx
  /docs/cli/query          ►  docs/cli/query.mdx   (max extra folder)

ルール：

• ホームはルートに置きます。 index.mdx は / です。
• ドキュメントのページには /docs/... を使います。 docs/quickstart.mdx は /docs/quickstart です。ガイドを /quickstart や /guides/quickstart に置かないでください。
• ネストは docs/<folder>/<page> までです。 docs の下に置けるサブディレクトリは 1 つまでです（docs/cli/query.mdx）。docs/cli/analytics/pages.mdx のような構成にはしないでください。
• ページ名に README.md や README.mdx を使わないでください。 どちらのファイル名も /README または /docs/README になります。実際のスラッグ（docs/sdk.mdx）を使い、共有 Markdown をインポートしてください。
• index はホームまたはセクションのハブにのみ使います。 ハブのファイル名に README を使わないでください。
• ページを移動すると URL が変わります。 古いスラッグからのリダイレクトを追加してください。navigation.pages と相対リンクを更新してください。ビルド時のリンク切れチェックで、更新漏れを検出できます。

navigation.global.anchors の アンカーは、すべてのタブで表示される永続的なサイドバーリンクです。GitHub、Changelog、Discord、その他の外部リンクに使用してください。

ナビゲーションでの段階的な情報開示。 グループ、ページ、タブは、読者が上から下へ読む順に並べてください。導入コンテンツ（はじめに、クイックスタート）から始め、次に主要な概念とガイド、最後に高度なトピックとリファレンス資料を配置します。読者が現在のセクションを理解するために、先の内容に飛ぶ必要がないようにしてください。

タブの順序。 navigation.tabs では、ドキュメントとガイドを最初に、次に API リファレンス、最後に changelog を並べます。外部 URL（href）へのリンクを含むタブは最後に配置してください。これにより、読者は概念からリファレンスへと進めます。

アイコン

ソースライブラリを明示するため、プレフィックス付きのアイコン名を使います。

"icon": "lucide:rocket"
"icon": "fontawesome:brands:github"

プレフィックスのない名前は、設定されたライブラリを参照します。詳しくは https://holocron.so/docs/customize/icons.md をご覧ください。

グループにアイコンを設定している場合、そのグループの最初のページには同じアイコンを使わないでください。ナビゲーションツリーで重複して見えます。

ローカルインポート

MDX ページでは .md、.mdx、.tsx、または .ts ファイルをインポートできます。絶対パスの / インポートではなく、相対インポート（./ または ../）を優先してください。

ラッパーページを使って共有 Markdown を再利用します。 GitHub 用の README.md、MCP.md、または SDK の Markdown ファイルは、pagesDir の外に置いてください。これらのファイルを README.md または README.mdx として pagesDir に置かないでください。Holocron のスラッグはファイルパスなので、sdk/README.mdx は /sdk/README になります。

pagesDir 内のラッパーが公開スラッグを管理します。

repo/
  README.md
  MCP.md
  website/src/pages/
    index.mdx
    docs/sdk.mdx          → /docs/sdk
    docs/mcp-setup.mdx    → /docs/mcp-setup

---
$schema: https://holocron.so/frontmatter.json
title: "MCP Setup"
sidebarTitle: MCP
---

import SharedDocs from '../../../../MCP.md'

<SharedDocs />

ファイル：docs/mcp-setup.mdx。ナビゲーションスラッグ："docs/mcp-setup"。URL：/docs/mcp-setup。

古い /README または /sdk/README の URL が存在する場合は、リダイレクトを追加してください。

"redirects": [
  { "source": "/sdk/README", "destination": "/docs/sdk", "permanent": true }
]

詳しくは https://holocron.so/docs/create/local-imports.md をご覧ください。

ページ間のリンク

重要

内部リンクは必ず相対パス（./ または ../）にしてください。/ で始まる 絶対パスのリンクは絶対に使用しないでください。

あるページから別のページへの内部リンクは、すべて次の条件を満たす必要があります。

1. ./ または ../ で始める — 現在のファイルからの相対パスにします。リンクを / で 始めてはいけません。
2. ディスク上の実際のリンク先ファイルを指定する — ルートやスラッグではなく、実際の .md／.mdx ファイルを指定します。
3. .md／.mdx 拡張子を残す。

✅ [SDK reference](./sdk.mdx)
✅ [Browser Analytics](./browser-analytics.mdx)
✅ [Quickstart](./quickstart.mdx)

❌ [SDK reference](/sdk/README)
❌ [Browser Analytics](/docs/browser-analytics)
❌ [Quickstart](/quickstart)

理由は、絶対パスの /slug リンクではルートが固定され、そのルートは pagesDir に依存するためです。同じファイルでも、プロジェクトによってスラッグが異なります（pagesDir: './src' と pagesDir: './src/pages'）。そのため、絶対パスのリンクは壊れやすく、pagesDir やフォルダー構成を変更すると機能しなくなります。実際のファイルへの相対パスは pagesDir に依存しません。Holocron は正しいルートに解決して拡張子を削除し、リンクから GitHub 上の実際のファイルを開くこともできます。

リンクを書くときに、スラッグや pagesDir を考慮してはいけません。 GitHub でのリンクと同じように、ディスク上の実際のファイルへの相対パスを書いてください。あとは Holocron が処理します。/ で始められるリンクは、外部の完全な URL（https://...）と、docs.json で宣言された knownPaths エントリーのみです。

GitHub でもレンダリングされる README のインポート

よくあるパターンとして、リポジトリの README.md をドキュメントのインデックスページとしてインポートし、GitHub と Holocron サイトの両方で同じファイルをレンダリングします。README から他のドキュメント（料金、ガイド、リファレンス）にリンクする場合、そのリンクは両方で機能する必要があります。

ルールはシンプルです。常に、正しい相対パスを使って、実際のリンク先ファイルにリンクしてください。拡張子は .md または .mdx で終わるようにします。 スラッグ、pagesDir、/ の位置を考慮してはいけません。GitHub でのリンクと同じように、README からディスク上の実際のファイルへの相対パスを書いてください。

あとは Holocron が処理します。インポートしたファイルをインライン化する際、すべての相対リンクをインポート先のページを基準に正しくなるよう再計算し、続いて .md／.mdx 拡張子を削除します。そのため、README から実際のファイルへのリンクは、環境ごとに推測しなくても、自動的にそのファイルのページに移動します。

ルール

1. 実際のファイルにリンクする。 リンク先は、指定した相対パス上にある、ディスク上の実際の .md／.mdx ファイルでなければなりません。これによって GitHub でリンクが機能し、Holocron による書き換えも機能します。ファイルが存在しない場合、GitHub では 404 となり、Holocron のリンク切れチェックで警告が表示されます。

2. 必ず相対パス（./ または ../）を使い、絶対パスは使わない。 GitHub と Holocron では README の基準ディレクトリが異なるため、/docs/x のような絶対パスや推測したパスは、どちらかで機能しなくなります。実際のファイルへの相対パスなら、Holocron が再計算するため、両方で機能します。

3. .md／.mdx 拡張子を残す。 GitHub でファイルを開くには拡張子が必要です。Holocron はリンク先がレンダリング済みのページになるよう、自動的に拡張子を削除します。

4. リンク先ファイルは pagesDir 内のページでなければならない。 Holocron がリンク先として対応付けるのは、pagesDir 内のファイルのみです。共有マークダウンファイルをインポートしても、そのファイルにルートが作成されるわけではありません。インポートしたマークダウンからは、README.md／MCP.md ではなく、pagesDir 内のラッパー .mdx にリンクしてください。

   [README.md](./README.md) は /README になります。代わりに [クイックスタート](./website/src/pages/docs/quick-start.mdx) を使用してください。

   README.md   [pricing](./docs/pricing.md)   ◄── correct relative path to a real file
        │
        ├──────────────────────► GitHub opens ./docs/pricing.md
        │
        ▼  imported into the index page
   Holocron recomputes the relative path ──► strips .md ──► lands on the page that renders pricing
        │
        ▼
   /docs/pricing   ◄── resolves as long as a page renders that file and it is in docs.json

書き換え後のスラッグに一致するページがない場合、ビルド時に README の該当行を示すリンク切れ警告が出力されます。<pagesDir>/<slug>.mdx にページ（または共有 .md をインポートするラッパー）を作成し、そのスラッグを docs.json のナビゲーションに追加して修正してください。

README ファイル内の MDX JSX

README.md 内では、<Aside>、<Note>、<CardGroup>、<Card> などの MDX JSX コンポーネントを使用しないでください。GitHub は不明な HTML タグ内のマークダウンをレンダリングしません。タグ内のコンテンツは、書式設定されていない生のテキストとして表示されます。

README では標準のマークダウンのみを使用してください。MDX 専用コンポーネントは、README 自体ではなく、README をインポートする .mdx ファイルに記述してください。

ページのフロントマター

すべての MDX ページには、YAML フロントマターを含めることができます。フィールドの完全な一覧は、 https://holocron.so/docs/create/pages.md を参照してください。

---
$schema: https://holocron.so/frontmatter.json
title: Quickstart
description: Build and deploy your first Holocron docs site.
icon: lucide:rocket
tag: NEW
prompt: |
  Write the Quickstart from @/cli/src/create.ts.
---

生成プロンプトを記録する

作成するすべてのドキュメントページには、そのページの生成に使用した指示とソースを記録する prompt フィールドを含める必要があります。このフィールドがない既存のページを編集する場合、実際のソースを特定できたら追加してください。保守用の指示ではなく、最初の生成レシピを記述してください。

リポジトリのルートからのソースファイルとフォルダーには @/path を使用してください。ソースが MDX ページと同じ場所にある場合に限り、@./path または @../path を使用してください。リモートソースには @https:// を付けてください。URL だけでは参照として扱われません。ソースを捏造せず、ソースの場所やページの範囲が変わったらプロンプトを更新してください。

---
$schema: https://holocron.so/frontmatter.json
title: Authentication
prompt: |
  Write the authentication guide from @/src/auth/ and
  @/src/middleware/session.ts.
  Use @https://github.com/example/project/releases for recent behavior.

  Explain sessions, API keys, and GitHub Actions OIDC.
  Include a complete TypeScript example for every method.
---

Holocron Maintain はこれらの参照を抽出し、ソースが変更されると生成プロンプトを再実行します。フォルダーを参照すると、そのフォルダー内で追跡されているファイルの変更がすべて対象になります。

既存のドキュメントサイトを移行する

ドキュメントサイトを Holocron に移行する場合、各 prompt は、ページを最初から作成するかのように記述してください。そのページで説明する内容を短くまとめてください。

移行、再作成、または以前のドキュメント URL について言及しないでください。@https://old-site/... の参照を追加しないでください。ユーザーから別途指示がない限り、移行後にソースサイトは閉鎖されます。

prompt: |
  Document connecting the first integration, role access, and chat validation.

タイトルは最大で50～60 文字にしてください。タイトルは、OG 画像内の大きなフォント、ブラウザーのタブ、検索結果に表示されます。簡潔で内容が伝わるものにしてください。

サイドバーのタイトル — title が30 文字を超える場合は、フロントマターに短いラベル（30 文字未満）を指定する sidebarTitle フィールドを追加してください。左側のナビゲーションの幅は 230px しかないため、長いタイトルは複数行に折り返され、見た目の統一感を損ないます。サイドバーのナビゲーションでのみ、sidebarTitle がタイトルに置き換わります。ページ見出し、ブラウザーのタブ、OG 画像には、引き続き完全なタイトルが表示されます。

---
$schema: https://holocron.so/frontmatter.json
title: Configuring Authentication Providers
sidebarTitle: Auth Providers
---

説明は120～150 文字にしてください。OG 画像ではタイトルの下に、検索エンジンのスニペットでは検索結果に表示されます。ページの内容を要約した一文にしてください。説明が長すぎると、省略記号で切り詰められます。

ページタイトルと SEO（必ず従ってください）

Google のタイトルリンクとスニペットは、ページ上のタイトル、H1、説明文から生成されます。 タイトルリンク とスニペットを参照してください。

Holocron はすでにサイト名を追加します。buildPageTitle は、title がサイト名で始まっていない限り、 {page title} — {site name} を表示します。 title や H1 にサイト名を入れないでください。 ブランド名が重複します （Kimaki: … — Kimaki）。検索順位を狙うキーワードだけを書いてください。Holocron に — {site name} を追加させます。

フロントマターのフィールドは 2 つです。

• title — ブラウザーのタブ、Google のタイトルリンク、OG 画像、挿入される H1 に使われます。SEO を意識して書いてください。このページで検索順位を狙うキーワードを入れます。
• sidebarTitle — サイドバー専用です。30 文字未満の短いラベルにします。

両方を必ず設定してください。 sidebarTitle がないと、長い SEO タイトルが幅 230px のサイドバーで折り返されます。

フロントマターの文字列は必ず引用符で囲んでください。 YAML では : はマップとして扱われます。title: Kimaki: AI agents はネストされた YAML です。その場合、Holocron はフロントマター全体を破棄し、ブラウザーのタイトルは本文の最初の見出しになります。引用符で囲まれていない値に : が含まれる場合や、解析されたキーにスペースと : が含まれる場合、Holocron は警告を表示します。

---
$schema: https://holocron.so/frontmatter.json
title: "Open-source browser automation"
sidebarTitle: Home
description: "Automate any browser with a TypeScript API. Control Chrome from a CLI or agent."
---

ブラウザーのタブ：Open-source browser automation — Playwriter 挿入される H1：Open-source browser automation サイドバー：Home

ほとんどのページでは、Holocron が title を唯一の H1 として挿入するため、title と H1 は同じです。この状態を保ってください。本文に別の # や <h1> を追加しないでください。

タイトルのルール：

• 検索順位を狙うキーワードを title に入れてください。 ホームページのタイトルが最も重要です。ドキュメントページでは、Introduction や Overview ではなく、トピックのキーワード（Subscriptions、Worktrees）を使います。
• title をサイト名で始めないでください。 Holocron がすでに — {site name} を追加します。
• title にサイト名と同じ文字列を設定しないでください。 Playwriter というタイトルは Playwriter — Playwriter になります。
• すべての title は必ず固有で、内容が明確にわかり、簡潔でなければなりません。 Google は長いタイトルを省略します。キーワードの詰め込みや、単語を 1 つだけ変えた定型文は避けてください。
• index.mdx では必ず sidebarTitle: Home（または Overview）を設定してください。 詳細は「ホームページの SEO」を参照してください。

H1 のルール：

• 1 ページにつき H1 は 1 つです。 title と同じ検索順位を狙うキーワードを含めてください。title のテキストをそのまま使うのがおすすめです。Holocron がタイトルを挿入すると、自動的にこのルールが適用されます。
• Google は、最初の目立つ H1 をタイトルリンクの情報源として使います。同じ重みの H1 を追加すると、ブラウザーのタブタイトルが別のものに置き換わることがあります（Quick Start — Site）。見出しの数は検索順位に影響しません。明確なメインタイトルが重要です。

説明文のルール：

description は <meta name="description"> になります。ページ上のテキストよりページ内容を的確に説明している場合、Google はスニペットとして使用することがあります。

• ページごとに固有の内容にしてください。 すべてのページに同じサイト全体の説明を使っても、検索結果では役に立ちません。
• このページの内容を 1〜2 文で要約してください。キーワードの羅列にはしないでください。
• 検索順位を狙うキーワードを自然に含めてください。 詰め込まないでください。タイトルの接尾辞にすでにサイト名があるからといって、繰り返す必要はありません。ホームページでは、要約の中で製品名を 1 回使ってもかまいません。
• 具体的に書いてください。 文字数に厳密な上限はありません。Google はデバイスの幅に合わせて省略します。120〜160 文字程度の短い紹介文を目安にしてください。
• YAML 文字列は引用符で囲んでください。

description: "Run AI coding agents from Discord. Each channel is a project, each thread is a session."

ホームページのSEO

ホームページのタイトルは、ブランド検索で最も強いシグナルです。ユーザーが検索するキーワードをtitleとH1に入れましょう。サイト名はHolocronに追加させます。

---
$schema: https://holocron.so/frontmatter.json
title: "AI coding agents from Discord"
sidebarTitle: Home
description: "Run AI coding agents from Discord. Each channel is a project, each thread is a session."
---

ブラウザーのタブ：AI coding agents from Discord — Kimaki H1：AI coding agents from Discord

H1は1つだけにし、titleと同じキーワードを使います。 ページに<Above>またはhideTitle: trueが設定されていない限り、HolocronはこのH1を挿入します。カスタムヒーローでも<h1>を表示すると、挿入されたタイトルと合わせてH1が2つになります。

ページに<Above>がある場合、そのヒーローがH1を担当します。 Holocronはタイトルを挿入しません。ヒーローのH1にはtitleと同じテキストを設定してください。ヒーローのH1にサイト名を入れないでください。その下のMDX本文に#や<h1>を書かないでください。本文の最初のセクションは##にします。追加のH1はH2に降格されます。

---
title: "AI coding agents from Discord"
sidebarTitle: Home
description: "Run AI coding agents from Discord. Each channel is a project, each thread is a session."
---

<Above>
  <HeroSection />
</Above>

<h1>
  <span>AI coding agents</span>
  <span>from Discord.</span>
</h1>

カスタムヒーローがない場合は、hideTitleを設定しないでください。 Holocronにtitleを唯一のH1として挿入させます。

/をGitHubのクローンにしないでください。 ヒーローの下にREADME.mdを読み込むのは問題ありません。それでもホームページには、独自のタイトル、H1、説明が必要です。/の内容がGitHubと同じ場合、GoogleはGitHubと固有のドキュメント内ページを優先します。

/へのロゴリンクだけでは効果が弱いです。まずタイトル、H1、説明を修正してください。

デプロイ後、公開中のHTMLを取得して次の点を確認します。

curl -sL -A 'Mozilla/5.0 (compatible; Googlebot/2.1)' 'https://example.com/' -o /tmp/home.html

<h1>が正確に1つだけであること、そのH1のテキストがtitleと一致していること、そして<title>が{title} — {site name}となり、サイト名が末尾にのみ含まれていることを確認してください。Googleが再クロールするまでは、検索順位は変わりません。

ヒーロー背景上のテキストを読みやすくする

VideoBackgroundShaderのヒーローに重ねたテキストは、アニメーションする文字がテキストと干渉するため、読みにくくなります。必ずコントラストレイヤーを追加してください。

見出しとCTA： 背景の中央を暗くする放射状のスクリーンを、コンテンツの背後に追加します（テキストのz-[2]より下のz-[1]）。

<div
  aria-hidden
  className='absolute inset-0 z-[1] pointer-events-none'
  style={{
    background:
      'radial-gradient(ellipse 45% 40% at 50% 42%, color-mix(in srgb, var(--background) 85%, transparent) 0%, color-mix(in srgb, var(--background) 60%, transparent) 50%, transparent 100%)',
  }}
/>

サブ見出しと小さなテキスト： ぼかしを加えた半透明のピル型背景を付けます。これがないと、控えめな色の小さなテキストは文字の背景に埋もれて読めません。

<p className='rounded-xl bg-background/50 px-3 py-1.5 text-sm text-muted-foreground backdrop-blur-md'>
  Paste the prompt into your agent
</p>

また、タイトルのコントラストを保てるよう、dotColorはページの背景色に近い色にしてください。

ページモード — サイドバーを非表示にする

サイドバーを非表示にするには、フロントマターで**mode**を設定します。ランディングページ、ツールページ、左ナビゲーションやAIチャットを表示しないページに使用してください。詳細はhttps://holocron.so/docs/customize/layout.mdを参照してください。

• center — 左ナビゲーションを非表示にして、コンテンツを中央に配置します。右側のサイドバーは引き続き使用できます。
• custom — 両方のサイドバーとエディトリアルグリッドを非表示にします。ナビゲーションバー、タブバー、フッターのみが残ります。完全な例はexample/src/landing.mdxを参照してください。

どちらのモードでも、コンテンツの幅が広すぎる場合があります。**maxWidth**を使って幅を制限してください。

---
$schema: https://holocron.so/frontmatter.json
mode: "custom"
maxWidth: 700
---

カスタムエントリー（Spiceflowアプリ内にドキュメントをマウントする）

既存のSpiceflowアプリ内にHolocronをマウントする場合（Viteプラグインのentryオプション）、まずカスタムエントリーのドキュメントを必ず確認してください。このページでは、ミドルウェアの順序、共有テーマCookie、Tailwindの@referenceルール、OpenAPIやChangelogのタブを含むドキュメントを/docs/*名前空間配下に置き、/apiなどのアプリのルートと競合しないようにする方法を説明しています。

curl -fsSL https://holocron.so/docs/custom-entry.md

リダイレクト

ドキュメントを再構成するときは、docs.jsonにリダイレクトを追加してください。詳細はhttps://holocron.so/docs/create/redirects.mdを参照してください。

リンク切れの検出

Holocronは、内部リンクが存在しないページを指していると本番ビルドを失敗させます。開発時には警告が表示されます。MDX、フッター、ナビゲーションバー、アンカー内のリンクがすべてチェックされます。リダイレクト元や静的ファイル（.json、.pdfなど）へのリンクは警告されません。警告にはソース、行番号、リンク切れのhrefが含まれるため、すぐに見つけて修正できます。

実行時にそのルートが実際に存在しない限り、knownPathsにパスを追加しないでください。knownPathsはチェックを抑止するだけで、ページを作成するものではありません。

knownPathsによる誤検出の抑制

ドキュメントをほかのルート（APIエンドポイント、ダッシュボード、ブログ）と一緒にマウントすると、MDX以外のパスへの内部リンクで、リンク切れの誤警告が発生します。docs.jsonの**knownPaths**フィールドを使って、これらのパスが有効であることをHolocronに伝えます。

{
  "knownPaths": ["/api/*", "/dashboard", "/blog/*"]
}

サポートされるパターン：

• 完全一致のパス — "/dashboard"は/dashboardのみに一致します。
• ワイルドカードのプレフィックス — "/api/*"は、/api/users、/api/v2/health、および/api/で始まるその他すべてのパスに一致します。

ワイルドカードは末尾が/*の形式でのみ使用できます。/api/*/usersのようなグロブパターンはサポートされていません。

ラッパー内の垂直方向の間隔

MDXコンテンツを<div>またはカスタムコンポーネントでラップする場合は、子要素に適切な垂直方向の間隔が適用されるよう、flex flex-col gap-(--prose-gap)を追加してください。追加しないと、要素が詰まって表示されます。ラッパーに、その範囲からはみ出してはいけない画像やコードブロックが含まれる場合は、no-bleedも追加してください。

<div className='no-bleed flex flex-col gap-(--prose-gap)'>

First paragraph.

Second paragraph with correct spacing above.

</div>

MDXコンテナコンポーネント

Callout、Note、Warning、Info、Tip、Check、Danger、Aside、Accordion、Steps、Card、Expandable、Panel、Frame、Promptなどのコンテナコンポーネントには、必ず複数行形式を使用してください。

<Note>
Use `Note` for neutral supporting information.
</Note>

1行形式では、段落で囲まれない簡潔な表現が子要素になり、スタイルが変わることがあります。

ネイティブの見出し（h1～h6）は自動的に修正されます。Holocronは形式にかかわらず、段落ラッパーを取り除きます。その他のリーフ要素（<span>、<div>、または大文字で始まるカスタムコンポーネント）では、ラッパーを避けるために1行形式を使用してください。

<MyBanner className='text-xl'>Short announcement text</MyBanner>

Asideのコンテンツ

Asideは配置専用で、視覚的なフレームはありません。表示するコンテンツは、必ずNote、Tip、Info、Warning、Callout、またはほかのフレーム付きコンポーネントで囲んでください。

<Aside>
<Note>
This appears in the sidebar with a proper callout frame.
</Note>
</Aside>

例外：Aside fullには、TableOfContentsPanelを直接含めることができます。

十分なコンテンツがあるセクションでのみ<Aside>を使用してください。 fullでないAsideは、属するセクション（2つの見出しの間のコンテンツ）と垂直方向のスペースを共有します。Asideがセクション本文より高い場合、Asideの高さに合わせるため、メインコンテンツの下に余白が生じます。Asideのコールアウトは短くし、本文が少なくとも数段落あるセクションにのみ配置してください。

ページの移動または名前の変更

ページを移動または改名する場合は、古いURLやブックマークが引き続き機能するよう、必ず古いパスから新しいパスへのリダイレクトを追加してください。ほかのページの内部リンクと、docs.jsonのナビゲーションにあるスラッグも更新してください。

docs.jsonのredirects配列にリダイレクトを追加します。

{
  "redirects": [
    { "source": "/old-page", "destination": "/new-page" },
    { "source": "/guides/setup", "destination": "/docs/setup", "permanent": true },
    // wildcard: redirect a whole moved folder (:splat = matched suffix)
    { "source": "/v1/*", "destination": "/v2/:splat" }
  ]
}

sourceとdestinationは絶対パスです（先頭に/を付け、拡張子は付けません）。301リダイレクトを設定する場合は"permanent": trueを追加します（デフォルトは302です）。詳しくは、完全なリファレンス（https://holocron.so/docs/create/redirects.md）を参照してください。

新しいページとナビゲーション

新しい.mdxまたは.mdページを作成したら、そのスラッグをdocs.jsoncのナビゲーションに追加してください。ナビゲーションツリーにないページはサイドバーに表示されず、404を返します。

まず既存のナビゲーション構造を確認し、最適なタブ、グループ、閲覧順序にページを配置してください。

法務およびサポートのページ：非表示のグループとフッター

プライバシーポリシー、利用規約、サポートなどのページは、読者にとって重要なページではありません。サイドバーには絶対に表示しないでください。"hidden": trueを指定したグループに入れ（引き続き配信およびインデックス登録されます）、footer.linksからリンクしてください。

{
  "navigation": {
    "groups": [
      // ...real docs groups
      {
        "group": "Legal",
        "hidden": true,
        "pages": ["docs/privacy", "docs/terms", "docs/support"]
      }
    ]
  },
  "footer": {
    "links": [
      {
        "header": "Legal",
        "items": [
          { "label": "Privacy", "href": "/docs/privacy" },
          { "label": "Terms", "href": "/docs/terms" },
          { "label": "Support", "href": "/docs/support" }
        ]
      }
    ]
  }
}

ページのフロントマターでhidden: trueを指定するのではなく、グループのhiddenフラグを使用してください。フロントマターでhiddenを指定すると、noindexも追加されます。アプリストアやOAuthの同意画面では標準的な短いパス（/privacy、/terms、/support）が求められることが多いため、そこからの"redirects"を"permanent": trueで追加してください。

新しいコンテンツの追加先

実際のドキュメントは website/src/pages/docs/ にあります。example/src/ ではありません。example/ フォルダーはデモ用のフィクスチャであり、公開されるドキュメントサイトではありません。

ドキュメントのコンテンツを追加または編集する前に、必ず最初に website/docs.json を読み、 ナビゲーションツリー全体と既存のページを確認してください。そのうえで、次の点を判断します。

1. このトピックを扱っている既存のページはありますか？ある場合は、そこにセクションを追加します。
2. このトピックは独立したページにするほど明確に異なりますか？該当する場合は、新しい .mdx ファイルを作成し、 website/docs.json の最適なグループに追加します。

最後に開いていたファイルだからという理由だけで、無関係なセクションをページに追加しないでください。 トピックに合ったページを選ぶか、新しいページを作成してください。

フィードバックループ

MDX ページ、docs.json のナビゲーション、またはフロントマターを編集した後は、問題を早期に発見できるよう、 必ずサイトをビルドしてください。ビルドでは、開発サーバーではページにアクセスするまで表示されない可能性がある、 内部リンク切れ、MDX の解析エラー、ナビゲーションで参照されているページの欠落、レンダリングの問題を検出できます。

pnpm build

変更を完了とする前に、警告やエラーをすべて修正してください。よくある問題は次のとおりです。

• リンク切れ — ナビゲーションに存在しないスラッグを指す内部リンク [link](/some-page)。
• MDX の解析エラー — JSX の形式不備、タグの閉じ忘れ、またはフロントマターの YAML が無効。
• ページの欠落 — docs.json のナビゲーションに記載されたスラッグに対応する .mdx ファイルがない。
• レンダリングエラー — コンポーネントの誤った使用（例：プロパティの誤り、子要素の欠落）。

ビルドで、実行時には存在するものの MDX ページではないパス（API ルート、ドキュメントと並行してマウントされている外部アプリ、ダッシュボードページ）へのリンクに関する警告が出る場合は、 docs.json の knownPaths フィールドを使ってそれらの警告を抑制してください。詳細は前述の リンク切れの検出セクションを参照してください。

CLI の概要

利用可能なコマンドをすべて確認するには、--help を実行してください。出力を省略してはいけません。

npx -y "@holocron.so/cli" --help

主なコマンド：login、logout、whoami、deploy、projects list、 projects create、keys list、keys create、keys delete、create。

ログインする前に、ユーザーがすでに認証済みかどうかを必ず確認してください。

npx -y "@holocron.so/cli" whoami

whoami が成功し、ユーザー、組織、プロジェクトが表示された場合は、ログインをスキップします。 whoami が失敗した場合に限り、npx -y "@holocron.so/cli" login を実行してください。

デプロイ

ユーザーが「サイトをデプロイして」と依頼した場合、holocron deploy ではなく、ユーザー独自の スクリプトやプラットフォーム（Cloudflare Workers、Node サーバー、CI パイプライン）を使ったデプロイを 指している可能性があります。まず package.json のスクリプトを確認してください。deploy、deployment、 または同様のスクリプト（例：wrangler deploy）がある場合は、Holocron CLI ではなく、そのスクリプトを使用します。 holocron deploy を使用するのは、プロジェクトに独自のデプロイスクリプトがない場合、またはユーザーが holocron.so でのホスティングを明示的に依頼した場合に限ります。

holocron deploy はドキュメントサイトをビルドし、holocron.so のホスティングにアップロードします。 独自のサーバーを管理せずに公開する最も速い方法です。

npx -y "@holocron.so/cli" deploy

このコマンドはビルドを実行し、変更されたファイルだけをアップロードして、デプロイを完了し、 公開 URL を出力します。アカウントに複数のプロジェクトがあり、セッション認証を使用している場合は、 --project prj_xxx を使用してください。プレビューのデプロイでブランチの検出を上書きするには、 --branch <name> を使用してください。

認証の優先順位： HOLOCRON_KEY 環境変数 > holocron login のセッショントークン > GitHub Actions OIDC トークン（id-token: write を設定した GitHub Actions で自動的に使用）。

デプロイ URL、GitHub Actions OIDC の設定、組織／プロジェクトの解決を含む全リファレンスは、 https://holocron.so/docs/deploy/holocron.md を参照してください。

本番環境の前に、必ずプレビュー環境へデプロイしてください。プレビューが失敗した場合は中止してください。

アイコンの一貫性

docs.json または MDX のフロントマターにアイコンを追加するときは、同じ階層にあるすべての兄弟要素で一貫して使用してください。アイコンの使い方に一貫性がないと、未完成に見え、視覚的なリズムが崩れます。

ルール：

• タブ：1つのタブにアイコンがある場合は、すべてのタブにアイコンを付けてください。
• グループ：サイドバーのグループにアイコンがある場合は、同じタブ内のすべての兄弟グループにもアイコンを付けてください。
• アンカー：navigation.global.anchors のアンカーにアイコンがある場合は、すべてのアンカーにアイコンを付けてください。
• ページ：グループ内のページにフロントマターの icon がある場合は、そのグループ内のすべてのページにアイコンを付けてください。例外：ページが1〜2ページだけのグループで、アイコンを付けてもナビゲーション上の価値がない場合。
• カード／CardGroup：<CardGroup> 内の <Card> に icon プロパティがある場合は、そのグループ内のすべてのカードに付けてください。
• Accordion／AccordionGroup：同じルールが適用されます。すべての項目にアイコンを付けるか、どの項目にも付けないでください。

ナビゲーションや MDX コンテンツを確認または作成するときは、兄弟要素を確認し、仕上げる前に不足しているアイコンを補ってください。同じライブラリ（通常は Lucide）からアイコンを選び、各項目には意味の異なるアイコンを割り当ててください。

MDX ページのライティングスタイル

見つけやすさを高めるため、キーワードを太字にする

各セクションと各段落には、少なくとも1つの太字のキーワードまたはフレーズを含めてください。読者はドキュメントのページをざっと読み、すべての言葉を読むわけではありません。太字のテキストは、目を relevant な段落へ誘導する目印になります。

要点を捉えた単語やフレーズを選んでください。文全体や、汎用的で内容のない言葉を太字にしないでください。読者が目を通すであろう、具体的な用語、API 名、または概念を太字にしてください。

補足情報には Aside を頻繁に使う

補足情報を右側のサイドバー列に配置するには、<Aside> を頻繁に使ってください。Aside は1列のテキストが続く単調さを崩し、関連する箇所に文脈に沿った注記を配置できます。Aside がまったくないページは平坦に見え、レイアウトを十分に活用できていません。

Aside に適した内容：

• ヒントや注意点：現在のセクションに関連するものの、本文の説明には含まれない内容
• バージョンに関する注記や互換性に関する警告
• 関連ページまたは外部の参考情報へのリンク
• 短いコードスニペット：別のアプローチや特殊なケースを示すもの
• 定義や補足説明：本文で紹介した用語に関するもの

Aside の内容は必ず、枠付きのコンポーネント（Note、Tip、Info、Warning、Callout）で囲んでください。

## Authentication

The deploy command authenticates via **GitHub Actions OIDC** when running in CI.

<Aside>
<Info>
If OIDC is not available, fall back to a **`HOLOCRON_KEY`** environment variable
or a session token from `holocron login`.
</Info>
</Aside>

主要なセクション（## 見出しごと）につき、おおよそ1つの Aside を目安にしてください。すべてのセクションに必要なわけではありませんが、ページに ## セクションが3つ以上あり、Aside が1つもない場合は、追加できる箇所がないか検討してください。

短いセクションでは Aside を避けてください。 全幅ではない Aside は、そのセクション（2つの見出しの間のテキスト）と縦方向のスペースを共有します。Aside の吹き出しがセクション本文よりも高さがあると、本文の下に空白が生じます。Aside は、その高さに見合う、またはそれ以上の本文があるセクションにだけ追加してください。Aside の吹き出しは簡潔に（1〜2文）してください。

アーキテクチャやフローの説明には図を使う

MDX ページでは ASCII 図を頻繁に使ってください。コードフェンスには必ず diagram の言語ヒントを付けてください。Holocron は diagram フェンスを特別なスタイルで描画します。Unicode の罫線文字や矢印は、ラベルとは異なる色で表示されます。

レイアウトのルール：

• 図は、コンテンツ列の幅いっぱい（およそ 94文字）を使うようにしてください。
• 1行の文字数は94文字を超えないでください。
• 変化に富んだ自然なレイアウトを優先してください。通常のテキストラベル、主要なコンポーネントを示すボックス、方向を示す矢印を組み合わせます。
• すべての接続には方向を示す矢印を使ってください。矢印の先端がない単なる線は使わないでください。
• npx -y "@holocron.so/cli" diagrams fix <file> を実行して配置を確認してください（下記の専用セクションを参照）。

```diagram
                ┌───────────────┐
docs.jsonc ───►│  Vite Plugin  │──────► Build Output
               └───────┬───────┘
                       │
               ┌───────▼───────┐
               │   sync.ts     │  MDX files ──► parsed sections
               │  (walk nav)   │  git SHA diff ──► cache hit/miss
               └───────┬───────┘
                       │
        ┌──────────────┼──────────────┐
        ▼              ▼              ▼
    navigation    page cache    virtual modules
    tree.json     holocron-mdx   holocron-pages
                  holocron-config holocron-config
```

図や表を編集した後は、必ず diagrams fix を実行してください

LLM は文字数を数えたり、表の列幅を確実に調整したりできません。MDX ページで図またはGFM テーブルを作成または編集するたびに、コミット前に必ず修正ツールを実行してください。これは必須です。

npx -y "@holocron.so/cli" diagrams fix path/to/file.mdx

このコマンドは次の処理を行います。

• ボックス罫線図の配置（パディング、枠線の幅、接続部分）をその場で修正します
• GFM テーブルをフォーマットします（列のパディング、パイプの位置合わせ、前後の空行）
• 変更された行数を報告します
• 図の行が最大幅（デフォルトでは94列）を超えている場合、またはテーブルのフォーマットがまだ必要な場合（--check）、終了コード1で終了します

出力に「No changes」と表示された場合、ファイルはすでに正しい状態です。幅の違反が報告された場合は、該当する図の行を手動で短くしてから、再実行してください。

この手順を省略しないでください。 エディター上で図や表が問題なく見えても、コマンドを実行してください。1文字分のパディングのずれや表の列幅の不均一さは、LLM には分かりませんが、等幅フォントでは人には明らかです。

OpenAPI の概要

OpenAPI の操作 summary フィールドは、サイドバーのタイトルになります。サイドバーの幅は230pxしかないため、概要は短くしてください。2〜3語、できれば20文字未満が目安です。ページの sidebarTitle フィールドと同じ簡潔なスタイルを使用してください。

• 動詞＋名詞のパターンにします：List users、Create order、Get me、Upload files。
• 修飾語、括弧書き、実装の詳細は省きます。Upload deployment files (zip batch) は Upload files にします。
• 概要でタグやグループ名を繰り返さないでください。タグが Deploy の場合、概要を「Deploy」で始めてはいけません。
• 230px幅のサイドバーラベルとして読みやすければ、十分に短いと言えます。

Bleed — コンテンツを本文カラムの外側まで広げる

YouTube の埋め込み、動画、大きな画像は、必ず <div className='bleed'> で囲み、 狭い本文幅に収めず、ページの左右の余白にまで広がるようにしてください。 <Frame> も className='bleed' を受け付けます。Callout、Card、Accordion などのコンテナは、 フレーム内に子要素を収めるため、no-bleed を自動的に適用します。

詳しくは https://holocron.so/docs/customize/bleed.md をご覧ください。

カスタム CSS — クラスセレクターより CSS 変数を優先する

Holocron サイトの見た目をカスタマイズする場合は、内部クラス名、DOM 構造、aria ラベルを対象にするのではなく、:root で CSS 変数をオーバーライドしてください。Holocron は、色、タイポグラフィ、間隔、コードブロック、引用、サイドバーのナビゲーションに関する、ドキュメント化された CSS 変数を公開しています。これらは Holocron のアップデート後も安定していますが、内部マークアップは変更される可能性があります。

/* style.css */
:root {
  --weight-heading: 700;
  --code-block-background: var(--muted);
  --code-block-border: 1px solid var(--border-subtle);
  --sidebar-link-radius: var(--radius-sm);
  --blockquote-border-color: var(--border-subtle);
}

利用可能なトークンの一覧を取得します。

curl -fsSL https://holocron.so/docs/customize/theme.md

CSS 変数が用意されていない項目のカスタマイズをユーザーが希望する場合、壊れやすいセレクターで無理に実現しないでください。代わりに、その用途向けの新しい CSS 変数をリクエストする Issue を Holocron リポジトリ（https://github.com/remorses/holocron/issues）で作成してください。Holocron はユーザーのニーズに応じて、新しい変数を積極的に追加しています。.slot-sidebar-left nav > div:first-child > a や figure[class~='group/code'] button[aria-label='Copy code'] のような内部セレクターは、リファクタリングのたびに壊れるため、決して使用しないでください。

エージェントのルール

• MDX ページは必ず Holocron の pagesDir 内に配置してください。 ドキュメントページを作成または編集する前に、プロジェクトの vite.config.ts（または vite.config.mts）を読み、Holocron プラグインに渡される pagesDir オプションを確認してください。pagesDir が設定されていない場合は、プロジェクトのルートがデフォルトになります。すべての .mdx および .md ページファイルはこのディレクトリ内に置く必要があります。ディレクトリ外のファイルはナビゲーションにもビルドにも表示されません。
• 以前のセッションで記憶した内容より、最新の取得済みドキュメントを優先してください。
• エージェントがドキュメント全体を取得する前でも確認できるよう、ルールに関わるプロジェクトの動作はこのスキルに記載してください。
• MDX ページ内の ASCII 図には、コードフェンスで必ず diagram 言語ヒント（```diagram）を指定してください。これにより、ウェブサイト上で通常の等幅フォントではなく、適切なスタイルで表示されます。
• 図または GFM テーブルを作成または編集した後は、配置とテーブル列のパディングを自動修正するため、npx -y "@holocron.so/cli" diagrams fix <file> を実行してください。LLM は文字数を数えたり、列のパディングを適切に調整したりできません。
• curl または --help の出力を head、tail、その他の切り詰めコマンドにパイプしないでください。必ず出力全体を読んでください。