juicepress

Static Blog Generator

Juicepress is a node package that generates a blog of HTML files from markdown sources. Currently, it must be invoked via grunt or gulp. Direct calls and other build tools are not yet supported.

Installation and Usage

This requires a plugin for a build tool

• grunt-contrib-juicepress
• gulp-juicepress

See the readme of this packages to find out, how to install and call it.

A fully working example can be seen at https://github.com/trenker/juicepress-example

Rendering

The creation of a blog consists of the following steps:

1. Read all markdown files, which are considered posts
2. Create category and tags information based on the YFM in the posts
3. Create a schedule of actual HTML pages to render, including splitted lists with pagination over several HTML files

Pages

There are two types of pages: posts and lists

• posts are blog posts which use markdown and are rendered using the defaultTemplate or the one configured in the YFM
• lists are lists of blog posts. They always use the listTemplate

There are three types of lists:

• index is the index page(s) of the blog, containing all posts
• category are the lists of posts that belong to a certain category
• tag the same as category lists, but this time the relation is created by the tags a post has.

All posts are sorted in chronological order with the newest first and the oldest last, aka descending. The relation, which categories and tags a post has, is defined in the YFM.

Templates

There must be at least two templates: default for posts and list for lists. All templates are rendered using handlebars, so you can use all the handlebars options and possibilities.

Additionally all options and YFM settings are available. Option settings and YFM settings that are not recognized by juicepress, are passed as well.

eg.: in the YFM you can add extended author information like this:

author:
  name: My Name
  email: [e-mail]

and in the template, you can write it out like this:

<p class"author">This is a post by <a href="mailto:{{ author.email }}">{{ author.name }}</a></p>

Targets

This does not refer to grunt targets. Instead, it's the URL of a page. Each page has a target property, a relative file name without file ending.

eg.:

A post with the title My Post and two categories Top, Lower (in that order!) will have the target top/lower/my-post

The second page of the posts listing of a category with the name Main Category and the default juicepress options, will have the target categories/main-category/page-2

This targets determine

1. How the URLs are created when using the helper link_post
2. To which file a page will be written.

Helpers

The following helpers are registered for all layouts:

{{link_post "name or target" }} Will create an URL to the given post.

eg.: a target "top/lower/my-post" and the default juicepress options will create the URL "/top/lower/my-post.html"

Options

Yaml Front Matter

Name	Type	Description	Required	Default
title	string	Page title of the post	Yes	-
date	DateTime	When the post was published	Yes	-
excerpt	string	A short summery of the blog post	No (but recomended)	-
categories	array>string<	List of tags	No (but recomended)	[]
tags	array>string<	List of tags	No (but recomended)	[]

Build Time Options

Name	Type	Description	Required	Default
linksPerPage	integer	How many items / links to show on a single list page	Yes	10
baseUrl	string	The (absolute) URL to the root of your blog. Should be set to a full URI like http://example.tld/blog/. MUST have a trailing slash!	Yes	"/"
minimize	boolean	If the generated HTML should be compressed using minimize	No	true
minimizeOptions	object	Options passed to minimize. If omitted, its default settings are used.	No	null
paginationSuffix	string	The suffix for list pages, higher than one. The placeholder {{ page }} will be replaced with the page number. If it starts with a slash (like the default), all pages will be in a subfolder.	No	"/page-{{ page }}"
categoryPagePrefix	string	The prefix / folder for list pages of categories.	No	"/categories"
tagPagePrefix	string	Same as categoryPagePrefix, but for tags.	No	"/tags"
layouts	string	Globbing pattern for handlebars templates. The files found can be used as layouts.	No	"./layouts/**.*"
defaultLayout	string	The default layout used for posts. The name is the templates file name without path or ending.	No	"default"
listLayout	string	The same as *defaultLayout*, but for list pages.	No	"list"
partials	string	Globbing pattern for handlebars templates, that will be injected as partials.	No	"list"
helpers	string	Globbing pattern for javascript files that are included prior the page rendering. They are expected to export a single function, that receives three arguments (in that order): "Handlebars": Reference to the handlebars instanced used, "options": This options, with their settings, "posts": An array of post page objects. Useful, eg., for adding additional helpers.	No	"./helpers/**/*.js"
buildDirectory	string	Name of the directory to write the files into. Relative to the process.cwd().IMPORTANT: Ignored when building with gulp!!	No	"./_build/"
generateSitemap	boolean	If a XML sitemap file should be generated. The last modified date is determined by the posts dates.	No	true
sitemap.frequency.(index|list|post)	string	The change frequency for the different page types	Yes (if generateSitemap is true)	"yearly" for posts, "monthly" for tag- and category - lists, "weekly" for index - lists
sitemap.priority.(index|list|post)	float as string	The priority settings for the page types	Yes (if generateSitemap is true)	"1.0* for posts, "0.8" for tag- and category - lists, "0.9" for index - lists
sitemap.target	string	The target filename of the sitemap file. Relative to the buildDirectory setting (grunt) or the cwd (gulp)	Yes (if generateSitemap is true)	"sitemap.xml"

For a full list of options for the setting minimizeOptions, please go to https://github.com/Moveo/minimize

The markdown renderer uses highlight.js for fenced code blocks. If you have code in your post, please add a stylesheet for propper display in the browser.

Todo

• Drafts
• Multi Language Support
• Direct invocation
• Unit tests (Yes, I know it should already have those)

License

Copyright (c) 2014 Georg Großberger

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.