Gravで扱う、マークダウン記法、YAMLについて。違いや役割

Markdown（マークダウン）と YAML の違いと役割
1. 📝 Markdown（マークダウン）とは？
2. YAML とは？
Markdown（.md）と YAML の関係
1. Grav での .md ファイルの構造
✅ よく使うHTMLタグ → Markdown記法一覧
Grav で定義されている主要な YAML のデータ項目
まとめ

Markdown（マークダウン）と YAML の違いと役割

Grav では、Markdown（.md）と YAML（YAML Frontmatter） を組み合わせてページを作成します。それぞれの特徴や役割をわかりやすく解説します。

📝 Markdown（マークダウン）とは？

Markdown（.md） は、テキストをシンプルに記述できるマークアップ言語です。
ブログ記事やウェブページの「本文」を作成するために使用されます。

Markdown の特徴

シンプルな記法で HTML に変換できる
文書の見た目を簡単に整えられる
拡張子は .md（例：blog.md）

Markdown の基本例

# これは見出し（h1）
## これは小見出し（h2）

**これは太字**  
*これは斜体*  

- 箇条書き
- リスト項目 1
- リスト項目 2

[リンク](https://example.com)

Markdown

⏩ この Markdown を HTML に変換すると…

<h1>これは見出し（h1）</h1>
<h2>これは小見出し（h2）</h2>
<p><strong>これは太字</strong></p>
<p><em>これは斜体</em></p>
<ul>
  <li>箇条書き</li>
  <li>リスト項目 1</li>
  <li>リスト項目 2</li>
</ul>
<a href="https://example.com">リンク</a>

HTML

📌 Markdown は「ページの内容（本文）」を記述するためのもの！

YAML とは？

YAML（ヤムル） は、データを構造化して記述できる設定ファイルの形式です。
Grav では、「ページのメタデータ（設定情報）」を定義するために使用されます。

YAML の特徴

キーと値のペアでデータを管理
インデント（スペース）で階層を表現
拡張子は .yaml（ただし Grav では .md の中で YAML を使う）

YAML の基本例

title: "ブログ"
author: "管理者"
date: "2024-02-23"
categories:
  - Tech
  - Programming
tags:
  - Grav
  - CMS
published: true

YAML

📌 YAML は「ページの設定情報」を記述するためのもの！

Markdown（.md）と YAML の関係

Grav では、1つの .md ファイルの中に YAML（設定）と Markdown（本文）を共存 させます。Frontmatterは「YAMLを使って書かれた、Markdownファイルの冒頭にある“メタデータ部分”」のことです。

Grav での .md ファイルの構造

— で囲まれてMarkdownの最初に書きます。

---
title: "ブログ"  # ページタイトル
author: "管理者"  # 作成者
date: "2024-02-23"  # 投稿日時
taxonomy:
  category: Blog  # カテゴリー
  tag: [CMS, Grav]  # タグ
---

# これはブログ記事のタイトル
本文の内容を書きます。

- Markdown でリストを作成
- **太字** や *斜体* も可能

Markdown

✅ よく使うHTMLタグ → Markdown記法一覧

HTMLタグ	よくある用途	Markdownでの書き方	表示例
`<h1>`〜`<h6>`	見出し	`#`〜`######`	`## 見出し2` → 見出し2
`<p>`	段落（文章のまとまり）	空行で囲む	通常の文章
`<strong>`	強調（太字）	`太字` または `__太字__`	太字
`<em>`	斜体	`斜体` または `_斜体_`	斜体
`<br>`	改行	行末に半角スペース2つ	改行される（下記参照）
`<ul>` `<li>`	箇条書きリスト	`-` または `*`	`- 項目`
`<ol>` `<li>`	番号付きリスト	`1.` `2.` `3.`	`1. 項目`
`<code>`	インラインコード	`コード`	`コード`
`<pre><code>`	複数行コードブロック	“` 言語名で囲む	`js \n console.log()`
`<blockquote>`	引用	`> 引用文`	> 引用文
`<hr>`	横線（区切り）	`---` または `***`	―――――
`<a>`	リンク	`[リンクテキスト](URL)`
`<img>`	画像	`![代替テキスト](画像URL)`	画像が表示される
`<details>`	折りたたみ（Qiita限定HTML）	HTMLでのみ使用可	Qiitaで展開可能

Grav で定義されている主要な YAML のデータ項目

基本的な項目

項目	説明	例
title	ページのタイトル	title: “ホーム”
content	ページのコンテンツ設定	content: “”
media_order	ページに関連付けられたメディアファイルの順序	media_order: “image1.jpg, image2.png”
body_classes	HTML <body> タグに追加されるクラス	body_classes: “custom-class”

ページの振る舞いに関する項目

項目	説明	例
published	ページを公開するかどうか	published: true
date	ページの作成・公開日	date: “2025-02-23”
slug	URL のスラッグ（省略時はファイル名が使用される）	slug: “my-page”
taxonomy	タグやカテゴリーを設定	taxonomy: { category: “blog”, tag: [“tech”, “grav”] }
visible	ナビゲーションに表示するかどうか	visible: true
routable	URL でアクセスできるかどうか	routable: true
cache_enable	キャッシュの有効・無効を設定	cache_enable: false
process	Markdown や Twig の処理設定	process: { markdown: true, twig: false }

メニューナビゲーション関連

項目	説明	例
menu	メニューに表示する名称	menu: “ホーム”
order	ページの表示順序を設定	order: 1
header_image	ヘッダー画像の指定	header_image: “banner.jpg”

レイアウト・テンプレート関連

項目	説明	例
template	使用するテンプレート	template: “blog”
extends@	親ページから Frontmatter を継承	extends@: ‘/blog’
twig_first	Twig を Markdown より先に処理するか	twig_first: true

メタ情報（SEO）

項目	説明	例
metadata	ページのメタデータ（SEO 用）	metadata: { description: “Grav CMS の紹介” }
canonical	カノニカル URL の設定	canonical: “https://example.com/page”

アクセス制御

項目	説明	例
access	特定のユーザー権限でのアクセス制御	access: { site.login: true }
permissions	ユーザーの権限設定	permissions: { read: true, write: false }

まとめ

✅ Markdown（.md）

記事の本文を書くためのシンプルな言語
HTML に変換される

✅ YAML

ページの設定情報を管理
title や date、category などを定義できる
--- で囲むことで .md の中に組み込める

✅ Grav では .md の先頭に YAML、その下に Markdown を書く！