Getting Started

Hexo is a fast and powerful static blog generating framework, it's based on Node.js. By using Hexo you can write articles easily with Markdown, and besides the grammer of Markdown, you can also use tag plugins provided by Hexo to insert special formated content simply. In this page we assume you have installed Hexo and created a site with it.

You can visit Hexo Docs to see how to install Hexo. Make sure that the version of Node.js and Hexo in the environment is higher than the minimum requirements of the NexT theme, and then continue with the following steps.


There are two main configuration files using by Hexo and both called _config.yml:

  1. The first one is under site root directory, which contains Hexo's config.
  2. The second one is under theme root directory, which is provided by NexT and contains theme's config.

Let's call the first one – site config file, and the second one – theme config file.
However, we do not recommend directly modifying the theme config file. It is quite often running into conflict status when updating NexT theme via git pull, or need to merge configurations manually when upgrading to new releases. For Hexo 5.0 or later, the theme can be installed through npm and it is also difficult to modify the theme config file in node_modules.

In order to resolve this issue, we recommend using the Alternate Theme Config feature to configure theme NexT.

NexT Installation

It's easy to install Hexo theme: you can just download the NexT theme, copy the theme folder to the themes directory under site root directory and specify in site config file your theme root directory. The detailed steps are as follows:

Downloading NexT

If you're using Hexo 5.0 or later, the simplest way to install is through npm.

Open your Terminal, change to Hexo site root directory and install NexT theme:

$ cd hexo-site
$ npm install hexo-theme-next

If you know about Git, you can clone the whole repository and update it in any time with git pull command instead of downloading archive manually.

Open your terminal, change to Hexo site root directory and clone the latest master branch of NexT theme:

$ cd hexo-site
$ git clone https://github.com/next-theme/hexo-theme-next themes/next
  1. Go to NexT version Release Page.
  2. Choose the version you need and download the Source Code (zip) in the Download section. For example v8.0.0-rc.3.
  3. Extract the zip file to site's themes directory and rename the extracted folder (hexo-theme-next-8.0.0-rc.3) to next.

You can also read detailed installation instructions if you want any other installation variant.

If you are still using NexT version 5, you can read instructions for update from v5 to v8.

Enabling NexT

Like all Hexo themes, after you download it, open site config file, find theme section, and change its value to next (or another theme directory name).

theme: next

Now you have installed NexT theme and enabled it. The following steps will help you verify whether NexT is enabled correctly.

Checking NexT

It's recommended to use hexo clean to clean Hexo's cache first.
Then start Hexo local server with debug parameter (by adding --debug), the whole command is hexo s --debug. You can see the output while running, and if you find problem, you can use the output to help others locate error better. When it prints:

INFO  Hexo is running at http://localhost:4000/. Press Ctrl+C to stop.

Now you can open http://localhost:4000 in your browser, and check whether the site works correctly.

If you find your site looks like this picture, you have installed it correctly. That's default NexT scheme – Muse.
Default Scheme – Muse

If everything is OK, in next steps we will change some settings including personalization and third-party services integration.

Hexo Configuration

The following settings in site config file are very helpful for optimizing your website.

Configuring Author

Edit site config file and set the value of author to your nickname.

# Site

Configuring Description

Edit site config file and set the value of description to your description, which can be a sentence you like.

# Site

After that we can configure deployment.

NexT Quick Start

Configuring Favicon

By default the Hexo site use NexT favicons in hexo-site/themes/next/source/images/ directory with different size for different device. You can replace them with your own favicons.

For example, you can put your favicons in hexo-site/source/images/ directory. Then you need to rename them and change the settings in favicon section in theme config file, otherwise icons from Next will rewrite your custom icons in Hexo.

You can also put custom favicons into hexo-site/source/ directory. In this way, you must remove /images prefix from paths.

To generate custom favicons, you can visit Favicon Generator.

small: /images/favicon-16x16-next.png
medium: /images/favicon-32x32-next.png
apple_touch_icon: /images/apple-touch-icon-next.png
safari_pinned_tab: /images/logo.svg
android_manifest: /images/manifest.json
ms_browserconfig: /images/browserconfig.xml

Creative Commons

NexT supports the display of Creative Commons 4.0 International License in sidebar and post including by, by-nc, by-nc-nd, by-nc-sa, by-nd, by-sa, zero. These licenses allow creators to communicate which rights they reserve, and which rights they waive for the benefit of recipients or other creators.

You can configure it by editing values in creative_commons section in theme config file, for example:

license: by-nc-sa
sidebar: true
post: true
language: deed.zh

Choosing Scheme

Scheme is a feature supported by NexT, by using Scheme NexT gives you different views. And nearly all config can be used by those Schemes. Till now NexT supports 4 schemes, and they are:

  • Muse → Default Scheme, this is the initial version of NexT. Uses black-white tone and mainly looks cleanly.
  • Mist → A tighter version of Muse with a tidy single-column view.
  • Pisces → Double-column Scheme, fresh like your neighbor's daughter.
  • Gemini → Looks like Pisces, but have distinct column blocks with shadow to appear more sensitive to view.

You can change Scheme by editing theme config file, searching scheme keyword. You'll see 4 lines of scheme settings and can enable one of them by removing it's # and added # to previous.

#scheme: Muse
#scheme: Mist
#scheme: Pisces
scheme: Gemini

Dark Mode

You can enable Dark Mode by setting darkmode to true in theme config file.

darkmode: true

The prefers-color-scheme CSS media feature is used to bring Dark Mode to all 4 schemes above, make sure your browser supports it.

Theme NexT automatically shows Dark Mode if the OS prefered theme is dark. It's supported by macOS Mojave, iOS 13 and Android 10 or later. Relevant docs:
How to use Dark Mode on your Mac
Use Dark Mode on your iPhone, iPad, or iPod touch
Dark theme | Android Developers

Configuring Menu Items

Menu settings items have format Key: /link/ || icon which contains 3 values:

By default, all menu items are commented out to ensure that you can override them in the Alternate Theme Config.
To customize menu items, edit the following content in theme config file:

home: / || fa fa-home
#about: /about/ || fa fa-user
#tags: /tags/ || fa fa-tags
#categories: /categories/ || fa fa-th
archives: /archives/ || fa fa-archive
#schedule: /schedule/ || fa fa-calendar
#sitemap: /sitemap.xml || fa fa-sitemap
#commonweal: /404/ || fa fa-heartbeat

Except home and archives, all custom pages under menu section need to be created manually. See «Custom Page Support».

Besides, hexo-generator-sitemap plugin is required for sitemap support.

Dynamic sub-menu within hierarchy structure is also supported. Add your sub-menu items in menu section in theme config file as following:

home: / || fa fa-home
archives: /archives/ || fa fa-archive
default: /docs/ || fa fa-book
Getting Started:
default: /getting-started/ || fa fa-flag
Installation: /installation.html || fa fa-download
Configuration: /configuration.html || fa fa-wrench
Third Party Services:
default: /third-party-services/ || fa fa-puzzle-piece
Math Equations: /math-equations.html || fa fa-square-root-alt
Comment Systems: /comments.html || far fa-comment

A default page is required for each sub-menu item.

By default NexT shows the icons of menu items without badges.