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 information on the time (Python, Git). Due to Matt Chapman’s article, I begun my first portfolio! So I made a decision to discover this answer and determine how one can 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 present portfolios, and never very enticing to knowledge fans or recruiters. Exploring the initiatives already carried out in the neighborhood, I discovered a number of initiatives with very good documentation. Listed below are 2 hyperlinks that impressed me: Multi pages documentation primarily based on GitHub Pages, and JavaScript portfolio primarily based on GitHub Pages and corresponding Medium article.
For this new version of my portfolio, my standards have been: a free answer, with minimal configuration. Wanting via present documentations and portfolios, I had a number of choices:
- possibility 1: Holding 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 popular 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 significantly caught my consideration for the visuals they supplied: 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 robotically generates the positioning with a minimal of motion on my half on the GitHub repository
- the web site generated is gorgeous and useful
Mkdocs-material permits using Google Tags, good for monitoring site visitors on my portfolio!
On the time of this undertaking, I had already arrange my GitHub Pages, created my repository and created the digital surroundings for my earlier portfolio. To allow everybody to comply with and reproduce this text, I’ve determined to start out 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 of grasp on to the branches with none worries.
On this article, I’ll be sharing some URL hyperlinks. My goal is to offer you a great understanding of each side of the code and, if crucial, to offer you assets to enter extra element on a topic or resolve an error that I haven’t described in my article.
Software program wanted
For this work, you will want a minimum of Python and Git put in and configured in your laptop, and a GitHub account. Personally, I work on VSCode and Miniconda built-in into PowerShell in order that I can have my scripts and terminal on the identical display. To configure Git, I refer you to the Your identification a part of the web page on the Git website.
Configure the native surroundings
I work with Miniconda. In the event you work with the identical device, you’ll acknowledge the ‘(base)>’ parts. If not, this factor signify the present digital python surroundings (base is the default digital surroundings of Miniconda). The factor `working_folder` is the the terminal’s present folder.
1. Step one is to create the digital surroundings for the portfolio undertaking:
(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) turn into (portfolio_env)
2. On this new surroundings, we have to set up the Python packages:
(portfolio_env)> pip set up mkdocs mkdocs-material
3. To ensure the reproducibility of your surroundings, we export necessities:
(portfolio_env)> conda env export > "environnement.yml" # Export the surroundings.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 can have the next structure:
<your GitHub username>.github.io
|- mkdocs.yml
|- surroundings.yml
|- necessities.txt
|- docs/
|- index.md
To know the mkdocs bundle, you’ll discover the documentation right here.
Prepare Git
If you have already got a GitHub Pages, you may 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 web site will introduce them to you and clarify why I exploit <your GitHub username>.github.io as repository identify.
The working folder can have the next structure:
<your GitHub username>.github.io
|- .git
|- readme.md
|- mkdocs.yml
|- surroundings.yml
|- necessities.txt
|- docs
|- index.md
Feed the web site
Mkdocs permits you to show web site and dynamically embody modifications, so you may see your website evolve over time. The code to dynamically generate the positioning:
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. While you created the working folder with the mkdocs bundle, it created a docs/index.md file which corresponds to the positioning’s house 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 undertaking:
- "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 vital: 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 house web page on the GitHub repository and the web site, or write a brand new index.md file to have a selected house web page on 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 undertaking: will signify 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 robotically finds the pages to show within the docs folder, so there isn’t any must specify this within the path. Nevertheless, because the horse well being prediction undertaking is offered in an eponymous folder, you have to specify during which folder the file you want to show is positioned.
Within the docs/ folder, I add my earlier undertaking:
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 undertaking’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. Nevertheless, if they aren’t listed, they won’t be instantly accessible to the customer.
Web site configuration
Then I configure invisible however crucial elements of my web site:
- Fundamental website info requested by mkdocs-material:
# Mission info
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 Knowledge scientist,
and you're right here on my knowledge science portfolio
The site_name equivalent to the identify on the tab browser.
- Some repo informations to permit mkdocs-material to show info within the high right-hand nook of the repository internet hosting the positioning:
# 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 an important step as a result of this line says to mkdocs: ‘Use the mkdocs-material bundle to construct the web site’. In the event you miss this step, the GitHub Pages is not going to have the mkdocs-material visible and functionalities!
I add some further info, to trace the site visitors on my web site:
# Further configuration
further:
analytics:
supplier: google
property: <your google analystics code>
The property is a code from Google Analytics, to trace site visitors on my portfolio. The code is generated with Google Analytics and linked to my Google account (you may discovered a tutorial to create your code right here).
In fact I didn’t write the entire file directly. I began so as to add one undertaking information and data within the file structure and within the navigation bar, then the configuration, then one other undertaking, then configuration, …
The ultimate mkdocs.yml file
My ultimate mkdocs.yml file is:
# Mission info
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 Knowledge 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
# Further configuration
further:
analytics:
supplier: google
property: <google analystics code>
# Web page tree
nav:
- Residence: index.md
- Present undertaking:
- "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 reworked into HTML hyperlinks and the sitemap of the positioning 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:
- Comply with earlier steps, to push a minimal portfolio
- On GitHub, within the distant repo house web page, click on on ‘Settings’ (high 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 high 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 website is on-line! Properly achieved, you succeeded!
You may see you web site on https://<your GitHub username>.github.io.
The extra I have a look at my portfolio to test and current it, the extra errors I discover. To appropriate them, nothing could possibly be less complicated:
- Make modifications in your laptop (to take a fast have a look at the modification made and make others if crucial, fast reminder: `mkdocs serve`)
- Regenerate the positioning utilizing `mkdocs gh-deploy`
- Commit all modifications
- Push into the distant repo.
And the magic occurs: GitHub robotically makes the modification (have a look at the ‘Actions’ tab to see the place GitHub is at).
You’ll discover my version 2024 portfolio right here and the GitHub repository right here. Sooner or later, I’d prefer 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 side of those duties to a minimal. What’s extra, for a web site as for a GitHub Pages, folks will discover out concerning the undertaking by clicking on a hyperlink that redirects them to my website, so bought web site or not, the end result would be the identical.
Many thanks on your consideration, this was my first medium article. Be at liberty to reply on the article, I’d love to listen to what you suppose. See you quickly!