Libx サンプルドキュメント

カスタマイズ

基本的なスタイリングから高度な設定まで、特定の要件に合わせてドキュメントシステムをカスタマイズし拡張する方法を学びます。

テーマのカスタマイズ

CSSカスタムプロパティ

ドキュメントシステムはテーマ用にCSSカスタムプロパティを使用します。カスタムCSSでこれらをオーバーライド：

/* カスタムテーマカラー */
:root {
  --color-primary: #your-brand-color;
  --color-secondary: #your-secondary-color;
  --color-accent: #your-accent-color;
  
  /* タイポグラフィ */
  --font-family-sans: 'Your Font', system-ui, sans-serif;
  --font-family-mono: 'Your Mono Font', 'Fira Code', monospace;
  
  /* スペーシング */
  --space-unit: 0.25rem;
  --space-xs: calc(var(--space-unit) * 1);
  --space-sm: calc(var(--space-unit) * 2);
  --space-md: calc(var(--space-unit) * 4);
  --space-lg: calc(var(--space-unit) * 6);
  --space-xl: calc(var(--space-unit) * 8);
}

ダークモードサポート

ダークモードの外観をカスタマイズ：

/* ダークモード用カスタムプロパティ */
[data-theme="dark"] {
  --color-background: #1a1a1a;
  --color-surface: #2d2d2d;
  --color-text: #ffffff;
  --color-text-muted: #a0a0a0;
  --color-border: #404040;
  
  /* ブランドカラーの調整 */
  --color-primary: #66b3ff;
  --color-accent: #ff6b6b;
}

/* 自動テーマ検出 */
@media (prefers-color-scheme: dark) {
  :root {
    --color-background: #1a1a1a;
    --color-text: #ffffff;
  }
}

カスタムフォント

Webフォントを統合：

/* Google Fontsの読み込み */
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Fira+Code:wght@400;500&display=swap');

:root {
  --font-family-sans: 'Inter', system-ui, sans-serif;
  --font-family-mono: 'Fira Code', monospace;
  
  /* フォントサイズのスケール */
  --font-size-xs: 0.75rem;
  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;
  --font-size-xl: 1.25rem;
  --font-size-2xl: 1.5rem;
  --font-size-3xl: 1.875rem;
}

レイアウトのカスタマイズ

ページ幅の調整

/* コンテンツ幅のカスタマイズ */
.main-content {
  max-width: 1200px; /* デフォルト: 1024px */
  margin: 0 auto;
  padding: 0 2rem;
}

/* 読みやすさのための行長さ制限 */
.prose {
  max-width: 70ch; /* 約70文字 */
}

/* 広いコンテンツ用 */
.wide-content {
  max-width: 100%;
  margin: 0 -2rem;
}

サイドバーのカスタマイズ

/* サイドバー幅の調整 */
.sidebar {
  width: 280px; /* デフォルト: 240px */
  min-width: 280px;
}

/* サイドバー項目のスタイリング */
.sidebar-item {
  border-radius: 8px;
  transition: background-color 0.2s ease;
}

.sidebar-item:hover {
  background-color: var(--color-surface);
}

.sidebar-item.active {
  background-color: var(--color-primary);
  color: white;
}

ヘッダーのカスタマイズ

/* ヘッダーの高さとスタイル */
.header {
  height: 70px; /* デフォルト: 60px */
  background: linear-gradient(90deg, var(--color-primary), var(--color-accent));
  backdrop-filter: blur(10px);
  border-bottom: 1px solid var(--color-border);
}

/* ロゴのカスタマイズ */
.logo {
  font-size: 1.5rem;
  font-weight: 700;
  color: var(--color-primary);
}

コンポーネントのカスタマイズ

ボタンのスタイリング

/* カスタムボタンスタイル */
.custom-button {
  background: linear-gradient(45deg, #ff6b6b, #4ecdc4);
  border: none;
  border-radius: 25px;
  padding: 0.75rem 1.5rem;
  color: white;
  font-weight: 600;
  text-decoration: none;
  transition: transform 0.2s ease, box-shadow 0.2s ease;
}

.custom-button:hover {
  transform: translateY(-2px);
  box-shadow: 0 8px 25px rgba(0,0,0,0.15);
}

アイコンのカスタマイズ

/* アイコンサイズのバリエーション */
.icon-xs { font-size: 0.75rem; }
.icon-sm { font-size: 1rem; }
.icon-md { font-size: 1.25rem; }
.icon-lg { font-size: 1.5rem; }
.icon-xl { font-size: 2rem; }

/* アイコンのアニメーション */
.icon-spin {
  animation: spin 1s linear infinite;
}

@keyframes spin {
  from { transform: rotate(0deg); }
  to { transform: rotate(360deg); }
}

カードのカスタマイズ

/* カスタムカードデザイン */
.custom-card {
  background: var(--color-surface);
  border: 1px solid var(--color-border);
  border-radius: 12px;
  padding: 1.5rem;
  box-shadow: 0 4px 6px rgba(0,0,0,0.1);
  transition: transform 0.2s ease, box-shadow 0.2s ease;
}

.custom-card:hover {
  transform: translateY(-4px);
  box-shadow: 0 12px 25px rgba(0,0,0,0.15);
}

設定のカスタマイズ

Astro設定

astro.config.mjsでビルド設定をカスタマイズ：

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [mdx()],
  
  // カスタムベースパス
  base: '/your-custom-path/',
  
  // サイト設定
  site: 'https://your-domain.com',
  
  // ビルド設定
  outDir: './custom-dist',
  publicDir: './custom-public',
  
  // 開発サーバー設定
  server: {
    port: 4000,
    host: true
  },
  
  // Vite設定のカスタマイズ
  vite: {
    css: {
      preprocessorOptions: {
        scss: {
          additionalData: `@import "src/styles/variables.scss";`
        }
      }
    }
  }
});

プロジェクト設定

src/config/docs.config.tsでドキュメント固有の設定：

export const docsConfig = {
  // サイト情報
  title: 'あなたのドキュメント',
  description: 'プロジェクトの包括的なドキュメント',
  
  // ナビゲーション設定
  navigation: {
    showBreadcrumbs: true,
    showPagination: true,
    showTableOfContents: true
  },
  
  // 機能設定
  features: {
    search: true,
    darkMode: true,
    languageSwitcher: true,
    versionSwitcher: true
  },
  
  // URL設定
  baseUrl: '/docs/your-project',
  
  // ソーシャルリンク
  social: {
    github: 'https://github.com/your-org/your-repo',
    twitter: 'https://twitter.com/your-handle',
    discord: 'https://discord.gg/your-server'
  }
};

コンテンツのカスタマイズ

カスタムMDXコンポーネント

独自のMDXコンポーネントを作成：

// src/components/CustomCallout.astro
---
export interface Props {
  type?: 'info' | 'warning' | 'error' | 'success';
  title?: string;
}

const { type = 'info', title } = Astro.props;
---

<div class={`custom-callout custom-callout--${type}`}>
  {title && <div class="custom-callout__title">{title}</div>}
  <div class="custom-callout__content">
    <slot />
  </div>
</div>

<style>
.custom-callout {
  border-left: 4px solid var(--color-primary);
  padding: 1rem;
  margin: 1rem 0;
  border-radius: 4px;
  background: var(--color-surface);
}

.custom-callout--warning {
  border-left-color: var(--color-warning);
  background: rgba(255, 193, 7, 0.1);
}

.custom-callout--error {
  border-left-color: var(--color-danger);
  background: rgba(220, 53, 69, 0.1);
}

.custom-callout--success {
  border-left-color: var(--color-success);
  background: rgba(40, 167, 69, 0.1);
}

.custom-callout__title {
  font-weight: 600;
  margin-bottom: 0.5rem;
}
</style>

カスタムレイアウト

特殊なページ用のカスタムレイアウト：

---
// src/layouts/CustomLayout.astro
import BaseLayout from './BaseLayout.astro';

export interface Props {
  title: string;
  description?: string;
  showSidebar?: boolean;
}

const { title, description, showSidebar = true } = Astro.props;
---

<BaseLayout title={title} description={description}>
  <div class="custom-layout">
    {showSidebar && (
      <aside class="custom-sidebar">
        <!-- カスタムサイドバーコンテンツ -->
      </aside>
    )}
    
    <main class="custom-main">
      <header class="custom-header">
        <h1>{title}</h1>
        {description && <p class="description">{description}</p>}
      </header>
      
      <div class="custom-content">
        <slot />
      </div>
    </main>
  </div>
</BaseLayout>

高度なカスタマイズ

プラグインシステム

カスタムAstroプラグインの作成：

// plugins/custom-plugin.js
export function customPlugin(options = {}) {
  return {
    name: 'custom-plugin',
    hooks: {
      'astro:config:setup': ({ addRenderer, config, updateConfig }) => {
        // カスタム設定の追加
      },
      'astro:build:start': ({ buildConfig }) => {
        // ビルド開始時の処理
      },
      'astro:build:done': ({ dir, routes }) => {
        // ビルド完了時の処理
      }
    }
  };
}

国際化の拡張

追加言語のサポート：

// src/i18n/languages.ts
export const languages = {
  en: {
    code: 'en',
    name: 'English'
  },
  ja: {
    code: 'ja', 
    name: '日本語'
  },
  ko: {
    code: 'ko',
    name: '한국어'
  },
  zh: {
    code: 'zh',
    name: '中文'
  }
};

パフォーマンス最適化

// astro.config.mjs
export default defineConfig({
  // 画像最適化
  image: {
    service: squooshImageService(),
  },
  
  // コード分割
  build: {
    split: true
  },
  
  // プリフェッチ設定
  prefetch: {
    prefetchAll: true,
    defaultStrategy: 'viewport'
  },
  
  // 圧縮設定
  compressHTML: true,
  
  // Vite最適化
  vite: {
    build: {
      rollupOptions: {
        output: {
          manualChunks: {
            vendor: ['react', 'react-dom'],
            ui: ['@docs/ui']
          }
        }
      }
    }
  }
});

デプロイメントカスタマイズ

環境変数の設定

# .env.local
PUBLIC_SITE_URL=https://your-domain.com
PUBLIC_GA_ID=G-XXXXXXXXXX
PUBLIC_SEARCH_API_KEY=your-search-key

# プライベート変数
DATABASE_URL=your-database-url
API_SECRET=your-api-secret

ビルドスクリプトのカスタマイズ

{
  "scripts": {
    "build": "astro build",
    "build:staging": "ENVIRONMENT=staging astro build",
    "build:production": "ENVIRONMENT=production astro build",
    "preview": "astro preview",
    "deploy": "npm run build:production && your-deploy-command"
  }
}

トラブルシューティング

一般的な問題

スタイルが適用されない

/* より具体的なセレクターを使用 */
.docs-content .custom-component {
  /* スタイル */
}

/* !importantの使用（最後の手段） */
.urgent-style {
  color: red !important;
}

ビルドエラー

# キャッシュをクリア
rm -rf node_modules/.astro
rm -rf dist

# 依存関係を再インストール
pnpm install

# ビルドを再実行
pnpm build

ベストプラクティス

メンテナンス性

  • CSS変数の使用: ハードコードされた値の代わりに変数を使用
  • コンポーネントの分離: 再利用可能なコンポーネントを作成
  • 設定の中央化: 設定を一箇所にまとめる

パフォーマンス

  • 必要最小限の読み込み: 使用しないスタイルやスクリプトは読み込まない
  • 画像の最適化: 適切な形式とサイズを使用
  • キャッシュ戦略: 適切なキャッシュヘッダーを設定

アクセシビリティ

  • コントラスト: 適切な色のコントラストを維持
  • キーボードナビゲーション: すべての機能をキーボードで操作可能に
  • スクリーンリーダー: 適切なARIAラベルと構造

次のステップ

カスタマイズの基本を理解したら：