使用github和Hexo搭建个人博客

这个文件会不断更新

这两天外面下雨闲着没事准备做一个博客，看网上说要什么搞个域名、买个服务器啊、然后部署啊之类的，觉得有点麻烦，我怕这种麻烦会让我还没开始就结束了写博客之旅，所以就准备用github来托管一下博客，这个比较方便。唯一不好的就是国内上github不稳定，网速还慢，但是相较于在CSDN这个（CSDN Steals Documents on Network）上写博客对于身心健康来说是大有脾益的；相较于gitee的代码审核，github可以即时展示。

本文主要参考的GitHub+Hexo 搭建个人网站详细教程进行，为了简洁，关于工具的详细介绍这里不赘述，只写关键的代码部分。

注意：下面的操作均是在windows系统上进行。

介绍

有关于Hexo是什么和github这里不多说，只说说比较的关键的和写博客密切相关的东西。我个人理解的github + Hexo的博客的流程图：

         编写markdown格式的博文
                  |
                  v
     使用Hexo把markdown转换为html文件
                  |
                  v
       使用Hexo把文件上传到github
                  |
                  v
访问xxx.github.io（github是公网大家都能访问）
                  |
                  v
    github按照对应路径给出对应的静态html文件
                  |
                  v
             浏览器渲染页面

hexo就是一个比较方便的把你写的markdown的文章按照你指定的主题转换为html文件的工具，也就是说除了hexo你也可以用其他的工具比如Hugo，甚至是你自己手写html然后放到github都可以；github实际上就是按照特定的路径把你事先准备好的html文件给显示出来，这就是托管作用。

比如可以看hexo-theme-Claudia作者的github博客，里面就是按照日期的文件夹，下面对应的就是一个index.html文件，当然了，还会有一些css、js文件。

安装npm

下载windows的node：node-v18.16.0-x64.msi，双击进行安装。

安装之后打开cmd测试一下：

node -v

在对应的文件夹右键，打开cmd（或者直接在任务栏的搜索里面搜索cmd）。如果没有，我推荐再安装一个ConEmu，然后右键会出现一个ConEmu Here。

安装hexo插件

1	npm install hexo-cli -g

如果出现下面的报错：

1
2
3

npm ERR! code CERT_HAS_EXPIRED
npm ERR! errno CERT_HAS_EXPIRED
npm ERR! request to https://registry.npm.taobao.org/hexo-asset-image failed, reason: certificate has expired

运行下面的代码：

1
2
3

npm cache clean --force
npm config set strict-ssl false
npm install

安装git

进入git for windows下载git，下载完成之后安装。完成之后在桌面右键，看是否多了两个选项：git GUI here、git bash here。

初始化博客

新建一个文件夹，比如D:/博客/，（这个文件夹是需要比较稳定的，不能放在随手不注意给删除了地方比如桌面之类的）。打开cmd，然后输入：

1
2
3

# 这里文件夹的路径你可以修改为其他位置
md D:/博客
cd D:/博客

进入这个文件夹，之后输出下面的命令：

# 新建一个hexo的项目（blog可以更改为你认为合适的名字）
hexo init blog

# 进入新建项目的内部
cd blog
# 新建一个文章名叫test_my_site
hexo new test_my_site
# 启动本地服务
hexo s

你会看到在cmd中出现这些文字：

1
2
3

INFO  Validating config
INFO  Start processing
INFO  Hexo is running at http://localhost:4000/ . Press Ctrl+C to stop.

打开浏览器，输入http://localhost:4000，你可以一个Hexo的地平线的网页，表示你创建成功了。

如果出现错误：Port 4000 has been used. Try other port instead.表示端口已经被用了，更换端口就可以：
1
hexo s -p 4001

更改主题

默认的主题有点历史感，目前我个人喜欢Haojen/hexo-theme-Claudia - Demo

如果上面服务开启了，先ctrl + c关闭掉，然后输入下面的命令：

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

如果上面git clone不下来，可以直接下载hexo-theme-Claudia.zip，然后把文件夹解压放到themes文件夹里面，然后把文件夹名称更改为Claudia。

然后下载这个主题的依赖：

# 注意安装下面的包一定是要在blog根目录下
cd D:/博客/blog

npm install hexo-renderer-pug 
npm install hexo-renderer-dartsass
npm install hexo-generator-search

# if you need RSS, you must be install this plugin
npm install hexo-generator-feed

# Flowchat
npm install hexo-filter-flowchart        
# Math
npm install hexo-renderer-mathjax

打开blog/_config.yml文件，将下面这一行修改为：

1 2	# theme: landscape theme: Claudia

保存，再次输入

1 2	hexo clean hexo s

继续在浏览器中输入http://localhost:4000查看主题是否更改了。

编写文章

写的文章都是放在D:/博客/blog/source/_posts下面，你可以看到之前我们生成的test-my-site.md文件，这里的笔记都是使用markdown格式编写的，如果不了解这个格式可以搜索markdown语法学习。

比如这里我想写一个新的文章，名叫使用github和Hexo搭建个人博客。

1	hexo new "使用github和Hexo搭建个人博客"

然后里面写上这些内容：

---
title: 使用github + Hexo搭建个人博客
date: 2023-06-17 22:31:58
tags:
---

## 1. 安装node

## 2. 安装git

## ...

注意文章中title、date、tags之类的东西不要删除掉，这是用来对文章进行排序和显示博文标题的。

以后在编写文章的时候推荐使用一个markdown的编辑器，我这里用的是Typora的历史版本（免费的那一版，我是用的0.9.92版），然后可以在里面编写好粘贴在使用hexo new生成的文件下面，然后修改一下title、date、tags的内容。

其他调整

有一些信息是默认的，需要更改为自己的信息，下面是一些常见的需要更改的地方：

1) Hexo的配置文件

这里打开的是blog/_config.yml文件，里面的这几项最好修改：

# 你的博客的站点的名称
title: eternal-bug的博客
subtitle: "打不死的小强"
description: "一个喜欢牵着骆驼、带着闪亮的R形状的戒指的白菜哥。"
keywords: "生物信息"

# 作者
author: eternal-bug
# 语言
language: zh-CN
# 时区
timezone: Asia/Shanghai

# 网站地址（更改为你自己的github博客的地址）
url: https://eternal-bug.github.io

注意，yml格式的:后面一定要有一个空格，不然这个会识别不出来，除了中文文字和句子中的标点之外，其他所有逗号空格，都需要是在英文输入状态下输入。

上传到github

现在是在本地查看，需要将这些东西上传到github上可以让其他人能访问到。

1) github注册

如果你没有github，需要注册一个github，新建一个GitHub账号，具体怎么申请，这里不赘述，如果有你直接登录就可以。

2) 新建仓库

申请好账号和登录github之后，你需要点击右上角的+，然后New repository，在Repository Name下面填上你的github名字.github.io（必须这么写，比如我的github的名字是eternal-bug，那么我就写上eternal-bug.github.io），其他的不用动，只需要给Add a README.md前面打勾。这个时候你可以打开https://eternal-bug.github.io/就已经可以访问了（eternal-bug更改为你的github的名字），只不过是默认页面。

3) 添加SSH关联

因为上传是需要口令的，这里需要申请一个口令：

# 配置用户名
git config --global user.name eternal-bug
# 输入申请github账号时候的邮箱
git config --global user.email xxxxxxxxxx@qq.com

第一次登录时，Git会提示你输入密码，但出于保密因素，除“Enter your password: ”这行系统提示消息外，命令行不会显示任何字符，也不会在你输入或删除字符时用增减星号（井号）表示，因此输入密码时，最好放慢速度，避免因打字过快而输错。

1 2	# 申请口令 ssh-keygen -t rsa -C xxxxxxxxxx@qq.com

会弹出下面的话，直接回车就好了（这是是让你上传github代码的时候输入的密码，因为这是我自己的电脑，密钥文件也是存在我这里这里，所以这个不需要设置密码）：

1
2
3

Enter file in which to save the key (/c/Users/tanglab_lzh/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:

完成之后，会在你的电脑的C:\Users\XXX\.ssh下面有（XXX表示你的电脑的用户名字）

1 2	id_rsa id_rsa.pub

两个文件。打开id_rsa.pub，然后按下ctrl+a选中所有的文本。

再次进入到github的界面，点击个人头像->Setting->点击SSH and GPG keys->点击SSH keys右侧New SSH key，在title里面填上你自己认识的名称，然后在key一栏中粘贴刚才从id_rsa.pub文件中复制过来的内容。点击Add SSH key完成口令的添加。

4) 上传

修改blog/_config.yml中的对应内容，拉到最下面：

deploy:
  type: git
  repo: git@github.com:eternal-bug/eternal-bug.github.io.git
  # 早些时候github主分支是master，但是从2020年10月01日开始美国为了政治正确，将master分支名称更改为了main，所以这里与时俱进写为main
  branch: main

回到本地，现在需要上传，进入blog文件夹，然后输入：

# 清理之前生成的静态文件
hexo clean
# 生成静态文件
hexo g
# 将文件推到github上面
hexo d

如果出现：

1
2
3

The authenticity of host 'github.com (xx.xxx.xxx.xxx)' can't be established.
ECDSA key fingerprint is SHA256:xxxxxxxxxxxxxxxxxxxxxx/xxxxxxx/xxxx.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

输入yes，回车，如果出现：

1	Enter passphrase

直接回车。

最后如果出现：

1	INFO Deploy done: git

表示上传成功，这个时候可以去你的github上查看。

注意

因为之前很多教程是让把branch: 写为branch: master的，如果你上传之后发现github的博客文件夹中的文件没有变化，这是因为现在主分支是main，一般可以把master合并到main中，但是相对于来说步骤比较多，这里直接把branch: master更改为branch: main然后再hexo g一次就可以了。

查看效果

打开网址https://eternal-bug.github.io查看效果（这里你需要把eternal-bug更改为你的github的名字）。如果显示github的404，检查一下你在New repository生成的文件的名称是否正确。

到这里已经完成，博客可以正常运作，后续内容都是优化包括主题设置，请分别食用！

更多优化

这里我们只是测试了一下基本的功能，把最主要的步骤走了一遍，但是页面不是很好看细节不够，还有更加丰富的东西去探索。

分门别类

0) 博客项目说明

blog/public的目录下没有一个README.md文件，在你的github的页面，比如https://github.com/eternal-bug/eternal-bug.github.io下面，点进去没有介绍，这个不是必要的，但是为了更加完整，可以在上面执行hexo g把本地的文件上传的时候，放一个README.md到blog/public里面，当然你可以一直放在这个文件夹里面随时更改。

1) 文章标签

在写的博文多了之后，如果按照时间线或者一页一页的去找是很麻烦的，需要对文章分类，第一种可以通过打标签的方式去给博文分类。

在生成文章的时候你应该发现文章头里面有一个：

1 2	title: 使用github和Hexo搭建个人博客 tags:

这样的东西，它是用来标记这篇文章的信息的，其中tags就是这篇文章的标签啦，你可以自己增加一些标签：

title: 使用github和Hexo搭建个人博客
tags:
  - Hexo
  - github
  - 博客

上面是为了给文章分类，你还需要有一个标签的显示界面，使用下面的命令来生成（只需要生成一次）：

1	hexo new page "tags"

这样就会在source文件夹下生成./tags/index.md文件，打开这个文件，在标题头里面写上这些内容：

title: tags
date: 2024-06-15 18:09:55
type: "tags"
layout: "tags"

这些内容只是让hexo默认生成一些标签，你可以自己在里面写上一些内容，比如标签的介绍啊之类的。

2) 文章分类

除了标签之外，还有分类。同样的，在markdown的开头除了：

1 2	title: 使用github和Hexo搭建个人博客 tags:

还可以添加一个分类：

1	categories: 博客

上面是为了给文章分类，你还需要有一个分类的显示界面，使用下面的命令来生成（只需要生成一次）：

1	hexo new page "categories"

这样就会在source文件夹下生成./categories/index.md文件，打开这个文件，在标题头里面写上这些内容：

title: categories
date: 2024-06-15 19:01:12
type: "categories"
layout: "categories"

3) 关于页面

一个博客没有关于自己的页面你写着博客就没劲啊，在这里可以介绍一下自己。还是一样：

1	hexo new page "about"

编辑./source/about/index.md文件，写你自己的介绍。

1
2
3

## 关于我

我是一个...

4) 404页面

如果不设置这个页面，在网页访问出错（比如原来你写了某一篇博客，但是后来更改了名称或者删除，别人保存了网址书签，再去访问）会出现的页面，如果不设置404的页面，会简单的弹出灰扑扑的404怼到浏览器面前。

5) 留言板

与上面新建标签一样这里新建一个留言板页面：

1	hexo new page "contact"

编辑source/contact/index.md，在里面写上：

title: contact
date: 2024-06-15 18:14:17
type: "contact"
layout: "contact"

6) 个性化页面

实际上hexo new page就是用来新建页面的，你可以自己建议一个页面，比如叫

1	hexo new page "mypage"

就会生成一个source/mypage/index.md的文件，编辑这个文件。后续可以在我的ButterFly主题的调教的文章中看到一个导航栏设置，可以在那里设置一个导航栏，地址设置为/mypage/就行了。

7) 草稿

如果不想让文章被发布到github上，就优先生成草稿，写好之后移动到_posts文件夹下就可以。

1	hexo new draft "测试草稿"

就会在source/_drafts下生成一个测试草稿.md和一个测试草稿文件夹，和之前文章一样正常编辑。

如果想要预览一下草稿，可以：

1	hexo s --draft

如果想要让草稿变成正文，可以使用这个命令：

1	hexo p "测试草稿"

实际上就是把文章从__drafts文件夹移动到了_posts文件夹。

8) 删除文章

直接在_posts文件夹下把对应的markdown文件和文件夹删除就就可以了，然后再：

1	hexo clean && hexo g && hexo d

评论系统

为了方便我使用的基于GitHub Discussions的评论的giscus插件，好处是自己方便，访客不是太方便，他们想要评论需要登录github，授权github作为评论账号。具体做法如下：

1. 创建github仓库

进入你自己的github界面，点击头像，选择your repositories，点击New新建一个仓库，名称我这里就写为giscus，点击Create repositories（一定不要设置为Private）。这个时候是位于这个仓库下面，点击仓库的Setting，找到Features，下面有一个Discussions栏目前面有一个小框，给小框打上勾。

2. 安装giscus应用

点击这个链接giscus github apps，点击Install，在下面的选项中选择Only select repositories，选择你刚才新建的那个仓库（这里我就是选的eternal-bug/giscus）。点击Install。

3. giscus配置

点击这个链接giscus配置，拉到仓库这里，有一个输入框，输入框里面填上仓库的名称（这里我填写的是eternal-bug/giscus），在页面映射部分选择Discussion 的标题包含页面的URL，然后在Discussion 分类的下拉框里面选择Announcements。

4. 复制代码到github中
在启用 giscus下面有一段代码，你复制这个代码放到你markdown文章的末尾：

<script src="https://giscus.app/client.js"
        data-repo="eternal-bug/giscus"
        data-repo-id="xxxxxxxxxxxxx"
        data-category="Announcements"
        data-category-id="xxxxxxxxxxxx"
        data-mapping="url"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="preferred_color_scheme"
        data-lang="zh-CN"
        crossorigin="anonymous"
        async>
</script>

注意：不要放在代码框中。

除此之外，使用Twikoo插件你可以将评论系统保存在腾讯云上，评论的时候游客只需要在相应的文本框中填入必要的信息即可评论，详细可以看这篇文章Hexo + Butterfly 评论功能。

搜索系统

后面在研究一下。

嵌入图片

1) 图片

在编写文章的时候，内部插入的图片的方法是可以将图片放在本地，然后在typora中编辑markdown文件写![image](/path/to/image.jpg)等等方式，这样做本地可以显示，在hexo将博客上传到github的时候就没了，需要按照特定的方式来放图片以便hexo可以将图片上传到github，以github作为图床来得到图片的路径，下面是具体做法：

安装npm的包：

1	npm install hexo-asset-image --save

找到npm安装包的路径./node_modules/hexo-asset-image/index.js，将它的内容替换为如下内容：

'use strict';
var cheerio = require('cheerio');
     
// http://stackoverflow.com/questions/14480345/how-to-get-the-nth-occurrence-in-a-string
function getPosition(str, m, i) {
  return str.split(m, i).join(m).length;
}
     
var version = String(hexo.version).split('.');
hexo.extend.filter.register('after_post_render', function(data){
  var config = hexo.config;
  if(config.post_asset_folder){
       var link = data.permalink;
   if(version.length > 0 && Number(version[0]) == 3)
      var beginPos = getPosition(link, '/', 1) + 1;
   else
      var beginPos = getPosition(link, '/', 3) + 1;
   // In hexo 3.1.1, the permalink of "about" page is like ".../about/index.html".
   var endPos = link.lastIndexOf('/') + 1;
    link = link.substring(beginPos, endPos);
     
    var toprocess = ['excerpt', 'more', 'content'];
    for(var i = 0; i < toprocess.length; i++){
      var key = toprocess[i];
      
      var $ = cheerio.load(data[key], {
        ignoreWhitespace: false,
        xmlMode: false,
        lowerCaseTags: false,
        decodeEntities: false
      });
     
      $('img').each(function(){
       if ($(this).attr('src')){
           // For windows style path, we replace '\' to '/'.
           var src = $(this).attr('src').replace('\\', '/');
           if(!/http[s]*.*|\/\/.*/.test(src) &&
              !/^\s*\//.test(src)) {
             // For "about" page, the first part of "src" can't be removed.
             // In addition, to support multi-level local directory.
             var linkArray = link.split('/').filter(function(elem){
               return elem != '';
             });
             var srcArray = src.split('/').filter(function(elem){
               return elem != '' && elem != '.';
             });
             if(srcArray.length > 1)
               srcArray.shift();
             src = srcArray.join('/');
             $(this).attr('src', config.root + link + src);
             console.info&&console.info("update link as:-->"+config.root + link + src);
           }
       }else{
           console.info&&console.info("no src attr, skipped...");
           console.info&&console.info($(this));
       }
      });
      data[key] = $.html();
    }
  }
});

编辑blog文件夹下的_config.yml文件，将第43行的：

1	post_asset_folder: false

替换为：

post_asset_folder: true
marked:
  prependRoot: true
  postAsset: true

保存一下。

这个时候新建一个博客用来测试图片：

1	hexo new "测试图片"

在新建博客之后，会有一些与之前不一样的地方，除了生成一个测试图片插入.md文件之外，还额外多了一个一摸一样名字的文件夹测试图片插入，这里你随便找一张图片比如叫test.jpg放到这个文件夹里面。

在对应的markdown文件中写上：

1	![image](test.jpg)

然后hexo本地预览一下：

1 2	hexo g hexo s

之前你写的博客也想要添加图片？可以手工在blog/source/_posts下建立一个和文章markdown文件相同名称的文件夹，把图片放进去，更改markdown文件，用hexo再生成一下就行了。

嵌入多媒体

emoji支持

安装一个库就可以：

1 2	cd D:/博客/blog npm install hexo-filter-github-emojis --save

然后打开_config.yml文件，在里面新增下面的配置信息：

githubEmojis:
  enable: true
  className: github-emoji
  inject: true
  styles:
  customEmojis:

网易云音乐

比如你想添加一个网易云音乐的播放按钮，你可以在markdown中添加这个代码：

1	<iframe frameborder="no" border="0" marginwidth="0" marginheight="0" width=330 height=86 src="//music.163.com/outchain/player?type=2&id=1956202531&auto=0&height=66"></iframe>

上面的auto设置为0是不自动播放，设置为1是自动播放。

如何查找你想要的歌曲的代码呢？首先打开网易云音乐（其他的音乐我暂时还没尝试应该也可以），搜索或者查找到你想要的歌曲，这里我查找《快乐老家》，点击“生成外链播放器”，把文本框里面的<iframe>...</iframe>复制过来，直接粘贴到markdown相应的位置（不需要放到代码框里面）。

bilibili的视频

比如你想添加一个b站的视频的播放界面，可以在对应的视频下面比如天线宝宝央配旧版开头/压箱底自收藏，点击分享按钮，然后选择嵌入代码，代码会复制到你的剪贴板中：

1	<iframe src="//player.bilibili.com/player.html?aid=938030801&bvid=BV1hT4y1Y7RF&cid=573164441&page=1" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"> </iframe>

但是这个页面的展示不是很完美，可以把上面的代码中添加一些东西：

<iframe src="//player.bilibili.com/player.html?aid=938030801&bvid=BV1hT4y1Y7RF&cid=573164441&page=1&as_wide=1&high_quality=1&danmaku=0&autoplay=0" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true" width="100%" height="500" sandbox="allow-top-navigation allow-same-origin allow-forms allow-scripts"> </iframe>

主要调整的是宽度和高度、再就是不进行自动播放。

百度地图

在百度地图里面找到你需要找的地方，点击百度给与的地点之后，点击分享，然后把网址复制https://j.map.baidu.com/58/rnJ下来，填到下面的src后面：

1	<iframe src="https://j.map.baidu.com/58/rnJ" width="100%" height="600px" frameborder="0" scrolling="No"></iframe>

上面的width和height可以根据你自己的需要更改。

高级设置

你如果对于html和css语法比较了解的，可以自己去修改主题的内部的东西得到你自己想要的效果。

嵌入看板娘

一个可爱的纸片人跃然纸上不是很好吗！

其他主题

除了上面主题之外，你也可以去hexo主题列表 - themes看更多的主题，注意最好是选择标记有#中文的主题，比如Next、ButterFly主题。但是我觉得Next主题过于简洁，而且很容易和其他人的博客“撞衫”，色调太单调了；ButterFly主题也还不错可以试一试。

你可以按照上面的更换主题的方式进行更换，只需要注意安装主题的依赖包，然后再对主题的配置进行细节的配置。

永久链接

最新写了几篇文章之后意识到一个很大的问题，文章的网页URL链接非常长，如果我把之前写的文章标题更改之后，其他引用这篇的文章的引用会失效，给别人分享的链接也会因此失效，搜了一下发现一个库可以解决这个问题，叫做hexo-abbrlink，具体做法如下：

# 以后安装库都进入这个文件夹
cd D:/博客/blog

npm install hexo-abbrlink --save

安装完成之后，用记事本打开这个文件夹下的_config.yml文件，将原本的这一行注释更换为这一行：

1 2	# permalink: :year/:month/:day/:title/ permalink: posts/:abbrlink.html # 此处可以自己设置

在下面额外粘贴这些内容：

# abbrlink config
abbrlink:
  alg: crc32      # support crc16(default) and crc32 进制
  rep: hex        # support dec(default) and hex  算法
  drafts: false   # (true)Process draft,(false)Do not process draft. false(default) 
  # Generate categories from directory-tree
  # depth: the max_depth of directory-tree you want to generate, should > 0
  auto_category:
     enable: true  #true(default)
     depth:        #3(default)
     over_write: false 
  auto_title: false #enable auto title, it can auto fill the title by path
  auto_date: false #enable auto date, it can auto fill the date by time today
  force: false #enable force mode,in this mode, the plugin will ignore the cache, and calc the abbrlink for every post even it already had abbrlink.

保存文件。

# 清理一下之前生成的文件
hexo clean
# 再次生成一下
hexo g

它将原本这样的链接：

1	https://eternal-bug.github.io/2023/06/18/%E4%BD%BF%E7%94%A8github%E5%92%8CHexo%E6%90%AD%E5%BB%BA%E4%B8%AA%E4%BA%BA%E5%8D%9A%E5%AE%A2/

转换为：

1	https://eternal-bug.github.io/posts/196e9b33.html

实际上网页后面的代码来自于markdown中，你会发现markdown文件头部多了一点东西，每一篇文章都不同：

1	abbrlink: 196e9b33

注意：这样处理之后新的问题又出现了，更新之后的文章中的图片失效了，原因是hexo-abbrlink和之前安装的hexo-asset-image库冲突了，之前图片的路径是以文字标题作为路径索引，这里更改文章路径之后图片就找不到了。查询了一圈，最好的解决办法是，去foreveryang321/hexo-asset-image/index.js把里面的代码全部复制，替换掉node_modules/hexo-asset-image/index.js里面的内容，然后再次hexo clean、hexo g就可以了。