Markdown記法ガイド

このウェブサイトの記事はMarkdown（MDX）ファイルで管理していて、AstroのContent collectionsの機能を使用して静的なウェブページを作成しています。Markdownのパースにはremarkを、HTMLへの変換にはrehypeを使用し、remarkプラグインとして独自に拡張した記法を利用できるようにしています。記法の開発にあたって、usagimaruさんの記事「自分好みのテキストレイアウトシステムを作る」で提案されている『角かく括かっ弧こ構こう文ぶん』を参考にさせていただきました。

このページで使用しているサンプルテキストは、宮沢賢治「ポラーノの広場」から引用しています。

見出し

このウェブサイトの記事で使用できる見出しレベルは2と3のみで、4以降を指定しても3と同じスタイルで表示します。

これから先はサンプルテキストです。そのころわたくしは、モリーオ市の博物局に勤めて居りました。

十八等官でしたから役所のなかでも、ずうっと下の方でしたし俸給もほんのわずかでしたが、受持ちが標本の採集や整理で生れ付き好きなことでしたから、わたくしは毎日ずいぶん愉快にはたらきました。殊にそのころ、モリーオ市では競馬場を植物園に拵え直すというので、その景色のいいまわりにアカシヤを植え込んだ広い地面が、切符売場や信号所の建物のついたまま、わたくしどもの役所の方へまわって来たものですから、わたくしはすぐ宿直という名前で月賦で買った小さな蓄音器と二十枚ばかりのレコードをもって、その番小屋にひとり住むことになりました。わたくしはそこの馬を置く場所に板で小さなしきいをつけて一疋の山羊を飼いました。毎朝その乳をしぼってつめたいパンをひたしてたべ、それから黒い革のかばんへすこしの書類や雑誌を入れ、靴もきれいにみがき、並木のポプラの影法師を大股にわたって市の役所へ出て行くのでした。

見出しレベル3

あのイーハトーヴォのすきとおった風、夏でも底に冷たさをもつ青いそら、うつくしい森で飾られたモリーオ市、郊外のぎらぎらひかる草の波。

またそのなかでいっしょになったたくさんのひとたち、ファゼーロとロザーロ、羊飼のミーロや、顔の赤いこどもたち、地主のテーモ、山猫博士のボーガント・デストゥパーゴなど、いまこの暗い巨きな石の建物のなかで考えていると、みんなむかし風のなつかしい青い幻燈のように思われます。では、わたくしはいつかの小さなみだしをつけながら、しずかにあの年のイーハトーヴォの五月から十月までを書きつけましょう。

見出しレベル2

見出しレベル3

見出しレベル2と3が隣り合ったときは、余白が狭くなるように調整しています。

見出しには inline code を含められます

見出しには inline code を含められます

## 見出しには `inline code` を含められます

### 見出しには `inline code` を含められます

改行

本来のMarkdownの記法では、改行は行末に半角スペースを2つ挿入することになっています。
（ここで改行）このように改行できます。

しかし、このウェブサイトではGitHub Flavored Markdownを参考に、単純に改行文字を挿入するだけで改行できるように調整しています。
（ここで改行）このように改行できます。

（ここで2行分の改行）空行を挿入した場合は、その行までのテキストが1つの文章の単位だと認識されて、p要素としてマークアップされます。

均等割付と改行機会要素

このウェブサイトの記事の本文は、均等割付を実現するために、p要素に text-align: justify; text-justify: inter-character; を指定しています。また、BudouX（rehype-budoux）を使用して、改行機会要素であるwbr要素を挿入しています。

強調

Markdownあるいは独自の記法で、強調を表現できます。

サンプル

重要なテキストはMarkdownの記法で強調を表現できます。
また、独自の記法でも強調を表現できます。
原則的にはMarkdownの記法を優先して使用します。

重要なテキストはMarkdownの記法で**強調**を表現できます。
また、独自の記法でも[強調(strong)]を表現できます。
原則的にはMarkdownの記法を優先して使用します。

打ち消し

Markdownあるいは独自の記法で、打ち消しを表現できます。

サンプル

打ち消したテキストはMarkdownの記法で打ち消しを表現できます。
また、独自の記法でも打ち消しを表現できます。
原則的にはMarkdownの記法を優先して使用します。

打ち消したテキストはMarkdownの記法で~~打ち消し~~を表現できます。
また、独自の記法でも[打ち消し(stroke)]を表現できます。
原則的にはMarkdownの記法を優先して使用します。

ルビ

独自の記法を使用して、テキストにルビを振ることができます。読みをスペースで区切ると1文字ずつ読みを割り当てるモノルビになり、区切らなければまとめて読みを振るグループルビになります。読みの数と基底文字の数が一致しない場合は、グループルビとして表示し、ビルドログに警告を出します。

サンプル：グループルビ

宮沢賢治みやざわけんじ

[宮沢賢治(ruby, みやざわけんじ)]

サンプル：モノルビ

宮みや沢ざわ賢けん治じ

[宮沢賢治(ruby, みや ざわ けん じ)]

サンプル：文章中のルビ

十八等官でしたから役所のなかでも、ずうっと下の方でしたし俸給ほうきゅうもほんのわずかでしたが、受持ちが標本の採集や整理で生れ付き好きなことでしたから、わたくしは毎日ずいぶん愉快にはたらきました。殊にそのころ、モリーオ市では競馬場を植物園に拵こしらえ直すというので、その景色のいいまわりにアカシヤを植え込んだ広い地面が、切符売場や信号所の建物のついたまま、わたくしどもの役所の方へまわって来たものですから、わたくしはすぐ宿直という名前で月賦で買った小さな蓄音器と二十枚ばかりのレコードをもって、その番小屋にひとり住むことになりました。

十八等官でしたから役所のなかでも、ずうっと下の方でしたし[俸給(ruby, ほうきゅう)]もほんのわずかでしたが、受持ちが標本の採集や整理で生れ付き好きなことでしたから、わたくしは毎日ずいぶん愉快にはたらきました。殊にそのころ、モリーオ市では競馬場を植物園に[拵(ruby, こしら)]え直すというので、その景色のいいまわりにアカシヤを植え込んだ広い地面が、切符売場や信号所の建物のついたまま、わたくしどもの役所の方へまわって来たものですから、わたくしはすぐ宿直という名前で月賦で買った小さな蓄音器と二十枚ばかりのレコードをもって、その番小屋にひとり住むことになりました。

圏点

独自の記法を使用して、テキストに圏点を振ることができます。圏点は強調表現の一種として解釈し、strong要素でマークアップされます。

サンプル

そのころわたくしは、モリーオ市の博物局に勤めて居りました。

そのころわたくしは、モリーオ市の[博物局(emphasize)]に勤めて居りました。

キーシンボル

独自の記法を使用して、キーボードのキーを表現できます。キーの名前だけでなく、シンボルの表示にも対応しています。シンボルの場合は、表示するキーに対応した名前がaria-label属性に指定されます。

サンプル：キーの名前

ここでCommandキーを押します。

ここで[Command(kbd)]キーを押します。

サンプル：シンボル

ここで⌘⇧↑キーを押します。
また、⌫のように指定すると、aria-label属性を上書きできます。

ここで[(kbd.command)][(kbd.shift)][(kbd.arrow-up)]キーを押します。
また、[(kbd.delete,title="Backspace")]のように指定すると、aria-label属性を上書きできます。

使用できるプリセットは次のとおりです。

プリセット	記号	プリセット	記号
control	⌃	space	␣
option	⌥	tab	⇥
shift	⇧	escape	⎋
command	⌘	arrow-up	↑
delete	⌫	arrow-down	↓
return	⏎	arrow-left	←
		arrow-right	→

リスト

Markdownの記法で、テキストのリストを表現できます。

サンプル

あのイーハトーヴォのすきとおった風、夏でも底に冷たさをもつ青いそら、うつくしい森で飾られたモリーオ市、郊外のぎらぎらひかる草の波。

• シグラフの丘
• ムルトの林道
  • 林道入り口の廃屋
  • 林道中ほどの泉
  • 林を抜けた先の小さな村
• クーボーの草原
  • 広大な草地
    • ここでキャンプを張り、満天の星の下で夜を明かした。
      • 満天の星の下
        • 夜を
          • 明かした

またそのなかでいっしょになったたくさんのひとたち、ファゼーロとロザーロ、羊飼のミーロや、顔の赤いこどもたち、地主のテーモ、山猫博士のボーガント・デストゥパーゴなど、いまこの暗い巨きな石の建物のなかで考えていると、みんなむかし風のなつかしい青い幻燈のように思われます。

1. シグラフの丘
2. ムルトの林道
   1. 林道入り口の廃屋
   2. 林道中ほどの泉
   3. 林を抜けた先の小さな村
3. クーボーの草原
   1. 広大な草地
      1. ここでキャンプを張り、満天の星の下で夜を明かした。
         1. 満天の星の下
            1. 夜を
               1. 明かした

では、わたくしはいつかの小さなみだしをつけながら、しずかにあの年のイーハトーヴォの五月から十月までを書きつけましょう。

1. シグラフの丘
2. ムルトの林道
   • 林道入り口の廃屋
   • 林道中ほどの泉
   • 林を抜けた先の小さな村
3. クーボーの草原
   • 広大な草地
     1. ここでキャンプを張り、満天の星の下で夜を明かした。
        • 満天の星の下
          1. 夜を
             • 明かした

定義リスト

HTMLの記法で、定義リストを表現できます。

サンプル

あのイーハトーヴォのすきとおった風、夏でも底に冷たさをもつ青いそら、うつくしい森で飾られたモリーオ市、郊外のぎらぎらひかる草の波。

シグラフの丘

見晴らしのよい高台。遠くにイーハトーヴの森が一望できる出発点。

ムルトの林道

暗い杉林を抜ける長い道。夜には星も見えず、風の音だけが響く。

• 林道入り口の廃屋
• 林道中ほどの泉
• 林を抜けた先の小さな村

クーボーの草原

広大な草地。

ここでキャンプを張り、満天の星の下で夜を明かした。

またそのなかでいっしょになったたくさんのひとたち、ファゼーロとロザーロ、羊飼のミーロや、顔の赤いこどもたち、地主のテーモ、山猫博士のボーガント・デストゥパーゴなど、いまこの暗い巨きな石の建物のなかで考えていると、みんなむかし風のなつかしい青い幻燈のように思われます。

あのイーハトーヴォのすきとおった風、夏でも底に冷たさをもつ青いそら、うつくしい森で飾られたモリーオ市、郊外のぎらぎらひかる草の波。

<dl>
  <dt>シグラフの丘</dt>
  <dd>見晴らしのよい高台。遠くにイーハトーヴの森が一望できる出発点。</dd>
  <dt>ムルトの林道</dt>
  <dd>
    暗い杉林を抜ける長い道。夜には星も見えず、風の音だけが響く。
    <ul>
      <li>林道入り口の廃屋</li>
      <li>林道中ほどの泉</li>
      <li>林を抜けた先の小さな村</li>
    </ul>
  </dd>
  <dt>クーボーの草原</dt>
  <dd>広大な草地。</dd>
  <dd>ここでキャンプを張り、満天の星の下で夜を明かした。</dd>
</dl>

またそのなかでいっしょになったたくさんのひとたち、ファゼーロとロザーロ、羊飼のミーロや、顔の赤いこどもたち、地主のテーモ、山猫博士のボーガント・デストゥパーゴなど、いまこの暗い巨きな石の建物のなかで考えていると、みんなむかし風のなつかしい青い幻燈のように思われます。

画像

src/ ディレクトリ内の画像ファイルをインポートすることで、Astroの画像最適化（フォーマット変換・サイズ調整など）が適用されます。使用する画像はMDXファイルの先頭でインポートしておきます。

import { Image, Picture } from 'astro:assets';
import exampleImage from '../../assets/pages/markdown/example.jpg';

img

基本的な画像表示には <Image /> コンポーネントを使います。alt 属性は必須で、画像の内容をテキストで書きます。

<Image src={exampleImage} alt="道路の端に群生するタンポポ。白い綿毛と黄色い花が咲き、周囲のアスファルトに白い花びらが散っている" />

figure

キャプションを付けたいときは、<figure> 要素と <figcaption> 要素で囲みます。

<figure>
  <Image src={exampleImage} alt="" />
  <figcaption>道路の端に群生するタンポポ。白い綿毛と黄色い花が咲き、周囲のアスファルトに白い花びらが散っている</figcaption>
</figure>

picture

複数のフォーマット（AVIFやWebPなど）の <source> を明示して出力したいときは <Picture /> コンポーネントを使います。通常は <Image /> で十分です。

<figure>
  <Picture src={exampleImage} formats={['avif', 'webp']} alt="" />
  <figcaption>道路の端に群生するタンポポ。白い綿毛と黄色い花が咲き、周囲のアスファルトに白い花びらが散っている</figcaption>
</figure>

スペーサー

独自の記法を使用して、テキストのあいだに余白を挿入できます。また、引数に単位つきの数値を指定することで、余白の大きさを自由に決められます。引数を省略すると 1em になり、単位は em・rem・px が使えます。

サンプル

宮沢賢治ポラーノの広場
宮沢賢治ポラーノの広場

宮沢賢治[(spacer)]ポラーノの広場
宮沢賢治[(spacer, 3em)]ポラーノの広場

区切り線

Markdownあるいは独自の記法で、区切り線を表現できます。

サンプル：実線（Markdownの記法）

あのイーハトーヴォのすきとおった風、夏でも底に冷たさをもつ青いそら、うつくしい森で飾られたモリーオ市、郊外のぎらぎらひかる草の波。

---

またそのなかでいっしょになったたくさんのひとたち、ファゼーロとロザーロ、羊飼のミーロや、顔の赤いこどもたち、地主のテーモ、山猫博士のボーガント・デストゥパーゴなど、いまこの暗い巨きな石の建物のなかで考えていると、みんなむかし風のなつかしい青い幻燈のように思われます。

あのイーハトーヴォのすきとおった風、夏でも底に冷たさをもつ青いそら、うつくしい森で飾られたモリーオ市、郊外のぎらぎらひかる草の波。

---

またそのなかでいっしょになったたくさんのひとたち、ファゼーロとロザーロ、羊飼のミーロや、顔の赤いこどもたち、地主のテーモ、山猫博士のボーガント・デストゥパーゴなど、いまこの暗い巨きな石の建物のなかで考えていると、みんなむかし風のなつかしい青い幻燈のように思われます。

サンプル：実線（独自の記法）

あのイーハトーヴォのすきとおった風、夏でも底に冷たさをもつ青いそら、うつくしい森で飾られたモリーオ市、郊外のぎらぎらひかる草の波。

---

またそのなかでいっしょになったたくさんのひとたち、ファゼーロとロザーロ、羊飼のミーロや、顔の赤いこどもたち、地主のテーモ、山猫博士のボーガント・デストゥパーゴなど、いまこの暗い巨きな石の建物のなかで考えていると、みんなむかし風のなつかしい青い幻燈のように思われます。

あのイーハトーヴォのすきとおった風、夏でも底に冷たさをもつ青いそら、うつくしい森で飾られたモリーオ市、郊外のぎらぎらひかる草の波。

[(divider)]

またそのなかでいっしょになったたくさんのひとたち、ファゼーロとロザーロ、羊飼のミーロや、顔の赤いこどもたち、地主のテーモ、山猫博士のボーガント・デストゥパーゴなど、いまこの暗い巨きな石の建物のなかで考えていると、みんなむかし風のなつかしい青い幻燈のように思われます。

サンプル：二重線

あのイーハトーヴォのすきとおった風、夏でも底に冷たさをもつ青いそら、うつくしい森で飾られたモリーオ市、郊外のぎらぎらひかる草の波。

---

またそのなかでいっしょになったたくさんのひとたち、ファゼーロとロザーロ、羊飼のミーロや、顔の赤いこどもたち、地主のテーモ、山猫博士のボーガント・デストゥパーゴなど、いまこの暗い巨きな石の建物のなかで考えていると、みんなむかし風のなつかしい青い幻燈のように思われます。

あのイーハトーヴォのすきとおった風、夏でも底に冷たさをもつ青いそら、うつくしい森で飾られたモリーオ市、郊外のぎらぎらひかる草の波。

[(divider, double)]

またそのなかでいっしょになったたくさんのひとたち、ファゼーロとロザーロ、羊飼のミーロや、顔の赤いこどもたち、地主のテーモ、山猫博士のボーガント・デストゥパーゴなど、いまこの暗い巨きな石の建物のなかで考えていると、みんなむかし風のなつかしい青い幻燈のように思われます。

サンプル：破線

あのイーハトーヴォのすきとおった風、夏でも底に冷たさをもつ青いそら、うつくしい森で飾られたモリーオ市、郊外のぎらぎらひかる草の波。

---

またそのなかでいっしょになったたくさんのひとたち、ファゼーロとロザーロ、羊飼のミーロや、顔の赤いこどもたち、地主のテーモ、山猫博士のボーガント・デストゥパーゴなど、いまこの暗い巨きな石の建物のなかで考えていると、みんなむかし風のなつかしい青い幻燈のように思われます。

あのイーハトーヴォのすきとおった風、夏でも底に冷たさをもつ青いそら、うつくしい森で飾られたモリーオ市、郊外のぎらぎらひかる草の波。

[(divider, dash)]

またそのなかでいっしょになったたくさんのひとたち、ファゼーロとロザーロ、羊飼のミーロや、顔の赤いこどもたち、地主のテーモ、山猫博士のボーガント・デストゥパーゴなど、いまこの暗い巨きな石の建物のなかで考えていると、みんなむかし風のなつかしい青い幻燈のように思われます。

テキストリンク

Markdownの記法で、テキストにハイパーリンクを指定できます。リンク先のパスに http:// または https:// を含む場合は、外部のウェブページへのリンクとしてa要素に target="_blank" rel="noopener noreferrer" が指定されます。また、URLを書くとa要素でマークアップされます。

サンプル

トップページ
漫才コンビの名前の一覧
ポラーノの広場
https://www.aozora.gr.jp/cards/000081/files/1935_19925.html

[トップページ](/)
[漫才コンビの名前の一覧](/manzai/)
[ポラーノの広場](https://www.aozora.gr.jp/cards/000081/files/1935_19925.html)
https://www.aozora.gr.jp/cards/000081/files/1935_19925.html

YouTube

独自の記法を使用して、YouTubeの動画をウェブページに埋め込めます。watch?v=・youtu.be・shorts・live・embed の各URL形式に対応しています。動画はプライバシー強化モード（youtube-nocookie.com）のiframeで埋め込まれ、再生するまでCookieが保存されません。URLに t=90 または start=90（秒数）が含まれていれば、再生開始位置として引き継ぎます。

title 引数はiframeの title 属性（読み上げ用のラベル）になります。省略すると「YouTube動画」になるため、動画のタイトルを指定することをおすすめします。

サンプル

『ミー・アット・ザ・ズー』（英語：Me at the zoo）は、動画投稿サイトYouTubeに投稿された最初の動画である。この動画は2005年4月23日20時31分52秒（PDT。UTCでは2005年4月24日3時31分52秒）に、YouTubeの創設者の1人であるジョード・カリムが「jawed」というアカウント名で投稿したもので、カリムの高校時代の友人であるヤコフ・ラピツキーによって撮影されたものである。

内容はアメリカ合衆国カリフォルニア州サンディエゴのサンディエゴ動物園で撮影された19秒の映像で、象舎で展示されている象の前で、象の「すごくすごくすごく長い鼻」に関心を寄せているカリムの様子が動画に収められている。（出典：Wikipedia「ミー・アット・ザ・ズー」）

『ミー・アット・ザ・ズー』（英語：Me at the zoo）は、動画投稿サイトYouTubeに投稿された最初の動画である。この動画は2005年4月23日20時31分52秒（PDT。UTCでは2005年4月24日3時31分52秒）に、YouTubeの創設者の1人であるジョード・カリムが「jawed」というアカウント名で投稿したもので、カリムの高校時代の友人であるヤコフ・ラピツキーによって撮影されたものである。

[(youtube, https://www.youtube.com/watch?v=jNQXAC9IVRw, title="Me at the zoo")]

内容はアメリカ合衆国カリフォルニア州サンディエゴのサンディエゴ動物園で撮影された19秒の映像で、象舎で展示されている象の前で、象の「すごくすごくすごく長い鼻」に関心を寄せているカリムの様子が動画に収められている。（出典：[Wikipedia「ミー・アット・ザ・ズー」](https://ja.wikipedia.org/wiki/%E3%83%9F%E3%83%BC%E3%83%BB%E3%82%A2%E3%83%83%E3%83%88%E3%83%BB%E3%82%B6%E3%83%BB%E3%82%BA%E3%83%BC)）

エスケープ

Markdownあるいは独自の記法をそのまま文中に表示したいときは[(divider)]のようにエスケープするか、インラインコードとして [(divider)] のように書きます。

なお、Markdownのリンク記法 [テキスト](URL)・脚注 [^1]・メソッドの丸括弧をともなわないただの角括弧 [こんにちは] は、角括弧構文として解釈されません。

このウェブサイト独自の記法

usagimaruさんの記事「自分好みのテキストレイアウトシステムを作る」で提案されている『角かく括かっ弧こ構こう文ぶん』を参考に、このウェブサイト独自の記法を用意しました。

記法の共通のルールとして、対象のテキストを角括弧で囲み、テキスト直後の丸括弧の中にメソッドと引数を書きます。dividerなど、対象を持たない場合はテキストを省略してもかまいません。

[テキスト(メソッド, 引数)]

• メソッド名は小文字の英字とハイフンで書きます。
• メソッド.プリセット の形式でプリセットを呼び出せます（例：kbd.command）。
• 式は行をまたげません。

引数はカンマで区切って並べ、前後の空白は無視されます。名前=値 の形式で名前付き引数を書けます（例：title="Me at the zoo"）。カンマなどを含む値は引用符で囲みます。ストレートクォート（" "）に加えて、カーリークォート（" "）も使えます。

このウェブサイトで使えるメソッドは次のとおりです。区切り線とYouTubeは、単独の段落としてのみ書けます（段落の途中に書いても変換されません）。

メソッド	機能	種別
strong	強調（太字）	インライン
stroke	打ち消し	インライン
ruby	ルビ	インライン
emphasize	圏点	インライン
kbd	キーシンボル	インライン
spacer	水平方向の余白	インライン
divider	区切り線	ブロック
youtube	YouTube動画の埋め込み	ブロック

実装

• この記法はapps/web/src/lib/remark-bracket-syntaxに実装したremarkプラグインで、.md と .mdx の両方で使えます。生成する要素のCSSは bracket-syntax.css にまとめています。
• 構文に合致しない式・未知のメソッド・不正な引数は、変換せずにソースの文字列をそのまま表示します。ビルドは失敗せず、ビルドログに bracket-syntax: で始まる警告を出します。
• 参考にした記法のうち、次のものは今のところ未対応です。書いた場合は変換されず、そのまま表示されます。
  • 範囲オペレーター：[(alignment:center)..]〜[..] のように複数の段落へ効果を適用する記法（alignment・columns）
  • ネスト：[[テキスト(stroke)] (strong)] のように複数の効果を重ねる記法
  • pointer（ポインターシンボル）・disable（機能の無効化マーカー）・spacer の auto（マルチカラムでの改列指定）