声明

这里是主题的使用手册，能帮助你解决大部分的问题。

本文档适用 v2.1.0 版本，向下兼容。（过高、过低的版本会有 Breaking Changes）

本文「博客目录」指的是 hexo init 命令的目录，存放站点文件。「主题目录」指的是 themes/miracle 目录，存放主题文件。

「博客配置」指的是 hexo init 命令目录下的 _config.yml 文件，「主题配置」指的是 hexo init 命令目录下的 _config.miracle.yml 文件或 themes/miracle 文件夹下的 _config.yml 文件。

为什么无法使用 / 报错？

请检查是否配置了 图片懒加载 与 WebP，如果您不需要使用它们，也请将 enable 设为 false！

在最新版的主题中已经不存在此问题。

下载与安装

在开始前，你需要先安装 Hexo 并初始化你的博客。

NPM

  1. 在博客目录下执行以下命令：
npm install hexo-theme-miracle —-save

  1. 在博客目录下创建 _config.miracle.yml，将主题的 _config.yml 内容复制过去。

  2. 修改博客目录下的 _config.yml 文件。

lang: zh-CN # 可选项，用与匹配语言文件
theme: miracle # 指定主题

发行版

  1. 前往 GitHub 下载 最新的发行版 。
  2. 将其解压至博客目录下的 themes 目录内。
  3. 将文件夹重命名为 miracle。
  4. 修改博客目录下的 _config.yml 文件。
lang: zh-CN # 可选项，用与匹配语言文件
theme: miracle # 指定主题

覆盖配置

覆盖配置可以使主题配置放置在主题目录之外，避免在更新主题时丢失自定义的配置。 通过 NPM 安装主题的用户可忽略。

Hexo 5.0.0 版本以上的用户，在博客目录下创建 _config.miracle.yml 文件，将主题的 _config.yml 内容复制过去。

以后如果修改任何主题配置，都只需修改 _config.miracle.yml 的配置即可。

请注意：

更新主题

NPM

如果您是使用 NPM 安装主题，请在博客目录下执行命令：

npm update hexo-theme-miracle --save

发行版

  1. 将自己的配置文件备份（如果使用 覆盖配置 功能可忽略此步骤）；
  2. 将 miracle 文件夹全部删除，重新下载 发行版 并解压；
  3. 如果某些配置发生了变化，发行版的的说明里会特别提示，同步修改原配置文件即可。

Git

如果您修改了主题的源码文件，或想使用开发版，可参考以下更新步骤：

  1. 确保自己的 miracle 目录已经开启 git，并且所有改动都已 commit

  2. 拉取仓库 (请自行根据实际情况修改分支等信息)：

git pull <https://github.com/hifun-team/hexo-theme-miracle.git> dev
  1. 解决代码冲突。

基础配置

博主信息

主题会在首页展示博主的名称与 Slogan 。

index:
    name: "Theme Miracle" # 博主 / 站点的名称
    slogan: "A clean and lightweight single-column theme for Hexo." # Slogan

自定义字体

所有页面的字体可以通过主题配置中的配置项设置：

global:
    font:
        # 页面字体
        family: "'Noto Sans SC', sans-serif"
        # 字体 CSS 文件，选填。注意，字体 CSS 文件不是字体文件，而是像 Google Fonts 一样声明字体的文件。
        css: "<https://fonts.googleapis.com/css2?family=Noto+Sans+SC&display=swap>"

导航栏菜单

导航栏菜单可以自行增减。

navbar:
    menu:
				# 导航栏文本: 导航栏链接
        Home: /
        GitHub: <https://github.com>

文章字数统计&时长预计

首先，在配置文件中启用文章字数统计与时长预计。

post:
    wordcount:
        enable: true # 设为 True。

    min2read:
        enable: true # 设为 True。

随后，可根据自己的需要修改文章的阅读速度：

post:
    min2read:
        # 每分钟阅读多少字，如果是技术文章，建议降低
        # Words read per minute
        words: 120

评论插件

首先，启用评论插件。

post:
    comment: true

并在下方选择对应的评论程序。

目前支持 Gitalk / Valine / Waline / Twikoo 作为评论系统。

comment:
    type: gitalk # valine / waline / twikoo

最后，根据选择的评论系统与评论的官方文档在下方逐一配置。

Tips: 仅需要配置您选择的评论系统即可。

站内搜索

主题已集成搜索插件，仅需启用即可。

search:
    enable: true
		field: post

如已安装其他搜索插件请关闭，避免生成多余的索引文件。

field 选项可指定范围，post 为文章，page 为页面，all 为所有。

网页统计

目前统计平台支持 百度统计、谷歌统计、51.la、友盟（CNZZ）与 不蒜子。

请参考配置文件中的注释完成配置。

需要注意！如果在使用 不蒜子统计 时不想在页面的底部显示 PV 和 UV，请将 pv_format 和 uv_format 留空。

global:
    # 网页访问统计
    # Analysis of website visitors
    web_analytics:
        # 百度统计的 Key，值需要获取下方链接中 `hm.js?` 后边的字符串
        # Baidu analytics, get the string behind `hm.js?`
        # See: <https://tongji.baidu.com/sc-web/10000033910/home/site/getjs?siteId=13751376>
        baidu:

        # Google 统计的 Tracking ID
        # Google analytics, set Tracking ID
        # See: <https://developers.google.com/analytics/devguides/collection/analyticsjs>
        google:

        # 51.la 站点统计 ID
        # 51.la analytics
        # See: <https://www.51.la/user/site/index>
        woyaola:

        # 友盟/cnzz 站点统计 web_id
        # cnzz analytics
        # See: <https://web.umeng.com/main.php?c=site&a=show>
        cnzz:

        busuanzi:
            enable: true
            # 页面显示的文本，{} 是数字的占位符（必须包含），下同
            # Displayed text, {} is a placeholder for numbers (must be included), the same below.
            pv_format: "总访问量 {} 次"
            uv_format: "总访客数 {} 人"

代码高亮

修改博客配置（博客目录下的 _config.yml 文件）：

highlight:
    enable: true # 启用高亮
    line_number: false
    auto_detect: false
    tab_replace: ''
    wrap: false # 推荐 False
    hljs: true # 必须为 True

随后修改主题配置，启用代码高亮：

post:
    # 代码显示设置
    # Code display setting
    code:
        # 代码高亮
        # Code highlight
        highlight: true # 设为 True

图片懒加载

编辑「博客配置」，在文件末尾追加以下内容：

lazyload:
	enable: true
	# 仅用于文章
	onlypost: false
	# 加载图片
	loadingImage: "/path/to/your/file"

WebP

可参考 我的图床解决方案 - YFun's Blog。

编辑「博客配置」，追加以下内容开启：

webp:
  enable: true

例如，在 https://example.com/image/ 下有 1.jpg 与 1.webp 两个文件。

此时，在 Markdown 文件中编写：

![Some Photo](<https://example.com/image/1.jpg>)

HTML 将会被生成为：

<picture>
	<source class="lazyload-img" data-srcset="<https://example.com/image/1.webp>" srcset="<YOUR_LAZYLOAD_IMAGE>" type="image/webp">
	<img webp-comp src="<https://example.com/image/1.jpg>" alt="Some Photo">
</picture>

这样子就可以在支持 WebP 的浏览器中显示 WebP，不支持的浏览器中显示原始图片。

例如，在 https://example.com/no-webp/ 下只有 2.jpg，没有 WebP 图片，则需要编写：

<img webp-comp src="<https://example.com/no-webp/2.jpg>">

HTML 将会被生成为：

<img webp-comp src="<https://example.com/no-webp/2.jpg>">

如果仍使用 ![]() 插入 Markdown 图片，则仍会被替换为 <picture> 标签，并导致图片 404。

哀悼模式

在 v2.1.0 版本中，我们对哀悼模式进行了优化。

编辑「主题配置」：

global:
	memorial:
			# 为 true 时启用
      enable: true
      # 日期, (M-D)
      # Date, (M-D)
      # eg: 7-8, 9-30, 12-1, 12-30 ...
      date:
          - "7-8"
          - "12-13"

文章阅读进度分享

其原理与实现代码请参见：让阅读无缝衔接 —— JS 获取用户阅读进度

编辑「主题配置」：

post:
	readingProgess:
		enable: true

此时，文章页面右下角会出现分享按钮。点击即可复制当前页面的分享链接。

Untitled

文章 Front-Matter

---
title: 
date: 
tags: 
category: 
excerpt: 
author: 
authorURL: 
url: 
copyrightText: 
comment: 
---

文章 Front-Matter

页面 Front-Matter

---
title: 
date: 
excerpt: 
comment: 
---

页面 Front-Matter

友情链接

首先，您需要启用友情链接：

links:
    enable: true

主题提供了两种友情链接列表，分别是 YAML 和 JSON。

YAML

links:
    enable: true
    items:
      - {
			  title: "Title",
				image: "/path/to/your/image",
				intro: "Hello ...",
				link: "your-domain.com"
      },
			- {
			  title: "Title",
				image: "/path/to/your/image",
				intro: "Hello ...",
				link: "your-domain.com"
      }
        
    # JSON 友链
    # JSON Links
    json_links:
        enable: false

        # JSON 文件链接
        # Link to JSON file
        item_links:

使用 YAML 时，请将 json_links 设为 false