Chris Martin

Web Technology, IT Infrastructure, and Other Puzzles

Getting Started with the Hexo Blogging Framework

New to blogging with the Hexo framework? This tutorial will walk you through installing Hexo, running a local server, and creating your first blog post.

Installing the Hexo CLI


You'll need Node.js and Git installed as pre-requisites.

Install the Hexo command line interface (CLI) globally with the Node.js package manager (NPM):

$ npm install -g hexo-cli

...once installed, use the hexo init command to create a new blog project:

$ hexo init my-blog && cd my-blog

This step can take a few minutes while it creates an initial file structure for your site and downloads other Node.js dependencies.

Starting the server

To view your newly created site in a browser, start the local server:

$ hexo server --draft --open

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

Didn't work?

Your current working directory must be in the my-blog project folder, or the server will not start.

This starts the server with a few extra options:

  • --draft : Enables viewable "draft" posts (by default, drafts are hidden)
  • --open : Open the local site in your browser

A browser should pop up and display the default blog site with a canned "Hello World" post.

You'll want to leave the server running in the terminal while authoring. The server process will watch for changes made to the Markdown source files and automatically generate new HTML files. The server's console log output is also helpful for troubleshooting errors that you may run across.

Heads up

Be aware that some actions require a restart of the server:

  • Editing the project's _config.yml
  • Installing or updating Hexo plugins with npm
  • Making changes to local plugins within the scripts folder(s)

Since most of the authoring time is spent within the Markdown files, a hard restart isn't required too often.

Creating your first post

A good practice when starting new posts is to use the "draft" feature. Drafts will not be published by default, so you are free to make changes to other posts while keeping unfinished drafts hidden from public.

Create a new draft post with the hexo new draft command:

$ hexo new draft "My First Blog Post"
# creates -> ./source/_drafts/


Other templates besides "draft" can be used when using the hexo new command. Look under the ./scaffolds/ folder and read the Hexo documentation on Scaffolds for more information.

To edit your draft, navigate to ./source/_drafts/ and open the file with your favorite Markdown editor.

Lets add a subheading and some paragraph content to your new post...

title: My First Blog Post
## Hello there
This is some content.


The stuff between the dashes --- at the top of the markdown file is called "front-matter". It is metadata that is used by Hexo and the active theme. See the Hexo documentation on Front-Matter for more information.


Ensure that your Markdown content for the page sits BELOW the front-matter dashes --- or the content will not display (and you'll likely see a YAMLException error in the server output).

Saving changes to your Markdown files will be automatically detected by the running hexo server and regenerated as static HTML files, but you must refresh the browser to view the changes.

Your post should look something like this in the browser:

Screenshot of First Blog Post

If you dislike having to manually refresh the browser each time, the hexo-livereload or hexo-browsersync plugins can do it automatically.

To install the hexo-browsersync plugin (my personal favorite):

$ npm install hexo-browsersync --save
$ hexo server --draft --open  # restart the server


Other Hexo plugins can be easily installed in this same way, using npm.

Many plugins will have configuration that can be tweaked from within the project's _config.yml file. You'll need to consult each plugin's documentation for their specific configuration properties.

In the case of hexo-browsersync, the defaults work fine and don't require editing the _config.yml file.

Displaying summary excerpts in listings

Say you have a lenghty post and don't like the fact that the entire article is displayed in the listing pages...

You can mark a spot in your markdown with <!-- more --> to hide it from the listing pages. It will be replaced with a "Read more" link that will open the rest of the article content.

title: My First Blog Post
This is a summary of the post.
<!-- more -->
## Hello there
This is some content.

Inserting images

Images and other asset files can be placed in subdirectories under the ./source/ folder. Use this picture of the original A-Team from Wikipedia as a test. Download it and save it to this path:


Edit your original post, inserting a markdown image link with a reference to /images/Ateam.jpg:

title: My First Blog Post
## Hello there
This is some content.

![I love it when a plan comes together.](/images/Ateam.jpg)

You should see something like this in the browser:

Screenshot of First Blog Post with image


Assets can also be organized in folders for each post. It requires enabling the post_asset_folder: true setting in _config.yml and some knowledge of its relative path referencing behavior. See the Hexo documentation on Asset Folders for more information.

Publishing drafts

When it's time to move the draft to a "live" post for the world to see, use the hexo publish command:

$ hexo publish My-First-Blog-Post

A few things will happen when this command is run:

  1. The markdown file moves from ./source/_drafts/ to ./source/_posts.
  2. The file's "front-matter" changes to include a publish date:

    title: My First Blog Post
    date: 2015-12-30 00:53:15  # <-

Finally, prepare the entire site for deployment. Run the hexo generate command:

$ hexo generate
# generates -> ./public/

Everything that is required to run the website will be placed inside the ./public folder. You are all set to take this folder and transfer it to your public webserver or CDN.

Next steps

Now that you've seen the general workflow, explore some other ways of enhancing your site:

Getting help

If you ever get lost on the command-line, simply type hexo for a list of the available commands:

$ hexo
Usage: hexo <command>

  clean     Removed generated files and cache.
  config    Get or set configurations.
  deploy    Deploy your website.
  generate  Generate static files.
  help      Get help on a command.
  init      Create a new Hexo folder.
  list      List the information of the site
  migrate   Migrate your site from other system to Hexo.
  new       Create a new post.
  publish   Moves a draft post from _drafts to _posts folder.
  render    Render files with renderer plugins.
  server    Start the server.
  version   Display version information.

And to see the options for a particular command, use hexo help {command}:

$ hexo help new
$ hexo help server

If you found this article useful, I'd love to hear it. Send me a tweet @c_g_martin.