Generate polished PDF and HTML resumes from a single YAML file.

simple-resume

simple-resume is a Python 3.10+ CLI and library for converting structured YAML (or JSON Resume) into PDF, HTML, or LaTeX. Templates and static assets ship with the package so users can render without creating additional content.

Supported platforms

• Python: 3.10+ (tested in CI)
• OS: Linux, macOS, Windows. PDF output uses WeasyPrint; ensure Cairo/Pango/GTK are available on your platform (see Usage Guide).

Installation

# With uv (recommended)
uv add simple-resume

# With pip
pip install simple-resume

Why Simple-Resume

• Keep your resume version-controlled as plain YAML.
• Swap templates, palettes, and formats without rewriting content.
• Pure-Python core with shell adapters; effects are testable and side-effect aware.
• Bundled HTML templates and static assets prevent "TemplateNotFound" errors in wheels/editable installs.

Feature Comparison

Feature	simple-resume	JSON Resume	HackMyResume	Resume.io
Open Source	Yes	Yes	Yes	No
Data Format	YAML + JSON Resume	JSON	JSON/FRESH	Proprietary
Version Control	Yes (Git-friendly)	Yes (Git-friendly)	Yes (Git-friendly)	No (Cloud-only)
Local Processing	Yes (100% private)	Yes (100% private)	Yes (100% private)	No (Cloud storage)
Template System	HTML + Jinja2	JSON themes	Multiple formats	Web builder
LaTeX Support	Yes	No	No	No
Python API	Yes (Native)	No	No	No
CLI Tools	Yes	Yes	Yes	No
Real-time Preview	Yes (HTML + auto-reload)	No	No	Yes
Custom Themes	Yes (Unlimited)	Limited	Limited	Limited (Paid only)
Color Palettes	Yes	No	Limited (Basic)	Limited
Privacy	Yes	Yes	Yes	No (Data stored on servers)
Setup Time	5 min	10 min	15 min	2 min
Learning Curve	Moderate	Easy	Easy	Easiest

See Detailed Comparison for full analysis and use case recommendations.

Development setup

git clone https://github.com/athola/simple-resume.git
cd simple-resume
uv sync --dev --extra utils   # or: pip install -e .[dev,utils]

Quick start (CLI)

Create a minimal YAML in resume_private/input/my_resume.yaml:

Note: JSON Resume (*.json from https://jsonresume.org) is also supported — drop it into your input/ folder and simple-resume will auto-convert it at load time.

Tip: Editor autocomplete is available via JSON Schema at src/simple_resume/shell/assets/static/schema.json (VS Code YAML extension supports schema association).

template: resume_no_bars
full_name: Jane Doe
email: jane.doe@example.com
body:
  Experience:
    - title: Senior Engineer
      company: TechCorp
      start: 2022
      end: Present
      description: |
        - Lead microservices migration
        - Improved latency by 40%

Generate output:

uv run simple-resume generate --format pdf         # PDF
uv run simple-resume generate --format html --open # HTML + open in browser

Built-in templates: resume_no_bars, resume_with_bars, demo (see src/simple_resume/shell/assets/templates/html/). Static assets are stored in .../assets/static/.

Python API

from simple_resume import generate, preview

# Generate with format overrides
results = generate("resume_private/input/my_resume.yaml", formats=["pdf", "html"])
print(results["pdf"].output_path)

# Browser preview with live reload
preview("resume_private/input/my_resume.yaml")

For batch operations:

from simple_resume import ResumeSession

with ResumeSession(data_dir="resume_private") as session:
    session.generate_all(format="pdf")

ATS Resume Scoring

Score resumes against job descriptions using multiple NLP algorithms:

from simple_resume import score_resume

# Score a resume against a job description
result = score_resume(
    resume_text="Senior Python Developer with 5 years experience...",
    job_description="We are looking for a Senior Python Engineer with 5 years of experience..."
)

print(f"Match score: {result.overall_score * 100:.1f}%")
print(f"Status: {result.metadata['scorer_names']}")

# Generate a detailed report
from simple_resume import ATSReportGenerator
from pathlib import Path

report_gen = ATSReportGenerator(
    result=result,
    resume_file="my_resume.yaml",
    job_file="job_description.txt"
)
yaml_report = report_gen.generate_yaml()
# Save to file (shell layer responsibility)
Path("ats_report.yaml").write_text(yaml_report)

Available scoring algorithms:

• TF-IDF + Cosine Similarity (TFIDFScorer): Statistical term frequency analysis
• Jaccard + N-gram (JaccardScorer): Set intersection and phrase overlap
• Exact Keyword (KeywordScorer): Direct keyword matching with fuzzy tolerance
• BERT Semantic (BERTScorer): Contextual embeddings via sentence-transformers (optional)

# Install with BERT support (optional)
uv add simple-resume[bert]

The tournament system combines multiple algorithms using weighted averages to produce detailed scores. See ATS Scoring Rubric for complete methodology.

Customization

• Palettes: --palette "Professional Blue" or --palette path/to/palette.yaml.
• Custom templates: --template custom.html with --templates-dir /path/to/templates.
• LaTeX: set config.output_mode: latex and compile with your TeX toolchain (see Usage Guide).
• Color utilities: simple_resume.core.colors.get_contrasting_text_color for accessibility checks.

Release workflow

Releases are automated via GitHub Actions. To create a new release:

# Tag the version (must start with 'v')
git tag v0.1.2
git push origin v0.1.2

The workflow builds the package, generates a changelog from commit history, and publishes a GitHub release with distribution artifacts.

Workflows & docs

• Guides: Getting Started, Usage, Workflows, Path Handling.
• API Docs: API Reference, API Stability Policy, Shell Layer APIs.
• Architecture: Architecture Guide and wiki/architecture/.
• Migration: Migration Guide (includes generate module reorganization notes).
• Development: Development Guide, Contributing, PDF renderer evaluation.
• Samples: sample/ directory; sample_dark_sidebar.html preview.

Troubleshooting

• TemplateNotFound: confirm installation includes packaged assets (bundled in wheels/editable installs); custom templates require --templates-dir.
• PDF on Linux: install system libs cairo, pango, gdk-pixbuf (WeasyPrint requirement).

Contributing

1. Follow the Development Guide to set up tools.
2. Run make lint and make test (or make check-all validate) before opening a PR.
3. Submit issues or ideas in GitHub Issues or discussions.

License

MIT License. See LICENSE.

Star history