scripts/build-manual.js

Genera el PDF del manual a partir de templates/manual.html usando Playwright (Chromium headless).

Requisitos

Node.js 18 o superior.
Playwright instalado:

cd scripts
npm install
npx playwright install chromium

Si ya tienes la skill playwright-skill de lackeyjb, no necesitas instalar Chromium dos veces: la skill lo trae.

Uso básico

Desde la raíz de la skill:

node scripts/build-manual.js

Esto:

Lee templates/manual.html.
Carga templates/manual.css y templates/manual.js.
Copia artifacts/ a un directorio temporal (si existe).
Renderiza el HTML con Chromium y exporta a dist/manual-{aplicacion}-v{version}.pdf.

Opciones

--html <ruta>            HTML fuente (por defecto templates/manual.html).
--out <archivo>          Ruta exacta del PDF de salida.
--out-dir <carpeta>      Carpeta de salida (por defecto dist/).
--no-background          No imprime colores de fondo.
--landscape              Orientación horizontal.
--margin-{top,bottom,left,right} <valor>
                         Margen CSS cuando --no-css-page-size está activo.
--no-css-page-size       Ignora @page y usa los márgenes dados.
--show-header-footer     Habilita la cabecera/pie nativa de Chromium.
-h, --help               Ayuda.

Ejemplos

Generar el PDF por defecto:

node scripts/build-manual.js

Generar otro manual (por ejemplo, el manual de administración):

node scripts/build-manual.js --html templates/admin.html --out dist/manual-admin-v1.0.0.pdf

Sobrescribir el archivo de salida en una ruta absoluta:

node scripts/build-manual.js --out /tmp/borrador.pdf

Estructura esperada del proyecto

manuales-factorpesca/
├── SKILL.md
├── references/
├── templates/
│   ├── manual.html        # fuente
│   ├── manual.css         # estilos pantalla + impresión
│   └── manual.js          # lógica de presentación
├── scripts/
│   ├── build-manual.js    # este script
│   └── package.json
├── artifacts/             # capturas de pantalla (opcional)
│   ├── 01-login.png
│   └── 02-panel.png
└── dist/                  # PDFs generados (se crea al ejecutar)

Solución de problemas

"No se encuentra 'playwright'": ejecuta npm install en scripts/.
"Chromium no encontrado": ejecuta npx playwright install chromium.
El PDF sale sin color: revisa references/estilo.md y asegúrate de que la regla -webkit-print-color-adjust: exact sigue presente en manual.css.
El índice está vacío: el HTML no contiene elementos con data-chapter o los h1 están fuera de [data-chapters].
Las anotaciones aparecen en otra posición: comprueba que data-annotations use porcentajes (x, y de 0 a 100) y que la imagen ocupe todo el ancho de .screenshot-frame.
La cabecera del PDF no muestra el capítulo: Chromium necesita que el texto se asigne vía string(chapter-title) Paged Media. Si no se ve, asegúrate de que la versión de Chromium es reciente (Playwright 1.40+).

3.1 KiB Raw Blame History