测试 on 远楒

hugo+GithubIO自建博客踩坑实录

Sun, 02 Feb 2025 17:21:58 +0800

此博客搭建过程参考的资料在"关于"页面可详细了解。本文具体步骤也可能会给出具体参考的内容。

不能正确渲染主题 - 2025.01.28

此博客采用源码-博客页分离的结构搭建。

源码为hugo个人博客的源码，设为github私有仓库，通过git action，在每次push之后，通过hugo -D命令云端编译生成public文件夹中的内容之后将public文件夹内的内容推送到GitHub - XingfenD/xingfen-star.github.io仓库中。

在搭建阶段，我将themes子文件夹下的第三方主题仓库设置为该主项目的子模块，导致在上传到私有仓库后，themes文件夹中没有实际的主题文件。最终导致无法编译出所选主题的页面。

我在github action中添加步骤Print Directory以打印路径信息，最终定位此问题并修复，完整的githu action如下。

最终博客项目的结构为三个仓库：

Hugo源码仓库(通过gitignore忽略public, resources, themes文件夹)
主题仓库(Hugo源码仓库的public文件夹)
Github Page仓库(Hugo源码仓库的public文件夹)

name: deploy

# 代码提交到main分支时触发github action
on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-22.04
    steps:
        - name: Checkout
          uses: actions/checkout@v4
          with:
              fetch-depth: 0

        - name: Setup Hugo
          uses: peaceiris/actions-hugo@v3
          with:
              hugo-version: "latest"
              extended: true

        - name: Print Directory
          run: tree -L 3 -d

        - name: Clone Theme
          run: git clone https://github.com/XingfenD/hugo-theme-custom.git themes

        - name: Git Configuration
          run: |
            git config --global core.quotePath false
            git config --global core.autocrlf false
            git config --global core.safecrlf true
            git config --global core.ignorecase false

        - name: Build Web
          run: hugo -D

        - name: Print Directory
          run: tree -L 3 -d

        - name: Deploy Web
          uses: peaceiris/actions-gh-pages@v4
          with:
              personal_token: ${{ secrets.ACTION_ACCESS_TOKEN }}
              external_repository: XingfenD/xingfen-star.github.io
              publish_branch: main
              publish_dir: public
              commit_message: auto deploy

主题配置后代码块显示异常 - 2025.02.02

使用hugo-theme-stack主题后

发现在白天模式下的代码块颜色异常，如下图所示：

在通过修改hugo-theme-stack主题的scss文件后成功定位异常原因：

hugo编译md文件后生成的博文html文件中的codeblock为如下结构:

<div class="highlight">
    <pre style="">
        <code class="language-markdown">
            <span class="line">
            ...
        </code>
    </pre>
</div>

图中所示的深色异常颜色为<pre>标签的style属性控制，因此导致全局scss文件失效。

阅读官方文档后，在`hugo.toml`中添加配置：

markup.highlight.noClasses=false

问题得以修复。

修改配置文件以激活右侧边栏 - 2025.02.12

阅读Stack主题官方文档右侧边栏配置项可以了解如何修改配置文件以激活右边栏。

在config.yaml文件中修改配置项[params.widgets]:

params:
    widgets:
        homepage:
          - type: search
          - type: categories
            params:
              limit: 10
          - type: tag-cloud
            params:
              limit: 10

        page:
          - type: toc
          - type: categories
            params:
              limit: 5
          - type: tag-cloud
            params:
              limit: 5

配置生效后右侧边栏效果如下图:

不能正确渲染`abbr`, `sub`等特殊html标签 - 2025.02.12

查阅在线资料修复Hugo静态生成器中忽略原始HTML的方法后，在hugo.toml中添加配置项：

markup.goldmark.renderer.unsafe=true

成功渲染，效果如图。

Markdown 语法指南

Sun, 02 Feb 2025 00:00:00 +0000

本文提供了可以在 Hugo 内容文件中使用的最基本 Markdown 语法样本，同时也展示了基本 HTML 元素是否可以通过 Hugo 主题中的 CSS 被装饰。

标题

以下 HTML <h1>—<h6> 元素代表六个级别的章节标题。<h1> 是最高级别，而 <h6> 是最低级别。

# H1
## H2
### H3
#### H4
##### H5
###### H6

H1

H2

H3

H4

H5

H6

段落

Xerum, quo qui aut unt expliquam qui dolut labo. Aque venitatiusda cum, voluptionse latur sitiae dolessi aut parist aut dollo enim qui voluptate ma dolestendit peritin re plis aut quas inctum laceat est volestemque commosa as cus endigna tectur, offic to cor sequas etum rerum idem sintibus eiur? Quianimin porecus evelectur, cum que nis nust voloribus ratem aut omnimi, sitatur? Quiatem. Nam, omnis sum am facea corem alique molestrunt et eos evelece arcillit ut aut eos eos nus, sin conecerem erum fuga. Ri oditatquam, ad quibus unda veliamenimin cusam et facea ipsamus es exerum sitate dolores editium rerore eost, temped molorro ratiae volorro te reribus dolorer sperchicium faceata tiustia prat.

Itatur? Quiatae cullecum rem ent aut odis in re eossequodi nonsequ idebis ne sapicia is sinveli squiatum, core et que aut hariosam ex eat.

引用块

引用块元素表示来自另一个源的内容，并且可选地带有必须在 footer 或 cite 元素内的引用，以及可选的如注释和缩写的行内更改。

无属性的引用块

Tiam, ad mint andaepu dandae nostion secatur sequo quae. 注意在引用块中可以使用 Markdown 语法。

带有属性的引用块

> 不要通过共享内存来通信，而是通过通信来共享内存。<br>
> — <cite>Rob Pike[^1]</cite>

[^1]: 上述引用摘自 Rob Pike 在 Gopherfest 2015 年 11 月 18 日[演讲](https://www.youtube.com/watch?v=PAAkCSZUG1c)的部分内容。

不要通过共享内存来通信，而是通过通信来共享内存。
— Rob Pike¹

表格

表格不属于核心 Markdown 规范的一部分，但 Hugo 开箱即用地支持它们。

名称	年龄
Bob	27
Alice	23

表格中的内联 Markdown

斜体	粗体	代码
斜体	粗体	`代码`

A	B	C	D	E	F
Lorem ipsum dolor sit amet, consectetur adipiscing elit.	Phasellus ultricies, sapien non euismod aliquam, dui ligula tincidunt odio, at accumsan nulla sapien eget ex.	Proin eleifend dictum ipsum, non euismod ipsum pulvinar et. Vivamus sollicitudin, quam in pulvinar aliquam, metus elit pretium purus	Proin sit amet velit nec enim imperdiet vehicula.	Ut bibendum vestibulum quam, eu egestas turpis gravida nec	Sed scelerisque nec turpis vel viverra. Vivamus vitae pretium sapien

代码块

使用反引号的代码块

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>示例 HTML5 文档</title>
</head>
<body>
  <p>测试</p>
</body>
</html>

使用四个空格缩进的代码块

    <!doctype html>
    <html lang="en">
    <head>
      <meta charset="utf-8">
      <title>示例 HTML5 文档</title>
    </head>
    <body>
      <p>测试</p>
    </body>
    </html>

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>示例 HTML5 文档</title>
</head>
<body>
  <p>测试</p>
</body>
</html>

使用 Hugo 的内部 highlight 短代码的代码块

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>示例 HTML5 文档</title>
</head>
<body>
  <p>测试</p>
</body>
</html>

Diff 代码块

[dependencies.bevy]
git = "https://github.com/bevyengine/bevy"
rev = "11f52b8c72fc3a568e8bb4a4cd1f3eb025ac2e13"
- features = ["dynamic"]
+ features = ["jpeg", "dynamic"]

列表类型

有序列表

第一项
第二项
第三项

无序列表

列表项
另一个项目
再一个项目

嵌套列表

水果
- 苹果
- 橙子
- 香蕉
奶制品
- 牛奶
- 奶酪

其他元素——abbr, sub, sup, kbd, mark

<abbr title="图形交换格式">GIF</abbr> 是一种位图图像格式。

H<sub>2</sub>O

X<sup>n</sup> + Y<sup>n</sup> = Z<sup>n</sup>

按下 <kbd>CTRL</kbd> + <kbd>ALT</kbd> + <kbd>Delete</kbd> 结束会话。

大多数 <mark>蝾螈</mark> 是夜行性的，并猎食昆虫、蠕虫和其他小生物。

GIF 是一种位图图像格式。

H₂O

Xⁿ + Yⁿ = Zⁿ

按下 CTRL + ALT + Delete 结束会话。

大多数蝾螈是夜行性的，并猎食昆虫、蠕虫和其他小生物。

超链接图片

上述引用摘自 Rob Pike 在 Gopherfest 2015 年 11 月 18 日演讲的部分内容。 ↩︎