GravのMarkdown/Shortcode記法とそのレンダリング例をまとめた。

以下のテーマ・プラグイン等が有効なことを前提とする。

• Markdown-Extra (Gravの設定)
• Quark Theme（spectre.css）
• Shortcode-Core Plugin
• Markdown-Notices Plugin
• Highlight Plugin
• Image-Caption Plugin

それぞれの設定方法の詳細についてはリンク集から。

目次

1. 見出し（Headings）
2. 水平線（Horizontal Rules）
3. 強調・装飾（Emphasis）
4. 引用（Blockquotes）
5. 通知（Notices）
6. リスト（Lists）
7. コードブロック（Code blocks）
8. リンク（Links）
9. 表（Tables）
10. 図（Figures）
11. その他（Others）
12. 参考になるリンク集（References）

見出し（Headings）

# h1見出し
## h2見出し
### h3見出し
#### h4見出し
##### h5見出し
###### h6見出し

結果は省略

見出しタグはページを構造化するための特別な意味をもってる。単にサイズの大きなテキストを表示したい場合はShortcodeの[size][/size]を使うようにする。

水平線（Horizontal Rules）

---
***
___

結果

区切りとして使う場合は直前に空行がないと上側のテキストが見出しになる。

強調・装飾（Emphasis）

+ **太字（bold text）**
+ _イタリック（italic text）_
+ ~~取り消し線（strikethrough text）~~
+ `インラインコード(inline code)`
+ [u]アンダーライン（under lined text）[/u]
+ [color=blue]色付き文字・青（colored text blue）[/color]
+ [color=red]色付き文字・赤（colored text red）[/color]
+ [mark]マーカーテキスト（marked text）[/mark]
+ [size=24]サイズ指定されたテキスト（bigger/small text）[/size]
+ [left]左寄せされたテキスト（left aligned text）[/left]
+ [center]中央寄せされたテキスト（center aligned text）[/center]
+ [right]右寄せされたテキスト（right aligned text）[/right]
+ [mark style=block]複数行にわたるマーカーブロック<br/>（multiline marked block）[/mark]
+ 以上の組み合わせ

結果

• 太字（bold text）
• イタリック（italic text）
• 取り消し線（strikethrough text）
• インラインコード(inline code)
• アンダーライン（under lined text）
• 色付き文字・青（colored text blue）
• 色付き文字・赤（colored text red）
• マーカーテキスト（marked text）
• サイズ指定されたテキスト（bigger/small text）
• 左寄せされたテキスト（left aligned text）
• 中央寄せされたテキスト（center aligned text）
• 右寄せされたテキスト（right aligned text）
• 複数行にわたるマーカーブロック
  （multiline marked block）
• 以上の組み合わせ

[]のあるものを使うにはShortcode Coreプラグインを有効にしている必要がある。これらは他の強調表示と重複して使うことが出来る（組み合わせを上げればきりがない）。Markdownに直接HTMLタグを書き込むことも出来る。

引用（Blockquotes）

> 引用（いんよう、英語：citation, quotation）とは、広義には、自己のオリジナル作品のなかで他人の著作を副次的に紹介する行為、先人の芸術作品やその要素を副次的に自己の作品に取り入れること。
> 
> <cite>Wikipediaより</cite>

結果

引用（いんよう、英語：citation, quotation）とは、広義には、自己のオリジナル作品のなかで他人の著作を副次的に紹介する行為、先人の芸術作品やその要素を副次的に自己の作品に取り入れること。

Wikipediaより

引用はネストしたり、引用のなかでMarkdownを使用することもできる。

> 文化庁によれば、適切な「引用」と認められるためには、以下の要件が必要とされる。 
>> * ア 既に公表されている著作物であること
>> * イ 「公正な慣行」に合致すること
>> * ウ 報道，批評，研究などの引用の目的上「正当な範囲内」であること
>> * エ 引用部分とそれ以外の部分の「主従関係」が明確であること
>> * オ カギ括弧などにより「引用部分」が明確になっていること
>> * カ 引用を行う「必然性」があること
>> * キ 「出所の明示」が必要（コピー以外はその慣行があるとき）
>> 
>> <cite>— 文化庁 (2010)、§8. 著作物等の「例外的な無断利用」ができる場合 ⑧ ア、「引用」（第32条第1項）</cite>
>
> <cite>[Wikipedia](https://ja.wikipedia.org/wiki/%E5%BC%95%E7%94%A8)より</cite>

結果

文化庁によれば、適切な「引用」と認められるためには、以下の要件が必要とされる。

• ア 既に公表されている著作物であること
• イ 「公正な慣行」に合致すること
• ウ 報道，批評，研究などの引用の目的上「正当な範囲内」であること
• エ 引用部分とそれ以外の部分の「主従関係」が明確であること
• オ カギ括弧などにより「引用部分」が明確になっていること
• カ 引用を行う「必然性」があること
• キ 「出所の明示」が必要（コピー以外はその慣行があるとき）

— 文化庁 (2010)、§8. 著作物等の「例外的な無断利用」ができる場合 ⑧ ア、「引用」（第32条第1項）

Wikipediaより

セマンティック・ウェブの観点から引用にはblockquoteを使用するようにする。逆にそれ以外の場合には使用しないようにする。

通知（Notices）

! blockquoteにおける`>`(大なり)と根本的に同じように`!`(ビックリ)をもちいることで、このような色付きのボックスの中にテキストを配置できる。通知（Notices）という名前をしてはいるが単純に視覚的なアクセントを加えるものと考えてよい。

!! Noticesの中で、
!! * Markdown/Shortcodeを使える
!! * ネストはできない。

!!! `!`の数によって色を変えられる。どのような色になるか・あるいはそもそもどのようなデザインになるかはプラグインの設定とCSSによる。

!!!! これはMarkdownそのものの記法ではなくMarkdown Noticesプラグインによる記法だが、GravではほぼMarkdownの記法として用いられる。blockquoteに無理やりスタイルを当てているわけではないので内容が引用かどうかに関係なく使える。

結果

箇条書き（Lists）

完全に普通のMarkdownと同じ。

順序無しリスト（Unordered Lists）

順序無しリストに使用できる記号は
* アステリスク（asterisk）
+ プラス（plus）
- マイナス（minus）

結果

順序無しリストに使用できる記号は

• アステリスク（asterisk）
• プラス（plus）
• マイナス（minus）

ネストすることもできる

+ 日本語フォント
 - ＭＳゴシック
 - メイリオ
 - Noto Sans JP
+ 可変幅フォント
 * sans-serif
 * Open Sans
 * Lato
+ 等幅フォント
 - monospace
 - Consolas
 - Roboto Mono

• 日本語フォント
  • ＭＳゴシック
  • メイリオ
  • Noto Sans JP
• 可変幅フォント
  • sans-serif
  • Open Sans
  • Lato
• 等幅フォント
  • monospace
  • Consolas
  • Roboto Mono

順序付きリスト（Ordered Lists）

1. Japanese
2. Arithmetics
3. Sceience
4. Social Study
5. English

結果

1. Japanese
2. Arithmetics
3. Sceience
4. Social Study
5. English

数字は全部1.にすれば自分でナンバリングする必要が無い。

1. Japanese
1. Arithmetics
1. Sceience
1. Social Study
1. English

結果は上に同じ

コードブロック（Code blocks）

前後の行を```で挟むか全体をインデントする。

```python
# -*- coding:utf-8 -*-
import numpy as np
import matplotlib.pyplot as plt

if __name__ == '__main__':
  t = np.linspace(0, 2*np.pi, 100)
  x = np.sin(t)
  plt.plot(t, x)
  plt.show()
```

結果

# -*- coding:utf-8 -*-
import numpy as np
import matplotlib.pyplot as plt

if __name__ == '__main__':
  t = np.linspace(0, 2*np.pi, 100)
  x = np.sin(t)
  plt.plot(t, x)
  plt.show()

Highlightプラグインを有効にして、CSSを当てるとシンタックス・ハイライティングができる。開始の```の後に言語の種類を指定する。

リンク（Links）

完全に普通のMarkdownと同じ。

[アンカーテキスト](https://www.tm23forest.com "タイトル")

結果
アンカーテキスト

ただしタイトル部分は省略できる。

ページ内のアンカータグにid指定でジャンプできる。Markdown Extraが必要。

## 目次
* [第１章 いろはに](#chapter1)
* [第２章 ほへと](#chapter2)
* [第３章 ちりぬるを](#chapter3)

### 第１章 いろはに{#chapter1}

...

### 第２章 ほへと{#chapter2}

...

### 第３章 ちりぬるを{#chapter3}

...

結果は省略

表（Tables）

普通のMarkdownと同じ。ただしスタイルを当てるためのShortcodeが必要。

[center]**表：プログラミング言語の実行方法**[/center]
[div class="table"]
| 言語 | 実行方法 |
| --- | ----------- |
| C/C++ | コンパイラでネイティブコードに変換してから実行する。 |
| Java | バイトコードといわれる中間言語に変換してからJVM上で実行する。 |
| Python | スクリプトファイルを直接実行できる。 |
[/div]

結果

spectre.cssによるスタイルが当たっていることがわかる。コロンで右寄せ左寄せを指定できる。

[center]**表：プログラミング言語の実行方法**[/center]
[div class="table"]
| 言語 | 実行方法 |
| --: | :---------- |
| C/C++ | コンパイラでネイティブコードに変換してから実行する。 |
| Java | バイトコードといわれる中間言語に変換してからJVM上で実行する。 |
| Python | スクリプトファイルを直接実行できる。 |
[/div]

結果

spectre.cssの他のtableクラスを指定することもできる。

結果のみ(Markdownはクラス指定を変更するだけ)

• class="table table-striped table-hover

• class="table table-scroll

図（Figures）

記法はMarkdownと変わらないがGravの機能をいくつか使用できる。

画像（Images）

![Altテキストを記述する](leaf.jpg?classes=img-responsive "タイトル")

結果

通常はコンテンツ幅を超える画像サイズは必要ない。幅を指定するとGrav側でリサイズして配信する。

![Altテキストを記述する](leaf.jpg?classes=img-responsive&width=800 "タイトル")

結果

リンクと同じくタイトルは省略できる。

lazysizesの使用

Gravにはlazysizesプラグインがあるがいくつかの問題があるためここでは使用しない。GravのMarkdownファイルではYAMLフロントマターからTwigも処理させることができる。

process:
    twig: true

リサイズ機能などはTwigからも利用でき、これを利用してMarkdownからlazysizesによる遅延読み込みを行える。

<img class="lazyload" data-src="{{ page.media['leaf.jpg'].resize(800).url }}">

結果は略

当然だがテーマのbase.html.twigなどでlazysizes.min.jsが読み込まれている必要がある。

figure/figcaptionの使用

Image-Captionプラグインを使用する。user/config/plugins/image-captions.yamlを次のように設定する。

enabled: true
built_in_css: false
entire_page: false
scope: img.caption
figure_class: figure
figcaption_class: 'figure-caption text-center'

spectre.cssに合わせてこのようなクラス設定にしている。scopeに指定したクラスをMarkdownのclassesで指定することでプラグインの機能を呼び出せる。

![Altテキストを記述する](figure.png?classes=img-responsive,caption&width=800 "Figure：sin関数の形")

こういうFigureに関してはSVG形式も有用。SVG形式をソースに指定するとGravのリサイズ機能は効かない。

![Altテキストを記述する](figure.svg?classes=img-responsive,caption "Figure：sin関数の形")

その他（Others）

safe-email

E-mail:[safe-email autolink="true"]user@domain.com[/safe-email]

結果
E-mail:user@domain.com

HTMLコード

E-mail:<a href="mailto:&#117;&#115;&#101;&#114;&#64;&#100;&#111;&#109;&#97;&#105;&#110;&#46;&#99;&#111;&#109;">&#117;&#115;&#101;&#114;&#64;&#100;&#111;&#109;&#97;&#105;&#110;&#46;&#99;&#111;&#109;</a>

意味あるかは別としてエンコードできる。

フェイク・コンテンツ

[lorem s=5 /]

結果

というようにレイアウトを確かめるための適当な文章が生成される。オプションはpで段落、sでセンテンス、wで単語数を指定できる。

参考になるリンク集（References）

• PHP Markdown Extra
• Markdown Syntax | Grav Documentation
• Grav Shortcode Core Plugin
• Spectre.css CSS Framework