Annie主题使用说明

零、准备工作

开始之前，你应该预先理解下列标签的意义：

0.1 代码对比

  This is a diff block.
+ This is add!
- This is subtract!

0.2 信息提示

!!!info
这是一个info提示

这是一个success提示

这是一个warning提示

这是一个danger提示

0.3 名词约定

序号	名词	说明	目录
1	站点配置文件	站点目录下的_config.yml文件	hexo/_config.yml
2	主题配置文件	主题目录下的_config.yml文件	hexo/themes/Annie/_config.yml
3	页头背景	网页页头背景	html/header(网页标签)

一、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

二、页头背景图片

文章详情页的页头背景图片为该文章的封面图，其他页的页头背景图片为随机图片或固定图片。原则上，使用固定图片时，应将参数mode设为normal，然后设置normal_url的路径；使用随机图片时，应将参数mode设为random，然后设置random_url的路径。

warning!
注意跨域问题，尽量不使用跨域的图片（即背景图片和网页最好托管在一起，存放于同一服务器）

0.1 使用固定图片，请确保参数mode设为normal，然后设置参数normal_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/

0.2 使用unplash随机图片，请确保参数mode设为normal，然后设置参数normal_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: https://source.unsplash.com/collection/954550/1920x1080
    random_max: 110 
    random_url: https://sariay.github.io/Random-img/

0.3 使用自定义随机图片，请确保参数mode设为random，然后设置参数random_max、random_url的值

• 第一步、fork 随机图片集 ；
• 第二步、开启你所fork的仓库的page服务；
• 第三步、获取相对地址；
• 第四步、设置random_url为获得的相对地址。

# background_image
# /img/01.jpg
# https://source.unsplash.com/collection/954550/1920x1080
# https://sariay.github.io/Random-img/
# May be cause CROS bug!
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/。

三、随机名言与当地时间

每次刷新网页，网页页头展示一条随机名言，获取并展示该时区的标准时间。

# 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

四、预加载遮罩

预加载遮罩的作用为，确保背景图片加载完成和背景构造完成。当背景加载并构造完成时，主题立即移除遮罩。预加载行为的超时时间默认设为10s，即最多10s左右后，不管背景是否加载并构造完成，主题都移除遮罩。你可以决定是否使用：

# 02-PROLOADER
# animation: spinner, transition or cyclic
preloader:
    enable: true
    animation: transition

五、首页的使用

首页文章展示有两种模式：图文模式cart和纯净模式pure。默认图文模式（cart），你只需编辑主题配置文件，设置index-style的参数，即可使用或扩展指定的主页文章展示模式。

# 03-INDEX
# index-style: pure, cart or poem
+index_style: cart

# index_cart_cover
cover: /img/cart_cover.jpg

5.1 文章封面图

title: Annie主题使用说明
date: 2018-08-27 20:16:19
+cover: /img/post-cover/74.jpg
categories: HEXO博客
tags: 说明

cover参数值即为图片路径，路径可为相对路径或绝对路径。

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文字的截断

# post_excerpt for index page
excerpt_cart: 80
excerpt_pure: 300   
excerpt_link: true

excerpt_cart为图文模式的截取字数，推荐小于等于100。excerpt_pure为纯净模式的截取字数，推荐字数为300。excerpt_link为阅读更多按钮展示与否的开关。

六、归档页的使用

Annie主题的归档页按年归档，不分页。当然，可以置参数archive_generator.per_page（站点配置文件）为1、2、3…..以达到分页目的。

warning!
Annie主题中无效，分页是对该页面[主页、归档页、标签页、分类页]的文章进行分页，即每次（每页）展示指定数量的文章

archive: 1
category: 1
tag: 1

archive_generator:
  per_page: 10

tag_generator:
  per_page: 0

category_generator: 
  per_page: 0

七、分类页的使用

执行命令，创建分类页

$ hexo new page categories

然后编辑站点目录下的source/categories/index.md，添加如下Front-matter

title: categories
date: 2019-03-30 19:25:34
+ layout: categories
+ type: categories

八、标签页的使用

执行命令，创建标签页

$ hexo new page tags

然后编辑站点目录下的source/tags/index.md，添加如下Front-matter

title: tags
date: 2019-03-30 19:25:34
+ layout: tags
+ type: tags

九、关于页的使用

执行命令，创建关于页

$ hexo new page about

然后编辑站点目录下的source/about/index.md，添加如下Front-matter

title: about
date: 2019-03-30 19:25:34
+ layout: about
+ type: about

十、相册页的使用

执行命令，创建相册页

$ hexo new page gallery

然后编辑站点目录下的source/gallery/index.md，添加如下Front-matter

title: gallery
date: 2019-03-30 19:25:34
+ layout: gallery
+ type: gallery

打开文件data.json（Annie/source/plugin/gallerypage/data.json）, 按照json语法在数组[……]中添加gallery的图片数据，请设置合适的eWidth、eHeight的值。

warning!
注意：下列注释在json文件中无效，使用时请去掉注释。（注释仅为说明）

[
{}, 
{
        "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

十二、文章页问题

12.1 分类和标签

title: Annie主题使用说明
date: 2018-08-27 20:16:19
cover: /img/post-cover/74.jpg
+ categories: HEXO博客
+ tags: 
+	- 说明
+	- other tag

分类页的HEXO博客字段来源于文章Front-matter中的categories参数值，标签页的说明字段来源于文章Front-matter中的tags参数值。hexo博客框架只支持一个同级分类，支持多个同级标签。

12.2相关的文章

文章页将展示与当前文章具有相同分类、相同标签的系列文章，排序规则：分类>标签>时间>不相关文章。你可以决定是否使用该模块，posts_limit为显示的文章篇数，posts_excerpt为每篇文章的文字截取数量。

# 04-POST
# post_relate
relate:
    enable: true
    posts_limit: 10
    posts_excerpt: 120
info!

只有全站博客文章篇数大于1且relate.enable为真时，该模块有效。

12.3 阅读量计数

对于leancloud_count，你必须设置appid、appkey；对于busuanzi_count，你只需要开启它即可。

0.1 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。

0.2 卜蒜子计数

# 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

该模块放置于页脚，文章页面只显示文章的阅读量，其他页面只显示总访问量和访客数（等待完善）

12.4文章点赞

如果你完成了12.3阅读量计数的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

12.5 文章排行

# 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

如果你完成了12.3阅读量计数的leancloud计数的设置，那么只需要开启topN_post。（文章阅读排行依赖于12.3阅读量计数）

info!
该模块放置于搜索页面，你可按需定制

12.6文章目录

若一篇文章的正文存在h1、h2、h3等标题，则文章页展示目录按钮。点击目录按钮，页面左侧展示文章目录。当屏幕宽度小于1024px或页面滚动高度大于文章正文高度时，页面隐藏文章目录。

# post_toc
post_toc:
    enable: true
    katelog: true

12.7数学公式

请先设置主题配置文件的mathjax参数，再于文章的Front-matter中添加mathjax: true

# post_mathJax
mathjax:
+  enable: true
DIFF
title: Annie主题使用说明
date: 2018-08-27 20:16:19
cover: /img/post-cover/74.jpg
+ mathjax: true
categories: HEXO博客
tags: 
	- 说明
	- other tag

12.8代码块高亮

综合考虑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的值

_config.yml
# 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:
warning!

请尽可能地指定相应代码块的语言类型（html、js、c++、java……），以使高亮风格有效。

12.9代码块复制

只有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

12.10文章评论功能

Hexo-theme-Annie主题集成了gitalk、DesertsP版的valine、livere评论插件。

序号	评论插件	使用方法
1	gitalk	正式文档、Annie主题使用Gitalk
2	valine	正式文档、加个Valine评论系统
3	livere	为Hexo博客添加LiveRe评论系统

warning!

对于gitalk，你必须设置clientID、clientSecret；对于Valine，你必须设置appid、appkey；对于livere，你必须设置livere_uid。

12.11文章分享功能

Hexo-theme-Annie主题集成了addThis、baiduShare、shareThis、socialShare分享插件。

序号	分享插件	使用方法
1	addThis	登录addThis获取应用的账户id
2	baiduShare	直接使用
3	shareThis	登录shareThis获取应用的账户id
4	socialShare	直接使用

info!
使用addThis、shareThis时，应注意关闭浏览器的内容拦截插件。

十三、站点分析

序号	分析插件	使用方法
1	卜算子分析	直接使用
2	baidu_analytics	需获取账户id
3	cnzz_analytics	需获取账户id
4	google_analytics	需获取账户id
4	tencent_analytics	需获取账户id

十四、其他的问题

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

14.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. 社交链接）

14.3版权声明

对于copyright ，since为站点建立年份，cotent_author为站点作者。

_config.yml
# copyright  
since: 2017
cotent_author: Sariay

14.4点击页面浮现桃心

# when click, emerge heart
love:
    enable: true

# back to top
totop:
    enable: true

对于love，若设置为true，则点击页面时，会出现随机颜色的桃心💚💛💕。对于totop，若设置为true，则启用返回顶部按钮。

十五、开发定制问题

15.1主题项目结构

Anniehexo-theme-Annie
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目录下。

15.2主题字体问题

主题整体字体大小，修改html标签的font-size属性

_main.styl
html {
-   font-size: 16px;
+   font-size: 14px;
}

主题整体字体族，修改body标签的font-family属性

_main.styl
body {
-   font-family: Ovo, Georgia, STZhongsong, "Microsoft YaHei", serif;
+   font-family: "PingFang SC", "Microsoft YaHei";
}

文章详情页字体族，修改#layout-post类的font-family属性

_post.styl
#layout-post {
+   font-family: "Source Sans Pro", "Segoe UI";
}

你可以检索styl文件，查询相应的标签或类，进而设置相应元素的属性。

15.3页头菜单颜色

页头菜单颜色会根据背景的主题色变化非黑即白。亦即主题色为浅色时，字体为黑；主题色为深色时，字体为白。你可以参考main.js中函数Annie_ColorExtraction(img)。（修改、完善它）