Usando o linter de conteúdo

Sobre o linter de conteúdo do GitHub Docs

Nosso linter de conteúdo impõe regras de guia de estilo em nosso conteúdo Markdown.

O linter usa markdownlint como estrutura para executar verificações, relatar falhas e corrigir automaticamente o conteúdo, quando possível. Essa estrutura executa regras específicas de forma flexível, fornece mensagens de erro descritivas e corrige erros. O linter de conteúdo do GitHub Docs usa várias regras markdownlint existentes e regras personalizadas adicionais para marcar o conteúdo de Markdown em nossos diretórios de content e data. Nossas regras personalizadas implementam verificações que ainda não estão disponíveis na estrutura markdownlint ou são específicas do conteúdo do GitHub Docs. As regras verificam a sintaxe de Markdown e Liquid.

Executar o linter de conteúdo do GitHub Docs

O linter de conteúdo do GitHub Docs será executado automaticamente na pré-commit, mas você também poderá executá-lo manualmente.

Executar automaticamente o linter na pré-commit

Quando você estiver gravando conteúdo localmente e confirmando arquivos usando a linha de comando, esses arquivos preparados serão automaticamente lintados pelo linter de conteúdo. Tanto os avisos quanto os erros são relatados, mas somente os erros impedirão a conclusão do commit.

Se for relatado algum erro, o commit não será concluído. Você precisará corrigir os erros relatados, adicionar novamente os arquivos alterados e confirmar as alterações novamente. Todos os erros relatados devem ser corrigidos para evitar a introdução de erros no conteúdo que violem o guia de estilo do GitHub Docs. Se algum aviso for relatado, você poderá optar por corrigi-lo ou não.

Quando você está escrevendo conteúdo localmente, há várias regras que podem ser corrigidas automaticamente usando a linha de comando. Se quiser corrigir automaticamente os erros que podem ser corrigidos, confira Corrigir automaticamente erros que podem ser corrigidos.

Se estiver editando um arquivo na interface do usuário do GitHub, você não poderá corrigir erros automaticamente nem executar o linter em um commit, mas receberá uma falha de CI se o conteúdo violar alguma regra com uma gravidade de error.

Executar o linter manualmente

Executar o linter em arquivos preparados e alterados

Use o comando a seguir para executar o linter localmente nos arquivos preparados e alterados. Ele produzirá falhas de gravidade warning e error.

npm run lint-content

Executar o linter em arquivos preparados e alterados e relatar apenas erros

Use o comando a seguir para executar o linter localmente nos arquivos preparados e alterados e relatar apenas falhas de gravidade error.

npm run lint-content -- --errors

Executar o linter em arquivos ou diretórios específicos

Use o comando a seguir para executar o linter localmente em arquivos ou diretórios específicos. Separe vários caminhos com um espaço. Você pode incluir arquivos e diretórios no mesmo comando.

npm run lint-content -- \
  --paths content/FILENAME.md content/DIRECTORY

npm run lint-content -- \
  --paths content/FILENAME.md content/DIRECTORY

Corrigir automaticamente erros que podem ser corrigidos

Se um erro tiver fixable: true em sua descrição, você poderá usar os comandos a seguir para corrigi-los automaticamente.

Execute este comando para corrigir somente arquivos preparados e alterados:

npm run lint-content -- --fix

Execute este comando para corrigir arquivos ou diretórios específicos:

npm run lint-content -- \
  --fix --paths content/FILENAME.md content/DIRECTORY

Executar um conjunto específico de regras de linter

Use o comando a seguir para executar uma ou mais regras de linter específicas. Esses exemplos executam as regras heading-increment e code-fence-line-length. Substitua heading-increment code-fence-line-length por um ou mais aliases de linter que você gostaria de executar. Para ver a lista de regras do linter que você pode passar nessa opção, execute npm run lint-content -- --help. Você pode usar o nome curto (por exemplo, MD001) ou o nome longo (por exemplo, heading-increment) de uma regra de linter.

Execute as regras de linter especificadas em todos os arquivos preparados e alterados:

npm run lint-content -- \
  --rules heading-increment code-fence-line-length

Execute as regras de linter definidas em arquivos ou diretórios específicos:

npm run lint-content -- \
  --rules heading-increment code-fence-line-length \
  --path content/FILENAME.md content/DIRECTORY

Ignorar o gancho de confirmação

Se o linter detectar erros que você não introduziu, você poderá ignorar o gancho de confirmação do git usando a opção --no-verify ao confirmar as alterações.

git commit -m 'MESSAGE' --no-verify

Exibir o menu de ajuda para o script de linter de conteúdo

npm run lint-content -- --help

Regras de lint

Cada regra é configurada em um arquivo no src/content-linter/style, que é onde as severidades das regras são definidas.

Os erros devem ser corrigidos antes de mesclar suas alterações com o branch main. Os avisos devem ser tratados, mas não impedem que uma alteração seja mesclada no branch main. A maioria das regras será eventualmente promovida a erros, quando o conteúdo não tiver mais violações de aviso.

          [MD001](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md001.md) | heading-increment | Os níveis de cabeçalho só devem ser incrementados em um nível de cada vez | erro | títulos |

| MD011 | no-reversed-links | Sintaxe de links invertidos | erro | links | | MD014 | commands-show-output | Cifrões usados antes dos comandos sem mostrar a saída | erro | codificar | | MD018 | no-missing-space-atx | Nenhum espaço após o hash no título de estilo atx | erro | títulos, atx, espaços | | MD019 | no-multiple-space-atx | Vários espaços após o hash no título de estilo atx | erro | títulos, atx, espaços | | MD023 | heading-start-left | Títulos devem começar no início da linha | erro | títulos, espaços | | MD027 | no-multiple-space-blockquote | Vários espaços após o símbolo de citação em bloco | erro | citação em bloco, espaço em branco, recuo | | MD029 | ol-prefix | Prefixo do item de lista ordenada | erro | ol | | MD030 | list-marker-space | Espaços após marcadores de lista | erro | ol, ul, espaço em branco | | MD031 | blanks-around-fences | Blocos de código cercados devem ser delimitados por linhas em branco | erro | código, linhas_em_branco | | MD037 | no-space-in-emphasis | Espaços dentro dos marcadores de ênfase | erro | espaços em branco, ênfase | | MD039 | no-space-in-links | Espaços dentro do texto do link | erro | espaços em branco, links | | MD040 | fenced-code-language | Blocos de código cercados devem ter uma linguagem especificada | erro | código, linguagem | | MD042 | no-empty-links | Nenhum link vazio | erro | links | | MD050 | strong-style | Estilo forte | erro | emphasis | | GH001 | no-default-alt-text | As imagens devem ter um texto alternativo significativo (texto Alt) | erro | acessibilidade, imagens | | GH002 | no-generic-link-text | Evite usar texto de link genérico, como Learn more ou Click here | erro | acessibilidade, links | | GHD001 | link-punctuation | Os títulos dos links internos não devem conter pontuação | erro | links, URL | | GHD002 | internal-links-no-lang | Os links internos não devem ter um código de idioma codificado | erro | links, URL | | GHD003 | internal-links-slash | Os links internos devem começar com um / | erro | links, URL | | GHD004 | image-file-kebab-case | Os nomes dos arquivos de imagem devem usar maiúsculas e minúsculas | erro | images | | GHD005 | hardcoded-data-variable | Cadeias de caracteres que contêm "token de acesso pessoal" devem usar a variável product em vez disso | erro | single-source | | GHD006 | internal-links-old-version | Links internos não devem ter uma versão codificada usando a sintaxe de controle de versão antiga | erro | links, url, controle de versão | | GHD007 | code-annotations | As anotações de código definidas em Markdown devem conter uma propriedade frontmatter de layout específica | erro | código, recurso, anotação, frontmatter | | GHD008 | early-access-references | Arquivos que não são de acesso antecipado não devem fazer referência a arquivos early-access ou early-access-files | erro | recursos, acesso antecipado | | GHD009 | frontmatter-early-access-references | Arquivos que não são de acesso antecipado não devem ter um frontmatter que faça referência a early-access | erro | frontmatter, recurso, acesso antecipado | | GHD010 | frontmatter-hidden-docs | Artigos com a propriedade de frontmatter hidden só podem ser localizados em produtos específicos | erro | frontmatter, recurso, acesso antecipado | | GHD011 | frontmatter-video-transcripts | A transcrição de vídeo deve ser configurada corretamente | erro | frontmatter, recurso, transcrições de vídeo | | GHD012 | frontmatter-schema | O frontmatter deve estar em conformidade com o esquema | erro | frontmatter, esquema | | GHD013 | github-owned-action-references | Referências de ações de propriedade do GitHub não devem ser codificadas | erro | recurso, ações | | GHD014 | liquid-data-references-defined | Dados líquidos ou referências de dados recuados foram encontrados em conteúdo que não tem valor ou não existe no diretório de dados | erro | liquid | | GHD015 | liquid-data-tag-format | As tags de dados líquidos ou de referências de dados recuados devem estar no formato adequado e ter número de argumentos e espaçamento corretos. | erro | líquido, formato | | GHD016 | liquid-quoted-conditional-arg | Tags condicionais líquidas não devem citar o argumento condicional | erro | líquido, formato | | GHD017 | frontmatter-liquid-syntax | As propriedades do frontmatter devem usar o Liquid válido | erro | líquido, preliminares | | GHD018 | liquid-syntax | O conteúdo do Markdown deve usar o Liquid válido | erro | liquid | | GHD019 | liquid-if-tags | Tags lifversion Liquid devem ser usadas em vez de tags if quando o argumento for uma versão válida | erro | liquid, controle de versão | | GHD020 | liquid-ifversion-tags | As tags ifversion Liquid devem conter nomes de versão válidos como argumentos | erro | liquid, controle de versão | | GHD021 | yaml-scheduled-jobs | Snippets YAML que incluem fluxos de trabalho agendados não devem ser executados por hora e devem ser exclusivos | erro | recurso, ações | | GHD022 | liquid-ifversion-versions | As marcas Liquid ifversion, elsif e else devem ser válidas e não podem conter versões sem suporte. | erro | liquid, controle de versão | | GHD031 | image-alt-text-exclude-words | O texto alternativo para imagens não deve começar com palavras como "imagem" ou "gráfico" | erro | acessibilidade, imagens | | GHD032 | image-alt-text-end-punctuation | O texto alternativo para imagens deve terminar com pontuação | erro | acessibilidade, imagens | | GHD033 | incorrect-alt-text-length | O texto alternativo de imagens deve ter entre 40 e 150 caracteres | erro | acessibilidade, imagens | | GHD035 | rai-reusable-usage | Artigos RAI e reutilizáveis só podem fazer referência a conteúdo reutilizável no diretório data/reusables/rai | erro | recurso, rai | | GHD036 | image-no-gif | A imagem não deve ser um gif, referência do guia de estilo: contributing/style-guide-and-content-model/style-guide.md#images | erro | images | | GHD038 | conteúdo expirado | O conteúdo expirado deve ser corrigido. | aviso | Expirado | | GHD039 | expirará em breve | O conteúdo que expira em breve deve ser tratado de forma proativa. | aviso | Expirado | | GHD040 | table-liquid-versioning | As tabelas devem usar o formato de controle de versão líquido correto | erro | tabelas | | GHD041 | third-party-action-pinning | Os exemplos de código que usam ações de terceiros precisam sempre ser fixados em um SHA de commit de comprimento completo | erro | recurso, ações | | GHD042 | liquid-tag-whitespace | As tags do Liquid devem começar e terminar com um espaço em branco. Os argumentos de tag do Liquid devem ser separados por apenas um espaço em branco. | erro | líquido, formato | | GHD043 | aspas no link | Títulos de link internos não devem ser cercados por aspas | erro | links, URL | | GHD045 | code-annotation-comment-spacing | Comentários de código em blocos de anotação devem ter exatamente um espaço após os caracteres de comentário | erro | código, comentários, anotar, espaçamento | | GHD046 | outdated-release-phase-terminology | A terminologia da fase da versão desatualizada deve ser substituída pela terminologia atual do GitHub | erro | terminologia, consistência, fases de versão | | GHD047 | table-column-integrity | As tabelas devem ter contagens de colunas consistentes em todas as linhas | erro | tabelas, acessibilidade, formatação | | GHD051 | frontmatter-versions-whitespace | O frontmatter de versões não deve conter espaço em branco desnecessário | erro | frontmatter, versões | | GHD054 | third-party-actions-reusable | Exemplos de código com ações de terceiros devem incluir aviso de isenção de responsabilidade reutilizável | erro | ações, reutilizáveis, de terceiros | | GHD056 | frontmatter-landing-recommended | Apenas as páginas de aterrissagem podem ter artigos recomendados, não deve haver artigos recomendados duplicados e todos os artigos recomendados devem existir | erro | frontmatter, aterrissagem, recomendado | | GHD057 | ctas-schema | As URLs de CTA devem estar em conformidade com o esquema | erro | CTAs, esquema, URLs | | GHD058 | trajetória-rastreamentos-líquido | As propriedades de trilha de percurso devem usar sintaxe Liquid válida | erro | frontmatter, trilhas de viagem, líquido | | GHD059 | jornada-trilhas-guia-caminho-existe | Os caminhos de guia do percurso devem referenciar arquivos de conteúdo existentes | erro | frontmatter, trajetórias de usuário | | GHD060 | journey-tracks-unique-ids | As IDs de faixa de percurso devem ser exclusivas em uma página | erro | frontmatter, journey-tracks, identificadores únicos | | GHD061 | frontmatter-hero-image | Os caminhos das imagens hero devem ser absolutos, sem extensões e devem apontar para imagens válidas em /assets/images/banner-images/ | erro | frontmatter, imagens | | GHD062 | frontmatter-intro-links | As chaves introLinks devem ser chaves válidas definidas em dados/ui.yml em product_landing | erro | frontmatter, fonte única | | search-replace | Sintaxe líquida preterida: octicon- | A sintaxe líquida octicon usada está obsoleta. Em vez disso, use este formato octicon "<octicon-name>" aria-label="<Octicon aria label>" | erro | | | search-replace | Sintaxe líquida preterida: site.data | Captura ocorrências da sintaxe de dados líquida obsoleta. | erro | | | search-replace | developer-domain | Captura ocorrências do domínio developer.github.com. | erro | | | search-replace | docs-domain | Captura ocorrências do domínio docs.github.com. | erro | | | search-replace | help-domain | Captura ocorrências do domínio help.github.com. | erro | | | search-replace | todocs-placeholder | Captura ocorrências do espaço reservado TODOCS. | erro | |

Sintaxe para regras de lint

Algumas regras de lint retornam avisos ou erros com base em comentários HTML que você pode adicionar a artigos.

Sintaxe para conteúdo em expiração e expirado

Verificação GHD038 e GHD039 de regras para conteúdo que recebeu manualmente uma data de validade. Quatorze dias antes da data especificada, o linter de conteúdo retornará um aviso de que o conteúdo está expirando em breve. A partir da data especificada, o linter de conteúdo retornará um aviso e sinalizará o conteúdo para correção.

Você pode adicionar uma data de término ao conteúdo encapsulando-o em marcas HTML que contêm uma data de término no formato: <!-- expires yyyy-mm-dd --> <!-- end expires yyyy-mm-dd -->

Use:

This content does not expire.
<!-- expires 2022-01-28 -->
This content expires on January 28, 2022.
<!-- end expires 2022-01-28 -->
This content also does not expire.

Observe que, se você estiver colocando as tags expiradas em um elemento HTML table, certifique-se de que a tag percorra toda a linha e não apenas a célula. Por exemplo:

<!-- expires 2024-06-28 -->
<tr>
<td>
macOS
</td>
<td>
The <code>macos-11</code> label is encerrando and will no longer be available after 28 June 2024.
</td>
</tr>
<!-- end expires 2024-06-28 -->

Suprimir regras de linter

Ocasionalmente, talvez você precise documentar algo que viola uma ou mais regras do linter. Nesses casos, é possível suprimir regras adicionando um comentário ao arquivo Markdown. Você pode desabilitar todas as regras ou regras específicas. Sempre tente limitar o mínimo possível de regras. É possível desabilitar uma regra para um arquivo inteiro, para uma seção de um arquivo Markdown, uma linha específica ou a próxima linha.

Por exemplo, se você estiver escrevendo um artigo que inclua a expressão regular (^|/)[Cc]+odespace/, que verifica a sintaxe de links invertidos, ele acionará a regra MD011, que verifica links invertidos. Você pode desabilitar a regra MD011 nessa linha específica adicionando o seguinte comentário.

(^|/)[Cc]+odespace/ <!-- markdownlint-disable-line MD011 -->

Se a linha que você está tentando ignorar estiver em um bloco de código, será possível ignorar esse bloco cercando-o com os seguintes comentários.

<!-- markdownlint-disable MD011 -->
```
(^|/)[Cc]+odespace/
```
<!-- markdownlint-enable MD011 -->

É possível usar esses comentários para habilitar ou desabilitar regras.