# Escapar para sobrescribir componentes

> Reemplaza el layout, los estilos, los scripts y los componentes integrados, o añade los tuyos, desde .htmlpress/.

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.

| Para sobrescribir                 | Coloca un archivo en                              |
| --------------------------------- | ------------------------------------------------- |
| la página alrededor del contenido | `.htmlpress/layout.html`                          |
| el tema global                    | `.htmlpress/styles/<name>.css`                    |
| un script global                  | `.htmlpress/scripts/<name>.js`                    |
| un componente                     | `.htmlpress/components/<name>/<name>.css` o `.js` |

- .htmlpress

  - layout.html

  - layouts
    - landing.html

  - styles

    - tokens.css
    - layout.css
    - content.css

  - scripts
    - code.js

  - components

    - callout
      - callout.css

    - tabs

      - tabs.css
      - tabs.js

    - credits
      - credits.html

* `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:

```sh
$ 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.

```html
<!-- .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

```sh
$ 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

```sh
$ 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/`](/es/customization/custom-routes/) 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.

> **Warning**
>
> Una carpeta bajo `components/` con un nombre que htmlpress no incluye, como `calout/`, añade un componente nuevo en lugar de reemplazar uno. Un archivo directamente en `components/` hace fallar la compilación, y también cualquier archivo bajo `styles/` o `scripts/` que no reemplace nada.

## Ver también

- [Temas de sintaxis](/es/customization/syntax-themes/): el aspecto de los bloques de código.
- [Rutas personalizadas](/es/customization/custom-routes/): páginas con un layout propio, en lugar de reemplazar el predeterminado.