4 Markdown - lenguaje de marcado

Trabajo previo

Lecturas

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

Tutoriales

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

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.

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

4.1.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://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*.

4.1.2 Visualización

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.

4.2 Sintaxis

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

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

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

4.2.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 (\).

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

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

4.2.6 Texto tachado

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

Sintaxis Markdown	Salida
`--Texto tachado--`	~~Texto tachado~~

4.2.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 un guión (-) antes y después del texto que se desea mostrar como subíndice.

Sintaxis Markdown	Salida
`superíndice^2^`	superíndice²
`subíndice-2-`	subíndice₂

4.2.8 Líneas horizontales

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

***

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

---

4.2.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)

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

4.2.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
`![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)`

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:

Imagen local

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

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

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

4.2.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:

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

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

4.2.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 dispersó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 dispersó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:

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 em Markdown con bloques de código ejecutables.

4.3 Ejercicios

En RStudio, cree un nuevo proyecto con la opción File - New Project - New Directory - New Project de RStudio.
En el nuevo proyecto, cree un nuevo documento Markdown con la opción File - New File - Markdown File de RStudio. 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).
Guarde el documento con el nombre README.md (RStudio asigna la extensión automáticamente).
Cree una cuenta gratuita en la plataforma de desarrollo colaborativo de software GitHub.
Cree un repositorio vacío en su cuenta en GitHub (ej. curriculum-vitae).
Suba al nuevo repositorio el archivo README.md.
Genere un sitio web en el servicio de alojamiento GitHub Pages con la opción Settings - Pages - Branch - main - Save de GitHub.
Repita los pasos 6 y 7 para cada modificación que realice en el documento Markdown.

4.4 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://ghdocs-prod.azurewebsites.net/en/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions