Creating a digital CV in Markdown on GitHub
Tags: career, markdown, github, tutorial
Published: 2020-09-08 21:19:53

---
title: Creating a digital CV in Markdown on GitHub
published: true
description: How to build and host a digital CV using GitHub Pages and a README.md
tags: 
  - career
  - markdown
  - github
  - tutorial
canonical_url: https://workwithcarolyn.com/blog/digital-cv-guide
---

In early August, I announced on Twitter that I was looking for my next role. My tweet included a link to [my digital CV](https://carolstran.github.io/cv/) and ever since I’ve received a lot of questions about how I built it. So here’s a short guide!

> This guide is based on a Twitter thread that I saw back in 2017. Unfortunately, I can’t remember who posted it… but if it was you, please know that I really appreciate you!

⚠️ Prerequisites:

* [GitHub account](http://github.com/)
* Comfort with [Markdown](https://www.markdownguide.org/)

✅  Steps:

1. [Create a new public repository on GitHub](#create-a-new-public-repository-on-github)
2. [Enable GitHub Pages for your repository](#enable-github-pages-for-your-repository)
3. [Select a theme (design template) for your CV](#select-a-theme-design-template-for-your-cv)
4. [Write your CV in Markdown](#write-your-cv-in-markdown)
5. [Enjoy](#enjoy-your-new-digital-cv) 💅🏼
6. [Optional: Set up a custom domain](#optional-set-up-a-custom-domain)
7. [Show me your CV](#show-me-your-cv) 💌

## Create a new public repository on GitHub

Everything we need for our digital CV will live in a repository on GitHub. 

To start, [**create a new repository**](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-new-repository) without a template.

![The GitHub top-level navigation. The cursor is clicking "New repository".](https://user-images.githubusercontent.com/26869552/92525736-a8070c00-f224-11ea-95bb-d5ae805bf3a8.png)

Choose a name (I called my `cv`) and include a description if you want. Make sure it's public.

> This digital CV will be hosted with GitHub Pages, which [requires your repository to be public](https://docs.github.com/en/github/working-with-github-pages/about-github-pages).

And finally, **don't initialize it with anything**.

> While you won't be importing an existing repository, it helps makes the process less complicated to start with a completely blank repository. You'll see why later!

![The new repository's settings. Most important is that it's public and not initialized with anything.](https://user-images.githubusercontent.com/26869552/92525986-0c29d000-f225-11ea-87e8-6de9f36145c5.png)

## Enable GitHub Pages for your repository

Your digital CV will be hosted with [GitHub Pages](https://pages.github.com/). GitHub Pages allows you to host personal and project pages directly from a GitHub repository. It’s great because it’s free and the functionality is built-in to GitHub so there’s no need for an additional account or a complex build pipeline.

To enable GitHub Pages for your CV, **go to your repository’s Settings page**. 

![Repository's menu bar with a box around Settings.](https://user-images.githubusercontent.com/26869552/92526111-3aa7ab00-f225-11ea-991e-462f5075f222.png)

Scroll until you find the **GitHub Pages section**. There are two subsections here: Source and Theme Chooser.

![GitHub Pages section of the Settings. This will be described later in the article.](https://user-images.githubusercontent.com/26869552/92526194-5c089700-f225-11ea-827f-ac3d8ea70e9c.png)

Under Source, it should say, _“GitHub Pages is currently disabled. You must first add content to your repository before you can publish a GitHub Pages site.”_ Because your repository is empty, you have no branches and you’re unable to select a source. _That’s ok!_ This will be taken care of momentarily.

The subsection you want is **Theme Chooser**. Here, you’ll select a design template for your site. This will then create a `gh-pages` branch and publish your site with your selected theme from that branch. 

> All of the options are [Jekyll](https://jekyllrb.com/) themes. **If you don’t know Jekyll, that’s ok.** This guide will walk you through the necessary configuration. Honestly, I have no idea how Jekyll works beyond GitHub Pages templates.

## Select a theme (design template) for your CV

CVs are supposed to give future employers an idea of who you are - so choose a theme that speaks to you! For this guide, we’ll continue with the **“Minimal” theme** as an example because that’s the one I use for [my CV](https://carolstran.github.io/cv/).

![Theme selection page, with a focus on the Minimal theme. Below the selection bar, there is a preview of this theme.](https://user-images.githubusercontent.com/26869552/92526408-bd306a80-f225-11ea-9d05-aea06ab800a3.png)

Once you select your theme, you’ll be prompted to edit a new `index.md` file. 

![Markdown editor page with a new index.md file and some boilerplate content.](https://user-images.githubusercontent.com/26869552/92526516-ecdf7280-f225-11ea-9e10-72a637d645fd.png)

Before you dive into that, there are a few things that happened in the background that you should know about…

* A new `gh-pages` branch was created (as mentioned earlier).
* This `index.md` file was created. 
* Jekyll theme was set to “Minimal”.

GitHub Pages confirms your theme selection by creating a file called **`_config.yml`**. By default, this file will only contain a `theme` field with your selection. 

Here’s what the `_config.yml` will look like if you select the "Minimal" theme:

```yml
theme: jekyll-theme-minimal
```

For my CV, I also added `title` and `description` fields:

```yml
theme: jekyll-theme-minimal
title: 💻✒️📄🌟
description: Carolyn Stransky's CV
```

You can check out all of the configuration possibilities in the [Jekyll documentation](https://jekyllrb.com/docs/configuration/).

## Write your CV in Markdown

Alright, back to the generated file. This is where all of the content for your CV will be.

First, you should **rename that `index.md` file to `README.md`**. This is optional, but having it as a README allows people to see your CV’s content immediately when they visit your repository. This is especially useful if you decide to [pin your CV repository to your GitHub profile](https://github.blog/2016-06-16-pin-repositories-to-your-github-profile/).

> If there’s no `index.md` present, then your README will work automatically with GitHub Pages - no additional configuration required.

Then, you can write your CV ✍🏻

![New file is now named README.md. The boilerplate content has been replaced with personal CV information.](https://user-images.githubusercontent.com/26869552/92526956-94f53b80-f226-11ea-8b60-a009dfea40de.png)

You’ll [write and style your content using Markdown](https://guides.github.com/features/mastering-markdown/) and then it will be rendered according to your selected theme.

For tips on how to showcase your skills effectively, I’d recommend Monica Lent’s article: [7 software developer resume tips to help you stand out](https://monicalent.com/blog/2020/04/21/software-developer-resume-tips/). If you’re looking for inspiration on how to style your content in Markdown, you can also [check out my digital CV](https://carolstran.github.io/cv/). 

Once you’re satisfied, **commit your changes** to the `gh-pages` branch. 

## Enjoy your new digital CV

It might take a few minutes to go live - but **your fresh, new, digital CV should now be available on the interweb** 🎉

In most cases, your page will be hosted at the following url:

```
<github-username>.github.io/<repository-name>
```

You can always confirm that your CV is published and what the url is by navigating back to the GitHub Pages section in your repository’s settings.

> If your digital CV isn’t updating after pushing a commit and waiting a few minutes, try doing a [hard refresh](https://www.getfilecloud.com/blog/2015/03/tech-tip-how-to-do-hard-refresh-in-browsers/#.X1aOftMzafU).

## Optional: Set up a custom domain

Custom domains can help your CV stand out - or alternatively, use your digital CV as a personal website.

Admittedly I’ve never set up a custom domain for my CV, but there are step-by-step instructions for how to do this in the [GitHub documentation](https://docs.github.com/en/github/working-with-github-pages/configuring-a-custom-domain-for-your-github-pages-site). 

> If you’re not sure where to get domains, I like [Namecheap](https://www.namecheap.com/).

## Show me your CV

If you followed this guide and built a digital CV, I’d love to see it! Tweet me a link [@carolstran](https://twitter.com/intent/tweet?text=Hey%20@carolstran,%20check%20out%20my%20fancy%20new%20digital%20CV) 💖

_________________

_Did you find this helpful or useful? If yes, please consider [buying me a coffee](https://ko-fi.com/carolstran) so I can continue to write posts like this_ ☕️