hugo-stack主题配置和美化

文件目录结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


my-hugo-site/
├── archetypes/           # 文章模板（新建内容时的默认 front matter）
│   └── default.md
│
├── assets/               # 包含通常通过资源管道传递的全局资源。这包括诸如图片、CSS、Sass、JavaScript 和 								    TypeScript 等资源
│
├── content/              # 站点内容（你的 Markdown 文章）
│   ├── post/
│   │   ├── hello-world.md
│   │   └── hugo-tutorial.md
│   └── about.md
│
├── data/                 # 存放数据文件（YAML / JSON / TOML）
│   └── authors.yaml
│
├── layouts/              # 模板文件目录（核心）
│   ├── _default/
│   │   ├── baseof.html   # 基础布局模板
│   │   ├── list.html     # 列表页模板
│   │   └── single.html   # 单页模板
│   ├── partials/         # 公共片段（header、footer等）
│   ├── shortcodes/       # 短代码目录
│   │   └── raw.html
│   └── index.html
│
├── static/               # 静态资源（图片、js、css... 不会被处理）
│   ├── images/
│   └── js/
│
├── themes/               # 主题目录（主题有自己的 layouts、static 等）
│   └── hugo-theme-stack/
│
├── config.toml           # 主配置文件（也可以是 .yaml 或 .json）
├── hugo.toml             # 新版可替代 config.toml

stack配置文件

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241


baseurl: https://example.com/   # 网站基础 URL，部署上线时改成你自己的域名
languageCode: en-us             # 默认语言环境
theme: hugo-theme-stack         # 使用的主题目录名称
title: Example Site             # 网站标题
copyright: Example Person       # 页脚版权信息

# Theme i18n support
# Available values: ar, bn, ca, de, el, en, es, fr, hu, id, it, ja, ko, nl, pt-br, th, uk, zh-cn, zh-hk, zh-tw
DefaultContentLanguage: en      # 默认语言
# Set hasCJKLanguage to true if DefaultContentLanguage is in [zh-cn ja ko]
# This will make .Summary and .WordCount behave correctly for CJK languages.
hasCJKLanguage: false           # 是否为中文/日文/韩文优化，开启可以正确统计中文字数

languages:                      # 多语言配置
    en:
        languageName: English   # 英文站点显示名
        title: Example Site     # 英文版标题
        weight: 1               # 权重（决定语言切换顺序）
        params:
            sidebar:
                subtitle: Example description   # 侧边栏描述
    zh-cn:
        languageName: 中文
        title: 演示站点 
        weight: 2
        params:
            sidebar:
                subtitle: 演示说明
    ar:
        languageName: عربي       # 阿拉伯语
        languagedirection: rtl  # 文字方向：从右到左
        title: موقع تجريبي 
        weight: 3
        params:
            sidebar:
                subtitle: وصف تجريبي

services:                       # 外部服务
    # Change it to your Disqus shortname before using
    disqus:
        shortname: "hugo-theme-stack"   # Disqus 评论系统 ID
    # GA Tracking ID
    googleAnalytics:
        id:                     # Google Analytics 跟踪 ID

pagination:
    pagerSize: 3                # 每页文章数

permalinks:                     # URL 规则
    post: /p/:slug/             # 文章链接形如 /p/xxx/
    page: /:slug/               # 单独页面链接形如 /about/

params:                         # 主题参数
    mainSections:				# 首页显示 content/post/ 下的文章
        - post
    featuredImageField: image   # 文章封面图字段
    rssFullContent: true        # RSS 全文输出
    favicon:                    # 网站 favicon 路径

    footer:
        since: 2020             # 页脚起始年份
        customText:             # 页脚自定义文字

    dateFormat:                 # 控制日期的显示格式（Go 的时间模板）
        published: Jan 02, 2006
        lastUpdated: Jan 02, 2006 15:04 MST

    sidebar:                    # 侧边栏
        emoji: 🍥 				# 侧面头像旁图标
        subtitle: Lorem ipsum dolor sit amet, consectetur adipiscing elit. #副标题
        avatar:
            enabled: true       # 启用头像
            local: true         # 使用本地头像
            src: img/avatar.png # 头像路径 

    article:                    # 文章配置
        math: false             # 数学公式支持
        toc: true               # 目录
        readingTime: true       # 阅读时间
        license:
            enabled: true       # 版权信息
            default: Licensed under CC BY-NC-SA 4.0

    comments:                   # 评论配置
        enabled: true           # 开启评论
        provider: disqus        # 评论提供商
        disqusjs:
            shortname:
            apiUrl:
            apiKey:
            admin:
            adminLabel:
        utterances:
            repo:
            issueTerm: pathname
            label:
        beaudar:
            repo:
            issueTerm: pathname
            label:
            theme:
        remark42:
            host:
            site:
            locale:
        vssue:
            platform:
            owner:
            repo:
            clientId:
            clientSecret:
            autoCreateIssue: false
        waline:
            serverURL:
            lang:
            pageview:
            emoji:
                - https://unpkg.com/@waline/emojis@1.0.1/weibo
            requiredMeta:
                - name
                - email
                - url
            locale:
                admin: Admin
                placeholder:
        twikoo:
            envId:
            region:
            path:
            lang:
        cactus:
            defaultHomeserverUrl: "https://matrix.cactus.chat:8448"
            serverName: "cactus.chat"
            siteName: "" # 唯一站点 ID
        giscus:
            repo:
            repoID:
            category:
            categoryID:
            mapping:
            lightTheme:
            darkTheme:
            reactionsEnabled: 1
            emitMetadata: 0
        gitalk:
            owner:
            admin:
            repo:
            clientID:
            clientSecret:
            proxy:
        cusdis:
            host:
            id:
    widgets:                    # 右侧小部件配置
        homepage:				 # 首页
            - type: search       # 搜索框
            - type: archives     # 归档
              params:
                  limit: 5
            - type: categories   # 分类
              params:
                  limit: 10
            - type: tag-cloud    # 标签云
              params:
                  limit: 10
        page:					 # 文章
            - type: toc          # 页面目录

    opengraph:                  # OpenGraph（社交分享卡片）
        #twitter:
            site:
            card: summary_large_image

    defaultImage:               # 默认分享图
        opengraph:
            enabled: false
            local: false
            src:

    colorScheme:                # 配色
        toggle: true            # 允许切换
        default: auto           # 默认自动（跟随系统）

    imageProcessing:            # 图片处理
        cover:
            enabled: true
        content:
            enabled: true

### Custom menu
### See https://stack.jimmycai.com/config/menu
### To remove about, archive and search page menu item, remove `menu` field from their FrontMatter
menu:
    main: []                    # 主菜单
    social:                     # 社交菜单
        - identifier: github
          name: GitHub			# 鼠标悬停时名称
          url: https://github.com/CaiJimmy/hugo-theme-stack
          params:
              icon: brand-github # 图标

related:                        # 相关文章推荐
    includeNewer: true           # 是否包含比当前文章新的内容
    threshold: 60                # 相似度阈值，越高要求越严格
    toLower: false               # 是否把内容转换为小写再比较
    indices:                     # 参与相似度计算的字段
        - name: tags             # 按标签计算相似度
          weight: 100            # 标签权重（影响匹配结果）
        - name: categories       # 按分类计算相似度
          weight: 200            # 分类权重更高，优先推荐同类文章

markup:                         # Markdown 渲染
    goldmark:
        extensions:
            passthrough:        # 允许原样渲染特殊符号
                enable: true
                delimiters:
                    block:
                        - - \[
                          - \]
                        - - $$
                          - $$
                    inline:
                        - - \(
                          - \)
        renderer:
            ## Set to true if you have HTML content inside Markdown
            unsafe: true        # 允许 HTML
    tableOfContents:            # 自动目录生成
        endLevel: 4             # 目录生成到 h4
        ordered: true           # 用数字编号（有序列表）
        startLevel: 2           
    highlight:                  # 代码块高亮配置
        noClasses: false        
        codeFences: true        
        guessSyntax: true       # 自动猜测语言
        lineNoStart: 1          
        lineNos: true           # 显示行号
        lineNumbersInTable: true 
        tabWidth: 4             

Front Matter

它是每篇 Markdown 文章开头的元数据，用来控制文章的标题、时间、状态、分类等。

每次使用hugo new命令创建文章时，都会从/archetypes/default.md读取模板创建。

hugo

字段名	类型	说明
`title`	字符串	页面标题
`date`	时间戳	页面发布日期，支持 ISO 8601 格式
`draft`	布尔值	草稿状态，`true` 不生成页面，`false` 发布页面
`weight`	整数	页面权重，用于排序，数值越小优先级越高
`params`	对象	自定义参数，可在模板中引用
`categories`	列表	文章分类，可多个
`tags`	列表	标签，可多个
`summary`	字符串	摘要，用于列表页显示
`layout`	字符串	页面布局类型，可指定使用哪个模板
`lang`	字符串	页面语言，用于多语言网站
`type`	字符串	页面类型，用于模板选择和内容组织

stack

字段名	类型	说明
`description`	字符串	页面描述
`image`	字符串	文章封面图片
`comments`	布尔值	是否显示评论区，适用于单页
`license`	字符串或布尔值	页面版权信息，若为 `false`，则隐藏版权部分；默认值为 `.Site.Params.Article.License.Default`
`math`	布尔值	是否启用 KaTeX 渲染，适用于单页
`toc`	布尔值	是否显示目录，适用于单页；若页面中至少有一个标题，则显示目录；默认值为 `.Site.Params.Article.toc`
`style`	字典（键值对）	文章分类标签的额外 CSS 样式，适用于列表页；目前支持 `background`（背景色）和 `color`（文字色）
`keywords`	字符串数组	页面关键词，用于 SEO
`readingTime`	布尔值	是否显示阅读时间，适用于单页；默认值为 `.Site.Params.Article.ReadingTime`

Shortcode

Hugo 简码是一种在 Markdown 内容中嵌入动态或可复用功能的机制。它可以把复杂的 HTML 或逻辑封装成一个可复用的标记，在文章中直接使用。语法和模板语法类似，支持参数和内部模板。

语法

自闭合简码

1

{{< shortcode-name param="value" >}}

带内容简码

1
2
3
4
5


{{< shortcode-name param="value" >}}
第一行
第二行
第三行
{{< /shortcode-name >}}

{\{< >}\} 是 不解析 Markdown 的原始简码，{\{% %}\} 是 解析 Markdown 的简码。

内置简码

简码名称	作用	示例
`figure`	插入图片，并可加标题或描述	`{\{< figure src="/img.png" title="示例图" >}\}`
`youtube`	嵌入 YouTube 视频	`{\{< youtube w7Ft2ymGmfc >}\}`
`relref`	链接站内内容，支持文章路径	`{\{< relref "post/my-article.md" >}\}`
`ref`	生成站内内容的完整 URL	`{\{< ref "post/my-article.md" >}\}`
`highlight`	高亮显示代码段	`{\{< highlight go >}\}fmt.Println("hello"){\{< /highlight >}\}`
`x`	嵌入推特内容	`{\{< x 1234567890 >}\}`

自定义简码

简码存放位置：layouts/shortcodes/shortcode-name.html，文件名就是简码的名称，例如alert.html就是{\{<alert>}\}

简码变量

变量 / 方法	类型	说明
`.Name`	string	当前简码的名字（即文件名，不含扩展名）
`.Params`	array / map	调用时传入的所有参数
`.Get <name/index>`	string	获取指定参数（可按名称或索引）
`.IsNamedParams`	bool	判断是否使用了命名参数形式（`name="value"`）
`.Inner`	string	获取简码标签内部的内容（即 `{\{< shortcode >}\}...{\{< /shortcode >}\}` 之间的文本）
`.Parent`	context	获取外层简码（嵌套简码时）
`.Page`	Page 对象	引用当前页面对象，可以访问 `.Title`、`.Permalink` 等
`.Site`	Site 对象	获取整个站点的全局变量（比如 `.Site.Params`、`.Site.Title`）

一个简单