Skip to content

サポートサイトのレイアウト刷新と補足情報の追記 #22

Closed
#23
Closed
サポートサイトのレイアウト刷新と補足情報の追記#22
#23
@laiso

Description

@laiso
laiso
opened on Apr 11, 2026

workspace/docs/index.html を更新してください。技術文書として読みやすい構造に刷新すると同時に、補足情報を新規項目を含めて計 7 項目に拡充します。

対象ファイル

  • workspace/docs/index.html

レイアウト要件

全体構成

  1. ヘッダー: 書影（80〜100px のサムネイル）、タイトル、技術評論社書籍ページへのリンク。既存の .hero グリッドは維持しつつ padding を 28px から 20px に縮小し、h1 のサイズは clamp(1.5rem, 3vw, 2.2rem) に調整する。
  2. コンテンツ領域: 左サイドバー（目次）と右メイン（補足情報本文）の 2 カラム。widescreen で grid-template-columns: 240px minmax(0, 1fr)。820px 以下では 1 カラムに折り畳み、サイドバーは上部に配置する。
  3. フッター: 既存の ISBN 表記、技術評論社リンク、構築者の注釈をそのまま維持する。

サイドバー目次の構造

<aside class="toc">
  <h2>補足情報</h2>
  <nav>
    <h3>第 2 章</h3>
    <ul>
      <li><a href="#ch02-env-gemini">環境変数 GEMINI_API_KEY</a></li>
    </ul>
    <h3>第 3 章</h3>
    <ul>
      <li><a href="#ch03-3-llm-api-error">3.3 節 LLMApiError のコンストラクタ引数</a></li>
    </ul>
    <h3>第 4 章</h3>
    <ul>
      <li><a href="#ch04-6-tools-demo-filename">4.6 節 ツール動作確認スクリプトのファイル名</a></li>
    </ul>
    <h3>第 7 章</h3>
    <ul>
      <li><a href="#ch07-2-variables">7.2 節 Variables の設定</a></li>
      <li><a href="#ch07-4-pr-permission">7.4 節 PR 作成の権限設定</a></li>
      <li><a href="#ch07-7-issue-text">7.7 節 ISSUE_TEXT の埋め込み</a></li>
    </ul>
    <h3>第 8 章</h3>
    <ul>
      <li><a href="#ch08-3-bubblewrap-sys-admin">8.3 節 bubblewrap と SYS_ADMIN 権限</a></li>
    </ul>
  </nav>
</aside>

aside.toc には position: sticky; top: 24px; align-self: start; を設定してスクロールに追従させます。

補足項目の構造

各補足項目は次の構造で記述します。

<article id="{anchor-id}">
  <header>
    <span class="chapter-label">{章節ラベル}</span>
    <h3>{タイトル}</h3>
    <a class="anchor" href="#{anchor-id}">#</a>
  </header>
  <dl>
    <dt>本書の記載</dt>
    <dd>...</dd>
    <dt>症状</dt>
    <dd>...</dd>
    <dt>対処</dt>
    <dd>...</dd>
  </dl>
</article>
  • 各 <article> に一意な id を設定し、アンカーリンクで直接参照できるようにする。
  • ファイルパス・関数名・環境変数名・コマンドは <code> で、複数行のコードは <pre><code> で表示する。
  • 章ごとに <section class="chapter-group"> でまとめ、その先頭に <h2>第 N 章</h2> を置く。

CSS の要件

既存の色パレット（--accent: #0066cc、--accent-soft: #e6f0ff、--surface: #f8fbff 等）と system-ui ベースのフォントはそのまま利用します。以下の CSS を追加してください。

.layout {
  display: grid;
  grid-template-columns: 240px minmax(0, 1fr);
  gap: 40px;
  margin-top: 28px;
}
.toc {
  position: sticky;
  top: 24px;
  align-self: start;
}
.toc h2 {
  font-size: 1rem;
  margin: 0 0 8px;
  color: var(--accent);
}
.toc h3 {
  margin: 16px 0 4px;
  font-size: 0.85rem;
  color: var(--muted);
  text-transform: uppercase;
  letter-spacing: 0.05em;
}
.toc ul {
  list-style: none;
  padding: 0;
  margin: 0;
}
.toc a {
  display: block;
  padding: 6px 10px;
  border-radius: 6px;
  color: var(--text);
  text-decoration: none;
  font-size: 0.9rem;
  line-height: 1.5;
}
.toc a:hover {
  background: var(--accent-soft);
  color: var(--accent);
}

.chapter-group {
  margin-bottom: 32px;
}
.chapter-group > h2 {
  margin: 0 0 16px;
  padding-bottom: 8px;
  border-bottom: 2px solid var(--border);
}

article {
  padding: 20px 24px;
  border: 1px solid var(--border);
  border-radius: 12px;
  background: var(--surface);
  margin-bottom: 16px;
}
article > header {
  display: flex;
  align-items: center;
  gap: 12px;
  margin-bottom: 12px;
}
article h3 {
  margin: 0;
  font-size: 1.1rem;
  flex: 1;
}
.chapter-label {
  display: inline-block;
  font-size: 0.75rem;
  font-weight: 700;
  color: var(--accent);
  background: var(--accent-soft);
  padding: 2px 10px;
  border-radius: 999px;
  letter-spacing: 0.04em;
}
.anchor {
  opacity: 0;
  color: var(--muted);
  text-decoration: none;
  font-weight: 700;
}
article:hover .anchor {
  opacity: 1;
}

dl {
  display: grid;
  grid-template-columns: 7em 1fr;
  gap: 8px 16px;
  margin: 0;
}
dt {
  color: var(--muted);
  font-weight: 600;
  font-size: 0.9rem;
  padding-top: 2px;
}
dd {
  margin: 0;
}

code {
  background: #f3f6fb;
  padding: 2px 6px;
  border-radius: 4px;
  font-size: 0.92em;
  font-family: ui-monospace, "SFMono-Regular", Consolas, monospace;
}
pre {
  background: #0f172a;
  color: #e2e8f0;
  padding: 14px 16px;
  border-radius: 8px;
  overflow-x: auto;
  margin: 8px 0 0;
}
pre code {
  background: transparent;
  color: inherit;
  padding: 0;
  font-size: 0.88em;
}

@media (max-width: 820px) {
  .layout {
    grid-template-columns: 1fr;
  }
  .toc {
    position: static;
  }
}

掲載する補足情報（計 7 項目）

各項目は上記の <article> 構造に沿って記述します。本文の文言は以下をそのまま使用してください。

第 2 章

ch02-env-gemini — 環境変数 GEMINI_API_KEY

  • chapter-label: 第 2 章
  • h3: 環境変数 GEMINI_API_KEY

本書の記載: 第 2 章の .env 例に GOOGLE_API_KEY=AI... が記載されています。第 6 章の createModelFromEnv の実装でも process.env.GOOGLE_API_KEY を参照する形で説明されています。

症状: @google/genai SDK が参照する標準の環境変数名は GEMINI_API_KEY です。GOOGLE_API_KEY だけを設定した場合、SDK からは空と判定されます。

対処: .env には GEMINI_API_KEY を設定します。本リポジトリの src/providers/google.ts は GEMINI_API_KEY ?? GOOGLE_API_KEY のフォールバックを備えているため両方の環境変数名を受け付けますが、新規設定では GEMINI_API_KEY を使用してください。

GEMINI_API_KEY=AI...

第 3 章

ch03-3-llm-api-error — 3.3 節 LLMApiError のコンストラクタ引数

  • chapter-label: 3.3 節
  • h3: LLMApiError のコンストラクタ引数

本書の記載: OpenAI プロバイダーの例で次の呼び出しが記載されています。

throw new LLMApiError('APIからの応答がありません');

症状: LLMApiError クラスの定義では第 1 引数が status: number、第 2 引数が provider: string で、文字列 1 つだけを渡す呼び出しは型エラーになります。

対処: 多引数形式で呼び出します。

throw new LLMApiError(500, 'openai', undefined, 'APIからの応答がありません');

第 4 章

ch04-6-tools-demo-filename — 4.6 節 ツール動作確認スクリプトのファイル名

  • chapter-label: 4.6 節
  • h3: ツール動作確認スクリプトのファイル名

本書の記載: コード例のコメントに // chapters/04-tools-demo.ts とあり、実行コマンドの例は bun run chapters/04-demo-tools.ts と記載されています。

症状: 実行コマンドのファイル名がコード例と一致していないため、記載どおりに実行するとファイルが見つからずエラーになります。

対処: 正しいファイル名は 04-tools-demo.ts です。次のコマンドで実行してください。

bun run chapters/04-tools-demo.ts

第 7 章

ch07-2-variables — 7.2 節 Variables の設定

  • chapter-label: 7.2 節
  • h3: Variables の設定

本書の記載: gh variable set による LLM_PROVIDER と LLM_MODEL の登録手順が記載されています。

症状: Variables が未登録の場合、ワークフロー実行時にこれらの環境変数が空となり、bin/cli.ts 起動時に「LLM設定が不足しています」のエラーで終了します。Secrets の LLM_API_KEY とは別に Variables として登録する必要があります。

対処: 次のコマンドで Variables を登録します。登録状況は gh variable list で確認できます。

gh variable set LLM_PROVIDER --body "openai"
gh variable set LLM_MODEL --body "gpt-5-mini"

ch07-4-pr-permission — 7.4 節 PR 作成の権限設定

  • chapter-label: 7.4 節
  • h3: PR 作成の権限設定

本書の記載: 7.4 節でワークフロー権限 pull-requests: write の設定手順が記載されています。

症状: ワークフロー権限だけではプルリクエストを作成できず、実行時に次のエラーで失敗します。

GitHub Actions is not permitted to create or approve pull requests

対処: リポジトリの Settings → Actions → General → Workflow permissions を開き、「Allow GitHub Actions to create and approve pull requests」にチェックを入れて Save してください。ワークフロー権限の設定と併用することで、プルリクエストの作成が許可されます。

ch07-7-issue-text — 7.7 節 ISSUE_TEXT の埋め込み

  • chapter-label: 7.7 節
  • h3: ISSUE_TEXT の埋め込み

本書の記載: ワークフロー YAML で ISSUE_TEXT 環境変数に Issue 本文を渡す設定が記載されています。

症状: bin/cli.ts の issueDrivenInstructions テンプレートが ISSUE_TEXT を参照しない構成の場合、エージェントは Issue タイトルしか認識できず、本文の詳細な指示に従えません。

対処: issueDrivenInstructions のテンプレートリテラル内で process.env.ISSUE_TEXT を取り込み、「## Issue本文（参照用）」の形で本文を埋め込みます。

const issueText = process.env.ISSUE_TEXT || '';
const issueDrivenInstructions = `${baseInstructions}

## Issue本文（参照用）
${issueText}
`;

第 8 章

ch08-3-bubblewrap-sys-admin — 8.3 節 bubblewrap と SYS_ADMIN 権限

  • chapter-label: 8.3 節
  • h3: bubblewrap と SYS_ADMIN 権限

本書の記載: bubblewrap の実行に --cap-add=SYS_ADMIN が必要と記載されています。

症状: 全ての環境でこのオプションが必須とは限りません。

対処: ホストのカーネル設定 kernel.unprivileged_userns_clone=1 が有効な環境では、--cap-add=SYS_ADMIN なしで bubblewrap を起動できる場合があります。実行環境のカーネル設定を確認のうえ、必要に応じてオプションを付与してください。

ヘッダーとフッター

  • ヘッダーは既存の書影・タイトル・技術評論社リンクを維持し、上記のとおりスリム化します。
  • フッターは現行どおり、ISBN、技術評論社書籍ページへのリンク、構築者の注釈を掲載します。

作業手順

作業完了後、createBranch でブランチを作成し、commitChanges でコミットし、pushBranch でプッシュし、createPullRequest でプルリクエストを作成してください。

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions