Vitepress でドキュメントサイトを作ろう!!

Vitepressとは

Vite + Vue3 + Markdownを使用した静的サイトジェネレーター（SSG）で、簡単にサイト構築を行えます。
特に、ドキュメントサイトを早く制作したい場合にとても有用です。

下記3つのでテーマを選択できます。
今回紹介するのは、Vueでカスタマイズできるディフォルトテーマ拡張版です。

• ディフォルトテーマ
• ディフォルトテーマ拡張
• カスタムテーマ

ディフォルトテーマ拡張版ついて

ディフォルトテーマを基調に、cssのカスタマイズ、Vueのコンポーネント、Frontmatterによる配置や出力のカスタマイズ、Markdown内でVueを使用することができ、他サイトとの差別化を簡単に実装できるのが特徴です。

---

環境構築について

※Node.jsバージョン 18 以上。

• 最新版をインストール

npm add -D vitepress@next

VitePressプロジェクトのセットアップします。

npx vitepress init

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./
│
◇  Where should VitePress look for your markdown files?
│  ./
│
◇  Site title:
│  My Awesome Project //サイト名を入力して下さい。
│
◇  Site description:
│  A VitePress Site //サイトの説明を入力して下さい。
│
◇  Theme:
│  Default Theme + Customization (Add custom CSS and layout slots)
│
◇  Use TypeScript for config and theme files?
│  Yes
│
◇  Add VitePress npm scripts to package.json?
│  Yes
│
◇  Add a prefix for VitePress npm scripts?
│  Yes
│
◇  Prefix for VitePress npm scripts:
│  docs
│
└  Done! Now run pnpm run docs:dev and start writing. //npmを使用している方は、npm Commandを使用して下さい。

ディフォルトテーマを使用した場合は、ナビ・トップページ・フッター・ページネーション・検索フォーム・メタタグ・ロゴなどをthemeConfig.mtsで設定することができます。(日本語検索には別途カスタマイズが必要です)

セットアップ後のファイル構造は下記の通りです。

.
├── .DS_Store
├── .vitepress
│   ├── .DS_Store
│   ├── cache
│   │   └── deps
│   │       ├── _metadata.json
│   │       ├── chunk-DEFK5HPI.js
│   │       ├── chunk-DEFK5HPI.js.map
│   │       ├── package.json
│   │       ├── vitepress___@vue_devtools-api.js
│   │       ├── vitepress___@vue_devtools-api.js.map
│   │       ├── vitepress___@vueuse_core.js
│   │       ├── vitepress___@vueuse_core.js.map
│   │       ├── vue.js
│   │       └── vue.js.map
│   ├── config.mts
│   └── theme
│       ├── index.ts
│       └── style.css
├── api-examples.md
├── index.md
├── markdown-examples.md
├── package-lock.json
└── package.json

---

開発について

npm run docs:dev

を実行して開発サーバーを起動します。

これで http://localhost:5173 にアクセスし、リアルタイムプレビューを確認。編集した /index.md の変更が即座に反映されます（HMR対応）。

基本的なコンテンツ作成

/index.mdを編集：

--- //front matter内はvueを使用することができません。
title: ホームページ
description: VitePressで構築したサイトです
--- 

# ようこそ！

<-- common.md --> //左のように記述するとmarkdownを共通して表示できます。

ここに**Markdown**でコンテンツを記述します。

<script setup>
import { ref } from 'vue'  //個別のmarkdownにvueをインポートできます。

const count = ref(0)
</script>

## Markdown コンテンツ

現在の値: {{ count }} //処理結果をvueで表示

<button :class="$style.button" @click="count++">Increment</button>

<style module>   //個別のmarkdownにcssやscssを記述できます。
.button {
  color: red;
  font-weight: bold;
}
</style>

新しいページ追加（例:  /guide/index.md ）：

guide(例)フォルダを作成するとそのままサブディレクトリとして使用することができます。

---
title: ガイド
---

## 最初のセクション

- リスト項目1
- リスト項目2

themeConfig.mtsのカスタマイズによってディフォルトテーマを調整

 .vitepress/themeConfig.mts でナビゲーション・サイドバー設定：

 import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'My Awesome Project', //サイトタイトル
  description: 'A VitePress Site', //サイト説明
  themeConfig: {
    nav: [
      { text: 'ガイド', link: '/guide/' }, 　//サイト上部のナビテキストとリンク
      { text: 'API', link: '/api/' }
    ],
    sidebar: [
      {
        text: 'ガイド',
        items: [
          { text: 'インストール', link: '/guide/install' }, //サイドメニューテキストとリンク
          { text: '設定', link: '/guide/config' }
        ]
      }
    ],
    socialLinks: [
      { icon: 'github', link: 'https://github.com/vuejs/vitepress' } //アイコンの設定
    ]
  }
})

theme/index.tsによるvueのコンポーネント化

// .vitepress/theme/index.ts
// https://vitepress.dev/guide/custom-theme
import { h } from 'vue' //vueのインポート
import type { Theme } from 'vitepress' //viteのインポート
import DefaultTheme from 'vitepress/theme' //テーマのインポート

//vueテンプレートのインポート(thema内にcomponentsフォルダを作成してまとめています)
import NotFound from "../theme/components/NotFound.vue";
import FooterOn from "../theme/components/FooterOn.vue";
import SimpleWaySocialLinks from "../theme/components/SimpleWaySocialLinks.vue";

export default {
  extends: DefaultTheme,
  Layout: () => {
    return h(DefaultTheme.Layout, null, {
			// https://vitepress.dev/guide/extending-default-theme#layout-slots
			"not-found": () => h(NotFound), //インポートしたvueをフックにかけてサイトに表示させています。
			"doc-after": () => h(FooterOn),
			"doc-before": () => h(SimpleWaySocialLinks),
		});
  },
  enhanceApp({ app, router, siteData }) {
		// サイトデータを使って何かする
		console.log("Site title:", siteData.value.title);
	}
} satisfies Theme

下記はフックを掛けられる場所です。

When layout: 'doc' (default) is enabled via frontmatter:
→ markdownのfrontmatterにdocを指定していた場合

doc-top
doc-bottom
doc-footer-before
doc-before
doc-after
sidebar-nav-before
sidebar-nav-after
aside-top
aside-bottom
aside-outline-before
aside-outline-after
aside-ads-before
aside-ads-after

When layout: 'home' is enabled via frontmatter:
→ markdownのfrontmatterにhomeを指定していた場合

home-hero-before
home-hero-info-before
home-hero-info
home-hero-info-after
home-hero-actions-after
home-hero-image
home-hero-after
home-features-before
home-features-after

When layout: 'page' is enabled via frontmatter:
→ markdownのfrontmatterにpageを指定していた場合

page-top
page-bottom

On not found (404) page:
→404ページのみ

not-found

Always:
→全て

layout-top
layout-bottom
nav-bar-title-before
nav-bar-title-after
nav-bar-content-before
nav-bar-content-after
nav-screen-content-before
nav-screen-content-after

ビルド・デプロイ

npm run docs:build

コンパイル後dist/ フォルダが出力され、静的HTML生成してそのままファイルサーバーにアップロードして公開することが可能です。
Netlify、Vercel、GitHub Pagesなどにデプロイすることも可能です。