# 新手上路
::: tip 前言
- 修改配置文件、安装新的依赖等,都需要重启 Hexo 服务器。
- 没有特别说明,配置项从 `v1.0.0` 版本开始支持。
- 稳定的配置使用 标明,表示基本不会变动。不稳定的配置使用 标明,表示未来可能会变动甚至删除。目前还不支持的配置使用 标明。被废弃的配置使用 标明。最早开始支持的版本号使用 标明。与主题无关的配置项使用 标明。
:::
## 配置文件
首先,你需要分清下面这两个配置文件的作用:
- Hexo 根目录下的 `_config.yml`。这是 Hexo 配置文件,其配置对整个网站生效。
- Stun 根目录下的 `_config.yml`。这是主题配置文件,其配置只对主题生效。
在接下来的文档中,会说明你应该修改哪一个配置文件。
## 添加新页面
Stun 主题内置有:分类页、标签页。默认没有启用。如果想启用它们,你需要执行以下步骤:
1. 执行命令
在 Hexo 根目录下:
``` bash
# 启用分类页,执行这条指令
$ hexo new page categories
# 启用标签页,执行这条指令
$ hexo new page tags
```
2. 修改 Front-Matter
在 Hexo 根目录下,找到 `source/categories` 或 `source/tags` 文件夹中的 Markdown 文件,设置 Front-Matter:
```
---
# 如果是分类页,设置这个
type: "categories"
# 如果是标签页,设置这个
type: "tags"
---
```
3. 修改主题配置文件
将 `categories` 或 `tags` 对应项取消注释:
``` yaml
# `||` 分隔符之前是页面路径,`||` 分隔符之后是图标
# 用法(有图标): `Key: /路径/ || fa(s|r|l|d|b) fa-图标名称`
# 用法(无图标): `Key: /路径/`
# fas far fal fad fab 是 FontAwesome 5.x 中图标的前缀,你需要根据具体图标自行设置
# 查找图标名称,请访问:https://fontawesome.com/icons
menu:
home: / || fas fa-home
archives: /archives/ || fas fa-folder-open
# categories: /categories/ || fas fa-layer-group
# tags: /tags/ || fas fa-tags
```
如果你想添加自定义页面,需要执行以下步骤:
以添加**阅读**页面为例。
1. 修改主题配置文件
``` yaml
menu:
reading: /reading/ || fas fa-book
```
2. 生成页面文件
在 Hexo 根目录下执行指令:
``` bash
# 这里的 reading 对应上一步你设置的路径名称
$ hexo new page reading
```
3. 国际化设置
找到 `languages` 目录下的语言文件,根据你网站使用的语言选择对应的语言文件,例如:
`zh-CN.yml`:
``` yaml
menu:
reading: 阅读
```
这样就添加好了自定义页面。
另外,你可以通过修改主题配置文件里的 `menu_settings` 选项,来设置图标和文字是否显示:
``` yaml
menu_settings:
# 是否只显示图标
icon_only: false
# 是否只显示文字
text_only: false
```
## Favicon
主题默认使用 Stun 的 Logo 作为网站图标,你需要换成自己的。
建议你在 **Hexo 根目录**下的 `source` 目录中,新建一个文件夹用于放置图片,例如 `assets`,然后你就可以通过 `/assets/xxx.png` 这样的路径使用图片。将图片路径填入你的主题配置文件:
``` yaml
favicon:
small: /assets/favicon-16x16.png # 16x16 像素大小的图片
medium: /assets/favicon-32x32.png # 32x32 像素大小的图片
# ! -----------------------------------------------------------------------
# 下面这些配置项默认不启用,你需要准备好相应的图片后才能启用,也可以直接忽略。
# ! -----------------------------------------------------------------------
# apple_touch_icon: /assets/apple-touch-icon.png # 180x180 像素大小的图片
# safari_pinned_tab: /assets/stun-logo.svg # SVG 格式的图片
# msapplication: /assets/favicon-144x144.png # 144x144 像素大小的图片
```
## 网站顶部设置
修改主题配置文件:
``` yaml
header:
enable: true
show_on:
# 在文章页面是否显示网站顶部
post: true
# 网站顶部的高度(设置为百分数,表示所占屏幕高度的百分比。支持所有 CSS 长度单位)
height: 80%
# 顶部背景图片
bg_image:
enable: false
# 填写图片路径或链接
url:
# 顶部背景图的遮罩效果
mask:
enable: false
# 透明度(取值:0 ~ 1)
opacity: 0.5
nav:
# 顶部导航栏的高度(支持所有 CSS 长度单位)
height: 50px
# 导航栏的背景颜色(吸顶时)
bg_color: "#333"
# 提示向下滚动的图标
scroll_down_icon:
enable: false
# 查找图标名称,请访问:https://fontawesome.com/icons
name: fas fa-angle-down
# 是否启用动画
animation: true
```
- 如果设置 `header.enable: false`,则所有页面中都不显示网站 Header(只显示顶部导航栏)。效果如下:
![](https://raw.githubusercontent.com/liuyib/picBed/master/hexo-theme-stun/doc/20200203194337.jpg)
- 如果设置 `header.enable: true` 和 `header.show_on.post: false`,则文章页不显示网站 Header,其它页面仍会显示。效果如下:
**文章页:**
![](https://raw.githubusercontent.com/liuyib/picBed/master/hexo-theme-stun/doc/20200203194337.jpg)
**首页(其他页面):**
![](https://raw.githubusercontent.com/liuyib/picBed/master/hexo-theme-stun/doc/20200203194338.jpg)
::: warning
下面是一些选项的版本支持情况和注意事项:
- `header.mask`
- `header.blur_effect`
- `header.scroll_down_icon`
- `header.nav_height` ,修改于
- `header.enable` ,`header.show_on`
> 当 `header.enable` 或 `header.show_on` 被设为 `false` 时,不兼容 `pjax.avoid_banner` 选项。
:::
### 指定顶部图
如果想要为某个页面或某篇文章指定顶部图,你需要在页面或文章 Markdown 源文件的 [Front-Matter](https://hexo.io/zh-cn/docs/Front-Matter) 中,添加 `top_image` 选项,然后填入的图片路径或链接即可。例如:
```
---
title: Hello Stun
top_image: https://xxxxx.jpg
---
```
## 网站主体设置
修改主题配置文件:
``` yaml
body:
# 网站主体背景图片
bg_image:
enable: false
# 填写图片路径或链接
url: https://xxxxx.png
# 是否固定背景图片(相当于设置 CSS 属性 position: fixed)
fixed: true
# 是否重复显示背景图片(相当于设置 CSS 属性 background-repeat: repeat/no-repeat)
repeat: false
# 网站主体背景图片的遮罩效果
mask:
enable: false
# 透明度(取值:0 ~ 1)
opacity:
# 默认情况下,网站主体背景图片的透明度
default: 0.1
# 夜晚模式下,网站主体背景图片的透明度
night_mode: 0.6
```
## 侧边栏设置
修改主题配置文件:
``` yaml
sidebar:
enable: true
# 侧边栏位置,可选值有:left 或 right
position: right
# 侧边栏吸顶时,距离页面顶部的距离(只支持 px 单位)
offsetTop: 20px
# 是否显示水平分割线
horizon_line: false
```
::: danger
其中,配置项 `sidebar.width` 在 `v1.6.0` 版本废弃。代替的配置是 `layout.sidebar`。
:::
### 作者信息
侧边栏默认头像是 Stun 的 Logo,你需要换成自己的,修改主题配置文件:
``` yaml
author:
enable: true
# 侧边栏头像
avatar:
# 填写图片路径或链接
url: https://xxxxx.png
# 是否显示为圆形
rounded: true
# 头像透明度(取值:0 ~ 1)
opacity: 1
# 鼠标经过时的动画,可选值:turn 或 shake
animation: turn
# 格言(可以是任意一句想写的话)
motto: hello world
```
### 社交链接
修改主题配置文件:
``` yaml
# `||` 分隔符之前是具体链接,`||` 分隔符之后是图标。
# 用法(有图标): `Key: /路径/ || fa(s|r|l|d|b) fa-图标名称`
# 用法(无图标): `Key: /路径/`
# fas far fal fad fab 是 FontAwesome 5.x 中图标的前缀,你需要根据具体图标自行设置。
# 查找图标名称,请访问:https://fontawesome.com/icons
#
# 如果你找不到想要的图标,可以考虑用文字来代替图标显示,用法:
# 通过添加 `origin:` 前缀即可显示文字。例如:`origin:知` 会以 `知` 代替图标显示。
social:
github: https://github.com/ || fab fa-github
google: https://plus.google.com/ || fab fa-google
twitter: https://twitter.com/ || fab fa-twitter
youtube: https://youtube.com/ || fab fa-youtube
# segmentfault: https://segmentfault.com/ || origin:sf
# weibo: https://weibo.com/ || fab fa-weibo
# zhihu: https://www.zhihu.com/ || origin:知
# wechat: yournumber || fab fa-weixin
# telegram: yournumber || fab fa-telegram
# qq: yournumber || fab fa-qq
# 社交链接的设置
social_setting:
# 是否启用社交链接
enable: true
# 是否只显示图标
icon_only: true
```
::: danger
其中,配置项 `social_setting.text_align` 在 `v1.2.0` 版本废弃。
:::
当你添加一个默认没有的社交链接时,需要进行国际化设置。这里以添加链接 `掘金` 为例,步骤如下:
1. 修改主题配置文件
``` yaml
social:
juejin: https://juejin.im/timeline || origin:掘
```
2. 国际化设置
找到 `languages` 目录下的语言文件,根据你网站使用的语言选择对应的语言文件,例如:
`zh-CN.yml`:
``` yaml
social:
juejin: 掘金
```
> 这里的国际化设置,对应于鼠标经过图标时,显示的文字。
效果如下:
![](https://raw.githubusercontent.com/liuyib/picBed/master/hexo-theme-stun/doc/20190717165333.png)
## 网站底部设置
修改主题配置文件:
``` yaml
footer:
# 背景图片
bg_image:
enable: false
# 填写图片路径或链接
url: https://xxxxx.png
# 遮罩效果
mask:
enable: false
# 遮罩透明度 (取值: 0 ~ 1).
opacity: 0.5
# 版权信息
copyright:
enable: true
# 显示的文字信息,例如:xxx All Rights Reserved
# 如果不设置,将显示 Hexo 配置文件中 author 项的内容
text:
# 开始时间(如果不设置,将使用最新的年份)
since:
# 结束时间(如果不设置,将使用最新的年份)
end:
# 日期和版权之间的图标
icon:
enable: true
# 查找图标名称,请访问:https://fontawesome.com/icons
name: fas fa-heart
# 心跳动画
animation: false
# 请使用包裹值(支持所有 CSS 颜色单位)
color: "#ff0000"
# Hexo 链接(Powered by Hexo)
powered:
enable: true
# 显示版本号(例如:vX.X.X)
version: true
# 主题链接(Theme - Stun)
theme:
enable: true
# 显示版本号(例如:vX.X.X)
version: true
# 备案信息(只有中国开发者会用到)详情: http://www.miitbeian.gov.cn/
beian:
enable: false
# 备案 XXXXXXXX 号
icp:
# 任何自定义文本,支持 HTML(例如:托管于 Github Pages)
custom:
enable: false
# 自定义文本内容
text:
```
效果如下:
![](https://raw.githubusercontent.com/liuyib/picBed/master/hexo-theme-stun/doc/20190623192514.png)
## 返回顶部
修改主题配置文件:
``` yaml
back2top:
enable: true
# 显示的图标
icon:
# 查找图标名称,请访问:https://fontawesome.com/icons
name: fas fa-rocket
# 火箭发射动画
animation: true
# 图标的旋转角度(角度的单位是:deg)
rotate: -45deg
# 请使用引号包裹值(支持所有 CSS 颜色单位)
color: "#49b1f5"
hover_color: "#fc6423"
```
## 文章摘要
如果想要保留文章摘要,你需要在文章的 Markdown 源文件中添加 `` 标记。标记之前的部分都会被保留为文章摘要,显示在文章列表中。
::: danger
从 `v2.0.0-rc.0` 版本开始,主题不再提供自动保留摘要的功能。
:::
---
到这里就完成了最基本的配置,如果你还想更详细的配置主题,请继续向后阅读文档。