Tinkererはテンプレートエンジンに Jinja2を使っている。

あとで使いやすいように使い方を調べてまとめた。

目次

Jinja2テンプレートの使い方

Jinja2 埋込み

記法 利用例 意味
{{ {{ apple }} 変数展開
{% {% for i in list %} 構文
{# {# comment #} コメント
<!DOCTYPE HTML PUBLIC "-//W3C/DTD HTML 4.01//EN">
<html lang="en">
  <body>
  {% for item in navigation %}
    <p>{{ item.description }}</p>
  {% endfor %}
  </body>
</html>

Jinja2 ブロックと継承

ブロックと呼ばれる機能がある。以下の様に囲まれた領域に名前を付けられる。 複数回呼ぶ場合や継承を通して上書きする事が可能になっている。

<h1>ブロックの例</h1>
{% block social %}
<div>なんか色々あるよ</div>
{% endblock %}
{% block footer %}
<footer>ショボいフッター</footer>
{% endblock %}

継承する場合, sphinxの探索パスからの相対パスで指定を行いブロックを再定義する。

{% extends "layout.html" %}
{% block title %}シンプルな内容に上書きする{% endblock %}
{% block footer %}
文言を手前に出力する。
{# blockを複数回出力したい場合はself.ブロック名 #}
{{ self.title() }}
{% block inner_block %}
  <p>ネストは許可される。さらにendblockの後ろにブロック名を明記する事も可能</p>
{% endblock inner_block %}
{# 親テンプレートの内容を利用する場合はsuper() #}
{{ super() }}
{% endblock footer %}

extends の探索パスはTinkererだと conf.pytemplate_path, html_theme_path配下が使われるっぽい。

他にもJinja2には空行・空白のコントロール・ ネストしたブロックのスコープ操作や略記がある。

Tinkererでのテンプレート継承関係

大事なテンプレート

layout.html

ブログ全体で利用する全体像

page.html

コンテンツ部分等を変更(layout.htmlを継承)

aggregated.html

トップページ用(page.htmlを継承)

archive.html

アーカイブページ用(page.htmlを継承)

他に何が自動で読み込まれるのかは調べていない。

テンプレートファイルの探索先

プロジェクトdirを {$PROJ} と記述する。 読まれるテンプレート関連のファイルは、以下の様になる。

$PROJ
  | - conf.py            # 全体設定 テーマ名(html_theme)
  | - _themes            # テーマ定義
       ` - ${THEME_NAME}  # 個別作成テーマ
  ` - (templates)        # テンプレート準備個所

探索順序は以下になっていた。

  1. $PROJ/_template
  2. $PROJ/conf.pyhtml_themeで設定したテーマディレクトリ($THEME)
  3. $THEME/theme.confinheritで設定した継承元テーマディレクトリ($SUPER_THEME)

テーマディレクトリの探索先

$THEME, $SUPER_THEMEなどテーマディレクトリはどこを探索されるかまとめる。

ちなみに自分だとtinkerer のインストール先ディレクトリ($PACK)は、 $HOME/.virtualenvs/for-blog/lib/python2.7/site-packages/tinkererだった。

デフォルトではテーマディレクトリは以下が探索される。

  1. $PROJ/_themes
  2. $PACK/themes

サイドバーテンプレートの追加方法

  1. サイドバーテンプレートの探索先にXXX.htmlというテンプレートを作成する
  2. 上記テンプレートの中に<div>要素内を記述する
  3. $PROJ/conf.pyhtml_sidebars 項目にテンプレート名を追加