利用github.io搭建自有博客 next v6 v8

Posted on Edited on In Views:

利用github.io搭建自有博客，基于hexo博客框架和next主题。
搭建这个blog框架吧，一是觉得csdn不好用，反正有一段时间特别卡，编辑界面出不来；二是觉得托管到上边没有github那种掌控感，反正csdn没有提供导出文章为md的功能，还得自己用工具把html转换为md，而且广告贼多，就感觉自己被白嫖了。索性研究一下搭建自己的blog。

环境准备，本地以windows为例

我一开始找到的是v6的仓库，结果遇到很多bug手动改源码处理，，最后才发现新版啥都解决了，还有更多集成的功能……
建议先读这个教程
除了hexo、next的相关，尤其可以了解到next混乱的版本地址……

Years Version Repository
2014 ~ 2017 v5 https://github.com/iissnan/
2018 ~ 2019 v6 ~ v7 https://github.com/theme-next/hexo-theme-next
2020~ v8 https://github.com/next-theme/hexo-theme-next

代码托管，创建<username>.github.io 仓库

创建的仓库，用来托管blog代码，github提供了github.io相关工具，最后代码同步完访问http://yourname.github.io
就可以看到自己的网页了。以下是我自己的仓库设置，供参考：
github设置

本地部署 Hexo 环境

Hexo 是一款基于 Node.js 效的静态博客框架

  • 安装Node.js，官网下载，安装最新版本即可

  • 安装 Hexo： npm install -g hexo-cli

  • 安装 swig：npm i hexo-renderer-swig

  • windows设置里 搜索 允许本地PowerShell脚本未签名的情况下运行 开启

    • 不开启powershell运行hexo server会报错

  • 初始化 Hexo 框架：hexo init hexo_blog

  • 进入上条命令所创建的 hexo_blog 文件夹中：cd hexo_blog

  • 启动 Hexo 服务：hexo server

  • 访问默认界面，测试是否安装成功：浏览器访问localhost:4000
    注意，以后本地都可以运行hexo服务后本地查看网页效果，觉得满意了在部署发布到github不迟。

  • 添加一篇文章/博客

    1
    2
    3
    $ hexo new 'First Post'
    INFO  Validating config
    INFO  Created: ~/blogs/source/_posts/First-Post.md

    生成后的文件通过模板添加了页面标题、时间以及标签。可以自己修改scaffolds下的post.md模板。
    注意，手动麻烦，自己整格式，添加时间啥的。直接hexo new比较快捷。

配置hexo和next主题

进入创建的 hexo_blog 文件夹中，将 Next 主题相关文件从 github 克隆到 themes 文件夹中 

1
2
3
4
git clone https://github.com/next-theme/hexo-theme-next.git themes/next_v8  #这个是v8的地址
#git clone https://github.com/theme-next/hexo-theme-next.git themes/next_v6  #这个是v6的地址，不用使用
#v8修复了很多v6.0的bug，后续小结属于v6的bug我会注明，v8是没有这些bug的。
#你要是想没事儿好奇看看这些bug，那就自己装v6的试试……

配置 Hexo 的主题参数（在根目录的 _config.yml 文件中），选择使用 Next 主题

修改参数为：theme: next_v8

next主题有很多配置，比如首页的文章折叠，这里自行看next_v8官网教程 配置。

  • 配置文件
    在 Hexo 中有两份主要的配置文件，其名称都是 _config.yml。 其中，一份位于站点根目录下，主要包含 Hexo 本身的站点配置；另一份位于主题目录下，这份配置由主题作者提供，主要用于配置主题相关的选项。
    为了描述方便，在以下说明中，将前者称为 站点配置文件， 后者称为 主题配置文件。
    1
    2
    3
    /hexo_blog/_config.yml

    /hexo_blog/themes/next/_config.yml

下面说几个遇到的bug，都是next_v6的

munu bug
如上图，原配置的||前边有空格，已经被我删除，如果不删除，页面上点击这些按钮，跳转会失败，报错类似：

1
Cannot GET /%20

%20其实就是空格的意思

cannot get archives%7C%7C%20archive v6的bug

修改themes\next\layout_macro\sidebar.swig 第52行

1
2
<a href="{{ url_for(theme.menu.archives).split('||')[0] | trim }}">  改为下面一行
<a href="{{ url_for(theme.menu.archives.split('||')[0]) | trim }}">

原因在于urlfor 解析的网址还没split呢，应该是（）不小心括错了。

next 中文标题无法跳转 v6的bug

我这里是超链接乱码问题，我们打开控制台，查看目录的的超链接标签，会看到 href 是一串乱码，实际上是被URL编码：
url messy1
修改themes\next\source\js\src\utils.js 233行下 如图：
url messy2
escapeSelector函数的目的是将选择器字符串中的某些特殊字符进行转义，以确保它们在JavaScript中可以安全使用。这个函数使用了正则表达式来匹配需要转义的字符，并使用replace方法将它们替换为转义后的版本。

然而，原先函数并没有考虑到中文字符，因为中文字符在CSS选择器中通常不需要转义。但是，如果中文字符在URL中被编码（例如，使用百分号编码），那么在解析这些字符之前需要进行解码。
所以解决这个问题，可以在escapeSelector函数中添加对中文字符的解码，然后再进行转义。

本地hexo可以跳转了，上传到github.io 还是无法跳转？
浏览器可能缓存了旧版本的JavaScript文件。尝试清除浏览器缓存或使用无痕模式访问GitHub Pages 网站。

安装插件hexo-generator-searchdb,执行以下命令:

1
npm install hexo-generator-searchdb --save

编辑 主题配置文件，启用本地搜索功能：

1
2
3
# Local search
local_search:
enable: true

永久文章链接设置

原始的文章链接是以日期来做的，那么不同日期修改了文章，链接就变了，如果其他文章引用了该文章，就会失效，为了防止这种问题产生，利用hexo-abbrlink生成永久链接，其实现方式：

对标题+时间进行md5然后再转base64，保存在front-matter中。

安装

1
npm install hexo-abbrlink --save

修改站点配置文件_config.yml

1
permalink: posts/:abbrlink.html

可以修改生成的算法和表示方式

1
2
算法：crc16(默认)或crc32
表示：dec(默认，十进制)或hex(十六进制)

配置方式

1
2
3
4
# abbrlink config
abbrlink:
  alg: crc32  #support crc16(default) and crc32
  rep: hex    #support dec(default) and hex

hexo 编译后，比如hexo server启动时，会给源文件的配置快插入：

1
abbrlink: xxxxx

文章链接就会永久以此为基础。

浏览统计

busuanzi可以对博客访问量计数。
主题配置文件修改：

1
2
busuanzi_count:
  enable: true

当enable: true时，代表开启全局开关。若site_uv、site_pv、page_pv的值均为false时，不蒜子仅作记录而不会在页面上显示。

放大缩小文中图片

开启Fancybox，这是一款用于显示图片、视频等。触摸启用，响应快，完全可定制。
主题配置文件修改：

1
fancybox: true

或者使用mediumzoom，更加简洁，两者不可同时使用。

开启giscus评论功能

Giscus 允许你将 GitHub Discussions 集成到你的网站上作为评论系统。这样做的好处是评论数据存储在 GitHub 上，不需要第三方服务。

仓库设置

新建一个仓库或者就在博客这个仓库设置以下属性：

  • 你的仓库必须是公开的 (public)，否则访客将无法查看 discussion
    创建仓库时要保证是public
  • 在你的仓库中启用 Discussions 功能
    在仓库的Settings下，找到Discussions勾选
  • 仓库安装giscus app
    访问https://github.com/apps/giscus 安装，记得设置就你开启评论的那个仓库就可以了，别整全部仓库了。

本地giscus安装和本地配置

  • 在你的 Hexo 博客目录中执行以下命令，安装 hexo-next-giscus 插件
    1
    npm install hexo-next-giscus --save
  • giscus配置
    访问：https://giscus.app/zh-CN
    在配置章节进行配置
    giscus配置
    如上图所示，最后会生成一个配置脚本，如下图
    giscus配置生成
    配置脚本就是这一段 <script … > …
    你可以按照它的说法，直接复制粘贴这段代码到想出现的位置。
    不过hexo或者next支持了giscus，所以可以在站点配置或者主题配置中加入以下内容，根据生成的配置代码填写对应项即可：
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    giscus:
    enable: false
    repo: # Github repository name
    repo_id: # Github repository id
    category: # Github discussion category
    category_id: # Github discussion category id
    # Available values: pathname | url | title | og:title
    mapping: pathname
    # Available values: 0 | 1
    reactions_enabled: 1
     # Available values: 0 | 1
    emit_metadata: 1
    # Available values: light | dark | dark_high_contrast | transparent_dark | preferred-color-scheme
    theme: light
    # Available values: en | zh-CN
    lang: en
    # Place the comment box above the comments
    input_position: bottom
    # Load the comments lazily
    loading: lazy
    最后启动服务，在文章末尾可以看到giscus评论区。

一些有趣配置

参考：http://home.ustc.edu.cn/~liujunyan/blog/hexo-next-theme-config/#next-%E9%85%8D%E7%BD%AE
文末添加诗词、背景动画、盘古动画等

Deploy github

将生成的静态页面部署到 github 上
修改站点配置文件_config.yml的最后部分

1
2
3
4
deploy:
  type: git
  repo: https://github.com/YourgithubName/YourgithubName.github.io.git
  branch: master

要先安装deploy-git，才能用命令部署到GitHub,否则报错ERROR Deployer not found: git

1
npm install hexo-deployer-git --save

然后

1
2
3
hexo clean #清除之前生成的东西
hexo generate  #生成静态文章，缩写hexo g
hexo deploy  #部署文章，缩写hexo d

过一会儿就可以在 http://yourname.github.io 这个网站看到你的博客了！

一键bat脚本

本地预览

1
2
3
@echo off
cd C:\Users\xxxx\Desktop\hexo_blog
hexo generate --watch&&hexo s

在服务器启动期间，Hexo 会监视文件变动并自动更新，无须重启服务器。
因为我的脚本文件就在c盘中，所以不需要切换盘符。bat规则可以查资料了解。

一键发布博客

1
2
3
@echo off
cd C:\Users\xxxx\Desktop\hexo_blog
hexo deploy --generate&&pause

参考：
比较全的教程：https://hexo-next.readthedocs.io/zh-cn/latest/
hexo官方文档：https://hexo.io/zh-cn/docs/
nextv8教程：https://theme-next.js.org/mist/docs/getting-started/
nextv5教程：https://theme-next.iissnan.com/ 可以做参考
markdown教程：https://markdown.com.cn/basic-syntax/
搭建blog教程：https://mini-pi.github.io/2024/02/28/how-to-make-blog-wedsite/
Hexo-Next 主题博客个性化配置：https://blog.csdn.net/as480133937/article/details/100138838

正在加载今日诗词....