This tutorial is structured to get you started with hosting your website via github. Here we built our website using Academic Pages, but there are many other available options, which you can browse here.
Most of the materials in this tutorial are directly taken from the Academic Pages template, and when necessary we are adding commentary and additional steps to make it more user-friendly. We wrote this tutorial based on MacOS, so if you are using a Linux or Windows machine, please refer to the Academic Pages repository for more instructions.
Tutorial duration: 10 - 15 mins.
1 Academic Pages Template
Academic Pages is a ready-to-fork (or clone) Github Pages template that is commonly used for academic personal websites.
In this brief tutorial, we will go over the basic set-up you need to clone the repository to your own Github account, and then you can edit your website on your pace.
First, let’s take a quick look at this Academic Pages template. You will see that it comes with pretty much all the sections that you may want to display on your academic website.
Now, we can check the GitHub repository for this template, and see what goes into this website. As you’ll see, there are a number of folders and sub-folders, each corresponding to one of the tabs you see on this website. You will also notice that we will be working with files of various formats, like markdown and html. The good news is that these are all the templates that we will easily edit in the next tutorial, once we clone this template to our own GitHub as a new repository.
2 Clone the Repository
Academic Pages recommends you to directly fork the repository, but when you fork, 1) your website layouts are subject to random changes if Academic Pages commits major updates to the original repository, and more importantly, 2) your website repository becomes publicly available immediately.
If you are anything like us, you may feel awkward to put your unedited repository online publicly yet (or ever). Worry not, as there is another way! We can clone this template to our github account as our own repository, which will remain private until we are ready to make it visible to everyone online (more on this in the next tutorial)! To do so, follow the next few steps:
On your preferred browser, log in to your own GitHub account. If you don’t already have an account, register for one, and make sure to confirm your e-mail (required).
Now, open the GitHub page for the template.
Navigate your way to the
"Use this template"button, and select the"Create a new repository"option.
- This will take you to a new page to let you create a new repository. From here, type the name you want to use for your website as “[your Github username].github.io” (note, this will be your website’s URL). Next, turn the visibility setting under Configuration from public to private (unless you are braver than we are 😃). Then, click on “Create repository” button, and voila!
Now that you have your own repository, we can move to the next steps of setting up this repository on your local device to start editing. Of course, you can directly edit online, but I find it easier to work on a local directory. Additionally, this will help us see how the changes we implement will appear on our website, before we push all the edits back to the online repository (so it gives us a lot of flexibility!).
3 Set up Git on your device to run locally
If you scroll down on your new “[your Github Page name].github.io” repository, you will find detailed instructions to different options you could use (and set up for) to work on your website locally. Here we will cover the main option, and follow the next steps:
3.1 First, let’s clone your repository to your device locally
Run the following code in your terminal. Make sure to edit the code to access and clone your own github repository.
cd ~
git clone https://github.com/your-username/your-username.github.io
cd your-username.github.ioIf you have never used Git via your terminal before, you may be prompted to enter your password. Currently, GitHub is no longer accepting passwords for authentication via HTTPS. You will therefore need to authenticate using a Personal Access Token (PAT) or set up SSH keys. Follow the steps before to set up and use a PAT for authentication.
Step 1: Create a Personal Access Token (PAT)
Go to: https://github.com/settings/tokens
Click “Generate new token (classic)”
Give it a name like Git from VSCode
Select scopes:
✅ repo (to access and push code)
Set an expiration date (e.g., 30 or 90 days)
Click Generate token
Copy the token immediately — you won’t see it again!
Step 2: Use Your Token When Pushing
When you push (git push origin master), Git will prompt for a username and password.
Username: Your GitHub username
Password: Paste the token you copied instead of your GitHub password
From here on, run the code below within your local your-username.github.io directory.
3.2 Next, make sure you have ruby-dev, bundler, and nodejs installed
On MacOS, the commands are:
brew install ruby
brew install node
gem install bundler3.3 Run bundle install to install ruby dependencies.
If you get errors, delete Gemfile.lock and try again.
If you see file permission error like Fetching bundler-2.6.3.gem ERROR: While executing gem (Gem::FilePermissionError) You don't have write permissions for the /var/lib/gems/3.2.0 directory. or Bundler::PermissionError: There was an error while trying to write to /usr/local/bin. Install Gems Locally (Recommended):
bundle config set --local path 'vendor/bundle'Then, try run bundle install again. If succeeded, you should see a folder called vendor and .bundle.
3.4 Run bundle exec jekyll serve -l -H localhost to generate the HTML and serve it from localhost:4000.
You can copy and paste the generated local host link to your browser, and this will show you how your page currently appears. Note that it should look the same as the Academic Pages for now since we have not edited anything yet. As we make edits to our website, the local server will automatically rebuild and refresh the pages to reflect the changes (more on this in the next tutorial).
You may also try jekyll serve -l -H localhost but running with bundle exec is safer as it ensures jekyll to use the specific dependencies on your own local machine.
If you are running into issues with jekyll, take a step back and make sure Jekyll is properly installed here
4 Set Up VSCode
As we edit the content and appearance of our website (next tutorial), we will use VS Code to flexibly edit both markdown and html files. So, make sure to install Visual Studio Code (VS Code) to your device before you start the next tutorial.
5 Materials to Prepare Before the Next Tutorial
At this point, if you can generate the local host, you have your repository properly set up on your local device and can start thinking about how you’d like your website to look. Please take some time to think about how you want to present yourself on your website, and prepare the following materials before the next tutorial:
A profile pic (ideally in .jpeg, .jpg or .png)
A short bio to go into your home/about me page
Your current CV/Resume
Your online presence (links): github, linkedin, google scholar, bluesky etc
(Optional) Contents for your publications and/or portfolio pages
Here we provide a few examples to give you some ideas. Note that not all of these websites used the Academic Pages template, but it is useful to look at various examples to gather your thoughts on your own preferences.