MDX

Introducció

MDX et permet utilitzar TSX en el teu contingut Markdown.

Pots importar components, com gràfics interactius o alertes, i incrustar-los dins del teu contingut. Això fa que escriure contingut de format llarg amb components sigui fantàstic. 🚀

De manera més pràctica, MDX es pot explicar com un format que combina markdown amb TSX i es veu així:

# Hello, world!

<div className="note">
  > Some notable things in a block quote!
</div>

El títol i la cita són markdown, mentre que aquestes etiquetes similars a HTML són TSX. El markdown sovint se sent més natural d’escriure que HTML o TSX per a coses comunes com èmfasi o títols. TSX és una extensió de TypeScript que sembla HTML, però fa que sigui convenient utilitzar components (coses reutilitzables).

Aquest exemple utilitza className en el <div>. Això és perquè va ser escrit per a React i React espera les classes d’aquesta manera.

Algunes altres característiques de TypeScript també són compatibles amb MDX: expressions entre claus ({1 + 1}) i ESM (import i export).

Sinatxi

La sintaxi MDX combina markdown amb TSX. Això ens dona quelcom similar a la programació literal. També ens dona una barreja peculiar de dos llenguatges: markdown és sensible als espais en blanc i tolerant (el que escrius pot no funcionar exactament però no fallarà) mentre que TypeScript és insensible als espais en blanc i intolerant (falla amb errors de sintaxi).

Markdown

El markdown sovint se sent més natural d’escriure que HTML o TSX per a coses comunes com èmfasi o títols. Markdown típicament sembla més el que es pretén i és més concís. En lloc del següent HTML:

<blockquote>
  <p>A blockquote with <em>some</em> emphasis.</p>
</blockquote>

Pots escriure l’equivalent en markdown (o MDX) així:

> A blockquote with *some* emphasis.

MDX suporta markdown estàndard per defecte (CommonMark):

# Heading (rank 1)
## Heading 2
### 3
#### 4
##### 5
###### 6

> Block quote

* Unordered
* List

1. Ordered
2. List

A paragraph, introducing a thematic break:

---

a [link](https://example.com), an ![image](./image.png), some *emphasis*,
something **strong**, and finally a little `code()`.

Les característiques no estàndard de markdown (com GFM, frontmatter, matemàtiques, ressaltat de sintaxi) es poden habilitar amb plugins (vegeu Ús de plugins).

Algunes característiques de markdown no funcionen en MDX:

• El codi indentat no funciona en MDX:

    console.log(1) // this is a paragraph in MDX!

El motiu és que pots indentar els teus components adequadament:

<main>
    <article>
        # Hello!
    </article>
</main>

• Els enllaços automàtics no funcionen en MDX. La raó és que poden ser indistingibles del JSX (per exemple: <svg:rect>). Si vols enllaços, utilitza enllaços complets: [text descriptiu](https://i-lenllaç-aqui.com)

• La sintaxi HTML no funciona en MDX, ja que és reemplaçada per TSX (<img> a <img />)

• En lloc de comentaris HTML, pots utilitzar comentaris TypeScript entre claus: {/* comentari! */}

• Els símbols menor que (<) i clau esquerra ({) sense escapar s’han d’escapar: \< o \{ (o utilitzar expressions: {'<'}, {'{'})

Més informació sobre com MDX difereix de markdown està documentada aquí.

TSX

TSX és una extensió de TypeScript que sembla HTML però fa que sigui convenient utilitzar components (coses reutilitzables). TSX típicament es combina amb un framework frontend com React. Aquests frameworks afegeixen suport per a components, que et permeten canviar coses repetitives com el següent marcatge:

<h2>Hello, Venus!</h2>
<h2>Hello, Mars!</h2>

…a TSX (o MDX) així:

<Welcome name="Venus" />
<Welcome name="Mars" />

TSX és bo per a components. Fa que les coses repetitives siguin més clares i permet la separació de preocupacions. MDX suporta la sintaxi TSX. El següent s’assembla molt a HTML:

<h1>Heading!</h1>

<abbr title="HyperText Markup Language">HTML</abbr> is a lovely language.

<section>
    And here is *markdown* in **TSX**!
</section>

Però com s’ha mencionat anteriorment, també pots utilitzar components. Nota que els components han d’estar definits. Pots importar-los, definir-los localment o passar-los més tard:

<MyComponent id="123" />

You can also use objects with components, such as the `thisOne` component on
the `myComponents` object: <myComponents.thisOne />

<Component
    open
    x={1}
    label={'this is a string, *not* markdown!'}
    icon={<Icon />}
/>

Hi ha alguns casos límit on MDX difereix de JSX.

Expressions

MDX també suporta expressions TypeScript dins de claus:

Two 🍰 is: {Math.PI * 2}

Les expressions poden contenir programes TypeScript complets sempre que (estiguin envoltats en) una expressió que s’avaluï a quelcom que es pugui renderitzar. Pots utilitzar una IIFE així:

{(function () {
  const guess = Math.random()

  if (guess > 0.66) {
    return <span style={{color: 'tomato'}}>Look at us.</span>
  }

  if (guess > 0.33) {
    return <span style={{color: 'violet'}}>Who would have guessed?!</span>
  }

  return <span style={{color: 'goldenrod'}}>Not me.</span>
})()}

Les expressions poden estar buides o contenir només un comentari:

{/* A comment! */}

ESM

MDX també suporta declaracions d’importació i exportació de TypeScript. Aquestes característiques ESM es poden utilitzar dins de MDX per definir coses:

import {External} from './some/place.js'

export const Local = properties => <span style={{color: 'red'}} {...properties} />

An <External>external</External> component and a <Local>local one</Local>.

ESM també es pot utilitzar per a no-components (dades):

import {Chart} from './chart.js'
import population from './population.js'
export const pi = 3.14

<Chart data={population} label={'Something with ' + pi} />

Interleaving

Pots utilitzar “inlines” de markdown, però no “blocs” dins de TSX si el text i les etiquetes estan a la mateixa línia:

<div># this is not a heading but *this* is emphasis</div>

El text i les etiquetes en una línia no produeixen blocs així que tampoc produeixen <p>s. En línies separades, sí que ho fan:

<div>
  This is a `p`.
</div>

Diferenciem utilitzant aquesta regla (mateixa línia o no). No basat en la semàntica dels elements en HTML. Així que pots construir HTML incorrecte (que no hauries):

<h1 className="main">
  Don’t do this: it’s a `p` in an `h1`
</h1>

<h1 className="main">Do this: an `h1` with `code`</h1>

No és possible embolicar “blocs” si el text i les etiquetes estan a la mateixa línia, però les etiquetes d’obertura i tancament corresponents estan en diferents blocs (així que això no és vàlid!):

Welcome! <a href="about.html">

This is home of...

# The Falcons!</a>

Per analitzar markdown, primer s’ha de dividir en “blocs”. Així que en aquest cas dos paràgrafs i un títol. Deixant una etiqueta a d’obertura en el primer paràgraf i una etiqueta a de tancament en el títol. Això causa un error, ja que està ben anidat.

Using

Using MDX