YAML

YAML とは、構造化されたデータを表現するためのフォーマットの1つです。NKSSG では、サイトの設定やテーマの設定で使います。ファイル形式が、ymlになっていることが、YAML で書かれている証です。また、各記事のフロントマターでも、YAML 記法を使います。

ここでは、YAML 記法について、NKSSG での使用例を用いて説明していきます。

なお、NKSSG では、YAML の処理に ruamel.yaml というパッケージを使っています。以下の説明は、この ruamel.yamlを使う前提の説明です。

【目次】

辞書
リスト
辞書と辞書のネスト
辞書とリストのネスト
コメント
値
複数行の値
辞書とリストの深いネスト
さらに深い辞書とリストのネスト

辞書

あるキーに対して、ある値を設定したい場合、「キー: 値」と書きます。コロンは半角で書き、コロンの後は半角スペースを書きます。

# 例
title: 記事のタイトル

# 実行結果
{'title': '記事のタイトル'}

次のように、複数並べて使うこともできます。

# 例
title: 初投稿
slug: my-first-post

# 実行結果
{'title': '初投稿', 'slug': 'my-first-post'}

辞書と辞書のネスト

辞書の値として、別の辞書を指定することができます。NKSSG では、サイトの設定で使われています。

# 例
site:
  site_name: Site Title
  site_url: http://example.com

# 実行結果
{'site': {'site_name': 'Site Title', 'site_url': 'http://example.com'}}

「キー: 値」と書いていた「値」の部分を辞書にするために、改行して半角スペースを2つつけています。その後は、同じように「キー: 値」と書きます。

上の例で、siteの後にも半角コロンがあることに注意しましょう。

辞書とリストのネスト

辞書の値としてリストを指定することができます。NKSSG では、タグなどのタクソノミーの指定をフロントマターで行うときに、使うことになります。

# 例
tag:
  - a
  - b
  - c

# 実行結果
{'tag': ['a', 'b', 'c']}

「キー: 値」と書いていた「値」の部分をリストにするために、改行して半角スペースを2つつけています。半角ハイフンを使うのは、リストの書き方で見た通りです。

ただ、フロントマターでタグを複数設定するときに、1つのタグで1行を使うと、本文がかなり下の方に追いやられてしまいます。このような場合には、リストは、次のように1行でまとめて書くことができます。

# 例
tag: [a, b, c]

# 実行結果
{'tag': ['a', 'b', 'c']}

こう書くと、だいぶスッキリしますね。どちらで書いても、同じ結果になります。

なお、複数の値を設定するときに、次のように書くことはできません。

# ダメな例
tag: a
tag: b
tag: c

1つのキーを複数回使うとエラーになってしまいます。

「# 」をつけると、行末までがコメントになります。

設定を一時的に無効にするために「# 」をつける、という使い方ができます。

VSCode を使っている場合、ymlファイル内では、Ctrl + /によってコメントのオン・オフができます。複数行を選択してまとめてオン・オフにすることもできます。

値

ここまで紹介した辞書やリストの書き方の中で、「値」が出てきました。値にもいくつか種類があります。

NKSSG でよく使うものは、文字列です。ダブルクォーテーション「"」や、シングルクォーテーション「'」で囲むと、自動的に文字列と認識します。

True か False を設定する真偽値も使えます。YAML では True に判定される書き方、Falseに判定される書き方はいろいろありますが、True, False をそれぞれ使うと間違いないでしょう。この書き方は、Python とも整合性があってわかりやすいと思います。

日付は、次のような形式で書きます。

2021-04-01          # 日付
2021-04-01 12:34:56 # タイムスタンプ

スラッシュは使えません。年・月・日の間には、ハイフンを使います。

整数や小数などの数値も使えます。10 や 3.14 など、普通の数値の書き方で使います。数値で使う場合は、クォーテーションで囲まずに使います。

数値や日付に変換できなかったものは、文字列として扱われます。

何も値を設定しない場合は、null と認識されます。

複数行の値

例えば、フロントマターで summary を定義するときに、複数行の値を書きたい場合があるかもしれません。その場合は、次のように書きます。書き方によって、改行の認識方法が変わります。

# 例
summary1:
  line1
  line2

summary2: |
  line1
  line2

summary3: |-
  line1
  line2

# 実行結果
{'summary1': 'line1 line2', 'summary2': 'line1\nline2\n', 'summary3': 'line1\nline2'}

縦線がないと、改行は空白に変換されます。縦線があると、改行を改行のまま認識します。|- と書けば、最後の改行を取り除くことができます。

辞書とリストの深いネスト

辞書の値がリストになっている例をすでに見ましたが、そのリストに含まれている値がまた別の辞書になっている、という例を見てみます。例えば、投稿タイプの設定は次のようになっています。

# 例
post_type:
  - post:
      archive_type: date
  - page
      archive_type: section

# 実行結果
{'post_type': [{'post': {'archive_type': 'date'}}, {'page': {'archive_type': 'section'}}]}

post_typeには、2つの辞書がリストに入っています。1つ目の辞書は、postの設定に関するものであり、archive_typeの設定を含んだ辞書になっています。

リストか、辞書か、インデントをどうするか、と考え出すと混乱してくるので、デフォルトの設定を参考にして設定するのが手っ取り早いです。

さらに深い辞書とリストのネスト

NKSSG では、nkssg.yml のタクソノミー設定でさらに深いネストが使われています。各タクソノミーに対し、各タームをリストにしているため、「リストの中のリスト」が登場します。

# 例
taxonomy:
  - tag:
    - tag1
    - tag2
    - tag3
  - category:
    - cat1
    - cat2

# 実行結果
{'taxonomy': [{'tag': ['tag1', 'tag2', 'tag3']}, {'category': ['cat1', 'cat2']}]}

taxonomyには、tagとcategoryという2つが含まれています。tagには、3つのタームが含まれていて、categoryには、2つのタームが含まれている、という設定になっています。

さらに、各タームにslugなどの設定を入れたい場合は、次のようになります。

# 例
taxonomy:
  - tag:
    - tag1
    - タグ2:
        slug: tag2
    - tag3

# 実行結果
{'taxonomy': [{'tag': ['tag1', {'タグ2': {'slug': 'tag2'}}, 'tag3']}]}

slugの設定は、「タグ2」の書かれているところからさらに半角スペース2つ分だけ下がっている点に注意しましょう。半角スペースがない場合は、正しく設定できません。以下は、正しくない例です。

# 間違っている例
taxonomy:
  - tag:
    - tag1
    - タグ2:
      slug: tag2
    - tag3

# 実行結果
{'taxonomy': [{'tag': ['tag1', {'タグ2': None, 'slug': 'tag2'}, 'tag3']}]}

これはどう解釈されているかというと、tagの2つ目のタームは、「タグ2」と「slug」の2つをキーに持つ辞書だ、となってしまっているわけです。1段下げないと、並列に扱われてしまいます。

ネストが深くなってくると、字下げがどれだけ必要かわかりにくくなってきます。デフォルトの設定を真似して設定するようにしてみましょう。

Next: Markdown

Prev: Visual Studio Code