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

"site config" refer to the _config.yml in the blog root directory.
"theme config" refer to the path theme/fluid/_config.yml or _config.fluid.yml.

# Global

# Configuration Override

TIP

Configuration override can avoid losing your customized configuration while updating Fluid.

Users who installed Fluid via npm can ignore it, while we recommended other users to learn to use it.

If your Hexo version >= 5.0.0(hexo -v), please create _config.fluid.yml in the blog directory and copy the content of our theme's_config.yml (opens new window) into it.

Notice:

The configuration existing in _config.fluid.yml is of high priority, so modifying _config.yml is useless.
There may be configuration changes in the upgraded theme, you need to manually modify _config.fluid.yml synchronously.
You can use hexo g -- debug to check configuration override.
If you want to cancel some configurations, you should:

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' }

If your Hexo version < 5.0.0, look 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:

Go to or create source/_data directory of the blog directory;
Create a file fluid_config.yml in _date , copy the content of _config.yml (opens new window) to fluid_config.yml;
You can set any config with the file fluid_config.yml, it can be used when hexo 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 already been integrated, disable it if you had installed other search plug-ins to avoid generating redundant index files.
By default, local-search.xml is generated in the root directory and being used.

Image source

There is banner_img property for every pages in the theme config, which can be assigned as a relative path or url.

To use a local image:

banner_img: /img/bg/example.jpg   # At /source/img/bg/example.jpg

To use a url:

banner_img: https://static.zkqiang.cn/example.jpg

TIP

You can define the path yourself, but it should be in the source directory

The source directory of blog and Fluid will be merged eventually, so the source of blog is preferred.

Image height

For different people's preferences, you can control the height of the banner_img on the page.

You can set banner_img_height for every pages in theme config with a valid range of 0 - 100. We think it is better to choose a number bigger than 70.

Alpha of mask

You can set banner_mask_alpha for every pages in theme config with a valid range of 0 - 1.0. 0 is completely transparent (no mask) while 1 is completely opaque.

TIP

The banner of each post page can be set independently. You can read the config about the posts for more details.

# Title of your Blog

The title is on the left side of the banner. It can be set by modifying the property title in file site 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:
  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: relates to [multilingual] (/en/guide/#languages). If no related , the value of the key itself will be displayed
link: href link
icon: css class of your icons which can be omitted. View built-in icons of theme
name: 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

Lazyload will make the image or comment plugin load only when it scrolls to visible, which can greatly improve the speed of loading your blog.

It is enabled by default, you can set some items in theme config:

lazyload:
  enable: true
  loading_img: /img/loading.gif
  onlypost: false
  offset_factor: 2

loading_img: The placeholder image when loading

onlypost: If true, only enable lazyload on the post page. For custom pages, you can set lazyload: true in front-matter (opens new window)

offset_factor: The factor of viewport height that triggers loading

# 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

# Languages

Setting a different language in the site config will change the text of the theme:

language: en

You can check which languages are supported in the theme languages (opens new window) directory, as long as the value of the above configuration is the same as the file name.

You can also use a similar way to override the configuration to customize the language:

Go to or create source/_data directory of the blog directory, then create the languages folder;
Create a file named en.yml in source/_data/languages , copy the content of en.yml (opens new window) in fluid/languages to you just created;
You can reset any config in en.yml you just created, it can be used when hexo g.

Of course, you can also choose other language yaml, just keep the filename and config value the same.

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

# OpenGraph

OpenGraph (opens new window) enables any web page to become a rich object in a social graph. For instance, this is used on Facebook to allow any web page to have the same functionality as any other object on Facebook.

Fluid implements this feature based on Hexo built-in method (opens new window) and is enabled by default, but if you want to use it better on social such as Facebook, you need to complete the following config items in theme config:

open_graph:
  enable: true
  twitter_card: summary_large_image
  twitter_id:
  twitter_site:
  google_plus:
  fb_admins:
  fb_app_id:

In addition, you can set fields in front-matter (opens new window) to specify the OpenGraph property of a single page:

---
og_img: /img/og.png
---

# 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 site 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  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, 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

hide makes the post invisible on all pages. But you can still enter post link.

# Archive Posts

If you want to makes the post invisible on index pages, you can set archive: 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
archive: true
---
This is post content

# 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 directory in source directory 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.

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.

![](/img/example.jpg)

# 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

List of supported comment plugins：

Valine (opens new window) : based on LeanCloud
Waline (opens new window) : derived from Valine with self-hosted service
Gitalk (opens new window) : based on GitHub Issues
Utterances (opens new window) : based on GitHub Issues
Disqus (opens new window) : based on third-party service
Changyan (opens new window) : based on third-party service
Livere (opens new window) : based on third-party service
Remark42 (opens new window) : based on self-hosted service
Twikoo (opens new window) : based on Tencent CloudBase
Cusdis (opens new window) : based on third-party or self-hosted service
Giscus (opens new window): based on GitHub Discussion

For usage and parameter setting, please click the link above to view the respective documents.

If you want to import a new comment plugin, you can add <script> through Custom JS, and judge whether there is #comments element to mount.

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

# Fold Block

By using fold blocks, you can fold code, images, text, or any other content. You can use the following format in markdown:

{% fold info "title" %}
Some content or `markdown`
{% endfold %}

info: Optional param similar to label tag title: Title of the fold block

# 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：

{% cb simple %}

{% cb checked, true %}

{% cb inline, false, true %} no wrapping after text

{% cb false %} You can also write some text after the checkbox

# Button

{% btn url, text, title %}

Or：

<a class="btn" href="url" title="title">text</a>

text

# Group Images

If you want to display a group of multiple images, you can use the following format in markdown:

{% gi total n1-n2-... %}
  ![](url)
  ![](url)
  ![](url)
  ![](url)
  ![](url)
{% 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.

Group Images

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

mathjax

npm uninstall hexo-renderer-marked --save
npm install hexo-renderer-pandoc --save

Also need to install Pandoc (opens new window)

katex

npm uninstall hexo-renderer-marked --save
npm install hexo-renderer-markdown-it --save
npm install @traptitech/markdown-it-katex --save

Then append to site config:

markdown:
  plugins:
    - "@traptitech/markdown-it-katex"

3. After installing, run hexo clean

Write LaTeX in Markdown:

$$
E=mc^2
$$

WARNING

You can't install more than one renderer, and can't install plugins such as hexo-math or hexo-katex.
If your typesetting can't display correctly, you can check the below steps.
The custom page doesn't load math by default, you need to specify math: true into front-matter (opens new window) to ues 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: 标题
layout: about
---

You can write the content here, support Markdown, HTML

# Meta

You can set some meta information about yourself in theme config:

about:
  avatar: /img/avatar.png
  name: "Fluid"
  intro: "An elegant theme for Hexo"

# Icons

Set icons in theme config:

about:
  icons:
    - { class: 'iconfont icon-github-fill', link: 'https://github.com', tip: 'GitHub' }
    - { class: 'iconfont icon-youtube-fill', link: 'https://youtube.com', tip: 'YouTube' }
    - { class: 'iconfont icon-twitter-fill', qrcode: '/img/favicon.png' }

class: CSS class of icons, more built-in icons of theme
link: target link
tip: display the tip when the mouse hovers over the icon
qrcode: QR-code image, when using this field, clicking will not be directed, but hover QR-code

# Comment

Enable comment plugin via the front-matter (opens new window) set comment: bool to enable the comment plugin, or set comment: 'type'to enable the specified comment plugin.

---
title: This is a title
layout: about
comment: 'disqus'
---

# 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 site
intro: The introduction of the site
link: The link of the site
avatar: The avatar image of the site, can be omitted
default_avatar: The default avatar of the site (replace only when the avatar is specified and fails to load)

# Custom Page

# Create page

If you want to create 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>

# Configuration

The params 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

# Comment

Enable comment plugin in the same way as the about page, via the front-matter (opens new window), set comment: bool to enable the comment plugin, or set comment: 'type'to enable the specified comment plugin.

---
title: example
comment: 'disqus'
---

# 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 404 page.

Fluid contains the default 404 page, you can also place the custom 404.html in source directory

# Guide

# About this Guide

# Global

# Configuration Override

# Static Assets

# Local Search

# Banner Image

# Title of your Blog

# Navigation bar

# Lazyload

# Font

# Web Analytics

# Languages

# Enforce Https

# Custom JS / CSS / HTML

# Dark Mode

# OpenGraph

# Home

# Slogan

# Post Excerpt

# Post Url Target

# Post Meta

# Hide Posts

# Archive Posts

# Sort Posts

# Post Page

# Index Image

# Banner Image

# Image In Post

# Post Meta

# Code Block

# Comment

# Footnote

# Tag Plugin

# Note

# Label

# Fold Block

# CheckBox

# Button

# Group Images

# Math

# Mermaid

# Archive Page

# Category Page

# Tag Page

# About Page

# Create About Page

# Meta

# Icons

# Comment

# Link Page

# Custom Page

# Create page

# Configuration

# Comment

# 404 Page