Uso del linter de contenido

Acerca del linter de contenido de GitHub Docs

Nuestro linter de contenido aplica reglas de la guía de estilo en nuestro contenido de Markdown.

El linter usa markdownlint como marco para realizar comprobaciones, notificar errores y corregir automáticamente el contenido, siempre que sea posible. Este marco ejecuta reglas específicas de forma flexible, proporciona mensajes de error descriptivos y corrige errores. El linter de contenido de GitHub Docs usa varias reglas de markdownlint existentes y reglas personalizadas adicionales para comprobar el contenido de Markdown en nuestros directorios content y data. Nuestras reglas personalizadas implementan comprobaciones que aún no están disponibles en el marco de markdownlint o que son específicas del contenido de GitHub Docs. Las reglas comprueban la sintaxis de Markdown y Liquid.

Ejecución del linter de contenido de GitHub Docs

El linter de contenido de GitHub Docs se ejecutará automáticamente en la confirmación previa, pero también puedes ejecutarlo manualmente.

Ejecución automática del linter en la confirmación previa

Si escribes contenido localmente y utilizas la línea de comandos para confirmar archivos, el linter de contenido revisará automáticamente los archivos almacenados provisionalmente. Se notifican tanto advertencias como errores, pero solo los errores impedirán que se complete la confirmación.

Si se notifica que hay algún error, la confirmación no se completará. Tendrás que corregir los errores notificados, volver a añadir los archivos modificados y confirmar los cambios de nuevo. Todos los errores que se notifique deben corregirse para evitar que en el contenido haya errores que infrinjan la guía de estilo de GitHub Docs. Si se notifican advertencias, puedes optar por corregirlas o no.

Al escribir contenido de forma local, hay varias reglas que puedes corregir automáticamente mediante la línea de comandos. Si deseas corregir automáticamente los errores que se pueden corregir, consulta Corrección automática de los errores que se puedan corregir.

Si vas a editar un archivo en la interfaz de usuario de GitHub, no podrás corregir errores ni ejecutar de manera automática el linter en una confirmación, pero obtendrás un error de IC si el contenido infringe una regla con una gravedad de error.

Ejecución manual del linter

Ejecutar el linter en archivos almacenados provisionalmente y modificados

Usa el siguiente comando para ejecutar el linter localmente en archivos almacenados provisionalmente y modificados. Generará errores de gravedad warning y error.

npm run lint-content

Ejecutar el linter en archivos almacenados provisionalmente y modificados y solo notificar errores

Usa el siguiente comando para ejecutar el linter localmente en los archivos almacenados provisionalmente y modificados, y notificar solo los errores de gravedad error.

npm run lint-content -- --errors

Ejecutar el linter en archivos o directorios concretos

Usa el siguiente comando para ejecutar el linter localmente en archivos o directorios concretos. Separa las distintas rutas de acceso mediante espacios. Puedes incluir archivos y directorios en el mismo comando.

npm run lint-content -- \
  --paths content/FILENAME.md content/DIRECTORY

npm run lint-content -- \
  --paths content/FILENAME.md content/DIRECTORY

Corrección automática de los errores que se puedan corregir

Si la descripción de cualquier error tiene fixable: true, puedes usar los siguientes comandos para corregirlo automáticamente.

Ejecuta este comando para corregir solo archivos almacenados provisionalmente y modificados:

npm run lint-content -- --fix

Ejecuta este comando para corregir archivos o directorios concretos:

npm run lint-content -- \
  --fix --paths content/FILENAME.md content/DIRECTORY

Ejecución de un conjunto concreto de reglas del linter

Usa el siguiente comando para ejecutar una o varias reglas de linter específicas. En estos ejemplos se ejecutan las reglas heading-increment y code-fence-line-length. Reemplaza heading-increment code-fence-line-length por uno o varios alias de linter que quieras ejecutar. Para ver la lista de reglas de linter que puedes usar en esta opción, ejecuta npm run lint-content -- --help. Puedes usar el nombre corto (por ejemplo, MD001) o el nombre largo (por ejemplo, heading-increment) de una regla de linter.

Ejecuta las reglas de linter especificadas en todos los archivos almacenados provisionalmente y modificados:

npm run lint-content -- \
  --rules heading-increment code-fence-line-length

Ejecuta las reglas de linter especificadas en archivos o directorios concretos:

npm run lint-content -- \
  --rules heading-increment code-fence-line-length \
  --path content/FILENAME.md content/DIRECTORY

Omitir el enlace de confirmación

Si el linter detecta errores que no ha introducido, puede omitir el enlace de confirmación de Git mediante la opción --no-verify al confirmar los cambios.

git commit -m 'MESSAGE' --no-verify

Mostrar el menú de ayuda del script del linter de contenido

npm run lint-content -- --help

Reglas de la revisión

Cada regla se configura en un archivo de src/content-linter/style, que es donde se definen las gravedades de las reglas.

Los errores deben solucionarse antes de combinar los cambios en la rama main. Las advertencias deben solucionarse, pero no impedir que se combine un cambio en la rama main. La mayoría de las reglas se ascenderán finalmente a errores, una vez que el contenido ya no presente infracciones de advertencia.

Sintaxis para reglas de linting

Algunas reglas de linting devuelven advertencias o errores basados en comentarios HTML que puedes agregar a artículos.

Sintaxis para el contenido en proceso de expiración o expirado

Las reglas GHD038 y GHD039 comprueban el contenido para el que se ha proporcionado manualmente una fecha de expiración. Catorce días antes de la fecha especificada, el linter de contenido devolverá una advertencia de que el contenido expira pronto. A partir de la fecha especificada, el linter de contenido devolverá un error y marcará el contenido para la corrección.

Puedes agregar una fecha de expiración al contenido si la encapsulas en etiquetas HTML que contengan una fecha de expiración con el siguiente formato: <!-- expires yyyy-mm-dd --> <!-- end expires yyyy-mm-dd -->

Use:

This content does not expire.
<!-- expires 2022-01-28 -->
This content expires on January 28, 2022.
<!-- end expires 2022-01-28 -->
This content also does not expire.

Tenga en cuenta que, si va a colocar las etiquetas expiradas en un elemento HTML table, asegúrese de que la etiqueta rodea toda la fila y no solo la celda. Por ejemplo:

<!-- expires 2024-06-28 -->
<tr>
<td>
macOS
</td>
<td>
The <code>macos-11</code> label is en desuso and will no longer be available after 28 June 2024.
</td>
</tr>
<!-- end expires 2024-06-28 -->

Supresión de reglas de linter

Ocasionalmente, es posible que tenga que documentar algo que infringe una o varias reglas de linter. En estos casos, puede suprimir reglas agregando un comentario al archivo Markdown. Puede deshabilitar todas las reglas o reglas específicas. Intente limitar siempre la menor cantidad de reglas que sea posible. Puedes deshabilitar una regla para un archivo completo, para una sección de un archivo Markdown, una línea específica o la línea siguiente.

Por ejemplo, si estás escribiendo un artículo que incluye la expresión regular (^|/)[Cc]+odespace/ que comprueba si hay sintaxis de vínculo invertido, esta desencadenará la regla MD011 que comprueba si hay vínculos invertidos. Puedes deshabilitar la regla MD011 en esa línea específica si agregas el comentario siguiente.

(^|/)[Cc]+odespace/ <!-- markdownlint-disable-line MD011 -->

Si la línea que intentas omitir está en un bloque de código, puedes omitir el bloque de código al rodearlo con los siguientes comentarios.

<!-- markdownlint-disable MD011 -->
```
(^|/)[Cc]+odespace/
```
<!-- markdownlint-enable MD011 -->

Puede usar estos comentarios para habilitar o deshabilitar reglas.