Payton's blog

Somewhere leisure.

个人博客的搭建

发表于 更新于 分类于
本文字数： 13k 阅读时长 ≈ 11 分钟

利用Github个人主页和各种静态博客框架，可轻松搭建出精美的个人博客。

TODOS

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Vercel部署博客
Vercel.com


https://www.sharesomething.cn/course/blog/blog.html#%E5%AE%89%E8%A3%85

用master分支
注意部署的时候框架要选择other，因为master分支本身就已经部署好了，不要再选一次框架，否则会拿源码再编一次

这样编译出来


用source分支
https://wiki-power.com/unlist/个人知识库极简搭建指南-VuePress

先部署，然后Setting-Git-Production Branch，改为source
然后push一次更新，让它重新部署

安装前的准备

首先需要安装node和git，且git已连接到github。

然后需要配置Github Pages。Github Pages是Github为每个用户提供的静态网页，每个用户只能有一个Github Pages主域名，但是可以有很多个子域名。主域名和子域名形式如下。

类型 域名
主域名 https://[用户名].github.io
子域名 https://[用户名].github.io/[仓库名]

新建一个仓库。若仓库名称为[用户名].github.io，则得到的是主域名，否则为子域名。注意，必须是Public Repository才可以有Github Pages。新建完成后点击Create new file，文件为index.html，内容任意。

进入Settings-Github Pages，选择用于存放网页内容的branch和页面主题，部署后即可在相应域名中看到相应的页面。

Hexo

搭建Hexo环境

终端切换到安装目录（此处为E盘），执行以下安装命令。

1
2
3
4
5
npm install hexo-cli -g
hexo init blog
cd blog
npm install
hexo s

在网页输入localhost:4000预览，若出现博客样式，则搭建成功。

部署到Github Pages

在建好的Github仓库中点击Clone or download，复制仓库地址。打开blog/_config.yml，在末尾添加（或修改）如下信息，注意空格和缩进。

1
2
3
4
deploy:
  type: git
  repo: // Github个人主页地址
  branch: master

然后修改配置文件中的URL部分，如下。

1
2
3
4
# URL
url: // Github个人主页地址
root: // 主域名填写/，子域名填写/[仓库名]/
...

终端路径切换到刚才的blog目录，输入以下命令完成部署。

1
2
3
npm install hexo-deployer-git --save
hexo g
hexo d

备份源文件

输入以下命令安装备份插件。

1
npm install hexo-git-backup --save

在_config.yml文件末尾添加以下内容。

1
2
3
4
5
6
# Backup
backup:
  type: git     
  message: backup for hexo blog
  repository:  
    github: git@github.com:[用户名]/[仓库名].git,source

保存后输入以下命令以备份。

1
hexo b

如果连接不上仓库，则删除.git文件夹，重试即可。

主题配置

以Next主题为例。

安装

终端路径切换到blog目录，输入以下命令下载Next主题。

1
git clone https://github.com/theme-next/hexo-theme-next themes/next

打开blog/_config.yml，将theme:更改为next。再次输入hexo s，若主题更改，则安装成功。

配置

Next主题的配置文件位于blog/themes/next/config.yml中，自定义样式文件位于blog/themes/next/source/css/custom/custom.styl中。

以下不说明时，默认在Next主题的配置文件修改。

更改高亮格式

可使用highlight.js或PrismJS两种渲染模式。示例如下。

1
https://theme-next.js.org/highlight/

若使用highlight.js，需在Hexo的配置文件中进行以下修改。

1
2
3
4
5
6
highlight:
  enable: true
  ...
prismjs:
  enable: false
  ...

在Next的配置文件中进行以下修改。其中night-owl为主题，可在以上链接查看。

1
2
3
4
5
codeblock:
  theme:
    light: night-owl
    dark: night-owl
  ...

更改底部ICON

1
2
3
4
5
footer:
  icon:
    name: fa fa-comments
    animated: false
    color: "#808080"

更改主题样式

1
2
3
4
5
# Schemes
#scheme: Muse
#scheme: Mist
scheme: Pisces
#scheme: Gemini

关闭脚注

1
2
footer:
  powered: false

左侧菜单添加图标

1
2
3
4
avatar:
  url: /images/avatar.gif
  rounded: true
  rotated: false

字体

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
font:
  enable: true

  host: https://fonts.loli.net

  global:
    external: true
    family: Noto Serif SC
    size: 0.9

  title:
    external: true
    family:
    size:

  headings:
    external: true
    family: Roboto Slab
    size: 1.7

  posts:
    external: true
    family: Noto Serif SC

  codes:
    external: true
    family:

代码块样式

1
2
3
4
5
6
7
codeblock:
  highlight_theme: night eighties

  copy_button:
    enable: true
    show_result: true
    style: mac

回到首页

1
2
3
4
back2top:
  enable: true
  sidebar: true
  scrollpercent: true

添加Mathjax公式支持

注意不能与Katex一起使用。

1
2
3
4
math:
  mathjax:
    enable: true
    mhchem: true

在需要使用Mathjax的文章在头部新增mathjax: true即可。如果没有效果，则在终端输入以下代码。

1
2
3
4
5
// 卸载自带markdown渲染器
npm un hexo-renderer-marked --save

// 安装支持mathjax的渲染器
npm i hexo-renderer-kramed --save

行内代码块自定义样式

在blog/themes/next/source/css/_custom/custom.styl添加以下样式。

1
2
3
4
5
code {
    color: #DC143C;
    margin: 2px;
    border: 1px solid #d6d6d6;
}

添加背景图片

在blog/themes/next/source/images下放入背景图片并重命名为background.jpg，在blog/themes/next/source/css/_custom/custom.styl添加以下样式。

1
2
3
4
5
6
7
8
9
10
11
12
13
@media screen and (min-width:1200px) {

    body {
    background-image:url(/images/background.jpg);
    background-repeat: no-repeat;
    background-attachment:fixed;
    background-position:50% 50%; 
    }

    #footer a {
        color:#eee;
    }
}

在文章末尾添加「本文结束」标记

在路径/themes/next/layout\_macro中新建passage-end-tag.swig文件，并添加以下内容。

1
2
3
4
5
<div>
  {% if not is_index %}
        <div style="text-align:center;color: #ccc;font-size:14px;">-------------本文结束<i class="fa fa-paw"></i>感谢您的阅读-------------</div>
  {% endif %}
</div>

接着打开/themes/next/layout\_macro/post.swig，在post-body之后、post-footer之前的</div>添加如下代码。

1
2
3
4
5
<div>
 {% if not is_index %}
  {% include 'passage-end-tag.swig' %}
 {% endif %}
</div>

然后打开主题配置文件_config.yml，在末尾添加如下代码即可。

1
2
3
// 文章末尾添加「本文结束」标记
passage_end_tag:
  enabled: true

添加宠物/动漫人物插件

很难卸载干净，不推荐使用。

打开终端，切换到博客根目录并输入以下命令以安装。

1
npm install --save hexo-helper-live2d

打开主题文件夹的_config.yml文件并添加以下内容到文件末尾。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# Live2D
## https://github.com/EYHN/hexo-helper-live2d
live2d:
  enable: true
  # enable: false
  scriptFrom: local # 默认
  pluginRootPath: live2dw/ # 插件在站点上的根目录(相对路径)
  pluginJsPath: lib/ # 脚本文件相对与插件根目录路径
  pluginModelPath: assets/ # 模型文件相对与插件根目录路径
  # scriptFrom: jsdelivr # jsdelivr CDN
  # scriptFrom: unpkg # unpkg CDN
  # scriptFrom: https://cdn.jsdelivr.net/npm/live2d-widget@3.x/lib/L2Dwidget.min.js # 你的自定义 url
  tagMode: false # 标签模式, 是否仅替换 live2d tag标签而非插入到所有页面中
  debug: false # 调试, 是否在控制台输出日志
  model:
    use: live2d-widget-model-wanko # npm-module package name
    # use: wanko # 博客根目录/live2d_models/ 下的目录名
    # use: ./wives/wanko # 相对于博客根目录的路径
    # use: https://cdn.jsdelivr.net/npm/live2d-widget-model-wanko@1.0.5/assets/wanko.model.json # 你的自定义 url
  react:
    opacity: 0.7

若需卸载，则在_config.yml和package.json中删除相关信息，终端切换到博客目录并运行以下命令。

1
npm uninstall -g hexo-helper-live2d

运行后搜索live2d并删除文件夹。

去除图片边框

失效教程

在themes/next/source/css/_common/components/post/post-expand.styl中修改以下代码即可。

1
2
3
4
5
6
7
img {
  box-sizing: border-box;
  margin: 0 auto 25px;
  padding: 3px;
-  border: 1px solid $gray-lighter;
+  border: none;
}

依赖安装

hexo-symbols-count-time

用于统计文章字数。在终端输入以下命令。

1
npm install hexo-symbols-count-time

在根目录的_config.yml文件末尾添加以下内容即可。若无效，则执行hexo clean，然后再生成。

1
2
3
4
5
6
7
8
9
symbols_count_time:
  symbols: true
  time: true
  total_symbols: true
  total_time: true
  exclude_codeblock: false
  awl: 4
  wpm: 275
  suffix: "mins."

项目链接如下。

1
https://github.com/theme-next/hexo-symbols-count-time

pangu

用于在英文单词和中文之间自动添加空格。在终端输入以下命令即可，需在配置文件中设置pangu: true。

1
npm install pangu --save

项目链接如下。

1
https://github.com/vinta/pangu.js

全局配置

常用命令

命令 操作
hexo s 启动服务预览
hexo g 生成静态页面
hexo d 部署
hexo new a 新建文章a（位于blog/source/_posts）
hexo new draft b 新建草稿b（位于blog/source/_drafts）
hexo publish b 发布草稿b
hexo new page c 新建页面c（位于blog/source）
hexo clean 删除已生成的静态页面

配置文件

Hexo的配置文件位于blog/_config.yml中，修改其中配置即可实现Hexo的不同功能。

默认新建页面

调整hexo new a所新建的页面a的位置。

1
2
default_layout: post //默认页面新建成post格式
default_layout: draft //默认页面新建成draft格式

给文章添加分类

终端进入blog目录，输入以下命令新建页面。

1
hexo new page categories

编辑刚新建的页面，如下。

1
2
3
4
title: Categories
date: 2014-12-22 12:39:04
type: "categories"
---

编辑主题的_config.yml，将menu中的categories: /categories注释去掉，然后在文章md文件头部新增categories:即可。

文章设置多标签

在文章md文件头部新增tags: [标签1,标签2,···]即可。

文章链接添加html后缀

在终端输入以下命令安装hexo-abbrlink插件。

1
npm install hexo-abbrlink --save

在Hexo根目录的配置文件_config.yml中修改/添加以下信息。

1
2
3
4
5
6
permalink: posts/:abbrlink.html

#abbrlinks
abbrink:
  alg: crc32
  rep: dec

文章md文件头部新增abbrlink: xxx，即可在渲染时得到xxx.html，否则将按照算法随机生成数字。

除使用:abbrlink变量外，也可以使用以下属性。

变量 描述
:year 文章的发表年份（4位数）
:month 文章的发表月份（2位数）
:i_month 文章的发表月份（去掉开头的零）
:day 文章的发表日期（2位数）
:i_day 文章的发表日期（去掉开头的零）
:title 文件名称
:id 文章ID
:category 分类（如果文章没有分类，则是default_category配置信息）

可在 permalink_defaults 参数下调整永久链接中各变量的默认值。

1
2
permalink_defaults:
  lang: en

本地搜索

安装命令如下。

1
npm install hexo-generator-searchdb

项目链接如下。

1
https://github.com/next-theme/hexo-generator-searchdb

安装完成后在Hexo根目录的配置文件_config.yml中修改/添加以下信息。

1
2
3
4
5
search:
  path: search.xml
  field: post
  content: true
  format: html

程序维护

更新

主程序

建议先更新node和npm。执行以下命令前先将路径切换到博客目录下。

1
2
3
4
5
6
7
npm install -g npm-check     # 安装npm-check
npm-check                    # 查看系统插件是否需要升级
npm install -g npm-upgrade   # 安装npm-upgrade
npm-upgrade        # 更新package.json
# 在执行npm-upgrade命令后会要求输入yes或者no，直接输入Yes或Y即可
npm update -g      # 更新全局插件
npm update --save  # 更新系统插件

如果完成后输入hexo提示command not found，输入以下命令即可。

1
npm install hexo-cli -g  # 全局升级hexo

重建文件夹

将原博客文件夹重命名，然后根据搭建Hexo环境中的命令重新搭建。搭建完成后通过代码对比工具对比两者的_config.yml并进行对应修改即可。

VuePress

搭建VuePress

终端切换到安装目录（此处为E:\vuepress），并执行以下命令。

1
2
3
npm init
npm install -D vuepress
mkdir docs && echo '# Hello VuePress' > docs/README.md

打开package.json，修改scripts部分如下。

1
2
3
4
5
6
{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

在终端运行以下命令，即可在http://localhost:8080预览网页。

1
npm run docs:dev

目录结构

进入docs文件夹并新建.vuepress文件夹，进入文件夹并新建config.js和public文件夹。其中config.js是博客配置，public文件夹存放图片等所需元素。

docs文件夹存放所有的md文档，可以使用文件夹代表组。一般而言，第一层文件夹代表导航栏上的类别，第二层文件夹及以后代表侧边栏上的类别，且每个第一层文件夹内必须要有README.md，在导航栏点击该类别时显示该文件的内容，第二层文件夹开始可不放README.md。这一存放逻辑有助于后面使用插件时直接生成可用的导航栏和侧边栏。

目录结构大致如下。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
├── docs
│   ├── Nav 1
│   │   ├── [其它Markdown文档]
│   │   ├── ...
│   │   └── README.md
│   ├── Nav 2
│   │   ├── Group 1
│   │   │   ├── [其它Markdown文档]
│   │   │   └── ...
│   │   ├── Group 2
│   │   │   ├── [其它Markdown文档]
│   │   │   └── ...
│   │   ├── [其它Markdown文档]
│   │   ├── ...
│   │   └── README.md
│   ├── ...
│   ├── .vuepress
│   │   ├── config.js
│   │   └── public
│   │       ├── [有用的图片]
│   └── README.md
├── package-lock.json
└── package.json

每篇md文档都需要有的开头如下。

1
2
3
4
5
---
title: [标题]
---

[正文]

基本配置

修改根目录的README.md以使用默认主题自带的首页，可以将相应的内容设置为null来禁用标题和副标题。注意需要在public文件夹放入image.jpeg作为主图。

1
2
3
4
5
6
7
8
9
10
11
12
---
home: true
heroImage: image.jpeg // 主图名称
heroText: // 标题
tagline: // 副标题
actionText: // 按钮上的文字
actionLink: // 点击以上按钮跳转的地方，如/Nav 1/
features:
// 可以有三项
- title: Record Something
  details: For future.
---

修改docs/.vuepress/config.js，如下。注意需要将icon.png放入public文件夹以在左上角显示logo。

1
2
3
4
5
6
7
8
9
10
11
12
module.exports = {
  title: '[标题]',
  description: '[描述]',
  base: // Github的仓库名，若仓库名为[用户名].github.io则填写'/'，否则为'/[仓库名]/'
  themeConfig: {
    logo: 'icon.png',
    repo: // Github的仓库地址，即'[用户名]/[仓库名]'
    smoothScroll: true, // 平滑滚动
    sidebarDepth: 2, // 侧边栏展开深度
    lastUpdated: 'Last Updated' // 上次更新时间
  }
}

目录插件

插件仓库如下。

1
https://github.com/boboidream/vuepress-bar

终端切换到根目录并输入以下命令。

1
npm install -D boboidream/vuepress-bar

根据插件约定，nav开头的文件夹将会成为导航栏，否则为侧边栏，加上数字可规定导航栏或侧边栏顺序，数字为10，20等。加–nc结尾表示该侧边栏默认展开，加–d2表示设置目录展开深度为2，也可为其他数字（–d3等）。如nav.10.[Group名称]，10.[Group名称]，10.[Group名称]--nc。

在docs/.vuepress/config.js添加以下内容。

1
2
3
4
5
module.exports = {
  ...
  plugins: ['autobar'],
  ...
}

目录示例如下。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
├── deploy.sh
├── docs
│   ├── nav.10.Nav1
│   │   ├── [其它Markdown文档]
│   │   ├── ...
│   │   └── README.md
│   ├── nav.20.nav2
│   │   ├── 10.Group1
│   │   │   ├── [其它Markdown文档]
│   │   │   └── ...
│   │   ├── 20.Group2
│   │   │   ├── [其它Markdown文档]
│   │   │   └── ...
│   │   ├── [其它侧边栏项]
│   │   ├── ...
│   │   └── README.md
│   ├── [其它导航栏项]
│   ├── ...
│   ├── .vuepress
│   │   ├── config.js
│   │   └── public
│   │       ├── icon.png
│   │       └── image.jpeg
│   └── README.md
├── package-lock.json
└── package.json

注意，如果不用插件而手动写导航栏项目，则在config.js按照如下示例填写。注意/表示根目录下的README.md，/group/表示group文件夹下的README.md，/[名称]表示该目录下的[名称].md。因此导航栏的文件夹下必须存放README.md。

1
2
3
4
5
6
7
themeConfig: {
  nav: [
    { text: 'Home', link: '/' },
    { text: 'Guide', link: '/guide/' },
    { text: 'External', link: 'https://google.com' },
  ]
}

部署到Github Pages

确保config.js中的base一项填写正确，然后在根目录新建deploy.sh，内容如下。注意最后部分根据自己部署的网站类型进行注释和取消注释。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
#!/usr/bin/env sh

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
npm run docs:build

# 进入生成的文件夹
cd docs/.vuepress/dist

# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果发布到 https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master

# 如果发布到 https://<USERNAME>.github.io/<REPO>
git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages

cd -

完成后在终端输入以下命令执行该脚本即可。

1
./deploy.sh

Gitbook

Github部署

打开以下网页并用Github账号登录。

1
https://www.gitbook.com/

新建一个Workspace，点击左侧的Integrations-Github，连接到Github账号，选择用作博客的仓库，类型选择Github to Gitbook。

然后需要将该仓库下载到本地。终端切换到安装目录并运行以下命令，以完成连接与提交。

1
2
3
4
5
6
7
8
git clone git@github.com:[用户名]/[仓库名].git
cd [仓库名]
git init
git remote add origin git@github.com:guanpeiheng1/gitbook.git
git pull
git add .
git commit -m "..."
git push origin master

目录结构

在根目录下的文件夹代表一个分组，每一个md文件代表一个页面。分组下可以再建文件夹表示嵌套分组。嵌套分组应当加README.md。

页面目录需要在SUMMARY.md定义，格式示例如下。注意，括号内代表文件路径时，空格需要用\20代替。可以使用Tab缩进实现子章节，最多支持三级标题。

1
2
3
4
5
6
7
8
9
10
11
12
13
# Table of contents
* [Introduction](README.md)

## Part I
* [A](part1/A.md)
* [B](part1/B.md)
* [Group I](part1/group1/README.md)
    * [Group I-A](part1/group1/A.md)
    * [Group I-B](part1/group1/B.md)

## Part II
* [A](part2/A.md)
* [B](part1/B.md)

网页预览

预览方式

切换到gitbook目录，终端运行以下命令以安装部署gitbook本地模块并进行预览。

1
2
npm install gitbook-cli -g
gitbook serve

常见问题

安装过程出现cb.apply is not a function

npm版本与gitbook不兼容所致。

到错误所提示的目录下找到其指定的文件，此处为polyfills.js。打开并注释以下三行代码即可。注意安装完成后不可取消注释。

1
2
3
4
// 这个函数的作用是用来修复node.js的一些bug
fs.stat = statFix(fs.stat)
fs.fstat = statFix(fs.fstat)
fs.lstat = statFix(fs.lstat)

预览时出现GitBook RangeError: Maximum call stack size exceeded

在仓库根目录下新建book.json，并填写以下内容。

1
2
3
{
    "plugins": ["-lunr"]
}

提交更改

与普通Github提交仓库更新一致。仓库更新后会自动修改Gitbook页面内容。

1
2
3
git add .
git commit -m "..."
git push origin master

参考教程

hexo的next主题个性化教程:打造炫酷网站

1
https://www.jianshu.com/p/f054333ac9e6

NexT使用文档

1
http://theme-next.iissnan.com/

安装gitbook的一些问题

1
https://blog.csdn.net/weixin_42349568/article/details/108414441

解决GitBook RangeError: Maximum call stack size exceeded

1
https://cloud.tencent.com/developer/article/1441125

VuePress官网

1
2
3
4
5
https://vuepress.vuejs.org/zh/config/
https://vuepress.vuejs.org/zh/guide/deploy.html
https://vuepress.vuejs.org/zh/guide/markdown.html
https://vuepress.vuejs.org/zh/guide/getting-started.html
https://vuepress.vuejs.org/zh/theme/default-theme-config.html

VuePress自动生成侧边栏和导航栏，完美替代GitBook

1
https://juejin.cn/post/6844903935027707918

部署VuePress到GitHub Pages(超详细)

1
https://juejin.cn/post/6844904122873806856