-
Notifications
You must be signed in to change notification settings - Fork 1
/
08_publicacion.qmd
152 lines (102 loc) · 8.9 KB
/
08_publicacion.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
---
title: "Publicando reportes"
toc: true
format:
html:
code-tools: true
self-contained: true
execute:
message: false
warning: false
---
Querés compartir tus resultados y tenés un archivo RMarkdown o Quarto en el que estuviste trabajando. Podrías compartir la carpeta del proyecto o un link a un repositorio pero sería ideal que cualquier persona pueda ver esos hermosos resultados sin necesidad de correr código. La otra alternativa es knitear el documento para compartir un PDF o archivo de Word. Las opciones no terminan ahí, Rmarkdown/Quarto abre un mundo de posibilidades para trabajar con código de R, texto y además compartir los resultados (y cualquier otra cosa!).
## Sitio web de una sola página
Si sabés cómo generar un reporte en formato html usando R Markdown, ¡ya sabés todo lo que necesitás para publicar un sitio web simple! Lo único que hace falta es un servicio que *hostee* el archivo y lo muestre a los visitantes. Uno de ellos es [Netlify](https://www.netlify.com/), que permite crear un sitio web con sólo arrastrar una carpeta.
**Pequeño detalle:** seguramente tu reporte (tu archivo RMarkdown o de Quarto) tiene algún nombre descriptivo consistente con su contenido. Para que *convertirlo* en una página web el archivo tiene que tener un nombre especial: "index.html". Adelante, nombrá a tu documento como index.Rmd y knitea a HTML como de costumbre.
Ahora deberías tener como resultado archivo llamado "index.html" en la carpeta de tu proyecto. ¡Felicitaciones! Creaste tu primer págna web.
### Publicación
Solo falta publicar tu página web para no viva solo en tu computadora. Veamos como se hace en Netlify.
Entrá a <https://app.netlify.com/drop> y arrastrar la carpeta en el recuadro. Netlify va a crear una página web con un nombre aleatorio y posiblemente imposible de deletrear, pero está publicada!
{{< video src="img/img_netlify_drop.webm" >}}
Nota: el video puedo verse también en [youtube.com/watch?v=hZ8TpfcL1l8](https://www.youtube.com/watch?v=hZ8TpfcL1l8)
Tal vez notaste que Netlify borra los sitios web luego de 24 horas. Para que tu sitio sea permanente tenés que crearte una cuenta en Netlify. Eso además te va a permitir cambiarle el nombre a tu página, por ejemplo migranweb.netlify.app
### ¿Qué pinta tiene?
Ahora que cubrimos los principios básicos de como publicar la página web, podemos concentrarnos en lo importante, el aspecto! (y por supuesto el contenido :) ).
La pinta de cualquier archivo RMarkdown se controla desde el encabezado o YAML y en este caso vamos a modificar algunas opciones del `output`.
El YAML de esta web tiene la siguiente pinta:
::: panel-tabset
### RMarkdown
---
title: "Webs con RMarkdown"
output:
html_document:
code_download: true
toc: true
toc_float: true
theme: unite
---
De todo esto, la única opción nueva es **theme** que permite cambiar el aspecto general de la página (por ejemplo el color de los links y el tipo de letra) y hay varios que viene listos para usar en el paquete {rmarkdown}: default, cerulean, journal, flatly, darkly, readable, spacelab, united, cosmo, lumen, paper, sandstone, simplex, y yeti. Podés verlos en acción [acá](https://bootswatch.com/3/).
### Quarto
``` yaml
---
title: "Mi primer RMarkdown"
format:
html:
code-tools: true
theme:
- united
toc: true
---
```
De todo esto, la única opción nueva es **theme** que permite cambiar el aspecto general de la página (por ejemplo el color de los links y el tipo de letra) y hay varios que viene listos para usar con Quarto: default, cerulean, cosmo, cyborg, darkly, flatly, journal, litera, lumen, lux, materia, minty, morph, pulse, quartz, sandstone, simplex, sketchy, slate, solar, spacelab, superhero, united, vapor, yeti y zephyr. Podés verlos en acción [acá](https://bootswatch.com/).
:::
Podés revisar un ejemplo de una web a partir de un único archivo en <https://01-webs-rmarkdown.netlify.app/>
Y podés revisar el código fuente [acá](https://github.com/paocorrales/01_Webs-RMarkdown).
::: callout-tip
## Ejercicio
**Desafío: Publicá un reporte**
1. Elegí un archivo .Rmd, puede ser alguno de los que usamos durante el curso a modo de prueba o el reporte de ejemplo sobre Pinguinos.
2. Renderizá el archivo a formato html.
3. Cambiale el nombre para que se llame index.html y publicalo usando Netlify.
4. Si querés compartí el link para que otras personas puedan verlo (opcional).
:::
## Muchos .Rmd o qmd
Tal vez el contenido que querés mostrar es más complejo y poner todo en un único .Rmd no termina de funcionar. RMarkdown y Quarto también permiten generar una web con estructura compleja (una barra de navegación con botones y menúes entre otras maravillas) a partir de un archivo de configuración y todos los .rmd o .qmd que necesites. El ejemplo de una web de este estilo se encuentra en:
El archivo "\_site.yml" controla la configuración y pinta de todo el sitio. Es archivo de texto plano con argumentos al estilo YAML. El contenido del archivo para esta web tiene la siguiente pinta:
``` yaml
navbar:
title: Una web con muchos .Rmd!
left:
- text: Configuración
href: archivo-site.html
- text: Contenido
menu:
- text: El index
href: archivo-index.html
- text: Un post
href: post.html
output:
html_document:
theme: united
```
## ¿Qué es lo que hace cada parte?
- `navbar:...` define la barra de navegación que ves ahí arriba. Tiene varias partes, el título, un primer elemento que "Configuración" que lleva a esta misma página y otro elementos que es un menú desplegable desde donde podés acceder a más contenido. Estos elementos tienen un nombre o `text` y el archivo al que hacen referencia, siempre el html.
- `output:...` define opciones globales de salida para no tener que definirlas dentro de cada archivo Rmd. Podés ver las opciones disponibles en la documentación con `?rmarkdown::html_document()`. En este caso, define que la apariencia a a ser con el tema "united".
Hay muchas más opciones, por ejemplo:
- `output_dir: docs` define que el sitio web se va a generar en la carpeta "docs", adentro de la carpeta del proyecto. Esto cambia el nombre por defecto de la carpeta "\_site" que contiene los archivos html y demás archivos necesarios para que el sitio funcione. Esta opción es particularmente útil si se quiere utilizar GitHub Pages que requieren que la carpeta se llame "docs" en vez de "\_site".
Tener el archivo \_site.yaml tiene otra gran ventaja. Ahora RStudio sabe que querés hacer un sitio web y podés generar todo el sitio web directamente yendo a la solapa "Build" y haciendo click en "Build Website" o con el atajo de teclado Ctrl + Shift + B. Esto va a renderizar todos los archivos .Rmd que estén en la raiz del proyecto y va a generar el sitio web en la carpeta especificada en `output_dir`.
El resto se parece mucho a lo que ya vimos. Necesitaremos un archivo index.html que será nuestra página de inicio y luego podremos agregar tantas secciones como queramos.
Podés revisar un ejemplo de una web construida a partir de varios archivos en: <https://02-webs-rmarkdown.netlify.app/>
Y el código fuente se encuentra [acá](https://github.com/paocorrales/02_Webs-RMarkdown).
## Palabras finales sobre la publicación
### Netlify
La opción de arrastrar la carpeta que contiene la web en Netlify puede se útil al principio pero se vuelve trabajoso rápidamente, sería genial que fuera automático. Y se puede.
Netlify tiene una habilidad muy útil, la primera es que se puede conectar con un repositorio en, por ejemplo, GitHub donde viva la página web.
Luego de haber publicado algunas webs así me encontré con algunos problemas y sus soluciones:
- Si la web está construida solo con R Markdown, Netlify necesita saber que la carpeta "\_site" es la que contiene la web, de otra manera va a dar error. Alternativamente se puede cambiar la configuración de la web desde el "\_site.yml" para que construya la web una carpeta que se llame "public".
- Quarto por su lado también genera una carpeta con nombre distinto al que necesitamos donde guarda los archivos html que le dan vida a la web. En cualquier caso, si vemos que la cosa no anda, puede que Netlify no esté encontrando los archivos y necesite que lo indiquemos explícitamente.
### GitHub Pages
Netlify no es el único servicio que permite hostear una web. Hay muchos otros, por ejemplo GitHub Pages. En este caso si o si necesitamos usar un repositorio donde esté, al menos, los htmls que generan la web.
Una de las diferencias importantes es que GitHub Pages *busca* la web en la carpeta raíz o alternativamente en una carpeta dentro del repositorio que debe llamarse "docs". La buena noticia es usando Quarto o RMarkdown se puede indicar en el archivo de configuración que nombre debe tener la carpeta que contenga el sitio construiido.