# Guide

# Theme Introduction

Fluid is an elegant Material-Design theme for Hexo, developed by Fluid-dev

GitHub Repository: https://github.com/fluid-dev/hexo-theme-fluid

Preview: Fluid's Blog zkqiang's blog

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

This page of the guide created by VuePress.


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

# Quick Start

# Install Hexo

If you don't have a hexo blog, please follow Hexo Docs to install and initialize your blog。

# Download Theme

Please download the latest release, or the master branch may not guarantee stability.

After download, extract it to the themes directory and rename it to fluid.

# Necessary Configuration

Modify _config.yml in the blog root directory as follows。

theme: fluid  # set theme

# 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

# Global

# Override Configuration

This feature can makes upgrade the theme smoother, recommended everyone to learn to use.

Override configuration can make the theme config out of the theme dictionary, and avoid losing custom config after the theme upgraded.

You should make sure that your version of Hexo is not lower than 3.0, because of the function about data-files


  1. cd into the folder 'source' in your blog root dictionary, mkdir _data (beside to the folder '_post');
  2. Create a file fluid_config.yml in the folder _date , copy the configurations from theme config to fluid_config.yml;
  3. You can set any config with the file fluid_config.yml, it can be used when you start hexo g.


You can also copy only part of the configurations.

The configuration existing in fluid_config.yml is of high priority, modifying _config.yml is invalid.

There may be configuration changes in the theme of upgrading, you need to manually modify fluid_config.yml synchronously.

You can use hexo g -- debug to check override configuration.

If you want to cancel some configurations, you should do this:

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

# Static Resource

The Url of all resource static files can be customized through fluid/_static_prefix.yml, it also can be override with _data/fluid_static_prefix.yml.

If we should get the JQuery CDN library, we can add a line at the end of the file /source/_data/fluid_static_prefix.yml:

jquery: https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/
  • 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.

  • 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


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


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:

  blog_title: your title
    - { 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 displayed
  • link: href link
  • icon: css class of icon, can be omitted. Built-in icons of theme
  • name: force this name to be displayed (no longer in multiple languages), can be omitted

Navbar supports subordinate menu:

  - {
      key: 'Docs',
      icon: 'iconfont icon-books',
      submenu: [
        { key: 'Guide', link: 'https://hexo.fluid-dev.com/docs/en/guide/' },
        { key: 'Example', link: 'https://hexo.fluid-dev.com/docs/en/example/' },
        { key: 'Icon', link: 'https://hexo.fluid-dev.com/docs/en/icon/' }

# Lazyload Image

  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_size: 16px
  code_font_size: 85%

If you want to set a specific page, you can write the style tag in markdown:

title: example

  /* 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;

# Web Analytics

Varies analytics servers have been supported, you can fill the 'Key' and 'ID' to enable it.

  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.

# Faster Loading

  1. For all the users, it is the effective way to use public CDN for the 'third-party lib', you can add it into the file _static_prefix.yml

  2. You can use OSS and bind your domain, then upload the files in the folder public to your OSS.

  3. For your custom images, especially the big banner picture, you can use tinypng to compress them, and upload them to your private CDN.

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

  1. Create a page from the command:
$ hexo new page example
  1. 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">
  1. The properties of all custom pages can be set in theme config:
  banner_img: /img/default.png
  banner_img_height: 70
  banner_mask_alpha: 0.3

Also set it in Front-matter:

title: example
banner_img: /img/default.png
banner_img_height: 60
banner_mask_alpha: 0.3

Markdown or HTML

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

  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

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 typewriter text in the large image of the home page can be set in the theme configuration file whether to turn on or not:

    enable: true
    text: This is a Slogan

If text is '', the subtitle in the 'blog config' will replace it.

Related dynamic effect settings:

  typing: # 为 subtitle add Slogan effect
    enable: true
    typeSpeed: 70 # Slogan speed
    cursorChar: "_" # cursor style
    loop: false # repeat

# Post Excerpt

control the excerpt automatically (default is enable):

    enable: true

If you need manual, you can use <!-- more --> to define except.

This is excerpt
<!-- more -->
This is body

Or you can set excerpt in Front-matter:

title: This is a title
excerpt: Some words


Priority: Manually > Automatically.

There are 3 lines works will display in index page, the rest will be hidden automatically.

# Post Url Target

  post_url_target: _self


  1. _blank: open post page in new tab
  2. _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.

    date: true
    category: true
    tag: true

# Hide Post

If you want to hide some posts from the index page, you can define hide: true at the head of a post Front-matter.

title: post title
index_img: /img/example.jpg
date: 2019-10-10 10:00:00
hide: true
This is post content


Hiding makes the post invisible in both category page and tag page. You can still enter post link.

# Post Page

# Index Thumbnails

You can define it at the head of a post Front-matter.

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 your thumbnails in the img folder, or you can create a new folder in folder source to save them in folder source.

You also can using other pictures in other locations, but using the correct link.

# Post Banner Image

You can define it at the head of a post, or use the home Banner image by defaulted

title: your title
tags: [Hexo, Fluid]
index_img: your Thumbnails
banner_img:  your post banner
date: 2019-10-10 10:00:00
This the body of the post

# Image In Post

You can save your pictures locally,or other locations.


# Date/Word Count/Reading Time/Reading count

These metas display after the post title.

    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"


The format of date must observe ISO-8601;

{}can replace number, you can change other content.

# Code Highlight

Highlight style can be selected from here: https://highlightjs.org/static/demo/

then set the name of style into theme config:

  enable: true
  style: 'Github Gist'
  bg_color: false
  copy_btn: true

bg_color: whether to change the code background color according to style. If style color is white, it is better to false
copy_btn: display the button to copy code

Line number of code is not supported.

# Comment

You can enable it in theme config:

    enable: true
    type: disqus

And then fill the arguments for corresponding module, Such as:

  shortname: fluid

Valine、Disqus、Gitalk、Utterances、Changyan、Livere、Remark42 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.


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.

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

    enable: true


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:


## Reference
[^1]: Text-A
[^2]: Text-B

You can also add section headers automatically by modifying header:

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


<p class="note note-primary">Note</p>









# Label

You can use labels by inserting the snippet into markdown:

{% label primary @text %}


<span class="label label-primary">Label</span>


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


{% 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 %}


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

Group Images

# LaTeX

Before you use LaTeX math typesetting, you should finish follow steps:

1. theme config

    enable: true
    specific: false
    engine: mathjax

if specific: true,you should add math: true into Front-matter , 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


You can't install more than one engines

If your typesetting can't display correctly, you can check the below steps.


Different formula engines have different advantages and disadvantages.



  • full support for LaTeX syntax.
  • right-click formula has extended function.


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



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

# Archives Page

There is no attribute, but Banner.

# Categories Page

There is no attribute, but Banner.

About adding categories

# Tags Page

You can changes some style of tags:

    min_font: 15
    max_font: 30
    unit: px  # font-size
    start_color: "#BBBBEE"
    end_color: "#337ab7"

About adding tags

# 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

Built-in icons of theme

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

# About Hexo Configuration

Blog _config.yml

Post Front-matter