La sintaxis básica de Markdown bien explicada al fin
@ Samquejo · Friday, Jul 24, 2020 · 14 minutos de lectura · Actualizado en Aug 18, 2020

Como este artículo lo he fusilado y adaptado de la web original, mejor será que lo aclare aquí.

Este artículo es una adaptación del original que podéis encontrar en The Markdown Guide.

Thanks for visiting The Markdown Guide!

This Markdown cheat sheet provides a quick overview of all the Markdown syntax elements. It can’t cover every edge case, so if you need more information about any of these elements, refer to the reference guides for basic syntax and extended syntax.

La verdad es que voy a explicarlo, traducirlo y adaptarlo a mis necesidades, a ver si coinciden con las vuestras. Ah, y seguro que lo ampliaré.

Trampeando Markdown para hacerlo útil y entendible por todos.

Tenemos que distinguir lo que voy a hacer, puesto que esto es un documento en markdown y no voy a poder adaptarlo al 100%

Sintaxis Básica

La sintaxis básica es la que definió John Gruber en el documento original de Markdown, y todos los dialectos lo tienen en común.

Lo que pasa es que siempre he visto lo mismo y no me gusta la estructura, y siempre que se aplique algún CSS, esa estructura va a cambiar por lo que me voy a quedar con lo que uso y lo voy a orientar al uso que le voy a dar con HUGO, por lo que el orden no está dividido entre sintaxis básica y extendida, si no por el uso que se le puede dar en un entorno creado con HUGO.

Qué quiero Cómo se hace Qué obtengo
Negritas 2 asteriscos o guiones bajos rodeando al texto texto en negritas también
Cursiva 1 asterisco o guion bajo rodeando al texto texto en cursiva también
Subrayado Ni está ni se le espera. Hay un debate entre redacción y maquetado. nada
Tachado 2 pispajillos o tilde o acento rodeando al texto texto tachado
Superíndice A pesar de mis intentos, el CSS no lo traduce así que… nada

Con respecto a las funcionalidades del subrayado, o del color, lo que tenemos en markdown son excepciones en el procesador de HTML. Esas excepciones lo que harán será ignorar cualquier etiqueta HTML que no sea capaz de integrar por lo que si preparamos algo como esto:

Esto es un texto donde voy a <span style="color:blue">escribir algo en *azul* </span>.
Lo que obtendremos en el HTML destino será

 
<p>Esto es un texto donde voy a <!-- raw HTML omitted -->escribir algo en <em>azul</em><!-- raw HTML omitted -->.</p> 

Obviamente si quiero escribir un * o cualquier otro símbolo de los indicados que son modificadores, pues tendré que poder.

Para esto se usa el modificador \ y se aplica en todos estos casos:

Lista de caracteres
Asterisco: * Guion: - Guion bajo: _
Paréntesis: () Corchetes: [] Llaves: {}
Punto: . Signo de exclamación: ! Almohadilla: #
Acento grave: ` Barra invertida: \ Signo de suma +

Existen una serie de caracteres un poco más complejos de usar, como son et o ampersand (&), y los símbolos de mayor y menor (<>), puesto que, si se quiere usar Markdown como base para la generación de HTML, como es este caso y con HUGO, el analizador puede confundirse.

Para ello, estos caracteres deben enmascararse también.

Tablas

Las tablas, como bien habéis podido comprobar, son tan simples de hacer como meter las cabeceras y unas líneas entre símbolos de tubería o pipe |.

Lo primero sería declarar la cabecera, es decir, la primera fila de la tabla.
En mi caso es obligatoria, con otros intérpretes puede no serlo.

Suponiendo que tengamos una tabla en la que pongamos los hipervisores y si son de tipo 1 o de tipo 2, quedaría una cabecera como esta:

Nombre de hipervisor Tipo 1 Tipo 2 Tipo emulador Tipo runtime

Para ello, necesitaremos el siguiente código:

En la primera línea, los 5 campos de la cabecera.

| Nombre de hipervisor | Tipo 1 | Tipo 2 | Tipo emulador | Tipo runtime | 

Y una segunda línea con este otro código, 5 separadores, uno por campo 1.

| --- | --- | --- | --- | --- | 

Ahora empezaríamos a añadir registros 1:

El primero para Vmware ESXi
Otro para VirtualBox …
Otro para virtualPC, hyper-v, kvm… Unos cuantos, vamos, como si fueran poco.

Nombre de hipervisor Tipo 1 Tipo 2 Tipo emulador Tipo runtime
Vmware ESXi X
Microsoft Hyper-V X X (Conectix VirtualPC)
Bosch X
JVM X

El código completo de la tabla es el siguiente:

| Nombre de hipervisor | Tipo 1 | Tipo 2 | Tipo emulador | Tipo runtime | 
| --- | --- | --- | --- | --- | 
| Vmware ESXi | X | | | | 
| Microsoft Hyper-V | X | X (Conectix VirtualPC) | | | 
| Bosch | | | X | | 
| JVM | | | | X | 

Y no, no hay opción a fijar ancho de columnas, o rehacer el entramado, porque el cálculo es dinámico.
Además, la tabla se genera en la conversión de MD a HTML por lo que, en todo caso, su aspecto vendrá definido por un CSS.

Por lo demás, tengo que investigar el uso y la influencia de los &nbsp; y resto de caracteres no imprimibles que juegan un papel importante en maquetación pero que no son habituales puesto que podrían suponer algún tipo de ayuda a la maquetación horizontal.

Sin olvidarme claro está, que los formatos básicos de Markdown están disponibles en las tablas.

Párrafos.

Esto es muy sencillo de contar, pero es complejo de ver.

Para que podamos emular las etiquetas <br> o <p> tenemos la opción de no acabar la línea justo en el carácter final, si no que podemos meter dos espacios y con ello indicar al intérprete que debe meter uno de estos dos códigos. En mi caso es <p>

Este texto sirva de ejemplo para lo que he comentado.

Esto es una nueva línea justo debajo. Se ha incluido un retorno de carro.
Esto es una línea en la que se ha incluido un segundo retorno de carro a la anterior.
Y esta es una línea en la que se ha incluido el doble espacio antes del retorno de carro.

Por lo tanto, tanto los dobles espacios como el doble retorno de carro delimitan la creación de un nuevo párrafo

Encabezados y títulos

Esta parte a la que siempre se le ha dado muchísima importancia, para mi tiene un interés incluso negativo. Solo lo uso para indicar un corte grande, como por ejemplo lo que separa cada sección, para lo cual uso un H2 por norma general.

En principio, de H1 a H6 van a tener equivalencia directa 1 a 1 con sus correspondientes iguales en HTML.

Así es la cabecera principal o de título

Y su código será por tanto # Título de nivel 1 o bien # Título de nivel 1 #

Así es la cabecera de sección

Y su código será ## Sección nivel 2 o bien ## Sección nivel 2 ##

Esto es un título de capítulo

### Capítulo nivel 3 o bien ### Capítulo nivel 3 ###

Esto podría ser un párrafo

#### Párrafo nivel 4 o bien #### Párrafo nivel 4 ####

Pero de aquí en adelante sigue siendo más que el texto plano, a pesar de que no se ni como llamarlo.

Esto ya no se ni como llamarlo además de sin nombre de nivel 5

##### Nivel 5 o bien ##### Nivel 5 #####

Y el último, el de nivel 6

###### Nivel 6 o bien ###### Nivel 6 ######

Como podéis ver, el segundo juego de almohadillas es opcional.

Citas, pies de página y listas de definición.

Como esto es principalmente una herramienta de documentación, las citas, las definiciones y los pies de página son mandatorios. Esto es lo que podríamos definir como las herramientas del documentalista.

En la conversión a HTML es mucho más estético pero en otros intérpretes como pandoc se ve su potencia más allá de cualquier duda.

Un bloque de cita es sencillo, tan simple como añadir un símbolo mayor > y un espacio antes de la cita.

Bloque de cita en línea con codificación markdown en línea para no equivocarnos y que ocupa más de una línea completa en código origen y el intérprete divide para ajustar al HTML.

En caso de tener varias líneas, se aplica lo mismo. Un juego de símbolo mayor > y un espacio antes de cada línea de la cita, sin añadir marcados de párrafo adicionales. Es decir, que cada línea llena o vacía llevará un juego de símbolo mayor > y un espacio al principio.

En caso de tener que dividir en varios la cita, se procedería así:

Acabo de poner una línea vacía.
Y ahora una línea pegada con un doble espacio.

Las citas se pueden anidar, por lo que a lo de un juego de símbolo mayor > y un espacio se le añade otro juego de símbolo mayor > y un espacio antes de la cita anidada.

Cuenta la leyenda que en 1981 Bill Gates dijo que

“640K deberían ser suficientes para cualquiera”

Cosa que más tarde, él mismo negó haber dicho.

Ni he comprobado cuanto se puede anidar, ni veo su utilidad más allá de este segundo o tercer nivel.
Lo que si he comprobado es que para entrar podemos hacerlo con una nueva línea, pero para salir y volver al nivel de identación anterior, hay que meter una línea en blanco en una línea marcada de cita.

También podemos hacer citas con atribución, lo que es retorcer la sintaxis de MD un poco más allá de lo que es habitual, y es una cosa sumamente útil como puede verse aquí:

“640K deberían ser suficientes para cualquiera”

No se puede atribuir a Bill Gates 2

Pero no solo de citas se puede vivir y cada cita, al menos, o también otros elementos, necesitan llamadas y aclaración. Para ello están las notas a pie.

La sintaxis es un número o letra o combinación (espero que nadie necesite más de 65000 notas a pie, el documento sería infumable) entre corchetes con un acento circunflejo delante 3 como por ejemplo esto [^1]

Para expandir el texto de la nota, debemos añadir el mismo indicador seguido de : y la línea correspondiente.

Concretamente así: [^1]: Texto de la nota

Dos apreciaciones sobre las notas.

  • La primera es que el texto y la nota deben concordar en lo que se ponga. Como se puede apreciar, por ejemplo, en la nota que he dejado en la sección de las tablas aclarando que es campo y que es registro.
  • La segunda y quizás más importante, es que sea cual sea el mecanismo que usemos para numerar, el intérprete renumerará desde 1 cualquier número y aparición de notas en el documento.

Y, por último, las listas de definición, que son más simples que las notas a pie tienen también un formato más simple.

Término.
Definición.

La verdad es que no tiene más que eso. Una línea justo a continuación que empieza por : y espacio y una definición en una línea. Algo tan simple como esto:

Término.  
: Definición. 

Listas

Para simplificar, listas numeradas y listas en bruto

  1. Primer elemento
  2. Segundo elemento
  3. Tercer elemento
  • Un elemento
  • Otro elemento
  • Último elemento

Las listas pueden empezar por número y un punto, e imagino que no habrá restricciones en cuanto a que cantidad de números se pueden poner.
Pero al igual que con las notas, aquí da exactamente igual lo que poner. En cada grupo de listas, el intérprete renumerará conforme a las reglas lógicas y no al capricho del autor, y lo único que vamos a poder elegir es el número por el que empieza la lista numerada.

Las listas no ordenadas, en bruto, pueden llevar como indicador un guion, -, un asterisco, * o un signo de suma, +. Porque da igual, en cada grupo, el intérprete lo limpiará. La diferencia queda en que se crearán tags <ul> separados si se usan diferentes indicadores, aun estando juntos en el documento.

Las listas de tareas, bueno, son una modificación aceptable que se basa en la lista en crudo con un espacio entre corchetes tal que así [ ] o bien rellenos con el símbolo que prefiráis tal que así [x].

  • Write the press release
  • Update the website
  • Contact the media

Y claro, si las citas se pueden anidar, una lista con mucha más razón.

Se pueden combinar en principio casi cualquier cantidad de listas numeradas o en bruto, pero la lógica vuelve a mandar, y sinceramente, si hace falta más de 3 o 4 niveles, hace falta otra herramienta. Los niveles de anidación se obtienen a partir de introducir 4 espaciso delante del signo de declaración de lista, numerada o no.

  1. Primer elemento
    • Un elemento anidado
      • Con elementos en lista no numerada
    • y con otro nivel de anidación no numerado
      • Otro elemento anidado
  2. Con elementos en lista numerada
    1. y con otro nivel de anidación numerado
      • Último elemento anidado
    2. Otro elemento

Como se puede observar, la verdad es que no hay demasiada variedad en la generación de elementos indicadores por cada elemento anidado, y no sé si es una limitación de HUGO, de HTML, de CSS o de Markdown, de ahí mi recomendación de no abusar de este recurso.

Enlaces, imágenes y otros recursos propios de la web.

Un enlace, concretamente un hiperenlace, se puede definir con sus dos componentes, uno entre corchetes con el texto a mostrar y a continuación el enlace completo (relativo o absoluto) entre paréntesis.

Página de YoVirtualizador

También podemos mostrar la url completa, bien por el método del enlace, o bien por el método directo, que es incluir directamente la url entre signos de < y >

https://www.YoVirtualizador.com

Para terminar con los enlaces, voy a retorcer la sintaxis al punto de realizar los enlaces automáticamente sobre palabras clave en todo el documento.

Esto es relativamente sencillo y tan solo hay que preparar en algún punto del documento un grupo de definiciones con palabras y enlaces, muy similar a las definiciones documentales, un enlace por referencia o contexto.

Personalmente no es un recurso que me agrade, al menos no es el de los popups, y lo uso sin problemas.

Aunque no se note, el código que genera esto es reutilizable a lo largo del documento y quedaría así:

[Personalmente] no es un recurso que me agrade, al menos no es el de los popups, y lo uso sin problemas.  
[Personalmente]: https://www.YoVirtualizador.com 

*Por último, las imágenes.

La verdad es que no es una grandiosa herramienta de publicación de material con imágenes insertadas. No tiene grandes opciones para trabajar con ellas.

Texto alternativo

Tan solo hay una sintaxis. Signo de exclamación cerrada ! seguido del texto en corchetes y la ruta entre paréntesis. La ruta puede ser absoluta o relativa, y podemos usar las etiquetas de sustitución para limpiar, de la misma forma que con los enlaces.

![Texto alternativo](/img/cover0.jpg)

Otros recursos menos habituales

  • Identificador de cabecera.

A veces es necesario, en un documento largo, como este, definir llamadas a una etiqueta en el texto. Es algo así como programar un goto en el navegador.
Puede servir perfectamente para, por ejemplo, trocear este documento.
Podemos así crear enlaces desde otras partes del documento, a modo de índice, o desde otros documentos. Su uso está indicado en cabeceras, o como parte de otros textos, enlaces o componentes, pero no como elemento suelto.

Su configuración es una almohadilla con la etiqueta entre llaves, así.

{#Identificador-de-cabecera}

Y la llamada tendría un código tan simple como esto:

[Página de YoVirtualizador](https://www.YoVirtualizador.com/esta-pagina/#Identificador-de-cabecera)

  • Una barra para separar.

Es totalmente viable de dos maneras.
La primera es usar 3 signos de suma, +, tres asteriscos, * o tres guiones, -, al principio de la línea, separada por líneas vacías. Dará una línea un poco más gruesa.


O bien, tal como forma parte de los títulos 1 y 2 tal como describo en la sección de cabeceras, algo así como esto, siendo una línea fina.

Secciones de código

  • Sección simple de código

code

Tan simple como eso, poner algo entre signos de acento grave `.
Solo tengo una pega, que ya resolveré. No se ven bien los contenidos de bloques de código cuando está activo el modo oscuro en el blog. Todo se andará.

  • Código vallado, o cercado, o como sea la traducción de fenced

La sección de código es para código en una sola línea. Para cosas más complejas, podemos englobar el código entre 2 grupos de 3 signos de acento grave `.

Un bloque de ejemplo en YAML quedaría así:

{ 
    "Nombre": "Manolo", 
    "Apellidos": "ElDelBombo", 
    "Edad": 55 
} 
  • Bloques de código con backticks lo que se traduce como garrapata

No se quien es el iluminado que ha puesto este nombre, pero así queda.

html 
<!DOCTYPE html> 
<html lang="es"> 
<head> 
<meta charset="UTF-8"> 
    <title>Ejemplo en HTML</title> 
</head> 
<body> 
    <p>Prueba</p> 
</body> 
</html> 
  • Bloque de código con el marcado de sintaxis propio

El uso del marcado extendido propio de HUGO ayuda cuando el marcado se realiza para alguno de los elementos de las sintaxis soportadas

 
<!DOCTYPE html> 
<html lang="es"> 
<head> 
<meta charset="UTF-8"> 
    <title>Ejemplo en HTML</title> 
</head> 
<body> 
    <p>Prueba</p> 
</body> 
</html> 

Resumen de Markdown

Es simple, todo esto será la chuleta para todo lo que voy a hacer con MD y HUGO, y posiblemente la chuleta para que alguien haga su TFG.
Y según necesite, como ahora mismo, actualizaré y modificaré este documento, con ampliaciones o correciones.


  1. Esto es un pequeño punto en este momento, tan solo para aclarar que campos son columnas y registros, filas. Es una simple convención, y como tal, queda en un pie de página que explicaré en su sección. También habrá una explicación de que significan los 3 guines juntos. ↩︎

  2. Y para liarlo más, por ejemplo, podemos meter una muy interesante nota a pie con la referencia a la cita. ¿suficientemente liado? ↩︎

  3. Funciona, demostrado. ↩︎

YoVirtualizador blog
Tu podcast y blog de confianza
actualizacion arm bananapi bcu blog bricolaje bulkcrap-uninstaller certificados clientes esxi fedora fedora-kde foss fusion gestion hipervisor hugo hyper-v instalaciones ios kde linux maquina-virtual markdown micro-pc migracion mobaxterm open-source openssh player powercli powershell punto-de-montaje reciclado seguridad share sintaxis sistema-operativo ssl sysadmin telegram virtualbox vmware vmware-player website whitebox windows-10 windows-ssh witebox workstation x11forwarding xdmcp yovirtualizador

© 2019 - 2020 YoVirtualizador

Powered by Hugo with theme Dream.

Acerca de YoVirtualizador

YoVirtualizador es la marca de varios proyectos

Podcast de informática profesional. Canal de Youtube sobre el blog, el podcast y de temática profesional. Blog de contenido diverso, con temática BOFH y técnica.

Gracias por la lectura.

Política de comentarios

En YoVirtualizador todos los comentarios serán bienvenidos pero moderados.

Respetos guardan respetos.

El contenido irrelevante u ofensivo será eliminado.

Galletas

Política de cookies

En YoVirtualizador no usamos cookies para nada, pero los servios de discus y analytics recopilan datos en servidores ajenos a yovirtualizador sin que yo pueda hacer nada.

Este aviso es sólo porque algún político tenía que justificar su existencia.