文章 on Solitude

开始使用 Solitude Hugo

solitude@example.org (Solitude) — Tue, 25 Aug 2026 10:00:00 +0800

Solitude 是一款注重内容体验的 Hugo 主题。它使用 Go Templates 组织页面，通过 Hugo Pipes 处理样式和 TypeScript；站点构建只需要 Hugo，不需要额外安装 Node.js、PostCSS、Sass 或 Stylus。

准备环境

请安装 Hugo v0.164.0 或更高版本。官方发行版已经包含主题需要的模板和资源处理能力，可以通过下面的命令确认版本：

hugo version

安装主题

在 Hugo 站点根目录把 Solitude 添加为 Git submodule：

git submodule add -b hugo https://github.com/everfu/hugo-solitude.git themes/solitude

随后在站点的 hugo.yaml 中启用主题，并声明搜索与友链数据使用的输出格式：

theme: solitude

outputs:
 home: [HTML, RSS, Search, Links]
 section: [HTML, RSS]
 taxonomy: [HTML, RSS]
 term: [HTML, RSS]

params:
 solitude:
 search:
 enable: true
 type: local

主题仓库中的 exampleSite/hugo.yaml 是完整配置起点。复制时建议保留配置层级，再逐项替换站点名称、导航、首页推荐、侧栏和页脚内容。

配置首页推荐与侧栏组合

solitude@example.org (Solitude) — Mon, 24 Aug 2026 10:00:00 +0800

线上演示站通过首页推荐和侧栏卡片帮助访客快速理解站点。Hugo 版本已经把这些能力收进主题配置：内容来自站点数据，不需要服务端接口，也不需要额外的侧栏插件。

首页标题与推荐内容

首页顶部由 params.solitude.hometop 控制。推荐项最多展示五条；配置不足五条时，主题会按发布日期自动补入最近文章。

params:
 solitude:
 hometop:
 enable: true
 banner:
 title: 用 Solitude<br>记录与创造
 desc: Hugo 主题演示、配置指南与前端实践
 recommendList:
 - title: 开始使用 Solitude Hugo
 url: /p/getting-started.html
 cover: /img/demo/cover-getting-started-v2.webp
 label: 快速开始
 color: "#3b82f6"
 - title: 配置首页推荐与侧栏组合
 url: /p/homepage-and-aside.html
 cover: /img/demo/cover-pagination-v2.webp
 label: 配置指南
 color: "#16a34a"

url 应当使用文章最终生成的地址，cover 则应放在站点 static/ 下或指向稳定的远程资源。首页卡片会复用文章标题、分类和封面，因此不必为自动补入的文章重复维护数据。

组合不同页面的侧栏

侧栏支持四个内置组件：

about：站点或作者信息卡。
newestPost：最近发布的五篇文章。
allInfo：标签与文章数、字数、运行时间等站点信息。
newest_comment：启用受支持评论服务后展示最近评论。

每种页面可以分别声明普通区域和吸顶区域：

params:
 solitude:
 aside:
 position: 1
 home:
 noSticky: about
 Sticky: allInfo
 post:
 noSticky: about
 Sticky: newestPost,allInfo
 page:
 noSticky: about
 Sticky: newestPost,allInfo

组件名称使用逗号分隔。文章存在 Markdown 标题并且没有设置 toc: false 时，目录会自动插入吸顶区域，不需要把 toc 写进组件列表。

用数据文件构建特色页面

solitude@example.org (Solitude) — Sun, 23 Aug 2026 10:00:00 +0800

Solitude 的特色页面使用 Hugo 分支包与数据文件协作：_index.md 决定页面地址和类型，data/ 中的 YAML 保存可重复维护的内容。调整数据即可更新页面，无需复制模板。

创建页面入口

以装备页为例，创建 content/equipment/_index.md：

---
title: 我的装备
type: kit
data: kit
aliases:
 - /kit/
---

type 用于选择 Solitude 的专用模板；data 可以把默认的 data/kit.yaml 改成其他文件名。关于、友链和即刻短文分别使用 about、links 与 brevity 类型。

关于页的模块顺序

data/about.yaml 必须使用模块化的 sections 数组，列表顺序就是最终展示顺序：

title: 关于 Solitude
sections:
 - type: intro
 greeting: 你好，欢迎了解 Solitude
 name_prefix: 这是
 name: Solitude
 description: 一款专注内容体验的 Hugo 主题

 - type: values
 motto:
 label: 设计原则
 prefix: 内容优先
 content: 克制表达
 expertise:
 label: 主题能力
 prefix: 专注于
 specialist: 阅读体验
 content: 长期维护
 level: 原生

主题只接受已经定义的模块类型，未知类型会让构建明确失败。项目示例使用项目历程和技术能力，不使用个人履历作为默认数据。

Solitude Hugo Shortcode 使用指南

solitude@example.org (Solitude) — Sat, 22 Aug 2026 10:00:00 +0800

Shortcode 是 Hugo 在 Markdown 之外提供的内容组件语法。Solitude 用它承载提示框、标签页、图库、图表等富内容；迁移旧文章时，也应把 Hexo 外挂标签改写为对应的 Hugo shortcode。

开始之前

Hugo shortcode 有两种边界符：{{< shortcode >}} 适合普通参数，{{% shortcode %}} 会先处理内部 Markdown。Solitude 的块级组件已经按各自用途处理正文，通常直接使用尖括号写法即可。

内容类型	推荐组件	适合场景
行内强调	`span`、`label`、`keyboard`	一句话中的状态、术语或快捷键
块级提示	`note`、`subnote`、`fold`	说明、警告、补充资料
导航与引用	`button`、`link`、`card`	行动入口、站内外资源
结构化内容	`tabs`、`timeline`、`gallery`、`series`	分组、步骤、图片与文章集合
动态内容	`mermaid`、`chartjs`、`typeit`	流程、数据与动态文字

文本与状态

彩色文本与标签

p 用于整段文字，span 用于行内文字，label 用于短小的状态标记。颜色参数可使用 blue、green、orange、red、purple 等主题色名称。

从 Hexo 迁移到 Hugo：URL 与 Front Matter

solitude@example.org (Solitude) — Fri, 21 Aug 2026 10:00:00 +0800

从 Hexo 迁移到 Hugo 时，Markdown 正文通常可以直接复用，真正需要仔细处理的是 Front Matter、固定链接和旧地址。Solitude Hugo 保留常用文章参数，同时使用 Hugo 的原生字段表达更新日期和 URL 兼容关系。

Front Matter 字段映射

Hexo	Hugo	说明
`date`	`date`	文章发布日期
`updated`	`lastmod`	最后更新时间
`abbrlink`	`slug`	用原短链接值生成文章地址
`categories`	`categories`	进入 Hugo 分类 Taxonomy
`tags`	`tags`	进入 Hugo 标签 Taxonomy
`top`	`weight` 或自定义字段	根据站点排序策略决定

cover、description、comment、aside、toc、series 等 Solitude 参数可以继续放在文章 Front Matter 中。

保留 abbrlink 地址

示例站在 hugo.yaml 中使用：

uglyURLs:
 posts: true

permalinks:
 posts: /p/:slug

文章把原 Hexo abbrlink 复制到 slug：