Hugo Stack 主题布局优化

本文详细记录 Hugo Stack 主题的布局优化，包括页面右边栏控制、友链多列响应式布局、归档页面双列布局等功能实现。

概述

本次优化主要涉及三个方面：

页面右边栏开关：为特定页面（如友链页面）提供隐藏右边栏的功能
友链多列布局：友链模块在大于 768px 时双列显示，大于 1024px 时三列显示
归档页面双列布局：归档页面的文章列表在大于 768px 时双列显示

1. 页面右边栏开关

1.1 需求说明

友链页面（links page）通常不需要显示右边栏，需要提供一种方式来隐藏右边栏。

1.2 实现方案

有两种实现方式：

方案一：检测 `links` 参数（推荐）

修改 themes/hugo-theme-stack/layouts/_default/single.html 文件中的 right-sidebar 块，添加对 links 参数的检测：

{{ define "right-sidebar" }}
    {{- if and (.Scratch.Get "hasWidget") (not .Params.links) -}}
        {{ partial "sidebar/right.html" (dict "Context" . "Scope" "page") }}
    {{- end -}}
{{ end }}

优点：无需在 front matter 中添加额外参数，系统自动检测 links 参数

方案二：使用 `hideRightSidebar` 参数

当前实现方式（使用 hideRightSidebar 参数）：

{{ define "right-sidebar" }}
    {{- if and (.Scratch.Get "hasWidget") (ne .Params.hideRightSidebar true) -}}
        {{ partial "sidebar/right.html" (dict "Context" . "Scope" "page") }}
    {{- end -}}
{{ end }}

使用方式：在页面的 front matter 中添加 hideRightSidebar: true

1.3 工作原理

方案一（推荐）：

当页面有 links 参数时（如友链页面），自动隐藏右边栏
其他页面保持原有逻辑，根据 widget 配置决定是否显示右边栏
无需在 front matter 中添加额外参数，系统自动检测

方案二：

通过 hideRightSidebar 参数手动控制右边栏显示
需要在每个需要隐藏右边栏的页面添加该参数

1.4 使用方式

方案一（推荐）：在友链页面的 front matter 中添加 links 参数即可自动隐藏右边栏：

---
title: 友链 | Links
slug: flinks 
links:
  - title: GitHub
    website: https://github.com
    # ... 其他配置
---

方案二：在需要隐藏右边栏的页面添加 hideRightSidebar: true：

---
title: 页面标题
hideRightSidebar: true
---

2. 友链多列响应式布局

2.1 需求说明

友链模块（.article-list--compact.links）需要响应式布局：

小于 768px：单列显示
768px - 1023px：双列显示
大于等于 1024px：三列显示

2.2 实现方案

在 themes/hugo-theme-stack/assets/scss/partials/article.scss 文件中添加友链模块的响应式样式：

/* Links module with responsive multi-column layout */
.article-list--compact.links {
    @include respond(md) {
        display: grid;
        grid-template-columns: repeat(2, 1fr);
        gap: 0;

        article {
            // Grid 布局下的边框规则：重置原有单列布局的边框
            border-bottom: 1.5px solid var(--card-separator-color);
            border-right: 1.5px solid var(--card-separator-color);

            // 每行的最后一个（偶数索引）移除右边框
            &:nth-child(2n) {
                border-right: none;
            }

            // 最后一行的所有元素移除下边框
            &:nth-last-child(-n + 2) {
                border-bottom: none;
            }
        }
    }

    @include respond(lg) {
        grid-template-columns: repeat(3, 1fr);

        article {
            // 三列布局下的边框规则
            // 每行的最后一个（3的倍数）移除右边框
            &:nth-child(3n) {
                border-right: none;
            }

            // 最后一行的所有元素移除下边框
            &:nth-last-child(-n + 3) {
                border-bottom: none;
            }

            // 重置两列布局的边框规则
            &:nth-child(2n) {
                border-right: 1.5px solid var(--card-separator-color);
            }
        }
    }
}

2.3 技术细节

响应式断点

md: 768px（双列布局）
lg: 1024px（三列布局）

边框处理逻辑

两列布局（768px - 1023px）：

每个 article 有下边框和右边框
每行的最后一个（偶数索引 2n）移除右边框
最后一行的所有元素（最后 2 个）移除下边框

三列布局（≥1024px）：

每个 article 有下边框和右边框
每行的最后一个（3 的倍数 3n）移除右边框
最后一行的所有元素（最后 3 个）移除下边框
重置两列布局的边框规则（2n 恢复右边框）

2.4 HTML 结构

友链模块的 HTML 结构：

<div class="article-list--compact links">
    <article>
        <a href="...">
            <div class="article-details">
                <h2 class="article-title">友链标题</h2>
                <footer class="article-time">描述</footer>
            </div>
            <div class="article-image">
                <img src="..." alt="...">
            </div>
        </a>
    </article>
    <!-- 更多 article 元素 -->
</div>

3. 归档页面双列布局

3.1 需求说明

归档页面（archives page）中的 .archives-group .article-list--compact 需要在大于 768px 时双列显示。

3.2 实现方案

在 themes/hugo-theme-stack/assets/scss/partials/article.scss 文件中添加归档页面的响应式样式：

/* Archives group with two-column layout on larger screens */
.archives-group {
    .article-list--compact {
        @include respond(md) {
            display: grid;
            grid-template-columns: repeat(2, 1fr);
            gap: 0;

            article {
                // Grid 布局下的边框规则：重置原有单列布局的边框
                border-bottom: 1.5px solid var(--card-separator-color);
                border-right: 1.5px solid var(--card-separator-color);

                // 每行的最后一个（偶数索引）移除右边框
                &:nth-child(2n) {
                    border-right: none;
                }

                // 最后一行的所有元素移除下边框
                &:nth-last-child(-n + 2) {
                    border-bottom: none;
                }
            }
        }
    }
}

3.3 HTML 结构

归档页面的 HTML 结构：

<div class="archives-group" id="2026">
    <h2 class="archives-date section-title">
        <a href="/archives/#2026">2026</a>
    </h2>
    <div class="article-list--compact">
        <article>
            <!-- 文章内容 -->
        </article>
        <!-- 更多 article 元素 -->
    </div>
</div>

3.4 边框处理

每个 article 有下边框和右边框
每行的最后一个（偶数索引 2n）移除右边框
最后一行的所有元素（最后 2 个）移除下边框

文件修改清单

修改的文件

themes/hugo-theme-stack/layouts/_default/single.html
- 修改 right-sidebar 块，添加 links 参数检测
themes/hugo-theme-stack/assets/scss/partials/article.scss
- 添加 .archives-group .article-list--compact 双列布局样式
- 添加 .article-list--compact.links 多列响应式布局样式
themes/hugo-theme-stack/layouts/partials/footer/footer.html
- （页脚统计功能已移至单独文档）

CSS 变量说明

样式使用了以下 CSS 变量（由主题定义）：

--card-separator-color: 卡片分隔线颜色
--card-border-radius: 卡片圆角
--card-background: 卡片背景色
--card-padding: 卡片内边距
--small-card-padding: 小卡片内边距

响应式断点

主题使用的响应式断点定义（themes/hugo-theme-stack/assets/scss/breakpoints.scss）：

$breakpoints: (
    sm: 640px,
    md: 768px,   // 双列布局起点
    lg: 1024px,  // 三列布局起点（友链）
    xl: 1280px,
    2xl: 1536px,
);

测试验证

1. 页面右边栏开关

友链页面（有 links 参数）不显示右边栏
其他页面正常显示右边栏（根据 widget 配置）

2. 友链多列布局

小于 768px：单列显示
768px - 1023px：双列显示，边框正确
大于等于 1024px：三列显示，边框正确
最后一行的边框处理正确

3. 归档页面双列布局

小于 768px：单列显示
大于等于 768px：双列显示，边框正确
最后一行的边框处理正确

浏览器兼容性

使用 CSS Grid 布局，需要现代浏览器支持
使用 nth-child() 和 nth-last-child() 伪类选择器
兼容所有支持 CSS Grid 的浏览器（IE 11+ 需要 polyfill，但主题已不兼容 IE）

总结

通过以上优化，实现了：

灵活的右边栏控制：通过检测页面参数自动隐藏不需要的右边栏
响应式友链布局：根据屏幕尺寸自动调整列数，提升用户体验
归档页面优化：双列布局提高内容密度，更好地利用屏幕空间

这些优化都遵循了主题的设计规范，使用主题提供的 CSS 变量和响应式断点，确保样式的一致性和可维护性。

注意：页脚统计功能（showStats、showRuntime）和 busuanzi 访问量统计的集成方法已移至单独文档：Hugo Stack 主题页脚统计和访问量集成

Hugo Stack 主题布局优化

概述

1. 页面右边栏开关

1.1 需求说明

1.2 实现方案

方案一：检测 links 参数（推荐）

方案二：使用 hideRightSidebar 参数

1.3 工作原理

1.4 使用方式

2. 友链多列响应式布局

2.1 需求说明

2.2 实现方案

2.3 技术细节

响应式断点

边框处理逻辑

2.4 HTML 结构

3. 归档页面双列布局

3.1 需求说明

3.2 实现方案

3.3 HTML 结构

3.4 边框处理

文件修改清单

修改的文件

CSS 变量说明

响应式断点

测试验证

1. 页面右边栏开关

2. 友链多列布局

3. 归档页面双列布局

浏览器兼容性

总结

方案一：检测 `links` 参数（推荐）

方案二：使用 `hideRightSidebar` 参数