Gitbook has been getting some (deserved) attention. For those who haven’t seen it, Gitbook is a system to create really beautiful interactive web (or PDF and ebook) books. For me, the timing of discovering this framework could not be better as I am preparing documentation for propensity score analysis for an upcoming workshop I am giving. Of course, I want to use it to write about R and would prefer to use R markdown instead of just plain markdown. I have written a number of R functions to combine the functionality of
knitr and Gitbook. The source code is on Gist or can be sourced directly using the
The first step is to create a new Gitbook. The
newGitbook will create a new directory and create four files.
.bookignore– This file is formatted like any
.gitignorefile, but is specifically for Gitbook. That is, list files here that you want Gitbook to ignore, but want Git to manage. This defaults to include
.Rprojfiles as well as the
logdirectory (this will be discussed below).
.gitignore– This defaults to include the
_bookdirectory. This is the default location for the built book and it is likely you do not want to include it in your master branch. As we will see below, this directory will be published to the
README.md– Introduction to your Gitbook.
SUMMARY.md– Defines the structure (i.e. table of contents) of your Gitbook.
You can get more information about how Gitbook is organized at their webiste gitbook.io.
> newGitbook('~/Dropbox/Projects/testbook') Creating /Users/jbryer/Dropbox/Projects/testbook Writing .bookignore... Writing .gitignore... Writing README.md... Writing SUMMARY.md... You can now open README.md and SUMMARY.md. Once you are done editting SUMMARY.md, initGitbook() will create the file and folder structure for your new Gitbook.
I should note that the
newGitbook will change the working directory to the location of your new Gitbook.
> getwd()  "/Users/jbryer/Dropbox/Projects/testbook"
And we can see the four files it created.
Jasons-MacBook-Air:testbook jbryer$ ls -la total 32 drwxr-xr-x 6 jbryer staff 204 Apr 18 10:52 . drwxr-xr-x 110 jbryer staff 3740 Apr 18 10:52 .. -rw-r--r-- 1 jbryer staff 35 Apr 18 10:52 .bookignore -rw-r--r-- 1 jbryer staff 49 Apr 18 10:52 .gitignore -rw-r--r-- 1 jbryer staff 75 Apr 18 10:52 README.md -rw-r--r-- 1 jbryer staff 231 Apr 18 10:52 SUMMARY.md
At this stage you can open
SUMMARY.md and change the outline of your book. Once you are done, the
initGitbook function will create the files and folders for your book. Unlike the Gitbook command line, this function will change the file extensions of all your files to
SUMMARY.md) even though you specify
.md in the links in that file. The
buildRmd function discussed below will convert those
.Rmd files to
buildRmd function will convert all
.Rmd files in your project to
.md using the
knitr package. It should be noted that this function will create a file,
.rmdbuild.Rda, in your working directory. This is an R data file that saves the status of the last build. This allows this function to only build R markdown files that have changed since the last build and therefore, increase the execution time. By default, all the
knitr messages will be printed to the console. If you specify
log.dir parameter, then all the output will be saved to log files in that given directory (one log file per Rmd file). There is also a
clean parameter that will build all R markdown files regardless of their modification timestamp.
buildGitbook function is simply a wrapper to the Gitbook command line and will generate your book from the markdown sources. As of this writing, there is a bug in Gitbook where the image URLS are incorrect. This function will fix the URLs. There is also another issue that links to the Introduction point to
/ and not
/index.html. These will also be fixed.
openGitbook will open your built book using your system’s default web browser.
publishGitbook will publish your built Gitbook to the
gh-pages branch of the specified Github repository. Special thanks to Ramnath Vaidyanathan who provided the shell script to do this. Take a look at the link as you can optionally save this as a Git hook to publish atomically after checking in code to the master branch.
Please leave comments below or suggestions to make this better. I would also be interested if there is interest in rolling this up into an R package.
Here is the source code: