# 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
Experience
{{EXPERIENCE}}
```
### 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.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 |