So I have a vignette, vignettes/test-vignette3.Rmd:
---
title: "Sample Document"
output:
html_document:
highlight: kate
theme: spacelab
toc: yes
pdf_document:
toc: yes
---
Header
=========
When I hit the knit HTML button, I get the following:
processing file: test-vignette3.Rmd
output file: test-vignette3.knit.md
Output created: /tmp/RtmpKVpegL/preview-5ef42271c0d5.dir/test-vignette3.html
However, if I copy this file to inst/doc and hit the knit HTML button, I get:
processing file: test-vignette3.Rmd
output file: test-vignette3.knit.md
Output created: test-vignette3.html
My questions are:
How do I get RStudio to save the output from knit HTML on vignettes/test-vignette3.Rmw to the vignettes directory?
How do I get RStudio to not delete test-vignette3.knit.md during the knit HTML procedure? (I'd like to have the .md so people can read it on my github repo.)
I'm running RStudio version 0.98.836, rmarkdown version 0.1.98 and knitr version 1.5.
Actually you should not keep the .html output under vignettes/, because the vignette output is supposed to be generated by R CMD build. R may fail to recompile your vignettes if the HTML output files have already been there when you build the source package, which means you are likely to see old (and possibly wrong) results because the HTML file was not generated from the latest version of the .Rmd file. Therefore RStudio intentionally avoid writing the HTML files in the vignetttes directory.
If you choose to ignore the warning above, you can certainly run rmarkdown::render('your-vignette.Rmd') in the R console.
For the second question, I do not recommend you to do that, either, because Github renders the markdown to HTML differently (compared to the Pandoc conversion done through the rmarkdown package). Normally the package vignettes are shown on CRAN, see, for example, the knitr page on CRAN. However, because the rmarkdown package is not on CRAN yet, you cannot use the vignette engine knitr::rmarkdown at the moment (I guess we are not too far away from the CRAN release now). You can consider pushing the HTML files to Github pages, though.
Related
My package has a PDF file which I'd like to include as a vignette. There are guides on the internet for doing that with Sweave and R.rsp, but I'd like to use knitr as the vignette engine because we are writing another vignette in Rmd.
My latest attempt has file.pdf and file.pdf.asis inside the vignettes/ folder, with the latter containing these two lines:
%\VignetteIndexEntry{title}
%\VignetteEngine{knitr::asis_output}
FWIW, if I use R.rsp as an engine, the second line above can simply contain %\VignetteEngine{R.rsp::asis} and that vignette builds fine, so one suspicion I have is that I am simply using the wrong knitr equivalent.
I've also tried some monstrosities involving a mix of a YAML header and LaTeX inclusion of the PDF, which didn't work either:
---
title: "title"
author: "yes"
output: pdf_document
vignette: >
%\VignetteIndexEntry{title}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
\includepdf{file.pdf}
Thanks to the power of open-source software, I was able to run browseVignettes(), go through my installed packages containing a mix of HTML and PDF vignettes, and eventually check out the source code for the jsonlite package. This led me to a simple solution I thought about but immediately dismissed because I thought it wasn't possible: declare both knitr and R.rsp as vignette engines.
So my package's DESCRIPTION now includes:
VignetteBuilder: R.rsp, knitr
and I have an Rmd vignette containing %\VignetteEngine{knitr::rmarkdown} on its YAML header and a file.pdf.asis containing %\VignetteEngine{R.rsp::asis}.
I'm writing a paper using R Markdown and TinyTex, using Biblatex for referencing. It works fine with default referencing styles, but I need to add a custom bibliography and citation style for the journal I'm writing for.
I need to follow the Unified Stylesheet for Linguistics, for which there is a Biblatex implementation available on Github here, containing a .bbx and .cbx file.
I've tried adding those .bbx and .cbx files to my local copy of TinyTex, inside Library/TinyTex/texmf-local/tex/latex/biblatex. My YAML header includes:
output:
pdf_document:
citation_package: biblatex
biblatexoptions: [bibstyle=biblatex-sp-unified, citestyle=sp-authoryear-comp]
When I knit the document, I get the following error:
tlmgr search --file --global '/biblatex-dm.cfg'
! Package keyval Error: bibstyle undefined.
I don't have a biblatex-dm.cfg file (nor do I really understand what that would be). I would have thought the .bbx and .cbx files would be sufficient, based on the regular installation instructions in the style's Github repo.
Where should I put .bbx and .cbx files, so that tlmgr can find them? And/or what additional steps do I need to take to use this style with my paper?
====================================================================
UPDATE: The problem seems to be coming from the Pandoc LaTeX template that R Markdown uses.
Setting aside R Markdown, I created a smaller minimal LaTeX example:
main.tex
references.bib
Where main.tex is:
\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage[bibstyle=biblatex-sp-unified,citestyle=sp-authoryear-comp]{biblatex}
\addbibresource{references.bib}
\begin{document}
Something something \citep{darwin_origin_1859}.
\printbibliography
\end{document}
And references.bib is:
#book{darwin_origin_1859,
location = {London},
title = {On the Origin of Species by Means of Natural Selection},
publisher = {J. Murray},
author = {Darwin, Charles},
date = {1859}
}
I had success compiling this example using the sequence of commands pdflatex, biber, pdflatex, pdflatex. Thus it seems my local TeX installation knows about the biblatex-sp-unified.bbx and sp-authoryear-comp.cbx files I added and can use them just fine.
Subsequently, I created an equivalent minimal R Markdown document with the YAML header:
title: "Untitled"
output:
pdf_document:
citation_package: biblatex
bibliography: references.bib
biblatexoptions: [bibstyle=biblatex-sp-unified, citestyle=sp-authoryear-comp]
and body:
Something something [#darwin_origin_1859].
This time, I got the same old error message from before:
tlmgr search --file --global '/biblatex-dm.cfg'
! Package keyval Error: bibstyle undefined.
This would seem to suggest that the problem is caused by something in Pandoc's LaTeX template, but I don't know what.
Just to confirm that it's definitely the Pandoc template and not my own installation/setup, I took the .tex file that gets produced when I knit the minimal R Markdown example above, and tried to compile it in Overleaf (with biblatex-sp-unified.bbx and sp-authoryear-comp.cbx files added). I reproduced the same error.
Although I think I've localised the problem, I'd still very much like to understand what and where the problem is in the Pandoc template. I'd also be keen to hear if anyone has any fixes (other than just using a different template or writing my own).
UPDATE: This seems to be an issue with using an out-of-date version of R Markdown and/or Pandoc.
I was using rmarkdown package v.1. At time of writing, the most up-to-date version is 2.1.
I updated all my packages and updated Rstudio (which currently ships with Pandoc v2.3.1) and no longer experience problems. I also upgraded R (from 3.5.something to 3.6.2) and did a fresh re-install of tinytex while I was at it, but I'm not sure whether those things had an effect for this particular problem.
Now, when I put biblatexoptions: [bibstyle=biblatex-sp-unified, citestyle=sp-authoryear-comp] in my YAML header, it's correctly converted into the LaTeX command \usepackage[bibstyle=biblatex-sp-unified,citestyle=sp-authoryear-comp]{biblatex}, rather than the \ExecuteBibliographyOptions command as described below.
Ralf Stubner initially suggested I check my R Markdown/Pandoc versions in the comments. Please give his comments an upvote if you them useful as well.
Problem recap:
I'm writing a document in R Markdown and I have a particular referencing style that I'd like to use with biblatex. I have a .bbx and .cbx file defining the style, available on Github (linked above). The problem is that the document fails to compile, saying biblio/citation styles are undefined (even when the style files are in the project folder itself).
I've found that the problem was caused by the way I was passing options to biblatex. In my YAML Header, the line:
biblatexoptions: [bibstyle=biblatex-sp-unified, citestyle=sp-authoryear-comp]
gets converted to the latex command:
\ExecuteBibliographyOptions{bibstyle=biblatex-sp-unified,citestyle=sp-authoryear-comp}
I'm not sure why, but when this command is included, it produces the errors I was observing.
Installing new Biblatex style:
I'm finding that TeX doesn't know about the .bbx and .cbx files when they're in my ~/Library/TinyTex/texmf-local/tex/latex/biblatex directory (which is where I expected to put them based on the Github installation instructions).
To get the referencing style recognised by the system, I placed .bbx and .cbx files inside ~/Library/TinyTex/texmf-dist/tex/latex/biblatex/bbx and ~/Library/TinyTex/texmf-dist/tex/latex/biblatex/cbx respectively. Then, in the terminal, I ran sudo mktexlsr.
(Alternatively, for use only with a particular document, the .bbx and .cbx files could simply be kept in the project directory with the R Markdown file)
Original hacky answer (but see update above):
Instead of using biblatexoptions in the YAML header of the R Markdown document, I simply knitted it with citation_package: biblatex (and no extra options). I also added keep_tex: yes. Then, I opened the resulting tex file, found the \usepackage{bibtex} command and added the desired options, so it read \usepackage[bibstyle=biblatex-sp-unified,citestyle=sp-authoryear-comp]{biblatex}.
Finally, I ran pdflatex and biber on the tex file in the terminal. Clearly far from ideal, but it will technically produce the desired output.
I have a problem with the preamble.tex file used in the Rmarkdown rticles template for R Journal Submission. This is the procedure I'm following:
Create a new Rmarkdown rticles template for submission to the R Journal
Knit the document and everything seems to be fine
Add some latex code to preamble.tex (like \usepackage{subfig})
Knit the document and it doesn't compile anymore.
If I just remove \usepackage{subfig} from preamble.tex then everything works fine. I think the problem is related to the fact that the \usepackage{...} code isn't put in the preamble of the .tex document but I don't know how to fix that.
If you want to test I created I git repo here with all the Rmarkdown files up to point 3 of the previous list. If I knit the Rmd document that I get an error.
Hope it's clear
This is due to a bug in the rticles package, which I just resolved on Github. If you install the Github version, it should work now:
remotes::install_github('rstudio/rticles')
I'm trying to see the vignette that I've created after rebuilding a package on my local computer. Note that this has nothing to do with suggestions on this post, since I'm not cloning from Github.
The vignettes portion of my vignette file looks like this:
vignette: >
%\VignetteIndexEntry{pack_name}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
The process is:
Ctr + Shift + K to knit the vignette
Ctr + Shift + B to rebuild the package
Enter browseVignettes("package name")
Get error:
No vignettes found by browseVignettes
I also tried changing knitr::markdown to knitr::knitr, but it didn't help.
Entire vignette top-portion:
---
title: "Random title"
author: "Author"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{vignette_name}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
You don't give all the details to say what went wrong, but here is what you need to do:
Vignettes need to be in the package vignettes directory.
If they are anything but Sweave vignettes (and yours is knitr::rmarkdown, according to the header lines you showed us), then you need to tell R about it in the DESCRIPTION file. For your example, you'd need
VignetteBuilder: knitr
in that file, and also have knitr listed in the Suggests, Depends, or Imports lines.
You need to follow the naming convention for your vignette engine. For knitr::rmarkdown, name the file something.Rmd.
You don't need to knit the file yourself. R will do that when it builds the source package. (You can configure RStudio to do this for "Install and Restart"; by default it doesn't.) Even if you haven't knitted the vignette, browseVignettes should find it if you've followed the other steps properly, it just won't display the HTML or PDF output, only the source and extracted R code.
Edited to add: When building and reinstalling the package, it appears that sometimes vignettes aren't included unless the install is done from a .tar.gz file. Use the "Build Source Package" option in the RStudio build pane to get one of those.
I am trying to write R Package vignettes using R Markdown. I am using R Studio's package authoring tools.
I have R greater than version 3.0.
I have an .Rmd file in the vignettes folder that contains the following text at the top:
<!--
%\VignetteEngine{knitr::knitr}
%\VignetteIndexEntry{An Introduction to the bootcorrelations package}
-->
I have the following in my DESCRIPTION file:
VignetteBuilder: knitr
Suggests: knitr
When I clean and build or build and reload the package in RStudio, the vignette source is displayed, but not the HTML (i.e., there's no HTML file in inst/man).
How can I get RStudio to automatically create the HTML from an R Markdown Vignette?
I've read through Yihui's post on R Package Vignettes with Markdown and it suggests using a makefile, but this more recent documentation about knitr vignettes suggests that the makefile is no longer required.
I also realise that I could manually create the HTML vignette with a command like this:
library(knitr)
knit(input='vignettes/foo.Rmd', output='inst/doc/foo.md')
library(markdown)
markdownToHTML('inst/doc/foo.md', 'inst/doc/foo.html')
A reproducible example:
Vectorize(dir.create)(c("test", "test/R", "test/man", "test/vignettes"))
cat(
'Package: test
Title: Test pkg
Description: Investigate how to auto-compile markdown vignettes
Version: 0.0-1
Date: 2015-03-15
Author: Jeromy Anglim
Maintainer: Jeromy Anglim <a#b.com>
Suggests: knitr
License: Unlimited
VignetteBuilder: knitr',
file = "test/DESCRIPTION"
)
cat(
'---
title: "Introduction"
author: "Jeromy Anglim"
date: "`r Sys.Date()`"
output: html_document
---
<!--
%\\VignetteEngine{knitr::rmarkdown}
%\\VignetteIndexEntry{Introduction}
-->
# Introduction
A sample vignette!
```{r}
1 + 1
```',
file = "test/vignettes/intro.Rmd"
)
cat(
"#' Nothing
#' This function is only needed so that roxygen generates a NAMESPACE file.
#' #export
nothing <- function() 0",
file = "test/R/nothing.R"
)
library(roxygen2)
library(devtools)
roxygenise("test")
build("test")
Update: Thinking laterally, there are at least three options.
1. Use build_vignettes()
As #Hadley points out, running build_vignettes() from the devtools package will build vignettes and place them in the inst/man directory of the package.
devtools::build_vignettes()
Building the vignette means you get three versions in inst/man:
the Rmd source
the knitted or weaved HTML vignette
and the R code in the code blocks
This is not tied to the build and reload command in RStudio, but it is a one line solution to the task. And it could easily be incorporated into a makefile.
2. Use Knit HTML in Rstudio
As #TylerRinker notes you can just use Knit HTML in Rstudio. This will add both md and HTML knitted versions of the rmd vignette to the vignettes directory.
This also is not tied to the build process but as #TylerRinker points out, often you don't want the vignettes tied to the main build process. This also has the benefit of giving you an md file which can be a nice option for displaying the vignette on github, although http://htmlpreview.github.com/ is an option for displaying HTML vignette on github.
3. Build source package and extract from compressed file
Build - Build Source Package in RStudio corresponds to R CMD build. When run a compressed tar.gz file is created which contains in the inst/doc directory the Rmd, R and HTML files for the original rmd vignette file.
This is described in the official documentation on writing package vignettes which instructs you to use R CMD build to generate PDF and HTML vignettes.
So it is possible to
Build Source
Unzip the tar.gz file
Browse and open the resulting file