Hugo

概述

Hugo 是一个非常流行的开源网站发布系统。Hugo网站中的页面通常使用纯Markdown编写，因此没有直接的方法可以自动且可重复地包含计算输出。

通过使用Quarto的hugo-md格式，您可以在Hugo网站中包含计算输出（例如生成图表的R或Python代码）。本文将详细解释如何实现这一点。

需要注意的是，当您将Quarto与Hugo结合使用时，许多与主题、页面布局和导航相关的Quarto功能并不适用。Hugo拥有自己的主题系统、语法高亮、目录、页面布局、导航菜单和全文搜索功能。您将使用Quarto来执行代码并生成Markdown，这些Markdown将在Hugo的HTML发布框架中渲染，而不是在Quarto自己的框架中。

站点配置

在使用 Quarto 与 Hugo 之前，您应该对 Hugo 的 config.toml 进行一些更改。首先，确保 .qmd、.ipynb 文件以及其他源代码或数据文件不会作为站点的一部分发布。例如：

ignoreFiles = [ "\\.qmd$", "\\.ipynb$", "\\.py$" ]

接下来，配置 Hugo 的 Markdown 渲染器以允许原始 HTML（因为许多 R 和 Python 包会使用原始 HTML 而不是 Markdown 生成计算输出）：

[markup.goldmark.renderer]
unsafe= true

创建页面

使用 Quarto 的 Hugo 文章和帖子应存放在它们自己的目录中（利用 Hugo 的页面捆绑功能）。这使得页面生成的任何内容（例如图表输出）都能与 Markdown 源文件一起存放。

要将 Quarto 文档添加到 Hugo 站点：

在 content 目录中创建一个目录，用于存放您的 Quarto 文章。
将一个 index.qmd 文档添加到该目录中。渲染后会生成一个 index.md，这将确保 Hugo 将其视为页面捆绑（自动将图像和其他引用的资源复制到发布目录）。
添加必要的 Hugo 前言，然后指定 format: hugo-md 以及任何其他需要的 Quarto 选项。

例如，假设我们想在 content 目录中创建一个名为 hello-quarto 的新文章。文件系统将如下所示：

mysite/
  content/
    hello-quarto/
      index.qmd

以下是 index.qmd 的源代码示例：

---
title: Hello, Quarto
date: "2012-04-06"
categories: 
  - Matplotlib
  - Coordinates
format: hugo-md
jupyter: python3
---

## 极坐标轴

有关极坐标轴上的线图演示，请参见 @fig-polar。

```{python}
#| label: fig-polar
#| fig-cap: "极坐标轴上的线图"

import numpy as np
import matplotlib.pyplot as plt

r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(subplot_kw={'projection': 'polar'})
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()
```

工作流程

使用 Quarto 与 Hugo 的基本概念是，您将计算标记文档（.qmd）或 Jupyter 笔记本（.ipynb）用于生成由 Hugo 渲染为 HTML 的纯标记文件（.md）。

index.qmd quarto => index.md hugo => index.html

quarto render 和 quarto preview 命令用于将 .qmd 或 .ipynb 文件转换为 Hugo 兼容的标记（.md）。计算文件位于您放置普通标记文件的同一位置（例如 blog 目录）。

渲染后，纯 .md 文件会与计算文档一起写入。然后，该标记文件由 Hugo 处理。

实时预览

quarto preview 命令会自动识别何时从包含 Hugo 网站的目录中运行：

Terminal

cd my-hugo-website
quarto preview

这将自动为您运行 hugo serve，以启动本地预览服务器。此外，它还会监视文件系统的变化，对 .qmd 和 .ipynb 输入进行更改，并在更改时自动重新渲染为 Hugo 兼容的 .md 文件。

请注意，这也适用于 Quarto VS Code 扩展中的集成渲染/预览命令。

渲染

如果您不进行预览并希望渲染站点中的所有 Quarto 文档（.qmd）和笔记本（.ipynb），请从站点的根目录调用 quarto render：

Terminal

cd my-hugo-website
quarto render

通常，在发布之前，您希望在站点级别进行 quarto render：

Terminal

quarto render && hugo

您还可以渲染单个文档或笔记本：

Terminal

quarto render blog/2022-07-26/hello-quarto/index.qmd

如果您有计算密集型文档，您可能希望考虑使用 Quarto 的 freeze 功能，只有在文档源代码更改时才重新执行代码。

请注意，如果您从未在项目级别进行渲染，而只是想用 Quarto 渲染单个文件，则应指定 hugo-md 格式，如下所示：

---
title: "我的博客文章"
format: hugo-md
---

配置

虽然 Quarto 在没有 _quarto.yml 项目配置文件的 Hugo 站点中工作良好，但您可以添加一个文件来定制默认行为、添加参考书目等。例如，一个简单的自定义 _quarto.yml 文件可能如下所示：

_quarto.yml

project:
  type: hugo
      
format: 
  hugo-md:
    code-fold: true
  
execute: 
  warning: false

bibliography: references.bib

重要的是要注意，如果您确实提供了显式的 _quarto.yml 文件，则需要如上所示明确指定项目类型（type: hugo）。

外部目录

您可能决定将所有 Quarto 文档和/或笔记本保存在与 Hugo 网站分开的自己的目录中。在此配置中，您将在 Quarto 目录中镜像站点的目录结构，然后在项目文件中将 output-dir 设置为指向 Hugo 目录。例如：

_quarto.yml

project:
  type: hugo
  output-dir: ../hugo-site

短代码

请注意，Hugo 短代码和 Quarto 短代码共享相同的基本语法（例如 {{< var foo >}}）。这通常不是问题，因为 Quarto 无法识别的短代码将保持不变地传递给 Hugo。

然而，在某些情况下，使用 Hugo 短代码会干扰 Pandoc 的 Markdown 处理，这时需要“保护”Hugo 短代码不被 Pandoc 处理。这通常可以通过用额外的花括号转义短代码来处理。例如：

{{{< ref "foo/index.md" >}}}

如果短代码的存在改变了 Pandoc 处理周围 Markdown 的方式（例如，目前已知链接会引发这种情况），那么可能需要在整个结构周围使用 Markdown 原始块。例如：

```{=markdown}
[click here]({{< ref "foo/index.md" >}})
```

或者对于内联内容，使用 Markdown 原始内联：

For more info, `[click here]({{< ref "foo/index.md" >}})`{=markdown}

WebTeX 数学

hugo 格式使用标准的美元符号分隔的行内 ( $...$ ) 和显示 ($$...$$) 语法来渲染 LaTeX 方程。然而，如果你发布的网页环境不支持美元符号分隔的数学表达式，你可以选择使用 WebTeX 来显示数学内容。这可以通过将 Pandoc 的 html-math-method 设置为 webtex 来实现。例如：

format:
  hugo:
    html-math-method: webtex

WebTeX适用于任何可以显示图像的网页，并且不需要特殊的JavaScript或CSS。文档中包含的任何行内或显示公式都将被转换为请求公式渲染版本的图像URL。例如，以下markdown：

$x + 1$

将被转换为：

![](https://latex.codecogs.com/svg.latex?x%20%2B%201)

渲染效果如下：

暗模式

SVG被用作默认的渲染方法，因为它在整体外观上表现最佳。然而，如果你的hugo文档在深色背景下渲染，你可能希望切换到指定深色背景的PNG格式。你可以按如下方式进行设置：

format:
   hugo:
     html-math-method: 
       method: webtex
       url: https://latex.codecogs.com/png.image?%5Cbg_black&space;