1. インストール

1.1. 事前準備

Java 6+ JRE がインストールされてて java コマンドが使用できる状態なら準備はおっけい。

1.2. バイナリを取ってくる場合

  1. ここからZIPをダウンロードして解凍。適当なディレクトリに配置します。以下、そのディレクトリ位置を JBAKE_HOME って記述します。

  2. JBAKE_HOME/bin をPath環境変数に足してね。

  3. コマンドプロンプトを開いて jbake -h (Windowsだったら jbake.bat -h) を実行。使用方法のヘルプテキストが出てきます。

JBake v2.5.1 (2017-12-26 17:56) [http://jbake.org]

Usage: jbake ...

1.3. SDKMANを使う場合

Bashベースのプラットフォーム(Mac OSX、Unix、Linux、Cygwin、Solarisなど)の場合、http://sdkman.io/[SDKMAN] を使ってインストールすることもできます。最新の SDKMAN を準備しといてください。

準備ができたら以下のコマンドを入力すれば JBake の最新バージョンがインストールできます。

$ sdk install jbake

1.4. Homebrewを使う場合

あなたが OS X を使用しているオシャレ野郎な場合、http://brew.sh/[Homebrew] を使ってインストールすることもできます。 Homebrew を準備した後に以下のコマンドを入力すれば JBake の最新バージョンがインストールできます。

$ brew install jbake

2. クイックスタートガイド

2.1. セットアップ

最初にインストールに書いてある方法で JBake を準備します。 次に、コマンドプロンプトを開いて次のコマンドを打って、動作確認をします。

jbake -h

上手くインストールできていれば、以下のような文字が表示されます。

JBake v2.5.1 (2017-12-26 17:56) [http://jbake.org]

Usage: jbake ...

2.2. プロジェクトの作成

手っ取り早く始めたい場合、サンプルテンプレートを使ったサンプルプロジェクトを使用することが出来ます。 まず新しいディレクトリを作成して、その中に入ります。

$ mkdir project
$ cd project

次に以下のコマンドを打つと、プロジェクトの基本構造とサンプルテンプレートがディレクトリ内に生成されます。

$ jbake -i
デフォルトでは Freemarker を使ったテンプレートが展開されます。その他のテンプレートエンジンを指定したい場合については、使い方 セクションを見てね。

2.3. 焼く!(Bake)

コンテンツを追加したり、テンプレートをカスタマイズしたら次のコマンドでこんがり焼くことができます。

$ cd project
$ jbake -b
焼く (Bakeする) ことによって、プロジェクト直下の output ディレクトリに処理された結果が配置されます(デフォルト設定の場合)。

2.4. プレビュー

サーバーモードで JBake を実行すれば、こんがり焼いたプロジェクトがどのように見えるかすぐに確認できます。

$ cd project
$ jbake -s

JBake v2.5.1 (2017-12-26 17:56) [http://jbake.org]

Serving out contents of: [output] on http://localhost:8820/
(To stop server hit CTRL-C)

ブラウザで http://localhost:8820 にアクセスすると、結果が確認できます。

こんな感じで、ステキな焦げ色のサイトがものの数分で焼きあがるっていう寸法ですよ!

3. 使い方

引数なしで jbake を実行すると -h を付けたときと同じく使用方法のテキストが表示されます。

$ jbake

3.1. Bake コマンド

bake コマンドはコンテンツとテンプレートを上手い具合に調理して、しっかり火の通ったWebサイトに仕上げます。 その方法は用途によっていくつか選ぶことが出来ます。

-b オプションの後ろに何も指定しない場合、現在の作業ディレクトリが bake 対象のコンテンツの位置と認識し、直下の output ディレクトリに調理結果を配置します。

$ jbake -b
output ディレクトリがまだ無い場合、JBake はこのディレクトリを生成します。

<source>ディレクトリのみをパラメータに指定した場合、調理結果は<source>ディレクトリの直下に生成されます。

$ jbake -b <source>

加えて<output>ディレクトリも指定すれば、すべてお好みの方法で料理することができます。

$ jbake -b <source> <output>

<source>ディレクトリと<output>ディレクトリの両方を指定する場合には、 -b オプションは省略可能です。

$ jbake <source> <output>

3.2. 初期化コマンド

初期化コマンドは、指定したディレクトリにプロジェクトに必要になるディレクトリ構造と多くのサンプルコンテンツ、テンプレートを配置します。 その際には、テンプレートの記述言語としてどのテンプレートエンジンを使用するかを選ぶことができます。

-i オプションの後ろに何も指定しない場合、現在の作業ディレクトリ内に、 Freemarker をテンプレートエンジンとして利用するプロジェクトを生成します、。

$ jbake -i

初期化するディレクトリを指定したい場合には、パラメータとして追加します。

$ jbake -i <directory>

テンプレートエンジンを変更したい場合には -t オプションを使って指定します。

$ jbake -i -t <freemarker|groovy|groovy-mte|thymeleaf|jade>
利用可能なテンプレートエンジンは FreemarkerGroovy Simple and MarkupThymeleafJade です。

3.2.1. サンプルプロジェクトの構造

サンプルプロジェクトの構造とテンプレートは JBake をインストールしたディレクトリ ( JBAKE_HOME ) にファイルとして保存されています。

  • example_project_freemarker.zip

  • example_project_groovy.zip

  • example_project_groovy-mte.zip

  • example_project_thymeleaf.zip

  • example_project_jade.zip

初期化に使用されるプロジェクト構造やテンプレートを変更したい場合、上記のZIPファイルを置き換えてください。 以降、JBake は置き換えられたファイルを基にして初期化処理を行います。

3.3. サーバーコマンド

サーバーコマンドを利用すると、HTTP WEBサーバーが立ち上がり、生成されたサイトの見た目を確認することができます。 リリース前にサイトの内容をプレビューするのに便利です。

-s オプションを使用すると、JBake はサーバーモードで起動し、http://localhost:8820/ にアクセスすることによって生成されるサイトをプレビューすることができるようになります。 デフォルトでは output ディレクトリの内容が表示されます。

$ jbake -s
ローカルポートの番号は設定ファイルによって変更することができます。

追加のパラメータを指定することによって、表示するディレクトリを変更することができます。

$ jbake -s <directory>

3.3.1. 監視モード

サーバーモードで実行されている間、JBake は Content ディレクトリ内の変更 (新しいファイルの追加や、既存ファイルの変更) を監視し、検知した場合には自動的に変換を実施します。そのため、ブラウザの表示内容更新を行うことで出力結果をすぐに確認することができます。

このモードはインクリメンタルレンダリングと組み合わせて使用することをオススメします。 やり方の詳細については コンテンツストアの永続化 の設定オプションを参照してください。

3.4. コマンドの結合

オプションコマンドは以下のように複数指定することもできます。

$ jbake -b -s

上記コマンドでは、JBake はサイトを生成した後にサーバーモードでも起動します。

4. プロジェクトの構造

以下はサンプルのプロジェクトのディレクトリ構造になります。

.
|-- assets
|   |-- favicon.gif
|   |-- robots.txt
|   |-- img
|   |   |-- logo.png
|   |-- js
|   |   |-- custom.js
|   |-- css
|       |-- style.css
|
|-- content
|   |-- about.html
|   |-- 2013
|       |-- 01
|       |   |-- hello-world.html
|       |-- 02
|           |-- weekly-links-1.ad
|           |-- weekly-links-2.md
|
|-- templates
|   |-- index.ftl
|   |-- page.ftl
|   |-- post.ftl
|   |-- feed.ftl
|
|-- jbake.properties

4.1. Assets ディレクトリ

Assets ディレクトリは、画像、CSSファイル、JavaScriptファイル等の静的ファイルを配置する場所です。 これらのファイルはなんの変換もされず、出力ディレクトリにコピーされます。 Assets ディレクトリ内の内容はそのままコピーされるため、好きなようにディレクトリ構造を作成しちゃってください。

4.2. Content ディレクトリ

Content ディレクトリは変換対象となるコンテンツを配置する場所です。このディレクトリ内のファイルは Bake (テンプレートによって処理) されて出力されます。 ディレクトリ内には自由にディレクトリ構造を作成することもできます。そのディレクトリ構造は Bake された処理結果にもそのまま適用されます。

JBake はコンテンツディレクトリ内のファイルをファイル拡張子によって判断して処理します。

  • .html = 素の HTML コンテンツ

  • .md = Markdown 記法によるコンテンツ

  • .ad = AsciiDoc 記法によるコンテンツ

  • .adoc = これも AsciiDoc 記法によるコンテンツ

  • .asciidoc = 同じく AsciiDoc 記法によるコンテンツ

JBake は Pegdown を利用してMarkdown記法を処理しています。また、AsciiDoc記法の処理には Asciidoctor を利用しています。

4.3. Templates ディレクトリ

Templates ディレクトリはテンプレートファイルの配置場所です。これらのファイルはContent ディレクトリ内のファイルと「結合」された状態で出力されます。 このディレクトリ内のファイルはTemplates ディレクトリ直下に配置されている必要があります。

ディレクトリ内のファイルは、ファイル拡張子によって処理に使われるテンプレートエンジンが決まります。

同じプロジェクト内で違うテンプレートエンジンを混在させることはやめておいたほうが良いです。 各テンプレートエンジンの詳細については、JBake が提供しているサンプルテンプレートと、それぞれのプロダクトのドキュメント ( FreemarkerGroovyThymeleafJade ) を参照してみてください。

4.4. プロジェクト設定

プロジェクト固有の設定は、プロジェクトのルートディレクトリにある jbake.properties ファイルに記述します。 このファイルの記述内容によって JBake はプロジェクトの焼き加減を調整したりします。

5. Content ファイル

5.1. メタデータヘッダ

メタデータヘッダには Content ファイルを処理するための基本的な設定内容を記述します。

素のHTMLや、各マークダウン記法によって記述されたファイルの先頭には以下のようなメタデータヘッダが 必須 です。

title=Weekly Links #2
date=2013-02-01
type=post
tags=weekly links, java
status=published
~~~~~~

statustype のヘッダ項目は 必須 で、その他の項目はオプションです。 設定ファイル 内にデフォルトの status が記述されている場合には、status の項目は省略することができます。

date の項目を記述しない場合、該当ファイルの更新日が使われます。

AsciiDocで記述されたファイルの場合、メタデータヘッダはオプションになります。 メタデータは AsciiDoc の記法を使って以下のように定義します。

= Project Structure
Jonathan Bullock
2013-10-17
:jbake-type: page
:jbake-tags: documentation, manual
:jbake-status: published
JBake のための属性を AsciiDoc ヘッダに記述する場合、名称の衝突を避けるため jbake- プレフィックスを付けます。

5.1.1. Status

この項目には以下の3つの状態のうちのひとつを記述します。

  • draft - draft (下書き) を記述した場合、公開コンテンツと同じく変換処理はされるけれど、first-post-draft.html のようにファイル名の末尾に -draft が付きます。 また、公開コンテンツには含まれません(一覧などではリンクされません)。

  • published - 変換処理されて、公開もされます。

  • published-date - メタデータヘッダの date が現在日時と同じかそれより古い場合に公開対象になります。

5.1.2. Type

この項目によってページを生成する際のテンプレートを決定します。 デフォルトテンプレートでは以下の2種類を選択することができます。

  • type=post post.ftl によって変換を実施

  • type=page page.ftl によって変換を実施

テンプレートを追加すれば、これ以外の type をプロジェクトに追加することもできます。 詳しいやり方は 独自テンプレート を参照してください。

5.1.3. 独自メタデータ

メタデータヘッダには以下のように独自の項目を記述することもできます。

summary=投稿内容が長いので概要とか書くよ!

この項目の記述内容は、テンプレートファイルに以下のように記述することによって利用することができます。

<p>${content.summary}</p>

この機能は Disqus のコメントのような外部の機能をテンプレートに埋め込んだり、 jQuery などのJavaScriptのライブラリを使って画像を表示し足りする場合に便利に利用することができます。

5.1.4. 階層構造をもつ独自メタデータ

メタデータに階層構造を持たせたい場合、以下のようにJSON形式を使用することができます。

type=page
og={"description": "Something"}
JSONデータは改行なしの1行で記述する必要があります。

このJSONデータをテンプレート内で参照する場合には、以下のように記述します。

<#if content?? && content.og??> (1)
	<meta property="og:description" content="${content.og.description}"/> (2)
</#if>
1 contentcontent.og が null ではないことをチェック
2 content.og 内の description の内容を出力

5.2. コンテンツ本体

メタデータヘッダ記述より後のすべての内容は、コンテンツ本体としてテンプレートに処理されます。 Markdown記法、AsciiDoc記法によって記述されている場合にはHTMLに変換されます。

6. テンプレート

6.1. デフォルトテンプレート

JBake のデフォルトテンプレートには、コンテンツファイルを必要としない、特別なページを出力するためのテンプレートファイルがいくつか準備されています。

  • index - index.html ファイルを出力します

  • archive - archive.html (記事の一覧) ファイルを出力します

  • feed - feed.xml (フィード情報) ファイルを出力します

  • tag - タグごとの記事一覧ページを出力します

  • sitemap - sitemap.xml ファイルを出力します

これらのファイルを出力する必要がない場合、jbake.properties ファイルに以下のように記述することで、処理を制御することができます。

...
render.index=false
render.archive=false
render.feed=false
render.tags=false
render.sitemap=false
...

加えて、デフォルトテンプレートには、コンテンツを処理するための2つのテンプレートが定義されています。

  • page - type に 'page' が指定されているコンテンツ (投稿以外のナニカ) を出力します

  • post - type に 'post' が指定されているコンテンツ (BLOGの投稿っぽやつ) を出力します

6.2. 独自テンプレート

いろいろな見た目のコンテンツを出力するために、独自のテンプレートを定義することもできます。

まず、以下のような記述を jbake.properties に加えます。

...
template.<customtype>.file=templateXYZ.ftl
...
<customtype> の定義に使う文字列は、 [A-Za-z0-9-_] の範囲である必要があります。

次に、テンプレートファイルを作成し、プロジェクトの 'templates' ディレクトリに配置します。 追加したテンプレートを利用する場合には、コンテンツファイルのメタデータヘッダに以下のように記述します。

...
type=<customtype>
...

HTML以外のファイルを出力するテンプレートを定義する場合には、 jbake.properties ファイルに以下のような記述を追加します。

...
template.<customtype>.extension=.xml
...

7. データモデル

データモデルは(使用するテンプレートエンジンに関係なく)展開され、各テンプレート処理時に参照することができます。 テンプレートではそのデータモデルを用いて、出力時のロジックを実行することができます。

7.1. Global

これらのデータ値は、すべてのテンプレートで参照することができます。

  • version = 現在使用している JBake のバージョン

  • published_date = Bake (変換) 実施日

  • [type]s = [type] 別のコンテンツ一覧 (例: posts の場合 type=post で定義されたすべてのコンテンツ)

  • published_content = type に関係なく status=published が定義された全てのコンテンツ

  • published_posts = 日付降順に並んだ type=post で status=published なコンテンツの一覧

  • published_pages = 日付降順に並んだ type=page で status=published なコンテンツの一覧

  • all_content = 全てのコンテンツ (type も status も関係なく)

  • alltags = status=published なコンテンツ内で使用されているタグの一覧

  • content.rootpath = プロジェクトのルートへの相対パス

  • config.[option] = jbake.properties ファイルに記述された内容のマップ

jbake.properties ファイル内の記述を参照する場合には、データ項目名の ._ に変換してください。 たとえば、 template.index.file=index.ftl を参照する場合には、 config.template_index_file と指定します。

テンプレート内では、一覧 ( Collection ) データをループで回して、各コンテンツ内の要素にアクセスすることができます。 ループのスコープ内では、content.title や、 content.body など、content.[value] という記述でコンテンツの各要素を参照します。

7.2. Page / Post / Custom

Page、Post または独自に定義したテンプレート内では、次のデータが定義されています。

  • content.[value] = 処理するファイルに記述された内容のマップ

content.title などのメタデータヘッダや、ファイルのBody要素である content.body など、全てのデータに対してアクセスが可能です。

またマップには以下の情報も含まれて居ます。

  • content.file = ソースファイルへのフルパス

  • content.uri = 変換後ファイルのURI

7.3. Index

このテンプレートでは、ページングを実現するために必要となる変数を参照することができます。

  • nextFileName = 次ページが存在する場合、そのページのファイル名

  • previousFileName = 前ページが存在する場合、そのページのファイル名

  • numberOfPages = 総ページ数 (バージョン2.5.1以降)

  • currentPageNumber = 現在のページ番号 (バージョン2.5.1以降)

これらの変数を利用すると、テンプレート内でページを前後するためのUIが提供できるようになります。

これらの変数は存在しない場合もありうるので、参照する際には存在チェックが必要です。

7.4. Tags

このテンプレートでは以下の追加データが定義されています。

  • tag = 処理対象となっているタグ

  • tag_posts = 該当タグが定義された type=post で status=published なコンテンツの一覧 (日付降順)

  • tagged_documents = type に関係なく status=published で該当タグが定義されたコンテンツの一覧 (日付降順)

8. 設定ファイル

jbake.properties ファイル (または旧バージョンの custom.properties) によって JBake の設定をカスタマイズすることができます。 たとえば、コンテンツやテンプレートを配置するディレクトリを変更したり、RSSフィードを生成するかどうかを決めたりすることができます。

JBake は全ての項目に関するデフォルト値を (default.properties) にて定義していますが、それらは jbake.properties によって上書きされます。 また、ハッシュ文字 ( # ) を行頭に記述することで行コメントを記述することができます。 以下のセクションではこのファイル内に設定可能なすべての項目について詳しく説明しています。

8.1. ビルトインオプション

8.1.1. Assets ディレクトリ

この項目は、変換対象外のプロジェクトファイルを配置するディレクトリ位置を定義します。

# folder that contains all asset files
asset.folder=assets

8.1.2. Content ディレクトリ

この項目は、テンプレートによって変換を行う対象となるコンテンツを配置するディレクトリ位置を定義します。

# folder that contains all content files
content.folder=content

8.1.3. 出力ディレクトリ

この項目は、コンテンツの Bake (変換) 結果を出力するディレクトリ位置を定義します。

# path to destination folder by default
destination.folder=output

8.1.4. テンプレートディレクトリ

この項目は、プロジェクトのテンプレートファイルを格納するディレクトリ位置を定義します。

# folder that contains all template files
template.folder=templates

8.1.5. Index テンプレートファイル

この項目は、indexページを生成するためのテンプレートファイルを定義します。

# filename of masterindex template file
template.masterindex.file=index.ftl
古いバージョンでは、この項目の名称は template.index.file でした。変わりました。

8.1.6. アーカイブテンプレートファイル

この項目は、archiveページを生成するためのテンプレートファイルを定義します。

# filename of archive template file
template.archive.file=archive.ftl

8.1.7. フィードテンプレートファイル

この項目は、feedファイルを生成するためのテンプレートファイルを定義します。

# filename of feed template file
template.feed.file=feed.ftl

8.1.8. サイトマップテンプレートファイル

この項目は、sitemapファイルを生成するためのテンプレートファイルを定義します。

# filename of sitemap template file
template.sitemap.file=sitemap.ftl

8.1.9. タグ一覧テンプレートファイル

この項目は、各タグの一覧ページを生成するためのテンプレートファイルを定義します。

# filename of tag template file
template.tag.file=tags.ftl

8.1.10. ページテンプレートファイル

この項目は、 type=page のコンテンツを処理するためのテンプレートファイルを定義します。

# filename of page template file
template.page.file=page.ftl

8.1.11. ポストテンプレートファイル

この項目は、 type=posst のコンテンツを処理するためのテンプレートファイルを定義します。

# filename of post template file
template.post.file=post.ftl

8.1.12. テンプレートの文字コード

この項目は、 テンプレートファイルを解析する際の文字コードを定義します。

# character encoding MIME name used in templates.
# use one of http://www.iana.org/assignments/character-sets/character-sets.xhtml
template.encoding=UTF-8

8.1.13. Indexページ処理フラグ

この項目は、 Indexページ生成の ON / OFF を制御します。

# render index file?
render.index=true
この項目はコンテンツファイルを独自のIndexファイルとして利用する場合に有用です。

8.1.14. アーカイブページ処理フラグ

この項目は、 アーカイブページ生成の ON / OFF を制御します。

# render archive file?
render.archive=true

8.1.15. フィードファイル処理フラグ

この項目は、 フィードファイル生成の ON / OFF を制御します。

# render feed file?
render.feed=true

8.1.16. サイトマップファイル処理フラグ

この項目は、 サイトマップファイル生成の ON / OFF を制御します。

# render sitemap.xml file?
render.sitemap=false

8.1.17. タグ一覧ページ処理フラグ

この項目は、タグ一覧ページ生成の ON / OFF を制御します。

# render tag files?
render.tags=true

8.1.18. Indexページ出力ファイル名

この項目は、Indexページを生成する際のファイル名を定義します。

# filename to use for index file
index.file=index.html

8.1.19. アーカイブページ出力ファイル名

この項目は、アーカイブページを生成する際のファイル名を定義します。

# filename to use for archive file
archive.file=archive.html

8.1.20. フィードファイル出力名

この項目は、フィードファイルを生成する際のファイル名を定義します。

# filename to use for feed
feed.file=feed.xml

8.1.21. サイトマップファイル出力名

この項目は、サイトマップファイルを生成する際のファイル名を定義します。

# filename to use for sitemap file
sitemap.file=sitemap.xml

8.1.22. タグ一覧ページ出力先ディレクトリ

この項目は、タグ一覧ページを出力するディレクトリを定義します。

# folder name to use for tag files
tag.path=tags

8.1.23. タグ文字列のサニタイズ処理フラグ

この項目は、タグの文字列をファイル名として使用する際にサニタイズを行うかどうかを制御します (例:スペースをハイフンに変換する等)。

# sanitize tag value before it is used as filename (i.e. replace spaces with hyphens)
tag.sanitize=false

この項目を true にした場合、タグ文字列 west wingwest-wing に置換され、生成されるファイル名は west-wing.html になります。

8.1.24. ファイル出力時の文字コード

この項目は、ファイルを出力する際に使用される文字コードを定義します。

# character encoding MIME name used for rendering.
# use one of http://www.iana.org/assignments/character-sets/character-sets.xhtml
render.encoding=UTF-8

8.1.25. コンテンツ出力時のファイル拡張子

この項目は、コンテンツファイルの変換出力を行う際のファイル拡張子を定義します。

# file extension for output content files
output.extension=.html

8.1.26. 下書きコンテンツファイルのサフィックス

この項目は、下書き (status=draft) コンテンツを出力する際にファイル名につけるサフィックス文字列を定義します。

# draft content suffix
draft.suffix=-draft

8.1.27. サーバーモードのポート番号

この項目は、サーバーモードで起動する際に使用するポート番号を定義します。

# default server port
server.port=8820

8.1.28. Freemarker プロジェクトファイル

この項目は、Freemarker を用いたサンプルプロジェクトのZIPファイルを定義します。

# zip file containing example project structure using freemarker templates
example.project.freemarker=example_project_freemarker.zip

8.1.29. Groovy SimpleTemplateEngine プロジェクトファイル

この項目は、Groovy SimpleTemplateEngine を用いたサンプルプロジェクトのZIPファイルを定義します。

# zip file containing example project structure using groovy templates
example.project.groovy=example_project_groovy.zip

8.1.30. Groovy MarkupTempateEngine プロジェクトファイル

この項目は、Groovy MarkupTempateEngine を用いたサンプルプロジェクトのZIPファイルを定義します。

# zip file containing example project structure using groovy markup templates
example.project.groovy-mte=example_project_groovy-mte.zip

8.1.31. Thymeleaf プロジェクトファイル

この項目は、Thymeleaf を用いたサンプルプロジェクトのZIPファイルを定義します。

# zip file containing example project structure using thymeleaf templates
example.project.thymeleaf=example_project_thymeleaf.zip

8.1.32. Asciidoctor 設定値

Asciidoc記法で記述されたコンテンツを変換する際に Asciidoctor に設定するパラメータを定義します。

# default asciidoctor options
asciidoctor.attributes=source-highlighter=prettify

この設定の値を複数設定する場合には、KEY=VALUE のセットをカンマ区切りで記述します。 デフォルト設定では、シンタックスハイライトを Prettify を用いて行うように設定されています。

8.1.33. Asciidoctor オプション

Asciidoctor実行時に渡すオプションを定義します。

gem path

この項目は、外部ディレクトリから gem をロードするように gem path を設定します。

asciidoctor.option.gemPath=/var/lib/gems/2.1.0
実行環境に現在設定されている gem path を確認する場合には、 gem environment gempath を実行してください。
requires

Asciidoctor実行時に参照するライブラリを追加する場合には、以下のような記述を追加してください。

asciidoctor.option.requires=asciidoctor-diagram
複数のライブラリを追加する場合には、カンマ区切りで記述します。

8.1.34. JBake の設定を Asciidoctor にエクスポート

この項目は、JBake の設定を Asciidoctor に属性としてエクスポートし、コンテンツ変換時に参照できるようにするかどうかを制御します。

# should JBake config options be exported to Asciidoctor engine?
asciidoctor.attributes.export=false
デフォルトではこの項目はfalseに設定されています。

エクスポートをする際のプレフィックスを定義することもできます。これはAsciiDocが既存で持つ属性との名称の衝突を避けるために有用です。

# prefix that should be used when JBake config options are exported
asciidoctor.attributes.export.prefix=
デフォルトではこの項目は無効に設定されています。

8.1.35. コンテンツファイルのステータスデフォルト値

この項目は、コンテンツファイルのステータスが記述されていなかった場合のデフォルト値を定義します。 この項目を有効にした場合、各コンテンツファイル内のステータス項目は必須ではなくなります。

# default status
#default.status=published
デフォルトではこの項目は無効に設定されています。

8.1.36. 日付フォーマットのデフォルト値

この項目は、コンテンツファイルのメタデータヘッダに記述された date 項目を JBake がパースする際に用いられます。

使用できるパターン文字列に関しては Java API docs の記述を参照して下さい。

# default date format used in content files
date.format=yyyy-MM-dd

8.1.37. Markdown エクステンション

この項目は、Markdown記法で記述されたコンテンツを変換する際に有効となる Markdown エクステンションを設定します。 複数の値を設定する場合にはカンマで区切って記述します。 設定可能なエクステンションの詳細については Pegdown docs を参照してください。

# comma delimited default markdown extensions
markdown.extensions=HARDWRAPS,AUTOLINKS,FENCED_CODE_BLOCKS,DEFINITIONS

ALL を設定することで全ての利用可能なエクステンションを有効にすることが出来ます。また名称の前にハイフンをつけることにより、特定のエクステンションを無効にすることもできます。

# comma delimited default markdown extensions
markdown.extensions=ALL,-HARDWRAPS

8.1.38. Markdown 処理タイムアウト値

この項目には、Markdown記法で記述されたコンテンツを Pegdown パーサーが変換処理する際のタイムアウト時間をミリ秒単位で定義します。 この値は、個々の Markdown コンテンツの処理時間を制限します。

# millis to parse single markdown page. See PegDown Parse configuration for details
markdown.maxParsingTimeInMillis=2000

8.1.39. コンテンツストアの永続化

この項目は、コンテンツファイルの処理中に構築されたコンテンツストアをディスクに保存して永続化するかどうかを制御します。 ディスクに保存されている場合、次の解析時には変更のかかったコンテンツのみが処理されます。 永続化がされていない場合には、毎回すべてのファイルを解析することになります。

# database store (local, memory)
db.store=memory
  • local = コンテンツストアはディスクに永続化されます

  • memory = コンテンツストアは Bake中のみメモリに展開されます

8.1.40. コンテンツストアを永続化する際のパス

この項目は、コンテンツストアの永続化を行う際にデータを保存するディレクトリを定義します。 コンテンツストアの永続化が有効な場合のみ参照されます。

# database path
db.path=cache

8.1.41. Thymeleaf ロケール

この項目は、Thymeleaf がテンプレートを処理する際のロケールを定義します。

# thymeleaf locale
thymeleaf.locale=en

8.1.42. Asset ディレクトリ内の隠しファイル制御フラグ

この項目は、Asset ディレクトリ内にある隠しファイルを処理の対象にするかどうかを制御します。 この項目の値に true を設定した場合、.DS_Storedesktop.ini のようなファイルは処理の対象外となります。

asset.ignore=false

8.1.43. Index ページのページング制御フラグ

この項目を有効にした場合、Indexページを出力する際にページングが有効になります。 次の項目とあわせて使用します。

index.paginate=false

8.1.44. ページ毎のコンテンツ件数

この項目は、ページングが有効な場合の1ページあたりに表示されるコンテンツ件数を定義します。

index.posts_per_page=10

8.1.45. 拡張子なし URI の有効化フラグ

この項目は、拡張子なし URI を有効にするかどうかを定義します。この項目を有効にした場合、JBake は /blog/2014/03/26/post.html ではなく、 /blog/2014/03/26/post/index.html にファイルを出力し、拡張子なしでURIを参照できるようにします。

uri.noExtension=false
プレフィックスを定義するためには次の項目を定義する必要があります。

8.1.46. 拡張子なし URI が有効な場合のプレフィックス

この項目は、拡張子なし URI に用いられるプレフィックスを定義します。

uri.noExtension.prefix=/blog/

8.2. 独自設定オプション

jbake.properties ファイルには独自の設定を追加することも可能です。 サンプルプロジェクトにはサイトのホストURLを定義する site.host が記述されています。

site.host=http://jbake.org

この独自設定オプションは、フィードファイル用テンプレート内で以下のようにリンクの絶対URLを生成するために参照されています。

...
<title><#escape x as x?xml>${post.title}</#escape></title>
<link>${config.site_host}/${post.uri}</link>
<pubDate>${post.date?string("EEE, d MMM yyyy HH:mm:ss Z")}</pubDate>
...

9. ライブラリとしての利用

JBake は他のソフトウェアシステムからライブラリとして利用することも可能です。 プログラムで自動的に Bake したりとかできます。

9.1. Maven coordinates

メインの JBake アーティファクトは以下の記述で Maven セントラルリポジトリから入手することができます。

<dependency>
	<groupId>org.jbake</groupId>
	<artifactId>jbake-core</artifactId>
	<version>2.5.1</version>
</dependency>

Markdown コンテンツや Freemarker テンプレートエンジンなどをサポートするサードパーティーのライブラリは、 jbake-core のオプションライブラリとして定義されています。そのため、これらを使用する場合にはプロジェクトの依存関係を追加する必要があります。

Markdown コンテントをサポートするためには、以下の記述を追加します。

<dependency>
	<groupId>org.pegdown</groupId>
	<artifactId>pegdown</artifactId>
	<version>1.6.0</version>
</dependency>

AsciiDoc コンテントをサポートするためには、以下の記述を追加します。

<dependency>
	<groupId>org.asciidoctor</groupId>
	<artifactId>asciidoctorj</artifactId>
	<version>1.5.4.1</version>
</dependency>

Freemarker テンプレートをサポートするためには、以下の記述を追加します。

<dependency>
	<groupId>org.freemarker</groupId>
	<artifactId>freemarker</artifactId>
	<version>2.3.25-incubating</version>
</dependency>

Groovy テンプレートをサポートするためには、以下の記述を追加します。

<dependency>
    <groupId>org.codehaus.groovy</groupId>
    <artifactId>groovy</artifactId>
    <version>2.4.7</version>
</dependency>
<dependency>
    <groupId>org.codehaus.groovy</groupId>
    <artifactId>groovy-templates</artifactId>
    <version>2.4.7</version>
</dependency>

Thymeleaf テンプレートをサポートするためには、以下の記述を追加します。

<dependency>
	<groupId>org.thymeleaf</groupId>
	<artifactId>thymeleaf</artifactId>
	<version>3.0.2.RELEASE</version>
</dependency>

Jade テンプレートをサポートするためには、以下の記述を追加します。

<dependency>
	<groupId>de.neuland-bfi</groupId>
	<artifactId>jade4j</artifactId>
	<version>1.2.3</version>
</dependency>

9.2. API

JBake をJavaプログラムから起動する際にメインとなるのは Oven クラスになります。 このクラスのインスタンスを生成する際にいくつかの引数を渡し、 .bake() メソッドを実行します。

try {
	File source = new File("/path/to/project_source"); (1)
	File destination = new File("/path/to/project_output"); (2)
	Oven oven = new Oven(source, destination, true); (3)
	oven.setupPaths(); (4)
	oven.bake(); (5)
} catch (JBakeException e) { (6)
	// do something with exception here
}
1 プロジェクトのルートディレクトリを定義します。JBake はこのディレクトリ直下の jbake.properties を参照します。
2 処理結果の出力先ディレクトリを定義します。
3 3つ目の引数はローカルキャッシュ (永続的なコンテンツストア) をクリアして Full Bake (全変換) するかどうかのフラグになります。
4 このメソッドで指定されたパスや、必須となる要素の存在チェックをします。
5 このメソッドで Baking (変換処理) を実施します。
6 パスチェックや変換処理で例外が発生した場合、 JBakeException によって通知されます。

9.3. Logging

コマンドラインインターフェイス以外の全ての出力は、 LogBack を利用して行われています。そのため、クラスパス上の logback.xml を編集することによって制御することができます。 バイナリディストリビューションには、あらかじめ設定された logback.xml が含まれているので、参考にして下さい。

10. ビルドツールからの利用

10.1. Maven プラグイン

Maven から JBake を実行可能とするプラグインが利用可能です。

このプラグインは、以下の記述によって Maven セントラルリポジトリから取得することが出来ます。

<dependency>
    <groupId>br.com.ingenieux</groupId>
    <artifactId>jbake-maven-plugin</artifactId>
    <version>0.0.9</version>
</dependency>

このプラグインは Aldrin Leal によって開発されました。

10.2. Gradle プラグイン

Gradle の JBake プラグインもあります。

このプラグインは Cédric Champeau によって開発されました。

10.3. SBuild プラグイン

SBuild のプラグインもあります。

このプラグインは、以下の記述によって Maven セントラルリポジトリから取得することが出来ます。

<dependency>
    <groupId>org.sbuild</groupId>
    <artifactId>org.sbuild.plugins.jbake</artifactId>
    <version>0.1.2</version>
</dependency>

このプラグインは Tobias Roeser によって開発されました。