# Specification — v2 Resume PDF (Playwright) > **Document:** `spec-v2-resume-playwright.md` > **Version:** 0.5.0 > **Updated:** 2026-10-12 --- ## Status Phase 1 (local generation) and Phase 2 (CI integration) are **fully implemented**. All core files: `scripts/generate-resume.ts`, `public/resume-template.html`, `public/fonts/`, `public/profile-photo.webp`, `src/data/resume.ts`, `src/components/sections/DownloadResume.tsx`, `.gitea/workflows/deploy.yml`. --- ## Requirement - Generate `resume.pdf` (A4, multi-page, embedded fonts) during build - Deployed at `/resume.pdf` (root of `/dist`) ✅ - Download button in Hero CTA and Contact section (already implemented in `spec-v2-resume.md`) - PDF content: Header (with profile photo), Experience, Skills, Projects (all) --- ## Phases ### Phase 1: Local Generation (Dev Testing) Mục tiêu: Developer có thể generate PDF locally để test layout, content, pagination trước khi push lên CI. **Scope**: - Tạo `scripts/generate-resume.ts` + `public/resume-template.html` + fonts - Install `playwright`, `tsx` as `devDependency` - Manual command: `pnpm tsx scripts/generate-resume.ts` → `dist/resume.pdf` - **KHÔNG** thêm vào `pnpm build` script - **KHÔNG** Gitea workflow changes **Workflow**: ``` git checkout -b feature/resume-pdf # implement Phase 1 pnpm tsx scripts/generate-resume.ts # test locally # verify PDF, iterate git push && PR ``` ### Phase 2: Gitea Workflow Integration Mục tiêu: PDF tự generate trong CI, deploy cùng site. **Scope**: - Split `deploy.yml` thành 3 jobs (build / generate-resume / deploy) - CI cache cho Playwright browser - Thêm `tsx scripts/generate-resume.ts` vào build pipeline - Artifact management cho PDF **Workflow**: ``` git checkout master # sau khi Phase 1 merged # implement Phase 2 # push → CI tự generate + deploy PDF ``` --- ## PDF Structure ### Page 1: Header + Start of Experience ``` ┌──────────────────────────────────────────┐ │ [Photo] Dong Nguyen │ │ Senior Software Engineer │ │ your.email@example.com │ │ github.com/... │ │ linkedin.com/... │ ├──────────────────────────────────────────┤ │ EXPERIENCE │ │ │ │ Senior Software Engineer │ │ Current Company | 2021 – Present │ │ Ho Chi Minh City, Vietnam │ │ │ │ • System ownership và architecture... │ │ • Developed IoT-DWS integration... │ │ • Led system maintenance... │ │ • Applied Computer Vision... │ │ • Scrum Master responsibilities... │ │ │ │ IoT-DWS Integration System │ │ Context: Tiếp nhận và nhanh chóng... │ │ Technical: HTTP integration, HMAC... │ │ Impact: Giải pháp DWS integration... │ │ Metrics: 16 sortations deployed │ │ Tech: Java, HTTP, HMAC, RocketMQ, DWS │ └──────────────────────────────────────────┘ ``` ### Page 2+: Remaining Content - AWB Detection (if fits with IoT-DWS, else new page) - System Maintenance (if fits, else new page) - Skills section (always starts on new page) - Projects section (each project starts on new page) ### Section Break Rules - **Experience** section starts on a new page (after header) - **Skills** section starts on a new page - **Each Project** starts on a new page - Experience achievements may flow across pages naturally if space permits --- ## Technology ### Library ``` playwright@^1.64.0 # Playwright (Chromium) tsx@^4.23.15 # TypeScript executor (handles .ts imports in Node) ``` - `playwright` full install (includes browser binary ~100MB) - `tsx` — lightweight TS executor for Node (no install overhead) - Installed as `devDependency` - Browser downloaded once, cached in `node_modules/.cache/playwright` ### Build Machine - Gitea runner: `ubuntu-latest` — cần `npx playwright install-deps chromium` cho system dependencies - Local dev: `npx playwright install chromium` (one-time) ### Font Embedding - Font: **Inter** (self-hosted WOFF2) — clean, professional, good Vietnamese support - Embed via `@font-face` with **base64-encoded WOFF2 inline in HTML** (not relative paths — file:// URLs fail in Playwright PDF) - Fallback: `system-ui, -apple-system, sans-serif` --- ## File Structure ``` scripts/ generate-resume.ts # Main build script (TS, executed via tsx) public/ resume-template.html # HTML template (with {{placeholders}}) fonts/ Inter-Regular.woff2 Inter-Medium.woff2 Inter-SemiBold.woff2 Inter-Bold.woff2 profile-photo.webp ``` --- ## Implementation ### 1. Font Setup Download Inter fonts (4 weights: Regular, Medium, SemiBold, Bold) from Google Fonts. Place in `public/fonts/` directory. Script reads each file, base64-encodes it, and injects `@font-face` CSS inline into the HTML template. **Commit font files into repo** (~50KB total). Do NOT add to `.gitignore`. ``` public/fonts/ Inter-Regular.woff2 Inter-Medium.woff2 Inter-SemiBold.woff2 Inter-Bold.woff2 ``` Script generates this CSS at build time: ```css @font-face { font-family: 'Inter'; font-style: normal; font-weight: 400; font-display: swap; src: url('data:font/woff2;base64,{{FONT_REGULAR_BASE64}}') format('woff2'); } @font-face { font-family: 'Inter'; font-style: normal; font-weight: 500; font-display: swap; src: url('data:font/woff2;base64,{{FONT_MEDIUM_BASE64}}') format('woff2'); } @font-face { font-family: 'Inter'; font-style: normal; font-weight: 600; font-display: swap; src: url('data:font/woff2;base64,{{FONT_SEMIBOLD_BASE64}}') format('woff2'); } @font-face { font-family: 'Inter'; font-style: normal; font-weight: 700; font-display: swap; src: url('data:font/woff2;base64,{{FONT_BOLD_BASE64}}') format('woff2'); } ``` ### 2. HTML Template `public/resume-template.html` — static template with `{{placeholder}}` tokens: ```html Resume - Dong Nguyen
Dong Nguyen

{{NAME}}

{{TITLE}}
{{EMAIL}}
{{GITHUB}}
{{LINKEDIN}}
Experience
{{EXPERIENCE}}
Skills
{{SKILLS}}
Projects
{{PROJECTS}}
``` ### 3. Build Script `scripts/generate-resume.ts` — executed via `tsx`: ```typescript import { chromium } from 'playwright'; import { readFileSync, existsSync } from 'node:fs'; import { join, resolve } from 'node:path'; const ROOT = resolve(import.meta.dirname, '..'); // --- Validate required files --- const requiredFiles = [ 'public/profile-photo.webp', 'public/fonts/Inter-Regular.woff2', 'public/fonts/Inter-Medium.woff2', 'public/fonts/Inter-SemiBold.woff2', 'public/fonts/Inter-Bold.woff2', 'public/resume-template.html', ]; for (const file of requiredFiles) { if (!existsSync(join(ROOT, file))) { console.error(`❌ Missing required file: ${file}`); process.exit(1); } } // --- Load data (tsx handles .ts imports natively) --- const { profile } = await import(join(ROOT, 'src/data/profile.ts')); const { experiences } = await import(join(ROOT, 'src/data/experience.ts')); const { skillGroups } = await import(join(ROOT, 'src/data/skills.ts')); const { projects } = await import(join(ROOT, 'src/data/projects.ts')); // --- Read template --- const template = readFileSync(join(ROOT, 'public/resume-template.html'), 'utf-8'); // --- Read and base64-encode assets --- const photoBase64 = readFileSync(join(ROOT, 'public/profile-photo.webp')).toString('base64'); const fonts: Record = {}; for (const [name, weight] of [ ['REGULAR', 'Inter-Regular.woff2'], ['MEDIUM', 'Inter-Medium.woff2'], ['SEMIBOLD', 'Inter-SemiBold.woff2'], ['BOLD', 'Inter-Bold.woff2'], ] as const) { fonts[name] = readFileSync(join(ROOT, 'public/fonts', weight)).toString('base64'); } // --- Generate font-face CSS --- const fontFaces = Object.entries(fonts).map(([key, b64]) => { const weightMap: Record = { REGULAR: 400, MEDIUM: 500, SEMIBOLD: 600, BOLD: 700 }; return `@font-face { font-family: 'Inter'; font-style: normal; font-weight: ${weightMap[key]}; font-display: swap; src: url('data:font/woff2;base64,${b64}') format('woff2'); }`; }).join('\n'); // --- Render HTML helpers --- function renderExperience(exps: Awaited): string { return exps.map(exp => `
${exp.title} ${exp.duration}
${exp.company}
${exp.location ? `
${exp.location}
` : ''}
    ${exp.responsibilities.map(r => `
  • ${r}
  • `).join('')}
${exp.achievements?.map(ach => `
${ach.title}
${ach.context}
${ach.technicalWork?.length ? `
    ${ach.technicalWork.map(t => `
  • ${t}
  • `).join('')}
` : ''}
${ach.technologies.map(t => `${t}`).join('')}
${ach.impact ? `
${ach.impact}
` : ''} ${ach.metrics?.length ? `
${ach.metrics.join(', ')}
` : ''}
`).join('')}
`).join(''); } function renderSkills(groups: Awaited): string { return groups.map(group => `
${group.title}
${group.skills.join(' · ')}
`).join(''); } function renderProjects(projs: Awaited): string { return projs.map(project => `
${project.title}
${project.role}
${project.summary}
${project.technologies.map(t => `${t}`).join('')}
${project.metrics?.length ? `
${project.metrics.join(', ')}
` : ''}
`).join(''); } // --- Assemble HTML --- const html = template .replace('{{NAME}}', profile.name) .replace('{{TITLE}}', profile.title) .replace('{{EMAIL}}', profile.email) .replace('{{GITHUB}}', profile.githubUrl.replace('https://', 'github.com/')) .replace('{{LINKEDIN}}', profile.linkedinUrl.replace('https://', 'linkedin.com/in/')) .replace('{{PHOTO_BASE64}}', photoBase64) .replace('{{FONT_FACES}}', fontFaces) .replace('{{EXPERIENCE}}', renderExperience(experiences)) .replace('{{SKILLS}}', renderSkills(skillGroups)) .replace('{{PROJECTS}}', renderProjects(projects)); // --- Generate PDF --- const browser = await chromium.launch(); const page = await browser.newPage(); await page.setContent(html); // No waitUntil needed — all resources inline const outputPath = join(ROOT, 'dist/resume.pdf'); await page.pdf({ path: outputPath, format: 'A4', printBackground: true, // margin inherited from @page CSS await browser.close(); console.log(`resume.pdf generated at ${outputPath}`); ``` ### 4. package.json **Phase 1** (local dev only): ```json { "scripts": { "build": "tsc -b && vite build" }, "devDependencies": { "playwright": "^1.64.0", "tsx": "^4.23.15" } } ``` Build script **không** chạy PDF generation. Developer chạy manual: ```bash pnpm tsx scripts/generate-resume.ts ``` **Phase 2** (CI integration): ```json { "scripts": { "build": "tsc -b && vite build && tsx scripts/generate-resume.ts" } } ``` ### Data Detection `src/data/resume.ts` — controls whether download button is visible in UI: ```ts // src/data/resume.ts export const resumeAvailable = true // set false when PDF not yet deployed ``` **Phase 1 (dev):** Hardcoded boolean. Developer sets `false` locally until PDF is ready, sets `true` after deployment to verify the button appears. **Phase 2 (CI):** After CI generates and deploys `dist/resume.pdf`, the button will show because `/resume.pdf` exists on the server. > ⚠️ Do NOT use `existsSync` — this file is bundled by Vite for the browser. > Node.js `fs` APIs are unavailable in browser runtime. ### Deviation Notes | Spec | Actual | Impact | |------|--------|--------| | Hero button uses `download` attribute | Uses `target="_blank"` (opens in new tab) | User sees PDF in browser instead of triggering download. Low impact — `/resume.pdf` is typically downloaded by browser automatically. | | `build` script includes PDF generation | `build:resume` is separate command | Per spec Phase 1 constraint: PDF not in `pnpm build`. CI handles PDF in separate `generate-resume` job. | | Artifact retention: PDF 30 days | Actual `retention-days: 1` in deploy.yml | Short retention. Consider increasing if needed. | --- ## Acceptance Criteria ### Phase 1 — **IMPLEMENTED** ✅ | # | Requirement | Status | Notes | |---|-------------|--------|-------| | 1 | `pnpm tsx scripts/generate-resume.ts` produces `dist/resume.pdf` | ✅ | Script at `scripts/generate-resume.ts`, alias `pnpm build:resume` | | 2 | PDF is A4 size, multi-page with correct pagination | ✅ | `@page { size: A4 }` in template, `format: 'A4'` in script | | 3 | Header contains profile photo (circular crop), name, title, contact info | ✅ | Base64 photo, profile data from `src/data/profile.ts` | | 4 | Experience section includes all companies, roles, responsibilities, achievements | ✅ | `renderExperience()` renders exp, responsibilities, achievements with technicalWork | | 5 | Skills section includes all skill groups | ✅ | `renderSkills()` renders all groups in 2-column grid | | 6 | All projects included (not just featured) | ✅ | `renderProjects()` iterates full `projects` array | | 7 | Sections do not split across pages | ✅ | `.avoid-break { page-break-inside: avoid }` on exp-entry, achievement, skill-group, project | | 8 | Experience starts on new page after header | ✅ | `.section + .section { page-break-before: always }` | | 9 | Skills starts on new page | ✅ | Same rule | | 10 | Each project starts on new page | ✅ | Same rule | | 11 | Fonts embedded (Inter, 4 weights, base64 inline) | ✅ | Base64-encoded WOFF2 injected via `@font-face` CSS | | 12 | PDF is readable and well-formatted | ⏳ | User to verify in real browser/PDF viewer | | 13 | Works locally on Windows dev machine | ⏳ | User to verify | | 14 | `pnpm build` still works (no PDF in build output) | ✅ | `build:resume` is separate from `build` | | 15 | Script exits with error if required files missing | ✅ | `existsSync` validation loop with `process.exit(1)` | ### Phase 2 — **IMPLEMENTED** ✅ | # | Requirement | Status | Notes | |---|-------------|--------|-------| | 1 | `pnpm build` produces `dist/resume.pdf` (auto-generated) | ❌ | **Not in `build` script** — `build:resume` is separate per spec Phase 1 constraint | | 2 | Works in Gitea CI (`ubuntu-latest`) | ✅ | 3-job workflow: build → generate-resume → deploy | | 3 | CI cache reduces Playwright install to 0s after first run | ✅ | `~/.cache/ms-playwright` cached on `pnpm-lock.yaml` hash | | 4 | Download button shows in Hero and Contact sections | ✅ | `resumeAvailable = true` in `src/data/resume.ts` | | 5 | PDF deployed to `/resume.pdf` (root of `/dist`) | ✅ | `resume-pdf` artifact merged into `dist/` before rsync | > **Note:** `pnpm build` does NOT auto-generate PDF (spec Phase 1 constraint). Use `pnpm build:resume` for local generation. CI generates PDF in the `generate-resume` job independently. --- ## Tradeoffs ### Phase 1 | Aspect | Detail | |--------|--------| | Install overhead | ~110MB (playwright + tsx) | | Manual command | `pnpm tsx scripts/generate-resume.ts` | | Build time | Not in `pnpm build` — developer controlled | | CSS control | Full CSS (same as website) | | Font embedding | Base64 in HTML, increases HTML size ~50KB | | Photo | Inline base64 (avoids file:// URL issues) | | Platform | Works on Windows local, Ubuntu CI | ### Phase 2 | Aspect | Detail | |--------|--------| | CI build time | +5-10s (download once cached, render ~2s) | | CI first run | +60s (download Playwright browser) | | CI subsequent | +5-10s (cache hit) | | Workflow complexity | 3 jobs (build / generate-resume / deploy) | | Failure isolation | PDF error does not block site deploy | --- ## Future Enhancements Deferred items are tracked in [`spec-v2-resume-future.md`](./spec-v2-resume-future.md): | # | Enhancement | Status | |---|-------------|--------| | 1 | PDF Metadata (title/author) | Deferred | | 2 | Version Stamping (footer date) | Deferred | | 3 | Conditional Content (placeholder detection) | Deferred | | 4 | Project Sections (render text/diagram/metrics/code) | Deferred | | 5 | Multiple Language Versions (EN + VI) | Deferred |