Structuring CV Data in RenderCV: Headers, Sections, and Entry Types

RenderCV takes one YAML file and gives you back a typeset PDF. Everything you write about yourself lives under a single top level key, and that key is what this lecture is about: the header at the top, the sections underneath it, and the nine entry types the sections are built from. Here is the start of such a file. The key is called cv, and it holds the whole of your content. Under it, three plain strings. A name, a headline, and a location. None of them is compulsory, and none of them is parsed: they are printed as you typed them. Then one more key, sections, and everything below the header hangs off it. Its keys are the titles you want printed. Here a summary, written as a single line of text, and then an experience section with one job in it. Now put the finished page beside it. The name is set largest, across the top, with the headline and the location under it. Each key under sections becomes a heading with a rule beneath it, and the entries you listed are set below that. The second key gives the second heading, in the order you wrote them. So the file has two halves. The header fields, which are all optional, and the sections, which carry the content. We will take the header first, then the one rule every section has to obey, and then each entry type in turn.

The header is everything above the first section heading. Every field in it is optional, so begin with a blank page and add only what you want on it. Under cv, the name comes first. It is the line set largest, across the top. A headline goes under it, one short line for your role. Then a location, printed exactly as you typed it. Next, the ways to reach you: an email address, a phone number, and a website. These are gathered into one row of links beneath your name. Write the phone number in full international form. How it is displayed, national, international, or E164, is decided over in the design half of the file, by this long field name. Add a photo, and RenderCV places the image itself on the page. Emails, phone numbers and websites can each be a list rather than a single value. One address looks like this. Several of them look like this: the key on its own, then a list underneath. They are printed in the order you wrote them. Networks that RenderCV knows about have a field of their own. Social networks takes a list, and each item is a pair: which network, and your username on it. Two pairs here, LinkedIn and GitHub. Each pair becomes one link, carrying that network's own icon, and the address is built for you. For anything else there are custom connections. Give the text you want shown, the address behind it, and the name of a Font Awesome icon. Leave the address out and the item is printed as plain text beside its icon, which is a tidy way to show something that is not a link. The icon names themselves come from the Font Awesome search page. That is the header: nine fields, every one of them optional, and RenderCV lays out whatever you provide. Now the sections underneath it.

On the finished page a section is just a title, a rule under it, and the entries beneath. In the file, one section is one key with a list under it. So sections is a dictionary, not a list. Its keys are the titles you want printed, and its values are lists of entries. A title can be any string, and it is printed exactly as written. Nothing about that name tells RenderCV what kind of entries are inside. Which means one section can be written in several ways. Here is the same job, three times over. First as an experience entry, with the company and the position as separate keys. Second, the same job as a normal entry. One name, and the dates. Everything else about it is optional. Third, as bullet entries: one line each, with the emphasis written in Markdown. Same section title, three quite different layouts. So the name of a section never decides its entry type. You pick the type that suits the content, section by section. There is one rule to obey. Here a section starts as an experience entry, and then a school is added underneath it as an education entry. RenderCV will not take it. Mixing two types inside one section is refused, so keep one type per section and open a second section for the other. One dictionary of titled sections, and one entry type inside each. Next, the types themselves.

RenderCV gives you nine entry types. They differ in the keys they accept and in how they are laid out on the page. Four of them carry dates and highlights, and this part is about those four: education, experience, publication, and normal. The remaining five are the compact ones, a single line or a single field each, and they come later. Start with the education entry, for a school. It has nine fields, and only two of them are required. Those two are the institution, and the area you studied. Everything else may be left out. The degree is a field of its own, so BS, MSc or PhD sits apart from the subject. Dates come as a pair, a start date and an end date, in year and month form. There is also a plain date field, which takes any string you like and overrides that pair, so you use one or the other, never both. Then a location, and highlights, which is a list of strings. Each string in it becomes one bullet under the entry. The experience entry has exactly the same shape, with two different keys at the front: the company, and the position you held there. Everything after that is the pattern you already know: the two dates, with the word present for a job you still hold, then a location, a summary, and the highlights, one line for each accomplishment you want to list. A publication entry needs a title and a list of authors. Write the authors as they should be printed, and wrap your own name in single asterisks to have it emphasised in the list. The rest is optional. A journal or venue, a DOI, a link, and a date. The identifier and the link are rendered for you as addresses. The normal entry is the general purpose one. It needs a single key, the name, and it is what you reach for when nothing more specific fits. Its optional fields are the familiar set: the dates, a location, a summary and highlights. Projects, awards, certificates and talks all sit happily in one of these.

The one line entry has two fields, and both are required: a label, and the details that belong to it. It is what most people use for skills. On the page the label is set in bold, and the details follow it on the same line. One pair, one line. A second pair gives a second line, and a whole skills section is usually four or five of them, stacked. Three of the nine types have exactly one field each. The bullet entry carries a single string, and it is printed as one bullet point. The numbered entry works the same way, except the items are counted for you, upward from one, in the order you wrote them. The reversed numbered entry counts the other way, downward, which is what you want for a publication list where the newest paper comes first. All three take one field and nothing else, so they are the cheapest way to put a plain list on the page. And the last type has no keys whatsoever. You write the string itself, as an item of the list, and that is the entire entry. Each string becomes its own paragraph, which makes this the natural choice for a summary at the top of a CV. That is all nine types.

Every text field in the file accepts Markdown, and there are four forms worth knowing. Two asterisks around a phrase make it bold. Square brackets round the words, then round brackets round the address, give you a link. A single asterisk either side is italic, and backticks set a phrase apart as code, which is handy for file names and flags. Because the PDF is typeset with Typst, Typst's own notation is available in those same fields. Surround an expression with double dollar signs and it is set as mathematics. Typst commands work as well. Write a hash, then the command name, then the content in square brackets. The emphasis command, spelled e m p h, gives you italics, exactly like the phrase standing on the right. One last thing about entries. You may add keys of your own to any of them. Here an experience entry carries a revenue figure, which is not part of any schema. By default nothing happens: the extra key is accepted and then ignored, so it is safe to keep notes in the file. It becomes useful when a template asks for it. The templates field in the design half of the file can print any key you have written, wherever you want it on the page. So, four things to take away. Your content lives under the cv key, and every field of the header is optional. Sections are a dictionary, where the keys are the titles that get printed and the values are lists of entries. Each section holds a single entry type, chosen from the nine. And every text field in the whole file takes Markdown and Typst, while any spare key you write sits quietly until a template calls for it. That is the content half of RenderCV, from top to bottom.