# Guide
# About this Guide
This guide is only for partial configuration instructions, Not for the all configs, For specific configuration requirements, please refer to the comments in the file _config.yml
at the path of the theme. For more help, Please write your questions at issues (opens new window).
TIP
About the config file in the guide:
- "blog config" refer to the
_config.yml
in the blog root directory. - "theme config" refer to the path
theme/fluid/_config.yml
# Global
# Override Configuration
TIP
Override configuration can avoid losing your customized configuration when updating Fluid.
Users who install Fluid via Npm can ignore it, other users are recommended to learn to use it.
If your Hexo version >= 5.0.0, create _config.fluid.yml
in the blog directory and copy the content of _config.yml (opens new window)
Notice:
- The configuration existing in
_config.fluid.yml
is of high priority, modifying_config.yml
is useless. - There may be configuration changes in the theme of upgrading, you need to manually modify
_config.fluid.yml
synchronously. - You can use
hexo g -- debug
to check override configuration. - If you want to cancel some configurations, you should do this:
about:
icons: # This is set to null, otherwise the configuration can't be override
# - { class: 'iconfont icon-github-fill', link: 'https://github.com' }
# - { class: 'iconfont icon-wechat-fill', qrcode: '/img/favicon.png' }
Hexo version < 5.0.0 click here
You should make sure that your version of Hexo is not lower than 3.0, because of the function about data-files (opens new window)
Usage:
- cd into the dictionary 'source' in your blog root dictionary, then
mkdir _data
(beside to the folder '_post'); - Create a file
fluid_config.yml
in the folder_date
, copy the configurations from theme config tofluid_config.yml
; - You can set any config with the file
fluid_config.yml
, it can be used when you starthexo g
.
# Static Assets
The Url of all static files can be customized through the static_prefix
item in theme config.
For example, custom the JQuery CDN library, you can set:
static_prefix:
# ...
jquery: https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/
# Local Search
The hexo-generator-search plug-in has been integrated, please close if you have installed other search plug-ins to avoid generating redundant index files.
By default,
local-search.xml
is generated and used in the root directory.
# Banner Image
- img src
there is banner_img
item for every pages in the theme config, you can use a relative path or url.
use a local image:
banner_img: /img/bg/example.jpg # stored at /source/img/bg/example.jpg
use a url:
banner_img: https://static.zkqiang.cn/example.jpg
TIP
You can define the ain path yourself, but it should be in the folder source
The source directory of blog and fluid will be merged eventually, so the source of blog is preferred.
- height
For different people's thoughts, you can control the height of the banner_img
on the page.
You can set a value to banner_img_height
for every pages in theme config, 0 - 100 is valuable, We think it is better to choose a number bigger than 70.
- alpha of mask
You can set a value banner_mask_alpha
for every pages in theme config, 0 - 1.0 is valuable, 0 is completely transparent (no mask), 1 is completely opaque
TIP
Each post page can define its banner independently, you can read the config about the posts for more details.
# Title of Blog
The title is on the left of the banner, Its value can set by the attribute title
in file blog config, which is also the title of the browser's tab.
If you want to set varies titles for different pages, you can change the theme config as follows:
navbar:
blog_title: your title
# Navbar
navbar:
menu:
- { key: 'home', link: '/', icon: 'iconfont icon-home-fill' }
- { key: 'tag', link: '/tags/', icon: 'iconfont icon-tags-fill' }
- { key: 'about', link: '/about/', icon: 'iconfont icon-user-fill', name: 'About Me' }
key
: relate to [multilingual] (/en/guide/#multi-languages). If no related , the value of the key itself will be displayedlink
: href linkicon
: css class of icon, can be omitted. Built-in icons of themename
: force this name to be displayed (no longer in multiple languages), can be omitted
Navbar supports subordinate menu:
menu:
- {
key: 'Docs',
icon: 'iconfont icon-books',
submenu: [
{ key: 'Guide', link: 'https://hexo.fluid-dev.com/docs/en/guide/' },
{ key: 'Advance', link: 'https://hexo.fluid-dev.com/docs/en/advance/' },
{ key: 'Icon', link: 'https://hexo.fluid-dev.com/docs/en/icon/' }
]
}
# Lazyload Image
lazyload:
enable: true
onlypost: false
When enabled, the image will only be loaded when scrolling to the visible range, which can greatly improve the overall loading speed of the web page.
if onlypost
is true, the lazyload
will be enabled only on the post pages.
# Font
The font-size and font-family of all page can be set through this items in theme config:
font:
font_size: 16px
font_family:
code_font_size: 85%
If you want to set a specific page, you can write the style tag in markdown:
---
title: example
---
<style>
/* For the page */
html, body, .markdown-body {
font-family: KaiTi,"Microsoft YaHei",Georgia, sans, serif;
font-size: 15px;
}
/* For the markdown content only */
.markdown-body {
font-family: KaiTi,"Microsoft YaHei",Georgia, sans, serif;
font-size: 15px;
}
</style>
# Web Analytics
Varies analytics servers have been supported, you can fill the 'Key' and 'ID' to enable it.
web_analytics:
enable: true
baidu: # Baidu analysis's Key,refer to https://tongji.baidu.com/sc-web/10000033910/home/site/getjs?siteId=13751376 after the code 'hm.js?'
google: # Google analysis's Tracking ID,refer to https://analytics.google.com/analytics/web/
tencent: # Tencent analysis's H5 App id,refer to https://mta.qq.com/h5/manage/ctr_app_manage
woyaola: # 51.la analysis's ID,refer to https://www.51.la/user/site/index
cnzz: # cnzz analysis's web_id,refer https://web.umeng.com/main.php?c=site&a=show
# Multi Languages
Some languages may change the font of some theme.
You can set up you language in the blog config, and you should define the language file name.
language: zh-CN # default is en
en zh-CN and ja is supported currently.
If you want to add more language, you'd better copy a new file to edit, and define the language file name.
# Enforce Https
When your domain update to https
, and some resources on your blog only support http protocol, the browser will not load this resources.
There will be errors in the console: Mixed Content: The page at 'https://xxx' was loaded over HTTPS
。
If it happens, you can change the theme config as follow:
force_https: true
Then all requests are forced by HTTPS (if it is an external resource, it needs to support HTTPS itself)
# Custom Page
If you want to generate a custom page, same as create about page.
- Create a page from the command:
$ hexo new page example
- Edit
/source/example/index.md
:
---
title: example
subtitle: Can be omitted, default is title
---
Content (Markdown or HTML)
The content has no markdown style by default. If you want to have the same style as post page, you can add:
<div class="markdown-body">
Content
</div>
- The properties of all custom pages can be set in theme config:
page:
banner_img: /img/default.png
banner_img_height: 70
banner_mask_alpha: 0.3
Also set it in Front-matter (opens new window):
---
title: example
banner_img: /img/default.png
banner_img_height: 60
banner_mask_alpha: 0.3
---
Markdown or HTML
Enable comment plugin on the custom page via the Front-matter (opens new window) set comment: 'type'
:
---
title: example
comment: 'disque'
---
# Custom JS / CSS / HTML
If you want to import external JS、CSS (such as iconfont) or HTML, you can set these in theme config:
# Set the path of the custom JS file, relative to the source directory
custom_js: /js/custom.js
# Set the path of the custom CSS file, relative to the source directory
custom_css: /css/custom.css
# Customize <head> HTML content
custom_head: '<meta name="key" content="value">'
# Customize the HTML content at the page bottom (above the footer), which can also be used to import JS or CSS externally. Be careful not to conflict with the post.custom configuration
custom_html: '<link rel="stylesheet" href="//at.alicdn.com/t/font_1067060_qzomjdt8bmp.css">'
# Dark Mode
Theme dark mode, switch button will appear in the menu after enable.
dark_mode:
enable: true
default: auto
default
Is the default mode of dark color, optional parameters:auto / light / dark
When you select auto
, the color schema of viewers will follow prefers-color-scheme (opens new window)
If this is not supported, enter dark mode from 18:00 local time to 6:00 the next day.
Regardless of any mode is selected, when the viewer manually switches, the options will be saved in local-storage, and the viewer will no follow the default mode.
# Home
# Slogan
The typing text in the banner image of the home page can be set in the theme config:
index:
slogan:
enable: true
text: This is a Slogan
api:
enable: false
url: "https://v1.hitokoto.cn/"
method: "GET"
headers: {}
keys: ["hitokoto"]
If text
is blank, the subtitle
in the blog config will replace it.
In addition, the content can be obtained through the API interface. If the request fails, it will be displayed in the text field:
url
: API url, which must be returned in JSON format
method
: request method, optional GET
, POST
, PUT
headers
: request headers, if the url requires some header items, set it here
keys
: Get the value field of the string from the response result, the program will get the value according to the field in the list, and finally need to get a string
For example, the content returned by the url is:
[
{
"data": {
"author": "Fluid",
"content": "An elegant theme"
}
},
{
"data": {
"author": "Test",
"content": "Test content"
}
}
]
Set keys: ["data", "content"]
, the program will execute as follows:
- If the response is a list, the program will get the first item (if not a list, skip this step)
- Get the value through the first key
data
, find that it is not a string, continue execution - Get the value through the second key
content
, find it is a string, and return the content; if it is not a string, the retrieval fails and the text value is used
The subtitle is enabled by default typing mobility, and the related configs is as follows:
fun_features:
typing:
enable: true
typeSpeed: 70
cursorChar: "_"
loop: false
TIP
Use the API feature of slogan must be first enable the typing feature
# Post Excerpt
Control the excerpt automatically (default is enable):
index:
auto_excerpt:
enable: true
If you need manual, you can use <!-- more -->
to define except.
Part of the content as an excerpt
<!-- more -->
The rest of the text
Or you can set excerpt
in Front-matter (opens new window):
---
title: This is a title
excerpt: Some words
---
TIP
Priority: Manually > Automatically.
There are 3 lines works will display in index page, the rest will be hidden automatically.
# Post Url Target
index:
post_url_target: _self
options:
- _blank: open post page in new tab
- _self: open post page in current tab
# Post Meta
You can hide any post meta, include: time、categories、tags etc.
After testing, if there are no thumbnails and summaries in the list of posts on the home page, the display of title + post information will make the page too crowded, so this configuration is given for students who like to display only the title of the post on the home page.
index:
post_meta:
date: true
category: true
tag: true
# Hide Posts
If you want to hide some posts on the index page, you can set hide: true
at the Front-matter (opens new window) of the post.
---
title: post title
index_img: /img/example.jpg
date: 2019-10-10 10:00:00
hide: true
---
This is post content
TIP
Hiding makes the post invisible in both category page and tag page. You can still enter post link.
# Sort Posts
If you want to sort posts on the index page, you can set sticky
at the Front-matter (opens new window) of the post, the premise is hexo-generator-index
>= 2.0.0.
---
title: post title
index_img: /img/example.jpg
date: 2019-10-10 10:00:00
sticky: 100
---
This is post content
The higher value of sticky
, the more forward the post will be.
When the post is setting with sticky
, Fluid will add an icon before the post title on the index page by default. You can modify something in theme config:
index:
post_sticky:
enable: true
icon: 'iconfont icon-top'
icon
can be modified to other icons through custom icon
# Post Page
# Index Image
You can define it at Front-matter (opens new window) of a post.
---
title: post title
tags: [Hexo, Fluid]
index_img: /img/example.jpg
date: 2019-10-10 10:00:00
---
This is post content
You can save the index image in the img
folder, or create a new folder in folder source
to save them.
You also can using other images in other locations, but using the correct link.
If you want to set a default image for all posts (when any post does not set the index_img
will use this image by default), which can be set in theme config:
post:
default_index_img: /img/example.jpg
When default_index_img
and index_img
are empty, no image will be displayed on the home page of the post.
# Banner Image
The default display of post.banner_img
in theme config, you can set banner_img
via Front-matter (opens new window) to set it separately:
---
title: your title
tags: [Hexo, Fluid]
index_img: /img/example.jpg
banner_img: /img/banner.jpg
date: 2019-10-10 10:00:00
---
This the content of the post
# Image In Post
You can save your pictures locally,or other locations.

# Post Meta
This meta display after the post title.
post:
meta:
author: # post author, first according to `author` in front-matter, then according to `author` in Hexo config
enable: false
date: # post date, first according to `date` in front-matter, then according to date of md file
enable: true
format: "dddd, MMMM Do YYYY, h:mm a" # format ISO-8601
wordcount: # word count
enable: true
format: "{} words" # placeholder
min2read: # Time required to read
enable: true
format: "{} minute"
views: # views count
enable: false
source: "leancloud"
format: "{} times"
TIP
The format of date must observe ISO-8601;
{}
can replace number, you can change other content.
# Code Block
code:
copy_btn: true
highlight:
enable: true
line_number: true
lib: "highlightjs"
highlightjs:
style: 'Github Gist'
bg_color: false
prismjs:
style: "default"
preprocess: true
copy_btn
: If true, enable copy code button
line_number
: If true, the code block display line numbers
highlight
: Configs of highlight library
lib
: Select the library to generate the highlight, options: highlightjs, prismjs, see the comments of the highlight configs in theme config
# Comment
You can enable it in theme config:
post:
comments:
enable: true
type: disqus
And then fill the arguments for corresponding module, Such as:
disqus:
shortname: fluid
Valine, Disqus, Gitalk, Utterances, Changyan, Livere, Remark42, twikoo can be supported currently.
For more comment systems, you can add corresponding ejs file into fluid/layout/_partial/comments/
, according to your system document, and then modify post.comments.type
link to your system.
TIP
If your comment area is not displayed, there may be throwing some errors, you can find out the reason in the console of your browser.
If you want to disable comment plugin on a post page, or want to enable comments on a custom page, you can set comment: false
or comment: 'type'
into Front-matter (opens new window).
For example, enable comment plugin on the about page:
---
title: About Page
layout: about
index_img: /img/example.jpg
date: 2019-10-10 10:00:00
comment: 'disqus'
---
Some words...
# Footnote
Fluid has built-in footnote, which can automatically generate footnotes with anchor points at the end of the post.
This is enabled by default in theme config:
post:
footnote:
enable: true
Syntax:
There are some words[^1]
[^1]: This is the footnote
A better way to use it is to put a footnote at the end of the post:
Content
## Reference
[^1]: Text-A
[^2]: Text-B
You can also add section headers automatically by modifying header
:
post:
footnote:
enable: true
header: '<h2>Reference</h2>' # It's equivalent to writing `## Reference`
# Tag Plugin
# Note
You can use notes by inserting the snippet into markdown:
{% note success %}
Some content or `markdown`
{% endnote %}
Or:
<p class="note note-primary">Note</p>
Optional:
primary
secondary
success
danger
warning
info
light
# Label
You can use labels by inserting the snippet into markdown:
{% label primary @text %}
Or:
<span class="label label-primary">Label</span>
Optional:
primary default info success warning danger
# CheckBox
You can use the following format in markdown:
{% cb text, checked?, incline? %}
text: text of item
checked:this item is checked or not, default false
incline: inline or not, default false
eg:
# Button
{% btn url, text, title %}
Or:
<a class="btn" href="url" title="title">text</a>
# Group Images
If you want to display a group of multiple images, you can use the following format in markdown:
{% gi total n1-n2-... %}





{% endgi %}
total:total number of images
n1-n2-... :number of images in each row
eg: {% gp 5 3-2 %}
means 5 images in total, 3 in the first row and 2 in the second row.
# Math
TIP
For hexo 5.0+, you can try hexo-math (opens new window) plugin to support more customization.
If you want to use LaTeX (opens new window) math, you should finish follow steps:
1. theme config
post:
math:
enable: true
specific: false
engine: mathjax
if specific
: true,you should add math: true
into Front-matter (opens new window) , and then the typesetting will be display on post page, and it can improve the speed of page load.
engine
: engine for typesetting, mathjax
or katex
is supported.
2. Change Markdown engine
Because the default engine of hexo doesn't support math typesetting, it should be changed by other better engine.
Uninstall the former engine:
npm uninstall hexo-renderer-marked --save
Then change your engine, such as:
mathjax: npm install hexo-renderer-kramed --save
katex: npm install @upupming/hexo-renderer-markdown-it-plus --save
3. After installing, run hexo clean
Write LaTeX in Markdown:
$$
E=mc^2
$$
WARNING
You can't install more than one engines
If your typesetting can't display correctly, you can check the below steps.
TIP
Different formula engines have different advantages and disadvantages.
MathJax
Advantages:
- full support for LaTeX syntax.
- right-click formula has extended function.
Shortcomings:
- need to load JS, pages will be slow to load, and there will be rendering changes.
- the kramed renderer does not support the escape character
\
of inline formulas.
Katex
Advantages:
- No JS will not affect page loading.
- the renderer works well (relative to kramed's inline formula for MathJax). Shortcomings.
- A small part of LaTeX do not support it.
# Mermaid
If you want to use Mermaid (opens new window), you should enable it:
post:
mermaid:
enable: true
specific: false
options:
specific
: If true, only set mermaid: true
into Front-matter will enable mermaid, to load faster when the page does not contain mermaid
options
: API options, see mermaidAPI.js (opens new window)
Write mermaid in Markdown, you can use the mermaid tag:
{% mermaid %}
gantt
dateFormat YYYY-MM-DD
title Adding GANTT diagram to mermaid
section A section
Completed task :done, des1, 2014-01-06,2014-01-08
Active task :active, des2, 2014-01-09, 3d
Future task : des3, after des2, 5d
Future task2 : des4, after des3, 5d
{% endmermaid %}
Alternatively, it can be written in code block:
```mermaid
classDiagram
Class01 <|-- AveryLongClass : Cool
Class03 *-- Class04
Class05 o-- Class06
Class07 .. Class08
Class09 --> C2 : Where am i?
Class09 --* C3
Class09 --|> Class07
Class07 : equals()
Class07 : Object[] elementData
Class01 : size()
Class01 : int chimp
Class01 : int gorilla
Class08 <--> C2: Cool label
# Archive Page
Please refer to theme config comments for details.
# Category Page
Please refer to theme config comments for details.
About adding categories (opens new window)
# Tag Page
You can custom some style of tags:
tag:
tagcloud:
min_font: 15
max_font: 30
unit: px # font-size
start_color: "#BBBBEE"
end_color: "#337ab7"
About adding tags (opens new window)
# About Page
# Create About Page
Since v1.7.0, the about page needs to be created manually:
$ hexo new page about
After successful creation, modify /source/about/index.md
and add layout
attribute.
The modified file example is as follows:
---
title: about
date: 2020-02-23 19:20:33
layout: about
---
# You can write the content here
Support Markdown, HTML
# Icons
# Link Page
The link page is used to display the site of friends. It is closed by default. To enable it, you need to delete the comment (#) of links
in the navbar
config item:
navbar:
menu:
- { key: 'links', link: '/links/', icon: 'iconfont icon-link-fill' }
Then find the config item of links
and set:
links:
items:
- {
title: 'Fluid Docs',
intro: 'Theme usage guide',
link: 'https://hexo.fluid-dev.com/docs/',
avatar: '/img/favicon.png'
}
default_avatar: /img/avatar.png
title
: The title of the siteintro
: The introduction of the sitelink
: The link of the siteavatar
: The avatar image of the site, can be omitteddefault_avatar
: The default avatar of the site (replace only when the avatar is specified and fails to load)
# 404 Page
If guest try to get the pages, which are not existed, 404 page will display.
To open this page, you need to configure it on the deployment environment of the blog:
- If your blog is deployed on a cloud server, you need to set the Nginx profile
error_page 404 = ./404.html
; - If deployed on Github Pages, no additional configuration is required, but the custom domain must be bound.
- For other platforms such as OSS, please refer to the 404-page configuration documentation for each platform, but not all platforms support redirect to this Html.