Hexo 博客搭建

What is Hexo?

Hexo is a fast, simple and powerful blog framework. You write posts in Markdown (or other markup languages) and Hexo
generates static files with a beautiful theme in seconds.

(copy from https://hexo.io/docs/ )

• hexo 是一个博客搭建框架
• hexo 自带主题比较简单，通常会选择找一个更适合的主题

Hexo 环境

• nodejs

nodejs 安装推荐使用nvm , 支持本地多版本环境切换

• hexo-cli

npm install -g hexo-cli

Hexo Setup

Once Hexo is installed, run the following commands to initialize Hexo in the target .

hexo init <folder>
cd <folder>
npm install

Once initialized, here’s what your project folder will look like:

.
├── _config.yml
├── package.json
├── scaffolds
├── source
|   ├── _drafts
|   └── _posts
└── themes

_config.yml

Site configuration file. You can configure most settings here.

package.json

Application data. The EJS, Stylus and Markdown renderers are installed by default. If you want, you can uninstall them
later.

package.json

{
  "name": "hexo-site",
  "version": "0.0.0",
  "private": true,
  "hexo": {
    "version": ""
  },
  "dependencies": {
    "hexo": "^3.8.0",
    "hexo-generator-archive": "^0.1.5",
    "hexo-generator-category": "^0.1.3",
    "hexo-generator-index": "^0.2.1",
    "hexo-generator-tag": "^0.2.0",
    "hexo-renderer-ejs": "^0.3.1",
    "hexo-renderer-stylus": "^0.3.3",
    "hexo-renderer-marked": "^0.3.2",
    "hexo-server": "^0.3.3"
  }
}

copy from (https://hexo.io/docs/setup )

Hexo 主题安装

本站点使用 redefine 主题 , 当前安装版本 v0.4.5

• 简洁、五脏俱全

cd your-hexo-site
npm install hexo-theme-redefine@latest

安装完成后，在 Hexo 配置文件中将 theme 设置为 Redefine。

# _config.yml
theme: redefine

顺便删除自带主题

rm _config.landscape.yml

npm remove hexo-theme-landscape

这个主题基本是开箱即用，默认的配置就挺好的，可以修改一些偏个人信息的部分

修改配置

首先从主题文件中复制默认配置到项目根目录

cp node_modules/hexo-theme-redefine/_config.yml _config.redefine.yml

修改配置中基础信息部分 _config.redefine.yml

# 基础信息
base_info:
  title: Attson Thinking # Site title
  author: Attson # Author name
  url: https://attson.github.io # Site url
  # Logo image (You can use local image, image external link or don’t fill)
  logo_img: # logo image on the left of the navigation bar

# 作者头像和网站图标部分
style:
  # 说明: images 路径 -> 在source/images 
  # <= v0.4.5 主题内置文件 images/(avatar.svg loading.svg logo.svg logo.webp), 请避开这些文件命名
  avatar: /images/my_avatar.svg # avatar of the author
  # Favicon (You can use local image or image external link)
  favicon: /images/my_logo.svg # favicon of the site

  first_screen:
    background_image:
      light: /images/background.jpeg # background image of the first screen, use relative path or external link (if your website is in subdirectory, use external link)
      dark: /images/background.jpeg # background image of the first screen, use relative path or external link (if your website is in subdirectory, use external link)
    # 网站首页一段文案，可以改成自己喜欢的
    description: 可怕的不是死亡，而是你从未真正活过 # the title in the middle of the first screen. HTML supported (e.g. svg html code of your logo)
# 菜单部分
menu:
  # 增加 tags 页
  Tags:
    path: /tags

部署 github.io

• 本站点为了区分源文件和静态站点文件，采用两个仓库来维护博客
• 私有仓库 attson-blog 用于放源文件
• 公开仓库 attson.github.io 用于放build后的静态文件, GitHub pages

注意: 默认情况 hexo generate 是忽略过程中的异常，在自动化构建脚本中，忽略异常可能会导致部署了有bug的博客。增加 -b 参数

{
  "scripts": {
    "build": "hexo generate -b",
    "clean": "hexo clean",
    "deploy": "hexo deploy",
    "server": "hexo server"
  }
}

自动化部署使用 github workflows

• 使用 github workflows 好处是不需要再依赖其他deploy插件

增加文件 .github/workflows/deploy.yml

# 文件内容基本来自 https://hexo.io/docs/github-pages
# 统一使用v3 版本 v2 部分功能已弃用

name: Deploy

on:
  push:
    branches:
      - master  # default branch
jobs:
  pages:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          # If your repository depends on submodule, please see: https://github.com/actions/checkout
          submodules: recursive
      - name: Use Node.js 16.x
        uses: actions/setup-node@v3
        with:
          node-version: '16'
      - name: Cache NPM dependencies
        uses: actions/cache@v3
        with:
          path: node_modules
          key: ${{ runner.OS }}-npm-cache
          restore-keys: |
            ${{ runner.OS }}-npm-cache
      - name: Install Dependencies
        run: npm install
      - name: Build
        run: npm run build
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        # 配置说明 https://github.com/peaceiris/actions-gh-pages
        # 修改最后部署的部分 (如不区分两个仓库，则无需修改)
        with:
          deploy_key: ${{ secrets.DEPLOY_GITHUB_IO_SECRECT }}
          external_repository: "attson/attson.github.io"
          publish_branch: master
          publish_dir: ./public
          # 修改 commit 信息，默认是 attson/attson-blog@30438be
          full_commit_message: ${{ github.event.head_commit.message }}

其中 deploy_key 需要在两个仓库分别设置 ssh 私钥和公钥

生成keys

ssh-keygen -t rsa -b 4096 -C "<your email address>" -f "attson.github.io" -N ""

在公开仓库 attson.github.io 添加 deploy key，用于支持部署（公钥）

• Title 任意
• 注意勾选 write access

在私有仓库 attson-blog 添加 secrets key，用于访问 attson.github.io（私钥）

• title 需与 .github/workflows/deploy.yml 中 deploy_key 一致 DEPLOY_GITHUB_IO_SECRECT

git commit && git push

• 配置完以上后，就可以直接提交代码到 源文件仓库了，github 的 workflow 会在提交之后自动触发
• 在 Actions 处可以看到 workflow 情况

其他

gitalk 评论支持

https://redefine-docs.evanluo.top/docs/configuration-guide/comment#gitalk

[redefine <= v0.4.5 gitalk 代码有bug #36 ]

comment:
  enable: true
  use: gitalk # values: waline | gitalk | twikoo
  # Gitalk
  # See: https://github.com/gitalk/gitalk
  gitalk:
    github_id: attson # GitHub repo owner
    repository: attson.github.io # Repository name to store issues
    client_id: <GitHub Application Client ID> # GitHub Application Client ID
    client_secret: <GitHub Application Client Secret> # GitHub Application Client Secret

新建github oath 应用

https://github.com/settings/applications/new

markdown 嵌套图片的问题

• 官方推荐的嵌入图片的方式 https://hexo.io/zh-tw/docs/tag-plugins#Embed-image 不太符合markdown 通用写法

本站点使用 https://github.com/yiyungent/hexo-asset-img 插件

npm install hexo-asset-img --save

markdown 默认渲染器

• hexo 默认使用 hexo-renderer-marked 对 markdown 渲染，渲染库支持的语法和功能较少，无法用插件方式新增其他语法，

• 推荐使用 hexo-renderer-markdown-it , 默认支持的语法更多，也可以添加额外的插件

npm uninstall hexo-renderer-marked --save

npm install hexo-renderer-markdown-it --save

参考

• seo 优化 https://juejin.cn/post/6844904178452529160