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
bpg-docs.code-workspacecom o VS Code para instalar automaticamente a AsciiDoc extensão. -
Saiba mais sobre a AsciiDoc extensão
no Visual Studio Marketplace.
-
-
Os arquivos de origem do site do AWS Docs são armazenados em
latest/bpg -
A sintaxe é muito semelhante ao markdown.
-
Analise a referência de sintaxe
nos AsciiDoctor documentos.
-
-
A plataforma docs só é
latest/bpg/imagesimplantada. Cada uma das seções do guia tem um link simbólico para esse diretório. Por exemplo,latest/bpg/networking/imagesaponta paralatest/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 comgit,github, e editores de texto. Para obter informações sobre como começar a usar git egithub, consulte Introdução à sua GitHub conta
-
Crie uma bifurcação do repositório do projeto. Saiba como bifurcar um repositório
nos GitHub documentos. -
Clone sua bifurcação do repositório do projeto. Saiba como clonar seu repositório bifurcado
.
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
-
Abra o VS Code.
-
Abra o
bpg-docs.code-workspacearquivo do repositório clonado. -
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.
-
Navegue até o
latest/bpgdiretó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
-
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.
-
-
Abra uma pré-visualização ao vivo da página.
-
Primeiro, pressione
ctrl-koucmd-k(dependendo do teclado). Em segundo lugar, pressionev. 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
Saiba como criar uma pull request
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.
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.
-
Navegue até a página deste guia que você deseja editar
-
Clique no link “Editar esta página em GitHub” na parte inferior
-
Clique no ícone de lápis de edição no canto superior direito do visualizador de GitHub arquivos ou pressione
e -
Edite o arquivo
-
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.
-
Abra o arquivo de origem da sua nova página em um editor de texto.
-
Na parte superior do arquivo, adicione a seguinte linha. Deve estar acima do primeiro título.
[#my-new-page]my-new-pageSubstitua pelo ID da página da sua nova página. -
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
-
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.
-
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.
- -
Crie um novo arquivo asciidoc, em uma pasta, se necessário, e adicione o seguinte texto ao arquivo:
[.” tópico "] [#<page-id>] = <page-title>:info_titleabbrev: < > page-short-title
Por exemplo,
[.” topic "] [#scalability] = Melhores práticas de escalabilidade do EKS:info_titleabbrev: Escalabilidade
Adicionar ao índice
-
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. -
Na parte inferior do arquivo pai, atualize e insira a seguinte diretiva:
incluem: <new-filename>[leveloffset=+1]
Por exemplo,
inclui: :dataplane.adoc [leveloffset=+1]
Inserir uma imagem
-
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/ -
Coloque sua imagem nesse caminho, como
latest/bpg/images/reliability -
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.
-
Atualize o exemplo a seguir com o texto alternativo e o nome do arquivo de imagem. Insira no local desejado.
imagem: <image-filename>[< image-alt-text >]
Por exemplo,
imagem: eks-data-plane-connectivity .jpeg [Diagrama de rede]
Verifique o estilo com a Vale
-
Executar
vale sync -
Instale a extensão Vale
a partir do Visual Studio Marketplace. -
Reinicie o VS Code e abra um AsciiDoc arquivo
-
O VS Code sublinha o texto problemático. Aprenda a trabalhar com erros e avisos
nos documentos do VS Code.
Crie uma prévia local
-
Instale a
asciidoctorferramenta usandobrewno Linux ou no macOS-
Saiba como instalar o asciidoctor cli
nos documentos. AsciiDoctor -
Saiba como instalar o gerenciador de pacotes brew
.
-
-
Abra um terminal e navegue até
latest/bpg/ -
Executar
asciidoctor book.adoc-
Revise todos os avisos e erros de sintaxe
-
-
Abra o arquivo
book.htmlde saída.-
No macOS, você pode executar
open book.htmlpara 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 6Listas
Listas não ordenadas:
- Item 1
- Item 2
-- Subitem 2.1
-- Subitem 2.2
- Item 3Listas ordenadas:
. First item
. Second item
.. Subitem 2.1
.. Subitem 2.2
. Third itemLinks
External link: https://example.com[Link text]
Internal link: <<page-id>>
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.
[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[]