Qué es Markdown o cómo estilizar el README de tus repositorios.

8 min readJun 7, 2021

Bienvenidos todos a mi primera publicación para Kodemia. Aquí aprenderemos que es Markdown y cómo nos sirve para generar increíbles README para los repositorios de nuestros proyectos.

¿Qué es un README?

El README es el punto de entrada a un proyecto, su función principal es explicar a los ajenos a este; de que trata, el como funciona y que se necesita para usarlo, esto no impide que muchas personas se pongan creativas y agreguen cosas extra como gifs, lista de colaboradores, capturas de pantalla o medallas que reflejan el estatus y las tecnologías del proyecto.

También es lo que toman muchos servicios donde de concentran paquetes para diferentes lenguajes como la portada de la librería, framework, etc…

Flutter Pub.dev y Npm Js preview del paquete utilizando sus readme

¿Cómo agrego un README a mi proyecto?

Para agregar un README basta con crear un archivo README.md en la raíz de tu proyecto. Este archivo es de tipo markdown, lo sabemos gracias a su extensión md, pero…

… ¿Qué es Markdown?

Markdown es un lenguaje de marcado ligero inventado por John Gruber, nos permite editar texto de manera sencilla y con archivos pequeños, a diferencia de HTML o XML donde la complejidad llega a crecer demasiado.

Nota: Aquí usaremos la version de markdown propuesta por Github ya que es de las mas aceptadas en todo internet

Esta edición de texto se hace a partir de símbolos que anteceden o rodean al texto al que queremos dar formato. Por ejemplo:

Para colocar una palabra en negritas utilizamos doble asterisco ** entonces algo como esto **Palabra** se convierte en Palabra.
Para un trozo de código pequeño utilizamos ` haciendo que algo como `esto` se vea así esto

Así como estos tenemos una lista de elementos

Headers o Títulos se les antepone desde una a seis almohadillas # dependiendo que tanta jerarquía tenga el texto que queremos estilizar.

Cabe notar que el elemento de mayor jerarquía es el que menos almohadillas tenga y que el titulo siempre tendrá una linea debajo.

Para itálicas utilizamos un asterisco * o un guion bajo _ antes y después de lo que queremos estilizar.
Para negritas utilizamos doble asterisco ** o doble guion bajo __ antes y después de lo que queremos estilizar.

Podemos mezclar y anidar estos estilos sin problemas, cabe notar que es mas común utilizar el guion bajo cuando se necesitan itálicas y los asteriscos cuando se requieren negritas.

Ahora, si necesitamos que una palabra aparezca rodeada de
* o _ sin que se aplique el estilo podemos escapar dichos símbolos precediéndolos con una \

Todos lo caracteres que podemos escapar son:

\ Diagonal invertida
` Acento agudo francés
* Asterisco
_ guion bajo
{} llaves
[] Corchetes
() Paréntesis
# Almohadillas
+ signo de mas
- signo de menos o guion
. punto
! símbolo de exclamación de cierre

Hay ocaciones donde queremos recalcar alguna cita importante

Para citar simplemente hay que utilizas cuñas de cierre > al inicio de cada renglón de la cita.

Y por si te lo preguntas, si, en las citas también podemos utilizar las negritas e itálicas

Aunque, no siempre vamos a necesitar poner párrafos, muchas veces necesitamos enumerar o listar elementos

Una lista se puede crear de dos formas; numerada, donde cada renglón lo antecede un numero seguido de un punto 1. y desordenadas, donde los renglones los antecede un asterisco * (el menos y mas también funcionan)

Y como te lo imaginas se pueden combinar listas y estilos de texto

Ejemplo de lista con sub listas y estilo

Ademas de listas comunes podemos agregar listas con checkboxes para marcar cosas que hayamos realizado

Para el checkbox se usa la siguiente sintaxis

- [ ] texto Esto no está marcado
- [x] texto Esto si está marcado

Siguiendo la parte del formato, también podemos crear tablas de la siguiente manera

La sintaxis de la tabla es:

escribir los headers de las columnas separados por un pipe |

el siguiente renglón deben ser guiones medios separados por pipes a la misma altura que los de los headers

Los siguientes renglones son los elementos por renglón de cada columna separados por pipes al final del elemento

Esta es la sintaxis mas compleja de Markdown, pero un buen ejemplo siempre ayuda a aclarar la teoría

Ahora posiblemente estes pensando “muy bonito el texto y todo, pero una imagen vale mas de mil palabras” y tienes razón por eso Markdown también incluye una forma de agregar imágenes en nuestros documentos.

Una imagen se incluye con la sintaxis:

![Titulo de la imagen](url_de_la_imagen)

Hay que notar que no hay for de definir dimensiones a la imagen

Pero que pasa si queremos agregar algo de navegación, es simple, podemos agregar enlaces a nuestras palabras u oraciones, incluso imágenes

Un enlace se incluye con la siguiente sintaxis:

[elemento_clicleable](url_del_enlace)

Para la imagen basta con mezclar la sintaxis de imagen y la sintaxis del enlace

Podemos hacer que estos textos se vean más vivos utilizando emojis.

Solo escribe el nombre del emoji entre dos :emoji_name:

Hay que notar que esto solo funciona en Github y todos los servicios que soporten el Markdown con sabor a github.

Esto está genial, pero nosotros somos desarrolladores y no vamos a estar poniendo ejemplos de código en imágenes, nosotros necesitamos extractos de código directo y markdown nos tiene cubiertos.

Un bloque de código pequeño (un renglón como máximo) se utiliza escribiendo el acento agudo francés ` antes y después del código, es util para ejemplificar nombres de archivos, variables y tipos de datos.
Un bloque de código mas complejo se logra con la siguiente sintaxis

tres acentos agudos franceses seguido del nombre del lenguaje para la apertura, el código a mostrar, cerramos con tres acentos agudos franceses

```lenguaje a utilizar Todo el código que queramos No importa cuanta lineas Sea ```

Definir el lenguaje nos agrega el sintaxis highlight haciendo que nuestro código sea mas fácil de leer

Bueno, ya tenemos muchos elementos para crear secciones en nuestro readme, pero como podemos separar estas secciones, simplemente agregamos una linea

Para agregar una linea basta con poner tres guiones medios ---

Pensando fuera de la caja

Con todos estos elementos ya podemos crear un readme con todas las de la ley, pero siempre se puede llegar mas lejos si utilizamos un poco de imaginación.

Shields

Aprovechándonos de la capacidad de Markdown de poner imágenes podemos agregar pequeñas medallas a nuestro readme que reflejen que tecnologías utilizamos, la version, o incluso enlazarlas con endpoints donde chequemos el estatus del build y reflejarlo en el repo, esto ultimo es mas avanzado así que lo omitiremos por ahora.

Pasos para poner una medalla:

Acceder a https://shields.io/
bajar a la sección “your badge” y llenamos los datos

Label: es el texto del lado oscuro del shield

Message: es lo que aparece del lado con color

Color: es el color que tendrá el shield en el lado del mensaje

Damos click en el botón “Make Badge”

esto nos llevara a una pagina donde se ve una preview del shield, pero lo que nos interesa es el URL

https://img.shields.io/badge/hello-word-pink

ya solo necesitamos agregar una imagen en markdown para que se vea el shield

Como vemos quedan en la misma linea y se ven genial a un lado del titulo

Si nos echamos un clavado al resto de la pagina de shields podremos ver que hay opción para cambiar el estilo, iconos, colores personalizados, etc…

Agregar Formulas

Aprovechándonos de nuevo de las imágenes podemos agregar formulas. Solo necesitamos entrar a https://latex.codecogs.com/

Codecogs nos permite utilizar Latex para crear imágenes svg de formulas, agregando el url de esta imagen podemos agregar formulas en nuestro readme.

https://latex.codecogs.com/svg.latex?x%3D%5Cfrac%7B-b%5Cpm%5Csqrt%7Bb%5E2-4ac%7D%7D%7B2a%7D

Hay que recalcar que estas imágenes tienen fondo blanco con letras negras, lo cual puede dificultar su lectura en fondos oscuros

Hacer un indice

Usando una de las habilidades de Github para acceder a diferentes secciones del readme mediante enlaces. Básicamente Github agrega un enlace interno a los títulos del readme, podemos tomar esos enlaces y crear enlaces a esas secciones utilizando links de markdown

Y si nos damos cuenta de que los archivos, directorios ramas y commits del repo tienen un enlace asociado también podríamos crear indices bastante mas complejos

Agregar Sub Readme

Tomando ventaja de como muestra Github las carpetas de los repos podemos agregar un readme a cada carpeta del repo y explicar cada sección de manera más detallada.

Esto es muy util si tenemos un repositorio monolítico donde tengamos varios proyectos y queramos detallar cada proyecto con su readme teniendo un readme principal en donde tengamos un indice con links a los readme de los diferentes proyectos del repositorio monolítico.

Eso es todo por hoy, espero que estos tips los ayuden a crear repositorios que impresionen y lo invito a seguirme en redes sociales, aparezco como @rurickdev en Twitter, Github, LinkedIn y demás redes sociales.

Gracias por leernos, hasta la próxima