As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Contribua com este guia Qualquer pessoa pode contribuir com o guia de melhores práticas. O Guia de Boas Práticas do EKS está escrito no AsciiDoc formato em GitHub. ## Resumo para colaboradores existentes + Abra o [https://github.com/aws/aws-eks-best-practices/blob/master/bpg-docs.code-workspace](https://github.com/aws/aws-eks-best-practices/blob/master/bpg-docs.code-workspace)com o VS Code para instalar automaticamente a AsciiDoc extensão. + Saiba mais sobre a [AsciiDoc extensão](https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode) no Visual Studio Marketplace. + Os arquivos de origem do site do AWS Docs são armazenados em [https://github.com/aws/aws-eks-best-practices/tree/master/latest/bpg](https://github.com/aws/aws-eks-best-practices/tree/master/latest/bpg) + A sintaxe é muito semelhante ao markdown. + Analise a [referência de sintaxe](https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/) nos AsciiDoctor documentos. + A plataforma docs só é `latest/bpg/images` implantada. Cada uma das seções do guia tem um link simbólico para esse diretório. Por exemplo, `latest/bpg/networking/images` aponta para`latest/bpg/images`. ## Configurar um ambiente de edição local Se você planeja editar o guia com frequência, configure um ambiente de edição local. ### Bifurque e clone o repositório Você precisa estar familiarizado com`git`,`github`, e editores de texto. Para obter informações sobre como começar a usar `git` e`github`, consulte [Introdução à sua GitHub conta](https://docs.github.com/en/get-started/onboarding/getting-started-with-your-github-account) nos GitHub documentos. 1. Veja o [Guia de Melhores Práticas do EKS em GitHub](https://github.com/aws/aws-eks-best-practices). 1. Crie uma bifurcação do repositório do projeto. Saiba como [bifurcar um repositório](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#forking-a-repository) nos GitHub documentos. 1. Clone sua bifurcação do repositório do projeto. Saiba como [clonar seu repositório bifurcado](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#cloning-your-forked-repository). ### Abra o espaço de trabalho do VS Code A AWS recomenda usar o Visual Studio Code da Microsoft para editar o guia. Para obter mais informações sobre o VS Code, consulte [Baixar o Visual Studio Code](https://code.visualstudio.com/download) e [começar a usar o Visual Studio Code](https://code.visualstudio.com/docs/getstarted/getting-started) na documentação do Visual Studio Code. 1. Abra o VS Code. 1. Abra o `bpg-docs.code-workspace` arquivo do repositório clonado. 1. Se for a primeira vez que você abre esse espaço de trabalho, aceite a solicitação para instalar a AsciiDoc extensão. Essa extensão verifica a sintaxe dos AsciiDoc arquivos e gera uma visualização ao vivo. 1. Navegue até o `latest/bpg` diretório. Esse diretório contém os arquivos de origem que são implantados no site de documentação da AWS. Os arquivos de origem são organizados por seção de guia, como “segurança” ou “rede”. ### Editar um arquivo 1. Abra um arquivo no editor. + Veja a AsciiDoc sintaxe para aprender a criar cabeçalhos, links e listas. + Você pode usar a sintaxe Markdown para formatar texto, criar listas e cabeçalhos. Você não pode usar a sintaxe Markdown para criar links. 1. Abra uma pré-visualização ao vivo da página. + Primeiro, pressione `ctrl-k` ou `cmd-k` (dependendo do teclado). Em segundo lugar, pressione`v`. Isso abre uma visualização prévia na visualização dividida. A AWS sugere o uso de ramificações de recursos para organizar suas alterações. Aprenda a criar ramificações com o git. ### Enviar um Pull Request Você pode criar uma pull request no GitHub site ou na GitHub CLI. Saiba como [criar uma pull request a partir de uma bifurcação](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) usando o GitHub site. Saiba como [criar uma pull request](https://cli.github.com/manual/gh_pr_create) usando a GitHub cli. ## Use o editor baseado na web github.dev O editor `github.dev` baseado na web é baseado no VS Code. Essa é uma ótima maneira de editar vários arquivos e visualizar conteúdo sem nenhuma configuração. Ele tem suporte para a AsciiDoc extensão. Você pode fazer operações do git usando a GUI. O editor baseado na web não tem um shell ou terminal para executar comandos. Você deve ter uma GitHub conta. Você será solicitado a fazer login, se necessário. [🚀 Inicie o editor GitHub baseado na web.](https://github.dev/aws/aws-eks-best-practices/blob/master/bpg-docs.code-workspace?workspace=true) ## Editar uma única página Você pode atualizar rapidamente páginas individuais usando GitHub o. Cada página contém um link "📝 Editar esta página em GitHub" na parte inferior. 1. Navegue até a página deste guia que você deseja editar 1. Clique no link “Editar esta página em GitHub” na parte inferior 1. Clique no ícone de lápis de edição no canto superior direito do visualizador de GitHub arquivos ou pressione `e` 1. Edite o arquivo 1. Envie suas alterações usando o botão “Confirmar alterações...”. Esse botão cria uma GitHub pull request. Os mantenedores do guia analisarão essa pull request. Um revisor aprovará a pull request ou solicitará alterações. ## Exibir e definir o ID de uma página Esta página explica como visualizar e definir o ID da página. O ID da página é uma string exclusiva que identifica cada página no site de documentação. Você pode ver o ID da página na barra de endereço do seu navegador quando estiver em uma página específica. O ID da página é usado para o URL, o nome do arquivo e para criar links de referência cruzada. Por exemplo, se você estiver visualizando esta página, o URL na barra de endereço do seu navegador será semelhante a: ``` https://docs.aws.amazon.com/view-set-page-id.html ``` A última parte do URL (`view-set-page-id`) é o ID da página. ### Definir o ID da página Ao criar uma nova página, você precisa definir o ID da página no arquivo de origem. O ID da página deve ser uma string concisa e hifenizada que descreva o conteúdo da página. 1. Abra o arquivo de origem da sua nova página em um editor de texto. 1. Na parte superior do arquivo, adicione a seguinte linha. Deve estar acima do primeiro título. ``` [#my-new-page] ``` `my-new-page`Substitua pelo ID da página da sua nova página. 1. Salve o arquivo. **nota** A página IDs deve ser exclusiva em todo o site de documentação. Se você tentar usar um ID de página existente, receberá um erro de compilação. ## Criação de uma nova página Saiba como criar uma nova página e atualizar o sumário do guia. ### Criar metadados da página 1. Determine o título da página e o título curto da página. O título curto da página é opcional, mas recomendado se o título da página tiver mais do que algumas palavras. 1. Determine o ID da página. Isso deve ser exclusivo no Guia de Melhores Práticas do EKS. A convenção é usar todas as palavras em minúsculas e separar com. `-` 1. Crie um novo arquivo asciidoc, em uma pasta, se necessário, e adicione o seguinte texto ao arquivo: **Example** [.” tópico "] [\$1] = :info\$1titleabbrev: < > page-short-title Por exemplo, **Example** [.” topic "] [\$1scalability] = Melhores práticas de escalabilidade do EKS:info\$1titleabbrev: Escalabilidade ### Adicionar ao índice 1. Abra o arquivo da página principal no sumário. Para novas seções do guia de nível superior, o arquivo principal é`book.adoc`. 1. Na parte inferior do arquivo pai, atualize e insira a seguinte diretiva: **Example** incluem: [leveloffset=\$11] Por exemplo, **Example** inclui: :dataplane.adoc [leveloffset=\$11] ## Inserir uma imagem 1. Encontre o prefixo da imagem para a página que você está editando. Revise a `:imagesdir:` propriedade no cabeçalho do arquivo. Por exemplo, ``:imagesdir: images/reliability/` 1. Coloque sua imagem nesse caminho, como `latest/bpg/images/reliability` 1. Determine o texto alternativo apropriado para sua imagem. Escreva uma breve descrição de alto nível da imagem. Por exemplo, “diagrama da VPC com três zonas de disponibilidade” é o texto alternativo apropriado. 1. Atualize o exemplo a seguir com o texto alternativo e o nome do arquivo de imagem. Insira no local desejado. **Example** imagem: [< image-alt-text >] Por exemplo, **Example** imagem: eks-data-plane-connectivity .jpeg [Diagrama de rede] ## Verifique o estilo com a Vale 1. [Instale o Vale CLI.](https://vale.sh/docs/vale-cli/installation/) 1. Executar `vale sync` 1. Instale a [extensão Vale](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode) a partir do Visual Studio Marketplace. 1. Reinicie o VS Code e abra um AsciiDoc arquivo 1. O VS Code sublinha o texto problemático. Aprenda a trabalhar com [erros e avisos](https://code.visualstudio.com/docs/editor/editingevolved#_errors-warnings) nos documentos do VS Code. ## Crie uma prévia local 1. Instale a `asciidoctor` ferramenta usando `brew` no Linux ou no macOS + Saiba como [instalar o asciidoctor cli](https://docs.asciidoctor.org/asciidoctor/latest/install/) nos documentos. AsciiDoctor + Saiba como [instalar o gerenciador de pacotes brew](https://brew.sh/index.html). 1. Abra um terminal e navegue até `latest/bpg/` 1. Executar `asciidoctor book.adoc` + Revise todos os avisos e erros de sintaxe 1. Abra o arquivo `book.html` de saída. + No macOS, você pode executar `open book.html` para abrir a visualização prévia no seu navegador padrão. ## AsciiDoc Folha de dicas ### Formatação básica ``` *bold text* _italic text_ `monospace text` ``` ### Cabeçalhos ``` = Document Title (Header 1) == Header 2 === Header 3 ==== Header 4 ===== Header 5 ====== Header 6 ``` ### Listas Listas não ordenadas: ``` - Item 1 - Item 2 -- Subitem 2.1 -- Subitem 2.2 - Item 3 ``` Listas ordenadas: ``` . First item . Second item .. Subitem 2.1 .. Subitem 2.2 . Third item ``` ### Links ``` External link: https://example.com[Link text] Internal link: <> Internal link: xref:page-id[Link text] ``` ### Imagens ``` image::image-file.jpg[Alt text] ``` ### Blocos de código ``` [source,python] ---- def hello_world(): print("Hello, World!") ---- ``` ### Tabelas [Aprenda a desenvolver uma tabela básica.](https://docs.asciidoctor.org/asciidoc/latest/tables/build-a-basic-table/) ``` [cols="1,1"] |=== |Cell in column 1, row 1 |Cell in column 2, row 1 |Cell in column 1, row 2 |Cell in column 2, row 2 |Cell in column 1, row 3 |Cell in column 2, row 3 |=== ``` ### Advertências ``` NOTE: This is a note admonition. WARNING: This is a warning admonition. TIP: This is a tip admonition. IMPORTANT: This is an important admonition. CAUTION: This is a caution admonition. ``` Versão prévia: **nota** Esta é uma advertência do tipo nota. ### Inclui ``` include::filename.adoc[] ```