Docsify vs Htmlpress

Docsify es una herramienta para sitios de documentación con un enfoque distinto al de todas las demás entradas de esta sección: no genera HTML estático en tiempo de compilación. En su lugar, distribuye un único index.html más un runtime de JavaScript que descarga archivos Markdown en el navegador y los renderiza al vuelo. No hay paso de compilación.

De un vistazo

Arquitectura

htmlpress es un único binario de Rust, instalado 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. Las páginas se prerenderizan a HTML estático en tiempo de compilación; htmlpress start las sirve con recarga en vivo mientras editas.

Docsify no tiene pipeline de compilación. Un sitio es un index.html que carga docsify.js desde un CDN (o desde node_modules) junto con un pequeño objeto de configuración en window.$docsify. En tiempo de ejecución, el script lee el hash de la URL (#/some/page), descarga el archivo .md correspondiente con fetch(), lo pasa por marked para analizar el Markdown y por Prism para el resaltado de sintaxis, e inyecta el resultado en la página. La navegación se basa en el hash por defecto; el modo History API es opcional, pero requiere reescrituras en el servidor.

En htmlpress la estructura del contenido es libre: 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 se exige 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. Docsify lee desde una única raíz de origen (el directorio que contiene index.html, configurable mediante basePath), y la URL de la petición se corresponde directamente con una ruta de archivo en disco: #/guide/install descarga guide/install.md. La navegación lateral se escribe a mano en _sidebar.md; no hay navegación autogenerada.

Superficie de contenido

Docsify admite Markdown simple (CommonMark mediante marked) con un puñado de extensiones integradas: helpers (callouts al estilo > [!TIP] mediante docsify-tabs y los plugins de admoniciones), paso directo de HTML y directivas limitadas al estilo de plantillas de Vue si se carga el compilador opcional de Vue. No hay MDX, ni análisis de frontmatter por defecto (un plugin puede añadirlo), ni componentes de React por página. Los plugins se registran añadiendo funciones a window.$docsify.plugins, donde se enganchan al ciclo de vida (init, mounted, beforeEach, afterEach, doneEach, ready).

Las páginas de htmlpress son HTML semántico simple, 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.

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.

Matriz de funciones

Salida y despliegue

Aquí es donde las herramientas divergen más claramente.

htmlpress genera un directorio de HTML prerenderizado + assets (.htmlpress/build/). Cada página es un archivo HTML real; los rastreadores, las previsualizaciones de enlaces y los clientes sin JS ven el contenido renderizado. 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 de agente en .well-known/agent-skills/. La clave base sirve el sitio bajo una subruta. Consulta Despliegue para ver las guías de hosts.

Docsify distribuye los archivos .md sin procesar junto a index.html. El "despliegue" consiste en subir el directorio fuente a cualquier host estático. La contrapartida: cero tiempo de compilación y edición con solo recargar, a cambio de HTML vacío en el primer pintado; los buscadores, las previsualizaciones sociales y los clientes sin JS solo ven el cascarón del cargador. El proyecto documenta un flujo de SSR/prerenderizado con docsify-ssr o prerenderizadores externos para mitigarlo en sitios sensibles al SEO.

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.