Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Vignette engines for Quarto #146

Merged
merged 30 commits into from
Jan 31, 2024
Merged
Changes from 1 commit
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
a1dbd20
Correctly handle null value
cderv Jan 30, 2024
17ae138
Vignette engines for Quarto (#57)
dcnorris Nov 3, 2023
2ff3300
Refactor a little
cderv Nov 3, 2023
0498b13
Refactor the vignette engine code
cderv Nov 3, 2023
d89a064
embed the resource for HTML vignettes
cderv Nov 3, 2023
ddc41d4
devtools::build_vignettes
cderv Nov 3, 2023
fe9374f
Add system_file from staticimports
cderv Nov 7, 2023
587183c
Set some meta for html vignette to enforce lightweight html for CRAN
cderv Nov 7, 2023
6c490d2
USe html vignette in the package
cderv Dec 22, 2023
007b953
typo
cderv Jan 30, 2024
54401e5
Same entry index as Title
cderv Jan 30, 2024
31c1eb9
Explain in demo vignette the HTML quarto engine
cderv Jan 30, 2024
c9c2c7a
Typo
cderv Jan 30, 2024
c88a0e3
Handle NULL in format
cderv Jan 30, 2024
00baa22
Add mention of quarto::pdf engine
cderv Jan 30, 2024
c2b5eec
Split HTML and PDF vignette
cderv Jan 30, 2024
37e8df1
Correct vignette format
cderv Jan 30, 2024
be0d20b
Update doc regarding maintainer change
cderv Jan 30, 2024
df248ac
install the package itself as we register vignette engine
cderv Jan 30, 2024
1990405
Add LaTeX install
cderv Jan 30, 2024
d3ca56e
Ignore intermediate directories that would be produced by a author mo…
cderv Jan 30, 2024
edf2f4c
Remove knitr as vignettebuilder dependency
cderv Jan 30, 2024
636324d
Use include to share doc
cderv Jan 30, 2024
3c58e07
Add toc to publishing
cderv Jan 30, 2024
d2b0ed9
Remove extra characters
cderv Jan 30, 2024
5c64a1d
Register a generic engine that will use whatever is defined in format…
cderv Jan 30, 2024
5e3c222
Remove usage of staticimport system_files
cderv Jan 31, 2024
0c6e443
Add NEWS bullet
cderv Jan 31, 2024
6ccc3b1
Go back to v2.6.7 for now as there is conflict in naming follwing update
cderv Jan 31, 2024
e6c7360
Bump version
cderv Jan 31, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Explain in demo vignette the HTML quarto engine
cderv committed Jan 30, 2024
commit 31c1eb93f17facdcec9006fd951d3b51dafc1a93
60 changes: 47 additions & 13 deletions vignettes/hello.qmd
Original file line number Diff line number Diff line change
@@ -11,26 +11,60 @@ vignette: >
%\VignetteEncoding{UTF-8}
---

## Hello Vignette World!
This is an example Quarto vignette, demonstrating how the **quarto** package can let you write R package vignettes with Quarto (<https://quarto.org>).

This is an example Quarto vignette, demonstrating how the **quarto** package can let you write package vignettes in Quarto.
## Vignette Engines

## Two Vignette Engines
The **quarto** R package registers vignette engines that can be used in `%\VignetteEngine{}` directives in vignette headers.

To learn more about how vignettes engine works, and how to write vignette engines, see the [Writing R Extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Non_002dSweave-vignettes) manual and the [R Packages (2e)](https://r-pkgs.org/vignettes.html) book.


### HTML

Add this to your YAML header

The **quarto** package registers 2 vignette engines, `quarto::pdf` and `quarto::html`. Either of these may be selected in a Quarto vignette's YAML header. For example, this vignette's header reads:
```yaml
vignette: >
%\VignetteIndexEntry{Vignette's Title}
%\VignetteEngine{quarto::html}
%\VignetteEncoding{UTF-8}
---
title: "Quarto Vignettes"
format:
pdf:
toc: false
```

This will build a HTML document using Quarto, suitable for using as vignette to publish on CRAN. Choice has been made to create a very minimal HTML vignette by default, and so it is built with the following changes based to Quarto's `format: html` defaults:

- The HTML file produced is standalone (i.e. [`embed-resources: true`](https://quarto.org/docs/output-formats/html-publishing.html#standalone-html))
- Bootstrap has been disabled (i.e. [`theme: none`](https://quarto.org/docs/output-formats/html-themes.html) and [`minimal: true`](https://quarto.org/docs/output-formats/html-basics.html#minimal-html))
- A custom CSS file is provided.

This is equivalent to

```yaml
format:
html:
theme: none
minimal: true
embed-resources: true
css: custom.css
```

All those configurations are set in way that they can't be override by YAML header in the vignette source file. Only new configuration can be set, e.g adding a Table Of Content:

````yaml
format:
html:
toc: true
vignette: >
%\VignetteIndexEntry{Vignettes}
%\VignetteEngine{quarto::pdf}
%\VignetteIndexEntry{Vignette's Title}
%\VignetteEngine{quarto::html}
%\VignetteEncoding{UTF-8}
---
```
````

This is one limitation of the current implementation of the vignette engine. This is to insure HTML vignette produced are reasonable in size and can be published on CRAN without problem.

The other limitation concerns the interactive rendering. If you render your vignette `.qmd` file using `quarto render` or any other function, the output will be based on default HTML format from Quarto and not the vignette engine one. Only building the vignette will produce the real results. More about building vignette in the [R Packages (2e)](https://r-pkgs.org/vignettes.html#sec-vignettes-how-built-checked) book.




Consequently, a PDF version of this vignette is built.