Orgモード

GitLabはgitlab-markup gemを使用し、それがorg-ruby gemを使用してOrgモードのコンテンツをHTMLに変換します。Orgモードの構文の完全な参照については、Org manualを参照してください。

Orgモードは以下の領域で使用できます:

• リポジトリ内のOrgモードドキュメント（.org）
• スニペットファイルに.org拡張子が付いている場合のスニペット
• Wikiページ

見出し

先頭のアスタリスク（*）は、見出し1から6としてレンダリングされます。

* Heading 1
** Heading 2
*** Heading 3
**** Heading 4
***** Heading 5
****** Heading 6

#+TITLE:は、ページ上部のH1見出しとしてレンダリングされます:

#+TITLE: Welcome to Org-mode

見出しアンカー

GitLabはすべてのOrgモード見出しに自動的にアンカーを追加するため、それにリンクできます。

見出しにカーソルを合わせると、そのアンカーへのリンクが表示されるため、見出しへのリンクをコピーして他の場所で簡単に使用できます。

アンカーは、次のルールに従って見出しの内容から生成されます。

1. すべてのテキストは小文字に変換されます。
2. 文字、数字、ハイフン、アンダースコア以外はすべて削除されます。
3. すべてのスペースはハイフンに変換されます。
4. 同じアンカーを持つ見出しがすでに生成されている場合、1から始まる一意の連番が付加されます。

例:

* This heading has spaces in it
** This heading has an accent in it: Café
** This heading has Unicode in it: 日本語
** This heading has spaces in it
*** This heading has spaces in it
** This heading has 3.5 in it (& parentheses)
** This heading has  multiple spaces and - hyphens_and_underscores

次の見出しアンカーが生成されます:

1. #this-heading-has-spaces-in-it
2. #this-heading-has-an-accent-in-it-café
3. #this-heading-has-unicode-in-it-日本語
4. #this-heading-has-spaces-in-it-1
5. #this-heading-has-spaces-in-it-2
6. #this-heading-has-35-in-it--parentheses
7. #this-heading-has--multiple-spaces-and---hyphens_and_underscores

スニペットでは、複数のファイル間でアンカーが重複しないように、ファイル名から生成したプレフィックスも見出しアンカーに付加されます。たとえば、README.orgという名前のファイルにある* TL;DR見出しには、#tldrではなく#readme-tldrというアンカーが設定されます。

リスト

Orgモードは、順序なしリスト、順序付きリスト、説明リスト、およびネストされたリストをサポートしています。

順序なしリスト

ハイフン（-）またはプラス記号（+）は、順序なしリストを作成します:

- Item one
- Item two
  - Nested item

+ Item one
+ Item two
  + Nested item

レンダリングすると、両方の例は次のようになります:

• 項目1
• 項目2
  • ネストされた項目

順序付きリスト

数字の後にピリオド（.）または閉じ括弧（)）を続けると、順序付きリストが作成されます:

1. First item
2. Second item
   1. Nested item

1) First item
2) Second item
   1) Nested item

レンダリングすると、両方の例は次のようになります:

1. 最初の項目
2. 2番目の項目
   1. ネストされた項目

説明リスト

- term1 :: Definition of term one
- term2 :: Definition of term two

レンダリングすると、この例は次のように表示されます。

term1: 用語1の定義

term2: 用語2の定義

チェックボックス

リストマーカーの後の[ ]、[X]、および[-]は、チェックボックス入力要素としてレンダリングされます。[-]（部分的にチェック済み）は、不確定なチェックボックスとしてレンダリングされます:

- [-] Prepare release
  - [X] Update changelog
  - [ ] Review merge requests

レンダリングすると、この例は次のように表示されます。

チェックボックスは順序付きリストでも機能します:

1. [-] Prepare release
   1. [X] Update changelog
   2. [ ] Review merge requests

レンダリングすると、この例は次のように表示されます。

テーブル

パイプ（|）はテーブルを作成します。ダッシュ（-）とプラス記号（+）で作られた区切り行は、その上の行をテーブルヘッダーにします:

| Item  | Unit price ($) | Quantity | Subtotal ($) |
|-------+----------------+----------+--------------|
| Eggs  |              3 |        2 |            6 |
| Milk  |              2 |        1 |            2 |
| Bread |              1 |        3 |            3 |
|-------+----------------+----------+--------------|
| Total |                |          |           11 |
#+TBLFM: $>=$2*$3::@>$>=vsum(@I..@II)

レンダリングすると、この例は次のように表示されます。

項目	単価（$）	数量	小計（$）
卵	3	2	6
牛乳	2	1	2
パン	1	3	3
合計			11

リンク

リンクは複数の方法で作成できます。

- This line shows an [[https://example.com][inline-style link]]
- This line shows a [[./permissions.md][link to a file in the same directory]]
- This line shows a [[../_index.md][relative link to a file one directory higher]]
- This line links to a [[#headings][heading on the same page, using a `#` and the heading anchor]]

レンダリングすると、この例は次のように表示されます。

• この行はインラインスタイルのリンクを示しています
• この行は、同じディレクトリ内のファイルへのリンクを示します。
• この行は1つ上のディレクトリにあるファイルへの相対リンクを示しています
• この行は、同じページの見出しへのリンクであり、#と見出しアンカーを使用しています。

URLの自動リンク

テキストに入力したほとんどすべてのURLは自動的にリンクされます。

See https://example.com for details.

レンダリングすると、この例は次のように表示されます。

詳細については、https://example.comを参照してください。

強調

画像

インラインで画像を埋め込む説明テキストのない画像ファイルへのリンク:

[[img/markdown_logo_v17_11.png]]

レンダリングすると、この例は次のように表示されます。

罫線

5つ以上の連続するハイフン（-）は、罫線を作成します:

Paragraph before.

-----

Paragraph after.

レンダリングすると、この例は次のように表示されます。

前の段落。

---

後の段落。

コメント

#で始まり、その後にスペースが続く行はレンダリングされません:

Visible before.

# This line is a comment and isn't rendered.

Visible after.

レンダリングすると、この例は次のように表示されます。

ブロックの前に表示。

ブロックの後に表示。

#+BEGIN_COMMENTと#+END_COMMENTの間のコンテンツはレンダリングされません:

Visible before the block.

#+BEGIN_COMMENT
This entire block is a comment.
None of these lines are rendered.
#+END_COMMENT

Visible after the block.

レンダリングすると、この例は次のように表示されます。

ブロックの前に表示されます。

ブロックの後に表示されます。

見出しマーカーの直後にCOMMENTでマークされた見出し、およびその下にネストされたすべての内容はレンダリングされません:

* Visible heading

Some visible text.

* COMMENT Hidden heading

This text isn't rendered.

** Nested under hidden heading

This text isn't rendered either.

* Another visible heading

レンダリングされた出力には、Visible headingとAnother visible heading、およびそれらの間のテキストのみが表示されます。

テキストブロック

#+BEGIN_QUOTEと#+END_QUOTEは引用ブロックを作成します:

#+BEGIN_QUOTE
Everything should be made as simple as possible,
but not any simpler ---Albert Einstein
#+END_QUOTE

レンダリングすると、この例は次のように表示されます。

すべてを可能な限りシンプルにすべきだが、それ以上にシンプルにしてはならない —アルバートアインシュタイン

#+BEGIN_EXAMPLEと#+END_EXAMPLEは、整形済みテキストブロックを作成します:

#+BEGIN_EXAMPLE
Here is an example.
#+END_EXAMPLE

レンダリングすると、この例は次のように表示されます。

Here is an example.

コロン（:）とスペースも整形済みテキストブロックを作成します:

: Here is an example.

レンダリングすると、この例は次のように表示されます。

Here is an example.

ソースコードブロック

#+BEGIN_SRCと#+END_SRCは、言語名で構文ハイライトされたコードブロックを作成します:

#+BEGIN_SRC python
import requests
data = requests.get("https://jsonplaceholder.typicode.com/users/1").json()
#+END_SRC

レンダリングすると、この例は次のように表示されます。

import requests
data = requests.get("https://jsonplaceholder.typicode.com/users/1").json()

GitLabは、構文ハイライトにRouge Ruby libraryを使用しています。サポートされている言語のリストについては、Rouge project Wikiを参照してください。

ブロックヘッダーに:exports bothを追加すると、レンダリングされた出力にソースブロックの実行結果（#+RESULTS:）が含まれます:

#+BEGIN_SRC python :exports both :results output code
import requests
data = requests.get("https://jsonplaceholder.typicode.com/users/1").json()
print([data["username"], data["email"]])
#+END_SRC

#+RESULTS:
#+begin_src python
['Bret', 'Sincere@april.biz']
#+end_src

レンダリングすると、この例は次のように表示されます。

import requests
data = requests.get("https://jsonplaceholder.typicode.com/users/1").json()
print([data["username"], data["email"]])

['Bret', 'Sincere@april.biz']

図表とフローチャート

コードブロック内のテキストから、GitLab Flavored Markdownと同様に図を生成できます。

Mermaid

#+BEGIN_SRC mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
#+END_SRC

レンダリングすると、この例は次のように表示されます。

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

PlantUML

PlantUMLインテグレーションはGitLab.comで有効になっています。GitLab Self-ManagedでPlantUMLを利用可能にするには、GitLab管理者がそれを有効にする必要があります。

#+BEGIN_SRC plantuml
Bob -> Alice : hello
Alice -> Bob : hi
#+END_SRC

数式

言語がmathとして宣言されたソースコードブロックに記述された数式は、KaTeXでレンダリングされます。KaTeXはLaTeXの一部の機能のみをサポートしています。

#+BEGIN_SRC math
\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)
#+END_SRC

レンダリングすると、この例は次のように表示されます。

GitLab Query Language（GLQL）

言語がglqlとして宣言されたソースコードブロックは、GitLab Query Language（GLQL）ビューを埋め込みます:

#+BEGIN_SRC glql
display: table
title: GLQL table 🎉
description: This view lists my open issues
fields: title, state, health, epic, milestone, weight, updated
limit: 5
query: type = Issue AND group = "gitlab-org" AND assignee = currentUser() AND state = opened
#+END_SRC

レンダリングすると、この例は次のように表示されます。