【Hexo】自定義 Hexo 配置文件

說明

上一篇里，介紹了使用 Hexo + github pages + travis ci 實現自動化博客部署，我們已經收獲了一個屬於自己的博客，但現在還比較簡陋，里面的設置信息都是默認的數據，所以我們需要把它們改成我們想要的內容。

所以這一篇里，主要介紹 Hexo 的配置文件如何設置。通過本篇的學習，你將知道 Hexo 配置文件的各個屬性是什么意思，並給出我使用的配置，這樣你就能隨心所欲的進行配置了。

站點信息

先來看第一部分，站點信息的配置。先說明一下各個字段的含義：

參數	描述
title	網站標題
subtitle	網站副標題
description	網站描述，主要用於 SEO，告訴搜索引擎關於站點的簡要信息
keywords	網站的關鍵詞。使用半角逗號, 分隔多個關鍵詞。
author	你的名字
language	網站使用的語言，常見的有 zh-Hans 、zh-CN 、 en
timezone	網站時區。默認使用本地時區。也可以指定其它時區，如 America/New_York, Japan, 和 UTC 。一般的，對於中國大陸地區可以使用 Asia/Shanghai。

下面是我的配置，可以作為參考：

# Site
title: 弗蘭克的貓
subtitle: '永遠年輕，永遠熱淚盈眶'
description: '銘記過去，擁抱未來，心中有夢，眼里有光'
keywords: 生活,編程,閱讀,音樂,電影
author: 清風
language: zh-CN
timezone: ''

網址信息

網址信息配置主要是設置網站的地址和文章鏈接格式。

參數	描述	默認值
url	網址
root	網站根目錄
permalink	文章的永久鏈接	格式 :year/:month/:day/:title/
permalink_defaults	永久鏈接中各部分的默認值
pretty_urls	改寫 permalink 的值來美化 URL
pretty_urls.trailing_index	是否在永久鏈接中保留尾部的 index.html，設置為 false 時去除	true
pretty_urls.trailing_html	是否在永久鏈接中保留尾部的 .html, 設置為 false 時去除 (對尾部的 index.html無效)	true

例如：

# 比如，一個頁面的永久鏈接是 http://example.com/foo/bar/index.html
pretty_urls:
  trailing_index: false
# 此時頁面的永久鏈接會變為 http://example.com/foo/bar/

這里通常只需要修改 url 和 root，如果博客是使用 github pages 進行部署的，url 配置成對應的博客地址即可。這里需要注意的是 root 的值，如果是按照我們上一篇中的方式進行部署的，則需要把 root 的值設置為 /項目名/。

下面是我的配置：

# URL
## If your site is put in a subdirectory, set url as 'http://yoursite.com/child' and root as '/child/'
url: https://mfrank2016.github.io/
root: /breeze-blog/
permalink: :year/:month/:day/:title/
permalink_defaults:
pretty_urls:
  trailing_index: true # Set to false to remove trailing 'index.html' from permalinks
  trailing_html: true # Set to false to remove trailing '.html' from permalinks

目錄信息

目錄信息是指定各類目錄對應的位置，通常不需要修改。

參數	描述	默認值
source_dir	資源文件夾，這個文件夾用來存放博客 md 等文件。	source
public_dir	公共文件夾，這個文件夾用於存放生成的站點靜態文件。	public
tag_dir	標簽文件夾	tags
archive_dir	歸檔文件夾	archives
category_dir	分類文件夾	categories
code_dir	Include code 文件夾，source_dir 下的子目錄	downloads/code
i18n_dir	國際化（i18n）文件夾	:lang
skip_render	跳過指定文件的渲染。匹配到的文件將會被不做改動地復制到 public 目錄中。您可使用 glob 表達式來匹配路徑。

例如：

skip_render: "mypage/**/*"
# 將會直接將 `source/mypage/index.html` 和 `source/mypage/code.js` 不做改動地輸出到 'public' 目錄
# 你也可以用這種方法來跳過對指定文章文件的渲染
skip_render: "_posts/test-post.md"
# 這將會忽略對 'test-post.md' 的渲染

我的配置如下：

# Directory
source_dir: source
public_dir: public
tag_dir: tags
archive_dir: archives
category_dir: categories
code_dir: downloads/code
i18n_dir: :lang
skip_render:

文章配置

這一部分是配置與文章相關的各類屬性。

參數	描述	默認值
new_post_name	新文章的文件名稱	:title.md
default_layout	預設布局	post
auto_spacing	在中文和英文之間加入空格	false
titlecase	把標題轉換為 title case	false
external_link	在新標簽中打開鏈接	true
external_link.enable	在新標簽中打開鏈接	true
external_link.field	對整個網站（site）生效或僅對文章（post）生效	site
external_link.exclude	需要排除的域名。主域名和子域名如 www 需分別配置	[]
filename_case	把文件名稱轉換為 (1) 小寫或 (2) 大寫	0
render_drafts	顯示草稿	false
post_asset_folder	啟動 Asset 文件夾	false
relative_link	把鏈接改為與根目錄的相對位址	false
future	顯示未來的文章	true
highlight	代碼塊的設置
highlight.enable	開啟代碼塊高亮	true
highlight.auto_detect	如果未指定語言，則啟用自動檢測	false
highlight.line_number	顯示行數	true
highlight.tab_replace	用 n 個空格替換 tabs；如果值為空，則不會替換 tabs	''
highlight.wrap	把代碼塊用 `` 包裹	true
highlight.hljs	為 highlight 的 css 文件中的類添加 hljs-* 前綴	false

auto_spacing 建議開啟，這樣的話看起來更美觀，titlecase 是指關鍵單詞首字母大寫，如果不太清楚，可以看下面的說明：

Titles should be written in title case. This means only using capital letters for the principal words. Articles, conjunctions, and prepositions do not get capital letters unless they start the title. For example:
The Last of the Mohicans

post_asset_folder 建議開啟，這樣會在生成新的文章時，同時會同一目錄下生成同名文件夾，這樣可以把該文章相關的圖片等資源放進去，方便引用和管理。

下面是我的配置：

new_post_name: :title.md # File name of new posts
default_layout: post
auto_spacing: true
titlecase: false # Transform title into titlecase
external_link:
  enable: true # Open external links in new tab
  field: post # Apply to the whole site
  exclude: ''
filename_case: 0
render_drafts: false
post_asset_folder: true
relative_link: false
future: true
# highlight:
#   enable: true
#   line_number: true
#   auto_detect: false
#   tab_replace: ''
#   wrap: true
#   hljs: false
highlight:
  enable: false

# 代碼高亮
prism_plugin:
  mode: 'preprocess'    # realtime/preprocess
  theme: 'tomorrow'
  line_number: false    # default false
  custom_css:

這里我使用了另一個代碼高亮插件，如果通常使用默認的 hljs 高亮即可。如果也想要使用這個插件，可以查看這里，需要先進行安裝：

npm i -S hexo-prism-plugin

分類和標簽信息

這里配置的是別名，即映射信息，如果文章使用的是英文名分類，這里可以不用設置，如果使用了中文名分類，最好配置一些對應的英文名，否則在對應的分類鏈接中就會出現 URL 編碼的中文，比如這樣：

http://localhost:4000/breeze-blog/categories/programming/life/%E6%B5%8B%E8%AF%95/

參數	描述	默認值
default_category	默認分類	uncategorized
category_map	分類別名
tag_map	標簽別名

我的配置如下：

# Category & Tag
default_category: uncategorized
category_map:
  編程: programming
  生活: life
  閱讀: reading
  隨想: thoughts
  理財: finance
tag_map:
  敏捷開發: agile-development
  環境搭建: environment-building

日期 / 時間格式

Hexo 使用 Moment.js 來解析和顯示時間。

參數	描述	默認值
date_format	日期格式	YYYY-MM-DD
time_format	時間格式	HH:mm:ss
use_date_for_updated	啟用以后，如果 Front Matter 中沒有指定 updated， post.updated 將會使用 date 的值而不是文件的創建時間。在 Git 工作流中這個選項會很有用	true

我的配置如下：

# Date / Time format
## Hexo uses Moment.js to parse and display date
## You can customize the date format as defined in
## http://momentjs.com/docs/#/displaying/format/
date_format: YYYY-MM-DD
time_format: HH:mm:ss
## Use post's date for updated date unless set in front-matter
use_date_for_updated: true

分頁信息

參數	描述	默認值
per_page	每頁顯示的文章量 (0 = 關閉分頁功能)	10
pagination_dir	分頁目錄	page

我的配置如下：

# Pagination
## Set per_page to 0 to disable pagination
per_page: 12
pagination_dir: page

擴展信息

參數	描述
theme	當前主題名稱。值為false時禁用主題
theme_config	主題的配置文件。在這里放置的配置會覆蓋主題目錄下的 _config.yml 中的配置
deploy	部署部分的設置
meta_generator	Meta generator 標簽。 值為 false 時 Hexo 不會在頭部插入該標簽

這里設置 theme 即可開啟對應的主題，具體如何設置會在后面的文章進行詳細說明。

theme_config 可以在這里配置主題文件里的各個參數進行覆蓋，這樣就不用維護兩份 config 文件了，不過個人覺得還是不同主題文件使用不同配置文件比較好。

deploy 是部署相關的配置，比如 git 部署，除此之外，還有很多其它部署姿勢，比如：Heroku、Netlify 等，但都需要先安裝對應的插件。

我的配置如下：

# Extensions
theme: hexo-theme-matery

# Deployment
deploy:
  type: 'git'
  repo: [e-mail]:MFrank2016/breeze-blog
  branch: gh-pages

包括或不包括目錄和文件

在 Hexo 配置文件中，通過設置 include/exclude 可以讓 Hexo 進行處理或忽略某些目錄和文件夾。可以使用 glob 表達式 對目錄和文件進行匹配。

include 和 exclude 選項都只能應用於 source/ 文件夾, 但 ignore 選項可以應用於所有文件夾。

參數	描述
include	Hexo 默認會忽略隱藏文件和文件夾（包括名稱以下划線和 . 開頭的文件和文件夾，Hexo 的 _posts 和 _data 等目錄除外）。通過設置此字段將使 Hexo 處理他們並將它們復制到 source 目錄下。
exclude	Hexo 會忽略這些文件和目錄
ignore	忽略文件或文件夾

舉例：

# Include/Exclude Files/Folders
include:
  - ".nojekyll"
  # 包括 'source/css/_typing.css'
  - "css/_typing.css"
  # 包括 'source/_css/' 中的任何文件，但不包括子目錄及其其中的文件。
  - "_css/*"
  # 包含 'source/_css/' 中的任何文件和子目錄下的任何文件
  - "_css/**/*"

exclude:
  # 不包括 'source/js/test.js'
  - "js/test.js"
  # 不包括 'source/js/' 中的文件、但包括子目錄下的所有目錄和文件
  - "js/*"
  # 不包括 'source/js/' 中的文件和子目錄下的任何文件
  - "js/**/*"
  # 不包括 'source/js/' 目錄下的所有文件名以 'test' 開頭的文件，但包括其它文件和子目錄下的單文件
  - "js/test*"
  # 不包括 'source/js/' 及其子目錄中任何以 'test' 開頭的文件
  - "js/**/test*"
  # 不要用 exclude 來忽略 'source/_posts/' 中的文件。你應該使用 'skip_render'，或者在要忽略的文件的文件名之前加一個下划線 '_'
  # 在這里配置一個 - "_posts/hello-world.md" 是沒有用的。

ignore:
  # Ignore any folder named 'foo'.
  - "**/foo"
  # Ignore 'foo' folder in 'themes/' only.
  - "**/themes/*/foo"
  # Same as above, but applies to every subfolders of 'themes/'.
  - "**/themes/**/foo"

列表中的每一項都必須用單引號或雙引號包裹起來。

include 和 exclude 並不適用於 themes/ 目錄下的文件。如果需要忽略 themes/ 目錄下的部分文件或文件夾，可以使用 ignore 或在文件名之前添加下划線 _。