MkDocs vs Htmlpress
MkDocs es un generador de documentación basado en Python. El contenido es Markdown plano, los layouts son plantillas Jinja2 y los temas son paquetes de Python instalables con pip. El tema de facto es Material for MkDocs, que es el que usa en la práctica la mayoría de los usuarios.
De un vistazo
| Aspecto | Htmlpress | MkDocs |
|---|---|---|
| Lenguaje / runtime | Rust (binario único, sin runtime) | Python 3.8+ |
| Framework de UI | Ninguno (HTML + CSS plano, web components htmlpress-*) |
Plantillas Jinja2 (HTML + CSS) |
| Herramienta de compilación | Binario de htmlpress | CLI de MkDocs |
| Formato de contenido | Páginas HTML y Markdown | Markdown (CommonMark + extensiones de Python-Markdown) |
| Licencia | MIT, autoalojado | BSD-2-Clause, autoalojado |
| Modelo de salida | Estático prerenderizado | Estático prerenderizado |
Arquitectura
htmlpress es un único binario de Rust que se instala desde npm
(gethtmlpress), PyPI o crates.io. Envuelve cada página HTML en un
layout con una navegación y un tema; no hay bundler, ni framework de UI, ni API de
plugins. Cada archivo integrado (el layout, los estilos, los scripts y cada
componente) se puede escapar: un archivo en la misma ruta bajo
.htmlpress/ lo reemplaza. En PyPI se distribuye como un wheel binario,
así que pip install htmlpress no necesita código Python en tiempo de
ejecución.
MkDocs es una CLI de Python. El sitio se configura mediante mkdocs.yml.
Los temas se instalan con pip; el pipeline de compilación pasa el contenido Markdown
por Python-Markdown (o pymdown-extensions) y por plantillas Jinja2. No hay paso de
compilación de JavaScript: la interactividad del sitio renderizado es la que emitan
las plantillas del tema.
Material for MkDocs añade un tema cuidado, un índice de búsqueda basado en lunr.js,
navegación instantánea y un amplio ecosistema de plugins (los extras de
mkdocs-material, además del espacio de nombres más amplio de plugins
mkdocs-* en PyPI).
En htmlpress la disposición del contenido no tiene restricciones: escanea por glob
(include/exclude en htmlpress.yaml, todos los
archivos .html por defecto), y la URL de una página sigue su ruta de
archivo bajo la base del glob, así que docs/**/*.html sirve
docs/guide.html en /guide/. No hace falta una carpeta
docs/. La navegación se construye a partir de las carpetas y del
<meta name="order"> de cada página; el index.html de
una carpeta da nombre a su grupo. MkDocs lee de docs/ (configurable
mediante docs_dir en mkdocs.yml), con rutas derivadas de
las rutas de archivo bajo ese directorio.
Superficie de contenido
MkDocs acepta Markdown con frontmatter; htmlpress acepta por igual páginas HTML y
Markdown con frontmatter. MkDocs extiende Markdown mediante extensiones de
Python-Markdown (admoniciones, pestañas, notas al pie, listas de definiciones) y
pymdown-extensions (que añade toda la sintaxis de Material: pestañas
=== "Tab 1", admoniciones :::note, atajos de teclado
++ctrl++, etc.). Personalizar más allá de lo que ofrecen las
extensiones requiere escribir un plugin de Python o hacer override de una plantilla
Jinja.
Las páginas de htmlpress son HTML semántico plano, al que el tema da estilo a partir
de los propios elementos. Los bloques más ricos son elementos personalizados
htmlpress-* (htmlpress-callout,
htmlpress-tabs, htmlpress-filetree,
htmlpress-cards, …), cuyo CSS y JS se enlazan solo en las páginas que
usan la etiqueta. Un proyecto añade su propia etiqueta con
.htmlpress/components/<name>/<name>.html, que reemplaza la
etiqueta en tiempo de compilación. Aquí esos mismos bloques son elementos HTML
normales: <dl>, <kbd>,
<details>.
htmlpress no tiene frontmatter: los metadatos de una página son su propio
<head> — <title>,
<meta name="description">,
<meta name="order">, <meta name="layout"> y
<meta name="image">; las demás etiquetas de
<head> se conservan. MkDocs lee title,
summary, tags (con un plugin), template, y
usa mkdocs.yml para la navegación.
Matriz de funciones
| Capacidad | Htmlpress | MkDocs |
|---|---|---|
| Versionado | Parcial (una sección o un despliegue por versión) | Sí (mediante el plugin mike) |
| Internacionalización (i18n) | Sí (traducciones, selector de idioma, 7 idiomas de interfaz incluidos) | Sí (plugin i18n de Material) |
| Búsqueda | Sí (integrada, en el cliente) | Sí (integrada, en el cliente) |
| Blog | No | Sí (plugin de blog de Material) |
| Registro de cambios | No | No (manual) |
| Sitemap | Sí (con site definido) |
Sí |
| RSS | No | Mediante plugin |
| Temas | Escapes en .htmlpress/ + tokens --htmlpress-* |
Paquetes de temas + overrides de Jinja |
| Plugins | No (componentes del proyecto en .htmlpress/components/) |
Plugins de Python (mkdocs-* en PyPI) |
| Rutas personalizadas |
Cualquier archivo .html; layouts adicionales en
.htmlpress/layouts/
|
No (solo contenido) |
| Toolchain independiente | Un único binario de Rust (npm, PyPI o crates.io) | Python + pip |
Salida y despliegue
Ambas herramientas producen HTML estático + recursos listos para cualquier hosting
estático. MkDocs emite en site/ por defecto; htmlpress emite en
.htmlpress/build/.
htmlpress escribe cada página como HTML estático en .htmlpress/build/,
junto con robots.txt, un sitemap.xml cuando
site está definido, una copia en Markdown de cada página,
llms.txt y las skills para agentes en
.well-known/agent-skills/. La clave base sirve el sitio
bajo una subruta. Consulta Despliegue para ver guías
por hosting.
Ver también
- Redacción — la superficie HTML de htmlpress.
- Personalización — las claves de configuración y los escapes de htmlpress.
- Comparativa — volver al índice.
Hecho con ❤ y Htmlpress