5 Markdown - lenguaje de marcado

5.1 Resumen

Markdown es un lenguaje de marcado ligero ampliamente utilizado en comunicación científica, documentación de programas e investigación reproducible, entre otras aplicaciones. Incluye marcas para especificar aspectos de estructura, semántica y estilo de un documento. Se basa en texto simple y se convierte fácilmente a HTML, el lenguaje de marcado más utilizado en páginas web.

Markdown puede emplearse junto con lenguajes de programación (ej. R, Python) para así combinar texto con código fuente, el cual inserta en los documentos salidas como tablas, gráficos y mapas, entre otras. Esta forma de trabajo facilita la automatización y la reproducibilidad de una investigación.

5.2 Trabajo previo

5.2.1 Instalación de software

Para la edición de código Markdown, en el contexto de la programación en R, se recomienda instalar:

Sistema base del lenguaje R (no es necesario para este capítulo, pero sí se utilizará más adelante)
RStudio Desktop

Opcionalmente, puede instalar Visual Studio Code u otro editor de código fuente.

5.2.2 Tutoriales

Markdown Tutorial

5.3 Introducción

Markdown es un lenguaje de marcado, creado en 2004 por John Gruber y Aaron Swartz. Las “marcas” se utilizan para especificar aspectos de la estructura (ej. títulos, encabezados), estilo (ej. negritas, itálicas) y semántica de un documento. Markdown se caracteriza por ser más sencillo de leer y de usar que otros lenguajes de marcado (ej. Lenguaje de Marcado de Hipertexto o HTML), por lo que se considera un lenguaje de marcado ligero.

Los documentos escritos en Markdown pueden exportarse a una gran variedad de formatos (ej. HTML, DOC, PDF, LaTex) para ser usados en libros, presentaciones o páginas web, entre otros fines.

5.3.1 Variaciones

Las variaciones de Markdown, también llamadas flavors, son extensiones o modificaciones de la especificación original. Entre las más populares están:

R Markdown: para el lenguaje R.
Quarto: es la “siguiente generación” de R Markdown, con soporte para más lenguajes de programación (Python, Julia, Observable, R) y motores de procesamiento (Jupyter, Knitr), entre otras mejoras.
Python Markdown: para el lenguaje Python.
GitHub Flavored Markdown: para la plataforma GitHub.
Pandoc’s Markdown: para el programa Pandoc de conversión entre formatos.
Kramdown: para el lenguaje Ruby.

Puede encontrarse una lista más extensa de variaciones de Markdown en Markdown Flavors.

5.4 Ejemplo de documento

El siguiente es un ejemplo de la sintaxis de Markdown, con marcas para un encabezado, texto en negrita, texto en itálica, un hipervínculo y una imagen.

### Los satélites galileanos

Se llaman **satélites galileanos** los cuatro satélites
de Júpiter descubiertos en 1610 por 
[Galileo Galilei](https://es.wikipedia.org/wiki/Galileo_Galilei): 
*Ío*, *Europa*, *Ganimedes* y *Calisto*. 
Son los más grandes de los satélites de Júpiter, 
siendo visibles incluso con telescopios de baja potencia.

![](https://upload.wikimedia.org/wikipedia/commons/thumb/f/fe/Jupiter_and_the_Galilean_Satellites.jpg/168px-Jupiter_and_the_Galilean_Satellites.jpg)

**Figura 1**. Los cuatro satélites galileanos, 
en una composición que compara sus tamaños con el tamaño de Júpiter. 
En orden descendente, son *Ío*, *Europa*, *Ganimedes* y *Calisto*.

Y la siguiente es la manera en la que se visualiza el documento:

Los satélites galileanos

Se llaman satélites galileanos los cuatro satélites de Júpiter descubiertos en 1610 por Galileo Galilei: Ío, Europa, Ganimedes y Calisto. Son los más grandes de los satélites de Júpiter, siendo visibles incluso con telescopios de baja potencia.

Figura 1. Los cuatro satélites galileanos, en una composición que compara sus tamaños con el tamaño de Júpiter. En orden descendente, son Ío, Europa, Ganimedes y Calisto.

El contenido de este ejemplo fue tomado de Satélite galileano - Wikipedia, la enciclopedia libre.

5.5 Herramientas para escritura de documentos

Markdown se escribe en “texto simple o plano” (i.e. texto sin formato, compuesto únicamente por caracteres que son legibles por humanos), por lo que puede escribirse con cualquier editor de texto. Se recomienda el uso de editores orientados a programación, también llamados editores de código fuente, los cuales proporcionan facilidades para el programador, como coloración de palabras clave, sangrado y autocompletado, entre otras.

También pueden utilizarse Entornos Integrados de Desarrollo o IDE, los cuales son aplicaciones informáticas que proporcionan servicios integrales para facilitarle al programador el desarrollo de software. Además de un editor de código fuente, un IDE incluye funciones para depuración (i.e. identificación de errores), interpretación y compilación de programas, entre otras.

Algunos de los editores de código fuente o IDE recomendados para Markdown son:

Visual Studio Code: editor de código fuente muy popular y de código abierto. Puede editar código de múltiples lenguajes de programación y sintaxis asociadas
RStudio Desktop: IDE para desarrollo en el lenguaje de programación R, el cual también puede manejar código en otros lenguajes de programación y sintaxis.

No se recomienda el uso de procesadores de texto (ej. Microsoft Word, Libre Office Writer), debido a que introducen caracteres especiales que no son reconocidos por Markdown.

5.6 Sintaxis

En esta sección, se muestran los principales elementos de sintaxis de Markdown y sus salidas.

5.6.1 Encabezados

Hay seis niveles de encabezados en Markdown, siendo el nivel 1 el de letras más grandes y el 6 el de letras más pequeñas. Se especifican mediante símbolos de numeral (#) antes del texto del encabezado (note el espacio entre el último signo de numeral y el inicio del texto).

Sintaxis Markdown	Salida
`# Encabezado de nivel 1`	Encabezado de nivel 1
`## Encabezado de nivel 2`	Encabezado de nivel 2
`### Encabezado de nivel 3`	Encabezado de nivel 3
`#### Encabezado de nivel 4`	Encabezado de nivel 4
`##### Encabezado de nivel 5`	Encabezado de nivel 5
`###### Encabezado de nivel 6`	Encabezado de nivel 6

Para los encabezados de nivel 1 y nivel 2, existe una sintaxis alterna, con símbolos de igual (=====) o guiones (-----) bajo el texto del encabezado.

Sintaxis Markdown	Salida
`Otro encabezado de nivel 1` `==========================`	Otro encabezado de nivel 1
`Otro encabezado de nivel 2` `--------------------------`	Otro encabezado de nivel 2

5.6.2 Párrafos

Los párrafos deben separarse mediante (al menos) una línea en blanco. Un simple cambio de línea no generará un nuevo párrafo.

Sintaxis Markdown	Salida
Este es el texto que corresponde al primer párrafo de un documento. Este es el texto que corresponde al segundo párrafo de un documento.	Este es el texto que corresponde al primer párrafo de un documento. Este es el texto que corresponde al segundo párrafo de un documento.

5.6.3 Negrita

Hay dos sintaxis para especificar texto en negrita: con dos asteriscos (**) o con dos guiones bajos (__), antes y después del texto.

Sintaxis Markdown	Salida
`Texto en negrita`	Texto en negrita
`__Otro texto en negrita__`	Otro texto en negrita

5.6.4 Itálica

Hay dos sintaxis para especificar texto en itálica: con un asterisco (*) o con un guión bajo (_), antes y después del texto.

Sintaxis Markdown	Salida
`Texto en itálica`	Texto en itálica
`_Otro texto en itálica_`	Otro texto en itálica

5.6.5 Citas textuales

Se especifican con un símbolo de “mayor que” (>) antes de cada línea.

Sintaxis Markdown	Salida
`> And on the pedestal these words appear:` `> "My name is Ozymandias, king of kings:` `> Look on my works, ye Mighty, and despair!"` `Percy Bysshe Shelley, "Ozymandias" (1818)`	“And on the pedestal these words appear: ”My name is Ozymandias, king of kings: Look on my works, ye Mighty, and despair!“ Percy Bysshe Shelley, “Ozymandias” (1818)

5.6.6 Enlaces (hipervínculos)

Se definen con paréntesis cuadrados ([]) seguidos de paréntesis redondos (()). En los paréntesis cuadrados se coloca (opcionalmente) el texto del enlace y en los redondos la dirección del documento al que conduce el enlace.

Sintaxis Markdown	Salida
`[Proyecto Gutenberg](https://www.gutenberg.org/)`	Proyecto Gutenberg

5.6.7 Imágenes

Se definen con un signo de admiración de cierre (!), paréntesis cuadrados ([]) y paréntesis redondos (()). En los paréntesis cuadrados se coloca (opcionalmente) un texto alternativo de la imagen y en los redondos la dirección de la imagen, ya sea local o remota.

Sintaxis Markdown	Salida
`![Imagen local](img/Jupiter_and_the_Galilean_Satellites.jpg)`
`![Imagen remota](https://upload.wikimedia.org/wikipedia/commons/thumb/f/fe/Jupiter_and_the_Galilean_Satellites.jpg/168px-Jupiter_and_the_Galilean_Satellites.jpg)`

5.6.8 Listas numeradas

Se definen con números (1. 2. 3. ...) antes de cada elemento.

Sintaxis Markdown	Salida
`1. Primer elemento.` `2. Segundo elemento.` `3. Tercer elemento.`	Primer elemento. Segundo elemento. Tercer elemento.

5.6.9 Listas no numeradas

Se definen con guiones (-) o asteriscos (*) antes de cada elemento.

Sintaxis Markdown	Salida
`- Un elemento.` `- Otro elemento.` `- Otro elemento más.`	Un elemento. Otro elemento. Otro elemento más.

5.6.10 Ecuaciones

Las ecuaciones se escriben con base en la sintaxis de LaTeX. Se delimitan (al inicio y al final) con:

Un símbolo de dólar ($), para ecuaciones dentro de un renglón (inline math).
Dos símbolos de dólar ($$), para ecuaciones en su propio bloque (display math).

Sintaxis Markdown	Salida
`Equivalencia entre masa y energía: $E = mc^{2}$`	Equivalencia entre masa y energía: $E = mc^{2}$
`Equivalencia entre masa y energía:` `$$E = mc^{2}$$`	Equivalencia entre masa y energía: \[E = mc^{2}\]

Para más detalles sobre la sintaxis de ecuaciones, se recomienda consultar:

5.7 Ejercicios

Con RStudio, cree un documento Markdown llamado README.md y escriba en este un breve curriculum académico o profesional.
1. Incluya información como: nombre, fotografía, datos de contacto, áreas de interés, carrera, cursos aprobados, publicaciones, etc.
2. Puede usar información ficticia (no incluya datos confidenciales o sensibles).
3. Especifique la fuente de las imágenes (y de cualquier otra información para la que sea necesario) y no utilice imágenes para las que no tiene autorización. Considere utilizar sitios con imágenes con licencias abiertas (ej. Wikimedia Commons, Unsplash, FreeImages).
4. Asegúrese de utilizar los siguientes elementos de sintaxis Markdown:
  - Encabezados de varios niveles.
  - Negritas e itálicas.
  - Listas.
  - Enlaces a sitios web.
  - Imágenes (al menos una local y una remota).

5.8 Recursos de interés

Carrera Arias, F. J. (2020). How to Install R on Windows, Mac OS X, and Ubuntu Tutorial. DataCamp Community. https://www.datacamp.com/community/tutorials/installing-R-windows-mac-ubuntu

Daring Fireball: Markdown. (s. f.). Recuperado 25 de marzo de 2023, de https://daringfireball.net/projects/markdown/

LaTeX/Mathematics—Wikibooks, open books for an open world. (s. f.). Recuperado 25 de marzo de 2023, de https://en.wikibooks.org/wiki/LaTeX/Mathematics

Markdown Guide. (s. f.). Recuperado 10 de abril de 2022, de https://www.markdownguide.org/

Quarto—Markdown Basics. (s. f.). Recuperado 25 de marzo de 2023, de https://quarto.org/docs/authoring/markdown-basics.html

Writing mathematical expressions. (s. f.). GitHub Docs. Recuperado 25 de marzo de 2023, de https://ghdocs-prod.azurewebsites.net/en/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions