Cómo escribir Markdown

Aunque no es algo propio de HTML, es una buena idea conocer Markdown ya que está muy relacionado. Markdown es un formato ligero que permite escribir contenido de forma rápida, dándole formato (enlaces, imágenes, destacados, cursiva...) y generando un formato final en HTML.

Los documentos se crean con extensión .md y se deben utilizar ciertos códigos para dar formato, que explicaremos a lo largo de este artículo. Markdown se utiliza mucho en desarrollo web e incluso para creación de documentos.

Títulos

Para crear un título, simplemente escribimos una # seguido del texto que queremos mostrar. Es importante que no escribamos titulares por el tamaño del texto, sino por la importancia que reflejan (posteriormente, el tamaño puede cambiarse con CSS):

• ✨ 6 niveles de títulos (#, ##, ###, ####, ##### y ######)
• ✅ Dejar un espacio entre la almohadilla y el texto
• 👀 Posibilidad de sintaxis alternativa con = o - (sólo nivel 1 y 2)

# Titular

Esto es un fragmento de texto.

## Subtitular

Esto es un fragmento más pequeño.

Titular
=======

Subtitular
----------

<h1>Titular</h1>
<p>Esto es un fragmento de texto.</p>

<h2>Subtitular</h2>
<p>Esto es un fragmento más pequeño.</p>

<h1>Titular</h1>

<h2>Subtitular</h2>

Observa en las pestañas el código HTML que genera el Markdown y como queda finalmente en la demo.

Si quieres más información sobre titulares, tienes más en el artículo títulos HTML.

Formatos

Todos los textos escritos en markdown se traducen a párrafos de texto, es decir a elementos <p> de HTML. Además, los textos escritos pueden estar rodeados de ciertos carácteres para darles formato:

• ✨ Mediante ** o __ puedes aplicar texto en negrita.
• ✨ Mediante * o _ puedes aplicar texto en cursiva.
• ✨ Mediante *** puedes aplicar las dos anteriores (negrita y cursiva).
• ✨ Mediante ~~ puedes tachar textos.

Esto es un ejemplo de **texto en negrita** y de
_texto en cursiva_. Opcionalmente, se puede escribir
***texto en negrita y en cursiva***. También puedes ~~tachar texto~~.

<p>
  Esto es un ejemplo de <strong>texto en negrita</strong> y de
  <em>texto en cursiva</em>. Opcionalmente, se puede escribir
  <em><strong>texto en negrita y en cursiva</strong></em>.
  También puedes <s>tachar texto</s>.
</p>

No todas las versiones de markdown lo soportan, pero en algunas ocasiones está soportado utilizar la siguiente sintaxis:

• ✨ Mediante == puedes destacar fragmentos de texto.
• ✨ Mediante ~ puedes crear subíndices.
• ✨ Mediante ^ puedes crear superíndices.

Frase destacada: ==Texto destacado==
Subscript: H~2~O
Superscript: x^2^

<p>Frase destacada: <mark>Texto destacado</mark></p>
<p>Subscript: H<sub>2</sub>O</p>
<p>Superscript: x<sup>2</sup></p>

Listas sin orden

Si necesitamos escribir una lista sin orden, podemos utilizar los guiones - o asteriscos * al principio de una linea. Además, también podemos usar TAB para crear un subelemento anidado de la lista:

- Primer elemento de una lista
- Segundo elemento de una lista
  - Subelemento uno
  - Subelemento dos

* Primer elemento de una lista
* Segundo elemento de una lista
  * Subelemento uno
  * Subelemento dos

Si quieres escribir un asterisco, utiliza un slash \ antes: \*

<ul>
  <li>Primer elemento de una lista</li>
  <li>Segundo elemento de una lista
    <ul>
      <li>Subelemento uno</li>
      <li>Subelemento dos</li>
    </ul>
  </li>
</ul>

<ul>
  <li>Primer elemento de una lista</li>
  <li>Segundo elemento de una lista
    <ul>
      <li>Subelemento uno</li>
      <li>Subelemento dos</li>
    </ul>
  </li>
</ul>

<p>Si quieres escribir un asterisco, utiliza un slash \ antes: *</p>

Por otro lado, como al escribir un * se detectará como un item de una lista, si quieres escribir un asterisco literalmente, tendrás que «escapar el texto», es decir, escribir un slash \ antes, de esta forma: \*.

Listas ordenadas

Si lo que deseas es escribir listas numeradas, simplemente, en lugar de escribir un * o un -, escribiremos un número seguido de un punto:

1. Primer elemento de una lista
2. Segundo elemento de una lista
3. Tercer elemento de una lista

<ol>
  <li>Primer elemento de una lista</li>
  <li>Segundo elemento de una lista</li>
  <li>Tercer elemento de una lista</li>
</ol>

Tareas

Aunque no está ampliamente soportado, en algunas versiones de Markdown es posible que soporten la creación de tareas con un <input> de tipo checkbox:

• ✨ Casillas desmarcadas con [ ]
• ✨ Casillas marcadas con [x]

- [x] Primera tarea
- [ ] Segunda tarea
- [ ] Tercera tarea

<ul>
  <li><input type="checkbox" disabled checked> Primera tarea</li>
  <li><input type="checkbox" disabled> Segunda tarea</li>
  <li><input type="checkbox" disabled> Tercera tarea</li>
</ul>

Recuerda que el formato visual es personalizable mediante CSS. Por ejemplo, con una linea de CSS podrías quitar los guiones o puntos de las listas.

Enlaces

En Markdown se pueden crear enlaces. Para ello, simplemente añadimos el texto a enlazar entre corchetes [], seguido de la URL a enlazar entre paréntesis (). De forma opcional puedes establecer un texto tras el enlace, en el interior de los paréntesis. Esto sería el texto de título que aparece al mover el ratón encima.

Veamos algunos ejemplos:

- La web de [ManzDev](https://manz.dev/)
- La web de [ManzDev](https://manz.dev/ "ManzDev: Streamer de código en Twitch")
- La web de <https://manz.dev/> (link automático)

<ul>
  <li>La web de <a href="https://manz.dev/">ManzDev</a></li>
  <li>La web de <a href="https://manz.dev/" title="ManzDev: Streamer de código en Twitch">ManzDev</a></li>
  <li>La web de <a href="https://manz.dev/">https://manz.dev/</a> (link automático)</li>
</ul>

Observa que la última forma es una forma de crear enlaces automáticos, con el mismo texto del enlace. Simplemente, se envuelve el enlace entre signos angulares <>.

Enlaces en notas al pie

Otra opción para añadir enlaces es utilizar las notas a pie de página. Se puede añadir un fragmento de texto entre corchetes [] seguido de un número entre corchetes []. Al final del documento o sección, añadimos el número entre corchetes con dos puntos []: e indicamos el enlace en cuestión:

Aquí tienes información sobre el concepto [Dunning-Krugger][1]. Por otro lado,
también tienes información sobre [el principio de Peter][2].

[1]: https://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect
[2]: https://en.wikipedia.org/wiki/Peter_Principle "El principio de Peter"

<p>
  Aquí tienes información sobre el concepto
  <a href="https://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect">Dunning-Krugger</a>.
  Por otro lado, también tienes información sobre
  <a href="https://en.wikipedia.org/wiki/Peter_Principle">el principio de Peter</a>.
</p>

Esto puede ser especialmente interesante si quieres tener mayor claridad en el texto, o si se repiten muchas veces los enlaces a colocar, de forma que puedes reutilizarlo con el mismo número.

Imágenes

Si sabemos añadir enlaces, también podemos añadir imágenes. Las imágenes se indican de forma muy similar a los enlaces, con la única diferencia que antes se incluye un !. De esta forma, si tenemos un enlace a una URL con una imagen, simplemente añadiendo ! antes, la convertiremos en una imagen:

![Imagen del artículo sobre Markdown](https://lenguajehtml.com/html/social.jpg)

<img src="https://lenguajehtml.com/html/social.jpg"
     alt="Imagen del artículo sobre Markdown">

Ten en cuenta que puedes incluir una imagen dentro del [] del enlace que vimos antes, creando así una imagen con enlace a una web o recurso.

Citas

Las citas se suele añadir en un documento para hacer referencia a algo, o a algún comentario que se ha dicho. En este ejemplo, he añadido un poco de CSS para que se entienda mejor la cita. Al convertirla a HTML, se utiliza una etiqueta llamada <blockquote>:

Esto es un párrafo de texto y a continuación tienes una cita:

> Este es un ejemplo de cita.

<p>Esto es un párrafo de texto y a continuación tienes una cita:</p>

<blockquote>
  <p>Este es un ejemplo de cita.</p>
</blockquote>

blockquote {
  background: #cfcff5;
  margin: 0;
  padding: 0.25rem;
  padding-left: 2rem;
  border-left: 1rem solid #ababdd;
}

Además, también podemos utilizar una cita dentro de otra, y crear citas o menciones anidadas:

Esto es una cita anidada:

> Esto es una cita simple.
>> Esto es una cita anidada.

<p>Esto es una cita anidada:</p>

<blockquote>
  <p>Esto es una cita simple.</p>
  <blockquote>
    <p>Esto es una cita anidada.</p>
  </blockquote>
</blockquote>

blockquote {
  background: #cfcff5;
  margin: 0;
  padding: 0.25rem;
  padding-left: 2rem;
  border-left: 1rem solid #0004;

  & blockquote {
    background: #c2a5d5;
  }
}

Nuevamente, he utilizado un fragmento de código CSS para darle estilo y que se entienda mejor.

Código

Por otro lado, en ciertas ocasiones nos puede interesar añadir fragmentos de código, de un lenguaje de programación o similares, donde tienen una sintaxis específica. Existen varias formas de hacerlo.

En primer lugar, podemos utilizar código en línea, es decir, dentro de un párrafo de texto. En esta ocasión necesitamos que permanezca dentro del párrafo de texto y se continue con el flujo del texto. Para ello utilizaremos un sólo backtick ` alrededor de dicho código:

Podemos utilizar los backticks para indicar código en línea: `console.log("Hola!")`. Además,
también podemos crear bloques de código:

```js
function log() {
  console.log("Hola!");
}
```

<p>
  Podemos utilizar los backticks para indicar código
  en línea: <code>console.log(&quot;Hola!&quot;)</code>. Además,
  también podemos crear bloques de código:
</p>

<pre><code class="js">function log() {
  console.log(&quot;Hola!&quot;);
}
</code></pre>

Observa que el fragmento de código se establece en un tipo de letra diferente al texto normal. Esto es porque se incluye dentro de una etiqueta <code>.

Además, también se puede crear un bloque de código, que en esa ocasión, queremos que se coloque a parte del texto donde escribimos, respetando los espacios en blanco y las líneas nuevas. Para ello, utilizaremos triple backtick ``` para rodear el bloque de código, y se generará una etiqueta <pre> que dentro tendrá una etiqueta <code>.

Observa que en algunos casos, se suele añadir el lenguaje (js, html, css, etc...) para que se añada como una clase a la etiqueta <code>. Esto permite que algunas librerías puedan resaltar con colores la sintaxis de código.

Otra forma de crear bloques de código es utilizar una indentación de 4 espacios antes de escribir el bloque de código. Esto también generará una etiqueta <pre><code>, de la misma forma anterior. En este caso, observa que también he añadido un poco de CSS para darle algo de estilo visual:

Otro bloque de texto:

    function log() {
      console.log("Hola!");
    }

<p>Otro bloque de texto:</p>

<pre><code>function log() {
  console.log(&quot;Hola!&quot;);
}</code></pre>

pre {
  background: #111;
  padding: 1rem;
  color: #ccc;
}

En algunas versiones extendidas de markdown, es posible escribir ~~~ en lugar de los backticks para crear bloques de código. También permitiendo añadir el lenguaje como ocurre en los backticks.

Línea

Si queremos añadir una línea horizontal a modo de separación temática, simplemente debemos escribir tres guiones seguidos: ---:

---

<hr>

HTML

No olvidemos que Markdown al final es un lenguaje que se procesa y se convierte a HTML. Por lo tanto, si escribimos HTML dentro de un fichero Markdown, se mostrará tal cual. Esto nos permite aprovechar las capacidades de HTML para añadir características de HTML aunque no existan en Markdown. Por ejemplo, un acordeón <details>:

Esto es un párrafo de texto.

<details>
  <summary>Más información haciendo clic aquí</summary>
  <div>Información adicional.</div>
</details>

<p>Esto es un párrafo de texto.</p>

<details>
  <summary>Más información haciendo clic aquí</summary>
  <div>Información adicional.</div>
</details>

Algunos sistemas como GitHub, eliminan ciertas etiquetas HTML de Markdown (por seguridad, rendimiento u otros temas), permitiendo sólo elementos HTML que sean seguros.

Tablas

Originalmente, las tablas no formaban parte de la especificación de Markdown, por lo que no se podían añadir. Sin embargo, en una versión extendida de Markdown se añadió soporte, y hoy en día, generalmente, se suele incluir y están soportadas.

Para crearlas, es tan fácil como crear la tabla de forma visual, utilizando pipes | o guiones -. La tabla siempre debe tener una cabecera, separada por guiones que tengan el mismo número de columnas:

| Cabecera  | Cabecera  |
|-----------|-----------|
| Celda 1   | Celda 2   |
| Celda 3   | Celda 4   |

<table>
  <thead>
    <tr>
      <th>Cabecera</th>
      <th>Cabecera</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Celda 1</td>
      <td>Celda 2</td>
    </tr>
    <tr>
      <td>Celda 3</td>
      <td>Celda 4</td>
    </tr>
  </tbody>
</table>

En algunas versiones avanzadas de Markdown, incluso podemos utilizar : para establecer la alineación de las tablas. Por ejemplo, si indicamos un : al final de la línea horizontal, el texto de esa columna estará alineado a la derecha. Si añadimos un : al principio, estará alineado a la izquierda, y si lo añadimos en ambos, estará centrado:

| Cabecera  | Cabecera  |
|----------:|:---------:|
| Celda 1   | Celda 2   |
| Celda 3   | Celda 4   |

<table>
  <thead>
    <tr>
      <th style="text-align:right">Cabecera</th>
      <th style="text-align:center">Cabecera</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align:right">Celda 1</td>
      <td style="text-align:center">Celda 2</td>
    </tr>
    <tr>
      <td style="text-align:right">Celda 3</td>
      <td style="text-align:center">Celda 4</td>
    </tr>
  </tbody>
</table>

Las tablas no deben tener necesariamente el tamaño visual deseado en el Markdown. Por ejemplo, podemos sustituir la linea de separación horizontal |-|-| y seguirá funcionando correctamente, siempre y cuando contengan el mismo número de columnas.

Emojis

En algunas versiones de Markdown es posible añadir emojis utilizando su alias entre el símbolo de dos puntos :. Por ejemplo, :joy: se cambiaría por 😂, y :smile: se cambiaría por 😄.

Hello! :joy:

<p>Hello! 😂</p>

Frontmatter

En ciertos ecosistemas, existe un formato de fichero denominado front-matter. Este formato fue promovido por Jekyll y se basa en una cabecera en formato YAML encerrado en bloques "fenced" mediante ---. El resto del documento es markdown:

---
title: "Título del documento"
description: "Esta es una descripción del contenido."
date: 2024-10-20
---

## Título del subcontenido

Más contenido **markdown** en el resto del fichero.

Este formato es muy utilizado hoy en día en generadores de contenido estáticos como Astro, Eleventy, Hugo o similares para generar sitios web de forma eficiente y rápida.

Editores o programas

Por último, existen múltiples editores markdown que se pueden utilizar para escribir documentos en formato md. En esta tabla añado algunos de ellos, aunque puedes encontrar muchos otros: