Breadcrumbの実装

Miyadaikuの コンフィグ を利用して、Breadcrumb付きのサイトを作成します。Breadcrumbは、Bootstrap4Breadclumbs で表示します。

このチュートリアルで作成するソースコードは、

https://github.com/miyadaiku/miyadaiku-docs/tree/master/samples/breadcrumb

からダウンロードできます。

作成したサイトは、

https://miyadaiku.github.io/samples/breadcrumb/index.html

で参照できます。

プロジェクトの作成

はじめに、次のコマンドで breadcrumb ディレクトリに miyadaiku のプロジェクトを作成します

$ miyadaiku-start ./breadcrumb

Bootstrap4テーマのインストール

Miyadaikuでは、かんたんにBootstrap4を使えるように、miyadaiku.themes.bootstrap4 テーマを用意しています。miyadaiku.themes.bootstrap4 は、次のコマンドでインストールできます。

$ pip3 install miyadaiku.themes.bootstrap4

プロジェクト設定

プロジェクト設定ファイル breadcrumb/config.ymlthemes を修正し、miyadaiku.themes.bootstrap4 を使用するように設定します。

first_blog/config.yml:
# Title of the site
site_title: FIXME - site title

# Default language code
lang: ja

(... 中略 ...)

# List of site theme
themes:                            # <--- この行を修正
  - miyadaiku.themes.bootstrap4    # <--- この行を修正

記事の作成

表示する記事として、breadcrumb/contents ディレクトリと breadcrumb/contents/child1 ディレクトリに、次の4ファイルを作成します。

breadcrumb/contents/index.rst:
.. article::
   :title: index.rst in the root directory

This is /index.rst.
breadcrumb/contents/page1.rst:
.. article::
   :title: page1.rst in the root directory

This is /page1.rst.
breadcrumb/contents/child1/index.rst:
.. article::
   :title: index.rst in the child1 directory

Welcome to the child1.
breadcrumb/contents/child1/child1-2.rst:
.. article::
   :title: child1-2.rst in the child1 directory

This is child1-2.rst file in the /child1 directory.

コンフィグの作成

コンフィグ は、ディレクトリごとの設定を指定するYAMLファイルです。

breadcrumb/contents ディレクトリと breadcrumb/contents/child1 ディレクトリにコンフィグを作成し、Breadcrumb に表示するタイトルを foldername 属性に指定します。

breadcrumb/contents/root.yml:
foldername: Root folder
breadcrumb/contents/child1/child1.yml:
foldername: Child1 folder

テンプレートの作成

Jinja2テンプレート breadcrumb/templates/page_article.html を作成します。

breadcrumb/templates/page_article.html:
<!DOCTYPE html>
<html>
<head>
  <!-- include boolstrap4 -->
  {{ bootstrap4.load_css(page) }}

  <title>{{ page.title }} - {{ page.site_title }}</title>
</head>

<body>


<nav aria-label="breadcrumb">
  <ol class="breadcrumb">

    {% for parent in page.parents_dirs %}
      <li class="breadcrumb-item">
        {{ page.link_to((parent, 'index.rst'),
                         text=config.get(parent, 'foldername')) }}
      </a></li>
    {% endfor %}

    <li class="breadcrumb-item active">
      {{ page.title }}
    </li>
  </ol>
</nav>


 <div class="container-fluid">
 <div class="row">
    <div class="col-sm">
      {{ page.html }}
    </div>
    <div class="col-sm">
      <ul>
        {% for article in contents.get_contents(subdirs=[page.dirname]) %}
          <li>{{ article.link(text="%s (/%s)" % (
                 article.title,
                 "/".join(article.dirname+(article.name,)))) }}
        {%endfor %}
      </ul>
    </div>
  </div>
</div>

</body>
</html>

次のように bootstrap4.load_css() を呼び出し、Bootstrap4のCSSをロードする <link> 要素を出力します。

<head>
  <!-- include boolstrap4 -->
  {{ bootstrap4.load_css(page) }}

ページオブジェクトの parents_dirs 属性で親ディレクトリの一覧を取得し、各ディレクトリの index.rst へのリンクをBreadcrumbとして出力します。

{% for parent in page.parents_dirs %}
  <li class="breadcrumb-item">
    {{ page.link_to((parent, 'index.rst'),
                     text=config.get(parent, 'foldername')) }}
  </a></li>
{% endfor %}

一番最後のBreadcrumbは、現在のページのタイトルを出力します。

<li class="breadcrumb-item active">
  {{ page.title }}
</li>

サイトのビルド

次のコマンドでサイトをビルドします。

$ miyadaiku-build ./breadcrumb

正常に終了すると、breadcrumb/outputs/index.html が出力されます。