node package manager

juicepress

Super simple static blog generator

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.

This requires a plugin for a build tool

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

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

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.

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>

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.

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"

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) []
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.

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

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.