Introducció

Markdown és un llenguatge de marcat lleuger que permet aplicar format al text pla de manera senzilla i ràpida. Va ser creat per John Gruber l’any 2004 amb l’objectiu de facilitar l’escriptura de contingut per a la web, mantenint una sintaxi llegible tant per a les persones com per a les màquines.

Gràcies a la seva simplicitat, Markdown s’ha convertit en una eina fonamental en la redacció de documentació tècnica, blogs, fitxers README en projectes de GitHub, apunts acadèmics i publicacions en plataformes com Jekyll, Hugo, Obsidian o Notion.

Coneixements previs

• Conceptes bàsics d’HTML

Referències

• CommonMark - Especificació estàndard i referència oficial de Markdown
• Markdown Guide - Guia completa i pràctica per aprendre Markdown
• MDX documentation - Documentació oficial per a MDX, integració de Markdown i JSX

Índex

1. Què és Markdown
2. Estructura dels fitxers
   2.1. Extensions: .md i .mdx
3. Sintaxi bàsica
   3.1. Encapçalaments
   3.2. Paràgrafs i salts de línia
   3.3. Èmfasi: negreta i cursiva
   3.4. Llistes
   3.5. Enllaços i imatges
   3.6. Cites i blocs de codi
   3.7. Regles horitzontals
4. Sintaxi avançada
   4.1. Taules
   4.2. Notes a peu de pàgina
   4.3. Ancoratges
   4.4. Llistes de definició
   4.5. Llistes de tasques
   4.6. Ratllat
   4.7. Emojis
   4.8. Ressaltat
   4.9. Subíndex i superíndex
   4.10. Markdown + HTML
5. Eines per treballar amb Markdown
6. Exercicis

1. Què és Markdown

Markdown és un llenguatge de marcat lleuger que permet aplicar format al text pla de manera senzilla i llegible. Va ser creat per John Gruber l’any 2004 amb l’objectiu que els textos escrits en Markdown es poguessin convertir fàcilment a HTML i, alhora, fossin còmodes de llegir directament en la seva versió sense processar.

S’utilitza àmpliament en la creació de documentació tècnica, blogs, fitxers README de projectes, publicacions acadèmiques, entre altres. El seu principal avantatge és que redueix la complexitat dels llenguatges de marcat tradicionals com HTML o LaTeX, permetent concentrar-se en el contingut sense preocupar-se per l’estil o l’estructura del codi.

Quan parlem de Markdown, podem distingir dos conceptes importants: Markdown estàndard i Markdown estès.

• Markdown estàndard fa referència a la sintaxi original definida per John Gruber i Aaron Swartz. Inclou els elements bàsics com encapçalaments, llistes, enllaços, imatges, èmfasi en el text (negreta, cursiva), blocs de codi i regles horitzontals. Aquesta versió bàsica és compatible amb la majoria de processadors Markdown i garanteix una màxima portabilitat i simplicitat.

• Markdown estès és una evolució que afegeix funcionalitats addicionals per cobrir necessitats més avançades en la creació de documents. Aquestes extensions poden incloure elements com llistes de definició, taules, notes a peu de pàgina, emojis, ressaltat de text, llistes de tasques, subíndexs, superíndexs, entre d’altres. Tanmateix, no tots els processadors donen suport a aquestes característiques i poden variar segons la plataforma.

Per exemple, GitHub i GitLab utilitzen una versió estesa coneguda com a GitHub Flavored Markdown (GFM), que admet taules i llistes de tasques, mentre que altres plataformes poden tenir les seves pròpies extensions o limitacions.

2. Estructura dels fitxers

Un fitxer Markdown és simplement un arxiu de text pla que conté contingut estructurat utilitzant la sintaxi Markdown. A diferència dels arxius .docx o .odt, els fitxers Markdown no contenen estils visuals integrats, només instruccions d’estructura (com ara “això és un títol”, “això és una llista”, “això és un enllaç”).

Un fitxer Markdown pot contenir:

• Títols o encapçalaments, utilitzant #
• Paràgrafs de text pla
• Llistes, numerades o amb vinyetes
• Enllaços i imatges
• Taules
• Blocs de codi
• Cites

Opcionalment, pot haver-hi a l’inici del fitxer una secció anomenada frontmatter entre ---, on s’hi afegeixen metadades com el títol, l’autor, la data o etiquetes del contingut (això és útil en sistemes com Astro)

Exemple d’un fitxer bàsic:

---
title: "Exemple de Markdown"
author: "José Luis Ferrer"
---

2.1. Extensions: .md i .mdx

L’extensió .md indica que es tracta d’un fitxer escrit en Markdown estàndard. Aquests fitxers són compatibles amb la majoria d’editors de text i plataformes de documentació (com GitHub, Obsidian, Typora, VSCode, etc.).

En obrir un .md, veuràs text pla amb símbols com #, *, -, etc., que representen l’estructura del contingut. No cal compilar-lo ni transformar-lo per poder-lo llegir, tot i que normalment es visualitza millor en un renderitzador de Markdown, que interpreta la sintaxi i la mostra amb estil.

L’extensió .mdx permet escriure Markdown combinat amb components de React. És a dir, pots barrejar text formatat amb elements interactius, botons, targetes o gràfics, integrant codi JSX directament en el contingut.

Per exemple, en un fitxer .mdx podries escriure:

import { Alert } from '../components/Alert'

# Benvingut

Aquest es un fitxer .mdx. Pots veure missatges com aquest:

<Alert type="info">Aquest és un component React dins del Markdown</Alert>

Els fitxers .mdx són molt útils en projectes fets amb Astro, Next.js, Gatsby, entre altres, perquè permeten enriquir la documentació o els tutorials amb funcionalitat addicional.

3. Sintaxi bàsica

Markdown proporciona una sèrie de regles simples per donar format als documents. Aquestes regles permeten definir títols, llistes, enllaços, imatges, cites, blocs de codi, entre d’altres.

3.1. Encapçalaments

Els encapçalaments en Markdown es creen utilitzant el símbol de coixinet (#). La quantitat de coixinets indica el nivell de l’encapçalament:

# Títol de nivell 1
## Títol de nivell 2
### Títol de nivell 3
#### Títol de nivell 4
##### Títol de nivell 5
###### Títol de nivell 6

3.2. Paràgrafs i salts de línia

En Markdown, un paràgraf és simplement un bloc de text separat per una línia en blanc. No cal utilitzar etiquetes ni ordres especials per crear paràgrafs; Markdown els detecta automàticament quan deixes un espai entre blocs de text.

Això és un primer paràgraf.

Això és un segon paràgraf.

Aquest codi generarà dos paràgrafs separats, ja que hi ha una línia en blanc entre ells.

Per fer un salt de línia sense iniciar un nou paràgraf, pots:

• Escriure dos espais al final de la línia
• O bé utilitzar una barra invertida al final: \\

Primera línia amb salt de línia.
Segona línia just a sota.

Això es mostrarà com:

Primera línia amb salt de línia.
Segona línia just a sota.

3.3. Èmfasi: negreta i cursiva

Markdown permet ressaltar parts del text mitjançant cursiva i negreta, cosa que és molt útil per destacar idees, paraules clau o instruccions importants.

• 🟡 Cursiva

Per escriure en cursiva, encercla el text entre * o _:

*Aquest text està en cursiva*
_Aquest també_

• ⚫ Negreta

Per usar negreta, s’utilitzen dobles asteriscs ** o guions baixos __:

**Aquest text està en negreta**
__Aquest també__

• 🟢 Combinació de negreta i cursiva

Pots combinar ambdós estils afegint tres asteriscs *** o tres guions baixos ___:

___Aquest text està en cursiva y negreta___
***Aquest text està en cursiva y negreta***

3.4. Llistes

Markdown permet crear dos tipus de llistes: no ordenades (amb vinyetes) i ordenades (numerades). Són una forma clara d’organitzar idees, passos o elements relacionats.

• 🔹 Llistes no ordenades

Utilitza -, * o + seguits d’un espai per crear una llista amb vinyetes.

- Poma
- Pera
- Plàtan

També es pot utilitzar:

* Opció A
* Opció B

• 🔸 Llistes ordenades

Només cal utilitzar números seguits d’un punt i un espai:

1. Pas u
2. Pas dos
3. Pas tres

No importa si no estan en ordre (Markdown els mostrarà correctament), però és bona pràctica numerar-los bé.

3.5. Enllaços i imatges

Markdown fa molt fàcil afegir enllaços i mostrar imatges sense haver d’escriure codi HTML.

• 🔗 Enllaços

L’estructura bàsica és:

[Text visible](https://url.com)

Per exemple:

Consulta el portal [FPCode](https://www.fpcode.es)

Això es mostrarà com:
👉 Consulta el portal FPCode

Es poden fer enllaços directament amb els símbols < > sense incloure cap text alternatiu.

Prem aquí 👉 <https://www.fpcode.es>

• 🖼️ Imatges

Per inserir una imatge, s’usa un signe d’exclamació ! seguit del mateix format que un enllaç:

![Text alternatiu](https://url-de-la-imatge.com/imatge.png)

Per exemple:

![Logo de FPCode](https://www.fpcode.es/ca/logo/entry.jpg)

Això mostrarà directament la imatge (si està disponible des d’aquesta URL).

3.6. Cites i blocs de codi

Markdown et permet representar cites textuals i blocs de codi, dos recursos molt útils quan estàs escrivint documentació tècnica, explicant fragments de programació o ressaltant informació d’una font externa.

• 🟨 Cites

Per escriure una cita o bloc citat, s’utilitza el símbol > a l’inici de la línia. El pots fer servir per destacar frases, definicions o cites d’autors.

> Aquesta és una cita simple.

Això es mostrarà visualment com:

Aquesta és una cita simple.

Pots anidar diverses línies dins d’una cita simplement mantenint el símbol > a cada línia o afegint línies en blanc dins del bloc:

> Markdown permet escriure de forma senzilla.
>
> Aquesta és una segona línia dins de la mateixa cita.

• 🟥 Blocs de codi

Markdown et permet mostrar fragments de codi de dues maneres:

Quan necessites mostrar només una paraula o una petita instrucció de codi dins d’una frase, utilitza una sola ` per encerclar el fragment:

La comanda `npm install` s’utilitza per instal·lar paquets.

Això es mostrarà com:

La comanda npm install s’utilitza per instal·lar paquets.

Quan vols mostrar diverses línies de codi, utilitza tres ` seguides al principi i al final del bloc. Pots especificar el llenguatge després de les primeres tres ` perquè tingui ressaltat de sintaxi (això és molt útil en editors com VSCode o plataformes com GitHub, Astro o Starlight).

Exemple per mostrar codi HTML:

```html
<!DOCTYPE html>
<html>
  <head>
    <title>Exemple</title>
  </head>
  <body>
    <p>Hola Markdown</p>
  </body>
</html>
`` `

Un altre exemple per mostrar codi JavaScript:

```javascript
function saludar(nom) {
  return `Hola, ${nom}!`;
}
`` `

Això permet que el codi sigui llegible, estigui ben formatat i no es barregi amb el text normal del document.

A continuació es mostra una llista comuna de llenguatges que poden suportar els blocs de codi.

3.7. Regles horitzontals

Les regles horitzontals s’utilitzen per separar visualment seccions dins d’un document, creant una línia divisòria que ajuda a organitzar el contingut.

Per crear una regla horitzontal en Markdown, només cal incloure en una línia en blanc almenys tres d’aquests caràcters: asteriscs *, guions - o guions baixos _.

***
Secció 1
---
Secció 2
___

Aquests símbols es tradueixen en HTML com una etiqueta <hr>, que genera una línia horitzontal en la presentació del contingut. La seva visualització és:

Sección 1

Sección 2

4. Sintaxi avançada

A més dels elements bàsics, Markdown ofereix característiques més avançades que permeten estructurar la informació de manera més completa, com l’ús de taules, notes a peu de pàgina, llistes de definició, entre d’altres. A més, existeix la possibilitat d’inserir directament codi HTML. Això facilita la combinació de Markdown amb elements HTML per personalitzar encara més el contingut.

És important tenir en compte que aquestes funcionalitats formen part d’una extensió de la sintaxi bàsica, la qual cosa significa que no totes les aplicacions o plataformes les suporten. Per això, és recomanable comprovar si l’entorn on treballes admet aquestes característiques abans d’utilitzar-les.

4.1. Taules

Markdown permet representar taules de manera senzilla utilitzant tubs (|) i guions (-). Les taules són útils per comparar elements, mostrar dades estructurades o resumir característiques.

L’estructura general d’una taula és:

| Columna 1 | Columna 2 |
|-----------|-----------|
| Dada A    | Dada B    |
| Dada C    | Dada D    |

Això es veurà així:

• 🧭 Alineació de columnes

Pots alinear el contingut a l’esquerra, al centre o a la dreta fent servir els dos punts (:):

• Alineació a l’esquerra: :---
• Alineació al centre: :---:
• Alineació a la dreta: ---:

Un exemple:

| Esquerra  | Centre | Dreta   |
|:----------|:------:|--------:|
| A         | B      | C       |
| D         | E      | F       |

4.2. Notes a peu de pàgina

Les notes a peu de pàgina són referències dins del text que es desenvolupen al final, molt útils per a cites o aclariments.

Aquest és un text amb una nota a peu de pàgina.[^1]

[^1]: Aquesta és l'explicació o aclariment de la nota.

4.3. Ancoratges

Els IDs personalitzats als encapçalaments et permeten assignar un identificador únic a cada títol, cosa que facilita enllaçar directament a aquesta secció des de qualsevol lloc, sigui dins del mateix document o des d’una altra pàgina.

Això és especialment útil per crear índexs dinàmics o referències ràpides en documents llargs.

Exemple:

### El Meu Gran Encapçalament {#custom-id}

Després, pots utilitzar un enllaç que apunti a aquest ID així:

[Anar al meu gran Encapçalament](#custom-id)

D’aquesta manera pots enllaçar directament a aquest títol utilitzant #custom-id a la URL o navegació.

4.4. Llistes de definició

Serveixen per definir termes de manera clara, molt usades en glossaris.

Terme 1
: Definició del terme 1

Terme 2
: Primera definició del terme 2
: Segona definició del terme 2

Es mostrarà:

Tèrmen 1

Definició del tèrmen 1

Tèrmen 2

Primera definició del tèrmen 2

Segona definició del tèrmen 2

4.5. Llistes de tasques

Permeten marcar tasques pendents o completades, molt usades en gestió i seguiment.

- [x] Escriure el comunicat de premsa
- [ ] Actualitzar la pàgina web
- [ ] Contactar amb els mitjans

Aquest codi mostrarà:

• Escriure el comunicat de premsa
• Actualitzar la pàgina web
• Contactar amb els mitjans

4.6. Ratllat

Per mostrar text eliminat o corregit s’utilitza la doble virgulilla.

~~El món és pla.~~

Es mostrarà:

El món és pla.

4.7. Emojis

Molts sistemes permeten inserir emojis escrivint el seu codi entre dos punts.

Això és molt divertit! :joy:

Així es podran veure els icones:

Això és molt divertit! 😄

4.8. Ressaltat

Algunes implementacions permeten destacar text amb doble signe igual.

Necessito ressaltar aquestes ==paraules molt importants==.

Es veurà així:

Necessito ressaltar aquestes paraules molt importants.

4.9. Subíndex i superíndex

S’utilitza per escriure text en format subíndex o superíndex, comú en fórmules químiques o matemàtiques, com potències o exponents.

H~2~O

Mostrarà: H₂O

X^2^

Mostrarà: X²

4.10. Markdown + HTML

Un dels avantatges de Markdown és que permet inserir codi HTML directament dins del document, cosa que resulta molt útil quan necessites una personalització que Markdown no cobreix per si sol. A més, en usar etiquetes HTML pots aplicar estils CSS en línia per modificar l’aparença del contingut de forma més detallada.

El resultat serà un text estilitzat amb color i negreta, sense haver utilitzat sintaxi Markdown per aplicar format, sinó directament CSS mitjançant atributs HTML.

També és possible combinar contingut escrit en Markdown amb estructures HTML més complexes, com llistes o taules personalitzades:

<p style="color: teal; font-weight: bold;">
Aquest text usa HTML dins de Markdown.
</p>

Aquesta combinació et dóna un major control visual respecte a les llistes tradicionals de Markdown. És especialment útil quan necessites afegir atributs, aplicar classes CSS o integrar elements interactius en un lloc web o documentació enriquida.

Això és un exemple, combinant *Markdown* i **HTML**.
<ul>
  <li>Element A</li>
  <li>Element B</li>
  <li>Element C</li>
</ul>

Això permet un major control visual que les llistes tradicionals en Markdown, per exemple si vols aplicar classes, estils o atributs específics.

5. Eines per treballar amb Markdown

Per treballar amb Markdown no n’hi ha prou amb tenir un editor de text: també cal disposar d’eines que tradueixin o compilin el contingut Markdown a HTML o altres formats usables a la web o en documents. Afortunadament, existeix un ampli ecosistema d’editors, processadors i convertidors que faciliten aquesta tasca i milloren l’experiència d’escriptura i publicació.

A continuació, es descriuen algunes de les eines més utilitzades.

Editors de Markdown

• Visual Studio Code
  és un editor generalista que permet treballar amb Markdown ampliant la seva funcionalitat amb les extensions que es poden instal·lar, com MDX per gestionar fitxers .mdx o markdownlint per mantenir la sintaxi correcta i consistent. VS Code ofereix funcionalitats avançades com l’autocompletat, vista prèvia en temps real, ressaltat de sintaxi i gestió de fragments (snippets), cosa que el converteix en un entorn molt potent i personalitzable per crear documents Markdown o contingut MDX dins de projectes web.

• Dillinger
  és un editor Markdown online i gratuït, ideal per a qui prefereix no instal·lar programari. Permet escriure, editar i exportar documents Markdown directament des del navegador, amb integració a serveis al núvol com Dropbox, GitHub i Google Drive. És perfecte per a treballs ràpids, col·laboratius o quan es treballa des de diferents dispositius sense un entorn fix.

• Obsidian
  editor centrat en la presa de notes i l’organització del coneixement basades en Markdown, amb un enfocament en la creació de xarxes de coneixement mitjançant enllaços entre notes. El seu principal avantatge és la possibilitat de crear xarxes de notes enllaçades, cosa que facilita la gestió de documentació complexa o extensa. És especialment útil per a escriptors, investigadors i professionals que treballen amb grans volums d’informació i necessiten mantenir-la estructurada i fàcilment accessible.

Convertidors i processadors

A més dels editors, és imprescindible disposar d’eines que converteixin el Markdown a HTML o altres formats útils per a la seva publicació i distribució.

• Pandoc
  és una eina extremadament versàtil que funciona com un convertidor universal de documents. Suporta múltiples formats d’entrada i sortida, incloent Markdown, HTML, PDF, LaTeX, DOCX, EPUB i molts més. Això permet, per exemple, generar documents professionals a partir de fitxers Markdown, o integrar Markdown en fluxos de treball acadèmics o editorials complexos. Pandoc també suporta extensions de Markdown avançat i permet personalitzar el resultat final mitjançant plantilles i filtres.

6. Exercicis