Hexo Tutorial To Build A Static Website With Node JS

This is a Hexo tutorial to build a static website. Hexo is a Javascript static generator that uses Node.js to produce warp speed static websites.

My Coding Setup

* OSX El Capitan
* iTerm2
* Tmux with Vim

Is this Hexo tutorial for you?

* OSX: Yes
* Linux: Yes but some commands might be different
* Windows: No. Unless you install Cygwin.

What is Hexo?

Hexo is a Javascript static site generator.

It uses Node.js to build “hundreds of files in seconds”

Hexo Requirements

These are the requirements for installing Hexo:

* Node.js
* Git
* Command Line Tools (Xcode)

Installing Command Line Tools

If you don’t have Command Line Tools installed then:

* Install Xcode
* Open Xcode. Preferences. Download. Command Line Tools. Install

Installing Git


Installing Node.js

* Install nvm (node version manager)
* Use nvm to install Node.js

Install nvm

As shown on the Hexo documentation. This command DID NOT work for me:

$ curl https://raw.github.com/creationix/nvm/master/install.sh | sh


Instead, I use this command, following the [nvm documentation](https://github.com/creationix/nvm)

$ curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.30.2/install.sh | bash


Install Node.js

Use this command to install the latest LTS version. As of this writing (v4.2.6 LTS). Not the latest features (v5.5.0)

$ nvm install 4.2.6
$ nvm alias default 4.2.6


Keep in mind that you have to reopen your Terminal after installing nvm. Otherwise you will get a:

$ -bash: nvm: command not found

If you still get a command not found. You have to add this to your .bash_profile. As seen on [Stackoverflow – nvm command not found](http://stackoverflow.com/questions/16904658/node-version-manager-install-nvm-command-not-found)

[[ -s $HOME/.nvm/nvm.sh ]] && . $HOME/.nvm/nvm.sh # This loads NVM

Go to official documentation to learn more about nvm [Node Version Manager](https://github.com/creationix/nvm)

Install Hexo

npm is the [package manager for node.js](https://www.npmjs.com/).

Something I have experienced of the coding learning process is not to copy/paste commands without fully understanding what you are typing.

Run this command to install Hexo:

$ npm install -g hexo-cli


Learning more about the -g flag.

You cannot google npm install -g because Google’s operator - means without. So it will search npm install without -g

Instead search using double quotes "npm install -g".

This is the best answer to [“what does the -g flag do”](http://stackoverflow.com/questions/13167588/what-does-the-g-flag-do-in-the-command-npm-install-g-something).

It says that “-g tells npm to install the named module so that you can access it globally”.

The named module being hexo-cli.

“-g is typically used for packages that provide command line utilities so that their executable components are available in the system PATH”

In English. This means that hexo-cli is a command line utility. And in order to run this utility, the executable needs to be available somewhere where the computer can find it. In this case the system PATH.

When running commands on the command line. It is helpful to take screenshots of the output to understand what they do. Many times the output says what you are supposed to do next if you run into issues.

Create a Hexo Blog

Run the command:

$ hexo init code-blog

Open the directory and run install:

$ cd code-blog
$ npm install

Run the Hexo server

$ hexo server

Or also run it with:

$ hexo s

Output says:

INFO Hexo is running at Press Ctrl+C to stop.

When you run the server a popup asked if you wanted to allow connections.

Open the browser and type:


Hexo is running!


Review the Configuration file

Open the file _config.yml with your favorite text editor, Textmate, Sublime or Vim.

Go to #Site and edit the contents for:

* Title
* Subtitle
* Description
* Author

I like to keep my permalinks free of dates. Go to #URL:

permalink: :title/

Change the url to your custom domain.

### Configure the Asset Folder

Since I want to add images related to each post. I would like to keep files organized.

There are 2 ways of doing this:

* Create an images folder inside the source directory
* Inside the config.yml, edit post_asset_folder to true

With post_asset_folder you can [separate assets on a post-per-post basis](https://hexo.io/docs/asset-folders.html)

Inside the _config.yml set:

post_asset_folder: true

Now Hexo will create a folder for every new post. The asset folder will have the same name as the post.

Place images inside this folder and use relative paths to reference them.

### Referencing Images

The Hexo documentation says that using regular markdown to reference images will not work:

![Some image](some-image.jpg)

Instead you need to use plugin syntax for a plugin that was added to the Hexo core:

Such as:

Create Content

I want to keep things simple and organized.

I want to organize each post into only 1 category and use tags for subtopics.

### To create a new post use:

$ hexo new "Title Of The Post"

The post will be created inside this folder:


As shown on the Hexo documentation, [Hexo uses Front-matter](https://hexo.io/docs/front-matter.html) at the beginning of a post. For a YAML file, it looks like this:

title: Title Of The Post
date: 2016/02/08 23:45:00

### Add categories and tags like this:

title: Title Of The Post
date: 2016/02/08 23:45:00
- TheCategory
- SubTopic1
- SubTopic2

Create a Repository on Github

As shown on the [Github Pages tutorial](https://pages.github.com/)

* Go to Github
* Create a new repository
* Name it yourusername.github.io
* Set to Public or Private
* Don’t check “Initialize with a Readme”

Configure Github on Hexo

Open the configuration file _config.yml.

Scroll down to Deployment and edit:

* type: git
* repo: git@github.com:yourusername/yourusername.github.io.git
* branch: master

Generate Markdown to HTML

$ hexo generate

Deploy to Github Pages

First you need to install a Node package called hexo-deployer-git:

$ npm install hexo-deployer-git --save


Generate and then deploy

$ hexo generate
$ hexo deploy

Or with one command:

$ hexo generate --deploy

Custom Domain

Go to the source folder and create a CNAME file with your custom domain:

$ cd source
$ touch CNAME

Edit the CNAME file and add your domain

Go to your DNS and add a CNAME that points your (domain or subdomain) to yourusername.github.io

Adding a nice Theme

You can install Themes on Hexo. You could also build your own.

[Icarus Hexo Theme](https://github.com/ppoffice/hexo-theme-icarus) is clean, responsive and well designed.

### Install the Icarus Hexo theme:

$ git clone https://github.com/ppoffice/hexo-theme-icarus.git themes/icarus

As seen on the documentation, follow these steps:

* Rename themes/icarus/_config.yml.example to themes/icarus/_config.yml
* Go to your root folder and edit the _config.yml. Change theme: icarus

### Edit the Theme _config.yml file

Go to themes/icarus/_config.yml and edit the settings to your own.

Adding an RSS feed

Install [Hexo generator feed](https://github.com/hexojs/hexo-generator-feed):

$ npm install hexo-generator-feed --save

The output of this was:

fsevents@0.3.8 install /Users/.../code-blog/node_modules/hexo-generator-feed/node_modules/nunjucks/node_modules/chokidar/node_modules/fsevents
node-gyp rebuild

SOLINK_MODULE(target) Release/.node
CXX(target) Release/obj.target/fse/fsevents.o
SOLINK_MODULE(target) Release/fse.node
hexo-generator-feed@1.1.0 node_modules/hexo-generator-feed
nunjucks@1.3.4 (optimist@0.6.1, chokidar@0.12.6)

Go to the root _config.yml and add this:

type: atom
path: atom.xml
limit: 20

Go to the theme _config.yml and edit this:

rss: /atom.xml

Clean Up Before Deploying Again

$ hexo clean

The output of this was:

INFO Deleted database.
INFO Deleted public folder.

Now run:

$ rm -rf .deploy_git/
$ hexo generate --deploy

Please add your comments or questions

Leave a Reply