JBake v2.3.0-SNAPSHOT (2013-10-12 22:43) [http://jbake.org] Usage: jbake ...
Make sure you have a Java 6+ JRE and that the java
command is available in your path
Download and unzip JBake into a folder on your hard disk
Add the JBake folder to your path environment variable
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 ...
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
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!
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.
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
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.
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:
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.
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
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
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>
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.
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.
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}
.
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}
.
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
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
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.
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
.
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.