In 2023, I’d been coding for knowledge initiatives for two years and was seeking to create my first portfolio to current my knowledge science initiatives. I found the Matt Chapman’s TDS article and the Matt Chapman’s portfolio. This text corresponded completely to my technical data on the time (Python, Git). Because of Matt Chapman’s article, I begun my first portfolio! So I made a decision to discover this answer and determine go about it. I found the reference that Matt Chapman used and the corresponding repository. I used this reference to create my portfolio.
In 2024, I discovered my outdated portfolio old school in comparison with current portfolios, and never very engaging to knowledge lovers or recruiters. Exploring the initiatives already carried out locally, I discovered a number of initiatives with excellent documentation. Listed here are 2 hyperlinks that impressed me: Multi pages documentation based on GitHub Pages, and JavaScript portfolio based on GitHub Pages and corresponding Medium article.
For this re-creation of my portfolio, my standards had been: a free answer, with minimal configuration. Trying via current documentations and portfolios, I had a number of choices:
- possibility 1: Preserving the identical visible and structure from my earlier portfolio
- possibility 2: Fork the JavaScript portfolio talked about above
- possibility 3: Use the mkdocs Python bundle
As I don’t code in JavaScript, I’d have been rapidly restricted in my customization, so I most well-liked to cross. Utilizing a single GitHub Pages as in my earlier portfolio wasn’t sufficient of an enchancment on my portfolio. Throughout my analysis, I found 2 mkdocs sub-packages that notably caught my consideration for the visuals they provided: mkdocs-material and just-the-docs. I lastly selected mkdocs for 3 causes:
- the bundle (mkdocs) is simple to make use of, and I do know Python and Git, that are the two applied sciences required
- the web site content material is in Markdown, and the bundle mechanically generates the location with a minimal of motion on my half on the GitHub repository
- the web site generated is gorgeous and purposeful
Mkdocs-material permits the usage of Google Tags, good for monitoring visitors on my portfolio!
On the time of this challenge, I had already arrange my GitHub Pages, created my repository and created the digital atmosphere for my earlier portfolio. To allow everybody to comply with and reproduce this text, I’ve determined to begin from scratch. For these of you who have already got a GitHub Pages portfolio, you’re already aware of Git and Python and can be capable to dangle on to the branches with none worries.
On this article, I’ll be sharing some URL hyperlinks. My purpose is to present you understanding of each facet of the code and, if essential, to offer you assets to enter extra element on a topic or clear up an error that I haven’t described in my article.
Software program wanted
For this work, you’ll need at the very least Python and Git put in and configured in your laptop, 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 display screen. To configure Git, I refer you to the Your id a part of the web page on the Git site.
Configure the native atmosphere
I work with Miniconda. When you work with the identical instrument, you’ll acknowledge the ‘(base)>’ parts. If not, this factor symbolize the present digital python atmosphere (base is the default digital atmosphere of Miniconda). The factor `working_folder` is the the terminal’s present folder.
1. Step one is to create the digital atmosphere for the portfolio challenge:
(base)> conda create -n "portfolio_env" # Create the brand new digital env named portfolio_env
(base)> conda activate portfolio_env # Activate the brand new digital env, (base) develop into (portfolio_env)
2. On this new atmosphere, we have to set up the Python packages:
(portfolio_env)> pip set up mkdocs mkdocs-material
3. To ensure the reproducibility of your atmosphere, we export necessities:
(portfolio_env)> conda env export > "environnement.yml" # Export the atmosphere.yml file, to make sure conda env repoductibility (together with the python model, the conda env configuration, … )
(portfolio_env)> conda record > "necessities.txt" # Export packages put in solely
Create the working folder
My earlier portfolio didn’t use mkdocs, so I create the mkdocs construction:
(portfolio_env)> mkdocs new "<your GitHub username>.github.io"
Substitute <your GitHub username> by your GitHub username. For the remainder of this text, I’ll name the folder <your GitHub username>.github.io working_folder. The brand new folder may have the next structure:
<your GitHub username>.github.io
|- mkdocs.yml
|- atmosphere.yml
|- necessities.txt
|- docs/
|- index.md
To grasp the mkdocs bundle, you will discover the documentation here.
Prepare Git
If you have already got a GitHub Pages, you possibly can clone your <your GitHub username>.github.io repository and skip this half. The step half is to create the native Git repository.
- Create a file named readme.md. This file is the traditional readme file for any Git repository
- Open a Git terminal and create the native repository
working_folder> git init # Provoke the native repo
working_folder> git add . # Save the readme file
working_folder> git commit -m "Provoke repo" # Commit modifications
3. In your GitHub account, create a brand new repository named <your GitHub username>.github.io (change <your GitHub username> by your GitHub username)
4. Join the native repository with the distant repository. Within the Git terminal:
working_folder> git distant add github https://github.com/<your GitHub username>.github.io
In case you are not aware of GitHub Pages, the GitHub Pages website will introduce them to you and clarify why I take advantage of <your GitHub username>.github.io as repository identify.
The working folder may have the next structure:
<your GitHub username>.github.io
|- .git
|- readme.md
|- mkdocs.yml
|- atmosphere.yml
|- necessities.txt
|- docs
|- index.md
Feed the web site
Mkdocs means that you can show web site and dynamically embrace modifications, so you possibly can see your web 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 web page of the distant repository. Whenever you created the working folder with the mkdocs bundle, it created a docs/index.md file which corresponds to the location’s residence web 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 half:
# Web page tree: confer with mkdocs documentation
nav:
- Residence: index.md
- Present challenge:
- "Well being open knowledge catalog": catalogue-open-data-sante/index.md
- Earlier knowledge science initiatives:
- "Predict Well being Outcomes of Horses": horse_health_prediction_project/readme.md
…
- Earlier expertise primarily based initiatives:
- "Predict US shares closing actions": US_stocks_prediction_project/readme.md
…
The Residence factor is essential: that is the house web page of the web site. You may select to duplicate the readme.md file contained in the index.md file to have the identical residence web page on the GitHub repository and the web site, or write a brand new index.md file to have a particular residence web page in your portfolio.
Let’s break down the next block:
- Earlier knowledge science initiatives:
- "Predict Well being Outcomes of Horses": horse_health_prediction_project/readme.md
…
Earlier knowledge science challenge: will symbolize the identify of a bunch of pages within the navigation bar. “Predict Well being Outcomes of Horses” would be the identify displayed within the menu of the file indicated, on this case: horse_health_prediction_project/readme.md . Mkdocs mechanically finds the pages to show within the docs folder, so there is no such thing as a must specify this within the path. Nonetheless, because the horse well being prediction challenge is offered in an eponymous folder, you will need to specify during which folder the file you want to show is positioned.
Within the docs/ folder, I add my earlier challenge:
working_folder
|- docs
|- horse_health_prediction_project
|- readme.md
|- pocket book.ipynb
|- pocket book.html
|- US_stocks_prediction_project
|- reamd.me
|- pocket book.ipynb
|- pocket book.html
Then I add every challenge’s presentation within the nav bar with the next syntax: `“<displayed identify>”: <path_from_docs_to_project_file>/<project_presentation>.md`.
The indentation right here is essential: it’s outline folders of the navigation bar. Not all information within the docs folder have to be listed within the navigation bar. Nonetheless, if they aren’t listed, they won’t be immediately accessible to the customer.
Web site configuration
Then I configure invisible however essential features of my web site:
- Fundamental site data requested by mkdocs-material:
# Venture data
site_name: Pierre-Etienne's knowledge science portfolio
site_url: https://petoulemmonde.github.io/
site_author: Pierre-Etienne Toulemonde
site_description: >-
I'am Pierre-Etienne Toulemonde, PharmD and Information scientist,
and you're right here on my knowledge science portfolio
The site_name akin to the identify on the tab browser.
- Some repo informations to permit mkdocs-material to show data within the prime right-hand nook of the repository internet hosting the location:
# Repository: essential to show the repo on the highest proper nook
repo_name: petoulemonde/petoulemonde.github.io
repo_url: https://github.com/petoulemonde/petoulemonde.github.io
- I outline the design to make use of right here:
# Configuration:
theme:
identify: materials
It’s a vital step as a result of this line says to mkdocs: ‘Use the mkdocs-material bundle to construct the web site’. When you miss this step, the GitHub Pages is not going to have the mkdocs-material visible and functionalities!
I add some further data, to trace the visitors on my web site:
# Extra configuration
additional:
analytics:
supplier: google
property: <your google analystics code>
The property is a code from Google Analytics, to trace visitors on my portfolio. The code is generated with Google Analytics and linked to my Google account (you possibly can discovered a tutorial to create your code here).
In fact I didn’t write the entire file directly. I began so as to add one challenge information and knowledge within the file structure and within the navigation bar, then the configuration, then one other challenge, then configuration, …
The ultimate mkdocs.yml file
My last mkdocs.yml file is:
# Venture data
site_name: Pierre-Etienne's knowledge science portfolio
site_url: https://petoulemonde.github.io/
site_author: Pierre-Etienne Toulemonde
site_description: >-
I'am Pierre-Etienne Toulemonde, PharmD and Information scientist,
and you're right here on my knowledge science portfolio# Repository
repo_name: petoulemonde/petoulemonde.github.io
repo_url: https://github.com/petoulemonde/petoulemonde.github.io
# Configuration
theme:
identify: materials
# Extra configuration
additional:
analytics:
supplier: google
property: <google analystics code>
# Web page tree
nav:
- Residence: index.md
- Present challenge:
- "Well being open knowledge catalog": catalogue-open-data-sante/index.md
- Earlier knowledge science initiatives:
- "Predict Well being Outcomes of Horses": horse_health_prediction_project/readme.md
…
- Earlier expertise primarily based initiatives:
- "Predict US shares closing actions": US_stocks_prediction_project/readme.md
…
The ultimate file construction
At this step, my file construction is:
petoulemonde.github.io
|- .git
|- readme.md
|- mkdocs.yml
|- necessities.txt
|- environnement.yml
|- docs/
|- index.md
|- US_stocks_prediction_project/
|- README.md
|- pocket book.ipynb
|- pocket book.html
|- horse_health_prediction_project/
|- README.md
|- pocket book.ipynb
|- pocket book.html
|- … others initiatives …
Deploy the work
Mkdocs permits to generate the code for the web site in 1 command line:
mkdocs gh-deploy
Mkdocs translate all of the mkdocs information to html web site, like a magician! The Markdown hyperlinks are remodeled into HTML hyperlinks and the sitemap of the location is generated.
Then, commit all of the modifications within the native repository and push it within the distant repository.
working_folder> git add .
working_folder> git commit -m "Create web site"
working_folder> git push github grasp
To arrange a GitHub Pages, the steps are:
- Observe earlier steps, to push a minimal portfolio
- On GitHub, within the distant repo residence web page, click on on ‘Settings’ (prime menu)
- On the left menu, click on on ‘Pages’
- Configure the web page:
– Supply: deploy from a department
– Department: gh-deploy and /root
– then save
Within the prime menu, click on on ‘Actions’. It is best to see a ‘workflow run’. Go away it there, and as quickly as it’s inexperienced, it’s good, your web site is on-line! Effectively completed, you succeeded!
You may see you web site on https://<your GitHub username>.github.io.
The extra I take a look at my portfolio to test and current it, the extra errors I discover. To appropriate them, nothing might be easier:
- Make modifications in your laptop (to take a fast take a look at the modification made and make others if essential, fast reminder: `mkdocs serve`)
- Regenerate the location utilizing `mkdocs gh-deploy`
- Commit all modifications
- Push into the distant repo.
And the magic occurs: GitHub mechanically makes the modification (take a look at the ‘Actions’ tab to see the place GitHub is at).
You’ll discover my version 2024 portfolio here and the GitHub repository here. Sooner or later, I’d wish to combine JavaScript to make the portfolio extra dynamic.
Why didn’t I purchase a web site for my portfolio? I’d like to focus on creating content material for my portfolio and new initiatives, and preserve the executive facet of those duties to a minimal. What’s extra, for a web site as for a GitHub Pages, folks will discover out in regards to the challenge by clicking on a hyperlink that redirects them to my web site, so bought web site or not, the end result would be the identical.
Many thanks in your consideration, this was my first medium article. Be at liberty to reply on the article, I’d love to listen to what you assume. See you quickly!