Un proyecto de programación es tan útil como la documentación que va con él. Hay quien dice que una aplicación es documentación con un poco de código añadido.
Como mínimo, necesitan un fichero README.md que explique la
intención del proyecto y qué hacer para instalarlo, así como cualquier
información adicional como quienes son los programadores y de qué
van. Markdown,
un lenguaje que permite añadir marcas simples para indicar el papel de
ciertas palabras en la estructura del documento, es una de las
soluciones más universales.
Markdown es un lenguaje de marcado ligero que, una vez interpretado, permite dar formato a un texto. Con este lenguaje, la meta es poder formatear de forma sencilla, donde la lectura sea clara y tener la posibilidad de convertir el resultado a otros formatos, como HTML o PDF.
Cuando no está interpretado, es decir, es texto plano, ya proporciona bastante información. Es muy visual. Esto lo convierte en una herramienta genial para documentar nuestros programas, ya que en el código fuente, en general, no tendremos ningún tipo de interpretación de las marcas del lenguaje.
Por otro lado, si utilizamos herramientas para generar documentación a partir del código fuente de nuestro programa, nos vemos obligados a aprender la sintaxis propia de esa herramienta, lo que se convierte en algo horrible teniendo en cuenta que cada lenguaje aporta su propio generador de documentación de una forma más o menos estándar. Con Markdown podemos escribir siempre siguiendo el mismo formato y generar nuestra documentación con las mismas herramientas, o similares, que las sugeridas en cada lenguaje; de hecho, Markdown se ha convertido en algo tan habitual que la mayoría de estas herramientas han incorporado algún tipo de extensión para soportarlo.
También es muy útil para la generación de páginas estáticas creadas con software como Jekyll, o, como estamos utilizando Go, Hugo. Estas herramientas nos permiten completar enriquecer nuestra documentación o crear un blog o una página estática, yendo más allá de la documentación del propio código.
Pero es que el uso de Markdown expande sus horizontes más allá del ámbito puramente relacionado con la programación y desarrollo de software: redacción de artículos de investigación, formateo de comentarios en sitios como reddit o el mismo StackOverflow mencionado anteriormente. Y también, por supuesto, para escribir libros como el que estás leyendo ahora mismo son algunos de los usos que otra mucha gente da a este lenguaje.
Un documento, en general, va a tener un título principal y luego una serie de
secciones, con una jerarquía inferior, que estructuran el texto en partes
relacionadas. Un README, por ejemplo, tendrá, tras una introducción,
instrucciones para instalar, para ejecutar y quizás una nota sobre la licencia
o sobre cómo colaborar con el mismo.
Si quieres poner cabeceras a tu texto, algo así como los títulos de cada
sección, solo tienes que escribir el carácter almohadilla y un espacio antes
de la frase a resaltar. Cuantas más almohadillas pongas, más abajo en la
jerarquía estará esa cabecera. Es decir, # Este es el nombre de mi proyecto
y ## Cómo instalar. ### Instalar desde GitHub y así.
Por ejemplo, si quieres tener tu texto en cursiva, solo necesitas abrir y
cerrar la oración con un asterisco, tal que *este texto se muestra en cursiva*. También vale la barra baja "_" en lugar del asterisco. ¿Qué tengo
que hacer si quiero poner ese mismo texto en negrita? En lugar de utilizar un
asterisco, utiliza dos. También vale para el caso del carácter "barra baja".
Osea, **este texto estaría en negrita**. Y **_este otro estaría en negrita y cursiva_**.
Markdown no interpretará, al menos por defecto, cuando quieras incluir
en tu texto un enlace a una página web. Para incluir uno, tienes que hacerlo
de la forma siguiente:[Texto a mostrar](URL a la que ir). ¿Así de fácil? Así
de fácil.
Insertar imágenes es muy parecido a insertar enlaces: la estructura es
la misma, salvo que tenemos que poner un signo de admiración justo antes
del primer corchete. Osea, . En cuanto
al "texto a mostrar", es el texto que verás si la imagen no carga o, si por
ejemplo has exportado el documento a HTML, el texto que se muestra
al poner el cursor del ratón encima.
¿Qué hay en un texto más enriquecedor que hacer referencia a otros textos
o, incluso, a lo que simplemente alguien dijo en algún momento? Para insertar
una cita, solo necesitamos iniciar la cita con el carácter "mayor que". Imagina
que queremos citar a John Johnson, entonces: > "Primero resuelve el problema. Entonces, escribe el código". Este texto se interpretará como:
"Primero resuelve el problema. Entonces, escribe el código"
Las listas tampoco podían faltar. Aquí tenemos dos opciones:
- Listas sin orden: para estas listas solamente necesitas poner cada elemento de la lista en una nueva línea y preceder dicha línea por un asterisco y un espacio. Un ejemplo de lista sería:
`* Resolver el problema`
`* Escribir el código`
`* Compartir la solución`- Listas ordenadas: tienes que precederlas por un número seguido de un punto:
`1. Resolver el problema`
`2. Escribir el código`
`3. Compartir la solución`Imagina que por alguna razón, no numeras bien la lista. ¡No pasa nada! El intérprete se dará cuenta y mostrará correctamente la lista ordenada.
¿Y qué pasa si quiero hacer una lista dentro de un elemento de una lista? Solamente tienes que añadir un nivel de indentación. Por ejemplo:
`* Resolver el problema`
` * Mirar posibles soluciones`
` * Establecer cual es la más adecuada`
`* Escribir el código`
` * Elegir un lenguaje`
` * Elegir los tipos de dato más adecuados`
`* Compartir la solución`
` * Publicarla en Github`
` * Escribir un artículo sobre ello`Resultaría en:
- Resolver el problema
- Mirar posibles soluciones
- Establecer cual es la más adecuada
- Escribir el código
- Elegir un lenguaje
- Elegir los tipos de dato más adecuados
- Compartir la solución
- Publicarla en Github
- Escribir un artículo sobre ello
Con esta pincelada, tienes casi todo lo que hay que saber sobre Markdown. Pero Markdown es una base que tiene diferentes sabores. Algunos, como el de GitHub, tienen algunas otras marcas que pueden ser muy útiles, como listas de tareas, tablas o resaltadores de sintaxis. Incluso emojis.
Markdown es un buen lenguaje para enriquecer el texto plano. Con unas pocas reglas de sintaxis puede hacer que tu texto incluya negritas, cursivas o cabeceras entre otros. Además, es el lenguaje que se usa en webs como las que se alojan en Github. Pero ese ya es otro capítulo.