Markdown és text pla amb uns quants símbols que després es converteixen en format. Els fitxers acaben en .md i els pots obrir amb qualsevol editor. A GitHub, Notion, Obsidian, Discord i Reddit el resultat és el mateix, amb alguna petita diferència.

Títols

Un # per cada nivell, de 1 a 6, i un espai abans del text.

exemple.md# Títol principal
## Subtítol
### Apartat

Paràgrafs i salts de línia

Dues línies seguides es fusionen en un sol paràgraf. Per començar-ne un de nou cal una línia en blanc.

exemple.mdPrimera línia
segona línia, mateix paràgraf.

Això és un paràgraf nou.

Per forçar un salt de línia dins del mateix paràgraf, acaba la línia amb una barra invertida. També val acabar-la amb dos espais, però no es veuen i es perden fàcilment.

exemple.mdCarrer Major, 5\
17001 Girona

Negreta, cursiva i tallat

exemple.md*cursiva*  o  _cursiva_
**negreta**  o  __negreta__
***negreta i cursiva***
~~tallat~~
**negreta amb *cursiva* a dins**

Línia separadora

exemple.mdText de dalt

---

Text de baix

Escapar símbols

Una barra invertida davant d'un símbol el mostra tal qual.

exemple.md\*això no és cursiva\*
1\. no és una llista
\# no és un títol

Els símbols que més sovint cal escapar són \ ` * _ [ ] # + - . ! |.

Llistes amb punts i numerades

Per a punts pots fer servir -, * o + (tria'n un i sigues coherent). Per a numerades, 1., 2.…

exemple.md- Pomes
- Peres
  - Peres de Girona
- Taronges

1. Primer pas
2. Segon pas
3. Tercer pas

• Per fer una llista dins d'una altra, sagna l'element sota del pare. Amb - n'hi ha prou amb 2 espais; amb 1. cal alinear-lo amb el text, és a dir 3 espais.
• En una llista numerada només importa el primer número. 1. 1. 1. es veu com 1, 2, 3, i així no has de renumerar si afegeixes un pas.
• Deixa una línia en blanc abans de començar una llista.

Numeració tipus 1, 1.1, 1.2

Markdown no numera així de manera automàtica. En una llista numerada, el nivell de dins torna a començar per 1, i 1.1 Text no és una llista perquè després del 1. no hi ha un espai. La solució és una llista amb punts i els números escrits a mà, en negreta.

exemple.md- **1.** Xarxa
  - **1.1** Adreçament
    - **1.1.1** IPv4
    - **1.1.2** IPv6
  - **1.2** Encaminament
- **2.** Serveis

• Sagna 2 espais per nivell.
• El punt final només al nivell 1 (**1.**); a la resta no cal.
• Si afegeixes un apartat has de renumerar la resta tu.
• Per a un document llarg amb índex automàtic, millor títols amb el número escrit: ## 1. Xarxa i ### 1.1 Adreçament.

Llistes de tasques

exemple.md- [x] Escriure la guia
- [ ] Revisar els exemples

A GitHub, dins d'un issue o d'un pull request, les caselles es poden marcar amb un clic.

Enllaços

El text va entre claudàtors i l'adreça entre parèntesis, enganxats.

exemple.md[Documentació de GitHub](https://docs.github.com)
[Amb títol](https://exemple.cat "Surt en passar el ratolí")
[Guia d'instal·lació](docs/install.md)
[Anar a les preguntes](#preguntes-frequents)

• La 3a línia és un enllaç relatiu a un altre fitxer del mateix projecte. Funciona sense posar el domini.
• La 4a és una àncora cap a un títol del mateix document. L'àncora és el títol en minúscules i amb els espais canviats per guions: ## Preguntes freqüents dona #preguntes-freqüents.
• Si l'adreça té espais, escriu-los com %20 o canvia'ls per guions. Un espai sense codificar trenca l'enllaç.

Imatges

És un enllaç amb un ! al davant. El text entre claudàtors és la descripció (alt).

exemple.md![Logotip de la meva app](img/logo.png)

Cites

exemple.md> Això és una cita.
> Pot ocupar diverses línies.
>
> > I se'n poden niar d'altres.

Codi en línia

Entre accents greus. A teclat català és la tecla de la dreta de la P: prem-la i després espai.

exemple.mdExecuta `git status` al terminal.
Amb un accent greu a dins: `` a`b ``

Blocs de codi

Tres accents greus a dalt i tres a baix. Després dels primers, escriu el nom del llenguatge perquè es pinti amb colors.

exemple.md```python
def salutacio():
    print("Hola, món!")
```

def salutacio():
    print("Hola, món!")

Taules

exemple.md| Exercici | Dies | Estat   |
|:---------|:----:|--------:|
| Cames    | 2    | Fet     |
| Esquena  | 3    | Pendent |

• La fila de guions sota la capçalera és obligatòria. Sense ella no hi ha taula.
• Els dos punts d'aquesta fila marquen l'alineació: :--- esquerra, :---: centre, ---: dreta.
• Posa'n 3 guions per columna. GitHub n'accepta menys, però alguns editors no.
• No cal alinear les columnes visualment ni posar barres a les vores. Ho fem per llegir-ho millor.
• Dins d'una cel·la hi pots posar negreta, cursiva, codi i enllaços. Per escriure una barra literal, \|. Per fer dues línies, <br>.

Aquests són els detalls que et fan escriure un README net en lloc d'un que només funciona.

Codi dins d'una llista

Sagna el bloc fins a l'alçada del text de l'element i deixa una línia en blanc a dalt i a baix. És el patró de qualsevol guia d'instal·lació.

README.md1. Clona el repositori:

   ```bash
   git clone https://github.com/usuari/projecte.git
   ```

2. Entra a la carpeta.

Enllaços automàtics i de referència

Una adreça entre < > es converteix en enllaç sense text. Si repeteixes una adreça llarga, defineix-la una vegada al final del document i referencia-la.

exemple.md<https://exemple.cat>

Consulta la [guia][g] i la [documentació][docs].

[g]: https://exemple.cat/guia
[docs]: https://exemple.cat/docs

Imatge que és un enllaç

Una imatge dins d'un enllaç. És com es fan els distintius (badges) a dalt dels README.

exemple.md[![Estat de la build](https://exemple.cat/badge.svg)](https://exemple.cat/builds)

HTML dins de Markdown

Quan Markdown no arriba, hi pots escriure HTML directament. Els usos més habituals:

exemple.md<details>
<summary>Veure la solució</summary>

Aquí dins **sí** funciona Markdown.

</details>

Prem <kbd>Ctrl</kbd> + <kbd>C</kbd>.
H<sub>2</sub>O i x<sup>2</sup>.

Comentaris i notes a peu de pàgina

exemple.md<!-- Això no surt al resultat -->

Una afirmació que necessita una font.[^1]

[^1]: Aquí hi va la nota.

Les notes a peu de pàgina funcionen a GitHub i Obsidian, però no a tots els editors.

Altres formes equivalents

Les veuràs en documents d'altres persones. Fan el mateix que el que ja saps.

No hi ha un sol Markdown. La base és CommonMark, l'estàndard. GitHub Flavored Markdown (GFM) hi afegeix taules, tallat, tasques i enllaços automàtics. Cada eina hi afegeix coses pròpies, i d'aquí ve que un mateix fitxer es vegi diferent segons on l'obris.

Alertes

Cinc tipus: NOTE, TIP, IMPORTANT, WARNING i CAUTION.

README.md> [!NOTE]
> Informació útil per a qui llegeix.

> [!WARNING]
> Això pot esborrar dades.

Diagrames amb Mermaid

Un bloc de codi amb el llenguatge mermaid es dibuixa com a diagrama a GitHub.

README.md```mermaid
flowchart LR
  A[Escric el .md] --> B[Faig commit] --> C[GitHub el mostra]
```

Fórmules matemàtiques

exemple.mdEn línia: $E = mc^2$

En bloc:
$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

Front matter en YAML

Un bloc entre dues línies --- al principi del fitxer, amb metadades. Obsidian, Hugo, Jekyll i Docusaurus el fan servir per al títol, la data i les etiquetes. A GitHub es mostra com una taula. Aquí practiques el YAML de l'altra guia.

nota.md---
title: La meva guia
date: 2026-10-20
tags: [markdown, apunts]
---

# La meva guia

Només a GitHub

• @usuari menciona una persona i #123 enllaça amb l'issue o el pull request 123.
• :tada: es converteix en emoji. També pots enganxar l'emoji directament.

Què funciona on

Escriu els exercicis en un fitxer .md al VS Code, mira'n la vista prèvia i només després obre la solució.

Exercici 1: README d'un projecte

El projecte és un script de Bash que copia una carpeta a un disc extern. El README ha de tenir:

1. Un títol amb el nom backup-script i una cita d'una línia que el descrigui.
2. Una taula de característiques amb dues columnes: funció i estat.
3. Una instal·lació en dos passos numerats, cadascun amb el seu bloc de codi bash.
4. Un apartat d'ús amb una ordre en codi en línia.
5. Una llista de tasques pendents amb una casella marcada i dues sense marcar.
6. Una alerta de tipus avís que digui que l'script sobreescriu els fitxers de destí.

README.md# backup-script

> Script en Bash que copia una carpeta a un disc extern.

## Característiques

| Funció          | Estat     |
|:----------------|:----------|
| Còpia completa  | Fet       |
| Còpia parcial   | Pendent   |

## Instal·lació

1. Clona el repositori:

   ```bash
   git clone https://github.com/marti/backup-script.git
   ```

2. Dona permisos d'execució:

   ```bash
   chmod +x backup.sh
   ```

## Ús

Executa `./backup.sh origen destí`.

> [!WARNING]
> L'script sobreescriu els fitxers que ja existeixin al destí.

## Pendent

- [x] Còpia completa
- [ ] Còpia incremental
- [ ] Avís per correu en acabar

Exercici 2: troba els 5 errors

Aquest fragment té cinc errors de sintaxi. Corregeix-los sense mirar la solució.

trencat.md#Instal·lació

Executa `git status al terminal.

| Nom | Edat |
| Anna | 25 |

Text en **negreta*

[Web](https:// exemple.cat)

Full de trucs