[Tutorial for R bookdownplus package] Installation + Quick Start (in RStudio)
Repository
https://github.com/pzhaonet/bookdownplus
What Will I Learn?
- Setting-up of the environment which bookdownplus requires.
- Using the function
bd()
to build a demo book. - Using the function
bookdownplus()
with different output formats and templates. - Contribute your own templates.
- Using other R packages to enhance bookdownplus.
Requirements
- Windows/mac/Linux OS
- R environment
- R bookdown package
- R bookdownplus package
- RStudio IDE (recommended)
Difficulty
- Intermediate
Introduction
The package bookdownplus (Zhao 2017a) is an extension of R bookdown (Xie 2016). It is a collection of multiple templates on the basis of LaTeX, which are tailored so that I can work happily under the umbrella of bookdown. bookdownplus helps you write academic journal articles, guitar books, chemical equations, mails, calendars, and diaries.
An old tutorial for bookdownplus was written more than one year ago and included in the readme of the bookdownplus repo. However, it is out of date and too short. In the recent months, bookdownplus has changed significantly. The structure of the functions have been improved. More book and article templates have been included. The website bookdownplus gallery has been set up. Thus, a new tutorial is necessary.
Quick start
Preparation
Install R, RStudio. LaTeX(e.g. MiKTeX or TinyTeX. See the official manual of ‘bookdown’ for details.
Run RStudio. Type the following codes in the top-left panel to install ‘bookdown’ packages:
install.packages('bookdown')
Installation
# the development version from GitHub (recommended)
devtools::install_github("pzhaonet/bookdownplus")
# or the stable version from CRAN
install.package("bookdownplus")
Generate a demo book
Firstly check your working directory (getwd()
) and make sure that it is empty. bookdownplus
will generate lots of files. An empty folder as a working directory is highly recommended. If you don’t know how to change your working directory with R command, you can use RStudio to create a new project (File – New Project - New Directory – Empty Project) and work always in this project.
Run the following codes:
require(bookdownplus)
bd('ubt')
Now a demo dissertation for the University of Bayreuth is generated in many formats in the _book/
folder in your working directory. Open _book/ubt.pdf
or other files so as to get an impression.
Write your own book
bd()
is a simplified function for demos. The main function of the bookdownplus package is:
bookdownplus()
with multiple parameters.
For example,
bookdownplus(template = 'ubt', render = TRUE)
You can see some other files (e.g. index.Rmd
, body.Rmd
, -bookdownplus.Rproj
) and folders. Write your own texts in body.Rmd
and revise the author and the book title in index.Rmd
. You can use RStudio or any other text editor (but please don’t use Microsoft Word).
After writing some texts, open -bookdownplus.Rproj
with RStudio, and press ctrl+shift+b
to build your own lovely book.
More outputs
By default, the book is built in a .pdf file and an .md file. From ‘bookdownplus v1.0.3’, users can get more output formats, including word, html and epub. From ‘bookdownplus v1.2.0’, uses can see the available output formats by running:
get_output()
You can specify the more_output
argument in the bookdownplus()
function:
bookdownplus(more_output = get_output())
Then all the required output files are in _book/
folder.
More templates
By default, the book is built from the ‘ubt’ template. From ‘bookdownplus v1.2.0’, users can see the available templates by running:
get_template()
A template with a name ended with ’_zh’ means that it supports Chinese characters. To list all these Chinese templates, run:
grep('_zh$', get_template()[, 'name'], value = TRUE)
You can specify the template
argument in the bookdownplus()
function:
bookdownplus(template = get_template()$name[1])
Then all the required output files are in _book/
folder.
Magic trick
Now it is time to witness the miracles. With the following magic trick you will see what bookdownplus can do.
Chinese users can run the following codes, and go and have a coffee break. When you come back, you will get more than 20 demo books generated from available templates, each in .pdf, .doc, .html, and .epub formats, in _book/
:
bd()
Non-Chinese users might encounter some errors because their computers do not support Chinese characters in the demo books. Instead, run the following codes, which exclude the Chinese templates and the remote templates:
my_t <- get_template()
my_t <- my_t$name[my_t$location == 'local' & !grepl('_zh$', my_t$name)]
bd(my_t)
Showcase
The website bookdownplus gallery shows some samples that bookdownplus provides.
Share Your Own Templates
bookdownplus
provides around 30 templates (Version 1.5.0). If you are willing to contribute your own bookdown templates to bookdownplus, just upload them to the bookdownplus repo. They will be displayed in the bookdownplus gallery automatically once accepted.
From the version 1.5, bookdownplus opens a widest-ever door to contributors. Here is how:
- Make sure that your template works successfully with bookdown.
- Prepare a folder in your working directory by running:
bookdownplus::share('your_template_name')
Follow the instructions in each subfolder and create the required files.
- (Mandatory) 'your_template_name/demo.zip' is the compressed file from your bookdown project folder.
- (Optional) 'your_template_name/showcase/' contains the sample files (e.g. pdf, image files). An image file 'cover.png' is recommended, which will be used as the cover image in the gallery.
- (Optional) You could write a 'your_template/readme.txt' (in markdown syntax), which will be displayed as the text in the gallery.
Upload your template folder 'your_template_name/' in to 'upload/' of the bookdownplus repo.
Add the template information, including the template name, the contributor's name, and a brief introduction, into 'upload/-list.csv'.
Create a Pull Request to bookdownplus.
Wait for the response, and your template will be available in the gallery. Users can get it easily by clicking the ".zip" link in the gallery, or running
bookdownplus("your_template_name")
Recommendations
I have been developing some other packages, which bring more features into ‘bookdown’, such as:
mindr (Zhao 2017b), which can extract the outline of your book and turn it into a mind map, and
pinyin (Zhao 2017c), which can automatically generate ‘{#ID}’ of the chapter headers even if there are Chinese characters in them.
Both of them have been released on CRAN and can be installed via install.packages('mindr')
and install.packages('pinyin')
.
Enjoy your bookdowning!
References
Xie, Yihui. 2016. Bookdown: Authoring Books and Technical Documents with R Markdown. https://github.com/rstudio/bookdown.
Zhao, Peng. 2017a. Bookdownplus: Generate Varied Types of Books and Documents with R ’Bookdown’ Package. https://CRAN.R-project.org/package=bookdownplus.
———. 2017b. Mindr: Convert Files Between Markdown or Rmarkdown Files and Mindmaps. https://CRAN.R-project.org/package=mindr.
———. 2017c. Pinyin: Convert Chinese Characters into Pinyin. https://CRAN.R-project.org/package=pinyin.
Proof of Work Done
This tutorial is inserted into the readme of the bookdownplus repo:
The code used in this tutorial can be found in:
Thank you for your contribution @dapeng.
Below we suggest some points:
Tutorial well explained and easy to understand. Thank you for your beautiful work.
Your contribution has been evaluated according to Utopian policies and guidelines, as well as a predefined set of questions pertaining to the category.
To view those questions and the relevant answers related to your post, click here.
Need help? Write a ticket on https://support.utopian.io/.
Chat with us on Discord.
[utopian-moderator]
Thank you very much for your comments! The title has been revised.
Thank you for your review, @portugalcoin!
So far this week you've reviewed 5 contributions. Keep up the good work!
Hi @dapeng!
Your post was upvoted by @steem-ua, new Steem dApp, using UserAuthority for algorithmic post curation!
Your post is eligible for our upvote, thanks to our collaboration with @utopian-io!
Feel free to join our @steem-ua Discord server
Hey, @dapeng!
Thanks for contributing on Utopian.
We’re already looking forward to your next contribution!
Get higher incentives and support Utopian.io!
Simply set @utopian.pay as a 5% (or higher) payout beneficiary on your contribution post (via SteemPlus or Steeditor).
Want to chat? Join us on Discord https://discord.gg/h52nFrV.
Vote for Utopian Witness!