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.
There are two main configuration files using by Hexo and both called
- The first one is under site root directory, which contains Hexo's config.
- 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.
available settings will be inside code blocks (with single backtick or
default settings will be bold inside code blocks (with single backtick or
All recommended settings will be highlighted under the success label.
All deprecated settings will be highlighted under the warning label.
And all possible errors will be highlighted under the danger label.
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:
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 latest master branch of NexT theme:
$ cd hexo
- Go to NexT version Release Page.
- Choose the version you need and download the Source Code (zip) in the Download section. For example v6.0.0.
- Extract the zip file to site's themes directory and rename the extracted folder (
You also can 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 v6.
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).
Now you have installed NexT theme, next we will verify whether it is enabled correctly. Between changing the theme and verifying it, we'd better use
hexo clean to clean Hexo's cache.
First start Hexo local server, and enable 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.
Now you've installed and enabled NexT. In next steps we will change some settings including personalization and third-party services integration.
There are 2 variants to hook up NexT plugins:
- Local installation (plugins scripts will be loaded from your site).
- CDN links (plugins scripts will be loaded from remote CDN hosts).
If your site is deployed to any free hosting service (Github, Gitlab, etc.), CDN links is recommended. CDN usually have faster speeds and no traffic restrictions.
In NexT config now you can find dependencies on each module which was moved to external repositories which can be found by main organization link. For example, you want to use
pjax in your site. Go to theme config file and see:
# Easily enable fast Ajax navigation on your website.
Then turn on
pjax and go to «Dependencies» link with installation instructions of this module.
If you use cdn for any plugins, you need to replace your cdn link. For example, you want to use
mediumzoom and you configured a cdn link. Go to theme config file and see:
And jsDelivr CDN is recommended to deliver our third-party plugins because it is fast in everywhere and has the valid ICP license issued by the Chinese government. It does not only crawl the js files from npm packages, and it crawls from the GitHub Releases! We could use the following link to reference the js files, just as other CDNs.
And it could automatically minify the JS and CSS files, even if you don't have the minified version. Just use the
filename.min.js or the
filename.min.css to replace the file above.
And we also provide other optional CDNs, including the famous CDNJS.
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.
You can enable Dark Mode by editing theme config file, searching
darkmode keyword. Theme NexT automatically shows Dark Mode if the OS prefered theme is dark. CSS
mix-blend-mode is used the to bring Dark Mode to all 4 schemes above, make sure your browser supports this property.
Edit site config file, set the value of
language to the language you need. For example, English looks like this:
NexT now supports following languages:
|Chinese (Hong Kong)||繁體中文-香港||
|Portuguese (Brazilian)||Português (Brazilian)||
If you would like to customize the default translation, you do not need to modify the translation files in the
languages directory. You can override all translations using Data files.
The files in the
language directory are automatically generated, you do not need to modify them directly. Please submit translations via Crowdin if you would like to add or improve translation for NexT theme.
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
next.yml configuration file.
To customize menu items, edit the following content in theme config file:
archives, all custom pages under
menu section need to be created manually. See «Custom Page Support»
Dynamic sub-menu within hierarchy structure is also supported. Add your sub-menu items in
menu section in theme config file as following:
If your site runs in a sub-directory, please remove the prefix
/ from the link.
By default NexT shows the icons of menu items without badges.
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.
favicon under site's
source dir. If you find that your Favicon doesn't work, please clean your browser's cache first and then visit your Favicon's URL directly, which should be
If your site is in a subdirectory please set it to
By default NexT doesn't show avatar in sidebar. You can configure it by editing values under
avatar setting in theme config file.
For first test you can uncomment
/images/avatar.gif value near the
avatar.url setting to see default avatar:
Then you need to specify your own avatar. It can be done one of the ways below:
Put your avatar under site directory
source/uploads/ (create directory if it doesn't exists).
And then change option to
Put your avatar under theme directory
And then change option to
Current site uses avatar under theme directory from file located in
next/source/images/apple-touch-icon-next.png with following config:
You also can specify any external URL with absolute path to image:
Set up rounded of avatar by changing the value of
true→ Avatar will be rounded.
false→ Avatar will be squared.
Set up rotated of avatar by changing the value of
true→ Avatar will be rotate under the mouse hovering.
false→ Avatar will not rotate under the mouse hovering.
Edit site config file and set the value of
author to your nickname.
Edit site config file and set the value of
description to your description, which can be a sentence you like.
After that we can configure deployment.