markdown-resume

markdown-resume is a developer tool that converts a plain markdown file into a formatted CV in both PDF and HTML using pandoc.

What is markdown-resume?

markdown-resume is an open-source command-line tool that takes one or more vanilla markdown files from a src/ directory and generates matching .pdf and .html files in an output/ directory. It runs on Linux, macOS, Windows via Docker, and inside GitHub Actions CI, and was originally inspired by Eliseo Papa's markdown-cv project. The tool is distributed as a GitHub repository and as a nietaki/markdown-resume Docker image on Docker Hub.

Key Features

• Pandoc-based conversion — Uses pandoc's markdown parser to convert content, so no Jekyll or LaTeX installation is required for the conversion itself.
• PDF and HTML output — Every source file yields both a PDF (via wkhtmltopdf) and an HTML file, making it easy to publish or print.
• Multiple simultaneous files — Drop several markdown files into src/ (for example one per language) and they all get compiled on a single make run.
• Style selection via front matter — The style variable in each file's YAML front matter picks a stylesheet from the styles/ directory; the title variable becomes the first h1.
• Zero local dependencies with GitHub CI — Push your markdown and the project's workflow compiles everything, then uploads the output as a zip artifact in the Actions summary page.
• File-watching mode — Running make watch rebuilds PDFs automatically whenever a source file changes (Linux only; macOS users can use the Docker workflow instead).
• Docker support — make docker mounts src/ and output/ into a container and regenerates files live, while make docker-simple runs a one-shot compilation using the published latest image.
• Custom styles and hidden text — Styles are plain CSS files, and the sample shows how to include a hidden text block (useful for keyword-rich sections) that appears in the document.

Who is markdown-resume for?

• Software developers who want to keep their CV in Git, review diffs of their work history, and generate professional-looking PDFs without leaving the terminal.
• Multilingual job seekers who need parallel CVs in several languages and want to build all of them from one command.
• Automation-minded users who prefer to trigger a CV build inside GitHub Actions rather than installing pandoc and wkhtmltopdf locally.

Use cases

• Job applications: write your résumé in markdown once and produce a consistent PDF and HTML version for every application.
• Version-controlled CV management: track edits and roll back to older revisions just like source code.
• CI-based distribution: commit your updated resume and fetch the freshly built PDF and HTML from the workflow artifact page instead of emailing files around.

How does markdown-resume work?

Put a markdown file (for example src/sample.md) in the src/ directory, optionally set title and style in its front matter, and run make (or make docker-simple). The build script invokes pandoc to convert the markdown to HTML, then wkhtmltopdf renders the PDF from that HTML, and both files land in output/. To auto-rebuild on changes, use make watch on Linux or make docker on any system with Docker.

Pros and cons

• Pros: No Jekyll or LaTeX dependency; simple make-based workflow; works with any text editor; CI-based builds require nothing installed locally; CSS-based themes are easy to tweak.
• Cons: Local builds require installing pandoc and wkhtmltopdf (plus lmodern for the default font); make watch is Linux-only and the README notes the Docker watch mode does not work on macOS with Podman.

Alternatives

• markdown-cv by Eliseo Papa — a Jekyll-based workflow that inspired this project and uses a similar markdown-to-CV approach with GitHub Pages hosting.

FAQ

Does markdown-resume require LaTeX?

No. The conversion pipeline uses pandoc and wkhtmltopdf only; LaTeX is not installed or invoked. The lmodern package is optional and used only to provide the default font when rendering PDFs locally.

How do I build my resume?

Place your markdown file under src/, then run make from the project root after installing the prerequisites (pandoc, wkhtmltopdf, and optionally lmodern). The generated .pdf and .html files appear in output/.

Can I build without installing anything locally?

Yes. The repository ships a GitHub Actions workflow that compiles every markdown file in src/ and uploads a zip containing the output. You only need to commit and push your markdown file.

How do I change the looks of my CV?

Set the style variable in the markdown front matter to the name of a directory inside styles/. Any CSS files in that directory are included in alphabetical order, so you can add your own theme or tweak the default one.

Does it support multiple CVs at once?

Yes. Put multiple markdown files in src/ and each one is compiled to its own PDF and HTML output. This is handy for maintaining separate language versions of your CV.