Markdown e MDX
Markdown é comumente usado para criar conteúdo com muito texto, como postagens de blog e documentação. Astro inclui suporte nativo para arquivos Markdown padrão que também incluem o frontmatter YAML para definir metadados customizados como um título, descrição e etiquetas.
Com a integração @astrojs/mdx
instalada, Astro também suporta arquivos MDX (.mdx
) que trazem alguns recursos adicionais como suporte para expressões JavaScript e componentes direto do seu conteúdo Markdown.
Use um ou ambos os tipos de arquivo para escrever seu conteúdo Markdown!
Páginas Markdown e MDX
Seção intitulada Páginas Markdown e MDXColeções de conteúdo
Seção intitulada Coleções de conteúdoVocê pode gerenciar seus arquivos Markdown e MDX no Astro em um diretório especial src/content/
. Coleções de conteúdo te ajudam a organizar seu conteúdo, validar seu frontmatter e a providenciar segurança de tipos do TypeScript automaticamente enquanto trabalha no seu conteúdo.
Directorysrc/content/
Directorynewsletter/
- semana-1.md
- semana-2.md
Directoryautores/
- grace-hopper.md
- alan-turing.md
Veja mais sobre como utilizar coleções de conteúdo no Astro.
Roteamento baseado em arquivos
Seção intitulada Roteamento baseado em arquivosAstro trata qualquer arquivo .md
(ou extensão alternativa suportada) ou .mdx
dentro do diretório /src/pages/
como uma página.
Colocar um arquivo nesse diretório, ou em qualquer subdiretório, criará automaticamente uma rota de página usando o nome do caminho do arquivo.
📚 Leia mais sobre o roteamento baseado em arquivos do Astro ou opções para criar rotas dinâmicas.
Funcionalidades do Markdown
Seção intitulada Funcionalidades do MarkdownAstro providencia algumas funcionalidades extras integradas ao Markdown, disponíveis ao se utilizar arquivos Markdown ou MDX.
Frontmatter layout
Seção intitulada Frontmatter layoutAstro fornece páginas Markdown e MDX com a propriedade frontmatter especial layout
, que pode especificar o caminho relativo (ou atalho) para um componente de layout Astro.
Propriedades específicas são estão disponíveis ao componente de layout através de Astro.props
. Por exemplo, você pode acessar propriedades do frontmatter através de Astro.props.frontmatter
:
Você também pode estilizar seu Markdown no seu componente de layout.
📚 Aprenda mais sobre Layouts Markdown.
IDs de Títulos
Seção intitulada IDs de TítulosUsar títulos no Markdown e MDX irá automaticamente te dar links de âncora para que você possa direcionar a certas seções da sua página.
Escapando caracteres especiais
Seção intitulada Escapando caracteres especiaisCertos caracteres tem um significado especial no Markdown e MDX. Você pode precisar usar uma sintaxe diferente se quiser mostrá-los. Para fazer isso, você pode utilizar entidades HTML para esses caracteres no lugar.
Por exemplo, para prevenir <
de ser interpretado como o começo de um elemento HTML, escreva <
. Ou, para prevenir {
de ser interpretado como o começo de uma expressão do JavaScript no MDX, escreva {
.
Funcionalidades únicas do MDX
Seção intitulada Funcionalidades únicas do MDXAdicionar a integração MDX do Astro aprimora sua experiência de autoria com Markdown com variáveis JSX, expressões e componentes.
Ela também adiciona funcionalidades extras ao MDX padrão, incluindo suporte para frontmatter estilo Markdown no MDX. Isso te permite utilizar a maioria das funcionalidades integradas para Markdown do Astro como a propriedade frontmatter layout
.
Arquivos .mdx
devem ser escritos na sintaxe do MDX ao invés da sintaxe semelhante ao HTML do Astro.
Usando Variáveis Exportadas no MDX
Seção intitulada Usando Variáveis Exportadas no MDXMDX suporta o uso de declarações export
para adicionar variáveis ao seu conteúdo MDX. Estas variáveis são acessíveis tanto no próprio template quanto como propriedades nomeadas ao importar o arquivo em outro lugar.
Por exemplo, você pode exportar um campo titulo
de uma página MDX ou componente para usar como um título com {expressões JSX}
:
Usando Variáveis Frontmatter no MDX
Seção intitulada Usando Variáveis Frontmatter no MDXA integração MDX do Astro inclui suporte para utilizar frontmatter no MDX por padrão. Adicione propriedades frontmatter assim como você faria em arquivos Markdown, e essas variáveis são acessíveis para uso dentro do template, em seu componente layout
, e como propriedades nomeadas ao importar o arquivo em outro lugar.
Usando Componentes no MDX
Seção intitulada Usando Componentes no MDXApós instalar a integração MDX, você pode importar e utilizar tanto componentes Astro quanto componentes de frameworks de UI em arquivos MDX (.mdx
) assim como você os usaria em qualquer outro componente Astro..
Não se esqueça de adicionar uma client:diretiva
em seus componentes de frameworks de UI, se necessário!
Veja mais exemplos da utilização de declarações de importação e exportação na documentação do MDX.
Definindo Componentes Customizados a elementos HTML
Seção intitulada Definindo Componentes Customizados a elementos HTMLCom MDX, você pode mapear a sintaxe Markdown a componentes customizados ao invés de seus elementos HTML padrões. Isso te permite escrever sintaxe padrão do Markdown enquanto aplica a estilização especial de componentes aos elementos selecionados.
Importe seu componente customizado em seu arquivo .mdx
, então exporte um objeto components
que mapeia o elemento padrão do HTML ao seu elemento customizado:
Visite o site do MDX para uma lista completa de elementos HTML que podem ser sobrescritos como componentes customizados.
Importando Markdown
Seção intitulada Importando MarkdownVocê pode importar arquivos Markdown e MDX diretamente em seus arquivos Astro. Isso te dá acesso ao seu conteúdo Markdown, assim como a outras propriedades como valores do frontmatter que podem ser utilizados em expressões estilo JSX do Astro.
Você pode importar uma página específica com import
ou múltiplas páginas com Astro.glob()
.
Quando você importa arquivos Markdown e MDX em um componente Astro, você recebe um objeto contendo suas propriedades exportadas.
Em arquivos MDX, você pode acessar propriedades tanto do frontmatter quanto de declarações de export
:
Opcionalmente, você pode fornecer um tipo para a variável frontmatter
usando um generic do TypeScript:
Propriedades Exportadas
Seção intitulada Propriedades ExportadasVeja as propriedades exportadas a um componente de layout Astro ao se utilizar o especial frontmatter layout do Astro.
As propriedades a seguir são disponibilizadas a um componente .astro
ao utilizar uma declaração de import
ou Astro.glob()
:
file
- O caminho absoluto do arquivo (e.x./home/usuario/projetos/.../arquivo.md
).url
- Se for uma página, a URL da página (e.x./pt-br/guides/markdown-content
).frontmatter
- Contém quaisquer dados especificados no frontmatter YAML do arquivo.getHeadings
- Uma função assíncrona que retorna uma array com todos os títulos (ou seja, elementosh1 -> h6
) no arquivo. Aslug
de cada título corresponde ao ID gerado para certo título e pode ser utilizado para links de âncora. Esta lista segue o tipo:{ depth: number; slug: string; text: string }[]
.Content
- Um componente que retorna os conteúdos do arquivo completamente renderizados.- (Apenas Markdown)
rawContent()
- Uma função que retorna o documento Markdown bruto como uma string. - (Apenas Markdown)
compiledContent()
- Uma função que retorna o documento Markdown compilado como uma string de HTML. Note que isso não inclui layouts configurados no seu frontmatter! Apenas o documento Markdown em si será retornado como HTML. - (Apenas MDX) - Arquivos MDX também pode exportar dados com uma declaração de
export
.
O Componente Content
Seção intitulada O Componente ContentImporte Content
para renderizar um componente que retorna todo o conteúdo renderizado de um arquivo Markdown ou MDX:
Exemplo: Roteamento dinâmico de páginas
Seção intitulada Exemplo: Roteamento dinâmico de páginasAo invés de colocar seus arquivos Markdown/MDX no diretório src/pages/
para criar rotas, você pode gerar páginas dinamicamente.
Para acessar seu conteúdo Markdown, passe o componente <Content/>
através das props
da página Astro. Você pode retirar o componente de Astro.props
e renderizá-lo no template da sua página.
Exportações únicas do MDX
Seção intitulada Exportações únicas do MDXArquivos MDX também podem exportar dados com uma declaração de export
.
Por exemplo, você pode exportar um campo titulo
de uma página MDX ou componente.
Esse titulo
será acessível a partir das declarações de import
e Astro.glob():
Componentes customizados com MDX importado
Seção intitulada Componentes customizados com MDX importadoAo renderizar conteúdo MDX importado, componentes customizados podem ser passados a partir da prop components
.
Componentes customizados definidos e exportados em um arquivo MDX precisam ser importados e passados novamente ao componente <Content />
a partir da propriedade components
.
Configurando Markdown e MDX
Seção intitulada Configurando Markdown e MDXO suporte para Markdown no Astro é fornecido pelo remark, uma poderosa ferramenta de processamento e parsing com um ecossistema ativo. Outros parsers de Markdown como Pandoc e markdown-it não são suportados atualmente.
Astro aplica os plugins GitHub-flavored Markdown e SmartyPants por padrão. Ele trás algumas coisas legais como gerar links clicáveis a partir de texto e formatação para citações e travessões.
Você pode personalizar como o remark faz parse do seu Markdown em astro.config.mjs
. Veja a lista completa de opções de configuração do Markdown.
Plugins do Markdown
Seção intitulada Plugins do MarkdownAstro dá suporte a plugins remark e rehype de terceiros para Markdown e MDX. Esses plugins te permitem estender seu Markdown com novas capacidades, como gerar um índice automaticamente, aplicar rótulos acessíveis à emojis e mais.
Nós o encorajamos a explorar o awesome-remark e awesome-rehype para achar mais plugins populares! Veja o README de cada plugin para instruções de instalação.
Este exemplo aplica os plugins remark-toc e rehype-accessible-emojis para ambos arquivos Markdown quanto MDX:
Note que por padrão, remarkToc
exige um título “ToC” ou “Table of Contents” (não diferencia maiúsculas de minúsculas) na página para mostrar a tabela de conteúdo.
IDs de Títulos e plugins
Seção intitulada IDs de Títulos e pluginsAstro injeta um atributo id
a todos os elementos de título (<h1>
ao <h6>
) em arquivos Markdown e MDX e fornece o utilitário getHeadings()
para pegar esses IDs em propriedades exportadas do Markdown.
Você pode customizar os IDs dos títulos adicionando um plugin do rehype que injeta atributos id
(e.x. rehype-slug
). Seus IDs customizados, ao invés dos padrões do Astro, serão refletidos no HTML resultante e nos itens retornados pelo getHeadings()
.
Por padrão, Astro injeta atributos id
depois que seus plugins do rehype foram executados. Se um dos seus plugins customizados do rehype precisam acessar os IDs injetados pelo Astro, você pode importar e utilizar o plugin rehypeHeadingIds
do Astro diretamente. Certifique-se de adicionar rehypeHeadingIds
antes de quaisquer plugins que podem depender dele:
Customizando um plugin
Seção intitulada Customizando um pluginPara customizar um plugin, adicione um objeto de opções depois dele envolvidos em um array.
O exemplo abaixo adiciona a opção do título ao plugin remarkToc
para alterar onde a tabela de conteúdo é colocada e a opção behavior
ao plugin rehype-autolink-headings
para adicionar a tag de link após o texto do título.
Modificando frontmatter programaticamente
Seção intitulada Modificando frontmatter programaticamenteSe você está usando coleções de conteúdo, por favor veja “Modificando Frontmatter com Remark”.
Você pode adicionar propriedades de frontmatter a todos os seus arquivos Markdown e MDX utilizando um plugin do remark ou rehype.
-
Adicione uma
propriedadeCustomizada
na propriedadedata.astro.frontmatter
a partir do argumentofile
do seu plugin:Adicionado em:astro@2.0.0
data.astro.frontmatter
contém todas as propriedades de um dado documento Markdown ou MDX. Isso te permite modificar propriedades existentes do frontmatter ou computar novas propriedades a partir do frontmatter existente. -
Aplique o plugin a configuração do
markdown
ou da integraçãomdx
:ou
Agora, todo arquivo Markdown ou MDX terá a propriedadeCustomizada
em seu frontmatter, a fazendo disponibilizando quando importar seu Markdown e a partir da propriedade Astro.props.frontmatter
em seus layouts.
Estendendo a configuração do Markdown a partir do MDX
Seção intitulada Estendendo a configuração do Markdown a partir do MDXA integração MDX do Astro irá estender a configuração Markdown existente do seu projeto por padrão. Para sobrescrever opções individuais, você pode especificar o seu equivalente na sua configuração do MDX.
O exemplo abaixo desabilita o Markdown estilo GitHub e aplica um diferente conjunto de plugins do remark para arquivos MDX:
Para evitar estender sua configuração do Markdown a partir do MDX, defina a opção extendMarkdownConfig
(habilitado por padrão) para false
:
Syntax Highlighting
Seção intitulada Syntax HighlightingAstro vem com suporte nativo para Shiki e Prism. Isso fornece syntax highlighting para:
- todas as code fences (```) usadas em um arquivo Markdown ou MDX.
- conteúdo dentro do componente
<Code />
nativo (oferecido por Shiki). - conteúdo dentro do componente
<Prism />
(oferecido por Prism).
Shiki é ativado por padrão, pré-configurado com o tema github-dark
. A saída compilada será limitada a style
s inline sem classes CSS de fora, folhas de estilo ou JS no lado do cliente.
Configuração do Shiki
Seção intitulada Configuração do ShikiShiki é o nosso syntax highlighter padrão. Você pode configurar todas as opções no objeto shikiConfig
assim:
Adicionando o seu próprio tema
Seção intitulada Adicionando o seu próprio temaAo invés de utilizar um dos temas pré-definidos do Shiki, você pode importar um tema customizado de um arquivo local.
Nós também sugerimos ler a documentação de temas do próprio Shiki para explorar mais sobre temas, alternância entre tema claro e escuro ou estilização por meio de variáveis CSS.
Mude o Modo de Syntax Highlighting Padrão
Seção intitulada Mude o Modo de Syntax Highlighting PadrãoSe você quiser mudar para o 'prism'
por padrão, ou desabilitar syntax highlighting por inteiro, você pode usar o objeto de configuração markdown.syntaxHighlighting
:
Configuração do Prism
Seção intitulada Configuração do PrismSe você optar por usar o Prism, o Astro irá aplicar as classes CSS do Prism no lugar. Note que você precisa trazer sua própria folha de estilos CSS para o syntax highlighting aparecer!
- Escolha uma folha de estilos pré-feita disponível nos Temas do Prism.
- Adicione essa folha de estilos ao diretório
public/
do seu projeto. - Carregue-o na
<head>
da sua página em um componente de layout a partir de uma tag<link>
. (Veja o guia de uso básico do Prism.)
Você também pode visitar a lista de linguagens suportadas pelo Prism para opções e como utilizar.
Buscando Markdown Remoto
Seção intitulada Buscando Markdown RemotoAstro foi primariamente projetado para arquivos Markdown locais que poderiam ser salvos dentro do diretório do seu projeto. Porém, pode haver certos casos em que você precisa buscar Markdown de uma fonte remota. Por exemplo, você pode precisar buscar e renderizar Markdown de uma API remota quando faz a build do seu site (ou quando um usuário faz uma requisição ao seu website, quando estiver utilizando SSR).
Astro não inclui suporte integrado para Markdown remoto! Para buscar Markdown remoto e renderizá-lo como HTML, você precisará instalar e configurar seu próprio parser Markdown do npm. Ele não irá herdar nenhuma das opções nativas de Markdown e MDX do Astro que você configurou. Certifique-se de que você entende estas limitações antes de implementar isso no seu projeto.
Learn