NikolaのListing機能

NikolaのListing機能って何？

以前の記事 でも書きましたが、 Nikolaには listing という機能があります。

NikolaのHandbook を見ると以下のように記載されています。

To use this, you have to put your source code files inside listings or whatever folders your LISTINGS_FOLDERS variable is set to fetch files from.

要はプログラムのソースコードなどをそのままこのフォルダに放り込んでおけば、 記事から以下のように参照できるということです。

.. listing:: 2020/06/hello.py python
   :number-lines:

シンタックス・ハイライトしてくれるので、その時の言語モードも指定できます。

以下は実際に取り込んだ例です。

2020/06/hello.py (ソース)

また、これだけでなく listings フォルダ内のプログラムは全て HTML化されます。 上記の例であれば、 hello.py.html というページが作成されます。 ( 生成例 )

Gist要らずの芸達者

詳細を調べると、便利そうなので自分への備忘としてまとめておきます。

listing ディレクティブ は reStructuredTextの includeディレクティブと 同じオプションが使えるらしく、以下のようなことが可能です。

まず、プログラムの6行目から8行目だけを取り込んで、行番号を振ってみます。

.. listing:: 2020/06/hello.py python
   :start-line: 5
   :end-line: 8
   :number-lines: 6

注意点は、Pythonなのでカウントが０から始まるので１行分指定がズレることと、 end-line の指定は指定行は含まないことです。上記の例では、表示上の行番号を 実際の行番号と合わすように number-lines の指定を調整しています。

レンダリング例

2020/06/hello.py (ソース)

また、 特定のキーワード以降だけを取り込むことが可能です。

以下の例では、 "python" という文字以降だけリストしています。

.. listing:: 2020/06/hello.py python
   :start-after: python

以下がレンダリング例です。

2020/06/hello.py (ソース)

import sys


def hello(name='world'):
    greeting = "hello " + name
    print(greeting)


if __name__ == "__main__":
    hello(*sys.argv[1:])

これだけできれば、Gistは不要ですし、ブログの記事に直接コードを張り込まなくても この機能で十分代替となりそうです。