Annie主题详细使用说明

开始之前的说明

0. 文中所有的指令都是在Hexo文件夹下开启的命令行中执行的

1. 代码对比

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

2. Bash指令

指令

3. 输出信息

输出信息

4. 提示信息

这是一个info提示

这是一个success提示

这是一个warning提示

这是一个danger提示

5. 文件目录

序号	名词	说明	目录
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标签进行相应设置。

1. 使用固定图片，请确保参数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/

2. 使用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/

3. 使用自定义随机图片，请确保参数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

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

8.2阅读量计数

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

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。

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

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

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主题的代码高亮风格。

1. 编辑主题配置文件，选择并设置highlight_theme的值

   # post_code
   # highlight_theme: normal | night | night blue | night bright | night eighties
   + highlight_theme: night bright
   code_copy:
       enable: true

2. 编辑站点配置文件，设置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)。