Pular para o conteúdo
Navegar na documentação
Nesta página

Escrever conteúdo MDX

Um documento .mdx combina front matter YAML, GitHub Flavored Markdown e componentes Blade anônimos.

---
title: Status do serviço
sitemap:
  priority: 0.5
  changefreq: weekly
---
# Status

| Serviço | Estado |
|---|---|
| Site | Ativo |

<x-ui.alert type="success">Operação normal.</x-ui.alert>

Tabelas, task lists, tachado, links, listas e fenced code blocks são convertidos para HTML. Títulos de nível dois e três recebem âncoras únicas automaticamente. Componentes funcionam em bloco ou inline e podem ser aninhados.

Syntax highlighting com Shiki

Com feature.shiki: true, fences com uma linguagem reconhecida recebem syntax highlighting no HTML gerado durante o build. O tema padrão é gruvbox-dark-medium; altere shiki.theme para escolher outro tema incluído no Shiki:

feature:
  shiki: true
shiki:
  theme: github-dark

Use o identificador da linguagem no fence. Por exemplo, um trecho PHP de uma página ou componente:

```php
$post = ['title' => 'Olá, BlogBlade'];

echo $post['title'];
```

Configurações também usam o lexer correspondente:

```yaml
feature:
  shiki: true
shiki:
  theme: gruvbox-dark-medium
```

Para anotações, logs ou formatos ainda sem lexer, omita a linguagem e preserve um bloco de código sem highlighting:

```
resultado: processamento concluído
```

O resultado preserva <pre><code> e contém os tokens com estilos inline do tema. Não há JavaScript de highlighting, CDN ou dependência Shiki no frontend. Um fence sem linguagem, ou com uma linguagem desconhecida, continua como bloco de código CommonMark normal para que o build não falhe. Shiki roda somente em build/build-fast; dev mantém a renderização CommonMark sem highlighting.

Diagramas Mermaid

Com feature.mermaid: true, um fenced code block cujo primeiro identificador é mermaid vira SVG durante o build. A mesma sintaxe funciona no artigo e na variante de apresentação:

```mermaid
flowchart TD
    A[Autor] --> B[Build]
    B --> C[SVG inline]
```

O recurso não usa CDN nem deixa JavaScript Mermaid na saída publicada. Use accTitle e accDescr na definição quando o diagrama precisar de uma descrição acessível. Se a definição for inválida, o build falha com a origem do MDX e o número do diagrama para facilitar a correção.

As opções globais ficam em mermaid no config.yaml. Use themeVariables para variáveis do tema e options para configurações específicas do tipo de diagrama. Customizações de aparência podem ficar em Content/assets/css/mermaid.css, que é carregado automaticamente pelos layouts:

mermaid:
  theme: neutral
  background: transparent
  themeVariables:
    primaryColor: "#f5f3ff"
  options:
    flowchart:
      curve: basis

.mermaid-diagram .node rect {
    fill: #f5f3ff !important;
}

Criar uma apresentação

Para publicar o mesmo conteúdo como artigo e como apresentação, opte pelo tipo presentation no front matter. O artigo continua disponível na rota normal; a versão Reveal.js é publicada em slides.html dentro da mesma pasta.

---
title: Minha palestra
type: presentation
sitemap:
  priority: 0.6
  changefreq: monthly
---
# Abertura

Conteúdo da primeira página.

<!-- slide -->

## Próximo tópico

Conteúdo da segunda página.

O marcador <!-- slide --> precisa ficar sozinho em uma linha e separa os slides. Sem marcador, o conteúdo inteiro vira um único slide. A leitura vertical do artigo não usa Reveal.js; a apresentação é uma segunda renderização opt-in em slides.html. No just dev, a URL é resolvida pelo servidor dinâmico; no just build + just serve, ela é um arquivo estático em dist/. O recurso pode ser desligado em feature.revealjs; se houver conteúdo presentation com o recurso desligado, o build falha para evitar uma publicação incompleta. Em um site com site.basePath, o prefixo também aparece no link da apresentação.

O conteúdo Markdown dentro de um componente não é processado novamente. Use HTML ou outro componente quando o slot precisar de marcação estruturada.

Componentes e atributos

O único Blade executado pelo parser MDX é uma tag de componente anônimo cujo nome começa por x-. A tag pode ser autocontida, inline, em bloco ou aninhada. Atributos literais HTML são encaminhados ao componente; valores dinâmicos, expressões PHP, @bind e diretivas de atributo não são avaliados em MDX.

<x-ui.badge featured="true">Destaque</x-ui.badge>

<x-ui.card title="Publicado" class="mt-4">
    Conteúdo literal do slot.
    <x-ui.button variant="secondary" type="button">Abrir</x-ui.button>
</x-ui.card>

O componente recebe os nomes declarados por @props; atributos restantes ficam em $attributes e só aparecem no HTML se o componente os imprimir. Por exemplo, class="mt-4" é combinado por $attributes->merge() nos componentes que oferecem esse contrato.

$slot é o único slot que pode ser composto de forma confiável em MDX. A sintaxe de slot nomeado (<x-slot:actions>...</x-slot:actions>) não faz parte da gramática MDX: ela é tratada como HTML/texto, não preenche $actions. Slots nomeados funcionam em páginas .blade.php; em MDX, use um componente dedicado ou aninhe componentes no slot default. @props, $slot, $attributes e x-slot só fazem sentido dentro do arquivo Blade do componente, não como construções executáveis no corpo MDX.

O que é preservado como texto

{{ $user->name }}
{!! $html !!}
@@if ($published) publicado @@endif
@@foreach ($items as $item) {{ $item }} @@endforeach

O resultado contém literalmente {{ $user->name }}, {!! $html !!}, @if e @foreach; nada é avaliado. Para dados ou condicionais, mova a composição para uma página .blade.php ou para um componente Blade e passe apenas atributos literais pela página MDX.

Markdown fora do componente é processado normalmente:

**Este texto vira `<strong>`.**

<x-ui.alert type="info">**Este texto permanece com os asteriscos.**</x-ui.alert>

Escolha a primeira forma quando precisar de Markdown; use a segunda somente para conteúdo que o componente renderiza como HTML ou como outro componente. Esta limitação evita uma segunda passagem ambígua pelo parser.

HTML comum permitido pelo GFM é mantido, mas script, style, iframe, textarea, title e elementos do blocklist são escapados. A saída é HTML estático: não use echos literais como mecanismo de segurança. Escape dados no componente e prefira atributos e componentes com progressive enhancement (por exemplo, um link ou botão HTML que continue utilizável sem JavaScript).

Expressões {{ ... }}, blocos {!! ... !!} e diretivas como @if ou @foreach são escapados como texto literal em MDX. Para executar essas construções, crie uma página .blade.php.

HTML bruto comum é preservado, mas tags perigosas do blocklist GFM são escapadas. Consulte Páginas e roteamento para os formatos suportados e Componentes para os componentes fornecidos pelo projeto atual.