Pular para o conteúdo principal
Interface Atlas
5 min de leitura
Guia

MDX, Coleções de Conteúdo e Conteúdo-como-Arquitetura

Por que jogar arquivos Markdown em uma pasta não cria um sistema de publicação e como construir um que seja escalável.

Publicado
Por Interface Atlas Team

Conteúdo

O modo de falha mais comum ao adotar MDX ou Markdown em um framework JavaScript é tratá-lo como um processador de texto glorificado.

As equipes configuram um parser, jogam cinquenta arquivos .mdx em uma pasta /content e assumem que têm um sistema de publicação. Seis meses depois, eles têm uma pilha de posts sem tipagem. O frontmatter é inconsistente. As páginas de guia usam um layout diferente dos posts do blog, mas apenas porque um autor lembrou de importar o componente correto. Reorganizar a documentação requer uma pesquisa regex em todo o repositório.

Quando o seu produto é material de leitura, o seu modelo de conteúdo é a sua arquitetura.

A Tese do Conteúdo-como-Arquitetura

Em uma publicação baseada em arquivos como o Interface Atlas, você deve parar de ver a pasta src/content/ como um balde de armazenamento. Ela é um banco de dados.

Se é um banco de dados, precisa de um esquema (schema). Precisa de relacionamentos. Precisa de restrições. No Astro, impomos essa arquitetura usando Coleções de Conteúdo.

O Repositório como um Sistema de Publicação

graph TD
    subgraph A Camada de Banco de Dados
        C1[Coleção de Guias] -->|Valida via Zod| S1(Esquema do Guia)
        C2[Coleção do Glossário] -->|Valida via Zod| S2(Esquema do Glossário)
    end
    
    subgraph A Camada de Gráfico
        S1 -->|topicKeys| T[Hubs de Tópicos]
        S1 -->|glossaryKeys| C2
    end
    
    subgraph A Camada de Apresentação
        T --> R1[Rota Astro de Tópico]
        C1 --> R2[Rota Astro de Guia]
        C2 --> R3[Rota Astro de Glossário]
    end

Passando do Markdown para Coleções de Conteúdo

A Pilha Sem Tipagem (O Modo de Falha)

Antes das Coleções de Conteúdo, os frameworks carregavam arquivos markdown via importações glob. Você recebia qualquer frontmatter que o autor digitasse. Se um autor digitasse diffculty: hard em vez de difficulty: Advanced, a compilação (build) passaria, mas a página descartaria silenciosamente o selo de dificuldade. A lógica de conteúdo ficava escondida dentro de componentes de interface frágeis tentando analisar dados corrompidos.

A Coleção Tipada (A Solução)

As Coleções de Conteúdo do Astro consertam isso introduzindo um limite estrito entre conteúdo e renderização.

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

export const guides = defineCollection({
  loader: glob({ pattern: "**/*.mdx", base: "./src/content/guides" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    topicKeys: z.array(z.string()), // Impõe a relação do gráfico
    difficulty: z.enum(["Foundation", "Intermediate", "Advanced"]), // Evita erros de digitação
  }),
});

Este código ensina uma consequência arquitetônica: Erros de conteúdo agora são erros de compilação. Se um autor esquecer o array topicKeys, o build do Astro falha. O site não pode ser implantado em um estado quebrado.

Frontmatter é o Esquema Relacional

Depois de ter coleções tipadas, o Frontmatter deixa de ser apenas um lugar para colocar o título. Ele se torna o esquema relacional que constrói seu gráfico de conteúdo.

No Interface Atlas, não codificamos “Guias Relacionados” no final dos arquivos MDX. Usamos chaves de frontmatter:

---
title: "Arquitetura da Informação"
topicKeys: ["architecture", "seo"]
glossaryKeys: ["taxonomy"]
relatedGuideKeys: ["what-frontend-architecture-really-is"]
---

Como isso é fortemente tipado, a camada de roteamento pode gerar automaticamente os links relacionados, os chips de hub de tópico e os tooltips de glossário.

O Fluxo de Trabalho Editorial Baseado em Git

Quando o repositório é o CMS, o fluxo de trabalho do Git é o fluxo de trabalho editorial.

  1. Rascunho: Um autor cria uma branch e escreve um arquivo MDX.
  2. Revisão: O Pull Request se torna a revisão editorial. Os revisores podem comentar na prosa da mesma forma que comentam no código.
  3. Validação: CI/CD roda o build do Astro. O esquema valida o frontmatter e o MDX valida a sintaxe do componente.
  4. Publicação: O merge para a branch main dispara um deploy estático para a edge.

Esse fluxo de trabalho falha quando as equipes tentam forçar editores não técnicos a usar o GitHub diretamente sem uma ferramenta como o Decap CMS, ou quando os arquivos MDX ficam tão poluídos com JSX complexo que os autores não conseguem mais ler o texto.

Quando o MDX Não é Suficiente

O MDX é um meio híbrido. Ele permite que você incorpore componentes interativos complexos diretamente em textos longos. Mas você deve saber quando parar.

Se um arquivo MDX contém 40 linhas de prosa e 300 linhas de gerenciamento complexo de estado React, você cruzou um limite. O conteúdo agora é subserviente à lógica do aplicativo.

A Regra: Mantenha os arquivos MDX focados na leitura. Se um widget interativo requer estado local complexo, abstraia-o em um componente Island e passe-lhe props simples a partir do arquivo MDX.

Guias e Termos Relacionados

Explore os sistemas de suporte: