Summary
この記事では、静的サイトジェネレーター「Docsaurus」を使った、軽量で汎用的なドキュメント管理をご紹介します。
Docusaurusの公式サイト
こんな人向け
- ドキュメント管理のツール色々試したけど、どれもしっくりこない
- Notionだと誰でもサクッと更新できるからミスが怖い
- GitHubのwikiだと見栄えが微妙
- wordpressみたいなDBありのものは運用が大変
- 静的サイトジェネレーターもいい感じのものが多いけど、ちょっと使いにくい
こんなことできるようになります
- 静的サイトジェネレーターを使ったドキュメント管理
- Docsaurusはドキュメント管理をテーマにしたSSGなのでUIが素敵
- GitLabの無料ホスティングサービスPagesを使うのでサーバーの契約が不要（つまり無料
- mainにマージされた時にGitLabCICDで自動デプロイされるのでデプロイの手間がない
- マークダウンでドキュメント管理
ポイント
1. Metaが開発運用
- DosaurusはMeta社が開発して運用してくれてるものです。
- なので、かなり作り込まれていて使いやすい。
2. ドキュメント管理のための素敵なUI
- Docsaurusは、ドキュメント管理をテーマにしているだけあって、必要十分な機能と素敵なデザインです。
- 最初から、チュートリアルとブログという２つのリンクやサンプル記事があります。
- これだけでも十分すぎる機能ですよね。
3. GitLabで無料ホスティング
- これはDocsaurusというか私個人が思いついたやり方なのですが。。。
- 静的サイトジェネレーターなのでビルド成果物は純粋なhtmlですよね。
- なので、GitLabのホスティングサービスを使って無料で公開します。
4. ビルド成果物はGit管理しない
- ビルドしたものはGit管理に含めていません。
- 「じゃあ、何をホスティングしているの？」っていう感じですよね。
- GitLabCICDでビルドし、GitLabのコンテナ内に生成されたビルド成果物を直接ホスティングしています。
- なので、Git管理されていないビルド成果物が公開されていることになります。
- これって、あんまりない運用かもしれませんが、個人的にイケてるポイントです。（SSGならではじゃないですか？
さあ、始めよう。
git clone git@gitlab.com:share292508/docsaurus-gitlab-publishing.git
# 👆このリポジトリは僕が公開しているDocusaurusの環境をDockerで作ったものです
git rm .git
git init
git remote add origin {{あなたのGitLabリポジトリURL}}
git add .
git commit -m'Docsaurusを使ったSSG'
git push origin main
そう、これだけです。
👆のコマンドを打てば、こんな感じでサイトをリリースできます。
これだけで、あなたのGitLabリポジトリでサイトをリリースできます。
もしかしたら、何かエラーなどで詰まるかもしれませんので、その時はこの記事にコメントする形で教えていただければ嬉しいです！
それと、「ここもっとこうしたら良いんじゃないかな」っていうアドバイスや改善のアイディアもいつでもお待ちしておりますー。
経緯
Docsaurusを使おう！と思ったきっかけは、実はtypescriptとReactを勉強したかったからです。
業務でこの子達を使うことになり、ハンズオンで動かしながらやってみたいと思ったのですが、どうせならフロントの技術をまるっと学びたいなと。
そこで静的サイトジェネレーターを探していたら、Docsaurusを見つけました。
ちょうど、自分用でガイドラインみたいなサイトを作りたいな〜なんて思っていたので使ってみた。
そうすると、少ないコマンドでサクッとサイトを立ち上げることができました。
他のSSGに比べてもかなり簡単でわかりやすかった気がします。
ここら辺にMetaのエンジニアさんたちの優秀さが伺えますね。
実は選べる、typescipt
cloneしたリポジトリはtypesciptが設定してあるのですが、「そんなの知らねーよ」って人のためにDocsaurusはjavasriptのみでの構築オプションもあります。
プロジェクト作成時にjavascript|typescriptと選べるので、ご自身でプロジェクトを作成し、選択してみてください。
最後に
よくウェブサイトを作るのですが、Wordpressだと重い、HTMLだと軽すぎると思っていました。
特に、数は多くないけどコンテンツを管理したい。っていう場面が結構あるんですよね。
そんな時に、このジェネレーターに出会いました。
いや〜必要十分な機能とすっきりしたデザインなので大好きです。
特に、チュートリアルページの下の方に、「前の記事」「後の記事」みたいなボタンが出てくるのが大好きです。
これから愛用していきます。
追記
限定公開のドキュメントも公開できるよ
- 上記の作業をGitLabのプライベートリポジトリ（日公開リポジトリ）でやれば、ページは公開されるのですが、リポジトリにアクセス権のあるユーザーのみ表示させることができます。
- こっちの方が内部ドキュメントとしては安心ですね。