Inline Formatting

你可以在这里检查 粗体、斜体、组合强调、行内代码，以及标准的 Hugo 链接 。

你还可以顺便测试类似 H2O 这样的上下标写法、Ctrl + K 这种键盘提示，以及 *literal asterisks* 这类转义字符。

Lists

Unordered List

• 封面优先的卡片在手机上依然应该保持平静的浏览节奏。
• 元信息在窄屏下也要足够易读。
• 间距和排版的重要性不低于字体本身。

Ordered List

1. 起草文章。
2. 添加封面图。
3. 在手机上检查阅读节奏。

Task List

• 添加 front matter
• 添加本地封面图
• 将示例文案替换成正式内容

Quote

好的文章主题，会在你阅读时悄悄退到后面。

更好的主题，则会在你点开文章之前就让浏览体验足够舒服。

Code Blocks

theme = "pocket-hugo-theme"
defaultContentLanguage = "en"
mainSections = ["posts"]

const article = {
  title: "Markdown Rendering Showcase",
  cover: "cover.webp",
  mobileReady: true,
};

Table

Image

这个页面 bundle 中的本地图片既会作为封面，也会作为正文内联图片出现：

Horizontal Rule

Final Notes

如果这篇文章在桌面端和手机端都显得平衡自然，那么这套主题通常就已经适合承载真正的随笔、更新记录、笔记和文档页面。

这个功能适合什么场景

当你希望文章在列表页和单页里看起来都足够完整，但又不想为每一篇文章都单独准备真实图片文件时，就很适合使用标题卡片。

它尤其适合：

• 笔记和短文
• 文档页面
• 希望保持统一节奏的多语言页面
• 那些更适合文字导向卡片，而不是照片封面的栏目

Quick start

在 front matter 中，最简单的写法只需要一个字母：

coverCard: "a"

规则如下：

• a 到 h：8 个浅色预设
• A 到 H：8 个深色预设
• 其他任意值：自动回退到随机预设

一旦你设置了 coverCard，主题就会使用生成的标题卡片，并停止使用 image。

隐藏重复的列表标题

如果你只想让标题出现在卡片内部，而不想在首页、分类、归档等列表页里重复显示外部标题，可以添加：

listTitle: false

这样会隐藏列表卡片里的重复标题。在单页中，如果该页面使用的是生成型标题卡片，也会一并隐藏独立的标题区块。

如果你想在全站范围修改，可以在 hugo.toml 中设置 params.article.listTitle = false。这个站点级开关只影响列表页里的渐变标题卡片，不影响普通图片封面。

Example front matter

title: "My Article"
date: 2026-02-09T08:30:00+08:00
slug: "my-article"
coverCard: "C"
listTitle: false

All 16 presets

下面展示的是主题内置的 16 个预设，顺序与主题内部使用顺序一致。

When to use which preset

• a / A：偏暖、偏编辑感，适合随笔和个人写作
• b / B：更柔和、更亲切，适合教程或文档
• c / C：对比更强，适合产品说明或发布记录
• d / D：低饱和、更安静，适合归档式或回顾型内容
• e / E：更轻快鲜明，适合工具、工作流和更新
• f / F：中性克制，适合技术参考
• g / G：更清晰、更数字化，适合软件和平台类主题
• h / H：黑白极简，适合简短笔记或索引页

Default behavior

如果页面没有定义 coverCard，主题就会按照 hugo.toml 中的站点级封面规则继续处理。

也就是说，用户即使什么都不做，也可能默认得到一张自动生成的标题卡片。当主题的 fallback 模式设置为 gradient 时，卡片预设会自动分配。

这意味着你可以把两种策略结合起来使用：

• 为普通文章设置一个全站 fallback 模式
• 只在需要特定风格的页面上单独指定 coverCard

One practical recommendation

一个很实用的做法是：先为整个站点启用自动 fallback，再只给少数你希望更有辨识度的页面手动分配字母。这样既能保持写作速度，也能让重要页面更有个性。

默认设置

默认情况下，Pocket Hugo Theme 会在所有页面启用评论。如果你想在某一篇页面或文章上关闭评论，只需要在对应 Markdown 文件的 front matter 中添加 comments = false。

这个主题默认使用 Twikoo 作为评论系统。若要使用 Twikoo，你需要按照 Twikoo 官方文档部署对应的云函数，才能正常运行。你也可以根据自己的偏好改用其他评论方案，例如 Utterances、Waline、Disqus 等。

• Twikoo 文档
• Giscus 文档
• Utterances 文档
• Waline 文档
• Disqus 文档

如果你希望下面所有区块都按预期渲染，请先在 hugo.toml 中打开对应开关：

[params.extensions]
  mermaid = true
  katex = true

代码高亮样式默认已经内置。对于 Mermaid 和 KaTeX，还需要在真正使用它们的文章 front matter 中声明页面级列表：

extensions:
  - mermaid
  - katex

Syntax Highlighting

Pocket Hugo 默认附带了一层轻量的代码高亮配色，所以普通的高亮代码块不需要额外开启页面级开关。

package main

import "fmt"

func main() {
    theme := "pocket-hugo-theme"
    enabled := []string{"syntax", "mermaid", "katex"}
    fmt.Println(theme, enabled)
}

.article-content pre {
  border-radius: 18px;
  overflow-x: auto;
}

Mermaid

开启 mermaid 扩展后，语言标记为 mermaid 的代码块会在页面中被转换成图表。

flowchart LR
    A[编写 Markdown] --> B[开启扩展]
    B --> C[构建站点]
    C --> D[查看渲染后的图表]

KaTeX

开启 katex 扩展后，文章中的行内公式和块级公式都可以直接渲染。

行内公式：$E = mc^2$

块级公式：

$$ \int_{0}^{1} x^2 , dx = \frac{1}{3} $$

$$ f(x) = \frac{1}{\sqrt{2\pi\sigma^2}} \exp\left(-\frac{(x-\mu)^2}{2\sigma^2}\right) $$

Mixed Content

这篇文章的重点，是展示代码、图表和数学公式可以同时出现在一篇普通文章里，而且不会破坏主题原有的阅读节奏。

1. Syntax highlighting 用来增强代码 token 的对比度。
2. Mermaid 会把围栏代码块转换成 SVG 图表。
3. KaTeX 负责渲染数学公式，同时不打断写作流程。