Introduction

This workshop is designed to help you create and publish a modern portfolio website. We will start with a ready-to-use portfolio website template for geospatial professionals and learn how to edit and setup your GitHub repository to publish your website. At the end of the workshop, you will have a beautiful and customized website with your portfolio that is hosted for free on GitHub Pages and ready to be shared with your network.

We will use the MkDocs static site generator with Material theme that creates modern responsive website from Markdown-formatted content.

This workshop will cover the following topics:

View Presentation

Installation and Preparation

Sign-up for GitHub

Preparing Content for the Portfolio

Before you start building the portfolio, it will be helpful to have the following items saved to a local directory on your computer.

  • Profile Picture: Save your preferred profile photo as a PNG file named profile.png. Preferably 300px x 300px in size.
  • Homepage Picture: A photo for the About Me section. Save a photo you would like to use on the homepage as a PNG file named about.png. Maximum 500px width.
  • Your Resume/CV: Save a copy of your CV as a PDF file named [YOUR NAME]-CV.pdf. If you name is John, the file would be John-CV.pdf.
  • Project Artifacts: Project Reports, Jupyter Notebooks or any other data relating to the projects you would like to showcase in the portfolio.

1. Setting Up Your Repository

Make sure you are logged-in to your GitHub account before trying the following steps.

  1. Go to the template repository at https://github.com/spatialthoughts/portfolio-website-template/. Go to Use this template → Create a new repository.

  1. Under General, enter the Repository name. To use GitHub Pages for free at https://your-username.github.io, name the repository exactly as your-username.github.io (replace your-username with your actual GitHub username). For example, if the github username is spatialthoughts, the repository name should be spatialthoughts.github.io. This is a special repository naming pattern that GitHub uses to publish the site at the root of your GitHub pages . Optionally, you may use any other name and the the site will be published at https://your-username.github.io/your-repository-name. Leave all other options as-is and click Create Repository.

  1. Your repository will now be created. When you first copy the template, a GitHub Action will run and setup a new branch named gh-pages and enable Github Pages. Wait for a minute for these tasks to finish and then go to Settings → Pages. It will show the URL of the portfolio website. Click on it to open the website in a new tab. It is not yet setup with the correct content.

  1. Scroll down to the Branch section and select gh-pages as the branch. Click Save. This will now take the HTML files generated by MkDocs and publish it on the Github Pages site.

  1. Wait for a minute and refresh the tab with your website. It should now show the default template website hosted on your GitHub Pages.

2. Updating the Site

2.1 Updating the Site Configuration

MkDocs uses a central configuration file named mkdocs.yml. This file is in the YAML format (.yml). You can learn about all available settings at MkDocs Configuration page. We will edit this file with the main configuration settings now.

  1. From your GitHub repository home, locate the mkdocs.yml file. Click on the filename to view it.

  1. At the top-right corner, locate the Edit this file button and click it.

  1. Update the placeholders with your name and information. At the least, you should update the site_name, site_description, site_author and site_url values. Once done, click Commit changes…. You will be shown a confirmation dialog, click Comment changes button again to save the changes.

2.2 Updating the Homepage

Next, we will now start modifying the content pages of the website. All the content pages as in the Markdown format (.md). Each time you update the markdown file, MkDocs will build and create a new HTML file from that content. We will now update the homepage of the site which is built from the index.md file.

  1. Locate the index.md file in the docs/ folder. Click to open it and click “Edit this file* button.

  1. In the file editor, update the placeholders [YOUR NAME], [YOUR JOB TITLE], [YOUR TAGLINE] with your information. In the About Me section, replace the paragraph with your bio.

  1. Scroll down and update the Skills and Connect sections. You can delete cards and links which are not relevant for you. Once done, save your changes by clicking Commit changes….

  1. The homepage has placeholders for your profile picture and an about me picture. We will now replace these with your pictures. Go to the docs/assets/images/ folder and click the … menu to locate the Upload files button.

  1. Upload your profile photo. Make sure it is named profile.png (case sensitive) and is no larger than 300px wide. Wait for the file to be uploaded and click Commit changes. Similarly, upload your about me picture named about.png. This photo can be any of dimensions, but to ensure the homepage loads fast, ensure it is not bigger than 700px wide.

  1. The homepage also has provision to download your CV. Go to the docs/assets/ folder and click on the Upload files button.

  1. Upload your CV file named <your name>-CV.pdf (If your name is John, name the file John-CV.pdf).

  1. Your homepage is now ready. Head over to the published website and refresh the tab. You should see the homepage with your pictures and information. If you see any formatting errors, you can go back and update the index.md file. If the images do not appear, ensure they are uploaded in the correct folder and the names match as specified in the index.md file.

2.3. Updating Content Pages using LLM AI Assistants

3. Setting-up a Local Development Environment

4. Advanced Customizations

License

This workshop material is licensed under a Creative Commons Attribution 4.0 International (CC BY 4.0). You are free to re-use and adapt the material but are required to give appropriate credit to the original author as below:

Building Your Geospatial Portfolio Website by Ujaval Gandhi www.spatialthoughts.com

© 2026 Spatial Thoughts www.spatialthoughts.com

If you want to report any issues with this page, please comment below.