La Antiguía definitiva de Markdown

No se si será MEGA, ULTRA, SUPER o definitiva esta guía, lo que si te puedo contar es mi experiencia y lo que he aprendido con Markdown.

Luego te pondré la sintaxis y el formateo para que puedas utilizarlo en tu día a día, aunque será más de lo mismo de las chorrocientas páginas que encontrarás en internet.

La diferencia que no verás en otras, es que hay una especicificación oficial y luego han añadido extras que al final se han convertido en ampliamente usadas, y saber estas diferencias te hará entender ciertos detalles que irás encontrando en distintas páginas de internet y en los programas que utilicen markdown.

¿Qué es Markdown?

Seguro que estás acostumbrado a escribir con negritas, cursiva, tipos de letra y todas esas cosas que te permite un editor de texto avanzado. Estos procesadores modernos tienen mil opciones, y para un texto escrito muchas veces solo necesitas negritas y poco más.

También es cierto que cuando generas un documento con un programa, solo lo puedes leer con ese programa, y es poco transportable entre otros programas y sistemas operativos.

Markdown entre otras ventajas viene a evitar tener que utilizar un editor de textos en concreto, puedes usar el que tu quieras, o utilizar diferentes según el sistema operativo que utilices.

También te permite centrarte en escribir y no levantar las manos del teclado. Esto si escribes mucho, a la larga te ahorra tiempo, y si escribes poco también te puede ayudar a que no se canse la muñeca cada vez que cojas el ratón.

La definición de Markdown que encontrarás por internet más o menos será esta:
Markdown es un sistema de formateo de texto que con una sintaxis te permite escribir un texto que puedes convertir a distintos formatos.

Filosofía

Markdown fue creado por John Gruber en 2004, con una ayuda importante de Aaron Swartz en la sintaxis. El objetivo de este lenguaje es que la gente «pueda escribir usando un formato de texto plano fácil-de-leer y fácil-de-escribir, y con la posibilidad de poder convertir su documento en XHTML (o HTML) válido”.

Se pensó con la idea de que fuese tan fácil de leer y escribir como fuera posible.

Así que la legibilidad se enfatiza por encima de todo. Un documento con formato Markdown debe poder publicarse tal cual, como texto sin formato, sin que parezca que se ha marcado con etiquetas o instrucciones de formato.

Aunque no lo he comentado una vez que tienes el documento en Markdown puedes convertirlo al formato que quieras, desde HTML hast PDF, con diversas herramientas y de manera sencilla.

Guía básica de sintaxis

Como existen muchos artículos en internet sobre la sintaxis de Markdown, este no te va a descubrir la pólvolra, pero si vas a ver la diferencia entre la definición incial y la que se usa habitualmente para escribir en github.

En esta primera parte vas a ver la sintaxis general de markdown y luego la que se aplica a Github.com. Por último verás algunos extras que son muy útiles para incorporar a Markdown.

Saltos de línea

Aunque esto parezca una chorrada, es más importante de lo que parece, porque Markdown define como salto de línea, una línea en blanco, que también puede ser un tabulador, o dos espacios en blanco. Así que los párrafos no deben tener sangría o espacios o tabulaciones.

Como entenderás la implicación de esto es que esta regla de «una o más líneas consecutivas de texto» hace que puedas escribir párrafos «ajustados». Esto es diferente de la mayoría de los editores de texto que traducen cada salto de línea en un párrafo.

Por ejemplo:

Aquí hay una línea en la que comienza un párrafo.

Esta línea está separada de la anterior por dos nuevas líneas, por lo que será un *párrafo separado*.

Esta línea también comienza un párrafo separado, pero ...  (<-- dos espacios)
Esta línea solo está separada por dos espacios finales y una sola línea nueva, por lo que es una línea separada en el *mismo párrafo*.

Algunos editores de markdown son estrictos en este sentido y en otros puedes cambiar esta configuración.

Encabezados

Puedes utilizar el carácter ‘#’ hasta seis veces ‘######’ para obtener encabezados seis tamaños diferentes. Múltiples ‘##’ seguidos significan tamaños de encabezados más pequeños.

# Este corresponde a la etiqueta <h1>
## Este corresponde a la etiqueta <h2>
###### Este corresponde a la etiqueta <h6>

Énfasis (negritas y cursivas)

Este es una característica que me encanta, puedes escribir negritas utilizando estrellas o guiones delante y detrás de las palabras y cursivas con estrellas o guiones, solo se diferencian en el número de estrellas o guiones.

*Este texto estará en cursiva*
_Esto también estará en cursiva_

**Este texto estará en negrita**
__Esto también estará en negrita__

_Puedes **combinarlos** como quieras_

Listas

Las listas que puedes utilizar, pueden ser numeradas o no numeradas. En las no numeradas puedes utilizar tanto guiones como estrellas.

Sin ordenar

* Elemento 1
* Elemento 2
    * Elemento 2a
    * Elemento 2b

Ordenadas

1. Elemento 1
2. Elemento 2
3. Elemento 3
    1. Elemento 3a
    1. Elemento 3b

Enlaces

Markdown soporta dos estilos para crear enlaces: ìnline y reference. Con ambos estilos puedes usar corchetes para delimitar el texto que deseas convertir en un enlace.

Enlace inline:

[enlace de ejemplo](http://example.com)
[enlace de ejemplo](http://example.com "Título Enlace")

Los enlaces reference te permiten hacer referencia a sus enlaces por nombres, que normalmente defines al final del documento:

Recibo diez veces más tráfico de [Google][1] que de [Yahoo][2] o [MSN][3].

[1]: http://google.com/ "Google"
[2]: http://search.yahoo.com/ "Búsqueda de Yahoo"
[3]: http://search.msn.com/ "Búsqueda de MSN"

El atributo de título es opcional. Los nombres de los enlaces pueden contener letras, números y espacios, pero no distinguen entre mayúsculas y minúsculas.

Empiezo mi mañana tomando un café con leche y me pongo a leer el [The New York Times][NY Times].

[ny times]: http://www.nytimes.com/

Imágenes

La sintaxis de las imágenes es muy parecida a la sintaxis de los enlaces:

En línea (los títulos son opcionales):

![alt text](/path/to/img.jpg "Título")

Estilo referencia:

![alt text][id]

[id]: /path/to/img.jpg "Título"

Citas

Si quieres utilizar citas, utiliza el carácter > antes de cada línea:

> "Café: la más fina suspensión orgánica jamás ideada... Pelearía con los Borg por él."
>
> - Captain Janeway.

Código en texto

Para escribir bloques de código en el texto, envuélvelos entre comillas invertidas:

El código es el siguiente: `var example = true`

Líneas Horizontales

Puedes generar una etiqueta de línea horizontal (que genera en html <hr /> colocando tres o más guiones, asteriscos o guiones bajos en una línea por sí mismos. Si quieres, puedes utilizar espacios entre guiones o asteriscos.

Cada una de las siguientes líneas producirá una línea horizontal:

* * *

***

*****

- - -
____

---------------------------------------

Diferentes especificaciones de Markdown

Desde la implementación original de John Gruber, no se ha añadido nada más, por que se creyó que era suficiente con las especificaciones que definieron. Esto ha conducido a que posteriormente se han querido añadir otras características que no cubría Markdown y se hayan creado diferentes especificaciones.

En esencia Markdown cambia poco de una especificación a otra, pero es interesante conocerlas para saber con qué estás trabajando.

Las especificaciones que existen principalmente son las siguientes:

• Markdown Extra se utiliza en WordPress.com y ha sido escrito por Michel Fortin. Incluye algunas características que originalmente no estában disponibles en Markdown, incluida la compatibilidad mejorada para HTML entre líneas, bloques de código, tablas y más.
• peg-multimarkdown es una implementación de MultiMarkdown derivada de John MacFarlane. Hace uso de una gramática de expresión de análisis (PEG) y está escrita en C. Este proyecto ha quedado obsoleto en favor de MultiMarkdown-6.
• MultiMarkdown es un superconjunto de Markdown que añade nuevas características de sintaxis, como notas al pie, tablas y metadatos. Además, ofrece mecanismos para convertir texto plano en LaTex con añadido de HTML.
• CommonMark es una especificación de sintaxis estándar e inequívoca para Markdown, junto con un conjunto de pruebas integrales para validar las implementaciones de Markdown con esta especificación.
• GitHub Flavored Markdown es una implementación de commonmark que está tan ampliamente extendida que se ha convertido en el estandar de facto de Markdown.

Github Flavored Markdown

Github.com utiliza su propia versión de la sintaxis de Markdown que proporciona un conjunto adicional de funciones útiles, muchas de las cuales facilitan el trabajo de la documentación en los repositorios de github.

Ten presente que algunas características de Github Flavored Markdown solo están disponibles en las descripciones y comentarios de los «Issues» y «Pull Requests» del código de github.com. Estos incluyen @menciones, así como referencias a SHA-1 hashes, «Issues» y «Pull Requests». La lista de tareas también están disponibles en los comentarios y los archivos markdown de Gist.

Resaltado de código

Aparte de la definición que hemos visto para definir el código, podemos usar otro resaltado como indica Github Flavored Markdown, con la definición del lenguaje:

​```javascript
function fancyAlert(arg) {
  if(arg) {
    $.facebox({div:'#foo'})
  }
}
​```

También podemos crear sangrías con cuatro espacios delante del código:

    function fancyAlert(arg) {
      if(arg) {
        $.facebox({div:'#foo'})
      }
    }

Un ejemplo sin resaltado de sintaxis con código Python:

def foo():
    if not bar:
        return True

Tablas

Las tablas no son parte de la especificación de Markdown, pero son ampliamente usadas y las puedes crear reuniendo una lista de palabras y dividiéndolas con guiones – (para la primera fila), y luego separando cada columna con una barra vertical |:

Se pueden utilizar dos puntos para alinear columnas:

| Tablas         | son                   | Chulas |
| -------------- |:---------------------:| ------:|
| columna 3 está | alineada a la derecha | 1600€  |
| columna 2 está | centradas             |   12€  |
| rayas de cebra | son limpias           |    1€  |

Esta tabla se convertirá en esta:

Otra opción para construir una tabla es tener al menos 3 guiones que separen cada celda del encabezado. Las barras verticales (|) son opcionales y no es necesario hacer la tabla Markdown alineada, puedes dejarla tal y como la escribes:

Markdown | Less | Pretty
--- | --- | ---
*Still* | `renders` | **nicely**
1 | 2 | 3

Esta tabla se convertirá en esta:

Lista de Tareas

Puedes utilizar lista de tareas, con un guión y un par de paréntesis con un espacio entre medio, un ejemplo es el siguiente:

- [x] se admiten @menciones, #referencias, [enlaces](), **formateo**, y <del>etiquetas</del>
- [x] la sintaxis de lista requiere cualquier lista ordenada o desordenada.
- [x] este es un elemento completo
- [ ] este es un elemento incompleto

Esto se convierte en lo siguiente:

• [x] se admiten @menciones, #referencias, [enlaces](), formateo, y etiquetas
• [x] la sintaxis de lista requiere cualquier lista ordenada o desordenada.
• [x] este es un elemento completo
• [ ] este es un elemento incompleto

Cuando incluyas una lista de tareas en el primer comentario de un «Issue» que se refiere al código de github.com, podrás ver una barra de progreso que te ayudará en tu lista de «Issues». ¡También funciona en «Pull Requests!

SHA references

Cualquier referencia SHA-1 hash en un commit se convertirá automáticamente en un enlace a ese commit en GitHub.

16c999e8c71134401a78d4d46435517b2271d6ac
mojombo@16c999e8c71134401a78d4d46435517b2271d6ac
mojombo/github-flavored-markdown@16c999e8c71134401a78d4d46435517b2271d6ac

Esto para quien no es programador, es indiferente, aunque siempre es interesante saber que existe.

Añadir referencias dentro de un repositorio

Como la característica anterior, esta también incumbe solo a los programadores. Los muggles nunca utilizaremos estas cosas.

Cualquier número que haga referencia a un Issue o un Pull Request se convertirá automáticamente en un enlace:

#1
mojombo#1
mojombo/github-flavored-markdown#1

Nombre de usuario con @menciones

Tecleando un símbolo de @ seguido de un nombre de usuario, notificará a esa persona para que vea el comentario. Esto se denomina «@mención», porque está mencionando a la persona. También puede @mencionar equipos dentro de una organización.

Esto solo vale para los archivos markdown que se escriban para github.com.

Así podrás poner un comentario en github.com del estilo: ¡Hola @kneath, me encanta tu jersey!

Enlaces automáticos para las URLs

Cualquier URL (como http://www.github.com/) se convertirá automáticamente en un enlace clicable. Aunque puede parecer obvio, el markdown estandard esto no lo contempla.

Tachado

Cualquier palabra envuelta con dos tildes (como ~~esta~~) aparecerá tachada.

Emoji

Los Emojis, ese gran invento del siglo XXI, está soportado por github. Aquí puede ver como utilizar emojis.

Para ver una lista de todos los emojis que puedes utilizar, aquí tienes la chuleta de Emojis.

Editor online para Markdown

Existen infinidad de editores online para que puedas practicar Markdown, el que te muestro a continuación es uno de tantos, pero me ha gustado porque es sencillo y te viene con una ayuda.

Dingus es una aplicación web que le permite escribir tu propio texto con formato Markdown y traducirlo a XHTML.

Extras con Markdown

A partir de aquí lo que vas a leer son extras que programadores han desarrollado a partir de la idea de escribir texto y que puedas generar marcas para generar otro tipo de documentos.

Recuerda que todo esto no es estándard de markdown y que para poder implementarlo en tu flujo de trabajo, tienes que acudir a herramientas de terceros.

Presentaciones con Markdown

Como habrás imaginado esto ni es estándard, ni está soportado por github, ni nada parecido, pero he de comentártelo porque ya que el pisuerga pasa por Valladolid podemos tener nuestras presentaciones con nuestras notas de texto.

La mayoría de presentaciones son poco más que texto e imágenes, y para eso este tipo de soluciones a mi me ha resultado muy interesante a la hora de simplificar mi flujo de trabajo.

Marp

Es un proyecto está en proceso de desarrollo y puedes ver más información aquí Puedes ver un ejemplo de cómo funciona.

Remark

Esta opción es mucho más versátil que la anterior, puedes ver el proyecto aquí. Puedes ver un ejemplo de presentanción que te explica como funciona remark. Puedes mejorar la presentación con CSS si te interesa. También existe una herramienta para convertir tus archivos markdown a presentación.

Mark Show

Desde mi punto de vista Mark Show es la mejor opción para hacer presentaciones online, ya que es super completa y permite hacer presentaciones elegantes empleando muy poco código.

Otras alternativas de presentaciones

Estas alternativas que te muestro son ya opciones más específicas, como por ejemplo convertir a Powerpoint o generar presentaciones que sean sin conexión a internet:

• Pandoc: con esta utilidad tienes formatos específicos a los que puedes convertir tu archivo.
• DZslides: otra opción si quieres hacer presentaciones elegantes con imágenes grandes y muy pocas palabras, una manera sencilla de hacerlo es con DZslides.
• Markdown Slides: con esta otra opción podrás escribir presentaciones simples con animaciones, fórmulas y archivos multimedia, que se pueden visualizar en un navegador web incluso sin una conexión a Internet, o exportar a PDF.

Mapas mentales con Markdown

Markmap es una combinación de Markdown y Mindmap. Como podrás suponer ni es estandard ni na da na, pero ofrece una posibilidad de hacer mapas mentales de manera muy rápida a tus archivos Markdown.

Esta utilidad extrae el contenido del archivo y con su estructura jerárquica genera un mapa mental interactivo en tu navegador web.

Puedes ver como funciona y más información en markmap.

Diagramas con Markdown

Como con todo lo anterior, a alguien se le ocurrió que igual que se pueden hacer presentaciones, también se podrían hacer diagramas con texto.

Así surgió mermaid, y la idea es que dentro de un documento markdown puedas escribir diagramas.

Como nota el markdown de github no soporta el renderizado de las gráficas, por lo que tendrás que convertirlos a imagen antes de subir estos archivos.

Fórmulas en Markdown

Para los que son de ciencias y números, no podían faltar las fórmulas en Markdown. En este caso el editor con el que trabajes debe soportar el poder previsualizar fórmulas ya que escribir lo vas a poder hacer, otra cosa es que las veas.

La sintaxis que se coge para las fórmulas es la de LaTex. También tienes una librería de javascript, que se llama MathJax, con la que puedes representar las fórmulas sin necesidad de convertirlas a imágenes.

Tienes una pequeña chuleta de fórmulas de LaTex para que empieces a practicar.

Wikilinks

Esta idea nació de las herramientas online que crean Wikis, ya que enlazan las páginas con el nombre de esta con dos corchetes, por ejemplo así: [[enlace-a-página]].

En markdown esto sería lo mismo que utilizar los enlaces, no hay ninguna diferencia. La diferencia está en los programas que implementan este tipo de enlaces.

Estos programas lo que hacen es relacionar los archivos markdown con Wikilinks como si fueran enlaces a páginas web, creando una base de datos de los archivos, y actualizando estos wikilinks en caso de que se cambie el nombre del archivo.

Esto genera una red de notas en la cual puedes trabajar tu conocimiento como si fuera una base de datos.

Conclusión

No he hablado en este artículo de exportar a PDF, ni a word, ni a HTML, pero he de decir que también es muy sencillo con algunos trucos y con posibilidades muy profesionales.

Markdown parece a priori que aporta poco a tu rutina diaria, pero he de decir que en mi caso me ha proporcionada una simplicidad, y al mismo tiempo una versatilidad que antes no tenía utilizando aplicaciones como LibreOffice o Microsoft Office.

Puede que este artículo lo hayas leido en diagonal y digas, ¡Cómo mola! ya mañana empezaré a usarlo, y luego se quedará para los propósitos del año que viene.

Interiorizar Markdown lleva un tiempo e integrarlo en tu flujo diario es un proceso lento, así que date la oportunidad y tiempo para hacerlo.

Yo he tardado como un año en que mi cerebro se acostumbre a esta manera de escribir y generar memoria muscular, y tengo que decir que es una de las mejores inversiones de aprendizaje que he hecho.

Te dejo ahora a ti que descubras por ti mismo las posibilidades que tiene.

Recuerda que si te ha gustado lo que has leído puedes apoyar este proyecto a través de tus compras en Amazon, si, si, has leído bien, apoyar el proyecto. Con las compras que hagas de amazon me estarás ayudando a seguir haciendo este tipo de artículos.

Solo tienes que ir aquí y pegar la URL del producto de amazon que quieres comprar.

Tan simple como eso.

Y tan fácil.

Se feliz, y disfruta este día como si fuera una gran aventura.