通用功能——Hexo搭建个人博客

发表于 | 分类于

Hexo 环境搭建

Hexo + Gitee搭建博客

Hexo官方提供了详细的Hexo使用文档Hexo官方文档，参考该文档安装相应的软件即可完成环境的搭建，涉及到的软件有：

  1. Node.js
  2. Git
  3. Homebrew，可以使用Homebrew 来安装Node.js和Git；

在必要软件安装好后，利用npm （javascript package manager）来安装hexo：

1
npm install -g hexo-cli

安装好hexo后，就可以开始建站了：

1
2
3
hexo init <site_folder>        // 初始化网站目录
cd <site_folder>                    // 切换到网站目录
npm install                                // 安装网站以来的文件，执行完毕后，当前目录回生成一个                                                            // node_modules文件夹

网站目录介绍

1
2
3
4
5
6
7
8
9
├── _config.yml                        // 网站配置文件
├── package.json                    // 网站依赖文件
├── scaffolds                            // 模板文件夹
├── node_modules                    // 以来的node插件库
├── source                                // 可以成为网站的源文件夹
|   ├── _drafts                        // 文章草稿文件夹
|   └── _posts                        // 已发布的文章文件夹
├── public                                // 网站生成的静态文件放置在给文件夹
└── themes                                // 主题文件夹

上面就是hexo网站的基本结构了，接下来是具体的设置。

Hexo 文章分类

在文章开头的yaml属性配置中添加如下内容：

1
2
3
categories: 
- 一级分类
- 二级分类

yaml支持以下属性：

  • layout，采用的布局可以是post，page，draft；
  • title，文章的标题，含空格的时候要用引号括起来；
  • date，日期，如2018-01-14
  • updated，修改日期
  • comments，是否开启评论
  • tags，标签，多个采用Markdown的无序列表
  • categories，分类，支持多级分类，采用Markdown无序列表，最上面代表一级分类

Hexo 更换主题

我采用的next主题，Hexo-Next实用主题优化

  • 下载好要更换的主题
  • 在Hexo根目录找到配置文件，搜索theme，讲主题名字替换为你下载好的主题

2022/02/20补充
出现网站首页打开不了的情况，但是具体的某一篇链接却可以打开，然来是之前添加制定功能时安装了插件：hexo-generator-index-pin-top，在安装之前将默认的hexo-generator-index插件卸载了，导致无法生成主页的index文件

常用主题配置说明：

Hexo博客技巧：添加自定义html页面

Hexo博文配图方法

参考链接：

Hexo发布博客引用自带图片的方法

上面文章介绍了两种方法：一种是不使用插件（前提是hexo版本需要V3.0以上）（尚未验证通过，可能打开方式不对）；一种是使用插件（这种方法已经成功验证）。

Hexo draft的使用

  • 使用hexo new draft “文章名”可以新建出来不发布到网上的文章

  • 如果需要预览draft类文章，可以如下操作：

    • 更改配置文件，render_draft: true
    • 启动server，hexo server —draft

  • 如果要发布已经写好的draft文章，可以使用hexo publish [layout] draft_file_name，其中Layout可以为page或post。

修改永久链接的默认格式

hexo默认的永久链接格式是:year/:month/:day/:title，如果文章标题是中文的，会出现各种问题。这里介绍下修改永久链接默认格式的方法。

安装插件

在站点的根目录安装如下插件：

1
npm install hexo-abbrlink --save

修改站点配置文件

打开根目录下的_config.yml，修改如下配置：

1
2
3
4
5
6
#permalink: :year/:month/:day/:title/
#permalink_defaults:
permalink: posts/:abbrlink.html
abbrlink: 
  alg: crc32  # 算法：crc16(default) and crc32
  rep: hex    # 进制：dec(default) and hex

然后执行hexo 操作三连：hexo clean、hexo g、hexo d，即可看到默认的链接样式改成了如下样式：

1
BLOG_HOST/posts/0.html # BLOG_HOST为博客域名，“0”为自己指定（或abbrlink生成的）链接名

注意，我们可以自己指定链接名（不要重复就行了），在文章开头添加：

1
abbrlink: '自定义链接'

注意：我在应用abbrlink插件时，添加的图片无法显示下来，搜索了好久，没有解决，然后就在source中添加一个images，将文章的图片添加到images中，然后再md中采用相对链接的方式来引用图片，然后解决了问题。
之前没有使用abbrlink时单独使用hexo-asset-image插件图片时可以显示的，现在不能显示很可能是前者对后者产生了影响，可以尝试修改插件源码来解决问题。

草稿文章处理

预览草稿

只想下面的命令，可以本机预览草稿：

1
hexo s --draft

发布草稿

执行下面代码，可以发布本机草稿：

1
hexo p <filename> #filename为不带.md后缀的草稿文件名称

Hexo文章置顶

文章多了，发现置顶就成了一个很必要的功能了，这里在晚上搜索了下相关的方法。

  • 修改hexo源码，具体参考解决Hexo文章置顶问题；

  • 安装相应的指定插件

    1. 删除原来的文章生成插件：

      1
      npm uninstall hexo-generator-index --save

    2. 安装支持指定的文章生成插件：

      1
      npm install hexo-generator-index-pin-top --save

    3. 在需要置顶的文章的Front-matter中加上top: true即可，比如如果想置顶这篇文章，就可以修改器Front-matter为一下格式：

      1
      2
      3
      4
      5
      6
      7
      8
      9
      title: 通用功能——Hexo搭建个人博客
      categories:
      - 通用
      tags:
        - 环境配置
      abbrlink: 'O180114'
      date: 2018-01-14 10:30:22
      updated: 2019-10-21 00:00:00
      top: true

Hexo数学公式显示

问题原因

Hexo默认使用 hexo-renderer-marked 引擎渲染网页，该引擎会把一些特殊的 markdown 符号转换为相应的 html 标签，比如在 markdown 语法中，下划线_代表斜体，会被渲染引擎处理为<em>标签。

因为类 Latex 格式书写的数学公式下划线_表示下标，有特殊的含义，如果被强制转换为<em>标签，那么 MathJax 引擎在渲染数学公式的时候就会出错。

类似的语义冲突的符号还包括*, {, }, \\等。

问题解决

第一步，更换 Hexo 的 markdown 渲染引擎，hexo-renderer-kramed 引擎是在默认的渲染引擎 hexo-renderer-marked 的基础上修改了一些 bug ，两者比较接近，也比较轻量级。

1
2
npm uninstall hexo-renderer-marked --save
npm install hexo-renderer-kramed --save

第二步，经过上面修改后，块数学公式可以在第三步第四步完成后可以正常显示了，但是行内数学公式不行，因为 hexo-renderer-kramed 引擎也有语义冲突的问题。接下来到博客根目录下，找到node_modules\kramed\lib\rules\inline.js，找到对应的内容并作相应修改

1
2
3
4
5
6
//escape: /^\\([\\`*{}\[\]()#$+\-.!_>])/,
  escape: /^\\([`*\[\]()#$+\-.!_>])/,


//em: /^\b_((?:__|[\s\S])+?)_\b|^\*((?:\*\*|[\s\S])+?)\*(?!\*)/,
  em: /^\*((?:\*\*|[\s\S])+?)\*(?!\*)/,

说明：

  1. escape的修改 是在原基础上取消了对\,{,}的转义

第三步，一般经过上面两部然后重启hexo，就可以解决问题了，如果还没有解决的话，需要做一下检查：

  1. 使用的主题中 Math渲染开关是否打开，打开方法如下：

    找到使用主题的根目录（我用的是next主题），打开_config.yml配置文件，找到math配置项，进行如下修改：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    # Math Equations Render Support
    math:
      enable: true

      # Default(true) will load mathjax/katex script on demand
      # That is it only render those page who has 'mathjax: true' in Front Matter.
      # If you set it to false, it will load mathjax/katex srcipt EVERY PAGE.
      per_page: true

      engine: mathjax
      #engine: katex

  2. 文章头部是否设置了 Math渲染支持，如果没有添加支持，添加上即可，添加方法如下：

    在文章的Front-matter里打开mathjax开关，

    1
    2
    3
    4
    5
    title: 通用功能——Markdown常用格式说明
    categories:
    - 通用
    abbrlink: 'A240229'
    mathjax: true

这样就解决了Hexo 博客 Math公式渲染的问题了，开心。

Hexo升级相关

  1. 安装 软件更新检查插件

    1
    npm install npm-check-updates -g

  2. 安装完成后，运行ncu命令，检查有哪些需要更新

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    ncu
    Checking /Users/randy/Documents/RandyBlog/package.json
    [====================] 13/13 100%

     hexo                         ^3.8.0  →  ^6.3.0
     hexo-abbrlink                ^2.0.5  →  ^2.2.1
     hexo-deployer-git            ^0.3.1  →  ^4.0.0
     hexo-generator-archive       ^0.1.4  →  ^2.0.0
     hexo-generator-category      ^0.1.3  →  ^2.0.0
     hexo-generator-json-content  ^3.0.1  →  ^4.2.3
     hexo-generator-tag           ^0.2.0  →  ^2.0.0
     hexo-renderer-ejs            ^0.3.0  →  ^2.0.0
     hexo-renderer-marked         ^0.3.0  →  ^6.1.1
     hexo-renderer-stylus         ^0.3.1  →  ^3.0.0
     hexo-server                  ^0.2.0  →  ^3.0.0

  3. 运行ncu-u 来更新package.json文件

  4. 删除老的node_moudles，重新安装

    1
    2
    rm -rf node_modules 
    npm install --save

问题解决

  1. hexo里面表格失效？
    解决：表格开头加两个空行。

  2. 目录及文件名中的中文提示 乱码

    1
    git config core.quotepath false

  3. 博客迁移时提示 plugin load failed

    1. 先查看node_modules文件夹中对应的插件完不完整，如果不完整，直接删除，利用npm install 插件名 --save重新安装；

  4. hexo更新后，生成部署成功后，博客无法打开，看了下生成的静态文件，出现如下代码

    1
    {% extends ‘_layout.swig‘ %} {% import ‘_macro/post.swig‘ as post_template %}

    原因是hexo在5.0之后把swig给删除了需要自己手动安装，通过如下方式解决：

    1
    npm install --save hexo-renderer-swig
     即重新安装该插件。

  5. hexo 更新后，next主题的博客点击导航栏报错如下

    1
    Cannot GET / about/%20/

    %20 是空格的意思，把next主题配置文件（_comfig.xml）里 ||之前所有的空格删掉即可。