Full Guide to Constructing a Skilled Portfolio with Python, Markdown, Git, and GitHub Pages

In 2023, I’d been coding for data projects for two years and was trying to create my first portfolio to present my data science projects. I discovered the Matt Chapman’s TDS article and the Matt Chapman’s portfolio. This text corresponded perfectly to my technical knowledge on the time (Python, Git). Because of Matt Chapman’s article, I begun my first portfolio! So I made a decision to explore this solution and work out methods to go about it. I discovered the reference that Matt Chapman used and the corresponding repository. I used this reference to create my portfolio.

In 2024, I discovered my old portfolio old-fashioned in comparison with existing portfolios, and never very attractive to data enthusiasts or recruiters. Exploring the projects already carried out in the neighborhood, I discovered several projects with superb documentation. Listed here are 2 links that inspired me: Multi pages documentation based on GitHub Pages, and JavaScript portfolio based on GitHub Pages and corresponding Medium article.

For this recent edition of my portfolio, my criteria were: a free solution, with minimal configuration. Searching through existing documentations and portfolios, I had several options:

• option 1: Keeping the identical visual and architecture from my previous portfolio
• option 2: Fork the JavaScript portfolio mentioned above
• option 3: Use the mkdocs Python package

As I don’t code in JavaScript, I might have been quickly limited in my customization, so I preferred to pass. Using a single GitHub Pages as in my previous portfolio wasn’t enough of an improvement on my portfolio. During my research, I discovered 2 mkdocs sub-packages that particularly caught my attention for the visuals they offered: mkdocs-material and just-the-docs. I finally selected mkdocs for 3 reasons:

• the package (mkdocs) is straightforward to make use of, and I do know Python and Git, that are the two technologies required
• the web site content is in Markdown, and the package robotically generates the location with a minimum of motion on my part on the GitHub repository
• the web site generated is gorgeous and functional

Mkdocs-material allows using Google Tags, perfect for tracking traffic on my portfolio!

On the time of this project, I had already arrange my GitHub Pages, created my repository and created the virtual environment for my previous portfolio. To enable everyone to follow and reproduce this text, I’ve decided to begin from scratch. For those of you who have already got a GitHub Pages portfolio, you’re already aware of Git and Python and can give you the chance to hold on to the branches with none worries.

In this text, I’ll be sharing some URL links. My aim is to provide you an excellent understanding of each aspect of the code and, if essential, to offer you resources to enter more detail on a subject or solve an error that I haven’t described in my article.

Software needed

For this work, you will have at the very least Python and Git installed and configured in your computer, and a GitHub account. Personally, I work on VSCode and Miniconda integrated into PowerShell in order that I can have my scripts and terminal on the identical screen. To configure Git, I refer you to the Your identity a part of the page on the Git site.

Configure the local environment

I work with Miniconda. In the event you work with the identical tool, you’ll recognize the ‘(base)>’ elements. If not, this element represent the present virtual python environment (base is the default virtual environment of Miniconda). The element `working_folder` is the the terminal’s current folder.

1. Step one is to create the virtual environment for the portfolio project:

(base)> conda create -n "portfolio_env" # Create the brand new virtual env named portfolio_env
(base)> conda activate portfolio_env # Activate the brand new virtual env, (base) develop into (portfolio_env)

2. On this recent environment, we’d like to put in the Python packages:

(portfolio_env)> pip install mkdocs mkdocs-material

3. To ensure the reproducibility of your environment, we export requirements:

(portfolio_env)> conda env export > "environnement.yml" # Export the environment.yml file, to make sure conda env repoductibility (including the python version, the conda env configuration, … )
(portfolio_env)> conda list > "requirements.txt" # Export packages installed only

Create the working folder

My previous portfolio didn’t use mkdocs, so I create the mkdocs structure:

(portfolio_env)> mkdocs recent ".github.io"

Replace by your GitHub username. For the remainder of this text, I’ll call the folder .github.io working_folder. The brand new folder can have the next architecture:

.github.io
|- mkdocs.yml
|- environment.yml
|- requirements.txt
|- docs/
|- index.md

To grasp the mkdocs package, you’ll discover the documentation here.

Prepare Git

In the event you have already got a GitHub Pages, you’ll be able to clone your .github.io repository and skip this part. The step part is to create the local Git repository.

1. Create a file named readme.md. This file is the classic readme file for any Git repository
2. Open a Git terminal and create the local repository

working_folder> git init # Initiate the local repo
working_folder> git add . # Save the readme file
working_folder> git commit -m "Initiate repo" # Commit changes

3. In your GitHub account, create a brand new repository named .github.io (replace by your GitHub username)

4. Connect the local repository with the distant repository. Within the Git terminal:

working_folder> git distant add github https://github.com/.github.io

In the event you are usually not aware of GitHub Pages, the GitHub Pages website will introduce them to you and explain why I take advantage of .github.io as repository name.

The working folder can have the next architecture:

.github.io
|- .git
|- readme.md
|- mkdocs.yml
|- environment.yml
|- requirements.txt
|- docs
|- index.md

Feed the web site

Mkdocs lets you display website and dynamically include modifications, so you’ll be able to see your site evolve over time. The code to dynamically generate the location:

mkdocs serve

This command returns an area URL (e.g. 127.0.0.1:8000) to stick into the browser.

readme.md and index.md

The readme file corresponds to the house page of the distant repository. Whenever you created the working folder with the mkdocs package, it created a docs/index.md file which corresponds to the location’s home page.

The menu

Step one is to configure the menu of the web site (the left panel, to navigate between pages). Within the working_folder/mkdocs.yml file, that is the nav part:

# Page tree: seek advice from mkdocs documentation
nav:
- Home: index.md
- Current project:
- "Health open data catalog": catalogue-open-data-sante/index.md
- Previous data science projects:
- "Predict Health Outcomes of Horses": horse_health_prediction_project/readme.md
…
- Previous skills based projects:
- "Predict US stocks closing movements": US_stocks_prediction_project/readme.md
…

The Home element is very important: that is the house page of the web site. You possibly can decide to duplicate the readme.md file contained in the index.md file to have the identical home page on the GitHub repository and the web site, or write a brand new index.md file to have a selected home page on your portfolio.

Let’s break down the next block:

- Previous data science projects:
- "Predict Health Outcomes of Horses": horse_health_prediction_project/readme.md
…

Previous data science project: will represent the name of a gaggle of pages within the navigation bar. “Predict Health Outcomes of Horses” might be the name displayed within the menu of the file indicated, on this case: horse_health_prediction_project/readme.md . Mkdocs robotically finds the pages to display within the docs folder, so there isn’t a have to specify this in the trail. Nonetheless, because the horse health prediction project is presented in an eponymous folder, you could specify by which folder the file you would like to display is positioned.

Within the docs/ folder, I add my previous project:

working_folder
|- docs
|- horse_health_prediction_project
|- readme.md
|- notebook.ipynb
|- notebook.html
|- US_stocks_prediction_project
|- reamd.me
|- notebook.ipynb
|- notebook.html

Then I add each project’s presentation within the nav bar with the next syntax: `“”: /.md`.

The indentation here could be very essential: it’s define folders of the navigation bar. Not all files within the docs folder have to be listed within the navigation bar. Nonetheless, in the event that they are usually not listed, they may not be directly accessible to the visitor.

Website configuration

Then I configure invisible but very essential features of my website:

• Basic website information asked by mkdocs-material:

# Project information
site_name: Pierre-Etienne's data science portfolio
site_url: https://petoulemmonde.github.io/
site_author: Pierre-Etienne Toulemonde
site_description: >-
I'am Pierre-Etienne Toulemonde, PharmD and Data scientist, 
and you're here on my data science portfolio

The site_name corresponding to the name on the tab browser.

• Some repo informations to permit mkdocs-material to display information in the highest right-hand corner of the repository hosting the location:

# Repository: essential to display the repo on the highest right corner
repo_name: petoulemonde/petoulemonde.github.io
repo_url: https://github.com/petoulemonde/petoulemonde.github.io

• I define the design to make use of here:

# Configuration:
theme:
name: material

It’s a vital step because this line says to mkdocs: ‘Use the mkdocs-material package to construct the web site’. In the event you miss this step, the GitHub Pages won’t have the mkdocs-material visual and functionalities!

I add some additional information, to trace the traffic on my website:

# Additional configuration
extra:
analytics:
provider: google
property: 

The property is a code from Google Analytics, to trace traffic on my portfolio. The code is generated with Google Analytics and linked to my Google account (you’ll be able to found a tutorial to create your code here).

In fact I didn’t write the entire file without delay. I began so as to add one project files and knowledge within the file architecture and within the navigation bar, then the configuration, then one other project, then configuration, …

The ultimate mkdocs.yml file

My final mkdocs.yml file is:

# Project information
site_name: Pierre-Etienne's data science portfolio
site_url: https://petoulemonde.github.io/
site_author: Pierre-Etienne Toulemonde
site_description: >-
I'am Pierre-Etienne Toulemonde, PharmD and Data scientist, 
and you're here on my data science portfolio
# Repository
repo_name: petoulemonde/petoulemonde.github.io
repo_url: https://github.com/petoulemonde/petoulemonde.github.io
# Configuration
theme:
name: material
# Additional configuration
extra:
analytics:
provider: google
property: 
# Page tree
nav:
- Home: index.md
- Current project:
- "Health open data catalog": catalogue-open-data-sante/index.md
- Previous data science projects:
- "Predict Health Outcomes of Horses": horse_health_prediction_project/readme.md
…
- Previous skills based projects:
- "Predict US stocks closing movements": US_stocks_prediction_project/readme.md
…

The ultimate file structure

At this step, my file structure is:

petoulemonde.github.io
|- .git
|- readme.md
|- mkdocs.yml
|- requirements.txt
|- environnement.yml
|- docs/
|- index.md
|- US_stocks_prediction_project/
|- README.md
|- notebook.ipynb
|- notebook.html
|- horse_health_prediction_project/
|- README.md
|- notebook.ipynb
|- notebook.html
|- … others projects …

Deploy the work

Mkdocs allows to generate the code for the web site in 1 command line:

mkdocs gh-deploy

Mkdocs translate all of the mkdocs files to html website, like a magician! The Markdown links are transformed into HTML links and the sitemap of the location is generated.

Then, commit all of the changes within the local repository and push it within the distant repository.

working_folder> git add .
working_folder> git commit -m "Create website"
working_folder> git push github master

To establish a GitHub Pages, the steps are:

• Follow previous steps, to push a minimal portfolio
• On GitHub, within the distant repo home page, click on ‘Settings’ (top menu)
• On the left menu, click on ‘Pages’
• Configure the page:
  – Source: deploy from a branch
  – Branch: gh-deploy and /root
  – then save

In the highest menu, click on ‘Actions’. It is best to see a ‘workflow run’. Leave it there, and as soon because it is green, it’s good, your site is online! Well done, you succeeded!

You possibly can see you website on https://.github.io.

The more I take a look at my portfolio to envision and present it, the more errors I notice. To correct them, nothing could possibly be simpler:

1. Make changes in your computer (to take a fast take a look at the modification made and make others if essential, quick reminder: `mkdocs serve`)
2. Regenerate the location using `mkdocs gh-deploy`
3. Commit all changes
4. Push into the distant repo.

And the magic happens: GitHub robotically makes the modification (take a look at the ‘Actions’ tab to see where GitHub is at).

You’ll find my edition 2024 portfolio here and the GitHub repository here. In the longer term, I’d prefer to integrate JavaScript to make the portfolio more dynamic.

Why didn’t I purchase a web site for my portfolio? I’d prefer to consider creating content for my portfolio and recent projects, and keep the executive aspect of those tasks to a minimum. What’s more, for a web site as for a GitHub Pages, people will discover in regards to the project by clicking on a link that redirects them to my site, so purchased website or not, the result might be the identical.

Many thanks on your attention, this was my first medium article. Be happy to reply on the article, I’d love to listen to what you’re thinking that. See you soon!