Chapitre 5 R Bookdown

Bookdown (Xie 2017 b) est un package R développé par Yihui Xe qui permet d’écrire des livres en format Rmarkdown pour les publier en pdf (via latex), epub, gitbook. Le principe de base consiste à utiliser un fichier Rmarkdown par chapitre.

Une documentation assez exhaustive écrite pour l’auteur est disponible

https://bookdown.org/yihui/bookdown/.

Et une anti-sèche est disponible

http://www.pzhao.org/en/post/bookdown-cheatsheet/.

Ce chapitre vise simplement à décrire notre expérience du l’utilisation du package.

5.1 Mise en oeuvre principe

1 . Installer le package bookdown via la CRAN ou bien via devtools

install.packages("devtools")
devtools::install_github("rstudio/bookdown")

Utiliser RStudio pour créer un répertoire “bookproject”
Par défaut les fichiers RMarkdown du répertoire du “bookproject” deviendront des chapitres, ordonnés ordres alphanumériques. Il est possible d’utiliser le fichier _bookdown.yml pour changer l’ordre des chapitres.
La compilation peut être effectué pour un clic sur Build Book ou par la ligne

rmarkdown::render_site(output_format = 'bookdown::gitbook', encoding = 'UTF-8')

Les formats de sortie possibles sont

- pdf
- gitbook
- epub

Publication (voir section 5.2 )

5.2 Publication du livre sur GitHub

Il existe de nombreuses possiblilités de publication mais nous avons testé la solution github utilisant un répertoire docs

Créer un repository git pour y mettre le contenu du bookproject

Nommer le répertoire de sortie docs (à la place de _book) en ajoutant dans le fichier de configuration _bookdown.yml la ligne suivante

output_dir: "docs"

Dans le répertoire “docs” ajouter un fichier vide caché nommé .nojekyll

{bash, eval=FALSE, echo=TRUE}
touch .nojekyll
git add .nojekyll

Le livre est alors accessible à l’adresse

https://user.github.io/project/

dans notre cas

https://cambroise.github.io/stateofther2017/

References

Xie, Yihui. 2017b. Bookdown: Authoring Books and Technical Documents with R Markdown. https://github.com/rstudio/bookdown.