Minerl is a blog-aware static site generator written in Perl, it supports tagging, automatic archiving, post, page and layout inheritance.
Before installation, make sure you have installed all modules required by Minerl, Minerl depends on the following modules:
Config::IniFiles HTML::Template Text::Template Text::MultiMarkdown Text::Textile Getopt::Compact::WithCmd HTTP::Server::Brick
I recommend cpanm for installing modules.
curl -o cpanm https://raw.github.com/miyagawa/cpanminus/master/cpanm chmod +x cpanm
After cpanm is installed, use the following command to install all required modules, note you may need root permission if your Perl modules are installed in system directory:
cpanm Config::IniFiles HTML::Template Text::Template Text::MultiMarkdown \ Text::Textile Getopt::Compact::WithCmd HTTP::Server::Brick
Okay, all prerequisites are met, we are ready to install and try out Minerl. It is that straightforward, simply clone the code from github, change direcotry to the root of the project,
make && make install installs the minerl script under
git clone https://github.com/neevek/minerl.git cd minerl make && make install
Now generate your first minerl site:
minerl genearte -d mysite cd mysite minerl build -v minerl serve
You may have already seen the output of the commands, navigate your browser to
http://127.0.0.1:8888. Cool! You have just created the first page of your minerl site.
minerl v0.02 usage: minerl [options] COMMAND options: -h, --help This help message Implemented commands are: build - Applies the templates on the pages, generates the final HTML pages createpost - Creates the skeleton of a new post generate - Creates a brand new Minerl site serve - Starts an HTTP server to serve the directory specified by the 'output_dir' property in minerl.cfg See 'minerl help COMMAND' for more information on a specific command.
Currently 4 commands are implemented, for more information, run
minerl help COMMAND.
What can Minerl do for you
Now that you have installed minerl, you may want to know more about it, and see what it can do for you. In the begining I mentioned that Minerl supports tagging and automatic archiving, which sounds unclear, what is that?
tagging per se is not interesting at all, the fun part is that after you tag your blog posts, Minerl will organize all your posts and group them by tags, so that you can create index pages listing posts for each tag, which is cool for a pure static site. automatic archiving works in the same way, it organizes all your posts and group them by months, you can create index pages for all months as you would for tags. automatic archiving requires the timestamp header in every post to work. I recommend you always use
minerl createpost to create the skeleton of a new post, which sets the timestamp as well as a few other headers for you.
Note: when I am talking about posts, I mean pages of type post, which is set in the header section.
A template file is composed of a header section and a content/body section, header section starts and ends with 3 or more dashes. Minerl uses
HTML::Template to expand variables in template files, template files can be inherited, which makes HTML structure design a lot easier even if you have many pages. A template inherits another by specifying the
layout header and name the inherited template without suffix, like this:
--- layout: default ---
- When a template is designed to be inherited(like
default.htmlin the demo created by
minerl generate), it MUST contain a variable called
content, like this:
Format of pages are the same as that of template files, a header section and a content/body section, the only difference is that you may always need to set more headers for pages. Let's take an example of this post, which contains the following headers:
- title: Introduction to Minerl
- layout: post
- format: markdown
- type: post
- tags: minerl, perl
- slug: introduction-to-minerl.html
- timestamp: 1372332934
For a normal page, the
timestamp headers are not needed.
slug is used as the final output file name of the page, if it is absent,
title will be used instead with whitespaces replaced with dahses.
Minerl offers quite a few builtin variables that can be used to generate index pages for tags and archives. Builtin variables can be referenced in templates with HTML::Template syntax.
Minerl offers the following builtin variables:
__minerl_all_posts- ARRAY, used in LOOP, available in all templates
__minerl_recent_posts- ARRAY, used in LOOP, available in all templates
__minerl_archived_months- ARRAY, used in LOOP, available in all templates
__minerl_archived_posts- ARRAY, used in LOOP, available in templates that are designed to be applied on pages of type
__minerl_cur_month- string SCALAR, available in templates that are designed to be applied on pages of type
__minerl_all_tags- ARRAY, used in LOOP, available in all templates
__minerl_tagged_posts- ARRAY, used in LOOP, available in templates that are designed to be applied on pages of type
__minerl_cur_tag- string SCALAR, available in templates that are designed to be applied on pages of type
The following builtin variables(string SCALAR) are only available in templates that are designed to be applied on pages of type
Besides the above variables, all user defined variables in page headers are available in all templates.
The following code uses the
__minerl_all_posts variable to list all posts of the site:
<ul> <TMPL_LOOP __minerl_all_posts> <li><a href="<TMPL_VAR __post_link>"><TMPL_VAR __post_title></a></li> <div class="post_content"> <TMPL_VAR __post_excerpt>... </div> </TMPL_LOOP> </ul>
The following code uses the
__minerl_tagged_posts variable to list all posts of a certain tag:
<ul> <TMPL_LOOP __minerl_tagged_posts> <li><a href="<TMPL_VAR __post_link>"><TMPL_VAR __post_title></a></li> <div class="post_content"> <TMPL_VAR __post_excerpt>... </div> </TMPL_LOOP> </ul>
For more information, run