本地搭建博客

本地环境：windows10

使用主题：PaperModX

安装过程

  • 安装Go并配置环境

  • 下载prebuilt版本的hugo

    • 注意hugo有普通版本和extended版本，最好使用extended版本，因为在使用PaperModX主题时，需要使用到extended版本（但是PaperMod主题使用普通版本就可以）

  • 新建站点：hugo new site myblog

  • 下载主题：在myblog/themes/下git clone git@github.com:reorx/hugo-PaperModX.git

    • 也可以使用git submodule的方式添加主题，此时方便进行版本控制和管理

本地配置

myblog/下的配置文件参考sulvblog’s config.yaml和PaperModX example’s config.yaml进行配置，自己慢慢调吧（papermodx在papermod的基础上添加了一些特性，比如侧边目录）

个人主要进行的修改有：

  • 在archetypes/posts.md中设定默认的meta内容
  • 修改为posts、archive、search、tags、categories、about六个menu，其中posts、categories、tags在content下为目录，archive、search、about在content下为md文件
    • 在文件夹下创建_index.md文件可以在里面添加Front Matter，用来设置当前文件夹下的meta信息
    • 在配置时留意是posts还是post，是archive还是archives
  • 加入数学公式的支持
    • 但是当使用带有/begin{} /end{}的多行公式，或者多行公式中含有若干下划线时，此时可能无法正确渲染，我的解决办法是将没有正确渲染的多行数学公式放在<span></span>标签对中，这样在网页博客和本地typora中都可以正常显示。考虑到平时不怎么写复杂的多行数学公式，因此手动修改也不多。
    • 在Hugo中优雅地使用数学公式中，博主的方法三自己编译一份加入了goldmark数学插件的hugo版本，但是注意编译过程中gcc版本不宜过高（我的gcc原来是8.1.0，编译不过，后来改到5.1.0，编译通过）。但是最终使用好像针对原生latex的多行公式支持不足（？不确定，可能是自己后面配置不正确？），最后没有使用这个方案
  • 调整了主页中Welcome部分的高度，在themes/hugo-PaperModX/assets/css/common/main.css的.first-entry中min-height修改为80px
  • 调整了页面中内容的宽度（原来侧边留空感觉有点多，可以适当减小），themes/hugo-PaperModX/assets/css/common/main.css的.main.post中添加right: 60px;
  • 在themes/hugo-PaperModX/assets/css/common/post-single.css中调整h1~h6标题的高度

内容管理

  • 写文章：hugo new posts/文章名称.md，注意写对md文件的路径

  • 本地预览：hugo server -D在localhost:1313上进行预览

    • -D表示draft: true的内容在预览时展示
    • 有时将draft改为false，使用hugo server进行预览时，对应文章没有出现，此时关掉PowerShell重开一个，重新运行一下命令

  • 构建：hugo会将构建的网站内容保存到public文件夹中，默认只会向public中添加内容，而不会删除外部不存在但是public中还存在的文件

    • hugo -F --cleanDestinationDir表示每次生成的public都是全新的，会覆盖原来的
    • --theme指定主题，--baseURL="xxx"指定url

将内容发布到GitHub Pages上

  • 将public文件夹转换为git库：

    • 进入到public文件夹，git init -b main 生成的默认主分支名字为main

  • 将git库关联到远程库：

    • git remote add origin git@github.com:QinganZhang/QinganZhang.github.io.git
    • 检查是否关联成功：cat .git/config
      • 如果[remote "origin"]信息正常显示，说明本地git库已经成功关联到远程库

  • 将修改commit到本地库

    1
2
3

    git status # 查看当前修改状态
git add . # 添加所有修改过的文件，也可以只添加某个文件
git commit -m "add a new post" #

  • 将修改push到远程库

    • git push -u origin main --force
    • 报错： error: src refspec main does not match any
      • 本地的branch为master，但是远程库默认branch是main，先将本地branch的名字修改为main
      • git branch -m master main
    • 报错： ! [rejected] main -> main (fetch first)
      • 提交冲突，远程库和本地库不一致。通常出现在初始化仓库有readme而本地没有等情况。参考
      • git pull --rebase origin main

  • 查看是否部署成功

    • 网页样式（css）丢失，但是内容还在，浏览器F12控制台报错：Failed to find a vlid digest in the 'integrity' attribute for source 'xxx.css' with computed SHA-256 integrity '***'. The resource has been blocked. （关键词：”integrity“）

      • 尝试方法一：解决 hugo 中关于 integrity 的错误，仍然出现原来的错误

      • 尝试方法二：解决Hugo无法加载css文件，仍然出现原来的错误，而且第一遍文章会覆盖在h1标题Posts上，

      • 最终方法：在themes/hugo-PaperModX/layouts/partial/head.html中，将

        1
2
3
4
5
6

        {{- if not site.Params.assets.disableFingerprinting }}
{{- $stylesheet := $stylesheet | fingerprint }}
<link crossorigin="anonymous" href="{{ $stylesheet.RelPermalink }}" integrity="{{ $stylesheet.Data.Integrity }}" rel="preload stylesheet" as="style">
{{- else }}
<link crossorigin="anonymous" href="{{ $stylesheet.RelPermalink }}" rel="preload stylesheet" as="style">
{{- end }}

        注释掉，只保留<link crossorigin="anonymous" href="{{ $stylesheet.RelPermalink }}" rel="preload stylesheet" as="style">这一行。猜想可能是与使用的主题相关，但是暂时没有找到使用相同主题类似错误的信息。

      • 更多参考：Hugo - Failed to find a valid digest in the ‘integrity’ attribute for resource - The resource has been blocked - Host on Github

使用GitHub Actions自动构建博客

使用上面的方式（手动构建），在本地写好博客之后，然后使用hugo在本地构建好静态博客，生成public目录，最终是将public目录push到GitHub仓库，构建静态博客。

还有一种方式，看起来更加高级，那就是基于GitHub Action自动构建博客。大致流程为：在本地写好博客之后，直接push到远程GitHub仓库，在远端而非本地构建博客。这个方式只是节省了自己使用hugo手动进行构建的这一步，但是如果当自己手工进行操作的步骤比较繁琐且固定时，使用GitHub Action自动化就很方便了。

在实际配置过程中，这里使用了两个仓库。一个是private的myblog仓库，本地写好博客后就push到这个myblog仓库；另一个仓库是public的、作为GitHub Pages的仓库，myblog仓库使用GitHub Action自动进行构建，将最终得到的public文件就放到这个仓库中。下面简要介绍基于Github Action自动构建博客的过程，着重介绍与上面手动构架不同的地方。

image-20240229143009260

具体过程：

  • 在Github远程新建一个仓库，比如命名为myblog

  • 在本地使用hugo新建站点时（比如hugo new site myblog），在本地myblog目录下git init -b main，并且使用git remote add将本地的myblog目录关联到远程myblog仓库

    • 注意之前手动构建的方式中，是在public目录下git init，并关联到远程仓库的，而且该远程仓库即为Github Pages

  • 在下载主题时，可以直接git clone源码，也可以使用git submodule的方式将主题作为子项目添加进来

    • 注意git submodule的子模块和原来的主模块是两个单独的项目，所以进入到子模块和主模块中进行git操作，是针对不同仓库的。Git Submodules介绍
    • 但是这里想将主题添加进来，自己进行一些修改，因此使用了另一种方法将主题添加进来：git subtree，这样可以直接将子项目作为主仓库的一个目录添加进来

  • 在myblog根目录下，创建.github/workflows/deploy.yaml，个人的deploy.yaml配置文件为：

     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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

    name: deploy

on: # 表示GitHub Action的触发条件（即push）
  push:
    branches: 
      - main # 设定触发的分支为main
  workflow_dispatch: # 可以在Github项目仓库的Action工具栏手动调用

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

jobs: # 表示GitHub Action的任务，这里定义了一个build的任务
  build:
    runs-on: ubuntu-latest # 指定GitHub Action的运行环境
    env: 
      HUGO_VERSION: 0.122.0
    steps: 
      # 其中run表示执行的命令，uses时GitHub Action中的一个插件
      - name: Checkout # 使用actions/checkout插件检出GitHub仓库
        uses: actions/checkout@v2
        # with:
          # submodules: false # 同时检出子模块
          # fetch-depth: 0 # 完整检出所有历史记录

      - name: Setup Hugo # 使用peaceiris/actions-hugo插件来安装Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: "0.122.0" # 0.122.0 
          extended: true

      - name: Build Web # 运行hugo命令生成博客的静态文件
        env: 
          HUGO_ENVIRONMENT: production
          HUGO_ENV: production
        run: hugo --gc --minify 
          # --baseURL "${{ steps.pages.outputs.base_url }}/" 

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with: 
          path: ./public

      - name: Deploy Web # 使用peaceiris/actions-gh-pages插件将静态网页部署到GitHub Pages上
        uses: peaceiris/actions-gh-pages@v3
        with:
          PERSONAL_TOKEN: ${{ secrets.PERSONAL_BLOG_TOKEN }} # 个人访问令牌
          EXTERNAL_REPOSITORY: QinganZhang/QinganZhang.github.io # 部署到的GitHub Pages仓库
          PUBLISH_BRANCH: main # Github Pages分支
          PUBLISH_DIR: ./public # hugo静态文件的目录
          commit_message: ${{ github.event.head_commit.message }} # 提交更改时使用的提交消息
          # cname: ${{ secrets.DOMAIN }} # 自定义域名，默认使用github pages域名

# reference1: https://blog.csdn.net/m0_51993913/article/details/132657065   
# reference2: https://blog.csdn.net/freeking101/article/details/135515958使用Github Actions自动化部署部分
# reference3: https://github.com/reorx/hugo-PaperModX/blob/master/.github/workflows/gh-pages.yml

  • 然后生成Token，参考

    • 因为需要从myblog仓库推送public目录到Github Pages仓库，所以需要向myblog仓库添加身份验证凭据

  • 最后将本地博客push到myblog远程仓库，然后myblog远程仓库下使用GitHub Actions将public目录推送到Github Pages仓库中

其他问题：

  • 如何将obsidian双链转换为HTML的<a></a>标签对？
    • 目前发现的一个方案是jekyll-wililinks，但是这个方案需要使用jeklly搭建静态博客