Párrafos¶
En un documento markdown simple, el texto se divide en varios párrafos. Veamos como estructurarlos.
Delimitar párrafos¶
En principio, todo documento es una simple secuencia de caracteres:
Este es un texto de varias líneas.
Cada una de ellas finaliza con
un salto de línea.
Al visualizar la página web generada
en el navegador,
todas las líneas se concatenarán
para formar una única línea de texto.
Cuando el navegador descarga la página web y la presenta, las líneas de texto consecutivas se concatenarán en una única línea, que se ajustará dependiendo del ancho de la ventana. Los espacios entre palabras se reducen a un espacio.
En el navegador, el archivo HTML descargado se visualizará de la siguiente forma:
Para separar párrafos, en el archivo markdown tenemos que insertar una línea en blanco:
Este es el primer párrafo. Es lo suficientemente
largo como para ocupar varias líneas, que serán visualizadas
como un bloque de texto, sin separación entre líneas.
Este es el segundo párrafo. Dejamos una línea
en blanco para separarlo del primero.
Lo que mostrará los párrafos por separado, añadiendo un espaciado entre ellos:
Este es el primer párrafo. Es lo suficientemente largo como para ocupar varias líneas, que serán visualizadas como un bloque de texto, sin separación entre líneas.
Este es el segundo párrafo. Dejamos una línea en blanco para separarlo del primero.
La conversión a HTML añade una etiqueta <p> al inicio de cada párrafo y otra </p> al final:
<p>Este es el primer párrafo. Es lo suficientemente
largo como para ocupar varias líneas, que serán visualizadas
como un bloque de texto, sin separación entre líneas.</p>
<p>Este es el segundo párrafo. Dejamos una línea
en blanco para separarlo del primero.</p>>
El navegador ignora los saltos de línea y las líneas en blanco.
En los archivos markdown se considera línea en blanco aquella que no contiene caracteres o solo tiene espacios en blanco. Si escribimos varias líneas en blanco entre dos párrafos, el exceso será ignorado y contarán como una sola.
Puede ser una buena idea escribir los textos de forma que en cada línea pongamos una frase, limitando el tamaño de las líneas y mejorando la legibilidad, en la seguridad de que en la conversión se unirán los textos para formar el párrafo completo.
Saltos de línea¶
Ya hemos visto que podemos forzar un salto de línea insertando manualmente una etiqueta html <br> en mitad del texto. MkDocs respeta las etiquetas html y las deja como parte del texto generado.
Por ejemplo:
Este es el primer párrafo. <br> Es lo suficientemente
largo como para ocupar varias líneas, que serán visualizadas
como un bloque de texto, sin separación entre líneas.
Este es el segundo párrafo. Dejamos una línea
en blanco para separarlo del primero.
Esto mostrará:
Este es el primer párrafo.
Es lo suficientemente
largo como para ocupar varias líneas, que serán visualizadas
como un bloque de texto, sin separación entre líneas.
Este es el segundo párrafo. Dejamos una línea en blanco para separarlo del primero.
Véase que el uso de la etiqueta <br> no inserta espaciado entre una línea y la siguiente.
Nota
El formato markdown original proporciona un mecanismo para respetar los saltos. Consiste en añadir al final de cada línea dos o más espacios en blanco. Pero yo no suelo hacer uso de esto, dado que al examinar un archivo, no es fácil distinguir visualmente que líneas llevan espacios adicionales.
Párrafos de cabecera¶
Nótese que, en estos cuadernos, cada página tiene un párrafo de título y párrafos de cabecera de sección, que se muestran con un tipo de letra especial. En fotmato markdown identificamos estos párrafos anteponiendo uno o más caracteres #. Por ejemplo:
# Título del documento
Texto del documento
El carácter (o caracteres) # se suprimirá del resultado final. Debemos dejar un espacio en blanco entre la marca # y el texto del título para que tenga efecto.
Podemos crear una estructura formada por un título general del documento, títulos a nivel de sección (nivel 2), a nivel de subsección (nivel 3) y así sucesivamente hasta 6 niveles. Por ejemplo:
# Título del documento
## Sección 1
### Subsección 1.1
Párrafo de texto regular
### Subsección 1.2
Otro párrafo de texto regular
El nivel se determina de acuerdo al número de caracteres #. El tipo de letra y aspecto lo determina MkDocs. Para ello, en la carpeta generada /site, junto a los archivos HTML, MkDocs añadirá una subcarpeta /stylesheets que contiene archivos con reglas de estilo CSS.
Opcionalmente podemos "cerrar" las líneas de título con más caracteres # a la derecha, que en el resultado final serán suprimidos. Es algo puramente "estético" y ni siquiera hace falta que el número de caracteres # coincida con los colocados a la izquierda:
## Título de la sección ######
En la conversión a HTML, los párrafos de cabecera se delimitan entre las siguientes etiquetas:
<h1> Cabecera de nivel 1 </h1>
<h2> Cabecera de nivel 2 </h2>
<h3> Cabecera de nivel 3 </h3>
<h4> Cabecera de nivel 4 </h4>
<h5> Cabecera de nivel 5 </h5>
<h6> Cabecera de nivel 6 </h6>
<p> Párrafo de texto regular </p>
¡Cuidado!
Si usamos estos párrafos de cabecera, debemos estructurar el documento de la forma adecuada. Téngase en cuenta que las cabeceras se utilizan con muchos propósitos. Sirven, por ejemplo, para para que MkDocs inserte de forma automática una tabla de contenidos, para crear enlaces a una sección o incluso las utilizan los buscadores de Internet. Es un error usar párrafos de cabecera solo para utilizar un tipo de letra especial. Para ese propósito hay otros mecanismos, como es el caso de los archivos .css
Un párrafo de cabecera no puede estar formado por varias líneas en el texto markdown. Lo siguiente:
# Texto de cabecera
más texto
se convertirá en:
<h1>Texto de cabecera</h1>
<p>más texto</p>
a pesar de no dejar una línea en blanco separadora.
La sintaxis de títulos basada en prefijos # es conocida como "atx", y fue inventada por Aaron Swartz, uno de los principales colaboradores en el diseño de markdown. Alternativamente existe la posibilidad de utilizar otra forma de sintaxis inspirada en el antiguo formato "Setext". Se trata de una opción que solo admite dos niveles de cabecera. Los títulos se delimitan subrayando con caracteres = las cabeceras de nivel uno, y con guiones las de nivel dos. Por ejemplo:
Título del documento
====================
Título de la sección
--------------------
Párrafo de texto regular
Sangrado de párrafos¶
Llamamos párrafo sangrado a aquel en el que todas sus líneas tienen espacios en blanco a la izquierda. Por ejemplo:
Primer párrafo estándar.
Este es un párrafo con sangría.
Tiene 4 espacios a la izquierda.
Markdown utiliza la sangría con propósitos especiales, y por lo tanto, debemos evitar todo tipo de espaciado a la izquierda excepto para esos casos particulares. El uso más habitual es crear párrafos preformateados.
Párrafos preformateados¶
Supongamos que estamos creando un manual de programación en lenguaje Java. Escribimos algo así como:
Programa de ejemplo:
class HelloWorld {
public static void main (String args[]) {
System.out.println("Hola Mundo");
}
}
Pero al visualizarlo, se unen todas las líneas de texto y el resultado es:
Queremos que el texto del programa forme un bloque donde se respeten los saltos de línea y los espacios extra. La solución es marcar todo ese texto como párrafo preformateado. En la sintaxis markdown, se logra añadiendo un sangrado de cuatro espacios:
Programa de ejemplo:
class HelloWorld {
public static void main (String args[]) {
System.out.println("Hola Mundo");
}
}
Y ahora, MkDocs tomará todo el bloque sangrado y respetará el espaciado, mostrándolo en un estilo de letra especial. Los cuatro espacios de sangría se suprimen en la conversión a HTML. La sangría adicional se mantiene:
class HelloWorld {
public static void main (String args[]) {
System.out.println("Hola Mundo");
}
}
Nótese que un sangrado de tres espacios no tiene efecto. Ha de ser de cuatro. Los espacios extra se mostrarán como tales.
En la conversión a HTML, los bloques preformateados (incluyendo líneas en blanco) se delimitan entre etiquetas <pre>:
<p>Programa de ejemplo:</p>
<pre>
<code>
class HelloWorld {
public static void main (String args[]) {
System.out.println("Hola Mundo");
}
}
</code>
</pre>
Las etiquetas <code> se utilizan para establecer el tipo de letra.
Código
Este tipo de bloques preformateados se suelen utilizar principalmente para mostrar ejemplos en un manual de programación. A las instrucciones de un programa se las denomina "Código fuente", de ahí que se utilice el término "Code" para referirnos a un texto técnico.
En los fragmentos preformateados identificados mediante sangría, no solo se respeta el espaciado y saltos de línea. Tampoco tiene efecto el formato markdown, considerando las marcas como texto literal:
Texto regular
# Párrafo de cabecera sangrado
Muestra:
# Párrafo de cabecera sangrado
Párrafos de citas¶
Los párrafos de cita se muestran en un formato especial:
Según Wikipedia:
HTML, acrónimo en inglés de HyperText Markup Language ('lenguaje de marcado de hipertexto'), hace referencia al lenguaje de marcado utilizado en la creación de páginas web.
Como de costumbre, el tipo de letra y otros elementos de formato depende de la "hoja de estilos" utilizada, bien la generada por MkDocs, o las añadidas por nosotros.
Markdown identifica las citas anteponiendo en cada línea un carácter >
Según Wikipedia:
> HTML, acrónimo en inglés de HyperText Markup Language
> ('lenguaje de marcado de hipertexto'), hace referencia
> al lenguaje de marcado utilizado en la creación de páginas web.
En la sintaxis markdown, el prefijo > solo es necesario en la primera línea de cada párrafo:
> Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.
Aunque es más elegante escribir:
> Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.
Lo que muestra:
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.
Las citas pueden "anidarse" (una dentro de otra) si añadimos caracteres ">" adicionales:
> Primer nivel de texto.
>
> > Cita dentro de otra.
>
> Volviendo al primer nivel.
Lo que muestra:
Primer nivel de texto.
Cita dentro de otra.
Volviendo al primer nivel.
Un párrafo de cita puede contener otros elementos markdown, incluyendo listas, cabeceras, bloques de código, etc.
> Lista de elementos:
>
> 1. Primer elemento.
> 2. Segundo elemento.
>
> Texto fuente de un programa delimitado mediante sangrado:
>
> return shell_exec("echo $input | $markdown_script");
En la conversión a HTML, las citas son bloques delimitados entre etiquetas <blockquote>, conteniendo otros elementos, como párrafos regulares, preformateados, etc:
<p>Según Wikipedia:</p>
<blockquote>
<p>HTML, acrónimo en inglés de HyperText Markup Language
('lenguaje de marcado de hipertexto'), hace referencia
al lenguaje de marcado utilizado en la creación de páginas web.</p>
</blockquote>
Línea horizontal¶
Podemos insertar una línea horizontal insertando una etiqueta <hr/> o bien si escribimos en una línea aparte tres o más guiones, asteriscos o caracteres de subrayado. Podemos añadir espacios entre estos símbolos. Por ejemplo:
* * *
***
*****
- - -
--------------------------
Un ejemplo:
Programa de ejemplo:
---
<pre>
class HelloWorld {
public static void main (String args[]) {
System.out.println("Hola Mundo");
}
}
</pre>
---
Muestra:
Programa de ejemplo:
class HelloWorld {
public static void main (String args[]) {
System.out.println("Hola Mundo");
}
}
El aspecto de final de la línea (grosor, color, etc.) depende de la hoja de estilos utilizada por MkDocs, o de las que añadamos nosotros. Nótese que en el ejemplo hemos prescindido del sangrado para marcar el párrafo preformateado, sustituyéndolo manualmente por etiquetas <pre>. Lo que logramos con esto es evitar el cambio de color de fondo añadido por las etiquetas <code>.