Skip to content
Get packs

Guide · Open source

How to use Hexo: install, write posts and deploy a static blog

Updated · written with AI from the project's own documentation and checked against our catalogue data

Hexo is an open-source blog framework built on Node.js. You write posts in Markdown, and Hexo generates a folder of plain static HTML files that you can host almost anywhere. This guide walks through installing Hexo, setting up a blog, creating a post, previewing it locally and generating the static files, so you can publish your first site.

Hexohexojs/hexo · ★ 41.8k · MIT

Quick start

  1. 1Install Node.js. Hexo needs Node.js installed on your computer before you can use its tools.
  2. 2Install the Hexo CLI. Run npm install hexo-cli -g, or use brew install hexo on macOS and Linux.
  3. 3Create a blog. Run hexo init blog, then cd blog to enter the folder.
  4. 4Preview locally. Run hexo server and open the local address in your browser to see your blog.
  5. 5Write a post. Run hexo new "Hello Hexo" to create a post, then edit it as Markdown.
  6. 6Generate static files. Run hexo generate to build the static HTML files for your blog.

Install Hexo with Node.js and the Hexo CLI

Hexo requires Node.js. Once Node.js is available, install the Hexo command-line tool globally with npm. The README gives this command for the Hexo CLI.

On macOS and Linux, the README also shows an option to install Hexo with Homebrew.

  • Prerequisite: Node.js
  • Install the CLI globally with npm
  • Alternative on macOS and Linux: Homebrew
$ npm install hexo-cli -g $ brew install hexo

Set up a new blog folder

The hexo init command creates a new blog in a folder. Then move into that folder so the remaining commands run inside your blog.

$ hexo init blog $ cd blog

Start the local server to preview your blog

Run hexo server to start a local server. Use it to preview your blog in a browser while you write and edit. The README lists this command under starting the server.

$ hexo server

Create and write a new post in Markdown

The hexo new command creates a new post. The README example uses a post titled Hello Hexo. Posts are written in Markdown, and Hexo supports GitHub Flavored Markdown.

Because Hexo uses Markdown, you can write posts in any plain text editor.

  • Hexo supports GitHub Flavored Markdown
  • Most Octopress plugins are supported, according to the README
$ hexo new "Hello Hexo"

Generate static files for hosting

The hexo generate command builds your blog into static files. Hexo generates plain static HTML, so you can host the output on many kinds of hosts.

The README notes one-command deploy to GitHub Pages, Heroku and similar hosts. Check the Hexo documentation for deploy setup details.

  • Output is plain static HTML
  • Deploy options include GitHub Pages and Heroku, per the README
$ hexo generate

Find themes, plugins and help

Hexo has themes and plugins for customization. The README links to a theme list and a plugin list on the Hexo website. For problems, the README points to the troubleshooting page in the documentation and to community chat channels.

  • Theme list and plugin list on hexo.io
  • Troubleshooting page in the Hexo documentation
  • Community: Google Group, Discord, Gitter, Telegram

What people use it for

  • A personal blog written in Markdown and hosted as static files
  • A developer blog deployed to GitHub Pages
  • A documentation or writing site that needs a fast, plain HTML output
  • A blog extended with community themes and plugins from the Hexo lists

Frequently asked questions

Is Hexo free and open source?

Yes. Hexo is licensed under the MIT license, according to the project listing. You can use, modify and share it under those terms.

What do I need to install Hexo?

Hexo requires Node.js. You install the Hexo CLI with npm install hexo-cli -g, or with Homebrew on macOS and Linux.

Do I need to know how to code to use Hexo?

Hexo is aimed at people comfortable with Node.js and the command line. Setup uses commands such as npm and hexo server, so non-technical users may find it hard to start.

Where do I host a Hexo blog?

Hexo generates static files, so you can host them almost anywhere. The README mentions one-command deploy to GitHub Pages and Heroku, among others.

Can Hexo run dynamic server-side features?

No. Hexo generates static files, so it is not suited to sites that need dynamic server-side features.

How is Hexo different from Jekyll, Hugo, Eleventy or Gatsby?

Jekyll, Hugo, Eleventy and Gatsby are comparable static site projects. This source does not compare them in detail, so check each project's documentation to choose between them.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Hexo suits bloggers and developers who are comfortable with Node.js and the terminal and want a fast static blog they fully control. If you want a no-code, hosted blogging service, or you are uncomfortable with commands like npm and hexo server, pick a hosted platform instead.

Install options & downloads