Share
Embed
VitePressを2週間使ってみた感想
ドキュメント・設計書の作成にVitePressを使ってみたところ想像以上に体験が良かったです。
2週間使ってみてわかった特徴や良かった点をまとめました。
Hal
January 16, 2025
Transcript
17 slides
-
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の<script setup>を書くことができます。 これにより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 </script> -
vitepress-openapiを利用することでOpenAPIのjsonファイルを埋め込むことができます。 OpenAPIを組み込める --- aside: false outline: false title: vitepress-openapi ---
<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 onBeforeMount(() => { useTheme(themeConfig) }) onBeforeUnmount(() => { useTheme().reset() }) </script> <OARemoteSpec :spec-url="specUrl" :isDark="isDark" /> npm i vitepress-plugin-openapi mermaid -D -
1. ドキュメントのバージョンがとても楽になった 開発や設計を進めながらドキュメントを書いていくことが多いため、 変更差分が管理できるのはとても嬉し買った。 2. 設計や移行手順書等も柔軟に表現できた MermaidやOpenAPIなどが使えるためAPIドキュメントやワークフロー、設計書、システム移行 手順書などを分かりやすい形で統合できた。 3. 既存プロジェクトに組み込みやすい
VitePressをインストールするだけで始められ、学習コストが低いので既存の開発 PJに 組み込みやすいと感じた。 4. 痒いところに手が届く ソーシャルリンクや検索機能、アンカーリンクの自動生成などあると嬉しい機能が 標準で搭載されているためドキュメントのポータルとして使いやすい 2週間使ってみた感想 -
1. Data Fetchの利用(CMSとの連携など) 2. og imageの自動生成対応 3. 既存OpenAPI製ドキュメントと設計書の VitePress統合 4.
既存エクセル・ Draw.io設計書の移行 これからの展望