# 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`](https://github.com/DavidAnson/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 verificar o conteúdo Markdown em nossos diretórios `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 linted 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](#automatically-fix-errors-that-can-be-fixed).

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

```shell
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`.

```shell
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 múltiplos caminhos com um espaço. Você pode incluir arquivos e diretórios no mesmo comando.

```shell copy
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:

```shell
npm run lint-content -- --fix
```

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

```shell
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:

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

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

```shell
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.

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

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

```shell
npm run lint-content -- --help
```

## Regras de linting

Cada regra é configurada em um arquivo no [`src/content-linter/style`](https://github.com/github/docs/tree/main/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.

<!-- markdownlint-disable -->
<!-- This file is automatically generated. Manual changes will be overwritten by a 🤖 -->
| ID da regra | Nomes das regras | Descrição | Severity | Marcas |
| ------- | ------------ | ----------- | -------- | ---- |
| [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](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md011.md) | no-reversed-links | Sintaxe de links invertidos | erro | links |
| [MD014](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md014.md) | commands-show-output | Cifrões usados antes dos comandos sem mostrar a saída | erro | codificar |
| [MD018](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md018.md) | no-missing-space-atx | Nenhum espaço após o hash no título de estilo atx | erro | títulos, atx, espaços |
| [MD019](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md019.md) | 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](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md023.md) | heading-start-left | Títulos devem começar no início da linha | erro | títulos, espaços |
| [MD027](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md027.md) | 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](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md029.md) | ol-prefix | Prefixo do item de lista ordenada | erro | ol |
| [MD030](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md030.md) | list-marker-space | Espaços após marcadores de lista | erro | ol, ul, espaço em branco |
| [MD031](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md031.md) | blanks-around-fences | Blocos de código cercados devem ser delimitados por linhas em branco | erro | código, linhas_em_branco |
| [MD037](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md037.md) | no-space-in-emphasis | Espaços dentro dos marcadores de ênfase | erro | espaços em branco, ênfase |
| [MD039](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md039.md) | no-space-in-links | Espaços dentro do texto do link | erro | espaços em branco, links |
| [MD040](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md040.md) | fenced-code-language | Blocos de código cercados devem ter uma linguagem especificada | erro | código, linguagem |
| [MD042](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md042.md) | no-empty-links | Nenhum link vazio | erro | links |
| [MD050](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md050.md) | strong-style | Estilo forte | erro | emphasis |
| [GH001](https://github.com/github/markdownlint-github/blob/main/docs/rules/GH001-no-default-alt-text.md) | no-default-alt-text | As imagens devem ter um texto alternativo significativo (texto Alt) | erro | acessibilidade, imagens |
| [GH002](https://github.com/github/markdownlint-github/blob/main/docs/rules/GH002-no-generic-link-text.md) | 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 |
| 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 l`ifversion` 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 |
| GHD034 | Aspas curvas no frontmatter | O título e a introdução do frontmatter não devem conter aspas curvas | erro | Formatação do frontmatter |
| 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 | link-quotation | 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 de versão desatualizada deve ser substituída pela terminologia GitHub atual | 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-carousels | Somente páginas de destino podem ter carrosséis, não deve haver artigos duplicados, e todos os artigos devem existir. | erro | página inicial, página de aterrissagem, carrosséis |
| GHD057 | ctas-schema | As URLs de CTA devem estar em conformidade com o esquema | erro | CTAs, esquema, URLs |
| GHD058 | journey-tracks-liquid | As propriedades de trilha de percurso devem usar sintaxe Liquid válida | erro | frontmatter, trilhas de viagem, líquido |
| GHD059 | journey-tracks-guide-path-exists | 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 |
| GHD063 | frontmatter-children | Os caminhos filhos do frontmatter devem existir. Dá suporte a caminhos relativos e caminhos /content/ absolutos para inclusão entre produtos. | erro | frontmatter, filhos |
| GHD064 | rai-app-card-structure | Os artigos sobre cartões de aplicativo/plataforma RAI devem seguir a estrutura de modelo exigida. | erro | recurso, rai |
| GHD065 | frontmatter-content-type | Os arquivos de conteúdo em diretórios de tipo de conteúdo devem ter uma propriedade de frontmatter `contentType` que corresponda ao diretório pai. | erro | frontmatter, tipo de conteúdo |
| GHD066 | frontmatter-docs-team-metrics | Artigos cujo caminho contém um valor docsTeamMetrics imposto por caminho devem incluir esse valor em sua propriedade de frontmatter docsTeamMetrics. | erro | frontmatter, docs-team-metrics |
| GHD067 | frontmatter-rest-api-category | Os arquivos de endpoint da API REST gerados automaticamente devem ter uma propriedade frontmatter válida `category` | erro | frontmatter, restante, categoria |
| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | sintaxe do liquid preterida: octicon-<icon-name> | A sintaxe do liquid octicon usada está obsoleta. Em vez disso, use este formato `octicon "<octicon-name>" aria-label="<Octicon aria label>"` | erro |  |
| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | Sintaxe líquida preterida: site.data | Captura ocorrências da sintaxe de dados líquida obsoleta. | erro |  |
| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | developer-domain | Captura ocorrências do domínio developer.github.com. | erro |  |
| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | docs-domain | Captura ocorrências do domínio docs.github.com. | erro |  |
| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | help-domain | Captura ocorrências do domínio help.github.com. | erro |  |
| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | todocs-placeholder | Captura ocorrências do espaço reservado TODOCS. | erro |  |

### Sintaxe para regras de linting

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

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

Regras `GHD038` e `GHD039` verificam o conteúdo ao qual foi dada 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:**

```markdown
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:

```html
<!-- 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.

```text
(^|/)[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.

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

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

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