Regras de Escrita de Elementos: Quando Usar Cada Bloco

Cada página no manual de SEO depende de uma distinção: um conteúdo tem um propósito, enquanto seu nível de cabeçalho e aparência visual são apenas apresentação. Estas regras de escrita de elementos transformam essa distinção em um contrato de produção. Siga-as antes de aplicar qualquer componente, converter um artigo entre sistemas de publicação ou alterar um elemento que já aparece em páginas publicadas.

Visão geral rápida

• Verifique a biblioteca de elementos por propósito antes do nome. Se o propósito de um elemento corresponde ao trabalho que uma seção realiza, esse elemento é obrigatório.
• Use Markdown simples somente após confirmar que nenhum elemento tipado representa o propósito da passagem. Texto livre é um fallback, não um padrão.
• Escreva o artigo completo como texto simples primeiro. Aplique os elementos em uma passada estrutural separada, de cima para baixo, para que composição e marcação não concorram pela atenção.
• Trate a diretiva Markdown como conteúdo canônico de autoria. Os renderizadores Hugo e WordPress mapeiam os mesmos campos e corpo para saída nativa da plataforma.
• Mantenha as páginas publicadas existentes no significado sob o qual foram revisadas. Uma mudança de definição que quebra cria uma nova versão e uma migração explícita; nunca reinterpreta silenciosamente conteúdo antigo.

A regra de precedência governante

A biblioteca deve ser verificada pelo que uma passagem faz, não pelo que o escritor casualmente a chamou. Nomes variam: um escritor pode intitular uma seção “O que é churn?”, outro “Churn explicado”, e um terceiro “Uma definição funcional”. O propósito delas é idêntico, então todas as três mapeiam para o mesmo elemento de definição.

Essa precedência existe porque texto livre e um elemento tipado podem parecer idênticos na tela enquanto se comportam completamente diferente downstream. Um cabeçalho estilizado seguido por um parágrafo pode assemelhar-se a uma caixa de definição no navegador, mas não carrega identidade de componente. Ele não pode produzir de forma confiável a saída estruturada da definição, expor seus campos a outro renderizador, reter sua semântica durante a migração ou ser encontrado por uma verificação de qualidade que pergunta se a página contém uma definição. O elemento tipado mapeia para um componente e uma forma de dados conhecida; texto livre visualmente similar mapeia para nada.

A regra é, portanto, estrita:

Antes de escrever ou aprovar qualquer cabeçalho ou bloco de conteúdo, identifique seu propósito. Se esse propósito corresponder a uma definição de elemento, use o elemento. Similaridade visual, um H2 existente ou a capacidade de expressar as mesmas palavras em um parágrafo não tornam o texto livre equivalente.

A precedência é semântica, não visual. Uma página ainda pode conter cabeçalhos comuns dentro ou ao redor de um elemento quando sua definição os permite, mas o cabeçalho nunca substitui o tipo do elemento.

Texto livre versus um elemento tipado

Use este caminho de decisão até que o diagrama compartilhado esteja disponível:

1. Declare o trabalho da passagem em um verbo. Exemplos incluem definir, alertar, resumir, comparar, provar, instruir ou convidar à ação. Isso impede que o texto do cabeçalho disfarce o propósito subjacente.
2. Pesquise na biblioteca por esse propósito e seus sinônimos. Um escritor procurando apenas pelo cabeçalho literal “O que é X?” pode perder um elemento de definição cuja página se chama “Caixa de definição”.
3. Use o elemento correspondente quando um existir. Não compare aparências nem pergunte se o Markdown poderia imitar o design; o comportamento registrado é o fator decisivo.
4. Use texto livre quando nenhum propósito corresponder. Isso é correto para explicação conectiva, argumento, análise, contexto narrativo e transições que pertencem ao fluxo principal do artigo e não exigem comportamento de componente distinto.
5. Registre uma lacuna repetida. Se o mesmo propósito não correspondido aparecer em várias páginas, proponha um elemento de biblioteca em vez de inventar uma diretiva avulsa ou tratamento CSS em um artigo.

Markdown simples é genuinamente correto quando as palavras formam o raciocínio contínuo do artigo e não precisam de um rótulo independente, contrato de dados, interação ou caminho de reuso. Por exemplo, dois parágrafos explicando por que uma recomendação segue da evidência anterior são prosa normal. Um conjunto compacto de conclusões no topo não é prosa normal apenas porque pode ser escrito como marcadores; ele tem o propósito reconhecido de um elemento de visão geral ou conclusões.

Confusões comuns que causam marcação incorreta

Estes casos são listados explicitamente porque passam facilmente por uma revisão visual. O erro torna-se visível apenas quando outro renderizador, validador, índice de busca ou consumidor de saída estruturada recebe a página.

A distinção entre principais conclusões e visão geral rápida é especialmente importante. Use conclusões quando os itens são descobertas que o leitor deve lembrar, o que significa que muitas vezes só podem ser escritas após o artigo existir. Use uma visão geral quando os itens orientam o leitor quanto ao escopo ou sequência antes da leitura. Escolha por esse trabalho editorial, mesmo que o tema atual faça ambos os componentes parecerem semelhantes.

Sintaxe de diretiva e atributos

A forma Markdown canônica usa uma diretiva de bloco nomeada. Atributos seguem o nome da diretiva entre chaves:

:::nome-do-elemento{chave=valor chave2="valor com espaços" .classe}
Corpo do conteúdo
:::

Atributos existem para carregar propriedades pequenas e estáveis que afetam o significado do elemento ou a apresentação suportada. Mantê-los legíveis por máquina impede que escritores escondam configuração em prosa. Use chave=valor para um valor sem espaços e chave2="valor com espaços" quando houver espaços. Um valor de atributo não entre aspas não pode conter espaços. Um ponto inicial adiciona uma classe suportada, como em .compact; não é um lugar para inventar estilização específica de página.

Chaves de atributo são em minúsculas e usam a grafia exata definida na página do elemento. Valores booleanos e enumerados também seguem o contrato dessa página. Não crie um atributo porque um renderizador por acaso o tolera: um atributo não declarado não tem garantia entre plataformas.

Os fechamentos ::: pertencem ao elemento externo. Mantenha-os em suas próprias linhas para que um analisador possa distinguir o corpo do próximo parágrafo. Exemplos de código que demonstram diretivas devem permanecer dentro de blocos de código delimitados, como fazem nesta página, para que o Hugo não os interprete como conteúdo.

Mapeamento padrão do corpo

A maioria dos elementos precisa de um título curto e um corpo mais longo. Exigir que autores repitam estes como atributos tornaria o texto longo difícil de editar e fácil de escapar incorretamente, então o corpo fornece o mapeamento padrão:

:::exemplo
## Um cabeçalho concreto

O resto do corpo pode conter parágrafos, listas, links e outros conteúdos permitidos pela definição do elemento.
:::

A menos que uma página de elemento substitua explicitamente a regra, o primeiro cabeçalho no corpo mapeia para title, e tudo após esse cabeçalho mapeia para content. O marcador de cabeçalho expressa hierarquia fonte para editores; o campo mapeado permite que cada plataforma renderize o nível de cabeçalho semântico apropriado no contexto.

Apenas o primeiro cabeçalho do corpo recebe este tratamento especial. Cabeçalhos posteriores permanecem parte de content. Se o corpo não tiver cabeçalho, title está ausente; isso é válido apenas quando a definição do elemento marca seu título como opcional. Se um elemento define slots nomeados ou um mapeamento diferente, sua própria página tem precedência sobre este padrão porque o renderizador deve saber exatamente onde cada fragmento pertence.

Itens aninhados

Alguns elementos contêm uma lista repetível cujas entradas precisam cada uma de atributos e um corpo, como passos com identificadores, cartões com rótulos ou itens de checklist com um estado inicial. Achatar essas entradas em uma lista Markdown faria com que seus campos individuais se perdessem, então itens aninhados usam uma diretiva de item explícita:

:::elemento-pai{variante=compacto}
::item{chave=valor}
### Título do primeiro item

A explicação do primeiro item.
::
::item{chave2="valor com espaços"}
### Título do segundo item

A explicação do segundo item.
::
:::

O contrato é ::item{chave=valor} … ::: dois dois-pontos abrem cada item, o nome no singular é item, e dois dois-pontos o fecham. O pai mantém seu fechamento de três dois-pontos. Essa diferença visual importa porque torna o aninhamento inequívoco sem depender de indentação, que é facilmente danificada por copiar-e-colar.

Cada item aplica o mesmo mapeamento padrão do corpo, a menos que a página do elemento pai diga o contrário: seu primeiro cabeçalho torna-se title desse item, e o restante torna-se seu content. Coloque atributos no item quando eles descrevem apenas aquele item; coloque-os no pai quando afetam a coleção como um todo.

Links, imagens e botões inline

Código fonte portável precisa de caminhos previsíveis. Uma URL relativa deve ser relativa à raiz do site, não ao arquivo Markdown atual, porque o mesmo fonte pode ser renderizado em uma profundidade diferente do sistema de arquivos no Hugo ou importado para o WordPress.

• Links de páginas internas usam barra inicial e final, como o link da biblioteca de elementos faz. Não use ../, omita a barra inicial nem codifique o domínio de produção para uma página interna.
• Links externos usam uma URL https:// completa. O esquema faz parte do destino e não deve ser inferido por um renderizador.
• Arquivos fonte de imagem ficam abaixo de cdn-assets/seo-playbook/, e seus caminhos públicos começam em /cdn-assets/seo-playbook/. Acrescente o grupo e nome de arquivo aprovados somente após o ativo existir.
• Texto alternativo descreve a informação transmitida por uma imagem, não seu nome de arquivo ou aparência decorativa. Uma imagem decorativa usa um texto alternativo vazio, mas a página do elemento relevante deve permitir explicitamente decoração.
• Uma chamada para ação inline usa :button[Rótulo visível]{href="/alvo/"}. O texto entre colchetes é o rótulo acessível e href segue as mesmas regras de caminho interno ou externo. Use um botão apenas para uma ação genuína seguinte, não para tornar um link de referência comum mais proeminente.

Uma imagem é conteúdo, não uma solução alternativa para layout não suportado. Se a imagem contém rótulos, números ou instruções essenciais, repita essa informação em texto acessível ou use um elemento estruturado que a exponha. Solicitações de captura de tela permanecem como comentários HTML até que o ativo nomeado exista; não são referências de imagem publicadas e devem definir screenshotsPending = true no front matter.

Front matter e elementos do corpo têm trabalhos diferentes

O front matter descreve o documento como documento. Diretivas do corpo descrevem blocos significativos dentro da experiência de leitura. Manter essas camadas separadas permite que páginas de listagem, esquemas, roteamento e ferramentas de publicação leiam metadados sem analisar prosa visível.

Elementos de metadados, portanto, vivem no front matter: título da página, descrição, palavras-chave, datas de publicação e atualização, informações canônicas ou de alias, propriedade, taxonomia, junções do manual e quaisquer coleções orientadas a esquema que o contrato da página coloca lá, como entradas de FAQ em páginas academy. Esses campos nunca são escritos como diretivas :::. Um bloco visível que repete alguns metadados não move o campo autoritativo para fora do front matter; ele recebe seu próprio elemento de corpo apenas quando tem um propósito separado voltado ao leitor.

Elementos de conteúdo vivem no corpo: definições, avisos, dicas, visões gerais, conclusões, checklists, comparações, blocos de evidência, exemplos, passos e chamadas para ação. Eles são diretivas porque sua localização na narrativa importa. Mover um aviso para o front matter o desconectaria da passagem que ele qualifica; esconder metadados em uma diretiva do corpo tornaria sistemas de nível de documento incapazes de encontrá-los de forma confiável.

Metadados são obrigatórios por padrão

Metadados conduzem rotas, pré-visualizações, descoberta, junções e saída estruturada antes que alguém leia o corpo. Um campo omitido pode, portanto, quebrar consumidores que nunca renderizam o artigo. Por essa razão, todo elemento de metadados é obrigatório a menos que sua página de elemento diga explicitamente que é opcional.

Obrigatório significa preenchido com um valor válido, não meramente presente como uma string vazia ou coleção vazia. Não infira opcionalidade da omissão de outra página e não adicione valores provisórios para satisfazer validação. Se um valor obrigatório ainda não é conhecido, a página não está pronta para publicação. Elementos do corpo seguem as regras de exigência do tipo de post relevante e das páginas de elemento, em vez deste padrão de metadados.

Escreva primeiro, aplique elementos depois

A seleção de elementos é uma tarefa de classificação, enquanto a redação é uma tarefa de raciocínio. Tentar realizar ambas frase por frase faz o escritor otimizar prematuramente para limites de componentes. O resultado usual são transições mais fracas, explicações rasas dimensionadas para uma caixa, cabeçalhos repetitivos criados para satisfazer marcação e diretivas escolhidas porque são convenientes em vez de porque seu propósito corresponde.

A produção, portanto, acontece em duas passadas distintas:

1. Escreva o artigo inteiro como texto simples. Complete o argumento, exemplos, qualificações, transições e conclusão. Nesta fase, cabeçalhos podem descrever a lógica do rascunho, mas não definem o tipo final do elemento.
2. Aplique elementos em uma passada separada de cima para baixo. Para cada cabeçalho e bloco, declare seu propósito, verifique a biblioteca, envolva as seções correspondentes, adicione atributos declarados e confirme o mapeamento e aninhamento do corpo.

A separação melhora ambas as saídas. A prosa desenvolve-se de acordo com as perguntas do leitor em vez dos tamanhos de caixa do tema atual, enquanto a passada de marcação pode comparar blocos semelhantes consistentemente em todo o documento. Também torna omissões visíveis: um escritor pode ver que o artigo contém um aviso ou definição antes de decidir como codificá-lo.

Após a passada estrutural, leia a página uma vez sem olhar para os nomes das diretivas. Elementos devem suportar um artigo coerente, não transformá-lo em uma pilha de widgets desconectados. Em seguida, inspecione o código fonte uma vez sem julgar a prosa, verificando delimitadores, atributos, itens aninhados, caminhos e metadados obrigatórios.

O contrato de três notações

Um elemento é definido uma vez por seu propósito, campos canônicos, valores permitidos, mapeamento do corpo, comportamento de acessibilidade, comportamento de saída estruturada e versão. Essa definição é a fonte da verdade. As três notações de plataforma são adaptadores para ela, não três designs de componente independentes.

As formas representativas explicam o mapeamento; a página individual do elemento publica seu nome e campos exatos suportados. Autores trabalham na notação exigida por seu fluxo de trabalho de publicação, mas não renomeiam campos, adicionam significados específicos de plataforma nem imitam manualmente o HTML de outro renderizador.

O proprietário do elemento mantém a definição canônica e decide se uma mudança proposta é compatível ou versionada. Mantenedores Hugo e WordPress possuem seus adaptadores e os testam contra fixtures compartilhadas: o mesmo título, conteúdo, atributos, itens, links e expectativas de acessibilidade devem sobreviver a todos os três caminhos. Proprietários editoriais verificam propósito e exemplos. Nenhum mantenedor de plataforma pode redefinir o significado editorial localmente; se uma plataforma não pode expressar o contrato, isso é um defeito do adaptador ou uma mudança de contrato proposta.

Este modelo permite que a apresentação difira onde as plataformas exigem, mantendo a semântica estável. Hugo pode renderizar HTML do lado do servidor e WordPress pode armazenar um comentário de bloco, mas um aviso permanece um aviso, um item de checklist permanece um item, e os mesmos campos obrigatórios permanecem disponíveis downstream.

Versionamento de elementos publicados

Conteúdo publicado foi revisado contra o significado do elemento que existia no momento da publicação. Mudar esse significado silenciosamente pode alterar avisos, dados estruturados, acessibilidade ou importações sem que um editor toque na página. O versionamento protege essa aprovação editorial.

Use a seguinte política de mudanças:

• Mudança compatível de renderizador: Um refinamento visual, melhoria de desempenho ou correção de bug que preserva propósito, campos, valores aceitos, mapeamento do corpo e significado da saída pode ser enviado dentro da versão atual. Páginas existentes o recebem através do renderizador.
• Mudança aditiva compatível: Um novo atributo opcional pode juntar-se à versão atual apenas quando sua ausência preserva a saída existente e todo adaptador pode ignorá-lo ou suportá-lo com segurança. A definição e os testes de plataforma mudam juntos.
• Mudança que quebra: Um campo renomeado ou removido, um novo campo obrigatório, mapeamento do corpo alterado, propósito alterado, valor padrão alterado com efeito semântico ou estrutura de item aninhado incompatível cria uma nova versão principal do elemento.
• Obsolescência: A versão antiga permanece renderizável para páginas publicadas. Sua página de elemento identifica a substituição e o caminho de migração; novas páginas usam a versão atual.
• Migração: Uma migração de conteúdo é explícita, com escopo definido, pré-visualizada em Markdown, Hugo e WordPress, e validada editorialmente antes da publicação. Registre quais páginas mudaram e por quê. Não faça um renderizador adivinhar como o código fonte antigo deve ser reinterpretado.

Quando nenhuma versão está escrita no código fonte, o elemento usa a versão base definida quando este contrato foi adotado. Essa linha de base implícita deve permanecer estável. Novas versões principais identificam-se usando o mecanismo de versão declarado na página do elemento; não reaproveitam a sintaxe sem versão.

Reverter também é importante. Mantenha o renderizador anterior e a representação fonte disponíveis até que as páginas migradas passem por verificações estruturais, visuais, de acessibilidade e de saída estruturada. Se uma migração falhar, restaure o mapeamento da versão anterior em vez de achatar o elemento em texto livre, o que descartaria a semântica que o versionamento pretende proteger.

Lista de verificação de revisão de produção

Use esta revisão final após a passada de prosa e a passada de elementos:

• O propósito de cada bloco que não é prosa pode ser declarado em um verbo?
• A biblioteca foi pesquisada por esse propósito e sinônimos próximos?
• Cada propósito correspondente usa seu elemento tipado, mesmo quando um H2 e parágrafo pareceriam semelhantes?
• Toda passagem de texto livre restante faz parte da explicação contínua, análise, narrativa ou transição do artigo?
• Os atributos seguem {chave=valor chave2="valor com espaços" .classe}, com espaços entre aspas e apenas chaves declaradas usadas?
• O primeiro cabeçalho do corpo mapeia para title e o restante para content, a menos que a página do elemento declare outro mapeamento?
• Filhos repetíveis usam ::item{chave=valor} … ::, com atributos do pai e do item colocados no nível correto?
• Links internos são relativos à raiz com barras inicial e final, links externos são absolutos e caminhos de imagem estão dentro da raiz de imagem aprovada?
• Campos de metadados estão no front matter, nunca em diretivas do corpo, e todos os valores de metadados obrigatórios estão completos?
• Os mesmos campos canônicos podem ser mapeados sem perda para Markdown, Hugo e WordPress?
• Alguma mudança de definição preserva páginas antigas ou introduz uma versão explícita e migração?

Esta página é um pré-requisito para cada página de elemento individual. Cada definição de elemento deve linkar de volta a estas regras base e, em seguida, documentar apenas suas exceções específicas de propósito: atributos suportados, campos obrigatórios, substituições de mapeamento do corpo ou de itens, aninhamento permitido, nomes exatos de plataforma e histórico de versões. Se uma página de elemento for omissa, os padrões desta página se aplicam.