HTML y CSS

Esta sección cubre la fuente de los documentos. Dice qué elemento HTML usar para cada cosa (y cuál no usar solo por su apariencia), cómo dar formato al código fuente HTML para que cualquiera del grupo lo lea y lo revise, y cuándo escribir en Markdown y cuándo en HTML. Aplica a las páginas del kit (la galería, esta guía), a los README y docs/ de cis-admin y cochid-datos, al manual de operación y a las plantillas del archivo societario. Las reglas sobre el código que se muestra al lector están en Código en el texto y Muestras de código; aquí se trata del código que escribes tú.

HTML y etiquetado semántico

Usa los elementos HTML para lo que fueron diseñados. Por ejemplo, cuando des el título de una obra completa (un libro, una película), márcalo con un elemento cite. Para más información sobre etiquetado semántico, consulta Semántica en HTML en la documentación web de MDN.

El navegador pinta cite en cursiva, que es justo lo que pide la casa para el título de una obra completa. Para más información, consulta la sección «Comillas y cursivas» de Referencias cruzadas y enlaces.

En situaciones donde no hay un elemento HTML semánticamente pertinente, usa CSS o los pocos elementos HTML que transmiten estilo visual sin semántica (i, b, span, div).

Las páginas del kit ya dan el ejemplo: esta página usa header para la barra superior, nav para los enlaces principales, aside para el menú lateral, article para el contenido y footer para el pie. Un lector de pantalla salta entre esas regiones sin leer lo que hay entre medio. Si las reemplazas por div con clases, el diseño se ve igual y la navegación por regiones desaparece. Para más información, consulta Accesibilidad.

Formato visual

Si quieres un resultado visual concreto, no uses elementos HTML que transmiten otra semántica.

En particular, sigue estas pautas:

• No uses marcos (frame, iframe) ni tablas para maquetar la página; usa la CSS de tu sitio. En los sitios del grupo la maquetación viene en chrome.css y components.css del kit, y los colores y medidas en tokens.css. Las tablas se reservan para datos tabulares. Para más información, consulta Tablas.
• No uses los elementos de encabezado (h1, h2…) para dar estilo visual a un texto; úsalos solo para encabezados con jerarquía, y usa CSS para el estilo. Un encabezado que no es sección engaña al índice, al lector de pantalla y al menú lateral de esta guía, que se construye con los h2. El texto del encabezado va en minúscula de oración (P37). Para más información, consulta Títulos y encabezados.
• El elemento em indica énfasis, no cursiva como tal. No lo uses para poner en cursiva algo que no quieres enfatizar; usa el elemento i para la cursiva sin énfasis (un extranjerismo, un término que defines). Para más información, consulta Cursivas en términos.
• El elemento strong indica importancia fuerte, no negrita como tal. Para poner en negrita una palabra que no amerita importancia fuerte, usa el elemento b. Las etiquetas «Recomendado» y «No recomendado» de esta guía van en b por eso: son rótulos, no advertencias.
• El elemento br está pensado «solo para saltos de línea que son parte del contenido, como en poemas o direcciones». No lo uses para ajustar el espacio entre líneas. Marca el texto con elementos como p y ajusta el interlineado con CSS.

Otros elementos con significado

Además de los anteriores, la casa usa estos elementos cuando el contenido lo pide:

• a para ir a otro lugar y button para hacer algo en la página. El botón que abre el menú de esta página es un button con aria-expanded. Un a href="#" con un manejador de clic no le dice nada al teclado ni al lector de pantalla.
• time con atributo datetime en formato ISO para fechas y horas. El texto visible sigue el formato de la casa (20-08-2026 o «20 de agosto de 2026», hora de 24 h); el atributo lo leen las máquinas. Para más información, consulta Fechas y horas.
• abbr con atributo title para una sigla que ya introdujiste y que el lector puede haber olvidado (DTE, RUT, CAF). No reemplaza la forma larga en el primer uso. Para más información, consulta Abreviaturas.
• code, kbd, samp y var para el código en el texto, las teclas, la salida de un programa y los marcadores de posición. Para más información, consulta Código en el texto y Formato de marcadores de posición.
• section con id (o el id en el propio encabezado) para que una sección reciba enlaces. El atributo name de a está obsoleto. Para más información, consulta Encabezados como destino de enlace.

Un límite que la casa fija con más dureza que Google: ningún elemento ni entidad te habilita la raya. Ni — ni su código numérico pasan el linter del canon (P05). Escribe el punto medio «·», una coma, un paréntesis o un punto y oración nueva, y escríbelos como caracteres directos. Para más información, consulta Rayas y guiones.

Formato de HTML

Sigue la Guía de estilo HTML/CSS de Google. Excepción: no omitas los elementos opcionales.

La guía HTML/CSS de Google permite omitir etiquetas que el estándar declara opcionales (html, head, body, los cierres </p> y </li>). En la documentación del grupo se escriben siempre: un archivo con todas sus etiquetas lo lee igual un navegador, un linter, un conversor a PDF o la persona que lo revisa en un diff.

En particular, estas son algunas pautas básicas de esa guía, que en general aplican también a otros archivos fuente de documentación (como YAML y Markdown):

• No uses tabulaciones para sangrar el texto; usa solo espacios. Cada editor interpreta distinto las tabulaciones, y algunas funciones de Markdown esperan espacios y no tabulaciones.
• Sangra con dos espacios por nivel.
• Escribe los elementos y los atributos en minúscula.
• No dejes espacios al final de una línea (salvo los que Markdown necesita, como los dos espacios que fuerzan un salto de línea).
• Pon los valores de atributo entre comillas dobles rectas (class="par"), no simples ni tipográficas.
• Escribe los caracteres directamente en UTF-8: las tildes y la eñe (á, ñ), las comillas angulares (« ») y el punto medio (·). Las referencias de entidad se reservan para los caracteres con significado en HTML (<, >, &) y para los invisibles ( ). Todos los archivos del grupo se guardan en UTF-8 y declaran <meta charset=utf-8>; una entidad como á solo hace ilegible la fuente y esconde las tildes a los linters.

Excepción del kit. La cabecera de las páginas del kit (<html lang=es>, <meta charset=utf-8>, los link a las hojas de estilo versionadas) se copia literal desde la plantilla. Va con sus atributos sin comillas y sin sangría, y no se reformatea. Las diez páginas de esta guía comparten esa cabecera byte a byte, y un retoque de estilo en una de ellas rompe la comparación entre todas. Es el mismo criterio que la sección siguiente aplica a los archivos antiguos: respeta el formato del archivo que tocas.

Largo de línea

Corta las líneas a 80 caracteres, salvo en los casos siguientes:

• La información de un elemento meta al comienzo del archivo tiene que ir en una sola línea, así que esas líneas pueden ser tan largas como haga falta.
• Si la URL de un enlace lleva un salto de línea, el enlace no funciona. Si una URL mide más de 80 caracteres (algo bastante común), no hay vuelta. En ese caso, pon la URL en su propia línea junto con el atributo href, para que sea más fácil revisar el texto anterior y posterior, como muestra el ejemplo siguiente:

Puedes encontrar más información en
<a href="https://example.com/archivo/sociedades/circulo-de-santiago-spa/constitucion-2026-03-08-extracto-diario-oficial.html"
>el extracto de constitución.</a>

El dominio example.com está reservado para ejemplos. Para más información, consulta Dominios y nombres de ejemplo.

Corta las muestras de código (dentro de bloques <pre>) a 80 caracteres. Usa el carácter de continuación del lenguaje (\ en la shell, un paréntesis abierto en Python, una coma al final de línea en SQL) para que el lector pueda copiar y pegar el bloque sin retocarlo. Para más información, consulta Muestras de código.

• Los archivos más antiguos pueden usar otro largo de línea. Si haces cambios pequeños en un archivo que usa de forma consistente un largo distinto de 80 caracteres, ajusta tus cambios al largo de ese archivo en vez de reformatearlo entero. Lo mismo vale para las páginas de la galería del kit, que escriben cada párrafo en una sola línea: si corriges un párrafo, no lo cortes.
• Cuando agregues saltos de línea, asegúrate de no cambiar el significado del código. Si no conoces el lenguaje de programación, pide ayuda a alguien que lo conozca. Y a veces una línea larga no se puede evitar (un hash, una URL firmada, un token de ejemplo): déjala larga antes que romperla.

Markdown contra HTML

Usa HTML o Markdown. Parte de esta guía asume que escribes en HTML. Si escribes en Markdown, detalles como qué elementos HTML usar en cada contexto pueden no aplicarte.

Markdown es más fácil de escribir que HTML, y a la mayoría de las personas le resulta más fácil leer una fuente Markdown que una fuente HTML. Pero HTML es más expresivo (sobre todo en el etiquetado semántico) y consigue algunos efectos concretos que en Markdown son difíciles o imposibles. Por ejemplo, puede que tengas que pasar al elemento code de HTML para escribir caracteres especiales dentro del código, como espacios indivisibles.

Al final, cuál usar es sobre todo una cuestión de preferencia personal; pero si tu equipo o la plantilla de tu documento ya usa uno de los dos, lo mejor es usar ese mismo.

Qué usa cada cosa en el grupo

En el grupo la plantilla ya decidió por ti en casi todos los casos:

• Markdown: los README, los docs/ de cada repo, los ADR, los planes en cis/docs/plans/, el canal compartido (CHANNEL.md) y el manual de operación. Es lo que GitHub renderiza y lo que prosa-lint lee sin conversión.
• HTML: las páginas del kit (la galería, esta guía), las páginas estáticas de los sitios y los documentos que WeasyPrint convierte a PDF con cabecera y pie propios (las actas de cds-protocolo, los certificados de cis-verify).
• JSX en las aplicaciones Next.js y Vite (cis-admin, el portal de medicamentos). Ahí rigen las mismas reglas semánticas de HTML y etiquetado semántico: un div con onClick sigue sin ser un botón.

No mezcles los dos formatos en un mismo conjunto de documentos sin motivo. Si el docs/ de un repo está en Markdown, la página nueva va en Markdown aunque te resulte más cómodo el HTML. La norma de prosa corre igual sobre .md y sobre .html, así que el formato no te libra del linter. Para más información, consulta Cómo se relaciona con la norma de prosa.

Cuándo escribir HTML dentro de Markdown

Markdown acepta HTML en línea. Úsalo solo para lo que Markdown no sabe hacer, y nunca para lo que sí sabe (negritas, listas, enlaces, encabezados, bloques de código). Los casos legítimos en la documentación del grupo son estos:

• Anclas estables. El Markdown de GitHub no admite {: #id }. Pon <a id="rotar-llave"></a> en la línea anterior al encabezado. Para más información, consulta Encabezados como destino de enlace.
• Espacio indivisible entre la cifra y la unidad. En español la cifra y su unidad van separadas por un espacio (10 GB, 24 h, 1.215.716 millones) y no deben quedar en líneas distintas. Markdown no tiene sintaxis para eso; escribe   (o el carácter U+00A0 directo, si tu editor lo muestra). Para más información, consulta Unidades de medida.
• Tablas que Markdown no expresa. Celdas combinadas, listas dentro de una celda o un encabezado de fila. Antes de escribir una tabla en HTML, pregúntate si la tabla se puede simplificar. Para más información, consulta Tablas.
• Contenido plegable. <details><summary> para un volcado largo o una salida de comando que el lector solo necesita a veces.
• Saltos de línea que son contenido. Una dirección postal o una firma, con <br>.

Dos cuidados al mezclar. Primero, dentro de un bloque HTML la mayoría de los conversores no interpreta Markdown: si abres un <details>, el **texto** de adentro sale con los asteriscos. Deja una línea en blanco después de la etiqueta de apertura o escribe el interior también en HTML. Segundo, el HTML en línea no tiene estilo propio en los README de GitHub ni en MkDocs: no uses atributos style ni colores a mano. Si una página necesita un estilo que el kit no da, el cambio va en los tokens del kit y no en el documento.

Adaptación al español y a las convenciones del grupo de la Google developer documentation style guide, publicada bajo CC BY 4.0. Donde esta guía y la norma de prosa de la casa difieren, manda la norma (core/prosa/NORMA.md).