Cómo usar Markdown en GitHub y Reddit de forma rápida

Informatec Digital » Recursos » Cómo usar Markdown en GitHub y Reddit de forma rápida

Si sueles escribir en GitHub o pasas bastante tiempo en Reddit, dominar Markdown es una de esas cosas que te ahorran horas y te hacen la vida más fácil. Es un lenguaje de marcado muy ligero que te permite dar formato a un texto plano de forma rápida, sin pelearte con menús ni botones, solo con unos cuantos símbolos colocados en los sitios correctos.

En GitHub lo vas a encontrar por todas partes: en los archivos README.md de los repositorios, en las issues, en las pull requests, en las discusiones e incluso en tu propio perfil. Reddit, por su parte, usa una variante llamada Snoomark (Markdown con sabor Reddit) que hereda buena parte de la sintaxis de GitHub, con algunas características propias y ciertas limitaciones. Vamos a ver, paso a paso y con muchos ejemplos, cómo usar Markdown en GitHub y en Reddit de forma rápida y sin dejarte nada importante en el tintero.

Qué es Markdown y por qué es tan útil en GitHub y Reddit

Markdown es un lenguaje de marcado ligero ideado para que el texto sin formato sea fácil de leer y de escribir, pero que al mismo tiempo se pueda transformar a HTML sin esfuerzo. En la práctica, esto significa que puedes escribir texto normal y añadir algunos caracteres especiales para conseguir títulos, listas, tablas, citas, código formateado, enlaces o imágenes.

En GitHub, la implementación que se usa es GitHub Flavored Markdown (GFM), que amplía la sintaxis clásica con tablas, listas de tareas, resaltado de código avanzado, soporte de colores, alertas y algunas etiquetas HTML permitidas. Todo esto se renderiza automáticamente en los archivos .md y en los campos de comentarios de la plataforma.

Reddit usa su propio procesador llamado Snoomark, una versión derivada de GFM. Comparte buena parte del comportamiento básico (negritas, cursivas, encabezados, listas, citas, código en línea o en bloque, enlaces…), pero tiene particularidades importantes: por ejemplo, el soporte de imágenes es más limitado según el contexto y añade elementos propios como los spoilers.

La gracia de todo esto es que, con una sola sintaxis, puedes escribir textos que se ven bien tanto en GitHub como en Reddit, adaptando solo algunos detalles donde cada plataforma funciona de forma distinta. Aprender las reglas básicas te permite moverte con soltura en las dos sin tener que reaprender nada de cero.

Encabezados y estructura del contenido

Una de las primeras cosas que usarás son los encabezados, tanto en GitHub como en Reddit. Sirven para estructurar el texto en secciones y subsecciones.

En Markdown, un encabezado se crea anteponiendo de uno a seis símbolos de almohadilla al texto: uno para un título de nivel 1, dos para nivel 2, y así hasta el nivel 6. Por ejemplo, en un README.md de GitHub podrías tener algo como: # Título principal, ## Sección, ### Subsección, etc.

GitHub, cuando encuentra dos o más encabezados en un archivo, genera automáticamente una tabla de contenido accesible desde el icono de “Esquema” en la parte superior del archivo. Cada título aparece como un enlace que te lleva directamente a esa sección, lo que viene genial en documentos largos.

Además, cada encabezado se convierte en un ancla interna a la que puedes enlazar con un fragmento de URL basado en el texto del título. Para generar ese fragmento, GitHub aplica unas reglas muy concretas: convierte las letras a minúsculas, reemplaza los espacios por guiones, elimina caracteres de puntuación y formato (como cursivas), recorta espacios sobrantes y, si el resultado coincide con otro encabezado previo, añade un sufijo numérico (-1, -2, etc.) para que sea único.

Esto permite hacer cosas como colocar una sección ## Sample Section y luego enlazarla desde otro punto del documento con un enlace del estilo (#sample-section), o incluso enlazar a secciones con caracteres especiales en el título, ya que GitHub genera el fragmento siguiendo esas reglas y lo hace accesible con el mismo patrón.

Énfasis, texto destacado y citas

Markdown te deja resaltar texto usando varias formas de énfasis: negrita, cursiva, texto tachado, subíndice, superíndice o subrayado. En GitHub, la tabla de estilos típica quedaría más o menos así, aunque aquí lo resumimos con palabras distintas:

Para poner texto en negrita, se rodea con dobles asteriscos o dobles guiones bajos; para la cursiva, se usan asteriscos o guiones bajos simples; para tachar algo, se recurre a la doble virgulilla (dos tildes de la ñ) a cada lado del fragmento. También se pueden combinar negrita y cursiva anidadas, usar tres asteriscos para aplicar ambas a todo un tramo de texto, o recurrir a etiquetas HTML como _{y ^{para subíndices y superíndices, y para subrayados.}}

GitHub permite además crear citas tipo blockquote anteponiendo el símbolo mayor que al comienzo de la línea. El texto citado se muestra con una barra vertical a la izquierda y en gris, destacándose de forma clara. Se pueden tener varias líneas dentro del mismo bloque de cita, e incluso anidar citas añadiendo más símbolos > al inicio.

Una forma avanzada de cita que solo existe en GitHub son las alertas o admoniciones. Se basan en la misma sintaxis de blockquote, pero la primera línea incluye un marcador especial para indicar el tipo de alerta. Por ejemplo, puedes especificar para información útil, para consejos prácticos, para datos clave, para avisos urgentes y para advertir de riesgos o consecuencias negativas. GitHub muestra cada tipo con un color e icono diferente, ayudando a resaltar información crítica en la documentación.

Reddit también soporta citas simples con el mismo símbolo >, aunque no cuenta con el sistema de alertas enriquecidas de GitHub. Aun así, sigue siendo una forma muy útil de responder a alguien citando parte de su mensaje sin repetirlo completo.

Resaltado de código, bloques y colores

Tanto GitHub como Reddit permiten destacar fragmentos de código dentro del texto usando comillas invertidas. Para código en línea, se encierra la palabra o comando con una sola comilla invertida a cada lado. Esto es ideal para resaltar, por ejemplo, un git status dentro de una frase, dejando claro que es un comando.

Cuando quieres un bloque de código independiente, Markdown usa tres comillas invertidas: escribes una línea con tres backticks, luego el código en líneas separadas y cierras con otros tres backticks. En GitHub, si además indicas el lenguaje justo después de las primeras comillas invertidas, se aplica resaltado de sintaxis con colores y formato específico para ese lenguaje.

GitHub ofrece también una función específica para resaltar valores de color dentro de comillas invertidas. Si escribes un color en formato hexadecimal, RGB o HSL entre backticks, la plataforma incluye un pequeño indicador de color al lado del texto. Por ejemplo, si el fondo en modo claro tiene el color #ffffff y en modo oscuro #000000, destacar esos códigos permite ver rápidamente cuál es cuál.

En cuanto a la visualización del código y las tablas, GitHub te deja activar una fuente monoespaciada fija en todos los campos de comentarios para que trabajar con texto técnico sea más cómodo. Si editas muchos fragmentos de código desde el navegador o en editores como Visual Studio Code, activar esta opción hace que la alineación y lectura sean mucho más coherentes.

Reddit también soporta bloques de código con backticks, tanto en línea como en bloque, aunque su uso allí se centra más en pequeños fragmentos o pseudocódigo que en documentación larga como la de un repositorio.

Enlaces, anclas y navegación interna

Crear enlaces en Markdown es muy sencillo: se encierra el texto que se va a mostrar al usuario entre corchetes y la URL entre paréntesis. Esto funciona tanto en GitHub como en Reddit, y se puede complementar con atajos de teclado en GitHub (por ejemplo, usar combinaciones de teclas para convertir rápidamente texto seleccionado en un enlace).

GitHub añade algunas funcionalidades extra relacionadas con la navegación. Por un lado, permite enlazar directamente a encabezados usando las reglas de generación de fragmentos comentadas antes. Por otro, soporta enlaces relativos dentro del propio repositorio, algo clave en documentación técnica.

Un enlace relativo es aquel que se calcula tomando como referencia el archivo actual. Por ejemplo, si tu README está en la raíz del proyecto y quieres enlazar un archivo docs/CONTRIBUTING.md, basta con escribir un enlace cuya ruta sea docs/CONTRIBUTING.md. GitHub se encarga de traducir ese enlace relativo de forma correcta en cualquier rama en la que te encuentres, lo que evita que se rompan al cambiar de rama o clonar el repositorio.

La recomendación es usar siempre rutas relativas para navegar entre archivos del mismo repositorio, porque los enlaces absolutos pueden dejar de funcionar en clones o forks. GitHub permite utilizar operadores estándar como ./ o ../ y rutas que empiecen por / relativas a la raíz del proyecto.

Si quieres crear puntos de anclaje personalizados dentro de un documento más allá de los encabezados, puedes recurrir a etiquetas HTML <a> con atributo name. Esto permite situar un punto de destino en medio de un párrafo o junto a un texto que no tiene título propio, y enlazar a él usando la misma sintaxis que para los encabezados generados automáticamente.

Imágenes en GitHub: Markdown, HTML y rutas relativas

En GitHub, las imágenes se insertan generalmente con la misma sintaxis que los enlaces, pero precedida por un signo de exclamación. Entre corchetes se especifica el texto alternativo (alt) y entre paréntesis la URL o la ruta de la imagen. Este texto alternativo es importante para la accesibilidad, ya que es lo que leerán los lectores de pantalla y lo que se mostrará si la imagen no carga.

Las imágenes pueden proceder tanto de archivos del propio repositorio como de URLs externas. GitHub permite múltiples patrones de rutas relativas para cargar imágenes desde distintas ramas, desde otros repositorios o incluso desde issues y comentarios, utilizando sufijos como ?raw=true para forzar la descarga directa del archivo cuando es necesario.

Además de la sintaxis estándar de Markdown, GitHub soporta el uso del elemento HTML <picture>. Este elemento es especialmente útil para cargar imágenes responsivas que cambian según las preferencias de tema del usuario (claro u oscuro). Mediante la media query prefers-color-scheme puedes definir distintas fuentes de imagen para cada modo, y una imagen por defecto para navegadores que no soportan esta característica.

El patrón típico consiste en incluir dentro de <picture> varios elementos <source> con sus atributos media y srcset, y al final un <img> con el atributo alt y una URL genérica. Así se consigue que quien use modo oscuro vea una imagen adaptada, y quien esté en modo claro reciba otra distinta, sin tener que duplicar contenido en el README.

GitHub también admite comentarios HTML en los archivos Markdown, lo que te permite agregar recordatorios invisibles al lector, por ejemplo para recordar que debes actualizar una sección de imágenes o añadir nuevos ejemplos más adelante.

Tablas, secciones plegables y separación de contenido

Una de las mejoras más útiles de GitHub Flavored Markdown es el soporte de tablas. Puedes organizar datos en filas y columnas usando barras verticales para separar celdas y una fila de guiones para marcar el encabezado. También es posible alinear columnas a la derecha, a la izquierda o al centro, utilizando dos puntos en la fila de separación.

Las tablas son muy útiles para presentar listas de lenguajes de programación, frameworks usados, tareas planificadas, comparativas de características o cualquier otra información que se beneficie de una estructura matricial. GitHub renderiza estas tablas con un estilo limpio y legible.

Para mantener ordenado un README largo, puedes usar la etiqueta HTML <details> para crear secciones plegables. Estas secciones muestran un resumen dentro de la etiqueta <summary> y permiten que el usuario expanda o contraiga contenido adicional según lo necesite. Es habitual encerrar tablas o bloques de información secundaria dentro de <details> para no saturar a simple vista.

Si quieres que la sección aparezca desplegada por defecto, basta con añadir el atributo open a <details>. Esta técnica es muy práctica para agrupar rankings, listas largas o contenidos que no son esenciales para una primera lectura pero que conviene tener accesibles.

Otra herramienta sencilla para organizar la información es la regla horizontal. Se genera escribiendo tres o más guiones en una línea y sirve para trazar una línea divisoria entre secciones, permitiendo separar claramente, por ejemplo, una parte descriptiva de una sección de referencias o de notas adicionales.

Estas reglas se pueden combinar con citas al final del documento para resaltar frases inspiradoras, recordatorios o mensajes clave. Un ejemplo típico sería colocar una cita motivacional al final de tu README de perfil, formateada con un blockquote después de una línea separadora.

Comentarios ocultos y control del formato

GitHub te permite introducir comentarios HTML dentro del Markdown usando la sintaxis <!– comentario –>. Todo lo que coloques dentro de ese comentario no se mostrará en el contenido renderizado, pero sí será visible en el código fuente, por lo que es ideal para notas internas o tareas pendientes.

Por ejemplo, en un README de perfil puedes añadir un comentario que diga algo como que tienes que ampliar la sección “About me” más adelante o que necesitas revisar una tabla de tecnologías obsoletas, sin que nadie que visite el perfil lo vea directamente.

Otra función útil es la de escapar caracteres que normalmente se interpretarían como Markdown. Si necesitas mostrar literalmente asteriscos, almohadillas u otros símbolos sin que se transformen en formato, basta con anteponer una barra invertida a cada uno. Esto permite, por ejemplo, escribir expresiones que incluyan símbolos de lista sin convertirlas en listas reales.

Cuando ves un archivo de marcado en GitHub, tienes la opción de alternar entre la vista renderizada y el código fuente con un botón en la parte superior (o abrirlo en editores como Brackets). Desactivar la interpretación de Markdown te deja acceder a funciones típicas de la vista de código como enlazar líneas concretas, algo muy útil cuando quieres señalar una parte exacta de un README o de cualquier archivo .md.

Por último, recuerda que GitHub procesa de forma diferente los saltos de línea en comentarios (issues, PRs, etc.) y en archivos .md. En comentarios, los saltos de línea se respetan directamente, mientras que en archivos Markdown necesitas añadir dos espacios al final de la línea, una barra invertida o un <br/> para forzar el salto dentro del mismo párrafo.

Listas, listas anidadas y listas de tareas

Las listas son uno de los elementos más usados en Markdown, tanto en GitHub como en Reddit. Puedes crear listas no ordenadas anteponiendo un guion, un asterisco o un signo más a cada elemento de la lista. Todas estas marcas se renderizan de forma similar como viñetas.

Para generar listas ordenadas, se numera cada línea con un número seguido de un punto y un espacio. Aunque el orden de los números no tiene por qué ser perfecto (GitHub suele recalcularlo), es buena idea mantener una numeración coherente para que el código fuente sea legible.

Las listas anidadas se crean simplemente añadiendo sangría a los elementos inferiores. En editores monoespaciados como Sublime Text, basta con alinear visualmente las marcas de lista anidada debajo del primer carácter del texto del elemento superior. En contextos como el editor de comentarios de GitHub, donde la fuente no es monoespaciada, conviene contar cuántos caracteres hay antes del texto y usar ese número de espacios para la sangría.

También puedes construir varios niveles de anidación, siempre que mantengas la coherencia en el número de espacios. Para listas muy complejas, este sistema requiere un poco de práctica, pero una vez interiorizado es muy rápido de aplicar.

GitHub ofrece además las listas de tareas, muy útiles en issues, pull requests y documentación. Se crean anteponiendo un guion, un espacio y una pareja de corchetes con espacio en blanco o con una x dentro: para tareas pendientes y para tareas completadas. Estas listas se renderizan con casillas de verificación que se pueden marcar o desmarcar desde la interfaz.

Si el texto de un elemento de lista de tareas comienza por un paréntesis, es necesario escaparlo con una barra invertida para evitar confusiones en el parser. Es un pequeño detalle, pero importante cuando redactas descripciones que empiezan por algo como (Opcional) o similar.

Menciones, referencias y emojis en GitHub

Una de las ventajas de escribir en Markdown en GitHub es poder usar menciones directas a usuarios y equipos de la plataforma. Simplemente escribes @ seguido del nombre de usuario o del equipo, y GitHub dispara una notificación a esa cuenta, atrayendo su atención a la conversación.

Al escribir el símbolo @, GitHub despliega una lista de usuarios y equipos relacionados con el repositorio o el hilo, y puedes ir filtrando esa lista a medida que tecleas. Con las flechas y la tecla Enter o Tab aceptas la sugerencia. En el caso de los equipos, se usa la forma @organizacion/nombre-del-equipo y todos sus miembros quedan suscritos al hilo.

Además de menciones, GitHub facilita referenciar issues y pull requests con solo escribir # seguido de un número o parte del título. Se muestra una lista de resultados sugeridos que puedes completar de la misma forma que con las menciones. Esto agiliza muchísimo la navegación entre conversaciones relacionadas.

Si en tu repositorio se han configurado referencias autovinculadas personalizadas, también es posible que determinadas notaciones externas (como identificadores de tickets de JIRA o Zendesk) se transformen automáticamente en enlaces cortos. Esta configuración requiere permisos administrativos, pero una vez activada permite cruzar información entre sistemas con un esfuerzo mínimo.

Por último, GitHub admite emojis mediante código: escribiendo dos puntos, seguido del nombre del emoji y terminando de nuevo con dos puntos. Al empezar a escribir aparece una lista de sugerencias que puedes aceptar con Tab o Enter. Incorporar emojis en tus comentarios ayuda a darles un tono más humano, siempre que no abuses de ellos en documentación formal.

Notas al pie y contenido avanzado

GitHub soporta también notas al pie usando una sintaxis basada en corchetes y un identificador con un carácter de intercalado. En el punto donde quieres la referencia, insertas algo como , y al final del documento defines el texto de esa nota con la misma etiqueta, seguida de dos puntos y el contenido.

Las notas al pie pueden tener varias líneas, y para forzar saltos dentro de la nota se utilizan espacios dobles al final de la línea, igual que en el cuerpo principal del Markdown. Al renderizar, GitHub muestra un superíndice en el texto y una lista de notas al pie al final, con enlaces de ida y vuelta para moverse entre referencia y nota.

Otro elemento avanzado que ofrece GitHub son las alertas ya comentadas (NOTE, TIP, IMPORTANT, WARNING y CAUTION). Es recomendable utilizarlas solo cuando sea realmente necesario, y no encadenar demasiadas una detrás de otra para no saturar al lector. No se pueden anidar dentro de otros elementos complejos, así que conviene planificar bien dónde se colocan.

Por último, puedes pedirle a GitHub que oculte temporalmente secciones de Markdown renderizado envolviéndolas en comentarios HTML, o que ignore el procesamiento de ciertos caracteres con barras invertidas. Esto es especialmente útil cuando estás documentando la propia sintaxis de Markdown y necesitas mostrar ejemplos tal cual, sin que se interpreten.

Markdown en Reddit: Snoomark y modo de edición

Reddit es una plataforma de discusión en la que casi cualquier tema tiene cabida, organizado en subforos llamados subreddits. A nivel de formato, ofrece dos editores: uno de texto enriquecido más visual y otro de texto plano basado en Markdown. Si quieres ir rápido y tener un control fino sobre el resultado, te interesa usar la opción de Markdown.

Por defecto, Reddit suele activar el editor de texto enriquecido, así que para cambiar al modo de marcado tienes que hacer clic en la opción Markdown mode dentro del cuadro de escritura de un post o comentario. A partir de ahí, puedes usar la sintaxis Snoomark de forma directa.

Si prefieres que siempre se cargue el editor de Markdown, debes ir a la configuración de usuario, entrar en la sección de ajustes del feed (Feed Settings) y activar la opción Default to markdown. De este modo, cada vez que empieces a escribir un post o un comentario se abrirá el editor de Markdown sin que tengas que cambiarlo a mano.

Reddit soporta la mayoría de elementos básicos y avanzados de Markdown: encabezados, negritas y cursivas, listas, citas, bloques de código, enlaces y algunos extras propios como los spoilers. Sin embargo, tiene carencias relevantes respecto a GitHub, especialmente en el manejo de imágenes, que depende bastante del contexto y del tipo de editor.

Sintaxis soportada por Reddit y spoilers

La variante Snoomark que usa Reddit incluye muchos elementos en común con GitHub, así que si ya dominas Markdown en repositorios, trasladar ese conocimiento al entorno de Reddit es bastante directo. Puedes usar encabezados para estructurar publicaciones largas, listas numeradas o con viñetas, citas para responder a otros usuarios y bloques de código cuando quieras mostrar comandos o fragmentos técnicos.

Una de las diferencias notables es la forma en que Reddit gestiona las imágenes. Aunque en muchos casos las imágenes se suben mediante la interfaz gráfica y no directamente con sintaxis Markdown, el motor que procesa el contenido de texto sigue siendo Snoomark, de modo que el formateo que rodea a esas imágenes sí se basa en Markdown.

Reddit, por otro lado, añade elementos adicionales que no forman parte de la especificación estándar, como los spoilers. Estos permiten ocultar texto tras una capa que el usuario puede revelar con un clic. Técnicamente, cuando Reddit procesa un spoiler, lo transforma a una combinación de HTML, clases CSS y JavaScript propios de la plataforma.

La representación HTML resultante de un spoiler incluye manejadores que controlan cuándo mostrar u ocultar el contenido, y aunque a nivel teórico se podría escribir algo similar con HTML simple, en Reddit depende de su implementación interna. Lo importante para ti como usuario es que, al escribir, solo necesitas usar la sintaxis específica de spoiler que ofrezca el editor, y Snoomark se encarga de traducirlo a la estructura adecuada.

En definitiva, Snoomark hereda muchos comportamientos de GitHub Flavored Markdown, pero orientados a las necesidades de una comunidad de discusión más que a la documentación de proyectos. Aun así, el núcleo es el mismo: texto plano con símbolos sencillos que se convierten en un contenido estructurado y legible.

Dominar la sintaxis de Markdown en GitHub y Reddit hace que escribir documentación técnica, abrir issues bien explicadas, dejar comentarios claros en pull requests y participar en debates de Reddit sea muchísimo más ágil. Con unas pocas reglas clave —encabezados, énfasis, listas, citas, bloques de código, enlaces, imágenes y trucos específicos como tablas, detalles plegables, alertas, notas al pie o spoilers— pasas de dejar mensajes planos a crear contenidos limpios, escaneables y profesionales sin tocar un solo botón del ratón.