Escribir páginas de documentación MDX que sigan las reglas del sitio y compilen sin errores

## Conocer cómo está organizado el sitio de documentación antes de escribir Trate el repositorio como una aplicación de documentación basada en esquemas, no como una colección inconexa de archivos Markdown. Identifique el generador del sitio, el tema de la documentación, el framework de componentes, el gestor de paquetes, la versión del entorno de ejecución y el destino del despliegue. Instale las dependencias con el comando bloqueado y reproducible del repositorio. Mantenga las versiones del entorno de ejecución y del gestor de paquetes alineadas con los metadatos del repositorio. Confirme la rama principal de contribución en lugar de suponer un nombre convencional. Distinga las páginas para usuarios, los parciales reutilizables, los registros de cambios, los datos del glosario, los metadatos de productos y otras colecciones estructuradas. Mantenga los componentes personalizados, los esquemas de contenido, los complementos de Markdown, los complementos de resaltado de código, los iconos, los recursos, los estilos y las rutas dinámicas en sus capas designadas. Trate los archivos públicos estáticos de forma distinta a las imágenes procesadas por el generador del sitio. Use el módulo central de exportación de componentes como superficie pública de importación para MDX. Mantenga los esquemas de las colecciones como autoridad para los campos y tipos de valores aceptados. Trate los directorios generados de habilidades o referencias como productos de la compilación. No edite los directorios generados ni confirme contenido generado que esté ignorado. Lea las instrucciones anidadas antes de cambiar un bot especializado de revisión o un worker de despliegue. Use como guía canónica las referencias de estilo, componentes y procedimientos propias del repositorio. No permita que los hábitos genéricos de Markdown prevalezcan sobre las reglas de MDX y de esquemas del sitio. ## Poner las páginas en las carpetas correctas y nombrar bien los archivos Coloque las páginas de documentación para usuarios bajo el directorio del producto o del tema. Coloque los fragmentos reutilizables en la colección de parciales. Coloque las entradas del registro de cambios en el subdirectorio correspondiente al producto o al tema. Coloque los términos del glosario y otros metadatos estructurados en las colecciones gestionadas por sus esquemas. Exija una página de índice en cada carpeta de contenido navegable cuando el sitio así lo requiera. Use nombres de archivo en minúsculas con las palabras separadas por guiones. Limite los directorios de contenido a las extensiones de texto y datos permitidas explícitamente. Los tipos permitidos habituales son MDX, JSON, YAML y texto sin formato. Deje que la validación de extensiones aplique la lista permitida, en lugar de ocultar los archivos no admitidos. No coloque imágenes ni binarios arbitrarios dentro de directorios de contenido examinados por el esquema. Coloque las imágenes procesables en el árbol de recursos dedicado para su optimización. Coloque los archivos realmente estáticos en el árbol público solo cuando deban servirse sin cambios. Mantenga los nombres de los directorios alineados con los metadatos de productos existentes. No cree un registro de cambios ni un subdirectorio de colección para una clave de producto desconocida. Preserve los límites establecidos de las colecciones en lugar de inventar una ubicación de contenido paralela. Al mover una página, actualice los enlaces entrantes, los metadatos de navegación, las redirecciones y las referencias a parciales relacionadas. ## Completar los datos de página (frontmatter) que exige el sitio Proporcione a cada página de documentación un bloque de frontmatter que satisfaga el esquema de su colección. Proporcione un título de página conciso. Proporcione una descripción para las búsquedas siempre que el tipo de contenido seleccionado la requiera. Elija el tipo de página entre la enumeración permitida del repositorio. Los tipos habituales incluyen `concept`, `configuration`, `example`, `FAQ`, `getting started`, `how-to`, `integration`, `implementation`, `overview`, `reference`, `release notes`, `solution`, `troubleshooting` y `tutorial`. Use tipos especializados como `design guide`, `learning unit`, `navigation`, `reference architecture` y `video` cuando el esquema los ofrezca. Use el orden de la barra lateral solo cuando se necesite una ordenación explícita. Use una etiqueta de la barra lateral solo cuando el texto de navegación deba diferir del título de la página. Haga referencia a productos o temas mediante las claves de metadatos existentes. Use la enumeración de dificultad documentada para el contenido de tutoriales. Registre las fechas de revisión en el formato obligatorio de año-mes-día. No invente campos de esquema ni valores de enumeración. Mantenga válidas la sangría de YAML y la estructura de las listas. Vuelva a generar los tipos de las colecciones de contenido después de cambiar definiciones de colecciones o esquemas. Valide los archivos de datos con sus esquemas en lugar de depender de una inspección visual. Mantenga sincronizados los metadatos de la página cuando cambien su finalidad, producto, título o estado de revisión. ## Escribir páginas MDX que compilen sin errores de sintaxis Siga la guía canónica de redacción y formato del repositorio. Trate MDX como Markdown más un lenguaje de componentes integrado con un análisis más estricto. Escape o aplique formato de código a las llaves y los signos de mayor y menor cuando formen parte de la prosa. Recuerde que MDX interpreta esos caracteres como expresiones o componentes incluso dentro de la prosa. Importe todos los componentes que use la página. Coloque las importaciones inmediatamente después del frontmatter y antes del contenido de la página. Use únicamente identificadores de lenguaje admitidos para el resaltado de sintaxis. Escriba la salida genérica del terminal con el identificador de texto sin formato del repositorio. Use identificadores de lenguaje en minúsculas en los bloques de código. Use rutas absolutas desde la raíz para los enlaces internos del sitio. No use URL completas de producción para destinos internos. No use enlaces relativos de páginas que no estén admitidos. Mantenga secuenciales los niveles de los encabezados y no se salte ningún nivel. Omita los símbolos del prompt del shell en los comandos que se puedan copiar. Escriba pasos concisos cuya acción, ubicación y resultado esperado sean inequívocos. Mantenga las explicaciones reutilizables en parciales cuando varias páginas necesiten el mismo texto mantenido. Verifique los ejemplos de código con la API documentada y el comportamiento actual del producto. ## Usar los componentes e imágenes del sitio y cambiar redirecciones solo cuando haga falta Importe componentes MDX únicamente mediante el módulo central de exportación de componentes del repositorio. Consulte la documentación de los componentes para conocer las propiedades obligatorias y las restricciones de uso. No copie la implementación interna de un componente en el contenido cuando exista un componente público admitido. Coloque el código de componentes nuevos en el directorio de componentes designado. Use el prefijo obligatorio para elementos personalizados y la convención de nombres kebab-case. Mantenga cada componente en un directorio que lleve el nombre de ese componente. Use nombres de clases en PascalCase con el sufijo obligatorio. No cambie el nombre de elementos heredados exentos solo para aplicar una regla de prefijo más reciente. Mantenga las imágenes de origen en el directorio de recursos optimizados de su producto o tema. Verifique las rutas de las imágenes mediante una compilación local completa. Modifique las redirecciones solo cuando lo requiera el traslado de una página o la migración de una URL. Termine las rutas de origen de las redirecciones con la barra obligatoria o con un sufijo de archivo o comodín aceptado. No incluya fragmentos en las URL de origen de las redirecciones. Detecte los bucles de redirección antes de la revisión. Ejecute el validador específico de redirecciones siempre que cambie el archivo de redirecciones. Mantenga los cambios de componentes, imágenes, enlaces y redirecciones dentro del alcance previsto de la página. ## Pasar las comprobaciones en local y en CI antes de dar una página por lista Ejecute las comprobaciones de esquemas y tipos después de cada cambio de contenido. Use una compilación local completa para validar el análisis de MDX, las rutas de imágenes y los enlaces internos. Active la comprobación de enlaces internos durante la compilación local de validación completa. No ejecute dentro de una integración continua restringida una compilación completa que se sabe que agotará el tiempo. En la integración continua, ejecute las comprobaciones de tipos, lint y formato como conjunto seguro reducido. Para los cambios de código, ejecute también las suites de pruebas completas del repositorio. Formatee todos los archivos editados antes de confirmarlos. Ejecute la comprobación de formato del repositorio después de las correcciones automáticas. Ejecute la validación de redirecciones solo cuando haya cambiado su configuración. Ejecute la sincronización de tipos de colección después de modificar esquemas o colecciones. Alinee la secuencia local de validación completa con el pipeline de integración continua cuando resulte práctico. Espere que la integración continua compruebe las extensiones de archivos, los tipos, el lint, el formato, la compilación y los enlaces, las redirecciones y las pruebas. Trate las advertencias del analizador de estilo como pruebas para la revisión, aunque no sean fallos estrictos. No informe de que una página está lista mientras falte un control de validación directamente pertinente. Distinga una limitación del entorno de integración continua de un fallo real del contenido. Vuelva a ejecutar las comprobaciones afectadas directamente después de cada edición correctiva. ## Dar a cada entrada del directorio un ID creado con la herramienta del sitio y conservarlo Proporcione a cada archivo de datos de entrada de directorio un identificador único y estable en la posición obligatoria de la primera línea. Use la longitud exacta de identificador y el conjunto de caracteres con confusión reducida del repositorio. En un esquema de seis caracteres, compruebe que cada valor generado tenga exactamente seis caracteres. Excluya los caracteres visualmente ambiguos cuando el esquema lo requiera. Genere los identificadores al azar en lugar de derivarlos de los nombres. No cree, adivine ni copie manualmente un identificador. Use la herramienta de identificadores del repositorio para comprobar la colección completa. Use su modo de corrección para los identificadores ausentes, mal formados o duplicados. Conserve un identificador válido existente cuando cambie el nombre visible o el nombre del archivo. Cambie un identificador existente únicamente para reparar un error de validación confirmado. Use sistemáticamente la única extensión YAML obligatoria. Trate la generación de identificadores como una operación automatizada, no como una decisión editorial. Compruebe la unicidad en toda la colección de directorios. Mantenga la generación de identificadores y la validación de esquemas en la integración continua. Revise el diff de la herramienta antes de confirmar los cambios generados. No ajuste manualmente un identificador generado después de que la herramienta finalice correctamente. ## Seguir las guías de cada tarea y las reglas de commits al enviar cambios Use el enrutador de contribuciones del repositorio antes de redactar, editar, revisar ejemplos, añadir registros de cambios o preparar una pull request. Siga la referencia específica de la tarea que seleccione ese enrutador. Lea las instrucciones locales de un bot especialista antes de cambiar su código, el enrutamiento del flujo de trabajo, su estado o su despliegue. Mantenga los enlaces simbólicos específicos de las herramientas apuntando a la configuración compartida y confirmada de los agentes. Cargue una habilidad del repositorio solo cuando su descripción coincida con la tarea. Use la guía de estilo canónica para las decisiones de redacción y formato. Use el catálogo de componentes para consultar propiedades, ejemplos y patrones obligatorios. Use la guía de procedimientos para las instrucciones paso a paso. Ejecute pruebas en cada espacio de trabajo de ejecución afectado por un cambio de código. Mantenga diferenciadas las pruebas del worker, del entorno de ejecución del servidor y del generador del sitio. Escriba las confirmaciones con el formato aceptado por el repositorio que lleva como prefijo el producto o el tipo. Haga que las descripciones de las confirmaciones sean específicas de la corrección visible para el usuario o de la corrección técnica. No incluya cambios de formato, contenido generado ni cambios de producto que no estén relacionados. Apruebe únicamente cuando coincidan el contenido, los esquemas, las importaciones, los recursos, los enlaces, las redirecciones, las pruebas y las convenciones de contribución.