Skip to main content

Esta versão do GitHub Enterprise Server foi descontinuada em 2024-03-26. Nenhum lançamento de patch será feito, mesmo para questões críticas de segurança. Para obter melhor desempenho, segurança aprimorada e novos recursos, atualize para a última versão do GitHub Enterprise Server. Para obter ajuda com a atualização, entre em contato com o suporte do GitHub Enterprise.

Usando o linter de conteúdo

Você pode usar o linter de conteúdo para marcar sua contribuições para erros.

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, consulte "Corrigir automaticamente os 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.

Shell
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.

ID da regraNomes das regrasDescriçãoSeveridadeMarcas
MD001heading-increment, header-incrementOs níveis de cabeçalho só devem ser incrementados em um nível de cada vezerrortítulos, cabeçalhos
MD002first-heading-h1, first-header-h1O primeiro título deve ser de nível superiorerrortítulos, cabeçalhos
MD004ul-styleEstilo de lista não ordenadaerrormarcador, ul
MD009no-trailing-spacesEspaços à direitaerrorwhitespace
MD011no-reversed-linksSintaxe de links invertidoserrorlinks
MD012no-multiple-blanksVárias linhas em branco consecutivaserrorwhitespace, blank_lines
MD014commands-show-outputCifrões usados antes dos comandos sem mostrar a saídaerrorcódigo
MD018no-missing-space-atxNenhum espaço após o hash no título de estilo atxerrortítulos, cabeçalhos, atx, espaços
MD019no-multiple-space-atxVários espaços após o hash no título de estilo atxerrortítulos, cabeçalhos, atx, espaços
MD022blanks-around-headings, blanks-around-headersTítulos devem ser delimitados por linhas em brancoerrorheadings, headers, blank_lines
MD023heading-start-left, header-start-leftTítulos devem começar no início da linhaerrortítulos, cabeçalhos, espaços
MD027no-multiple-space-blockquoteVários espaços após o símbolo de citação em blocoerrorcitação em bloco, espaço em branco, recuo
MD029ol-prefixPrefixo do item de lista ordenadaerrorol
MD030list-marker-spaceEspaços após marcadores de listaerrorol, ul, espaço em branco
MD031blanks-around-fencesBlocos de código cercados devem ser delimitados por linhas em brancoerrorcode, blank_lines
MD037no-space-in-emphasisEspaços dentro dos marcadores de ênfaseerrorespaços em branco, ênfase
MD039no-space-in-linksEspaços dentro do texto do linkerrorespaços em branco, links
MD040fenced-code-languageBlocos de código cercados devem ter uma linguagem especificadaerrorcódigo, linguagem
MD042no-empty-linksNenhum link vazioerrorlinks
MD047single-trailing-newlineOs arquivos devem terminar com um único caractere de nova linhaerrorblank_lines
MD049emphasis-styleO estilo de ênfase deve ser consistenteerroremphasis
MD050strong-styleO estilo forte deve ser consistenteerroremphasis
search-replacetodocs-placeholderCaptura ocorrências do espaço reservado TODOCS.error
search-replacedocs-domainCaptura ocorrências do domínio docs.gitub.com.error
search-replacehelp-domainCaptura ocorrências do domínio help.github.com.error
search-replacepreview-domainCaptura ocorrências do domínio preview.ghdocs.com.error
search-replacedeveloper-domainCaptura ocorrências do domínio developer.github.com.error
search-replacedeprecated liquid syntax: site.dataCaptura ocorrências da sintaxe de dados líquida obsoleta.error
search-replacedeprecated liquid syntax: octicon-A sintaxe líquida octicon usada está obsoleta. Em vez disso, use este formato octicon "<octicon-name>" aria-label="<Octicon aria label>"error
GH001no-default-alt-textAs imagens devem ter um texto alternativo significativo (texto Alt)erroracessibilidade, imagens
GH002no-generic-link-textEvite usar texto de link genérico, como Learn more ou Click hereerroracessibilidade, links
GHD030code-fence-line-lengthAs linhas de cercas de código não devem exceder um comprimento máximogeralcódigo, acessibilidade
GHD032image-alt-text-end-punctuationO texto alternativo para imagens deve terminar com pontuaçãoerroracessibilidade, imagens
GHD004image-file-kebab-caseOs nomes dos arquivos de imagem devem usar maiúsculas e minúsculaserrorimages
GHD033incorrect-alt-text-lengthO texto alternativo de imagens deve ter entre 40 e 150 caracteresgeralacessibilidade, imagens
GHD002internal-links-no-langOs links internos não devem ter um código de idioma codificadoerrorlinks, url
GHD003internal-links-slashOs links internos devem começar com um /errorlinks, url
GHD031image-alt-text-exclude-wordsO texto alternativo para imagens não deve começar com palavras como "imagem" ou "gráfico"erroracessibilidade, imagens
GHD034list-first-word-capitalizationA primeira palavra do item da lista deve ser em maiúsculasgeralul, ol
GHD001link-punctuationOs títulos dos links internos não devem conter pontuaçãoerrorlinks, url
GHD008early-access-referencesArquivos que não são de acesso antecipado não devem fazer referência a arquivos early-access ou early-access-fileserrorrecursos, acesso antecipado
GHD021yaml-scheduled-jobsSnippets YAML que incluem fluxos de trabalho agendados não devem ser executados por hora e devem ser exclusivoserrorrecurso, ações
GHD006internal-links-old-versionLinks internos não devem ter uma versão codificada usando a sintaxe de controle de versão antigaerrorlinks, url, controle de versão
GHD005hardcoded-data-variableCadeias de caracteres que contêm "token de acesso pessoal" devem usar a variável product em vez dissoerrorsingle-source
GHD013github-owned-action-referencesReferências de ações de propriedade do GitHub não devem ser codificadaserrorrecurso, ações
GHD016liquid-quoted-conditional-argTags condicionais líquidas não devem citar o argumento condicionalerrorlíquido, formato
GHD014liquid-data-references-definedDados 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 dadoserrorliquid
GHD015liquid-data-tag-formatAs tags de dados líquidos ou de referências de dados recuados devem ter o número correto de argumentos e espaçamentoerrorlíquido, formato
GHD010frontmatter-hidden-docsArtigos com a propriedade de frontmatter hidden só podem ser localizados em produtos específicoserrorfrontmatter, recurso, acesso antecipado
GHD009frontmatter-early-access-referencesArquivos que não são de acesso antecipado não devem ter um frontmatter que faça referência a early-accesserrorfrontmatter, recurso, acesso antecipado
GHD011frontmatter-video-transcriptsA transcrição de vídeo deve ser configurada corretamenteerrorfrontmatter, recurso, transcrições de vídeo
GHD012frontmatter-schemaO frontmatter deve estar em conformidade com o esquemaerrorfrontmatter, esquema
GHD007code-annotationsAs anotações de código definidas em Markdown devem conter uma propriedade frontmatter de layout específicaerrorcódigo, recurso, anotação, frontmatter
GHD017frontmatter-liquid-syntaxAs propriedades do frontmatter devem usar o Liquid válidoerrorliquid, frontmatter
GHD018liquid-syntaxO conteúdo do Markdown deve usar o Liquid válidoerrorliquid
GHD019liquid-if-tagsTags lifversion Liquid devem ser usadas em vez de tags if quando o argumento for uma versão válidaerrorliquid, controle de versão
GHD020liquid-ifversion-tagsAs tags ifversion Liquid devem conter nomes de versão válidos como argumentoserrorliquid, controle de versão
GHD022liquid-ifversion-versionsLíquid ifversion (e elsif) nem sempre deve ser truegeralliquid, controle de versão
GHD035rai-reusable-usageArtigos RAI e reutilizáveis só podem fazer referência a conteúdo reutilizável no diretório data/reusables/raierrorrecurso, rai
GHD036image-no-gifA imagem não deve ser um gif, referência do guia de estilo: contributing/style-guide-and-content-model/style-guide.md#imageserrorimages
GHD038conteúdo expiradoO conteúdo expirado deve ser corrigido.errorExpirado
GHD039expirará em breveO conteúdo que expira em breve deve ser tratado de forma proativa.geralExpirado

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.

ComentárioEfeito
<!-- markdownlint-disable -->
Desabilitar todas as regras
<!-- markdownlint-enable -->
Habilitar todas as regras
<!-- markdownlint-disable-line -->
Desabilitar todas as regras para a linha atual
<!-- markdownlint-disable-next-line -->
Desabilitar todas as regras para a próxima linha
<!-- markdownlint-disable RULE-ONE RULE-TWO -->
Desabilitar uma ou mais regras por nome
<!-- markdownlint-enable RULE-ONE RULE-TWO -->
Habilitar uma ou mais regras por nome
<!-- markdownlint-disable-line RULE-NAME -->
Desabilitar uma ou mais regras por nome para a linha atual
<!-- markdownlint-disable-next-line RULE-NAME -->
Desabilitar uma ou mais regras por nome para a próxima linha