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.
Identificador de la regla | Nombres de la regla | Descripción | severity | Etiquetas |
---|---|---|---|---|
MD001 | incremento de encabezado | Los niveles de título solo deben incrementarse en un nivel a la vez | error | encabezados |
MD004 | ul-style | Estilo de listas sin ordenar | error | viñeta, ul |
MD009 | no-trailing-spaces | Espacios finales | error | whitespace |
MD011 | no-reversed-links | Sintaxis de vínculo invertido | error | vínculos |
MD012 | no-multiple-blanks | Varias líneas en blanco consecutivas | error | espacio en blanco, blank_lines |
MD014 | commands-show-output | Signos de dólar usados antes de los comandos sin mostrar la salida | error | code |
MD018 | no-missing-space-atx | Sin espacio después del hash en el título de estilo atx | error | encabezados, atx, espacios |
MD019 | no-multiple-space-atx | Varios espacios después del hash en el título de estilo atx | error | encabezados, atx, espacios |
MD022 | blanks-around-headings | Los títulos deben estar rodeados de líneas en blanco | error | encabezados, blank_lines |
MD023 | heading-start-left | Los encabezados deben comenzar al principio de la línea | error | encabezados, espacios |
MD027 | no-multiple-space-blockquote | Varios espacios después del símbolo de blockquote | error | blockquote, espacio en blanco, sangría |
MD029 | ol-prefix | Prefijo de elemento de lista ordenado | error | ol |
MD030 | list-marker-space | Espacios después de marcadores de lista | error | ol, ul, espacio en blanco |
MD031 | blanks-around-fences | Los bloques de código delimitados deben estar rodeados por líneas en blanco | error | código, blank_lines |
MD037 | no-space-in-emphasis | Espacios dentro de marcadores de énfasis | error | espacio en blanco, énfasis |
MD039 | no-space-in-links | Espacios dentro del texto del vínculo | error | espacios en blanco, vínculos |
MD040 | fenced-code-language | Los bloques de código delimitados deben tener un lenguaje especificado | error | código, lenguaje |
MD042 | no-empty-links | No hay vínculos vacíos | error | vínculos |
MD047 | single-trailing-newline | Los archivos deben terminar con un carácter de línea nueva | error | blank_lines |
MD049 | emphasis-style | Estilo de énfasis | error | emphasis |
MD050 | strong-style | Estilo strong | error | emphasis |
search-replace | todocs-placeholder | Detectar ocurrencias del marcador de posición TODOCS. | error | |
search-replace | docs-domain | Detectar ocurrencias del dominio docs.github.com. | error | |
search-replace | help-domain | Detectar ocurrencias del dominio help.github.com. | error | |
search-replace | preview-domain | Detectar ocurrencias del dominio preview.ghdocs.com. | error | |
search-replace | developer-domain | Detectar ocurrencias del dominio developer.github.com. | error | |
search-replace | deprecated liquid syntax: site.data | Detectar ocurrencias de la sintaxis de datos de Liquid en desuso. | error | |
search-replace | deprecated liquid syntax: octicon- | La sintaxis de Liquid Octicon utilizada está en desuso. Usa este formato en lugar de octicon "<octicon-name>" aria-label="<Octicon aria label>" | error | |
GH001 | no-default-alt-text | Las imágenes deben tener texto alternativo significativo (texto alternativo) | error | accesibilidad, imágenes |
GH002 | no-generic-link-text | Evita usar texto de vínculo genérico como Learn more o Click here | error | accesibilidad, vínculos |
GHD030 | code-fence-line-length | Las líneas de delimitación de código no deben superar una longitud máxima | general, | código, accesibilidad |
GHD032 | image-alt-text-end-punctuation | El texto alternativo de las imágenes deben terminar con una puntuación | error | accesibilidad, imágenes |
GHD004 | image-file-kebab-case | Los nombres de archivo de imagen deben usar kebab-case | error | images |
GHD033 | incorrect-alt-text-length | El texto alternativo de las imágenes debe tener entre 40 y 150 caracteres | general, | accesibilidad, imágenes |
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 |
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 |
GHD034 | list-first-word-capitalization | La primera palabra del elemento de lista debe escribirse en mayúsculas | general, | ul, ol |
GHD001 | link-punctuation | Los títulos de vínculos internos no deben contener signos de puntuación | error | vínculos, url |
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 |
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 |
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 |
GHD005 | hardcoded-data-variable | Las cadenas que contienen «token de acceso personal» deben usar la variable de producto en su lugar | error | single-source |
GHD013 | github-owned-action-references | Las referencias de acción propiedad de GitHub no deben codificarse de forma rígida | error | características, acciones |
GHD016 | liquid-quoted-conditional-arg | Las etiquetas condicionales de Liquid no deben citar el argumento condicional | error | liquid, formato |
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 |
GHD010 | frontmatter-hidden-docs | Los artículos con la propiedad de texto preliminar hidden fsolo se pueden encontrar en productos específicos | error | frontmatter, feature, early-access |
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 | frontmatter, feature, early-access |
GHD011 | frontmatter-video-transcripts | La transcripción de vídeo debe configurarse correctamente | error | frontmatter, feature, video-transcripts |
GHD012 | frontmatter-schema | El texto preliminar debe cumplir el esquema | error | texto preliminar, esquema |
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 |
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 |
GHD022 | liquid-ifversion-versions | Liquid ifversion (y elsif ) no siempre debe ser true | general, | liquid, control de versiones |
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. | error | expirado |
GHD039 | expiring-soon | El contenido que expira pronto debe abordarse de forma proactiva. | general, | expirado |
GHD040 | table-liquid-versioning | Las tablas deben usar el formato de control de versiones líquido 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 |
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.
Comentario | Efecto |
---|---|
<!-- markdownlint-disable --> | Deshabilitar de todas las reglas |
<!-- markdownlint-enable --> | Habilitar todas las reglas |
<!-- markdownlint-disable-line --> | Deshabilitar todas las reglas de la línea actual |
<!-- markdownlint-disable-next-line --> | Deshabilitar todas las reglas de la línea siguiente |
<!-- markdownlint-disable RULE-ONE RULE-TWO --> | |
<!-- markdownlint-enable RULE-ONE RULE-TWO --> | Habilitar una o varias reglas por nombre |
<!-- markdownlint-disable-line RULE-NAME --> | Deshabilitar una o varias reglas por nombre para la línea actual |
<!-- markdownlint-disable-next-line RULE-NAME --> | Deshabilitar una o varias reglas por nombre para la línea siguiente |