$30 off During Our Annual Pro Sale. View Details »

開発ドキュメントの管理・閲覧に VitePress を使ってみて感じた良かった点と注意点 / ...

開発ドキュメントの管理・閲覧に VitePress を使ってみて感じた良かった点と注意点 / document-with-vitepress

Yuhei FUJITA

November 19, 2022
Tweet

More Decks by Yuhei FUJITA

Other Decks in Programming

Transcript

  1. 自己紹介 名前 Yuhei FUJITA 藤田 悠平 Twitter @Yuhei_FUJITA 最近の活動 カンファレンススタッフ

    - Vue Fes - PWA Night Conference - VS Code Conference 所属 アララ株式会社 https://www.arara.com 好きな言語 フレームワーク TypeScript, Vue.js
  2. Vite: The DX that can't be beat Feel the speed

    of Vite. Instant server start and lightning fast HMR that stays fast regardless of the app size. VitePress Vite & Vue Powered Static Site Generator Simple, powerful, and performant. Meet the modern SSG framework you've always wanted. Get Started View on GitHub VitePress VitePress とは Markdown からSSG できる Markdown でドキュメントサイトが作れる 静的サイトとして公開できる Vue.js ベース Vue.js のComponent が使える VuePress の後継 Vite によって高速化された 現在(2022/11/19 )はまだAlpha 版 VuePress のようなPlugin は未実装
  3. セットアップは簡単 1. プロジェクトを作成 2. Vitepress をインストール 3. package.json に追記 4.

    ディレクトリ構成を作成 5. ローカルで起動 yarn init yarn add --dev vitepress vue ` ` "scripts": { "docs:dev": "vitepress dev docs", "docs:build": "vitepress build docs", "docs:serve": "vitepress serve docs" }, { "devDependencies": { "vitepress": "^1.0.0-alpha.4", "vue": "^3.2.37" } } . ├─ docs │ ├─ .vitepress │ │ └─ config.js │ └─ index.md └─ package.json yarn dev
  4. ランニングコストが ほとんどかからない Netlify, Vercel, AWS Amplify, Cloudflare Pages, Render GitHub

    Pages GitLab Pages Azure Static Web Apps Firebase Surge Heroku Layer0 Markdown 拡張が豊富 手順書で役立つCode Blocks Line Highlighting in Code Blocks markdown-it のplugin で拡張出来る markdown-it-plantuml でPlantUML も使える Static Site Hosting できればよい 標準のMarkdown だけでは不足する表現が可能
  5. すべてをGit 管理出来る バージョン管理はやはりGit が楽 勝手な更新がされにくい GitHub をフル活用出来る Issue ベースで管理できる 変更の経緯がPR

    やIssue として残る ドキュメントもソースコード同様Git 管理が安心・安 全 使い慣れたGitHub で管理できるのは学習・運用コスト がかからない
  6. 同時編集は厳しい ディスカッションしながら書くには向いてない ある程度落ち着けばIssue 上げて修正していくで よい Google ドキュメントみたいに共同編集できない 大枠決まるまではこっちで下書きしたほうが 楽? Git(GitHub)

    が必須 GitHub Teams 使うなら有料 このためだけにアカウント追加するのは… 要件定義や設計は技術者だけとは限らない 企画や営業にGit 使わせるのは酷