Wiki

  • GitLab 14.9でページの読み込みが非同期に変更されました。
  • GitLab 14.9でページのスラッグエンコーディング方法をERB::Util.url_encode に変更しました。

ドキュメントをリポジトリに保管せず、コードと同じプロジェクトに保管したい場合は、GitLabが各GitLabプロジェクトに提供しているWikiを使うことができます。各Wikiは独立したGitリポジトリなので、WikiページはWebインターフェイスで作成することも、Gitを使ってローカルで作成することもできます。

GitLabのWikiはMarkdown、Rdoc、AsciiDoc、Orgをコンテンツとしてサポートしています。Markdownで書かれたWikiページはすべてのMarkdown機能をサポートし、リンクのためのWiki特有の動作も提供します。

GitLab 13.5以降では、Wikiページはカスタマイズ可能なサイドバーを表示します。このサイドバーにはWiki内のページの一部のリストがあり、ネストされたツリーとして表示され、兄弟ページがアルファベット順に表示されます。全ページのリストを表示するには、サイドバーのView All Pagesを選択します：

Wiki sidebar

プロジェクトWikiの表示

プロジェクトWikiにアクセスするには：

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. Wikiを表示するには、どちらかを選択します：

プロジェクトの左サイドバーにPlan > Wikiが表示されていない場合、プロジェクト管理者がそれを無効にしています。

Wiki のデフォルトブランチの設定

GitLab 14.1 で導入されました。

WikiリポジトリのデフォルトブランチはGitLabのバージョンによって異なります：

  • GitLab バージョン 14.1 以降：Wikiは、インスタンスまたはグループに設定されたデフォルトのブランチ名を継承します。カスタム値が設定されていない場合、GitLabはmainを使用します。
  • GitLabバージョン14.0以前：GitLab はmaster を使用します。

GitLabのどのバージョンでも、以前に作成したWikiのデフォルトブランチの名前を変更することができます。

Wiki ホームページの作成

Wikiが作成されたとき、Wikiは空です。最初の訪問で、ユーザーがwikiを閲覧するときに見るホームページを作成することができます。このページはwikiのトップページとして使用するために特定のタイトルを必要とします。作成するには

  1. 左側のサイドバーで、「検索」を選択するか、または「移動」を選択して、プロジェクトまたはグループを見つけます。
  2. 計画 > Wikiを選択します。
  3. 最初のページを作成]を選択します。
  4. GitLabでは、この最初のページのタイトルをhomeとする必要があります。このタイトルのページはWikiのフロントページとなります。
  5. テキストのスタイルを設定するフォーマットを選択します。
  6. コンテンツセクションにホームページ用のウェルカムメッセージを追加します。後でいつでも編集できます。
  7. コミットメッセージを追加します。Gitはコミットメッセージを必要とするので、自分で入力しない場合はGitLabが作成します。
  8. Create page を選択します。

新しい Wiki ページを作成します。

少なくともDeveloperロールを持つユーザは新しいWikiページを作成することができます：

  1. 左側のサイドバーで、「検索」を選択するか、または「移動」を選択して、プロジェクトまたはグループを見つけます。
  2. 計画 > Wikiを選択します。
  3. このページ、または他のWikiページの新規ページを選択します。
  4. コンテンツのフォーマットを選択します。
  5. 新しいページのタイトルを追加します。ページタイトルはサブディレクトリやフォーマット用の特殊文字を使用し、長さの制限があります。
  6. Wikiページにコンテンツを追加します。
  7. オプション。ファイルを添付すると、GitLabはそれをWikiのGitリポジトリに保存します。
  8. コミットメッセージを追加します。Gitはコミットメッセージを必要とするので、自分で入力しない場合はGitLabが作成します。
  9. Create page を選択します。

ローカルでWikiページを作成または編集します。

WikiはGitリポジトリに基づいているので、他のGitリポジトリと同じようにローカルにクローンして編集することができます。Wikiリポジトリをローカルにクローンするには、Wikiページの右側のサイドバーからリポジトリをクローンするを選択し、画面の指示に従ってください。

ローカルでWikiに追加するファイルは、使用するマークアップ言語に応じて、次のサポートされている拡張子のいずれかを使用しなければなりません。サポートされていない拡張子のファイルは、GitLabにプッシュされたときに表示されません：

  • Markdown拡張子：.mdown.mkd,.mkdn,.md,.markdown.
  • AsciiDoc拡張機能：.adoc.ad,.asciidoc.
  • その他のマークアップ拡張：.textile .rdoc,.org,.creole,.wiki,.mediawiki,.rst.

ページタイトルの特殊文字

Wiki ページは Git リポジトリにファイルとして保存されるため、特定の文字には特別な意味があります：

  • ページを保存するとき、Pages はハイフンに変換されます。
  • ハイフン (-) は、ページを表示するときにスペースに変換されます。
  • スラッシュ (/) はパスの区切り文字として使われ、タイトルには表示 /できません。文字を/含むタイトルを作成 /した場合、GitLabはそのパスを構築するために必要なすべてのサブディレクトリを作成します。例えば、docs/my-page というタイトルをつけると、/wikis/docs/my-page というパスの Wiki ページが作成されます。

ファイル名とディレクトリ名の長さの制限

GitLab 12.8で導入されました。

多くの一般的なファイルシステムでは、ファイル名やディレクトリ名に255バイトの制限があります。GitとGitLabはどちらもこれらの制限を超えるパスをサポートしています。しかし、ファイルシステムがこれらの制限を強制している場合、この制限を超えるファイル名を含むWikiのローカルコピーをチェックアウトすることはできません。この問題を防ぐために、GitLabのウェブインターフェイスとAPIはこれらの制限を強制します：

  • ページタイトルは245バイト（ファイル拡張子のために10バイトを確保）。
  • ディレクトリ名用に255バイト。

ASCII以外の文字は1バイト以上必要です。

これらの制限を超えるファイルをローカルで作成することはできますが、チームメイトはその後ローカルでWikiをチェックアウトすることができないかもしれません。

Wikiページの編集

Wikiページを編集するには少なくとも開発者ロールが必要です：

  1. 左側のサイドバーで、「検索」を選択するか、または「移動」を選択して、プロジェクトまたはグループを見つけます。
  2. 計画 > Wikiを選択します。
  3. 編集したいページに移動します：
  4. 内容を編集します。
  5. 変更を保存を選択します。

Wikiページへの未保存の変更はローカルブラウザストレージに保存され、偶発的なデータ損失を防ぎます。

目次の作成

Wikiページの小見出しから目次を生成するには、[[_TOC_]] タグを使用します。例については目次をご覧ください。

Wiki ページの削除

Wikiページを削除するには少なくとも開発者ロールが必要です：

  1. 左側のサイドバーで、「検索」を選択するか、または「移動」を選択して、プロジェクトまたはグループを見つけます。
  2. 計画 > Wikiを選択します。
  3. 削除したいページに移動します。
  4. 編集アイコン（{鉛筆}）を選択します。
  5. ページの削除を選択します。
  6. 削除を確認します。

Wikiページの移動

Wikiページを移動するには少なくとも開発者ロールが必要です：

  1. 左側のサイドバーで、「検索」を選択するか、または「移動」を選択して、プロジェクトまたはグループを見つけます。
  2. 計画 > Wikiを選択します。
  3. 移動したいページに移動します。
  4. 編集アイコン（{鉛筆}）を選択します。
  5. タイトルフィールドに新しいパスを追加します。例えば、company の下にabout という Wiki ページがあり、それを Wiki のルートに移動したい場合、Titleをabout から/aboutに変更します。
  6. 変更を保存を選択します。

Wikiページの履歴を見る

wikiページの変更履歴はwikiのGitリポジトリに記録されます。履歴ページに表示されます：

Wiki page history

  • ページのリビジョン（GitコミットSHA）。
  • ページの作成者。
  • コミットメッセージ。
  • 最後の更新。
  • ページバージョンの欄でリビジョン番号を選択すると、以前のリビジョンが表示されます。

Wiki ページの変更点を表示するには：

  1. 左側のサイドバーで、「検索」を選択するか、または「移動」を選択して、プロジェクトまたはグループを見つけます。
  2. 計画 > Wikiを選択します。
  3. 履歴を表示したいページに移動します。
  4. ページ履歴を選択します。

ページのバージョン間の変更を表示

GitLab 13.2 で導入されました。

バージョン管理された差分ファイルビューと同じように、Wikiページのバージョンで行われた変更を見ることができます：

  1. 左側のサイドバーで、「検索」を選択するか、または「移動」を選択して、プロジェクトまたはグループを見つけます。
  2. 計画 > Wikiを選択します。
  3. 興味のある Wiki ページに移動します。
  4. ページ履歴を選択すると、すべてのページバージョンが表示されます。

  5. 興味のあるバージョンの変更欄のコミットメッセージを選択してください。

    Wiki page changes

Wiki イベントの追跡

GitLabはWikiの作成、削除、更新イベントを追跡します。これらのイベントはこれらのページに表示されます：

Wiki へのコミットはリポジトリ分析ではカウントされません。

サイドバーのカスタマイズ

GitLab 13.8から導入されたサイドバーは、サイドバーの編集ボタンを選択することでカスタマイズすることができます。

Wikiナビゲーションのサイドバーをカスタマイズするには、少なくとも開発者ロールが必要です。このプロセスでは、デフォルトのサイドバーナビゲーションを完全に置き換える_sidebar という名前の Wiki ページを作成します：

  1. 左側のサイドバーで、「検索」を選択するか、または「移動」を選択して、プロジェクトまたはグループを見つけます。
  2. 計画 > Wikiを選択します。
  3. ページの右上で、サイドバーの編集を選択します。
  4. 完了したら、「変更を保存」を選択します。

_sidebar 、Markdownでフォーマットした例です：

### [Home](home)

- [Hello World](hello)
- [Foo](foo)
- [Bar](bar)

---

- [Sidebar](_sidebar)

プロジェクトWikiを有効もしくは無効にします

GitLab では Wiki はデフォルトで有効になっています。プロジェクト管理者はSharing and permissions の説明に従ってプロジェクト Wiki を有効/無効にすることができます。

自分で管理するGitLabインストールの管理者は、追加のWiki設定を行うことができます。

グループ設定からグループWikiを無効にすることができます。

プロジェクトの左サイドバーから外部Wikiへのリンクを追加します：

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. 設定]>[インテグレーション]を選択します。
  3. 外部 Wiki を選択します。
  4. 外部WikiのURLを追加します。
  5. オプション。Test settingsを選択します。
  6. 変更を保存を選択します。

これでプロジェクトの左サイドバーに外部Wikiオプションが表示されます。

このインテグレーションを有効にすると、外部wikiへのリンクは内部wikiへのリンクに置き換えられません。サイドバーから内部Wikiを隠すには、プロジェクトのWikiを無効にします。

外部Wikiへのリンクを隠すには：

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. 設定]>[インテグレーション]を選択します。
  3. 外部 Wiki を選択します。
  4. インテグレーションを有効にする]で、[アクティブ]チェックボックスをオフにします。
  5. 変更を保存を選択します。

プロジェクトの Wiki を無効にします。

プロジェクトの内部 Wiki を無効にします：

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. 設定] > [全般]を選択します。
  3. 可視性]、[プロジェクト機能]、[権限]を展開します。
  4. スクロールダウンしてWikiを見つけ、オフに切り替えます（灰色）。
  5. 変更を保存を選択します。

内部 Wiki が無効になり、ユーザーとプロジェクト・メンバーが表示されます：

  • プロジェクトのサイドバーからWikiへのリンクが見つかりません。
  • Wikiページの追加、削除、編集ができません。
  • どのWikiページも閲覧できません。

Wikiを再び有効にするために、以前に追加されたWikiページは保存されます。ウィキを再び有効にするには、ウィキを無効にするプロセスを繰り返しますが、オン（青）に切り替えます。

リッチテキストエディタ

GitLabはWikiでGitLab Flavored MarkdownのWYSIWYG編集体験を提供します。

サポートには以下が含まれます：

  • 太字、斜体、ブロック引用符、見出し、インラインコードの使用など、テキストの書式設定。
  • 順序付きリスト、順序なしリスト、チェックリストの書式設定
  • 表構造の作成と編集
  • シンタックスハイライトを使用したコードブロックの挿入と書式設定
  • Mermaid、PlantUML、Krokiダイアグラムのプレビュー(GitLab 15.2で導入)
  • HTMLコメントの作成と編集（GitLab 15.7で導入）。

リッチテキストエディタを使う

  1. 新しいWikiページを作成するか、既存のWikiページを編集します。
  2. フォーマットとしてMarkdownを選択します。
  3. コンテンツ]の上にある[リッチテキストを編集]を選択します。
  4. リッチテキストエディタで利用可能なさまざまな書式オプションを使用して、ページのコンテンツをカスタマイズします。
  5. 新規ページの場合は「ページを作成」、既存ページの場合は「変更を保存」を選択します。

リッチテキスト編集モードは、生のソースの編集に切り替えるまで、デフォルトのままです。

古いエディタに戻る

  1. リッチテキストエディタでページを編集している場合は、コンテンツまでスクロールします。
  2. ソースの編集を選択します。

GitLabフレーバーMarkdownのサポート

リッチテキストエディタでのすべてのGitLab Flavored Markdownコンテンツタイプのサポートは現在進行中です。CommonMark と GitLab Flavored Markdown サポートの開発状況については、こちらをご覧ください：

トラブルシューティング

Apacheリバースプロキシでのページスラッグレンダリング

GitLab 14.9 以降では、ページスラッグはERB::Util.url_encode メソッドを使ってエンコードされるようになりました。Apache のリバースプロキシを使っている場合は、Apache の設定のProxyPass 行にnocanon 引数を追加することで、ページスラッグが正しくレンダリングされるようになります。

RailsコンソールでプロジェクトWikiを再作成します。

caution
このオペレーションはWikiのすべてのデータを削除します。
caution
データを直接変更するコマンドは正しく実行されない場合、もしくは適切な条件下で実行されない場合、ダメージを与える可能性があります。念のため、インスタンスのバックアップをリストアする準備ができているテスト環境で実行することを強く推奨します。

プロジェクトWikiからすべてのデータを消去し、空白の状態で再作成します：

  1. Railsコンソールセッションを開始します。

  2. 以下のコマンドを実行します：

    # Enter your project's path
p = Project.find_by_full_path('<username-or-group>/<project-name>')
   
# This command deletes the wiki project from the filesystem.
GitlabShellWorker.perform_in(0, :remove_repository, p.repository_storage, p.wiki.disk_path)
   
# Refresh the wiki repository state.
p.wiki.repository.expire_exists_cache

Wikiのすべてのデータがクリアされ、Wikiを使用する準備が整いました。