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

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 http://0.0.0.0:4000/. Press Ctrl+C to stop.

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.

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/My-First-Blog-Post.md

To edit your draft, navigate to ./source/_drafts/My-First-Blog-Post.md 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
tags:
---
## Hello there
This is some content.

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:

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

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
tags:
---
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:

./source/images/Ateam.jpg

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

---
title: My First Blog Post
tags:
---
## 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:

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 My-First-Blog-Post.md 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  # <-
   tags:
   ---
   ...
   

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:

• Commit your changes with Git so that you can always revert back to a good state if things go wrong. Read jr0cket's guide for Managing your Hexo website with Git and Github.
• Customize your blog with various configuration settings inside the _config.yml file.
• Automate your deployment to GitHub Pages, Heroku, Amazon S3, and other providers via the hexo deploy command.
• Enhance the style and functionality of your articles with built-in tag plugins.
• Browse the growing catalog of community Hexo plugins.
• Reconfigure the default Hexo "landscape" theme, try out some of the other free themes that are available, or create your own.
• Migrate your old posts from another blog system (Wordpress, Jekyll, Octopress, etc.) to Hexo.

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>

Commands:
  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.