Personalize Your Github Academic Website-1

Note

In this tutorial, we will set up the basic configurations for your website (e.g. personal information, site-wide layouts), and customize your homepage.

We will use VS Code to edit both markdown and html files. If you have not yet installed VS Code, please do so before you continue with the rest of the tutorial. If you are comfortable using Jupyter Notebook, that is another great alternative!

If you are new to Github Academic Pages, and have not yet created your own repository on GitHub to host your website, please first read our Intro to Academic Pages tutorial.

Tutorial duration: 15 - 20 mins.

1 Basic Configuration

First, open your local repository via VS Code:

Select the folder corresponding to your cloned Academic Pages repository (your-username.github.io)

Colors indicate git status of the files in a folder

Before we start editing, let’s make sure we can see how our website is currently looking. Run the code below:

cd path-to/your-username.github.io
bundle exec jekyll serve -l -H localhost

This should start a localhost which you can load in your preferred browser, where you see how it currently looks. As soon as an edit is made locally, this preview will be updated automatically without a commit.

1.1 Editing basic information in _config.yml

Let’s start by replacing some of the default contents with your personal information. Open _config.yml:

• Edit all the fields under Basic Site Settings and Site Author to reflect your information. Set url to https://[your GitHub username].github.io – it must match with your GitHub username to correctly render the website at [your GitHub username].github.io! Alternatively, if you already have and prefer to use a personal domain, enter it for url here. Make sure to keep baseurl as "".
• Comment out with # if you don’t want a field to appear.
• Edit your biographic information that will appear on the side column. To display a photo above your name, add the image file under images/, and update avatar with headshot_filename.JPG (or .png). Note the image may not render if the file is too large.

You can leave the other parts of _config.yml as they are for now. Keep in mind that as you further customize your website, you may want to keep the publication_category, collections sections updated.

1.2 Editing _data/navigation.yml

This is where you can design what to appear on the menu bar on the top of your website. You can see the default settings currently being rendered, e.g. Publications, Talks, Portfolio, etc. If you don’t want a category to appear, go to _data/navigation.yml, and comment the corresponding lines out with #. For the purpose of this tutorial, we only keep “Publications” and “CV” (not “cv-json”). We will later see how to create “Projects”/“Portfolio” as well.

The page that you will be redirected to after clicking on an option in the navigation bar is written by the .html or .md files under _pages/. If there are webpages nested in this page (e.g. a webpage for a single publication entry), a separate folder (e.g. _publications/) will contain .md files for every such webpage. In the next tutorial, we will show how that is done for “Publications”.

1.3 Removing Unnecessary Links / Icons

There are a lot of files in the template we cloned / forked. Before publishing our websites, we want to make sure the default content that are no longer relevant do not appear. Below is a non-exhaustive list of items we found unnecessary and better to be turned off.

• Remove “feed”: in _config.yml, set hide: true under atom_feed.

• Remove the “share” icon in each page: under defaults in _config.yml, set values: share: false for the corresponding type of pages.

• By default, the author profile on the sidebar always shows up in every page. If you want to turn it off for a specific page (e.g. Publications), set values: author_profile: false.

• Take a look at the _pages/ folder. When the website is rendered, each of the existing .html / .md files here will be turned into a webpage. If you open any of these files, there is a permalink in the header, which can be appended to the root address of your website to view this page. If you don’t want it to be visible / searchable, make sure to comment out the permalink (html: <!-- -->, md: #). Then, if you type the same address, a “Page Not Found” page will appear (which you can also customize in _pages/404.md).

• To delete “sitemap” in the footer, go to _includes/footer/custom.html, comment out everything.

• Update README.md so that the homepage of your github repository does not show information for Academic Pages.

• You may also want to delete any irrelevant folders or files in the forked repository. For example, you can delete extra image files under /images. Do so carefully and only if you know what you are deleting. Always preview before your commit.

2 Homepage

The first content you might want to modify is the homepage. This is the root page that people will see if they go to your github-name.github.io website. To do so, open _pages/about.md. Update the title in the header, and replace the text below with your short bio.

3 Next step

Congratulations on finishing the basic setups for your personal website! If everything looks good in the preview, you can commit and push to your github repo! You may need to wait a bit for it to render the website. As soon as you see a green check mark next to your most recent commit, you should be able to view your website on the browser.

Committing and pushing our edits:

In addition to the flexibility of editing, VS Code also allows us to directly commit our changes in our local repository (highlighted in yellow in the above screenshot), so the changes are pushed to the online version before we finish our editing session.

That said, we can also make those commits in a new terminal window, using the code below:

cd path-to/your-username.github.io
git add . # will compile all the edits you made across all your files
git commit -m "[write details of this commit: what updates are you pushing?]"
git push origin master # or main, depending on how the branching looks on your github!

Not satisfied with the basic configurations? Check out our second tutorial on how to customize the main pages shwon in the menu bar – “Publications”, “CV”, and “Portfolio”.