Partilhar via

Contribua usando o 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. Quando você usa um espaço de código, obtém as mesmas ferramentas de criação que a equipe usa para escrever e editar.

Você pode usar um espaço de código em seu navegador, fazendo suas contribuições no VS Code hospedado pela internet. Se você tiver o VS Code instalado localmente, você pode se conectar ao espaço de código lá também.

Ferramentas disponíveis

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

  • Markdownlint para verificar sua sintaxe Markdown.
  • cSpell para verificar a ortografia.
  • Vale para revisar a sua prosa.
  • O Learn Authoring Pack para inserir sintaxe específica da plataforma, visualizar sua contribuição e muito mais.
  • A extensão Reflow Markdown para reorganizar o seu Markdown quando necessário, facilitando a leitura e a edição.
  • A extensão Table Formatter para tornar suas tabelas mais legíveis sem ter que alinhar colunas manualmente.
  • A extensão change-case para converter a capitalização dos seus títulos e prosa.
  • A extensão GitLens para revisar alterações de arquivos históricos.
  • A extensão do PowerShell para interagir criando exemplos do PowerShell.
  • O rastreador Gremlins para Visual Studio Code para localizar caracteres problemáticos em seu Markdown.

Custo

Os Codespaces do GitHub podem ser usados gratuitamente até 120 horas-chave 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 do GitHub Codespaces.

Sugestão

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á custo associado ao uso de devcontainers. Para obter mais informações, consulte o tutorial Dev Containers.

Criando seu espaço de código GitHub

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

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

Depois de seguir essas etapas, o GitHub cria um novo espaço de código para esse repositório e o configura para você. Quando o codespace estiver pronto, a página atualiza e mostra a interface do editor web para o codespace. A interface do usuário é baseada no VS Code e funciona da mesma maneira.

Abrindo seu espaço de código do GitHub

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

  1. Abra https://github.com/codespaces no seu navegador.
  2. A página lista os seus Codespaces. Encontre o espaço de código criado para o repositório para o qual deseja contribuir e selecione-o.

Depois de selecionar seu espaço de código, o GitHub o abre na mesma janela. A partir daqui, você está pronto para contribuir.

Para abrir seu GitHub Codespace no VS Code, siga as etapas em Usando o GitHub Codespaces no Visual Studio Code.

Edição no seu ambiente de desenvolvimento GitHub

Depois de ter seu GitHub Codespace aberto em seu navegador ou VS Code, contribuir para a documentação segue o mesmo processo.

O restante deste artigo descreve uma seleção de tarefas que você pode fazer em seu espaço de código do GitHub enquanto escreve ou edita sua contribuição.

Quando 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 ação abre o menu de contexto de refatoração. Para substituir o (destination.md) no link por [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

Quando você revisa um artigo em seu espaço de código, a Vale verifica automaticamente o artigo quando você o abre pela primeira vez e toda vez que você o salva. Se a Vale encontrar alguma violação de estilo, ela destaca-os no documento com rabiscos coloridos.

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

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

Se a regra permitir uma correção rápida, pode selecionar "Correção rápida..." ao passar o cursor sobre a informação de violação e aplicar uma das correções sugeridas, selecionando-a no menu de contexto. Você também pode pressionar Ctrl+. quando o cursor estiver sobre um problema realçado para aplicar uma correção rápida, se a regra permitir.

Se a regra não suportar correções rápidas, leia a mensagem da regra e corrija-a, se possível. Se você não tiver certeza de como corrigi-lo, os editores podem fazer uma sugestão ao revisar seu PR.

Corrigir problemas de sintaxe

Quando você revisa um artigo em seu espaço de código, o Markdownlint verifica automaticamente o artigo quando você o abre e enquanto digita. Se o Markdownlint encontrar algum problema de sintaxe, ele o destacará no documento com rabiscos coloridos.

Passe o cursor sobre uma violação para ver mais informações sobre ela. Para abrir uma página da Web que explique a regra, selecione o ID da regra nas informações ao passar o cursor.

Se a regra permitir uma correção rápida, pode selecionar "Correção rápida..." ao passar o cursor sobre a informação de violação e aplicar uma das correções sugeridas, selecionando-a no menu de contexto. Você também pode pressionar Ctrl+. quando o cursor estiver sobre um problema realçado para aplicar uma correção rápida, se a regra permitir.

Se a regra não suportar correções rápidas, leia a mensagem da regra e corrija-a, se possível. Se você não tiver certeza de como corrigi-lo, os editores podem fazer uma sugestão ao revisar seu 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. À medida que 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 o fizer, o Markdownlint atualiza o documento para resolver quaisquer violações para as quais tenha uma solução rápida.

Formatar uma tabela

Para formatar uma tabela Markdown, coloque o cursor sobre a tabela no Markdown. Abra a Paleta de Comandos e procure o Table: Format Current comando. Quando você seleciona esse comando, ele atualiza a marcação da tabela para alinhar e preencher a tabela para melhorar a legibilidade.

Ele converte uma tabela definida assim:

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

Nisto:

|  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, abra a Paleta de Comandos e procure o Learn: Alert comando. Quando você seleciona esse comando, ele abre um menu de contexto. Selecione o tipo de alerta que deseja adicionar. Quando o fizer, o comando insere o Markdown do alerta no cursor do documento.

Fazer com que um título use caixa de frase

Para converter a caixa de um cabeçalho, realce o texto do título, exceto os símbolos à esquerda # , que definem o nível do título. Quando tiver o texto realçado, abra a Paleta de Comandos e procure o Change case sentence comando. Quando você seleciona esse comando, ele converte o invólucro do texto realçado.

Você também pode usar os comandos de caixa 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 menu superior. Em seguida, selecione "Paleta de comandos..." no menu de contexto.

Para abrir a Paleta de Comandos com o teclado, prima a combinação de teclas do seu sistema operativo:

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

Pré-visualize a sua contribuição

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

Observação

As ligações relativas ao site e de referência entre si não funcionam quando pré-visualizadas.

Reorganize o seu conteúdo

Para limitar os comprimentos de linha de um parágrafo num documento, coloque o cursor sobre o parágrafo. Em seguida, abra a Paleta de Comandos e procure o Reflow Markdown comando. Quando você seleciona o comando, ele atualiza os comprimentos de linha do parágrafo atual para o comprimento configurado. Para os 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 em bloco que está a reformatar está rodeado por linhas em branco. Caso contrário, o comando reorganiza todos os parágrafos.

Atenção

Não use este comando ao editar artigos. As linhas desses documentos não devem ter mais de 80 caracteres. Atualmente, 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 artigos.

Rever todos os problemas num documento

Para rever todas as violações de sintaxe e regras de estilo num documento, abra a Vista de problemas.

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

Para abrir a Vista de Problemas com o teclado, prima a combinação de teclas do seu sistema operativo:

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

A Vista de Problemas apresenta 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.

Atualizando os metadados ms.date

Para atualizar os metadados de ms.date um artigo, abra a Paleta de Comandos e procure 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 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