快速入门

Hexo是一个快速而强大的静态博客生成框架,它基于Node.js。通过使用Hexo,您可以使用Markdown轻松编写文章,除了Markdown的语法外,您还可以使用Hexo提供的tag plugins来简单的插入特殊格式的内容。在此页面中,我们假设您已经安装了Hexo并使用它创建了一个站点。

您可以访问Hexo Docs了解如何安装Hexo。

Documentation Variables

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.

All available settings will be inside code blocks (with single backtick or <code> tags).

And all default settings will be bold inside code blocks (with single backtick or <code> and ** or <strong> tags).

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.

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

1
2
$ cd hexo
$ git clone https://github.com/theme-next/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 v6.0.0.
  3. Extract the zip file to site’s themes directory and rename the extracted folder (hexo-theme-next-6.0.0) to next.

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

If you still use NexT version 5, you can read instructions for update from v5 to v6.

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).

hexo/_config.yml
1
theme: next

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.

Checking NexT

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://0.0.0.0: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

Now you’ve installed and enabled NexT. In next steps we will change some settings including personalization and third-party services integration.

Adding Plugins

There are 2 variants to hook up NexT plugins:

  • Local installation (plugins scripts will loaded from your site).
  • CDN links (plugins scripts will loaded from remote hosts).

If your site hosted on VPS (or any other) with NGINX configuration, recommended to use local installation.
And if your files deployed to any free hosting service (Github, Gitlab, etc.), recommended to use CDN links.

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:

next/_config.yml
1
2
3
# Easily enable fast Ajax navigation on your website.
# Dependencies: https://github.com/theme-next/theme-next-pjax
pjax: false

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:

next/_config.yml
1
2
3
4
5
vendors:
# ...
# Some contents...
# ...
mediumzoom: # Set or update mediumzoom CDN URL.

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.

1
//cdn.jsdelivr.net/gh/user/repo@version/file

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 and the Bootcss which has the quite high access speed in China.

NexT Configuration

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.

next/_config.yml
1
2
3
4
#scheme: Muse
#scheme: Mist
#scheme: Pisces
scheme: Gemini

Choosing Language

Edit site config file, set the value of language to the language you need. For example, English looks like this:

hexo/_config.yml
1
language: en

NexT now supports following languages:

Language Example Code
🇨🇳 Chinese (Simplified) 简体中文 zh-CN
🇹🇼 Chinese (Traditional) 繁體中文 zh-TW
🇭🇰 Chinese (Hong Kong) 繁體中文-香港 zh-HK
🇧🇶 Dutch Niederländisch nl
🇺🇸 English English en
🇹🇫 French Français fr
🇩🇪 German Deutsch de
🇮🇩 Indonesian Indonesia id
🇮🇹 Italian Italiano it
🇯🇵 Japanese 日本語 ja
🇰🇷 Korean 한국어 ko
🇮🇷 Persian فارسی fa
🇵🇹 Portuguese Português pt
🇧🇷 Portuguese (Brazilian) Português (Brazilian) pt-BR
🇷🇺 Russian Русский ru
🇪🇸 Spanish Español es
🇹🇷 Turkish Türk tr
🇺🇦 Ukrainian Український uk
🇻🇳 Vietnamese Tiếng Việt vi

If you want to add or improve language for NexT theme, you can do it easily with crowdin service.

Configuring Menu Items

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

By default NexT provides home and archives items. To customize menu items, edit the following content in theme config file:

All custom pages which commented by default under menu section need to create manually. See «Custom Page Support»

next/_config.yml
1
2
3
4
5
6
7
8
9
menu:
home: / || home
#about: /about/ || user
#tags: /tags/ || tags
#categories: /categories/ || th
archives: /archives/ || archive
#schedule: /schedule/ || calendar
#sitemap: /sitemap.xml || sitemap
#commonweal: /404/ || heartbeat

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

next/_config.yml
1
2
3
4
5
6
7
8
menu:
home: / || home
archives: /archives/ || archive
Docs:
default: /docs/ || book
Third Party Services:
default: /third-party-services/ || plug
Algolia Search: /algolia-search/ || adn

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.

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.

hexo/_config.yml
1
2
3
4
5
6
7
favicon:
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

Configuring Avatar

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:

next/_config.yml
1
2
avatar:
url: /images/avatar.gif

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 avatar: /uploads/avatar.png.

Put your avatar under theme directory source/images/.
And then change option to avatar: /images/avatar.png.

Current site uses avatar under theme directory from file located in next/source/images/apple-touch-icon-next.png with following config:

hexo/_config.yml
1
2
3
4
5
theme_config:
avatar:
url: /images/apple-touch-icon-next.png
rounded: true
rotated: false

You also can specify any external URL with absolute path to image: http(s)://example.com/avatar.png

Set up rounded of avatar by changing the value of avatar.rounded:

  • true → Avatar will be rounded.
  • false → Avatar will be squared.
next/_config.yml
1
2
avatar:
rounded: true

Set up rotated of avatar by changing the value of avatar.rotated:

  • true → Avatar will be rotate under the mouse hovering.
  • false → Avatar will not rotate under the mouse hovering.
next/_config.yml
1
2
avatar:
rotated: true

Configuring Author

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

hexo/_config.yml
1
2
# Site
author:

Configuring Description

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

hexo/_config.yml
1
2
# Site
description:

After that we can configure deployment.