Documentation v2.3.0

Getting Started

Installation

  1. Make sure you have a Java 6+ JRE and that the java command is available in your path

  2. Download and unzip JBake into a folder on your hard disk

  3. Add the JBake folder to your path environment variable

  4. Open a command prompt and run jbake -h (or jbake.bat -h if you are on Windows) to confirm everything works, you should see usage help text

JBake v2.3.0-SNAPSHOT (2013-10-12 22:43) [http://jbake.org]

Usage: jbake ...

Usage

  • Run jbake to do some baking, this will use the current folder as the source and place any baked output into an output folder in the current folder

  • Or you can run jbake <source_folder> <destination_folder> if you want full control over the source & destination folders

Quick Start

To get up and running quickly with JBake you can use its example project structure as a starting point for your site.

$ mkdir project
$ cd project
$ jbake -i

The -i option initialises the current folder with the necessary folder structure along with a default set of Freemarker templates to get you started. You can also get a set of Groovy or Thymeleaf based templates by supplying an extra parameter:

$ jbake -i groovy
$ jbake -i thymeleaf

Once you have added some real content to your site and customised the templates you can bake your site by running the following commands:

$ cd project
$ jbake

This will place your baked site in the output folder by default. You can then see what it looks like immediately by running JBake in server mode:

$ cd project
$ jbake -s
JBake v2.3.0-SNAPSHOT (2013-10-12 22:43) [http://jbake.org]

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

You can then preview your site in your browser at http://localhost:8820. You can configure what port the server runs via your configuration file.

You can also specify the folder to serve out along with the -s option like so:

$ jbake -s /home/user/site/output/
JBake v2.3.0-SNAPSHOT (2013-10-12 22:43) [http://jbake.org]

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

That’s all there is to it, to getting your own baked site!

Example Project Structures

The example project structure and sample templates are stored in your JBake installation folder in the files:

  • example_project_freemarker.zip

  • example_project_groovy.zip

  • example_project_thymeleaf.zip

If you’d like to change the structure or sample templates in some way then you can extract the contents of these files, update as required, then ZIP them back up and replace the original files with your updated files. Then JBake will use your updated project structure and templates when ever it initialises a new folder from then on.

Project Structure

Here is an example source folder structure:

.
|-- assets
|   |-- favicon.gif
|   |-- robots.txt
|   |-- css
|       |-- style.css
|-- content
|   |-- about.html
|   |-- 2013
|       |-- 02
|           |-- weekly-links-1.html
|           |-- weekly-links-2.md
|-- templates
|   |-- index.ftl
|   |-- page.ftl
|   |-- post.ftl
|   |-- feed.ftl
|-- jbake.properties

Assets Folder

Place your static files in this folder and they will be copied to the root of the destination folder. Any folder structure you create will be maintained.

Content Folder

Place your dynamic content in this folder, the content in the files in this folder will be "mixed" with the templates to generate your site. Again any folder structure you create will be maintained in the destination folder.

The extension of the file determines what content it contains:

  • .html = raw HTML content

  • .md = Markdown formatted content

  • .ad = AsciiDoc formatted content

  • .adoc = AsciiDoc formatted content

  • .asciidoc = AsciiDoc formatted content

JBake uses the Java integration library of the Asciidoctor project to support the AsciiDoc format.

Each raw HTML or Markdown content file must have a meta-data header in it:

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

In the header you must have at least the status & type fields, the rest are optional. The only exception to this rule is if you define a default status in your configuration file.

For an AsciiDoc content file the meta-data header section is optional, the JBake meta-data can be included in the AsciiDoc header itself like so:

= Project Structure
Jonathan Bullock
2013-10-17
:jbake-type: page
:jbake-tags: documentation, manual
:jbake-status: published

Note: JBake related attributes included in the AsciiDoc header require the jbake- prefix.

Status

You have 3 options for the status field:

  • draft - drafts are rendered along with published posts however they are given a "-draft" suffix, for example first-post-draft.html, but not included in the published posts or pages arrays

  • published - published content is rendered and included in the published posts or pages arrays

  • published-date - providing content date is equal to or past current date content will be included in published posts or pages array

Type

You can choose what template file your content file will be rendered or mixed with by changing the value of the type field:

  • type=post will use post.ftl

  • type=page will use page.ftl

Expandable Header

You can also include extra meta data in the header that is also exposed to the templates:

summary=This is a summary of the larger post

And access it from the template like so:

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

Templates Folder

This is the folder where your Freemarker, Groovy or Thymeleaf templates go. The following template extensions are supported:

  • .ftl = Freemarker

  • .gsp = Groovy

  • .groovy = Groovy

  • .gxml = Groovy

  • .thyme = Thymeleaf

It is recommended that you don’t mix different template types, try to stick to just 1 type of templates.

For more information on what you can do in each template engine have a look at the example templates provided with JBake and their respective documentation: Freemarker, Groovy & Thymeleaf.

Data Model

A data model is exposed to each of the template engines allowing you to get access to the data contained within the content files, the model can also be used to apply logic to the output from the templates.

Global

This data is available to all templates regardless.

  • $v2.7.0-rc.6 = version of JBake being used

  • ${published_date} = date baking took place

  • ${[type]s} = collection of all content of <type> (e.g. posts = all of type=post & pages = all of type=page)

  • ${published_content} = collection of all published content (regardless of type)

  • ${all_content} = collection of all content (regardless of type)

  • ${config.[options]} = map of configuration data

All the configuration options are available with any . in the property being replaced with _. For example template.index.file=index.ftl is available via ${config.template_index_file}.

You can loop through any of the collections above in the templates, and access the map of options for each element like so: ${post.[option]} all of the header fields are available such as ${post.title} or ${post.body}.

Page / Post / Custom

These predefined templates as well as any custom templates you create yourself have the following data available to them:

  • ${content.[options]} = map of file contents

All of the header fields are available such as ${content.title} and the body of the file is available via ${content.body}.

Index / Feed / Archive

These predefined templates have the following extra data available to them:

  • ${published_posts} = collection of just published posts in date descending order

  • ${published_pages} = collection of just published pages in date descending order

Tags

This predefined template has the following extra data available to it:

  • ${tag} = tag being rendered

  • ${tag_posts} = collection of published posts for tag in date descending order

Configuration

The jbake.properties (or custom.properties) file allows you to override the default configuration of JBake. You can change the name of the folder that stores your content or templates, decide whether to generate a RSS feed or not. See default.properties for what options you can override.

Export to Asciidoctor

If asciidoctor.attributes.export is set to true then the JBake configuration options are made available from within Asciidoctor formatted pages. You can also set a prefix for the JBake configuration options by defining a value for asciidoctor.attributes.export.prefix.

Default Status

You can avoid having to include a status value in every content file by setting a default using the option default.status. The default is only used if one hasn’t been defined in the content file itself.


Fork me on GitHub