よく使うGravのMarkdown/Shortcode記法

/ Grav

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)

---
***
___

結果




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

Gravではデフォルトで===をサマリ・セパレータとして使用します(レンダリングはされない)。コンテンツを記述するMarkdownファイルの内===より上がpage.summaryになります。

強調・装飾(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タグを書き込むことも出来る。

全ての装飾はインラインHTMLタグかインラインspanタグ+style属性で実現できますがShortcodeの方がいくらか簡素に書けて直観的です。それだけではなく、Shortcode記法のパースはMarkdown記法のパースと独立しているので、Shortcodeを使う方が意図せぬ結果を招きにくいです。

引用(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に無理やりスタイルを当てているわけではないので内容が引用かどうかに関係なく使える。

結果

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

Noticesの中で、

  • Markdown/Shortcodeを使える
  • ネストはできない。

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

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

箇条書き(Lists)

完全に普通のMarkdownと同じ。

順序無しリスト(Unordered Lists)

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

結果

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

  • アステリスク(asterisk)
  • プラス(plus)
  • マイナス(minus)

ネストすることもできる

+ 日本語フォント
 - MSゴシック
 - メイリオ
 - Noto Sans JP
+ 可変幅フォント
 * sans-serif
 * Open Sans
 * Lato
+ 等幅フォント
 - monospace
 - Consolas
 - Roboto Mono
  • 日本語フォント
    • MSゴシック
    • メイリオ
    • 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が必要。

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

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

...

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

...

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

...

結果は省略

表(Tables)

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

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

結果

表:プログラミング言語の実行方法

言語 実行方法
C/C++ コンパイラでネイティブコードに変換してから実行する。
Java バイトコードといわれる中間言語に変換してからJVM上で実行する。
Python スクリプトファイルを直接実行できる。

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

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

結果

表:プログラミング言語の実行方法

言語 実行方法
C/C++ コンパイラでネイティブコードに変換してから実行する。
Java バイトコードといわれる中間言語に変換してからJVM上で実行する。
Python スクリプトファイルを直接実行できる。

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

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

  • class="table table-striped table-hover

表:プログラミング言語の実行方法

言語 実行方法
C/C++ コンパイラでネイティブコードに変換してから実行する。
Java バイトコードといわれる中間言語に変換してからJVM上で実行する。
Python Pythonインタプリタからスクリプトファイルを直接実行できる。
C# 中間言語にコンパイルしてから.NET Framework上で実行する。

  • class="table table-scroll

表:プログラミング言語の実行方法

言語 実行方法 コンパイラコマンド 実行コマンド 説明
C/C++ コンパイラでネイティブコードに変換してから実行する。 gcc/cl 実行ファイル clはVisual Studioのもの
Java バイトコードといわれる中間言語に変換してからJVM上で実行する。 javac java 主にopenJDKに含まれる
Python Pythonインタプリタからスクリプトファイルを直接実行できる。 - python インタプリタと呼ばれることは少なくなった
C# 中間言語にコンパイルしてから.NET Framework上で実行する。 cs 実行ファイル(Windows) csはVisual Studioのもの

図(Figures)

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

画像(Images)

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

結果
Altテキストを記述する

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

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

結果
Altテキストを記述する

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

元画像を最適化してアップロードしても、Gravのリサイズ機能によってリサイズされると最適化の効果は失われます。いくつかのプラグインによってリサイズ後の画像に自動的に最適化を施すことができますが、今のところこれらは不必要に有料のAPIを使用します(これは残念なことです)。

lazysizesの使用

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

process:
    twig: true

Twigを処理させると設定によってはサイト全体がエラーで落ちることがあるので注意する。Gravはリクエストごとに全てのページを含むPagesオブジェクトを構築するため、関係のないページに影響しえる。

リサイズ機能などは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関数の形")
Altテキストを記述する
Figure:sin関数の形

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

![Altテキストを記述する](figure.svg?classes=img-responsive,caption "Figure:sin関数の形")
Altテキストを記述する
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 /]

結果

Lorem ipsum dolor sit amet consectetur adipiscing, elit fusce enim nulla nisi magna tellus, leo varius massa lectus sapien. Tempus convallis suspendisse per dignissim aliquam potenti porta laoreet, dictumst enim mattis rutrum facilisi proin sed risus, id leo lectus senectus ut felis ad. Cursus bibendum nunc fringilla gravida class non malesuada, adipiscing iaculis volutpat tristique pulvinar rhoncus lacinia, vivamus cras condimentum dictumst turpis magnis. Cras litora potenti fames gravida curabitur eleifend varius neque, tortor accumsan non tempor massa morbi metus eros, proin nisi natoque habitant volutpat dictum blandit. Faucibus tempus ultrices curae dictumst mollis, tristique dictum volutpat neque, molestie enim vestibulum egestas.

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

参考になるリンク集(References)