Qué es Markdown y cómo utilizarlo

Si eres un creador de contenidos y no has vivido en una cueva durante los últimos quince años, deberías conocer el lenguaje Markdown. Pero, sobre todo, tendrías que saber cómo aprovecharlo al máximo.

Sin embargo, si no sabes hacerlo, estás en el lugar adecuado para aprenderlo.

¿Qué es Markdown?

Markdown es un lenguaje de marcado (markup) creado en 2004 por John Gruber y Aaron Swartz.

¿Por qué crear otro lenguaje de marcado si ya existían HTML, LaTeX y muchos otros?

Markdown se basa en 3 principios:

1. inmediatez
2. compatibilidad
3. longevidad

Inmediatez de Markdown

El objetivo de Gruber y Swartz era permitir la creación de contenidos formateados incluso a los usuarios menos experimentados, que no tuvieran conocimientos de diseño web o formateo.

Para crear contenidos con formato HTML el usuario debe utilizar una determinada sintaxis y un conjunto de más de 100 elementos (llamados tags).

En cambio, el formateo de texto en Markdown es mucho más sencillo. Un texto en Markdown es un archivo de texto plano (plain text), en el que no cambia el tamaño de la letra, el color o la fuente, como ocurre en Microsoft Word, por ejemplo.

La sintaxis es más sencilla, sin etiquetas, y emplea unos pocos símbolos para marcar la función del texto.

Diez minutos son suficientes para aprender la sintaxis básica.

Por ejemplo, para escribir un texto en negrita en HTML, es necesario teclear hasta 17 caracteres (los correspondientes a la etiqueta strong): la etiqueta de apertura va entre cuñas (<…>), al igual que la etiqueta de cierre, que también lleva el indicador de barra oblicua para señalar que es una etiqueta de cierre (</…>).

<strong>Texto en negrita</strong>

Sin embargo, en Markdown sólo se requieren 4 caracteres, es decir, dos pares de asteriscos:

**Texto en negrita**

En algunos casos, no es necesario agregar ningún símbolo.

Mientras que en HTML un párrafo se indica con el par de etiquetas<p>...</p>, en Markdown basta con insertar una línea en blanco entre párrafos.

Con estas y otras sencillas medidas, Markdown simplifica enormemente la creación de documentos formateados.

Sin olvidar que en un archivo Markdown siempre es posible añadir partes de código HTML, que serán procesadas por Markdown como tal.

Compatibilidad de Markdown

Markdown tiene otra gran virtud: los archivos *.md o *.markdown pueden convertirse a HTML y a muchos otros formatos utilizando un procesador Markdown, es decir, un programa especial.

Otra ventaja es que, dado que los archivos *.md son archivos de texto plano, es decir, pueden abrirse con cualquier procesador de textos, no dependen de un software o aplicación concretos.

A diferencia de los archivos de texto creados por procesadores de texto propietarios, los archivos de texto escritos en Markdown pueden compartirse entre diferentes dispositivos y sistemas.

Longevidad de Markdown

Dado que los archivos escritos en Markdown no se compilan, sino que son archivos de texto plano, es razonable suponer que serán legibles por los procesadores durante muchísimos años.

Incluso si todos los programas que utilizan Markdown dejaran de existir mañana (lo que es muy poco probable, dado su uso generalizado), un usuario podría seguir accediendo al contenido de estos archivos con cualquier editor de texto (como el bloc de notas de Windows, por ejemplo).

Para qué se usa Markdown

Basándonos en lo antedicho, no es casualidad que Markdown se esté convirtiendo en el estándar de escritura para académicos, investigadores, redactores de contenidos y blogueros.

Algunos sitios web como GitHub, Reddit, Stack Exchange, OpenStreetMap o SourceForge han adoptado la sintaxis Markdown para los comentarios de los usuarios.

Markdown puede utilizarse en cualquier situación en la que sea necesario escribir un texto formateado.

A menudo se utiliza para formatear archivos README en proyectos de desarrollo de software, para escribir mensajes en los foros de discusión, para escribir documentación técnica y para crear artículos y páginas dentro de las herramientas de creación de sitios web, como Grav, el CMS** con el que se creó el sitio web de Qabiria donde te encuentras ahora mismo.

Muchos programas de creación de notas y bases de conocimiento utilizan Markdown como formato estándar, por ejemplo, Obsidian.

Las variantes de Markdown

Puede resultar sorprendente, pero no existe un estándar definido para Markdown, con la excepción del artículo original de John Gruber, que sin embargo describe el lenguaje dejando espacio para la ambigüedad y la interpretación.

La documentación oficial sobre sintaxis no aborda o aborda vagamente algunas cuestiones, como las sublistas y la “regla de los cuatro espacios”, entre otras cosas.

Como resultado, se crearon muchas variantes del lenguaje original, para corregir incoherencias o errores, o añadir funciones no previstas originalmente.

Uno de los esfuerzos de normalización más consistentes es el llamado CommonMark, que te invito a conocer.

Si se quiere comparar variantes, se puede recurrir a Babelmark, que analiza el resultado de las distintas implementaciones y destaca las diferencias.

Además de las variantes propiamente dichas, también han surgido una serie de extensiones, es decir, otros lenguajes que añaden nuevas funciones a Markdown, como tablas, notas a pie de página, listas de definiciones, etc.

Algunos de estos lenguajes “extendidos” son:

• Markdown Extra
• GitHub Flavored Markdown (GFM)
• MultiMarkdown
• Maruku
• Kramdown
• Pandoc’s Markdown

Qué programa utilizar para escribir en Markdown

Como debería haber quedado claro a estas alturas, para escribir en Markdown sólo se necesita cualquier procesador de texto simple.

Sin embargo, existen editores específicos para los principales sistemas operativos. Estos editores también suelen ofrecer la opción de previsualizar el texto formateado con los estilos aplicados, es decir, una versión HTML renderizada de lo que se está escribiendo.

Los que utilizan emacs, gedit, vim, BBEdit, NotePad++ pueden utilizar plugins específicos o incluso funciones integradas para resaltar la sintaxis de los archivos Markdown y previsualizarlos.

En Notepad++ puedes usar el plugin MarkdownViewer++ para tener una pantalla de vista previa y poder exportar el contenido a HTML o PDF.

Un gran programa en línea para aprender Markdown sin tener que instalar nada es Dillinger, un editor de Markdown en línea basado en HTML5 y en la nube. Dillinger también permite exportar archivos creados en Markdown a HTML y PDF.

Sintaxis básica de Markdown

Veamos ahora las reglas básicas para formatear el texto en Markdown.

Cursiva y negrita

Para marcar un texto como cursiva basta con añadir un guión bajo (underscore) o un asterisco antes y después del texto, sin dejar espacios entre el guión bajo (o el asterisco) y la palabra, de esta manera:

_texto en cursiva_

*texto en cursiva*

Del mismo modo, para enfatizar una palabra o frase en negrita debes encerrarla entre 2 asteriscos o 2 guiones bajos:

**texto en negrita**
__texto en negrita__

Texto tachado

Para tachar un texto, hay que encerrarlo entre dos pares de tildes ~~ (en Windows se escribe ALT + 126 en el teclado numérico).

~~ texto tachado~~

Títulos o encabezados

Los títulos pueden tener dos formatos:

• insertando signos de “igual” = o guiones en la línea inferior al texto, o
• precediendo el texto con uno o más símbolos de “almohadilla” #, usando uno para los títulos de primer nivel y más de uno para los de nivel inferior. No es necesario “cerrar” el texto con otro signo de almohadilla, pero si lo haces por razones estéticas, Markdown no se queja.

Este es un ejemplo del primer modo (llamado Setext):

Este es un título que se convertirá en H1
=============================================

Este es un título que se convertirá en H2
---------------------------------------------

Mientras que este es un ejemplo del segundo modo (llamado atx):

# Este es un título H1
## Este es un título H2
...
##### Este es un título H5

Párrafo

En Markdown, un párrafo consiste en una o más líneas de texto consecutivas, separadas por una o más líneas en blanco. Este párrafo estará separado del resto por un salto de párrafo (en inglés, hard return). Si deseas insertar un retorno automático (en inglés, soft return), es decir, un retorno indicado con la etiqueta HTML <br />, entonces simplemente inserta dos o más espacios al final de una línea antes del retorno.

Citas

Para destacar un texto como cita, puedes utilizar el símbolo de mayor al principio del párrafo. También es posible anidar citas una dentro de la otra empleando varios símbolos y utilizar otra sintaxis de Markdown dentro de la cita, como se muestra en el siguiente ejemplo:

> Esta es una cita de primer nivel.
> > Esta es una cita de segundo nivel.
>
> Aquí se utiliza un **negrita**
> 
> ## Y esto es un título dentro de una cita.

El estilo en el que se mostrarán las citas depende del dispositivo y del CSS asociado al archivo HTML producido.

Listas numeradas y con viñetas

Para crear una lista con viñetas, basta con añadir un asterisco, un símbolo de más o un guión al principio de la línea, seguido de un espacio y el elemento de la lista.

En cambio, para crear una lista numerada, el texto va precedido de una cifra, seguida de un punto, un espacio y el texto.

El orden elegido para la lista numerada es irrelevante y no afecta al resultado. Es decir, se puede escribir 1. primera entrada o 7.. primera entrada. El número que aparecerá en la página generada por Markdown dependerá de la posición real de esa entrada dentro de la lista y del primer número utilizado.

Aquí tienes un ejemplo:

* Primer elemento de una lista con viñetas
* Segundo elemento de una lista con viñetas
* Tercer elemento de una lista con viñetas

4. Primer elemento de una lista numerada
1. Segundo elemento de una lista numerada
2. Tercer elemento de una lista numerada

La lista numerada aparecerá así:

4. Primer elemento de una lista numerada
5. Segundo elemento de una lista numerada
6. Tercer elemento de una lista numerada

Código de programación

Para insertar un fragmento de código en un documento Markdown para que aparezca como <pre><code>...</code></pre> debes insertar cuatro espacios al principio del párrafo.

Otro método es utilizar tres acentos graves (en inglés, backtick) ` o tres tildes ~ en una línea separada para marcar el comienzo del código y tres más en otra línea para marcar el final. Por ejemplo:

```
print('Hola, mundo!')
```

Enlaces

Para insertar enlaces, se utiliza una sintaxis especial: el texto a enlazar va entre corchetes y la URL va inmediatamente después (sin espacio de separación) entre paréntesis, posiblemente seguido del nombre del enlace (que se convertirá en el valor del atributo title en el HTML resultante):

Este es un ejemplo de [enlace](https://enlace.com "Nombre del enlace")

Imágenes

La sintaxis de las imágenes es similar a la de los enlaces, pero el par de corchetes y paréntesis va precedido de un signo de exclamación, como en el ejemplo a continuación:

![Descripción de la imagen](/ruta/imagen/img.jpg)

En el caso de las imágenes, el texto entre corchetes se mostrará como el valor del atributo alt de la etiqueta img.

Líneas de separación horizontales

Para insertar una línea horizontal, correspondiente a la etiqueta HTML <hr />, hay que insertar tres o más guiones, asteriscos o guiones bajos en una sola línea, también separados por espacios.

Por ejemplo, todas las combinaciones a continuación...

* * *
---
- - -
****

generan una línea horizontal:

---

---

---

---

Caracteres especiales

En algunos casos, es necesario utilizar el carácter de barra invertida (backslash) \ para generar caracteres literales que, de otro modo, serían interpretados por Markdown como sintaxis de formato.

Por ejemplo, si quieres encerrar una palabra entre asteriscos, debes utilizar la barra invertida antes de los asteriscos, de lo contrario el texto se interpretaría como en cursiva, así:

\*texto entre asteriscos\*

lo que da como resultado *texto entre asteriscos* y no texto entre asteriscos (en cursiva).

Lo mismo ocurre con otros caracteres especiales, como:

• Asterisco: *
• Guión: -
• Guión bajo (underscore): _
• Paréntesis: ()
• Corchetes: []
• Llaves: {}
• Punto: .
• Signo de exclamación: !
• Almohadilla: #
• Acento grave (backtick): `
• Barra invertida (backlash): \

Ten en cuenta que, para escribir estos caracteres por separado, no se necesita la barra invertida. Esta sólo se necesitará en el caso de que puedan interpretarse como sintaxis de formateado.

Cómo traducir archivos de Markdown

Pero, ¿cómo se traduce un texto creado en Markdown?

Como estamos hablando de archivos de texto, la forma más fácil es abrir el archivo *.md con un editor de texto y traducirlo manualmente dentro del editor.

Sin embargo, de esta manera no podemos utilizar todos los recursos de traducción que tendríamos a nuestra disposición si tradujéramos el archivo con un programa de traducción asistida.

La traducción de archivos Markdown implica 2 problemas principales:

1. al no existir una norma, el programa de traducción o el filtro que interpreta el archivo a traducir debe tener en cuenta todas las variantes y posibles extensiones que, por cierto, no son todas compatibles entre sí
2. los programas que utilizan Markdown suelen combinar la sintaxis de Markdown con un encabezado en formato YAML (como es el caso de Jekyll o Grav), por lo que el programa o filtro debe ser capaz también de interpretar este encabezado.

Traducción de Markdown con Trados Studio

El programa de traducción asistida quizás más popular, Trados Studio, tiene un filtro para los archivos Markdown a partir de la versión 2019.

Antes era necesario crear un filtro personalizado utilizando una serie de expresiones regulares.

El filtro ofrece algunas opciones, como:

• considerar los saltos de línea como etiquetas internas
• traducir bloques de código con un filtro adicional
• traducir bloques de código HTML con un filtro adicional.

Se recomienda activar al menos esta última opción para que los fragmentos HTML utilizados en los archivos Markdown aparezcan en el editor de traducción.

Traducción de Markdown con Memsource

Memsource, uno de los sistemas de gestión de proyectos de traducción más populares, dispone de un filtro para traducir archivos Markdown, que pueden importarse y traducirse en Memsource sin mucha complicación.

En particular, el filtro ofrece las siguientes opciones al importar el archivo a traducir:

• eligir la variante de Markdown a considerar (Flavor)
• segmentar las unidades de traducción tras los retornos hard
• mantener los espacios en blanco en el documento traducido (es decir, espacios, retornos, etc.)
• considerar o no el encabezado YAML (a elegir si el encabezado incluye textos traducibles)
• importar bloques de código (expone el código contenido en el archivo Markdown a la traducción)
• excluir elementos de código

También es posible aplicar expresiones regulares para convertir un determinado texto en etiquetas, así como definir los elementos del archivo que se convertirán en etiquetas y también las secciones que no se importarán.

Por último, se puede definir una lista de caracteres que no necesitan ser escapados en el archivo traducido.

Traducción de Markdown con OmegaT

Para traducir los archivos Markdown a OmegaT tienes dos opciones:

1. utilizar el filtro de archivos de texto plano
2. utilizar el filtro de archivos Markdown incluido en el plugin de Okapi

El filtro de archivos de texto plano expone todo el contenido del archivo, por lo que el traductor debe tener especial cuidado de no distorsionar la sintaxis de formato, ningún encabezado, HTML u otro código del texto.

Sin embargo, de este modo también tiene la posibilidad de intervenir en el texto a mano sin limitaciones. Esto puede ser necesario cuando hay que insertar imágenes o enlaces distintos de los originales en la versión traducida, o hay que añadir campos y valores a la cabecera YAML.

Por lo tanto, esta opción se recomienda en los casos en que el traductor esté familiarizado con Markdown y con la estructura del archivo original.

El filtro de Okapi para archivos Markdown extrae el texto traducible de los archivos Markdown. Dado que no todas las variantes de Markdown son compatibles entre sí, Okapi ha optado por diseñar el filtro para que funcione con CommonMark, con algunas opciones para que también sea compatible con el GitHub Flavored Markdown (GFM).

Los detalles del filtro se pueden encontrar en la Wiki de Okapi, a la que nos remitimos para más detalles. Aquí baste decir que existe un parámetro para incluir o excluir de la traducción cualquier encabezado YAML, que sin embargo está desactivado por defecto. Por lo tanto, si deseas utilizar opciones distintas a las predeterminadas, es necesario utilizar Rainbow para crear un archivo con los parámetros del filtro, que luego debe cargarse en OmegaT.

Qué estrategia elegir para traducir archivos Markdown

El flujo de traducción de un archivo Markdown no sólo depende del sistema que se utilice para traducirlo, sino también del programa que haya generado y deba interpretar los archivos Markdown.

Hay que prestar especial atención a los sistemas de traducción automática, ya que no siempre respetan la sintaxis al pie de la letra. Por ejemplo, cuando se traduce un contenido escrito en Markdown con Google Translate, la traducción puede tener una serie de acentos graves que no coinciden con el original, lo que hace que el archivo traducido sea inutilizable.