Markdown
Markdown és un llenguatge orientat a l'escriptura de documents de manera que siguin bons d'escriure i bons de llegir. Amb això comparteix la mateixa filosofia que altres com reStructuredText o Textile, és a dir, són llenguatges que permeten escriure la documentació de manera que sigui llegible directament en text pla.
Aixà com com reStructuredText és va força bé per escriure documents llargs i complexos, Markdown és ideal per al l'escriptura d'apunts als blogs, ja que a més del seu marcatge particular, permet incloure directament html si ho necessitam.
Mesclant markdown i HTML
Consideram dos tipus d'elements HTML a l'hora de incloure codi HTML dins el document markdown:
elements de bloc: Per poder passar a escriure HTML dins el document markdown he de tenir en compte que el codi HTML ha d'estar separat de la resta del document markdown per un lÃnia en blanc i l'HTML ha de començar a la primera columna, és a dir, sense espais ni tabuladors. Si feim servir l'HTML no podem fer servir la sintaxi markdown, és a dir, una vegada inicial el bloc html tot allò és html. elements en lÃnia: Podem utilitzar l'html aixà com vulguem, per exemple, podem fer servir indistintament l'asterisc o <strong/> per marcar una paraula o frase en negreta. Són elements en lÃnia <span>, <cite>, <a>, <img> etc.
Elements de bloc
Parà grafs
Per a indicar un parà graf simplement hem de deixar una o més lÃnies en blanc. La conversió que fa markdown cap a HTML fa que es generin marques de parà graf <p>. Si volem generar sals de lÃnies amb <br/> haurem de fer acabar el nostre parà graf amb dos o més espais en blanc i seguidament pitjar la tecla de salt de lÃnia.
Capçaleres
Markdown pot fer servir dos estils de capçaleres:
Capçalera tipus H1
==================
Capçalera tipus H2
-------------------
o bé fer servir # per a indicar el nivell de la capçalera que volem fer servir, aixÃ:
# Això és un H1
## Això és un H2
### Això és un H3
###### Això és un H6
encara que no és estrictament necessari podem fer acabar la capçalera també amb el mateix sÃmbol. Per exemple:
# Capçalera H1 estèticament millor #
Citacions
Markdown permet citar text fent servir el sÃmbol > davant cada lÃnia que vulguem que figuri com a citada o davant el parà graf. AixÃ:
> això és una cita literal d'un text
queda com
això és una cita literal d'un text
Llistes
Podem fer servir llistes ordenades i no ordenades. Les perimeres es fan posant un nombre seguit d'un punt, i les segones amb un asterisc, guió o sÃmbol de suma.
Per exemple:
Llista no ordenada
* Joan
* Pere
* Miquel
Llista ordenada
1. Joan
2. Pere
3. Miquel
No és necessari mantenir l'ordre de la nuemració en un llista ordenada, basta que hi hagi un nombre seguit d'un punt, a partir d'aquà Markdown ja ho generarà com toca.
Si els elements de la llista estan separats per una lÃnia en blanc, markdown generarà tags de parà graf al voltant dels elements de la llista. Si l'element està composat per dos o més parà graf hem de tenir en compte que cada parà graf de la llista ha d'estar identat al manco per 4 espais o un tabulador. Per posar codi dins una llista l'hem d'identar al manco 8 espais o 2 tabuladors.
Si per la raó que sigui no volem que s'inicii la numeració d'una llista, haurem d'escapar el punt amb la barra invertida \.
Blocs de codi
Els bloc de codi van molt bé quan un ha de parlar damunt programació o té necessitat de posar un llistat de codi dins el text. Markdown genera el tag <code> si identam cada lÃnia que formi part del codi amb un tabulador o quatre espais.
El bloc de codi continuarà fins a trobar un bloc que no estigui identat o fins al final de parà graf.
Dins un bloc de codi els (&) i (<>) són gestionats automà ticament pel makdown i convertits de manera que es pugui representar fà cilment codi HTML. Per a facilitar que es pugui escriure de markdown la sintaxis markdown no es processada dins un bloc de codi, la qual cosa, per exemple permet escriure aquest article.
LÃnia horitzontal
Generar una lÃnia horitzontal <hr /> és tan senzill com posar asteriscs o guionets al començament de la lÃnia i que no hi hagi res mes. Queda molt bé indicar visualment que es tracta d'una lÃnia horitzontal decorant-ho un poc més. Per exemple:
------------------------------------------------------------------
queda molt més clar que si sol feim
*
Tot i això el resultat el mateix:
Elements en lÃnia
Enllaços.
Per posar un enllaç la sintaxi és
[nom que ha d'aparèixer](url "text del tÃtol")
per exemple:
[trespams] (http://trespams.com "blog de trespams")
genera el codi
<a href="http://trespams.com" title="blog de trespams">trespams</a>
Si hem d'enllaçar recursos locals dins el mateix servidor, podem fer servir camins relatius, per exemple:
mira [Sobre mi] (/about/) per més detalls
Podem enllaçar també per referència i fer servir dreceres per escriure el link quan en nom i l'enllaç coincideixen:
Tenc 10 vegades més trà fic des de [Google][] que des de
[Yahoo] [1] o [MSN] [2].
[Google]: http://google.com "El cercador Google"
[1]: http://search.yahoo.com/ "Cerca a Yahoo"
[2]: http://search.msn.com/
En el primer cas com que l'enllaç i el nom coincideixen ens bastaria posar el nom, en el segon cas feim la referència i també posam el tÃtol i en el tercer cas hem fet la referència però no posam el tÃtol. Això genera:
Tenc 10 vegades més trà fic des de Google que des de
Yahoo o MSN.
La idea de les referències no és que siguin més fà cils d'escriure sinó que es fan per augmentar la llegibilitat del codi, ja que es veu que hi ha un enllaç però aquest no posa renou dins el codi.
Èmfasi
Per posar negretes o cursives feim servir el doble asterisc o l'asterisc simple respectivament. També podem fer servir el guionet de subrajat, doble en el primer cas i simple en el segon.
**Això va en negreta** i això _italic_
Això va en negreta i això italic
Si volem posa un asterisc * o un guionet de subrajat _ ho haurem de fer escapant els carà cters, aixà \* i \_.
Codi
Per indicar que estam escrivint codi, però que aquest s'ha de tractar com a un element de lÃnia farem servir l'accent greu `, per exemple:
exemple de funció lambda `lambda x,y: x+y` en [Python](http://python.org "Python site")
exemple de funció lambda lambda x,y: x+y en Python
Imatges
Per a incloure una imatge la sintaxi és
De la mateixa manera que amb els enllaços, podem indicar les imatges per referència de manera que la sintaxi queda com:
![Text Alt][referència]
[referència]: url/a/la/imatge "tÃtol opcional"
Altres
Markdown ens permet dreceres per a la generació d'enllaços. Simplement hem d'escriure el nom de l'enllaç i envoltar-ho de <>. Per exemple l'enllaç http://bulma.com, s'ha generat com
<http://bulma.com>
Per escriure adreces d'e-mail també ho podem fer d'auesta manera, però en aquest cas markdown fa una conversió intel·ligent per mirar de fotre els spammers, convertir cada carà cter de l'adreça al seu equivalent hexadecimal. Per a escapar un carà cter amb significat especial a markdown ho podem fer precedint-ho de \
Agraïments
Aquest document és una traducció lliure al català del document original en anglès escrit per John Gruber. Ha estat escrit amb l'editor Kate de KDE com a part de la documentació en català de que esper que sigui aviat el meu nou programari per a la gestió del blog de trespams. Podeu trobar el document original en format markdown dins el subversion del projecte. | 
