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.
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.
ID da regra | Nomes das regras | Descrição | Severidade | Marcas |
---|---|---|---|---|
MD001 | heading-increment | Os níveis de cabeçalho só devem ser incrementados em um nível de cada vez | erro | títulos |
MD004 | ul-style | Estilo de lista não ordenada | erro | marcador, ul |
MD009 | no-trailing-spaces | Espaços à direita | erro | espaço em branco |
MD011 | no-reversed-links | Sintaxe de links invertidos | erro | links |
MD012 | no-multiple-blanks | Várias linhas em branco consecutivas | erro | whitespace, blank_lines |
MD014 | commands-show-output | Cifrões usados antes dos comandos sem mostrar a saída | erro | código |
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 |
MD022 | blanks-around-headings | Títulos devem ser delimitados por linhas em branco | erro | títulos, blank_lines |
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 | code, blank_lines |
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 |
MD047 | single-trailing-newline | Os arquivos devem terminar com um único caractere de nova linha | erro | blank_lines |
MD049 | emphasis-style | Estilo de ênfase | erro | emphasis |
MD050 | strong-style | Estilo forte | erro | emphasis |
search-replace | todocs-placeholder | Captura ocorrências do espaço reservado TODOCS. | 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 | preview-domain | Captura ocorrências do domínio preview.ghdocs.com. | erro | |
search-replace | developer-domain | Captura ocorrências do domínio developer.github.com. | erro | |
search-replace | deprecated liquid syntax: site.data | Captura ocorrências da sintaxe de dados líquida obsoleta. | erro | |
search-replace | deprecated 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>" | erro | |
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 |
GHD030 | code-fence-line-length | As linhas de cercas de código não devem exceder um comprimento máximo | geral | código, acessibilidade |
GHD032 | image-alt-text-end-punctuation | O texto alternativo para imagens deve terminar com pontuação | erro | acessibilidade, imagens |
GHD004 | image-file-kebab-case | Os nomes dos arquivos de imagem devem usar maiúsculas e minúsculas | erro | images |
GHD033 | incorrect-alt-text-length | O texto alternativo de imagens deve ter entre 40 e 150 caracteres | geral | acessibilidade, imagens |
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 |
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 |
GHD034 | list-first-word-capitalization | A primeira palavra do item da lista deve ser em maiúsculas | geral | ul, ol |
GHD001 | link-punctuation | Os títulos dos links internos não devem conter pontuação | erro | links, url |
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 |
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 |
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 |
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 |
GHD013 | github-owned-action-references | Referências de ações de propriedade do GitHub não devem ser codificadas | erro | recurso, ações |
GHD016 | liquid-quoted-conditional-arg | Tags condicionais líquidas não devem citar o argumento condicional | erro | líquido, formato |
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 |
GHD010 | frontmatter-hidden-docs | Artigos com a propriedade de frontmatter hidden só podem ser localizados em produtos específicos | erro | frontmatter, recurso, 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 |
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 |
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 |
GHD017 | frontmatter-liquid-syntax | As propriedades do frontmatter devem usar o Liquid válido | erro | liquid, frontmatter |
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 |
GHD022 | liquid-ifversion-versions | Líquid ifversion (e elsif ) nem sempre deve ser true | geral | liquid, controle de versão |
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. | erro | Expirado |
GHD039 | expirará em breve | O conteúdo que expira em breve deve ser tratado de forma proativa. | geral | 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 |
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.
Comentário | Efeito |
---|---|
<!-- 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 --> | |
<!-- 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 |