r - 从 md 文件而不是 Rmd 创建小插图

Question

有没有一种方法可以从 Markdown (.md) 文件而不是 Rmarkdown (.Rmd) 或任何其他类型的文件创建一个包 vignette？

我找到了 this other question但它是关于从 .Rmd 输入生成/保留 .md 输出，而我想从 .md 输入开始。

Answer 1

问题

问题是要使用非 Sweave 插图，您必须有一个插图引擎。作为section 1.4.2 of the Writing R Extensions manual解释

Vignettes in formats other than Sweave are supported via “vignette engines”....

R recognizes non-Sweave vignettes using filename extensions specified by the engine. For example, the knitr package supports the extension .Rmd (standing for “R markdown”). The user indicates the vignette engine within the vignette source using a \VignetteEngine line, for example

%\VignetteEngine{knitr::knitr}

This specifies the name of a package and an engine to use in place of Sweave in processing the vignette. As Sweave is the only engine supplied with the R distribution, the package providing any other engine must be specified in the ‘VignetteBuilder’ field of the package DESCRIPTION file, and also specified in the ‘Suggests’, ‘Imports’ or ‘Depends’ field (since its namespace must be available to build or check your package).

...

Package writers who would like to supply vignette engines need to register those engines in the package .onLoad function. For example, that function could make the call

tools::vignetteEngine("knitr", weave = vweave, tangle = vtangle, pattern = "[.]Rmd$", package = "knitr")

不幸的是，knitr 的小插图引擎(发现 here )均未使用将拾取纯 md 文档的模式。

R.rsp 提供了一个 markdown 插图引擎(参见 here 和 here ):

vignetteEngine("md", package=pkgname,
    pattern="[.]md$",
    weave=rspWeave,
    tangle=function(file, ..., pattern="[.]md$") asisTangle(file, ..., pattern=pattern)
)

它允许您将 R.rsp::md 指定为小插图引擎并使用 markdown 小插图。但是，正如评论中所讨论的，似乎没有办法允许自定义 CSS 样式表更改默认格式。

解决方案

所以，我在一个名为 mdVignettes 的 R 包中制作了我自己的 markdown vignette 引擎可用 at this GitHub repo .

要使用它，只需添加

Suggests: mdVignettes
VignetteBuilder: mdVignettes

到您的 DESCRIPTION 文件。然后，创建一个包含

%\VignetteEngine{mdVignettes::md}

您可以使用

包含自定义 CSS 样式表

output:
    html_document:
        css: custom.css

代替

output: html_document

在 YAML frontmatter 中(将 custom.css 替换为样式表的文件名)。

例如，我通过以下方式创建了一个虚拟 R 包

devtools::create("vigex", rstudio = FALSE)

然后我将上面的 Suggests 和 VignetteBuilder 行添加到描述中，创建了一个 vignettes/ 目录，并在 vigex.md 中添加了以下内容:

---
title: "A Simple Vignette"
author: "duckmayr"
output:
    html_document:
        css: custom.css
vignette: >
  %\VignetteIndexEntry{vigex}
  %\VignetteEngine{mdVignettes::md}
  %\VignetteEncoding{UTF-8}
---

# A simple vignette

Here's an example of custom-formatted code:

    print("Hello, world!")

以及 vignettes/custom.css 中的以下内容:

code {
    background: wheat;
    color: green;
}

然后我通过

安装了带有小插图的包

devtools::install("vigex", build_vignettes = TRUE)

vignette("vigex") 显示以下内容:

另一种解决方案:使用 R.rsp

首先，添加

Suggests: R.rsp
VignetteBuilder: R.rsp

到您的 DESCRIPTION 文件。然后，创建一个包含

%\VignetteEngine{R.rsp::md}

就这么简单。我这样做是使用

package.skeleton("vignetteEX")

在 R 中，添加上面的 DESCRIPTION 行，然后将以下内容保存在 vignettes/vignetteEX.md 中:

---
title: "Vignette Example"
author: "duckmayr"
date: "October 26, 2018"
output: html_document
vignette: >
  %\VignetteIndexEntry{vignetteEX}
  %\VignetteEngine{R.rsp::md}
  %\VignetteEncoding{UTF-8}
---

# A simple vignette

Here it is.

然后我构建并安装了包(通过R CMD build 和R CMD INSTALL)并且能够通过

打开小插图

vignette("vignetteEX")