## Contexto

Um tema de documentação precisa de componentes dentro da prosa — callouts,
código em separadores, campos de parâmetros, árvores. Havia duas sintaxes
disponíveis. O **MDX** compila o Markdown num módulo de componente e deixa uma
página importar e escrever JSX; o **MDC** é a sintaxe de componentes em bloco e
em linha que o Content já traz e já analisa.

As páginas também são lidas por algo que não é um navegador. O tema publica o
Markdown de origem de cada página para os modelos, por isso a sintaxe em que as
páginas estão escritas é aquilo que um modelo recebe.

## Decisão

Os componentes em Markdown são **MDC**. Os componentes que uma página pode
chamar vivem num diretório de conteúdo dedicado, onde um ficheiro de quem a
consome com o mesmo nome substitui o da camada.

## Consequências

Não é preciso instalar nem configurar nada para uma página chamar um componente,
e uma página continua a ser um ficheiro Markdown em vez de se tornar um módulo.

Um bloco MDC sobrevive a ser entregue a um modelo como texto: lê-se como uma
chamada de componente com argumentos nomeados. JSX compilado não sobreviveria.

A sintaxe é do Content, por isso as suas capacidades e os seus limites também
são do Content. Tudo o que uma página queira e o MDC não consiga exprimir tem de
ser resolvido como um componente e não como uma expressão na página — o que é
uma restrição para quem escreve e, num site de documentação, uma restrição
desejável.

Os nomes dos componentes no diretório de conteúdo fazem parte da superfície
pública, já que uma página escrita para um deles é um ficheiro de quem a
consome.

## Alternativas consideradas

**MDX.** Mais expressivo, e cada bocado dessa expressividade é JavaScript numa
página de documentação. Precisaria ainda de um módulo e de um caminho de
compilação que o Content não tem, para acabar por ter páginas que são piores de
entregar a um modelo.