Markdown e MDX

Este guia ensina a sintaxe básica que você vai usar para escrever qualquer conteúdo no site: notícias, publicações, páginas de atividades, perfis da equipe, etc.

O que é Markdown?

Markdown é uma forma simples de formatar texto usando caracteres comuns (como #, *, -). Você escreve em texto puro e o site transforma automaticamente em HTML bonito.

Por exemplo, em vez de escrever código HTML assim:

<h2>Meu título</h2>
<p>Texto em <strong>negrito</strong> e <em>itálico</em>.</p>

Você escreve assim em Markdown:

## Meu título

Texto em **negrito** e _itálico_.

O resultado visual é o mesmo — mas o Markdown é muito mais fácil de ler e escrever.

Diferença entre .md e .mdx

Na prática, use .mdx sempre. Ele aceita tudo que o .md aceita e ainda permite usar componentes visuais extras. Todos os guias do site usam .mdx.

O que é YAML frontmatter?

Todo arquivo de conteúdo começa com um bloco chamado frontmatter. Ele fica entre três hífens (---) e define informações sobre a página (título, data, autor, etc.).

---
title: 'Minha página'
date: 2026-04-15
lang: 'pt'
---

Regras do frontmatter

1. Sempre começa e termina com --- (três hífens, sozinhos na linha).
2. Cada campo segue o formato campo: valor.
3. Textos devem ficar entre aspas simples: title: 'Meu título'.
4. Datas ficam sem aspas: date: 2026-04-15.
5. Listas usam colchetes: tags: ['Tag 1', 'Tag 2'].
6. Booleanos (verdadeiro/falso) ficam sem aspas: featured: true.

Exemplo anotado

---
title: 'Workshop de Análise de Dados'   # Texto entre aspas
date: 2026-04-15                         # Data sem aspas (formato YYYY-MM-DD)
authors: ['Ana Silva', 'Bruno Costa']    # Lista entre colchetes
tags: ['Dados', 'R']                     # Outra lista
lang: 'pt'                               # Idioma: pt, en ou es
featured: false                          # true ou false, sem aspas
---

Sintaxe Markdown

Títulos

Use # para criar títulos. Quanto mais #, menor o nível do título.

# Título nível 1 (grande)
## Título nível 2
### Título nível 3
#### Título nível 4

Parágrafos

Basta escrever o texto normalmente. Para criar um novo parágrafo, deixe uma linha em branco entre eles.

Este é o primeiro parágrafo.

Este é o segundo parágrafo.

Se você não deixar a linha em branco, o texto continua no mesmo parágrafo:

Esta linha
e esta linha
aparecem juntas no mesmo parágrafo.

Negrito e itálico

**texto em negrito**
_texto em itálico_
**_negrito e itálico juntos_**

Resultado: texto em negrito, texto em itálico, negrito e itálico juntos.

Listas

Lista com marcadores (não ordenada):

- Primeiro item
- Segundo item
  - Sub-item (use 2 espaços antes do `-`)
  - Outro sub-item
- Terceiro item

Resultado:

• Primeiro item
• Segundo item
  • Sub-item
  • Outro sub-item
• Terceiro item

Lista numerada (ordenada):

1. Primeiro passo
2. Segundo passo
3. Terceiro passo

Resultado:

1. Primeiro passo
2. Segundo passo
3. Terceiro passo

Links

[Texto do link](https://exemplo.com)

Resultado: Texto do link

Para links internos do site, use caminhos relativos:

[Veja o guia de Notícias](./noticias)

Imagens

![Descrição da imagem](/imagens/noticias/minha-foto.jpg)

A descrição entre [ ] é o texto alternativo (importante para acessibilidade). O caminho entre ( ) aponta para o arquivo da imagem.

Código

Código inline (dentro do texto): use crases simples.

Use o comando `npm run build` para compilar.

Resultado: Use o comando npm run build para compilar.

Bloco de código: use três crases, opcionalmente com a linguagem.

```javascript
const nome = 'CPPS';
console.log(nome);
```

Resultado:

const nome = 'CPPS';
console.log(nome);

Linguagens comuns: javascript, python, bash, yaml, markdown, html, css.

Tabelas

| Coluna 1    | Coluna 2     | Coluna 3       |
|-------------|--------------|----------------|
| Dado A      | Dado B       | Dado C         |
| Outro dado  | Mais um      | Último         |

Resultado:

Citações (blockquote)

> Esta é uma citação.
> Pode ter várias linhas.

Resultado:

Esta é uma citação. Pode ter várias linhas.

Linha horizontal

---

Cria uma linha divisória (como a que separa as seções deste guia). Cuidado: no topo do arquivo, --- delimita o frontmatter. No meio do texto, vira uma linha horizontal.

Componentes MDX

Componentes são blocos visuais especiais que só funcionam em arquivos .mdx. Eles usam a mesma sintaxe de tags HTML, mas com nomes específicos.

Para ver todos os componentes disponíveis com exemplos visuais, consulte o guia Escrever.

Resumo rápido:

Exemplo de componente Notice

<Notice type="warning">
  Atenção: este campo é obrigatório!
</Notice>

Resultado:

Estrutura completa de um arquivo

Juntando tudo — frontmatter, Markdown e componentes — um arquivo .mdx típico fica assim:

---
title: 'Workshop de Dados Abertos'
date: 2026-04-20
resumo: 'Oficina prática sobre uso de dados abertos governamentais.'
image: '/imagens/noticias/2026-04-20-workshop-dados.jpg'
lang: 'pt'
tags: ['Dados', 'Oficina']
author: 'Equipe CPPS'
featured: false
---

O Centro de Estudos de Políticas Públicas promoveu uma oficina sobre
dados abertos no dia 20 de abril.

## O que foi discutido

Os participantes aprenderam a:

- Acessar portais de dados abertos
- Filtrar e baixar datasets
- Realizar análises básicas em **R** e **Python**

## Materiais

| Material | Link |
|----------|------|
| Slides | [Baixar PDF](/arquivos/workshop-slides.pdf) |
| Dataset | [Portal de dados](https://dados.gov.br) |

> "Foi uma experiência muito produtiva para todos os envolvidos."
> — Participante da oficina

<Notice type="tip">
  O próximo workshop será em maio. Fique atento às novidades!
</Notice>

Resumo rápido