Blogging for Developers

The Road So Far

I’ve tried several times to setup a blog , but found that the existing web-based solutions just never felt quite right.
With the list of static site generators growing rapidly I thought it would be fun to try and approach the same problem
again with the tooling that I, as a developer, am comfortable with.

Finally with Hexo I think I may just have the setup I want.

The Approach

My setup is fairly straight forward:

  • Hexo for generating my blog.
  • IntelliJ IDEA, the best IDE around.
  • The markdown plugin for IntelliJ.
  • Github for source control.
  • GruntJS for automating building and deploying. Note that this may not be necessary, but it’s highly recommended for automating.

IntelliJ Benefits

  • Syntax highlighting with the Markdown plugin.
  • Builtin terminal and GruntJS task runner.
  • Git support.
  • Some spellchecking.
  • Awesome local history just in case.

Setup

Download and install:

Install Global NPM Packages

npm install hexo grunt-cli -g

Create Blog

hexo init <BlogName>
cd <BlogName>
npm install
npm install grunt time-grunt grunt-shell --save-dev

That should set up your blog, to test it out quick you can run hexo server and browse to http://localhost:4000
to check it out.

Blog Config

I would strongly recommend you work through the config instructions on the Hexo site. However if you’re the gung-ho type
you can make your changes in the _config.yml file at the root of the blog.

Note you will need to kill the server if you tested the blog in the previous section (Ctrl + C) and restart it for the config changes to take affect.

Comments (Disqus)

Just a quick note on comments on your posts. If you would like to have comments added into your blog posts Hexo supports the awesome
Disqus product to give you a powerful set of tools for metrics and moderating of the comments on your blog.

To make use of this simply ensure you’ve configured your Disqus shortname in the _config.yml file.

Grunt Setup

Create Gruntfile.js in the root of your project. This will be where we will define our build tasks that will wrap some smaller
tasks into higher level run and deploy tasks.

Our Gruntfile.js will contain:

Gruntfile.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
module.exports = function (grunt) {
	require('time-grunt')(grunt);
	// Project configuration.
	grunt.initConfig(
		{
			pkg: grunt.file.readJSON('package.json'),
			shell: { // Hexo has it's own cli that we invoke for our simple process.
				clean: {
					command: 'hexo clean'
				},
				generate: {
					command: 'hexo generate --deploy'
				},
				server: {
					command: 'hexo server'
				}
			}
		});
	grunt.loadNpmTasks('grunt-shell');
	grunt.registerTask('run', ['shell:clean', 'shell:server']);
	grunt.registerTask('deploy', ['shell:clean', 'shell:generate']);
	// Default task.
	grunt.registerTask('default', ['run']);
};

Deploying

Make sure you read the Hexo docs on configuring deployments and in particular the docs
batch deployments. I would highly recommend that you configure both your
site deployment details as well as your Git details so that both are kept in sync by our buildscripts.

Running The Script

If you’re using IntelliJ then you can just run the tasks from the Grunt runner that’s built in. However if you are not you can just as
easily run grunt, grunt run or grunt deploy from your terminal in the blog folder.

Adding Content

Hexo has the concept of “scaffolds” which are analogous to templates or layouts for creating new documents for your site.

I would recommend reading the Writing section of the hexo docs to get a better understanding of
what options are available to you aside from posts.

Our First Post

To create your first post you need only run hexo new post "My New Post".

This will create an empty post:

My-New-Post.md
1
2
3
4
title: My New Post
date: 2014-12-18 00:42:37
tags:
---

At this point you can start editing your first post preview it with grunt run.

Note that the syntax for listing categories and tags in the header is as follows:

1
2
3
4
5
6
7
...
categories:
- Blogging
tags:
- intellij
- markdown
...

Icing

Theming

Now that all the heavy lifting has been done I would highly recommend that you take a look at one of the many awesome
themes available for Hexo.

Even better customize an existing theme and share it with the community.

Writing Good

If you’re not sure of your ability to wield the English language like the pointy stick that it is there are some interesting tools
that try to help you out.

Spellchecking is quick and simple with the grunt-spell plugin and it can easily integrate into our
existing grunt scripts and workflow.

For sentence structure you could look at installing write-good. A Nodejs project that tries to naively lint
english prose. There is no cost involved other than the time to get it setup and it can be added into our Grunt scripts using the shell task as we did
for the Hexo commands.

Another option is an editor like Hemmingway the web version is free to use. There is also a
desktop version which will cost you some cash and appears to have the same functionality as the web version.