I was dusting off my resume and wanted a way to write it in Markdown because it has an easy to write syntax that allows you to focus on the content and structure of the document. I prefer this over using WYSIWYG editors like Microsoft Word where you need to fiddle around with setting the design while you write the content. Additionally, there is a lot of support in converting Markdown into other formats that allow fine-grained control of the output document's design and layout, which WYSIWYG editors may not support.
With that in mind, I already knew about the document converter, Pandoc, and was using it for basic conversions, like Markdown to HTML. However, I did not know how to use it for creating PDFs, which is probably the most important format your resume can be in. When I tried, it always gave me an error about not having a PDF engine. After searching for a while, finding pandoc_resume, and digging around in the Pandoc documentation, I was inspired to use ConTeXt as my PDF engine and make my own templates based on how I would like my resume to look.
Lots of fiddling later, I had something working. So, I decided to clean it up a bit and share it here. This project does not aim to be as fully featured as pandoc_resume does. Rather, it aims to be a starter template to give others an idea of how to convert their own resume documents into other formats using Pandoc.
Theoretically, since Pandoc's Markdown supports a wide variety of structures, you can also use this template to generate documents other than resumes, but I will leave you to explore that if you wish to.
The following packages need to be installed and be in your PATH:
assets- This is where you will put the images and other media you want to locally reference in your resume/s.
- All local media files must be referenced relative to this directory. See the Images section in
sample.mdfor examples. - The project comes with two sample images,
sample.jpgandsample.png, which are stored here.
build- This is where Pandoc will emit the different document formats generated.
- It automatically gets created when running
generate.sh.
scripts- This contains the scripts that run the batch jobs.
src- This is where you will store your Markdown resume/s.
- This holds
sample.md, which details some ways you can use the project.
templates- This contains the Pandoc templates that are used in this project.
The following scripts are written in shell script, which are usually run on *nix systems. However, they should be runnable in Windows using environments like Cygwin, Git for Windows, or Windows Subsystem for Linux running any POSIX-ish shells such as Bash.
This script deletes all of the files and directories inside of the build directory.
This script coverts the Markdown files inside of the src directory into the specified formats. It takes the following arguments:
./generate.sh <format> <base_names><format> specifies the format to convert to. It can be any of pdf, context, html, docx, odt, rtf, or all. Specifying all will convert the specified Markdown file/s to all supported formats.
<base_names> specifies the base names, without any extensions, of one or more Markdown file/s located in the src directory to convert. Because it relies on base names without any extensions to find the files to convert, this script assumes that you use a .md extension for your Markdown files.
If <base_names> is omitted, all Markdown files within the src directory except for sample.md will be converted into the specified format.
If both <format> and <base_names> are omitted, the format will default to all and all Markdown files within the src directory except for sample.md will be converted.
You can run,
./generate.sh all sampleto see an example of how the supported formats would look using sample.md as input.
Assuming the file src/resume.md exists and does not reference any media,
./generate.sh pdf resumecreates a resume directory inside of the build directory and outputs resume.pdf inside of it using src/resume.md as input;
./generate.sh context resumeoutputs resume.tex in the previously created resume directory; this intermediate format can be useful in debugging any problems with PDF creation or for using Pandoc to do most of the heavy lifting in creating a ConTeXt document, editing some parts to better suit your needs and tastes, and running context resume.tex in the resume directory to create resume.pdf;
./generate.sh all resumeoutputs the following files in the resume directory:
resume.docxresume.htmlresume.odtresume.pdfresume.rtfresume.tex
Assuming the file src/other-resume.md exists and references the image sample.jpg from the assets directory,
./generate.sh html other-resumecreates an other-resume directory inside of the build directory and outputs other-resume.html as well as sample.jpg inside of it; if instead of sample.jpg, src/other-resume.md references the image https://example.com/sample.jpg which has a SHA-1 hash of 9b6fb57ef128201893db6ee99117f5c14601f3b7, then,
./generate.sh html other-resumestill creates an other-resume directory inside of the build directory and outputs other-resume.html. However, instead of also outputting sample.jpg, this time, it will output 9b6fb57ef128201893db6ee99117f5c14601f3b7.jpg;
./generate.sh docx other-resumeonly outputs other-resume.docx inside of the previously created other-resume directory as media files are embedded directly into DOCX files.
Assuming the files src/resume-1.md, src/resume-2.md, and src/resume-3.md exists and do not reference any media,
./generate.sh rtf resume-1 resume-2 resume-3creates resume-1, resume-2, and resume-3 directories inside of the build directory and outputs resume-1.rtf, resume-2.rtf, and resume-3.rtf in their respective directories.
./cleanup.shDeletes all of the previously generated directories and files as well as any other directories and files located inside of the build directory.
-
Due to certain limitations, some structures will look different between PDF and HTML outputs.
-
Only styles the first four levels of headings; this means that it only styles
h1toh4HTML tags andsectiontosubsubsubsectionConTeXt headings. -
Uses colors from the RAL Classic color system as they are used in ConTeXt; below are the specific colors used, their respective approximated hexadecimal values, and where they are used:
RAL color Hexadecimal value Used in RAL 9005 #0a0a0aDocument text RAL 9003 #f4f4f4Document background RAL 7011 #434b4dBlock quote text and border RAL 5015 #2271b3Link text RAL 9018 #d7d7d7Code background
template.tex is used to create both PDF and ConTeXt formats. It is based on the default ConTeXt template used by Pandoc version 2.14.
Since some may not be familiar with using TeX or ConTeXt like I was, I have included some resources below that helped me get started with making this template which may also be helpful to you:
- The ConTeXt website contains documentation and references to other documentation about how to use ConTeXt. The following pages from it may be of particular interest:
- Layout
- Interactions such as links
- Color
- Font switching
- Information about the fonts that come with ConTeXt
- Using graphics such as images
- Search can help you find documentation about different ConTeXt commands.
- Tobias Weh's Units in TeX illustration gives a good visual overview of TeX’s length units and their definitions.
Note: JPEG, PNG, and some other image formats are automatically supported by ConTeXt. However, SVG, GIF, and other media types are not. See their documentation about image conversion and embedding videos if you wish to use these other media formats in your documents.
template.html is based on the default HTML5 template used by Pandoc version 2.11.3.2.
The CSS within template.html is based on the default styles used by Pandoc version 2.14.1.
When converting to this format, emails are obfuscated by encoding them as decimal or hexadecimal, code is highlighted with the monochrome theme, and any inline or display math is styled using KaTeX.
I have removed most of the configurable variables provided by Pandoc in these templates as I did not see the need for them when generating resumes.
The following are the variables that I kept or added, which can be set in your Markdown file/s front matter. Of course, for your templates, you may modify these or add your own.
Default: en
As per the Pandoc documentation,
identifies the main language of the document using IETF language tags ... affects most formats, and controls hyphenation in PDF output when using LaTeX ... or ConTeXt.
Default: None
Sets the value of the HTML <title> element and the PDF Title metadata. When converting to HTML and this is not set, Pandoc will set it to the base name of the file without its extension.
Default: None
Sets the content of the HTML <meta> element with a name property of author and the PDF Author metadata.
Default: None
Sets the content of the HTML <meta> element with a name property of version and the PDF Version metadata. Version is non-standard PDF metadata, so you may need specific tools like this to view this in a generated PDF file.
Default: None
Sets the content of the HTML <meta> element with a name property of description and the PDF Description metadata. Description is also non-standard PDF metadata, so the same caveat noted in version-meta applies.
Default: letter
Sets the paper size of PDF outputs and the paper size when HTML outputs are printed. Typically, this only needs to be set to either letter or A4. However, if you wish to use a different paper size, it is best to use a value that is supported by both ConTeXt and CSS.
The ODT and RTF formats do not have templates, nor does the DOCX format have a reference document. I did not create any as I only included these formats for the sake of completeness. I think that 99% of the time, all you really need are PDF and HTML formats. PDF for job applications, and if you want to, HTML for your personal website.
I may create templates for these formats one day, but it is not really a priority.
When converting to this format, code is highlighted with the monochrome theme.
This format does not seem to support TeX math well, so Pandoc shows a warning when converting a document that has TeX macros like \sqrt{25}. This happens when running ./generate.sh rtf sample as sample.md contains that exact macro.
Additionally, this format does not seem to play well with LibreOffice, as an error occurs when I try to open a generated RTF file that contains embedded images.
If you find anything wrong or would like to suggest any improvements, issues and pull requests are welcome.
You might want to start with the following:
- Updating the templates
- Correcting any edge cases that I might have missed with the templates
- Creating templates for supported formats without templates (i.e., for DOCX, ODT, or RTF formats)
- Adding or suggesting other formats to support
sample.jpgis a photo by Cassie Boca.sample.pngcomes from the finance icon set by Ruma Entertainment.
Copyright 2021-present Matthew Espino
This project is licensed under the Apache 2.0 license.