Docusaurus

概述

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

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

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

工作流程

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

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

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

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

实时预览

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

Terminal

cd my-docusaurus-website
quarto preview

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

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

渲染

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

Terminal

cd my-docusaurus-website
quarto render 

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

Terminal

quarto render && npm run build

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

Terminal

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

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

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

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

配置

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

_quarto.yml

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

bibliography: references.bib

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

外部目录

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

_quarto.yml

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

代码块

Docusaurus中的代码块与Quarto非常相似。需要记住的一个重要事项是，语法高亮主题来自Docusaurus而非Quarto。有关更多详细信息，请参阅主题文档。

如果你在Quarto中使用filename属性，它将自动成为Docusaurus代码块的title：

```{.python filename="hello.py"}
1 + 1
```

代码折叠也会自动应用。因此，例如以下可执行代码块：

```{python}
#| code-fold: true
1 + 1
```

在Docusaurus中呈现为一个可折叠的块：

标注与标签集

与Quarto类似，Docusaurus支持标注和标签集。当在文档中包含这些组件时，应使用Quarto标准Markdown语法，该语法将自动转换为适当的Docusaurus结构。

例如，这是一个Quarto标注：

::: {.callout-important}
注意这里使用了Quarto标注语法。
:::

在Docusaurus中呈现为：

这是一个Quarto标签集：

::: {.panel-tabset group="fruits"}

## 苹果
这是一个苹果 🍎

## 橙子
这是一个橙子 🍊

## 香蕉
这是一个香蕉 🍌

:::

在Docusaurus中呈现为：

HTML 和 MDX

Docusaurus网站使用一种Markdown风格（MDX），与Pandoc（Quarto的原生Markdown渲染器）有一些重大差异，其中最大的差异是虽然Quarto允许嵌入HTML，但MDX不允许。相反，MDX允许直接嵌入JavaScript代码和React JSX组件（看起来像HTML，但在行为上有一些显著差异）。

Quarto对Docusaurus的支持考虑到了这些差异，并使你能够在需要时嵌入原始HTML以及使用MDX组件和JavaScript。

HTML 块

Docusaurus网站不允许任意HTML内容。相反，使用JSX来发出HTML标签。虽然这些JSX标签大多数时候看起来和作用像HTML标签，但有一些重要的注意事项和约束，最值得注意的是class属性必须写成className，并且style属性需要指定为JavaScript对象而不是CSS字符串。

如果你需要包含不符合JSX的原始HTML，应使用原始的```{=html}代码块。例如：

```{=html}
<p style="color: green;">段落</p>
```

如果你需要嵌入HTML代码（例如徽章、视频或推文），你应该确实使用如上所示的原始HTML块，以避免JSX遇到无法解析的标签时发生的错误。

请注意，由计算生成的HTML（例如在笔记本中显示的Pandas数据框）通常使用带有class和/或style标签的原始HTML。这种计算输出会自动包含在原始的```{=html}代码块中，以便在Docusaurus中正确渲染。

MDX 块

你还可以在针对Docusaurus的Quarto文档中使用MDX组件和JavaScript。为此，将它们包含在```{=mdx}原始代码块中。例如：

```{=mdx}
export const Highlight = ({children, color}) => (
  <span
    style={{
      backgroundColor: color,
      borderRadius: '2px',
      color: '#fff',
      padding: '0.2rem',
    }}>
    {children}
  </span>
);

<Highlight color="#25c2a0">Docusaurus GREEN</Highlight> 和 <Highlight color="#1877F2">Rams blue</Highlight> 是我最喜欢的颜色。

我可以在我的 _JSX_ 旁边写 **Markdown**!
```

呈现如下：

请注意，普通Markdown内容也可以与JavaScript和React组件一起包含在mdx块中。

LaTeX 数学

默认情况下，Quarto在Docusaurus项目中使用WebTeX渲染LaTeX数学，这是一个服务，根据输入的TeX表达式为网页发布创建PNG图像。

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

$x + 1$

将被转换为：

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

渲染效果如下：

暗模式

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

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

KaTeX

可以配置Docusaurus使用KaTeX进行数学渲染。有关此选项的更多信息，请参阅Docusaurus文档中的使用KaTeX。

确认KaTeX在你的网站中正确渲染方程后，你应该更新_quarto.yml文件，指定应使用katex而非webtex来渲染方程：

_quarto.yml

format:
  docusaurus-md:
    html-math-method: katex