Fl0w3r

carpe diem

Getting Started

NexT User Docs – Starting to Use

Hexo Installation

If this is your first time using Hexo, you can take some time to review the Hexo Docs to see how to install Hexo and initialize a site. After the installation is successful, you should be able to execute hexo (or npx hexo) on the command line, and there must be package.json, source, themes and other directories in your site root directory:

$ cd hexo-site
$ ls
_config.yml  node_modules  package-lock.json  package.json  scaffolds  source  themes

If you are new to Node.js or Hexo, you can also modify the source code of an existing Hexo website instead of creating a new one, to help you understand how Hexo works. In fact, the document you are reading is generated by Hexo with NexT, and you can install it with the following command:

$ git clone https://github.com/next-theme/theme-next-docs
$ cd theme-next-docs
$ npm install

Make sure that you have installed Hexo and created a site with it successfully, because the following documents require you to operate in the site root directory.

NexT Installation

The detailed steps to install or upgrade the theme are as follows.

Downloading NexT

It’s easy to install Hexo theme: you can choose to install the theme through npm, or download the source code of the theme in the themes directory under site root directory.

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

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

Upgrading NexT

A new version of NexT will be released every month. Please read the release notes before updating the theme. You can update NexT by the following command.

Install the latest version throuth npm:

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

Or update to the latest master branch:

$ cd hexo-site
$ cd themes/next
$ git pull origin master

When running git pull, you can bypass merge conflicts (error message like «Commit your changes or stash them before you can merge») by using the Commit, Stash or Reset commands for local changes. See here how to do it.

If you are still using NexT version 5 or 7, you can read instructions for upgrading from legacy version.

Configuration Files

After the installation of Hexo and NexT, you may found that there are two 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 (e.g. thems/next/_config.yml or node_modules/hexo-theme-next/_config.yml), which is provided by NexT and contains theme’s config.

Let’s call the first one – Hexo config file, and the second one – NexT config file.

However, we do not recommend directly modifying the NexT 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 the theme installed through npm, it is also difficult to modify the NexT config file in node_modules.

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

Hexo Configuration

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

Configuring Author

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

Hexo config file
# Site
author:

Configuring Description

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

Hexo config file
# Site
description:

Enabling NexT

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

Hexo config file
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

After that we can configure deployment.

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