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
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:
- Read all markdown files, which are considered posts
- Create category and tags information based on the YFM in the posts
- 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:
This is a post by {{ author.name }}
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
- How the URLs are created when using the helper
link_post
- 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.