How to Publish a Book With Bookdown
Table of Contents
Bookdown is an open-source R package that facilitates writing books and long-form articles/reports with R Markdown. In this example we will see an easy way for publishing bookdown books on GitLab pages. We will also see how to render the book locally and how to publish it on GitHub.
1 How to start your own book
To get started, we will use this bookdown example, which is a minimal example of a book that can be hosted and edited on GitLab.
- Go to https://gitlab.com/dashohoxha/bookdown-example and fork
it. It will be automatically published on the address
https://<username>.gitlab.io/bookdown-example/(but you may have to wait for a few minutes). For more details on why and how this works check the next section.
- Go to the "Settings" of the project and change the "Project name". Expand the "Advanced" section and change the project path as well.
index.Rmdand change any fields, like:
_bookdown.ymland change the field
- Change and modify the
*.mdfiles, and don't forget to update
_bookdown.ymlas well with the names of the new files.
- Optionally, you may also experiment with changing the look and
layout of the book by customizing
index.Rmd. For more details about the available options make sure to read:
2 How the book is auto-published on GitLab
You have already seen (in the previous section) that whenever you make
changes to the GitLab project
https://gitlab.com/<username>/<book-title>.git, the book is
automatically published and updated on the URL address
https://<username>.gitlab.io/<book-title>/. How does it happen?
The key to understanding this is the file
.gitlab-ci.yml, which has
a content like this:
image: dockerscripts/bookdown pages: script: - ./render.sh artifacts: paths: - public only: - master
This file instructs the CI/CD (Continuous Integration and Development) system of GitLab to do something whenever the content of the project is updated (for example some commits are pushed or a Merge Request is accepted).
image: dockerscripts/bookdown tells it to start a Docker
container based on the image dockerscripts/bookdown.
pages: tells it that this CI/CD job is about generating
the GitLab pages for this project. The content of the field shows how
to do it. Basically, in plain English, it says something like this:
- Clone the branch
masterof the project inside the Docker container,
- then run the script
./render.shin it (which is expected to generate the directory
public/with the content of the website that should be published),
- then get the content of the directory
public/and publish it on the website of the project:
You can check the page "CI/CD -> Pipelines" to see more details about the CI/CD jobs, whether they passed or failed, etc. This can be very useful especially when a job has failed, because you can also check the log messages and hopefully find out what was the problem.
3 How to add a custom domain
If you want to use a custom domain for the book you can do this from "Settings -> Pages".
For example for the book http://dashohoxha.gitlab.io/101-problema-programimi/ I have used as custom domain http://p101.fs.al, which is much shorter and convenient.
4 How to render and test the book locally
The details are described on: https://gitlab.com/docker-scripts/bookdown
Let's summarize them quickly:
- Install docker-scripts:
apt install m4 git clone https://gitlab.com/docker-scripts/ds /opt/docker-scripts/ds cd /opt/docker-scripts/ds/ make install
- Install wsproxy:
ds pull wsproxy ds init wsproxy @wsproxy cd /var/ds/wsproxy/ ds make
- Install bookdown container:
ds pull bookdown ds init bookdown @bookdown cd /var/ds/bookdown/ ds make
- Install the book bookdown-example:
cd /var/ds/bookdown/ git clone https://gitlab.com/dashohoxha/bookdown-example mv bookdown-example books/ ds render books/bookdown-example ds site add mybook.example.org books/bookdown-example
- Add on
Then open in browser:
You can edit
books/bookdown-example/ with any editor that you
like. Then, to update the page with the latest changes you run again
ds render books/bookdown-example/. This will regenerate the content
of the directory
books/bookdown-example/public/, which is being
Alternatively, you can update/regenerate it like this:
ds shell cd books/bookdown-example/ ./render.sh
5 How to publish the book on GitHub
Since GitHub pages support only Jekyll and plain HTML pages, the most easy way to publish a bookdown book on GitHub is to generate the HTML pages locally, as described on the previous section, and to push them on GitHub. You can do it like this:
- Edit the script
books/bookdown-example/render.shand add to it a command that creates an empty file named
echo 'touch public/.nojekyll' >> books/bookdown-example/render.sh
This will let GitHub know that the content of the
public/directory contains a plain HTML site, and it should not try to process it with Jekyll.
- Regenerate the
public/directory which contains the HTML files and other files that compose the website of the book:
ds render books/bookdown-example/
- Remove the file
.gitignorewhich prevents the directory
public/from being committed to Git, and commit this directory to Git:
cd books/bookdown-example/ cat .gitignore git rm .gitignore git add public git commit -m 'Add rendered book' git push
- Go to your repository’s settings and under "GitHub Pages" change the "Source" to be *"master branch /public folder"* (as described in this GitHub help page).
To update the page, after making some changes, you have to regenerate
public/ directory with
ds render books/bookdown-example/, and
to commit and push its changes to GitHub.
It is also possible to build an auto-update system with Travis CI, which would update the website of the book whenever some changes to the markdown files are committed and pushed to GitHub. This automated way is described in this help page. However it is a bit complex and maybe not worth the trouble.
6 The syntax of the markdown files
The format of the
*.Rmd files is basically the Pandoc's
Markdown syntax, which is described on this page as well:
However bookdown supports some further extensions, which are mainly useful for math. These extensions are described on this page: https://bookdown.org/yihui/bookdown/markdown-extensions-by-bookdown.html
Besides these, the syntax of GitLab markdown is a bit different from
that of Pandoc's Markdown. For example the delimiter of the math code
on Pandoc's Markdown is a single dollar sign, like this:
while that delimiter for GitLab Markdown is like this:
These small differences are fixed automatically by the script
render.sh, so that markdown files are rendered nicely both on the
GitLab web interface and on the website of the book.