rstudio / bookdown

Authoring Books and Technical Documents with R Markdown

bookdown

A open-source (GPL-3) R package to facilitate writing books and long-form articles/reports with R Markdown. Features include:

• Generate printer-ready books and ebooks from R Markdown documents
• A markup language easier to learn than LaTeX, and to write elements such as section headers, lists, quotes, figures, tables, and citations
• Multiple choices of output formats: PDF, LaTeX, HTML, EPUB, and Word.
• Possibility of including dynamic graphics and interactive applications (HTML widgets and Shiny apps)
• Support for languages other than R, including C/C++, Python, and SQL, etc.
• LaTeX equations, theorems, and proofs work for all output formats
• Can be published to GitHub, bookdown.org, and any web servers
• Integrated with the RStudio IDE
• One-click publishing to https://bookdown.org

Book

Installation

You can install the package from CRAN as follows:

install.packages("bookdown")

If you want to use the development version of the bookdown package, you can install the package from GitHub via the pak package:

# install.packages("pak")
pak::pak('rstudio/bookdown')

Usage

The easiest way to start a new Bookdown project is from within RStudio IDE. Go to File > New Project > New Directory > Book project using bookdown.

This will create a new directory with an example book as template. You can build the HTML version of this example book without doing any modification:

• Go into the Build Pane in the RStudio IDE
• Click on Build Book > bookdown::gitbook

You can also run bookdown::render_book() in the R console.

Learn more about using bookdown in the Getting started section.

Getting help

There are two main places to get help:

1. The RStudio community is a friendly place to ask any questions about bookdown. Be sure to use the bookdown tag.

2. Stack Overflow is a great source of answers to common bookdown questions. Use the tags [r][bookdown] if you ask a question.

Code of Conduct

Please note that the bookdown project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

bookdown's Issues

Link to documentation in readme

http://rstudio.github.io/bookdown/

Provide an RStudio add-in to help manage cross-references

just like the LyX panel that allows you to choose a reference key interactively

Similar thing for citations.

Is `\@ref` syntax only exclusive to `bookdown` at the moment?

I've enjoyed the \@ref feature for referencing tables and figures. I noticed, however, that this seems exclusive to bookdown. Is that the case?

Is there anyway to have this same referencing syntax across any .Rmd? I would love to use it in a .Rmd I'm currently writing with output: html_document!

Apologies as I know that this is not exactly an issue with bookdown but more of a request to have this feature extended to any rmarkdown document.

Issues with bookdown gitbook Travis build

I recently setup a gh-pages hosted bookdown gitbook (https://github.com/nate-d-olson/mgmgnotes) and ran into a few issues, which I expected since the package is under active development. I was able to find work arounds for the issues and the Travis-CI build is working. Here is a list of the issues I ran into along with my work arounds.

• Documentation related
  • File numbering- section/ subsection and role of _bookdown.yml, it is unclear from the documentation how the file numbering and rmd list in _bookdown.yml determine chapters.
  • The Travis build required a DESCRIPTION file, also needed to state devtools was a dependency for installing packages on github e.g. bookdown. Travis build log with error https://travis-ci.org/nate-d-olson/mgmgnotes/builds/116715029
• Running scripts build and deploy scripts - needed to add the following to the .travis.yml due to a permissions issue. Not sure if it is better to define this in the .travis.yml or change permissions locally. Travis build log https://travis-ci.org/nate-d-olson/mgmgnotes/builds/116736240

before_script:
 - chmod +x ./_build.sh
 - chmod +x ./_deploy.sh

• Issues with _deploy.sh pushing to github (see build error message below ). I fix the issue I added git config --global user.email and git config --global user.name to the deploy script. I might have not set the GH_TOKEN up correctly though. Travis build log https://travis-ci.org/nate-d-olson/mgmgnotes/builds/116739556

$ ./_deploy.sh
Cloning into 'book-output'...
remote: Counting objects: 175, done.
remote: Compressing objects: 100% (118/118), done.
remote: Total 175 (delta 62), reused 152 (delta 44), pack-reused 0
Receiving objects: 100% (175/175), 457.89 KiB | 0 bytes/s, done.
Resolving deltas: 100% (62/62), done.
Checking connectivity... done.
*** Please tell me who you are.
Run
  git config --global user.email "[email protected]"
  git config --global user.name "Your Name"
to set your account's default identity.
Omit --global to set the identity only in this repository.
fatal: empty ident name (for <[e-mail]>) not allowed

Function to clear caches?

It would be nice to have a function that could inspect _bookdown.yml and figure out all files that need to be deleted if you want to start completely from fresh.

Before_chapter_script doesn't work?

In _bookdown.yaml I have:

before_chapter_script: "_common.R"

and in _common.R I have:

knitr::opts_chunk$set(
  comment = "#>",
  collapse = TRUE,
  cache = TRUE
)

but the chunk options don't seem to have any affect. What am I missing?

before_chapter_script also needs to be run by preview_chapter

So local previews look the same as building the complete book.

render before publish?

In the docs for publish_book I say "be sure to render all your formats before publishing". Should we just automatically render before publishing? (perhaps with a render argument to override this behavior). I guess if books are computationally expensive it would be annoying to have them auto-rendered but in that case perhaps caching is in use.

Don't have a strong opinion here, just wanted to raise the issue for discussion.

Equivalent of oldbookdown::screenshot()

I don't think we have anything that's quite equivalent yet. There are two important differences from knitr::include_graphics():

• you can use it inside r for inline graphics
• it preserves the original size of the image (using optional dpi argument to scale) (i.e. it ignores fig.width and fig.height)

This is most useful for diagrams (so the screenshot() name isn't great), where you have carefully sized the image.

A collection of problems that bookdown can solve

• cross-references http://stackoverflow.com/q/34003550/559676
• citation http://stackoverflow.com/q/33284343/559676
• split file http://stackoverflow.com/q/35295898/559676
• figre/table captions https://github.com/adletaw/captioner
• https://github.com/jbryer/Rgitbook

Can not copy files

bookdown::render_book("index.rmd")

#>  Error in file.copy(files_md[!rerun], basename(files_md[!rerun]), overwrite = TRUE) : 
#>   file can not be copied both 'from' and 'to' 
#> 4 stop("file can not be copied both 'from' and 'to'") 
#> 3 file.copy(files_md[!rerun], basename(files_md[!rerun]), overwrite = TRUE) at render.R#138
#> 2 render_new_session(files, main, force_knit, output_format, clean, 
#>     envir, ...) at render.R#94
#> 1 bookdown::render_book("index.rmd") 

Any ideas?

Title Documents

I'm guessing there's a way to do this with custom templates somehow, but it would be nice if there were a simple way to add a title to a document. This would be prepended on PDFs and perhaps integrated into the <title> of HTML?

Gitbook: default description

Currently you get <meta name="description" content="Documentation for using GitBook and gitbook.com">

Weird styling of headings with code

Allow duplicate chunk labels?

After merging all Rmd files, there might be duplicate chunk labels (e.g. the current ggplot2 book has this problem), we can allow such labels by setting a knitr option, but it may make the automatic figure/table labels unpredictable, e.g. a chunk with label foo may get \label{fig:foo-1} when the label is duplicated and knitr has automatically "corrected" it.

Should output_dir default to book?

This just seems like such a natural way to work to me, that I wonder if it shouldn't be the default. It seems fundamentally different to working on a single file - it feels more like preparing a website to publish, so like jekyll etc, it should default to putting all the files in a new directory.

chapter titles with math in them, e.g. subscripts, mess up the contents panel

If you do CO$_2$ as a chapter or section heading, the subscript will not show and the contents panel will have a big white space under it.

Icons on gitbook toolbar are invisible on iPhone

Haven't found out why. Scrolling/double-touching may make them visible show randomly. May need to bisect to figure out when the problem was introduced.

html_dependency problem

bookdown::render_book("index.rmd")
#> Error: path for html_dependency not found: /tmp/RtmpO4fv0m/widgetbindingcb3263a9aa9f 

traceback()
#> 10: stop("path for html_dependency not found: ", list$src$file, call. = FALSE) at html_dependencies.R#141
#> 9: FUN(X[[i]], ...) at html_dependencies.R#128
#> 8: lapply(dependencies, validate_html_dependency) at html_dependencies.R#93
#> 7: dependency_resolver(all_dependencies) at html_extras.R#13
#> 6: html_extras_for_document(knit_meta, runtime, dependency_resolver, 
#>   format_deps) at html_document_base.R#92
#> 5: base(...) at output_format.R#81
#> 4: output_format$pre_processor(yaml_front_matter, utf8_input, runtime, 
#>   knit_meta, files_dir, output_dir) at render.R#387
#> 3: rmarkdown::render(main, output_format, ..., clean = clean, envir = envir, 
#>   run_pandoc = TRUE, knit_meta = knit_meta) at render.R#129
#> 2: render_new_session(files, main, force_knit, output_format, clean, 
#>   envir, ...) at render.R#86
#> 1: bookdown::render_book("index.rmd")

Any ideas?

Navigation is not working in the preview of a book

When I preview the a book using the preview addin, or serve_book() the navigation doesn't work in the RStudio Viewer. When opened from the viewer into an external browser links are downloaded as html files, and not opened in the browser. If I open index.html for the same book directly in an external browser navigation works correctly.

When I open index.html of the book directly withservr::httw and servr::httd they show the same behaviour: links in the TOC are downloaded and not opened in the browser. The same index.html TOC works correctly when opened directly in an external browser.

Output format for single documents?

Is there an output document tailored for individual chapters? It's nice to be able to use the same cache and visual appearance while iterating on a single chapter.

Mention before_ and after_script in R code section

That seems like a natural place to cross-reference things related to running code.

Include version dep for servr package

To make sure you get a version with httw

Gitbook: add "edit me" link

That links back to github. This probably doesn't need to be built into the gitbook style, but there should be sufficient customisation ability that I can add it (maybe there already is but I don't know about it)

Gitbook: suppress "social links"

Like twitter, facebook etc

Missing title?

On http://www.frontendhandbook.com, when you hover over the top navbar, the name of the book comes up. That doesn't happen with bookdown, and when I look at the source the <h1> in the navbar is empty.

Think about gitbook performance

e.g. https://developers.google.com/speed/pagespeed/insights/?url=http%3A%2F%2Fr4ds.had.co.nz&tab=desktop

I think the main problem is that the gitbook app.js is 760 kb!! This seems ridiculously large.

Cross-Reference Section by Title

Currently, I can use @\ref{} to add a reference to a section, which will insert the numerical ID of the section. I'd prefer, in some cases, to have the link contain the section title (which may, of course, be different from the bookmark title). e.g.

You'll find more information in the '@\ref(somesect)' section.

## Something Here {#somesect}

My hope is that that would render as:

You'll find more information in the 'Something Here' section.

Maybe that requires an extra argument a la @\ref(somesect, title=TRUE). Even if I had to manually provide the text for the link, that would be a feasible work-around for now.

If output_dir is set, should _main.* live in that directory?

Or can those files be deleted after a successful run?

Object 'arry' not found in parse_fig_labels

Looks like a variable got missed in a recent refactor.

> bookdown::render_book('', bookdown::html_chapters())


processing file: _main.Rmd

  |                                                                       
  |                                                                 |   0%
  |                                                                       
  |.................................................................| 100%
  ordinary text without R code


output file: _main.knit.md

/usr/local/bin/pandoc +RTS -K512m -RTS _main.utf8.md --to html --from markdown+autolink_bare_uris+ascii_identifiers+tex_math_single_backslash --output _main.html --smart --email-obfuscation none --standalone --section-divs --table-of-contents --toc-depth 3 --template /usr/local/lib/R/site-library/bookdown/templates/default.html --number-sections --variable 'theme:bootstrap' --include-in-header /tmp/Rtmp6s3ilB/rmarkdown-str1606b35cffc.html --mathjax --highlight-style pygments --variable navigationjs=libs/navigation 
Error in parse_fig_labels(content) : object 'arry' not found
Calls: <Anonymous> ... split_chapters -> resolve_refs_html -> parse_fig_labels
Execution halted

Cmd + Shift + K loses place in html preview

Not exactly sure where this issue belongs but if you have:

---
knit: bookdown::preview_chapter

---

Then pressing Cmd + Shift + K always takes you to the top of the rendered document. This is obviously frustrating when you're working further down the chapter.

cc @jjallaire @jmcphers

html_name argument is a bit confusing

I think calling it split_by (say) would be more evocative of what it does

Make render_book() work?

By looking for _bookdown.yml in current directory, and adding document format metadata to it as well.

Turning a book into an R package

Are there any plans on automatically turning a book into an R package? Using travis, I've already specified a DESCRIPTION file with all my dependencies. Without thinking, I've added datasets to a data directory.

In order to make this a package I would:

• Move *.Rmd to inst/vignettes (this could easily be scripted)
• Any scripts to R/
• Perhaps tweak the DESCRIPTION file.

The "book" can then be installed and viewed as a vignette.

Self-contained format

When I create a self-contained HTML and remove the _book folder or move it to another directory, the content is ok, but the layout is strange with two scrollbars:

--- 
title: "Authoring A Book with R Markdown"
date: "`r Sys.Date()`"
author: "Dieter Menne"
knit: "bookdown::render_book"
output:
  bookdown::gitbook: 
    self_contained: true

---

# Index

yml:

book_filename: "dieter-bookdown.Rmd"
chapter_name: "Chapter "
rmd_files: [ "index.Rmd", "c.Rmd", "b.Rmd", "a.Rmd" ]

Set output directory

We run the following to compile HTML and PDF outputs

R -e "setwd('/data');" \
   -e "bookdown::render_book('', bookdown::html_chapters(lib_dir='out/assets'), output_dir='out');"
   -e "bookdown::render_book('', 'bookdown::pdf_book', output_file='out/_main.pdf', output_dir='out')"

the hope is that all output files would be rendered in ./out. It took some finagling to get that to work for both HTML and PDF, but it seems like the above set of options successfully executes. The issue is that the chapters HTML is still in the current directory, along with a slew of _main* files.

It would be great to have a way to avoid polluting the source tree and instead keep all rendered docs in a separate dir.

gitbook: allow user scaling

Currently have:

<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">

I think

<meta name="viewport" content="width=device-width, initial-scale=1">

Is more appropriate, because it's often useful to zoom into pictures etc.

Problem with knit and merge

When I set new_session:yes in bookdown.yml I get:

bookdown::render_book("index.rmd")
Error in (function (input, output_format = NULL, output_file = NULL, output_dir = NULL,  : 
  unused argument (run_pandoc = FALSE)
Calls: local ... eval -> eval -> eval -> eval -> do.call -> <Anonymous>
Execution halted

Does this suggest I have an out of date dependency?

default HTML output on iPad

Hi @yihui
When browsing the standard HTML output from bookdown on an iPad, there doesn't seem to be a way to collapse the sidebar containing the table of contents. So, when reading the bookdown or r4ds websites, the sidebar always takes up over 1/3 of the reading space on the iPad. It would be great if the default HTML output allowed one to collapse/expand the TOC, or to see TOC in a menu.

Thanks
Kyle

Include build tip in docs

Create a _build.sh that contains:

#!/usr/bin/env Rscript
bookdown::render_book("index.rmd")

Then chmod +x _build.sh

Then In RStudio, you can map Cmd + Shift + B to build the complete book by going to project options, build tools, select custom and then selecting _build.sh.

@jjallaire will this always get you the version of R that's running in RSudio?

In gitbook, is there an equivalent of the latex \part?

Many books are big enough that they need some organisation of chapters (e.g http://adv-r.had.co.nz). Does gitbook/bookdown offer any tools for this?

Next button has confusing click target

On safari (at least), if I hover over anywhere over the next button, my mouse pointer turns into the "clicky hand", but clicking does nothing. It's only if I'm over the text that clicking works to take me to the next page

Cross-referencing syntax

I just converted a large report from rmarkdown with css figure/caption numbering (rstudio/rmarkdown#522) to bookdown::html_document2. This worked nicely; great feature.

I am not so happy about the latex-lookalike syntax for cross-referencing. Since more than 3 year, there has been an inofficial standard in pandoc which needs some clumsy postprocessing, but worked once you got the setup done:

https://github.com/lierdakil/pandoc-crossref

Failing to find str_view again

https://travis-ci.org/hadley/r4ds#L2802

This is something in the intersection between dev stringr, htmlwidgets, and r4ds :/

Look into Calibre for converting EPUB to MOBI

Calibre is free and open-source: https://calibre-ebook.com/

Because Amazon's kindlegen has some restrictions https://www.amazon.com/gp/feature.html?docId=1000599251 It seems we are not allowed to use kindlegen on a server:

You may make one copy of the Software for back-up purposes. You may not use the Software over a network. All rights not expressly granted to you are reserved by Amazon.

Malformed remote specification when installing

I'm quite exited about the bookdown project and want to try it out and provide feedback. However, if I try to install bookdown either by cloning and installing the repository and or by running

devtools::install_github("rstudio/bookdown")

I get the error message

Installing bookdown
Error: Malformed remote specification 'rstudio/rmarkdown'

Installing the github version of rstudio/rmarkdown doesn't really fix it. Is there anything I can do to get it up and running?

TOC not floating in HTML, stuck at top

See: https://www.dropbox.com/s/5ej0fvf6dwydiia/ch1.html?dl=0

on latest master

Floating table of contents

See if this works after the document is split into chapters: rstudio/rmarkdown#600

Appendix

For LaTeX output, inserting \appendix is basically all we need to do. For HTML, there is no concept of "appendix", so we need some sort of hack to mark certain sections after a certain point to be appendices. (Requested by @aronatkins)

Add a period after the section number

e.g. 1. Section instead of the Pandoc default HTML output 1 Section