GitHub (GFM)

概述

虽然Markdown是Quarto的输入格式，但在某些情况下它也可以作为输出格式（例如，如果你有一个接受Markdown输入的网站或CMS，并且希望整合来自Python或R的计算）。

本文介绍如何使用Quarto生成GitHub Flavored Markdown (GFM)。你可能想要这样做是为了：

  • 从Jupyter笔记本生成GitHub的README.md

  • 创建包含计算的GitHub wiki页面（例如图表输出）。

GFM格式

使用gfm格式从Quarto创建GitHub Flavored Markdown。例如：

---
title: "我的项目"
format: gfm
---

有关GFM输出的所有可用选项的完整列表，请参见GFM 格式参考。

要使用Quarto创建README.md，请从一个以README为文件名前缀的笔记本（.ipynb）或计算性Markdown文件（.qmd）开始，例如：

README.qmd
---
title: "我的项目"
format: gfm
jupyter: python3
---

这是一个从Python动态生成内容的GitHub README：
    
```{python}
1 + 1
```

使用以下命令渲染README：

终端
quarto render README.qmd

这将在输入文件旁边创建README.md。

预览模式

当你使用quarto preview预览GitHub Flavored Markdown文档时，默认会显示一个近似GitHub上渲染的Markdown样式的HTML预览。如果你更喜欢查看生成的原始Markdown，可以使用preview-mode: raw选项。例如：

---
title: "我的项目"
format: 
  gfm:
    preview-mode: raw
---

WebTeX 数学

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

format:
  gfm:
    html-math-method: webtex

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

$x + 1$

将被转换为：

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

渲染效果如下：

暗模式

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

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

GitHub Wiki

如果你想使用Quarto将计算整合到GitHub wiki中，首先克隆wiki以便本地编辑。

然后，只需为wiki中的每一页创建一个计算性Markdown文件（.ipynb, .qmd）。你可以使用Quarto项目一次性将所有这些文件渲染成相应的.md文件。例如：

终端
quarto render

即使没有Quarto项目文件，你也不需要严格这样做，因为默认情况下，如果没有任何项目文件，quarto render将渲染目录中的所有输入文件。