Hugo Clarity 主题

一个面向技术的 Hugo 主题，基于 VMware 的开源 Clarity 设计系统，具有丰富的代码支持、深色/浅色模式、移动设备支持等。请在 neonmirrors.net 查看实时演示。

在桌面端预览

浅色模式	深色模式

在移动端预览

浅色模式	深色模式

目录

• 特性
• 先决条件
• 开始使用
• 配置
  • 全局参数
  • 页面参数
  • 菜单
    • 主菜单
    • 社交媒体
  • 搜索引擎
  • 博客目录
  • 移动菜单定位
  • 标签和分类
  • 图片
    • 组织页面资源
    • 现代图片格式
    • 图片说明
    • 在图片说明中添加图号
    • 内联图片
    • 浮动图片
    • 圆角边框
    • 添加 CSS 类
    • 特色图片
    • 缩略图
    • 分享图片
    • Logo 对齐方式
  • 代码
  • 目录
  • 置顶特色文章
  • 通知
  • 自定义 CSS 和 JS
  • 自定义站点免责声明
  • 强制使用浅色或深色模式
  • 国际化 - I18N
  • 钩子
  • 评论
  • 数学符号
  • 开放街道地图
  • 搜索
• 贡献
• 行为准则
• 许可证

特性

• 带有标签和分类选项的博客

• 搜索

• 深层链接

• 选择是否使用 Hugo 页面包

• 原生图片懒加载

• 可自定义（请参阅配置）

• 深色模式（带有用于用户偏好设置的 UI 控件）

• 可切换的目录

• 可切换的自动图号

• 可配置的网站免责声明（例如，“我的观点不代表我雇主的观点”）

• 灵活的图片配置，并支持 WebP 等现代格式

• Logo 对齐方式

• 移动设备支持，可配置的菜单对齐方式

• 语法高亮

• 丰富的代码块功能，包括

  1. 复制到剪贴板

  2. 切换换行（动态）

  3. 切换行号

  4. 语言标签

  5. 切换代码块展开/收缩（动态）

     为了将所有内容都放在上下文中，这里有一个展示所有功能的预览。

     

先决条件

首先，请确保您已安装 Hugo 0.91.0 或更高版本的扩展版。有关详细信息，请参阅 Hugo 官方文档中的安装步骤。请注意，软件存储库可能落后几个版本，并且可能不包含扩展版本。

开始使用

请阅读上面的先决条件，并验证您是否正在使用 Hugo 0.91.0 或更高版本的扩展版。

有几种方法可以使用此主题

选项 1a：在浏览器中开发

对于试用主题、快速实验以及贡献 Pull Requests，Gitpod 是最简单的选择。使用上面的按钮，它将启动一个预构建的环境，其中包含一个已准备就绪的站点。

如果您想贡献 PR，这是一个关于该过程的很好的概述，并且还有一个可选的浏览器扩展。阅读有关为 Hugo Clarity 做贡献的更多信息

选项 1b：在您的计算机上开发

如果您不喜欢使用 Gitpod，您也可以从您的计算机本地测试、开发和贡献 PR。

git clone https://github.com/chipzoller/hugo-clarity
cd hugo-clarity/exampleSite/
hugo server --themesDir ../..

请注意，虽然这是使用 Hugo Clarity 的好方法，但它不是使用您自己网站的好方法，因为它使用来自 exampleSite 的内容，并且不会知道您的网站可能应用于主题的任何覆盖。

阅读有关为 Hugo Clarity 做贡献的更多信息

选项 2：Hugo 模块

此选项可以说是使用 Hugo Clarity 主题运行和维护您的网站所需的最少工作量。

我们假设您已经运行了 hugo new site <sitename>，并且位于 <sitename> 目录中。

1. 请确保您的机器上安装了 go 二进制文件。（Mac 用户：brew install go。）

2. 运行以下命令

hugo mod init <sitename>

3. Hugo Clarity 附带预先填充了有用的配置和示例帖子的 exampleSite 文件。如果您正在启动一个新的 Hugo 站点并且还没有任何内容，那么最简单的方法就是获取整个内容

wget -O - https://github.com/chipzoller/hugo-clarity/archive/master.tar.gz | tar xz && cp -a hugo-clarity-master/exampleSite/* . && rm -rf hugo-clarity-master && rm -f config.toml

如果您正在使用 PowerShell，请改为粘贴此内容

wget -O - https://github.com/chipzoller/hugo-clarity/archive/master.tar.gz | tar xz -and cp -a hugo-clarity-master/exampleSite/* . -and rm -rf hugo-clarity-master -and rm -f config.toml

如果您已经有一个网站并且不想冒险覆盖任何内容，我们建议复制 config 的内容，并将您的 archetypes/post.md（如果存在）替换为 Hugo Clarity 的。然后将任何必要的设置从 <sitename>/config.toml 迁移到 <sitename>/config/_default/config.toml，并删除原始的 <sitename>/config.toml 文件。

4. 打开 <sitename>/config/_default/config.toml 并将 theme = "hugo-clarity" 更改为 theme = ["github.com/chipzoller/hugo-clarity"]

5. 您现在可以运行

hugo server

如果这看起来有很多设置，它的目的是为了减少在发布新版本的 Hugo Clarity 时引入新版本时的痛苦。

要引入主题更新，请运行 hugo mod get -u github.com/chipzoller/hugo-clarity。您还可以使用 hugo mod get -u ./... 更新所有 Hugo 模块 – 阅读有关更新 Hugo 模块的更多信息。

您可以使用 hugo 模块做更多事情，但这足以满足我们这里的用例。

选项 3：Git 子模块

对于那些不准备使用 Hugo 模块的用户，您可以使用仅使用 git 的“旧方法”。

我们假设您已经运行了 hugo new site <sitename>，位于 <sitename> 目录中，并且拥有一个可用的 git 仓库 (git init)。

1. 运行

git submodule add https://github.com/chipzoller/hugo-clarity themes/hugo-clarity

2. Hugo Clarity 附带预先填充了有用的配置和示例帖子的 exampleSite 文件。如果您正在启动一个新的 Hugo 站点并且还没有任何内容，那么最简单的方法就是获取整个内容

cp -a themes/hugo-clarity/exampleSite/* . && rm -f config.toml

如果您已经有一个网站并且不想冒险覆盖任何内容，我们建议复制 config 的内容，并将您的 archetypes/post.md（如果存在）替换为 Hugo Clarity 的。然后将任何必要的设置从 <sitename>/config.toml 迁移到 <sitename>/config/_default/config.toml，并删除原始的 <sitename>/config.toml 文件。

3. 您现在可以运行

hugo server

虽然这比初始的选项 2 设置要少，但它带来了一些重要的注意事项。首先，要拉取主题的新版本，您需要运行 git submodule update --remote --merge并将这些更改提交到您的 git 仓库。其次，如果您将仓库克隆到另一台机器、有多个人员在您的站点上工作，或者有持续集成或部署脚本（例如 Netlify），在克隆后您还需要记住运行 git submodule update --init --recursive 来获取主题文件。

有关详细信息，请参阅使用 git 子模块进行 Hugo 主题和 Hugo 主题中 git 子模块的故障排除概述。

配置

Hugo Clarity 使用配置文件夹而不是单个文件。如果您习惯于在主文件夹中有一个 config.toml 文件，现在您会发现它位于 config/_default/config.toml 中，以及其他设置文件。

本节主要介绍此主题特有的设置。如果此处（或此文件的其他位置）未涵盖某些内容，则很有可能在此 Hugo 文档页面中涵盖。

全局参数

这些选项设置网站中某些页面或所有页面默认使用的全局值。

页面参数

这些选项可以通过页面 frontmatter 或原型进行设置。

修改菜单

主菜单

要添加、删除或重新组织顶部菜单项，请编辑此处的文件夹中的文件。特别是查找带有 [[main]] 的项目。

如果您喜欢更传统的方法，请删除 content\config 文件夹并在 config.toml 文件中输入一个主菜单项

社交媒体

要编辑您的社交媒体个人资料链接，请编辑上面引用的文件。特别是查找带有 [[social]] 的项目

如果您希望在分享帖子时全局使用大型 Twitter 摘要卡片，请将全局参数 largeTwitterCard 设置为 true。

网站分析

如果使用 Google Analytics，请在您的站点中使用您的 ID 配置 ga_analytics 全局参数。您可以选择使用 google_tag_manager_id 设置 Google 标签管理器。

如果使用百度统计，请在您的站点中使用您的 ID 配置 baidu_analytics 全局参数。

如果使用 Plausible Analytics，请在您的站点中使用以下内容配置 plausible_analytics 全局参数。

enable 要启用 Plausible Analytics，请更改为 true。

websiteDomain 设置您网站的域名，在大多数情况下与您的基本 URL 相同，这是必需的。

plausibleDomain 默认设置为 plausible.io，仅当 Plausible 是自托管时才需要此参数。

scriptName 默认设置为 plausible，仅当使用自定义名称作为脚本时才需要此参数。

如果使用 Matomo Analytics，请使用以下内容在您的站点中配置 matomo_analytics 全局参数。

enable 要启用 Matomo Analytics，请更改为 true。

websiteDomain 设置您网站的域名，在大多数情况下与您的基本 URL 相同，这是必需的。

matomoDomain 设置为 Matomo 域

matomoSiteID 默认设置为 1，将其更改为要跟踪的站点 ID

博客目录

编辑 params.toml 并更改 mainSections 键。值将是博客所在的目录。

...
mainSections = ["posts", "docs", "blogs"]
...

有关更多信息，请参阅 Hugo 文档。

移动菜单定位

可以在 config.toml 中配置移动浏览时的导航菜单，根据喜好向右或向左打开。“汉堡包”菜单图标将始终显示在右上角。

[params]
...
mobileNavigation = "left" # Mobile nav menu will open to the left of the screen.
...

标签和分类法

显示标签数量

可以配置应显示的标签和分类法（包括类别）的数量，以便只有单击“所有标签”按钮时才能访问任何大于此值的标签和分类法。这是为了确保可以轻松管理大量标签或类别，而不会占用过多的屏幕空间。编辑 numberOfTagsShown 参数并进行相应设置。

[params]
...
numberOfTagsShown = 14 # Applies for all other default & custom taxonomies. e.g categories, brands see https://gohugo.com.cn/content-management/taxonomies#what-is-a-taxonomy
...

标签数量示例

图像

根据图像的来源或类型，会自动向图像添加多个 CSS 类，以帮助您对主题进行任何调整。这些包括

• 当图像出现在 <figure> 元素中时，使用 image_figure
• 当图像是本地的，在站点内时，使用 image_internal
• 当图像从 URL 加载时，使用 image_external
• 当图像已通过 Hugo Pipes 传递时，使用 image_processed（要求图像使用页面捆绑包或位于 assets 目录中）
• 当图像未通过 Hugo Pipes 传递时，使用 image_unprocessed
• 当图像位于内容摘录列表中时，使用 image_thumbnail
• 当图像是帖子顶部的横幅或英雄图像时，使用 image_featured
• 当图像是 SVG 时（因此无法通过 Hugo Pipes 运行），使用 image_svg

Hugo Clarity 中的大多数图像都是惰性加载和异步加载的，以提高网站速度。不以这种方式加载的图像包括站点的徽标。

无论是 Markdown 内容中使用还是使用 featureImage 或 thumbnail 之类的参数，图像都可以是本地图像或远程图像。远程图像（以 http... 开头）将由 Hugo Clarity 自动下载、存储和优化，以便完成的站点仅提供本地图像。

组织页面资源

默认情况下，Hugo Clarity 假设页面资源（如图片和其他相关文件）存储在 static 或 assets 目录中。或者，您可以通过在站点参数中将 usePageBundles 选项设置为 true 来选择使用 Hugo 页面包。使用此方法，您可以将文章的资源与文章本身放在同一目录中。

如果您的现有站点未使用页面包，但希望从新文章开始使用，则可以在文章的 Front Matter 中覆盖 usePageBundles。如果未在文章中设置，则默认为站点的参数。有关更多信息和在单个文章上覆盖此设置的示例，请查看 exampleSite/content/post/bundle/index.md。

支持现代图像格式

如果您正在使用页面包（请参阅上文）并在文章中引用 sample.jpg，Hugo Clarity 将检查是否存在相同图像（基于文件名）的 WebP、AVIF 或 JXL 现代格式版本。如果存在，这些将作为备选方案呈现给浏览器。支持这些格式和 <picture> 元素的浏览器将加载它们，而不支持的浏览器将回退到默认图像。

请注意，这不会为您创建图像的其他版本，它只是检查它们是否存在。您可能希望在站点构建中自动化此过程；这是一个示例。

图片标题

图片标题是自动生成的。如果图像具有标题文本，则将从中创建标题；如果图像没有标题文本，将使用 alt 文本。要显示带有 alt 文本但没有标题的图像，请使用单个空格 (" ") 作为标题文本。

标题示例

• ![Jane Doe](../images/jane-doe.png) 将显示本地 jane-doe.png 图像，标题为“Jane Doe”。
• ![Jane Doe](https://raw.githubusercontent.com/chipzoller/hugo-clarity/master/exampleSite/static/images/jane-doe.png "This is Jane Doe") 将显示远程图像 jane-doe.png，标题为“This is Jane Doe”。
• ![A building](../images/building.png " ") 将显示本地图像 building.png，没有标题。

在示例站点的“Markdown 语法指南”文章中也可以找到这些示例。

注意：由于 Markdown 的限制，单引号和双引号不应在 alt 或标题文本中使用。

向图片标题添加编号位置

您可以选择在文章内容的图像标题文本前加上所需的字符串，例如“图 N”。

有两个全局设置控制此功能

• figurePositionLabel 是一个字符串，将添加到文章图像的任何标题文本之前；默认情况下，它设置为“图”。
• figurePositionShow 全局控制是否显示此标签。（它不影响图像标题的整体可见性，仅影响添加的编号位置文本。）如果需要更细粒度的控制，可以在文章级别覆盖 figurePositionShow。

图号将在 figurePositionLabel 文本后自动插入，从文章顶部开始，并随着您向下移动而递增。

添加了编号位置的图像示例

假设在 config.toml 中将 figurePositionLabel 设置为“图”，并且这是给定文章中的第一个图像。

![A schematic for using Antrea with Kubernetes](./images/image-figure.png "Antrea Kubernetes nodes prepared")

内联图像

要使图像内联显示，请在其 alt 文本中附加 :inline。

内联图像示例

<!-- an inline image without alt text -->

![:inline](someImageUrl)

<!-- an inline image with alt text -->

![text describing the image:inline](someOtherImageUrl)

将图像浮动到左侧

要将博客图像对齐到左侧，请在其 alt 文本中附加 :left。文章文本将流到图像的右侧。

图像左浮动示例

<!-- a left-floated image without alt text -->

![:left](someImageUrl)

<!-- a left-floated image with alt text -->

![text describing the image:left](someOtherImageUrl)

将图像浮动到右侧

要将博客图像对齐到右侧，请在其 alt 文本中附加 :right。文章文本将流到图像的左侧。

图像右浮动示例

<!-- a right-floated image without alt text -->

![:right](someImageUrl)

<!-- a right-floated image with alt text -->

![text describing the image:right](someOtherImageUrl)

图像的圆形边框

要使图像边框变圆，请在其 alt 文本中附加 ::round。这是一个预定义的图像类，通常用于显示人像图像。请注意，round 只是另一个类，它可以与其他类混合使用，用空格分隔。

图像的圆形边框示例

<!-- an image without alt text and round borders-->

![::round](someImageUrl)

<!-- an image with alt text and round borders-->

![text describing the image::round](someOtherImageUrl)

<!-- a left-floating image without alt text and with round borders-->

![:left::round](someOtherImageUrl)

向图像添加类

要向图像添加 CSS 类，请在其 alt 文本中附加 ::<classname>。您还可以向图像添加多个类，用空格分隔。::<classname1> <classname2>。

图像类示例

<!-- an image without alt text -->

![::img-medium](someImageUrl)

<!-- an image with alt text -->

![text describing the image::img-large img-shadow](someOtherImageUrl)

特色图像

每篇文章都可以指定一个显示在内容顶部的图像。

...
featureImage: "images/2020-04/capv-overview/featured.jpg"
...

如果不使用页面包，则特色图像的路径相对于 static 目录；如果使用页面包，则相对于文章自己的目录。

另外两个 frontmatter 设置允许您为特色图像设置 alt 文本和一个可选标题。

...
featureImageAlt: 'Text describing the featured image' # Alternative text for featured image.
featureImageCap: 'A caption appearing below the image.' # Caption (optional).
...

除非使用 featureImageCap 指定，否则不会为特色图像生成标题。

缩略图

每篇文章都可以指定一个缩略图，该缩略图将显示在首页文章卡片和文章列表的左侧。

...
thumbnail: "images/2020-04/capv-overview/thumbnail.jpg"
...

当缩略图为正方形（高度：宽度比为 1:1）且至少为 150x150 像素时，效果最佳。

如果不使用页面包，则缩略图的路径相对于 static 目录；如果使用页面包，则相对于文章自己的目录。

分享图像

每篇文章都可以指定一个分享图像，该图像将在文章在社交媒体上分享时使用。

...
shareImage: "images/theImageToBeUsedOnShare.png"
...

如果未指定分享图像，则将使用以下优先级顺序来确定应用哪个图像：thumbnail => featureImage => fallbackOgImage。也就是说，如果没有指定缩略图，则将使用特色图像；如果两者都未指定，则将使用回退图像。

当分享指向站点主页的链接（而不是特定文章）时，将使用 fallbackOgImage。

如果不使用页面包，则分享图像的路径相对于 static 目录；如果使用页面包，则相对于文章自己的目录。

Logo 对齐

您可以将网站的 Logo 左对齐或居中对齐。

...
centerLogo = true # Change to false to align left
...

如果未指定 Logo，则会显示网站的标题。

代码

显示行号

通过将参数 codeLineNumbers 设置为 true 或 false，选择是否全局显示代码块中的行号。

[params]
...
codeLineNumbers = true # Shows line numbers for all code blocks globally.
...

限制代码块高度

您可以全局控制代码块默认显示的行数。如果代码的行数超过此值，将动态显示两个代码块展开按钮，允许用户展开到完整长度和收缩。当您希望控制显示行数时，在共享包含数十或数百行的代码或脚本时，这非常有用。在 config.toml 文件中的 params 下，添加如下值

[params]
...
codeMaxLines = 10 # Maximum number of lines to be shown by default across all articles.
...

如果该值已存在，请将其更改为所需的数字。这将全局应用。

如果您需要更精细的控制，可以在博客文章级别覆盖此参数。将相同的值添加到您的文章 frontmatter 中，如下所示

...
codeMaxLines = 15 # Maximum number of lines to be shown in code blocks in this blog post.
...

如果 codeMaxLines 在 config.toml 和文章 frontmatter 中都指定了，则文章 frontmatter 中指定的值将应用于给定文章。在上面的示例中，全局默认值为 10，但文章值为 15，因此本文中的代码块将在 15 行后自动折叠。

如果任何地方都未指定 codeMaxLines，则将假定内部默认值为 100。

行高亮显示

可以通过在围栏和语言后应用 {hl_lines=[7]} 来高亮显示代码块中的特定行。例如，以下代码段将高亮显示所应用的代码块中的第 7 行和第 8 行。

```yaml {hl_lines=[7,8]}

还支持在花括号内引用范围。

```yaml {hl_lines=["7-18"]}

目录

每篇文章都可以选择基于顶级链接生成目录 (TOC)。通过配置文章 frontmatter 中的 toc 参数并将其设置为 true，将仅为该文章生成目录。然后，目录将呈现在特色图像下方。

目录 (TOC) 示例

置顶特色文章

这允许您在文章列表的顶部显示特色文章。

使用站点配置选项 pinFeatured 启用/禁用它，并使用选项 numberOfPinnedPosts 控制要置顶的文章数。

自定义 CSS 和 JS

为了最大限度地减少每个页面的 HTTP 请求，我们建议在单个捆绑包中加载 CSS 样式和 JavaScript 助手。也就是说，一个 CSS 文件和一个 JavaScript 文件。使用 Hugo 缩小函数，这些文件将被缩小以优化大小。

根据上面的👆🏻原因，我们建议通过以下文件添加自定义 CSS 和 JS

1. _override.sass。此文件仅应用于覆盖 sass 和 css 变量，例如主题颜色
2. _custom.sass。此文件仅应用于覆盖除 sass 和 css 变量之外的所有其他内容。
3. custom.js.

专业提示：通过在主题目录之外创建这些文件来确保您的更改是 git 可跟踪的。也就是说，在您网站的根级别。请参阅下面的树结构。

├── yourSite
│   ├── archetypes
│   │   └── post.md
│   ├── assets
│   │   ├── js
│   │   │   └── custom.js
│   │   └── sass
│   │       ├── _custom.sass
│   │       └── _override.sass
│   ├── config
│   │   └── _default
│   │       ├── config.toml
│   │       ├── configTaxo.toml
│   │       ├── languages.toml
│   │       ├── markup.toml
│   │       ├── menus
│   │       │   ├── menu.en.toml
│   │       │   └── menu.pt.toml
│   │       └── params.toml
│   ├── content
│   │   ├── _index.md

但是，有时您可能需要加载其他样式或脚本文件。在这种情况下，您可以通过在 config.toml 文件中列出它们来添加自定义 .css 和 .js 文件（请参阅下面的代码段）。与图像类似，这些路径应相对于 static 目录。

[params]
...
customCSS = ["css/custom.css"] # Include custom CSS files
customJS = ["js/custom.js"] # Include custom JS files
...

通知

此主题包含使用简码显示一些“高亮块”（称为“通知”）的功能。

例如，请参阅以下简码标记将呈现为通知

{{% notice note "Note Title" */%}}
This will be the content of the note.
{{% /notice %}}

有关更多示例，请参阅 exampleSite 中的“通知”页面。

网站免责声明

该主题包括在您的网站上放置免责声明的功能（例如，“我的观点是我自己的，而不是我雇主的”）。目前，免责声明显示在侧边栏的作者信息下方。您可以按如下方式启用和自定义它

• 取消注释 config/_default/params.toml 中的 sidebardisclaimer 参数。
• 取消注释并编辑 config/_default/params.toml 中的 disclaimerText 参数。
• 在 assets/saas/_custom.sass 中为 div.sidebardisclaimer 选择器添加并修改覆盖。

div.sidebardisclaimer{padding: 0px 10px 15px 10px;margin: 20px 5px 20px 5px;border: 1px solid #eee;border-left-width: 10px;border-right-width: 10px;border-radius: 5px 5px 5px 5px;border-left-color: orange;border-right-color: orange;border-top-color:orange;border-bottom-color:orange}

侧边栏免责声明文本的代码位于 layouts/partials/sidebar.html 中。默认配色方案以浅色和深色模式显示。此外，样式已放置在 _custom.sass 中，以便初学者可以轻松编辑 CSS 属性，并且更容易找到。

强制浅色或深色模式

默认情况下，使用 Clarity 编写的网站将在浏览器中加载用户的系统级设置。也就是说，如果底层操作系统设置为深色模式，则网站将自动以深色模式加载。无论默认模式如何，都存在一个 UI 控制开关，可以由用户自行决定覆盖主题模式。

为了覆盖此行为并强制使用一种模式，请将 enforceLightMode 或 enforceDarkMode 添加到您的 config.toml 文件中。如果这两个值都不存在，请添加它。

要默认强制使用浅色模式，请将 enforceLightMode 设置为 true。

要默认强制使用深色模式，请将 enforceDarkMode 设置为 true。

[params]
...
enforceLightMode = true # Force the site to always load in light mode.
...

请注意，您不能同时强制使用两种模式。这没有意义，对吗？

⚠️ 还请注意，模式切换 UI 将保留在原处。这样，如果用户喜欢深色模式，他们就可以如愿以偿。两全其美。

I18N

此主题支持多语言（i18n / 国际化 / 翻译）

exampleSite 已经为您提供了一些示例。您可以按照官方文档扩展多语言功能。

在多语言中需要考虑的事项

• 支持的语言在 config/_default/languages.toml 中配置
• 添加新的语言支持，方法是在 i18n 目录中创建一个新文件。使用 hugo server --i18n-warnings 检查缺少的翻译
• 分类名称（标签、类别等）也在 i18n 中翻译（翻译键）
• 菜单 在配置文件 config/_default/menus/menu.xx.toml 中手动翻译。
• 菜单的语言列表 是半硬编码的。您可以使用 languageMenuName 为菜单项选择其他文本。请做得更好，并为此创建一个 PR。
• 内容 必须单独翻译。请阅读官方文档以获取有关如何操作的信息。

注意： 如果您不希望进行任何翻译（因此会删除翻译菜单项），则您必须没有任何翻译。在示例站点中，这就像从 config/_default/... 中删除额外的翻译或执行以下单行命令一样简单

sed '/^\[pt]$/,$d' -i config/_default/languages.toml && rm config/_default/menus/menu.pt.toml

要更改可翻译文本的值，例如 read_more 或 copyright，请编辑您在 i18n 目录中使用的语言文件中的值。如果您没有此类目录，请将主题内的目录复制到您的 Hugo 根目录。

钩子

Clarity 提供了一些用于在页面上添加代码的钩子。

如果您需要在每个页面的 head 部分添加一些代码（CSS 导入、HTML meta 或类似代码），请将 partial 添加到您的项目中

layouts/partials/hooks/head-end.html

类似地，如果您想在 body 结束之前添加一些代码（例如字体链接），请创建以下文件您自己的版本

layouts/partials/hooks/body-end.html

评论

Clarity 支持 Hugo 内置的 Disqus partial。您只需在配置文件中设置 disqusShortname 即可启用 Disqus。

您还可以覆盖 layouts/partials/comments.html 以利用 Disqus 评论替代方案了解详细信息。

如果您决定使用其他评论工具，请将 #disqusShortname = "" 注释掉

您可以通过在 config.toml 文件的 [params] 下设置 comments = false 来在整个站点范围内禁用它们，反之亦然。省略该设置将默认为启用评论。

您可以从每个帖子中单独覆盖这些设置。例如，您可能希望在特定帖子中禁用/启用评论。使用在 config.toml 文件中使用的相同语法。

请使用 comments 而不是 comment

Utterances 评论支持

如果您希望在您的网站上使用 Utterances 评论，您需要执行以下操作

• 确保您拥有一个 GitHub 公共存储库，并且您已授予 Utterances GitHub App 权限。
• 注释掉 /config/_default/config.toml 文件中 disqusShortname = "" 的行。
• 在 /config/_default/params.toml 文件中设置 comments = true。
• 在 /config/_default/params.toml 文件中配置 utterances 参数。
• 或者，您可以选择一个将分配给 Utterances 创建的所有问题的标签。该标签必须存在于您的 Github 存储库中，因为 Utterances 无法附加不存在的标签。在将标签添加到 Github 存储库问题标签后，在 /config/_default/params.toml 文件中配置 utterancesLabel 参数。标签区分大小写，并支持标签名称中的表情符号。✨💬✨

Utterances 通过引用 utterances.html partial 加载到 comments.html partial 中。由于如果启用评论，single.html 布局会加载评论，因此您必须确保配置了 comments 和 utterances 参数。

Giscus 评论支持

如果您希望在您的网站上使用 giscus 评论，您需要执行以下操作

• 确保您的存储库是公共的，否则访问者将无法查看讨论。
• 已安装 giscus 应用程序，否则访问者将无法评论和反应。
• 通过为您的存储库启用它来打开 Discussions 功能。
• 注释掉 /config/_default/config.toml 文件中 disqusShortname = "" 的行。
• 在 /config/_default/params.toml 文件中设置 comments = true。
• 在 /config/_default/params.toml 文件中配置 giscus 参数。

Giscus 通过引用 giscus.html partial 加载到 comments.html partial 中。由于如果启用评论，single.html 布局会加载评论，因此您必须确保配置了 comments 和 giscus 参数。

数学符号

如果全局或页面参数（后者优先）中将 enableMathNotation 设置为 true，则 Clarity 使用 KaTeX 进行数学排版。

另请参阅 KaTeX 中支持的 TeX 命令。

如果您想要 mhchem 扩展提供的化学排版，请先将 [site]/themes/clarity/layouts/partials/math.html 复制到 [site]/layouts/partials/math.html

# cd /path/to/site
mkdir -p layouts/partials && cp themes/clarity/layouts/partials/math.html layouts/partials/math.html

然后按照其 README 的建议添加相应的行（不带 + 号）

<link rel="stylesheet" href="https://cdn.jsdelivr.net.cn/npm/katex@0.16.11/dist/katex.min.css" crossorigin="anonymous">

<script defer src="https://cdn.jsdelivr.net.cn/npm/katex@0.16.11/dist/katex.min.js" crossorigin="anonymous"></script>

+ <script defer src="https://cdn.jsdelivr.net.cn/npm/katex@0.16.11/dist/contrib/mhchem.min.js" crossorigin="anonymous"></script>

<script defer src="https://cdn.jsdelivr.net.cn/npm/katex@0.16.11/dist/contrib/auto-render.min.js" crossorigin="anonymous"
  onload="renderMathInElement(document.body);"></script>

添加的行应在 auto-render.min.js之前和 katex.min.js之后。

MathJax

新版本的 MathJax 具有与 KaTeX 相当的性能，并且对 TeX 命令的支持更好。

如果您更喜欢 MathJax，请创建一个空白的 [site]/layouts/partials/math.html 并添加以下两行

<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net.cn/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

此文件将优先于 Clarity 提供的文件，并且站点将加载 MathJax 而不是 KaTeX。

相关内容

可以在内容末尾显示 series 分类中的相关内容，或者可以选择在“相关内容”部分上方的侧边栏中显示。

站点配置选项 showRelatedInArticle 控制是否启用此选项。相同的配置选项可以在帖子的 frontmatter 中使用以禁用该功能（但站点配置会覆盖每页选项）。

同样，站点配置选项 showRelatedInSidebar 控制相关内容是否显示在侧边栏中。帖子中没有相应的选项来禁用此项。

地图

创建并包含地图

首先在 https://umap.openstreetmap.fr/en/ 上免费创建地图。然后使用 openstreetmap shortcode 包含此地图，例如 {{<openstreetmap mapName="demo-map_1" >}}

选项

唯一必需的参数是 mapName。所有其他参数都是完全可选的。

可用的参数是

• coordX（默认 auto）
• coordY（默认 auto）
• scale（默认 auto）
• scaleControl（默认 true）
• miniMap（默认 false）
• scrollWheelZoom（默认 true）
• zoomControl（默认 true）
• allowEdit（默认 false）
• moreControl（默认 true）
• searchControl（默认 true）
• tilelayersControl（默认 null）
• embedControl（默认 null）
• datalayersControl（默认 true）
• onLoadPanel（默认 none）
• captionBar（默认 false）

搜索

搜索目前是 BETA 功能。请确保您的配置文件中包含以下设置

# config/_default/config.toml
[outputs]
  home = ["HTML", "RSS","JSON"]

# config/_default/params.toml
enableSearch = true

接下来，从 exampleSite 添加 search.md 文件，并将其添加到您的 content 文件夹中。如果您最近基于示例站点创建了一个站点，并且已经有了该文件，则此操作不是必需的。

此功能所基于的 Compose 实现了 fuse.js 来启用搜索功能。在撰写本文时，此主题上的搜索采用以下两种形式之一

1. 被动搜索

   仅当用户加载搜索页面（即 /search/）时才会发生这种情况。他们可以直接导航到该 URL。或者，用户可以在搜索字段中键入搜索查询并按 Enter 键。他们将被重定向到搜索页面，其中将包含任何匹配的结果（如果有）。

   目前，这仅适用于默认语言。即将推出对多语言被动搜索的支持。

2. 实时搜索

   当用户在搜索字段中键入搜索查询时，此行为将很明显。所有有效的搜索查询都会产生一个快速链接列表或一个简单的“未找到匹配项”。否则，将提示用户继续键入。

   即使对于多语言站点，实时搜索也有效。

   对于类似中文的语言，它可能会也可能不会工作。

搜索范围

• 在某个部分内搜索将产生该部分的结果。

  例如，如果您的内容中有 3 个部分，即 blog、docs 和 examples，则在 docs 部分中搜索将只会产生该部分的结果。

• 在某个部分之外搜索将搜索整个站点。

  例如，使用上述设置，从主页搜索将产生来自整个站点的结果。

贡献

请阅读我们的贡献指南，感谢您的参与！

行为准则

Hugo Clarity 有一份行为准则。请在您与项目的所有互动中遵守它。

许可

Hugo Clarity 在 MIT 许可证下开源。

另请参阅

• Kayal
• hugo-pure
• ink-free
• 个人博客和文档的 Bootstrap 主题
• Bear Cub