- Describing the practical steps to host and format a resume using the software stack on
GitHub
. - Using lightweight markup languages such as
Markdown
to create technical documentation that is easy to read, write, and maintain. - Using version control systems such as
git
to keep track of changes made to the documentation.
Before following the instructions in this README, you will need the following:
Web Browser.
A Resume in Markdown Format
.
If you have a GitHub account already, you can skip to step 2.
- Go to the GitHub homepage at https://github.com/.
- Click on the
Sign up
button in the top right corner of this page. - Enter your preferred username, email address, and strong password.
- Click the
Create account
button. - Choose a plan. You can choose the free plan for now.
- Follow the on-screen steps to complete filling out your personal information and selecting your preferences.
- Verify your email address by clicking the link that has been sent to you at the email address you have provided.
The Second step in hosting your resume on GitHub Pages is to create a new repository on GitHub. You can do this by following these steps:
- Log in to your GitHub account if you are already not logged in.
- Click on the
+
icon in the top right corner of the screen. Then selectNew repository
. - Give your repository a name, For example,
online-resume
, and selectPublic
. - Check the box that says,
Initialize this repository with a README
. - Click the
Create repository
button.
This step will cover preparing the resume for the static website.
- Rename the resume filename as
index.md
. - Remember the location where you saved this file.
In this step, we will upload our markdown formatted resume to our GitHub resume repository. You can do this by following these steps:
- Go to the repository on GitHub from your browser.
- Click on the "Add file" dropdown button and select "Upload files".
- Drag and drop the resume file, namely
index.md
from your computer. - Click on the "Commit changes" button at the bottom to upload the files to the repository.
To generate a static site and add a theme to your resume, we will be using Jekyll. Jekyll is a static site generator that allows you to create websites and blogs by writing content in Markdown or HTML and using templates to generate the pages. To generate a static site using Jekyll and add a theme, we need to create a _config.yml
file. From the repository,
- Click on the
"Add file"
dropdown button and select"Create new file"
. - Write the name your file at the top of the text editor. The name must be exactly
_config.yml
- Copy this code below in the text editor.
remote_theme: pages-themes/slate@v0.2.0 # this line adds the slate theme of Jekyll. You can replace "slate@v0.2.0" with your preferred theme.
plugins:
- jekyll-remote-theme # add this line to the plugins list if you already have one
title: "RESUME OF [Your Name]" # Replace "[Your Name]" with your first and last name.
- Click on the
Commit changes
button at the bottom.
To activate the Github site hosting feature, follow the steps below.
- In the repository, navigate to the
Settings
tab. - Scroll down to the
Pages
section on the left side of the page. - Select the branch you want to use as the source. For now, select the
main
branch. - Click
Save.
- Wait up to 10 minutes for Github to build your site. However, the usual time is around 2 minutes.
- Go to
https://username.github.io/repository_name/
, where username is your GitHub username and repository_name is the name of the repository where you uploaded your resume. - You should see your resume displayed on the site.
- Markdown Tutorial
- Modern Technical Writing: An Introduction to Software Documentation
- GitHub Pages Documentation
This README was created by Saif Mahmud and peer-reviewed by Aditya Kashyap.
The theme used in the resume is Jekyll slate@v0.2.0
found here.
Q. Can I edit my resume after I have hosted it on GitHub Pages?
Yes, you can edit your resume after you have hosted it on GitHub Pages. Simply make the necessary changes to your Markdown file and save the changes. Then, upload the updated file to your GitHub repository using the same steps outlined in Step 4. Your changes should be reflected on your hosted resume shortly after GitHub rebuilds your site.
Q. Can I use a different theme for my GitHub Pages site?
Yes, you can use a different Jekyll theme by changing the remote_theme field in the _config.yml file to the theme you prefer. A list of Jekyll themes is available here. Once you update the _config.yml file, commit the changes and your GitHub Pages site will automatically update with the new theme.
Relate the practical steps described above to the general principles of current technical writing, as explained in Andrew Etter's book Modern Technical Writing.
- A general understanding of Andrew Etter's book, Modern Technical Writing.
In Etter's book, "Modern Technical Writing," he discusses the importance of using lightweight markup languages. A lightweight markup language such as Markdown makes it easy to create technical documentation that is easy to read, write, and maintain. This readme document and the resume we have made were in markdown format. From a markdown format, one can easily convert it into an HTML document without worrying about the complexities of HTML markup.
The book also emphasizes using a static site generator such as Jekyll. Jekyll is a static site generator that allows the creation of websites by writing content in Markdown or HTML and using templates to generate the pages. In the instructions above, we have used Jekyll to generate a static site and add a theme to our resume. By creating a _config.yml file and specifying a theme, we were able to generate a professional-looking resume with minimal effort.
Etter highly encouraged the advantages of utilizing version control systems like Git to track modifications made to the documents. In this README, we have used a version control system called GitHub as a platform to host our resume. With Git, we can effectively track and revert any modifications made to our documents. Moreover, by hosting our resume on GitHub, we can seamlessly share it with others and engage in collaborative work on the same document for free.
In conclusion, by following the practical steps outlined in this README, we have demonstrated the key principles of using lightweight markup languages, formatting a document with a static site generator, and sharing/hosting documents on a distributed version control system. As outlined in Etter's book, these principles, are very effective for creating and maintaining technical documentation.