Blog 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 分支完善中。

折腾 Hexo 的 Icarus 主题

Sat, 11 Mar 2023 23:46:37 +0000

本文的博客页面基于 Hexo +Icarus 主题搭建，在使用过程中对该主题做了一些简单的配置，以适应自己的需求。这里介绍一下自己粗浅的方案。

十分推荐 Icarus 这个主题，功能支持十分全面而且作者的文档也较为详实，推荐大家去了解。

拓宽显示页面区域

include/style/base.styl 中定义了各种基本页面尺寸：

        
        
        
        js
    
$gap ?= 64px
$tablet ?= 769px
$desktop ?= 1088px
$widescreen ?= 1280px
$fullhd ?= 1472px

可以在 include/style/responsive.styl 中定义 2 栏 3 栏情况下所使用的宽度：

        
        
        
        js
    
+widescreen()
    .is-3-column .container
        max-width: $fullhd- $gap
        width: $fullhd - $gap

    .is-1-column .container, .is-2-column .container
        max-width: $widescreen - 2 * $gap
        width: $widescreen- 2 * $gap

移动端优化

该主题在移动端表现的时候，两侧的 widget 会自动挪到下方，这样每个文章看完的时候体验很差，所以我希望在移动端的时候能隐藏这些 widget。

source/js/main.js 中仿照下面的格式添加对应 widget 的 type 即可：

        
        js
    
$('div.container div.card[data-type=categories]').addClass('is-hidden-mobile');

但是该代码会有问题，就是相应 disable 的 widget 对应的单独界面在移动端会失效。

自定义 404 界面

在 hexo 的默认配置（非 icarus 的配置）_config.yml 中跳过对 404.html 的渲染，直接使用该静态 html 页面进行页面的配置。

        
        yml
    
skil_render:
	- 404.html

404 静态页面可以使用腾讯公益界面，或者网上找一个模版使用，效果如下：

夜间模式（切换 variant）

夜间模式的实现主要参考，网上大多用的都是这个方案，但是个人非常喜欢 cyberpunk 的变体，所以希望实现夜间模式的时候切换成 cyberpunk 的 variant ，本文基于其实现做了一些改动，基本实现了该功能，但是目前而言还存在一些问题。

本人不是很懂前端，因此这个 dom 加载完成后重新加载 css 过程中，导致的页面畸变问题目前不知道该如何解决，望前端大大给点指导

添加主题切换按钮

在 layout/common/navbar.jsx 中添加夜间模式切换按钮，绑定 night-nav 事件，

        
        jsx
    
//{showSearch ? 
//	
// : null}

<a class="navbar-item night" id="night-nav" title="Night Mode" href="javascript:;">
	<i class="fas fa-lightbulb" id="night-icon">i>
a>

预先载入两个 css 文件

在 layout/common/head.jsx 中预先载入可选的第二个 stylesheet（css 文件）

        
        jsx
    
{/*  */}

<link rel="stylesheet" href={url_for('/css/' + 'default' + '.css')} title='default'/>
<link rel="alternate stylesheet" href={url_for('/css/' + 'cyberpunk' + '.css') } title='cyberpunk'/>

编写 js 实现 css 跳转

本部分主要来自 imagegoo 的夜间模式实现，修改了一下其调用的文件和变体变量，在 source/js/night.js 中实现。

        
        
        
        js
    
(function () {
    /**
     * Icarus 夜间模式 by iMaeGoo
     * https://www.imaegoo.com/
        */
      var isNight = localStorage.getItem('default');
      var nightNav;
  
    function applyNight(value) {
        $(window).trigger('resize');
        if (value.toString() === 'true') {
            // document.body.classList.remove('light');
            // document.body.classList.add('night');
            setStyleSheet('cyberpunk');
            
        } else {
            // document.body.classList.remove('night');
            // document.body.classList.add('light');
            setStyleSheet('default');
        }
        
    }
  
    function findNightNav() {
        nightNav = document.getElementById('night-nav');
        if (!nightNav) {
            setTimeout(findNightNav, 100);
        } else {
            nightNav.addEventListener('click', switchNight);
        }
    }
  
    function switchNight() {
        location.reload();
        isNight = isNight ? isNight.toString() !== 'true' : true;
        applyNight(isNight);
        localStorage.setItem('default', isNight);
        
    }

    function setStyleSheet(title){
        var link_list = document.getElementsByTagName("link");
        if (link_list){
            for (var i=0; i<link_list.length; i++){
                if (link_list[i].getAttribute("rel").indexOf("style") != -1 && link_list[i].getAttribute("title")){
                    link_list[i].disabled = true;
                    if (link_list[i].getAttribute("title") == title) link_list[i].disabled = false;
                }
            }
        }
    }
  
    findNightNav();
    isNight && applyNight(isNight);
  }());

并在 layout/common 完成对该 js 的引入。

        
        js
    
	<script src={url_for('/js/main.js')} defer></script>
	<script src={url_for('/js/night.js')} defer={true}></script>
</Fragment>;

添加访客数和访问次数

该主题原本就支持 busuanzi 的访客统计，在设置中打开就行，但是只显示其中一种，如果想要全部打开，可以仿照其原本的补充编写：

        
        js
    
// 在如下的地方依照类似的方法添加访客计数pv
visitorCounterTitle: _p('plugin.visitor_count', '0'),
visitorCounterTitle: _p('plugin.visitor_count', '0')

同样对该值的调用和渲染也要到相应的地方注册。

        
        js
    
visitorCounterTitle,
visitCounterTitle

并添加渲染：

        
        js
    
{showVisitorCounter ? <span id="busuanzi_container_site_pv"
	dangerouslySetInnerHTML={{ __html: visitorCounterTitle }}></span> : null}

{showVisitorCounter ? " and ": null}
	{showVisitorCounter ? <span id="busuanzi_container2_site_uv"
		dangerouslySetInnerHTML={{ __html: visitCounterTitle }}></span> : null}

所有图片居中

参考资料：请问如何实现文章中图片居中显示

单张图片居中可以使用：

        
        js
    
<div style="text-align:center">
    <img src= https://picture-bed-001-1310572365.cos.ap-guangzhou.myqcloud.com/mac/20230403173436.png title="devops">
</div>

全部图片居中可以在 hexo-theme-icarus/source/css/style.styl 中的 article 部分添加如下的最后四行：

        
        
        
        javascript
    
.article
    .article-meta
        margin-bottom: 0.5rem !important
    .content
        font-size: 1.1rem
        blockquote.pullquote
            float: right
            max-width: 50%
            font-size: 1.15rem
            position: relative
        a
            img
                margin: auto
                display: block

新版的修改的地址已经迁移到：themes/icarus/include/style/article.styl 中,同样还是找到这一段描述中添加最后四行即可。

文章以更新时间排序

修改 node_modules\hexo-generator-index\lib\generator.js 文件为以下内容重新 hexo s 即可：

修改之前记得备份

        
        
        
        js
    
'use strict';  
var pagination = require('hexo-pagination');  
module.exports = function(locals){  
  var config = this.config;  
  var posts = locals.posts;  
    posts.data = posts.data.sort(function(a, b) {  
        if(a.top && b.top) { // 当两篇文章top都有定义时  
            if(a.top == b.top) return b.updated - a.updated; // 若top值一样，则按照文章更新日期降序排列  
            else return b.top - a.top; // 否则按照top值降序排列  
        }  
        else if(a.top && !b.top) { // 以下两种情况是若只有一篇文章top有定义，则将有top的排在前面（这里用异或操作居然不行233）  
            return -1;  
        }  
        else if(!a.top && b.top) { //上一条已解释  
            return 1;  
        }  
        else return b.updated - a.updated; // 若都没定义，则按照文章更新日期降序排列  
    });  
  var paginationDir = config.pagination_dir || 'page';  
  return pagination('', posts, {  
    perPage: config.index_generator.per_page,  
    layout: ['index', 'archive'],  
    format: paginationDir + '/%d/',  
    data: {  
      __index: true  
    }  
  });  
};

Troubleshooting

map 迭代错误

执行 hexo cl && hexo g 会出现以下的错误：

Uncaught TypeError: Cannot read properties of undefined (reading ‘map‘)

该错误主要是由于使用 map 进行循环之前未判断变量是否非空，导致对 undefined 变量做遍历导致，因此只需要在循环之前加上判断即可。

主要出错的是在一下的两个文件里：

Layout/category.Jsx
Layout/index.Jsx

使用如下的方式在使用 map 对变量进行遍历之前做一个非空判断：

在react中使用map遍历，出现错误：Uncaught TypeError: Cannot read properties of undefined (reading ‘map‘)_学习前端的渣渣的博客-CSDN博客

spawn failed 解决方法

执行 hexo d 进行部署的时候可能会遇到 spawn failed 的各种问题，主要有两种情况

网络问题
文件结构问题

网络问题可以使用 ss -T git@github 测试连接情况；而文件结构问题的话，其实就是我们的链接库 .deploy_git 文件夹无法正常推送到 github，这种情况下可以考虑以下几种解决方式：

【重置部署文件夹】删除 .depoly_git 文件夹，重新执行 hexo d
【不推荐】进入 .deploy_git 文件夹强制推送，git push -f
【多系统编写导致文件混合编码问题】 git config –global core.autocrlf false

参考资料：Hexo错误：spawn failed的解决方法 | 张洪Heo (zhheo.com)

Reference

and here are some theme I may want to try：

设置各Editor自动添加meta信息

Wed, 13 Apr 2022 23:29:10 +0000

Hexo和Gitee一致，都是由Markdown文件为基础，构建的博客，编写Markdown本身无需多言，由于Hexo并非笔者的首选笔记管理方式，故而再其他地方构建和编写文件是常态，该Blog主要是利用其他工具来方便Hexo博文的编写（Header）

默认的是 hexo new [layout] title 可简写为 hexo n [layout] title，其中布局应该是在博客目录中定义，该命令也局限于博客的对应目录。

post(默认)、draft、page

除了默认的方法，本篇将介绍Obsidian、VsCode-like、Vim自动添加Header的方式，用以方便随时随地的编写博文。

同时为了方便已有笔记迁移，本文也编写了Python脚本，CPY后为Target Dir的版本自动添加Header，但是其中对应的Catagories最好还是手动修改一下。

Obsidian

通过template插件，按照对应主题的Header样式添加，可以去官方文档中找对应的语法和说明。从而构建自己的Template

Workflow：插件市场添加Template -> 设置指定Template文件夹 -> 按照语法编写Template文件 -> 使用快捷键插入模板

由于这一块没有什么存在歧义的操作，就不赘述，唯一需要注意的是语法，简单参考一下官方的Example 即可，无需过于深入

本文使用的是Live my Life的Hexo-Theme，模板文件如下：

        
        
        
        ts
    
---
title: <% tp.file.title %>
catalog: true
data: <% tp.date.now("YYYY-MM-DD HH:mm:ss") %>
subtitle:
lang: cn
header-img: /img/header_img/lml_bg1.jpg
tag:
- 
categories:
-
mathjax: true
sticky: 22

---

实际上各个模块的操作思想都是一致的Snippet方案。

Vim/Nvim

通过Vimscript设置或者Lua的设置文件，令Vim，Neovim再新建.md的同时，为其添加默认Header。Lua实际上调用的是Vimscript的接口，这里仅给出.lua版本，相应的转换不在赘言。

配置NeoVim中的 ~/.config/nvim/lua/basic/config.lua

        
        
        
        lua
    
vim.cmd('autocmd BufNewFile *.md,*.sh,*.cpp,*.py,*.lua exec ":lua set_title()"')
function set_title()
    filetype = vim.fn.expand("%:e")
    -- set title for markdown
    if filetype == "md" then
		vim.fn.setline("1", "--- " .. vim.fn.expand("%"))
        vim.fn.append(vim.fn.line("."), "")
        vim.fn.append(vim.fn.line(".")+1, "Author: AikenHong  ")
        vim.fn.append(vim.fn.line(".")+2, "Mail: h.aiken.970@gmail.com  ")
        vim.fn.append(vim.fn.line(".")+3, "Date: " .. os.date("%Y-%m-%d %H:%M:%S  "))
        vim.fn.append(vim.fn.line(".")+4, "Desc: ")](<vim.fn.setline("1", "---")
        vim.fn.append(vim.fn.line("."), "title: " .. vim.fn.expand("%"))
        vim.fn.append(vim.fn.line(".")+1, "catalog: true")
        vim.fn.append(vim.fn.line(".")+2, "subtitle: ")
        vim.fn.append(vim.fn.line(".")+3, "date: " .. os.date("%Y-%m-%d %H:%M:%S  "))
        vim.fn.append(vim.fn.line(".")+4, "lang: cn")
        vim.fn.append(vim.fn.line(".")+5, "header-img: /img/header_img/lml_bg1.jpg")
        vim.fn.append(vim.fn.line(".")+6, "tag: ")
        vim.fn.append(vim.fn.line(".")+7, "-  ")
        vim.fn.append(vim.fn.line(".")+8, "categories: ")
        vim.fn.append(vim.fn.line(".")+9, "-  ")
        vim.fn.append(vim.fn.line(".")+10, "mathjax: true")
        vim.fn.append(vim.fn.line(".")+11, "sticky: ")
        vim.fn.append(vim.fn.line(".")+12, "")
        vim.fn.append(vim.fn.line(".")+13, "---")>)
    end
end        

这样当我们用nvim newblog.md的时候，会自动添加上Header。

Vscode

使用Snippet插件添加代码片段，等待补充。

Convert md2Blogs

使用Python脚本为原有.md 批量添加Header，缺点是不太灵活，但是用于初始化还是能省不少事。如果原本按照Tag，或者Categories进行文件夹归类的话，倒是能起到不错的初始化效果。

Shut Out and Show my Code：

        
        
        
        python
    

# define the path of saving and the target path.
# Specific for windows or Linux version yourself

def get_all_blogs(path):
    # get all blog path.
    dirs = os.listdir(BlogPath)
    blogs = []

    for blog_dir in dirs:
        if blog_dir not in ['.obsidian','_book', 'Day Planners', 'node_module','Draft']:
            tmpdir = os.path.join(BlogPath, blog_dir)
            blogs += glob.glob(tmpdir + '/*.md')
    # del using _ replace space of filename.
    for blog in blogs:
        if ' ' in blog:
            blog = blog.replace(' ', '_')
            print(blog)

    return blogs

获取文件后我们需要得到文件的一些基本属性，用于Header中对应值的填充

        
        
        
        python
    
# TODO: get the basic info of each blog
# title(name of files) \ catalog: true \ data: create time \ subtitle: desc \ lang cn\en
# header-img: we can create a loop to generate this part.
# tags, categories, mathjax.
def change_realtime(timestamp):
    time_struct = time.localtime(timestamp)
    return time.strftime('%Y-%m-%d %H:%M:%S', time_struct)

def get_attribute(blog, verbose=False):
    attr = {}
    # get timestamp.
    create_time = os.path.getctime(blog)
    modify_time = os.path.getmtime(blog)
    attr['data'] = change_realtime(create_time)
    attr['m_data'] = change_realtime(modify_time)

    # get tags and categories.
    tags = blog.split('\\')[-2]
    attr['tags'] = tags
    attr['categories'] = tags

    # get title.
    with open(blog, 'r', encoding='UTF-8') as f:
        lines = f.readlines()
        title = lines[0].strip().split('#')[1]
        attr['title'] = title

    # default attr
    attr['lang'] = 'cn'
    # verbose:
    if verbose: print(blog, '\n', attr)
    return attr

为了不意外损坏源文件，同时保持源文件的结构、组织和属性等等，我们Cpy并只对副本进行操作，cpy的同时转移文件路径到所需地点。

        
        
        
        python
    
def cpy_files(blog,target):
    """cpy files to the target path"""
    filename = os.path.basename(blog)
    os.system('cp ' + blog + ' ' + target + filename)
    return target + filename

在获取完基本属性和转移后，我们需要开始对文件进行添加header的处理,在这里我们添加了一个Loop为Blog设置不同的背景图片，根据自己有多少图片进行自定义设置吧。

        
        
        
        python
    

def add_header(blog,index=0,attr=None):
    """add default header for each files"""
    header_imgs = ["",1, 2, 3, 4,5]
    with open(blog, "r+", encoding='UTF-8') as f:
        old = f.read()
        f.seek(0)
        f.write("---\n")
        f.write("title: " + attr['title'] + "\n")
        f.write("catalog: true\n")
        f.write("date: " + attr['data'] + "\n")
        f.write("subtitle: \n")
        f.write("lang: " + attr['lang'] + "\n")
        f.write("header-img: " + '/img/header_img/lml_bg{}.jpg'.format(index%6) + "\n")
        f.write("tags: " + "\n")
        f.write("-  " + attr['tags'] + "\n")
        f.write("categories: " + "\n")
        f.write("-  " + attr['categories'] + "\n")
        f.write("---\n")
        f.write(old)
    return

然后就是执行文件夹的批量处理了。可以添加args便于对多个文件夹进行处理，或者控制只变换单个文件等，应该需求不大，且代码比较简单，这里就暂时不贴出了。

        
        
        
        python
    
def dir_process():
    blogs = get_all_blogs(BlogPath)
    for i,blog in enumerate(blogs):
        b_attr = get_attribute(blog)
        new_blog = cpy_files(blog, TargetPath)
        add_header(new_blog, index=i, attr=b_attr)

if __name__ == '__main__':
    dir_process()
    print('Done!')

Latex tesing

Wed, 13 Apr 2022 16:50:53 +0000

该文档主要目的是用于测试Latex语法对应前端的渲染能力，主要用于测试Hexo站点是否能正常渲染Latex。

Example1: 2 inline in one sentence.

When $a \ne 0$ , there are two solutions to $(ax^2 + bx + c = 0)$ and they are

$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a}. $$

Example2: Matrix Example

$$ \begin{bmatrix} 1&x&x^2\\ 1&y&y^2\\ 1&z&z^2 \end{bmatrix} \\ \begin{bmatrix} 1&x&x^2\\\\ 1&y&y^2\\\\ 1&z&z^2 \end{bmatrix} \\ vmatrix ||、Bmatrix{}、pmatrix() $$

Example3: the Conditional Formula

$$ f(x)= \begin{cases} 0& \text{x=0}\\\\ 1& \text{x!=0} \end{cases} $$

Example4: Sprcial Symboy

$$ \lim_{\alpha \rightarrow +\infty} \frac{1}{\alpha(\beta+1)} $$

Example5: Complex Function Which Occurs Error in Much Situation

$$ \begin{gathered} \mathcal{L}_{POD-final} = \frac{\lambda_c}{L-1}\sum_{l=1}^{L-1} \mathcal{L}_{POD-spatial}(f_l^{t-1}(x),f_l^t(x)) + \\ \lambda_f \mathcal{L}_{POD-flat}(f_l^{t-1}(x),f_l^t(x)) \end{gathered} $$

Example6：Mathbb、Text、etc…

$$ \mathcal{L}_{\text {POD-pixel }}\left(\mathbf{h}_{\ell}^{t-1}, \mathbf{h}_{\ell}^{t}\right)=\sum_{c=1}^{C} \sum_{w=1}^{W} \sum_{h=1}^{H}\left\|\mathbf{h}_{\ell, c, w, h}^{t-1}-\mathbf{h}_{\ell, c, w, h}^{t}\right\|^{2} $$

Example7: Multiple Lines of Loss in Incremental Learning

$$ \begin{gathered} \mathcal{L}_{\text {POD-channel }}\left(\mathbf{h}_{\ell}^{t-1}, \mathbf{h}_{\ell}^{t}\right)=\sum_{w=1}^{W} \sum_{h=1}^{H}\left\|\sum_{c=1}^{C} \mathbf{h}_{\ell, c, w, h}^{t-1}-\sum_{c=1}^{C} \mathbf{h}_{\ell, c, w, h}^{t}\right\|^{2} \\ \mathcal{L}_{\text {POD-gap }}\left(\mathbf{h}_{\ell}^{t-1}, \mathbf{h}_{\ell}^{t}\right)=\sum_{c=1}^{C}\left\|\sum_{w=1}^{W} \sum_{h=1}^{H} \mathbf{h}_{\ell, c, w, h}^{t-1}-\sum_{w=1}^{W} \sum_{h=1}^{H} \mathbf{h}_{\ell, c, w, h}^{t}\right\|^{2} \\ \mathcal{L}_{\text {POD-width }}\left(\mathbf{h}_{\ell}^{t-1}, \mathbf{h}_{\ell}^{t}\right)=\sum_{c=1}^{C} \sum_{h=1}^{H}\left\|\sum_{w=1}^{W} \mathbf{h}_{\ell, c, w, h}^{t-1}-\sum_{w=1}^{W} \mathbf{h}_{\ell, c, w, h}^{t}\right\|^{2} \end{gathered} $$

如果这些都能正确渲染的话，基本整个文档中的Latex基本渲染应该都没问题，用该文档能验证当前本地渲染的版本是否是正确的。

部署和发布 Hexo 博客

Tue, 12 Apr 2022 11:16:30 +0000

该文档用以，记录自己（外行）利用Hexo建立Blog的过程，将原本用Gitbook构建的笔记转移到Hexo中，同时购买域名并部署其上。网页部署于Github Page 。以Live my Live主题为例。

腾讯云和Github Page的操作和理解在现有的一些博客中过时了，或者说存在一些问题，后续会对此进行简单的讲解。同时大部分博客都是使用NexT主题进行配置，这里采用的是Live My Life主题，该博文介绍自己的粗浅理解，也为自己后续的工作进行一定的参考。

还存在一些没有解决的问题：

对主题切换和主题配置和全局配置的的深入理解（Live my Life主题覆盖了很多默认配置）
前端代码的理解，自定义Layout，超链接，图标等
深入理解插件的应用和自定义
推送网站到baidu和google（Option）（没有计划）

之后有时间的话可以去研究一下：

关键词：Hexo_Livemylive、Github Page、腾讯云（Domain、DNS、SSL）

Environment

需要准备的环境如下：本地Node（NPM），Page部署Git（SSH），可在Windows，Linux，WSL2中部署均可，但需要注意的是，如果在WSL2中进行部署，生成速度与部署速度会明显慢于宿主机。

首先安装NodeJS、NPM、Git并验证是否成功安装，根据Linux和Windows不同环境进行安装，可以去官网了解相关的安装步骤，或者参考Gitee和Github的两篇博文。

为了更好的编写笔记，最好配置一个图床，图床的配置可以使用Github、Gitee或者腾讯云的COS服务，相关的配置可以参考LInk

        
        sh
    
git version
node -v
npm -v

安装Hexo

        
        sh
    
npm install -g hexo-cli

# 查看Hexo的版本
hexo -v

Initialize

Blog

对博客目录初始化：hexo init blog，blog为空的话初始化当前文件夹，初始化后基本结构如下：

        
        
        
        sh
    
.
├── _config.yml # 网站的全局配置信息，在此配置大部分的参数。 
├── package.json # 定义Hexo，以及对应安装的依赖的版本等
├── node_module: # Hexo安装插件的位置
├── scaffolds # 页面模版文件夹
├── source  # 资源文件夹，除 _posts 文件，其他以下划线_开头的文件或者文件夹不会被编译打包到public文件夹
|   ├── _drafts # 草稿文件
|   └── _posts # 文章Markdowm文件 
└── themes  # 主题文件夹

有了初始化的目录后，就可以参考相关主题的官方介绍页面进行对应的配置，不同的主题可能有不同的配置方法。接下来我们会以《Live my life》主题为例。

后续基于别的主题对文件配置有了更深入的理解后，会对配置部分进行更新说明，或另开一贴。

Github

本文使用Github Page构建自己的静态站点，用于部署自己的网页。GitHub只能使用一个同名仓库托管一个静态站点：aikenh.github.io，但是可以在此站之上，使用其他仓库构建子域名如: aikenh.github.io/Docs

Git和Github仓库和链接的初始化参见GitWorkflow ；对应的io，可以通过建立【UserName】.github.io为名的Repo，并在Setting-> Code and automation -> Page中选择对应的Branch作为Source.

完成后如图所示，后续设置好域名解析服务后后可在Custom domain中设置你的自定义域名，github.io将自动转换成该域名，会在域名解析部分详细介绍

创建完该网站Github的初始部分差不多完成。

Config-livemylife

本章节的基本操作均针对_config.yml进行。

基于我的理解，为了便于多主题的配置和切换，在主Config.yml 中应该尽量不参与特定主题的设置，而在Theme/SpecificTheme/_config.yml中为每个主题定制基本的配置为好。但目前只用过这个主题，就以此为例。

更多的设置去主题的readme中查看和设置。

初始化主题：设置主题的基本需求，并基于此安装相关依赖

        
        
        
        sh
    
cd blog
rm -rf scaffolds source themes _config.landscape.yml _config.yml package.json yarn.lock #just keep node_modules
git clone https://github.com/V-Vincen/hexo-theme-livemylife.git
mv hexo-theme-livemylife/* ./
rm -rf hexo-theme-livemylife
npm install

设置主题：修改配置中的theme值

        
        yaml
    
theme: livemylife

themecolor:
	enable: true
	mode: light

完成了基础设置后，可以直接在本地运行博客，查看效果，方便后续调试后部署，具体命令如下

        
        bash
    
hexo cl && hexo g && hexo s -p your-port
# default port is 4000
hexo g && hexo s

Basic Configs

使用自己的信息修改配置文件的对应选项，以下介绍一些基本属性配置：

        
        
        
        yaml
    
# header
title: My_Blog
subtitle: some description of u or ur site
author: NickName
timezone: 

# url
url: http://aikenh.cn # note: 不要忘了修改source文件中的CNAME
root: 
permalink: :lang/:title/ # 子页面的链接形式

# site setting
SEOTitle: Names Blog # 标签栏显示的标题
email：
description: "Development Documentation"
keyword: "name,Name,blog,Blog"
header-img: img/header_img/bg_img.jpg # 标题图像的存储路径，Source为根路径

favicon: img/avatar/f_img.png # 标签栏显示的图像

# 暂时不使用签名
signature: false
signature-img: _ 

不使用Internationalization 设置，关掉选项：

        
        yaml
    
langselect:
	enable: false

该选项会关闭生成语言选择按钮。

Effects custom

该部分控制页面的特效设置。主要包括关闭线段背景，线段背景消耗CPU的同时还会遮挡文字，故而关闭；鼠标点击特效mouseclick关闭，在界面使用的时候异常选中的问题以及遮挡的问题。

        
        
        
        yaml
    
wave: true

# false can not disable this, should del content and color alse
mouseclick:
	enable: false
	content: 
	color: 

ribbonDynamic: true
bglinecanvas: false

启用侧边栏放置相关的个人信息，SNS的设置实际上也与该部分相关，会显示在头像的下方。

        
        
        
        yaml
    
sidebar: true   # whether or not using Sidebar.
sidebar-about-description: "making trash"
sidebar-avatar: img/avatar/samura.jpg    # use absolute URL, seeing it's used in both `/` and `/about/`
widgets:
- visitor   # busuanzi: https://busuanzi.ibruce.info/
- featured-tags
- short-about
- recent-posts
- friends-blog
- archive
- category

# widget behavior 设置相关的Archieve侧边部件
## Archive
archive_type: 'monthly'
show_count: true

## Featured Tags 
featured-tags: true   # whether or not using Feature-Tags
featured-condition-size: 0    # A tag will be featured if the size of it is more than this condition value

## Friends 友站设置
friends: [
    {
        title: "GitBook",
        href: "https://Name.github.io/Docs"
    },
    {
        title: "Hexo",
        href: "https://hexo.io/"
    }]

# SNS Settings just enable what u want.
RSS: false
github_username: yourAccount
twitter_username: yourAccount
# instagram_username: 
# facebook_username:  yourAccount
# linkedin_username:  yourAccount
zhihu_username: yourAccount
weibo_username: numid of weibo in url

Layout Custom

修改一些页面布局，除了一些基础设置，还有还有一些对应的标签问题。

        
        
        
        yaml
    
# top scroll progress
scroll: true
# make article sticky
top: true
# count word for each doc
wordcount: true
# show tag of each article
home_posts_tag: true
# anchorjs 设置锚点
anchorjs: true
socialshare: true
viewer: true

页面的Newer Posts和Old Posts在theme中，根据不同的语言选项去修改即可。

页面背景在博文中通过Header（Meta-data）设置，批量转化的时候可以通过代码循环生成，后续进行转化的时候最好依靠随机数指定。

Github Page

安装部署插件如下：

        
        shell
    
npm install hexo-deployer-git  --save

实际上就是将public 文件夹push到对应仓库的指定分支，有插件能够直接执行该操作，在config中执行如下设置：

        
        yaml
    
deploy:
  type: git
  repo: https://github.com// # or https://gitee.com//
  branch:

之后执行 hexo d即可

Mathjax（TB fix）

用于下一次验证的策略：手动添加MathJa支持而不基于Kramed ，基于此思想迁移到Mathjax3 ，也避免了Kramed和Prismjs的冲突。

支持公式的方式主要有以下的几种思路，该设置实际上主要是和Next主题相关，包括Katex等

该主题目前使用的是Mathjax + kramed + it的方式。

官方描述对应的Latex支持, 该部分目前的渲染效果处于玄学状态，有时候能用，有时候针对一些语法会出现渲染错误，但是并不能很好的定位到错误的原因。现象如下：

缩略图中出现正常的渲染，而在正文中只显示公式
部分语法可以正常渲染，稍微复杂一点的无法渲染，且原因不定。

目前猜测可能与Package有一定的关系，在对hexo-renderer-marked等Package进行操作后，可能就会恢复正常。

当前情况下在Windows清除，在WSL2中执行Hexo命令好像就可以，非常的玄学。

目前按照主题的方式（默认已配置好），后续如果效果仍然不稳定，可能会对渲染的方式进行改动。比如利用math的jax支持，或者基于pandoc 的方式把。后续再出现问题的话对比一下。

利用pandoc可以完美的显示所有的LaTex，但是原有设置下Archive主页的归档信息消失：
基于karmx等的数学公式无法完美显示，问题有些严重，所以最终还是换了

其中的一些语义冲突修改倒是在新版本中，好像影响不是很明显，可能更多的是与marked的冲突，但是我们使用的是别的渲染引擎

CDN的设置：可能需要自动添加文件末尾，CDN可以自己去找一找了，把后面的对其就行

在 ~/blog/_config.yml 文件（注意，是 Hexo 博客文件夹根目录中的 /_config.yml 而不是主题目录下的 /themes/next/_config.yml）中增加 MathJax 的支持，并手动设置下面的 src（这一步很重要，使用默认的 src 会导致数学表达式渲染显示失败。这里的关键是 src 中的 ?config=TeX-MML-AM_CHTML 这个字段）

Pandoc

MathJax + PanDoc + it的解决方案，最好部署在自己的服务器上，部署在Github上有一些折磨, Pandoc需要使用CI或者Action去部署，等熟悉了再采用该方法把。

pandoc 需要本机中首先安装 pandoc ，各平台参考官方链接进行安装即可。

        
        bash
    
npm uninstall hexo-renderer-kramed --save
npm install hexo-renderer-pandoc -- save

（非正常方式）对于Archive的问题只需要修改一下生成Archive的路径即可，即通过修改config的生成archive和archive的路径

具体的对pandoc的配置可以参考：[Link1](https://feigeek.com/posts/b1bbb984 . html)，对其一些bug的修复则用Link2 ，但是暂时作为可选项，新版的好像已经没有问题。

目前配置如下（有一些不对的冗余存在）：

        
        
        
        bash
    
mathjax: 
  enable: true
  mhchem: false

katex: 
  enable: false
  copy_tex: false

pandoc:
 extensions:
    - '+hard_line_breaks'
    - '+emoji'
    - '-implicit_figures'

Prismjs

在Hexo6.0之前还是需要借助插件的，但是根据官方说明，在6.0之后官方已经添加了Prismjs的支持，disable Hightlight，Enable prismjs后，基于preprocess模式

        
        
        
        yaml
    
highlight:
  enable: false
  line_number: true
  auto_detect: true
  tab_replace:
  wrap: true
  hljs: false
  
prismjs:
  enable: true
  preprocess: true
  line_number: true
  tab_replace: ''

在对应的Theme/specific theme/layout/_partial/head.ejs中添加需要的css样式。

        
        javascript
    
<head>
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism-themes/1.9.0/prism-lucario.min.css">
  ...
  
<\header>

对应的样式可以在github prismjs 中查看，其对应的cdn则按照此链接查询，虽然不懂得javascript，但是我寻思下载到本地也是一样的，按照其他对应的prismjs-hexo-Blog中的处理即可。

        
        javascript
    
<head>
  <link rel="stylesheet" href="/js/prism/prism.css">
  ...
  
<\header>

之后应该就可以正常使用

Password 4 Blog

利用插件对特定的文章进行加密，使得特定的文章的查看需要输入密码。

安装插件：

        
        shell
    
npm install --save hexo-blog-encrypt

快速使用: 只需要在文章的Meta信息中添加Password字段即可

        
        markdown
    
---

password: test

---

也可进行全局加密设置：参考Password

Domain Setup

腾讯云注册：首先获取一个免费的域名或是去腾讯云 /阿里云购买一个域名，（实名制->付钱->审核备案）

DNS Setting

DNS解析：在购买域名的提供商为域名添加解析，以腾讯云为例：

（不推荐）如果想要使用ipv4，ipv6进行dns解析的话可以搜索Github Page的IP，或者

        
        bash
    
ping username.github.io

（推荐）在域名注册控制台选择对应的域名解析

主机记录：@、www分别注册一次，分别用于https://yourdomain和 https:// www. yourdomain的解析。

记录类型：由于同个网站的CNAME和AAAA会发生冲突，这里建议使用CNAME类型，并在后续的

记录值: 中填写自己的username.github.io

后面有免费的SSL记得勾选，等待审核即可。

Deploy it

Hexo部署：

本地部署和服务启动不需要d（eploy）执行到前面即可在指定的端口查看本地的部署效果了。远程部署实际上就是git Push -f 到远程仓库的指定分支，完成前面github page的设置可以使用hexo -d 进行部署。

        
        bash
    
hexo cl 
hexo g
hexo s
hexo d

hexo cl && hexo g && hexo s && hexo d

Github绑定：

在站点的source目录下创建CNAME并添加域名

        
        bash
    
echo "yourDomain" >> CNAME

在Github-> Repo -> Settting -> Page —> Custom Domain 中填写域名并保存，等待解析完成后，即可。

参考资料：Link1 、Link2

Themes Switch

主题之间的切换应该和我预想的一致，下载主题到对应的Theme文件夹，在最外层的_Config中切换，但是由于我们的初始主题Live my LIfe极度依赖默认_config.yml，而非自身目录下的配置文件。故而有以下的几点工作

Compatibility Check： config setting，plugin version and dependencies conflics
Dir structure： check the consistency of the dir tree structure
Find themes u like: latex-support，post-style，archive，tag，Difficulty，Long-Time-Support…

以下这些是一些初步筛选出来的觉得还可以的主题，之后可以切换看看：

画廊 Miccall主页为画廊的基本样式，有对应的图库功能，作为图片和效果展示的话可能还不错，post页面和标签等页面较为一般。
三钻主题，亮色惊艳，暗色太花，设计难度和修改难度估计较大，Archive为时间轴模式，大爱，可以的话看看怎么将LivemyLife的Archive也变为这种样式。正文的效果以及对应的TOC
极简程序员博客，简洁美但是稍微有点太简洁，Archive界面好像崩了
闪耀狐，LTS，分类的雷达图，标签的热力图大爱，想办法搞到自己的主题里，功能较为全面和完善，如果想要自定义或者添加一些功能，完全可以参考这个主题。
Find More 官方主题游廊

当前对各方各面的概念还不是太理解，后面考虑对网页构建的底层，以及其他的相关知识进行进一步的了解，方便自己对网站进行更进一步的自定义。

Public

站点提交，通过将自己的网页提交给搜索引擎，使得自己的文章能够被搜索到，目前暂时先不考虑Public，所以这里先行占位，功能暂时不进行支持。

主要参考Link1 ，初步计划使用sitemap进行站点提交，由于baidusitemap存在较多冲突考虑先不启用。后续进行继续实验。

Reference

基础+百度网站提交 | 基础解读 |
Official SIte ：介绍默认_config文件的配置信息
简单修改 livemylife主题的一些简单修改
知乎教程可以添加网易云音乐的外链，同时有我们需要的自定义社交网络按钮的部分（基于Next）去看看用的是什么插件，怎么嵌入。
zhihu2 ，基本同上，但是多了一些其他的自定义的
大小写的改变不会git推送，导致发生404 错误

使用 PicGo 设置图床

Sun, 27 Mar 2022 09:19:23 +0000

@Aiken 2020 first write，2021 modify

Mainly using picgo-core(command line) to setting picbed，and we can update the setting method

Github

使用PicGo-Core（command line）设置github图床，自动转义url
插入自动复制图片，使用git上传github

基本部署

在偏好设置中的图像，进行如下设置👇：下载或更新PicGo-Cord(command line)

接着去Github中建立一个Repo：UserName/RepoName，用以存放图片（Public），简单的用readme初始建立即可。
在Github的setting - developer setting-personal access tokens中新建token，指定简单的repo权限，并记录个人的token（只显示一次） Attention： 忘记记录的话，在token中也是通过update token（好像是这个名，获取新的值的）
用Typora打开配置文件设置，或者使用命令行进行配置

        
        
        
        json
    
   {
       "picBed": {
           "github": {
             "repo": "UserName/RepoName",
             "token": "your github token here",
             "path": "img/",
             "customUrl": "https://raw.githubusercontent.com/UserName/RepoName/master",
             "branch": "master"
           },
           "current": "github",
           "uploader": "github"
         },
         "picgoPlugins": {}
   }

点击验证图片上传选项，进行测试，成功即可

存在问题

用Github做图床的话，上传不是十分的稳定（可能需要依赖科学上网技术。请八仙过海，各显神通）。可以用其他的服务器作图床，大体过程应该也差不多，后续个人有更换的话在进行补充。

在其他的pc上可以使用相同的token进行复用，但是在进行测试的时候要记得将repo中的两张测试图片删除，不然可能会导致验证失败的问题。

PicGo With Obsidian etc.

这种方法可能是最稳健的泛化能力也最强，再很多编辑器类似的地方都能用，但是前提就是我们进行笔记撰写的时候要把picgo的客户端打开。

安装picgo客户端，（在其中安装你对应图床的插件）

和上述描述的一样再gitee或者github中设置相应的图床token等，并在软件中填写对应的token
picgo设置中，打开server即可
再Obsidian中安装插件 image auto upload plugin 并在其中设置本地ip:port即可

COS in tencent-cloud

相关网站：Tencent-Cloud-Cos 参考资料：Create-Tencent-Cloud-Cos , Setting-Your-PicGoApp

创建存储桶

Create Store-Bucket(Private write Public read) ->
Create A sub-User(which only got access for the cos R/W) ->

QcloudCOSFullAccess, Pic Below to add the access
generate a private_token ->

token manage
cp SecretID,SecretKey,Main_Account_ID,name_of_bucket to PicGo

the area in the second figure

Picgo 设置

进入腾讯云的对象存储页面：
- 存储桶列表中可以看到存储桶名称，即Bucket
- 所属地域，也就是设定存储区域如：ap-guangzhou
右上角的用户信息中点击访问管理进入到用户界面
- 用户-> 子用户可以看到账号 ID：即Appid
- 点击子账户进入详情页->API 密钥
  - SecretId
  - SecretKey
设置完成即可。

Gitee（防盗链事件后抛弃）

因为gitee是国内的github，服务器比较稳定，所以我们也可以使用gitee作为我们更为稳定的图床；

两个链接合起来才是好用的，都有一些冗余：

gitee基本部署

安装Node，npm；
安装picgo-core的命令行命令：

        
        shell
    
  npm install picgo -g

安装gitee的插件：

        
        shell
    
  picgo install super-prefix
  picgo install gitee-uploader

配置Gitee Repo

初始化一个repo，保存URL中的User/repo，不要轻信标题，因为有昵称机制。
在个人资料中初始化个人的Token，勾选projects选项即可;

设置配置文件

基于picgo的命令，会自动的更新Json文件，我们不许需要

        
        
        
        shell
    
picgo set uploader
# up to the command hint, we input those messages
1.按上下键找到gitee，回车    
2.repo：用户名/仓库名 （打开自己的仓库，浏览器里的网址username/reponame）    
3.token：刚才生成的token    
4.path:路径，写仓库的名字就是reponame    
5.custompath:不用填，回车   
6.customURL:不用填，回车    
# finish setting process
picgo use uploader

基于 Gitbook 发布笔记

Sun, 26 Sep 2021 15:36:25 +0000

Gitbook命令行工具，基于Markdown编写文档，后续基于Github发布该Blog

笔记的构建流程：

Chapter1 Install

安装Gitbook之前我们需要安装node.js和npm的依赖，使用npm安装gitbook

首先安装Install Nodejs，Npm

Windows：Node.js (nodejs.org)

Linux:
bash
```
# add & update apt source before install nodejs.
curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -
sudo apt-get update

# install nodejs after that.
sudo apt-get install -y nodejs
```
然后安装gitbook
bash
```
npm install gitbook-cli -g 

gitbook fetch beta # 安装历史版本
gitbook ls-remote # 列举可以下载的版本
```
检查Gitbook版本
bash
```
gitbook -V
```

安装Gitbook插件

安装插件主要有两种方式：一种是直接通过book和gitbook的安装来实现，另一种是基于Npm预先安装

        
        bash
    
npm install gitbook-plugin-PACKAGE

基于book的安装方式

插件和相关的配置在book.json中指定，关键词plugins & pluginsConfig为对应的插件的配置信息

添加插件通过修改book.json如下：

        
        
        
        json
    
{
	"plugins": [
        "-summary","-katex","mathjax-pro","anchor-navigation-ex-toc",
        "search-plus","-lunr","-search","splitter","copy-code-button","github",
        "theme-comscore","-latex-codecogs","tbfed-pagefooter","-expandable-chapters-small",
        "-edit-link-plus","expandable-chapters","pageview-count","-editlink",
        "lightbox","-highlight","prism","disqus"
    ],
}

添加完新的插件配置之后，运行gitbook install ./来安装新的插件

gitbook-plugin-mathjax-pro - npm (npmjs.com) ；PrismJS/prism-themes: A wider selection of Prism themes (github.com)

        
        bash
    
# gitbook-plugin-mathjax-pro 安装方式
npm install mathjax@2.7.7
npm install gitbook-plugin-mathjax-pro
# and editor the book.json as below

        
        
        
        json
    
{
    "author": "AikenHong",
    "title": "Aiken's Blogs",
    "language": "zh-hans",
    "plugins": [
        "-summary","-katex","mathjax-pro","anchor-navigation-ex-toc",
        "search-plus","-lunr","-search","splitter","copy-code-button","github",
        "theme-comscore","-latex-codecogs","tbfed-pagefooter","-expandable-chapters-small",
        "-edit-link-plus","expandable-chapters","pageview-count","-editlink",
        "lightbox","-highlight","prism","disqus"
    ],
    "pluginsConfig": {
        "insert-logo":{
            "url": "https://picture-bed-001-1310572365.cos.ap-guangzhou.myqcloud.com/imgs/img/20210927180958.png",
            "style": "background: none; max-height: 120px; min-height: 120px"
        },
        "github":{
            "url": "https://aikenh.github.io/about/"
        },
        "tbfed-pagefooter": {
            "copyright":"© AikenHong",
            "modify_label": "该文件修订时间：",
            "modify_format": "YYYY-MM-DD HH:mm:ss"
        },
        "mathjax-pro":{
            "version": "2.7.7"
        },
        "prism":{
            "css": [
                "prismjs/themes/prism-tomorrow.css"
            ],
            "lang":{
                "flow": "typescript"
            }
        },
        "disqus":{
            "shortName": "aikensdoc"
        }
        
    }
}

安装Disqus的时候，要到Disqus官网进行账号注册，并安装个人评论的网站，记录唯一的个人标识符，然后再配置中引入即可；

使用prism代替

Chapter2 Configure

gitbook init会初始化文件目录，文件夹会包含如下的结构：目录中的文件对应有如下的作用

        
        
        
        bash
    
.
├── _book         # 自动生成的html
├── book.json     # 配置文件
├── README.md     # 电子书的前言或者简介
├── SUMMARY.md    # 电子书的目录
├── chapter-1/
|   ├── README.md # 章节的描述
|   └── something.md
└── chapter-2/ 
    ├── README.md # 章节的描述
    └── something.md

编辑对应的SUMMARY同时可以按照文件夹结构进行组织，基本的组织结构可以按照下面的来进行部署

        
        markdown
    
# 概要

* [卷 I](part1/README.md)
    * [写作很棒](part1/writing.md)
    * [GitBook很酷](part1/gitbook.md)
  
* [卷 II](part2/README.md)
    * [期待反馈](part2/feedback_please.md)
    * [更好的写作工具](part2/better_tools.md)

Chapter3 Deploy

在本地部署和运行一个样本书，设置gitbook的配置文件

初始化

        
        bash
    
gitbook init
gitbook init ./directory # 在指定的目录中生成

构建

使用下面的命令会在当前目录下或者指定目录里生成_book目录，里面的内容是静态站点的资源文件：

        
        bash
    
gitbook build

Debugging

您可以使用选项 --log=debug 和 --debug 来获取更好的错误消息（使用堆栈跟踪）。例如：

        
        bash
    
gitbook build ./ --log=debug --debug

启动服务

使用下列服务在LocalHost 可以预览我们的的本地书籍

        
        bash
    
gitbook serve

Chapter4 Publish

希望可以不借助gitbook服务来可视化界面，全靠git & cmd & github来进行一系列操作，这样就能通过我的onedrive来进行比较好的统一管理

托管到Github Pages

optional: 创建username.github.io的个人repo,可以通过jekyll 来init该githubpage

创建note’s repo, 用来存储自己的所有Liture
调用gitbook serve之后将_book的文件推送到repo的gh-pages分支
就可以在下列的url中看到自己的文档：aikenh.github.io/REPONAME/
修改io文件夹中的_layout中的Default.html如下
html
```
  <a href="https://aikenh.github.io/Docs/">Bloga>
```

        
        
        
        bash
    
# enter the right dir
# we need to excute gitbook serve int terminal first
cd _book

# using condtional rules to control the update actions
if [ -d ".git" ];then
  echo "exist git files"
else
  git init
fi

# update those blogs using git
git add . 
git commit -m "update those blogs"
echo "update the local git log"

# push the update to the remote repo
git remote add origin git@github.com:AikenH/Docs.git
git push -f origin master:gh-pages
echo "finish pushing files"