GitLab Wiki の使い方・入門ガイド – Markdownで簡単wiki作成

By /

はい、承知いたしました。GitLab WikiをMarkdownで利用する方法に焦点を当て、入門から応用までを網羅した約5000語の詳細な記事を作成します。記事本文を直接表示します。

GitLab Wiki の使い方・入門ガイド – Markdownで簡単wiki作成

GitLab プロジェクトでドキュメントや情報を管理する際に、手軽で強力なツールとなるのが Wiki 機能です。特に、シンプルで扱いやすい Markdown 形式で記述できるため、開発者だけでなく様々なチームメンバーが協力して情報を整理するのに適しています。

本記事では、GitLab Wiki の基本的な使い方から、Markdown による効率的なコンテンツ作成、さらには高度な活用方法まで、詳細かつ網羅的に解説します。GitLab Wiki を使って、プロジェクトの知識共有を加速させましょう。

第1章: GitLab Wiki とは？ なぜ使うべきか

1.1 GitLab Wiki の概要

GitLab Wiki は、GitLab の各プロジェクトに組み込まれているドキュメント作成・管理ツールです。プロジェクトのソースコードや Issue と密接に連携しており、プロジェクトに関するあらゆる情報を一元管理するのに役立ちます。

Wiki は一般的に、共同でドキュメントを作成・編集するための Web ベースのシステムを指しますが、GitLab Wiki の最大の特徴は、そのコンテンツが Git リポジトリとして管理される点にあります。これにより、以下のようなメリットが生まれます。

  • バージョン管理: すべてのページ変更がコミットとして記録されるため、いつでも過去の状態に戻したり、変更履歴を確認したりできます。これは、ドキュメントの信頼性を高め、共同編集時のコンフリクト解決にも役立ちます。
  • ローカルでの編集: Git クライアントを使用して Wiki リポジトリをローカルにクローンし、慣れたエディタでオフライン編集が可能です。変更は通常の Git ワークフロー（コミット、プッシュ）で反映できます。
  • アクセス制御: プロジェクトのアクセス権限設定が Wiki にも適用されるため、誰が Wiki を閲覧・編集できるかをプロジェクトレベルで管理できます。

1.2 なぜプロジェクトで Wiki を使うべきか？

GitLab Wiki は、以下のような様々な目的で利用できます。

  • プロジェクトの知識ベース: プロジェクトの概要、セットアップ手順、アーキテクチャ、設計思想、意思決定の記録などを集約します。新しいメンバーのオンボーディングにも役立ちます。
  • 技術ドキュメント: API 仕様、コーディング規約、テスト手順などを整備します。Markdown はコードの表示にも適しているため、開発者間の情報共有に最適です。
  • 会議の議事録: 会議の議題、決定事項、To-Do リストなどを記録し、プロジェクトメンバー全体で共有します。
  • ブレインストーミングやアイデア出し: プロジェクトに関するアイデアや検討事項を気軽に書き出し、整理する場として利用できます。
  • タスクリストやチェックリスト: プロジェクト進行上のタスクや確認事項をリストアップし、進捗を管理します。
  • FAQ (よくある質問): プロジェクトに関するよくある質問とその回答をまとめ、自己解決を促進します。

Wiki を使うことの最大のメリットは、情報がサイロ化せず、プロジェクトメンバー全員が同じ場所で最新の情報を参照・更新できる点です。これにより、コミュニケーションロスが減り、プロジェクトの効率が向上します。Issue やマージリクエストだけでは残しきれない、より構造化された、あるいは永続的な情報を記録するのに Wiki は非常に適しています。

1.3 Wiki と他のドキュメントツールの違い

  • Issue / Merge Request の説明欄: 特定のタスクや変更に関する議論・情報共有には適していますが、プロジェクト全体の知識ベースとしては構造化しにくいです。
  • 外部ドキュメントツール (Confluence, Notion など): 機能豊富なものが多いですが、GitLab プロジェクトから離れてしまうため、文脈の切り替えが発生します。GitLab Wiki はプロジェクトに統合されているため、コードや Issue との連携がスムーズです。
  • コード内のコメント/ドキュメンテーション: コード自体の説明には必須ですが、プロジェクト全体の概要や設計など、コードから離れた情報を記述するのには向きません。
  • Git リポジトリ内のドキュメントファイル (.md, .txt など): ドキュメント自体もバージョン管理されますが、Web UI での閲覧性や編集の容易さ、ナビゲーションのカスタマイズ性では Wiki が優れています。Wiki は Git リポジトリの上に Wiki 機能の UI レイヤーが載っていると考えると理解しやすいでしょう。

これらのツールはそれぞれ得意なことが異なるため、GitLab プロジェクトでは Wiki を中心に据えつつ、他のツールと組み合わせて利用するのが最も効果的です。

第2章: Wiki へのアクセスと基本操作

GitLab Wiki を使い始めるのは非常に簡単です。ここでは、Wiki へのアクセス方法と基本的なページ操作を解説します。

2.1 Wiki へのアクセス

GitLab プロジェクトページに移動し、左サイドバーにあるメニューから「Wiki」を探してクリックします。

  • もし Wiki がまだ作成されていない場合、初回アクセス時には Wiki の作成を促すページが表示されます。
  • Wiki がすでに存在する場合、Wiki のホームページ（Home ページ）が表示されます。

2.2 Wiki のホームページ (Home Page)

すべての Wiki には、デフォルトで「Home」という名前のページが作成されます。これが Wiki のエントリポイントとなります。プロジェクトの概要や Wiki の使い方など、最初に見てほしい情報をここに記述するのが一般的です。

  • 初回アクセス: Wiki がない場合、「Create your first page」のようなボタンが表示されます。これをクリックすると、Home ページの編集画面が開きます。
  • 既存の Wiki: Home ページの内容が表示されます。右上の「Edit」ボタンをクリックすると編集できます。

2.3 新しいページの作成

Wiki に新しいページを作成する方法はいくつかあります。

2.3.1 Web UI から作成する

  1. Wiki ページを表示している状態で、右上の「New page」ボタンをクリックします。
  2. 「New page」画面が表示されます。
  3. Page title: ページのタイトルを入力します。このタイトルが、Wiki 内でのページ名（ファイル名に相当）や、リンクを作成する際の識別子となります。例えば、「Project Setup Guide」と入力します。
  4. Content: ページの本文を Markdown 形式で記述します。
  5. Commit message: 変更内容を示すコミットメッセージを入力します。「Add ‘Project Setup Guide’ page」のように、簡潔に内容がわかるように記述します。
  6. 「Create page」ボタンをクリックします。

これで新しいページが作成され、Wiki に追加されます。

2.3.2 既存のページからリンクを作成して作成する

Wiki 内でまだ存在しないページへのリンクを作成し、そのリンクをクリックしてページを作成することもできます。例えば、既存のページに [[新しいページ]] のようにリンクを記述して保存すると、「新しいページ」というリンクが表示されます。このリンクは最初は赤色や点線で表示され、ページがまだ存在しないことを示します。このリンクをクリックすると、「新しいページ」というタイトルの新規作成画面に遷移します。

この方法は、情報を記述しながら、関連するがまだ存在しないトピックへのリンクを貼り、後でそのページを作成するというワークフローに適しています。

2.4 ページの編集

既存のページを編集するには：

  1. 編集したい Wiki ページを表示します。
  2. ページ右上の「Edit」ボタンをクリックします。
  3. 編集画面で Markdown コンテンツを修正します。
  4. Content の下にある「Commit message」に、どのような変更を行ったかを記述します。（例: 「Update setup steps」, 「Fix typo in README」）
  5. 「Save changes」ボタンをクリックします。

これでページの変更が保存され、新しいバージョンとして履歴に残ります。

2.5 ページの削除

ページの編集画面で、左下にある「Delete page」ボタンをクリックすると、そのページを削除できます。削除時もコミットメッセージの入力が求められます。

2.6 ページの履歴 (History)

GitLab Wiki の大きな利点はバージョン管理されていることです。各ページの変更履歴を確認するには：

  1. 履歴を見たい Wiki ページを表示します。
  2. ページ右上の「History」ボタンをクリックします。

これにより、そのページのすべてのコミット履歴が表示されます。各コミットについて、誰がいつ変更したか、そして「Change」ボタンをクリックすることでそのコミットで具体的にどの行がどのように変更されたか（Diff）を確認できます。古いバージョンに戻したい場合は、履歴から該当するコミットを選び、「Revert」ボタンをクリックすることでその状態に差し戻すことができます。

2.7 ページの検索

Wiki 内の情報を検索するには、GitLab のプロジェクト検索機能を利用します。プロジェクトページの検索バーにキーワードを入力し、結果を「Wiki」で絞り込むか、Wiki ページ表示中に検索バーを利用します。

第3章: Markdown 入門: GitLab Wiki での基本

GitLab Wiki のコンテンツは Markdown 形式で記述するのが標準です。Markdown は、特別なツールを使わずにプレーンテキストで書かれたドキュメントを、簡単に見出しやリスト、リンクなどの構造を持った HTML に変換するための軽量なマークアップ言語です。

ここでは、GitLab Wiki でよく利用される基本的な Markdown 構文を解説します。

3.1 Markdown とは？ なぜ Wiki に適しているのか？

Markdown は、John Gruber によって開発された記法です。その設計思想は「読みやすく書きやすいプレーンテキスト形式であること」にあります。HTML のようなタグは使わず、記号（#, *, -, > など）を使って見出しやリスト、強調などを表現します。

GitLab Wiki が Markdown を採用している理由は以下の通りです。

  • 習得が容易: 基本的な記法は非常にシンプルで、短時間で習得できます。
  • 読みやすさ: マークアップされていてもプレーンテキストとして読めるため、ソースの状態でも内容を把握しやすいです。
  • 書きやすさ: キーボードから手を離さずに素早く記述できます。
  • バージョン管理との親和性: プレーンテキストなので、Git による差分管理（Diff）が見やすいです。共同編集時のコンフリクトも比較的解決しやすいです。
  • 幅広いツールとの連携: Markdown は非常にポピュラーな形式であり、多くのエディタやツールが対応しています。

3.2 基本的な Markdown 構文

3.2.1 見出し (Headings)

行の先頭に # をつけることで見出しを作成できます。# の数が多いほど、小さい見出しになります。

“`markdown

これは一番大きな見出しです (H1)

これは二番目の見出しです (H2)

これは三番目の見出しです (H3)

これは四番目の見出しです (H4)

これは五番目の見出しです (H5)
これは六番目の見出しです (H6)

“`

表示例:

これは一番大きな見出しです (H1)

これは二番目の見出しです (H2)

これは三番目の見出しです (H3)

これは四番目の見出しです (H4)

これは五番目の見出しです (H5)
これは六番目の見出しです (H6)

GitLab Wiki では、通常 # H1 はページタイトルとして使用されるため、本文中では ## H2 以下から始めるのが一般的です。

3.2.2 段落 (Paragraphs)

段落は、1行以上のテキストを記述し、空行で区切ることで作成されます。

“`markdown
これは最初の段落です。
特に何もマークアップされていない通常のテキストです。

ここは空行で区切られているため、新しい段落になります。
ドキュメントの構造を分かりやすくするために、段落は重要です。
“`

表示例:

これは最初の段落です。
特に何もマークアップされていない通常のテキストです。

ここは空行で区切られているため、新しい段落になります。
ドキュメントの構造を分かりやすくするために、段落は重要です。

3.2.3 改行 (Line Breaks)

Markdown では、行末でEnterキーを押すだけでは改行として表示されない場合があります。意図的に改行するには、行末にスペースを2つ以上入力するか、<br> タグを使用します。

“`markdown
これは最初の行です。
これは次の行です（行末にスペース2つ）。

これは段落が分かれています。

これは
改行タグ
を使った例です。
“`

表示例:

これは最初の行です。
これは次の行です（行末にスペース2つ）。

これは段落が分かれています。

これは
改行タグ
を使った例です。

3.2.4 強調 (Emphasis)

文字を太字や斜体にできます。

  • 斜体 (Italic): アンダースコア (_) またはアスタリスク (*) で囲みます。
    markdown
    _斜体_ または *これも斜体*
    表示例: 斜体 または これも斜体

  • 太字 (Bold): ダブルアンダースコア (__) またはダブルアスタリスク (**) で囲みます。
    markdown
    __太字__ または **これも太字**
    表示例: 太字 または これも太字

  • 太字と斜体 (Bold and Italic): トリプルアンダースコア (___) またはトリプルアスタリスク (***) で囲みます。
    markdown
    ___太字と斜体___ または ***これも太字と斜体***
    表示例: 太字と斜体 または これも太字と斜体

3.2.5 リスト (Lists)

項目を列挙する際に使用します。

  • 順序なしリスト (Unordered List): 行頭に -, *, または + とスペースを置きます。
    “`markdown

    • 項目1
    • 項目2
    • ネストされた項目2.1
    • ネストされた項目2.2
    • 項目3
      “`
      表示例:
    • 項目1
    • 項目2
      • ネストされた項目2.1
      • ネストされた項目2.2
    • 項目3

  • 順序付きリスト (Ordered List): 行頭に数字とピリオド、スペースを置きます。数字は連番でなくても構いませんが、1から始めるのが一般的です。
    “`markdown

    1. 最初のステップ
    2. 次のステップ
    3. 最後のステップ
      “`
      表示例:
    4. 最初のステップ
    5. 次のステップ
    6. 最後のステップ

3.2.6 リンク (Links)

他のページや外部サイトへのリンクを作成します。

  • インラインリンク: [リンクテキスト](URL または ページ名) の形式です。
    markdown
    これは [GitLab 公式サイト](https://about.gitlab.com/) へのリンクです。
    表示例: これは GitLab 公式サイト へのリンクです。

  • Wiki ページへのリンク:

    • ページ名のみ: [[ページ名]] の形式。ページ名がリンクテキストになります。
    • リンクテキストを指定: [[リンクテキスト|ページ名]] の形式。

    markdown
    [[Home]] ページへのリンク
    [[プロジェクトセットアップガイド|Project Setup Guide]] へのリンク
    表示例:
    [[Home]] ページへのリンク
    [[プロジェクトセットアップガイド|Project Setup Guide]] へのリンク

    GitLab Wiki では、ページ名の代わりにファイルパス（例: subfolder/page-name）も指定できます。これについては後述します。

3.2.7 画像 (Images)

画像を挿入します。構文はリンクに似ていますが、行頭に ! がつきます。

markdown
![代替テキスト](画像URL または 画像ファイル名)

  • 代替テキスト は、画像が表示されない場合に代わりに表示されるテキストです。スクリーンリーダーもこのテキストを読み上げます。
  • 画像URL または 画像ファイル名 は、画像ファイルへのパスまたは URL です。GitLab Wiki にアップロードしたファイルの場合はファイル名またはパスを指定します。

markdown
プロジェクトロゴ: ![Project Logo](logo.png)
GitLab の画像: ![GitLab CI Logo](https://about.gitlab.com/images/press/logo/png/gitlab-logo-gray-rgb.png)

表示例:
プロジェクトロゴ: Project Logo
GitLab の画像: GitLab CI Logo

GitLab Wiki に画像をアップロードする方法については、後述の「ファイルのアップロード」セクションで詳しく解説します。

3.2.8 コード (Code)

コードの一部やコマンドなどを表示する際に使用します。

  • インラインコード: バッククォート (`) で囲みます。
    markdown
    これは `git status` コマンドです。
    表示例: これは git status コマンドです。

  • コードブロック: 3つのバッククォート () で囲みます。最初の の後に言語名（ruby, python, javascript, bash, markdown, yaml など）を指定すると、シンタックスハイライトが有効になります。
    markdownpython
    def hello_world():
    print(“Hello, Wiki!”)
    “`

    bash
    git clone <repository_url>
    cd <repository_name>
    “`markdown

    Wiki 見出し

    • リスト項目

      単なるテキストブロック
      シンタックスハイライトなし

表示例:

python
def hello_world():
print("Hello, Wiki!")

bash
git clone <repository_url>
cd <repository_name>

“`markdown

Wiki 見出し

  • リスト項目
    “`

単なるテキストブロック
シンタックスハイライトなし

コードブロックは、手順や設定例、スニペットなどを共有するのに非常に便利です。

3.2.9 引用 (Blockquotes)

他からの引用や、特定の注意書きなどを表現するのに使います。行頭に > を置きます。

“`markdown

これは引用ブロックです。
複数の行にまたがることができます。

ネストされた引用も可能です。

  • リストも使えます
  • 別の項目
    “`

表示例:

これは引用ブロックです。
複数の行にまたがることができます。

ネストされた引用も可能です。

  • リストも使えます
  • 別の項目

3.2.10 区切り線 (Horizontal Rule)

テーマの区切りやセクションの分割を示す水平線を作成します。3つ以上の *, -, または _ を単独の行に置きます。

“`markdown
これは最初のセクションです。

これは次のセクションです。

これは別のセクションです。
“`

表示例:

これは最初のセクションです。

これは次のセクションです。

これは別のセクションです。

3.2.11 テーブル (Tables)

表を作成します。ヘッダー行とデータ行、そしてそれらを区切る区切り行 (---) で構成されます。列は | で区切ります。

markdown
| ヘッダー1 | ヘッダー2 | ヘッダー3 |
|---|:---:|---:|
| 左寄せセル | 中央寄せセル | 右寄せセル |
| データA | データB | データC |

区切り行 (|---|:---:|---:|) は、列の配置を指定します。
* --- または ---| または |--- : 左寄せ (デフォルト)
* :---: : 中央寄せ
* ---: : 右寄せ

表示例:

ヘッダー1 ヘッダー2 ヘッダー3
左寄せセル 中央寄せセル 右寄せセル
データA データB データC

Markdown のテーブル記法は少し手作業感がありますが、シンプルな表であれば十分に使えます。複雑な表には向いていません。

3.2.12 タスクリスト (Task Lists)

Issue や To-Do リストのようなチェック可能なリストを作成します。リスト項目の先頭に - [ ] または - [x] を置きます。

markdown
- [x] 最初のタスク (完了)
- [ ] 次のタスク (未完了)
- [ ] ネストされたタスク
- [x] 別の完了タスク

表示例:

  • [x] 最初のタスク (完了)
  • [ ] 次のタスク (未完了)
    • [ ] ネストされたタスク
  • [x] 別の完了タスク

これらのチェックボックスは、Wiki 上でクリックして状態を変更できます（ページを保存する必要があります）。

3.3 Markdown のプレビュー機能

GitLab Wiki の編集画面には、入力中の Markdown がどのように表示されるかを確認できるプレビュー機能があります。

編集画面の右側（またはタブ）にある「Preview」をクリックすると、記述した Markdown がレンダリングされた状態が表示されます。「Write」に戻るには「Write」をクリックします。

この機能を使うことで、保存する前に意図した通りに表示されるかを確認でき、記述ミスを防げます。

第4章: Wiki をさらに活用する Markdown テクニック

基本的な Markdown 構文に加えて、GitLab Wiki で特に役立つテクニックや構文を紹介します。

4.1 Wiki ページ間のリンク

前述の [[ページ名]] または [[リンクテキスト|ページ名]] 記法は非常に便利です。

  • 大文字・小文字: 通常、ページ名の大文字・小文字は区別されません。ただし、使用している GitLab のバージョンや設定によっては異なる場合があるため、正確なページ名を使うことを推奨します。
  • スペース: ページ名にスペースが含まれる場合も、そのまま [[ページ名]] と記述できます。
  • ファイル拡張子: Wiki ページは内部的には .md や .html などの拡張子を持つファイルとして保存されますが、リンクを作成する際に拡張子を記述する必要はありません。

4.2 サブページとパスを使ったリンク

Wiki では、スラッシュ (/) を使ってページの階層構造を作成できます。これにより、関連するページをグループ化し、Wiki の整理が容易になります。

例えば、「docs」というフォルダの下に「setup」と「usage」というページを作成したい場合：

  • 新しいページを作成する際に、タイトルに docs/setup と入力します。
  • もう一つ、「docs/usage」というページを作成します。

これで、「docs」という「フォルダ」の中に「setup」と「usage」というページが作成されたように見えます。

これらのページにリンクする場合も、パスを含めて指定できます。

markdown
[[docs/setup]] - セットアップ手順へのリンク
[[利用方法|docs/usage]] - 利用方法ガイドへのリンク

表示例:
[[docs/setup]] – セットアップ手順へのリンク
[[利用方法|docs/usage]] – 利用方法ガイドへのリンク

相対パスでリンクすることも可能です。例えば、「docs/setup」ページから同じ「docs」フォルダ内の「usage」ページにリンクする場合：

markdown
[利用方法](../usage)

または、明示的に ./usage とすることもありますが、GitLab Wiki では通常、パスを指定する場合は Wiki のルートからの絶対パス（スラッシュから始める必要はありません）または [[...]] 記法を使うのが最も安全で一般的です。

4.3 ファイルのアップロードと埋め込み

画像やその他のファイルを Wiki ページに添付したり、埋め込んだりすることができます。

  1. Wiki の編集画面を開きます。
  2. 編集エリアの上部にあるツールバーの、クリップのアイコン（添付ファイル）をクリックします。
  3. ファイルをアップロードするためのダイアログが表示されます。「ファイルを選択」をクリックして、アップロードしたいファイルを選びます。
  4. アップロードが完了すると、ファイルの URL または Markdown 記法が編集エリアに挿入されます。

例えば、my-image.png という画像をアップロードした場合、以下のような Markdown が挿入されます。

markdown
![my-image](uploads/xxxxxxxxxxxxxxxxxxxxxxxxxxxx/my-image.png)

uploads/xxxxxxxxxxxxxxxxxxxxxxxxxxxx/ の部分は、GitLab が生成する一意のパスです。この記法を使えば、画像が Wiki ページに埋め込まれて表示されます。

PDF や ZIP ファイルなどの画像以外のファイルをアップロードした場合も同様に Markdown リンクが生成されます。

markdown
[document.pdf](uploads/yyyyyyyyyyyyyyyyyyyyyyyyyyyy/document.pdf)

これにより、Wiki ページから直接ファイルをダウンロードするためのリンクを提供できます。

アップロードされたファイルは、Wiki の Git リポジトリ内の uploads/ ディレクトリ以下に保存されます。

4.4 目次 (Table of Contents) の自動生成

長い Wiki ページの場合、見出しから自動的に目次を生成するとナビゲーションが容易になります。GitLab Wiki は、ページ内の見出し (#, ##, …) を基に目次を生成する Markdown 拡張機能に対応しています。

目次を挿入したい場所に、以下の Markdown を記述します。

markdown
[[_TOC_]]

この文字列がある場所に、ページ内のすべての見出しへのリンクを含む目次が自動的にレンダリングされます。通常、ページの冒頭に配置するのが最も一般的です。

注意点: 目次生成機能は GitLab のバージョンに依存する場合があります。公式ドキュメントで確認するか、実際に試してみてください。

4.5 その他の便利な Markdown 拡張機能

GitLab は標準的な Markdown に加えて、いくつかの拡張機能に対応しています。

  • チェックボックス (Task Lists): 前述の通り、- [ ] や - [x] でタスクリストを作成できます。
  • 絵文字 (Emoji): :smile: のような記法で絵文字を表示できます。GitLab が対応している絵文字リストを参照してください。
    markdown
    プロジェクト成功！ :tada: :rocket:
    表示例: プロジェクト成功！ 🎉 🚀

  • 脚注 (Footnotes): テキストの最後に注釈を入れることができます。
    “`markdown
    これは注釈付きのテキストです^1。

    “`
    表示例: これは注釈付きのテキストです^1。

    • 定義リスト (Definition Lists): 用語とその定義をリスト化できます。
      “`markdown
      用語
      : 定義1
      : 定義2

    別の用語
    : その定義
    “`
    表示例:

    用語
    : 定義1
    : 定義2

    別の用語
    : その定義
    * HTML タグの利用: Markdown の中に直接 HTML タグを記述することも可能です。これにより、Markdown だけでは表現できない複雑なレイアウトや要素（例: ボタン、特定のスタイルを持つブロック）を挿入できます。ただし、セキュリティ上の理由から使用できるタグや属性には制限があります。過度な使用は Markdown の利点（読みやすさ、バージョン管理の容易さ）を損なうため、必要最小限に留めるのが良いでしょう。

これらの拡張機能を活用することで、より表現豊かで機能的な Wiki ページを作成できます。

第5章: GitLab Wiki の高度な機能とカスタマイズ

Wiki の利用が活発になってくると、情報の整理やナビゲーションが重要になります。ここでは、Wiki の構造を整理したり、より便利に利用するための高度な機能を紹介します。

5.1 サイドバーのカスタマイズ (_sidebar.md)

GitLab Wiki の左側には、デフォルトでページリストなどが表示されるサイドバーがあります。このサイドバーの内容は、特別な Markdown ファイルを編集することでカスタマイズできます。

プロジェクトの Wiki のルートに、「_sidebar.md」という名前のページを作成します。このページに記述した Markdown コンテンツが、Wiki のすべてのページのサイドバーとして表示されるようになります。

_sidebar.md の内容は、通常、以下のような形式で記述されます。

“`markdown
プロジェクト Wiki

  • [[Home]]
  • [[プロジェクト概要]]
  • [[セットアップ手順|setup]]
  • [[フロントエンドセットアップ|setup/frontend]]
  • [[バックエンドセットアップ|setup/backend]]
  • [[よくある質問|FAQ]]

関連リソース

ポイント:

  • Markdown のリスト (-) やリンク ([[...]] または [...]) を使って、ナビゲーションメニューを作成します。
  • [[ページ名]] の記法を使うと、Wiki 内のページへのリンクになります。パスを指定することも可能です ([[setup/frontend]])。
  • [...] 記法を使うと、外部サイトや GitLab プロジェクト内の他のセクション（Issue、リポジトリなど）へのリンクを作成できます。プロジェクト内の要素へのリンクは、相対パス (../-/issues) を使うと便利です。
  • 見出し (##) や太字 (**) を使って、サイドバーの項目をグループ化したり強調したりできます。
  • 区切り線 (---) でセクションを分けることも可能です。

_sidebar.md を活用することで、ユーザーが必要な情報に素早くアクセスできるようになり、Wiki の使いやすさが格段に向上します。Wiki の利用が増えてきたら、早い段階で _sidebar.md を整備することをお勧めします。

5.2 サブページによる階層構造

前述の「サブページとパスを使ったリンク」でも触れましたが、ページタイトルにスラッシュ (/) を含めることで、Wiki のページを階層化できます。これは、関連するページを整理し、Wiki 全体の構造を分かりやすくするために非常に重要です。

例えば、以下のようなページ構造を作成できます。

  • Home
  • Meetings/Agenda_2023-01-01
  • Meetings/Minutes_2023-01-01
  • Meetings/Agenda_2023-01-08
  • Meetings/Minutes_2023-01-08
  • Specifications/API_Design
  • Specifications/Database_Schema
  • Guides/Setup_Environment
  • Guides/Contribution_Guidelines

Web UI でページを閲覧する際には、パンくずリストが表示され、現在のページがどの階層にあるかが分かります（例: Home / Meetings / Minutes_2023-01-01）。

_sidebar.md でこの階層構造を反映したナビゲーションを作成すると、さらに使いやすくなります。

5.3 Wiki のクローンとローカルでの編集

Wiki のコンテンツは Git リポジトリとして管理されているため、通常の Git リポジトリと同様にローカルにクローンし、オフラインで編集することができます。これは、大量のページを一度に編集したり、複雑なツールを使って編集したりする場合に非常に便利です。

  1. Wiki リポジトリの URL を確認: Wiki ページを表示している状態で、右上の「Clone」ボタンをクリックします。HTTPS または SSH のクローン URL が表示されます。
  2. ローカルにクローン: ターミナルを開き、以下のコマンドを実行します。（ここでは HTTPS の例）
    bash
    git clone <HTTPS または SSH のクローンURL>
    例: git clone https://gitlab.com/your-group/your-project.wiki.git
  3. ローカルで編集: クローンしたディレクトリに移動し、好きなエディタで Markdown ファイル (.md) を編集します。サブページはディレクトリとして表現されます（例: meetings/Agenda_2023-01-01.md）。アップロードしたファイルは uploads/ ディレクトリ以下にあります。
  4. 変更をコミット: 編集が終わったら、Git コマンドで変更をステージングし、コミットします。
    bash
    git add .
    git commit -m "Add new guide page and update existing ones"
  5. リモートにプッシュ: 変更を GitLab にプッシュします。
    bash
    git push origin main # または master
    デフォルトブランチ名は main または master です。Wiki ページのデフォルトブランチはプロジェクトのデフォルトブランチ設定に依存します。

プッシュが成功すると、GitLab 上の Wiki に変更が反映されます。Web UI で編集した場合と同様に、すべての変更はコミット履歴として記録されます。

ローカルでの編集は、特に以下のような場合に有効です。

  • 複雑な表を含むページを作成・編集する場合（スプレッドシートソフトでデータを作成し、Markdown テーブルに変換するなど）
  • 複数のページにまたがる大規模な更新を行う場合
  • インターネット接続がない場所で作業する場合
  • 慣れたエディタや Markdown ツールを使いたい場合
  • Git のブランチ機能を使って、大規模な変更をレビューしてからマージしたい場合

5.4 ホームページの変更

デフォルトのホームページは「Home」ですが、別のページを Wiki のエントリポイントにしたい場合、そのページの名前をプロジェクトの設定で指定できます。

  1. プロジェクトの「Settings」>「General」に移動します。
  2. 「General project settings」を展開します。
  3. 「Wiki」セクションを見つけます。
  4. 「Home page」フィールドに、新しいホームページとして設定したい Wiki ページのタイトル（例: Introduction や Overview）を入力します。
  5. 「Save changes」をクリックします。

ただし、通常は「Home」ページをエントリポイントとして利用し、そこに主要な情報のリンクをまとめるのが分かりやすいため、この設定を変更する必要はあまりないかもしれません。

第6章: Wiki を効果的に使うためのヒントとベストプラクティス

GitLab Wiki を単なる情報の置き場にせず、チームの強力な知識共有ツールとして活用するためのヒントとベストプラクティスを紹介します。

6.1 一貫性のある命名規則と構造

Wiki ページが増えてくると、情報の探しやすさが重要になります。以下の点を意識しましょう。

  • 明確で具体的なページ名: ページの内容が推測できるような、具体的で短い名前をつけましょう。「いろいろ」や「メモ」のような曖昧な名前は避けます。
  • スラッシュを使った階層化: 関連するページはサブページとしてまとめることで、Wiki 全体の構造が整理されます。「Guides/Setup」「Guides/Deployment」のように、カテゴリごとにディレクトリを作成します。
  • ファイル名の規約: ローカルで編集することを考慮すると、ファイル名（ページ名）にはスペースや日本語を使わない方が無難な場合があります。_ や - を区切りに使うのが一般的です（例: project_setup_guide, api-specifications）。Web UI では日本語やスペースも使えますが、Git レベルでの扱いで問題が発生する可能性もゼロではありません。
  • Home ページの活用: Home ページを Wiki の総合案内所として活用します。主要なカテゴリや重要なページへのリンクを Home ページに集約することで、ユーザーはそこから情報を探し始められます。
  • _sidebar.md の活用: ナビゲーションのカスタマイズは、Wiki の使いやすさに直結します。主要なページや頻繁にアクセスされるページへのリンクをサイドバーに配置しましょう。

6.2 コンテンツの品質と鮮度

  • 正確性と最新性: Wiki の情報は常に正確で最新の状態に保つことが非常に重要です。古い情報や誤った情報は、プロジェクトの進行を妨げる可能性があります。
  • 担当者の明確化: 重要な Wiki ページには、そのページの責任者や更新担当者を明記しておくと、情報が古くなった場合に誰に確認すればよいかが分かります。
  • 定期的なレビュー: 定期的に Wiki のコンテンツ全体をレビューする機会を設けるか、関連するタスク（例: リリース、機能開発完了など）の完了時に Wiki の更新をプロセスに組み込むようにしましょう。
  • 情報の粒度: 一つのページにすべての情報を詰め込むのではなく、適切な粒度でページを分けましょう。長すぎるページは読みにくく、特定の情報を見つけにくくなります。
  • 不要なページの整理: 使われなくなった古いページは、アーカイブするか削除することで、Wiki 全体をシンプルに保ちます。削除する前に、本当に不要か、履歴として残しておくだけで十分かなどを検討しましょう。

6.3 Markdown の効果的な使い方

  • 構造化: 見出しを使ってページの構造を明確にします。自動目次 ([[_TOC_]]) の活用も有効です。
  • 強調とリスト: 太字や斜体、リストを使って重要な箇所を強調したり、手順を分かりやすく示したりします。
  • コードブロック: コード、コマンド、設定ファイルなどは必ずコードブロックで表示します。シンタックスハイライトを指定するとさらに見やすくなります。
  • リンクの活用: 関連する Wiki ページ間は積極的にリンクを貼ることで、情報のネットワークを構築します。GitLab の Issue や Merge Request、コードへのリンクも活用しましょう。
  • 画像の活用: スクリーンショットや図などを適切に挿入することで、テキストだけでは伝わりにくい情報を補足できます。

6.4 共同編集の促進と管理

  • 編集しやすい文化: Wiki は「誰でも編集して良い」というオープンな文化を醸成することが理想です。完璧を目指すよりも、まずは情報を書き出すことを奨励します。
  • コミットメッセージ: 変更を保存する際には、どのような意図で、どのような変更を行ったのかを明確に記述したコミットメッセージを残しましょう。これは変更履歴を追う際に非常に役立ちます。
  • 変更履歴の確認: ページの変更履歴はいつでも確認できます。意図しない変更や問題が発生した場合は、履歴を遡って原因を特定したり、古いバージョンに戻したりできます。
  • マージリクエストを利用した編集フロー: 大規模な変更や重要なドキュメントの編集を行う場合は、ローカルで Wiki リポジトリをクローンし、フィーチャーブランチを作成して編集を行い、マージリクエストを作成してチームメンバーにレビューを依頼するという、コード開発と同様のワークフローを採用することも可能です。これにより、変更内容のレビューや議論を経てから本流に取り込むことができます。
  • コンフリクトの解決: 複数の人が同時に同じページを編集し、プッシュする際にコンフリクトが発生することがあります。GitLab の Web UI やローカルでの Git 操作でコンフリクトを解決する必要があります。Wiki のコンフリクト解決は、通常のコードのコンフリクト解決と同様の方法で行います。

6.5 Wiki をどこに置くか？ (プロジェクト vs グループ)

GitLab では、プロジェクトごとに Wiki を持つのが基本ですが、グループレベルで Wiki 機能を持つプラン（GitLab Premium 以降）もあります。

  • プロジェクト Wiki: 特定のプロジェクトに関する情報を管理するのに適しています。ほとんどのケースでこれで十分です。
  • グループ Wiki: グループ内の複数のプロジェクトに共通する情報（グループ全体の開発規約、ツール、オンボーディング資料など）を管理するのに適しています。グループ内のすべてのプロジェクトから参照できる単一の情報源を作成できます。

組織の構造や情報の性質に応じて、適切な場所に Wiki を作成・配置しましょう。

第7章: よくある問題とトラブルシューティング

GitLab Wiki の利用中によく遭遇する可能性のある問題とその解決策をいくつか紹介します。

7.1 Markdown が正しくレンダリングされない

  • 構文の確認: Markdown 記法に間違いがないか、一文字一句確認します。特に、スペースやタブの有無、記号の種類（ハイフン - とアスタリスク * など）、バッククォートの数などを注意深く見ます。
  • 空行の確認: 段落やブロック要素（コードブロック、引用など）の間には空行が必要です。空行がないと意図した通りに表示されないことがあります。
  • Markdown 拡張機能の確認: 使用している記法が、GitLab がサポートしている Markdown 拡張機能であるか確認します。一般的な Markdown 記法はほぼ網羅されていますが、特定の高度な記法はサポートされていない場合があります。
  • プレビュー機能の活用: 編集画面のプレビュー機能を使って、記述と表示結果をリアルタイムで比較確認しましょう。

7.2 Wiki ページへのリンクが機能しない

  • ページ名の正確性: リンク先のページ名（またはパス）が正確か確認します。大文字・小文字は通常区別されませんが、完全に一致しているか再確認します。
  • サブページへのリンク: サブページへのリンクは、Wiki のルートからの相対パスではなく、ページタイトル全体（例: docs/setup）を使用するのが最も確実です。[[docs/setup]] または [セットアップ手順](docs/setup) の形式を使います。
  • 削除されたページ: リンク先のページが削除されていないか確認します。削除されたページへのリンクは機能しません。
  • 特殊文字: ページ名に特殊文字が含まれる場合、リンク記法で問題が発生する可能性があります。できるだけ英数字とハイフン、アンダースコアなどでページ名を構成することをおすすめします。

7.3 ファイルがアップロードできない、または表示されない

  • ファイルサイズの制限: GitLab にはファイルアップロードサイズの上限があります。大きすぎるファイルはアップロードできません。
  • プロジェクトのストレージ容量: プロジェクト全体のストレージ容量制限に達している場合、ファイルのアップロードを含む Git リポジトリへのプッシュができなくなることがあります。
  • アップロードパスの確認: 画像などを埋め込む際に、Markdown 記法で指定されたパスが正しいか確認します。アップロード時に生成されるパスは uploads/ から始まる固有のものです。手動でパスを記述した場合は、間違いがないか確認します。
  • ファイルのエンコーディングやファイル名: ファイル名に日本語などのマルチバイト文字や特殊文字が含まれる場合、問題が発生することがあります。できるだけ英数字のみのファイル名を使用するのが安全です。

7.4 Wiki の編集権限がない

  • GitLab プロジェクトのメンバーロールによって、Wiki を閲覧・編集できるかどうかが決まります。Wiki の編集には、通常 Developer 以上のロールが必要です。自分のロールを確認し、必要であればプロジェクトのオーナーまたはメンテナーに相談してください。

7.5 ローカルでクローンした Wiki でコンフリクトが発生した

  • 複数の人が同時に同じファイルを編集し、それぞれがプッシュしようとした場合に発生します。
  • Git の標準的なコンフリクト解決手順に従います。git pull を実行してリモートの変更を取り込み、コンフリクトしているファイルをエディタで修正し、git add、git commit、git push の手順で解決します。Web UI から編集する方が手軽ですが、Git の知識があればローカル編集の方が強力なツールを使えます。

結論: GitLab Wiki を活用してチームの情報共有を促進しよう

本記事では、GitLab Wiki の基本的な使い方から、Markdown を使ったコンテンツ作成、さらには高度な機能やベストプラクティスまで、幅広く解説しました。

GitLab Wiki は、GitLab プロジェクトに統合された、シンプルながらも強力な情報共有ツールです。Markdown という扱いやすい記法で記述でき、Git によるバージョン管理が組み込まれているため、チームでの共同作業に非常に適しています。

プロジェクトのドキュメント、仕様、会議の議事録、手順書、FAQ など、様々な情報を Wiki に集約することで、情報のサイロ化を防ぎ、チーム全体の生産性を向上させることができます。

まずは Home ページを作成し、簡単な Markdown 記法でプロジェクトの概要を記述することから始めてみましょう。慣れてきたら、新しいページを追加したり、サブページで構造化したり、_sidebar.md でナビゲーションを整備したりと、徐々に Wiki を育てていってください。

GitLab Wiki と Markdown をマスターして、あなたのプロジェクトの知識共有をより円滑で効率的なものにしましょう。この記事が、その最初の一歩を踏み出すための詳細なガイドとなれば幸いです。

コメントする

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

上部へスクロール