Htmlpress

Htmlpress es el generador de sitios estáticos para humanos y agentes. Convierte una carpeta de páginas Markdown y HTML en un sitio. Cada página conserva su propio marcado, y htmlpress añade un layout, un tema, una navegación y un servidor de desarrollo con recarga en vivo. Es un único binario de Rust, que se instala desde npm, PyPI o crates.io.

Escribes Markdown sencillo o HTML semántico, o deja que tu agente lo escriba: los agentes los conocen mejor que cualquier lenguaje de plantillas, y cada página acaba con el aspecto del mismo sitio: sin framework, sin configuración de compilación, sin clases utilitarias.

Qué obtienes

• Solo escribe Markdown o HTML. Una página es cualquier archivo .md con frontmatter, o cualquier archivo .html, un documento completo o un simple fragmento, cuyas etiquetas <title> y <meta> hacen lo que hace el frontmatter; consulta Páginas Markdown.
• Un tema que estiliza los elementos. Los encabezados, las tablas, los bloques de código, <details>, <figure> y el resto se ven bien sin clases, en modo claro y oscuro.
• Elementos enriquecidos. Avisos, pestañas, pasos, tarjetas, insignias, árboles de archivos, tablas ordenables, terminales, pestañas de paquetes (npm/pnpm/yarn/bun), diagramas de Mermaid e incrustaciones (YouTube, SoundCloud), todos como elementos personalizados htmlpress-*.
• Navegación gratis. Una barra lateral anidada por carpetas, migas de pan, una tabla de contenidos, enlaces de anterior/siguiente y un enlace «Editar esta página».
• Multilingüe. Traducciones junto a sus originales, un selector de idioma y la interfaz en siete idiomas incluidos; consulta Traducciones.
• Pensado para agentes. Cada compilación publica una copia en Markdown de cada página, llms.txt y tus skills de agente; todos los comandos hablan JSON.
• Personalizable. Tokens --htmlpress-* y sobrescrituras por archivo del layout, los estilos y los componentes mediante una carpeta .htmlpress/.
• Un solo binario. Sin runtime y sin dependencias: un sitio estático con sitemap.xml, robots.txt y una página 404, listo para cualquier hosting.

Inicio rápido

No necesitas nada más que el binario. Todos los canales distribuyen el mismo binario en la misma versión, así que elige el gestor de paquetes que ya use el proyecto.

Instalar

curl -fsSL https://htmlpress.dev/install.sh | sh

npm install --global gethtmlpress
# or run it without installing
npx gethtmlpress --version

pip install htmlpress
# or run it without installing
uvx htmlpress --version

cargo install htmlpress

Hay binarios precompilados para Linux, macOS y Windows en x64 y arm64:

En cualquier otra plataforma, compila con cargo install htmlpress y, para el paquete de npm, apunta HTMLPRESS_BINARY al resultado.

Configurar

La configuración es opcional. Para definir los metadatos del sitio, crea htmlpress.yaml en la raíz de tu proyecto:

title: My docs
description: Documentation for my project
include: docs/**/*.html

Sin include, cada archivo .html del proyecto es una página; con él, solo lo son los que coinciden, servidos sin la base del glob, así que docs/usage.html queda en /usage/. Consulta Archivo de configuración para ver todas las claves.

Añadir contenido

Cada página define su título, descripción y orden en etiquetas que también puede llevar un fragmento:

<title>Getting Started</title>
<meta name="description" content="Set up the project in five minutes." />
<meta name="order" content="1" />

<h1>Getting Started</h1>
<p>Welcome!</p>

---
title: Getting Started
description: Set up the project in five minutes.
order: 1
---

# Getting Started

Welcome!

Consulta Frontmatter para saber qué significa cada etiqueta.

Ejecutar

htmlpress start    # dev server with live reload at http://localhost:8000
htmlpress build    # production build to .htmlpress/build/
htmlpress preview  # serve the production build locally
htmlpress clear    # remove .htmlpress/build/

Ese es todo el ciclo. Añade .htmlpress/build/ a tu .gitignore. Este sitio se compila así a partir de la carpeta rust/docs/ del repositorio.

Estructura del proyecto

Un sitio típico de htmlpress:

Un archivo en .htmlpress/ en la ruta de uno integrado, como layout.html, styles/tokens.css o components/tabs/tabs.css, reemplaza al predeterminado, así que puedes personalizar el layout, el tema y los componentes sin hacer un fork. Ejecuta htmlpress escape <name> para copiar un archivo predeterminado a .htmlpress/, listo para editar.

Comandos

htmlpress build [root]

Renderiza el proyecto en root (por defecto .) en root/.htmlpress/build, reemplazando lo que haya. --out / -o elige otra carpeta; se rechaza una que contenga el proyecto, o una carpeta visible dentro de él, ya que sus páginas se volverían a leer como fuentes.

$ htmlpress build docs
built 6 pages and 0 files into docs/.htmlpress/build

htmlpress start [root]

Compila el proyecto, lo sirve en http://localhost:8000 y lo recompila con cada cambio. Las páginas abiertas se recargan solas después de cada compilación. Una compilación fallida imprime su error y lo muestra en el navegador: sobre las páginas ya abiertas y en lugar de cualquier página que se abra después. El servidor sigue en marcha, aunque falle la primera compilación, y la siguiente compilación correcta recarga todas las páginas.

Si el 8000 está ocupado, prueba el 8001 y sigue hasta el 8009, e imprime la URL que obtuvo. --port / -p indica un puerto concreto (0 elige cualquiera libre). --host solo sirve en todas las direcciones, para que un teléfono en la misma red pueda abrir el sitio, e imprime también esa URL; --host <address> sirve en una. Con base en htmlpress.yaml, el sitio se sirve bajo esa ruta, las URL impresas la incluyen y / lleva allí; reinicia después de cambiar base. --open abre el sitio en el navegador en cuanto escucha; --open <path> abre esa página, bajo base. --out / -o funciona igual que en build.

$ htmlpress start docs --host
serving http://localhost:8000
network http://192.168.1.107:8000

htmlpress preview [root]

Compila el proyecto para producción y lo sirve tal como se desplegará: sin vigilar cambios ni recargar. Acepta --port, --host, --open y --out como start.

htmlpress clear [root]

Elimina la salida de la compilación (--out para indicar otra), con la misma protección que build.

htmlpress escape [names…]

Copia archivos integrados a .htmlpress/ para editarlos: un nombre es una ruta como components/tabs/tabs.js, o la etiqueta de un componente para todos sus archivos. Sin nombres, lista cada archivo integrado e indica si el proyecto lo ha escapado. --root / -r elige el proyecto (por defecto .). Se niega a sobrescribir un archivo; consulta Sobrescritura/Escape.

$ htmlpress escape htmlpress-tabs
escaped .htmlpress/components/tabs/tabs.css
escaped .htmlpress/components/tabs/tabs.js

Para scripts y agentes

La CLI está construida con Fireargs, así que todos los comandos hablan JSON. --json imprime el resultado como JSON y, con un valor, también recibe la entrada como JSON:

$ htmlpress build docs --json
{
  "output": "docs/.htmlpress/build",
  "pages": 6,
  "files": 0
}
$ htmlpress build --json '{"root":"docs","out":"dist"}'

htmlpress start --json y preview --json nunca terminan, así que imprimen {"url": "…", "network": []} en una línea en cuanto el servidor escucha.

htmlpress --llms imprime el esquema de entrada y salida de cada comando como una lista de herramientas con forma de MCP, para que un agente aprenda la CLI sin leer esta página.

Personalización

Htmlpress está pensado para verse bien sin configuración y no estorbarte cuando necesitas más. Personalizaciones habituales:

• Metadatos del sitio: título, descripción, favicon, logo. Consulta Metadatos del sitio.
• Secciones: agrupa las páginas por carpeta en la barra lateral. Consulta Secciones de artículos.
• Enlaces externos: enlaces en la cabecera y la barra lateral hacia cualquier sitio. Consulta Enlaces externos.
• Sobrescritura/Escape: reemplaza el layout, cualquier hoja de estilos o componente desde tu proyecto. Consulta Sobrescritura/Escape.
• Agentes de IA: lo que cada compilación publica para los agentes. Consulta Agentes de IA.

Documentación

La documentación completa está en htmlpress.dev:

• Referencia de redacción: cada elemento y componente con ejemplos
• Personalización: cada opción, con fragmentos listos para copiar y pegar
• Despliegue: publicar la compilación en un hosting
• Contribuir: configuración local y flujo de PR

Recursos

• npm: npmjs.com/package/gethtmlpress
• PyPI: pypi.org/project/htmlpress
• crates.io: crates.io/crates/htmlpress
• GitHub: github.com/datisthq/htmlpress
• Incidencias: github.com/datisthq/htmlpress/issues
• Discusiones: github.com/datisthq/htmlpress/discussions

Licencia

MIT; consulta LICENSE.md.