genghis v0.1.8

genghis

A static blogging engine. Build a blog with more controls in a single setting.

Why?

There are lots of blogging engine already, most of them are great working if you want to build a general and simple blog. But for some cases, it was not that easy to configure. Such as if you want to change your posts' routes from /posts/ to /blog/post, or tags' routes from /tags/ to /blog/tags it was hard to change.

genghis not only make the whole blog's routes flexible, and also make the whole configuration in one place, which means you only need to setup your blog in a .json file. Sounds cool?! :)

Table of Content

• Install
• Usage
• API
• Sample
• Blog
  • Structure
• Settings
  • Post Settings
  • Posts
  • Categories
  • Tags
  • Author

Install

Install genghis cli tool to global.

npm install -g genghis

Install npm module

npm install genghis

Usage

build blog

options

• -w: watching files, if hbs changes genghis will rebuild files.

$ genghis ./blog.json -w

API

build

build blog API

genghis.build(json_file_path)
      .then(function(){
          // do your stuff
      })
      .catch(function(err){
          // deal with error
      });

watch

watch blog API

genghis.build(json_file_path, true)
      .then(function() {
        // do things
      })
      .catch(function(err) {
        // do things
      })

Sample

Here is a sample configure file blog-multi.json

Blog

Structure

Your setting structure of the blog.

blog.json:

{
  // categories (optional)
  "categories": {
    ... (see categories section for more information)
  },
  // tags (optional)
  "tags": {
    ... (see tags section for more information)
  },
  // author (optional)
  "author": {
    ...  (see author section for more information)
  },
  // necessary
  "post_settings" {
    ... (see post settings section for more information)
  },
  // necessary
  "posts": [
    ... Array (see posts section for more information )
  ]
}

Settings

post settings

Setting your post's layout and where the post's root folder, add a key named post_settings, set your layout, path inside. Every posts will render through the layout, and generate to the path in the path setting.

e.g.

"post_settings": {
  // hbs helpers, partials, see settings in helpers and partial sections (optional)
  "helpers": ["./blog/helper.js"],
  "partials" ["./blog/partials"],
  "layout": "./blog/post.hbs",
  "path": "./opendata/post/"
},

posts

Create a new post.

Setting date, url_name are necessary.

Main settings

• date: date's format should be like %Y/%m/%d %H:%M:%S this is very important. Because the date is used to render a specific post result. For example, if you set the post settings' path to "path": "./opendata/post/" and your date "date": "2015/08/03 22:07:39", genghis will build your post in directory ./opendata/post/2015/08/03/your-post-name.html

• url_name: Defines your post file name. From the example above it defines ./opendata/post/2015/08/03/<url_name>.html.

e.g.

"posts": [{
  "title": "This is a test post",
  // date format should be like %Y/%m/%d %H:%M:%S
  "date": "2015/08/03 22:07:39",
  "categories": ["opendata", "visualization"],
  "tags": ["taiwan", "health"],
  "cover": "http://i.imgur.com/o6llC95.jpg",
  "content": "./blog/test_post.md",
  // what your post html file called
  "url_name": "test-post",
  "author": "taiwanstat"
}]

Categories

Create categories in your blog.

Main settings

Setting layout, path, items are necessary.

• layout: genghis will generate all the categories using the layout.
• path: path is the root of the category folders. For instance, "path": "./opendata/categories" means it will generate ./opendata/categories/category1/, ./opendata/categories/category2/, ...
• items: This is where you defined your categories. The sample below means this blog have opendata, visualization categories. And every variables defines in it will pass to your hbs template while rendering.

e.g.

// categories (optional)
"categories": {
  // hbs helpers, partials, see settings in helpers and partial sections (optional)
  "helpers": ["./blog/helper.js"],
  "partials" ["./blog/partials"],
  "layout": "./blog/categories.hbs",
  "path": "./opendata/categories",
  "items": {
    // your categories settings
    "opendata": {
      "description": "this is a opendata categories",
      "others": "you can put your other variables here"
    },
    "visualization": {
      "description": "this is a visualization categories",
      "others": "you can put your other variables here"
    }
  }
}

Tags

Create tags in your blog.

Main settings

Setting layout, path, items are necessary.

• layout: genghis will generate all the tags using the layout.
• path: path is the root of the tag folders. For instance, "path": "./opendata/tags" means it will generate ./opendata/tags/tag1/, ./opendata/tag/tag2/, ...
• items: This is where you defined your tags. The sample below means this blog have weather, blog, health, taiwan tags. And every variables defines in it will pass to your hbs template while rendering.

e.g.

// tags (optional)
"tags": {
  // hbs helpers, partials, see settings in helpers and partial sections (optional)
  "helpers": ["./blog/helper.js"],
  "partials" ["./blog/partials"],
  "layout": "./blog/tags.hbs",
  "path": "./opendata/tags/",
  "items": {
    // your tags settings
    "weather": {
      "description": "this is a weather tag",
      "others": "you can put your other variables here"
    },
    "blog": {
      "description": "this is a blog tag",
      "others": "you can put your other variables here"
    },
    "health": {
      "description": "this is a health tag",
      "others": "you can put your other variables here"
    },
    "taiwan": {
      "description": "this is a taiwan tag",
      "others": "you can put your other variables here",
      "others2": "you can put your other variables here"
    }
  }
}

Author

Create Author list

Main settings

Setting layout, path, items are necessary.

• layout: genghis will generate all the author using the layout.
• path: path is the root of the author folders. For instance, "path": "./opendata/author" means it will generate ./opendata/author/taiwanstat/, ./opendata/author/chilijung/, ...
• items: This is where you defined your author. The sample below means this blog have taiwanstat, chilijung author. And every variables defines in it will pass to your hbs template while rendering.

e.g.

"author": {
  // hbs helpers, partials, see settings in helpers and partial sections (optional)
  "helpers": ["./blog/helper.js"],
  "partials" ["./blog/partials"],
  "layout": "./blog/author.hbs",
  "path": "./opendata/author",
  "items": {
    "taiwanstat": {
      "email": "test@gmail.com",
      "nickname": "taiwanstat"
    },
    "chilijung": {
      "email": "chilijung@test.com",
      "nickname": "chilijung"
    }
  }
},

helpers and partials

Setting up helpers and partials in hbs, see canner helpers and canner partials

TODO

• init blog, append posts
• create new tags, authors, categories in cli

License

MIT