概述

Stack 主题是我用过最舒服的 Hugo 主题之一——卡片化设计、配置直观、生态完善。但凡事总有两面，本文记录一些不直观的地方与踩过的坑，希望能帮后来者少走弯路。

一、必须使用 Hugo extended

主题使用 SCSS/TS 编译，如果用普通版 Hugo，启动会直接失败：

Error: TOCSS: failed to transform "scss/style.scss"

📌 重要

下载时务必选择文件名包含 extended 的版本。

二、Widgets 配置

Stack 的 widgets（小部件）分两类：

• widgets.homepage：首页右侧栏
• widgets.page：文章页右侧栏

支持的类型：search、archives、categories、tag-cloud、taxonomy、toc。

示例：

[params.widgets]
  homepage = [
    { type = "search" },
    { type = "archives", params = { limit = 8 } },
    { type = "categories", params = { limit = 10 } },
  ]
  page = [
    { type = "toc" },
    { type = "search" },
  ]

三、搜索页必须存在

要使用搜索功能，必须先创建 content/page/search.md：

---
title: "搜索"
layout: "search"
---

否则侧栏虽然能看到搜索框，但点击后会 404。

四、暗色模式

主题支持跟随系统的暗色模式：

[params.colorScheme]
  toggle  = true
  default = "auto"

default 可选 light / dark / auto。

五、文章分析

主题内置 Google Analytics：

[services.googleAnalytics]
  ID = "G-XXXXXXXXXX"

💡 提示

国内站点也可通过 layouts/partials/extend_head.html 自定义脚本接入不蒜子、百度统计、Umami 等。

六、目录与代码块

• 目录显示需同时启用 params.article.toc = true 与侧栏 type = "toc" widget。
• 代码块支持 100+ 语言高亮，使用 ```lang 标记即可。

七、封面图建议

推荐比例 16:9 或 3:2，分辨率 ≥ 1200×630，否则在小屏会被强制放大模糊。

小结

• 主题门槛低，但 extended 版本是硬性要求
• 搜索、归档、目录等高级功能都依赖显式创建页面或显式启用 widget
• 暗色模式、GA、字体等都可以精细定制

工具是骨架，文章才是灵魂。