📄 Markdown-based CV Generator

A professional CV generator using Markdown + Jekyll + GitHub Pages with automated PDF pipeline.

[!TIP] Live Demo: Check out the example at doctor500.github.io/cv

---

📚 Table of Contents

• Overview
• Quick Start
• Local Development
• Customization
• PDF Generation Pipeline
• Governance & Git Workflow
• AI Agent Workflows
• Contributing
• License

---

👋 Overview

Create and maintain your professional CV using simple Markdown, with beautiful templates and automated PDF generation. Inspired by elipapa's markdown-cv.

Why This Project?

| Traditional CV | This Project ✨ | |----------------|-----------------| | Word/PDF editing | Simple Markdown editing | | Manual styling & formatting | Multiple professional templates | | Manual PDF creation | Automated PDF pipeline | | Hard to version control | Git-integrated workflow | | Static hosting required | Free GitHub Pages hosting |

✨ Key Features

• ✍️ Markdown-based editing - Write your CV in simple, readable markdown
• 🎨 Multiple templates - Professional designs (kjhealy, davewhipp, doctor-originale-1) ready to use
• 📄 Automated PDF generation - GitHub Actions pipeline creates PDFs automatically
• 🚀 GitHub Pages deployment - Your CV goes live at username.github.io/cv
• 🐳 Docker-based development - Preview changes locally with zero setup
• 🔒 Private build option - Generate PDFs with sensitive data (phone numbers)
• 🔄 Auto-reload preview - See changes instantly during development
• 🤖 AI agent workflows - Pre-built automation for CV updates and template creation

---

🚀 Quick Start

Get your CV live in under 10 minutes!

Prerequisites

• ✅ GitHub account
• ✅ Git installed locally (optional, for local development)
• ✅ Docker installed (optional, for local preview)

Step-by-Step Setup

graph LR
    A[1. Fork Repo] --> B[2. Enable Pages]
    B --> C[3. Edit index.md]
    C --> D[4. Commit]
    D --> E[5. View Live CV]
    E --> F{Happy?}
    F -->|No| C
    F -->|Yes| G[6. Generate PDF]

1️⃣ Fork This Repository

Click the Fork button at the top of this page to create your own copy.

2️⃣ Enable GitHub Pages

1. Go to your fork's Settings → Pages
2. Under Source, select branch: main (or create a gh-pages branch)
3. Click Save
4. Wait 1-2 minutes for deployment

[!IMPORTANT] For fork users: You own your repository, so you can commit directly to main or any branch you choose. No need for feature branches unless you prefer that workflow.

3️⃣ Edit Your CV Content

1. Navigate to index.md in your fork
2. Click the pencil icon (✏️) to edit
3. Replace the content with your own information
4. Follow the existing markdown structure for best results

4️⃣ Commit Your Changes

1. Scroll to the bottom of the edit page
2. Add a commit message (e.g., "Update CV with my information")
3. Click Commit changes

5️⃣ View Your Live CV

• URL: https://[your-username].github.io/[repo-name]
• Example: https://doctor500.github.io/cv
• Wait time: 1-2 minutes after commit

[!TIP] Bookmark your CV URL! It updates automatically every time you commit changes to your branch.

✅ Verify Success

• Visit your GitHub Pages URL
• Your CV should display with the default template
• Try editing index.md again and watch it update

What's Next?

• 🎨 Customize your template for different styling
• 💻 Set up local development to preview before publishing
• 📄 Generate a PDF for job applications

---

💻 Local Development

Preview your CV locally before publishing changes to GitHub Pages.

Choose Your Setup

| Method | Best For | Pros | Cons | |--------|---------|------|------| | Docker 🐳 | Beginners, consistent environment | No Ruby setup needed, works anywhere | Requires Docker install (~20s reload) | | Ruby Server 💎 | Ruby developers, faster iteration | Faster reload, native environment | Requires Ruby/Jekyll setup |

---

Option 1: Docker (Recommended)

[!TIP] Choose Docker if: You want the easiest setup, don't have Ruby installed, or want a consistent environment across machines.

Requirements: Docker Desktop installed (Download here)

# Start Jekyll server
docker-compose up -d

# Verify it's running
curl http://localhost:4000

# Access in browser
open http://localhost:4000  # macOS
# or visit http://localhost:4000 in your browser

# Stop server when done
docker-compose down

Customize the Port:

Edit docker-compose.yml if port 4000 is already in use:

services:
  jekyll:
    ports:
      - '4077:4000'  # Change 4077 to your preferred port

---

Option 2: Ruby Server (Alternative)

[!TIP] Choose Ruby if: You're already a Ruby developer, want faster reload times, or prefer native tooling.

Requirements: Ruby 2.7+ and Bundler installed

# Install dependencies (first time only)
bundle install

# Start Jekyll server
bundle exec jekyll serve

# Access in browser
open http://localhost:4000

# Stop with Ctrl+C

---

Development Workflow

1. Make changes to index.md or CSS templates
2. Wait for auto-reload (~20s for Docker, ~5s for Ruby)
3. Refresh browser to see changes
4. Repeat until satisfied

[!WARNING] Config changes require restart: If you edit _config.yml, stop and restart your server. Markdown file changes auto-reload.

Common Issues & Troubleshooting

<details> <summary><strong>Port 4000 already in use</strong></summary>

Error: Address already in use - bind(2) for 127.0.0.1:4000

Solution: Either stop the process using port 4000, or change the port in docker-compose.yml

# Find what's using port 4000
lsof -i :4000

# Kill the process (replace PID with actual process ID)
kill -9 PID

</details> <details> <summary><strong>Docker permission denied</strong></summary>

Error: permission denied while trying to connect to the Docker daemon socket

Solution: Add your user to the docker group or run with sudo

# Add user to docker group (then log out and back in)
sudo usermod -aG docker $USER

</details> <details> <summary><strong>Changes not showing up</strong></summary>

Solution:

1. Wait the full reload time (~20s for Docker)
2. Hard refresh your browser (Ctrl+Shift+R or Cmd+Shift+R)
3. Check the terminal for build errors
4. If editing _config.yml, restart the server

</details>

---

🎨 Customization

Editing CV Content

Your CV content lives in index.md - this is the single source of truth.

Main sections (in order):

1. Header - Name, title, contact information
2. Profile Summary - Professional overview
3. Technical Skills - Technologies and tools
4. Professional Experience - Work history (reverse chronological)
5. Education - Academic background
6. Activities - Publications, certifications, projects
7. Languages - Language proficiency

[!TIP] Pro tip: Use the /add-cv-section custom command (if you have the .agent/workflows setup) to interactively add new sections with proper formatting!

---

Changing Templates

Available templates in media/ directory:

| Template | Style | Best For | |----------|-------|----------| | kjhealy (default) | Classic two-column, minimalist academic style | Academic, Research, Traditional | | davewhipp | Modern two-column with warm accents | Professional, Corporate, Balanced | | doctor-originale-0 | Clean single-column, print-optimized | Tech, ATS-friendly, PDF-focused | | doctor-originale-1 | Modern single-column with blue theme (print same as -0) | Tech, Startups, Web-first |

[!NOTE] doctor-originale series: All variants share the same print template for consistent PDF output. Differences are in web view styling only.

To switch templates:

1. Edit _config.yml
2. Change the style value:

markdown: kramdown
style: davewhipp  # Options: kjhealy, davewhipp, doctor-originale-1

3. Restart your local server to see changes
4. Commit when satisfied

Each template includes:

• [template]-screen.css - For web display
• [template]-print.css - For PDF generation

[!TIP] Want a custom template? Use the /generate-template workflow (if available) or create your own CSS files following the naming convention above.

---

Advanced Configuration

Jekyll Configuration (_config.yml):

• markdown: kramdown - Markdown engine (don't change unless you know what you're doing)
• style: kjhealy - Template name (matches files in media/ folder)

Layout Template (_layouts/cv.html):

• Defines HTML structure
• Injects CSS based on style setting
• Renders markdown content from index.md

Adding custom sections to index.md:

## New Section Name

`DateRange`
__Position/Title__, Organization

Description of what you did

- Achievement 1 with **metrics** in bold
- Achievement 2

---

📄 PDF Generation Pipeline

Automatically generate professional PDFs from your CV using GitHub Actions.

How It Works

graph TD