Escrever páginas de documentação MDX que sigam as regras do site e compilem sem erros

## Entender como o site de documentação é organizado antes de escrever Trate o repositório como um aplicativo de documentação orientado por esquemas, não como uma coleção solta de arquivos Markdown. Identifique o gerador do site, o tema da documentação, o framework de componentes, o gerenciador de pacotes, a versão do ambiente de execução e o destino da implantação. Instale as dependências com o comando bloqueado e reproduzível do repositório. Mantenha as versões do ambiente de execução e do gerenciador de pacotes alinhadas aos metadados do repositório. Confirme o branch principal de contribuição, em vez de presumir um nome convencional. Diferencie páginas voltadas para usuários, parciais reutilizáveis, registros de alterações, dados do glossário, metadados de produtos e outras coleções estruturadas. Mantenha componentes personalizados, esquemas de conteúdo, plugins de Markdown, plugins de realce de código, ícones, recursos, estilos e rotas dinâmicas em suas camadas designadas. Trate arquivos públicos estáticos de forma diferente das imagens processadas pelo gerador do site. Use o módulo central de exportação de componentes como a interface pública de importação para MDX. Mantenha os esquemas das coleções como autoridade para os campos e tipos de valores aceitos. Trate os diretórios gerados de habilidades ou referências como produtos da compilação. Não edite diretórios gerados nem confirme conteúdo gerado ignorado. Leia as instruções aninhadas antes de alterar um bot especializado de revisão ou um worker de implantação. Use referências específicas do repositório para estilo, componentes e procedimentos como orientação normativa. Não permita que hábitos genéricos de Markdown se sobreponham às regras de MDX e de esquemas do site. ## Colocar as páginas nas pastas certas e nomear bem os arquivos Coloque as páginas de documentação voltadas para usuários no diretório do produto ou assunto. Coloque os trechos reutilizáveis na coleção de parciais. Coloque as entradas do registro de alterações no subdiretório correspondente ao produto ou assunto. Coloque os termos do glossário e outros metadados estruturados nas coleções controladas por seus esquemas. Exija uma página de índice em cada pasta de conteúdo navegável quando o site esperar uma. Use nomes de arquivos em minúsculas com as palavras separadas por hífens. Limite os diretórios de conteúdo às extensões de texto e dados permitidas explicitamente. Os tipos normalmente permitidos são MDX, JSON, YAML e texto simples. Deixe a validação de extensões impor a lista de permissões, em vez de ocultar arquivos não compatíveis. Não coloque imagens nem binários arbitrários dentro de diretórios de conteúdo verificados por esquemas. Coloque imagens processáveis na árvore de recursos dedicada à otimização. Coloque arquivos realmente estáticos na árvore pública somente quando precisarem ser servidos sem alterações. Mantenha os nomes dos diretórios alinhados aos metadados de produtos existentes. Não crie um registro de alterações nem um subdiretório de coleção para uma chave de produto desconhecida. Preserve os limites estabelecidos das coleções, em vez de inventar um local de conteúdo paralelo. Ao mover uma página, atualize os links de entrada, os metadados de navegação, os redirecionamentos e as referências relacionadas a parciais. ## Preencher os dados de página (frontmatter) que o site exige Forneça a cada página de documentação um bloco de frontmatter que satisfaça o esquema de sua coleção. Forneça um título de página conciso. Forneça uma descrição de pesquisa sempre que o tipo de conteúdo selecionado a exigir. Escolha o tipo de página na enumeração permitida pelo repositório. Os tipos comuns incluem `concept`, `configuration`, `example`, `FAQ`, `getting started`, `how-to`, `integration`, `implementation`, `overview`, `reference`, `release notes`, `solution`, `troubleshooting` e `tutorial`. Use tipos especializados como `design guide`, `learning unit`, `navigation`, `reference architecture` e `video` quando o esquema os fornecer. Use a ordem da barra lateral somente quando for necessária uma ordenação explícita. Use um rótulo da barra lateral somente quando o texto de navegação precisar ser diferente do título da página. Faça referência a produtos ou assuntos por meio das chaves de metadados existentes. Use a enumeração de dificuldade documentada para conteúdo de tutoriais. Registre as datas de revisão no formato obrigatório ano-mês-dia. Não invente campos de esquema nem valores de enumeração. Mantenha válidos o recuo do YAML e a estrutura das listas. Gere novamente os tipos das coleções de conteúdo depois de alterar definições de coleções ou esquemas. Valide os arquivos de dados com seus esquemas, em vez de depender de inspeção visual. Mantenha os metadados da página sincronizados quando a finalidade, o produto, o título ou o estado de revisão da página mudar. ## Escrever páginas MDX que compilem sem erros de sintaxe Siga o guia normativo de redação e formatação do repositório. Trate MDX como Markdown acrescido de uma linguagem de componentes incorporada com análise mais rigorosa. Use escape ou formatação de código nos caracteres de chaves e de sinais de maior e menor quando fizerem parte do texto. Lembre-se de que o MDX interpreta esses caracteres como expressões ou componentes mesmo dentro do texto. Importe todos os componentes usados pela página. Coloque as importações imediatamente após o frontmatter e antes do conteúdo da página. Use somente identificadores de linguagem compatíveis com o realce de sintaxe. Escreva a saída genérica do terminal com o identificador de texto simples do repositório. Use identificadores de linguagem em minúsculas nos blocos de código. Use caminhos absolutos a partir da raiz para links internos do site. Não use URLs completas de produção para destinos internos. Não use links relativos de páginas que não sejam compatíveis. Mantenha os níveis dos títulos em sequência e não pule nenhum nível. Omita os símbolos do prompt do shell nos comandos que podem ser copiados. Escreva etapas concisas cuja ação, localização e resultado esperado não sejam ambíguos. Mantenha as explicações reutilizáveis em parciais quando várias páginas precisarem do mesmo texto mantido. Verifique os exemplos de código com a API documentada e o comportamento atual do produto. ## Usar os componentes e imagens do site e mudar redirecionamentos só quando preciso Importe componentes MDX somente pelo módulo central de exportação de componentes do repositório. Consulte a documentação dos componentes para conhecer as propriedades obrigatórias e as restrições de uso. Não copie a implementação interna de um componente para o conteúdo quando houver um componente público compatível. Coloque o código de novos componentes no diretório de componentes designado. Use o prefixo obrigatório de elementos personalizados e a convenção de nomes kebab-case. Mantenha cada componente em um diretório com o nome desse componente. Use nomes de classes em PascalCase com o sufixo obrigatório. Não renomeie elementos legados isentos apenas para aplicar uma regra de prefixo mais recente. Mantenha as imagens de origem no diretório de recursos otimizados do produto ou assunto correspondente. Verifique os caminhos das imagens por meio de uma compilação local completa. Modifique os redirecionamentos somente quando uma mudança de página ou migração de URL exigir. Termine os caminhos de origem dos redirecionamentos com a barra obrigatória ou com um sufixo aceito de arquivo ou curinga. Não coloque fragmentos nas URLs de origem dos redirecionamentos. Detecte ciclos de redirecionamento antes da revisão. Execute o validador dedicado de redirecionamentos sempre que o arquivo de redirecionamentos mudar. Mantenha as alterações de componentes, imagens, links e redirecionamentos dentro do escopo pretendido da página. ## Passar nas verificações locais e de CI antes de dar uma página como pronta Execute a verificação de esquemas e tipos após cada alteração de conteúdo. Use uma compilação local completa para validar a análise de MDX, os caminhos das imagens e os links internos. Habilite a verificação de links internos durante a compilação local de validação completa. Não execute em uma integração contínua restrita uma compilação completa que sabidamente excederá o tempo limite. Na integração contínua, execute verificações de tipos, lint e formatação como o conjunto seguro reduzido. Para alterações de código, execute também as suítes de testes completas do repositório. Formate todos os arquivos editados antes de confirmá-los. Execute a verificação de formatação do repositório após as correções automáticas. Execute a validação de redirecionamentos somente quando a configuração deles mudar. Execute a sincronização dos tipos de coleção após alterações em esquemas ou coleções. Alinhe a sequência local de validação completa ao pipeline da integração contínua quando for viável. Espere que a integração contínua verifique extensões de arquivos, tipos, lint, formatação, compilação e links, redirecionamentos e testes. Trate os avisos do analisador de estilo como evidência para a revisão, mesmo quando não forem falhas obrigatórias. Não informe que uma página está pronta enquanto faltar um portão de validação diretamente relevante. Diferencie uma limitação do ambiente de integração contínua de uma falha real do conteúdo. Execute novamente as verificações diretamente afetadas após cada edição corretiva. ## Dar a cada entrada do diretório um ID gerado pela ferramenta do site e mantê-lo Forneça a cada arquivo de dados de entrada de diretório um identificador único e estável na posição obrigatória da primeira linha. Use o comprimento exato do identificador e o conjunto de caracteres com menos possibilidade de confusão do repositório. Em um esquema de seis caracteres, verifique se cada valor gerado tem exatamente seis caracteres. Exclua caracteres visualmente ambíguos quando o esquema exigir. Gere identificadores aleatoriamente, em vez de derivá-los de nomes. Não crie manualmente, adivinhe nem copie um identificador. Use a ferramenta de identificadores do repositório para verificar a coleção completa. Use o modo de correção da ferramenta para identificadores ausentes, malformados ou duplicados. Mantenha um identificador válido existente quando o nome exibido ou o nome do arquivo mudar. Altere um identificador existente somente para corrigir um erro de validação confirmado. Use de forma consistente a única extensão YAML obrigatória. Trate a geração de identificadores como uma operação automatizada, não como uma decisão editorial. Verifique a exclusividade em toda a coleção de diretórios. Mantenha a geração de identificadores e a validação de esquemas na integração contínua. Revise o diff da ferramenta antes de confirmar as alterações geradas. Não ajuste manualmente um identificador gerado depois que a ferramenta for concluída com êxito. ## Seguir os guias de cada tarefa e as regras de commit ao enviar mudanças Use o roteador de contribuições do repositório antes de redigir, editar, revisar exemplos, adicionar registros de alterações ou preparar uma pull request. Siga a referência específica da tarefa selecionada por esse roteador. Leia as instruções locais de um bot especialista antes de alterar seu código, o roteamento do fluxo de trabalho, o estado ou a implantação. Mantenha os links simbólicos específicos das ferramentas apontando para a configuração compartilhada e confirmada dos agentes. Carregue uma habilidade do repositório somente quando a descrição dela corresponder à tarefa. Use o guia de estilo normativo para decisões de redação e formatação. Use o catálogo de componentes para consultar propriedades, exemplos e padrões obrigatórios. Use o guia de procedimentos para instruções passo a passo. Execute testes em cada espaço de trabalho de execução afetado por uma alteração de código. Mantenha separados os testes do worker, do ambiente de execução do servidor e do gerador do site. Escreva as confirmações no formato aceito pelo repositório, prefixado pelo produto ou tipo. Torne as descrições das confirmações específicas para a correção visível ao usuário ou para a correção técnica. Não inclua formatação, conteúdo gerado nem alterações de produto não relacionados. Aprove somente quando conteúdo, esquemas, importações, recursos, links, redirecionamentos, testes e convenções de contribuição estiverem de acordo.