Rewrite internal PDF links and embed favicon

Embed the site favicon into the generated cover and update the PDF generation flow to rewrite internal documentation links as in-PDF GoTo actions. Changes: inject favicon data URI into pdf-cover.html, adjust cover styles/branding, add PROD_URL, track per-document page offsets while crawling, merge PDFs into a single PDFDocument, and rewrite URI annotations to GoTo destinations using pdf-lib internals (buildPathLookup, extractAnnotUri, rewriteInternalLinks). Also update stage logging/counts and remove an unused sample image (static/img/sample-app.png).

Author: alegauss

scripts/gen-pdf.mjs

@@ -6,6 +6,7 @@
  *   1. Render the branded cover (HTML → PDF)
  *   2. Crawl every documentation page following "next" links, printing each to PDF
  *   3. Merge everything into a single PDF with pdf-lib
+ *   4. Rewrite internal links as in-PDF GoTo hyperlinks
  *
  * Prerequisites:
  *   - Docusaurus serve running on localhost:3000
@@ -15,16 +16,18 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
-import { PDFDocument } from 'pdf-lib';
+import { PDFDocument, PDFName, PDFDict, PDFString, PDFHexString, PDFArray } from 'pdf-lib';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname  = dirname(__filename);
 const ROOT       = join(__dirname, '..');
 
 const COVER_HTML = join(__dirname, 'pdf-cover.html');
 const STYLE_CSS  = join(__dirname, 'pdf-style.css');
+const FAVICON    = join(ROOT, 'static', 'img', 'favicon.png');
 const OUTPUT_PDF = join(ROOT, 'turing-es-2026.1-documentation.pdf');
 const BASE_URL   = process.env.PDF_BASE_URL || 'http://localhost:3000';
+const PROD_URL   = process.env.PDF_PROD_URL || 'https://docs.viglet.com';
 const ENTRY_PATH = '/turing/getting-started/intro';
 
 const HEADER_HTML = [
@@ -60,10 +63,15 @@ async function launchBrowser() {
    Stage 1 — Cover (HTML → PDF)
    ────────────────────────────────────────────────────── */
 async function generateCover() {
-  console.log('  [1/3]  Rendering cover pages …');
+  console.log('  [1/4]  Rendering cover pages …');
 
   const page = await browser.newPage();
-  const html = readFileSync(COVER_HTML, 'utf-8');
+
+  // Embed favicon as base64 data URI in the cover HTML
+  const faviconB64 = readFileSync(FAVICON).toString('base64');
+  const faviconDataUri = `data:image/png;base64,${faviconB64}`;
+  const html = readFileSync(COVER_HTML, 'utf-8')
+    .replaceAll('FAVICON_DATA_URI', faviconDataUri);
 
   await page.setContent(html, { waitUntil: 'networkidle0' });
   await page.evaluateHandle('document.fonts.ready');
@@ -81,33 +89,43 @@ async function generateCover() {
 
 /* ──────────────────────────────────────────────────────
    Stage 2 — Crawl doc pages & print each to PDF
+   Returns { buffers: Buffer[], pageMap: Map<string, number> }
+   pageMap maps URL path → starting page index in merged PDF
    ────────────────────────────────────────────────────── */
-async function generateDocs() {
-  console.log('  [2/3]  Generating documentation pages …');
+async function generateDocs(coverPageCount) {
+  console.log('  [2/4]  Generating documentation pages …');
 
   const cssContent = readFileSync(STYLE_CSS, 'utf-8');
   const page = await browser.newPage();
-  const pagePDFs = [];
+  const buffers = [];
+  const pageMap = new Map();   // path → page index in final PDF
   let url = `${BASE_URL}${ENTRY_PATH}`;
   const visited = new Set();
+  let cumulativePages = coverPageCount;
 
   while (url) {
-    // Normalise to avoid revisiting with trailing slashes etc.
     const normalized = url.replace(/\/+$/, '');
     if (visited.has(normalized)) break;
     visited.add(normalized);
 
-    const pageNum = visited.size;
-    process.stdout.write(`         [${pageNum}] ${normalized.replace(BASE_URL, '')} … `);
+    const docNum = visited.size;
+    const path = normalized.replace(BASE_URL, '');
+    process.stdout.write(`         [${docNum}] ${path} … `);
 
     await page.goto(url, { waitUntil: 'networkidle0', timeout: 30_000 });
 
+    // Capture next URL BEFORE modifying the DOM
+    const nextUrl = await page.evaluate(() => {
+      const next = document.querySelector('a.pagination-nav__link--next');
+      return next?.href ?? null;
+    });
+
     // Inject our PDF stylesheet
     await page.addStyleTag({ content: cssContent });
 
-    // Remove chrome elements from the DOM entirely
+    // Remove chrome elements from the DOM
     await page.evaluate(() => {
-      const selectors = [
+      const remove = [
         '.navbar', '.nav-root', 'nav.navbar',
         'footer', '.footer',
         '.pagination-nav',
@@ -120,11 +138,14 @@ async function generateDocs() {
         '.theme-doc-version-badge',
         '.col--3',
       ];
-      for (const sel of selectors) {
+      for (const sel of remove) {
         document.querySelectorAll(sel).forEach((el) => el.remove());
       }
     });
 
+    // Record page mapping BEFORE printing
+    pageMap.set(path, cumulativePages);
+
     // Print this page to PDF
     const pdfBuf = await page.pdf({
       format: 'A4',
@@ -135,26 +156,27 @@ async function generateDocs() {
       margin: { top: '25mm', bottom: '20mm', left: '15mm', right: '15mm' },
     });
 
-    pagePDFs.push(pdfBuf);
-    console.log('✓');
+    // Count how many PDF pages this doc produced
+    const tmpDoc = await PDFDocument.load(pdfBuf);
+    const pageCount = tmpDoc.getPageCount();
+    cumulativePages += pageCount;
 
-    // Find the "next" pagination link
-    url = await page.evaluate(() => {
-      const next = document.querySelector('a.pagination-nav__link--next');
-      return next ? next.href : null;
-    });
+    buffers.push(pdfBuf);
+    console.log(`✓  (${pageCount}p)`);
+
+    url = nextUrl;
   }
 
   await page.close();
-  console.log(`         ${pagePDFs.length} pages generated ✓`);
-  return pagePDFs;
+  console.log(`         ${buffers.length} sections generated ✓`);
+  return { buffers, pageMap };
 }
 
 /* ──────────────────────────────────────────────────────
    Stage 3 — Merge all PDFs (pdf-lib)
    ────────────────────────────────────────────────────── */
 async function mergePDFs(coverBuf, docBuffers) {
-  console.log('  [3/3]  Merging PDFs …');
+  console.log('  [3/4]  Merging PDFs …');
 
   const merged = await PDFDocument.create();
 
@@ -178,11 +200,91 @@ async function mergePDFs(coverBuf, docBuffers) {
   merged.setProducer('pdf-lib + Puppeteer');
   merged.setCreationDate(new Date());
 
-  const mergedBytes = await merged.save();
-  writeFileSync(OUTPUT_PDF, mergedBytes);
+  return merged;
+}
 
-  const sizeMB = (mergedBytes.length / 1_048_576).toFixed(2);
-  console.log(`         Merged PDF saved (${sizeMB} MB) ✓`);
+/* ──────────────────────────────────────────────────────
+   Stage 4 — Rewrite internal links as in-PDF GoTo
+   ────────────────────────────────────────────────────── */
+
+/** Build lookup table: URL path → page index in merged PDF */
+function buildPathLookup(pageMap) {
+  const lookup = new Map();
+  for (const [path, pageIdx] of pageMap) {
+    const clean = path.replace(/\/+$/, '');
+    lookup.set(clean, pageIdx);
+    if (clean.endsWith('/intro')) {
+      lookup.set(clean.replace(/\/intro$/, ''), pageIdx);
+    }
+  }
+  return lookup;
+}
+
+/** Extract URI string from a PDF annotation's action dict, or null */
+function extractAnnotUri(annot, context) {
+  const aRef = annot.get(PDFName.of('A'));
+  if (!aRef) return null;
+  const aDict = context.lookup(aRef);
+  if (!(aDict instanceof PDFDict)) return null;
+
+  const sName = aDict.get(PDFName.of('S'));
+  if (!sName || sName.toString() !== '/URI') return null;
+
+  const uriObj = aDict.get(PDFName.of('URI'));
+  if (!uriObj) return null;
+  if (uriObj instanceof PDFString || uriObj instanceof PDFHexString) {
+    return { uri: uriObj.decodeText(), aDict };
+  }
+  return null;
+}
+
+/** Resolve a URI to an internal doc path, or null */
+function resolveInternalPath(uri) {
+  let path = null;
+  if (uri.startsWith(BASE_URL))  path = uri.slice(BASE_URL.length);
+  else if (uri.startsWith(PROD_URL)) path = uri.slice(PROD_URL.length);
+  if (!path) return null;
+  const hashIdx = path.indexOf('#');
+  return (hashIdx >= 0 ? path.slice(0, hashIdx) : path).replace(/\/+$/, '');
+}
+
+async function rewriteInternalLinks(merged, pageMap) {
+  console.log('  [4/4]  Rewriting internal links …');
+
+  const context = merged.context;
+  const pathToPage = buildPathLookup(pageMap);
+  let rewritten = 0;
+
+  for (let i = 0; i < merged.getPageCount(); i++) {
+    const annotsRef = merged.getPage(i).node.get(PDFName.of('Annots'));
+    if (!annotsRef) continue;
+
+    const annots = context.lookup(annotsRef);
+    if (!(annots instanceof PDFArray)) continue;
+
+    for (let j = 0; j < annots.size(); j++) {
+      const annot = context.lookup(annots.get(j));
+      if (!(annot instanceof PDFDict)) continue;
+
+      const result = extractAnnotUri(annot, context);
+      if (!result) continue;
+
+      const pathOnly = resolveInternalPath(result.uri);
+      if (!pathOnly) continue;
+
+      const targetIdx = pathToPage.get(pathOnly);
+      if (targetIdx === undefined) continue;
+
+      // Rewrite URI action → GoTo action
+      const targetRef = merged.getPage(targetIdx).ref;
+      result.aDict.set(PDFName.of('S'), PDFName.of('GoTo'));
+      result.aDict.delete(PDFName.of('URI'));
+      result.aDict.set(PDFName.of('D'), context.obj([targetRef, PDFName.of('Fit')]));
+      rewritten++;
+    }
+  }
+
+  console.log(`         ${rewritten} links rewritten as in-PDF navigation ✓`);
 }
 
 /* ──────────────────────────────────────────────────────
@@ -197,14 +299,29 @@ async function main() {
 
   await launchBrowser();
 
-  const coverBuf  = await generateCover();
-  const docBufs   = await generateDocs();
-  await mergePDFs(coverBuf, docBufs);
+  // Stage 1 — Cover
+  const coverBuf = await generateCover();
+  const coverDoc = await PDFDocument.load(coverBuf);
+  const coverPageCount = coverDoc.getPageCount();
+
+  // Stage 2 — Crawl & print docs
+  const { buffers, pageMap } = await generateDocs(coverPageCount);
+
+  // Stage 3 — Merge
+  const merged = await mergePDFs(coverBuf, buffers);
+
+  // Stage 4 — Rewrite internal links
+  await rewriteInternalLinks(merged, pageMap);
+
+  // Save final PDF
+  const mergedBytes = await merged.save();
+  writeFileSync(OUTPUT_PDF, mergedBytes);
 
   await browser.close();
 
+  const sizeMB = (mergedBytes.length / 1_048_576).toFixed(2);
   console.log();
-  console.log(`  ✅  ${OUTPUT_PDF}`);
+  console.log(`  ✅  ${OUTPUT_PDF}  (${sizeMB} MB)`);
   console.log();
 }
 

scripts/pdf-cover.html

@@ -202,22 +202,16 @@
     gap: 4mm;
   }
 
-  .product-dot {
-    width: 10px;
-    height: 10px;
-    border-radius: 2px;
-    display: inline-block;
+  .brand-logo {
+    width: 24px;
+    height: 24px;
   }
-  .dot-turing  { background: #4169E1; }
-  .dot-shio    { background: #FF6347; }
-  .dot-dumont  { background: #006400; }
 
   .brand-name {
     font-size: 11pt;
     font-weight: 700;
-    color: #64748b;
+    color: #94a3b8;
     letter-spacing: 0.08em;
-    margin-left: 2mm;
   }
   .brand-url {
     font-size: 9pt;
@@ -421,14 +415,9 @@
     align-items: center;
     gap: 3mm;
   }
-  .inner-brand-squares {
-    display: flex;
-    gap: 1.5px;
-  }
-  .inner-brand-sq {
-    width: 8px;
-    height: 8px;
-    border-radius: 1.5px;
+  .inner-brand-logo {
+    width: 28px;
+    height: 28px;
   }
   .inner-brand-text {
     font-size: 12pt;
@@ -657,10 +646,8 @@
 
   <!-- Bottom branding -->
   <div class="bottom-brand">
-    <span class="product-dot dot-dumont"></span>
-    <span class="product-dot dot-shio"></span>
-    <span class="product-dot dot-turing"></span>
-    <span class="brand-name">VIGLET</span>
+    <img class="brand-logo" src="FAVICON_DATA_URI" alt="Viglet" />
+    <span class="brand-name">viglet</span>
     <span class="brand-url">viglet.com</span>
   </div>
 </div>
@@ -738,11 +725,7 @@
   <!-- Bottom -->
   <div class="inner-bottom">
     <div class="inner-brand">
-      <div class="inner-brand-squares">
-        <div class="inner-brand-sq" style="background:#006400;"></div>
-        <div class="inner-brand-sq" style="background:#FF6347;"></div>
-        <div class="inner-brand-sq" style="background:#4169E1;"></div>
-      </div>
+      <img class="inner-brand-logo" src="FAVICON_DATA_URI" alt="Viglet" />
       <span class="inner-brand-text">viglet</span>
     </div>
     <span class="inner-url">docs.viglet.com</span>