Annie主题详细使用说明
开始之前的说明
文中所有的指令都是在Hexo文件夹下开启的命令行中执行的
- 代码对比
This is a diff block.
+ This is add!
- This is subtract!
- Bash指令
Bash指令
- 文件目录
| 序号 | 名词 | 说明 | 目录 |
|---|---|---|---|
| 1 | 站点配置文件 |
站点目录下的_config.yml文件 |
Hexo/_config.yml |
| 2 | 主题配置文件 |
主题目录下的_config.yml文件 |
Hexo/themes/Annie/_config.yml |
| 3 | 文章目录 | 文章.md文件 | Hexo/source/_posts |
一、LOGO和FAVICON
编辑主题配置文件，设置favicon和logo的路径即可。当然，你可以使用文字logo或图片logo，即logo的值为空时，主题使用title的值作为logo！
# favicon & logo
# if the value of logo is false, the 'title' is optional.
- favicon: /img/favicon.ico
- logo: /img/logo.png
- title: Welcome
+ favicon: /img/your-favicon.ico
+ logo: /img/your-logo.png
+ title: your-title
这里的img是指的Hexo/themes/Annie/source/img目录
二、页头背景图片
文章详情页的页头背景图片为该文章的封面图，其他页的页头背景图片为随机图片或固定图片。
原则上:
使用固定图片时，应将参数mode设为normal，然后设置normal_url的路径；
使用随机图片时，应将参数mode设为random，然后设置random_url的路径。
# background_image
# /img/1.jpg
# https://source.unsplash.com/collection/954550/1920x1080
# https://sariay.github.io/Random-img/
# May be cause CROS bug!
background_image:
mode: normal #normal or random
normal_url: /img/1.jpg
random_max: 110
random_url: https://sariay.github.io/Random-img/
注意跨域问题，尽量不使用跨域的图片（即背景图片和网页最好托管在一起，存放于同一服务器）
编辑主题配置文件，找到background_image标签进行相应设置。
- 使用固定图片，请确保参数
mode设为normal，然后设置参数normal_url的值
background_image:
+ mode: normal #normal or random
+ normal_url: /img/1.jpg
random_max: 110
random_url: https://sariay.github.io/Random-img/
- 使用unplash随机图片，请确保参数
mode设为normal，然后设置参数normal_url的值
background_image:
+ mode: normal #normal or random
+ normal_url: https://source.unsplash.com/collection/954550/1920x1080
random_max: 110
random_url: https://sariay.github.io/Random-img/
- 使用自定义随机图片，请确保参数
mode设为random，然后设置参数random_max、random_url的值
- 第一步、fork 随机图片集；
- 第二步、开启你所fork的仓库的page服务；
- 第三步、获取相对地址；
- 第四步、设置random_url为获得的相对地址。
background_image:
+ mode: random #normal or random
normal_url: https://source.unsplash.com/collection/954550/1920x1080
+ random_max: 110
+ random_url: https://sariay.github.io/Random-img/
你可以将随机图片集上传到云（腾讯云、七牛云等），然后获取https://....../Random-img/格式的地址，最后将random_url的值设置为该地址。
你也可以在主题目录下的img文件夹中新建Random-img文件夹，将0.jpg、1.jpg、2.jpg、3.jpg……110.jpg命名格式的图片放入其中，然后将random_url的值设置为/img/Random-img/。
图片的命名使用连续的整数，random_max的值小于等于（0、1、2、3…..110）的最大整数。（ps：如你偏爱访问速度🙃，尽可能使用固定图片）
三、随机名言与当地时间
每次刷新网页，网页页头展示一条随机名言，获取并展示该时区的标准时间。
# show motto
motto:
enable: true
# show current time
+ #This is only a demo, please go to "https://time.is" to set your city time!
timejs:
enable: true
编辑主题配置文件，设置motto和timejs下的enable为true的参数即可。
四、预加载遮罩
预加载遮罩的作用为，确保背景图片加载完成和背景构造完成。当背景加载并构造完成时，主题立即移除遮罩。预加载行为的超时时间默认设为10s，即最多10s左右后，不管背景是否加载并构造完成，主题都移除遮罩。你可以决定是否使用：
# 002-PROLOADER
# animation: spinner | transition | cyclic
preloader:
+ enable: true
+ animation: transition
编辑主题配置文件，设置preloader下的enable为true并设置animation参数（spinner, transition or cyclic）。
五、首页文章展示样式
首页文章展示有两种模式：图文模式cart和纯净模式pure
编辑主题配置文件，设置index_style的参数即可。
# 003-INDEX
# index-style: pure | cart
+ index_style: cart
# index_cart_cover
+ cover: /img/cart_cover.jpg
+ lazy_image: /img/placeholder.jpg
未设置图片的文章默认设置cover路径下的图片，文章图片未加载出来时显示lazy_image下的图片
5.1设置文章封面图
在每篇文章的头部添加cover标签设置每篇文章的背景，路径可为相对路径或绝对路径。
---
title: title
date: 2019-01-01 08:00:00
tags: [tag1, tag2, tag3]
categories: Note
description:
abstract:
+ cover: /img/1.jpg
---
5.2首页的分页
hexo博客默认首页分页，编辑站点配置文件，设置参数per_page为1、2、3…..以达到分页目的，0则不分页。
# Home page setting
# path: Root path for your blogs index page. (default = '')
# per_page: Posts displayed per page. (0 = disable pagination)
# order_by: Posts order. (Order by date descending by default)
+index_generator:
path: ''
+ per_page: 5
order_by: -date
5.3文字的截断
编辑主题配置文件
excerpt_cart为图文模式的截取字数，推荐小于等于100;
excerpt_pure为纯净模式的截取字数，推荐字数为300;
excerpt_link为阅读更多按钮展示与否的开关。
# post_excerpt for index page
excerpt_cart: 80
excerpt_pure: 300
excerpt_link: true
六、其他page的使用
6.1归档页(archive)
Annie主题的归档页按年归档，不分页。当然，可以置参数archive_generator.per_page（站点配置文件）为1、2、3…..以达到分页目的。
Annie主题中无效，分页是对该页面[主页、归档页、标签页、分类页]的文章进行分页，即每次（每页）展示指定数量的文章
archive: 1
category: 1
tag: 1
archive_generator:
per_page: 10
tag_generator:
per_page: 0
category_generator:
per_page: 0
6.2分类页(categories)
执行命令$ hexo new page categories，创建分类页
$ hexo new page categories
编辑站点目录下的source/categories/index.md
---
title: categories
date: 2018-09-11 20:31:03
+ type: "categories"
---
6.3标签页(tags)
执行命令$ hexo new page tags，创建标签页
$ hexo new page tags
编辑站点目录下的source/tags/index.md
---
title: tags
date: 2018-09-11 21:41:02
+ type: "tags"
---
6.4关于页(about)
执行$ hexo new page about命令，创建关于页
$ hexo new page about
编辑站点目录下的source/about/index.md
---
title: about
date: 2018-09-11 20:30:08
---
---
+ <font color=#000000 size=4>这里可以添加介绍文字</font>
---
6.5相册页(gallery)
执行命令$ hexo new page gallery，创建相册页
$ hexo new page gallery
编辑站点目录下的source/gallery/index.md
---
title: gallery
date: 2019-11-21 21:54:19
+ type: "gallery"
---
打开文件data.json（Annie/source/plugin/gallerypage/data.json）, 按照json语法在数组[……]中添加gallery的图片数据，请设置合适的eWidth、eHeight的值。
[
{},
{
"thumbnail": "https://img.jpg", //小图路径
"enlarged": "https://img.jpg", //大图路径（可与小图一致）
"title": "百里守约", //图片标题
"categories": [{
"id": 9, //根据id来进行分类
"title": "百里玄策",
"photo_count": 41787, //可忽略
"links": { //可忽略
"self": "https://img.jpg",
"photos": "https://img.jpg"
}
}
],
"tWidth": 800.6130030959752, //小图相对宽度
"tHeight": 500, //小图相对高度
"eWidth": 3630, //大图相对宽度
"eHeight": 2907 //大图相对高度
},
{}
]
当然，你可以将该文件data.json移至其他目录，在主题配置文件中相应地修改路径gallery_data
# gallery page
# gallery_format: natural | square
gallery_format: natural
# one time to load 4 rows or other count, 0 to load img automatically when scrolling.(0,1,2,3,4,5,6......)
gallery_limit: 0
# data url
+ gallery_data: plugin/gallerypage/data.json
七、站内搜索
若此时仍未配置站内搜索，则执行命令，安装插件hexo-generator-search-zip
$ npm install hexo-generator-search-zip --save
编辑站点目录下的_config.yml，添加如下语句
search:
path: search.json
zipPath: search.zip
versionPath: searchVersion.txt
field: post
#field: post, page or all（3个可选参数）
编辑主题目录下的_config.yml，添加如下语句
# Local search
# Dependencies: https://github.com/flashlab/hexo-generator-search
local_search:
enable: true
# if auto, trigger search by changing input
# if manual, trigger search by pressing enter key or search button
trigger: auto
# show top n results per article, show all results by setting to -1
top_n_per_article: 2
八、文章页问题
8.1相关的文章
文章页将展示与当前文章具有相同分类、相同标签的系列文章，排序规则：分类>标签>时间>不相关文章。你可以决定是否使用该模块，posts_limit为显示的文章篇数，posts_excerpt为每篇文章的文字截取数量。
主题配置文件中：
# 04-POST
# post_relate
relate:
enable: true
posts_limit: 10
posts_excerpt: 120
<font color=#0099ff face="幼圆" size="3">只有全站博客文章篇数大于1且relate.enable为真时，该模块有效。</font>
8.2阅读量计数
对于leancloud_count，你必须设置appid、appkey；
对于busuanzi_count，你只需要开启它即可。
- leancloud计数
# post_count
leancloud_count:
+ enable: true
+ appid: 'dXz'
+ appkey: 'wzG'
like_post:
enable: true
+ visit_post:
enable: true
topN_post:
enable: true #param1 for topN_post
limit: 10 #param2 for topN_post
busuanzi_count:
enable: true
如果你使用过Valine评论插件，那么leancloud_count的使用十分简单。如果你没有使用过，请参考文章Hexo博客next主题添加文章阅读量统计功能创建leancloud应用，创建counter类，并获取其appid、appkey，且设置上面的appid、appkey为相应的值，最后开启visit_post。
- 卜蒜子计数
# post_count
leancloud_count:
enable: false
appid: 'dX--'
appkey: 'dX--'
like_post:
enable: true
visit_post:
enable: true
topN_post:
enable: true #param1 for topN_post
limit: 10 #param2 for topN_post
busuanzi_count:
+ enable: true
该模块放置于页脚，文章页面只显示文章的阅读量，其他页面只显示总访问量和访客数（等待完善）
8.3文章点赞
如果你完成了8.2阅读量计数的leancloud计数的设置，那么只需要开启like_post。
# post_count
leancloud_count:
enable: false
appid: 'dX--'
appkey: 'dX--'
+ like_post:
+ enable: true
visit_post:
enable: true
topN_post:
enable: true #param1 for topN_post
limit: 10 #param2 for topN_post
busuanzi_count:
enable: true
8.4文章排行
# post_count
leancloud_count:
enable: false
appid: 'dX--'
appkey: 'dX--'
like_post:
enable: true
visit_post:
enable: true
+ topN_post:
+ enable: true #param1 for topN_post
+ limit: 10 #param2 for topN_post
busuanzi_count:
enable: true
如果你完成了8.2阅读量计数的leancloud计数的设置，那么只需要开启topN_post。（文章阅读排行依赖于8.2阅读量计数）
8.5文章目录
若一篇文章的正文存在h1、h2、h3等标题，则文章页展示目录按钮。点击目录按钮，页面左侧展示文章目录。当屏幕宽度小于1024px或页面滚动高度大于文章正文高度时，页面隐藏文章目录。
# post_toc
post_toc:
enable: true
katelog: true
8.6数学公式
先设置主题配置文件的mathjax参数，再于文章的Front-matter中添加mathjax: true
# post_mathJax
mathjax:
+ enable: true
title: Annie主题使用说明
date: 2018-08-27 20:16:19
cover: /img/post-cover/74.jpg
+ mathjax: true
categories: HEXO博客
tags:
- 说明
- other tag
8.7代码块高亮
综合考虑hexo自身的代码高亮插件和hexo-pism-plugin高亮插件的特性及代码块解析规则，2019-04-27日更新后，主题弃用hexo-prism-plugin插件，参考&使用了next主题的代码高亮风格。
- 编辑
主题配置文件，选择并设置highlight_theme的值
# post_code
# highlight_theme: normal | night | night blue | night bright | night eighties
+ highlight_theme: night bright
code_copy:
enable: true
- 编辑
站点配置文件，设置highlight的值
# Writing
new_post_name: :title.md # File name of new posts
default_layout: post
titlecase: false # Transform title into titlecase
external_link: true # Open external links in new tab
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:
8.8代码块复制
只有theme.code_copy.enable为真且config.highlight.enable为真时，代码块的复制功能才有效
# post_code
# highlight_theme: normal | night | night blue | night bright | night eighties
highlight_theme: night bright
code_copy:
+ enable: true
8.9文章评论功能
Hexo-theme-Annie主题集成了gitalk、DesertsP版的valine、livere评论插件。
| 序号 | 评论插件 | 使用方法 |
|---|---|---|
| 1 | gitalk | 正式文档、Annie主题+Gitalk |
| 2 | valine | 正式文档、加个Valine评论系统 |
| 3 | livere | 为Hexo博客添加LiveRe评论系统 |
注：对于gitalk，你必须设置clientID、clientSecret；对于Valine，你必须设置appid、appkey；对于livere，你必须设置livere_uid。
8.10文章分享功能
Hexo-theme-Annie主题集成了addThis、baiduShare、shareThis、socialShare分享插件。
| 序号 | 分享插件 | 使用方法 |
|---|---|---|
| 1 | addThis | 登录addThis获取应用的账户id |
| 2 | baiduShare | 直接使用 |
| 3 | shareThis | 登录shareThis获取应用的账户id |
| 4 | socialShare | 直接使用 |
注：使用addThis、shareThis时，应注意关闭浏览器的内容拦截插件。
九、站点分析
| 序号 | 分析插件 | 使用方法 |
|---|---|---|
| 1 | 卜算子分析 | 直接使用 |
| 2 | baidu_analytics | 需获取账户id |
| 3 | cnzz_analytics | 需获取账户id |
| 4 | google_analytics | 需获取账户id |
| 5 | tencent_analytics | 需获取账户id |
十、其他的问题
10.1社交链接
直接增加相应的社交图标、社交链接即可
# social
social:
github:
url: http://github.com/
icon: fa fa-github
weibo:
url: http://github.com/
icon: fa fa-weibo
pinterest:
url: http://github.com/
icon: fa fa-pinterest
instagram:
url: http://github.com/
icon: fa fa-instagram
twitter:
url: http://github.com/
icon: fa fa-twitter
rss:
url: /atom.xml
icon: fa fa-rss
+ digg:
+ url: http://github.com/
+ icon: fa fa-digg
10.2RSS订阅
主题将使用到 hexo-generator-feed 插件来生成atom.xml 文件。执行命令安装该插件：
npm install hexo-generator-feed --save
编辑站点配置文件，添加相应的参数：
+feed:
+ type: atom
+ path: atom.xml
+ limit: 20
执行 hexo clean & hexo g重新生成博客文件，你将在 hexo/public/ 目录下看到 atom.xml 文件，说明你已经安装成功了。 （rss的社交链接见于上一节：1. 社交链接）
10.3版权声明
对于copyright ，since为站点建立年份，cotent_author为站点作者。
_config.yml
# copyright
since: 2018
cotent_author: author
10.4点击页面浮现桃心
# when click, emerge heart
love:
enable: true
# back to top
totop:
enable: true
对于love，若设置为true，则点击页面时，会出现随机颜色的桃心💚💛💕。对于totop，若设置为true，则启用返回顶部按钮。
十一、开发定制问题
11.1主题项目结构
ANNIE
├─languages #国际化语言支持
├─layout #html页面模板
│ └─_partial
│ ├─custom
│ ├─plugin
│ │ ├─clipboard
│ │ ├─comment
│ │ ├─share
│ │ └─statistics
│ ├─post
│ └─widget
├─scripts #站点脚本
└─source #主题资源
├─css
│ └─_highlight
├─img
│ ├─post-cover
│ ├─quote
│ └─random
├─js
└─plugin
├─chinese
├─clipboard
├─comment
├─fancybox
├─gallerypage
│ └─images
├─imgLazyLoader
├─imgResize
├─love
├─motto
├─nicescroll
├─search
├─toc
└─vibrant
Annie主题基于hexo 3.8.0、ejs、styl开发而成。一般来说，如果你想修改页面的html结构，请到layout目录下添加或修改相应的ejs文件； 如果你想修改页面元素的css样式，请到source/css目录下添加或修改相应的styl文件；如果你想添加一些js代码，原则上，自定义代码片段应添加于source/js/main.js文件中，引入的js文件应放置于source/plugin目录下
11.2主题字体问题
主题整体字体大小，修改html标签的font-size属性
html {
- font-size: 16px;
+ font-size: 14px;
}
主题整体字体族，修改body标签的font-family属性
body {
- font-family: Ovo, Georgia, STZhongsong, "Microsoft YaHei", serif;
+ font-family: "PingFang SC", "Microsoft YaHei";
}
文章详情页字体族，修改#layout-post类的font-family属性
#layout-post {
+ font-family: "Source Sans Pro", "Segoe UI";
}
你可以检索style文件，查询相应的标签或类，进而设置相应元素的属性。
11.3页头菜单颜色
页头菜单颜色会根据背景的主题色变化非黑即白。亦即主题色为浅色时，字体为黑；主题色为深色时，字体为白。你可以参考main.js中函数Annie_ColorExtraction(img)。
