僕はただドキュメントを HTML で見たいだけなんだ

【teamLab Study Session ~frontend~ #3 】にてチームラボのフロントエンドエンジニアが登壇用に作成したスライドです。

teamLab Study Session ~frontend~ とは

チームラボのフロントエンド班がチームラボ内で定期的に実施している勉強会を、フロントエンドの技術に興味ある参加者を募集し、オンラインで配信する勉強会です。

https://teamlab.connpass.com/event/393589/

Transcript

1. © teamLab Inc. 僕はただドキュメントを HTML で見たいだけなんだ teamLab Study Session ~frontend~ #3 金子 巧磨 チームラボ パッケージチーム 所属
2. © teamLab Inc. 所属｜ 2 自己紹介 2 パッケージチーム フロントエンド班 フロントエンドスペシャリスト 金子 巧磨 Kaneko Takuma 入社｜2023年新卒（4年目） 趣味｜ごはん
3. © teamLab Inc. 僕について dathra A full-stack JS framework that works with the new order TC39 Signals vue-swipe-modal Modal window that can be swiped to close. （Swipeable Bottom Sheet） 3
4. © teamLab Inc. 4 ドキュメント何で作ってますか？
5. © teamLab Inc. 社内ドキュメント何で作ってますか？ 5
6. © teamLab Inc. 社内ドキュメント何で作ってますか？ 6
7. © teamLab Inc. 社内ドキュメント何で作ってますか？ 7
8. © teamLab Inc. 社内ドキュメント何で作ってますか？ 8
9. © teamLab Inc. 9 保守できてますか？
10. © teamLab Inc. 10 リッチすぎませんか？
11. © teamLab Inc. 11 もっと楽に ドキュメントを HTML で見る方法 あるんじゃないだろうか
12. © teamLab Inc. 12 ただドキュメントで HTML を見るだけでいいの
13. © teamLab Inc. 13 一番楽に ドキュメントを HTML で見る 方法を探します！
14. © teamLab Inc. 一番シンプルなドキュメントフレームワーク を使ってみる 14
15. © teamLab Inc. 一番シンプルなドキュメントフレームワークを使ってみる シンプル とは？ - 依存関係数が少ない - ドキュメント以外のコード量が少ない - 学習コストが少ない 15
16. © teamLab Inc. 一番シンプルなドキュメントフレームワークを使ってみる 探してみる 主要フレームワークを比較 - Docsify - mdBook - MkDocs - VitePress - Starlight - Docusaurus - Nextra - Sphinx - Docute 16
17. © teamLab Inc. 一番シンプルなドキュメントフレームワークを使ってみる Docsify A magical documentation site generator ビルドプロセス不要・CDNで即起動・プラグインで拡張可能 17 動作タイプ Runtime 依存関係 ほぼ 0 （CDN実行） 設定方法 index.html 学習コスト 極低（md のみ）
18. © teamLab Inc. 一番シンプルなドキュメントフレームワークを使ってみる mdBook Create book from markdown files Rustコミュニティ公式採用・ドキュメント内コードの自動テスト対応 18 動作タイプ SSG（Rust） 依存関係 バイナリのみ 設定方法 book.toml + src/SUMMARY.md 学習コスト 極低（md のみ）
19. © teamLab Inc. 一番シンプルなドキュメントフレームワークを使ってみる MkDocs Project documentation with Markdown ライブプレビュー内蔵・Material テーマが強力 19 動作タイプ SSG（Python） 依存関係 18 設定方法 mkdocs.yml 学習コスト 低
20. © teamLab Inc. 一番シンプルなドキュメントフレームワークを使ってみる VitePress Vite由来の爆速HMR・最も軽量なNode.js系 20 動作タイプ SSG（Node.js/Vite） 依存関係 170 設定方法 vitepress/config.[ext], 他にもちょっと 学習コスト 中（特殊記法あり）
21. © teamLab Inc. 一番シンプルなドキュメントフレームワークを使ってみる Starlight 検索・i18n・SEO・ダークモードがゼロ設定で全部入り React/Vue/Svelteどれでも拡張可 21 動作タイプ SSG（Node.js/Astro） 依存関係 430 設定方法 astro.config.mjs, 他にもちょっと 学習コスト 低〜中
22. © teamLab Inc. 一番シンプルなドキュメントフレームワークを使ってみる Nextra Next.jsのSSG/SSR/ISRがそのまま使える・MDX内蔵UIコンポーネント 22 動作タイプ SSG（Node.js/Next.js） 依存関係 476 設定方法 Next.js 学習コスト 中〜高（Next.js の基礎知識, .mdx）
23. © teamLab Inc. 一番シンプルなドキュメントフレームワークを使ってみる Docusaurus 複数バージョンのdocsを共存管理できる・i18n標準対応 23 動作タイプ SSG（Node.js/React） 依存関係 1,280 設定方法 docusaurus.config.js, sidebars.js, src/pages/index.tsx, custom.css 学習コスト 中〜高（ちょっと構造が複雑, .mdx）
24. © teamLab Inc. 一番シンプルなドキュメントフレームワークを使ってみる Sphinx HTML/PDF/ePubを1ソースから多形式出力 PythonコードからAPIドキュメント自動生成 24 動作タイプ SSG（Python） 依存関係 22 設定方法 conf.py, Makefile 学習コスト 高
25. © teamLab Inc. 一番シンプルなドキュメントフレームワークを使ってみる Docute 事前ビルド不要、Markdownを置くだけでサイト化 ≒ Docsify 2025年3月 EOL 25 動作タイプ Runtime 依存関係 ほぼ 0 設定方法 index.html 学習コスト 極低
26. © teamLab Inc. 一番シンプルなドキュメントフレームワークを使ってみる 結論... 26
27. © teamLab Inc. 一番シンプルなドキュメントフレームワークを使ってみる 結論... Docsify Node.js のセットアップもいらない markdown の基本構文さえあれば書ける 設定ファイルも不要 らしい？ので 27 動作タイプ Runtime 依存関係 ほぼ 0 （CDN実行） 設定方法 index.html 学習コスト 極低（md のみ）
28. © teamLab Inc. Docsifyを使ってみる 公式ドキュメント 　https://docsify.js.org 28
29. © teamLab Inc. Docsifyを使ってみる https://codesandbox.io/p/sandbox/nhg36v 29
30. © teamLab Inc. Docsifyを使ってみる 以下のファイルの作成 _sidebar.md abouts.md index.html README.md 30
31. © teamLab Inc. Docsifyを使ってみる 所感 メリット - 最小構成が、本当に最小 - カスタマイズ性も一応ある - 設定も簡単 デメリット - SPA（not SSR SSG） - SPAなので curl とかで取得できない - 色々やろうとすると、結局 index.html や _sidebar.md の管理が必要 31
32. © teamLab Inc. Docsifyを使ってみる SPA, curl で取得できない Agent にドキュメントを読ませるのが面倒 完全に人間用と割り切れば問題なし 結局 index.html や _sidebar.md の管理が必要 config.json 的なものは無いが、 index.html の <script> に結局色々書くことになる _sidebar もカオス化しないようにしないといけない 32
33. © teamLab Inc. 33 設定必要では...？ ちょっとだけど
34. © teamLab Inc. 34 設定書きたくないぃ
35. © teamLab Inc. mo を使ってみる 35
36. © teamLab Inc. mo を使ってみる mo とは？ k1LoW/mo mo is a Markdown viewer that opens .md files in a browser. 36 877 42
37. © teamLab Inc. mo を使ってみる mo とは？ k1LoW/mo mo is a Markdown viewer that opens .md files in a browser. → markdown viewer ってこと？ 37 877 42
38. © teamLab Inc. mo を使ってみる - GitHub Alerts (admonitions) - Fullscreen zoom modal for images and Mermaid diagrams - dark theme Dark / light theme light theme - group File grouping - toc Table of contents panel - flat view Flat / tree view tree sidebar view with drag-and-drop reorder - file name File name / heading title heading title sidebar display toggle (per-group) - search Full-text search across file names and content - YAML frontmatter display (collapsible metadata block) - MDX file support (renders as Markdown, strips import/export, escapes JSX tags) - font size Content font size toggle (small / medium / large / extra large) - wide view Wide / narrow view narrow content width toggle - raw Raw markdown view - copy Copy content (Markdown / Text / HTML) 38
39. © teamLab Inc. mo を使ってみる https://codesandbox.io/p/devbox/mo-tutorial-5sdwjh 39
40. © teamLab Inc. mo を使ってみる 40 以下のインストール mo コマンド 以下のファイルの作成 docs/index.md docs/about.md
41. © teamLab Inc. mo を使ってみる 所感 メリット - markdown であれば、どこに置いてあるものでも見れる！ - “設定ファイルを管理する”というコストがゼロ - もちろんデプロイも不要 デメリット - mo を入れないといけない - ローカルに md が存在している必要がある - ドキュメントリンクというものが存在しない（ localhost ） 41
42. © teamLab Inc. mo を使ってみる mo を入れないといけない, ローカルに md が存在している必要がある 受け入れるしか無い エンジニアは見れるけど、カタリストとかテスターは見れない ドキュメントリンクというものが存在しない 「このページだよー」が出来ない 起動ポートを固定 & hosts で http://localdoc.com とかで起動できるようにすれば... 42
43. © teamLab Inc. 43 ドキュメントを HTML で見たいだけ という目的には最適！
44. © teamLab Inc. 44 チーム運用 制約, 仕組みづくり が発生する
45. © teamLab Inc. 自作したらどれぐらいの難易度？ やってみた 45
46. © teamLab Inc. 自作したらどれぐらいの難易度？やってみた 作るもの - 素の md を html で表示できる - CommonMark + GFM - mdx 未サポート - 独自記法は作らない - frontmatter 対応 - SSG で HTML が吐き出される - 設定ファイルは不要 - npm ライブラリとして配布できる状態 - html 生成処理はコマンド実行 46
47. © teamLab Inc. 自作したらどれぐらいの難易度？やってみた 47 https://codesandbox.io/p/github/takuma-ru/mdhm.cli/main
48. © teamLab Inc. 自作したらどれぐらいの難易度？やってみた 所感 メリット - できちゃった笑 - これが一番の理想形 - 金子的最適解 - 500行弱ぐらいでいける デメリット - 設定ファイルは無いけど、出力設定は必要（どうしても） 48
49. © teamLab Inc. 自作したらどれぐらいの難易度？やってみた インストールすれば使えるのでぜひ！ npm : https://www.npmjs.com/package/mdhm.cli GitHub : https://github.com/takuma-ru/mdhm.cli 49 npm install mdhm.cli mdhm dev --root-dir docs --out-dir docs/dist
50. © teamLab Inc. ただドキュメントを HTML でみるだけなら？ 50
51. © teamLab Inc. ただドキュメントを HTML でみるだけなら？ 個人的には 51
52. © teamLab Inc. ただドキュメントを HTML でみるだけなら？ 個人的には k1LoW/mo → 保守の必要なし（ドキュメントのためのファイルがない） 52
53. © teamLab Inc. ただドキュメントを HTML でみるだけなら？ 個人的には k1LoW/mo → 保守の必要なし（ドキュメントのためのファイルがない） → リッチすぎない UI 53
54. © teamLab Inc. ただドキュメントを HTML でみるだけなら？ 個人的には k1LoW/mo → 保守の必要なし（ドキュメントのためのファイルがない） → リッチすぎない UI → いくつかのデメリットも簡単な仕組み化で解決できる 54
55. © teamLab Inc. ただドキュメントを HTML でみるだけなら？ Docsify は？ Hosting するときの最小構成かも！ Vitepress 系は？ SEO や Agent を考慮する場合はいいかも！（SSG ができるので） 不特定多数に見られる場合もおすすめ？ 今なら簡単に自作もできる 55
56. © teamlab Inc. 金子 巧磨 チームラボ パッケージチーム 所属 僕はただドキュメントを HTML で見たいだけなんだ teamLab Study Session ~frontend~ #3 ありがとうございました！