Vignette engines for Quarto

.Rbuildignore

@@ -6,3 +6,7 @@
 ^\.github$
 ^\.vscode$
 ^\.quarto$
+^doc$
+^Meta$
+
+^vignettes/*_files$

.github/workflows/R-CMD-check.yaml

@@ -50,21 +50,24 @@ jobs:
       - uses: quarto-dev/quarto-actions/setup@v2
         with:
           version: ${{ matrix.config.quarto || 'release' }}
+          tinytex: true
+
 
       # replace with setting up QUARTO Pandoc for rmarkdown
-      - uses: r-lib/actions/setup-pandoc@v2
+      - uses: r-lib/actions/setup-pandoc@v2.6.5
 
-      - uses: r-lib/actions/setup-r@v2
+      - uses: r-lib/actions/setup-r@v2.6.5
         with:
           r-version: ${{ matrix.config.r }}
           http-user-agent: ${{ matrix.config.http-user-agent }}
           use-public-rspm: true
 
-      - uses: r-lib/actions/setup-r-dependencies@v2
+      - uses: r-lib/actions/setup-r-dependencies@v2.6.5
         with:
-          extra-packages: any::rcmdcheck
+          # install the package itself as we register vignette engine
+          extra-packages: any::rcmdcheck, local::.
           needs: check
 
-      - uses: r-lib/actions/check-r-package@v2
+      - uses: r-lib/actions/check-r-package@v2.6.5
         with:
           upload-snapshots: true

.gitignore

@@ -7,3 +7,5 @@ inst/doc
 docs
 
 /.quarto/
+/doc/
+/Meta/

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: quarto
 Title: R Interface to 'Quarto' Markdown Publishing System
-Version: 1.3.11
+Version: 1.3.12
 Authors@R: c(
     person("JJ", "Allaire", , "jj@posit.co", role = "aut",
            comment = c(ORCID = "0000-0003-0174-9868")),
@@ -21,17 +21,18 @@ Imports:
     rlang,
     rmarkdown,
     rstudioapi,
+    tools,
     utils,
     yaml
 Suggests: 
     curl,
     knitr,
     rsconnect (>= 0.8.26),
-    testthat (>= 3.1.0),
+    testthat (>= 3.1.7),
     withr,
     xfun
 VignetteBuilder: 
-    knitr
+    quarto
 Config/testthat/edition: 3
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)

NAMESPACE

@@ -26,5 +26,6 @@ importFrom(rlang,is_interactive)
 importFrom(rmarkdown,relative_to)
 importFrom(rstudioapi,isAvailable)
 importFrom(rstudioapi,viewer)
+importFrom(tools,vignetteEngine)
 importFrom(utils,browseURL)
 importFrom(yaml,write_yaml)

NEWS.md

@@ -1,5 +1,7 @@
 # quarto (development version)
 
+- Add registration of vignette engine to use `quarto` as a vignette builder, and use `.qmd` file as vignette. See `vignette("hello", package = "quarto")`. (thanks, @dcnorris, #57).
+
 - Add `quarto_binary_sitrep()` to check possible difference in Quarto binary used by this package, and the one used by RStudio IDE (thanks, @jthomasmock, #12).
 
 - Add `quarto_create_project()` function that calls `quarto create project <type> <name>` (thanks, @maelle, #87).

R/quarto-package.R

@@ -4,5 +4,6 @@
 ## usethis namespace: start
 #' @import rlang
 #' @importFrom cli cli_inform
+#' @importFrom tools vignetteEngine
 ## usethis namespace: end
 NULL

R/quarto.R

@@ -124,14 +124,16 @@ check_quarto_version <- function(ver, what, url) {
 #' @export
 quarto_binary_sitrep <- function(verbose = TRUE, debug = FALSE) {
 
-  quarto_found <- normalizePath(quarto_path(), mustWork = FALSE)
+  quarto_found <- quarto_path()
   if (is.null(quarto_found)) {
     if (verbose) {
       cli::cli_alert_danger(quarto_not_found_msg)
     }
     return(FALSE)
   }
 
+  quarto_found <- normalizePath(quarto_found, mustWork = FALSE)
+
   same_config <- TRUE
   if (debug) verbose <- TRUE
 

R/render.R

@@ -34,7 +34,7 @@
 #'   This will be merged over `metadata-file` options if both are
 #'   specified.
 #' @param metadata_file A yaml file passed to `--metadata-file` CLI flags to
-#'   overrite metadata. This will be merged with `metadata` if both are
+#'   override metadata. This will be merged with `metadata` if both are
 #'   specified, with low precedence on `metadata` options.
 #' @param debug Leave intermediate files in place after render.
 #' @param quiet Suppress warning and other messages.

R/utils-vignettes.R

@@ -0,0 +1,47 @@
+register_vignette_engines <- function(pkg) {
+  vig_engine("html", quarto_format = "html")
+  vig_engine("pdf", quarto_format = "pdf")
+  vig_engine("format", quarto_format = NULL)
+}
+
+
+vig_engine <- function(..., quarto_format) {
+  rmd_eng <- tools::vignetteEngine('rmarkdown', package = 'knitr')
+  tools::vignetteEngine(
+    ...,
+    weave = vweave_quarto(quarto_format),
+    tangle = rmd_eng$tangle,
+    pattern = "[.]qmd$",
+    package = "quarto",
+    aspell = rmd_eng$aspell
+  )
+}
+
+vweave_quarto <- function(format) {
+  meta <- get_meta(format)
+  function(file, driver, syntax, encoding, quiet = FALSE, ...) {
+    quarto_render(file, ..., output_format = format, metadata = meta)
+  }
+}
+
+get_meta <- function(format) {
+  if (is.null(format)) return(NULL)
+  if (format == "html") {
+    return(get_meta_for_html())
+  }
+}
+
+get_meta_for_html <- function() {
+
+  css <- system.file("rmarkdown", "template", "quarto_vignette", "resources",
+                      "vignette.css", package = "quarto")
+  meta <- list()
+  meta$format$html <-
+    list(
+      `embed-resources` = TRUE,
+      minimal = TRUE,
+      theme = "none",
+      css = css
+    )
+  meta
+}

R/utils.R

@@ -1,5 +1,4 @@
 
-
 relative_to_wd <- function(path) {
   relative_to(getwd(), path)
 }

R/zzz.R

@@ -0,0 +1,4 @@
+# Register engines to support Quarto vignettes
+.onLoad <- function(lib, pkg) {
+  register_vignette_engines(pkg)
+}

inst/rmarkdown/template/quarto_vignette/resources/vignette.css

@@ -0,0 +1,158 @@
+body {
+  background-color: #fff;
+  margin: 1em auto;
+  max-width: 700px;
+  overflow: visible;
+  padding-left: 2em;
+  padding-right: 2em;
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-size: 14px;
+  line-height: 1.35;
+}
+
+
+
+table {
+  margin: 1em auto;
+  border-width: 1px;
+  border-color: #DDDDDD;
+  border-style: outset;
+  border-collapse: collapse;
+}
+table th {
+  border-width: 2px;
+  padding: 5px;
+  border-style: inset;
+}
+table td {
+  border-width: 1px;
+  border-style: inset;
+  line-height: 18px;
+  padding: 5px 5px;
+}
+table, table th, table td {
+  border-left-style: none;
+  border-right-style: none;
+}
+table thead, table tr.even {
+  background-color: #f7f7f7;
+}
+
+p {
+  margin: 0.5em 0;
+}
+
+blockquote {
+  background-color: #f6f6f6;
+  padding: 0.25em 0.75em;
+}
+
+hr {
+  border-style: solid;
+  border: none;
+  border-top: 1px solid #777;
+  margin: 28px 0;
+}
+
+dl {
+  margin-left: 0;
+}
+dl dd {
+  margin-bottom: 13px;
+  margin-left: 13px;
+}
+dl dt {
+  font-weight: bold;
+}
+
+ul {
+  margin-top: 0;
+}
+ul li {
+  list-style: circle outside;
+}
+ul ul {
+  margin-bottom: 0;
+}
+
+pre, code {
+  background-color: #f7f7f7;
+  border-radius: 3px;
+  color: #333;
+  white-space: pre-wrap;    /* Wrap long lines */
+}
+pre {
+  border-radius: 3px;
+  margin: 5px 0px 10px 0px;
+  padding: 10px;
+}
+pre:not([class]) {
+  background-color: #f7f7f7;
+}
+
+code {
+  font-family: Consolas, Monaco, 'Courier New', monospace;
+  font-size: 85%;
+}
+p > code, li > code {
+  padding: 2px 0px;
+}
+
+div.figure {
+  text-align: center;
+}
+img {
+  background-color: #FFFFFF;
+  padding: 2px;
+  border: 1px solid #DDDDDD;
+  border-radius: 3px;
+  border: 1px solid #CCCCCC;
+  margin: 0 5px;
+}
+
+h1 {
+  margin-top: 0;
+  font-size: 35px;
+  line-height: 40px;
+}
+
+h2 {
+  border-bottom: 4px solid #f7f7f7;
+  padding-top: 10px;
+  padding-bottom: 2px;
+  font-size: 145%;
+}
+
+h3 {
+  border-bottom: 2px solid #f7f7f7;
+  padding-top: 10px;
+  font-size: 120%;
+}
+
+h4 {
+  border-bottom: 1px solid #f7f7f7;
+  margin-left: 8px;
+  font-size: 105%;
+}
+
+h5, h6 {
+  border-bottom: 1px solid #ccc;
+  font-size: 105%;
+}
+
+a {
+  color: #0033dd;
+  text-decoration: none;
+}
+a:hover {
+  color: #6666ff; }
+a:visited {
+  color: #800080; }
+a:visited:hover {
+  color: #BB00BB; }
+a[href^="http:"] {
+  text-decoration: underline; }
+a[href^="https:"] {
+  text-decoration: underline; }
+
+

tests/testthat/_snaps/quarto.md

@@ -77,3 +77,12 @@
     Output
       [1] TRUE
 
+---
+
+    Code
+      quarto_binary_sitrep(debug = TRUE)
+    Message
+      x Quarto command-line tools path not found! Please make sure you have installed and added Quarto to your PATH or set the QUARTO_PATH environment variable.
+    Output
+      [1] FALSE
+

tests/testthat/test-quarto.R

@@ -65,4 +65,12 @@ test_that("quarto CLI sitrep", {
       transform = transform_quarto_cli_in_output(full_path = TRUE, normalize_path = TRUE)
     )
   )
+
+  # Mock no quarto found
+  with_mocked_bindings(
+    quarto_path = function(...) NULL,
+    expect_snapshot(
+      quarto_binary_sitrep(debug = TRUE)
+    )
+  )
 })

vignettes/.gitignore

@@ -1,2 +1,3 @@
 *.html
 *.R
+*_files

vignettes/.install_extras

@@ -0,0 +1 @@
+include