Contribución mediante GitHub Codespaces

GitHub tiene una característica denominada Codespaces que puede usar para contribuir a la documentación de PowerShell sin tener que instalar ni configurar ningún software localmente. Cuando se usa un espacio de código, se obtienen las mismas herramientas de creación que usa el equipo para escribir y editar.

Puede usar un espacio de código en el navegador, realizando sus contribuciones en VS Code hospedado a través de Internet. Si tiene VS Code instalado localmente, también puede conectarse al codespace.

Herramientas disponibles

Cuando se usa un espacio de código para contribuir a la documentación de PowerShell, el editor ya tiene estas herramientas disponibles para usted:

  • Markdownlint para comprobar la sintaxis de Markdown.
  • cSpell para revisar la ortografía.
  • Vale para comprobar su prose.
  • Learn Authoring Pack para insertar sintaxis específica de la plataforma, obtener una vista previa de la contribución, etc.
  • La extensión Reflow Markdown para ajustar Markdown según sea necesario, lo que facilita la lectura y edición.
  • La extensión Formateador de tabla para hacer que las tablas sean más legibles sin tener que alinear manualmente las columnas.
  • La extensión change-case para convertir las mayúsculas y minúsculas de los títulos y la prosa.
  • La extensión de GitLens para revisar los cambios históricos de los archivos.
  • La extensión de PowerShell para interactuar y crear ejemplos de PowerShell.
  • El rastreador de Gremlins para Visual Studio Code para encontrar caracteres problemáticos en Markdown.

Costos

GitHub Codespaces se puede usar de forma gratuita hasta 120 horas de CPU al mes. El uso mensual se calcula en todos los repositorios, no solo en la documentación.

Para más información sobre los precios, consulte Acerca de la facturación de GitHub Codespaces.

Sugerencia

Si está familiarizado con el uso de contenedores y Docker, puede obtener la misma experiencia mediante el devcontainer definido para los repositorios de documentación de PowerShell. No hay ningún costo asociado al uso de devcontainers. Para obtener más información, consulte el tutorial Dev Containers.

Creación de gitHub Codespace

Para crear gitHub Codespace para contribuir a la documentación de PowerShell, siga estos pasos:

  1. Abra https://github.com/codespaces en el explorador.
  2. Seleccione el botón "Nuevo espacio de código" en la parte superior derecha de la página.
  3. En la página "Crear un nuevo espacio de código", seleccione el botón "Seleccionar un repositorio" y escriba el nombre del repositorio al que desea contribuir, como MicrosoftDocs/PowerShell-Docs.
  4. Deje el resto de la configuración como valor predeterminado.
  5. Seleccione el botón "Crear espacio de código".

Después de seguir estos pasos, GitHub crea un nuevo espacio de código para ese repositorio y lo configura automáticamente. Cuando el espacio de código esté listo, la página se actualiza y muestra la interfaz de usuario del editor web para el espacio de código. La interfaz de usuario se basa en VS Code y funciona de la misma manera.

Apertura de un GitHub Codespace

Para abrir GitHub Codespace en el explorador, siga estos pasos:

  1. Abra https://github.com/codespaces en el explorador.
  2. En la página se enumeran los espacios de código. Busque el espacio de código creado para el repositorio al que desea contribuir y selecciónelo.

Después de seleccionar el espacio de código, GitHub lo abre en la misma ventana. Desde aquí, estás listo para contribuir.

Para abrir GitHub Codespace en VS Code, siga los pasos descritos en Uso de GitHub Codespaces en Visual Studio Code.

Edición en el GitHub Codespace

Una vez que gitHub Codespace esté abierto en el explorador o VS Code, la contribución a la documentación sigue el mismo proceso.

En el resto de este artículo se describe una selección de tareas que puede realizar en El espacio de código de GitHub al escribir o editar su contribución.

Cuando desee convertir un vínculo insertado, como [some text](destination.md), en un vínculo de referencia como [some text][01], seleccione el destino del vínculo en el editor. A continuación, puede hacer lo siguiente:

  1. Haga clic con el botón derecho en el destino del vínculo y seleccione "Refactorizar..." en el menú contextual.
  2. Prensa Ctrl+Shift+R.

Cualquiera de las acciones genera el menú contextual de refactorización. Para reemplazar (destination.md) en el vínculo por [def], seleccione Extraer a la definición del vínculo en el menú contextual. Puede cambiar el nombre de la definición escribiendo un nuevo nombre.

Para la documentación de PowerShell, se usan definiciones de vínculo de referencia numérica de dos dígitos, como [01] o [31]. Usa solo las definiciones de vínculo de referencia en artículos y documentación conceptual. No use definiciones de vínculo de referencia en la documentación de referencia del cmdlet.

Solucionar infracciones del estilo de la prosa

Al revisar un artículo en el codespace, Vale comprueba automáticamente el artículo cuando lo abra por primera vez y cada vez que lo guarde. Si Vale encuentra alguna infracción de estilo, las resalta en el documento con subrayados ondulados de color.

Mantenga el puntero sobre una infracción para ver más información sobre ella.

Para abrir una página web que explique la regla, seleccione el nombre de la regla en la información del puntero. Para abrir la regla y revisar su implementación, seleccione el nombre de archivo de la regla (que termina en .yml).

Si la regla admite una corrección rápida, puede seleccionar "Corrección rápida..." en la información del puntero de la infracción y aplique una de las correcciones sugeridas seleccionándola en el menú contextual. También puede presionar Ctrl+. Cuando el cursor está en un problema resaltado para aplicar una corrección rápida si la regla lo admite.

Si la regla no admite correcciones rápidas, lea el mensaje de la regla y corrija si es posible. Si no está seguro de cómo corregirlo, los editores pueden hacer una sugerencia al revisar el pull request.

Corrección de problemas de sintaxis

Al revisar un artículo en el espacio de código, Markdownlint comprueba automáticamente el artículo al abrirlo y a medida que escribe. Si Markdownlint encuentra problemas de sintaxis, los resalta en el documento con ondulaciones de color.

Mantenga el puntero sobre una infracción para ver más información sobre ella. Para abrir una página web que explique la regla, seleccione el identificador de la regla en la información del puntero.

Si la regla admite una corrección rápida, puede seleccionar "Corrección rápida..." en la información del puntero de la infracción y aplique una de las correcciones sugeridas seleccionándola en el menú contextual. También puede presionar Ctrl+. Cuando el cursor está en un problema resaltado para aplicar una corrección rápida si la regla lo admite.

Si la regla no admite correcciones rápidas, lea el mensaje de la regla y corrija si es posible. Si no está seguro de cómo corregirlo, los editores pueden hacer una sugerencia al revisar el pull request.

También puede aplicar correcciones a todas las infracciones de sintaxis de un artículo. Para ello, abra la paleta de comandos y escriba Fix all supported markdownlint violations in the document. A medida que escribe, la paleta de comandos filtra los comandos disponibles. Seleccione el comando "Corregir todas las infracciones de Markdownlint admitidas en el documento". Cuando lo hace, Markdownlint actualiza el documento para resolver las infracciones para las que tiene una corrección rápida.

Dar formato a una tabla

Para dar formato a una tabla de Markdown, coloque el cursor en la tabla de Markdown. Abra la paleta de comandos y busque el Table: Format Current comando . Al seleccionar ese comando, se actualiza el Markdown de la tabla para alinearla y rellenarla, mejorando así su legibilidad.

Convierte una tabla definida de la siguiente manera:

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

En esto:

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

Insertar una alerta

La documentación usa alertas para que la información sea más notable para un lector.

Para insertar una alerta, puede abrir la paleta de comandos y buscar el Learn: Alert comando. Al seleccionar ese comando, se abre un menú contextual. Seleccione el tipo de alerta que desea agregar. Cuando lo haces, el comando inserta el Markdown de la alerta en el punto donde está el cursor en el documento.

Hacer que un encabezado use mayúsculas y minúsculas de oraciones

Para convertir el uso de mayúsculas y minúsculas de un encabezado, resalte el texto del encabezado, excepto los símbolos iniciales # , que establecen el nivel de título. Cuando tenga el texto resaltado, abra la paleta de comandos y busque el Change case sentence comando. Cuando seleccionas ese comando, convierte el formato de mayúsculas y minúsculas del texto resaltado.

También puede usar las funciones de cambio de mayúsculas y minúsculas para cualquier texto del documento.

Abrir la paleta de comandos

Puede usar la paleta de comandos de VS Code para ejecutar muchos comandos útiles.

Para abrir la paleta de comandos en la interfaz de usuario, seleccione "Ver" en la barra de menús superior. A continuación, seleccione "Paleta de comandos..." en el menú contextual.

Para abrir la paleta de comandos con el teclado, presione la combinación de teclas para el sistema operativo:

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

Vista previa de la contribución

Para obtener una vista previa de la contribución, abra la paleta de comandos y busque el Markdown: Open Preview comando . Al seleccionar ese comando, VS Code abre una vista previa del documento activo. El estilo de la versión preliminar coincide con la plataforma Learn.

Nota:

Los vínculos relativos al sitio y entre referencias no funcionan en la versión preliminar.

Volver a distribuir el contenido

Para limitar las longitudes de línea de un párrafo de un documento, coloque el cursor en el párrafo. A continuación, abra la paleta de comandos y busque el Reflow Markdown comando . Al seleccionar el comando, actualiza las longitudes de línea del párrafo actual a la longitud configurada. Para nuestros repositorios, esa longitud es de 99 caracteres.

Al usar este comando para las citas en bloque, asegúrese de que el párrafo de la cita en bloque que está reformateando está rodeado de líneas en blanco. De lo contrario, el comando vuelve a agrupar todos los párrafos.

Precaución

No use este comando al editar acerca de los artículos. Las líneas de esos documentos no deben tener más de 80 caracteres. Actualmente no hay manera de que un repositorio configure diferentes longitudes de línea por carpeta o nombre de archivo, por lo que la reestructuración no funciona para documentos relacionados con artículos.

Revisar todos los problemas de un documento

Para revisar todas las infracciones de las reglas de estilo y sintaxis en un documento, abra la vista Problemas.

Para abrir la Vista de problemas en la interfaz de usuario, seleccione "Ver" en la barra de menús superior. A continuación, seleccione "Problemas" en el menú contextual.

Para abrir la Vista de problemas con el teclado, presione la combinación de teclas para el sistema operativo:

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

La vista Problemas muestra todos los errores, advertencias y sugerencias para el documento abierto. Seleccione un problema para desplazarse hasta él en el documento.

Puede filtrar los problemas por tipo o coincidencia de texto.

Actualización de los metadatos ms.date

Para actualizar los ms.date metadatos de un artículo, abra la paleta de comandos y busque el Learn: Update "ms.date" Metadata Value comando . Al seleccionar el comando, actualiza los metadatos a la fecha actual.

Recursos adicionales

Las tareas y comandos descritos en este artículo no cubren todo lo que puede hacer con VS Code o las extensiones instaladas.

Para obtener más información sobre el uso de VS Code, consulte estos artículos:

Para obtener más información sobre las extensiones instaladas, consulte su documentación:

  • Last updated on