静的サイトジェネレータPelicanで使用可能なMarkdown記法

This image is generated with ChatGPT-4 Omni, and edited by the author.
作成日:2024年10月16日(水) 00:00
最終更新日:2024年10月16日(水) 22:04
カテゴリ:Web
タグ:  Pelican Markdown Python Tips

静的サイトジェネレータPelican では記事の執筆にMarkdownが使えるので便利です．本記事ではPelicanで使用可能なMarkdown記法を紹介します．

目次

こんにちは．高山です．
今回の記事は，Pelicanの記事ファイルの書き方の補足記事になります．

本サイトの記事作成で使用している静的サイトジェネレータ Pelican は，記事ファイルの執筆に Markdown が使えます．

Markdown の解説は山ほどあるので今更ではあるのですが，Pelican 上での動作確認の意味も込めて本記事でまとめておくことにしました．
基本的には Markdown Guide の内容に即していますが，注意が必要な記法は適時補足を加えます．

1. 基本記法

まずは，オリジナルのマークダウンで使用可能な記法を説明します．

1.1 ヘッディング

ヘッディング要素は下記のように書きます．

# H1
## H2
### H3
...
###### H6

これらは HTML の <h1> から <h6> 要素に変換されます．

H1

H2

H3

1.2 太字

** で対象文字列を囲むことで，太字にできます．

**太字**テキスト

HTML の <strong> 要素に変換され，下記のように表示されます．

太字テキスト

なお，__でも太字に変換されますが空白を挟まないと上手く動かないので，推奨されていません．

1.3 斜体文字

* で対象文字列を囲むことで，斜体文字 (イタリック) にできます．

*Italic*テキスト

HTML の <em> 要素に変換され，下記のように表示されます．

Italicテキスト

フォントやCSSの設定によっては，<em> のスタイルがキャンセルされて斜体の見た目にならない場合がありますので，注意してください．
本サイトでも日本語の場合は，斜体文字の見た目になりませんでした．

なお，_でも斜体文字に変換されますが空白を挟まないと上手く動かないので，推奨されていません．

1.4 太字 & 斜体文字

*** で対象文字列を囲むことで，太字の斜体文字にできます．

***Bold italic***テキスト

HTML の <em><strong> 要素に変換され，下記のように表示されます．

Bold italicテキスト

なお，___でも斜体文字に変換されますが空白を挟まないと上手く動かないので，推奨されていません．

1.5 ブロック引用

> を段落先頭につけると，ブロック引用ができます．

> ブロック引用

HTML の <blockquote> 要素に変換され，下記のように表示されます．

ブロック引用

ここではスタイルを適用していないので，単純に字下げだけが行われています．

1.6 番号付きリスト

1., 2., 3. と各行の先頭に番号とピリオドを付けると，番号付きリストが作成できます．
なお，実際の番号は自動採番されるので，全て 1. でも構いません．

1. 1番目のアイテム
2. 2番目のアイテム
3. 3番目のアイテム

HTML の <ol><l1> 要素に変換され，下記のように表示されます．

  1. 1番目のアイテム
  2. 2番目のアイテム
  3. 3番目のアイテム

入れ子のリスト

あるアイテムの下に別のリストを入れ子にしたい場合は，親要素から4スペース分インデントして記入します．

1. 1番目のアイテム
2. 2番目のアイテム
    1. 2-1番目のアイテム
    2. 2-2番目のアイテム
3. 3番目のアイテム

下記のように表示されます．

  1. 1番目のアイテム
  2. 2番目のアイテム
    1. 2-1番目のアイテム
    2. 2-2番目のアイテム
  3. 3番目のアイテム

1行開けて別の番号を並べるとき

1行開けて別の番号を並べるときは，少し注意が必要です．
下記のように単純に並べると，２つのリストが結合されて表示されます．
(しかも3番目と4番目のアイテムに <p> が挿入されてレイアウトが崩れます)

1. 1番目のアイテム
2. 2番目のアイテム
3. 3番目のアイテム

1. 別の1番目のアイテム
2. 別の2番目のアイテム
3. 別の3番目のアイテム
  1. 1番目のアイテム
  2. 2番目のアイテム

  3. 3番目のアイテム

  4. 別の1番目のアイテム

  5. 別の2番目のアイテム
  6. 別の3番目のアイテム

空のダミー要素を間に入れると防ぐことができます．

1. 1番目のアイテム
2. 2番目のアイテム
3. 3番目のアイテム

<span></span>

1. 別の1番目のアイテム
2. 別の2番目のアイテム
3. 別の3番目のアイテム
  1. 1番目のアイテム
  2. 2番目のアイテム
  3. 3番目のアイテム

  1. 別の1番目のアイテム
  2. 別の2番目のアイテム
  3. 別の3番目のアイテム

1.7 箇条書きリスト

-, -, - と各行の先頭にハイフンとスペースを付けると，箇条書きリストが作成できます．

- 1番目のアイテム
- 2番目のアイテム
- 3番目のアイテム

HTML の <ul><l1> 要素に変換され，下記のように表示されます．

  • 1番目のアイテム
  • 2番目のアイテム
  • 3番目のアイテム

細かな注意点は，番号付きリストと同様です．

1.8 コード

"`" (アクセント記号，グレイヴ記号) で文字を囲むと，コードを表記ができます．

プログラムでは，`i=1` は等号ではなく代入です．

HTML の <code> 要素に変換され，下記のように表示されます．

プログラムでは，i=1 は等号ではなく代入です．

Pelicanのコードブロックについて説明した記事で細かく説明していますので，併せてご一読いただければうれしいです．

1.9 水平区切り線

--- によって，水平区切り線が作成できます．

HTML の <hr> 要素に変換され，下記のように表示されます．

1.10 リンク

[表示文字列](URL) という書式でリンクが作成できます．

[高山研究開発事務所](https://takayama-rado.com)

HTML の <a> 要素に変換され，下記のように表示されます．

高山研究開発事務所

内部リンクの作成方法については，記事作成方法の記事 (第2.2項) をご参照ください．

1.11 画像ファイル

![alt属性](URL) という書式でリンクが作成できます．

![alt属性](URL)

HTML の <img> 要素に変換されます．

気軽に外部から引っ張れる画像が無いので，ここでは表示例は割愛させていただきます．

2. 拡張記法

次に，オリジナルのマークダウンから追加された拡張的な記法を説明します．
これらの拡張記法については，アプリケーション毎にサポート状況が異なります．

2.1 表

| をデータ区切りとして，表を作成することができます．

| ヘッダ1 | ヘッダ2 |
| --- | --- |
| データ1-1 | データ1-2 |
| データ2-1 | データ2-2 |

HTML の <table>, <thead>, <tbody>, <tr>, <td> 要素に変換され，下記のように表示されます．
(区切り線を表示するには，CSSでスタイルを指定する必要があります)

ヘッダ1 ヘッダ2
データ1-1 データ1-2
データ2-1 データ2-2

2.2 コードブロック

本記事でも既に出てきていますが，"```" で囲まれた領域はコードブロックになります．

```
a = 1
b = 2
print(a+b)
```

HTML の <code> 要素に変換され，下記のように表示されます．

1
2
3
a = 1
b = 2
print(a+b)

Pelicanのコードブロックについて説明した記事で細かく説明していますので，併せてご一読いただければうれしいです．

2.3 注釈

[^識別子] という書式で，注釈が作成できます．

短い注釈[^1]や，長い注釈が作れます[^2]．

[^1]: 短い注釈は1行で書きます．
[^2]: 長い注釈は下記のように4スペースでインデントして書きます．
    このように書くと，同じブロック内と解釈されます．

短い注釈1や，長い注釈が作れます2．
なお，注釈ブロックは記事末尾に挿入されます．

複数のクラス付き HTML タグを組み合わせた変換が行われますので，HTML 要素の説明は割愛させていただきます．

2.4 ID付きヘッダ (Pelicanでは不可)

アプリケーションによっては下記の書式で，ID付きヘッダを作成できます．

同一行の2個目の＃はコメントと解釈されるようなので，大文字で書いてます．
# H1 with ID {＃header-id}

HTML の <h1 id="header-id"> のような要素に変換されます．
このIDを利用して，<a href="#header-id"> のようにヘッダへの内部リンクを作成することができます．

なお，Pelican では同一行の2個目の＃がコメントと解釈されるようで，上手く動きませんでした．

2.5 定義リスト

次の書式で定義リストを作成することができます．

定義名
: 定義内容

HTML の <dl>, <dt>, <dd> 要素に変換され，下記のように表示されます．

偶数
2で割り切ることのできる自然数

2.6 打ち消し線 (Pelicanでは不可)

アプリケーションによっては，~~ で対象文字列を囲むと文字列の上に打ち消し線が描画されます．

~~Aのようです．~~ すみませんBでした．

Pelican では上手く動かないようで，下記のようにそのまま表示されます．

~~Aのようです．~~ すみませんBでした．

2.7 タスクリスト (Pelicanでは不可)

アプリケーションによっては，下記の書式でタスクリストが作成できます．

- [x] チェック済みタスク
- [ ] 未チェックタスク1
- [ ] 未チェックタスク2

Pelican の場合は，単純に箇条書きリストと文字列に変換されます．

  • [x] チェック済みタスク
  • [ ] 未チェックタスク1
  • [ ] 未チェックタスク2

2.8 絵文字 (Pelicanでは不可)

アプリケーションによっては，下記の書式で絵文字が作成できます．

キャンプ :tent: に行きたいなぁ．

Pelican では上手く動かないようで，下記のようにそのまま表示されます．

キャンプ :tent: に行きたいなぁ．

2.9 ハイライト (Pelicanでは不可)

アプリケーションによっては，下記の書式でハイライト文字が作成できます．

==ハイライト== テキスト

Pelican では上手く動かないようで，下記のようにそのまま表示されます．

==ハイライト== テキスト

2.10 上付き，下付き文字

アプリケーションによっては，下記の書式で上付き文字と下付き文字が作成できます．

H~2~O
X^2^

Pelican では上手く動かないようで，下記のようにそのまま表示されます．

H~2~O X^2^

今回は，Markdown 記法を紹介して Pelican 上で動作するかを確かめてみましたが，如何でしょうか?

拡張記法は動かないのも結構ありましたね．
個人的には，複雑な機能は生の HTML やCSS，および Javascript で書いてしまうことが多いので，別段問題視していませんでしたが，皆様は如何でしょう．

今回の話が，これからWebサイト等を作ろうと考えている方に何か参考になれば幸いです．

  1. 短い注釈は1行で書きます． ↩

  2. 長い注釈は下記のように4スペースでインデントして書きます． このように書くと，同じブロック内と解釈されます． ↩

静的サイトジェネレータPelicanの記事ファイルの書き方
実践手話認識 - モデル開発編 補足: Pydanticを用いてTransformerベース孤立手話単語認識モデルをリファクタリング

関連する記事