A step-by-step guide to build a data science portfolio quickly, including useful resources and common rabbit holes.

I had been contemplating making a data science portfolio for some time. The universe, rather eagerly, sent me signs that I shouldn’t postpone this project any longer. I decided to document the journey here, hoping to provide useful tips for people who are doing this for the first time.

Why you need a portfolio

It’s 2026 and the job market for data roles is highly competitive. Having a modern portfolio to showcase your skills can give you the visibility you need to get a job.

[JOB MARKET FACTS].

A portfolio is an opportunity to go beyond the bullet points of a CV which, in my opinion, don’t do justice to the complexity behind the work of many data professionals. Having a platform to demonstrate what you mean by model evaluation and feature engineering can help you stand out. Indeed, I have noticed an increasing number of job applications requesting links to portfolios and personal websites.

How to build a portfolio

I started this journey by doing a bit of research. I realised that I wasn’t the first person, and won’t be the last, to ever build a portfolio. I did not want to re-invent the wheel. After all, I’m part of an industry that champions automation. I had a portfolio vision in mind and I set out to look for resources to turn that vision into reality. I wanted to build my portfolio with a tool that was: a) open-source, b) well-documented, and c) flexible and easy to use.

1. Choosing a hosting platform

There are plenty of platforms you can use to host a personal website, but I opted for GitHub Pages. In a nutshell, GitHub Pages allows you to publish static websites from your GitHub account at no cost and without ads. Websites are automatically generated from your repo using Jekyll.

I had neither used GitHub Pages nor heard of Jekyll before starting this project. I anticipated a bit of a learning curve, as it’s natural with all software things, but I was wary of rabbit holes. Luckily, it turns out that Jekyll uses a lot of markdown and html. My experience in quarto and web scraping came handy here! Don’t worry if you haven’t worked with these files before, you do not need to be an experienced website developer to use GitHub Pages.

Jekyll does require your repo to follow a specific structure to generate your website correctly. However, I wouldn’t let that be a cause of concern because there are ready-to-go templates that contain the correct set up to deploy a website. This is a major advantage of GitHub Pages, but certainly not the only one. I would add a couple more, such as:

• Easy set up: If you already have a GitHub account, getting started can be as easy as forking a demo repo. Additionally, you can hit the ground immediately by checking the documentation that comes with pre-styled templates.
• Previews: The official GitHub Pages themes and other website templates offer previews of supported functionality and aesthetics. My personal favourites include the minimal and cayman themes.
• Automatic deployment: Any updates to your website will be reflected automatically after you push those changes to the repo. This is done via GitHub actions.
• Version control: You can leverage Git to handle version control, which naturally encourages experimentation. You can test new features on a separate branch, or roll back your website to a previous version if you make a mistake.

2. Testing a minimum viable product

If you’re like me and you’re no expert in website development, it’s important to understand the basics of GitHub Pages. I’d recommend following along this GitHub skills tutorial to create your first blog post.

I used the repo generated from that tutorial to make a proof-of-concept portfolio and, more importantly, to make mistakes. Why did you bother doing that? I hear you ask. Call it experience, or instinct, but I had a feeling that there would be an unforeseen obstacle that would derail my progress… and I was right.

I fell down the rabbit hole when I was testing different procedures to share code. There’s no standard approach to share code in a portfolio. I found examples that described projects at a high level and re-directed people to GitHub repos or Code lab spaces to see the full project. This approach might favour consistency, but it did not resonate with me. In my opinion, having users jump between different sites to see your work creates a disjointed user experience. I wanted descriptions and project content to be all in the same website.

Before I discuss how to share code, I would suggest you have a dummy project to test publishing (if you don’t have a real one yet). This can be as minimal as a couple of code cells and plots from a pre-loaded data set such as iris. Just make sure what you test reflects the types of outputs you’d be sharing. For my specific use case, I tested sharing dummy code and outputs generated in a Jupyter notebook.

Jupyter notebooks are great to lay your work out in a portfolio-friendly manner (i.e., a mix of text, code cells, and images), but embedding them in a Jekyll website can be tricky when you’re a novice website developer. An .ipynb file may render automatically on GitHub, but it won’t on your website because Jekyll doesn’t render it natively. You’ll need to convert jupyter notebooks into markdown or html files. The magic commands that you will need to run in your terminal are either:

• jupyter nbconvert <file.ipynb> --to markdown
• jupyter nbconvert <file.ipynb> --to html

I ran both in Anaconda prompt. Make sure you’re pointing to the correct working directory: cd path/to/notebook/folder. Check this post if you want to learn more about conversions with nbconvert.

Neither approach is perfect. The choice to pick one came down to which drawback was easier to fix with my current level of skill:

• Markdown conversions generate an additional folder <your-notebook-name>-files, which will contain files such as images generated from plots in your code. The markdown file will make references to that new file folder automatically, but you will have to adjust paths so Jekyll can render output files from the new folder on the website. This post expands on markdown conversions and proposes a workflow you can use to embed on your website.
• HTML conversions translate most of the notebook into html code, so no additional files folder is generated. This seemed great at first, until I tested making a page using the converted file. Website configuration in the background was using html to define layout and aesthetics. The converted notebook had its own html styling and thus conflicted and overwrote defaults from the mininal theme. Trying to fix this effect was turning into a rabbit hole within a rabbit hole. I started exploring, but eventually abandoned, alternatives such as using different templates in nbconvert (e.g., jupyter nbconvert <file.ipynb> --to html --template base) or using html iframes.

At this point, I already had enough of an idea of what I signed up for. I opted to go for markdown conversions, as they didn’t cause html conflicts. I also realised that I needed a new website template, something that offered more built-in website functionality and a more user friendly layout to share code.

3. Choosing your preferred approach

During my second round of searching, I came across a couple of articles from TDS (towards data science) that I found very useful. This guide prompted me to looked for examples of other portfolios for inspiration.

Eventually, I came across the Academic pages website template. With a documented repo and an active number of forks, this seemed like a good option. Although I’m not personally in academia, the pre-designed layout enticed me. Not only was there a section for portfolio, but also sections to add a CV and publications. Therefore extending my original idea of a portfolio to a personal website very naturally. Another winning feature for me was the .devcontainer. I will confess that in my first portfolio attempt, I was pushing endlessly to test what changes would look like on the website. This got tiresome quickly, so having the ability to render oyu website locally was a game changer. I used docker desktop and docker compose up quickly became the command I ran in the terminal most frequently.

Adapted he template to fit my particular needs.

4. Documenting your struggle journey

I think this is intrinsic to the ethos of open source. People put plenty of effort to develop code other can use. Sharing your experience using that code is not only helpful to those who created the original project, it’s also very valuable to people trying to implement it. The template I ended up using for this website is great, but I couldn’t have achieved such a quick turn around without the articles and tutorials I’ve mentioned throughout this article.

Recommended reading list