Livemark カスタマイズ

livemark.config.ts で公開されている以上に、Livemark プロジェクトの UI レイヤーをカスタマイズするためのガイダンスです。

このスキルを使用する場合

以下のいずれかをユーザーが要求した場合に実行してください。

• 組み込みコンポーネントのレイアウトまたはマークアップを変更する（Footer、Sidebar、Banner など）。
• 共有プリミティブを再スタイルする（ボタン、入力欄、カード、シートなど）。
• CSS トークンでリブランディングする（色、半径、タイポグラフィ）。
• Markdown 記事ではない新しいページを追加する（ランディングヒーロー、価格ページ、About ページ）。
• Livemark のデフォルトランディングページをカスタム React コンポーネントで置き換える。
• カスタム favicon.svg、robots.txt、og-image.png、またはその他の静的アセットを提供する。

3 つの重複するメカニズム

目的	メカニズム
デフォルトコンポーネント/スタイルを置き換える	.livemark/components/<Name>.tsx などにファイルを配置
特定の URL に新しいページを追加する	.livemark/routes/<path>.tsx を作成
/<path> で静的アセットを提供する	ファイルを .livemark/public/<path> に配置

いずれも設定変更が不要です。Vite プラグイン（website/plugins/vite-livemark.ts）は .livemark/** を監視し、ホットリロードします。

オーバーライド可能なもの を見つける

escape コマンドを実行してください。引数なしで、すべてのオーバーライド可能なファイルを一覧表示します。

livemark escape

出力は components/、elements/、styles/ にわたるフラットな <subdir>/<file> リストです。引数付きで実行すると、コマンドはデフォルトを .livemark/ にコピーします。

livemark escape components/Footer.tsx   # → .livemark/components/Footer.tsx
livemark escape elements/button.tsx     # → .livemark/elements/button.tsx
livemark escape styles/general.css      # → .livemark/styles/general.css

既存のオーバーライドを上書きすることは拒否されます。新しい開始が必要な場合は、まずオーバーライドを削除してください。

典型的なワークフロー: コンポーネントをオーバーライドする

1. livemark escape components/Footer.tsx — デフォルトをコピーします。
2. .livemark/components/Footer.tsx を編集します。すべてのサイトの Footer レンダリングが保存時に新しいファイルに移行します。
3. オーバーライド内で、livemark/<subdir>/* サブパスエクスポートから他の Livemark モジュールをインポートしてください。

   import { cn } from "livemark/helpers/style"
   import { Button } from "livemark/elements/button"
   

典型的なワークフロー: リブランディング

1. livemark escape styles/general.css。
2. .livemark/styles/general.css の :root および .dark ブロックを編集します。
   • --primary — ブランドアクセント（Tailwind スタイルの oklch 値で動作します）。
   • --radius — コーナーの丸さの基本値。
   • さらに深いツイークが必要な場合は Sidebar / チャートトークン。
3. 保存してください — 開発サーバーが直ちに適用されます。

サイト全体のコントラストが監査されます。ライトモードはブルー600 を、ダークモードはブルー500 をターゲットにします。新しいトークン値を両方の背景で AA 準拠に保ってください（テキストで ≥4.5:1）。

典型的なワークフロー: ページを追加する

カスタムルートは TanStack Router を使用します。最小限の例：

import { createFileRoute } from "@tanstack/react-router"

export const Route = createFileRoute("/about")({
  component: () => (
    <main className="mx-auto max-w-3xl px-6 py-16 prose">
      <h1>About</h1>
      <p>Hello.</p>
    </main>
  ),
})

ファイル名は URL パスにマップされます。.livemark/routes/pricing.tsx → /pricing/。ネストされたパスはネストされたフォルダで機能します。

.livemark/routes/ の index.tsx は、Livemark のデフォルトランディングを / で 置き換え ます。

カスタムルートは、正確な URL で Markdown のキャッチオールに優先します。記事 URL と衝突するルートは、記事を隠すつもりがない限り、作成しないでください。

経験則

1. 日常的なカスタマイズのためにリポジトリをフォークしないでください。 .livemark/ を最初に使用してください — Livemark のアップグレードを確実に存続させます。
2. 同じファイル名、.livemark/ の下の同じパス。 オーバーライドプラグインは大文字と小文字を区別し、サブディレクトリ構造をまったく同じようにミラーします。
3. オーバーライドファイルは完全な置き換えで、差分ではありません。 最初にデフォルトをコピー（escape 経由）してから編集してください。
4. 相対パスではなく livemark/* 経由で Livemark の内部をインポートしてください — プラグインはそれをオーバーライドリゾルバーを通じてルーティングするため、チェーンされたオーバーライド（例：あなたのレイアウトがあなたの Sidebar を使用する）が正しく構成されます。
5. 静的ファイルは .livemark/public/ に属します。 Vite はそれをサイトルートで公開します。

オーバーライド不可能なもの

• actions/、commands/、program.ts — サーバー/CLI コード。これらを変更する必要がある場合はアップストリームをフォークしてください。
• livemark.config.ts スキーマ — 固定。
• コンテンツコレクション変換パイプライン。フォーク内の remark/rehype プラグインでマークダウンをカスタマイズするか、アップストリームに PR してください。

検証

• pnpm type — オーバーライドが型チェックされることを確認します。
• pnpm docs:build — オーバーライドがバンドルに含まれることをスモークテストします。
• ブラウザ：開発サーバーで記事ページを読み込みます。カスタム Footer/Sidebar/など が フルリロードなしでレンダリングされるはずです。

リファレンス

• 説明ドキュメント：docs/customization/file-overrides.md、docs/customization/custom-routes.md。
• プラグイン実装：website/plugins/vite-livemark.ts。
• Escape コマンド：commands/escape.ts。
• サブパスエクスポート：package.json exports ブロック。