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.

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 erro 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 descontinuado 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.