A short overview of creating a {bookdown} book and publishing on bookdown.org
This post will explain the steps involved to edit and create Reproducible Medical Research in R, which is published on bookdown.org, where you can create an account to publish your own e-book and share it with the world. Go ahead, go to bookdown to set up your own account.
Once you have an account,
Install the {bookdown} package, with install.packages('bookdown')
.
Then run library(bookdown)
in the Console to load the package.
Then, in the RStudio IDE, Choose File/New Project/Book Project using bookdown.
Then go to the Files tab, open index.Rmd, and click the Knit button. The Preview Window will show you a minimal example of a bookdown book. You can now start editing and adding new chapters.
You can edit your _bookdown.yml
file, which controls the setup of your book. I chose to have ‘manual’ control of chapter order, by listing the ‘ready for prime time’ chapters in the _bookdown.yml
file in order. Draft chapters will not be included in the published book until I list them in this file.
My _bookdown.yml
file looks something like this (more chapters being added):
book_filename: "rmrwr"
title: "Reproducible Medical Research with R"
language:
ui:
chapter_name: "Chapter "
delete_merged_file: true
new_session: yes
rmd_files:
- index.Rmd
- io02-getting-started.Rmd
- io03-tasting.Rmd
- io65-error_messages.Rmd
- io04-updating.Rmd
- io07-major-updates.Rmd
- io08-data-validation.Rmd
- io09-timeseries.Rmd
- io10-tableOne.Rmd
- io30-ttest.Rmd
- io70-r_cmd_line.Rmd
- io98-title-holder.Rmd
- io99-references.Rmd
You can edit your _output.yml
file, which controls the output and look of your book. My _output.yml
file looks like this:
::gitbook:
bookdown: style.css
css:
config:
toc: |
before<li><a href="./">RMRWR</a></li>
: |
after<li><a href="https://github.com/rstudio/bookdown" target="blank">Published with bookdown</a></li>
: https://github.com/rstudio/bookdown-demo/edit/master/%s
edit: ["pdf", "epub"]
download::pdf_book:
bookdown:
includes: preamble.tex
in_header: xelatex
latex_engine: natbib
citation_package: yes
keep_tex::epub_book: default bookdown
Note that this file refers to a style.css
file, which affects the appearance of your book, by using cascading style sheets (css) for formatting. Lots of this was borrowed from Desiree DeLeon and her tinystats book.
My style.css
file looks like this:
@import url('https://fonts.googleapis.com/css?family=Abril+Fatface|Source+Sans+Pro:400,400i,700,700i|Lora:400,400i,700,700i&display=swap');
p.caption {: #777;
color-top: 10px;
margin
}
p code {-space: inherit;
white
}
pre {-break: normal;
word-wrap: normal;
word
}
pre code {-space: inherit;
white
}
/* Desiree custom css */
/* next 3 rules for setting large image at top of each page and pushing book content to appear beneath that */
/*
-image-container {
.hero: absolute;
position: 0;
top: 0;
left: 0;
right: 390px;
height/*background-image: url("images/books.jpg");
-color: #2F65A7;
background*/
}
/*.hero-image {
: 100%;
width: 390px;
height-fit: cover;
object*/
}
/*.page-inner {
-top: 440px !important;
padding*/
}
/* Links */
-body .page-wrapper .page-inner section.normal a {
.book .book: #702082;
color
}
/* Body and header text */
-family-1 {
.book.font-family: 'Source Sans Pro', arial, sans-serif;
font
}
h1, h2, h3, h4 {-family: 'Lora', arial, sans-serif;
font
}
-body .page-wrapper .page-inner section.normal h1,
.book .book-body .page-wrapper .page-inner section.normal h2,
.book .book-body .page-wrapper .page-inner section.normal h3,
.book .book-body .page-wrapper .page-inner section.normal h4,
.book .book-body .page-wrapper .page-inner section.normal h5,
.book .book-body .page-wrapper .page-inner section.normal h6 {
.book .book-top: 1em;
margin-bottom: 1em;
margin
}
.title {-family: 'Lora';
font-size: 3em !important;
font: #2f65a7;
color-top: 0.275em !important;
margin-bottom: 0.35em !important;
margin
}
.subtitle {-family: 'Lora';
font: #2f65a7;
color
}
/* DROP CAPS*/
/*p:nth-child(2):first-letter { /* /* DROP-CAP FOR FIRST P BENEATH EACH H1 OR H2*/ /*
: #2f65a7;
color: left;
float-family: 'Abril Fatface', serif;
font-size: 7em;
font-height: 65px;
line-top: 4px;
padding-right: 8px;
padding-left: 3px;
padding-bottom: 9px;
margin
}*/
/* try the below with the ~ instead...or just the space?) */
> p:first-of-type:first-letter { /*drop cap for first p beneath level 1 headers only within class .section*/
.section.level1 : #2f65a7;
color: left;
float-family: 'Abril Fatface', serif;
font-size: 6em;
font-height: 65px;
line-top: 4px;
padding-right: 8px;
padding-left: 3px;
padding-bottom: 9px;
margin
}
/* add drop cap to first paragraph that follows the first 2nd level header*/
/*
:first-of-type > p:first-of-type:first-letter {
.section.level2: #2f65a7;
color: left;
float-family: 'Abril Fatface', serif;
font-size: 7em;
font-height: 65px;
line-top: 4px;
padding-right: 8px;
padding-left: 3px;
padding-bottom: 9px;
margin
}*/
/* TOC */
-summary {
.book .book: white;
background-right: none;
border
}
.summary{-family: 'Source Sans Pro', sans-serif;
font
}
/* all TOC list items, basically */
-summary ul.summary li a, .book .book-summary ul.summary li span {
.book .book-top: 8px;
padding-bottom: 8px;
padding-left: 15px;
padding-right: 15px;
padding: #00274c;
color
}
:hover {
.summary a: #ffcb05 !important;
color
}
-summary ul.summary li.active>a { /*active TOC links*/
.book .book: #d86018 !important;
color-left: solid 4px;
border-color: #d86018;
border-left: 11px !important;
padding
}
/* for TOC part names */
li.appendix span, li.part span { -top: 1em;
margin: #000000;
color: .9 !important;
opacity-transform: uppercase;
text
}
+ li[data-level=""] { /* grabs first .chapter immediately after .part...but only those ch without numbers */
.part -transform: uppercase;
text
}
> li > a { /* The > selects all the li's which are immediately within the class summary*/
ul.summary font-family: 'Source Sans Pro', sans-serif;
}
/* The next two rules make the horizontal line go straight across in top navbar */
.summary > li:first-child {
height: 50px;
padding-top: 10px;
border-bottom: 1px solid rgba(0,0,0,.07);
}
.book .book-summary ul.summary li.divider {
height: 0px;
}
/* source code copy button */
.copy {
width: inherit;
background-color: #e2e2e2 ;
border: none;
border-radius: 2px;
float: right;
font-size: 60%;
padding: 4px 4px 4px 4px;
}
/* Two columns */
.col2 {
columns: 2 200px; /* number of columns and width in pixels*/
-webkit-columns: 2 200px; /* chrome, safari */
-moz-columns: 2 200px; /* firefox */
}
.side-by-side {
display: flex;
}
.side1 {
width: 40%;
}
.side2 {
width: 58%;
margin-left: 1rem;
}
/* -------------- div tips-------------------*/
div.warning, div.tip, div.tryit, div.challenge, div.explore {
border: 4px #dfedff; /* very light blue */
border-style: solid;
padding: 1em;
margin: 1em 0;
padding-left: 100px;
background-size: 70px;
background-repeat: no-repeat;
background-position: 15px center;
min-height: 120px;
color: #00274c; /* blue text */
background-color: #bed3ec; /* light blue background */
}
div.warning {
background-image: url("images/warning.png");
background-color: #f7f7f7; /* gray97 background */
}
div.tip {
background-image: url("images/tip.png");
background-color: #fff7bc; /* warm yellow background */
}
div.tryit {
background-image: url("images/tryit.png");
background-color: #edf8fb; /* light blue background */
}
div.challenge {
background-image: url("images/challenge.png");
color: #4b0082; /* indigo text */
background-color: #ffe1ff; /* thistle background */
}
div.explore {
background-image: url("images/explore.png");
background-color: #d0faee; /* green card background */
}
/* .book .book-body .page-wrapper .page-inner section.normal is needed
to override the styles produced by gitbook, which are ridiculously
overspecified. Goal of the selectors is to ensure internal "margins"
controlled only by padding of container */
.book .book-body .page-wrapper .page-inner section.normal div.rstudio-tip > :first-child,
.book .book-body .page-wrapper .page-inner section.normal div.tip > :first-child {
margin-top: 0;
}
.book .book-body .page-wrapper .page-inner section.normal div.rstudio-tip > :last-child,
.book .book-body .page-wrapper .page-inner section.normal div.tip > :last-child {
margin-bottom: 0;
}
iframe {
-moz-transform-origin: top left;
-webkit-transform-origin: top left;
-o-transform-origin: top left;
-ms-transform-origin: top left;
transform-origin: top left;
}
.iframe-container {
overflow: auto;
-webkit-overflow-scrolling: touch;
border: #ddd 2px solid;
box-shadow: #888 0px 5px 8px;
margin-bottom: 1em;
}
.iframe-container > iframe {
border: none;
}
Each chapter was created in R Markdown, with R code chunks, flipbooks, microquizzes with {webexercises}, and learnr apps as exercises.
Note that each chapter should start with a level 1 header, which will be the title of the chapter. Each level 1 header starts with a single hashtag, then a space, then the text of the title.
You can save draft chapters without necessarily publishing them to the final book. They will not be included until you list them in your _bookdown.yml
file.
After saving and knitting each chapter successfully, the finalized chapters can be included in the book build, and ordered, by adding them to the _bookdown.yml
file, in between index.Rmd, and io98-title-holder.Rmd.
The names of each of my chapters follow the convention, io###-Topic.Rmd. This is so that they will alphabetically follow index.Rmd and largely be in order.
Add the new chapter to the list of chapters in order in _bookdown.yml
, somewhere in between
- index.Rmd and
- io98-title_holder.Rmd
Note that I need to have a title holder chapter as a placeholder, so that the Preface will not get a weird title from the last chapter. I am not sure why.
It just works.
Render the book with bookdown::render_book('index.html')
Publish the book with your account name
bookdown::publish_book(account = 'pdr_higgins')
Then commit the changes and push to Github
Within a minute or three, the updated book will appear at:
https://bookdown.org/pdr_higgins/rmrwr/
More details can be found at:
https://bookdown.org/yihui/bookdown/rstudio-connect.html
and at
https://bookdown.org/home/about/
For attribution, please cite this work as
Higgins (2020, Dec. 12). Medical R: Publishing a {bookdown} book on bookdown.org. Retrieved from https://higgi13425.github.io/medical_r/posts/2020-12-12-publishing-a-bookdown-book-on-bookdownorg/
BibTeX citation
@misc{higgins2020publishing, author = {Higgins, Peter}, title = {Medical R: Publishing a {bookdown} book on bookdown.org}, url = {https://higgi13425.github.io/medical_r/posts/2020-12-12-publishing-a-bookdown-book-on-bookdownorg/}, year = {2020} }