Auto-compile CV from LaTeX source to PDF and HTML

[jeremymanning]

Overview

Automatically compile Jeremy Manning's CV from LaTeX source into both PDF and HTML formats. The HTML version should have the same visual appearance as the PDF and include a "Download PDF" link.

Goals

1. Single source of truth: Edit CV in LaTeX, automatically generate PDF and HTML
2. Visual consistency: HTML version should match PDF appearance as closely as possible
3. Easy download: HTML page includes prominent "Download PDF" button/link
4. Automated builds: Changes to LaTeX source trigger regeneration

Implementation Options

Option A: LaTeX → PDF → HTML (via pdf2htmlEX or similar)

• Pros: Perfect visual fidelity
• Cons: Large file size, may not be mobile-friendly

Option B: LaTeX → PDF + LaTeX → HTML (via tex4ht/make4ht)

• Pros: Native HTML, more accessible
• Cons: May require CSS tweaking for visual match

Option C: LaTeX → PDF + Markdown → HTML

• Pros: Clean, maintainable HTML
• Cons: Requires maintaining parallel Markdown or extracting from LaTeX

Recommended: Option B with custom CSS

Use make4ht or tex4ht to convert LaTeX to HTML, then apply custom CSS to match the PDF styling.

File Structure

cv/
  JRM_CV.tex           # LaTeX source
  JRM_CV.pdf           # Generated PDF
  JRM_CV.html          # Generated HTML
  cv-style.css         # Custom styles for HTML version
  build_cv.sh          # Build script

documents/
  JRM_CV.pdf           # Copy for download link (or symlink)

HTML Page Features

• Clean, readable layout matching PDF design
• Responsive design for mobile viewing
• "Download PDF" button prominently displayed
• Print stylesheet that matches PDF
• Proper semantic HTML (headings, lists, etc.)
• Accessible (screen reader friendly)

Build Script Requirements

#!/bin/bash
# build_cv.sh

# Compile LaTeX to PDF
pdflatex JRM_CV.tex
pdflatex JRM_CV.tex  # Run twice for references

# Convert to HTML
make4ht JRM_CV.tex "html5"

# Apply custom styling
# (may need post-processing script)

# Copy PDF to documents folder
cp JRM_CV.pdf ../documents/

Testing Plan

• PDF compiles without errors
• HTML generates without errors
• Visual comparison: HTML matches PDF layout
• All links in HTML work
• Download PDF button works
• Mobile layout is readable
• Print from HTML produces good output

Dependencies

• LaTeX distribution (TeX Live or similar)
• make4ht (for HTML conversion)
• Possibly Node.js for post-processing

Labels

enhancement, automation, documentation

[jeremymanning]

Implementation Plan: Auto-compile CV from LaTeX Source

Overview

This plan implements automated CV compilation from the existing LaTeX source (documents/JRM_CV.tex) to generate both PDF and HTML outputs. The HTML version will be styled to match the site theme and include a prominent PDF download link.

Branch Strategy

git checkout -b feature/auto-compile-cv

Key Technical Decisions

LaTeX to HTML Conversion: make4ht (Option B from issue)

After analyzing the LaTeX source, I recommend make4ht because:

1. The CV uses XeLaTeX with custom fonts (Dartmouth Ruzicka) - make4ht handles this well
2. Produces semantic HTML that can be styled with CSS
3. Better accessibility than PDF-to-HTML conversion
4. Smaller file sizes and mobile-friendly output

Fallback Strategy

If make4ht produces unsatisfactory output, we'll use pandoc as a fallback:

pandoc -s JRM_CV.tex -o JRM_CV.html --metadata title="Jeremy Manning CV"

File Structure

documents/
├── JRM_CV.tex           # LaTeX source (already exists)
├── JRM_CV.pdf           # Generated PDF
└── JRM_CV.html          # Generated HTML (new)

scripts/
├── build_cv.py          # Python build script
└── cv_utils.py          # CV-specific utilities (if needed)

templates/
└── cv.html              # HTML wrapper template with site styling

css/
└── cv.css               # CV-specific styles (or add to style.css)

tests/
└── test_build_cv.py     # Tests for CV build system

.github/workflows/
└── build-cv.yml         # GitHub Actions workflow for CV

Implementation Phases (Parallelizable Batches)

Batch 1: Foundation (Sequential - Must Complete First)

Agent 1: Build Script Development

• Create scripts/build_cv.py with functions:
  • compile_latex_to_pdf() - Run xelatex twice for references
  • compile_latex_to_html() - Run make4ht or pandoc
  • post_process_html() - Apply site styling, add PDF download link
  • validate_output() - Check PDF/HTML generated correctly
• Handle font fallbacks (Dartmouth Ruzicka may not be available on GitHub Actions)

Batch 2: Parallel Development (Can Run Simultaneously)

Agent 2A: CSS Styling

• Create CV-specific CSS that matches site theme (Dartmouth green: rgb(0, 112, 60))
• Style section headings, lists, links
• Add print stylesheet for HTML-to-print consistency
• Ensure responsive design for mobile

Agent 2B: HTML Template

• Create templates/cv.html wrapper with:
  • Site header/navigation (consistent with other pages)
  • Prominent "Download PDF" button
  • Footer with last-updated timestamp
  • Meta tags for SEO

Agent 2C: Test Development

• Create tests/test_build_cv.py with REAL tests (no mocks):
  • Test PDF compilation succeeds
  • Test HTML generation succeeds
  • Test PDF file size > 0 and is valid PDF
  • Test HTML contains expected sections (Employment, Education, etc.)
  • Test all links in HTML are valid
  • Test PDF download link works

Batch 3: Integration (After Batches 1-2)

Agent 3: GitHub Actions Workflow

• Create .github/workflows/build-cv.yml:
  • Trigger on changes to documents/JRM_CV.tex
  • Install TeX Live and required packages
  • Handle font installation or fallback
  • Run build script
  • Commit generated PDF/HTML
  • Run tests

Testing Strategy (NO MOCKS)

Local Testing Before Push

# 1. Compile PDF locally
cd documents && xelatex JRM_CV.tex && xelatex JRM_CV.tex

# 2. Verify PDF
ls -la JRM_CV.pdf  # Should be ~100KB
open JRM_CV.pdf    # Visual verification

# 3. Run HTML conversion
make4ht JRM_CV.tex "html5" || pandoc -s JRM_CV.tex -o JRM_CV.html

# 4. Verify HTML
open JRM_CV.html   # Visual verification in browser

# 5. Run automated tests
python -m pytest tests/test_build_cv.py -v

# 6. Run full test suite
python -m pytest tests/ -v

Test Cases (Real File I/O)

1. PDF Generation Test: Actually compile LaTeX, verify PDF exists and is valid
2. HTML Generation Test: Actually convert, verify HTML structure
3. Content Validation: Parse HTML, verify sections exist (Employment, Education, Publications, etc.)
4. Link Validation: Extract all hrefs, verify they are well-formed URLs
5. Visual Regression (manual): Compare HTML rendering to PDF side-by-side
6. Mobile Responsiveness (manual): Test HTML on mobile viewport

GitHub Actions Workflow

name: Build CV
on:
  push:
    branches: [main]
    paths: ['documents/JRM_CV.tex']
  workflow_dispatch:

jobs:
  build-cv:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install TeX Live
        run: |
          sudo apt-get update
          sudo apt-get install -y texlive-xetex texlive-fonts-extra tex4ht
          
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
          
      - name: Build CV
        run: python scripts/build_cv.py
        
      - name: Run tests
        run: python -m pytest tests/test_build_cv.py -v
        
      - name: Commit changes
        if: github.event_name == 'push'
        run: |
          git config user.name 'github-actions[bot]'
          git config user.email 'github-actions[bot]@users.noreply.github.com'
          git add documents/JRM_CV.pdf documents/JRM_CV.html
          git diff --staged --quiet || git commit -m "Auto-build: Update CV PDF and HTML"
          git push

Font Handling Strategy

The CV uses "Dartmouth Ruzicka" font which may not be available on GitHub Actions. Options:

1. Bundle font: Include .ttf/.otf files in repo (check licensing)
2. Use fallback: Modify LaTeX to use system fonts on CI
3. Pre-build PDF: Only rebuild HTML on CI, use existing PDF

Recommended: Create a font-fallback version of the LaTeX for CI that uses a similar free font (e.g., Linux Libertine, which is already in the LaTeX file as a comment).

Cleanup Plan

Before completing the issue:

1. Remove any temporary files (*.aux, *.log, *.out, etc.)
2. Update .gitignore to exclude LaTeX build artifacts
3. Update notes/ folder with session documentation
4. Ensure no debug code or print statements remain
5. Verify all tests pass locally AND on GitHub Actions

Validation Checklist

• PDF compiles without errors locally
• HTML generates without errors locally
• HTML visually matches PDF structure
• All links in HTML work
• PDF download link works
• Mobile layout is readable
• All 76+ existing tests still pass
• New CV tests pass
• GitHub Actions workflow succeeds
• No LaTeX build artifacts committed
• Documentation updated (README, CLAUDE.md if needed)

Dependencies to Add

# requirements-build.txt additions (if needed)
beautifulsoup4  # Already present
lxml            # For HTML parsing in tests

Risk Mitigation

1. Font issues on CI: Pre-test with fallback fonts, document manual PDF updates if needed
2. make4ht failures: Have pandoc as backup conversion method
3. Complex LaTeX: The CV uses etaremune, multicol, marginnote - test these convert properly

Estimated Agent Allocation

• Batch 1: 1 agent, ~30 min
• Batch 2: 3 agents in parallel, ~20 min each
• Batch 3: 1 agent, ~15 min
• Testing & Integration: 1 agent, ~20 min

Total: ~1.5 hours with parallelization

---

Ready to proceed with implementation after review.

[jeremymanning]

Updated Implementation Plan (Rev 2)

Changes from Rev 1

1. No pandoc fallback - If make4ht doesn't work well, we'll write custom LaTeX-to-HTML parsing with a CSS stylesheet to maintain consistent formatting
2. Font files available - Dartmouth Ruzicka TTF files are now in data/ folder (Regular, Bold, Italic, BoldItalic)
3. CV link update - Change people.html CV link to point to HTML version
4. PDF download button - Add prominent download button at top of HTML CV

---

Updated File Structure

documents/
├── JRM_CV.tex           # LaTeX source
├── JRM_CV.pdf           # Generated PDF
└── JRM_CV.html          # Generated HTML (standalone with embedded styles)

data/
├── DartmouthRuzicka-Regular.ttf
├── DartmouthRuzicka-Bold.ttf
├── DartmouthRuzicka-RegularItalic.ttf
├── DartmouthRuzicka-BoldItalic.ttf
├── publications.xlsx
├── people.xlsx
└── software.xlsx

scripts/
├── build_cv.py          # CV build script
└── extract_cv.py        # LaTeX parser (if make4ht insufficient)

css/
└── cv.css               # CV-specific styles (Dartmouth Ruzicka @font-face)

tests/
└── test_build_cv.py     # CV tests (real compilation, no mocks)

HTML CV Design

<!DOCTYPE html>
<html>
<head>
    <title>Jeremy R. Manning, Ph.D. - CV</title>
    <style>
        @font-face {
            font-family: 'Dartmouth Ruzicka';
            src: url('../data/DartmouthRuzicka-Regular.ttf');
            font-weight: normal;
        }
        /* ... more @font-face for Bold, Italic, BoldItalic ... */
    </style>
    <link rel="stylesheet" href="../css/cv.css">
</head>
<body>
    <div class="cv-download-bar">
        <a href="JRM_CV.pdf" class="download-button" download>
            Download CV as PDF
        </a>
    </div>
    
    <div class="cv-content">
        <!-- CV content here -->
    </div>
</body>
</html>

People Page Update

Change line 74 in people.html:

<!-- Before -->
<p>[<a href="documents/JRM_CV.pdf" target="_blank">CV</a>] ...</p>

<!-- After -->
<p>[<a href="documents/JRM_CV.html" target="_blank">CV</a>] ...</p>

Conversion Strategy

Primary: make4ht

make4ht -x -f html5 JRM_CV.tex

Then post-process to:

• Add PDF download button
• Apply site-consistent CSS
• Embed @font-face for Dartmouth Ruzicka

Fallback: Custom LaTeX Parser

If make4ht output is unsatisfactory, write scripts/extract_cv.py that:

1. Parses LaTeX source directly using regex/custom parsing
2. Extracts sections (Employment, Education, Publications, etc.)
3. Converts LaTeX formatting to HTML (\textbf{} → <strong>, etc.)
4. Handles special environments (etaremune → <ol reversed>, multicol → CSS columns)
5. Generates clean semantic HTML with CSS stylesheet

This ensures consistent formatting matching the original PDF.

Implementation Batches (Updated)

Batch 1: Core Build System

Agent 1: Create scripts/build_cv.py

• compile_pdf() - XeLaTeX compilation
• compile_html() - make4ht or custom parser
• inject_download_button() - Add PDF download bar
• apply_styling() - Apply CV CSS

Batch 2: Parallel Tasks

Agent 2A: CSS Development

• Create css/cv.css with @font-face for Dartmouth Ruzicka
• Match site theme (Dartmouth green)
• Style sections, lists, margin notes
• Responsive design

Agent 2B: Test Development

• Real LaTeX compilation tests
• HTML structure validation
• Link validation
• PDF download button test

Agent 2C: People Page Update

• Update CV link to HTML version
• Update data/people.xlsx director entry
• Rebuild people.html

Batch 3: Integration

Agent 3: GitHub Actions

• Install fonts on CI
• Workflow for CV building
• Integration with existing build-content.yml

Font Installation for CI

- name: Install Dartmouth Ruzicka font
  run: |
    mkdir -p ~/.fonts
    cp data/DartmouthRuzicka-*.ttf ~/.fonts/
    fc-cache -fv

Local Testing Checklist

# 1. Compile PDF
cd documents && xelatex JRM_CV.tex && xelatex JRM_CV.tex

# 2. Generate HTML
python scripts/build_cv.py

# 3. Verify outputs
open JRM_CV.pdf
open JRM_CV.html

# 4. Check PDF download button works
# (click button in browser)

# 5. Run tests
python -m pytest tests/test_build_cv.py -v
python -m pytest tests/ -v

# 6. Verify people.html link
python scripts/build_people.py
open people.html
# Click CV link - should open HTML version

Validation Checklist

• PDF compiles without errors
• HTML generates with correct structure
• Dartmouth Ruzicka font renders in HTML
• PDF download button visible and functional
• CV link in people.html points to HTML version
• All existing tests pass (76+)
• New CV tests pass
• GitHub Actions succeeds
• Mobile layout readable

---

Ready to proceed after approval.