こんにちは。現場で泥臭く、かつ優雅にコードを書いているエンジニアです。
今日は、多くの開発者が「ブラウザ上のフォームでポチポチ編集するもの」と勘違いしているGitLab Wikiの真の姿を解き明かします。
実はGitLab Wikiの正体は、あなたのプロジェクトと同じ「Gitリポジトリ」です。つまり、VS Codeで快適に執筆し、Gitコマンドで履歴を管理し、CI/CDでドキュメントを自動ビルドすることも可能なのです。
この「Wikiをコードとして扱う（Docs as Code）」アプローチをマスターすれば、ドキュメント作成のストレスはゼロになり、開発のスピードは劇的に加速します。一緒に見ていきましょう。
—
1. GitLab Wikiの「正体」を理解する
GitLabのWikiページを開き、右側のサイドバーを見てください。「Clone repository」というボタンがあるはずです。これをクリックしてURLをコピーしてください。
そう、GitLab Wikiは独立したGitリポジトリとして存在しています。
- ブラウザ編集: 手軽だが、レビューも履歴管理も貧弱。
- Git連携: VS Codeの強力な補完、拡張機能、マージリクエストを通したレビューが可能。
今回は後者の「プロの運用」を目指します。
—
2. 環境構築：VS Codeとの接続
まずは、ローカルのPCにWikiリポジトリを持ってきましょう。
1. VS Codeを開き、ターミナルで以下のコマンドを実行します。
# プロジェクトのWikiリポジトリをクローン
git clone <コピーしたWikiのURL> my-project-wiki
cd my-project-wiki
2. 推奨拡張機能のインストール:
VS Codeの拡張機能で「Markdown All in One」を入れてください。目次生成やプレビューが爆速になります。
これだけで、あなたのローカル環境が「GitLab Wiki専用の執筆スタジオ」に変わりました。
—
3. ハローワールド：最初の変更を同期する
まずは一番簡単な更新を試しましょう。
1. `Home.md` を作成（または編集）します。
2. VS Codeで以下のように記述します。
# プロジェクトWikiへようこそ
これはローカルのVS Codeから追記しています！
3. Gitでコミット＆プッシュします。
git add .
git commit -m “docs: 最初のドキュメント更新”
git push origin master
4. GitLabのWikiページをリロードしてみてください。ブラウザを開かずに内容が更新されているはずです。これがDocs as Codeの第一歩です。
—
4. 【極限の最適化】CI/CDによる自動化術
ここからが本題です。Wikiを単なるメモ帳で終わらせず、「CI/CDで検証・公開する」というエンジニアの魂を込めた運用へ昇華させます。
例えば、「Wiki内のリンク切れをCIで検知する」仕組みを導入しましょう。
`.gitlab-ci.yml` の設定
Wikiリポジトリのルートに `.gitlab-ci.yml` を作成します（WikiリポジトリでもCIは動かせます！）。
stages:
- test
リンク切れチェック用のジョブ
check-links:
image: node:latest
script:
- npm install -g markdown-link-check
- find . -name “.md” -print0 | xargs -0 markdown-link-check
# リンク切れがあればCIを失敗させ、修正を促す
allow_failure: false
これにより、誰かが間違ったリンクを貼っても、プッシュした瞬間にCIが「警告」を出してくれます。これぞDevOpsの真骨頂です。
—
5. なぜこの方法が「最強」なのか
私がこのワークフローを強く勧める理由は3つあります。
1. レビューの民主化: Wikiの変更もマージリクエスト（MR）経由で行う運用にすれば、チーム全員でドキュメントの品質を担保できます。
2. オフライン執筆: 電波のない飛行機の中でも、VS Codeさえあればドキュメントを書き溜められます。
3. CI/CDの恩恵: 上記のように、ドキュメントの整合性チェックを自動化できます。人間が目視でチェックする時代は終わりました。
—
最後に：先輩エンジニアからのアドバイス
ドキュメントは「書いた瞬間から腐る」と言われます。しかし、Gitで管理し、CIでテストし、VS Codeで快適に書く環境を作れば、ドキュメントは「開発プロセスの一部」として生き続けます。
まずは今日、ローカルにクローンするところから始めてみてください。あなたのドキュメント管理が、劇的に楽になることを保証します。
何か詰まったら、いつでも聞いてくださいね。現場の壁を一緒に乗り越えていきましょう！