Docus実践ガイド — Nuxt Contentからの移行と運用ノウハウ

# Docusテンプレートでプロジェクト作成
npx nuxi init docs -t docus
cd docs

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

# 開発サーバーの起動
pnpm dev

docs/
├── content/               # Markdownコンテンツ
│   ├── 1.intro/          # 章1（orderで制御）
│   │   ├── index.md
│   │   ├── 1.getting-started.md
│   │   └── 2.installation.md
│   ├── 2.guide/          # 章2
│   │   ├── index.md
│   │   └── 1.basic-usage.md
│   └── index.md          # トップページ
├── public/               # 静的アセット
│   ├── images/           # 画像ファイル
│   ├── favicon.ico
│   └── og-image.png
├── components/           # Vueコンポーネント
│   └── content/          # Markdownで使用するコンポーネント
│       ├── LinkCard.vue
│       └── Badge.vue
├── app.config.ts         # Docus設定
├── nuxt.config.ts        # Nuxt設定
└── package.json

# Docusパッケージのインストール
pnpm add docus

# 必要に応じて追加パッケージをインストール
pnpm add @nuxt/content @nuxt/ui

export default defineNuxtConfig({
  extends: ['docus'],
  // その他の既存設定...
})

---
title: ページのタイトル
description: 120字以内の要約（検索とOGPカード用）
order: 10
draft: false
navigation:
  title: サイドバー表示名（省略可。titleと同じなら削除）
  icon: i-heroicons-book-open  # アイコン（省略可）
---

---
title: セクション名
description: セクションの概要
order: 20
navigation:
  icon: i-heroicons-folder
---

---
title: ナビに表示しないページ
description: プライバシーポリシーなど
navigation: false
---

---
title: 執筆中の記事
description: まだ公開していない記事
draft: true  # ビルド時に除外される
---

# 依存関係のインストール
pnpm add -D fast-glob gray-matter tsx

# package.jsonにスクリプトを追加
# "frontmatter:fix": "tsx scripts/fix-frontmatter.ts"

# 実行
pnpm frontmatter:fix

export default defineAppConfig({
  docus: {
    // ... 既存設定

    // DocSearch設定（Algoliaから取得した認証情報）
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
      langAttribute: 'lang',
      docSearch: {
        placeholder: 'サイト内を検索',
        translations: {
          button: {
            buttonText: '検索',
            buttonAriaLabel: 'サイト内を検索'
          },
          modal: {
            searchBox: {
              cancelButtonText: 'キャンセル',
              resetButtonTitle: 'クリア'
            }
          }
        }
      }
    }
  }
})

app/
├── pages/
│   ├── blog/
│   │   └── index.vue              # → BlogIndexPage
│   ├── biblio/
│   │   └── index.vue              # → BiblioIndexPage
│   └── jenre/
│       └── tags/
│           └── [slug].vue         # → JenreTagsPage（存在する場合）
├── components/
│   ├── blog/
│   │   ├── BlogIndexPage.vue      # 複雑なロジック + UI
│   │   └── BlogCardHorizontal.vue
│   ├── biblio/
│   │   ├── BiblioIndexPage.vue    # 複雑なロジック + UI
│   │   └── BiblioCard.vue
│   └── content/
│       └── home/
│           └── HomeLanding.vue    # トップページのUI
└── content/
    ├── index.md                   # / → <home-landing />
    ├── blog/
    │   └── *.md                   # 個別記事
    └── biblio/
        └── *.md                   # 個別書籍

<style scoped>
@reference "tailwindcss";

/* Before: 従来のCSS */
.hero {
  position: relative;
  width: 100%;
  height: 500px;
  overflow: hidden;
}

@media (max-width: 768px) {
  .hero {
    height: 400px;
  }
}

/* After: Tailwind CSS */
.hero {
  @apply relative w-full h-[500px] overflow-hidden md:h-[400px];
}

.hero__overlay {
  @apply absolute inset-0 bg-gradient-to-b from-black/10 to-black/30;
}
</style>

<template>
  <UCard
    :ui="{
      root: 'overflow-hidden rounded-md ring-1 ring-gray-200 dark:ring-gray-800',
      body: 'p-0 sm:p-0',
      header: 'p-0 sm:p-0',
    }"
    class="my-3 not-prose"
  >
    <!-- コンテンツ -->
  </UCard>
</template>

/* code-collapse ボタンのスタイル */
.prose div[class*="bg-gradient-to-t from-muted"] button,
.prose button[data-state="closed"],
.prose button[data-state="open"] {
  background-color: #d1d5db !important;
  padding: 0.5rem 1rem !important;
  border-radius: 0.375rem !important;
  transition: background-color 0.2s ease !important;
  color: #1f2937 !important;
  font-weight: 500 !important;
  opacity: 0.5;
}

.prose div[class*="bg-gradient-to-t from-muted"] button:hover,
.prose button[data-state="closed"]:hover,
.prose button[data-state="open"]:hover {
  background-color: #9ca3af !important;
  opacity: 1;
}

/* ダークモード */
.dark .prose div[class*="bg-gradient-to-t from-muted"] button,
.dark .prose button[data-state="closed"],
.dark .prose button[data-state="open"] {
  background-color: #374151 !important;
  color: #d1d5db !important;
  opacity: 0.5;
}

.dark .prose div[class*="bg-gradient-to-t from-muted"] button:hover,
.dark .prose button[data-state="closed"]:hover,
.dark .prose button[data-state="open"]:hover {
  background-color: #4b5563 !important;
  opacity: 1;
}

cd public/img/blog
for file in *.png; do
  cwebp -q 80 "$file" -o "${file%.png}.webp"
done

<NuxtPicture
  :src="heroImage.src"
  :width="heroImage.width"
  :height="heroImage.height"
  :alt="heroImage.alt"
  :img-attrs="{ class: 'hero-image', loading: 'eager' }"
  sizes="sm:100vw md:1356px lg:1356px"
  :modifiers="{ fit: 'cover', quality: 80 }"
  format="webp"
/>

export default defineNuxtConfig({
  modules: [
    '@nuxt/scripts',
    // ...
  ],

  scripts: {
    registry: {
      clarity: process.env.NODE_ENV === 'production' ? {
        id: 'xxxxxxxx',
        trigger: 'idle'
      } : false,
      googleAnalytics: process.env.NODE_ENV === 'production' ? {
        id: 'G-xxxxxxx',
        trigger: 'idle'
      } : false
    },
  },
})

---
title: イントロダクション
order: 10
---

Hydration completed but contains mismatches.

<template>
  <ClientOnly>
    <UColorModeButton />
  </ClientOnly>
</template>

# broken-link-checkerのインストール
pnpm add -D broken-link-checker

# package.jsonにスクリプトを追加
# "linkcheck": "blc http://localhost:3000 -ro"

# 実行（開発サーバー起動後）
pnpm linkcheck

{
  "redirects": [
    { "source": "/old-path", "destination": "/docs/new-path", "permanent": true },
    { "source": "/legacy/:slug", "destination": "/docs/:slug", "permanent": true }
  ]
}

/old-path           /docs/new-path   301
/legacy/:slug       /docs/:slug      301