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

1.5 Global options

blogdown 包使用 .Rprofile 文件中指定的全局选项来帮助用户自定义 blogdown 的工作方式。当您创建新站点时，blogdown 会在您的网站项目的根目录中添加一个项目级 .Rprofile` 文件。

选项应使用语法 options(name = value) 进行设置，新 blogdown 站点的 .Rprofile 文件中包含的选项如 Table 1.1 所示。

TABLE 1.1: Global options for configured for new blogdown sites.
Option name Default Meaning
blogdown.hugo.version A valid Hugo version A Hugo version number
blogdown.knit.on_save TRUE Knit Rmd files automatically on save?
blogdown.method markdown The output format of .Rmd posts
blogdown.serve_site.startup FALSE Serve the site on RStudio startup?

其中三个选项值得进一步解释：

  • blogdown.hugo.version: 您可以在 https://github.com/gohugoio/hugo/releases/ 找到可用的 Hugo 版本，并通过 blogdown::find_hugo('all') 查找所有本地安装的 Hugo 版本。指定此选项时的一个常见错误是省略末尾的版本号 0。例如，仅 Hugo v0.55.0 存在，但不存在 v0.55，因此 options(blogdown.hugo.version = '0.55') 将不起作用，您必须将其精确设置为 0.55.0。

  • blogdown.knit.on_save: 默认情况下，Rmd 文件保存时会自动 knitted。如果您更喜欢单击 RStudio 中的 Knit 按钮来手动 knit 文件，可以将此选项设置为 FALSE。如果未设置此选项，当您单击 Knit 按钮时，blogdown 会将当前 R 会话设置为 TRUE（带有提醒消息）。

  • blogdown.method: 默认情况下，Rmd 帖子通过 rmarkdown 编译为 .md (Markdown)，该文件将由 Hugo 的 Markdown 渲染器（例如 Goldmark）渲染为 HTML。您可以将此选项设置为 "html" 以将 .md 预渲染为 .html 并绕过 Hugo 的 Markdown 渲染器。基本上，此选项决定您是否要使用 Pandoc 还是 Hugo 的 Markdown 渲染器将 Markdown 渲染为 HTML。有关详细信息，请参阅 Section @ref{method}。

我们建议您在 R 启动配置文件中设置这些选项。如果您以前从未使用过启动配置文件，您可以查看帮助页面 ?Rprofile。在这里，我们提供简短但不完整的介绍，以便您快速熟悉。

启动配置文件基本上是一个 R 脚本，在 R 会话启动时执行。这是设置全局选项的完美位置，因此您无需在每次启动新的 R 会话时再次键入这些选项。

在使用 R 的启动配置文件之前，您需要了解以下几点：

  1. 您可以使用一个全局配置文件 ~/.Rprofile,8 或 RStudio 项目根目录下的每个项目文件 .Rprofile。前者将应用于您启动的所有 R 会话，除非您提供了后者来覆盖它。

  2. 名称 “startup profile file” 意味着 R 仅在您首次启动 R 会话时执行此文件。这意味着当您修改并保存 .Rprofile 时，必须重新启动 R 才能使更改生效。

  3. R 将默默忽略 .Rprofile 的最后一行 如果它没有尾随换行符, 因此请确保在 .Rprofile 末尾添加至少一个换行符。

如果您想将配置文件添加到现有的 blogdown 项目，或者您在不使用 blogdown::new_site() 的情况下创建了新网站，则可以在 R 控制台中使用以下命令创建样板版本：

blogdown::config_Rprofile()

这是创建或修改每个项目配置文件的最简单方法。在新的 blogdown 网站项目的文件顶部，您将看到以下内容：

# REMEMBER to restart R after you modify and save this file!

# First, execute the global .Rprofile if it exists. You may
# configure blogdown options there, too, so they apply to any
# blogdown projects. Feel free to ignore this part if it sounds
# too complicated to you.
if (file.exists("~/.Rprofile")) {
  base::sys.source("~/.Rprofile", envir = environment())
}

首先，请注意顶部消息！下一部分代码是执行项目配置文件以及全局配置文件所必需的（如果存在）。R 只读取一个启动配置文件。例如，如果当前目录下有一个 .Rprofile 和一个全局 ~/.Rprofile，则当 R 从当前目录启动时，只会执行前一个。为您提供此代码，以便您可以执行全局和每个项目的配置文件。请注意，此代码只能存在于项目配置文件中，并且您不能将其添加到全局 ~/.Rprofile 中，否则它将触发无限递归。

在其下方，您将设置您的选项。这些可以堆叠在单独的行上，或者您可以使用逗号将多个选项一起列出：

# stacked options
options(blogdown.serve_site.startup = FALSE)
options(blogdown.knit.on_save = TRUE)

# comma-separated options
options(blogdown.serve_site.startup = FALSE,
        blogdown.knit.on_save = TRUE)

如何格式化您的配置文件取决于您—无论哪种方式都有效。样板配置文件中提供的 blogdown 选项只是可用选项的子集。根据您的个人喜好和您选择的主题，您可能希望在网站上工作时设置更多全局选项。例如：

TABLE 1.2: Additional global options that affect the behavior of blogdown.
Option name Default Meaning
blogdown.author The default author of new posts
blogdown.ext .md Default extension of new posts: .md / .Rmd / .Rmarkdown
blogdown.subdir post Default subdirectory under content/ for new posts
blogdown.yaml.empty TRUE Preserve empty fields in YAML?

假设您总是喜欢编写 .Rmd 帖子（而不是默认的 .md），并且希望新帖子的作者默认为 “John Doe”。您可以在配置文件中设置这些选项：

options(blogdown.ext = '.Rmd', blogdown.author = 'John Doe', blogdown.subdir = 'blog')

设置这些选项的一个很好的结果是，当您使用 RStudio 插件 “New Post” 时，“Author”、“Subdirectory” 和 “Format” 字段将自动填充，因此您无需每次都操作它们，除非你想改变默认值。

使用启动配置文件时的一个不便之处在于团队创作的博客，其中多个作者在同一个网站项目上进行协作。您无法在单个 .Rprofile 中使用 blogdown.author 选项设置特定于作者的选项，因为此选项对于不同的作者应该不同。一种解决方法是在项目 .Rprofile 中设置通用网站选项，然后允许每个作者在每个作者计算机上的全局 ~/.Rprofile 中设置自己的特定于作者的选项。如果您使用样板 blogdown::config_Rprofile()，顶部的第一块代码将确保全局 ~/.Rprofile 也被执行（如果存在）。

  1. 波形符 ~ 表示您系统中的主目录。↩︎