# MkDocs vs Htmlpress

> Rust + HTML plano frente a Python + Jinja2 + Markdown.

[MkDocs](https://www.mkdocs.org) 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](https://squidfunk.github.io/mkdocs-material/), 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](/es/deployment/) para ver guías por hosting.

## Ver también

- [Redacción](/es/authoring/) — la superficie HTML de htmlpress.
- [Personalización](/es/customization/) — las claves de configuración y los escapes de htmlpress.
- [Comparativa](/es/comparison/) — volver al índice.