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

Question

有没有办法从 Markdown (.md) 文件创建包插图，而不是 Rmarkdown (.Rmd) 或任何其他类型？

我找到了，但它是关于 .Rmd 输入的 generating/keeping .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 的插图引擎中的 none（发现 here）使用的模式将拾取纯 md 文档。

R.rsp 提供降价插图引擎（参见 here and 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 包中制作了我自己的降价插图引擎可用 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;
}

然后我通过

安装了带有 vignette 的包

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")

Answer 2

一个更简单的解决方案是将原始 markdown 包含在 Rmarkdown 存根中。

your.md 包含：

# R Markdown

lorem ipsum

那么vignette.Rmd包含：

---
title: "Vignette Title"
author: "Vignette Author"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette:
vignette: >
  %\VignetteIndexEntry{Vignette Title}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r child = "your.md"}
```

这样，您就可以用纯 markdown 编写，只需使用 Rmd 存根即可构建小插图。那是你想要的吗？

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

Creating vignette from md file, not Rmd

markdown

r

r-markdown

r-package

问题

一个解决方案

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