El Blog de Trespams

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/ "sobre mi") 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

    ![Text Alt](url "títol opcional")
    

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://trespams.com, s'ha generat com

  <http://trespams.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 </li>

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.