Documentation v2.2.1

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.2.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 base 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 templates to get you started.

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.2.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.2.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!

Base Project Structure

The base project structure and sample templates are contained in base.zip in your JBake installation folder. If you’d like to change the structure or sample templates in some way then extract the contents of this file, update as required, then ZIP them back up and replace the base.zip file with your updated file. Then JBake will use your updated file when ever it initialises a new folder.

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.

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 templates go. Each template file must have a .ftl extension. For more information on what you can do in Freemarker templates see the Manual.

Data Variables

Data variables are exposed to the Freemarker templates allowing you to get access to the data contained within the content files, they can also be used to apply logic to the output.

Global

This data is available to all templates regardless.

  • ${version} = version of JBake

  • ${posts} = collection of all posts (files that don’t have type=page)

  • ${pages} = collection of all pages (files that have type=page)

  • ${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 the above collections using:

<#list posts as post>
	..
</#list>

Within the loop you can then access the options for each post or page: ${post.[options]} or ${page.[options]}

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

Page / Post

These templates (page.ftl & post.ftl) 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 templates (index.ftl, feed.ftl & archive.ftl) have the following extra data available to them:

  • ${published_posts} = collection of just published posts

  • ${published_date} = date when file is generated (only available to Feed)

Tags

This template (tags.ftl) has the following extra data available to it:

  • ${tag} = tag being rendered

  • ${tag_posts} = collection posts for tag

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.


Fork me on GitHub