Rmd: document HTML

Markdown a été conçu à l'origine pour la sortie HTML. Pour créer un document HTML à partir de R Markdown, spécifier le format de sortie html_document dans les métadonnées YAML de votre document:

--- 
 title:  Habits 
 author:  John Doe 
 date:  March 22, 2005 
 output:  html_document 
--- 

Ajouter une table des matières à l'aide de l'option toc et spécifier la profondeur des en-têtes auxquels elle s'applique à l'aide de l'option toc_depth . Par exemple:

---
title:   "Habits" 
output: html_document: 
  toc:  true 
  toc_depth:  2 
--- 

Si la profondeur de la table des matières n'est pas explicitement spécifiée, la valeur par défaut est 3 (ce qui signifie que tous les en-têtes de niveau 1, 2 et 3 seront inclus dans la table des matières).

Spécifier l'option toc_float pour faire flotter la table des matières à gauche du contenu du document principal. La table des matières flottante sera toujours visible même lorsque le document est déroulé. Par exemple:

--- 
title:   "Habits" 
output: html_document: 
  toc:  true 
  toc_float:  true
--- 

Eventuellement spécifier une liste d'options pour le paramètre toc_float qui contrôlent son comportement. Ces options comprennent:

• collapsed (par défaut, TRUE ) contrôle si la table des matières apparaît uniquement avec les en-têtes de niveau supérieur (par exemple, H2). Si elle est initialement réduite, la table des matières est automatiquement développée en ligne si nécessaire.
• smooth_scroll (la valeur par défaut est TRUE ) détermine si les défilements de page sont animés lorsque les éléments de la table des smooth_scroll via des clics de souris.

Par exemple:

--- 
title:   "Habits" 
output: html_document: 
  toc:  true 
  toc_float: 
     collapsed:  false 
     smooth_scroll:  false 
--- 

Ajouter une numérotation de section aux en-têtes à l'aide de l'option number_sections :

--- 
title:   "Habits" 
output: html_document: 
  toc:  true 
  number_sections:  true 
--- 

On peut organiser le contenu à l'aide d'onglets en appliquant .tabset aux en-têtes d'un document. Ainsi, tous les sous-en-têtes de l'en-tête avec l'attribut .tabset apparaîtront dans des onglets plutôt que sous forme de sections autonomes. Par exemple:

 ## Quarterly Results {.tabset} 
 ### By Product (tab content) 
 ### By Region (tab content) 

On peut également spécifier deux attributs supplémentaires pour contrôler l'apparence et le comportement des onglets:

• .tabset-fade provoque l'effacement des onglets lors du basculement entre les onglets.
• .tabset-pills fait en sorte que l'aspect visuel des onglets soit d'aspect “pillule” plutôt que des onglets traditionnels. Par exemple:

  ## Quarterly Results {.tabset .tabset-fade .tabset-pills} 

Plusieurs options permettent de contrôler l'apparence des documents HTML:

• theme spécifie le thème Bootstrap à utiliser pour la page (les thèmes sont tirés de la bibliothèque de thèmes de Bootswatch ). Les thèmes valides sont les suivants: défaut, céruléen, journal, plat, sombre, lisible, spacelab, uni, cosmo, lumière, papier, grès, simplex et yeti. Passez null pour aucun thème (dans ce cas, vous pouvez utiliser le paramètre css pour ajouter vos propres styles).
• highlight spécifie le style de surbrillance de la syntaxe. Les styles pris en charge comprennent les styles par default , tango , pygments , kate , monochrome , espresso , zenburn , haddock et textmate . Passez null pour empêcher la coloration syntaxique.
• smart (activé par défaut) indique s'il faut produire une sortie typographiquement correcte, en convertissant les guillemets droits en guillemets bouclés, — d-tirets, – en tirets, et … en ellipses.

Par exemple:

--- title:   "Habits" 
output: html_document: 
  theme:  united 
  highlight:  tango 
--- 

On peut ajouter des CSS à un document HTML à l'aide de l'option css :

--- title:   "Habits" 
output: html_document: 
css:  styles.css 
--- 

Pour fournir un styles à tout du document à partir d'un CSS, définir le theme (et éventuellement le highlight ) sur null :

--- 
title:   "Habits" 
output: html_document: 
   theme:   null 
   highlight:   null 
css:  styles.css 
--- 

On peut également cibler des sections spécifiques de documents avec des CSS personnalisées en ajoutant des identifiants ou des classes aux en-têtes de section du document. Par exemple, l'en-tête de section suivant:

## Next Steps {#nextsteps .emphasized} 

Permettrait d'appliquer CSS à tout son contenu à l'aide de l'un des sélecteurs CSS suivants:

#nextsteps { color : blue ; } .emphasized { font-size : 1.2em ; } 

Un certain nombre d’options affectent la sortie des figures dans les documents HTML:

• fig_width et fig_height peuvent être utilisés pour contrôler la largeur et la hauteur de la figure par défaut (7×5 est utilisé par défaut).
• fig_retina spécifie la mise à l'échelle à effectuer pour les affichages de rétine (la valeur par défaut est 2, ce qui fonctionne actuellement pour tous les affichages de rétine largement utilisés). Définir sur null pour empêcher la mise à l'échelle de la rétine.
• fig_caption contrôle si les figures sont rendues avec des légendes.
• dev contrôle le périphérique graphique utilisé pour rendre les figures (par défaut, png ).

Par exemple:

--- 
title:   "Habits" 
output: html_document: 
  fig_width:  7 
  fig_height:  6 
  fig_caption:  true 
--- 

On peut améliorer l'affichage par défaut des trames de données via l'option df_print . Les possibles de l'option dfprint pour le format htmldocument sont:

Lorsque l'option df_print est définie sur paged, les tables sont imprimées sous forme de tables HTML prenant en charge la pagination sur des lignes et des colonnes. Par exemple :

--- 
title: "Motor Trend Car Road Tests" 
output: html_document:  
  df_print: paged 
--- 
```
{r} mtcars 
``` 

Options pour les tables HTML paginées.

Ces options sont spécifiées dans chaque bloc comme ci-dessous:

```
{r cols.print=3, rows.print=3} 
mtcars 
``` 

Lorsque l'option knitr chunk echo = TRUE est spécifiée (comportement par défaut), le code source R contenu dans les fragments est inclus dans le document rendu. Dans certains cas, il peut être approprié d'exclure entièrement le code ( echo = FALSE ), mais dans d'autres cas, peut-être que le code devrait être disponible mais ne soit pas visible par défaut.

L'option code_folding: hide permet d'inclure du code R mais de le masquer par défaut. Les utilisateurs peuvent ensuite choisir d'afficher les fragments de code R masqués individuellement ou dans l'ensemble du document. Par exemple:

--- 
title: "Habits" 
output: html_document:  
  code_folding: hide 
--- 

On peut spécifier code_folding: show pour toujours afficher tout le code R par défaut, puis autoriser les utilisateurs à masquer le code s'ils le souhaitent.

Par défaut, les scripts MathJax sont inclus dans les documents HTML pour le rendu des équations LaTeX et MathML. On peututiliser l'option mathjax pour contrôler la manière dont MathJax est inclus:

• Spécifier default pour utiliser une URL HTTPS à partir d'un hôte CDN (actuellement fourni par RStudio).
• Spécifier local pour utiliser une version locale de MathJax (qui est copiée dans le répertoire de sortie). Lorsqu'on utilise “local” on doit également définir l'option self_contained sur false.
• Spécifier une autre URL pour charger MathJax à partir d'un autre emplacement.
• Spécifier null pour exclure entièrement MathJax.

Par exemple, pour utiliser une copie locale de MathJax:

--- 
title:   "Habits" output: 
html_document: 
  mathjax: local 
  self_contained:  false 
--- 

Pour utiliser une copie auto-hébergée de MathJax:

--- 
title:   "Habits" 
output: html_document: 
  mathjax:   "http://example.com/MathJax.js" 
--- 

Pour exclure entièrement MathJax:

--- 
title:   "Habits" 
output: html_document: 
  mathjax:   null 
--- 

Par défaut, R Markdown génère des fichiers HTML autonomes sans dépendance externe, à l'aide de data: URI pour incorporer le contenu de scripts, de feuilles de style, d'images et de vidéos liés. Cela signifie qu'on peut partager ou publier le fichier exactement comme on partage des documents Office ou des PDF. Si on préfér conserver les dépendances dans des fichiers externes, spécifier self_contained: false. Par exemple:

--- 
title:   "Habits" 
output: html_document: 
self_contained:  false 
--- 

L'une des raisons courantes de conserver les dépendances externes est de servir les documents R Markdown à partir d'un site Web (les dépendances externes peuvent être mises en cache séparément par les navigateurs, ce qui accélère le chargement des pages). Pour également consolider les fichiers de bibliothèque dépendants (par exemple, Bootstrap et MathJax, etc.) dans un seul répertoire partagé par plusieurs documents, utiliser l'option lib_dir. Par exemple:

--- 
title:   "Habits" 
output: html_document: 
self_contained:  false 
lib_dir:  libs 
--- 

Lorsque knitr traite un fichier d'entrée R Markdown, il crée un fichier Markdown (*.md) qui est ensuite transformé en HTML par Pandoc. Pour conserver une copie du fichier Markdown après le rendu, utiliser l'option keep_md:

--- 
title:   "Habits" 
output: html_document: 
keep_md:  true 
--- 

On peut personnaliser davantage la sortie en ajoutant du contenu HTML supplémentaire ou en remplaçant entièrement le modèle Pandoc principal. Pour inclure le contenu dans l'en-tête du document ou avant / après le corps du document, utiliser l'option includes comme suit:

--- 
title: "Habits" 
output: html_document:  
includes:  
  in_header: header.html  
  before_body: doc_prefix.html  
  after_body: doc_suffix.html 
--- 

On peut également remplacer le modèle Pandoc sous-jacent à l’aide de l’option template :

--- 
title:   "Habits" 
output: html_document: 
  template:  quarterly_report.html 
--- 

Par défaut, R Markdown est défini comme toutes les extensions Pandoc Markdown avec les modifications suivantes pour la compatibilité en amont avec l'ancien package de démarques (J. Allaire, Horner, et al. 2018 ) :

+autolink_bare_uris 
+ascii_identifier 
+tex_math_single_backslash 

On peut activer ou désactiver les extensions de Markdown à l'aide de l'option md_extensions. Par exemple:

--- 
title:   "Habits" 
output: html_document: 
md_extensions:  
  -autolink_bare_uris
  +hard_line_breaks 
--- 

Ce qui précède désactiverait l'extension autolink_bare_uris et activerait l'extension hard_line_breaks.

Pour utiliser certaines fonctionnalités Pandoc n'ayant pas leur équivalent dans les options YAML, utiliser en transmettant des arguments pandoc_args personnalisés. Par exemple:

--- title:   "Habits" 
output: html_document: 
  pandoc_args: 
    [ "--title-prefix" , "Foo" , "--id-prefix" , "Bar" ] 
--- 

Pour spécifier un ensemble d'options par défaut à partager par plusieurs documents dans un répertoire, inclure un fichier nommé _output.yml dans le répertoire. Aucun délimiteur YAML ( — ) ni champ de output englobant ne sont utilisés dans ce fichier. Par exemple:

 html_document: 
   self_contained:  false 
   theme:  united
   highlight:  textmate 

Il ne devrait pas être écrit comme ceci :

--- 
output: html_document: 
  self_contained:  false 
  theme:  united 
  highlight:  textmate 
--- 

Pour créer un fragment HTML plutôt qu'un document HTML complet, on peut utiliser le format html_fragment . Par exemple:

--- 
output:  html_fragment 
---