Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
Contribuye a esta guía
Cualquier persona puede contribuir a la guía de mejores prácticas. La Guía de mejores prácticas de EKS está escrita en el AsciiDoc formato que aparece en GitHub.
Resumen para los colaboradores actuales
-
Ábrelo
bpg-docs.code-workspacecon VS Code para instalar automáticamente la AsciiDoc extensión. -
Obtenga más información sobre la AsciiDoc extensión
en Visual Studio Marketplace.
-
-
Los archivos fuente del sitio web de AWS Docs se almacenan en
latest/bpg -
La sintaxis es muy similar a la de markdown.
-
Revisa la referencia de sintaxis
en los AsciiDoctor documentos.
-
-
La plataforma de documentos solo se implementa.
latest/bpg/imagesCada una de las secciones de la guía tiene un enlace simbólico a este directorio. Por ejemplo,latest/bpg/networking/imagesapunta alatest/bpg/images.
Configure un entorno de edición local
Si planea editar la guía con frecuencia, configure un entorno de edición local.
Bifurca y clona el repositorio
Debe estar familiarizado con gitgithub, y los editores de texto. Para obtener información sobre cómo empezar a usar tu cuenta git ygithub, consulta la sección Cómo empezar con tu GitHub cuenta
-
Consulte la guía de mejores prácticas de EKS en GitHub
. -
Cree una bifurcación del repositorio del proyecto. Obtén información sobre cómo bifurcar un repositorio
en los GitHub documentos. -
Clona tu bifurcación del repositorio del proyecto. Aprenda a clonar su repositorio bifurcado
.
Abra el espacio de trabajo de VS Code
AWS recomienda usar Visual Studio Code de Microsoft para editar la guía. Para obtener más información sobre VS Code, consulte Descargar Visual Studio Code
-
Abra VS Code.
-
Abre el
bpg-docs.code-workspacearchivo desde el repositorio clonado. -
Si es la primera vez que abre este espacio de trabajo, acepte la solicitud para instalar la AsciiDoc extensión. Esta extensión comprueba la sintaxis de AsciiDoc los archivos y genera una vista previa en directo.
-
Navegue hasta el
latest/bpgdirectorio. Este directorio contiene los archivos fuente que se implementan en el sitio de documentación de AWS. Los archivos fuente están organizados por secciones de la guía, como «seguridad» o «redes».
Editar un archivo
-
Abre un archivo en el editor.
-
Consulta la AsciiDoc sintaxis para aprender a crear encabezados, enlaces y listas.
-
Puedes usar la sintaxis de Markdown para dar formato al texto, crear listas y encabezados. No puedes usar la sintaxis de Markdown para crear enlaces.
-
-
Abre una vista previa en vivo de la página.
-
Primero, presiona
ctrl-kocmd-k(según el teclado). En segundo lugar, pulsev. Esto abre una vista previa en vista dividida.
-
AWS sugiere usar ramas de funciones para organizar los cambios. Aprenda a crear ramas con git.
Envía una solicitud de extracción
Puedes crear una solicitud de extracción desde el GitHub sitio web o desde el GitHub cli.
Aprende a crear una solicitud de extracción a partir de una bifurcación
Obtén información sobre cómo crear una solicitud de incorporación
Usa el editor web github.dev
El editor github.dev basado en la web se basa en VS Code. Esta es una excelente manera de editar varios archivos y previsualizar el contenido sin necesidad de configuración alguna.
Tiene soporte para la AsciiDoc extensión. Puede realizar operaciones de git mediante la interfaz gráfica de usuario. El editor basado en la web no tiene un shell o terminal para ejecutar comandos.
Debe tener una GitHub cuenta. Se le pedirá que inicie sesión si es necesario.
🚀 Inicie el editor GitHub basado en la web.
Edita una sola página
Puede actualizar rápidamente páginas individuales utilizando GitHub. Cada página contiene un enlace GitHub "📝 Editar esta página en» en la parte inferior.
-
Navegue hasta la página de esta guía que desee editar
-
Haz clic en el enlace «Editar esta página en GitHub» situado en la parte inferior
-
Haz clic en el icono del lápiz de edición situado en la parte superior derecha del visor de GitHub archivos o pulsa
e -
Edita el archivo
-
Envíe los cambios mediante el botón «Confirmar cambios...». Este botón crea una solicitud GitHub de cambios. Los encargados del mantenimiento de la guía revisarán esta solicitud de extracción. Un revisor aprobará la solicitud de extracción o solicitará cambios.
Ver y configurar el ID de una página
En esta página se explica cómo ver y configurar el ID de página.
El ID de página es una cadena única que identifica cada página del sitio de documentación. Puede ver el ID de la página en la barra de direcciones del navegador cuando se encuentre en una página específica. El ID de página se usa para la URL, el nombre del archivo y para crear enlaces de referencias cruzadas.
Por ejemplo, si estás viendo esta página, la URL de la barra de direcciones del navegador tendrá un aspecto similar al siguiente:
https://docs.aws.amazon.com/view-set-page-id.html
La última parte de la URL (view-set-page-id) es el ID de la página.
Establece el ID de la página
Al crear una página nueva, debe establecer el ID de la página en el archivo fuente. El identificador de página debe ser una cadena concisa y separada por guiones que describa el contenido de la página.
-
Abre el archivo fuente de la nueva página en un editor de texto.
-
En la parte superior del archivo, añade la siguiente línea. Debe estar por encima del primer encabezado.
[#my-new-page]my-new-pageSustitúyalo por el identificador de página de la nueva página. -
Guarde el archivo.
nota
La página IDs debe ser única en todo el sitio de documentación. Si intentas usar un identificador de página existente, aparecerá un error de compilación.
Cómo crear una nueva página
Obtén información sobre cómo crear una página nueva y actualizar el índice de la guía.
Crea metadatos de página
-
Determine el título de la página y el título abreviado de la página. El título abreviado de la página es opcional, pero se recomienda si el título de la página tiene más de unas pocas palabras.
-
Determina el identificador de la página. Debe ser exclusivo de la Guía de mejores prácticas de EKS. La convención es usar todas las minúsculas y separar las palabras con.
- -
Cree un nuevo archivo asciidoc, en una carpeta si es necesario, y añada el siguiente texto al archivo:
[.» tema "] [#<page-id>] = <page-title>:info_titleabbrev: < > page-short-title
Por ejemplo:
[.» topic "] [#scalability] = Mejores prácticas de escalabilidad de EKS: info_titleabbrev: Escalabilidad
Añadir a la tabla de contenido
-
Abra el archivo de la página principal en la tabla de contenido. Para las nuevas secciones de la guía de nivel superior, el archivo principal es
book.adoc. -
En la parte inferior del archivo principal, actualice e inserte la siguiente directiva:
incluye: <new-filename>[leveloffset=+1]
Por ejemplo,
include: :dataplane.adoc [leveloffset=+1]
Inserta una imagen
-
Busca el prefijo de imagen de la página que estás editando. Revise la
:imagesdir:propiedad del encabezado del archivo. Por ejemplo,`:imagesdir: images/reliability/ -
Coloca la imagen en esta ruta, por ejemplo
latest/bpg/images/reliability -
Determina el texto alternativo adecuado para tu imagen. Escribe una breve descripción de alto nivel de la imagen. Por ejemplo, «diagrama de VPC con tres zonas de disponibilidad» es un texto alternativo adecuado.
-
Actualice el siguiente ejemplo con el texto alternativo y el nombre de archivo de la imagen. Inserte en la ubicación deseada.
imagen: <image-filename>[< image-alt-text >]
Por ejemplo:
imagen:: eks-data-plane-connectivity .jpeg [Diagrama de red]
Compruebe el estilo con Vale
-
Ejecute
vale sync -
Instale la extensión Vale
desde Visual Studio Marketplace. -
Reinicie VS Code y abra un AsciiDoc archivo
-
VS Code subraya el texto problemático. Aprenda a trabajar con errores y advertencias
en los documentos de VS Code.
Crea una vista previa local
-
Instale la
asciidoctorherramientabrewen Linux o macOS-
Aprenda a instalar asciidoctor cli
en los AsciiDoctor documentos. -
Aprenda a instalar el administrador de paquetes brew
.
-
-
Abre una terminal y navega hasta
latest/bpg/ -
Ejecute
asciidoctor book.adoc-
Revise las advertencias y los errores de sintaxis
-
-
Abra el archivo
book.htmlde salida.-
En macOS, puedes ejecutar
open book.htmlpara abrir la vista previa en tu navegador predeterminado.
-
AsciiDoc Hoja de trucos
Formato básico
*bold text*
_italic text_
`monospace text`Encabezados
= Document Title (Header 1)
== Header 2
=== Header 3
==== Header 4
===== Header 5
====== Header 6Listas
Listas sin ordenar:
- Item 1
- Item 2
-- Subitem 2.1
-- Subitem 2.2
- Item 3Listas ordenadas:
. First item
. Second item
.. Subitem 2.1
.. Subitem 2.2
. Third itemEnlaces
External link: https://example.com[Link text]
Internal link: <<page-id>>
Internal link: xref:page-id[Link text]Imágenes
image::image-file.jpg[Alt text]
Bloques de código
[source,python]
----
def hello_world():
print("Hello, World!")
----Tablas
Aprende a crear una tabla 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
|===Advertencias
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.Vista previa:
nota
Esta es una nota de advertencia.
Incluye
include::filename.adoc[]