2.2 Configuration

A note from the authors: Some of the information and instructions in this book are now out of date because of changes to Hugo and the blogdown package. If you have suggestions for improving this book, please file an issue in our GitHub repository. Thanks for your patience while we work to update the book, and please stay tuned for the revised version!

In the meantime, you can find an introduction to the changes and new features in the v1.0 release blog post and this "Up & running with blogdown in 2021" blog post.

— Yihui, Amber, & Alison

您可能想要查看的第一个文件是根目录中的配置或 config 文件，您可以在其中设置站点的全局配置。它可能包含网站的标题和描述等选项，以及其他全局选项，例如社交网络的链接、导航菜单和网站的基本 URL。

生成站点时，Hugo 将首先搜索名为 config.toml 的文件。如果找不到，它将继续搜索 config.yaml。³ 由于大多数 Hugo 主题都包含提供 config.toml 文件的示例站点，并且 TOML (Tom’s Obvious, Minimal Language) 格式似乎在 Hugo 社区中更流行，我们这里主要讨论 config.toml。

我们建议您仅在配置文件中使用 TOML 语法（如果您愿意，也可以使用 YAML），并使用 YAML 作为 (R) Markdown 页面和帖子的 metadata 的数据格式，因为 R Markdown 和 blogdown 完全支持仅限 YAML。⁴ 如果您的网站已经使用了 TOML，您可以使用 blogdown::hugo_convert(unsafe = TRUE) 将 TOML 数据转换为 YAML，但请首先确保您已备份该网站，因为它会覆盖您的网站 Markdown 文件。

Hugo 文档在其示例中没有一致地使用 TOML 或 YAML，这可能会令人困惑。将示例复制到您自己的网站时，请密切注意配置格式。

2.2.1 TOML Syntax

如果您不熟悉 TOML 语法，我们将提供简要概述，您可以阅读 full documentation 以了解详细信息。

TOML 由用等号分隔的键值对组成：

key = value

当您想要编辑 TOML 文件中的配置时，只需更改 value 即可。字符串 Values 应放在引号中，而布尔 values 应小写且不包含任何内容。

例如，如果您想为您的网站指定标题 “My Awesome Site”，并使用相对 URLs 而不是默认的绝对 URLs，则您的 config.toml 文件中可能包含以下条目。

title = "My Awesome Site"

relativeURLs = true

大多数网站的全局变量都是以这种方式输入到 config.toml 文件中的。

进一步深入您的 config 文件，您可能会注意到括号中的一些值，如下所示：

[social]
    github  = "https://github.com/rstudio/blogdown"
    twitter = "https://twitter.com/rstudio"

这是一个 TOML 语言的表格，Hugo 使用它们来填写站点内其他页面上的信息。例如，上表将填充站点模板中的 .Site.Social 变量（更多信息请参见 Section 2.5）。

最后，您可能会在双括号中找到一些值，如下所示：

[[menu.main]]
    name = "Blog"
    url = "/blog/"

[[menu.main]]
    name = "Categories"
    url = "/categories/"

[[menu.main]]
    name = "About"
    url = "/about/"

在 TOML 中，双括号用于指示表数组。Hugo 将此信息解释为菜单。如果在 config.toml 文件中找到上述代码，则生成的网站将在网站主菜单中包含指向博客、类别和关于页面的链接。该菜单的位置和样式在其他地方指定，但每个菜单选项的名称以及每个部分的链接都在此处定义。

每个主题的 config.toml 文件都不同。确保当你选择一个主题时，你彻底阅读了它的文档，以了解每个配置选项的作用（更多关于主题的信息，请参见 Section 2.4）。

2.2.2 Options

您可以为 Hugo 设置的所有内置选项在 https://gohugo.io/overview/configuration/ 列出。您可以更改除 contentDir 之外的任何选项，它是硬编码到 blogdown 中的内容。我们的一般建议是，除非您了解后果，否则最好不要修改默认值。我们列出了您可能感兴趣的一些选项：

baseURL: 通常您必须将此选项的值更改为您网站的基本 URL。某些 Hugo 主题可能在其示例站点中将其设置为 http://replace-this-with-your-hugo-site.com/ 或 http://www.example.com/，但请确保将其替换为您自己的 URL（有关发布网站和获取域名的更多信息，请参阅 Chapter 3 和 Appendix C）。请注意，如果您的网站要在域名的子路径下发布，则此选项可以是带有子路径的 URL，例如 http://www.example.com/docs/。
enableEmoji: 您可以将其设置为 true，以便您可以在 Markdown 中使用 :smile: 等 Emoji emoticons。
permalinks: 生成页面永久链接的规则。默认情况下，Hugo 使用 content/ 下的完整文件名来生成链接，例如，content/about.md 将呈现为 public/about/index.html，content/post/2015-07-23-foo.md 将呈现为 public/post/2015-07-23-foo/index.html，所以实际的链接是网站上的 /about/ 和 /post/2015-07-23-foo/。尽管不需要为永久链接设置自定义规则，但通常会看到 /YYYY/mm/dd/post-title/ 形式的链接。 Hugo 允许您使用有关源文件的多项信息来生成链接，例如日期（年月日）、标题和文件名等。链接可以独立于实际文件名。例如，您可以要求 Hugo 使用链接的日期和标题来呈现 content/post/ 下的页面：
```
[permalinks]
    post = "/:year/:month/:day/:title/"
```
就我个人而言，我建议您使用 :slug 变量⁵ 而不是 :title:
```
[permalinks]
    post = "/:year/:month/:day/:slug/"
```
这是因为你的帖子标题可能会发生变化，而你可能不希望帖子的链接发生变化，否则你必须将旧链接重定向到新链接，并且会出现像 Disqus 评论这样的其他类型的麻烦。如果帖子的 YAML metadata 中未设置名为 slug 的字段，则 :slug 变量会回退到 :title 。您可以设置固定的 slug，以便帖子的链接始终固定，并且您可以自由地更新帖子的标题。

您可以在 https://gohugo.io/extras/permalinks/ 找到可在 permalinks 选项中使用的所有可能变量的列表。
publishDir: 您要在其下生成网站的目录。
theme: themes/ 下 Hugo 主题的目录名。
ignoreFiles: Hugo 在构建网站时忽略某些文件的文件名模式（正则表达式）列表。我建议您至少指定这些模式 ["\\.Rmd$", "\\.Rmarkdown$", "_cache$"]。您应该忽略 .Rmd 文件，因为 Hugo 应该只识别它们的输出文件（例如 .html 或 .md 文件）。后缀为 _cache 的目录应该被忽略，因为它们包含 Rmd 文件编译后的辅助文件，这些文件对 Hugo 来说是无用的。
uglyURLs: 默认情况下，Hugo 生成 “clean” URLs。这可能有点令人惊讶，并且要求您了解浏览器从服务器获取页面时 URL 的工作原理。基本上，Hugo 默认为 foo.md 生成 foo/index.html 而不是 foo.html，因为前者允许您通过 clean URL foo/ 访问页面，而不需要 index.html。大多数网络服务器都能理解 http://www.example.com/foo/ 之类的请求，并将在 foo/ 下向您显示 index.html。如果您更喜欢从 *.md 到 *.html 的严格映射，您可以通过将 uglyURLs 设置为 true 来启用 “ugly” URLs。
hasCJKLanguage: 如果您的网站主要是 CJK（中文、韩文和日文），我建议您将此选项设置为 true，以便 Hugo 的自动摘要和字数统计效果更好。

除了内置的 Hugo 选项外，您还可以在 config.toml 中设置其他任意选项。例如，很常见的是名为 params 的选项，它广泛应用于许多 Hugo 主题中。当您在 Hugo 主题中看到变量 .Site.Params.FOO 时，它表示您在 config.toml 中的 [params] 下设置的选项 FOO，例如 .Site.Params.author 是 Frida Gomam，具有以下配置文件：

[params]
    author = "Frida Gomam"
    dateFormat = "2006/01/02"

所有这些选项的目标是避免对 Hugo 主题中的任何内容进行硬编码，以便用户可以轻松编辑单个配置文件以将主题应用到他们的网站，而不是浏览许多 HTML 文件并逐一进行更改。

Hugo 也支持 config.json，但 blogdown 不支持，所以我们不建议您使用它。↩︎
TOML 有它的优点，但我觉得它们在 Hugo 网站的背景下并不重要。当 YAML 代表 “另一种标记语言” 时，必须了解另一种语言 TOML 是一种痛苦。我不确定 XKCD 漫画是否适用于这种情况：https://xkcd.com/927/。↩︎
slug 只是一个字符串，可用于标识特定的帖子。即使标题改变，slug 也不会改变。例如，如果您决定将帖子的标题从 “I love blogdown” 更改为 “Why blogdown is the best package ever”，并且您在 URL 中使用了该帖子的标题，那么您的旧链接现在将被破坏。相反，如果您通过 slug（类似于 “blogdown-love”）指定 URL，那么您可以根据需要多次更改标题，并且不会出现任何损坏的链接。↩︎