gulp-viking-posts

Viking Posts is a gulp plugin meant to work with Viking Base to create lightweight JSON blog posts from Markdown files. The plugin can be used without Viking Base, too.

Getting Started

Install the package via npm:

npm install --save-dev gulp-viking-posts

Edit the gulp file in your Viking Base project:

// Output updates
vb.output.post = 'posts/';
vb.output.posts = 'posts.json';
 
// Source updates
vb.sources.posts = 'posts/**/*.md';
 
// Task updates
vb.tasks.build.depends = [
  'handlebars',
  'js-doc',
  'posts',
  'root'
];
 
vb.tasks.posts = {
  cb: function() {
 
    return gulp.src( this.sources.posts )
      .pipe( plugins.vikingPosts() )
      .pipe( gulp.dest( this.output.publish + this.output.post ) )
      .pipe( plugins.concat( this.output.posts, {
        newLine: ','
      }))
      .pipe( plugins.vikingPosts({
        concat: true
      }))
      .pipe( gulp.dest( this.output.publish + this.output.post ) );
  }
};

In the above example, 4 key steps are shown:

Post output is specified. There's a path to the post output folder, vb.output.post, and a file name for concatenated posts vb.output.posts.
Post source is defined vb.sources.posts.
Build dependencies now include posts task.
Posts task is defined. The example above also shows how to concatenate posts into one file.

Note: Concatenating posts is optional and is easily done by using the gulp-concat plugin that Viking Base already depends on. If you aren't using Viking Base, you'll need to include gulp-concat yourself. Pay close attention to the second argument passed to plugins.concat. This is an options hash for gulp-concat. It's critical that the newLine property's value is ','. If not, gulp-concat will separate posts with a new line and produce invalid JSON for the final output. It's also key to pass an options hash to the second occurence of plugins.vikingPosts with a concat property having a value of true. This tells the Viking Posts plugin to work with concatenated posts and to remove the full content from them, leaving only the excerpt.

Using gulp-viking-posts without Viking Base

Using this plugin without Viking Base is perfectly fine but the above example won't be too helpful.

A more abstract example:

var concat = require('gulp-concat'),
    gulp = require('gulp'),
    vp = require('gulp-viking-posts');
 
gulp.task('posts', function() {
  
  return gulp.src('posts/**/*.md')
    .pipe( vp() )
    .pipe( gulp.dest('dist/posts') )
    .pipe( concat( 'posts.json', {
      newLine: ','
    }))
    .pipe( vp({
      concat: true
    }))
    .pipe( gulp.dest('dist/posts') );
});

Writing Posts

Posts are simply Markdown files that can optionally include YAML front matter. If front matter is ommitted, Viking Posts will get the title from the file name, the excerpt from the first <p> tag it finds, the creation and updated dates from the file system and the category from the file path. For example, a file found in posts/articles/ that has no front matter will be categorized in "articles".

Example:

---
title: Hello World
category: articles
excerpt: My first post!
created: 6/24/2014
updated:
---
 
# Hello World
 
This is my first post!

Custom Front Matter

Any front matter that isn't title, category, content, created, excerpt or updated will be added to the generated post object.

Plugin Options

You may pass an options hash to the Viking Posts plugin. The options are:

concat: {boolean} Tells the Viking Posts plugin to concatenate posts
formatDate: {function} User-defined function that overrides the built-in date formatting function. Expects a date or a string to be passed in.
highlightSyntax: {boolean} Tells the Viking Posts plugin to highlight syntax with Highlight.js. Default is false.
sortPosts: {function} User-defined sort function for concatenated posts. Defaults to date descending, category, title. Expects two post objects to be passed in.
titleSeparator: {string} For use without front matter. Viking Posts will generate a post title from the file name, separating words by this separator. Default is '-'.

Syntax Highlighting

Introduced in version 0.0.5, Viking Posts uses Highlight.js to highlight syntax. To enable this feature, set the option highlightSyntax to true. Since Viking Posts parses GitHub flavored Markdown by default, you can specify the language of any code block as follows:

```javascript
function example() {
  
  // This is a JavaScript example
}
```

Note: You need to add CSS from Highlight.js to your project manually. Viking Posts only adds the Highlight.js markup.

Example Output

Single post dist/posts/articles/hello-world.json:

{
  "title": "Hello World",
  "category": "articles",
  "excerpt": "<p>My firt post</p>",
  "content": "<h1>Hello World</h1>\n<p>My first post is here!</p>",
  "created": "6/20/2014",
  "updated": ""
}

Concatenated posts dist/posts/posts.json:

[
  {
    "title": "Hello World",
    "category": "articles",
    "excerpt": "<p>My firt post</p>",
    "created": "6/20/2014",
    "updated": ""
  },
  {
    "title": "Chicken Soup",
    "category": "recipes",
    "excerpt": "<p>A delicious chicken soup recipe that's been in my family for generations.</p>",
    "created": "6/19/2014",
    "updated": "6/24/2014"
  }
]

Changelog

v0.0.6

Fixed major bug in previous release: Highlight.js module was not included in dependencies

0.0.5

Added syntax highlighting via Highlight.js

v0.0.4

Posts no longer create an updated date from the file system if that date matches the creation date

v0.0.3

Changed Markdown dependency

v0.0.2

Changed default posts sort by creation date instead of updated date