博客搭建 on 远楒

Widgets修复与开发

Wed, 12 Feb 2025 16:33:24 +0800

计划

添加widget，展示当前博文的tags

右侧边栏的tag-cloud和categories不能处理hidden博文

tag-cloud识别hidden博文

把layouts/partials/widget/tag-cloud.html的渲染tag-cloud的逻辑进行如下修改：

        <div class="tagCloud-tags">
-        {{ range first $limit $context.Site.Taxonomies.tags.ByCount }}
-            <a href="{{ .Page.RelPermalink }}" class="font_size_{{ .Count }}">
-                {{ .Page.Title }}
-            </a>
+        {{- $cateTaxonomy := $context.Site.GetPage "tags" -}}
+        {{- $cateTerms := $cateTaxonomy.Pages -}}
+        {{ range first $limit $cateTerms }}
+            {{- $pages := .Pages -}}
+            {{- $filteredPages := where $pages ".Params.hidden" "!=" true -}}
+            {{ if $filteredPages }}
+                <a href="{{ .RelPermalink }}" class="font_size_{{ len $filteredPages}}">
+                    {{ .Title }}
+                </a>
+            {{ end }}
+        {{ end }}
    </div>

如另一篇博文中的方法，从$context.Site中获取所有tags然后过滤掉hidden == true的博文后，判断$filteredPages中是否还有元素，如果有则渲染这个tag。

添加模板文件

在layouts/partials/widget文件夹下新建文件cur-tags.html，添加如下内容：

{{- $context := .Context -}}
{{ if .Context.Page.Params.Tags }}
<section class="widget curTags">
    <div class="widget-icon">
        {{ partial "helper/icon" "tag" }}
    </div>
    <h2 class="widget-title section-title">{{ T "widget.curTags.title" }}</h2>
    <div class="curTags-tags">
        {{ range (.Context.Page.GetTerms "tags") }}
            <a href="{{ .RelPermalink }}">
                {{ .LinkTitle }}
            </a>
        {{ end }}
    </div>
</section>
{{ end }}

首先判断当前文章是否有tag，然后根据其他widget的模板修改成current tags，使用GetTerms方法获得当前文章的tags，作为<a>标签的参数。

注意<h2>标签中的T函数，用于在修改页面语言时批量替换文本，我们需要在对应文件中添加widget.curTags.title命名空间的值。

添加i18n替换文本

在i18n/en.yaml和i18n/zh-cn.yaml中添加相关内容，在widget域下添加内容：

widget:
+    curTags:
+        title:
+            other: Tags of current blog

添加scss样式表

在assets/scss/partials/widgets.scss中添加curTags的样式。

/* Current tags widget */
.curTags {
    .curTags-tags {
        display: flex;
        flex-wrap: wrap;
        gap: 10px;

        a {
            background: var(--card-background);
            box-shadow: var(--shadow-l1);
            border-radius: var(--tag-border-radius);
            padding: 8px 20px;
            color: var(--card-text-color-main);
            font-size: 1.4rem;
            transition: box-shadow 0.3s ease;

            &:hover {
                box-shadow: var(--shadow-l2);
            }
        }
    }
}

自此，current tags控件的开发已经成功，在stack/config.yaml中添加配置项即可。

params:
    widgets:
        page:
+          - type: cur-tags

Archive页改造

Sun, 02 Feb 2025 22:46:55 +0800

Archive页介绍

archive页面展示了当前博文的所有类型，在此之下依据年份时序展示所有博文。

改造计划:

添加对以tag分类的支持
- 支持在archive页展示tag模块
- 修改tag–tile的大小
- 修改tag–tile的排列方式
- 为tag分类的每一个tile添加不同颜色
修复在archive页面的category tile展示异常
修复category详细页的文章数量异常
添加archive页面对应配置项

使用开发者工具检查archive页面元素

发现category分类的元素为：

    <h2 class="section-title">类别 - Categories</h2>
    <div class="subsection-list">
        <div class="article-list--tile">
            <article>
            </article>
        </div>
    </div>

显然<div class="article-list--tile">的class属性命名并不合理，因为在archive首页展示的category列表的每一个tile并不是一篇article，因此应当修改为<div class="category-list--tile">。

在文件themes/hugo-theme-stack/layouts/_default/archives.html中将<div class="article-list--tile">修改为<div class="category-list--tile">。

同时将下列文件中的选择器article-list--tile修改为category-list--tile。在scss文件中建议保留原有的选择器，新增修改名称后的选择器。

themes/hugo-theme-stack/assets/scss/partials/article.scss
themes/hugo-theme-stack/assets/scss/partials/layout/list.scss
/home/fendy/Project/BlogSrc/themes/hugo-theme-stack/assets/ts/main.ts

修复category tile展示异常

本质上是没有添加对hidden文章的判断逻辑，在themes/hugo-theme-stack/layouts/_default/archives.html中添加筛选逻辑：

    <h2 class="section-title">类别 - {{ $cateTaxonomy.Title }}</h2>
    <div class="subsection-list">
        <div class="category-list--tile">
            {{ range $cateTerms }}
                {{- $pages := .Pages -}}
                {{- $filteredPages := where $pages ".Params.hidden" "!=" true -}}
                {{ if $filteredPages }}
                    {{ partial "article-list/tile" (dict "context" . "size" "250x150" "Type" "taxonomy") }}
                {{ end }}
            {{ end }}
        </div>
    </div>

添加对tag分类的支持

支持在archive页展示tag模块

在themes/hugo-theme-stack/layouts/_default/archives.html中，类别模块的下方添加如下代码：

    {{- $tagTaxonomy := $.Site.GetPage "taxonomyTerm" "tags" -}}
    {{- $tagTerms := $tagTaxonomy.Pages -}}
    {{ if $tagTerms }}
    <h2 class="section-title">标签 - {{ $tagTaxonomy.Title }}</h2>
    <div class="subsection-list">
        <div class="tag-list--tile">
            {{ range $tagTerms }}
                {{/* 获取当前标签下的所有页面 */}}
                {{- $pages := .Pages -}}
                {{/* 过滤掉 hidden 为 true 的页面 */}}
                {{- $filteredPages := where $pages ".Params.hidden" "!=" true -}}
                {{ if $filteredPages }}
                    {{ partial "article-list/tile" (dict "context" . "Type" "tag" "pages" $filteredPages) }}
                {{ end }}
            {{ end }}
        </div>
    </div>
    {{ end }}

添加tag的样式并修改tag–tile的大小

在themes/hugo-theme-stack/assets/scss/partials/article.scss中添加:

.tag-list--tile {
    article {
        border-radius: var(--card-border-radius);
        overflow: hidden;
        position: relative;
        height: 350px;
        width: 250px;
        box-shadow: var(--shadow-l1);
        transition: box-shadow 0.3s ease;
        background-color: var(--card-background);

        &:hover {
            box-shadow: var(--shadow-l2);
        }

        .article-details {
            border-radius: var(--card-border-radius);
            position: relative;
            height: 100%;
            width: 100%;
            display: flex;
            flex-direction: column;
            justify-content: flex-end;
            z-index: 2;
            padding: 15px;

            @include respond(sm) {
                padding: 20px;
            }
        }

        .article-title {
            font-size: 2rem;
            font-weight: 500;
            color: var(--card-text-color-main);

            @include respond(sm) {
                font-size: 2.2rem;
            }
        }
    }
}

在themes/hugo-theme-stack/assets/scss/partials/layout/list.scss中添加:

    .tag-list--tile {
        display: flex;

        article {
            width: 120px;
            height: 30px;
            margin-right: 20px;
            flex-shrink: 0;

            .article-title {
                margin: 0;
                font-size: 1.8rem;
            }

            .article-details {
                padding-bottom: 5px;
                text-align: center;
            }
        }
    }

添加archives页面对应配置项

设计配置项

由于目前archives页面有三个板块：Categories，Tags，Dates。考虑添加如下配置项（标注出的为默认配置，不进行配置也会以下面代码块给定的配置渲染）：

params:
    archives:
        showCategories: true
        showTags: false
        showDates: true

修改对应源码读取配置项

修改layouts/_default/archives.html文件，将{{ if $term }}判断语句添加一个与项，同时修改变量名。最终修改后结果如下：

{{ if and (eq (.Site.Params.archives.showCategories | default true) true) (gt (len $cateTerms) 0) }}

同理，在渲染tags和dates板块的部分使用如下语句对包裹：

{{ if and (eq (.Site.Params.archives.showTags | default false) true) (gt (len $tagTerms) 0) }}
{{ /* 渲染Tags板块 */ }}
{{ end }}


{{ if eq (.Site.Params.archives.showDates | default true) true }}
{{ /* 渲染Dates板块*/ }}
{{ end }}

修复category详细页的文章数量异常问题

在layouts/_default/list.html文件中进行如下修改：

-    <h3 class="section-count">{{ T "list.page" (len .Pages) }}</h3>
+    {{- $filteredPages := where .Pages ".Params.hidden" "!=" true -}}
+    <h3 class="section-count">{{ T "list.page" (len $filteredPages) }}</h3>

把.Pages的元素个数替换为筛选后的元素个数。

新增分类方式：collections

设计配置项

在layouts/_default/archives.html中添加配置项showCollections。

params:
    archives:
        showCategories: true
+        showCollections: true
        showTags: false
        showDates: true

修改archive.html渲染collections列表

<!-- Collections Section -->
{{- $collectionTaxonomy := $.Site.GetPage "collections" -}}
{{- $collectionTerms := $collectionTaxonomy.Pages -}}
{{ if and (eq (.Site.Params.archives.showCollections | default false) true) (gt (len $collectionTerms) 0) }}
<h2 class="section-title">合集 - {{ $collectionTaxonomy.Title }}</h2>
<div class="subsection-list">
    <div class="category-list--tile">
        {{ range $collectionTerms }}
            {{- $pages := .Pages -}}
            {{- $filteredPages := where $pages ".Params.hidden" "!=" true -}}
            {{ if $filteredPages }}
                {{ partial "article-list/tile" (dict "context" . "size" "250x150" "Type" "taxonomy") }}
            {{ end }}
        {{ end }}
    </div>
</div>
{{ end }}

在文件layouts/_default/archives.html中需要的位置添加如上代码。这篇博客是在categories和tags中间添加。

修改配置文件

修改hugo.toml添加如下配置项。

[taxonomies]
category = 'categories'
tag = 'tags'
collection = 'collections'

新建模板文件

在content文件夹下新建文件夹collections，在collections文件夹下如category一般新建分类项。如新建子目录及文件test-collection/_index.md，并在子目录中添加如下内容：

---
title: "测试用"
description: "test"
---

在这之后就可以在博文的front-matter中添加如下内容，以将这篇博文归类到一个合集中：

collections = "test-collection"

效果展示

新建合集rvs-enr-crs选择一篇博文添加collections = "rvs-env-crs"。

可见成功生效。

hugo+GithubIO自建博客踩坑实录

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

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

不能正确渲染主题 - 2025.01.28

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

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

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

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

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

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

name: deploy

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

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

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

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

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

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

        - name: Build Web
          run: hugo -D

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

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

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

使用hugo-theme-stack主题后

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

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

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

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

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

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

markup.highlight.noClasses=false

问题得以修复。

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

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

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

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

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

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

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

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

markup.goldmark.renderer.unsafe=true

成功渲染，效果如图。

博客搭建 on 远楒

Widgets修复与开发

计划

右侧边栏的tag-cloud和categories不能处理hidden博文

tag-cloud识别hidden博文

添加一种展示当前博文tags的Widget

添加模板文件

添加i18n替换文本

添加scss样式表

Archive页改造

Archive页介绍

使用开发者工具检查archive页面元素

修复category tile展示异常

添加对tag分类的支持

支持在archive页展示tag模块

添加tag的样式并修改tag–tile的大小

添加archives页面对应配置项

设计配置项

修改对应源码读取配置项

修复category详细页的文章数量异常问题

新增分类方式：collections

设计配置项

修改archive.html渲染collections列表

修改配置文件

新建模板文件

效果展示

hugo+GithubIO自建博客踩坑实录

不能正确渲染主题 - 2025.01.28

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

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

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

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