# Uso del linter de contenido El linter de contenido lo puedes usar para comprobar si hay errores en las contribuciones que realices. ## 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`](https://github.com/DavidAnson/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 ejecuta automáticamente con la preconfirmación, 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](#automatically-fix-errors-that-can-be-fixed). Si editas un archivo en la interfaz de usuario de GitHub, no podrás corregir errores automáticamente ni ejecutar el linter en un commit, pero obtendrás un fallo de CI si el contenido infringe alguna 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`. ```shell 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`. ```shell 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. ```shell copy 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: ```shell npm run lint-content -- --fix ``` Ejecuta este comando para corregir archivos o directorios concretos: ```shell 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: ```shell npm run lint-content -- \ --rules heading-increment code-fence-line-length ``` Ejecuta las reglas de linter especificadas en archivos o directorios concretos: ```shell 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. ```shell git commit -m 'MESSAGE' --no-verify ``` ### Mostrar el menú de ayuda del script del linter de contenido ```shell npm run lint-content -- --help ``` ## Reglas de la revisión Cada regla se configura en un archivo de [`src/content-linter/style`](https://github.com/github/docs/tree/main/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. | Id. de regla | Nombres de la regla | Descripción | severity | Etiquetas | | ------- | ------------ | ----------- | -------- | ---- | | [MD001](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md001.md) | incremento de encabezado | Los niveles de título solo deben incrementarse en un nivel a la vez | error | encabezados | | [MD011](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md011.md) | no-reversed-links | Sintaxis de vínculo invertido | error | vínculos | | [MD014](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md014.md) | commands-show-output | Signos de dólar usados antes de los comandos sin mostrar la salida | error | código | | [MD018](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md018.md) | no-missing-space-atx | Sin espacio después del hash en el título de estilo atx | error | encabezados, atx, espacios | | [MD019](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md019.md) | no-multiple-space-atx | Varios espacios después del hash en el título de estilo atx | error | encabezados, atx, espacios | | [MD023](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md023.md) | heading-start-left | Los encabezados deben comenzar al principio de la línea | error | encabezados, espacios | | [MD027](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md027.md) | no-multiple-space-blockquote | Varios espacios después del símbolo de blockquote | error | blockquote, espacio en blanco, sangría | | [MD029](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md029.md) | ol-prefix | Prefijo de elemento de lista ordenado | error | ol | | [MD030](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md030.md) | list-marker-space | Espacios después de marcadores de lista | error | ol, ul, espacio en blanco | | [MD031](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md031.md) | blanks-around-fences | Los bloques de código delimitados deben estar rodeados por líneas en blanco | error | código, blank_lines | | [MD037](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md037.md) | no-space-in-emphasis | Espacios dentro de marcadores de énfasis | error | espacio en blanco, énfasis | | [MD039](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md039.md) | no-space-in-links | Espacios dentro del texto del vínculo | error | espacios en blanco, vínculos | | [MD040](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md040.md) | fenced-code-language | Los bloques de código delimitados deben tener un lenguaje especificado | error | código, lenguaje | | [MD042](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md042.md) | no-empty-links | No hay vínculos vacíos | error | vínculos | | [MD050](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md050.md) | strong-style | Estilo strong | error | emphasis | | [GH001](https://github.com/github/markdownlint-github/blob/main/docs/rules/GH001-no-default-alt-text.md) | no-default-alt-text | Las imágenes deben tener texto alternativo significativo (texto alternativo) | error | accesibilidad, imágenes | | [GH002](https://github.com/github/markdownlint-github/blob/main/docs/rules/GH002-no-generic-link-text.md) | no-generic-link-text | Evita usar texto de vínculo genérico como `Learn more` o `Click here` | error | accesibilidad, vínculos | | GHD001 | link-punctuation | Los títulos de vínculos internos no deben contener signos de puntuación | error | vínculos, url | | GHD002 | internal-links-no-lang | Los vínculos internos no deben tener un código de lenguaje codificado de forma rígida | error | vínculos, url | | GHD003 | internal-links-slash | Los vínculos internos deben comenzar con / | error | vínculos, url | | GHD004 | image-file-kebab-case | Los nombres de archivo de imagen deben usar kebab-case | error | images | | GHD005 | hardcoded-data-variable | Las cadenas que contienen «token de acceso personal» deben usar la variable de producto en su lugar | error | single-source | | GHD006 | internal-links-old-version | Los vínculos internos no deben tener una versión codificada de forma rígida mediante la sintaxis de control de versiones anterior | error | vínculos, url, control de versiones | | GHD007 | code-annotations | Las anotaciones de código definidas en Markdown deben contener una propiedad de texto preliminar de diseño específica | error | código, característica, anotar, texto preliminar | | GHD008 | early-access-references | Los archivos que no son de acceso anticipado no deben hacer referencia a archivos de acceso anticipado o de acceso anticipado | error | característica, acceso anticipado | | GHD009 | frontmatter-early-access-references | Los archivos que no son de acceso anticipado no deben tener una instancia de texto preliminar que haga referencia al acceso anticipado | error | preliminares, característica, acceso anticipado | | GHD010 | frontmatter-hidden-docs | Los artículos con la propiedad de texto preliminar `hidden` solo se pueden encontrar en productos específicos | error | preliminares, característica, acceso anticipado | | GHD012 | frontmatter-schema | El texto preliminar debe cumplir el esquema | error | texto preliminar, esquema | | GHD013 | github-owned-action-references | Las referencias de acción pertenecientes a GitHub no deben codificarse de forma fija | error | características, acciones | | GHD014 | liquid-data-references-defined | Se encontraron referencias a datos de Liquid o datos con sangría en el contenido que no tienen ningún valor o que no existen en el directorio de datos | error | Liquid | | GHD015 | liquid-data-tag-format | Los datos de Liquid o las etiquetas de referencia de datos con sangría deben formatearse correctamente y tener el número correcto de argumentos y espaciado | error | liquid, formato | | GHD016 | liquid-quoted-conditional-arg | Las etiquetas condicionales de Liquid no deben citar el argumento condicional | error | liquid, formato | | GHD017 | frontmatter-liquid-syntax | Las propiedades de texto preliminar deben usar Liquid válido | error | liquid, texto preliminar | | GHD018 | liquid-syntax | El contenido de Markdown debe usar Liquid válido | error | Liquid | | GHD019 | liquid-if-tags | Las etiquetas `ifversion` de Liquid se deben usar en lugar de etiquetas `if` cuando el argumento es una versión válida | error | liquid, control de versiones | | GHD020 | liquid-ifversion-tags | Las etiquetas de Liquid `ifversion` deben contener nombres de versión válidos como argumentos | error | liquid, control de versiones | | GHD021 | yaml-scheduled-jobs | Los fragmentos de código YAML que incluyen flujos de trabajo programados no deben ejecutarse en la hora y deben ser únicos | error | características, acciones | | GHD022 | liquid-ifversion-versions | Las etiquetas Liquid `ifversion`, `elsif` y `else` deben ser válidas y no contener versiones no admitidas. | error | liquid, control de versiones | | GHD031 | image-alt-text-exclude-words | El texto alternativo de las imágenes no debe comenzar con palabras como «imagen» o «gráfico» | error | accesibilidad, imágenes | | GHD032 | image-alt-text-end-punctuation | El texto alternativo de las imágenes deben terminar con una puntuación | error | accesibilidad, imágenes | | GHD033 | incorrect-alt-text-length | El texto alternativo de las imágenes debe tener entre 40 y 150 caracteres | error | accesibilidad, imágenes | | GHD034 | frontmatter-curly-quotes | El título y la introducción del frontmatter no deben contener comillas rizadas. | error | material preliminar, formato | | GHD035 | rai-reutilizable-usage | Los artículos rai y los reutilizables solo pueden hacer referencia al contenido reutilizable en el directorio de datos/reutilizables/rai. | error | función, rai | | GHD036 | image-no-gif | La imagen no debe ser una referencia gif, styleguide: contributing/style-guide-and-content-model/style-guide.md#images | error | images | | GHD038 | expired-content | Se debe corregir el contenido expirado. | advertencia | expired | | GHD039 | expiring-soon | El contenido que expira pronto debe abordarse de forma proactiva. | advertencia | expired | | GHD040 | table-liquid-versioning | Las tablas deben usar el formato de control de versiones de Liquid correcto | error | tablas | | GHD041 | third-party-action-pinning | Los ejemplos de código que usan acciones de terceros siempre deben anclarse a un SHA de confirmación de longitud completa | error | características, acciones | | GHD042 | liquid-tag-whitespace | Las etiquetas de Liquid deben comenzar y terminar con un espacio en blanco. Los argumentos de etiqueta de Liquid solo deben estar separados por un espacio en blanco. | error | liquid, formato | | GHD043 | link-quotation | Los títulos de vínculo internos no deben estar entre comillas | error | vínculos, url | | GHD045 | code-annotation-comment-spacing | Los comentarios de código de los bloques de anotación deben tener exactamente un espacio después de los caracteres de comentario | error | código, comentarios, anotar, espacios | | GHD046 | outdated-release-phase-terminology | La terminología de la fase de versión obsoleta debe reemplazarse por la terminología actual de GitHub | error | terminología, coherencia, fases de versión | | GHD047 | table-column-integrity | Las tablas deben tener recuentos de columnas coherentes en todas las filas | error | tablas, accesibilidad, formato | | GHD051 | frontmatter-versions-whitespace | Las versiones de frontmatter no deben contener espacios en blanco innecesarios | error | frontmatter, versiones | | GHD054 | third-party-actions-reusable | Los ejemplos de código con acciones de terceros deben incluir declinación de responsabilidades reutilizables | error | acciones, reutilizables, de terceros | | GHD056 | frontmatter-landing-carousels | Solo las páginas de aterrizaje pueden tener carruseles, no debe haber artículos duplicados y todos los artículos deben existir. | error | frontmatter, página de destino, carruseles | | GHD057 | ctas-schema | Las direcciones URL de CTA deben cumplir el esquema | error | CTA, esquema, URL | | GHD058 | journey-tracks-liquid | Las propiedades de seguimiento de recorrido deben usar la sintaxis Liquid válida | error | material preliminar, rutas de viaje, líquido | | GHD059 | journey-tracks-guide-path-exists | Las rutas de acceso de la guía de seguimiento del recorrido deben hacer referencia a los archivos de contenido existentes | error | prefacio, rutas de proceso | | GHD060 | journey-tracks-unique-ids | Los identificadores de seguimiento de recorrido deben ser únicos dentro de una página | error | frontmatter, journey-tracks, identificadores-unicos | | GHD061 | frontmatter-hero-image | Las rutas de imagen de Hero deben ser absolutas, sin extensión y apuntar a imágenes válidas en /assets/images/banner-images/ | error | frontmatter, imágenes | | GHD062 | frontmatter-intro-links | las claves introLinks deben ser claves válidas definidas en data/ui.yml bajo product_landing | error | frontmatter, origen único | | GHD063 | frontmatter-children | Deben existir rutas de frontmatter secundarias. Admite rutas de acceso relativas y rutas de acceso absolutas /content/ para la inclusión cruzada entre productos. | error | cabecera, componentes hijos | | GHD064 | rai-app-card-structure | Los artículos de tarjetas de plataforma o aplicación RAI deben seguir la estructura de plantilla necesaria. | error | función, rai | | GHD065 | frontmatter-content-type | Los archivos de contenido de los directorios de tipo de contenido deben tener una propiedad frontmatter contentType que coincida con el directorio primario. | error | frontmatter, tipo de contenido | | GHD066 | frontmatter-docs-team-metrics | Los artículos cuya ruta de acceso contiene un valor docsTeamMetrics aplicado a la ruta de acceso deben incluir ese valor en su propiedad frontmatter docsTeamMetrics. | error | frontmatter, docs-team-metrics | | GHD067 | frontmatter-rest-api-category | Los archivos de punto de conexión de la API REST generados automáticamente deben tener una propiedad frontmatter válida `category` . | error | metadatos de cabecera, resto, categoría | | [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | sintaxis líquida obsoleta: octicon- | La sintaxis de Liquid Octicon utilizada está en desuso. Usa este formato en lugar de `octicon "" aria-label=""` | error | | | [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | sintaxis liquida en desuso: site.data | Detectar ocurrencias de la sintaxis de datos de Liquid en desuso. | error | | | [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | developer-domain | Detectar ocurrencias del dominio developer.github.com. | error | | | [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | docs-domain | Detectar ocurrencias del dominio docs.github.com. | error | | | [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | help-domain | Detectar ocurrencias del dominio help.github.com. | error | | | [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | todocs-placeholder | Detectar ocurrencias del marcador de posición TODOCS. | error | | ### 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á una advertencia y marcará el contenido para su 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: ` ` **Use:** ```markdown This content does not expire. This content expires on January 28, 2022. 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: ```html macOS The macos-11 label is cerrar definitivamente and will no longer be available after 28 June 2024. ``` ## 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. ```text (^|/)[Cc]+odespace/ ``` 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. ````text ``` (^|/)[Cc]+odespace/ ``` ```` Puede usar estos comentarios para habilitar o deshabilitar reglas. | Comentario | Efecto | | :-- | :-- | | `` | Deshabilitar todas las reglas | | ``| Habilitar todas las reglas | | `` | Deshabilitar todas las reglas de la línea actual | | `` | Deshabilitar todas las reglas de la línea siguiente | | ``| | Deshabilitar una o varias reglas por nombre | | `` | Habilitar una o varias reglas por nombre | | `` | Deshabilitar una o varias reglas por nombre para la línea actual | | `` | Deshabilitar una o varias reglas por nombre para la línea siguiente |