こんにちは．高山です．
本サイトはPelicanという静的サイトジェネレータを使って作っています．
コードブロックを書くときに行番号付きで表示したいケースがよくあるのですが，今までMarkdownを何となくで書いていたためつまづく所が結構ありました．

今回は，Pelican上のMarkdownでコードブロックを書く際に色々と調べたことをまとめたいと思います．

更新履歴 (大きな変更のみ記載しています)

• 2024/09/17: タグを更新しました

1. Markdownのコードブロック

Markdownのコードブロックは下記のようなブロックを指します．

import os
print("This is a code block.")

コードブロック内のテキストはMarkdownで処理されずにそのまま表示されます (リテラルとして扱うと説明される場合もあります)．

2. コードブロックの書き方

コードブロックの書き方は2種類あります．

2.1 Indented Code Block

１つ目はIndented Code Blockという書き方で，下記のように先頭から4個のスペースを開けるとコードブロックとして扱われます．

Markdown上で次のように書くと...

    import os
    print("This is a code block.")

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

import os
print("This is a code block.")

2.2 Fenced Code Block

2つ目の書き方はMarkdown Extraで導入された書き方で，Fenced Code Blockと呼びます．

この書き方では，3つ以上のバッククオート(`)やチルダ(~)で囲まれたテキストをコードブロックとみなします．

例えば，Markdown上で次のように書くと...

```
import os
print("This is a code block.")
```

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

import os
print("This is a code block.")

お恥ずかしい話ですが，私は1つ目の書き方がオリジナルだと知らず，2つ目の書き方しか知りませんでした(^^;)
PelicanやMarkdownパーサの仕様書はIndented Code Blockで説明されていたため，理解するのに手間取ってしまいました．

3. 行番号付きコードブロックの書き方

Pelicanでは，MarkdownからHTMLへの変換にPython-Markdownというモジュールを使用しています．
Python-Markdownでは拡張機能として，行番号付きコードブロックやコードブロック内のテキストをそれぞれの言語に準じた形式で色付する機能が搭載されています．
色付け機能にはPygmentsというモジュールを使用しています．

3.1 Indented Code Block

Indented Code Blockを用いる場合は，下記のようにして行番号の有無を制御することができます．

行番号無し

例えば，次のようにコードブロックの先頭行にコロン(:)を3個並べて言語名を記述すると...

    :::python
    import os
    print("This is a code block.")

行番号無しでPythonに準じた色付けができます．

import os
print("This is a code block.")

行番号有り

次のように先頭にShebang(#!)を記述して言語名を記述すると...

#!python
import os
print("This is a code block.")

行番号有りでPythonに準じた色付けができます．

1
2

import os
print("This is a code block.")

3.2 Fenced Code Block

Fenced Code Blockを用いる場合は，先頭のチルダの直後に制御属性値を記入することで行番号の有無を制御することができます．

行番号無し

行番号を無しにしたい場合は次のように書けます．

~~~ { .python linenums=false }
import os
print("This is a code block.")
~~~

上のスクリプトは下のように表示されます．

import os
print("This is a code block.")

行番号有り

同様に，行番号を入れたい場合は次のように書けます．

~~~ { .python linenums=true }
import os
print("This is a code block.")
~~~

上のスクリプトは下のように表示されます．

1
2

import os
print("This is a code block.")

4. Pelicanでサイト全体で固定の設定をしたい場合

ここまで説明してきた方法は，各コードブロックに制御属性を記入しなければいけません．
Pelicanではサイトを生成する際の設定によって行番号の有無を制御することができます．

サイト生成用の設定ファイル (通常はpelicanconf.py) に次のように記述すると，全てのコードブロックに行番号が入るようになります．

1
2
3
4
5
6
7
8

MARKDOWN = {
  'extension_configs': {
    'markdown.extensions.codehilite': {'css_class': 'highlight', 'linenums': True},
    'markdown.extensions.extra': {},
    'markdown.extensions.meta': {},
  },
  'output_format': 'html5',
}

ただし，この設定を行った場合はIndent Code Block上で行番号の有無を直接制御することはできなくなるのでご注意ください．

今回は，Pelican上のMarkdownで行番号付きコードブロックを書く方法を紹介させていただきましたが，如何でしょうか?
MarkdownやWebサイト構築に関しては私も勉強している最中です．
勉強中に学んだことや気づいたことは本サイトで順次紹介していこうと思っています．

今回の記事が，同様のことでつまづいている方に何か参考になれば幸いです．