Building A Website With Hexo.io

In my last article, I wrote about my personal experiences getting MichaelArnel.com up and running. This article covers using a Static Site Generator (SSG) to build your very own website. Static Site Generators are tools that take content in one format, such as Markdown, and transforms that content into another format, usually HTML and lays out pages so that the look and feel is consistent across the entire site.

Why use a Static Site Generator?

There are many benefits to using SSG’s to build and maintain your site.

  • Sites built using SSGs are static html, js, and css files which means it can be hosted on any platform by any webserver of your choice.
  • Because the content is made up of flat text files, static sites are easy to version with source control tools like GIT.
  • There is no server side code executing or database interactivity so static sites are much more secure and generally free from exploits.
  • Static sites are extremely fast!!!

Once you’ve decided to use a SSG to build your website with, it’s time to choose a SSG to use. There are many tools out there for you to choose from. It’s important to choose one that’s built on a platform your comfortable developing on, for example javascript, ruby, php, etc. This is important because you want to be able to contribute to the project, or possibly fix bugs that might be impacting your site. For the purposes of this tutorial i’ve chosen to use Hexo.io which is built using JavaScript on Node.js Hexo is also the same SSG I’ve used to build MichaelArnel.com

This tutorial makes the assumption that you’re already familiar with NodeJS and already have it installed to your system. If you need to install NodeJS please head on over to the node.js homepage and follow the instructions there. Once complete continue back over here.

Hexo Quick Setup:

In order to install Hexo, you’ll need to open up the terminal or command line. We’re going to use Node Package Manager (NPM) to install the hexo package globally. Run the following command now:

1
npm install -g hexo-cli

Now that the hexo package is installed globally, use the terminal and navigate to the folder you want to create your website at. Let’s assume we wanted to build a blog, to get started we would run the command below to initialize a hexo website.

1
hexo init Blog

After this command is run, a skeleton project is stubbed out and a new project folder called “Blog” is created, containing the files generated by Hexo. Before we can fire up the server and see the site in action, we’ll have to run an npm command to install all the project dependencies. Switch to the new directory created by hexo and run the npm command below.

1
2
cd Blog
npm install

At this point all the dependencies should be installed and your new Blog website is ready for you to run and explore. Run the following command to start the webserver. After running the command you should see output by hexo letting you know that it’s running and how to stop it.

1
2
hexo server
>>Hexo is running at http://localhost:4000/. Press Ctrl+C to stop.

Your brand new Blog website is up and running now! Open up a web browser and navigate to http://localhost:4000. You should see something simular to the image below in your browser.

Pretty Cool! In less than 5 minutes you have a fully functional website up and running and all you’ve done is run a few commands from the command line. Let’s start adding some content so we can customize it. Before we being let’s take a look at the directory contents created by hexo. You should see something similar to the structure below.

1
2
3
4
5
6
7
8
├── _config.yml
├── package.json
├── scaffolds
├── scripts
├── source
| ├── _drafts
| └── _posts
└── themes

Basic Configurations

Inside the new project directory created, find and open the file _config.yml This file is the configuration that drives the static site that’s generated by hexo. It controls things about your site like title, author, url, paging settings and much much more. Let’s start with some simple changes and modify the site configuration region to reflect the blog we’re building.

1
2
3
4
5
6
7
8
9
10
11
12
# Site
title: My Cool New Blog
subtitle: Blogging cool stuff!
description:
author: <Your Name Here>
email: <Your Email Here>
language: English
# URL
## If your site is put in a subdirectory, set url as 'http://yoursite.com/child' and root as '/child/'
url: http://mycoolblog.com
root: /

For now this is all we’ll modify in the _config.yml, save the file and close it. To learn more about what the rest of settings in the _config.yml do, visit http://hexo.io/docs/ and explore the documentation. The changes you’ve made to the *_config.yml won’t take place until you stop and restart the hexo server. Use the command line and stop and restart the server now. Refresh the browser and take note of the changes. You should now see the blog title and subtitle displayed in the page header!

1
2
Press Ctrl+C to stop
hexo server

Writing Some Content

Writing content for your new blog is just as easy. The first thing we need to do is tell Hexo to provision a new article. This is done by going back to the command line and running the following command:

1
hexo new Post MyFirstEntry

Note: There are 3 different types of content stubs you can generate out of the box with hexo. The default is a Post, but you can also choose from Draft and Page documents as well.

Hexo now generates a new file inside the _posts directory under the source folder at the root of your project. Navigate to the _posts directory and you should now see a new file titled MyFirstEntry.md This is a special file type known as Markdown. Markdown is a simple to use text format for non-programming types to write in. That text is taken and then read in by a processor and converted to HTML. This makes it super easy to quickly write down your thoughts and include things such as tables, page headings, blockquotes and more without using a bit of HTML Markup. COOL!

Play around writing some content and save the file. If you didn’t stop the server (Ctrl+C) in the previous step, when we created the new post, do so now, then restart. We do this so that hexo can rebuild your site including the new content you’ve just added. Refresh the web browser and you should now see a new article linking to the content you just wrote. Notice all the other cool things hexo did for you while generating the site. It’s automatically set up links to the article based on any categories and or tags you’ve specified in the MyFirstEntry.md file. This is what makes your site static. Traditionally all of this processing would by done dynamically via server-side code at runtime.

*Note: After the file is generated by hexo and the server is restarted, any changes you make to your content files are automatically picked up by the running hexo server. This makes it easy to refresh and browser and quickly see the changes you’ve made while you work.

Generating Your Site for Deployment

This is just the tip of the iceburg of what you can do with Hexo, but for the moment you’re but just one small step from being able to publish your website so that the rest of the world can see your work. Stop the hexo server by going back to the command line and hitting Ctrl+C. Run the following commands to build out your website for deployment:

1
2
hexo clean
hexo generate

The first command (hexo clean) run’s cleanup by hexo on the files it generates internally to track the content that makes up your website. The second command (hexo generate) actually builds out the website and creates the files in a new folder called public in the root of your project folder. This folder contains everything you need to copy your website to a webserver so that it can be hosted on the internet. That’s all there is to it, dust off your hands and pat yourself on the back. You’ve now just built out your first website using Hexo, and in less than an hour!

What’s Next?

Time for you to go off and explore how you can use the rest of the Hexo tool to build your website. Check out the documentation for all the details you need to become a master of Hexo. You might also want to take a look at the custom themes available, that others have built and shared to give your site a different look and feel.

In Part 3 of this series we’ll explore how to manage your site using tools like GIT for source control, Grunt.js to automate certain aspects of the development of your site, and finally how to use Github to publish your source files and host your static site for free!

Prev: Hello World