Poet is a blog generator in node.js to generate routing, render markdown/jade/whatever posts, and get a blog up and running fast. Poet may not make you blog-famous, and it may give you one less excuse for not having a blog, but just imagine the insane hipster cred you get for having node power your blog. "Cool blog, is this Wordpress or something?" your square friend asks. "Nah dude, this is in node," you respond, while skateboarding off into the sunset, doing mad flips and stuff. Little do they know you just used Poet's autoroute generation to get your content in, like, seconds, up on that internet.
First thing first, throw Poet into your express app's package.json, or just install it locally with:
npm install poet
Once you have the Poet module in your app, just call it and pass in your express server and use some autorouting methods. Now you just need to make some posts and you're good to go!
var
express = require('express'),
app = express(),
poet = require('poet')( app );
poet
.createPostRoute()
.createPageRoute()
.createTagRoute()
.createCategoryRoute()
.init();
You can also pass in some configuration options, and specify a callback in the init method once all your posts are loaded up. All the locals/middleware functions and stores are passed into the init function for modification or use. Below are the config defaults:
var
express = require('express'),
app = express(),
poet = require('poet')( app );
poet.set({
posts: './_posts/', // Directory of posts
postsPerPage: 5, // Posts per page in pagination
metaFormat: 'json', // meta formatter for posts
readMoreLink: function (post) {
// readMoreLink is a function that
// takes the post object and formats an anchor
// to be used to append to a post's preview blurb
// and returns the anchor text string
},
readMoreTag: '<!--more-->' // tag used to generate
// the preview. More in 'preview' section
})
.createPostRoute()
.createPageRoute()
.createTagRoute()
.createCategoryRoute()
.init(function ( locals ) {
// Some callback to run once everything is set up
// The core storage is passed in as an argument,
// where all the locals/middleware functions
//and stores can be altered
});
Posts are constructed in markdown/jade/whatever, prefixed by front matter via YAML or JSON. All attributes are stored in the posts object. An example of a blog post formatted with JSON Front Matter is below:
{{{
"title" : "Hello World.js",
"tags" : [ "blog", "fun" ],
"category" : "javascript",
"date" : "8-9-2012"
}}}
Here goes the content that belongs to the blog post.
Blawg blawg blawg blawg.
With autoroutes, the name of the file is the slug used in the route.
There are several ways of specifying the text of your post preview. First is through a preview property on your post, which is the text that will run through your template and appear as the preview. Second is a previewLength property on a post, which will take the first n characters of your post (preformatted) and run it through the template, becoming your preview. Third, and easiest most likely, is specfiying a readMoreTag option during set up, which by default is <!--more-->. Whenever the readMoreTag is found in the post, anything before becomes the preview. You can set this in your options, or specify a readMoreTag property for each post individually.
The above is the order that Poet checks for when generating the post previews.
Below the front matter, your posts can be written in markdown, jade, whatever. Out of the box, Poet renders markdown and jade, based off of the file extension. If you'd like to write your own formatter in mustache, YAML, or what have you, call addTemplate.
var
express = require('express'),
app = express(),
yaml = require('yaml'),
poet = require('poet')( app );
poet
.addTemplate({
ext: 'yaml',
fn : function ( s ) { return yaml.eval( s ); }
})
.createPostRoute()
.createPageRoute()
.createTagRoute()
.createCategoryRoute()
.init();
You can chain-add formatters and Poet will use the appropriate templating based off of the file extension on a per-post basis. Some blogs are more text-based where markdown works great, but others require simple HTML elements, like Jade. The packaged markdown settings will allow you to print HTML explicitly, however. Or maybe you'd like some other template that works great for you!
The methods autogenerate routes for individual posts, post lists, tags and categories. You can choose to use the generated routes, configure the generated routes, or just use your own. Each generator takes a route and a view file as their arguments -- below are the methods and their default routes and views.
For examples, check out the repo for demos using the default routing, configured autogenerated routes, and hand-made custom routes.
The following variables and functions are exposed to all views.
Using the route generators, additional locals are passed in on specific pages:
When on a specific post's page, all the post's metadata specified in the front-matter is exposed in the post object as well as the following:
When on a page of posts..
When on a tag page..
When on a category page..
You can also use all the non-page specific locals in your routes, especially useful when defining your own custom routes. Use the middleware method when setting up your express app like so:
app.use( express.static( __dirname + '/public' )); app.use( poet.middleware() ); app.use( app.router );
This exposes all the locals to the request object under the poet namespace.
Also check out the custom routes example to see an example of attaching the middleware and using the locals in routes.
Easy to set up an RSS feed too! Check out the example in the examples directory in the source. Uses jade templating and a simple route, so can be extended anyway you'd like by adding additional properties on per post and using them in your RSS view.
Time to start writing your sweet, beautiful words. For more development information, check out the repository, or scope out the examples in there to get a better idea. If you have any comments, questions, or suggestions, hit me up @jsantell!