This document serves as a comprehensive guide to formatting and hosting a resume using Pelican and GitHub Pages.
It is intended for students, developers, and technical writers looking to learn how to create and publish a static site efficiently.
By following this guide, you will:
✔️ Format a resume using Markdown
✔️ Generate a static website with Pelican
✔️ Host the resume for free on GitHub Pages
✔️ Learn about technical writing best practices from Modern Technical Writing by Andrew Etter
Technical writing principles encourage automation, accessibility, and simplicity in documentation. This guide follows Etter’s recommendations on leveraging static site generators to create structured, maintainable documentation.
Before moving forward, ensure you have the following installed:
- A GitHub account (for hosting the site)
- Basic knowledge of Markdown (for formatting the resume)
- A computer with Python 3 installed (for running Pelican)
- An internet connection (for deploying the site)
- Git installed (for version control and pushing changes to GitHub)
Take a look at the Further Resources & Readings section for help with any of these steps
Markdown is a lightweight formatting language that is easier to use than HTML. It allows for quick edits, better readability, and seamless conversion into HTML without requiring extensive technical knowledge.
Example:
- Markdown:
# Work Experience - Managed financial reports - Improved budgeting efficiency by 20%
- Equivalent HTML:
<h1>Work Experience</h1> <ul> <li>Managed financial reports</li> <li>Improved budgeting efficiency by 20%</li> </ul>
Using Markdown aligns with Etter’s principle of keeping documentation simple and avoiding unnecessary complexity.
Static websites load faster, require less maintenance, and are more secure compared to dynamic websites. This follows Etter’s recommendation that documentation should be hosted in a way that requires minimal manual intervention.
Advantages of static websites:
- No databases or server-side processing
- Quick page load speeds
- Secure hosting through GitHub Pages
- Automated deployments via version control
Using Pelican, a static site generator, automates the transformation of Markdown into a fully formatted website.
-
Create a project folder
my-resumeand navigate into it:mkdir my-resume cd my-resume -
Create a virtual environment & activate it:
python3 -m venv pelican-env source pelican-env/bin/activateWhy use a virtual environment?
Virtual environments prevent dependency conflicts by isolating packages needed for this project. -
Install Pelican and Markdown support:
pip install pelican markdown
Etter’s principle of automation applies here. By using tools like Pelican, we avoid manual HTML writing.
- Create a
content/folder and add your resume:mkdir content touch content/resume.md
- Write your resume in Markdown.
Make sure to include a header at the beginning of each markdown file:Title: John Doe Date: 2025-03-06 Category: Resume Author: John Doe Summary: Experienced software engineer with expertise in Python and web development.
This approach follows Etter’s advice to use structured content formats, making resumes easy to edit and maintain.
- Run Pelican’s quickstart command:
pelican-quickstart
- Answer the prompts:
- Site title:
"Your Name's Resume" - Default language:
"en" - Use a simple theme:
"Yes"
- Site title:
- Place your Markdown resume file in the
content/directory.
By automating content generation, Pelican reduces manual HTML maintenance, aligning with best practices in modern technical writing.
- Generate the website:
pelican content
- Preview the site locally:
pelican --listen
- Open in a browser:
Navigate tohttp://localhost:8000.
Previewing the site before deployment ensures quality control, a core technical writing principle.
- Move the generated files to the root:
mv output/* . rm -r output
- Create a GitHub repository and copy its URL.
- Initialize a Git repository and push the files:
git init git add . git commit -m "Initial commit: Hosted resume using Pelican" git branch -M main git remote add origin https://github.com/yourusername/my-resume.git git push -u origin main
- Enable GitHub Pages:
- Go to GitHub Repository → Settings → Pages.
- Select main branch as the source.
- Save changes.
Your resume is now accessible at:
https://yourusername.github.io/my-resume/
This approach follows Etter’s recommendation of using cloud-based documentation hosting for accessibility.
- Pelican Documentation
- Markdown Syntax Guide
- GitHub Pages Guide
- Andrew Etter’s Modern Technical Writing
Technical writing best practices encourage providing additional resources to support learning.
Markdown is easier to read, write, and maintain than raw HTML. Instead of opening and closing tags (<h1>Title</h1>), Markdown simplifies the syntax (# Title). It also converts automatically into HTML, reducing the chance of errors.
Changes do not automatically appear on the website. You must regenerate and push the updated content:
pelican content
git add .
git commit -m "Updated resume"
git push origin mainIf changes do not appear, try clearing the browser cache (Ctrl + Shift + R).
Yes, to install and apply a new theme:
git clone https://github.com/getpelican/pelican-themes.git
pelican-themes --install pelican-themes/FlexModify pelicanconf.py:
THEME = "pelican-themes/Flex"Rebuild the site:
pelican contentA 404 error on GitHub Pages usually means:
- The website deployment is still in progress. GitHub Pages may take a few minutes to process changes. Wait a few minutes and refresh the page.
- The site is being served from the wrong branch. Ensure GitHub Pages is set to serve from the
mainbranch:- Go to GitHub Repository → Settings → Pages.
- Under Branch, select
main. - Click Save.
- Your
index.htmlfile is missing. Run:Then refresh the page.pelican content mv output/* . rm -r output git add . git commit -m "Rebuilt site" git push origin main
Pelican allows you to add images for a more professional website.
Adding Images:
- Create a folder for images:
mkdir content/images
- Place your images inside the
images/folder. - Add an image to your Markdown resume using:
No, once your website is set up, you only need to update your Markdown file and regenerate the site.
Steps to update your resume:
- Edit
resume.mdin thecontent/folder. - Rebuild the site:
pelican content
- Push the updated files to GitHub:
git add . git commit -m "Updated resume" git push origin main
Your website will update automatically after a few minutes.
Yes, you can host your Pelican website on other platforms, such as:
- Netlify – Supports static site hosting with automated deployment.
- GitLab Pages – Similar to GitHub Pages but hosted on GitLab.
- Cloudflare Pages – Offers fast static site hosting with global caching.
To use these platforms, check their documentation for instructions on setting up static sites.
- Nataniella Ogogo – Author, project setup, and technical writing.
- Tofunmi Layi-Babatunde – Peer reviewer, technical feedback, FAQ and content edits.
- Kikiola Ojuko – Peer reviewer, technical feedback, FAQ and content edits.
- Pelican – Static site generator (Pelican Project).
- GitHub Pages – Hosting platform (GitHub Pages).
- Pelican Themes – Website themes (Pelican Themes Repository).
- Markdown Guide – Formatting reference (Markdown Guide).
- Modern Technical Writing – Reference book (Amazon Listing).