5  Markdown - lenguaje de marcado

En este capítulo se introduce el lenguaje de marcado ligero Markdown, el cual permite especificar la estructura, los estilos y la semántica de un documento. El Markdown es apropiado para intercalar texto con código fuente y sus salidas (ej. tablas, gráficos y mapas).

5.1 Resumen

Markdown es un lenguaje de marcado ligero creado en 2004 por John Gruber y Aaron Swartz. Las marcas se utilizan para indicar aspectos estructurales (ej. encabezados, listas), estilísticos (ej. negritas, itálicas) y semánticos de un documento. En comparación con otros lenguajes de marcado como HTML, Markdown es más sencillo de leer y de escribir, por lo que suele emplearse en documentación técnica, páginas web y archivos README de proyectos de software.

Los documentos escritos en Markdown pueden exportarse a una gran variedad de formatos, como HTML, PDF, DOC o LaTeX. Existen además múltiples variaciones o flavors (ej. R Markdown, Quarto, GitHub Flavored Markdown, Pandoc’s Markdown) que extienden el lenguaje original para soportar funcionalidades adicionales, como la inclusión de bloques de código ejecutables o expresiones matemáticas.

5.2 Trabajo previo

5.2.1 Lecturas

Quarto - Markdown Basics. (s.f.). Quarto. Recuperado el 1 de marzo de 2024, de https://quarto.org/docs/authoring/markdown-basics.html

5.2.2 Tutoriales

Markdown Tutorial. (s.f.). Recuperado el 1 de marzo de 2024, de https://www.markdowntutorial.com/

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.

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. Más que una variación de Markdown es un sistema de publicación de documentos técnicos y científicos que utiliza Markdown.
• 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.

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 documento Markdown. Se muestra primero la sintaxis del documento y luego la manera en la que se visualiza.

5.4.1 Sintaxis

La sintaxis del documento incluye marcas para un encabezado, texto en negrita, texto en itálica, hipervínculos y una imagen.

---

# Los satélites galileanos

Se llaman **satélites galileanos** los cuatro satélites de
[Júpiter](https://es.wikipedia.org/wiki/J%C3%BApiter_(planeta))
descubiertos en 1610 por el astrónomo italiano
[Galileo Galilei](https://es.wikipedia.org/wiki/Galileo_Galilei) (1564 - 1642): 
*Í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://images-assets.nasa.gov/image/PIA00600/PIA00600~small.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*.

---

5.4.2 Visualización

A continuación se muestra el documento Markdown de la subsección anterior una vez renderizado a HTML.

---

Los satélites galileanos

Se llaman satélites galileanos los cuatro satélites de Júpiter descubiertos en 1610 por el astrónomo italiano Galileo Galilei (1564 - 1642): Í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 está basado en Satélite galileano - Wikipedia, la enciclopedia libre.

5.4.3 Ejercicios

En los siguientes pasos se practica la edición de un documento Markdown en RStudio, la visualización local del documento renderizado y su publicación en GitHub Pages.

5.4.3.1 Creación y edición de un documento Markdown

1. En RStudio, cree un nuevo proyecto con la opción File - New Project - New Directory - New Project. Asigne al directorio el nombre satelites-galileanos y seleccione una ubicación en su computadora para almacenarlo. Haga clic en Create Project; RStudio abrirá automáticamente el nuevo proyecto.

2. Dentro del proyecto, cree un archivo Markdown con la opción File - New File - Markdown File. RStudio abrirá un editor de texto vacío para el nuevo archivo.

3. Copie en el editor el contenido Markdown del documento sobre los satélites galileanos que se muestra en la subsección anterior, Sintaxis.

4. Guarde el archivo con la opción File - Save (o el atajo Ctrl + S en Windows/Linux, Cmd + S en macOS) y asígnele el nombre README.md. El archivo quedará almacenado en la raíz del proyecto satelites-galileanos.

5. Para visualizar localmente el documento renderizado, haga clic en el botón Preview ubicado en la barra de herramientas del editor (con el ícono de un ojo). RStudio convertirá el archivo Markdown a HTML y lo mostrará en una ventana aparte o en el panel Viewer, según la configuración. El resultado debería ser similar al que aparece en la subsección anterior, Visualización.

6. Con el archivo README.md abierto en el editor, practique la edición agregando y modificando contenido. Por ejemplo: incluya un nuevo párrafo o enlaces adicionales a otros artículos de Wikipedia.

7. Guarde los cambios (File - Save) y vuelva a hacer clic en Preview para ver el resultado actualizado. Repita el ciclo de editar → guardar → previsualizar hasta familiarizarse con el proceso de edición.

5.4.3.2 Publicación en GitHub Pages

GitHub es una plataforma de desarrollo colaborativo basada en el sistema de control de versiones Git, que permite alojar y compartir código fuente y otros archivos en repositorios públicos o privados. GitHub Pages es un servicio gratuito de GitHub que publica sitios web estáticos a partir del contenido de un repositorio. Cuando el repositorio contiene un archivo README.md en su raíz y no incluye un index.html, GitHub Pages usa automáticamente el README.md como página principal del sitio.

1. Si aún no cuenta con una, cree una cuenta gratuita en GitHub. Complete el formulario de registro con una dirección de correo electrónico, un nombre de usuario y una contraseña, y verifique la cuenta mediante el correo de confirmación que GitHub le enviará.

2. Con la sesión iniciada en GitHub, cree un nuevo repositorio haciendo clic en el botón + (en la esquina superior derecha de la página) y seleccionando New repository. Asigne al repositorio el nombre satelites-galileanos, marque la opción Public (requerida para publicar en GitHub Pages con una cuenta gratuita) y haga clic en Create repository. No active las opciones Add a README file, Add .gitignore ni Choose a license, ya que va a subir su propio archivo README.md.

3. En la página del repositorio recién creado, haga clic en el enlace uploading an existing file. Arrastre el archivo README.md desde el directorio del proyecto satelites-galileanos al área indicada en el navegador (o haga clic en choose your files para seleccionarlo). Al final de la página, haga clic en Commit changes para confirmar la carga.

4. Para activar GitHub Pages, vaya a la pestaña Settings del repositorio y seleccione Pages en el menú lateral izquierdo. En la sección Build and deployment, en Source, escoja Deploy from a branch. En Branch, seleccione main con la carpeta / (root) y haga clic en Save.

5. Espere uno o dos minutos y recargue la página Settings - Pages. Cuando el sitio esté publicado, aparecerá un mensaje con la URL pública, con el formato https://<usuario>.github.io/satelites-galileanos/, donde <usuario> es su nombre de usuario en GitHub. Haga clic en la URL para visitar el documento publicado.

6. Para actualizar el documento en el futuro, edite el archivo README.md directamente en la interfaz web de GitHub (haciendo clic en el archivo y luego en el ícono de lápiz) o cargue una nueva versión desde su computadora repitiendo el paso 3. Los cambios se reflejarán en el sitio publicado pocos minutos después.

5.5 Sintaxis

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

5.5.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.5.2 Párrafos

Los párrafos deben separarse mediante (al menos) una línea en blanco.

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.5.3 Cambios de línea

Si se requiere un cambio de línea sin una línea en blanco entre párrafos, pueden agregarse dos espacios en blanco al final de la línea () o también un espacio y una barra invertida (\).

5.5.4 Texto en 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.5.5 Texto en 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.5.6 Texto tachado

El texto tachado se especifica con dos tildes (~~) antes y después del texto.

Sintaxis Markdown	Salida
~~Texto tachado~~	Texto tachado

5.5.7 Superíndices y subíndices

Un superíndice se especifica con un acento circunflejo (^) antes y después del texto que se desea mostrar como superíndice. Un subíndice se especifica con una tilde (~) antes y después del texto que se desea mostrar como subíndice.

Sintaxis Markdown	Salida
superíndice^2^	superíndice2
subíndice~2~	subíndice2

5.5.8 Líneas horizontales

Tres o más asteriscos (***) generan una línea horizontal:

***

---

También puede generarse con tres o más guiones (---):

---

---

5.5.9 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.5.10 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.5.11 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. Una imagen local se encuentra en la misma computadora en la que está el documento que la referencia, mientras que una imagen remota se encuentra en otra computadora a la que se accede mediante un protocolo de redes como el Protocolo de transferencia de hipertexto (HTTP).

Sintaxis Markdown	Salida


Markdown no cuenta con sintaxis para especificar el tamaño de una imagen, pero esto puede lograrse con el Lenguaje de marcado de hipertexto (HTML, HyperText Markup Language), su elemento img y sus atributos height y width, los cuales especifican la altura y el ancho de una imagen (las unidades por defecto son pixeles).

Por ejemplo, la expresión HTML:

<img src="img/Jupiter_and_the_Galilean_Satellites.jpg" height="100" alt="Imagen local">

genera como salida una imagen de 100 pixeles de altura:

Si se usa solo el atributo height, width se ajusta automáticamente y viceversa.

5.5.12 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.

Las listas numeradas pueden anidarse para mostrar la información de una forma jerárquica. Para crear un nivel de anidación, deben usarse sangrías con una cantidad de espacios consistente en toda la lista. La numeración se ordena automáticamente (incluso si hay errores).

Sintaxis Markdown	Salida
1. Primer elemento             1. Elemento anidado             2. Elemento anidado 2. Segundo elemento             1. Elemento anidado             2. Elemento anidado 3. Tercer elemento             1. Elemento anidado             2. Elemento anidado	Primer elemento Elemento anidado Elemento anidado Segundo elemento Elemento anidado Elemento anidado Tercer elemento Elemento anidado Elemento anidado

5.5.13 Listas no numeradas

Se definen con guiones (-), asteriscos (*) o signos de adición (+) antes de cada elemento.

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

Las listas no numeradas también pueden anidarse. Debe utilizarse un mínimo de dos espacios en los elementos anidados.

Sintaxis Markdown	Salida
- Un elemento             + Elemento anidado             + Elemento anidado - Otro elemento             + Elemento anidado             + Elemento anidado - Otro elemento más             + Elemento anidado             + Elemento anidado	Un elemento Elemento anidado Elemento anidado Otro elemento Elemento anidado Elemento anidado Otro elemento más Elemento anidado Elemento anidado

Las listas numeradas y las no numeradas pueden intercalarse.

Sintaxis Markdown	Salida
1. Primer elemento             - Elemento anidado             - Elemento anidado 2. Segundo elemento             - Elemento anidado             - Elemento anidado 3. Tercer elemento             - Elemento anidado             - Elemento anidado	Primer elemento Elemento anidado Elemento anidado Segundo elemento Elemento anidado Elemento anidado Tercer elemento Elemento anidado Elemento anidado

5.5.14 Notación matemática

Las expresiones en notación matemática (ej. 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 las expresiones matemáticas, se recomienda consultar:

• Writing mathematical expressions - GitHub Docs
• LaTeX/Mathematics

5.5.15 Bloques de código fuente

Los documentos Markdown pueden contener bloques de código fuente, ya sea incrustados en una línea de texto (inline) o en líneas separadas.

5.5.15.1 Bloques en línea

Para mostrar fragmentos cortos de código en una sola línea dentro del texto, se usa una sola comilla invertida o backtick para delimitar el código.

Por ejemplo, la sintaxis:

Este es un fragmento de código en línea: `x = 10`

genera:

Este es un fragmento de código en línea: x = 10

5.5.15.2 Bloques multilínea

Para fragmentos de código de múltiples líneas, se utilizan tres comillas invertidas o una sangría de cuatro espacios al inicio de cada línea.

El siguiente es un ejemplo de bloque de código delimitado con comillas invertidas (la forma más usada):

```
function sumar(a, b) {
  return a + b;
}
```

Se visualiza como:

function sumar(a, b) {
  return a + b;
}

Si el código es de un lenguaje específico, puede indicarse para resaltar (y colorear) la sintaxis. Por ejemplo, para un bloque de código en R, se escribe r después de las tres comillas invertidas.

Sintaxis de código en R:

```r
# Gráfico de dispersión del conjunto de datos cars con etiquetas en los ejes x e y
plot(
  x=cars$speed,
  y=cars$dist,
  xlab="Velocidad (mph)", 
  ylab="Distancia requerida para frenar (pies)"
)
```

Visualización de código en R:

# Gráfico de dispersión del conjunto de datos cars con etiquetas en los ejes x e y
plot(
  x=cars$speed,
  y=cars$dist,
  xlab="Velocidad (mph)", 
  ylab="Distancia requerida para frenar (pies)"
)

El uso de resaltado de sintaxis con bloques de código lo hace más fácil de leer y comprender. El resultado (colores, fuentes de texto, etc.) de sintaxis depende de la plataforma o editor de Markdown que se utilice. Plataformas como GitHub y algunos editores soportan muchos lenguajes, mientras que otros pueden no reconocer todos.

Para más información sobre el uso de bloques de código en documentos Markdown, se recomienda consultar:

• Creating and highlighting code blocks
• The languages YAML file
• Markdown Code Block: Including Code In .md Files - Markdown Land

Nótese que los bloques de código en un documento Markdown normal (con extensión .md) no se ejecutan, solo se muestran. Sin embargo, hay sistemas como Quarto y Jupyter Notebooks que permiten combinar narrativa en Markdown con bloques de código ejecutables.

5.6 Ejercicios

En el siguiente ejercicio se aplica lo visto en este capítulo a un documento con contenido propio.

Siguiendo el mismo procedimiento descrito en la subsección Ejercicios del Ejemplo de documento (creación del proyecto en RStudio, edición del archivo README.md, visualización local y publicación en GitHub Pages), cree un nuevo proyecto con un archivo README.md que contenga un breve curriculum académico o profesional (o cualquier otro tema que sea de su interés: su trabajo final de graduación, un proyecto personal, etc.). Asigne al proyecto y al repositorio en GitHub un nombre descriptivo del contenido (ej. curriculum-vitae).

Considere las siguientes recomendaciones y requisitos adicionales:

• El contenido puede incluir información como nombre, fotografía, datos de contacto, áreas de interés, carrera, cursos aprobados, publicaciones, etc.
• Puede usar información ficticia. No incluya datos confidenciales o sensibles.
• 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).
• 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.7 Recursos de interés

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/

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