A Minimal Book Example
2021-10-25 13:03:31
Chapter 1 Workshop 211021
1.1 workshop material
- in order to follow along, please download github repo as zip file https://github.com/nils-holmberg/sfac-r/archive/refs/heads/main.zip
- unzip repo file on local computer and navigate to it in rstudio, or upload zip file to https://rstudio.cloud, demo will be held on this web service
1.2 install libs
install.packages("rmarkdown")
install.packages("bookdown")
install.packages("rsconnect")
#install.packages("bslib")
#library(rmarkdown)
#library(bookdown)
1.3 test rmarkdown
- we are going to use rmarkdown to render a single Rmd document, setwd() to sfac-r-main/web/bkd/workshop
#setwd("/cloud/project/sfac-r-main/web/bkd/workshop")
::render('document1.Rmd', output_format='all', output_dir='./')
rmarkdown#rmarkdown::render('document2.Rmd', output_format='all', output_dir='./')
- the output formats are specified in the yaml header of the Rmd file, you can preview the result by opening the output file
- when using docx output, we can use a reference document that will determine the styling of the output (could be useful for journal article templates ?)
1.4 test bookdown
- bookdown is build on top of rmarkdown, and its primary function is to handle multiple Rmd files and render them as a coherent output document
- now we are going to try to render a collection of Rmd files as a book, the original bookdown demo can be found on github https://github.com/rstudio/bookdown-demo, but you can also change directory to sfac-r-main/web/bkd
#setwd("/cloud/project/sfac-r-main/web/bkd")
::render_book('index.Rmd', output_dir='./') bookdown
- the output formats are specified in the yaml header of the index.Rmd file, you can preview the result of any changes by opening the index.html file
1.5 publish book
- if we have a git client and a github account, the book could now be published to github
- however, we can also choose to publish to the web service https://bookdown.org/ by creating a freemium account there
# rstudio connect package
::accounts()
rsconnect#rsconnect::connectUser(account="nils.holmberg", server="bookdown.org")
- the following commands can also be accessed more easily through the rstudio gui
- connect your r client to bookdown.org, rstudio connect while being logged in with web browser
- when publishing the bookdown file bundle, we need to stand in the correct working directory
#setwd("/cloud/project/sfac-r-main/web/bkd")
::publish_book(render="local", account="nils.holmberg", server="bookdown.org", name="sfac-r-bookdown") bookdown
1.6 collaborate
- seems to only be available for shinyapps at this point, however web interface to rsconnect might have these functions available..
::showUsers(account="nils-holmberg", server="shinyapps.io") rsconnect
1.7 troubleshoot
- instead of using the publish_book() function provided by the bookdown package, we can also try to deploy site using the rsconnect package to publish rendered Rmd output files
::deployments(".")
rsconnect#rsconnect::forgetDeployment(dryRun = TRUE)
#rsconnect::deploySite(account="nils.holmberg", siteName="sfac-r-bookdown", server="bookdown.org")
1.8 deploy to github
- an example of a collaborative bookdown project that consists of multiple book parts https://nils-holmberg.github.io/scom-expb/web/
- reviewers needed, please contact me if you are interested or know someone who might be nils.holmberg@isk.lu.se