Sommaire
{bookdown}, à quoi ça sert ?
Ok, arrêtons de jouer aux groupies et revenons-en à nos moutons. {bookdown} est un package R qui permet de créer des livres via R, de la même manière que nous créons des documents à l’aide de R Markdown. Il s’appuie d’ailleurs sur {rmarkdown}, hérite donc de la simplicité de la syntaxe markdown, et permet aussi plusieurs formats de sortie : html, pdf, Word. Le style Gitbook ou le pdf_book par dessus et le tour est joué, vous avez un beau livre numéroté avec accès aux chapitres et tout le toutim. Regardons maintenant quelques exemples :- La documentation du package
{bookdown}
itself : https://bookdown.org/yihui/bookdown/ - Un bookdown sur la création de packages, écrit par Hadley Wickham et Jennifer Bryan: https://r-pkgs.org/
- Un bookdown pour créer des applications Shiny prêtes pour la mise en production rédigé par vos serviteurs chez ThinkR : https://engineering-shiny.org/
- Pour d’autres exemples, c’est par là : https://bookdown.org/home/archive/
{bookdown}
peut être utilisé simplement pour créer un livre numérique qui ne sera constitué que de quelques fichiers RMarkdown que l’on souhaite lire linéairement en une séquence, ou encore pour mettre en page sa prise de notes de cours, rédiger sa thèse, le rapport de ce projet que l’on vient de terminer, … Écrire un livre numérique avec {bookdown} a également de nombreux avantages :
- On ne se soucie pas de la composition du document
- Cela nous évite d’utiliser le langage LateX directement, has been et relativement compliqué quand on ne connait pas
- La collaboration autour de la rédaction s’en trouve largement simplifiée
- Les multiples formats de sorties possibles (PDF, HTML, Word)
- On peut également intégrer du contenu dynamique et interactif aux livre HTML
![bookdown engineering-shiny.org](https://thinkr.fr/wp-content/uploads/bookdown-engineering-shiny-org-e1587894805113.png)
gitbook HTML : “Engineering Production-Grade Shiny Apps” rédigé avec {bookdown}
Votre premier bookdown
Avant de commencer
Ne mettons pas la charrue avant les bœufs. Avant de pouvoir écrire notre book, plusieurs choses vont être nécessaires. Déjà, on commence par installer le package. La version stable du CRAN :install.packages("bookdown")
library(bookdown)
ou la version en développement sur GitHub :
devtools::install_github('rstudio/bookdown')
library(bookdown)
Nous avons également besoin d’une distribution de packages LaTeX pour la création de PDF, et pour ce faire, on télécharge le package {tinytext}
et on l’installe (attention, cela peut prendre pas mal de temps) :
install.packages('tinytex')
tinytex::install_tinytex()
Il vous faudra ensuite connaître les bases de RMarkdown, je vous conseille vivement de visiter cette page : https://rmarkdown.rstudio.com/ et de consulter autant qu’il le faudra la cheatsheet suivante : https://rstudio.com/wp-content/uploads/2016/03/rmarkdown-cheatsheet-2.0.pdf
Une fois les bases acquises, venons-en au fait.
Création du nouveau book
La création d’un book commence par la création d’un nouveau projet. Dans RStudio : File -> New Project… -> New Directory. L’installation du package{bookdown}
a introduit une nouvelle ligne à la liste de choix de type de projet :
![](https://thinkr.fr/wp-content/uploads/bookdown-new_proj.png)
![](https://thinkr.fr/wp-content/uploads/bookdown-files.png)
---
title: "A Minimal Book Example"
site: bookdown::bookdown_site
documentclass: book
bibliography: [book.bib, packages.bib]
biblio-style: apalike
link-citations: yes
description: "This is a minimal example of using the bookdown package to write a book. The output format for this example is bookdown::gitbook."
---
- Un livre contient typiquement plusieurs chapitres. Ici, chaque fichier RMarkdown constitue un chapitre :
01-intro.Rmd
,02-literature.Rmd
, etc. Par défaut, tous les RMarkdown sont pris en compte, dans l’ordre alphanumérique, excepté le fichierindex.Rmd
qui passe toujours en premier. Chaque fichier .Rmd doit commencer par un titre de niveau avec le nom du chapitre. Par exemple, le fichier02-literature.Rmd
commence par :
# Literature
- Le fichier
_bookdown.yml
est un fichier au format YAML contenant les métadonnées de notre livre. Si on souhaite faire apparaître seulement certains RMarkdown, ou dans un ordre différent, on l’indique dans ce fichier de la façon suivante :
rmd_files: ["index.Rmd", "03-method.Rmd", "01-intro.Rmd"]
- Le fichier
_output.yml
permet de définir les caractéristiques des formats de sortie. Vous avez noté que lorsqu’on rédige un fichierRMarkdown
, on se pré-occupe uniquement du contenu. Pour la forme, elle est gérée à part, avec des fichiers de configuration spécifiques au format HTML, LateX pour une sortie PDF ou un fichier de styles Word. Vous pouvez notamment créer vos propres templates d’entreprise ou d’organisation pour tous les documents internes ou à diffuser, une bonne fois pour toutes ! Le fichier_output.yml
permet donc d’ajouter les éléments de forme à nos pages, notamment une feuille de style css, ou encore du texte et des liens avant ou après la liste des chapitres :
bookdown::gitbook:
css: style.css
config:
toc:
before: |
<li><a href="./">A Minimal Book Example</a></li>
after: |
<li><a href="https://github.com/rstudio/bookdown" target="blank">Published with bookdown</a></li>
Attention : Tous les fichiers doivent être encodés en UTF-8
Ok, et maintenant, on regarde à quoi il ressemble ce book ? Comme lorsqu’on développe un package R, on retrouve l’onglet Build, et il suffit de cliquer sur le bouton Build Book :
![](https://thinkr.fr/wp-content/uploads/bookdown-build.png)
bookdown::render_book(
input = "index.Rmd",
output_format = "bookdown::gitbook",
output_dir = "docs")
Les bonus de {bookdown}
par rapport à {rmarkdown}
Le package {bookdown}
comble les manques de syntaxe de {rmarkdown}
pour la rédaction de documents :
- Créer des légendes pour vos graphiques et tables avec un formattage markdown. Dans le chunk qui crée votre table ou image, vous pouvez utiliser le paramètre
fig.cap
pour ajouter une légende. Lorsqu’on a de longues légendes de tables ou de graphes, ou lorsqu’on souhaite formatter le texte (e.g. texte en italique ou url), il est possible de rédiger en dehors du chunk avec la syntaxe markdown. Par exemple :
_Notez qu'il est nécessaire d'avoir une ligne vide au-dessus et en-dessous de la ligne où l'on écrit la légende._
(ref:maref) Un *scatterplot* des données `cars`
```{r foo, fig.cap='(ref:maref)'}
plot(cars)
```
Notez qu’il est nécessaire d’avoir une ligne vide au-dessus et en-dessous de la ligne où l’on écrit la légende.
![](https://thinkr.fr/wp-content/uploads/bookdown-fig1.png)
- Faire référence à des chapitres, des figures et des tableaux dans le texte du document. Utiliser la notation
{#titre}
pour nommer la référence à un titre du document. Utiliser\@ref(titre)
pour y faire référence dans le texte. Fonctionnez de la même manière pour faire référence à une figure en ajoutant le prefixe de labelfig
comme ci-dessous avec\@ref(fig:pression)
:
## Titre précédent {#avant}
Du texte.
## Réferences
Faites référence à la figure \@ref(fig:pression).
Mais aussi au chapitre précédent (chapitre \@ref(avant)).
(ref:pressioncap) La légende du graphique.
```{r pression, fig.cap='(ref:pressioncap)'}
plot(pressure)
```
![](https://thinkr.fr/wp-content/uploads/bookdown-text-reference.png)
- numéroter et référencer les équations :
\begin{equation}
f\left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k}
(\#eq:binom)
\end{equation}
\@ref(eq:binom)
Notez que {bookdown} comme {rmarkdown} permet d’écrire les équations au format LateX. L’équation ci-dessus apparaît donc comme sur l’équation (1)
![](https://thinkr.fr/wp-content/uploads/bookdown_equation_1.png)
- écrire des théorèmes, lemmes, corrollaires, etc… qui sont numérotés :
```{theorem}
Ceci est mon théorème.
```
![](https://thinkr.fr/wp-content/uploads/bookdown-th1.png)
![](https://thinkr.fr/wp-content/uploads/bookdown-theorems.png)
{theorem}
par {definition}
dans le code ci-dessus.
Il est aussi possible de nommer un théorème, notamment pour pouvoir y faire référence :
```{theorem, name = "Pythagore"}
Pour un triangle rectangle, si $C$ désigne la longuur de l'hypothénuse et
$A$ et $B$ la longeur des deux autres cotés, alors on a :
$$A^2 + B^2 = C^2$$
```
![](https://thinkr.fr/wp-content/uploads/bookdown-th2.png)
- de la même manière, écrire des preuves, remarques ou solutions, qui sont elles non numérotées, en utilisant respectivement
proof
,remark
, etsolution
. L’intérêt de ces classes particulières c’est qu’elles peuvent être customisée spécifiquement dans une feuille de style adaptée.
```{css}
.remark {
color: red;
}
```
```{remark}
Voici notre remarque
```
![](https://thinkr.fr/wp-content/uploads/bookdown-remark.png)
![bookdown-template-pdf-avec-pdfreport](https://thinkr.fr/wp-content/uploads/bookdown-pdfreport-e1587895372253.png)
Création de template PDF avec {pdfreport}
Laisser un commentaire