Wiki

Wikiと呼ばれるドキュメンテーションのための独立したシステムは、各GitLabプロジェクトに組み込まれています。 すべての新しいプロジェクトでデフォルトで有効になっており、プロジェクトのWikiで見つけることができます。

Wikiは、ドキュメントをリポジトリに置きたくないが、コードが存在する同じプロジェクトに置きたい場合にとても便利です。

各Wikiは個別のGitリポジトリであるため、WikiページはウェブインターフェイスまたはローカルでGitを使って作成することができます。

初めてのホームページ作成

初めてWikiにアクセスすると、ホームページを作成するように指示されます。 ホームページはWikiを閲覧する際のランディングページとなるため、作成する必要があります。コンテンツセクションを埋めて、ページの作成をクリックするだけです。 後でいつでも編集することができますので、ウェルカムメッセージを書いてください。

New home page

新しいWikiページの作成

注:開発者権限が必要です。

すべてのWikiページにある「新しいページ」ボタンをクリックして、新しいページを作成します。

新しいWikiページのタイトルを入力するよう求められます。

サブディレクトリを示すためにタイトルに’/’を使用することで、ウィキページのフルパスを指定することができます。 足りないディレクトリは自動的に作成されます。 例えば、docs/my-page というタイトルは/wikis/docs/my-pageというパスを持つウィキページを作成します。

GitLabのWikiはMarkdown、RDoc、AsciiDoc、Orgをサポートしています。MarkdownベースのページではすべてのMarkdown機能がサポートされ、リンクではWiki特有の動作があります。

ウェブインタフェースではコミットメッセージは任意ですが、GitLab WikiはGitをベースにしているためコミットメッセージが必要です。

準備ができたら、Createpageをクリックすると、新しいページが作成されます。

New page

アタッチメントストレージ

GitLab 11.3で導入されました

GitLab 11.3から、GitLabのインターフェイスを通してWikiにアップロードされたファイルはWikiのGitリポジトリに保存され、Wikiリポジトリをローカルにクローンすれば利用できるようになりました。 GitLab 11.3以前にアップロードされたファイルはすべてGitLab自体に保存されます。 もしWikiのGitリポジトリの一部にしたい場合は、再度アップロードする必要があります。

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

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

  • ページを保存する際、Pagesはハイフンに変換されます。
  • ハイフン (-) は、ページを表示する際にスペースに変換されます。
  • スラッシュ (/) はパスの区切り文字として使用されるため、使用できません。

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

GitLab 12.8で導入されました

多くの一般的なファイルシステムでは、ファイル名とディレクトリ名に255バイトの制限があります。GitとGitLabはどちらもこれらの制限を超えるパスをサポートしていますが、これらのファイルシステムのユーザーがWikiリポジトリをローカルにチェックアウトすることは不可能です。

このような状況を避けるために、GitLabのウェブインターフェースやAPIを通してページを編集する際には、これらの制限が適用されます:

  • ページタイトル用に245バイト(ファイル拡張子用に10バイト確保)。
  • ディレクトリ名は255バイト。

ご注意ください:

  • 非ASCII文字は1バイト以上を占めます。
  • Gitを使ってローカルに制限を超えるファイルやディレクトリを作成することは可能ですが、他の人のマシンでは壊れてしまうかもしれません。

Wikiページの編集

注:開発者権限が必要です。

ページを編集するには、Editボタンをクリックし、内容を変更します。 変更が完了したら、Save changesをクリックし、変更を有効にします。

目次の追加

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

Wiki ページの削除

注:メンテナーの権限が必要です。

削除ボタンはページの編集時にのみ表示されます。 削除ボタンをクリックし、ページを削除することを確認してください。

Wiki ページの移動

編集フォームのWikiページタイトルにフルパスを指定することで、Wikiページをあるディレクトリから別のディレクトリに移動することができます。

Moving a page

After moving a page

Wikiページをルートディレクトリに移動するには、Wikiページのタイトルの前にスラッシュ(/)を付ける必要があります。

作成されたWikiページの一覧表示

すべてのWikiにはサイドバーがあり、そこから作成されたページの短いリストを見ることができます。 リストはアルファベット順に並んでいます。

Wiki sidebar

ページ数が多い場合、すべてのページがサイドバーに表示されるわけではありません。すべてのページを表示するには、「すべてのページを表示」をクリックしてください。

Wikiページの履歴の閲覧

Wiki ページの変更履歴は Wiki の git リポジトリに記録され、ページ履歴ボタンをクリックすることで閲覧することができます。

履歴ページでは、ページのリビジョン (Git のコミット SHA)、作成者、コミットメッセージ、最終更新日時を見ることができます。 ページの以前のバージョンがどのようなものだったかを見るには、ページのバージョン欄のリビジョン番号をクリックしてください。

Wiki page history

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

GitLab 13.2 で導入されました

バージョン別の差分ファイルビューと同様に、指定した Wiki ページのバージョンで行われた変更を見ることができます:

  1. 興味のある Wiki ページに移動します。
  2. Pageshistoryをクリックすると、すべてのページのバージョンを見ることができます。
  3. 興味のあるバージョンの変更欄のコミットメッセージをクリックしてください:

    Wiki page changes

Wikiアクティビティ記録

  • GitLab 12.10 で導入されました
  • フィーチャーフラグで有効・無効を切り替えることができ、デフォルトでは無効になっています。
  • GitLab.comで有効になっています。
  • GitLabセルフマネージドインスタンスで使うには、GitLab管理者に頼んで有効にしてもらいましょう。

Wikiイベント(作成、削除、更新)はGitLabによって追跡され、ユーザープロファイルグループプロジェクトのアクティビティページに表示されます。

制限事項

アクティビティが記録されるのは、ブラウザやAPIを通じて行われた編集のみです。 gitを通じて行われプッシュされた編集は、現在のところアクティビティリストには表示されません。

Wiki イベントの有効化または無効化

Wikiイベントアクティビティは開発中であり、本番環境では使用できません。デフォルトでは無効になっている機能フラグの後ろにデプロイされています。 GitLab RailsコンソールにアクセスできるGitLab管理者は、インスタンスで有効にすることができます。 テストするのは自由ですが、使用は自己責任でお願いします。

有効にするには:

Feature.enable(:wiki_events)

無効化するには:

Feature.disable(:wiki_events)

ローカルでのWikiページの追加と編集

WikiはGitリポジトリをベースにしているので、他のGitリポジトリと同じようにローカルにクローンして編集することができます。

右側のサイドバーで、リポジトリのクローンをクリックし、画面の指示に従ってください。

ローカルでWikiに追加するファイルは、使用したいマークアップ言語に応じて、次のサポートされている拡張子のいずれかを持つ必要があります:

  • マークダウン拡張:.mdown,.mkd,.mkdn,.md,.markdown.
  • AsciiDoc 拡張:.adoc,.ad,.asciidoc.
  • その他のマークアップ拡張:.textile,.rdoc,.org,.creole,.wiki,.mediawiki,.rst.

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

プロジェクトのWikiページには、デフォルトでWikiページリストを階層構造で表示する右側ナビゲーションがあります。

サイドバーをカスタマイズするには、_sidebar という名前のファイルを作成して、デフォルトのナビゲーションを完全に置き換えることができます。

警告:_sidebar ファイルをカスタムナビからリンクしない限り、編集するにはブラウザのアドレスバーからhttps://gitlab.com/<namespace>/<project_name>/-/wikis/_sidebar と入力して直接アクセスする必要があります (自己管理型の GitLab インスタンスの場合は、_sidebar をインスタンスの URL に置き換えてください)。

_sidebar の例(Markdown フォーマットを使用):

### [Home](home)

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

---

- [Sidebar](_sidebar)

カスタムサイドナビゲーションで生成されたTOCの表示をサポートする予定です。