アスキードック

GitLab はAsciidoctorgem を使って AsciiDoc コンテンツを HTML5 に変換します。Asciidoctor の完全なリファレンスはAsciidoctor ユーザーマニュアルを参照してください。

AsciiDoc は以下の分野で使用できます:

  • Wikiページ
  • リポジトリ内部のAsciiDocドキュメント (.adoc または.asciidoc)

構文

ここでは最もよく使われる AsciiDoc 構文を簡単に説明します。AsciiDoc 構文の完全なドキュメントはhttps://asciidoctor.org/docs/ にあります。

パラグラフ

A normal paragraph.
Line breaks are not preserved.

行コメント(// で始まる行)はスキップされます:

// this is a comment

段落は空行で区切られます。

[%hardbreaks] オプションを指定した段落は改行を保持します:

[%hardbreaks]
This paragraph carries the `hardbreaks` option.
Notice how line breaks are now preserved.

字下げされた(リテラル)段落は、テキスト書式を無効にし、スペースと改行を保持し、固定幅フォントで表示されます:

 This literal paragraph is indented with one space.
 As a consequence, *text formatting*, spaces,
 and lines breaks will be preserved.

戒めの段落は読者の注意を引きます:

  • NOTE: This is a brief reference, please read the full documentation at https://asciidoctor.org/docs/.
  • TIP: Lists can be indented. Leading whitespace is not significant.

テキストのフォーマット

拘束(単語の境界で適用)

*strong importance* (aka bold)
_stress emphasis_ (aka italic)
`monospaced` (aka typewriter text)
"`double`" and '`single`' typographic quotes
+passthrough text+ (substitutions disabled)
`+literal text+` (monospaced with substitutions disabled)

非制約(任意の場所に適用)

**C**reate+**R**ead+**U**pdate+**D**elete
fan__freakin__tastic
``mono``culture

置換

A long time ago in a galaxy far, far away...
(C) 1976 Arty Artisan
I believe I shall--no, actually I won't.

マクロ

// where c=specialchars, q=quotes, a=attributes, r=replacements, m=macros, p=post_replacements
The European icon:flag[role=blue] is blue & contains pass:[************] arranged in a icon:circle-o[role=yellow].
The pass:c[->] operator is often referred to as the stabby lambda.
Since `pass:[++]` has strong priority in AsciiDoc, you can rewrite pass:c,a,r[C++ => C{pp}].
// activate stem support by adding `:stem:` to the document header
stem:[sqrt(4) = 2]

属性

ユーザー定義属性

// define attributes in the document header
:name: value
:url-gem: https://rubygems.org/gems/asciidoctor

You can download and install Asciidoctor {asciidoctor-version} from {url-gem}.
C{pp} is not required, only Ruby.
Use a leading backslash to output a word enclosed in curly braces, like \{name}.

環境属性

GitLabは以下の環境属性を設定します:

属性説明
docnameソース文書のルート名 (先頭のパスやファイル拡張子はなし)。
outfilesuffixバックエンド出力に対応するファイル拡張子 (ドキュメント間の相互参照を動作させるため、デフォルトは.adoc です)。
https://example.org/page[A webpage]
link:../path/to/file.txt[A local file]
xref:document.adoc[A sibling document]
mailto:hello@example.org[Email to say hello!]

アンカー

[[idname,reference text]]
// or written using normal block attributes as `[#idname,reftext=reference text]`
A paragraph (or any block) with an anchor (aka ID) and reftext.

See <<idname>> or <<idname,optional text of internal link>>.

xref:document.adoc#idname[Jumps to anchor in another document].

This paragraph has a footnote.footnote:[This is the text of the footnote.]

リスト

順序なし

* level 1
** level 2
*** level 3
**** level 4
***** level 5
* back at level 1
+
Attach a block or paragraph to a list item using a list continuation (which you can enclose in an open block).

.Some Authors
[circle]
- Edgar Allen Poe
- Sheri S. Tepper
- Bill Bryson

オーダー

. Step 1
. Step 2
.. Step 2a
.. Step 2b
. Step 3

.Remember your Roman numerals?
[upperroman]
. is one
. is two
. is three

チェックリスト

* [x] checked
* [ ] not checked

コールアウト

// enable callout bubbles by adding `:icons: font` to the document header
[,ruby]
----
puts 'Hello, World!' # <1>
----
<1> Prints `Hello, World!` to the console.

説明

first term:: description of first term
second term::
description of second term

文書の構造

= Document Title
Author Name <author@example.org>
v1.0, 2019-01-01

セクション

= Document Title (Level 0)
== Level 1
=== Level 2
==== Level 3
===== Level 4
====== Level 5
== Back at Level 1

含まれるもの

note
AsciiDocフォーマットで作成されたWikiページは、ファイル拡張子.asciidoc で保存されます。AsciiDoc Wiki ページで作業する場合、ファイル名を.adoc から.asciidocに変更してください。
include::basics.adoc[]

システムの良好なパフォーマンスを保証し、悪意のあるドキュメントが問題を引き起こすのを防ぐために、GitLabは1つのドキュメントで処理されるincludeディレクティブの数に上限を設けています。includeできるドキュメントは32個までで、これは推移的依存関係を含みます。

別ページや内部URLからのincludeを使うには、アプリケーション設定でallow-uri-read

// define application setting allow-uri-read to true to allow content to be read from URI
include::https://example.org/installation.adoc[]

ブロック

--
open - a general-purpose content wrapper; useful for enclosing content to attach to a list item
--
// recognized types include CAUTION, IMPORTANT, NOTE, TIP, and WARNING
// enable admonition icons by setting `:icons: font` in the document header
[NOTE]
====
admonition - a notice for the reader, ranging in severity from a tip to an alert
====
====
example - a demonstration of the concept being documented
====
.Toggle Me
[%collapsible]
====
collapsible - these details are revealed by clicking the title
====
****
sidebar - auxiliary content that can be read independently of the main content
****
....
literal - an exhibit that features program output
....
----
listing - an exhibit that features program input, source code, or the contents of a file
----
[,language]
----
source - a listing that is embellished with (colorized) syntax highlighting
----
\```language
fenced code - a shorthand syntax for the source block
\```
[,attribution,citetitle]
____
quote - a quotation or excerpt; attribution with title of source are optional
____
[verse,attribution,citetitle]
____
verse - a literary excerpt, often a poem; attribution with title of source are optional
____
++++
pass - content passed directly to the output document; often raw HTML
++++
// activate stem support by adding `:stem:` to the document header
[stem]
++++
x = y^2
++++
////
comment - content which is not included in the output document
////

テーブル

.Table Attributes
[cols=>1h;2d,width=50%,frame=topbot]
|===
| Attribute Name | Values

| options
| header,footer,autowidth

| cols
| colspec[;colspec;...]

| grid
| all \| cols \| rows \| none

| frame
| all \| sides \| topbot \| none

| stripes
| all \| even \| odd \| none

| width
| (0%..100%)

| format
| psv {vbar} csv {vbar} dsv
|===

カラーズ

HEX,RGB,HSL 形式で記述された色を、カラーインジケータ付きでレンダリングさせることが可能です。サポートされているフォーマット(名前付きカラーはサポートされていません):

  • HEX `#RGB[A]` または`#RRGGBB[AA]`
  • RGB:`RGB[A](R, G, B[, A])`
  • HSL:`HSL[A](H, S, L[, A])`

バックテックの中に書かれた色の後に “チップ “が続きます:

- `#F00`
- `#F00A`
- `#FF0000`
- `#FF0000AA`
- `RGB(0,255,0)`
- `RGB(0%,100%,0%)`
- `RGBA(0,255,0,0.3)`
- `HSL(540,70%,50%)`
- `HSLA(540,70%,50%,0.3)`

方程式と公式(STEM)

Science, Technology, Engineering, and Mathの(STEM) 式を含める必要がある場合は、ドキュメントのヘッダーのstem 属性をlatexmath に設定してください。 式と数式はKaTeXを使用してレンダリングされます:

:stem: latexmath

latexmath:[C = \alpha + \beta Y^{\gamma} + \epsilon]

[stem]
++++
sqrt(4) = 2
++++

A matrix can be written as stem:[[[a,b\],[c,d\]\]((n),(k))].

ダイアグラムとフローチャート

Mermaidや PlantUMLを使って、GitLabのテキストからダイアグラムやフローチャートを生成することができます。

Mermaid

GitLab 13.3 で導入されました

詳細は公式ページをご覧ください。Mermaidを使うのが初めてだったり、Mermaidコード内のイシューを特定するのに助けが必要な場合、MermaidライブエディターはMermaidダイアグラム内でイシューを作成・解決するのに役立つツールです。

ダイアグラムやフローチャートを作成するには、mermaid ブロックにテキストを入力します:

[mermaid]
----
graph LR
    A[Square Rect] -- Link text --> B((Circle))
    A --> C(Round Rect)
    B --> D{Rhombus}
    C --> D
----

クロキ

Krokiは12以上のダイアグラム・ライブラリをサポートしています。KrokiをGitLabで使えるようにするには、まずGitLab管理者が有効にする必要があります。詳しくはKrokiインテグレーションページをご覧ください。

Krokiを有効にすると、AsciiDocやMarkdownドキュメントでダイアグラムを作成できるようになります。GraphVizダイアグラムを使った例です:

アスキードック

[graphviz]
....
digraph G {
  Hello->World
}
....

マークダウン

```graphviz
digraph G {
  Hello->World
}
```

PlantUML

PlantUMLインテグレーションはGitLab.comで有効になっています。GitLabのセルフマネージドインストールでPlantUMLを利用できるようにするには、GitLab管理者が有効にする必要があります

PlantUMLが有効になったら、plantuml ブロックにテキストを入力してください:

[plantuml]
----
Bob -> Alice : hello
----

マルチメディア

image::screenshot.png[block image,800,450]

Press image:reload.svg[reload,16,opts=interactive] to reload the page.

video::movie.mp4[width=640,start=60,end=140,options=autoplay]

GitLabはAsciiDocコンテンツにYouTubeやVimeoの動画を埋め込むことをサポートしていません。標準のAsciiDocリンクを使用してください:

https://www.youtube.com/watch?v=BlaZ65-b7y0[Link text for the video]

区切り

// thematic break (aka horizontal rule)
---
// page break
<<<