A tiny static-ready blog engine inspired by the toto library. The shiniest blog engine in Oz!
npm install -g tinman
A basic tinman blog looks like this:
example
├── articles
│ └── 2014-06-22-hello-world.md
└── public
└── style.css
Some features include:
Tinman generates a page for each article, and an index page listing your
articles (sorted by filename). Naming your articles YYYY-MM-DD-my-title.md
will sort them such that the most recent article is listed first. It
will also set the article's date property for you.
$ tinman create
Blog title: myblog
Your blog is ready! To get started:
cd myblog/
tinman server
$ tinman create myblog
# Generate example templates to play with as well
$ tinman create myblog --with-templates
$ tinman new
Title: This is my first blog post
Article generated at: articles/2014-07-05-this-is-my-first-blog-post.md
$ tinman server
Server listening on port 3000...
$ tinman server --port 1337
Server listening on port 1337...
$ tinman build
Blog successfully built to: build/
$ tinman build --output-dir www
Blog successfully built to: www
Articles are written in Markdown and use YAML Front Matter to set various options.
---
title: Hello, World!
date: 2014-06-22
---
Once upon a time...
This article will be accessible at the url /hello-world
by default
(based on the article's title). You can customize this option by either:
slug
property, making the article accessible at
/your-slug-here
route
property, and completely overriding the slug (i.e.
route: /2014/06/24/musings/my-article
You can include any custom options you'd like (i.e. color: red
) in
your YAML Front Matter, and recall it from a custom template.
Tinman uses EJS templates and includes the following:
To customize these templates, pass the --with-templates
option to
tinman create
:
$ tinman create myblog --with-templates
Your blog is ready! To get started:
cd myblog/
tinman server
$ tree myblog
myblog
├── articles
│ └── 2014-06-22-hello-world.md
├── public
│ └── style.css
├── templates
│ ├── article.ejs
│ ├── index.ejs
│ └── layout.ejs
└── tinman.json
Beyond the articles directory and sample stylesheet, the
--with-templates
option creates a templates directory and a
tinman.json
file, instructing Tinman to use these templates instead of the
ones built into it.
The article template receives all properties of the article as defined in
the YAML Front Matter. The content of the article is stored as body
. Some
extra fields include:
date
property of the article's Front MatterThe index template has access to the array articles
, which holds
every article in your blog.
The layout template receives a body
, which contains the rendered HTML of
the page it contains (either an article page or the index). This template also
has access to two strings, stylesheets
and scripts
, which store the CSS/JS
resource tags generated automatically based on the contents of your public
directory.
Plugins are small helper modules that all templates can access, allowing you to add extra functionality to your blog. An example plugin may look like the following:
// hello.js
module.exports = function (name) {
return "Hello, " + name + "!";
};
Which you can then access in any template like so:
<title><%= plugins.greeting("Jordan") %></title>
In order for Tinman to appropriately load your plugins, you need to
populate the plugins
object in your tinman.json
file. You'll notice
this file is generated for you automatically when you create a new blog
using the --with-templates
option.
{
"title": "Jordan's awesome blog",
"plugins": {
"greeting": "./hello"
}
}
Each entry in plugins
consists of two items, the identifier that your
template will be able to call (i.e. plugins.greeting
) and a require
string (just as you would pass to require()
in node).
{
"plugins": {
"ms": "ms", // load "ms" from node_modules/
"other": "./blah" // load "blah.js" locally as "other"
}
}
Just remember to npm install
any external modules before trying to use
them.
Tinman will automatically copy static assets (images, stylesheets,
javascripts) from the "public" directory (default: public/
).
For instance, you can write the following to public/css/colors/main.css:
body {
color: #222222;
}
And access it like so:
<link rel="stylesheet" href="https://github.com/jdan/tinman/blob/master/css/colors/main.css">
You can follow the same pattern for including images in your articles, or even serving static HTML documents.
In addition, Tinman scans for javascripts (*.js
) and stylesheets (*.css
)
and automatically generates resource tags in the layout template
(layout.ejs is sent both a scripts and stylesheets string). You do
not need to edit any templates after writing javascripts or stylesheets.
-- MIT Licensed