Escapar para sobrescribir componentes

Htmlpress incluye un layout, un tema, dos scripts y una biblioteca de componentes, todos compilados en el binario. Cualquier archivo integrado se puede reemplazar: coloca un archivo en la misma ruta bajo .htmlpress/ y la compilación lo usará en su lugar.

layout.html

La página alrededor del contenido, HTML simple con los elementos de layout que htmlpress rellena, como <htmlpress-content> y <htmlpress-nav>.

styles/*.css

El tema global, unido en un único theme.css en cada página: tokens.css (los valores --htmlpress-*), layout.css (los estilos globales de la página) y content.css (encabezados, prosa, tablas, código).

scripts/code.js

El botón de copiar de los bloques de código y el enlace de cada encabezado.

scripts/hints.js

La sugerencia emergente de las abreviaturas y las referencias a notas al pie.

components/<name>/<name>.css y .js

Un componente cada uno, incluidos los elementos del armazón del layout, en una carpeta con el nombre de su etiqueta sin el prefijo htmlpress-. Sus estilos van dentro de @scope (<tag>), así que nunca salen de él, y su script solo define ese elemento. Una página enlaza solo los componentes que usa.

No hace falta ningún otro cambio: el resto de htmlpress detecta automáticamente el archivo escapado.

El comando htmlpress escape

htmlpress escape copia un archivo predeterminado a .htmlpress/ como punto de partida. Nombra un archivo por su ruta, o un componente por su etiqueta para obtener todos sus archivos:

$ htmlpress escape                       # list every file, marking the escaped ones
$ htmlpress escape htmlpress-tabs        # its .css and .js
$ htmlpress escape layout.html styles/tokens.css
$ htmlpress escape htmlpress-tabs -r docs  # in another project folder

htmlpress escape nunca sobrescribe un archivo que ya tienes: bórralo primero para empezar de nuevo. Una copia escapada conserva el código del que se copió, así que tras una actualización no recibe los nuevos valores predeterminados.

Borrar un escape restaura el valor predeterminado: al instante mientras se ejecuta htmlpress start, o si no en el siguiente start o build.

Ejemplo: créditos

Una carpeta bajo components/ con un nombre nuevo añade un componente propio, <htmlpress-<name>>, con cada archivo nombrado como la carpeta. Su .html rellena cada una de esas etiquetas en el layout y en las páginas al compilar; su .css y su .js se cargan allí donde aparece la etiqueta.

<!-- .htmlpress/components/credits/credits.html -->
<footer><p>Built by my team · 2026</p></footer>

/* .htmlpress/components/credits/credits.css */
@scope (htmlpress-credits) {
  :scope { display: block; }
  p { color: var(--htmlpress-muted); }
}

Después pon <htmlpress-credits></htmlpress-credits> en un layout.html escapado o en cualquier página. Guarda: el servidor de desarrollo lo detecta de inmediato. Un nombre consta de letras minúsculas, dígitos y guiones.

Ejemplo: cambiar el tema de los botones

$ htmlpress escape components/button/button.css

Edita .htmlpress/components/button/button.css para cambiar el estilo de los botones en todas partes: cada página que usa <htmlpress-button> enlaza tu copia en lugar de la integrada.

Ejemplo: ajustar un token

$ htmlpress escape styles/tokens.css

Edita el bloque :root de .htmlpress/styles/tokens.css para cambiar la imagen de marca:

:root {
  --htmlpress-accent: oklch(0.55 0.24 27); /* red */
}

Para una sola página, sobrescribe el token desde el <style> propio de esa página; no hace falta ningún escape.

Usar otros componentes desde una sobrescritura

Un layout.html escapado, un layout propio y el .html de un componente pueden contener cualquier componente htmlpress-*, que se renderiza y enlaza sus estilos como lo haría en una página. El .html de un componente no puede contener la etiqueta de otro componente del proyecto: se inserta una sola vez y nunca se vuelve a reescribir.

Limitar los estilos de un componente

La etiqueta de un componente permanece alrededor del marcado con el que la rellena su .html, conservando sus atributos, así que su .css se limita a la etiqueta, @scope (htmlpress-credits), con o sin .html. Un elemento personalizado es inline hasta que su CSS diga lo contrario. Para cambiar el estilo de un componente desde otro, supera su :scope: :scope htmlpress-header, no un htmlpress-header a secas.

Transiciones entre páginas

Al pasar de una página a otra solo el contenido se funde: <htmlpress-header> y <htmlpress-sidebar> llevan los nombres de transición htmlpress-header y htmlpress-sidebar y cambian a la nueva página al instante. Pasar el cursor sobre un enlace prerenderiza su página, así que está lista al hacer clic. Los botones de la cabecera vienen en cada página; un script del head pone data-scripted en <html>, y sin él quedan ocultos, así que estiliza lo que solo funciona con scripts bajo :root[data-scripted].

Qué no puedes sobrescribir así

• El marcado de los elementos de layout: el marcado dentro de <htmlpress-nav>, <htmlpress-page-toc>, <htmlpress-pager> y los demás elementos de layout se construye a partir del sitio, así que solo se pueden escapar su .css y su .js. Un components/brand/brand.html rellena uno con tu propio HTML estático; su .css integrado sigue aplicándose a la etiqueta, así que escápalo también para cambiar su estilo.
• Páginas con un layout distinto: usa .htmlpress/layouts/ en su lugar.
• El binario: la lectura de páginas, la navegación y los comandos no se pueden sobrescribir; haz un fork del repositorio si necesitas cambiarlos.
• El esquema de configuración: la forma de htmlpress.yaml es fija.

Ver también

• Temas de sintaxis: el aspecto de los bloques de código.
• Rutas personalizadas: páginas con un layout propio, en lugar de reemplazar el predeterminado.