Chapitre 11 Pour aller plus loin sur Pagedown

Pagedown est une implémentation pour Rmarkdown de paged.js, qui permet de réaliser des documents html paginés.

C’est un outil puissant pour concilier les fonctionnalités HTML (donc mise en formes CSS) et la possibilité d’impression PDF, galerie :

knitr::include_url("https://dreal.statistiques.developpement-durable.gouv.fr/parc_social/2020/www/export_demarchePropre.pdf")

11.1 Paged.js

paged.js est une bibliothèque javascript visant à mettre en oeuvre [les propriétés css dédiées au médias paginés(https://www.w3.org/TR/css-page-3/) du W3C.

Ces spécifications visent à pouvoir réaliser des documents prêt pour l’impression avec les technologies du web (html, css, js).

Ces spécifications sont toujours en draft pour le moment au sein du W3C, donc pas vraiment reconnues par les principaux navigateurs. D’où le besoin de cette bibliothèque javascript pour pouvoir les mettre en oeuvre.

11.2 Démarrer avec Pagedown

Pour installer {pagedown} depuis le CRAN :

install.packages('rstudio/pagedown')

Depuis Rstudio, cela vous apporte un nouveau type de document rmarkdown, accessible depuis File -> New File -> Rmarkdown... -> From template -> Paged HTML document.

Une fois celui ci créé, vous pouvez cliquer sur knit de l’interface de Rstudio. Cela vous compilera le document par défaut en html, qui sera accessible dans le répertoire du projet et visible par défaut dans le viewer.

La structure du yaml est relativement proche d’un document Rmarkdown classique.

A noter toutefois une option utile à retenir, la balise knit: pagedown::chrome_print qui vous permet de compiler directement votre document en pdf grâce à la fonction pagedown::chrome_print() livrée dans le package.

Cette fonction par ailleurs peut être utilisée pour imprimer en pdf tout document html en pdf ou en format image. Elle utilise la technologie d’impression de google chrome.

title: "A Multi-page HTML Document"
author: "Yihui Xie and Romain Lesur"
date: "2026-03-09"
output:
  pagedown::html_paged:
    toc: true
    \# change to true for a self-contained document, but it'll be a litte slower for Pandoc to render
    self_contained: false
\# uncomment this line to produce HTML and PDF in RStudio:
\#knit: pagedown::chrome_print

11.3 Configurer votre yaml

Les documents html paginés étant destinés à être imprimés, l’entête yaml d’un document Pagedown contient des options du yaml spécifiques. En voici quelques unes intéressantes à connaître :

  • Pour modifier le titre du sommaire du document :
toc-title: sommaire
  • Pour ajouter et configurer une liste de tableaux et de graphiques dans le sommaire.
lot: true
lot-title: "Tableaux"
lof: true
lof-title: "Graphiques"

Si vous ne voulez pas que les graphiques et tableaux apparaissent dans le sommaire, vous pouvez utiliser lot-unlisted: true.

  • Pour modifier le préfixe du titre du chapitre.
chapter_name: "Chapitre\\ "

Vous pouvez ensuite insérer un chapitre en utilisant # Ceci est un titre de chapitre {.chapter}

  • Pour transformer automatiquement un lien url dans votre document en note de bas de page.
links-to-footnotes: true

Ainsi [CRAN](https://cran.r-project.org/) sera traduit comme CRAN^[(https://cran.r-project.org/)].

  • front_cover et back_cover pour ajouter une image pour la première de couverture et la 4e de couverture :
  pagedown::html_paged:
    front_cover: !expr system.file("help","figures","lter_penguins.png", package = "palmerpenguins")
    back_cover: https://www.r-project.org/Rlogo.png

On utilise le préfixe !expr pour insérer du code R créant en sortie une image.

11.4 Quelques balises importantes à connaître

{.page-break-before} et {.page-break-after} sont des classes CSS qui insèrent un saut de page avant/après le paragraphe auquel la balise est attachée.

### Nouveau chapitre après un saut de page {.page-break-before}

11.5 Modifier le CSS

Apprendre à customiser un document pagedown va vous demander d’investir sur l’apprentissage du CSS en général et de pagedjs en particulier pour construire un template ad hoc.

C’est un investissement en soit, qui pourra vous être utile de la même façon que la gestion de la mise en page d’un document bureautique.

Vous pouvez aussi centraliser cet investissement pour votre équipe sur une ou deux personnes, ou travailler avec votre service web sur vos projets.

Quelques ressources pour apprendre le CSS :

Voici déjà quelques recettes de base pour commencer à modifier votre document.

Première étape : importer les css par défaut de pagedown dans votre document.

files <- c("default-fonts", "default-page", "default")
from <- pagedown:::pkg_resource(paste0("css/", files, ".css"))
to <- c("custom-fonts.css", "custom-page.css", "custom.css")
file.copy(from = from, to = to)

Ajouter une référence à ces fichiers dans le yaml :

output:
  pagedown::html_paged:
    css:
    - custom-fonts.css
    - custom-page.css
    - custom.css
    toc: true
    self_contained: false

  • Lancer dans la console xaringan::inf_mr(), qui permet de compiler un document Rmarkdown en ayant un aperçu live du rendu.

  • Appuyer ensuite sur Show in new window pour consulter le document sur votre navigateur par défaut.

  • Puis sur Clear all viewer item, pour que vos modifications puisse s’afficher en live.

11.6 Configurer votre CSS

Vous pouvez commencer à modifier vos fichiers css et voir le résultats immédiatement.

Les 3 fichiers correspondent aux éléments suivants :

  • custom-fonts.css correspond aux polices de caractères
  • custom-page.css correspond aux paramètres de la page (format de la page, orientation,…)
  • custom.css intègre entre autre la façon dont les pages sont affichées à l’écran (couleur de fond, espacement entre les pages…)

11.7 Exemple d’usage : le modèles de 4 pages Info rapides Justice du SSER

Le Rmd modèle s’installe avec le package {chartegraphique.sser} :

devtools::install_gitlab(repo="sser/chartegraphique.sser@master",
                         host="https://git.lab.sspcloud.fr",
                         dependencies = TRUE,
                         upgrade = FALSE)

Après avoir redémarré R, on a une nouvelle entrée dans le menu File / New File / R Markdown... / From Template

Cliquer sur cette nouvelle entrée permet d’accéder au document, puis de le compiler pour accéder au résultat.

<<<<<<<< HEAD:03_rmarkdown_decortique_exo.Rmd

======== >>>>>>>> dev:10_exo2_rmarkdown_decortique_exo.Rmd > info importante! je n’arrive pas à installer TinyTex avec cette commande: tinytex::install_tinytex(). j’ai une erreur “Error in extract(pkg, exdir = path.expand(target)) : cannot open file ‘C:/Users/caroline.coudrin/AppData/Roaming/TinyTeX/tl-tray-menu.exe’: Permission denied”. du coup je ne peux pas tester le format PDF.