VitePressを 2週間使ってみた感想 Hal

みなさんは Vitepress 使ったことがありますか？

VitePressとは... マークダウン記法でリッチなドキュメントが 作成できるライブラリ。 プラグインを追加でき、 OpenAPIやMermaidなど 様々なレイアウトや記法を取り入れることが可能。

よくみるこんなドキュメントが簡単に作れる https://vue3datepicker.com/installation/

1. 設計書や手順書等の開発用資料を backlogとエクセルで作っていたが、 バージョン管理ができなかった 2. マークダウンで管理できるため、直感的かつ手軽にドキュメント作成でき ると思った →OpenAPI(swagger)ならjsonかyml 3. これまで作成したドキュメントの場所がわからなくなることがあった →後述する検索機能が非常に有効だった 4. 見やすい・保守しやすいドキュメントの形を模索していた なぜ導入してみたのか

● マークダウン記法で書ける ● 検索機能が簡単に導入できる →超強力 ● 見出しでアンカーリンクを取得できる ● i18nに対応 ● ソーシャルリンクを埋め込める ● 動的パス生成が可能 ● CMS等と連携して data fetchが可能 ● SSR対応 ● OpenAPI / Mermaid / Vueなど様々な構文で書ける Vitepressの特徴

● マークダウン記法で書ける ● 検索機能が簡単に導入できる ● 見出しでアンカーリンクを取得できる ● i18nに対応 ● ソーシャルリンクを埋め込める ● 動的パス生成が可能 ● CMS等と連携して data fetchが可能 ● SSR対応 ● OpenAPI / Mermaid / Vueなど様々な構文で書ける Vitepressの特徴

VitePressはmdファイルを作成することでお手軽にリッチなドキュメントが作成できます。 ルーティングは配置されたパスに従い自動で行われ、カスタムしたり動的生成も可能です。 マークダウン記法で書ける # Command Line Interface ## `vitepress dev` Start VitePress dev server using designated directory as root. Defaults to current directory. The `dev` command can also be omitted when running in current directory. ### Usage ```sh # start in current directory, omitting `dev` vitepress # start in sub directory vitepress dev [root] ```

.vitepress/config.ts で以下の設定を入れることで検索機能を追加できます。 i18nによる拡張や検索の微調整ができます。 特に見出しのキーワードにはヒットしやすく、ドキュメントを探す際に非常に便利です。 検索機能が簡単に導入できる import { defineConfig } from 'vitepress' export default defineConfig({ themeConfig: { search: { provider: 'local' } } }) https://vitepress.dev/reference/default-theme-search#search

マークダウンでは頻繁に利用する見出しですが、アンカーリンクとしてジャンプできます。 スペースや特殊文字を含んでいるなどでうまくジャンプしない場合、 {#~~~}を追加するとアンカーを指定できます。 見出しでアンカーリンクを取得できる # Command Line Interface ## `vitepress dev` {#vitepress_dev} Start VitePress dev server using designated directory as root. Defaults to current directory. The `dev` command can also be omitted when running in current directory. a /reference/cli/#vitepress_dev

マークダウンの中に Vueのを書くことができます。 これによりuseDataにアクセスしたり、マークダウンだけでは実現できなかった表現が可能になります。 マークダウン内で Vueの糖衣構文が使える <ClientOnly> <Teleport to="#modal"> <div> // ... </div> </Teleport> </ClientOnly> <script setup lang="ts"> import { onBeforeMount, onBeforeUnmount } from 'vue' import { useRoute, useData } from 'vitepress' import { useTheme } from 'vitepress-openapi' const route = useRoute() const { isDark } = useData() const exampleSlug = route.data.params.exampleSlug const specUrl = route.data.params.specUrl const themeConfig = route.data.params.themeConfig

vitepress-openapiを利用することでOpenAPIのjsonファイルを埋め込むことができます。 OpenAPIを組み込める --- aside: false outline: false title: vitepress-openapi --- import { onBeforeMount, onBeforeUnmount } from 'vue' import { useRoute, useData } from 'vitepress' import { useTheme } from 'vitepress-openapi' const route = useRoute() const { isDark } = useData() const exampleSlug = route.data.params.exampleSlug const specUrl = route.data.params.specUrl const themeConfig = route.data.params.themeConfig onBeforeMount(() => { useTheme(themeConfig) }) onBeforeUnmount(() => { useTheme().reset() }) npm i vitepress-plugin-openapi mermaid -D

ガントチャートやフロー図などを書くことができる Mermaidですが、 vitepress-plugin-mermaidをインストールすることで使うことができます。 Mermaid記法が使える npm i vitepress-plugin-mermaid mermaid -D

1. ドキュメントのバージョンがとても楽になった 開発や設計を進めながらドキュメントを書いていくことが多いため、 変更差分が管理できるのはとても嬉し買った。 2. 設計や移行手順書等も柔軟に表現できた MermaidやOpenAPIなどが使えるためAPIドキュメントやワークフロー、設計書、システム移行 手順書などを分かりやすい形で統合できた。 3. 既存プロジェクトに組み込みやすい VitePressをインストールするだけで始められ、学習コストが低いので既存の開発 PJに 組み込みやすいと感じた。 4. 痒いところに手が届く ソーシャルリンクや検索機能、アンカーリンクの自動生成などあると嬉しい機能が 標準で搭載されているためドキュメントのポータルとして使いやすい ２週間使ってみた感想

1. Data Fetchの利用（CMSとの連携など） 2. og imageの自動生成対応 3. 既存OpenAPI製ドキュメントと設計書の VitePress統合 4. 既存エクセル・ Draw.io設計書の移行 これからの展望

Mermaidのセットアップ時、 GANGANさんが書かれた以下の記事がと ても参考になりました。 セットアップ時に参考にした記事 https://zenn.dev/gangannikki/articles/vitepress-mermaid

ご清聴ありがとうございました！