juicepress v1.1.0

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: email@author.com

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

Build Time Options

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.