Contribuya usando GitHub Codespaces

GitHub tiene una función llamada Codespaces que puedes usar para contribuir a la documentación de PowerShell sin tener que instalar o configurar ningún software localmente. Cuando usas un espacio de código, obtienes las mismas herramientas de creación que usa el equipo para escribir y editar.

Puedes utilizar un codespace en tu navegador, realizando tus contribuciones en VS Code alojado en Internet. Si tiene VS Code instalado localmente, también puede conectarse al codespace allí.

Herramientas disponibles

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

• Markdownlint para comprobar la sintaxis de Markdown.
• cSpell para revisar tu ortografía.
• Vale por comprobar tu prosa.
• El paquete de creación de aprendizaje para insertar sintaxis específica de la plataforma, obtener una vista previa de su contribución y más.
• La extensión Reflow Markdown para ajustar su Markdown según sea necesario, facilitando la lectura y edición.
• La extensión Table Formatter para hacer que sus tablas sean más legibles sin tener que alinear columnas manualmente.
• La extensión de cambio de mayúsculas y minúsculas para convertir las mayúsculas y minúsculas de sus títulos y prosa.
• La extensión GitLens para revisar cambios históricos de archivos.
• La extensión de PowerShell para interactuar con ejemplos de creación de PowerShell.
• El rastreador de Gremlins para Visual Studio Code para encontrar caracteres problemáticos en Markdown.

Costo

Los GitHub Codespaces se pueden utilizar de forma gratuita hasta 120 horas centrales por mes. Con la configuración que recomendamos en este artículo, eso significa hasta 60 horas de uso gratuito por mes. El uso mensual se calcula en todos sus repositorios, no solo en la documentación.

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

Creando tu espacio de código GitHub

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

1. Abra https://github.com/codespaces en su navegador.
2. Selecciona 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 todas las demás configuraciones como predeterminadas.
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 por usted. Cuando el codespace está listo, la página se actualiza y muestra la interfaz de usuario del editor web para el codespace. La interfaz de usuario se basa en VS Code y funciona de la misma manera.

Abriendo tu espacio de código GitHub

Para abrir tu GitHub Codespace en el navegador, sigue estos pasos:

1. Abra https://github.com/codespaces en su navegador.
2. La página enumera sus 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 su espacio de código, GitHub lo abre en la misma ventana. Desde aquí, estás listo para contribuir.

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

Creación en tu Codespace de GitHub

Una vez que tenga su GitHub Codespace abierto en su navegador o VS Code, contribuir a la documentación sigue el mismo proceso.

El resto de este artículo describe una selección de tareas que puedes realizar en tu GitHub Codespace mientras escribes o editas tu contribución.

Extraer un enlace de referencia

Cuando desee convertir un enlace en línea, como [some text](destination.md), en un enlace de referencia como [some text][01], seleccione el enlace destino en el editor. Entonces puedes:

1. Haga clic derecho en el destino del enlace y seleccione "Refactor..." en el menú contextual.
2. Presione Ctrl+Mayús+R.

Cualquiera de las acciones abre el menú contextual de refactorización. Seleccione "Extraer para vincular definición" en el menú contextual. Esto reemplaza (destination.md) en el enlace con [def]. Puede cambiar el nombre de la definición escribiendo un nombre.

Para la documentación de PowerShell, utilizamos definiciones de enlaces de referencia numéricas de dos dígitos, como [01] o [31]. Utilice únicamente definiciones de enlaces de referencia en temas relacionados y documentación conceptual. No utilice definiciones de vínculos de referencia en la documentación de referencia de cmdlets.

Corregir violaciones de estilo de prosa

Cuando revisas un artículo en tu codespace, Vale verifica automáticamente el artículo cuando lo abres por primera vez y cada vez que lo guardas. Si Vale encuentra alguna violación de estilo, la resalta en el documento con garabatos de colores.

Pase el cursor sobre una infracción para ver más información al respecto.

Seleccione el nombre de la regla en la información emergente para abrir una página web que explica la regla. Seleccione el nombre de archivo de la regla (que termina en .yml) para abrir la regla y revisar su implementación.

Si la regla admite una solución rápida, puede seleccionar "Solución rápida..." en la información sobre la infracción y aplicar una de las soluciones sugeridas seleccionándola en el menú contextual. También puede presionar Ctrl+. cuando el cursor esté sobre un problema resaltado para aplicar una solución rápida si la regla lo admite.

Si la regla no admite soluciones rápidas, lea el mensaje de la regla y corríjala si puede. Si no está seguro de cómo solucionarlo, los editores pueden hacer una sugerencia al revisar su PR.

Solucionar problemas de sintaxis

Cuando revisas un artículo en tu codespace, Markdownlint verifica automáticamente el artículo cuando lo abres y mientras escribes. Si Markdownlint encuentra algún problema de sintaxis, lo resalta en el documento con garabatos de colores.

Pase el cursor sobre una infracción para ver más información al respecto.

Seleccione el ID de la regla en la información emergente para abrir una página web que explica la regla.

Si la regla admite una solución rápida, puede seleccionar "Solución rápida..." en la información sobre la infracción y aplicar una de las soluciones sugeridas seleccionándola en el menú contextual. También puede presionar Ctrl+. cuando el cursor esté sobre un problema resaltado para aplicar una solución rápida si la regla lo admite.

Si la regla no admite soluciones rápidas, lea el mensaje de la regla y corríjala si puede. Si no está seguro de cómo solucionarlo, los editores pueden hacer una sugerencia al revisar su PR.

También puede aplicar correcciones a todas las violaciones de sintaxis en un artículo. Para hacerlo, abra la paleta de comandos y escriba Corregir todas las infracciones de Markdownlint admitidas en el documento. A medida que escribe, la paleta de comandos filtra los comandos disponibles. Seleccione el comando "Reparar todas las infracciones de Markdownlint admitidas en el documento". Cuando lo hace, Markdownlint actualiza el documento para resolver cualquier infracción para la que tenga una solución rápida.

Dar formato a una tabla

Para formatear una tabla de Markdown, coloque el cursor dentro o sobre la tabla en su Markdown. Abra la paleta de comandos y busque el comando Tabla: Formatear actual. Cuando selecciona ese comando, actualiza el Markdown de su tabla para alinear y rellenar la tabla para mejorar la legibilidad.

Convierte una tabla definida así:

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

En esto:

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

Insertar una alerta

La documentación utiliza alertas para que la información sea más visible para el lector.

Para insertar una alerta, puede abrir la paleta de comandos y buscar el comando Aprender: Alerta. Cuando selecciona ese comando, se abre un menú contextual. Seleccione el tipo de alerta que desea agregar. Cuando lo hace, el comando inserta el Markdown de la alerta en el cursor del documento.

Hacer un encabezado usando mayúsculas y minúsculas

Para convertir las mayúsculas y minúsculas de un encabezado, resalte el texto del encabezado excepto los símbolos # iniciales, que establecen el nivel del encabezado. Cuando tenga el texto resaltado, abra la paleta de comandos y busque el comando Cambiar frase entre mayúsculas y minúsculas. Cuando selecciona ese comando, convierte las mayúsculas y minúsculas del texto resaltado.

También puede utilizar los comandos de mayúsculas y minúsculas para cualquier texto del documento.

Abra la paleta de comandos

Puede utilizar 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ú superior. Luego seleccione "Paleta de comandos..." en el menú contextual.

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

• Windows y Linux: Ctrl+Mayús+P
• macOS: Cmd+Mayús+P

Vista previa de su contribución

Para obtener una vista previa de su contribución, abra la paleta de comandos y busque el comando Markdown: Abrir vista previa. Cuando selecciona ese comando, VS Code abre una vista previa del documento activo. El estilo de la vista previa coincide con la plataforma Learn.

Redistribuye tu contenido

Para limitar la longitud de las líneas de un párrafo de un documento, coloque el cursor en el párrafo. Luego abra la paleta de comandos y busque el comando Reflow Markdown. Cuando selecciona el comando, actualiza la longitud de línea del párrafo actual a la longitud configurada. Para nuestros repositorios, esa longitud es de 99 caracteres.

Cuando utilice este comando para citas en bloque, asegúrese de que el párrafo de la cita en bloque que está redistribuyendo esté rodeado de líneas en blanco. De lo contrario, el comando redistribuye todos los párrafos juntos.

Revisar todos los problemas en un documento.

Para revisar todas las violaciones de reglas de estilo y sintaxis en un documento, abra la Vista de problemas.

Para abrir la Vista de problemas en la interfaz de usuario, seleccione "Ver" en la barra de menú superior. Luego seleccione "Problemas" en el menú contextual.

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

• Windows y Linux: Ctrl+Mayús+M
• macOS: Cmd+Mayús+M

La Vista de 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 de ms.date

Para actualizar los metadatos ms.date de un artículo, abra la paleta de comandos y busque el comando Aprender: Actualizar valor de metadatos "ms.date". Cuando selecciona 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:

• Consejos y trucos sobre el código de Visual Studio
• Edición básica
• Usando el control de fuente Git en VS Code
• Código de rebajas y Visual Studio

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

• caso de cambio
• GitLens
• Rastreador de Gremlins para Visual Studio Code
• Paquete de aprendizaje de creación
• rebajas
• Rebaja de reflujo
• Formateador de tablas