Part 2 of my Hexo Bootstrap Series: how to install Hexo and core configuration
In this post, we’ll install everything needed to create a new Hexo blog:
- Install node.js and git
- Install the core Hexo commands
- Create a Hexo blog instance
- Install a theme
- Install some plugins
- Set your configuration
- Make small changes to the theme layout
For all posts in the series, check the Hexo-Bootstrap-Series tag.
I grabbed the most current version of Git for Windows at the time (2.6.4).
Then spent half and hour trying to make sense of Node.js’s new semantic versioning (apparently, they adopted IoJS’s versions), before downloading the most current 4.x LTS series for Windows (4.2.4).
Finally, install hexo itself via an admin command prompt
npm install -g hexo-cli.
(Note that you don’t need to install these on your server, just your own computer).
Create a new folder somewhere and open a command prompt there (admin not required any more).
hexo init and an
npm install you’ll get a bare bones Hexo instance.
If you do a
hexo generate at this point, you’ll get a bunch of HTML files in a
And Hexo’s basic web server is now a separate plugin.
In your Hexo folder, run
npm install hexo-server --save to install the web server component.
hexo server --debug, and you’ll see a bunch of debug spew come up as it processes your files.
You can now browse to
http://localhost:4000 to load the default site.
At this point, it is easy to be seduced by diving into the configuration and installing heaps of plugins (as I was).
But you really want to choose a theme first. Really.
Check out the Hexo Theme List.
There are some simple themes, and much more complex and fleshed out themes available on the official theme list. I’m sure there are more available somewhere else, but I didn’t look.
I chose Hueman as my theme, because:
- It looked decent.
- It had a responsive / mobile layout.
- The author has good documentation.
- The author updates the theme regularly.
Installation is quite easy.
Clone the git repository to download files required, then update
_config.yml to select the correct theme.
And I added a chunk of config options as listed on the Hueman documentation page to my
Since I started my site, it seems the theme author has added a
_config.yml.example which you can copy instead.
Restart your Hexo server and you should see your new theme.
OK, now you can go crazy with plugins!
Hexo’s plugins all use NodeJS’s
npm package manager.
So installation is as easy as
npm install hexo-some-plugin --save.
In addition to the defaults, I added some pretty core plugins, plus some nice to haves:
hexo-server- for testing on a local server (alread installed above)
hexo-generator-alias- for redirects
hexo-generator-feed- for an rss feed
hexo-generator-sitemap- to generate a sitemap.xml file
hexo-toc- to allow for a table of contents on a post
After you add each plugin, you should check if it has any configuration and add it to your
Remember to comment the config for each plugin (I added web links).
At this point, you should have all the possible options in your
So, keep the Hexo documentation handy (along with any plugin or theme doco) and start tweaking!
When editing your config, remember that the built-in server does not seem to notice changes to it. It will regenerate content, but not when you update the config file. So you’ll need to restart the server pretty often.
The lesson I learned here was that the defaults are pretty good.
I thought the
relative_link options should be switched on, but turned out it was better to leave them off.
You’ll want to spent a bit of time thinking about your permalink format.
It is rather permanent, afterall.
Some variation on a date based structure will scale nicely.
I went with
Some other things to note:
skip_render- You’ll need to add your Google Site auth file here, or it will be processed as any other html content (not what you want) (Bing’s XML auth file is not processed though, so you don’t need to add it).
marked.breaks- I prefer my Markdown not to insert line breaks unless I leave a blank line (makes version control work better). So I set this to false.
highlight.line_number- I’m not a fan of line numbers against source code. So I changed this to false.
Finally, there were a few things I wanted to change in the theme code. Obviously, this is specific to the hueman theme, but I’m sure you’ll find similar small things for whichever theme you chose too.
These changes are definitely not for someone who just wants to churn out content. So no shame in ignoring this whole section.
But as a professional web developer, they’re well within my capability.
From easiest to hardest, here are the three changes I made.
Unfortunately, you need to choose a license for any publicly released content.
So I added a Creative Commons license link in
hueman/layout/_partial/footer.ejs file, which will appear at the bottom of all pages.
There’s also some copyright and license information on the about page.
I prefer “© 1812 - 3812 Bloggs“ rather than “© 3812 Bloggs“. As it gives the reader an idea of how long the site has been running for.
So I added a config variable called
start_year, which is the year this blog started (2016).
And tweaked the display of the copyright year in
Now I get “© 2016“ in 2016, and “© 2016 - 2017“ in 2017.
Hueman assumes the site logo is an image. That’s fine, except when you don’t have an image or want an image.
My main performance constraint when self-hosting is my network connection. A very ordinary residential ADSL connection. With less than 1 Mbps upstream capacity. Every byte I need to serve really hurts me. And one more image, one more HTTP connection, and a few more kB do make a difference.
So no logo.
In my config, I removed all the logo stuff, and added a flag to turn a text based logo on:
Add a style for the text based logo in
#header-title .logo-text line-height: logo-height + 10 color: color-nav-foreground text-shadow: 0 1px rgba(0, 0, 0, 0.2) font-size: 40px a.logo-text color: color-nav-foreground text-decoration: none ... #footer .logo-text line-height: logo-height + 10 color: color-nav-foreground text-shadow: 0 1px rgba(0, 0, 0, 0.2) font-size: 32px a.logo-text color: color-nav-foreground text-decoration: none
footer.ejs, choose the style as approparite.
<h1 class="logo-wrap"> <a href="<%- url_for() %>" class="<%= theme.logo.use_text_logo ? "logo-text" : "logo" %>"><%= theme.logo.use_text_logo ? theme.title : "" %></a> </h1>
And I’m free of any images for my logo! (And my ADSL connection can rest easy).
As with all things in IT, if you want to do it properly, starting a Hexo blog is a bit more work that you’d think at first. But not too much. And if you don’t care about little tweaks like logos and copyright, then the complicated bits are not relevent.
Now, you should have a Hexo blog up and running on your local computer. It should look nice and just how you’d like it.
Next time: hosting it on an IIS server so the rest of the world can see it.