Compartilhar via

Contribuir usando GitHub Codespaces

O GitHub tem um recurso chamado Codespaces que você pode usar para contribuir com a documentação do PowerShell sem precisar instalar ou configurar nenhum software localmente. Ao usar um codespace, você obtém as mesmas ferramentas de criação que a equipe usa para escrever e editar.

Você pode usar um codespace em seu navegador, fazendo suas contribuições no VS Code hospedado pela Internet. Se você tiver o VS Code instalado localmente, também poderá se conectar ao codespace.

Ferramentas disponíveis

Quando você usa um codespace para contribuir com a documentação do PowerShell, seu editor já tem estas ferramentas disponíveis para você:

Custo

Os Codespaces do GitHub podem ser usados gratuitamente até 120 horas principais por mês. O uso mensal é calculado em todos os seus repositórios, não apenas na documentação.

Para obter mais informações sobre preços, consulte Sobre a cobrança para codespaces do GitHub.

Dica

Se você estiver confortável usando contêineres e Docker, poderá obter a mesma experiência usando o devcontainer definido para os repositórios de documentação do PowerShell. Não há nenhum custo associado ao uso de devcontainers. Para obter mais informações, consulte o tutorial Contêineres de Desenvolvimento.

Criando seu codespace do GitHub

Para criar seu Codespace do GitHub para contribuir com a documentação do PowerShell, siga estas etapas:

  1. Abra https://github.com/codespaces no navegador.
  2. Selecione o botão "Novo codespace" no canto superior direito da página.
  3. Na página "Criar um novo codespace", selecione o botão "Selecionar um repositório" e digite o nome do repositório para o qual você deseja contribuir, como MicrosoftDocs/PowerShell-Docs.
  4. Deixe todas as outras configurações como padrão.
  5. Selecione o botão "Criar codespace".

Depois de seguir essas etapas, o GitHub criará um novo codespace para esse repositório e o configurará para você. Quando o codespace estiver pronto, a página será atualizada e mostrará a interface do editor web para o codespace. A interface do usuário é baseada no VS Code e funciona da mesma maneira.

Abrindo seu codespace do GitHub

Para abrir o Codespace do GitHub no navegador, siga estas etapas:

  1. Abra https://github.com/codespaces no navegador.
  2. A página lista seus Codespaces. Localize o codespace criado para o repositório para o qual você deseja contribuir e selecione-o.

Depois de selecionar seu codespace, o GitHub o abrirá na mesma janela. A partir daqui, você está pronto para contribuir.

Para abrir o Codespace do GitHub no VS Code, siga as etapas em Usar os Codespaces do GitHub no Visual Studio Code.

Criação em seu Codespace do GitHub

Depois de abrir o Codespace do GitHub no navegador ou no VS Code, a contribuição para a documentação segue o mesmo processo.

O restante deste artigo descreve uma seleção de tarefas que você pode fazer em seu Codespace do GitHub ao escrever ou editar sua contribuição.

Quando você quiser transformar um link embutido, como [some text](destination.md), em um link de referência como [some text][01], selecione o destino do link no editor. Em seguida, você pode:

  1. Clique com o botão direito do mouse no destino do link e selecione "Refatorar..." no menu de contexto.
  2. Pressione Ctrl+Shift+R.

Qualquer uma das ações abre o menu de contexto de refatoração. Para substituir o (destination.md) no link com [def], selecione Extrair para definição de link no menu de contexto. Você pode renomear a definição digitando um nome.

Para a documentação do PowerShell, usamos definições de link de referência numérica de dois dígitos, como [01] ou [31]. Use apenas definições de link de referência em artigos e documentação conceitual. Não use definições de link de referência na documentação de referência do cmdlet.

Corrigir violações de estilo de prosa

Ao examinar um artigo em seu codespace, a Vale verifica automaticamente o artigo quando você o abre pela primeira vez e sempre que o salva. Se Vale encontrar violações de estilo, ela as destacará no documento com rabiscos coloridos.

Passe o mouse sobre uma violação para ver mais informações sobre ela.

Para abrir uma página da Web que explique a regra, selecione o nome da regra nas informações ao passar o mouse. Para abrir a regra e examinar sua implementação, selecione o nome do arquivo da regra (terminando em .yml).

Se a regra der suporte a uma correção rápida, você poderá selecionar "Correção Rápida..." nas informações de foco da violação e aplique uma das correções sugeridas selecionando-a no menu de contexto. Você também pode pressionar Ctrl+. quando o cursor estiver em um problema realçado para aplicar uma correção rápida se a regra der suporte a ele.

Se a regra não der suporte a correções rápidas, leia a mensagem da regra e corrija-a se puder. Se você não tiver certeza de como corrigi-lo, os editores poderão fazer uma sugestão ao revisar sua PR.

Corrigir problemas de sintaxe

Quando você revisa um artigo em seu codespace, o Markdownlint verifica automaticamente o artigo quando você o abre e à medida que digita. Se Markdownlint encontrar problemas de sintaxe, ele os realçará no documento com rabiscos coloridos.

Passe o mouse sobre uma violação para ver mais informações sobre ela. Para abrir uma página da Web que explica a regra, selecione a ID da regra nas informações de foco.

Se a regra der suporte a uma correção rápida, você poderá selecionar "Correção Rápida..." nas informações de foco da violação e aplique uma das correções sugeridas selecionando-a no menu de contexto. Você também pode pressionar Ctrl+. quando o cursor estiver em um problema realçado para aplicar uma correção rápida se a regra der suporte a ele.

Se a regra não der suporte a correções rápidas, leia a mensagem da regra e corrija-a se puder. Se você não tiver certeza de como corrigi-lo, os editores poderão fazer uma sugestão ao revisar sua PR.

Você também pode aplicar correções a todas as violações de sintaxe em um artigo. Para fazer isso, abra a paleta de comandos e digite Fix all supported markdownlint violations in the document. Conforme você digita, a paleta de comandos filtra os comandos disponíveis. Selecione o comando "Corrigir todas as violações de markdownlint suportadas no documento". Quando você faz isso, Markdownlint atualiza o documento para resolver quaisquer violações para as quais ele tem uma correção rápida.

Formatar uma tabela

Para formatar uma tabela Markdown, coloque o cursor dentro ou sobre a tabela em seu Markdown. Abra a Paleta de Comandos e pesquise o Table: Format Current comando. Quando você seleciona esse comando, ele atualiza o Markdown para alinhar e preencher a tabela, melhorando assim a legibilidade.

Ele converte uma tabela definida desta forma:

| foo | bar | baz |
|:--:|:--|-:|
| a | b | c |

Para isso:

|  foo  | bar  | baz  |
| :---: | :--- | ---: |
|   a   | b    |    c |

Inserir um alerta

A documentação usa alertas para tornar as informações mais notáveis para um leitor.

Para inserir um alerta, você pode abrir a Paleta de Comandos e pesquisar o Learn: Alert comando. Quando você seleciona esse comando, ele abre um menu de contexto. Selecione o tipo de alerta que você deseja adicionar. Quando você faz isso, o comando insere o Markdown do alerta em seu cursor no documento.

Faça um título e use letras maiúsculas e minúsculas

Para converter a caixa de um título, destaque o texto do título, exceto os símbolos de início #, que definem o nível do título. Quando você tiver o texto realçado, abra a Paleta de Comandos e pesquise o Change case sentence comando. Quando você seleciona esse comando, ele altera a capitalização do texto destacado.

Você também pode usar os comandos de maiúsculas e minúsculas para qualquer texto no documento.

Abrir a paleta de comandos

Você pode usar a Paleta de Comandos do VS Code para executar muitos comandos úteis.

Para abrir a Paleta de Comandos na interface do usuário, selecione "Exibir" na barra de menus superior. Em seguida, selecione "Paleta de Comandos..." no menu de contexto.

Para abrir a Paleta de Comandos com o teclado, pressione a combinação de teclas para o sistema operacional:

  • Windows e Linux: Ctrl+Shift+P
  • macOS: Cmd+Shift+P

Visualizar sua contribuição

Para visualizar sua contribuição, abra a Paleta de Comandos e pesquise o Markdown: Open Preview comando. Quando você seleciona esse comando, o VS Code abre uma visualização do documento ativo. O estilo da versão preliminar corresponde à plataforma Learn.

Observação

Os links relativos ao site e de referência cruzada não funcionam na versão preliminar.

Refluxo de seu conteúdo

Para limitar os comprimentos de linha de um parágrafo em um documento, coloque o cursor no parágrafo. Em seguida, abra a Paleta de Comandos e pesquise o Reflow Markdown comando. Quando você seleciona o comando, ele atualiza os comprimentos de linha do parágrafo atual para o comprimento configurado. Para nossos repositórios, esse comprimento é de 99 caracteres.

Ao usar este comando para citações em bloco, verifique se o parágrafo na citação que você está reorganizando está cercado por linhas em branco. Caso contrário, o comando refaz o fluxo de todos os parágrafos juntos.

Cuidado

Não use esse comando ao editar sobre artigos. As linhas nesses documentos não devem ter mais de 80 caracteres. No momento, não há como um repositório configurar diferentes comprimentos de linha por pasta ou nome de arquivo, portanto, o refluxo não funciona para documentos de artigo.

Examinar todos os problemas em um documento

Para examinar todas as violações de regra de estilo e sintaxe em um documento, abra o Modo de Exibição de Problemas.

Para abrir o Modo de Exibição de Problemas na interface do usuário, selecione "Exibir" na barra de menus superior. Em seguida, selecione "Problemas" no menu de contexto.

Para abrir o Modo de Exibição de Problemas com o teclado, pressione a combinação de teclas para o sistema operacional:

  • Windows e Linux: Ctrl+Shift+M
  • macOS: Cmd+Shift+M

O Modo de Exibição de Problemas exibe todos os erros, avisos e sugestões para o documento aberto. Selecione um problema para rolar até ele no documento.

Você pode filtrar os problemas por tipo ou correspondência de texto.

Atualizar os metadados ms.date

Para atualizar os ms.date metadados de um artigo, abra a Paleta de Comandos e pesquise o Learn: Update "ms.date" Metadata Value comando. Quando você seleciona o comando, ele atualiza os metadados para a data atual.

Recursos adicionais

As tarefas e os comandos descritos neste artigo não abrangem tudo o que você pode fazer com o VS Code ou as extensões instaladas.

Para obter mais informações sobre como usar o VS Code, consulte estes artigos:

Para obter mais informações sobre as extensões instaladas, consulte a documentação:

  • Last updated on