Introduction

This workshop is a gentle introduction to Git, GitHub and Web Development with the goal of creating and publishing a personal portfolio website. We will start with a ready-to-use portfolio website template for geospatial professionals and learn how to edit and set up your GitHub repository to publish your website. We will cover best practices on leveraging LLM-based AI assistants to extract and format content from existing documents and populate the portfolio.

At the end of the workshop, you will have a beautiful, modern and customized portfolio website that is hosted for free on GitHub Pages and ready to be shared with your network.

No prior experience with Git or GitHub is required.

This workshop will cover the following topics:

Introduction to GitHub and GitHub pages
Introduction to Static Site Generators
Fundamentals of Markdown
Introduction to MkDocs
Use of AI-Assistants to automatically extract and format content from your CV and Project Reports
Setting up a local development environment and advanced customization

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

View Example Portfolio Website ↗

Installation and Preparation

Install Git and GitHub CLI

Follow our Git and GitHub CLI Installation Guide install and configure Git and GitHub CLI.

Install Conda

We will use conda to install the required Python packages and manage local development environment.

Follow our step-by-step Conda Installation Guide to install Miniconda for your operating system.

Install Visual Studio Code

We recommend Visual Studio Code (VS Code) editor for this workshop.

Follow our step-by-step Visual Studio Code Installation Guide to install and configure VS Code on your system.

Sign-up for Claude

We rely heavily on LLM-based AI assistants for populating the content of your portfolio. If you already have a favorite coding assistant (ChatGPT, Microsoft Copilot etc.), you may use it for this workshop. However, we strongly recommend using Claude. You can sign-up for a free account using the instructions below.

Visit Claude AI and sign-up for an account. Select the Free plan.

For this workshop, we will be using the web interface. Click Skip when prompted to install the app.

Prepare 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 your 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. Basics of Git, GitHub and Web Development

View the Presentation ↗

2. Setting up Your Local Development Environment

In this section, we will clone your GitHub repository to the computer, install the required packages, and start a local preview server.

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

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.

In your GitHub repository, click the Code button and copy the repository URL shown for HTTPS. The URL should be in the form https://github.com/<your-username>/<your-username>.github.io.git.

On your computer, launch Visual Studio Code. Click the Explorer button to open the file browser and click Open Folder. Browse to a folder on your computer where you want the Git repository. The Desktop folder is a good choice as you easily locate it for copy/pasting files. Select it and click Open. If you are prompted with a security warning, click Yes, I truest the authors.

Once the folder is open, open a new terminal by going to Terminal → New Terminal.

A new terminal will open and the current working directory will be set to the open folder in the editor. Also the conda environment will be initialized and you should see the base environment activated.

On some Windows systems, you may get a Powershell UnauthorizedAccess error. Run this command and restart the terminal to fix it.

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Now we will clone your Git repository to computer. Enter the following command - replacing the URL with your own repository URL.

git clone https://github.com/<your-username>/<your-username>.github.io.git

This will copy the repository to your computer. Use the cd (Change Directory) command to go to the folder with the newly cloned repository.

cd <your-username>.github.io

The repository contains a environment.yml file with instructions for a conda environment. Run the following command to create a new environment using this file. This will create a new conda environment named portfolio and install the required packages.

conda env create -f environment.yml

Once the installation finishes, activate the environment.

conda activate portfolio

Next, we start a local MkDocs server which will build the portfolio website from the source content. The --livereload option tells the server to watch the files in the repository and automatically rebuild the site whenever we update any content.

A warning maybe displayed about the MkDocs 2.0 version. You can ignore it.

mkdocs serve --livereload

Once the server has started, open your browser and go to http://127.0.0.1:8000. You will see the portfolio website.

Your local development environment is now setup. Keep the server running so you will be able to preview changes as you edit the content. Click the Hide Panel button to close the Terminal window. If you want to see it, you can open it from View → Terminal

3. Introduction to Markdown

Markdown is a simple formatting language to create structured documents. It allows you to write plain-text documents with simple markups that is both human and machine-readable. It is a widely used standard for creating documents, websites, and prompts for AI models. We will now practice writing Markdown by editing the README.md file in your repository.

Expand your repository’s folder in Visual Studio Code’s Explorer. Click on the README.md file.

Delete the existing text and enter new text about your repository in the Markdown format. Below is the sample text you can use. You can use the Open Preview to the Side button to see the rendered version of your text.

You can see Github’s Markdown Guide for help with syntax.

# [YOUR NAME]'s Portfolio

This is the repository for my portfolio website. The portfolio is hosted at https://<your-username>.github.io/

 This website is built using the following tools
 
* MkDocs
* GitHub Pages
* GitHub Actions

> Tip: You can get the portfolio template from [Spatial Thoughts](https://github.com/spatialthoughts/portfolio-website-template)

Check the preview and fix any formatting issues.

Once you are done, save the changes from File → Save.

4. Introduction to MkDocs

MkDocs is a Python-based static site generator focused on building project documentation sites. The template we are using is setup to use MkDocs to create the portfolio website using the following components.

Content: Each page is a Markdown (.md) file in the docs/ folder.
Configuration: All configuration lives in a single mkdocs.yml file. The site name, navigation etc. are defined in a single place.
Theme: The template uses the popular Material for MkDocs which supports responsive design with search, dark mode, and more.

5. Publishing Your Portfolio Site

We will now edit the content files using a code editor, preview the updated portfolio and then push the changes to GitHub.

5.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.

From your GitHub repository folder, locate the mkdocs.yml file. Click on the filename to edit it.Update the placeholders with your name and information. At the least, you should update the site_name, site_description, site_author, site_url, copyright and extra.social values.

5.2 Editing and Committing Changes

All the content pages as in the Markdown format (.md). We can edit these files and preview the resulting site. Once we are happy with the changes, we will commit and push these changes to GitHub.

1.We will start by updating the homepage of the site which is built from the index.md file. The homepage requires a profile picture and an about me picture. We will first upload these image. Go to the docs/assets/ folder, right-click and select Reveal in File Explorer.

In the docs/assets/ folder, copy your CV. You can name your file <your name>-CV.pdf (If your name is John, name the file John-CV.pdf).

GitHub has a limit of 25MB per file. Ensure your CV file is smaller than the limit. You can use a tool such as Smallpdf to compress your file.

Next, replace the placeholder images in the docs/assets/images/ folder with your own. Copy your profile photo named profile.png (case sensitive). Similarly, copy your about me picture named about.png.

Ensure your photos are not too large. These photos are loaded every time someone visits your homepage. To ensure optimal experience, ensure the pictures are not too large. Use Resize image tool on your computer to reduce the size of the images to a maximum of 500px.

Now we will update the Markdown file for the homepage. Locate the index.md file in the docs/ folder. Click to open it.

In the 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. If your uploaded images have different names, make sure to update them as well. 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.

Your homepage is now ready. Head over to the browser tab connected to the local development server. 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.

We will now commit these changes and push them to GitHub. Go to View → Terminal. Click the + New Terminal button.

Change the directory to the GitHub repository and enter the following command to see the status.

cd <your-username>.github.io

git status

We have some modifications to existing files and some new files that needs to be committed. We first use git add command to move these changes to the staging area. git add . stages all changes in the current directory and its sub-directories.

git add .

Now we commit these changes to the Git repository. The -m option is to add a commit message that will appear in the Git history.

git commit -m "update"

Next, we push the locally committed changes to the GitHub repository.

If you get an error, make sure you have signed-in to your GitHub account using the GitHub CLI

git push

5.3 Understanding GitHub Actions

GitHub Actions is feature of the GitHub platform that allows you to automate workflows. You can setup actions to trigger a task when a specific event happens. The template repository you used to create your portfolio, already comes with a pre-defined workflow action that watches your repository and runs MkDocs to generate new set of static HTML pages whenever you update the main branch. Let’s understand how actions work.

Go to your GitHub account and load the repository for your portfolio. GitHub Actions are defined in the .github/workflows/ folder. Click on it.

Open the deploy.yml file which contains a workflow named Run MkDocs and Create HTML Pages. This file is a YAML configuration that defines when the action will be triggered and what sequence of commands will be run. The main step here is the step called Deploy which runs mkdocs gh-deploy --force command which builds your site and updates your gh-pages branch with the new HTML pages. The workflow is set to be run on whenever a new commit is pushed to the main branch. Click the View Runs button.

This shows all the previous runs of the workflow. As you recently pushed new changes to the main branch, you will see a recent run of the workflow.

Let’s switch to the gh-pages branch. Go to the repository home and select the gh-pages branch from the dropdown menu.

You will see that the gh-pages branch contains the static website pages created by MkDocs. All the files were recently updated by the GitHub Action. The homepage of the website is the index.html file. In the next section, we will publish these pages as a static website using GitHub Pages.

5.4 Enabling GitHub Pages

GitHub Pages is a static site hosting service that turns your repository files into a live website. You can enable Github Pages on your repository and configure it to publish the content from a branch to your user site. As MkDocs is setup to generate and push the pages to the gh-pages branch, we will setup GitHub Pages to serve from that branch.

Go to your portfolio repository on Github. Navigate to Settings → Pages.

For user repositories named <your-username>.github.io, GitHub Pages is enabled by default. If it is not enabled for your repository, select a branch under Deploy from a branch option.

Select gh-pages and click Save.

A built-in action will now run and deploy your site to GitHub Pages. Monitor the progress of the action by going to Settings → Actions.

Once the site is deployed, go to Settings → Pages and click on the Visit site button.

You will now see the site deployed and accessible from a public URL <your-username>.github.io.

This is a one-time configuration. Now your repository is set to automatically build and deploy to GitHub Pages every time you push a change to the main branch of the repository.

6. Updating the Site Content

6.1 Updating Content Pages (LLM Assisted)

You are now familiar with the process of updating the content of a page with Markdown text. You can update the contact.md, experience.md and publications.md with personalized content. Most of this content will already be present in your CV, LinkedIN profile or Google Scholar. In this section, we will learn how we can use LLM AI Assistants to automatically format existing content to Markdown for easily updating your portfolio.

We recommend using Claude AI but you may use your favorite AI assistant.

Locate and open the experience.md file in the docs/ folder. This file is for the page on your portfolio that lists your work experience, education, certifications etc. We will automatically create this content from your CV. Click on the file and open it.

Click on the Raw button and copy the URL.

Go to Claude AI and start a new chat. Attach your CV and enter a prompt like below. Make sure to replace the path to the experience.md with the Github URL you copied in the previous step.

I want to use the information from my attached CV to update my online portfolio. See the file https://raw.githubusercontent.com/<your-username>/<your-username>/refs/heads/main/docs/experience.md for the required format. Format the content from my CV as Markdown that I can copy/paste to update that file.

Copy the LLM generated Markdown content. Go to the GitHub repository and open the experience.md page for editing. Paste the content after the checklist. Preview the output to verify it looks correct and make any adjustments you like. Click Commit changes… to save the changes.

Once the site rebuilds, refresh the portfolio and you will see the updated page.

You can repeat this process for the publication.md page to pull your publications from your CV, ResearchGate or Google Scholar profile.

6.2 Adding a New Page

The template provides you with a handful of pages pre-configured for the website. It is quite easy to add new pages. Adding a new page is a 2-step process - you first create a new file with the content and then update the mkdocs.yml file to add it to the navigation. Let’s create a new page.

Go to the docs folder and click Add file → + Create new file.

You can name the page with the .md extension. Here we are creating a new page that lists learning resources so we have named it resources.md. Add the content for the page in the Markdown format. Here we are using the Grids provided by the Material theme to organize the resources in a responsive layout. Click Commit changes… to save the file.

Next go to the root of your repository and locate the mkdocs.yml file. Open it for editing and scroll down to the nav: section. Add the newly created page to the navigation menu. Click Commit changes… to save the file.

Once the site rebuilds, refresh the portfolio and you will see the newly added page.

6.3 Deleting a Page

If there are pages from the template that you would like to remove, you can first remove it from the navigation menu in mkdocs.yml and delete the file. Let’s see the process by removing the publications.md page.

Open the mkdocs.yml file and scroll down to the nav: section. Locate the item with the page that you would like to delete.

Delete the line and click Commit changes…. This will now remove the reference to this page from the navigation menu.

Go to the docs/ folder and open the file that you want to delete.

Click on the … menu and select Delete file.

Click Commit changes… to delete the file.

Once the site rebuilds, refresh the portfolio and you will see the updated menu.

6.4 Adding a Project Page (LLM Assisted)

The portfolio template is custom design to showcase your project. You can add multiple projects to your site. Each project will be shown using a card layout. Adding a project requires uploading a cover image and creating a Markdown file.

Go to the docs/assets/images/ folder and click Add file → Upload files.

Upload a cover image for your project and click Commit changes…. The project images are shown as horizontal cards, so choose an appropriate image with a landscape layout.

The template comes with a sample-project.md file with suggested sections for a project. Open the file and click on the Raw button. Copy the URL. We will use this to prompt an LLM Assistant to help us draft the project page.

Go to Claude AI and start a new chat. Enter a prompt shown below, replacing the image name and file path with your own. Claude will ask you questions about the project and share as much information as you can. You can optionally attach your project report or add a link with information about your project. Once the content is created, click the Copy button.

I want to add a project to my portfolio
My image is uploaded at docs/assets/images/<image-path>.png

My template is at https://raw.githubusercontent.com/<yourusername>/<your-username>.github.io/refs/heads/main/docs/projects/sample-project.md 

Ask me questions regarding my project and once you have enough information, generate the content in Markdown format that I can use to create the page

On GitHub, go to docs/projects/ folder and create a new file. Enter the name as <project-name>.md and paste the content. Edit the content as required and click Commit changes….

We need to add the project to the card layout. Open the docs/projects/index.md file.

Edit the file with the project name and description. Update the cover image and project file path. Click Commit changes….

Next, we add this project to the navigation menu. Edit the mkdocs.yml file and add the name and path of the project file and click Commit changes….

Once the site rebuilds, refresh the portfolio and head over to the Projects page to see the new project.

6.5 Adding a Notebook Project

The portfolio template also supports using Jupyter Notebooks (.ipynb) as project pages. The notebooks can have cells with Markdown content, code, charts, interactive maps. These will be converted to compatible Markdown content by MkDocs and will be rendered as a project page. Adding a project via a notebook requires uploading a cover image and a notebook file.

Prepare your project notebook. Make sure to add a Markdown cell at the top with the project title. You may clear outputs of cells with warnings or unwanted outputs so your resulting page is clean. Also make sure to replace any API Keys with placeholders.

On Github, go to the docs/projects/ folder and click Upload files.

Select the project notebook file and click Commit changes….

Next, go to the docs/assets/images/ folder and upload the cover image for the project.

Now we will update the index.md in the docs/projects/ folder with the card for the newly uploaded project.

Replace the placeholder project card with the details of your notebook project.

Next, we add this project to the navigation menu. Edit the mkdocs.yml file and add the name and path of the project file and click Commit changes….

Once the site rebuilds, refresh the portfolio and head over to the Projects page to see the new project.

Supplement

Adding a Cover Image on the Homepage

To add a cover image to your homepage, add a banner image assets/images/hero-image.png and update the Hero section in the assets/css/extra.css as below.

/* Hero section on the Home page */
.hero {
  text-align: center;
  padding: 1rem 1rem 1.25rem 1rem;
  background:
    linear-gradient(135deg, 
      rgba(232,244,248,0.82) 0%,
      rgba(240,247,255,0.82) 50%, 
      rgba(232,240,254,0.82) 100%),
    url('../images/hero-image.png') center / cover no-repeat;
  border-radius: 8px;
}

Using a Custom Domain

GitHub Pages allows to connect your site to your own domain name and host the GitHub Pages site on it. See About custom domains and GitHub Pages for official instructions. We are providing simplified version of these instructions here for the most common setup.

To use a custom domain, you need to purchase a domain name. There are many registrars who sell domain names. The cost depends on the uniqueness of the domain and the extension (like .com, .in, .ai). We recommend Hover for purchasing the domain but you can use any registrar of your choice. All you need is the access to the control panel.

Make sure to include WHOIS privacy when purchasing a domain. Skipping this may expose your contact information to the public.

Once you have access to the domain, login to the control panel. Go to Forwards and setup a forward from your-domain.com to www.your-domain.com. This greatly simplifies the configuration needed to connect the domain to GitHub.

Next, go to the DNS and add a CNAME record for the host www with the value your-username.github.io (replacing your-username with your GitHub username).

Now, go to your GitHub repository. Go to Settings → Pages and add the custom domain name. Make sure to prefix www to the name and click Save. The site URL will update and your portfolio will be visible at the new domain.

DNS propagation can take some time. So you may need to wait 15-30mins before the new domain starts working.

Static Site Hosting Alternatives

There are many services that offer free hosting for static sites similar to GitHub Pages. Below are some of the other popular alternatives

Netlify: Offers additional option of hosted backends that allows you to easily add forms, database and serverless functions.
Cloudflare Pages: Free plan with unlimited bandwidth and Workers to add dynamic logic.
GitLab Pages: Allows private repositories in the free plan.

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

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

Building Your Geospatial Portfolio Website

A hands-on workshop for creating a modern portfolio website using GitHub Pages and MkDocs.

Ujaval Gandhi