minerl is a blog-aware static site generator written in Perl, it supports tagging, automatic archiving, post, page and layout inheritance.
You can read the introduction in the following or read it in the first site generated by minerl.
Before installation, make sure you have installed all modules required by minerl, which 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 -L https://cpanmin.us | perl - --sudo App::cpanminus
After cpanm is installed, use the following command to install all required modules, note you may need root permission if the modules are to be 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 /usr/local/bin:
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.
mysite/
├── _pages
│ └── index.html
├── _raw
├── _templates
│ └── default.html
└── minerl.cfg
Page files are put in the _pages directory, layout files are put in the _templates directory, resource files(images/js/css) are put in the _raw directory, these directories are all specified in the minerl.cfg configuration file.
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.
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 byminerl generate), it MUST contain a variable calledcontent, like this:<TMPL_VAR content>.
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 type, tags and 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 typearchive__minerl_cur_month- string SCALAR, available in templates that are designed to be applied on pages of typearchive__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 typetaglist__minerl_cur_tag- string SCALAR, available in templates that are designed to be applied on pages of typetaglist
The following builtin variables(string SCALAR) are only available in templates that are designed to be applied on pages of type post:
__post_timestamp__post_title__post_link__post_createdate__post_createtime__post_tags__post_content__post_excerpt
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>
Currently minerl supports markdown, textile and Perl script, and of course, plain text/HTML.
Copyright 2013 neevek.
This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:
http://www.perlfoundation.org/artistic_license_2_0
Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.
If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.
This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.
This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.
Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.