blogdown: Creación de sitios web con R Markdown

1.5 R Markdown vs. Markdown

Si no está familiarizado con R Markdown , consulte el Apéndice A para obtener un tutorial rápido. Cuando crea una nueva publicación, debe decidir si desea usar R Markdown o Markdown simple , como puede ver en Figure 1.2. Las principales diferencias son:

No puede ejecutar ningún código en R en un documento de Markdown simple, mientras que en un documento de Markdown R, puede incrustar fragmentos de código R (```{r}). Sin embargo, aún puede incrustar código de R en Markdown simple usando la sintaxis para bloques de código delimitados ```r(tenga en cuenta que no hay llaves {}). Tales bloques de código no se ejecutarán y pueden ser adecuados para propósitos de demostración pura. A continuación se muestra un ejemplo de un fragmento de código de R en R Markdown:
```
```{r cool-plot, fig.width='80%', fig.cap='A cool plot.'}
plot(cars, pch = 20)  # no es muy chévere
```
```
Y aquí hay un ejemplo de un bloque de código de R en Markdown simple:
```
```r
1 + 1  # no ejecutada
```
```
Una publicación en Markdown simple es ejecutada en HTML a través de Blackfriday (un paquete escrito en lenguaje Go y adoptado por Hugo). Un documento R Markdown se compila a través de los paquetes rmarkdown, bookdown, y Pandoc, lo que significa que puede usar la mayoría de las características de Markdown de Pandoc y extensiones de Markdown para bookdown en blogdown. Si usa R Markdown (Allaire et al. 2018) con blogdown, le recomendamos que lea la documentación de Pandoc y bookdown al menos una vez para conocer todas las características posibles. No repetiremos los detalles en este libro, pero enumeraremos las características brevemente a continuación, que también se muestran en el sitio web de ejemplo: https://blogdown-demo.rbind.io.
- Formateo en línea: texto en _italica_ / **negrita** y `código en línea`.
- Elementos en línea: subíndices (e.g., H~2~0) y superíndices (e.g., R^2^); links ([texto](url)) e imágenes ![título](url); notas al pie texto^[nota al pie].
- Elementos de nivel bloque: párrafos; encabezados de sección numerados y no numerados; listas ordenadas y no ordenadas; citas en bloque; bloques de código; tablas; reglas horizontales.
- Expresiones matemáticas y ecuaciones.
- Teoremas y demostraciones.
- Bloques de código en R que se pueden usar para producir salida de texto (incluidas tablas) y gráficos. Tenga en cuenta que las ecuaciones, teoremas, tablas y figuras se pueden numerar y referenciadas cruzadamente.
- Citas y bibliografía.
- HTML widgets, y aplicaciones en Shiny incrustadas mediante <iframe>.

Hay muchas diferencias en la sintaxis entre el Markdown de Blackfriday y el Markdown de Pandoc. Por ejemplo, puede escribir una lista de tareas con Blackfriday, pero no con Pandoc:

- [x] Escribir un paquete en R.
- [ ] Escribir un libro.
- [ ] ...
- [ ] Beneficio!

Del mismo modo, Blackfriday no admite matemática en LaTeX y Pandoc sí. Hemos agregado el soporte MathJax al tema predeterminado (hugo-lithium-theme en blogdown para compilar matemática en LaTeX en páginas HTML, pero hay una advertencia para las publicaciones simples de Markdown: debe incluir expresiones matemáticas en línea con un par de comillas `$math$`, por ejemplo, `$S_n = \ um_{i=1}^n X_i$`. Del mismo modo, las expresiones matemáticas del estilo de visualización deben escribirse en `$$math$$`. Para las publicaciones de R Markdown, puede usar $math$ para expresiones matemáticas en línea, y $$math$$ para expresiones de estilo de visualización.¹⁴

Si considera que es un dolor tener que recordar las diferencias entre R Markdown y Markdown, una opción conservadora es usar siempre R Markdown, incluso si su documento no contiene ningún fragmento de código en R. Markdown de Pandoc es mucho más rico que Blackfriday, y solo hay un pequeño número de características no disponibles en Pandoc pero presentes en Blackfriday. Las principales desventajas de usar R Markdown son:

Puede sacrificar algo de velocidad en la renderización del sitio web, pero esto puede no ser notorio debido a un mecanismo de almacenamiento en caché en blogdown (lea más sobre esto en la sección D.3). Hugo es muy rápido cuando procesa archivos de Markdown simples, y típicamente debería tomar menos de un segundo para renderizar unos cientos de archivos de Markdown.
Tendrá algunos archivos HTML intermedios en el directorio fuente de su sitio web, porque blogdown tiene que llamar a rmarkdown para renderizar previamente los archivos *.Rmd *.html. También tendrá carpetas intermedias para las figuras (*_files/) y la memoria caché (*_cache/) si tiene una salida de trazado en fragmentos de código en R o ha habilitado el almacenamiento en cache de knitr. A menos que le importe mucho la “limpieza” del repositorio fuente de su sitio web (especialmente cuando usa una herramienta de control de versiones como GIT), estos archivos intermedios no deberían importar.

En este libro, generalmente nos referimos a los archivos .Rmd cuando decimos “Documentos de R Markdown”, que se compilan a .html de forma predeterminada. Sin embargo, hay otro tipo de documento de R Markdown con la extensión de nombre de archivo .Rmarkdown. Dichos documentos de R Markdown se compilan para los documentos Markdown con la extensión .markdown, que serán procesados por Hugo en lugar de por Pandoc. Hay dos limitaciones principales de usar .Rmarkdown en comparación con.Rmd:

No puede usar las funciones de reducción solo compatibles con Pandoc, como las citas. Las expresiones matemáticas solo funcionan si ha instalado el paquete xaringan (Xie 2018 d) y ha aplicado la solución de JavaScript mencionada en la sección B.3.
Los widgets HTML no son compatibles.

La principal ventaja de usar .Rmarkdown es que los archivos de salida son más limpios porque son archivos Markdown. Puede ser más fácil para usted leer la salida de sus publicaciones sin mirar las páginas web reales renderizadas. Esto puede ser particularmente útil al revisar los pull requests de GitHub. Tenga en cuenta que las tablas, figuras, ecuaciones y teoremas numerados también son compatibles. No puede usar directamente la sintaxis de Markdown en las leyendas de tabla o figura, pero puede usar referencias de texto como una solución alternativa (consulte la documentación de bookdown).

Para cualquier documento de R Markdown (no específico de blogdown), debe especificar un formato de salida. Hay muchos posibles formatos de salida en el paquete rmarkdown (como html_document y pdf_document) y otros paquetes de extensión (tales como tufte::tufte_html y bookdown::gitbook). Por supuesto, el formato de salida para los sitios web debe ser HTML. Hemos proporcionado una función de formato de salida blogdown::html_page en blogdown, y todos los archivos R Markdown se renderizan con este formato. Se basa en el formato de salida bookdown::html_document2, lo que significa que ha heredado muchas características de bookdown además de las características en Pandoc. Por ejemplo, puede numerar y hacer referencias cruzadas de ecuaciones matemáticas, figuras, tablas y teoremas, etc. Consulte el Capítulo 2 del libro bookdown (Xie 2016) para obtener más detalles sobre la sintaxis.

Note que el formato de salida bookdown::html_document2 a su vez hereda de rmarkdown::html_document, entonces necesita ver la página de ayuda ?rmarkdown::html_document para todas las opciones posibles para el formato blogdown::html_page. Si desea cambiar los valores predeterminados de las opciones de este formato de salida, puede agregar un campo output a sus metadatos YAML. Por ejemplo, podemos agregar una tabla de contenido a una página, establecer el ancho de la figura en 6 pulgadas y usar el dispositivo svg para los gráficos estableciendo estas opciones en YAML:

---
title: "Mi grandiosa publicación"
author: "John Doe"
date: "2017-02-14"
output:
  blogdown::html_page:
    toc: true
    fig_width: 6
    dev: "svg"
---

Para establecer opciones para blogdown::html_page() globalmente (es decir, aplicar ciertas opciones a todos los archivos Rmd), puede crear un archivo _output.yml en el directorio raíz de su sitio web. Este archivo YAML debe contener el formato de salida directamente (no coloque el formato de salida bajo la opción output), por ejemplo,

blogdown::html_page:
  toc: true
  fig_width: 6
  dev: "svg"

Por el momento, no todas las funciones de rmarkdown::html_document son compatibles con blogdown, como df_print, code_folding,code_download, etc.

Si su trozo de código tiene salida de gráficos, le recomendamos que evite caracteres especiales como espacios en la etiqueta de fragmentos. Lo ideal es que solo use caracteres alfanuméricos y guiones, por ejemplo, ```{r, my-label} en lugar de ```{r, my label}.

No se recomienda cambiar las opciones knitr chunk fig.path o cache.path en R Markdown. Los valores predeterminados de estas opciones funcionan mejor con blogdown. Lea la sección ?? para conocer los motivos técnicos, si lo prefiere.

Si está trabajando en una publicación de R Markdown, pero no quiere que blogdown la compile, puede cambiar temporalmente su extensión de nombre de archivo de .Rmd a otra extensión desconocida como .Rmkd.

Referencias

Allaire, JJ, Yihui Xie, Jonathan McPherson, Javier Luraschi, Kevin Ushey, Aron Atkins, Hadley Wickham, Joe Cheng, and Winston Chang. 2018. Rmarkdown: Dynamic Documents for R. https://CRAN.R-project.org/package=rmarkdown.

Xie, Yihui. 2018d. Xaringan: Presentation Ninja. https://CRAN.R-project.org/package=xaringan.

Xie, Yihui. 2016. Bookdown: Authoring Books and Technical Documents with R Markdown. Boca Raton, Florida: Chapman; Hall/CRC. https://github.com/rstudio/bookdown.

El motivo por el que necesitamos los respaldos para documentos de Markdown simples es que tenemos que evitar que Blackfriday interprete el código LaTeX como Markdown. Las comillas asegurarán que el contenido interno no se traduzca como Markdown a HTML, por ejemplo, `$$x *y* z$$` se convertirá en <code> $$x *y* z$$</code>. Sin las comillas, se convertirá en $$x <em>y</em> z$$, que no es una expresión matemática en LaTeX válida para MathJax. Problemas similares pueden surgir cuando tenga otros caracteres especiales como guiones bajos en sus expresiones matemáticas.↩