Nota: esta guía está totalmente basada en la guía de DaringFireball. y traducida al español.
Markdown admite dos estilos de encabezados, Setext y atx.
Los encabezados de estilo de texto están “subrayados” usando signos de igual (para encabezados de primer nivel) y guiones (para encabezados de segundo nivel). Por ejemplo:
This is an H1
=============
This is an H2
------------- Cualquier número de subrayado = 's o' funcionará.
Los encabezados de estilo Atx usan 1-6 caracteres hash al comienzo de la línea, correspondientes a los niveles de encabezado 1-6. Por ejemplo:
# This is an H1
## This is an H2
###### This is an H6
Opcionalmente, se puede “cerrar” los encabezados de estilo atx. Esto es puramente cosmético; podés usarlo si crees que se ve mejor. Los hashes de cierre ni siquiera necesitan coincidir con el número de hashes utilizados para abrir el encabezado. (El número de hashes de apertura determina el nivel del encabezado):
# This is an H1 #
## This is an H2 ##
### This is an H3 ######
Markdown utiliza caracteres de estilo de correo electrónico > para comillas en bloque. Si estás familiarizado con citar pasajes de texto en un mensaje de correo electrónico, entonces sabés cómo crear una cita en bloque en Markdown. Se ve mejor si ajustás firmemente el texto y ponés un > antes de cada línea:
> This is a blockquote with two paragraphs. 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.
Markdown allows you to be lazy and only put the > before the first line of a hard-wrapped paragraph:
> This is a blockquote with two paragraphs. 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 en bloque se pueden anidar (es decir, una cita en bloque en una cita en bloque) agregando niveles adicionales de >:
> This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level.
Las citas en bloque pueden contener otros elementos de Markdown, incluidos encabezados, listas y bloques de código:
> ## This is a header.
>
> 1. This is the first list item.
> 2. This is the second list item.
>
> Here's some example code:
>
> return shell_exec("echo $input | $markdown_script");
Cualquier editor de texto decente debería facilitar las citas al estilo del correo electrónico. Por ejemplo, con BBEdit, puede hacer una selección y elegir Aumentar Nivel de Cita en el menú Texto.
Markdown admite listas ordenadas (numeradas) y no ordenadas (con viñetas).
Las listas desordenadas utilizan asteriscos, más y guiones - de manera intercambiable - como marcadores de lista:
* Red
* Green
* Blue
es equivalente a:
+ Red
+ Green
+ Blue
y:
- Red
- Green
- Blue
Las listas ordenadas usan números seguidos de puntos:
1. Bird
2. McHale
3. Parish
Es importante tener en cuenta que los números que usás para marcar la lista no tienen efecto en la salida HTML que Markdown produce. El HTML Markdown que produce la lista anterior es:
<ol>
<li>Bird</li>
<li>McHale</li>
<li>Parish</li>
</ol>
Si, en cambio, escribiste la lista en Markdown así:
1. Bird
1. McHale
1. Parish
o incluso:
3. Bird
1. McHale
8. Parish
obtendrías exactamente la misma salida HTML. El punto es que, si querés, podés usar números ordinales en sus listas de Markdown ordenadas, para que los números en su fuente coincidan con los números en su HTML publicado. Pero si querés ser flojo, no tenés que hacerlo.
Sin embargo, si utilizás la numeración de la lista diferida, aún tenés que comenzar la lista con el número 1. En algún momento en el futuro, Markdown puede admitir el inicio de listas ordenadas en un número arbitrario.
Los marcadores de lista generalmente comienzan en el margen izquierdo, pero pueden estar indentados por hasta tres espacios. Los marcadores de lista deben ir seguidos de uno o más espacios o una pestaña. Para que las listas se vean bien, puede envolver elementos con indentación colgantes:
* 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.
Pero si querés ser flojo, no tenés que hacerlo:
* 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.
Si los elementos de la lista están separados por líneas en blanco, Markdown ajustará los elementos en etiquetas <p> en la salida HTML. Por ejemplo, esta entrada:
* Bird
* Magic
Se convertirá en:
<ul>
<li>Bird</li>
<li>Magic</li>
</ul>
Pero esto:
* Bird
* Magic
Se convertirá en:
<ul>
<li><p>Bird</p></li>
<li><p>Magic</p></li>
</ul>
Los elementos de la lista pueden consistir en múltiples párrafos. Cada párrafo posterior en un elemento de la lista debe estar sangrado por 4 espacios o una pestaña:
1. This is a list item with two paragraphs. 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.
2. Suspendisse id sem consectetuer libero luctus adipiscing.
Se ve bien si indentás cada línea de los párrafos posteriores. Pero, nuevamente, Markdown te permitirá ser flojo:
* This is a list item with two paragraphs.
This is the second paragraph in the list item. You're
only required to indent the first line. Lorem ipsum dolor
sit amet, consectetuer adipiscing elit.
* Another item in the same list.
Para colocar una cita en bloque dentro de un elemento de la lista, los delimitadores de la cita (>) en bloque deben indentarse:
* A list item with a blockquote:
> This is a blockquote
> inside a list item.
To put a code block within a list item, the code block needs to be indented twice — 8 spaces or two tabs:
* A list item with a code block:
<code goes here>
Vale la pena señalar que es posible activar una lista ordenada por accidente, escribiendo algo como esto:
1986. What a great season.
In other words, a number-period-space sequence at the beginning of a line. To avoid this, you can backslash-escape the period:
1986\. What a great season.
Los bloques de código formateados previamente se utilizan para escribir sobre código fuente de programación o marcado. En lugar de formar párrafos normales, las líneas de un bloque de código se interpretan literalmente. Markdown envuelve un bloque de código en las etiquetas <pre> y <code>.
Para producir un bloque de código en Markdown, simplemente indentá cada línea del bloque por al menos 4 espacios o 1 tabulación. Por ejemplo, dada esta entrada:
This is a normal paragraph:
This is a code block.
Markdown generará:
<p>This is a normal paragraph:</p>
<pre><code>This is a code block.
</code></pre>
Se elimina un nivel de sangría, 4 espacios o 1 tabulación, de cada línea del bloque de código. Por ejemplo, esto:
Here is an example of AppleScript:
tell application "Foo"
beep
end tell
Se convertirá en:
<p>Here is an example of AppleScript:</p>
<pre><code>tell application "Foo"
beep
end tell
</code></pre>
Un bloque de código continúa hasta que alcanza una línea que no está indentada (o al final del artículo).
Dentro de un bloque de código, los símbolos (&) y los corchetes angulares (
<div class="footer">
© 2004 Foo Corporation
</div>
Se convertirá en:
<pre><code><div class="footer">
&copy; 2004 Foo Corporation
</div>
</code></pre>
La sintaxis de Markdown normal no se procesa dentro de los bloques de código. Por ejemplo, los asteriscos son solo asteriscos literales dentro de un bloque de código. Esto significa que también es fácil usar Markdown para escribir sobre la sintaxis propia de Markdown.
Podés producir una etiqueta de regla horizontal (<hr />) colocando tres o más guiones, asteriscos o guiones bajos en una línea por sí mismos. Si lo desea, puede usar espacios entre los guiones o asteriscos. Cada una de las siguientes líneas producirá una regla horizontal:
* * *
***
*****
- - -
---------------------------------------
Markdown admite dos estilos de enlaces: en línea y de referencia.
En ambos estilos, el texto del enlace está delimitado por [corchetes].
Para crear un enlace en línea, usá un conjunto de paréntesis regulares inmediatamente después del corchete de cierre del texto del enlace. Dentro de los paréntesis, colocá la URL donde desea que apunte el enlace, junto con un título opcional para el enlace, entre comillas. Por ejemplo:
This is [an example](http://example.com/ "Title") inline link.
[This link](http://example.net/) has no title attribute.
producirá:
<p>This is <a href="http://example.com/" title="Title">
an example</a> inline link.</p>
<p><a href="http://example.net/">This link</a> has no
title attribute.</p>
Si se refiere a un recurso local en el mismo servidor, podés usar direcciones relativas:
See my [About](/about/) page for details.
Los enlaces de estilo de referencia usan un segundo conjunto de corchetes, dentro del cual coloca una etiqueta de su elección para identificar el enlace:
This is [an example][id] reference-style link.
Opcionalmente, podés usar un espacio para separar los conjuntos de corchetes:
This is [an example] [id] reference-style link.
Luego, en cualquier parte del documento, definís su etiqueta de enlace de esta manera, en una línea por sí misma:
[id]: http://example.com/ "Optional Title Here"
Es decir:
Las siguientes tres definiciones de enlace son equivalentes:
[foo]: http://example.com/ "Optional Title Here"
[foo]: http://example.com/ 'Optional Title Here'
[foo]: http://example.com/ (Optional Title Here)
NOTA: Hay un error conocido en Markdown.pl 1.0.1 que evita que se usen comillas simples para delimitar los títulos de los enlaces.
La URL del enlace puede, opcionalmente, estar entre corchetes angulares:
[id]: <http://example.com/> "Optional Title Here"
Podés colocar el atributo de título en la siguiente línea y usar espacios o pestañas adicionales para el relleno, que tiende a verse mejor con URL más largas:
[id]: http://example.com/longish/path/to/resource/here
"Optional Title Here"
Las definiciones de enlace solo se usan para crear enlaces durante el procesamiento de Markdown, y se eliminan de su documento en la salida HTML.
Los nombres de definición de enlace pueden consistir en letras, números, espacios y signos de puntuación, pero no distinguen entre mayúsculas y minúsculas. P.ej. estos dos enlaces:
[link text][a]
[link text][A]
son equivalentes.
El acceso directo implícito al nombre del enlace le permite omitir el nombre del enlace, en cuyo caso el texto del enlace se usa como nombre. Simplemente usá un conjunto vacío de corchetes; por ejemplo, para vincular la palabra “Google” al sitio web google.com, simplemente escribí:
[Google][]
Y luego definí el enlace:
[Google]: http://google.com/
Como los nombres de los enlaces pueden contener espacios, este acceso directo incluso funciona para varias palabras en el texto del enlace:
Visit [Daring Fireball][] for more information.
Y entonces, definí el link:
[Daring Fireball]: http://daringfireball.net/
Las definiciones de enlace se pueden colocar en cualquier parte de su documento Markdown. Se tiende a ponerlos inmediatamente después de cada párrafo en el que se usan, pero si querés, podés ponerlos todos al final de su documento, como notas a pie de página.
Aquí hay un ejemplo de enlaces de referencia en acción:
I get 10 times more traffic from [Google] [1] than from
[Yahoo] [2] or [MSN] [3].
[1]: http://google.com/ "Google"
[2]: http://search.yahoo.com/ "Yahoo Search"
[3]: http://search.msn.com/ "MSN Search"
Usando el acceso directo de nombre de enlace implícito, en su lugar podrías escribir:
I get 10 times more traffic from [Google][] than from
[Yahoo][] or [MSN][].
[google]: http://google.com/ "Google"
[yahoo]: http://search.yahoo.com/ "Yahoo Search"
[msn]: http://search.msn.com/ "MSN Search"
Los dos ejemplos anteriores producirán la siguiente salida HTML:
<p>I get 10 times more traffic from <a href="http://google.com/"
title="Google">Google</a> than from
<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
A modo de comparación, aquí está el mismo párrafo escrito con el estilo de enlace en línea de Markdown:
I get 10 times more traffic from [Google](http://google.com/ "Google")
than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
[MSN](http://search.msn.com/ "MSN Search").
El punto de los enlaces de estilo de referencia no es que sean más fáciles de escribir. El punto es que con los enlaces de estilo de referencia, la fuente del documento es mucho más legible. Compará los ejemplos anteriores: usando enlaces de estilo de referencia, el párrafo en sí solo tiene 81 caracteres de longitud; con enlaces de estilo en línea, tiene 176 caracteres; y como HTML sin procesar, tiene 234 caracteres. En el HTML sin formato, hay más marcado que texto.
Con los enlaces de estilo de referencia de Markdown, un documento fuente se parece mucho más a la salida final, tal como se representa en un navegador. Al permitirte mover los metadatos relacionados con el marcado fuera del párrafo, podés agregar enlaces sin interrumpir el flujo narrativo de su prosa.
Markdown trata los asteriscos (*) y los guiones bajos (_) como indicadores de énfasis. El texto envuelto con uno * o _ se envolverá con una etiqueta HTML <em>; los dobles * ’o _’s se envolverán con una etiqueta HTML <strong>. Por ejemplo, esta entrada:
*single asterisks*
_single underscores_
**double asterisks**
__double underscores__
producirá:
<em>single asterisks</em>
<em>single underscores</em>
<strong>double asterisks</strong>
<strong>double underscores</strong>
Podés usar el estilo que prefieras; La única restricción es que se debe usar el mismo carácter para abrir y cerrar un intervalo de énfasis.
El énfasis se puede usar en medio de una palabra:
un*frigging*believable
Pero si rodeás un * o _ con espacios, se lo tratará como un asterisco literal o guión bajo.
Para producir un asterisco literal o un guión bajo en una posición donde de otro modo se usaría como un delimitador de énfasis, podés usar una barra invertida para escaparlo:
\*this text is surrounded by literal asterisks\*
Para escribir un bloque de código, envolvelo con comillas de retroceso (`). A diferencia de un bloque de código preformateado, un intervalo de código indica código dentro de un párrafo normal. Por ejemplo:
Use the `printf()` function.
producirá:
<p>Use the <code>printf()</code> function.</p>
Para incluir un carácter de retroceso literal dentro de un intervalo de código, podés usar múltiples retrocesos como delimitadores de apertura y cierre:
``There is a literal backtick (`) here.``
que producirá esto:
<p><code>There is a literal backtick (`) here.</code></p>
Los delimitadores de retroceso que rodean un tramo de código pueden incluir espacios, uno después de la apertura, uno antes del cierre. Esto te permite colocar caracteres de retroceso literal al principio o al final de un intervalo de código:
A single backtick in a code span: `` ` ``
A backtick-delimited string in a code span: `` `foo` ``
producirá:
<p>A single backtick in a code span: <code>`</code></p>
<p>A backtick-delimited string in a code span: <code>`foo`</code></p>
Con una extensión de código, los signos de unión y los corchetes angulares se codifican automáticamente como entidades HTML, lo que facilita la inclusión de ejemplos de etiquetas HTML. Markdown convertirá esto:
Please don't use any `<blink>` tags.
en:
<p>Please don't use any <code><blink></code> tags.</p>
Podés escribir esto:
`—` is the decimal-encoded equivalent of `—`.
para producir:
<p><code>&#8212;</code> is the decimal-encoded
equivalent of <code>&mdash;</code>.</p>
Es cierto que es bastante difícil diseñar una sintaxis “natural” para colocar imágenes en un formato de documento de texto sin formato.
Markdown utiliza una sintaxis de imagen que pretende parecerse a la sintaxis de los enlaces, lo que permite dos estilos: en línea y de referencia.
La sintaxis de la imagen en línea se ve así:
Es decir:
La sintaxis de la imagen de estilo de referencia se ve así:
![Alt text][id]
Donde “id” es el nombre de una referencia de imagen definida. Las referencias de imagen se definen utilizando una sintaxis idéntica a las referencias de enlace:
[id]: url/to/image "Optional title attribute"
Al escribir estas líneas, Markdown no tiene sintaxis para especificar las dimensiones de una imagen; si esto es importante para vos, simplemente podés usar etiquetas HTML normales <img>.
Markdown admite un estilo de acceso directo para crear enlaces “automáticos” para URL y direcciones de correo electrónico: simplemente rodeá la URL o la dirección de correo electrónico con corchetes angulares. Lo que esto significa es que, si querés mostrar el texto real de una URL o dirección de correo electrónico, y también hacer que sea un enlace en el que se pueda hacer clic, podés hacer esto:
<http://example.com/>
Markdown convertirá esto en:
<a href="http://example.com/">http://example.com/</a>
Los enlaces automáticos para direcciones de correo electrónico funcionan de manera similar, excepto que Markdown también realizará un poco de codificación aleatoria de entidades decimales y hexadecimales para ayudar a ocultar su dirección de los robots de spam que recolectan direcciones. Por ejemplo, Markdown convertirá esto:
<address@example.com>
en algo como esto:
<a href="mailto:addre
ss@example.co
m">address@exa
mple.com</a>
que se mostrará en un navegador como un enlace en el que se puede hacer clic “dirección@ejemplo.com”.
(Este tipo de truco de codificación de entidades realmente engañará a muchos, si no a la mayoría, de los robots de recolección de direcciones, pero definitivamente no los engañará a todos. Es mejor que nada, pero una dirección publicada de esta manera probablemente comenzará a recibir correo no deseado.)
Markdown te permite usar escapes con barra invertida para generar caracteres literales que de otro modo tendrían un significado especial en la sintaxis de formato de Markdown. Por ejemplo, si querés rodear una palabra con asteriscos literales (en lugar de una etiqueta HTML <em>), podés usar barras invertidas antes de los asteriscos, de esta manera:
\*literal asterisks\*
Markdown proporciona escapes de barra invertida para los siguientes caracteres:
\ barra invertida
` retroceso
* asterisco
_ guion bajo
{} llaves
[] corchetes
() paréntesis
# símbolo de hash
+ signo más
- signo menos (guión)
. punto
! signo de exclamación