如何使用 hugo-theme-virgo 主题

🎨 hugo-theme-virgo

为什么要把使用指南单独列出，而不是放在 README 中？

一方面，内容更新频繁（虽然没有必要），把更改放在 README 中需要每次都提交主题更新，然而有时候只是单纯的更新 README 而已。

另一方面，国内网络推送到 Github 仓库的时候经常抽风 (如下图)，速度也慢。

![[assets/Pasted image 20230815144943.png]]

更新日志

- 2023-09-27 15:12 cool 模式下更灵活地配置背景壁纸和遮罩透明度
- 2023-09-21 17:04 恢复 dark 暗色模式（真的不常用），并调整部分图标
- 2023-09-07 16:24 调整 1920*1080 分辨率下样式，正确渲染不以 / 开头的图片
- 2023-08-15 12:21 合并、删除 ob 分支，为功能完整版打标签 v1.0.0
- 2023-08-14 15:46 新增 giscus 评论插件，并默认使用（代替 utterances）
- 2023-08-02 18:31 新增 ob 分支，精简功能，适配 Obsidian
- 2023-03-23 14:58 增加 utterances 评论插件
- 2023-03-22 16:08 更新主页快捷联系选项，增加知乎和简书
- 2023-03-21 17:58 更新导航页面文件结构 - `nav.md` 或 `nav/index.md`
- 2023-03-19 00:05 优化导航页面快速跳转

简介

一个简单纯净的主题，欢迎使用。🎉🎉🎉

> 版本功能简介

旧完整版

![[assets/Pasted image 20230815105343.png]]

‘她’包含：

• 两种模式：纯净、酷爽，
• 内置但不限于精美的本地字体，
• 高亮的层级目录，以及
• 简单强大的本地文章实时搜索功能等。

新精简版

该版本为基于旧版本的精简版，包含但不限于以下更新：

• 移除本地全局搜索功能（用的不多）；
• 页面归并改造
  • 移除独立的文章页、归档页入口
  • 归档页精简为只显示标签列表（Obsidian 只支持标签），置于首页
  • 更新导航页
• 移除暗色模式（基本没用过）
• 移除相邻文章切换功能（使用不多）
• 精简了配置项
• ……

![[assets/Pasted image 20230908094527.png]]

快速开始

下载主题

首先，下载该主题。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 方案一
cd YOUR_SITE_DIR	# 本地站点目录
## 默认拉取新精简版
git clone https://github.com/loveminimal/hugo-theme-virgo.git themes/virgo
## 若要拉取旧完整版
git clone --branch v1.0.0 https://github.com/loveminimal/hugo-theme-virgo.git themes/virgo
git switch -c master

# 方案二
cd YOUR_SITE_DIR
git submodule add https://github.com/loveminimal/hugo-theme-virgo.git themes/virgo

💡 使用哪种方式呢？如果你有这个疑问，那么就选择第一种方案。

然后，更新你站点的 config.toml 内容，如下（后续可按需修改）：

• 旧完整版 config-old.toml
• 新精简版 config-new.toml

现在，你就可以进入网站根目录，运行 hugo server -D 开始你的折腾之旅了。

导航页

旧完整版

对于功能完整版，如果，你想使用导航页并正确渲染，那么就应该严格按照这种格式搭建你的 nav.md 文件结构，详见 nav-old.md 。

为什么要做格式方面的限制呢？

众所周知，Markdown 对 Table 的支持很一般，鉴于导航页的内容主要是外链和书签，使用列表管理是最方便的。另外，我们会使用 JS 进行内容项的统计，所以就需要使用者遵守格式，不然可能页面显示可能会不正常。

新精简版

该版本对于 nav.md 的格式要求就比较宽松，详见 nav-new.md 。

导航页放在哪儿？

放在站点根目录中的 contents/nav.md 即可。

它本质上也是一个博客文件，只不过由于其与常规页面而言有一些定制化，我们在 Front Matter 中定义了 type: nav 来标识它。

标记语法增强

> 使用 JS 对 markdown 做出的一些增强性修改

不止一次吐槽过 markdown 虽然是纯文本性质的，但是其某些标记语法真的是让人不敢恭维，直观性和表现力都是一般。不过，从另一个方面来说，本来就是轻量级的标记语言，不可能承载太多。

本来想直接修改 markdown 引擎来实现，研究了一下，还要颇费一番工夫。鉴于仅满足于个人使用，用一些曲线方式使用 js 来实现反而更加简单些。

此处就记录一下针对 hugo-theme-virgo 做的一些魔改。

行内格式

Markdown 中的行内格式有以下几种：

是的，markdown 中没有下划线的标记语法。

本来想用行内代码的标记格式做魔改，鉴于博文中出现行内的代码的概率较高，遍历起来相对更耗性能（虽然并没有多少），故决定选择 *斜体* 语法标记，其使用频率不多，且其对应的 Org Mode 中可以直接显为粗体显示。

| *-高亮* | -高亮 | ❌
| *=吐槽系* | =吐槽系 | ❌

如此，我们便增加了 _下划线 和 =高亮 两种语法标识了。另外，在文章中，尤其是一些摘录和转载的文章中，我们需要做一些随笔，之前我们是使用 <div class="oh-essay">...</div> 这种标签插入，如上表，我们也对其做了语法标识。

如上，所示，更改了一些语法标记，因为有的 Markdown 引擎中使用 ==高亮== 来高亮文本，我们这里就用 *=高亮* 来表示，以做到在观感上统一。

另外，我们不再使用 *=吐槽系* 来表示个人在摘录或编辑中的个人想法展示，主要是由于在不支持当前语法标记的主题中，它只能以斜体展示，不容易和正文内容作区分。我们使用 >:: 吐槽系 或 > :: 吐槽系 来表示，如此在不支持的情况下，可以解析为引用样式，便于区分。

之前我们做了一些 snippet 进行 html 标签的插入，以实现以上效果，但是这就限定在了某些编辑器中，些许背离了纯文本输入的理念，以上小小的增强，使得我们可以任何文本编辑器中进行方便的文本输入。

>:: 好吧，尽管它们只能在 `hugo-theme-virgo` 中才有效果 😅
> ::好吧，尽管它们只能在 `hugo-theme-virgo` 中才有效果 😅
> :: 好吧，尽管它们只能在 `hugo-theme-virgo` 中才有效果 😅

上述语法标记是等价的，会被解析为如下样式：

:: 好吧，尽管它们只能在 hugo-theme-virgo 中才有效果 😅

代码块折叠

在 Markdown 中，包裹代码块很方便。但有时候在博文中，我们可能引入较多的代码片段，这会导致正文内容的间断，所以，允许其进行折叠，可以在 config.toml 中，使用 hasFoldAllCodeBlocks: true 进行初始化。

既然已经可以折叠了，这里我们不妨用它再做一个更通用的折叠板（默认折叠），原理也很简单，利用 lang 判别。

如果其为 _lang 这种格式，则表示轻量级代码折叠 - 不换行；如果使用 __lang 则折叠板中内容会自动换行。

💡 在新精简版中，我们 不再支持 代码块折叠及折叠板功能。

Wiki 链接及图片语法渲染

最近使用 Obsidian ，其使用的链接及图片格式为 Wiki 语法，如下：

Hugo 默认的 Markdown 引擎是不支持渲染这种语法的，我们这里做了一下增强，现在你可以畅快地使用 Obsidian 来编辑你的博客了。

:: 图片和链接，好像 Wiki 的这种语法写起来更加简洁。其实，还是使用 <img> 标签的通用性更好些，不过许多软件的即时渲染又不支持，就很伤。

图片渲染相关

在使用 Obsidian 或 Typora 自动插入图片时，自动插入的图片路径形式为 assets/xxx.jpg 等（无法通过设置使其插入路径为 /assets/xxx.jpg 的形式），Hugo 无法正确渲染访问路径，它在解析的时候，会生成有类似如下路径： http://localhost:1313/temp-%E8%B0%83%E8%AF%95%E6%96%87%E4%BB%B6/assets/baby.png ，所以，我们对其遍历，为不以 / 开头的路径，添加 / ，以使其正确渲染。

结语

制作主题，对‘强迫症’来说，真的是一件挺‘辛苦’的事情，或者说是‘痛并快乐着’ ？！