Elementos enriquecidos

Unos pocos elementos htmlpress-* cubren lo que HTML no tiene como elemento. Son elementos personalizados en light DOM, así que su contenido sigue siendo HTML simple que se lee bien incluso antes de que cargue el script. Los estilos y el script de cada uno se enlazan solo en las páginas que lo usan. Pon contenido de bloque (<p>, <h3>, <pre>) dentro de un componente, no texto suelto.

Tablas

Una <table> recibe estilo tal cual, y una con <thead> se ordena por la cabecera en la que se haga clic:

<table>
  <thead><tr><th>Language</th><th>Year</th><th>Typing</th></tr></thead>
  <tbody><tr><td>TypeScript</td><td>2012</td><td>Static</td></tr>…</tbody>
</table>

| Language | Year | Typing |
| --- | --- | --- |
| TypeScript | 2012 | Static |

Se renderiza como:

Avisos

Los avisos destacan información importante. type es info (el predeterminado), note, tip, warning o danger, y title sustituye al encabezado que da el tipo:

<htmlpress-callout><p>This is a note.</p></htmlpress-callout>

<htmlpress-callout type="warning" title="Breaking Change">
  <p>This API has been removed in v2.</p>
</htmlpress-callout>

:::info
This is a note.
:::

:::warning[Breaking Change]
This API has been removed in v2.
:::

Se renderiza como:

Los encabezados dentro de un aviso quedan fuera de la tabla de contenidos de la página.

Desplegables

No hace falta ningún componente: el tema da estilo a un <details> simple.

<details>
  <summary>Click to expand</summary>
  <p>Hidden content here with <strong>HTML</strong> support.</p>
</details>

:::details[Click to expand]
Hidden content here with **Markdown** support.
:::

Se renderiza como:

Puedes anidar cualquier HTML dentro, incluidos bloques de código, listas y avisos:

site: https://htmlpress.dev
title: Htmlpress

Pestañas de código

Las pestañas que contienen solo bloques de código se unen en un único bloque enmarcado. Cada <section> es una pestaña, con el nombre de su title:

<htmlpress-tabs sync="lang">
  <htmlpress-tab title="JavaScript"><pre><code>console.log("hello")</code></pre></htmlpress-tab>
  <htmlpress-tab title="Python"><pre><code>print("hello")</code></pre></htmlpress-tab>
</htmlpress-tabs>

```js tab="JavaScript" sync="lang"
console.log("hello")
```

```python tab="Python"
print("hello")
```

Se renderiza como:

console.log("hello")

print("hello")

Añade sync="key" para mantener sincronizados los grupos de pestañas, como se describe más abajo en Pestañas de contenido.

Pestañas de contenido

Agrupa contenido arbitrario en pestañas con <htmlpress-tabs>, una <htmlpress-tab title> por pestaña.

Añade un atributo sync para sincronizar la selección de pestañas entre grupos de pestañas. Cuando un lector selecciona una pestaña en un grupo, todos los demás grupos con la misma clave sync cambian a la pestaña correspondiente, y la elección se recuerda entre páginas en localStorage.

<htmlpress-tabs sync="channel">
  <htmlpress-tab title="cargo"><p>From crates.io, built on your machine.</p></htmlpress-tab>
  <htmlpress-tab title="npm"><p>A prebuilt binary per platform.</p></htmlpress-tab>
  <htmlpress-tab title="pip"><p>A binary wheel.</p></htmlpress-tab>
</htmlpress-tabs>

:::tab{title="cargo" sync="channel"}
From crates.io, built on your machine.
:::

:::tab{title="npm"}
A prebuilt binary per platform.
:::

:::tab{title="pip"}
A binary wheel.
:::

Se renderiza como (ambos grupos comparten sync="channel"; cambia uno):

cargo install htmlpress

npm install -g gethtmlpress

pip install htmlpress

Pasos

Un encabezado con data-step es un paso numerado, y los pasos se cuentan a lo largo de la página; su contenido lo sigue como siempre. Esos encabezados quedan fuera de la tabla de contenidos de la página.

<h3 data-step>Install</h3>
<p>…</p>
<h3 data-step>Write a page</h3>
<p>…</p>

### Install [step]

…

### Write a page [step]

…

Se renderiza como:

Instala

Elige un canal en las pestañas de arriba.

Escribe una página

Cualquier archivo .html de la carpeta.

Arranca

Ejecuta htmlpress start y abre la URL que muestra.

Tarjetas

Las tarjetas en <htmlpress-cards> llenan dos columnas, una sola en pantallas estrechas. El title de una tarjeta es su encabezado, un href hace clicable toda la tarjeta, un icon se muestra antes del título en el color de acento, y su contenido es el cuerpo de la tarjeta.

<htmlpress-cards>
  <htmlpress-card title="Getting Started" href="/introduction/" icon="rocket">
    <p>Learn how to set up your first project.</p>
  </htmlpress-card>
  <htmlpress-card title="Plain HTML"><p>…</p></htmlpress-card>
</htmlpress-cards>

:::card{title="Getting Started" href="/introduction/" icon="rocket"}
Learn how to set up your first project.
:::

:::card{title="Plain HTML"}
…
:::

Se renderiza como:

Los encabezados dentro de una tarjeta quedan fuera de la tabla de contenidos de la página.

Insignias

Una etiqueta en línea. variant es secondary u outline para un estilo más sobrio, o positive, warning o destructive para un tono; sin él, el color de acento.

<htmlpress-badge>New</htmlpress-badge>
<htmlpress-badge variant="positive">Stable</htmlpress-badge>

:badge[New] :badge[Stable]{variant="positive"}

Se renderiza como: Nuevo Secundaria Estable Beta Eliminado Contorno

Botones

<htmlpress-button href label> es una llamada a la acción que enlaza a su href. variant es secondary, outline, ghost o link para uno más discreto, y positive, warning o destructive para uno con tono; size es sm o lg.

<htmlpress-button href="/introduction/" label="Get Started"></htmlpress-button>
<htmlpress-button href="…" label="GitHub" variant="secondary"></htmlpress-button>

::button[Get Started]{href="/introduction/"}

::button[GitHub]{href="…" variant="secondary"}

Se renderiza como:

Empezar GitHub Contorno Enlace

Iconos

<htmlpress-icon name="…"> dibuja en línea un icono integrado de Lucide, con el color y el tamaño del texto; los mismos nombres van en el icon de un enlace o de una sección. Un nombre desconocido hace fallar la compilación. Estos son los 114 integrados:

<htmlpress-icon name="rocket"></htmlpress-icon> Get started

:icon{name="rocket"} Get started

Árbol de archivos

Una lista anidada dentro de <htmlpress-filetree>; un elemento que contiene una lista es una carpeta.

<htmlpress-filetree>
  <ul>
    <li>docs<ul><li>index.html</li></ul></li>
    <li>htmlpress.yaml</li>
  </ul>
</htmlpress-filetree>

:::filetree
- docs
  - index.html
- htmlpress.yaml
:::

Se renderiza como:

Columnas

<htmlpress-columns> coloca sus hijos uno junto a otro, dos por defecto y hasta cuatro con cols, cada <htmlpress-column> una columna:

<htmlpress-columns cols="2">
  <htmlpress-column><p><strong>Left column</strong> with content.</p></htmlpress-column>
  <htmlpress-column><p><strong>Right column</strong> with more content.</p></htmlpress-column>
</htmlpress-columns>

:::column
**Left column** with content.
:::

:::column
**Right column** with more content.
:::

Se renderiza como:

Tokens del tema

Los colores, las fuentes y los anchos son propiedades personalizadas de CSS en :root, con un conjunto oscuro bajo prefers-color-scheme o el selector de tema de la cabecera: --htmlpress-accent, --htmlpress-accent-text, --htmlpress-banner, --htmlpress-banner-text, --htmlpress-highlight, --htmlpress-highlight-text, --htmlpress-bg, --htmlpress-surface, --htmlpress-text, --htmlpress-muted, --htmlpress-border, --htmlpress-info, --htmlpress-success, --htmlpress-warning, --htmlpress-danger, --htmlpress-font, --htmlpress-mono, --htmlpress-radius, --htmlpress-shadow, --htmlpress-width y --htmlpress-nav-width. Sobrescríbelas desde la hoja de estilos propia de una página:

:root {
  --htmlpress-accent: oklch(0.6 0.18 30);
  --htmlpress-font: "Inter", system-ui, sans-serif;
  --htmlpress-width: 52rem;
}

Layout

El layout es HTML simple. Htmlpress rellena su <head> (charset, viewport, título, descripción, etiquetas de vista previa social, enlace canónico, favicon, el tema, los estilos y scripts de los componentes que usa la página, las etiquetas head de htmlpress.yaml y, por último, las etiquetas de head propias de la página) y sustituye estos elementos al compilar:

<htmlpress-content>

El contenido de la página.

<htmlpress-brand>

El título del sitio con la description debajo, después del logo si está definido, enlazando al inicio.

<htmlpress-banner>

El banner de htmlpress.yaml.

<htmlpress-breadcrumbs>

El inicio, cada carpeta por encima de la página (con el nombre y el enlace de su página índice cuando la tiene) y, por último, la página.

<htmlpress-nav>

Las páginas de la sección abierta (todas las páginas si no hay sections), agrupadas por carpeta superior bajo una etiqueta "Artículos" ("Entradas" en un blog, "Versiones" en un changelog); el grupo de una carpeta lleva el nombre de su página índice y enlaza a ella. Las secciones de la barra lateral la abren y los links de la barra lateral la cierran, bajo "Enlaces".

<htmlpress-links>

Las secciones de la cabecera, con la abierta marcada, y después los links de la cabecera de htmlpress.yaml.

<htmlpress-page-toc>

Los <h2> y <h3> de la página, resaltando el que está a la vista. Un encabezado sin id recibe uno a partir de su texto.

<htmlpress-pager>

Las páginas anterior y siguiente en el orden de la navegación.

<htmlpress-edit>

Un enlace "Editar esta página" a partir de edit en htmlpress.yaml.

<htmlpress-search>

Búsqueda en todas las páginas, con el script: un botón en la cabecera, que también se abre con S, / o ⌘K / Ctrl K. La compilación escribe el índice en _htmlpress/search.json, dividido en los encabezados de cada página, y el diálogo lo carga la primera vez que se abre. Coincide cualquier palabra de la consulta, como inicio de palabra o con una errata; un resultado abre su página con ?highlight= y la consulta, cuyas coincidencias se pintan con --htmlpress-highlight y se desplazan a la vista. Por debajo de 56rem el campo ocupa la cabecera en lugar de un diálogo.

<htmlpress-toolbar>

Un enlace a la copia en Markdown de la página; el script añade "Copiar Markdown", "Abrir en ChatGPT" y "Abrir en Claude".

<htmlpress-footer>

Un crédito "Hecho con Htmlpress".

<htmlpress-language>

El selector de idioma, que enlaza a esta página en cada idioma, como menú desplegable o, en un móvil, en una hoja; solo en un sitio con traducciones.

<htmlpress-shortcuts>

Un menú de la cabecera con los atajos de teclado, con el script, que lista todas las teclas y desactiva las que la página no atiende, como L sin página siguiente; una fila también pulsa su tecla. Oculto por debajo de 56rem, donde no hay teclado.

<htmlpress-skip>

El enlace "Saltar al contenido", que solo se muestra al recibir el foco.

Cada texto que muestran estos elementos y sus scripts aparece en el idioma de la página. Los scripts leen los suyos de un <script type="application/json" id="htmlpress-messages"> que htmlpress escribe en el head, y sin él recurren al inglés.

Un elemento sin nada que mostrar se elimina. <htmlpress-nav-toggle> (la barra lateral como cajón en un móvil; en pantallas más anchas, pliega la barra lateral y lo recuerda), <htmlpress-theme-toggle> (un menú con claro, oscuro y la elección del sistema, desplegable o, en un móvil, en una hoja) y <htmlpress-back-to-top> los construye el script en el navegador. Sus teclas coinciden con las de Livemark: M muestra u oculta la barra lateral, T alterna entre claro y oscuro y U vuelve arriba, mientras que J y K desplazan cualquier página hacia abajo y hacia arriba y D va al final. Con un <htmlpress-pager> en la página, L y H van a la página siguiente y a la anterior. Ninguna se activa mientras escribes en un campo.

Cada hoja del móvil, el contenido, el tema, el idioma y el selector de secciones de la barra lateral, es un mismo <htmlpress-sheet> que los scripts añaden al body. Se cierra al deslizarla hacia abajo, al tocar el fondo, con Esc o con su botón de cerrar, así que escapar components/sheet/sheet.css les da estilo a todas.

El marco que los rodea también está hecho de elementos. No contienen nada propio, solo dan estilo y colocan lo que hay dentro, así que un layout conserva los que quiere y les da roles de landmark como atributos:

<htmlpress-shell>

La barra lateral junto al resto; apilados en un móvil.

<htmlpress-sidebar>

La marca y la navegación; un cajón en un móvil.

<htmlpress-main>

La columna junto a la barra lateral.

<htmlpress-header>

La barra fija de arriba, que muestra su marca y su botón de menú solo en un móvil.

<htmlpress-page>

El <main> que contiene, junto al aside.

<htmlpress-aside>

La columna junto al contenido, oculta cuando está vacía o la pantalla es estrecha.

Un .htmlpress/layout.html en el proyecto sustituye al layout integrado, y una página puede elegir el suyo en .htmlpress/layouts/. Los estilos y el script de cada componente se pueden sustituir o añadir de la misma forma: consulta Sobrescritura/Escape.