blog-hexo/source/_posts/Cosy-Starter-Guide.md
2024-03-15 15:38:52 +08:00

660 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
title: Cosy 入门
top: 2
categories:
- Hexo
status: doing
abbrlink: 59577
---
# 写在前面 💡
由于 hexo 的大版本更新, hexo-theme-cosy也有 `1.x.x``2.x.x` 版本
- hexo 6.3.0 -> hexo-cosy-theme 1.x.x
- hexo 7.0.0 -> hexo-cosy-theme 2.x.x
请确认您使用的 `hexo`版本、`hexo-theme-cosy`版本,以及 `_config.yml` 是否正确
> 如果 `package.json` 是正确的,看看是否是 `xxx.lock` 文件锁了版本
# 安装
hexo-theme-cosy 主题 `1.x.x 版本` 是在 Hexo `6.3.0` 版本下进行的开发、测试的。根据可靠消息Hexo `7.0.0` 版本不兼容 😂
如您使用的是 `6.3.x` 版本的 hexo 系统,遇到如下情况:
- 代码高亮不正常
- 搜索显示不正常
请检查 `package.json``dependencies` 中的 hexo 版本号,修改完 `6.3.0`,然后 `npm install` 重新安装依赖即可。
hexo-theme-cosy 主题的 github仓库、npm已经更新到 `2.x.x` 版本,默认是在 Hexo `7.0.0` 版本下开发,官方的代码高亮配置文件有所改变,会导致 `代码高亮` 失效,如果您使用的是 `7.0.x` 版本的 Hexo请调整如下配置
```yml
# v7.0.0
syntax_highlighter: prismjs
prismjs:
preprocess: true
line_number: true
line_threshold: 0
tab_replace: ''
# v6.3.0
# highlight:
# enable: false
# line_number: true
# auto_detect: false
# tab_replace: ""
# wrap: true
# hljs: false
# prismjs:
# enable: true
# preprocess: true
# line_number: true
# line_threshold: 0
# tab_replace: ""
```
## 使用 npm 安装
在主题的根目录
```yml
npm i hexo-theme-cosy
```
此外,需要新建一个 `_config.cosy.yml`,用来定义`主题配置`
最后,修改`hexo`的配置: `_config.yml`,添加下面的内容:
```yml
theme: cosy
algolia:
appId: 你的
apiKey: 你的
adminApiKey: 你的
SearchOnlyAPIKey: 你的
chunkSize: 5000
indexName: 你的algolia的index
fields:
- content
- excerpt:strip
- categories
- title
- permalink
- slug
- tags
- title
```
## 传统方式 - 安装 Hexo 安装主题
将主题 `hexo-theme-cosy` 文件夹复制目录的 `themes` 目录下,然后在 `Hexo``_config.yml` 中修改下主题配置即可
```yml
# 找到 theme 配置项
theme: hexo-theme-cosy
```
## 获取 Cosy
- 进入 [Cosy 代码仓库](https://github.com/17px/hexo-theme-cosy/tree/main),了解最新的主题开发进度
- 在 [发布页面](https://github.com/17px/hexo-theme-cosy/releases) 下载 `hexo-theme-cosy.zip`
- 解压至站点的 `themes` 目录下
- 在 Hexo 的 `_config.yml` 中启用
# hexo 配置
`Hexo``_config.yml` 中调整
## 基础配置
```yml
# 网页标题
title: 17px blog
# 侧边栏顶部显示
subtitle: "Mozzie"
# 用于SEO的html元描述
description: ""
# 用于SEO的html关键字
keywords:
# 文章版权声明显示作者名称
author: Mozzie
# 在此处设置您的网站url
url: https://maxshader.com
```
## 语言
你可以在 `hexo-theme-cosy/languages` 中找到不同的语言文件,如果想切换语言,在配置文件中,填入 `yml` 的文件名
> hexo-theme-cosy v2版本只支持 zh-CN 和 en其他语言不再支持
```yml
language: en
```
## 文章语法高亮
关闭hexo默认的highlight.js语法高亮下面的配置基于 `hexo v6.3.0` 版本
```yml
highlight:
enable: false
line_number: true
auto_detect: false
tab_replace: ""
wrap: true
hljs: false
prismjs:
enable: true
preprocess: true
line_number: true
line_threshold: 0
tab_replace: ""
```
`7.0.0` 版本请使用这个配置:
```yml
# v7.0.0
syntax_highlighter: prismjs
prismjs:
preprocess: true
line_number: true
line_threshold: 0
tab_replace: ''
```
# Cosy 主题配置
注意:
- 采用 `npm` 的方式进行了主题安装那么是针对hexo根目录 `_config.cosy.yml`
- 采用传统方式安装,则是针对 `/hexo-theme-cosy/_config.yml`
## 文章分类图标
> 可以在 [xicon](https://www.xicons.org/) 获取丰富的图标
在`主题_config.yml`文件中,添加`分类名称`和`图标svg`的映射,如值设置为 `false`,代表不显示该分类
```yml
category_meta:
foo: <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 24 24"><g fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 17v1a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-1"></path><path d="M8 16h8"></path><path d="M8.322 12.582l7.956.836"></path><path d="M8.787 9.168l7.826 1.664"></path><path d="M10.096 5.764l7.608 2.472"></path></g></svg>
bar: false
```
## 网站图标 favicon
- 支持 `svg`
- 支持 `图片url`,如:`/img/favicon.png`
```yml
favicon: ''
```
## 主题色 🆕 (v2新增)
默认是针对 `css` 的变量 `var(--color-primary)` 进行全局主题色控制,保持多样性 😁
```yml
# 基佬紫,天下无敌
color: hsl(238,50%,56%)
```
## ICP备案号
😁 如不需要备案号,可直接删除
```yml
icp: 苏ICP备xxxxxxx号-x
```
## 首页底部文字 🆕
> v2版本移除了改配置默认显示到文章页底部
😁 如不需要,可直接删除,或者改为 `false`
```yml
motto: false
```
## 文章版权申明 🆕
v1 版本默认开启,当 `enable: false`,默认关闭
> v2 版本移除该配置以及模块
```yml
postCopyright:
enable: true
license: CC BY-NC-SA 4.0
license_url: https://creativecommons.org/licenses/by-nc-sa/4.0/
```
## katex 数学公式
可自行配置 `cdn`,全局默认关闭该插件
```yml
katex:
jsCdn: //cdn.jsdelivr.net/npm/katex@0.13.18/dist/katex.min.js
cssCdn: //cdn.jsdelivr.net/npm/katex@0.13.18/dist/katex.min.css
```
为了加载速度,如果文章需要用到插件,请在文章头部增加,如
```markdown
---
use: katex
---
```
## mermaid 流程图
在撰写时,请使用 `{% mermaid %}``{% endmermaid %}` 包裹,全局默认关闭该插件
```markdown
{% mermaid %}
graph TD;
A --> B;
A --> C;
B --> D;
C --> D;
{% endmermaid %}
```
相应配置如下
```yml
mermaid:
# 默认使用 neutral可选配置default | dark | forest | neutral
theme: neutral
cdn: //cdn.jsdelivr.net/npm/mermaid@10.4.0/dist/mermaid.min.js
```
为了加载速度,如果文章需要用到插件,请在文章头部增加,如
```markdown
---
use: mermaid,katex...
---
```
## valine 文章评论
首先需要注册 `LeanCloud` 国际区用户,创建数据库
请根据相关地区法规,酌情,全局默认关闭该插件
```yml
valine:
# 替换
appId: appId
# 替换
appKey: appKey
avatar: monsterid
cdn: //unpkg.com/valine@latest/dist/Valine.min.js
# 替换
serverURLs: //xxxxxxxx.api.lncldglobal.com
```
为了加载速度,如果文章需要用到插件,请在文章头部增加,如
```markdown
---
use: valine,mermaid...
---
```
# algolia搜索
博客自带的本地搜索,基于前端开发,存在或多或少的问题,建议换成 `algolia`,免费账户 总共有 `10,000` 条记录,每月有 `100,000` 的操作数
## 关闭搜索
主页左侧导航栏不再显示搜索,通知相关资源不会加载,在主题 `_config.yml` 中:
```yml
search: false
```
## 注册 & 获取 Key
1. 创建一个新的 `Index`,例如 `hex-blog`
2. 复制并保存:
- Application ID
- Search-Only API Key
- Admin API Key
- Usage API Key
![API Keys](/img/algolia-api-keys.png)
3. 替换配置
`Hexo``_config.yml` 中加入
```yml
algolia:
# 替换
appId: Application ID
# 替换
apiKey: Usage API Key
# 请勿泄露,用于上报,替换
adminApiKey: Admin API Key
# 替换
SearchOnlyAPIKey: Search-Only API Key
chunkSize: 5000
# 替换
indexName: hex-blog
fields:
- content
- excerpt:strip
- categories
- title
- permalink
- slug
- tags
- title
```
## 安装 hexo-algoliasearch-next
这是 Hexo 博客帖子索引插件,自动化提交索引到 Algolia
> 如出遇到问题,可阅读 [hexo-algoliasearch-next 仓库](https://github.com/Becavalier/hexo-algoliasearch-next) 最新说明
安装命令:
```bash
npm install hexo-algoliasearch-next --save
```
## 使用 algolia
在每次博客发布之前,进行索引上传的操作,命令通常如下
```bash
hexo clean
hexo generate
hexo algolia
```
# 🇨🇳 和风天气 Widget
Cosy 主要针对国内用户,在首页集成了和风天气的卡片,通过 [和风天气开发服务](https://dev.qweather.com/docs/start/) 注册
注册完成后,在配置中填入你的 `appKey``cityCode(城市代码)`
```yml
weather:
enable: true
# 替换
cityCode: cityCode
appKey: appKey
```
其中 `cityCode` 可以在 [官方的地区列表仓库](https://github.com/qwd/LocationList) 中的 `China-City-List-latest.csv` 找到你所在城市的 `cityCode`
# 前置元数据
在 Hexo 的 Markdown 文件中,一个典型的 YAML 格式的 `Front Matter` 可能会是这样的:
```markdown
---
title: 我的文章标题
categories:
- javascript
tags:
- 编程
- JavaScript
---
```
## top
实现文章置顶的功能,给定一个数值,可以进行排序,设定了 `top` 元数据的文章,会在分类列表中,使用 📌 标记
例如有三篇文章:
- 文章1
```markdown
---
title: 文章1
top: 0
categories:
- javascript
tags:
- 编程
- JavaScript
---
```
- 文章2
```markdown
---
title: 文章2
top: 1
categories:
- javascript
tags:
- 编程
- JavaScript
---
```
- 文章3
```markdown
---
title: 文章3
categories:
- javascript
tags:
- 编程
- JavaScript
---
```
那么在 `javascript` 分类下,排序的顺序依次为:`文章1 > 文章2 > 文章3`
## status
用于区分文章的状态,同时利用文章分类列表的`筛选`进行快速筛选Cosy 主题内置了 4 种状态
- done完成
- doing进行中
- todo待办
- other废弃
例如:
```markdown
---
title: 文章1
categories:
- javascript
status: done
---
```
# 自定义页面
Hexo 使用 Markdown或其他渲染引擎解析你的文章并生成静态文件以快速加载。除了默认生成的文章和归档页面之外Hexo 还允许你创建自定义页面。
## 基本配置 🆕
可以通过配置 `nav_meta` 属性关闭页面、更改图标
v1版本配置
```yml
nav_meta:
# 不显示 timeline页面
timeline: false
# 自定义图标
roadmap:
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 24 24">
<g fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<path d="M10.5 20.4l-6.9-6.9c-.781-.781-.781-2.219 0-3l6.9-6.9c.781-.781 2.219-.781 3 0l6.9 6.9c.781.781.781 2.219 0 3l-6.9 6.9c-.781.781-2.219.781-3 0z"></path>
<path d="M9 14v-2c0-.59.414-1 1-1h5"></path>
<path d="M13 9l2 2l-2 2"></path>
</g>
</svg>
resume:
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 24 24">
<g fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<path d="M14 3v4a1 1 0 0 0 1 1h4"></path>
<path d="M5 8V5a2 2 0 0 1 2-2h7l5 5v11a2 2 0 0 1-2 2h-5"></path>
<circle cx="6" cy="14" r="3"></circle>
<path d="M4.5 17L3 22l3-1.5L9 22l-1.5-5"></path>
</g>
</svg>
```
v2版本配置
```yml
nav_meta:
archives: svg
cosy-roadmap: svg
cosy-resume: svg
```
## 偏好设置 🆕 (v2新增)
创建偏好设置页面
```bash
hexo new page cosy-preference
```
## Roadmap 路线图 🆕
创建页面,你可以使用命令
```bash
# v1版本请使用
hexo new page roadmap
# v2版本请使用
hexo new page cosy-roadmap
```
成功后在 `source/` 文件夹下会生成一个新的文件夹 `/roadmap/index.md`
你可以参照此模板,进行配置,参数说明:
- title: roadmap 页面 html 的标题
- initYear: 默认显示的年份
```markdown
---
title: 陈不渡 - roadmap
layout: roadmap
initYear: 2023
years:
2022:
- title: 读书
start: 01-01
end: 1-5
- title: 还是读书
start: 02-01
end: 05-30
2023:
- title: 越陌度阡
start: 01-01
end: 1-2
- title: 枉用相存
start: 02-01
end: 06-30
- title: 短歌行
start: 10-26
end: 10-31
content: 对酒当歌,人生几何!譬如朝露,去日苦多。慨当以慷,忧思难忘。何以解忧?唯有杜康。青青子衿,悠悠我心。但为君故,沉吟至今。呦呦鹿鸣,食野之苹。
- title: 声律启蒙
start: 11-01
end: 11-31
content: 花开红锦绣,水漾碧琉璃。去妇因探邻舍枣,出妻为种后园葵
---
```
## Resume 简历页面 🆕
创建页面,你可以使用命令
```bash
# v1版本请使用
hexo new page resume
# v2版本请使用
hexo new page cosy-resume
```
成功后在 `source/` 文件夹下会生成一个新的文件夹 `/resume/index.md`
你可以参照此模板,进行配置,参数说明:
- title: resume 页面 html 的标题
- avatar: 头像图片的地址
```yml
title: 页面标题document.title
layout: resume
avatar: /img/avatar.png
name: Hi! Mozzie
role: Full Stack
email: himozzie@gmail.com
phone: +86 180-xxxx-xxx
birth: Jan 21, 1994
location: Nanjing, China
social:
- name: github
link: https://github.com/17px
icon: svg
about:
- 我的工作是建立你的网站,使其功能强大,用户友好,但同时具有吸引力。
- 此外,我为您的产品添加了个人风格,并确保其引人注目且易于使用。我的目标是以最有创意的方式传达你的信息和身份。我为许多知名品牌公司设计网页。
skill:
- 熟悉Node具备后端开发能力有SpringBoot、Egg、Koa2、Midway等单个应用项目经验有Nestjs微服务应用项目经验
- 具有Monoreo工程经验能够分离单个单元的前端和后端并应用DevOps
education:
- school: 大学艺术学院
time: 2012-2016
workExp:
- inc: 创意研发
time: 2021.09 ~ 至今
- inc: Web设计
time: 2021.01 ~ 2021.09
projectExp:
- name: PC/React• 标注 ,算法数据中心
desc: 这是一个xxx系统。它主要包括一个bc函数。我主要负责x、y和z模块的开发和维护。
list:
- 使用pnpm工作区管理Monorepo中的多个代码库支持多个框架共存共享通用组件库和功能
- name: PC/React•Tavigator主动脉根部/外周
desc: 这是一个xxx系统。它主要包括一个bc函数。我主要负责x、y和z模块的开发和维护。
portfolio:
- name: 项目A
desc: 项目A描述
iconSVG: 复制svg的path到这里
link: 网址http(s)://...
# 更多 ...
```