Hugo on aiken's blog

基于Github部署和发布Hugo博客

Thu, 19 Dec 2024 11:35:08 +0000

托管平台选择

一些常见的托管平台 PaaS Platform as a Service 平台及服务，旨在使用户专注于应用代码开发的免费情况如下；

Site	Github Page	Vercel	Netfily	Coolify	Zeabur
Free?	Y	Y	Y	自托管免费	N（月费外无需额外）
Auto Re-Deployed	Y	Y	Y	-	-

其实对于这些小型的静态网页的项目部署，大多都是免费的，整体部署的流程也是相对简单，选择一个顺眼，便于国内访问用即可，但是无论是哪个方案，都建议绑定一下自己的域名，一来是更便于记，二来也能便于国内访问。

Todo

了解一下 Coolify，是否是类似一个公网转发平台的方案，将特定端口的服务使用 Coolify 转发到公网上，然后可以绑定自己的域名，这样的话也不失为一个好东西，我之前的服务也就都能部署出去了；

最终选择的时候可以考虑以下都是谁在访问自己的博客，然后测一下对应地区平台访问的速度来做决定，国内的话 vercel 好像是被 DNS 污染了，如果要部署在 Vercel 上的的话，考虑在域名解析的地方更换为CF 的解析服务原因：【多图预警】vercel部署及国内访问 | VuePress Theme Gungnir 具体方案：一招解决Vercel站点在国内无法访问的问题 | 程序猿DD | 如何在国内访问vercel部署应用？我个人觉得vercel是做前端的大家都应该去了解并且掌握的一个非常方便的部署工具，能 - 掘金；

直接使用 Public 文件夹进行部署

作为静态网页生成器，hugo 通过部署模式生成的 public 文件夹可以很轻松的在包括 Github pages 和 Vercel 等第三方平台上的各个托管平台进行部署，部署起来相当简单，只需要将 Publish 文件夹推到github 上，后面的都比较简单了

Github Page 直接在Setting-Pages 中设置选择源 Branch 即可，不需手动去写Github Action；
Vercel, Netfily 也是直接绑定对应的Github 仓库的指定分支即可，framework 选择Other；

且均能根据 Publish 的变更对网页重新构建，这里就不再赘述。

基于源码直接部署

基于源码部署主要是考虑到同时将博文本身推送上去，一是使用 git 做版本管理，二是可以不再额外管理一个仓库；因此也可以采用此种方式；

但实际上如果要和本地的 Editor 如 Obsidian 做无缝集成的话，还是会需要一些额外的脚本去做处理，包括写完后自动更新 repo 和推送这些，后续如果笔者记得的话可能也会更新一下相应的脚本；

部署到 Github Page

参考 hugo官方教程使用 Github Action 进行在线构建和实现 Github Page 的发布，修改其中自己需要进行构建的分支名称和部署命令等，然后直接 push 上去即可。

这里我对部署命令的修改部分如下：

        
        
        
        yaml
    
run: |
  hugo \
    --gc \
    --minify \
    --environment papermod \
    --baseURL "${{ steps.pages.outputs.base_url }}/"    

使用非 Master 分支进行构建可能会遇到以下的问题（build 成功，deploy 部分显示如下错误）

Error

Branch “x” is not allowed to deploy to github-pages due to environment protection rules.

解决方案：Github community · Discussion #39054 ，Repo 的 Setting 中找到 Environments 中的 github-pages 项中的 Deployment branches and tags 新增自己想要部署的分支即可；

Error

Static 中的资源加载出现 404，导致界面表现不合预期的情况

此外，如果个人之前已经对其他的 GithubPage 绑定了域名（例如 http://aikenh.cn/ ），这样可能会导致由于网页部署在域名的子目录下( http://aikenh.cn/hugoblog/ )，导致一些资源的 url 绑定到域名上（资源被绑定到 http://aikenh.cn/ 中导致 404 ），无法获取到，这里的解决方式是，通过绑定子域名/二级域名或者新的域名。

这里简单讲一下子域名的添加 Github Docs ，首先在 Github-Repo-Setting-Pages 中设置 Custom domain 如下

添加后去自己的域名控制台添加对应的 cname 子域名记录，然后稍后即可

添加子域名解析后可能会发现反而 CSS 等样式表加载不出来的问题（上一步的时候没问题），这时候就要考虑是不是 BaseURL 忘记更新了；记得修改项目配置（非 GithubAction 配置）中自己的 baseURL 再推上去使其重新构建，避免存在部分解析问题即可；

部署到其他 PaaS

Error

由于我们本地开发使用的 Git Submodule 中的地址通常是 git@github ,可能会导致第三方平台在拉取 Submodule 的时候出现一些权限错误导致拉取失败

因此当我们部署 Netlify 之前可以按照下面的方式更新 Submodule 为 http 链接，首先更改 .gitmodules 中子模块的URL

        
        ini
    
[submodule "themes/PaperMod"]
  path = themes/PaperMod
  url = https://github.com/AikenH/papermod-sidebar.git

然后执行下列命令来更新子模块的URL

        
        bash
    
git submodule sync
git submodule update --init --recursive

更新完以后将其推送到部署分支，例如 netlify

        
        bash
    
git checkout -b netlify
git add . 
git commit -m "[Conf] update submodule for third-party deploy"
git push origin netlify:netlify

部署到 Netlify

做完上述 Submodule 的准备之后，在 Netlify 的dashboard 上导入Repo 进行发布：

导入仓库，选择好发布的分支

可以参考下列命令来设置自己的发布参数以及环境变量（hugo 版本）

环境变量的Key-Value 分别为：HUGO_VERSION 还有你本地的 hugo 版本，可以通过下列命令获取

        
        bash
    
hugo version

域名绑定：主要是参考官方指引，将需要的域名填入后，按照如下指引，在购买域名处添加CName 即可；

随后记得更新网站的 BaseURL 以便网站正常工作;

部署到 Vercel

做完上述 Submodule 的准备之后，同样在 Vercel 处的设置也是比较简单的，导入指定的仓库后，将模版指定为Hugo，并修改部署配置如下：

同样添加环境变量：

但是 Vercel 中指定分支的方式相对较麻烦一些，在部署后，进入project 的dashboard 中，选择Setting

其中的 Git -> Production 跳转到指定页面去设置分支，设置完记得选择保存，同时下面有个环境变量也可以在设置一次。

到此为止的话其他分支上的提交也会导致触发build，为此我们还需要进一步设置，在刚刚 Git 页面的最底下，选择 only build production 即可，这里参考 oragekk ：

后面再触发一次 Deploy 任务以后就可以看到分支切换到指定的分支即可

添加域名：待补充；

TroubleShooting 问题解决

部署时 CSS 样式不显示问题

hugo 部署时遇到像 CSS 和 JS 或者图像等不显示的问题，可能有以下的两种原因：

一、假如图像, JS, CSS 都不显示，可以通过浏览器的开发者模式中的网络选项等去检查资源的对应地址是否是正确的，然后检查 hugo.yaml 中的 base_url 是否设置正确；

二、假如仅 CSS 不显示，只显示图像和文字，可以打开开发者模式中的控制台，看是否有如下报错：

Error

Failed to find a valid digest in the ‘integrity’ attribute for resource

如果是如下报错的话，可能是由于 minify 生成静态网页时，去掉了 html,js,css 等文件的部分空格和格式，来缩小文件的体积，但是修改后会导致文件校验失败，从而阻止加载，因此就会有两种解决方式：

hugo 设置中关闭校验 bj-Space : 在 hugo.yaml 中添加，（使用toml 配置的情自行修改对应选项）

        
        yaml
    
params:
	assets:
		disableFingerprinting: true

关闭 minify 选项 3rd’s blog

还有一些其他的可能问题：http 和 https 混用

FI

利用ShortCode增加Hugo的样式支持

Wed, 18 Dec 2024 17:15:37 +0000

Important

本文为了避免 hugo 直接将 shortcode 渲染出来，在所有的 {{ 和 < 或 >，% 之间添加空格，具体使用的时候记得去掉。

What’s ShortCode in Hugo Mean 啥是简码

Hugo 中的短代码后续用简码来表示可以理解成一种使用固定方式引用的 Template(或者说 Alias)，通过使用预先定义模版，避免在 markdown 中直接添加大量 html 或者 go templates 代码

通常通过 {{ < shortcode > }} 的方式来调用模版，定义的简码可以为如下的三种形式：

type	example
Single-Word ShortCode	`{{ < year > }}`
With-Params ShortCode	`{{ < img src="URL" title="Title" > }}`
Paired ShortCode	`{{ < shortcode > }} content {{ < shortcode > }}`

来支持不同类型的模版代码，将一些比较复杂的 html 代码通过简码的形式嵌入，可以使得我们的静态博客支持更多的拓展样式；官方文档

Benefits and Limitation 利弊分析

Summary

简码存在什么好处和弊端，应该在什么时候使用简码，什么情况下定义为简码，什么时候将其定义为内置的渲染类型；

正如上文所说，ShortCode 其实本质上可以理解为 Hugo 内置的一种模版功能，通过模版用于在 Markdown 中快速的调用额外的样式，因此优势也就显而易见：

模版的角度：简化书写，具备良好的可重用性，统一管理；
拓展的角度：丰富样式，增强功能

例如我们可以使用简码为文章添加 sidenote(边注)，可以让文章的主体更加简洁，更为美观，效果如下：

虽然使用简码确实能够使得 blog 更加的美观，拓展一些额外的功能，但是相应的会使得本地软件编写时的所见即所得的特性被破坏，同时对文档或者说博客平台迁移的时候也会增加一些额外的工作量对文档进行处理；

当然这里也可以通过对一些开源的笔记软件进行适配去维持所见即所得的效果，但是工作量的增加是实打实的；

为此，退而求其次的，为了保持原 markdown 的可迁移的特性不要被严重破坏，同时能够较好的维持所见即所得的可以考虑使用一下的流程去处理笔者使用 Obsidian 编写文档：

---
title: 文档处理流程
---
flowchart LR
	subgraph source
		MD["Md + ez-HTML"]
		Obs["Obsidian"] --- MD
	end
	subgraph Publish
		Pub["Publish Dir"]
		Hugo["Hugo"] --- Pub
	end
	source --Cond--> Scr["Convert Md"]
	Scr --> Publish
	Publish --> Tri["Tiggle Publish"]

在源文件中尽可能的使用原生的 markdown 和一些简单的 html 去编写，然后触发转换脚本之后，根据各种不同的条件（例如发布平台）去进行 markdown 的转换（html 转换为短代码，或删除多余部分）并发布到对应的路径上去触发发布任务；

以边注为例，这里可以使用 content 在 Obsidian 中显示其脚注的特性，然后当发布到 Hugo 的时候，利用脚本将 small 转换为 sidenote 的形式即可，这里替换起来还是很简单的；

        
        python
    
import re
content = re.sub(r'', '', content)
content = re.sub(r'', '', content)

整体而言，笔者认为尽量少用那些比较特异的样式来破坏 markdown 的所见即所得的特性，但是可以通过这这种简单的 html 格式来保持的倒是无所谓，像是一些时间轴之类的，或者一些比较复杂的样式，建议还是少用，或者在一些场景将其转换为图片嵌入，主要的部分还是要让博客回归内容本身；

Some Default ShortCode 默认简码

hugo 本身支持了部分的 ShortCode，这里简单列举记录，便于需要的时候调用，同时避免重复造轮子：

Name	Example
Gist	`{{ < gist spf13 7896402 > }}`
Ins	`{{ < instagram CxOWiQNP2MO > }}`
Twitter	`{{ < twitter user="SanDiegoZoo" id="1453110110599868418" > }}`
Youtube	`{{ < youtube 0RKpf3rK57I > }}`

这些具体的参数或者更多默认的一些 Shortcode 可以去官网查阅，这里就不在多说。

How To Design a ShortCode 编写简码

主要的流程如下，如果需要自己定义，建议还是去官网查看详细的文档、参数和优先级说明。

一、创建简码文件

在 Hugo 项目的 layout/shortcodes 中新建 【keyword】.html 文件，这里文件名的 keyword 会成为后续调用简码时的关键词；

二、编写简码文件

使用 Go template 和 html 编写你所需要的拓展样式，并通过 Go template 获取调用简码时传入的内容和参数进行处理和渲染；

下面简单列一些获取采位置参数，设定参数的写法：

        
        go
    
{{ .Get "class" }}
{{ .Get 0 }}

获取 Paired 中填写的内容则可以使用 .Inner 去获取，如下：

        
        go
    
{{ if strings.ContainsNonSpace .Inner }}
  Inner is not empty
{{ end }}

更多参数和内置变量和方法请参见官网文档和说明。

三、调用简码

使用 {{ < keyword > }} 或者 {{ % keyword % }} 的方式，或是上述提及的 paired 的方式进行调用。

What I Support In My Website

Summary

本章节主要分享&感谢一些本博客中使用的短代码的来源，并简单介绍部分我修改或者编写的短代码，包括加密还有边注的短代码；

主题中引入的大部分 Shortcode 来自以下几位博主，这里简单整理了一下，这里就不再重复，如果需要的话可以转到博主的文章中查看，感谢几位博主的分享!!：

author	shortcodes
荷载独彷徨	文字对齐、github 卡片、notice(两种)、quote(两种)
Naive koala	Notice、隐藏内容、聊天气泡、时间轴、友联、块引用、bilibili、腾讯视频
YC Photography	iframe
向着悠远的苍穹	PPT、PDF、博客内链、代码折叠

部分博主使用的是 Scss，使用的时候可以去网上搜索一下 Scss 转 css 的去转换成自己熟悉的格式，再根据自己主题的配色和习惯去简单调整一下 css 样式即可。

接下来介绍一下自己修改或者编写的一些简码，这里也分享出来供大家参考：

Sidenote 边注简码

笔者希望博客能够充分利用视区的宽度，因此将 Papermod 的 Nav 和 Toc 都改到了侧边，但是通常使用宽屏阅读的时候，感觉还是有一部分空间没有被利用，决定通过简码支持 MarginNote 这里受台运鹏该博客的启发，感谢其分享

最终参考 KF KF: Marginal Notes 和 a Scripter Sidenotes using only CSS ❚ A Scripter’s Notes 的实现，编写 hugo 的 shortcode，其核心就在于

使用 relative 和 float 进行 postion 控制
然后通过-值的 margin 来校准位置
考虑响应式的要素再去启用侧边注释，否则就嵌入正文中
使用 counter 做脚注

最终 shortcode 在本博客中呈现的效果和对应的 html 和 css 如下：

        
        html
    
<span class="sidenote-number"><small class="sidenote">{{ .Inner | markdownify }}small>span>

        
        
        
        css
    
.sidenote {
  font-size: 80%;
  position: relative;
}
/* Wide viewport */
@media (min-width: 1500px) {
  .sidenote {
    float: left;
    clear: left;
    margin-left: -16vw;
    text-align: right;

    top: 0rem;
    width: 13vw;
    margin-top: 1rem;
    
    border-top: 2px solid rgb(0, 0, 0);
  }
  .dark .sidenote{
    border-top: 2px solid rgb(255, 98, 0);
  }
}

/* Sidenote counter */
main {
  counter-reset: sidenote-counter;
}
.sidenote-number {
  counter-increment: sidenote-counter 1;
  
}
/* Counter before the sidenote in the margin. */
.sidenote::before {
  content: counter(sidenote-counter) ".";
  position: relative;
  vertical-align: baseline;
  font-size: 0.9em;
  font-weight: bold;
}
/* Counter in the main body. */
.sidenote-number::after {
  content: counter(sidenote-counter);
  vertical-align: super;
  font-size: 0.7em;
  font-weight: bold;
  margin-right: 0.5rem;
}
@media (min-width: 1400px) {
  /* Highlight the sidenote when mouse hovers on the sidenote number in body. */
  .sidenote-number:hover .sidenote {
    -webkit-backdrop-filter: blur(30px);
    backdrop-filter: blur(30px);
    background-color: #ffffff7a;
    border-radius: 5px;
    font-weight: bold;
    padding: 5px;
    box-shadow: 5px 5px 10px rgb(25, 25, 25),
                -5px -5px 10px rgb(60, 60, 60);
  }
  .dark .sidenote-number:hover .sidenote {
    background-color: rgba(0, 0, 0, 0.5);
  }
}
.dark .sidenote-number small.sidenote,
.dark .sidenote-number small.sidenote a {
  color: rgb(255, 179, 0);
}
.sidenote-number + p {
  display: inline;
}

p:has(+ .sidenote-number) {
  display: inline;
}

也遇到了一些小问题：

Error

counter 计数混乱

一开始使用 body 去做 counter-reset ，后续改为 main 去做 counter-reset 后就好，没有找到中间哪里触发了 body 的 reset，如果有了解的希望指点一二，感恩；

还有一些其他可以借鉴的 MarginNote 的实现如下，感兴趣的大家可以去看看：

Encrypt 加密简码实践

由于博客难免会写一些只想自己看或者说，只想和朋友分享的内容，因此在之前的 hexo 中支持了加密的功能，于是在 hugo 上找替代品的时候，目前发现的都是需要外部的代码|二进制执行，或是使用 submodule，这里为了更简单一些就尝试将其改为简码的模式；

参考 Li4n0的hugo_encryptor 借助 Gpt4o 将其改为纯 html+js 的形式，由此实现利用简码对文章加密，效果如下：

但是这个方法的加密实际上是一个伪加密，存在以下的问题：

一篇文章仅能加密一次，否则会使得密码出错;
无法加密源文件，文章的内容仍能通过开发者模式中的源文件进行查看未加密的 html，只是无法直观的获取。

这是由于该脚本仅仅是对加载过程中的网页进行加密，但是对对应的 html 内容是没有加密的

这是由于 hugo 静态站点生成的本质，如果需要完全的加密的话，可能还是要考虑外部对生成的 html 进行处理，或者看能不能想办法干预 hugo 本身生成静态文件的过程，这里由于笔者本身对相应的技术栈还不是特别熟悉，因此暂且搁置。

这里还尝试了 Li4n0的hugo_encryptor 和 hugoArticleEncryptor 都会对我的主题样式产生严重的影响，导致无法使用，如果有需要彻底加密的还是建议去参考他们的实现；

这里分享一下笔者基于 Li4n0 将加密过程改到 shortcode 中的代码如下，：

        
        
        
        html
    
<head>
    
    <script src="https://mirrors.sustech.edu.cn/cdnjs/ajax/libs/crypto-js/3.1.9-1/crypto-js.js">script>
head>

{{ $_hugo_config := `{ "version": 1 }` }}
{{/*
    ## Hugo Encrypt
    ### Params:
    - `password`:
        require param
    - Simple
*/}}
{{/* DEFAULTS */}}

<div class="hugo-encryptor-container">
  <div class="hugo-encryptor-prompt">
    {{ if eq .Site.Params.hugoEncryptorLanguage "en-us" }}
      <p>Part of this article is encrypted with password:p>
    {{ else }}
      <p>文章的部分内容被密码保护：p>
    {{ end }}
  div>
  <div class="hugo-encryptor-form">
    <input
      class="hugo-encryptor-input"
      placeholder='{{ if eq .Site.Params.hugoEncryptorLanguage "en-us" }}Please input the password{{ else }}请输入密码{{ end }}'
    />
    <input
      class="hugo-encryptor-button"
      type="button"
      value='{{ if eq .Site.Params.hugoEncryptorLanguage "en-us" }}Click to verify{{ else }}CLICK{{ end }}'
      onclick="_click_handler(this)"
    />
  div>
  <div
    class="hugo-encryptor-cipher-text"
    data-password="{{ .Get 0 }}"
    style="display: none;"
  >
    <span style="display: none;">--- DON'T MODIFY THIS LINE ---span>
    {{ .Inner }}
  div>
div>

<script>
    // This script should be included in your Hugo templates
// Make sure to include the crypto-js library in your HTML

function sanitizeContent(content) {
    // Remove unwanted characters (like control characters)
    return content.replace(/[\x00-\x1F\x7F]/g, '').trim(); // Remove control characters and trim whitespace
}

function encryptContent(password, content) {
    const key = CryptoJS.MD5(password).toString();
    const iv = key.substring(16); // Use the second half of the key as IV
    const paddedContent = padContent(content);
    const encrypted = CryptoJS.AES.encrypt(paddedContent, CryptoJS.enc.Utf8.parse(key), {
        iv: CryptoJS.enc.Utf8.parse(iv),
        mode: CryptoJS.mode.CBC,
        padding: CryptoJS.pad.Pkcs7
    });
    return CryptoJS.enc.Base64.stringify(encrypted.ciphertext);
}

function padContent(content) {
    const blockSize = 32; // AES block size
    const padlen = blockSize - (content.length % blockSize);
    // const padding = String.fromCharCode(padlen).repeat(padlen);
    // return content + padding;
    return content;
}

function processEncryptedBlocks() {
    const blocks = document.querySelectorAll('.hugo-encryptor-cipher-text');
    blocks.forEach(block => {
        const password = block.getAttribute('data-password');
        const content = block.innerHTML.trim(); // Trim whitespace
        const sanitizedContent = sanitizeContent(content); // Sanitize content
        const encryptedContent = encryptContent(password, sanitizedContent);
        block.innerHTML = encryptedContent;
        block.removeAttribute('data-password');
    });

    // Append the decrypt.js script
    const script = document.createElement('script');
    script.src = '/js/decrypt.js';
    document.body.appendChild(script);
}

// Call the function to process the blocks after the DOM is fully loaded
document.addEventListener('DOMContentLoaded', processEncryptedBlocks);
script>

对应的样式设置如下

        
        
        
        css
    
/* change the style of the encrypt button & input */
/* only encrypt once in one posts. */

.hugo-encryptor-container:has(>.hugo-encryptor-prompt) {
    border-top: 2px solid black;
    border-bottom: 2px solid black;
    /* background: rgb(0 0 0 / 20%); */
    backdrop-filter: blur(5px);
    padding: 5px;   
    margin-bottom: 10px;
}
.dark .hugo-encryptor-container:has(>.hugo-encryptor-prompt) {
    border-top: 2px solid #5cbd63;
    border-bottom: 2px solid #5cbd63;
}

.hugo-encryptor-prompt {font-weight: bold;}

input.hugo-encryptor-input {
    border: 2px solid black;
    color: var(--primary);
}

input.hugo-encryptor-button {
    border: unset;
    background: black;
    border-radius: 20px;
    padding: 0px 5px;
    box-shadow: 0px 0px 2px 2px rgb(0,0,0);
    color:azure
}

input.hugo-encryptor-button:hover {
    background-color:#5cbd63;
    transition: 0.7s;
}

input.hugo-encryptor-button:focus {
    outline-color: transparent;
    outline-style:solid;
    box-shadow: 0 0 0 4px #5cbd63;
}

input.hugo-encryptor-input:focus{
    outline-color: transparent;
    outline-style:solid;
    box-shadow: 0 0 0 1px #0e0912;
}
.dark input.hugo-encryptor-input:focus{
    box-shadow: 0 0 0 1px #5cbd63;
}

.post-single:has(.post-content .hugo-encryptor-prompt) #toc-container{
    display: none;
}

此外当你有加密的需求，记得把你的 repo 改为 Private，不然图啥呢是吧🔒；

FI

我可以不用，但是我得有啊，你说是不?

修改Hugo中Markdown的基础渲染

Tue, 17 Dec 2024 17:38:18 +0000

Summary

利用 hugo 主题的 render hook 的功能，修改 markdown 转换为 html 的样式，通过这种方法更改特定 Markdown 元素的渲染；

What’s Render Hook In Hugo 啥是渲染钩子

Render Hook 是 Hugo 给希望增强 Markdown 渲染功能的开发者留出的工具，通过 Render Hook 可以使开发者为各种 Markdown 元素创建自定义的渲染模版，满足不同用户对于渲染的不同需求；

具体而言，当编辑/创建如下这些特定路径的文件，其会覆盖默认的 markdown 渲染成 html 的方式，具体路径为 Render Hooks Introduction ：

        
        
        
        text
    
layouts/
└── _default/
    └── _markup/
        ├── render-blockquote.html  # 渲染引用快
        ├── render-codeblock.html   # 渲染代码块
        ├── render-image.html       # 图片
        ├── render-link.html        # 链接
        └── render-table.html       # 表格

具体的参数和各种类型的具体文件，请在修改的时候参考对应的官方文档即可，如：codeBlock

Why ？为啥使用它呢

简单介绍 Render Hook 后，其实其优点就呼之欲出了：

灵活 | 可自定义 | 增强功能：可以根据自己的需求随意的更改渲染的样式，甚至嵌入 js 引入复杂功能（收起，复制等）；
无需对博文做任何调整，不破坏 markdown 本身的可迁移性；
一劳永逸，统一管理；

同时默认的样式在功能和外观上都比较基础，很多特性不被支持，如：

外部打开链接
代码块的复制和折叠
图片的大小限制和位置限制等

而为了支持这些特性，相比借助简码使用支持原生 markdown 的 render hook 去实现新特性，保持文章的简洁和完整性，那当然是最好不过；

Define Personal Render 定义自己的渲染

Mermaid 流程图支持

官方文档已经给出了对应的支持方案，主要分为三步：

一、在 layouts/_default/_markup/render-codeblock-mermaid.html 中添加

        
        html
    
<pre class="mermaid">
    {{- .Inner | htmlEscape | safeHTML }}
  pre>
  {{ .Page.Store.Set "hasMermaid" true }}

二、在内容模版的底部添加如下内容（这里我是添加到 ``layouts/_default/single.html` 中）

        
        
        
        html
    
{{ if .Store.Get "hasMermaid" }}
  <script type="module">
    import mermaid from 'https://cdn.jsdmirror.com/npm/mermaid/dist/mermaid.esm.min.mjs';
    // import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/+esm'
    mermaid.initialize({ 
      startOnLoad: true,
      'theme': 'dark',
     });
  script>
  {{ end }} 

可以修改 CDN 来加速 mermaid 的加载感谢blog.jsdmirror.com 的镜像站

三、可以在 markdown 中通过代码块的方式调用 mermaid ：

四、如果 mermaid 仍然渲染失败，或者没有开始渲染，尝试将 guessSyntax 设置为 false 如下 Mermaid doesn’t work 从零开始搭建Hugo博客：

        
        yaml
    
markup:
  highlight:
    guessSyntax: true

最终应该可正常渲染 mermaid，下面是一个随机例子

从零开始搭建Hugo博客中还有两种其他的支持 mermaid 的方式，感兴趣的也可以参考；

Image 自适应图片大小 & FancyBox 查看原图

多年图像不居中就难受症候群，对原始的图片渲染确实是十分不满意，同时一些比较大/长的图片也会很破坏整个页面的结构和阅读体验，为了避免用 html 逐个调整，因此修改图像的默认 render hook 这里感谢夜云泊分享的十分完整的解决方案；

这里我针对 PaperMod 主题对夜云泊提供的代码做了简单的改动，具体原因已不可考，依稀记得是由于原始的 markdown 中有部分用 html 呈现的图像会有一些问题：

修改后的 render-image.html 如下：

        
        
        
        html
    
{{- $u := urls.Parse .Destination -}}
{{- $src := $u.String -}}
{{- if not $u.IsAbs -}}
  {{- $path := strings.TrimPrefix "./" $u.Path }}
  {{- with or (.PageInner.Resources.Get $path) (resources.Get $path) -}}
    {{- $src = .RelPermalink -}}
    {{- with $u.RawQuery -}}
      {{- $src = printf "%s?%s" $src . -}}
    {{- end -}}
    {{- with $u.Fragment -}}
      {{- $src = printf "%s#%s" $src . -}}
    {{- end -}}
  {{- end -}}
{{- end -}}
{{- $attributes := merge .Attributes (dict "alt" .Text "src" $src "title" (.Title | transform.HTMLEscape) "loading" "lazy") -}}
{{if .Page.Site.Params.fancybox }}
<div class="post-img-view">
  <a data-fancybox="gallery" href="{{ .Destination | safeURL }}">
    <img {{- with $attributes -}}
    {{- range $k, $v := . -}}
      {{- if $v -}}
        {{- printf " %s=%q" $k $v | safeHTMLAttr -}}
      {{- end -}}
    {{- end -}}
  {{- end -}}  class="responsive-image" src="{{ .Destination | safeURL }}" style="display: block; margin: 0 auto;"
      alt="{{ .Text }}" {{ with .Title}} title="{{ . }}" {{ end }} />
  a>
div>
{{else}}
<img
  {{- range $k, $v := $attributes -}}
    {{- if $v -}}
      {{- printf " %s=%q" $k $v | safeHTMLAttr -}}
    {{- end -}}
  {{- end -}} style="display: block; margin: 0 auto; " class="responsive-image">
{{- /**/ -}}
{{ end }}

<script>
  document.addEventListener("DOMContentLoaded", function() {
      var images = document.querySelectorAll(".responsive-image");
      var maxHeight = window.innerHeight / 2.5;
      images.forEach(function(image) {
          image.style.maxHeight = maxHeight + "px";
      });
  });
script>

然后去 Hugo 配置文件 hugo.yml 中新增一项：

        
        yaml
    
params:
  fancybox: true

具体的代码介绍请转向原作者 👍，最终效果如下：

开启 fancybox：

Link 默认新窗口打开网页

参考： How to open plain URL links in a new tab? - support - HUGO 实现如下 render-link.html：

        
        html
    
<a href="{{ .Destination | safeURL }}" {{ with .Title}} title="{{ . }}" {{ end }}{{ if strings.HasPrefix
    .Destination "http" }} target="_blank" rel="noopener" {{ end }}>{{ .Text | safeHTML }}a>

Code Block 代码折叠

由于有时会分享一些较长的代码，如果始终使代码完整呈现的话，其实页面不是那么的美观，而且也废滚轮，因此感觉折叠功能还是很必要的🔥，同时由于默认的样式怎么看都有些变扭，因此也顺便的加上标签栏来优化对应的样式。

实现代码折叠主要是如下思路：

将原本的代码渲染包含在
中；
新增同级别元素
用于存放标题，同时作为开关控制折叠；

接着话不多说开始实现，首先获取原本的基础实现和一些基本参数 Code block render hooks | Hugo 如下：

        
        go
    
{{ $result := transform.HighlightCodeBlock . }}
{{ $result.Wrapped }}

该代码置于 render-codeblock.html 中，为默认的代码块渲染样式，如果需要修改特定语言的渲染，可以参考官方文档和 mermaid 的方式去处理；

接着就很简单了，通过 {{.Type}} 可以获取语言类型信息用作 title，然后通过 js 和 css 实现折叠效果和样式调整即可，最终实现效果如下：

折叠后：

具体代码如下：

        
        
        
        html
    
<div class="code-block">
    <div class="code-title" onclick="toggleCode(this)">
        <span class="code-block-open"><ion-icon name="code-slash-outline">ion-icon>span>
        <span>{{.Type}}span>
    div>
    <div class="code-content">
        {{ $result := transform.HighlightCodeBlock . }}
        {{ $result.Wrapped }}
    div>
div>

<script>
function toggleCode(element) {
    const codeContent = element.nextElementSibling;
    if (codeContent.style.display === "none" || codeContent.style.display === "") {
        codeContent.style.display = "block"; // Show the code block
        codeContent.parentNode.classList.remove("code-has-hidden-child");
    } else {
        codeContent.style.display = "none"; // Hide the code block
        codeContent.parentNode.classList.add("code-has-hidden-child");

    }
}
script>

        
        
        
        css
    
.code-block {
    background: var(--code-block-bg);
    box-shadow: 0px 4px 30px rgba(0, 0, 0, 0.5);
    border-radius: 8px;
    position: relative;
    /* padding: 2px; */
    margin: 8px 0px;
}

.code-title {
    display: flex;
    align-items: center;
    justify-content: space-between;
    margin: 10px;
    border-bottom: 1px solid rgba(255, 255, 255, 0.602);
    cursor: pointer;

}

.code-title span {
    letter-spacing: 1.57px;
    color: rgb(212 212 212);
    /* width: 90%; */
    /* align-items: center; */
    font-size: 1rem;
    padding: 5px;
    padding-left: 10px;
    text-transform: capitalize;
}

.code-has-hidden-child {
    border: 1px solid salmon;
}

此外这里也将 copy-code 按钮挪到了标题栏上，主要是修改 copy 的样式和渲染位置可以参考 [Feat] update default code style · AikenH 剩余部分的修改，感兴趣的也可以点个 star，感谢。

Alert-Blockquote 特殊引用块

在之前简码部分的博客已经介绍了一些特殊的引用块样式和实现，可以根据官网 Blockquote render hooks | Hugo 将其改为自己的默认引用块即可，即可 markdown 中按照如下方式引用实现：

        
        markdown
    
> [!{alert-keywork}]
> {alert-content}

这是本博客中部分样式展示：

Note 样式：

Note

test note block’s style.

important 样式

Important

重要内容

Error 样式

Error

Error

该部分可以发现大家都参考了 hugo-notice ，而本博客则是在其他博主分享感谢 tom’s blog 感谢绅士喵的样式之上根据本人的 Obsidian 调整了一下样式和默认值，具体实现如下：

        
        
        
        html
    
{{ $alertTypes := dict
  "note" "<path d=\"M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z\">path>"
  "tip" "<path d=\"M8 1.5c-2.363 0-4 1.69-4 3.75 0 .984.424 1.625.984 2.304l.214.253c.223.264.47.556.673.848.284.411.537.896.621 1.49a.75.75 0 0 1-1.484.211c-.04-.282-.163-.547-.37-.847a8.456 8.456 0 0 0-.542-.68c-.084-.1-.173-.205-.268-.32C3.201 7.75 2.5 6.766 2.5 5.25 2.5 2.31 4.863 0 8 0s5.5 2.31 5.5 5.25c0 1.516-.701 2.5-1.328 3.259-.095.115-.184.22-.268.319-.207.245-.383.453-.541.681-.208.3-.33.565-.37.847a.751.751 0 0 1-1.485-.212c.084-.593.337-1.078.621-1.489.203-.292.45-.584.673-.848.075-.088.147-.173.213-.253.561-.679.985-1.32.985-2.304 0-2.06-1.637-3.75-4-3.75ZM5.75 12h4.5a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1 0-1.5ZM6 15.25a.75.75 0 0 1 .75-.75h2.5a.75.75 0 0 1 0 1.5h-2.5a.75.75 0 0 1-.75-.75Z\">path>"
  "important" "<path d=\"M0 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v9.5A1.75 1.75 0 0 1 14.25 13H8.06l-2.573 2.573A1.458 1.458 0 0 1 3 14.543V13H1.75A1.75 1.75 0 0 1 0 11.25Zm1.75-.25a.25.25 0 0 0-.25.25v9.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h6.5a.25.25 0 0 0 .25-.25v-9.5a.25.25 0 0 0-.25-.25Zm7 2.25v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 9a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z\">path>"
  "warning" "<path d=\"M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z\">path>"
  "caution" "<path d=\"M4.47.22A.749.749 0 0 1 5 0h6c.199 0 .389.079.53.22l4.25 4.25c.141.14.22.331.22.53v6a.749.749 0 0 1-.22.53l-4.25 4.25A.749.749 0 0 1 11 16H5a.749.749 0 0 1-.53-.22L.22 11.53A.749.749 0 0 1 0 11V5c0-.199.079-.389.22-.53Zm.84 1.28L1.5 5.31v5.38l3.81 3.81h5.38l3.81-3.81V5.31L10.69 1.5ZM8 4a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 8 4Zm0 8a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z\">path>"
  "error" "<path d=\"M4.47.22A.749.749 0 0 1 5 0h6c.199 0 .389.079.53.22l4.25 4.25c.141.14.22.331.22.53v6a.749.749 0 0 1-.22.53l-4.25 4.25A.749.749 0 0 1 11 16H5a.749.749 0 0 1-.53-.22L.22 11.53A.749.749 0 0 1 0 11V5c0-.199.079-.389.22-.53Zm.84 1.28L1.5 5.31v5.38l3.81 3.81h5.38l3.81-3.81V5.31L10.69 1.5ZM8 4a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 8 4Zm0 8a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z\">path>"
}}

{{
  $default := "<path d=\"M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z\">path>"
}}
  
  
{{ if eq .Type "alert" }}
<blockquote class="alert-blockquote alert-{{ .AlertType }}">
  <p class="alert-heading">
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16">
      {{- $alertType := index $alertTypes .AlertType | default $default }}
      {{ $alertType | safeHTML }}
    svg>
    <span>{{ or (i18n .AlertType) (title .AlertType) }}span>
  p>
  {{ .Text | safeHTML }}
blockquote>
{{ else }}
<blockquote>
  {{ .Text | safeHTML }}
blockquote>
{{ end }}

        
        
        
        css
    
.alert-blockquote {
  --title-color: #fff;
  --content-color: inherit;
  padding: 18px 18px 10px 18px !important;
  line-height: 24px;
  margin: 1rem 0;
  border-radius: 4px;
  color: var(--content-color);
  /* border-left: none !important; */
  /* border: 1px solid black; */
}

.dark .alert-blockquote *,
.alert-blockquote * {
  color: var(--content-color) !important;
}

.post-content blockquote%3Ep>p{
    padding: unset;
}

.alert-blockquote .alert-heading {
  margin: -18px -18px 12px;
  padding: 10px 18px;
  border-radius: 4px 4px 0 0;
  font-weight: 600;
  color: var(--title-color) !important;
  display: flex;
  align-items: center;
}

.alert-blockquote .alert-heading svg {
  width: 1em !important;
  height: 1em !important;
  margin-right: 0.5rem !important;
  fill: currentColor !important;
}

.alert-blockquote p:last-child {
  margin-bottom: 0;
}

/* Light theme */
/* default */
.alert-blockquote {
  border-top:unset;
  /* border: 1px solid #166dd0; */
  /* --title-background-color: rgba(221, 233, 244, 0.631); */
  --content-background-color: rgba(221, 233, 244, 0.602);
}
.alert-blockquote > .alert-heading {
  /* border-bottom: 1px dashed #166dd07c; */
  color: #0969da !important;
}

/* note */
.alert-blockquote.alert-note {
  /* border: 1px solid #166dd0; */
  /* border-left-color: #0969da !important; */
  /* --title-background-color: rgba(221, 233, 244, 0.631); */
  --content-background-color: rgba(221, 233, 244, 0.602);
}
.alert-blockquote.alert-note .alert-heading {
  color: #0969da !important;
}

/* tip */
.alert-blockquote.alert-tip {
  /* border: 1px solid #1a7f37; */
  /* --title-background-color: rgb(173,193,182); */
  --content-background-color: rgba(222, 240, 223, 0.7);
}
.alert-blockquote.alert-tip .alert-heading {
  color: #1a7f37 !important;
  /* border-bottom: 1px dashed #1a7f37; */
}

/* important */
.alert-blockquote.alert-important {
  /* border: 1px solid #8250df; */
  /* border-left-color: #8250df !important; */
  /* --title-background-color: #6843ae7c; */
  --content-background-color: rgba(235, 227, 245, 0.9);
}

.alert-blockquote.alert-important .alert-heading {
  color: #8250df !important;
  /* border-bottom: 1px dashed #8250df; */
}

/* warning */
.alert-blockquote.alert-warning {
  /* border: 1px solid #9a6700; */
  /* border-left-color: #9a6700 !important; */
  /* --title-background-color: rgb(232, 198, 140); */
  --content-background-color: rgba(243, 232, 222);
}
.alert-blockquote.alert-warning .alert-heading {
  color: #9a6700 !important;
  /* border-bottom: 1px dashed #9a6700; */
}

/* caution */
.alert-blockquote.alert-error,
.alert-blockquote.alert-caution {
  /* border: 1px solid #cf222e; */
  /* border-left-color: #cf222e !important; */
  /* --title-background-color: rgb(244, 224, 223,0.5); */
  --content-background-color: rgba(243, 207, 205, 0.9);
}
.alert-blockquote.alert-error .alert-heading,
.alert-blockquote.alert-caution .alert-heading {
  color: #cf222e !important;
  /* border-bottom: 1px dashed #cf222e; */
}

/* Dark theme */
.dark .alert-blockquote {
  border-top:unset;
  /* --content-color: #d0d7dd; */
  /* --title-background-color: #5151527c; */
  --content-background-color: rgba(22, 37, 50, 0.8);
}

.dark .alert-blockquote .alert-heading {
  color: #58a6ff !important;
}

.dark .alert-blockquote.alert-note {
  /* --title-background-color: #58a6ff7c; */
  --content-background-color: rgba(22, 37, 50, 0.8);
}
.dark .alert-blockquote.alert-note .alert-heading {
  color: #58a6ff !important;
}

.dark .alert-blockquote.alert-tip {
  /* --title-background-color: #82bd8a7c; */
  --content-background-color: rgba(55, 84, 56, 0.7);
}
.dark .alert-blockquote.alert-tip .alert-heading {
  color: #3fb950 !important;
}

.dark .alert-blockquote.alert-important {
  /* --title-background-color: #9173c57c; */
  --content-background-color: rgba(46, 32, 62, 0.9);
}
.dark .alert-blockquote.alert-important .alert-heading {
  color: #8d62d8 !important;
}

.dark .alert-blockquote.alert-warning {
  /* --title-background-color: #d1b068a0; */
  --content-background-color: rgb(84, 68, 55);
}
.dark .alert-blockquote.alert-warning .alert-heading {
  color: #d1b271 !important;
}

.dark .alert-blockquote.alert-error,
.dark .alert-blockquote.alert-caution {
  /* --title-background-color: #c94a43; */
  --content-background-color: rgba(108, 57, 54, 0.9);
}
.dark .alert-blockquote.alert-error .alert-heading,
.dark .alert-blockquote.alert-caution .alert-heading {
  color: #ff9791 !important;
}

.alert-blockquote .alert-heading {
  background: var(--title-background-color);
}

.alert-blockquote {
  background: var(--content-background-color);
}


blockquote:not(.alert-blockquote){
  color: #a02222c2;
  border-top: 2px solid  #9c1e1ec2;
  font-size: 0.9rem;
  font-style: italic;
}

源码也都已经在 Github 中分享。

Change Default Renders’ Style 改变一些默认样式

除了上述 markdown 基本单元的渲染调整，表格的样式也不是特别美观，但是由于表格本身的 html 模版已经不在需要调整，因此这里仅对其 css 样式做调整。

Tables 表格样式调整

默认的表格本身主要存在以下的一些问题：

非全宽&不居中：这里考虑直接调整为全宽；
样式单调：可以按照需求调整为三线表或者调整一下标题栏等；
可以添加 Hover 效果来优化交互；

这里通过将 display 调整为 table 来支持全宽，同时通过 overflow 和 wordbreak 等属性来自适应格子宽度避免溢出 Responsive tables in markdown - support - HUGO html - Horizontal scroll on overflow of table - Stack Overflow ；

样式代码如下，编写的时候要避免 table 属性对其他元素的影响，特别是代码块，因此需要用 not 属性做一些排除：

        
        
        
        css
    
/* make the table fully wide  & style */
.post-content table:not(.lntable .highlighttable,.highlight table,.gist .highlight){
  display: table;
  background-color: transparent;
  border-radius: 6px;
  border: 1px solid black;
  outline: 2px solid black;
  overflow-x: auto;
  table-layout: fixed;
  word-break: break-all;
}
/* responsive ref */
/* ref: https://discourse.gohugo.io/t/responsive-tables-in-markdown/10639/8 */
/* ref: https://stackoverflow.com/questions/19794211/horizontal-scroll-on-overflow-of-table/62451601#62451601 */

.dark .post-content table:not(.lntable .highlighttable,.highlight table,.gist .highlight){
  outline: 2px solid rgb(54, 156, 95);
}

.post-content table:not(.lntable .highlighttable,.highlight table,.gist .highlight) thead{
  background-color: #545d7b8a;
}

.dark .post-content table:not(.lntable .highlighttable,.highlight table,.gist .highlight) thead{
  background-color: rgb(62, 62, 62);
}

.post-content table:not(.lntable .highlighttable,.highlight table,.gist .highlight) td,
.post-content table:not(.lntable .highlighttable,.highlight table,.gist .highlight) tr,
.post-content table:not(.lntable .highlighttable,.highlight table,.gist .highlight) th{
  border-bottom: unset;
  border: 1px solid black,
}

.post-content table:not(.lntable .highlighttable,.highlight table,.gist .highlight) td:hover,
.post-content table:not(.lntable .highlighttable,.highlight table,.gist .highlight) td:focus{
  background-color: rgba(170, 217, 248, 0.8);
  /* transform: scale(1.1); */
  /* border: 2px solid black; */
}

.dark .post-content table:not(.lntable .highlighttable,.highlight table,.gist .highlight) td:hover,
.dark .post-content table:not(.lntable .highlighttable,.highlight table,.gist .highlight) td:focus{
  background-color: rgb(0, 0, 0, 0.7);
  /* transform: scale(1.1); */
  /* border: 2px solid black; */
}

Fi

有错误欢迎指正和交流，感兴趣的也欢迎去 github 上点个 star，不胜感激；

调整PaperMod的页面结构以及新增功能

Sun, 15 Dec 2024 16:52:43 +0000

Summary

除了基础的样式和功能，本篇介绍一些会改变原本页面结构的样式调整，或是支持一些除了 markdown 渲染外的一些额外的功能。

Assign Unique ClassName for Pages 给页面注册单独的类名

在进行一些比较复杂的样式设置之前，为了避免样式会影响到预期之外的页面，因此通过 hugo 中的 go-template 语法判断页面类型后，通过修改原有模版，给搜索，时间线，profile 等页面注册一个单独的类名。

修改 themes/PaperMod/layouts/_default/baseof.html，将其中对应部分替换为如下内容：

        
        
        
        html
    
<body class="
{{- if (or (ne .Kind `page` ) (eq .Layout `archives`) (eq .Layout `search`)) -}}
{{- print "list" -}}
{{- end -}}
{{- if eq .Type `linklog` -}}
{{- print "-linklog-" -}}
{{- end -}}
{{- if eq .Layout `search` -}}
{{- print " search" -}}
{{- end -}}
{{- if (eq .Layout `archives`) -}}
{{- print "-archive" -}}
{{- end -}}
{{- if .IsHome -}}
{{- print "-profile" -}}
{{- end -}}
{{- if not .IsHome | and .Title | and .Description }}
{{- print "post" -}}
{{- end -}}
{{- if eq site.Params.defaultTheme `dark` -}}
{{- print " dark" }}
{{- end -}}
" id="top">

替换即可通过如下的 class 对页面进行索引：

Selector	Page
.list-linklog-post	linklog 页面
.list.search	search 界面
.list-archive	archive 界面
.list-profile	主页

在上述页面选择器之后添加 .dark 即可定位对应的深色主题样式，这部分可以按照自己的习惯去随便修改即可。

Background Image 设置背景

可以参考笔者的设置，给背景添加一层简单的遮罩，具体代码如下：

        
        
        
        css
    
#top,
.list,
.list-profile {
  background-image: url(/cover/cover1.jpeg);
  background-size: cover;
  background-repeat: no-repeat;
  background-attachment: fixed;
}

#top.dark,
.list.dark,
.list-profile.dark {
  background-image: url(/cover/cover0.jpeg);
}

#top::after,
.list::after,
.list-profile::after {
  background: inherit;
  filter: blur(5px);
  content: "";
  position: fixed;
  top: 0;
  left: 0;
  width: 100%;
  min-height: 100%;
  background-size: cover;
  z-index: -1;
  background-attachment: fixed;
}

如果后续由于背景图像的色块比较杂乱，会导致文本模糊不清，可以给文本区域添加底色和对应的毛玻璃特效如下：

        
        
        
        css
    
.list-archive .main,
.list-linklog-post .main,
#top article.post-single {
  -webkit-backdrop-filter: blur(30px);
  backdrop-filter: blur(30px);
  background-color: rgba(104, 152, 191, 0.45);
}

完成了基础设置之后就可以开始对页面结构做调整了，接下来主要介绍一下侧边目录、侧边导航栏，以及新建分享页面三个部分的页面调整和页面新增。

Support LinkLog Page 添加博文收藏界面

受到 Xiaofei Ge Linklog | Xiaofei Ge 的启发，确实希望能有一个页面来专门存放一些自己喜欢或者希望存档的文章，通过直接跳转或者表明转载（防止原博挂掉）的方式进行收藏，避免和自己的文章混在一起。

参考 Using Hugo as a redirect service - Dan North & Associates Limited ，设计对应收藏博文的 markdown 元信息应该如下：

        
        
        
        yaml
    
title: 「特别篇」在关闭光猫、路由器IPv6防火墙后可能遇到的安全问题
url: "www.bilibili.com/opus/825167559504429056"
date: 2023-11-05
draft: false
type: "linklog"
author: "ce-12"

通过 type 定义页面类型，日期存储我们收藏的时间，url 则是核心的跳转页面，还有一些作者和 title 的展示信息，并在 archive 按照日期展示每一条链接。

因此借助 GPT 快速实现了一版，并调整了一下搜索代码，使得搜索到 Linklog 文章的时候，会有符号&样式去标识其为外部跳转的博文。

Add LinkLog Page 添加博文收藏界面

上述说到希望以 archive 界面的形式来收藏博文，通过简单的标题和简介来记录对应的博文，以及存放博文的时间，因此参考 /layouts/_default/archives.html 创建 layouts/linklog/list.html 如下，定义 LinkLog 的界面.

        
        
        
        html
    
{{- define "main" }}

<header class="page-header">
  <h1>{{ .Title }}h1>
  {{- if .Description }}
  <div class="post-description">{{ .Description }}div>
  {{- end }}
header>

{{- $linklogPages := where site.RegularPages "Type" "linklog" }} 

{{- range $linklogPages.GroupByPublishDate "2006" }}
{{- if ne .Key "0001" }}
<div class="archive-year">
  {{- $year := replace .Key "0001" "" }}
  <h2 class="archive-year-header" id="{{ $year }}">
    <a class="archive-header-link" href="#{{ $year }}">
      {{- $year -}}
    a>
    <sup class="archive-count"> {{ len .Pages }}sup>
  h2>
  {{- range .Pages.GroupByDate "January" }}
  <div class="archive-month">
    <h3 class="archive-month-header" id="{{ $year }}-{{ .Key }}">
      <a class="archive-header-link" href="#{{ $year }}-{{ .Key }}">
        {{- .Key -}}
      a>
      <sup class="archive-count"> {{ len .Pages }}sup>
    h3>
    <div class="archive-posts">
      {{- range .Pages }}
      <div class="archive-entry">
        <h3 class="archive-entry-title">
          {{- if .Params.url}}
            <span class="jump-icon"><ion-icon name="link-outline">ion-icon>span>
            <a href="https://{{ .Params.url }}" target="_blank" rel="noopener noreferrer">{{ .Title }}a> 
          {{- else}}
            <a href="{{ .Permalink }}" >转) {{ .Title }}a> 
          {{- end}}
        h3>
        {{- if .Params.description }} 
        <div class="archive-entry-description">
          {{ .Params.description }} 
        div>
        {{- end }}
        <div class="archive-meta">
          {{- partial "post_meta.html" . -}} 
        div>
      div>
      {{- end }}
    div>
  div>
  {{- end }}
div>
{{- end }}
{{- end }}

{{- end }}{{/* end main */}}

其中根据页面元信息是否存在 url 决定是否是外部链接，来决定 title 前面的样式是跳转符号还是转载标识，随后设置跳转标识的样式如下：

        
        
        
        css
    
.jump-icon {
  position: relative;
  top:3px;
  padding-right: 10px; /* Space between the icon and the title */
  font-size: 1em; /* Adjust size as needed */
}
#search-link{
  text-decoration: underline;
  color: slateblue;
}

.list-linklog-post .archive-entry-description{
  color: var(--secondary);
}

设置完成后，即可在 content 中新建 linklog 文件夹，并在其中存放对应的转载文章，例如 linklog/example.md ，然后填写上述我们设计的格式，尝试跳转效果。最终页面效果如下：

外部链接点击后即可跳转到对应的博文。

Avoid Url Directly Visit Wrong Page 避免直接用 url 访问对应页面时出现空页面

添加 layouts/linklog/single.html 来设置页面的重定向，避免直接输入 linklog 对应地址以后，跳转到了一个空的 markdown 页面，具体代码如下：

        
        
        
        html
    
{{- define "main" }}

{{- if .Params.url }}
<meta http-equiv="refresh" content="0; url=https://{{ .Params.url }}">
<script>
    window.location.href = "https://{{ .Params.url }}";
script>
<title>Redirecting...title>
<p>If you are not redirected, <a href="https://{{ .Params.url }}">click herea>.p>
{{- else }}
....
{{- end }}

{{- end }}{{/* end main */}}

通过判断参数中是否存在 url 来设置是否执行跳转，否则则使用默认的 single.html 的方式渲染 markdown 的转载文章。 else 中省略的部分填写的是 _dafault/single.html 中的内容。

Add Diff Style in Search Result 搜索结果中支持跳转和特殊样式

由于在搜索中可能会搜到对应的文章，这里也需要和普通的文章做一些区分，因此修改 assets/js/fastsearch.js 的搜索结果部分如下：

        
        
        
        js
    
/ execute search as each character is typed
sInput.onkeyup = function (e) {
    // run a search query (for "term") every time a letter is typed
    // in the search box
    if (fuse) {
        let results;
        if (params.fuseOpts) {
            results = fuse.search(this.value.trim(), {limit: params.fuseOpts.limit}); // the actual query being run using fuse.js along with options
        } else {
            results = fuse.search(this.value.trim()); // the actual query being run using fuse.js
        }
        if (results.length !== 0) {
            // build our html if result exists
            let resultSet = ''; // our results bucket

            for (let item in results) {
                const permalink = results[item].item.permalink; // Get the permalink
                
                const url = new URL(permalink)
                const pathAfterDomain = url.pathname;

                console.log("Permalink:", permalink); // Log the permalink

                console.log("Last Segment:", pathAfterDomain); // Log the last segment
                // Check if the last segment contains a period
                const jumpIcon = pathAfterDomain.includes('.') ? '' : '';
                
                if (pathAfterDomain.includes('.'))
                {
                    resultSet += `
                        ${jumpIcon}${results[item].item.title} »
                        ${permalink}" target="_blank" rel="noopener noreferrer" aria-label="${results[item].item.title}">
                    
`;
                }
                else
                {
                    resultSet += `
                        ${jumpIcon}${results[item].item.title} »
                        ${permalink}" aria-label="${results[item].item.title}">
                    
`;
                }
            }

            resList.innerHTML = resultSet;
            resultsAvailable = true;
            first = resList.firstChild;
            last = resList.lastChild;
        } else {
            resultsAvailable = false;
            resList.innerHTML = '';
        }
    }
}

由于在之前的设置下，通过判断搜索结果的跳转链接在我们域名之后是否还存在 . 来判断其是否为外部链接，进而为其添加跳转标识即可，最终效果如下：

Side Toc 宽屏下设置侧边目录

正如以往笔者的 hexo 博客的设置，将目录放到侧边，一是能优化 PaperMod 主题在宽屏时对空间的利用，二是能够方便阅读的时候进行章节的跳转以及对进度的提示，因此下定决心在页面较宽时将目录改至侧边。

实现的方案主要借鉴自周鑫的个人博客，在此之上添加了以下的一些特性：

为已读的内容添加 read 的类名，设置不同的样式；
在加密页面隐藏 toc
仅展开当前正在阅读的章节的子章节
添加 toc 中 H2 的 index

这里仅额外介绍一下改动部分，最终的源码可从 Github 上获取 papermod-sidebar/layouts/partials/toc.html · AikenH/papermod-sidebar papermod-sidebar/assets/css/common/toc.css · AikenH/papermod-sidebar

本博客的回到顶部也是基于周鑫的实现完成，这里不在赘述，可以自行前往参考。

Diff Style for Read & Unread 基于阅读状态修改样式

在周鑫的实现中 toc.html 的滚动函数部分首先添加 read 状态的重置，避免回滚时的样式错误：

        
        
        
        html
    
window.addEventListener('scroll', () => {
	// Get the current scroll position
	const scrollPosition = window.pageYOffset || document.documentElement.scrollTop;

	// Check if the scroll position is at the top of the page
	if (scrollPosition === 0) {
		return;
	}

	// Ensure elements is a valid NodeList
	// ---------------------状态重置添加位置
	if (elements && elements.length > 0) {
		elements.forEach(element => {
			const id = encodeURI(element.getAttribute('id')).toLowerCase();
			const tocLink = document.querySelector(`.inner ul li a[href="#${id}"]`);
			tocLink.classList.remove('read');
		});
	 // --------------------------------------------
		// Check if there is an object in the top half of the screen or keep the last item active
		...
		...

然后再滚动判断 active 元素的部分添加 read 属性的赋值：添加如下 3 行即可

        
        
        
        html
    
elements.forEach((element, index) => {
	const id = encodeURI(element.getAttribute('id')).toLowerCase();
	const tocLink = document.querySelector(`.inner ul li a[href="#${id}"]`);
	if (element === activeElement){
		tocLink.classList.add('active');

		// Ensure the active element is in view within the .inner container
		const tocContainer = document.querySelector('.toc .inner');
		const linkOffsetTop = tocLink.offsetTop;
		const containerHeight = tocContainer.clientHeight;
		const linkHeight = tocLink.clientHeight;

		// Calculate the scroll position to center the active link
		const scrollPosition = linkOffsetTop - (containerHeight / 2) + (linkHeight / 2);
		tocContainer.scrollTo({ top: scrollPosition, behavior: 'smooth' });
	} else {
		// ------------------添加部分---------------------
		if (getOffsetTop(element) < scrollPosition) {
			tocLink.classList.add('read'); // Mark as read
		}
		// ------------------添加部分---------------------
		tocLink.classList.remove('active');
	}
});

toc.css 中对 read 添加样式

        
        css
    
.read {
    color: rgb(105, 105, 105) !important;
}

Only Unfold Current Chapter 自动折叠其他章节

在 layouts/partials/head.html 中添加如下代码

        
        
        
        html
    
{{ if or .Params.autofoldtoc .Page.Site.Params.autofoldtoc }}
    {{ $styles := resources.Get "css/autofoldtoc.css.tmpl" | resources.ExecuteAsTemplate "autofoldtoc.css" . }}
    <style>
        {{ $styles.Content | safeCSS }}
    style>
{{ end }}

使得页面在设置了 autofoldtoc 时，引入我们预先定义好的样式表，实现对非激活章节的折叠，然后在 assets.css 中新建 autofoldtoc.css.tmpl 预先定义折叠样式为Hugo主题添加动态跟随目录Scrollspy效果如下

        
        css
    
.toc-container.wide li>ul {
    display: none;
}

.toc-container.wide li:has(a.active) ul{
    display: inherit !important;
}

后续可以在 hugo.yaml 中设置如下开启全局目录自动折叠功能

        
        yaml
    
params:
  autofoldtoc: true

或者在 markdown 的 meta-info 中添加如下一行即可针对单篇文章开启。

        
        yaml
    
autofoldtoc: true

Hide Toc before Decrypt 博文解密之前隐藏目录

修改 toc.html 的 getOffsetTop 如下：

        
        
        
        html
    
<script>
function getOffsetTop(element) {
    if (!element.getClientRects().length) {
        if (!document.querySelector('.hugo-encryptor-prompt') && elements.length != 0) {
            // Re-query the elements if the class is not found
            elements = document.querySelectorAll('h1[id],h2[id],h3[id],h4[id],h5[id],h6[id]');
            // console.log('Elements re-queried:', elements);
        }
        return 0;
    }
    let rect = element.getBoundingClientRect();
    let win = element.ownerDocument.defaultView;
    return rect.top + win.pageYOffset;   
}
script>

这一部分后面使用简码加密的会讲到，实际上是一个伪加密，只是不显示对应模块罢了。

Auto Index 添加章节计数

toc.css 中设置 H2 的样式如下：

        
        
        
        css
    
.toc .inner > ul > li{
    list-style: none;
    counter-increment: toc-section;
}
.toc .inner > ul > li::before{
    content: counter(toc-section) '.';
    margin-right: 0.4em;
}

在默认的 nav 之外添加一个 sidebar 结构体，然后通过 css 在不同的视窗中启用不同的导航栏即可，sidebar 可以添加在 layouts/partials/header.html 中：

        
        
        
        html
    
<header>
...
header>

{{- $iconMap := dict "home" "home-outline" "posts" "newspaper-outline" "tags" "pricetags-outline" "categories"
"grid-outline" "archives" "folder-outline" "search" "search" "about" "person" "linklog" "link"}}
{{- $bgColorMap := dict "home" "#f44336" "posts" "#b145e9" "tags" "#0f93c7" "categories" "#ffa117" "archives" "#0fc70f"
"search" "#15c095" "about" "#d16111" "linklog" "#0fc70f"}}
<div class="sidebar">
    <ul>
        <li class="logo" style="--bg: #333;">
            <a href="#">
                <div class="logo-icon"><img src="/logo/logo.png">div>
                <div class="logo-text">Aiken's Blog div>
            a>
        li>
        <div class="menulist">
            {{- range site.Menus.main }}
            {{- $menu_item_url := (cond (strings.HasSuffix .URL "/") .URL (printf "%s/" .URL) ) | absLangURL }}
            {{- $page_url:= $currentPage.Permalink | absLangURL }}
            {{- $is_search := eq (site.GetPage .KeyName).Layout `search` }}
            {{- $iconName := index $iconMap .Name }}
            {{- $bgColor := index $bgColorMap .Name }}
            <li class="{{- if eq $menu_item_url $page_url }}active{{- end }}" style="--bg: {{ $bgColor }};">
                <a href="{{ .URL | absLangURL }}" title="{{ .Title | default .Name }} {{- cond $is_search (" (Alt + /)" | safeHTMLAttr) ("" | safeHTMLAttr ) }}"
                {{- cond $is_search (" accesskey=/" | safeHTMLAttr) ("" | safeHTMLAttr ) }}>

                    <div class="logo-icon">
                        <ion-icon name="{{ $iconName }}">ion-icon>
                    div>

                    <div class="logo-text">{{ .Name }}div>
                a>
            li>
            {{- end }}
        div>
        <div class="logo-switches">
            <button id="theme-toggle" accesskey="t" title="(Alt +T)">
                <li>
                    <div class="logo-icon" id="moon">
                        <ion-icon name="moon-outline">ion-icon>
                    div>
                    <div class="logo-icon" id="sun">
                        <ion-icon name="sunny-outline">ion-icon>
                    div>
                li>
            button>
        div>
    ul>
div>

然后通过 css 去控制 sidebar 的位置和基本样式即可，这里的样式是来自之前自己练手项目，这里就不再详细分享：

基本的一些设置，包括 hover，nav 和 sidebar 的切换部分的 css 如下：

        
        
        
        css
    
/* sidebar styles */
@media screen and (min-width: 768px) {
  .nav{
    display: none;
  }
}
/* @media screen and (min-width: 768px) and (max-width: 1600px){
  .main:has(>article:first-child){
    margin-left: 80px;
  }
} */

.sidebar {
  /* background-color: var(--para-color); */
  background-color: #abc3d1bb;
  opacity: 0.9;
  position: fixed;
  padding-top: 0vh;
  padding-left: 10px;
  height: 100%;
  width: 80px;
  overflow: hidden;
  border-radius: 0px/30px 30px/30px;
  box-shadow: 20px 40px 40px rgba(0, 0, 0, 0.3);
  transition: width 0.5s ease 0s;
  z-index: 999;
}

@media screen and (max-width: 768px){
  .sidebar {
    display: none;
  }
}

.sidebar:hover {
  width: 270px;
  height: 100vh;
}

主题中完整的侧边 css 可从 sidebar.css at · AikenH/papermod-sidebar 获取。

Extensions 功能拓展

Disqus Support 使用 Disqus 作为评论区

为博客添加评论区实际上有比较多的选择，这里由于之前使用的都是 disqus，这里暂时就不做切换，后续如果有需求的话可能会做别的尝试，例如 giscus

参考 PaperMod 主题的说明 papermod-wiki-comments ，创建 layouts/partials/comments.html ，然后将 disqus 获取的代码贴进去，同时在设置 hugo.yaml 中打开评论区即可。

        
        yaml
    
params:
  comments: true

而由于 disqus 在国内的访问不是特别的友好，可能会成为页面加载的瓶颈，甚至阻碍其他核心的板块的加载进程，因此使用延迟加载方案使得当页面滚动到评论区域时才开始加载 disqus 板块，这里建议去原作者站点查看，故不再赘述使 Disqus 不再拖累性能和页面加载 | Sukka’s Blog 感谢作者，这也是本博客使用的方案延迟加载 Disqus 评论 | CSS-Tricks 中文感谢作者分享

此外由于觉得 disqus 的 reactions 模块有点烦人，因此在设置中讲 reactions 板块关闭 Document how to disable reactions · Issue #146 · disqus/disqus-react ;

busuanzi 统计网站访问人数

使用不蒜子统计站点访问次数和人数，参考官方教程将对应的代码嵌入 footer 中即可，如果需要人次的话就把 pv 改成 uv 。

最终代码如下：

        
        
        
        html
    
...
<script async src="//busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js">script>
        <span id="busuanzi_container">
            Visitors: <span id="busuanzi_value_site_uv">span>
            Views: <span id="busuanzi_value_site_pv">span>
    span> 
footer>

如果希望初始化站点的访问量和人数，避免域名转换后的重新计数，可以使用在西面添加 js 脚本对技术进行调整，可以参考 Hugo + PaperMod搭建技术博客 | Kunyang’s Blog 这里不再重复说明。

页面中引入 Sakana 摆件dsrkafuu/sakana-widget: Sakana widget for Web. | 网页小组件版本的石蒜模拟器。，并将其自定义了欣欣向荣两兄弟的图片效果如下：

欣欣小荣

该组件的使用，包括样式的调整文档里已经非常详细了，这里不在多说；

以供参考：本文在 hugo 中引入相关代码的位置位于layouts/partials/header,html的末尾

本文引入新角色的代码如下：

        
        
        
        js
    
function initSakanaWidget() {
	const ronSang = SakanaWidget.getCharacter('chisato');
	ronSang.initialState = { 
		...ronSang.initialState,
		controls: false,
		t: 0.8, i: 0.002, s: 1, d: 0.999, t: 0.5, w: 0.05,
	};

	ronSang.image = 'xxx.png';
	SakanaWidget.registerCharacter('ronSang', ronSang);
	new SakanaWidget({ character: 'ronSang' }).mount('#sakana-widget');
	...
}

World Cloud 词云

尝试了一下做标签云，试图优化一下 tag 页面，但是设置了背景以后配合的不是很好，因此本博客中没有使用这个功能，这里分享一下实现词云 Hugo的标签使用词云WordCloud2展示 | Blog - XLapTop wordcloud2.js/API.md at gh-pages · timdream/wordcloud2.js Adding a Tag Cloud to my Hugo blog · Jack Henschel’s Blog 的代码:

这里需要去 wordcloud2.js/src/wordcloud2.js at gh-pages · timdream/wordcloud2.js 将该 js 文件存在 static 目录下，然后将下述代码替换到 layouts/_default/terms.html 中

        
        
        
        html
    


<div id="sourrounding_div" style="width:100%;height:100%;min-height: 500px;">
    <div id="tag-canvas">div>
div>

<script src="/js/wordcloud2.js">script>

{{- range $key, $value := .Data.Terms.Alphabetical }}
    {{ if eq "" ($.Scratch.Get "tagsMap") }}
        {{ $.Scratch.Set "tagsMap" (slice (dict .Name .Count))  }}
    {{ else }}
        {{ $.Scratch.Add "tagsMap" (slice (dict .Name .Count)) }}
    {{ end }}
{{- end }}
{{ $result := ($.Scratch.Get "tagsMap")}}
`<span id="tag-temp" style="display:none">`{{$result | jsonify }}

<script>
    //因为前期每个标签值比较小，帮X一个系数
    //为了动态宽度[[]()]()
    var div = document.querySelector("#sourrounding_div");
    var canvas = document.querySelector("#tag-canvas");
    canvas.style.width = div.offsetWidth+'px';
    canvas.style.height = div.offsetHeight+'px';
    var wordFreqData =  document.querySelector("#tag-temp").innerHTML;

    let tagMap = new Map();
    let tagArray = new Array();
    {{- range $key, $value := .Data.Terms }}
    tagMap.set("{{ $key }}", {{- len $value }});
    tagArray.push([{{- $key }}, {{- len $value }}]);
    {{- end }}
    
    //获取当前是暗色还是浅色
    var isDark = document.body.className.includes("dark");
    WordCloud(canvas, {
          "list": tagArray,//或者[['各位观众',45],['词云', 21],['来啦!!!',13]],只要格式满足这样都可以
          "shape": "diamond", //形状 circle (default), cardioid (心型), diamond, square, triangle-forward, triangle, pentagon, and star.
          "gridSize": 18, // 密集程度 数字越小越密集
          "weightFactor": 6, // 字体大小=原始大小*weightFactor
          "fontWeight": 'normal', //字体粗细
          "fontFamily": 'Times, serif', // 字体
          "hover": window.drawBox,
          "color": isDark?'random-light':'random-dark', // 字体颜色 'random-dark' 或者 'random-light'
          "backgroundColor": 'transparent', // 背景颜色
          "classes": "tag-cloud-item word-color", //用于点击事件
          "shrinkToFit": true,
          "rotationSteps": 2,
          "minSize": "32",
          "rotateRatio": 0,
      });
      canvas.addEventListener('wordcloudstop', function (e) {
            //点击
            document.querySelectorAll('.tag-cloud-item').forEach(function (element) {
                const text = element.innerHTML;
                element.innerHTML = `${text}" style="color: inherit;">${text}`;
            });
        });
  
script>

{{- end }}{{/* end main */ -}}

效果演示如下，各种的形状，参数等可以根据官网进行调整尝试，找到适合自己的。

gallery 使用简码支持 neogallery2

参考：Hugo博客添加相册功能-腾讯云-素履coder 的实现，这里不赘述，感谢博主，可以参照下一个章节优化一下国内的速度，替换一下 CDN。

CDN 加速访问

通过 CDN Content Delivery Network 内容分发网络，使用靠近访问者的服务器为其分发内容来加速博客在不同地区的访问速度；

国内目前可用的 CDN 节点的话可以参考 aksBlog ，感谢其整理与分享，目前本站主要使用的是cdn.jsdmirror.com 感谢 blog.jsdmirror.com ;

此外其实也可以将一些资源直接上传至仓库，直接利用发布平台托管静态文件，利用托管平台自身的服务也行吧；

Something More

一些注意事项

调试的时候记得使用 --cleanDestinationDir 选项，不然有时部分页面生成失败了，延续了之前的页面，会使得定位错误变得更加复杂麻烦。

一些其他博主的设计

PaperMod 搜索页展示系列列表 | loyayz
我的Hugo博客搭建记录 - 少数派最后两个章节，集成 loading 和 memos =》 Obsidian到Anytype：Anytype介绍+个人实践分享有很多有意思的页面爆改
Hello World - Hugo博客搭建笔记 | Kenshin2438 一些修改的点子，虽然有一些没有实现
零基础搭建我的个人博客 | HermyGong’s Studio 简单入门
PaperMod主题Markdown示例 | 向着悠远的苍穹

Fi 写在最后

本博客的源码位于：AikenH/hugoblog: my blog’s hugo variant. with submodule AikenH/papermod-sidebar: my sidebar & transparnet background variant of papermod

一些处理脚本后续可能会分享到：AikenH/ManipulateMarkdownNotes: manipulate markdown file for publish or some other reason 目前在 dev 分支完善中。

文中有任何错误、版权使用不当之处、或者问题欢迎指正和交流，可以留言也可以发邮件；

初始化&设置PaperMod主题的基础功能

Thu, 12 Dec 2024 13:26:12 +0000

本文其实是配置和自定义 hugo 主题的第一章，从 papermod 的部署开始，记录整个基于 papermod 进行功能拓展和定制化的过程；

Setup PaperMod 安装和设置 PaperMod

Init Hugo Project 初始化 Hugo 项目

通过 hugo 指令新建一个 hugo 项目并制定使用 yaml 格式的配置进行设置；

        
        bash
    
hugo new site {your-proj-name} --format yaml

进入目录并通过 git clone 安装一个主题到 theme/ 目录下，如果想要使用 git 进行一些版本管理进行自己的修改，可能需要使用 submodule 的方式添加；

如果想直接对主题的内容也进行修改的话，建议先 fork 一下原仓库，将 fork 的仓库作为 submodule 和 hugo proj 一起进行版本管理和开发；

        
        shell
    
cd {your-proj-name}
git init # [optional] for develop
git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod --depth=1 
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod # [optional] for develop

如果是自己的仓库，记得使用 git 的方式拉取，如果用 http 的方式拉取后，可能无法提交后续的修改，可以用下列命令去修改 submodule 对应的 url How to change the remote repository for a git submodule? - Stack Overflow

        
        bash
    
git submodule set-url themes/PaperMod git@github.com:{your-proj}.git

后续部署的分支需要转换为 http 的形式，这里可以参见后面部署的文章。

Manage Your Configurations 配置文件管理

推荐使用 config 文件夹切分基础配置和主题配置，这样方便在多个主题之间进行切换；

        
        bash
    
cd your-prj-name
mkdir -p config/_default
mkdir -p config/papermod
touch config/paermod/hugo.yaml

配置文件相关的目录结构如下：

        
        
        
        txt
    
.
├── hugo.yaml
├── config
│   ├── _default
│   │   └── hugo.yaml
│   └── papermod
│       └── hugo.yaml

此处使用根目录的 hugo.yaml 作为默认的配置文件，papermod/hugo.yaml 设置主题特有的配置项，启动特定主题时使用 --environment {config-dif} 指定使用特定的配置文件：

        
        bash
    
hugo --environment papermod server

该部分具体的配置切分目前还没有完全确定，暂时还没有深入尝试使用别的主题，但是结构上应该是没问题的；

Hugo’s Organization 博客的文件夹组织逻辑

在进行后续的修改和迭代之前，了解一下 hugo 目录结构对应的作用目录结构 | Hugo官方文档是相当重要的，此外由于本文对 PaperMod 主题进行修改，也要对 PaperMod 的覆盖逻辑有一定的了解，包括模版覆盖 hugo-PaperMod Wiki-override-theme-template 和样式覆盖 hugo-PaperMod Wiki-bundling-custom-css-with-themes-assets ，由于官方文档中的介绍都比较详细，这里就不在赘述。

这里有一个特殊功能界面 _index.md 可以通过内容组织 | Hugo官方文档简单了解并尝试一下，后面对组织文档和界面可能会有用武之地。

PaperMod Setting 主题的基础页面配置

一、设置自己的文章模版

Archetypes 文件夹中可以注册不同的文章模版 archetypes/{template.md}，可以使用下列命令来基于指定的模版新建文章，此处由于大多时候都是直接使用 obsidian 编写后迁移过来的，该部分就不做太多说明；

        
        shell
    
hugo new --kind template {post-name}.md

但是官方模版中页面包含了大量的元数据信息，如果不是需要经常修改的属性，可以直接丢到 Theme/Hugo.yaml 中，避免每个 markdown 的元信息都十分冗长，等需要修改的时候再用指定的 markdown 上新增去覆盖即可；

二、启用 Archive 、 Search 、About页面等

此外 PaperMod 的很多页面是没有默认开启的包括 Search，Archive ，这些参考官方 wiki 或者中文的话 PaperMod主题配置 | 🚀 田少晗的个人博客简单配置一下这些页面，并启动 server 看一下这些页面是否正常生成；

about 界面可以仿照 archive 界面直接创建一个 about.md 在 content 目录中，最终其呈现的 URL 如下：http://localhost:1313/about/，content 中存放文件的最终路径均类似，会包含对应的文件夹路径。创建完成后将其新增到导航栏中 FAQs · adityatelange/hugo-PaperMod Wiki :

三、参考官方wiki 完成自己需要的基本模式和参数设置。

完成上面三步设置之后，添加一下博文测试一下各方面效果是否符合预期，没问题的话就可以开始折腾了👹

Extra Basic Function Support 额外基础功能支持

现在编写 Markdown 的时候事实上大多都额外支持或者使用了 Html 的部分语法来使得 Markdown 更加美观，或者是 Latex 来记录一些数学推导，但是博客本身这些功能要么没有默认开启或者是没有很好的支持，因此首先拓展这些基础功能；

Render Html 支持对 html 的渲染

基于安全性考虑，默认的 Goldmark 并不会渲染混合在 markdown 中的 html Configure markup | Hugo ，要打开的话修改/添加如下设置即可：

        
        yaml
    
markup:
  goldmark:
    renderer:
      unsafe: true

这里请确保自己的 html 内容是安全的

Render Latex 支持渲染 Latex

这一部分相关的资料和文章还是比较多的，主要会遇到的问题都是由于 markdown 渲染和 latex 渲染之间的冲突导致的，被 $ 或者 $$ 包裹的内容需要如何被匹配和被谁渲染，以及一些其他的特殊字符之间的问题；

Error

没有特别处理过的话，最终会导致一些复杂的 Latex 或者是一些内联公式导致最后的样式混乱；

经过多种尝试后，这里最终使用的如下方案使用 Mathematics in Markdown | Hugo 中的分隔符处理使用 How to enable latex on PaperMod | terakoya 该博主的 katex 方案 How to enable Math Typesetting in PaperMod? · Issue #236 · adityatelange/hugo-PaperMod 也提到了这种混合解法：

修改 hugo.yaml ：

        
        
        
        yaml
    
markup:
  goldmark:
    extensions:
      passthrough:
        delimiters:
          block:
          - - \[
            - \]
          - - $$
            - $$
          inline:
          - - \(
            - \)
        enable: true
params:
  math: true

在 layouts/partials 中添加 math.html

        
        
        
        html
    
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.15.2/dist/katex.min.css" integrity="sha384-MlJdn/WNKDGXveldHDdyRP1R4CTHr3FeuDNfhsLPYrq2t0UBkUdK2jyTnXPEK1NQ" crossorigin="anonymous">

<script defer src="https://cdn.jsdelivr.net/npm/katex@0.15.2/dist/katex.min.js" integrity="sha384-VQ8d8WVFw0yHhCk5E8I86oOhv48xLpnDZx5T9GogA/Y84DcCKWXDmSDfn13bzFZY" crossorigin="anonymous">script>

<script defer src="https://cdn.jsdelivr.net/npm/katex@0.15.2/dist/contrib/auto-render.min.js" integrity="sha384-+XBljXPPiv+OzfbB3cVmLHf4hdUFHlWNZN5spNQ7rmHTXpd7WvJum6fIACpNNfIR" crossorigin="anonymous"
    onload="renderMathInElement(document.body);">script>


<script>
document.addEventListener("DOMContentLoaded", function() {
    renderMathInElement(document.body, {
        delimiters: [
            {left: "$$", right: "$$", display: true},
            {left: "$", right: "$", display: false}
        ]
    });
});
script>

在 layouts/partials/extend_head.html 的末尾添加如下内容：

        
        html
    
{{ if or .Params.math .Site.Params.math }}
{{ partial "math.html" . }}
{{ end }}

此外，针对有时因为三个 {{{ 的出现导致渲染公式异常的情况Hugo博客添加LaTeX语法支持 | 🚀 田少晗的个人博客，可以通过脚本在 publish 时在代码块外侧添加

避免 markdown 干涉公式的渲染，使其正确渲染：

这里提供我的处理脚本，以供参考：

并不一定需要处理，可以视自己配置后的具体情况而定

        
        
        
        python
    
def _surround_latex_by_tag(self, content:str) -> str:
        # *. need to match those inline latex & block latex & ignore those $ in ``` block
        # 1. read code block and ignore it.
        # 非贪婪匹配
        code_block_pattern = re.compile(r'```.*?```', re.DOTALL)
        preserved_code_blocks = {}
        for i, match in enumerate(code_block_pattern.finditer(content)):
            placeholder = f"__CODE_BLOCK_{i}__"
            preserved_code_blocks[placeholder] = match.group(0)
            content = content.replace(match.group(0), placeholder)

        # 2. add space surround the inline latex sentence
        inline_latex_pattern = re.compile(r'(?)
        
        content = inline_latex_pattern.sub(lambda match: self._latex_add_space_inline(match, content), content)

        # 3. add newline between the `\ $\$ ` block or `\ $\$ \$` block 
        block_latex_pattern = re.compile(r'(?, re.DOTALL)

        content = block_latex_pattern.sub(lambda match: self._latex_add_div_tags(match, content), content)

        # 4. restore the code block
        for placeholder, code_block in preserved_code_blocks.items():
            content = content.replace(placeholder, code_block)
            
        return content

其他参考资料 Math Typesetting | PaperMod

Rss Setting for Follow 为 follow 认证设置 rss

Ref： Follow 中如何 Claim 自己的博客 | Rokcso’s blog

参考上述文章，在 rss.xml 中设置相关的 RSS Tag 即可，感谢博主的分享；

参考：Hugo+PaperMod 双语博客搭建 Home-Info+Profile Mode - YUNYI BLOG ，从 Choose a License 按自己的需求选择一个协议，并设置自己的知识共享协议；

我这里直接硬编码进 layouts/partials/footer.html 中如下：

        
        
        
        html
    
<footer class="footer">
    {{- if not site.Params.footer.hideCopyright }}
        {{- if site.Copyright }}
        <span>{{ site.Copyright | markdownify }}span>
        {{- else }}
        
        <span>© {{ now.Year }} <a href="{{ "" | absLangURL }}">{{ site.Title }}a>span>
        <span xmlns:cc="http://creativecommons.org/ns#" xmlns:dct="http://purl.org/dc/terms/">
            Licensed under
            <a
              href="https://creativecommons.org/licenses/by-nc/4.0/?ref=chooser-v1"
              target="_blank"
              rel="license noopener noreferrer"
              style="display:inline-block;"
              >CC BY-NC 4.0 a
            >span
        >
        {{- end }}
        {{- print " · "}}
    {{- end }}

Basic Style Change 基础样式修改

PaperMod 主题本身有一些基础样式个人不是很喜欢，例如内容部分的宽度比较窄，在全屏或者宽屏观看的时候比较变扭。因此这里也会针对主题的一些基础样式做针对的调整。

Get Wider Space for Content 拓宽正文区域

根据自己的布局修改 css 中如下属性即可 Change width of the content hugo-PaperMod · Discussion #442 ：

        
        css
    
:root {
  --post-width: max(60vw, 100vh);
  --main-width: max(60vw, 100vh);
}

Header Counter 为 Title 添加章节序号

直接利用 CSS 的 counter 和 before 属性为正文中的小标题添加对应的章节序号，实现如下：

        
        
        
        css
    
main {
    counter-reset: h1-cnt h2-cnt h3-cnt h4-cnt h5-cnt h6-cnt;
}

.post-content h1 {
    counter-increment: h1-cnt;
    counter-reset: h2-cnt h3-cnt h4-cnt h5-cnt h6-cnt; /* Reset lower levels */
}

.post-content h2 {
    counter-increment: h2-cnt;
    counter-reset: h3-cnt h4-cnt h5-cnt h6-cnt; /* Reset lower levels */
}

.post-content h3 {
    counter-increment: h3-cnt;
    counter-reset: h4-cnt h5-cnt h6-cnt; /* Reset lower levels */
}

.post-content h4 {
    counter-increment: h4-cnt;
    counter-reset: h5-cnt h6-cnt; /* Reset lower levels */
}

.post-content h5 {
    counter-increment: h5-cnt;
    counter-reset: h6-cnt; /* Reset lower levels */
}

.post-content h6 {
    counter-increment: h6-cnt;
}

.post-content h1::before {
    content: counter(h1-cnt) '. ';
}

.post-content h2::before {
    content: counter(h2-cnt) '. ';
}

.post-content h3::before {
    content: counter(h2-cnt) '.' counter(h3-cnt) '. ';
}

.post-content h4::before {
    content: counter(h2-cnt) '.' counter(h3-cnt) '.' counter(h4-cnt) '. ';
}

.post-content h5::before {
    content: counter(h2-cnt) '.' counter(h3-cnt) '.' counter(h4-cnt) '.' counter(h5-cnt) '. ';
}

.post-content h6::before {
    content: counter(h2-cnt) '.' counter(h3-cnt) '.' counter(h4-cnt) '.' counter(h5-cnt) '.' counter(h6-cnt) '. ';
}

需要注意的是，这里由于笔者习惯在正文中仅使用>=2 级的标题，因此对 H1 是没有做显示的，如果需要从 H1 开始需要对上述 css 进行简单调整；

将该 css 存放在 assets/css/extended 中即可生效。

Pagination Update 分页拓展

当博客多起来以后，如果在 post 界面不显示页码，以及不能快速的回到首页的话，十分破坏体验，因此简单的添加了回到首页和去到尾页的按钮，方便翻页操作，同时将页码打开，效果如下：

一、在 hugo.yml 中开启页码

        
        yaml
    
params:
  ShowPageNums: true

二、添加跳转至首页和尾页的 button 参数参考分页 | Hugo官方文档

在 layouts/_default/list.html 中的 prev 和 next 处添加 button 如下：

        
        
        
        html
    
<footer class="page-footer">
  <nav class="pagination">
    {{- if $paginator.HasPrev }}
    <a class="last-icon" href="{{ $paginator.First.URL | absURL }}">
      
      <span><<span>
    a>
    <a class="prev" href="{{ $paginator.Prev.URL | absURL }}">
      « {{ i18n "prev_page" }} 
      {{- if (.Param "ShowPageNums") }}
      {{- sub $paginator.PageNumber 1 }}/{{ $ paginator.TotalPages }}
      {{- end }}
    a>
    {{- end }}
    {{- if $paginator.HasNext }}
    <a class="next" href="{{ $paginator.Next.URL | absURL }}">
      {{- i18n "next_page" }} 
      {{- if (.Param "ShowPageNums") }}
      {{- add 1 $paginator.PageNumber }}/{{ $ paginator.TotalPages }}
      {{- end }} »
    a>
    <a class="last-icon" href="{{ $paginator.Last.URL | absURL }}">
      
       <span>>>span>
    a>
    {{- end }}
  nav>
footer>

三、简单设置其样式即可，可以在 assets/css/extended 中随意添加一个 css 文件对默认样式进行覆盖，当然也可以考虑写在主题的 css 中。

        
        
        
        css
    
.pagination a.last-icon {
  background: unset;
  border: unset;
  font-size: 1.3rem;
  color: #001e1d;
  /* padding-top: 2px; */
  font-weight: bold;
}

.pagination a.last-icon {
  color: var(--primary);
}

虽然没有按照该方法实现，但是如果想要更好的分页，可以参考自定义 Hugo 的分页导航栏 | DSRBLOG ；

PanGu JS 引入盘古之白

為什麼你們就是不能加個空格呢？vinta/pangu.js: Paranoid text spacing in JavaScript

如果你跟我一樣，每次看到網頁上的中文字和英文、數字、符號擠在一塊，就會坐立難安，忍不住想在它們之間加個空格。這個外掛（支援 Chrome 和 Firefox）正是你在網路世界走跳所需要的東西，它會自動替你在網頁中所有的中文字和半形的英文、數字、符號之間插入空白。

漢學家稱這個空白字元為「盤古之白，因為它劈開了全形字和半形字之間的混沌。另有研究顯示，打字的時候不喜歡在中文和英文之間加空格的人，感情路都走得很辛苦，有七成的比例會在 34 歲的時候跟自己不愛的人結婚，而其餘三成的人最後只能把遺產留給自己的貓。畢竟愛情跟書寫都需要適時地留白。

感谢 pangu.js 的作者，以及分享异步加载方案的博主盘古之白 - 中英文之间自动加空格 - Yihui Xie | 谢益辉 Hugo：中英文之间自动加空格 | Blog ，将该脚本异步引入 hugo 中。

在 layouts\partials\footer.html 中添加即可。

        
        
        
        html
    
<script>
    (function(u, c) {
      var d = document, t = 'script', o = d.createElement(t),
          s = d.getElementsByTagName(t)[0];
      o.src = u;
      if (c) { o.addEventListener('load', function(e) { c(e); }); }
      s.parentNode.insertBefore(o, s);
    })('//cdn.bootcss.com/pangu/3.3.0/pangu.min.js', function() {
      pangu.spacingPage();
    });
    script>

Font Setting 字体修改

本文使用的中文字体为霞鹜文楷，感谢开源分享，英文字体可以去 google font 中找一个顺眼的，参考上述开源字体的指引，通过 cdn 引入对应的 html 和 css 即可直接在 font-family 中调用。

html 插入到：layouts/partials/extend_head.html 中
（如有）css 插入到 assets/css/extended/blank.css 中

然后直接在 css 中使用 font-family 调用即可：

        
        css
    
body {
  font-family: "Open Sans", "LXGW WenKai", sans-serif;
}

当 post 数量较多时，文章是比较零散的，希望能在 widget 界面展示文章的 Tag 提供更多文章的信息，来建立文章和文章之间的关联。

找到主题中定义 widget 结构和样式的地方 /layouts/_default/list.html 中的 post-entry 部分 How to display tags in the post list? · adityatelange/hugo-PaperMod · Discussion #606 主要样式和实现参考：novikov-ai/novikov-ai.github.io ，使用 go-template 语法遍历&获取具体的 tag 参考 Params | Hugo官方文档获取 tag ，然后将其添加到对应的 meta 模块后面如下：

        
        
        
        html
    
<footer class="entry-footer">
      {{- partial "post_meta.html" . -}}
    footer>
    {{- if .Params.tags }}
    <div class="tags" style="padding: 2px;">
      <div style="display: flex; flex-wrap: wrap; justify-content: flex-end; margin-top: 5px;">
        {{ range .Params.tags }}
        <a href="/tags/{{ . | urlize }}" style="margin-right: 5px; 
                  color: white; 
                  background-color: rgba(53, 174, 128, 0.7); 
                  border-radius: 6px; 
                  padding: 1px 10px;
                  font-size: 13px;
                  z-index: 999; ">
          #{{ . }}
        a>
        {{ end }}
      div>
    div>
    {{- end }}

这里添加 z-index 将 tag 标签移至外层，避免元素置于其余元素下方导致跳转失效。
此外为了使得 tag 和 meta 信息处于同一行而非另起一行，添加如下样式：

        
        css
    
.tags {
  /* display: inline-block; */
  float: right;
}

Tag on Meta info 文章的元信息中显示 Tag

在上述的讨论区中 mgopsill 提供了解决方案，感谢其分享，具体操作是通过修改 layouts/partials/post_meta.html 中的 author 部分如下：

        
        
        
        html
    
{{- $author := (partial "author.html" .) }}
{{- $tags := (partial "tags.html" .) }}
{{- if $tags }}
    {{- $scratch.Add "meta" (slice $ author $tags) -}}
{{- else}}
    {{- $scratch.Add "meta" (slice $ author) -}}
{{- end}}

并添加对应的 layouts/partials/tags.html 如下：

        
        
        
        html
    
{{- $tags := .Params.tags -}}
{{- if $tags -}}
  {{- $lastIndex := sub (len $ tags) 1 -}}
  {{- range $index, $ tag := $tags -}}
    <a href="/tags/{{ $tag | urlize }}"> {{ $ tag }}a>
    {{- if ne $index $ lastIndex }} · {{ end -}}
  {{- end -}}
{{- end -}}

Post Widget’s Image to left 将文章封面图移至侧边

在 post 页面，如果封面图片处于信息块的上方，会导致其对页面空间过度占用，同时不同 size 也会导致呈现效果好坏参差不齐，因此为了使得页面更加美观且高效，参考 Hugo博客文章封面图片缩小并移到侧边 | PaperMod主题-素履coder 的文章，将文章的封面移至侧边；

按照上述博主说的用 div clss=post-info 将整个 post-entry 卡片的内容包括 content、meta、footer 等包裹起来后，将下列两行移至 post-info 的上一行即可，最终结构如下：

        
        
        
        html
    
<article class="{{ $class }}">
  {{- $isHidden := (.Param "cover.hiddenInList") | default (.Param "cover.hidden") | default false }}
  {{- partial "cover.html" (dict "cxt" . "IsSingle" false "isHidden" $isHidden) }}
  <div class="post-info">
    ...
  div>

该方法会导致同时影响了文章顶部的图片展示，笔者不同于原文的解决方案，这里通过更具体的 css 选择器做区分即可，还有一些其他的调整如下 assets/css/common/post-entry.css：

        
        
        
        css
    
/* F2 make the cover in the side on blogs page */
.post-entry {
  display: flex;
  flex-direction: row;
  align-items: center;
}

.post-info {
  display: inline-block;
  overflow: hidden;
  width: 90%;
}

.post-entry .entry-cover {
  overflow: hidden;
  padding-right: 18px;
  height: 80%;
  width: 40%;
  margin-bottom: unset;
}

Something more 一些别的

一个多图片居中失败的例子

以往使用如下代码使得多张图片同一行居中显示如下图所示，此次在该主题上失效：

源码：

        
        
        
        html
    
<p align="center">
  <a href=" https://aikenh.cn"><img alt="github" title="AikenD" src=" https://custom-icon-badges.demolab.com/badge/-aiken%20blog-palegreen?style=for-the-badge&logo=package&logoColor=black">a>
  <a href=" https://twitter.com/aiken_h97"><img alt="twitter" title="Twitter" src=" https://custom-icon-badges.demolab.com/badge/-twitter%20aikenh97-plum?style=for-the-badge&logo=package&logoColor=black">a>
  ...
p>

可以考虑使用 div 或者内联样式去覆盖主题或 hugo 的样式修复该问题如下：

使用 div：

        
        html
    
<div style="display: flex; justify-content: center; align-items: center;"> 
<a href="https://aikenh.cn"><img alt="github" title="AikenD" src="https://custom-icon-badges.demolab.com/badge/-aiken%20blog-palegreen?style=for-the-badge&logo=package&logoColor=black">a> <a href="https://twitter.com/aiken_h97"><img alt="twitter" title="Twitter" src="https://custom-icon-badges.demolab.com/badge/-twitter%20aikenh97-plum?style=for-the-badge&logo=package&logoColor=black">a> 
...
div>

使用 inline-style in p:

        
        
        
        html
    
<p align="center">
  <a href="https://aikenh.cn" style="display: inline-block; margin: 0 5px;"><img alt="github" title="AikenD" src="https://custom-icon-badges.demolab.com/badge/-aiken%20blog-palegreen?style=for-the-badge&logo=package&logoColor=black">a>
  <a href="https://twitter.com/aiken_h97" style="display: inline-block; margin: 0 5px;"><img alt="twitter" title="Twitter" src="https://custom-icon-badges.demolab.com/badge/-twitter%20aikenh97-plum?style=for-the-badge&logo=package&logoColor=black">a>
 ...
p>

一些资源或参考

网页图标：favicon.io
一种毛玻璃的实现方式：Achieving backdrop blur without ‘backdrop-filter’ - DEV Community
给网站添加 loading 页面： How to Quickly Add a Loading Screen onto your website! - DEV Community
对 hugo 的理解：风月

FI

文中有任何错误、版权使用不当之处、或者问题欢迎指正和交流，可以留言也可以发邮件，本博客的源码位于：

AikenH/hugoblog: my blog’s hugo variant. with submodule AikenH/papermod-sidebar: my sidebar & transparnet background variant of papermod

一些处理脚本后续可能会分享到：

AikenH/ManipulateMarkdownNotes: manipulate markdown file for publish or some other reason

目前在 dev 分支完善中。