# 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 to fluid_config.yml;
You can set any config with the file fluid_config.yml, it can be used when you start 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 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

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

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

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

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：

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

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

Built-in icons of theme

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

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

# Guide

# About this Guide

# Global

# Override Configuration

# Static Assets

# Local Search

# Banner Image

# Title of Blog

# Navbar

# Lazyload Image

# Font

# Web Analytics

# Multi Languages

# Enforce Https

# Custom Page

# Custom JS / CSS / HTML

# Dark Mode

# Home

# Slogan

# Post Excerpt

# Post Url Target

# Post Meta

# Hide Posts

# Sort Posts

# Post Page

# Index Image

# Banner Image

# Image In Post

# Post Meta

# Code Block

# Comment

# Footnote

# Tag Plugin

# Note

# Label

# CheckBox

# Button

# Group Images

# Math

# Mermaid

# Archive Page

# Category Page

# Tag Page

# About Page

# Create About Page

# Icons

# Link Page

# 404 Page