Skip to content

TODO.md

Latest commit

 

History

History
601 lines (420 loc) · 39.2 KB

TODO.md

File metadata and controls

601 lines (420 loc) · 39.2 KB
Raw

NotroTail ドキュメント敎備 TODO

調査日: 2026-03-20 10゚ヌゞェントによるコヌドベヌス・ビルド結果・Astro公匏サむト構造の䞊列調査結果をもずに䜜成。 前提: NotroTail はテンプレヌトずしお Vercel/Netlify ぞのデプロむを想定。notro・remark-nfm はオプション。

方針

察象オヌディ゚ンス2皮類

オヌディ゚ンス 目的 䞻な動線
テンプレヌト利甚者 NotroTail をクロヌンしお Notion ブログを立ち䞊げたい トップ → クむックスタヌト → デプロむ
パッケヌゞ利甚者 既存 Astro プロゞェクトに notro / remark-nfm を远加したい Docs → API リファレンス → npm

珟状の課題

  1. トップペヌゞ — デプロむ CTA がない。GitHub ずデモブログぞの誘導しかなく、テンプレヌトずしお䜿う入口がない。
  2. Docs ペヌゞ (/contact/) — "How this site is built" ずいう説明ペヌゞ止たり。クむックスタヌト・API リファレンス・デプロむガむドがない。
  3. チュヌトリアルがブログに埋もれおいる — 優良な入門蚘事setup, add-notro-to-astro 等がブログ䞀芧に䞊んでいお、孊習パスずしお機胜しおいない。
  4. notro がオプションであるこずが䌝わらない — テンプレヌトを Notion なしで䜿うパタヌンが瀺されおいない。
  5. テスト蚘事が本番衚瀺されおいる — test-callout-edge-cases, test-markdown-edge-cases がブログ䞀芧に出おいる。

1. トップペヌゞindex.astroの改善

1-1. ヒヌロヌセクション

  • 「Deploy to Vercel」「Deploy to Netlify」ボタンをヒヌロヌに远加
    • Vercel: [![Deploy with Vercel](...)](https://vercel.com/new/clone?...) スタむル
    • Netlify: [![Deploy to Netlify](...)](https://app.netlify.com/start/deploy?...) スタむル
  • CTAの重耇を解消 — ヒヌロヌず最終CTAで「GitHub」「デモブログ」が2回出おいる。ヒヌロヌはデプロむ重芖、最終CTAはGitHub重芖に圹割を分ける。
  • クむックスタヌトコマンドをテンプレヌト利甚者向けに倉曎
    • 珟状: npm install notroパッケヌゞ利甚者向け
    • 远加: Use this template → clone → deploy の3ステップ

1-2. 2぀の䜿い方を明瀺するセクションを远加

┌──────────────────────────┐  ┌──────────────────────────┐
│  テンプレヌトずしお䜿う     │  │  npm パッケヌゞずしお䜿う  │
│  Notion ブログを5分で     │  │  既存 Astro プロゞェクトに │
│  Vercel/Netlify にデプロむ│  │  notro を远加する         │
└──────────────────────────┘  └──────────────────────────┘
  • notro・remark-nfm がオプションであるこずを「機胜」セクションで明蚘

1-3. 「3ステップ」セクションをテンプレヌト芖点に倉曎

珟圚: 「Notionで曞く → notroが倉換 → Astroが生成」パッケヌゞ利甚者芖点 倉曎埌: テンプレヌト利甚者向けの3ステップを远加たたは䞊蚘

  1. このリポゞトリをテンプレヌトずしお䜿うGitHub の "Use this template"
  2. Notion トヌクンずデヌタ゜ヌス ID を環境倉数に蚭定
  3. Vercel / Netlify にデプロむワンクリック

1-4. CTA「ブログを芋る」→「Docs を芋る」に倉曎

  • ヒヌロヌの「ブログを芋る →」ボタンを「ドキュメントを芋る →」/contact/に倉曎 ※ デモずしおのブログぞのリンクは残すセカンダリボタン

2. Docs ペヌゞ/contact/の敎備

2-1. ペヌゞ党䜓の再構成

contact.astro を Docs ハブずしお再構成。珟圚の「3ペヌゞ皮類の説明 + パむプラむン説明」は「サむトの仕組み」セクションずしお残し぀぀、以䞋を远加:

  • クむックスタヌトセクションテンプレヌト利甚者向け

    1. リポゞトリをクロヌン / GitHub の "Use this template" で䜜成
2. npm installルヌトで実行
3. .env に NOTION_TOKEN, NOTION_DATASOURCE_ID を蚭定
4. npm run devlocalhost:4321 で確認
5. Vercel / Netlify にデプロむ

  • Notion セットアップガむド

    • Notion むンテグレヌション䜜成手順notion.so/my-integrations ぞのリンク
    • デヌタ゜ヌス ID の取埗方法URL から抜出
    • デヌタベヌススキヌマ必須プロパティ䞀芧
    プロパティ 型 必須 説明
    Name title ✓ 蚘事タむトル
    Slug rich_text ✓ URL スラッグ
    Public checkbox ✓ 公開フラグ
    Description rich_text — 説明文・meta description
    Tags multi_select — タグpage/pinned は内郚マヌカヌ
    Date date — 公開日

  • 環境倉数リファレンステヌブル

    倉数 必須 説明
    NOTION_TOKEN ✓ Notion Internal Integration Token
    NOTION_DATASOURCE_ID ✓ Notion デヌタ゜ヌス IDDB ID

  • Vercel / Netlify デプロむガむド

    • Vercel: vercel.json が templates/blog/dist を自動蚭定
    • Netlify: netlify.toml が蚭定枈みのためそのたたデプロむ可
    • 環境倉数の蚭定箇所各ダッシュボヌドのスクリヌンショット or リンク

  • notro パッケヌゞ API リファレンスセクション

    • 3぀の゚ントリヌポむントnotro, notro/utils, notro/integration
    • loader() オプションqueryParameters, clientOptions
    • NotroContent propsmarkdown, linkToPages, classMap, components
    • classMap キヌ䞀芧callout, toggle, h1–h4, p, ul, ol, li, a, pre, table, etc.

  • remark-nfm スタンドアロン利甚セクション

    • import { remarkNfm } from 'remark-nfm' の基本䜿甚䟋
    • 修正 Fix 0〜9 の簡易衚

  • チュヌトリアルぞの誘導リスト

    📖 チュヌトリアルブログ蚘事
├── セットアップガむド              → /blog/setup/
├── 既存 Astro プロゞェクトぞの远加  → /blog/add-notro-to-astro/
├── Notion でのコンテンツ管理        → /blog/content-management/
├── ビルドずデプロむ                → /blog/build-and-deploy/
└── コンポヌネントのカスタマむズ     → /blog/customize-components/

  • トラブルシュヌティングセクション

    • truncated === true の察凊倧きなペヌゞを分割
    • unknown_block_ids の意味Notion API が倉換できなかったブロック
    • Notion API レヌト制限429ぞの察応自動リトラむあり
    • 画像が衚瀺されないS3 プリサむン URL の有効期限切れ → 再ビルド

2-2. URL のリネヌム怜蚎

  • /contact/ → /docs/ ぞのリネヌムを怜蚎ファむル名が実䜓ず乖離しおいる
    • src/pages/contact.astro → src/pages/docs.astro
    • astro.config.mjs に redirects: { '/contact/': '/docs/' } を远加埌方互換
    • Header・Footer のリンク先を曎新

3. チュヌトリアルブログ蚘事の敎理

3-1. 既存蚘事マッピング

スラッグ タグ 孊習段階
setup セットアップ, 入門 ★ 入門1
add-notro-to-astro notro, Astro, 入門 ★ 入門2
content-management Notion, コンテンツ管理 ★★ 基瀎
build-and-deploy デプロむ, Netlify, Vercel ★★ 基瀎
customize-components カスタマむズ, Tailwind ★★★ 応甚
blocks — ★★★ リファレンス
test-callout-edge-cases test, callout テスト甚非公開掚奚
test-markdown-edge-cases test, edge-cases テスト甚非公開掚奚

3-2. テスト蚘事の非公開化Notion 偎操䜜

  • Notion で test-callout-edge-cases ず test-markdown-edge-cases の Public を false に倉曎 ※ コヌド倉曎䞍芁

3-3. ブログ䞀芧での「入門」蚘事の優遇

  • blog/[...page].astro で 入門 タグの蚘事を「ピン留め」同様に1ペヌゞ目䞊郚に衚瀺するか怜蚎
    • 珟状: ピン留めpinned タグず日付゜ヌトのみ
    • 案: 入門 タグ蚘事を「はじめおの方ぞ」セクションずしお固定衚瀺

3-4. 新芏蚘事の執筆Notion で䜜成

  • テンプレヌトのフォルダ構成ガむド — src/ 各ディレクトリの圹割説明タグ: 入門
  • remark-nfm スタンドアロン䜿甚ガむド — Astro なしで䜿いたい人向けタグ: remark-nfm
  • Notion ブロック察応状況リファレンス — blocks 蚘事を拡充しおコンポヌネント + CSS クラス䞀芧タグ: リファレンス

4. 内郚タグの仕様を README / Docs で明文化

  • page タグ — ブログ䞀芧・タグペヌゞ非衚瀺、日付/タグ/前埌ナビ非衚瀺。固定ペヌゞAbout, Privacy 等に䜿甚。
  • pinned タグ — ブログ䞀芧1ペヌゞ目の「ピン留め」セクションに衚瀺。通垞リストからは陀倖。
  • 入門 タグ — 入門者向け。チュヌトリアル序列の基準ずしお䜿甚。
  • 䞊蚘を content-management 蚘事 たたは Docs ペヌゞで明蚘

5. 技術的な実装タスク優先床順

# タスク ファむル 優先床
1 test蚘事を非公開Notion操䜜 Notion DB 🔎 即時
2 index.astro にデプロむボタン远加 src/pages/index.astro 🔎 高
3 index.astro のCTA重耇解消 + ボタン圹割敎理 src/pages/index.astro 🔎 高
4 Docs ペヌゞにクむックスタヌト远加 src/pages/contact.astro 🔎 高
5 Docs ペヌゞに Vercel/Netlify デプロむガむド远加 src/pages/contact.astro 🟠 äž­
6 Docs ペヌゞに Notion セットアップガむド远加 src/pages/contact.astro 🟠 äž­
7 Docs ペヌゞにチュヌトリアル誘導リスト远加 src/pages/contact.astro 🟠 äž­
8 Docs ペヌゞに API リファレンス远加 src/pages/contact.astro 🟠 äž­
9 Docs ペヌゞにトラブルシュヌティング远加 src/pages/contact.astro 🟡 䜎
10 /contact/ → /docs/ リネヌム + redirect astro.config.mjs, contact.astro 🟡 䜎
11 index.astro「ブログを芋る」→「Docs を芋る」に倉曎 src/pages/index.astro 🟡 䜎
12 ブログ䞀芧で「入門」蚘事を優先衚瀺 src/pages/blog/[...page].astro 🟡 䜎
13 OGP 画像og-default.pngをテンプレヌト向けに曎新 public/og-default.png 🟡 䜎

サむト党䜓の情報蚭蚈目暙

/                    トップ
                     └── テンプレヌトの䟡倀提案 + デプロむ CTAVercel/Netlify
                         2぀の䜿い方テンプレヌト / npm パッケヌゞ
                         3ステップテンプレヌト芖点+ 機胜䞀芧

/docs/               Docs珟圚の /contact/
                     ├── クむックスタヌト5分でデプロむ
                     ├── Notion セットアップ
                     ├── 環境倉数
                     ├── デプロむガむドVercel / Netlify
                     ├── API リファレンスloader, Renderer, classMap
                     ├── remark-nfm スタンドアロン
                     ├── チュヌトリアル䞀芧→ /blog/
                     ├── サむトの仕組み珟圚の内容
                     └── トラブルシュヌティング

/blog/               ブログNotion 管理
                     ├── 入門蚘事setup, add-notro-to-astro, ...
                     ├── 基瀎・応甚蚘事
                     └── リファレンス蚘事blocks, ...

/blog/about/         AboutNotion 管理、page タグ
/blog/privacy/       プラむバシヌポリシヌNotion 管理、page タグ
/404                 404 ペヌゞ

templates/blog × packages/ モノレポ利甚の改善案

調査日: 2026-04-16 templates/blog が packages/ 配例 (notro-loader / notro-ui / rehype-beautiful-mermaid / remark-nfm / create-notro) をどう䜿っおいるかを確認し、改善ポむントを抜出。

芁玄

  • import ゚ントリポむントの䜿い分けが䞍培底で、玔粋 TS ヘルパヌたで notro-loader メむンから匕っ匵っおおり、Astro コンポヌネント䞀匏が䞍芁な経路にも巻き蟌たれおいる。
  • notro-ui の CLI (notro-ui init/add/update) 前提のワヌクフロヌに察し、テンプレヌト偎に notro.json が無く、䞊流の曎新を取り蟌む運甚経路が閉じおいる。
  • notro-theme.css ず packages/notro-ui/src/templates/theme.css がドリフトしおおり、どちらが source of truth か曖昧。
  • その他、CLAUDE.md のガむドずの敎合性に欠ける箇所が散芋<script> 内ロゞックの未抜出、@/* ゚むリアス䞍圚、ドキュメント蚘茉ず実装の乖離。

1. notro-loader の import ゚ントリ誀甚優先床: 🔎 高

玔粋 TS ナヌティリティ (getPlainText / getMultiSelect / hasTag / buildLinkToPages) は notro-loader/utils から import するのが正解だが、以䞋の箇所ではメむン゚ントリ (notro-loader) から読んでいる。メむン゚ントリは NotroContent.astro を含むため、利甚しない経路たで Astro コンポヌネントのロヌドパスに乗っおしたう。

ファむル 珟状 修正案
src/pages/rss.xml.ts:4 import { getPlainText, hasTag } from "notro-loader"; "notro-loader/utils" ぞ倉曎
src/pages/blog/[...page].astro:4 import { hasTag } from "notro-loader"; "notro-loader/utils" ぞ倉曎
src/pages/blog/tag/[tag]/[...page].astro:4 import { hasTag } from "notro-loader"; "notro-loader/utils" ぞ倉曎
src/pages/blog/[slug].astro:3 buildLinkToPages, getPlainText, hasTag, NotroContent を混圚 NotroContent のみ "notro-loader"、残りは "notro-loader/utils" に分離
src/components/blog/PostCard.astro:3 getPlainText, getMultiSelect from "notro-loader" "notro-loader/utils" ぞ倉曎
  • 䞊蚘 5 箇所を notro-loader/utils 経由に曞き換え
  • src/lib/blog.ts は既に notro-loader/utils を䜿えおいるただし 4 行目で PropertyPageObjectResponseType を notro-loader から type-only import しおいる。import type にすれば実行時圱響はない。珟状 import type 指定なしなので芁確認

2. notro-ui CLI 利甚基盀の敎備優先床: 🔎 高

CLAUDE.md では notro-ui の運甚は notro-ui init → notro.json 生成 → add/update/remove ずいう CLI ベヌスずされおいるが、

  • templates/blog/notro.json が 存圚しないtemplates/blank/ も同様
  • src/components/notro/ 配䞋はすでに 28 個の .astro + colors.ts + index.ts を抱えおいるが、notro-ui update --all の流入経路が無い

結果ずしお、packages/notro-ui/src/templates/ (source of truth) ぞの修正がテンプレヌトぞ自動的に反映されない。

  • templates/blog/ ず templates/blank/ で notro-ui init 盞圓の notro.json を生成しおコミット
    • outDir, stylesDir, installed components list を定矩
  • src/components/notro/index.ts に残っおいる「Site-customized components (differ from notro-ui defaults)」コメントを、notro.json 偎の「update 陀倖リスト」or 各 .astro 先頭の // notro-ui: customized マヌカヌずしお圢匏化する。CLI が差分を刀別できるようにする。

3. notro-theme.css ず packages/notro-ui/src/templates/theme.css のドリフト優先床: 🟠 䞭

diff 結果:

  • templates/blog/src/styles/notro-theme.css はタスクリスト関連の CSS が @utility 局111–127 行に眮かれおおり、コメントで「cascade precedence の説明」が远蚘されおいる。
  • packages/notro-ui/src/templates/theme.css (source of truth) ではタスクリストが別の䜍眮182–192 行に眮かれ、コメントも簡玠。

どちらが最新の意図かを決めずに差分が残っおいる。

  • source of truth を packages/notro-ui/src/templates/theme.css ず定め、ブログ偎の修正タスクリストの cascade 問題の fixを䞊流に取り蟌む
  • 取り蟌み埌、notro-ui update --all --yes 盞圓の操䜜で䞋流を同期notro.json 敎備埌に可胜
  • 取り蟌み察象の差分:
    • タスクリスト芏則の @utility 局配眮
    • .notro-markdown .contains-task-list / .task-list-item / input[type=checkbox] のセレクタ詳现床に関するコメント

4. package.json 䟝存関係の点怜優先床: 🟠 䞭

templates/blog/package.json:

"notro-loader": "^0.0.3",
"rehype-beautiful-mermaid": "^0.0.2",
"beautiful-mermaid": "^1.1.3",   ← ?
...
  • beautiful-mermaid の必芁性: rehype-beautiful-mermaid の peerDep ではない可胜性がある未確認。盎接 import しおいる箇所が無ければ削陀。
  • remark-nfm の扱い: 珟状 remarkPlugins に远加する圢で独立利甚しおいないので notro-loader 掚移䟝存のたたで OK。ただし CLAUDE.md の蚘茉通り preprocessNotionMarkdown 等を盎接呌ぶ堎合は packages/remark-nfm を dependencies に昇栌させる必芁がある。芁刀断。
  • ルヌト pnpm.overrides による workspace 匷制: 意図は「テンプレヌトは公開版指定のたた、モノレポ開発時は workspace:* に解決」で合理的。ただし notro-ui・remark-nfm・create-notro は overrides に入っおいない。必芁に応じお拡匵を怜蚎。

5. CLAUDE.md 蚘茉ずの乖離優先床: 🟡 䜎

  • notro-loader のコンポヌネント: CLAUDE.md は components/ (NotroContent, DatabaseCover, DatabaseProperty) ず曞いおいるが、実装は packages/notro-loader/src/components/NotroContent.astro のみ。DatabaseCover は templates/blog/src/components/blog/DatabaseCover.astro にテンプレヌト偎で自前実装。
  • CLAUDE.md の該圓蚘述を「NotroContent のみ」に蚂正、たたは notro-loader 偎に DatabaseCover / DatabaseProperty を埩掻させるどちらを source にするかを決める。
  • @/* path alias: src/components/notro/index.ts:6 のコメント䟋に import { notroComponents } from '@/components/notro'; ずあるが、tsconfig.json に paths が未定矩で、実際の import は党お盞察パス。
  • tsconfig.json に compilerOptions.baseUrl + paths: { "@/*": ["src/*"] } を远加しお統䞀するか、コメント偎を盞察パスに盎す。

6. Astro 実装ベストプラクティスCLAUDE.md §Astro Implementationずの敎合優先床: 🟡 䜎

  • Header.astro の <script> ロゞック未抜出: 89–102 行の DOM 操䜜 15 行。CLAUDE.md は「耇雑な堎合は src/lib/ に .ts ずしお抜出」ず芏定。
  • src/lib/header-menu.ts に initHeaderMenu() を切り出し、Header.astro からは import { initHeaderMenu } from "@/lib/header-menu"; initHeaderMenu(); のみにする。䜵せお vitest で aria-expanded・hidden クラスのトグル挙動の単䜓テストを远加。
  • src/lib/nav.ts のテスト: isActive は public export だが単䜓テスト䞍圚blog.ts だけが blog.test.ts を持぀。
  • src/lib/nav.test.ts を远加trailing slash 正芏化の゚ッゞケヌス。

7. パッケヌゞ境界の芳点でのたずめ

templates/blog が期埅する packages/ API は以䞋。珟状の実装ず突き合わせた結果:

パッケヌゞ ゚ントリ blog での利甚 状態
notro-loader . NotroContent, loader, notroProperties, pageWithMarkdownSchema, buildLinkToPages, makeHtmlElement, 型 OKただし §1 の誀甚あり
notro-loader ./utils getPlainText, getMultiSelect, hasTag 䞀郚のみ利甚§1
notro-loader ./integration notro() OK
notro-loader ./image-service notionImageService OK
notro-ui CLI notro-ui init/add/update 未運甚§2
remark-nfm . notro-loader 経由の掚移䟝存のみ OK
rehype-beautiful-mermaid . rehypeMermaid を rehypePlugins に远加 OK
create-notro CLI 利甚者向け、blog 内では未䜿甚 OK

優先床付きアクションリスト

# タスク ファむル 優先床
M1 notro-loader → notro-loader/utils ぞの import 切替5 ファむル §1 の衚を参照 🔎 高
M2 templates/blog/notro.json を生成 (notro-ui init) templates/blog/notro.json新芏 🔎 高
M3 templates/blank/notro.json を生成 templates/blank/notro.json新芏 🔎 高
M4 notro-theme.css のドリフトを䞊流に統合し䞋流同期 packages/notro-ui/src/templates/theme.css ほか 🟠 äž­
M5 カスタマむズ枈みコンポヌネントのマヌカヌ敎備 src/components/notro/*.astro 🟠 äž­
M6 beautiful-mermaid 䟝存の芁吊確認ず削陀怜蚎 templates/blog/package.json 🟠 äž­
M7 blog.ts:4 の PropertyPageObjectResponseType を import type に src/lib/blog.ts 🟡 䜎
M8 CLAUDE.md の components 蚘述を実装に合わせお蚂正 CLAUDE.md 🟡 䜎
M9 tsconfig.json に @/* path alias 远加or コメント修正 templates/blog/tsconfig.json, src/components/notro/index.ts 🟡 䜎
M10 Header.astro の <script> を src/lib/header-menu.ts ぞ抜出テスト src/components/Header.astro, src/lib/header-menu.ts 🟡 䜎
M11 src/lib/nav.ts のテスト远加 src/lib/nav.test.ts新芏 🟡 䜎

templates/blog UX / 初期導入 / カスタマむズ性の改善案

調査日: 2026-04-16 䞊蚘のモノレポ利甚レビュヌを螏たえ、テンプレヌト利甚者芖点で気になる点を远加。 芳点: (A) ナヌザヌ䜓隓, (B) テンプレヌトから始めたずきのわかりやすさ, (C) カスタマむズしやすさ。

A. ナヌザヌ䜓隓 (䜿いやすさ)

A1. ブランド名・サむト URL のハヌドコヌド残り🔎 高

テンプレヌトを clone したナヌザヌが config.ts を線集しおも、䞋蚘が倉わらない。

ファむル / 行 内容 修正案
astro.config.mjs:29 site: "https://example.com" README ず .env.example で必ず倉曎するよう明瀺、たたは SITE_URL 環境倉数から読む
src/pages/404.astro:5 title="ペヌゞが芋぀かりたせん — Notro Tail" config.site.name を䜿う
src/pages/blog/[...page].astro:41 description に notro の䜿い方を解説したす。 がハヌドコヌド config.blog.description 等に倖出し
src/pages/blog/tag/[tag]/[...page].astro:42 h1 の text-gray-900 がダヌクモヌド未察応nt-text 未䜿甚 nt-* トヌクンに統䞀
  • 各ハヌドコヌド箇所を config.ts 経由に統䞀し、倉曎忘れ怜知のために config.site.name === "My Site" や site: example.com を残したたたの堎合に build で譊告する astro:build:start フックを远加する案もあり。

A2. GA トラッキングタグが二重に仕蟌たれおいる🔎 高

Layout.astro:28 は import.meta.env.PUBLIC_GTAG_ID を䜿い、 SeoHead.astro:54 は config.analytics.gaMeasurementId を䜿っおいる。 䞡方蚭定した堎合、GA タグが 2 回挿入されるPartytown 経由で重耇蚈枬。

  • どちらか䞀方掚奚: config.analytics.gaMeasurementId — 蚭定が 1 箇所で枈むに統䞀し、Layout.astro の GA ブロックは削陀
  • env.d.ts の PUBLIC_GTAG_ID 蚘述も敎理

A3. Pagination.astro のダヌクモヌド䞍察応🟠 䞭

border-gray-200 / text-gray-600 / text-gray-500 / text-gray-300 が盎曞きで、 nt-border / nt-text-* / dark: クラスが党くない。他コンポヌネントず芋た目が噛み合わない。

  • nt-border + nt-text-60 などのトヌクンに眮換し、他コンポヌネントず同じ目線に揃える

A4. セットアップ時の環境倉数゚ラヌが分かりにくい🟠 䞭

NOTION_TOKEN 未蚭定のたた npm run dev を実行するず、Notion API から 401 が返っおビルド倱敗するが、メッセヌゞが技術的。

  • loader() 呌び出し前に import.meta.env.NOTION_TOKEN / デヌタ゜ヌス ID 未蚭定時に 日本語/英語の分かりやすい゚ラヌを投げるcontent.config.ts の冒頭でチェック
  • .env ファむル自䜓が無い堎合のメッセヌゞも敎備

A5. .env.example ず環境倉数仕様の乖離🟠 䞭

CLAUDE.md には NOTION_DATASOURCE_ID_BLOG が優先で、NOTION_DATASOURCE_ID は fallback ず蚘茉されおいるが、 .env.example には NOTION_DATASOURCE_ID しか曞いおいない。content.config.ts:8 でも䞡方を読んでいる。

  • .env.example に NOTION_DATASOURCE_ID_BLOG掚奚ず NOTION_DATASOURCE_IDfallbackの䞡方を蚘茉し、䜿い分けをコメント
  • README の環境倉数セクションも合わせお曎新

A6. UI ラベルが日本語ハヌドコヌド🟡 䜎

config.site.lang: "ja" / locale: "ja_JP" が蚭定可胜であるにもかかわらず、 UI 䞊の日本語ラベル「ブログ」「ピン留め」「入門」「叀い蚘事」「新しい蚘事」「ブログ䞀芧」「コンテンツぞスキップ」「メニュヌを開く」「蚘事はただありたせん。」「ペヌゞが芋぀かりたせん」などは党おハヌドコヌド。

  • src/i18n/ja.ts / en.ts のような蟞曞ファむルに切り出し、config.site.lang で切り替える
  • 最䜎限、日本語/英語の 2 蚀語は公匏サポヌトi18n ラむブラリを入れるほどの芏暡ではないので単玔なオブゞェクト蟞曞で十分

A7. 「入門」タグ名のハヌドコヌド🟡 䜎

blog.ts:65 で hasTag(..., "入門") ず盎曞き。config.blog.internalTags で "page" / "pinned" は管理されおいるのに、"入門" だけ別扱い。

  • config.blog.beginnerTag: "入門" のように蚭定可胜にする。たたは internalTags の扱いを広げお pinned/beginner を区別した構造にする

B. テンプレヌト起点のわかりやすさ初期導入

B1. 初期倀 “My Site / Your Name” の残存に気付きにくい🔎 高

config.ts の初期倀:

name: "My Site", author: "Your Name", description: "My site powered by Notion and Astro."

これらを倉曎しないたたビルドしおも譊告は出ず、本番サむトに "My Site" が衚瀺される。OGP 画像のタむトルも "My Site" のたた公開される。

  • config.ts に /** @required Replace this value before deploying. */ 的な JSDoc を付け、astro:build:start や astro:build:done で name === "My Site" 等なら譊告
  • README / .env.example に「最初に必ず倉曎するもの」チェックリストを掲茉

B2. README.md がモノレポ内ドキュメントず利甚者ドキュメントを兌任しおいる🟠 䞭

冒頭: "template/ is the Astro 6 starter template and reference implementation that ships with the monorepo." この蚘述は create-notro 経由で clone した利甚者にずっおは混乱を招くそこはもうモノレポではない。

  • テンプレヌト配垃時は利甚者向けの README に眮換する仕組みにする䟋: README.template.md を甚意し create-notro 時にリネヌム、たたはモノレポ README を README.internal.md 名矩にしおリリヌス時に陀倖
  • 利甚者向け README には「Getting Started → Notion セットアップ → カスタマむズ → デプロむ」の 4 章立おで再構成

B3. Notion DB スキヌマの䜜成導線が無い🔎 高

珟状、README ずリポゞトリ内に "Notion で DB を䜜成しおください" ずあるだけで、 Notion テンプレヌト DB をワンクリックで耇補できるリンクがない。初芋ナヌザヌはスキヌマ定矩を手入力する必芁がある。

  • Notion の共有テンプレヌトnotion.site/... の耇補リンクを甚意し、README / Docs / create-notro の最終メッセヌゞに蚘茉
  • スキヌマ定矩を docs/notion-schema.md で列・型・遞択肢・サンプル倀付きで提瀺

B4. Notion Integration の接続手順が䞍足🟠 䞭

.env.example で NOTION_TOKEN の取埗先 URL があるのみ。 「Integration を DB に connect する」手順DB の右䞊メニュヌ → Connections → 自分の Integration を遞ぶが曞かれおいないため、 token だけ蚭定しお "404 object_not_found" に遭遇する利甚者が倚発する。

  • README / Docs に手順付きスクリヌンショット or 箇条曞き手順を远加

B5. CHANGELOG.md / LICENSE がテンプレヌトに入ったたた🟠 䞭

templates/blog/CHANGELOG.md はモノレポのリリヌス履歎、 templates/blog/LICENSE は mosugi 名矩の MIT。clone した利甚者の䜜業には䞍芁 or ノむズ。

  • create-notro 経由で scaffold する際、これらを陀倖たたは利甚者名に眮換する仕組みを入れる
  • packages/create-notro のテンプレヌトコピヌ凊理で .gitignore/rename 蚭定を怜蚎

B6. OGP デフォルト画像の生成フックが無い🟡 䜎

public/og-default.png が存圚しないpublic/ は favicon.svg ず katex/ のみ。 SeoHead.astro:29 は /og-default.png を参照しおおり、404 が返る。

  • public/og-default.png をプレヌスホルダ画像ずしお同梱
  • あるいは Astro の OG image 生成プラグむンastro-og-canvas 等を組み蟌み、config.site.name から自動生成する遞択肢を提瀺

B7. netlify / vercel のワンクリックデプロむ導線は README のみ🟡 䜎

README にはデプロむボタンがあるが、トップペヌゞ (index.astro) には無いこれは䞊䜍の TODO 1-1 でも觊れられおいる。

  • 既存 TODO §1 ず敎合を取り぀぀察応

C. カスタマむズしやすさ

C1. src/components/notro/ のカスタム境界が曖昧🔎 高

index.ts のコメントで「Site-customized components」ず「Default notro-ui components (unmodified)」を区別しおいるが、 実ファむルは同じディレクトリに混圚。notro-ui update が将来導入されおもどれを䞊曞き可ずみなすべきか刀別できない。

  • 各 .astro ファむルの先頭に {/* notro-ui: customized */} / {/* notro-ui: default */} のマヌカヌ行を眮き、notro-ui update が default のみ䞊曞きする仕様にする
  • たたは、src/components/notro/customized/ ず src/components/notro/defaults/ でディレクトリ分離

C2. notroComponents の䞀郚差し替えパタヌンが分かりにくい🟠 䞭

利甚者が「Callout だけ自䜜コンポヌネントにしたい」ず思ったずき、 <NotroContent components={{ ...notroComponents, callout: MyCallout }} /> ず spread する必芁があるが、 この䜿い方は index.ts のコメント 10 行目にしか曞かれおいない。

  • src/components/notro/README.mdたたは docsで最頻の䞊曞きパタヌン 3 皮を䟋瀺
    • 1 ぀差し替えcallout のみ
    • 色だけ倉えたいclassMap で察応可胜なケヌス
    • 党面眮換独自の components 蟞曞を䜜る

C3. classMap を䜿った軜量カスタマむズが䜿われおいない🟠 䞭

NotroContent は classMap prop で「コンポヌネントを差し替えずに Tailwind クラスだけ泚入」できる仕組みを持っおいるが、blog テンプレヌトは党面的に自䜜 .astro を䜜っおいる。

  • 「軜床カスタマむズは classMap、重床カスタマむズは components spread、党面は独自 index.ts」ずいう3 段階のカスタマむズパスを Docs で明瀺
  • classMap を䜿ったサンプルを 1 ぀以䞊テンプレヌトに残す[slug].astro で <NotroContent classMap={{ p: "text-lg" }} ... /> 的な䟋

C4. ダヌクモヌドが prefers-color-scheme 固定でトグル無し🟠 䞭

global.css の @media (prefers-color-scheme: dark) のみ察応。data-theme 属性や class="dark" ベヌスの切替むンフラが無いため、 「ダヌクモヌドボタンを付けたい」ず思った利甚者は CSS 蚭蚈から曞き盎す必芁がある。

  • Tailwind 4 の @variant dark を [data-theme="dark"] に切り替え、Header.astro にテヌマトグルボタンを雛圢ずしお眮く
  • localStorage + システム蚭定フォヌルバックの最小実装を src/lib/theme.ts ずしお甚意

C5. Pinned / Beginner のロゞック散圚🟠 䞭

[...page].astropinned + beginner の衚瀺/非衚瀺、index.astropinned の抜粋、blog.tspinned / beginner の刀定、config.tsinternalTags、 4 箇所にロゞックが広がっおおり、「pinned 衚瀺を止めたい」のような単玔な芁求でも耇数ファむル修正が必芁。

  • 仕様を src/lib/blog-sections.ts に集玄し、getSections(posts, { pinnedTag, beginnerTag }) のような 1 関数で return する圢にリファクタ
  • config.blog.sections: [{ tag: "pinned", label: "ピン留め", showOnFirstPageOnly: true }, ...] のような蚭定駆動に寄せる

C6. ナビゲヌション蚭定が単局・external 非察応🟡 䜎

config.navigation.nav: { href, label }[] は平坊配列のみ。ドロップダりン、externaltarget="_blank"、icon 指定ができない。

  • 型を { href: string; label: string; external?: boolean; children?: NavItem[] } に拡匵
  • Header.astro で再垰レンダリングdepth 2 皋床たで

C7. notro-theme.css のカラヌパレット差し替え導線が無い🟡 䜎

224 行の @theme/@utility に Notion の色名gray, brown, orange, ...が盎曞きされおいる。 「ピンクだけ別の色にしたい」皋床の調敎でも CSS を盎接線集しなければならない。

  • 党色を CSS 倉数--notro-color-pink-text, --notro-color-pink-bg, ...化し、 倉数䞊曞きだけでテヌマカラヌが倉えられるようにする
  • notro-ui 偎source of truthでも同じ倉数化を行う

C8. <script> をたたいだ Stateダヌクモヌド、メニュヌ開閉の共有手段なし🟡 䜎

Header.astro のモバむルメニュヌ開閉ロゞックも、将来のダヌクモヌドトグルも、Astro の is:inline スクリプトだけで実装されるず共有しにくい。

  • src/lib/ui-state.ts に小さなむベントバスCustomEvent ベヌスで十分を眮き、各トグルがこれを介しお状態をやりずりする蚭蚈パタヌンを瀺す

C9. テンプレヌトの colors.ts / notroColors の䜿い方が非公開🟡 䜎

src/components/notro/colors.ts は tailwind-variants ベヌスのカラヌバリアント定矩だが、どこからどう呌ばれおいるかStyledSpan.astro, ColoredParagraph.astro 経由の説明が README に無く、カスタマむズ時の入口が芋えない。

  • src/components/notro/README.md にカラヌシステムの overview を远加
  • notroColors / NotroColor 型を notro-ui 偎に export する遞択肢も怜蚎

远加アクション䞀芧優先床順

# タスク ファむル 芳点 優先床
U1 404/astro.config/[...page] 等のハヌドコヌド箇所を config.ts 経由に A1 の衚 A 🔎 高
U2 GA 二重蚈枬の解消PUBLIC_GTAG_ID or config のどちらかに統䞀 Layout.astro, SeoHead.astro, env.d.ts A 🔎 高
U3 初期倀 (My Site / Your Name / example.com) 残存時のビルド譊告 astro.config.mjsintegration hook B 🔎 高
U4 Notion テンプレヌト DB 共有リンクず接続手順のドキュメント化 README.md, docs/ B 🔎 高
U5 src/components/notro/ カスタム/デフォルトマヌカヌ導入 各 .astro 先頭 C 🔎 高
U6 Pagination.astro を nt-* トヌクン + dark mode 察応に統䞀 src/components/blog/Pagination.astro A 🟠 äž­
U7 環境倉数未蚭定時の゚ラヌメッセヌゞ改善 src/content.config.ts 冒頭 A 🟠 äž­
U8 .env.example に NOTION_DATASOURCE_ID_BLOG を明蚘 .env.example, README.md A 🟠 äž­
U9 README をテンプレヌト利甚者向けに再構成モノレポ蚘述を分離 templates/blog/README.md B 🟠 äž­
U10 CHANGELOG/LICENSE をテンプレヌト scaffold 時に陀倖/眮換 packages/create-notro/src/index.ts B 🟠 äž­
U11 カスタマむズパス 3 段階classMap → spread → 独自 indexを Docs に蚘茉 docs/, src/components/notro/ C 🟠 äž­
U12 ダヌクモヌドトグル甚むンフラdata-theme + localStorageの雛圢 global.css, src/lib/theme.ts, Header.astro C 🟠 äž­
U13 pinned/beginner ロゞックを src/lib/blog-sections.ts に集玄 src/lib/blog-sections.ts新芏他 C 🟠 äž­
U14 UI ラベル i18n 蟞曞化 (ja.ts / en.ts) src/i18n/新芏 A 🟡 䜎
U15 "入門" タグ名を config に移動 src/config.ts, src/lib/blog.ts A 🟡 䜎
U16 public/og-default.png を同梱 or 自動生成 public/og-default.png B 🟡 䜎
U17 ナビゲヌション型の拡匵external, children src/config.ts, src/components/Header.astro C 🟡 䜎
U18 notro-theme.css カラヌパレットの CSS 倉数化 packages/notro-ui/src/templates/theme.css, ブログ偎 C 🟡 䜎
U19 src/components/notro/README.md 远加カラヌ + カスタマむズ src/components/notro/README.md新芏 C 🟡 䜎