記事投稿シリーズについて
QiitaでGitHub Flavored Markdown (以下GFM) に準拠したMarkdownパーサーがベータ版として公開されました！
Qiitaアカウントによる説明記事にも書いてあるのですが、今までと記法が変わっている箇所があるので注意が必要です。
せっかく書いた記事の表示が崩れてしまうのは困るので、可能な限り防ぎたいと考えています！
そこで、記事を書く時に注意すべき記法などについて、Qiita運営から5日間に分けて10記事のシリーズで投稿することになりました！
少しでも皆様が執筆する際の助けになればと思います。
詳しくはQiitaアカウントによる説明記事に、投稿シリーズの説明や、他の記事一覧が載っていますのでぜひ他の記事も読んでみてください！
この記事ではGFMの記法のうち、「コードブロック」と「コードスパン」について説明します。
コードブロック
基本の書き方
コードブロックを書くときの基本形は以下のようになります。
```
puts "hello"
```
見え方は以下のようになります。
puts "hello"
書き方の種類
GFMのコードブロックは大きく分けて2種類の書き方があります。
- Fenced code blocks
- Indented code blocks
Fenced code blocks
Fenced code blocksはよく知られているコードブロックの書き方です。
バッククォート（`） もしくはチルダ（~） を3つ以上つなげたコードフェンスで囲います。
```
puts "hello"
```
もしくは
~~~
puts "hello"
~~~
``` ~~~がフェンス（柵）のように見えるため、コードフェンスと呼ばれています。
コードブロックに情報を付与する
始まりのコードフェンスの後ろにはinfo stringと呼ばれるテキストを追加することができます。
```ruby
puts "hello"
```
もしくは
~~~ruby
puts "hello"
~~~
GitHubやQiitaなどではこのinfo stringにコードブロック内の言語を指定して、シンタックスハイライトできるようになっています。
（正確には、GitHub・Qiita側でinfo stringの中身を見てシンタックスハイライトを有効にする処理が用意されている）
例）
```ruby
puts "hello"
```
↓ シンタックスハイライトが有効になる
puts "hello"
また、Qiitaではシンタックスハイライトの他に、
- ファイル名
-
info stringを言語名:ファイル名とする
-
- diff
-
info stringをdiffとする -
diff_言語名とするとシンタックスハイライトも有効になる
-
が使えます。
例1）
```ruby:main.rb
puts "hello"
```
↓ ファイル名がつく
puts "hello"
例2）
```diff_ruby
def foo
+ "foo"
- "bar"
end
```
↓ + -を使うとdiffを表現できる
def foo
+ "foo"
- "bar"
end
例3）
```diff_ruby:main.rb
def foo
+ "foo"
- "bar"
end
```
↓ 組み合わせ技も可能
def foo
+ "foo"
- "bar"
end
Tips
バッククォート・チルダは3つである必要はない
バッククォート（
`） もしくは チルダ（~） を3つ以上つなげたコードフェンスで囲います。
の通り、 3つ以上 であれば何個でも大丈夫です。
例1）
``````
puts "hello"
``````
↓
puts "hello"
例2）
~~~~~~~~~~
```
puts "hello"
```
~~~~~~~~~~
↓
```
puts "hello"
```
コードフェンスの先頭にスペースを3つまで入れられる
あまり使うイメージが湧きませんが、 始まりのコードフェンスの先頭にスペースを3つまで入れることができます。
例）
```
puts "hello"
```
↓
puts "hello"
始まりのコードフェンスの先頭にあるスペース数だけ、コードブロックの各行の先頭から切り取られます。
詳しくは、https://github.github.com/gfm/#fenced-code-blocks のExampleを見るとわかりやすいです。
コードブロックの前後に空行が不要
下の方で説明するIndented code blocksでは前後に空行が必要ですが、Fenced code blocksでは空行が不要です。
例）
hoge
```
foobar
```
fuga
↓
hoge
foobar
fuga
注意点
始まりと終わりのコードフェンスを同じフェンスにする必要がある
始まりと終わりのコードフェンスは同じ文字列 でなければなりません。
# OK
```
puts "hello"
```
# OK
~~~~~~
puts "hello"
~~~~~~
# NG （フェンスの種類が違う）
```
puts "hello"
~~~
# NG （数が違う）
```
puts "hello"
``````
Indented code blocks
Indented code blocksはバッククォートやチルダを使わず、 4つのスペースでインデントさせる方法 です。
puts "hello"
注意点
コードブロックの前後に空行が必要
Indented code blocksの 前後の行には空行が必要 です。
# OK
（空行）
puts "hello"
（空行）
# NG
foobar
puts "hello"
また、Indented code blocks内で空行を含めたい場合は、スペース4つのみの行を用意することで実現できます。
例）
def foo
"foo"
end
def bar
"bar"
end
↓
def foo
"foo"
end
def bar
"bar"
end
info stringをつけれない
Fenced code blocksで使える info stringをつけることはできません。
そのため、GitHubやQiitaなどでの シンタックスハイライト・ファイル名をつけることができない です。
4つより多いスペースは切り取られない
4つより多くのスペースがある場合は、 先頭4つのスペースのみが切り取られ、残りのスペースはそのまま になります。
スペース4つ
スペース5つ
↓ スペース5つの方の行頭にスペースが1つ含まれている
スペース4つ
スペース5つ
コードスパン
基本の書き方
コードスパンを書くときの基本形は以下のようになります。
`Ruby on Rails`
見え方は以下のようになります。
Ruby on Rails
定義
コードスパンは、 バッククォート（`） を1つ以上つなげたバックティック文字列で囲います。
上記の場合、バックティック文字列は`になります。
Tips
バッククォートは1つである必要はない
コードスパンは、 バッククォート（
`） を1つ以上つなげたバックティック文字列で囲います。
の通り、1つ以上であれば何個でも大丈夫です。
例1）
``foobar``
↓ バックティック文字列は``になる
foobar
例2）
``` コードスパンは`こうやってかく` ```
↓ バックティック文字列は```になる
コードスパンは`こうやってかく`
例3）
` `` ``` `` ``` ` ``
↓ バックティック文字列は`になる（先頭から解析される）
`` ``` `` ``` ``
コードスパン記法内で改行ができる
バックティック文字列で囲まれたテキストは改行をすることができます。
ただし、 改行は半角スペースに変換される ため注意が必要です。
例1）
`foo
bar`
↓ 改行が半角スペースになります
foo bar
例2）
``
foo
bar
``
↓ コードブロックに似てるけどコードスパン
foo bar
注意点
始まりと終わりのバックティック文字列を同じ文字列にする必要がある
始まりと終わりのバックティック文字列は同じ文字列 でなければなりません。
# OK
`Ruby on Rails`
# OK
``foo`bar``
# NG （始まりと終わりのバックティック文字列が違う）
``foo bar```
最後に
他の記法についてもまた別の記事でまとめていますので、合わせて読んでみてください！
詳しくはQiitaアカウントによる説明記事をご覧ください！
↓記事投稿シリーズまとめ
↓次の記事
↓前の記事