95 lines
3.1 KiB
Markdown
95 lines
3.1 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
node scripts/build-manual.js
|
|
```
|
|
|
|
Esto:
|
|
|
|
1. Lee `templates/manual.html`.
|
|
2. Carga `templates/manual.css` y `templates/manual.js`.
|
|
3. Copia `artifacts/` a un directorio temporal (si existe).
|
|
4. Renderiza el HTML con Chromium y exporta a `dist/manual-{aplicacion}-v{version}.pdf`.
|
|
|
|
## Opciones
|
|
|
|
```text
|
|
--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:
|
|
|
|
```bash
|
|
node scripts/build-manual.js
|
|
```
|
|
|
|
Generar otro manual (por ejemplo, el manual de administración):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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+).
|