Markdown + Astro = ❤️

Markdown é uma ótima invenção que nos permite escrever menos marcações. Ele também lida com questões tipográficas, como a conversão de apóstrofos retos (') em aspas de abertura ou fechamento (' ou ') para nós.

Embora o Astro tenha suporte integrado para Markdown por meio de arquivos .md, eu diria que sua experiência com Markdown pode ser aprimorada de duas maneiras:

1. MDX
2. Componente de redução

Eu abordei isso em detalhes em Astro prático: sistemas de conteúdo .

Vamos nos concentrar no MDX hoje.

MDX

MDX é um superconjunto de Markdown. Permite usar componentes em Markdown e JSX simples, além de todos os outros recursos do Markdown.

Para Astro, você também pode usar componentes de qualquer framework frontend que você tenha instalado. Então você pode fazer algo como:

---
# Frontmatter...
---

import AstroComp from '@/components/AstroComp.astro'
import SvelteComp from '@/components/AstroComp.astro'

<AstroComp> ... </AstroComp>
<SvelteComp> ... </SvelteComp>

Pode ser um ótimo substituto para coisas com muito conteúdo porque permite escrever marcações como as seguintes.

<div class="card">
  ### Card Title

  Content goes here

  - List
  - Of
  - Items

  Second paragraph
</div>

O Astro converterá o MDX no seguinte HTML:

<div class="card">
  <h2>Card Title</h2>

  <p>Content goes here </p>

  <ul>
    <li> List </li>
    <li> Of </li>
    <li> Items </li>
  </ul>

  <p>Second paragraph</p>
</div>

Observe o que fiz acima:

• Usei ---
  # Frontmatter...
  ---

  import AstroComp from '@/components/AstroComp.astro'
  import SvelteComp from '@/components/AstroComp.astro'

  <AstroComp> ... </AstroComp>
<SvelteComp> ... </SvelteComp> em vez de uma tag <div class="card">
### Card Title

  Content goes here

  - List
  - Of
  - Items

  Second paragraph
</div> completa.

• usei <div class="card">
  <h2>Card Title</h2>

  <p>Content goes here </p>

  <ul>
  <li> List </li>
  <li> Of </li>
  <li> Items </li>
  </ul>

  <p>Second paragraph</p>
</div> em vez de ## e h2 para denotar listas.

• Não precisei de nenhuma tag de parágrafo.

Escrever tudo diretamente em HTML teria sido um pouco chato.

Instalando MDX

O pessoal da Astro construiu uma integração para MDX, então é fácil adicioná-lo ao seu projeto. Basta seguir estas instruções .

Três maneiras principais de usar MDX

Esses métodos também funcionam com arquivos Markdown padrão.

1. Importe-o diretamente para um arquivo Astro
2. Através de coleções de conteúdo
3. Através de um layout

Importe diretamente

A primeira maneira é simplesmente importar seu arquivo MDX e usá-lo diretamente como um componente.

---
import MDXComp from '../components/MDXComp.mdx'
---

<MDXComp />

Por causa disso, o MDX pode funcionar como um parcial.

Por meio de coleções de conteúdo

Primeiro, você alimenta seu MDX em uma coleção de conteúdo. Observe que você deve adicionar o padrão - ao seu glob aqui.

Importe-o diretamente

A primeira maneira é simplesmente importar seu arquivo MDX e usá-lo diretamente como um componente.

// src/content.config.js
import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/blog" }),
});

export const collections = { blog };

Em seguida, você recupera o arquivo MDX da coleção de conteúdo.

###PRE_f33ce2843c97fd99a34306251fev2926###

Ao fazer isso, você pode passar componentes para os arquivos MDX para não precisar importá-los individualmente em cada arquivo.

Por exemplo, aqui está como eu passaria o componente <ul> de Splendid Labz em cada um dos meus arquivos MDX.

---
import { getEntry, render } from 'astro:content'
const { slug } = Astro.props
const post = await getEntry('blog', slug)
const { Content } = await render(post)
---

<Content />

Em meus arquivos MDX, agora posso usar <li> sem importá-lo.

---
import { Image } from '@splendidlabz/astro'
// ...
const { Content } = await render(post)
const components = { Image }
---

<Content {components} />

Use um layout

Finalmente, você pode adicionar um frontmatter de layout no arquivo MDX.

<Image src="..." alt="..." />

Este frontmatter ---
import MDXComp from '../components/MDXComp.mdx'
---

<MDXComp /> deve apontar para um arquivo Astro.

Nesse arquivo:

• Você pode extrair propriedades do frontmatter de mdx.
• O conteúdo MDX pode ser renderizado com // src/content.config.js
  import { defineCollection } from 'astro:content';
  import { glob } from 'astro/loaders';

  const blog = defineCollection({
  loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/blog" }),
  });

  export const collections = { blog };.

---
title: Blog Post Title
layout: @/layouts/MDX.astro
---

Advertências

Falha na formatação e linting

ESLint e Prettier não formatam bem arquivos MDX, então você acabará recuando manualmente a maior parte de sua marcação.

Isso é adequado para pequenas quantidades de marcação. Mas se você tiver muitos deles… então o componente Markdown será uma escolha muito melhor.

Mais sobre isso em outra postagem futura.

Problemas de RSS

A integração Astro RSS não suporta arquivos MDX prontos para uso.

Felizmente, isso pode ser resolvido facilmente com contêineres Astro. Mostrarei como fazer isso em Practical Astro .

Indo além

Venho construindo com o Astro há mais de 3 anos e continuei enfrentando os mesmos pontos de atrito em sites com muito conteúdo: páginas de blog, páginas de tags, paginação e estruturas de pastas que ficam confusas com o tempo.

Então eu construí Practical Astro: Content Systems , 7 soluções prontas para uso para fluxos de trabalho de conteúdo Astro (MDX é apenas uma delas). Você obtém o código e o pensamento por trás dele.

Se você deseja um fluxo de trabalho de conteúdo mais limpo e tranquilo, dê uma olhada.

Eu também escrevo sobre Astro Patterns e Usando Tailwind + CSS juntos em meu blog . Venha e diga oi!

Markdown + Astro = ❤️ originalmente escrito à mão e publicado com amor em CSS-Tricks . Você realmente deveria receber o boletim informativo também.