Skip to main content

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 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.

Shell
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 reglaNombres de la reglaDescripciónGravedadEtiquetas
MD001heading-increment, header-incrementLos niveles de título solo deben incrementarse en un nivel a la vezerrortítulos, encabezados
MD002first-heading-h1, first-header-h1El primer título debe ser un título de nivel superiorerrortítulos, encabezados
MD004ul-styleEstilo de listas sin ordenarerrorviñeta, ul
MD009no-trailing-spacesEspacios finaleserrorespacio en blanco
MD011no-reversed-linksSintaxis de vínculo invertidoerrorvínculos
MD012no-multiple-blanksVarias líneas en blanco consecutivaserrorespacio en blanco, blank_lines
MD014commands-show-outputSignos de dólar usados antes de los comandos sin mostrar la salidaerrorcódigo
MD018no-missing-space-atxSin espacio después del hash en el título de estilo atxerrortítulos, encabezados, atx, espacios
MD019no-multiple-space-atxVarios espacios después del hash en el título de estilo atxerrortítulos, encabezados, atx, espacios
MD022blanks-around-headings, blanks-around-headersLos títulos deben estar rodeados de líneas en blancoerrortítulos, encabezados, blank_lines
MD023heading-start-left, header-start-leftLos encabezados deben comenzar al principio de la líneaerrortítulos, encabezados, espacios
MD027no-multiple-space-blockquoteVarios espacios después del símbolo de blockquoteerrorblockquote, espacio en blanco, sangría
MD029ol-prefixPrefijo de elemento de lista ordenadoerrorol
MD030list-marker-spaceEspacios después de marcadores de listaerrorol, ul, espacio en blanco
MD031blanks-around-fencesLos bloques de código delimitados deben estar rodeados por líneas en blancoerrorcódigo, blank_lines
MD037no-space-in-emphasisEspacios dentro de marcadores de énfasiserrorespacio en blanco, énfasis
MD039no-space-in-linksEspacios dentro del texto del vínculoerrorespacios en blanco, vínculos
MD040fenced-code-languageLos bloques de código delimitados deben tener un lenguaje especificadoerrorcódigo, lenguaje
MD042no-empty-linksNo hay vínculos vacíoserrorvínculos
MD047single-trailing-newlineLos archivos deben terminar con un carácter de línea nuevaerrorblank_lines
MD049emphasis-styleEl estilo de énfasis debe ser coherenteerroremphasis
MD050strong-styleEl estilo de los elementos resaltados con «strong» debe ser coherenteerroremphasis
search-replacetodocs-placeholderDetectar ocurrencias del marcador de posición TODOCS.error
search-replacedocs-domainDetectar ocurrencias del dominio docs.github.com.advertencia
search-replacehelp-domainDetectar ocurrencias del dominio help.github.com.error
search-replacepreview-domainDetectar ocurrencias del dominio preview.ghdocs.com.error
search-replacedeveloper-domainDetectar ocurrencias del dominio developer.github.com.error
search-replacedeprecated liquid syntax: site.dataDetectar ocurrencias de la sintaxis de datos de Liquid en desuso.error
search-replacedeprecated 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
GH001no-default-alt-textLas imágenes deben tener texto alternativo significativo (texto alternativo)erroraccesibilidad, imágenes
GH002no-generic-link-textEvita usar texto de vínculo genérico como Learn more o Click hereerroraccesibilidad, vínculos
GHD030code-fence-line-lengthLas líneas de delimitación de código no deben superar una longitud máximaadvertenciacódigo, accesibilidad
GHD032image-alt-text-end-punctuationEl texto alternativo de las imágenes deben terminar con una puntuaciónerroraccesibilidad, imágenes
GHD004image-file-kebab-caseLos nombres de archivo de imagen deben usar kebab-caseerrorimages
GHD033incorrect-alt-text-lengthEl texto alternativo de las imágenes debe tener entre 40 y 150 caracteresadvertenciaaccesibilidad, imágenes
GHD002internal-links-no-langLos vínculos internos no deben tener un código de lenguaje codificado de forma rígidaerrorvínculos, url
GHD003internal-links-slashLos vínculos internos deben comenzar con /errorvínculos, url
GHD031image-alt-text-exclude-wordsEl texto alternativo de las imágenes no debe comenzar con palabras como «imagen» o «gráfico»erroraccesibilidad, imágenes
GHD034list-first-word-capitalizationLa primera palabra del elemento de lista debe escribirse en mayúsculasadvertenciaul, ol
GHD001link-punctuationLos títulos de vínculos internos no deben contener signos de puntuaciónerrorvínculos, url
GHD008early-access-referencesLos archivos que no son de acceso anticipado no deben hacer referencia a archivos de acceso anticipado o de acceso anticipadoerrorcaracterística, acceso anticipado
GHD021yaml-scheduled-jobsLos fragmentos de código YAML que incluyen flujos de trabajo programados no deben ejecutarse en la hora y deben ser únicoserrorcaracterísticas, acciones
GHD006internal-links-old-versionLos vínculos internos no deben tener una versión codificada de forma rígida mediante la sintaxis de control de versiones anteriorerrorvínculos, url, control de versiones
GHD005hardcoded-data-variableLas cadenas que contienen «token de acceso personal» deben usar la variable de producto en su lugarerrorsingle-source
GHD013github-owned-action-referencesLas referencias de acción propiedad de GitHub no deben codificarse de forma rígidaerrorcaracterísticas, acciones
GHD016liquid-quoted-conditional-argLas etiquetas condicionales de Liquid no deben citar el argumento condicionalerrorliquid, formato
GHD014liquid-data-references-definedSe 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 datoserrorliquid
GHD015liquid-data-tag-formatLos datos de Liquid o las etiquetas de referencia de datos con sangría deben tener el número correcto de argumentos y espaciadoerrorliquid, formato
GHD010frontmatter-hidden-docsLos artículos con la propiedad de texto preliminar hidden fsolo se pueden encontrar en productos específicoserrorfrontmatter, feature, early-access
GHD009frontmatter-early-access-referencesLos archivos que no son de acceso anticipado no deben tener una instancia de texto preliminar que haga referencia al acceso anticipadoerrorfrontmatter, feature, early-access
GH011frontmatter-video-transcriptsLa transcripción de vídeo debe configurarse correctamenteerrorfrontmatter, feature, video-transcripts
GHD012frontmatter-schemaEl texto preliminar debe cumplir el esquemaerrortexto preliminar, esquema
GHD007code-annotationsLas anotaciones de código definidas en Markdown deben contener una propiedad de texto preliminar de diseño específicaerrorcódigo, característica, anotar, texto preliminar
GHD017frontmatter-liquid-syntaxLas propiedades de texto preliminar deben usar Liquid válidoerrorliquid, texto preliminar
GHD018liquid-syntaxEl contenido de Markdown debe usar Liquid válidoerrorliquid
GHD019liquid-if-tagsLas etiquetas ifversion de Liquid se deben usar en lugar de etiquetas if cuando el argumento es una versión válidaerrorliquid, control de versiones
GHD020liquid-ifversion-tagsLas etiquetas de Liquid ifversion deben contener nombres de versión válidos como argumentoserrorliquid, control de versiones

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.

ComentarioEfecto
<!-- 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 -->
Deshabilitar una o varias reglas por nombre
<!-- 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