If you’ve ever happened upon someone’s website and thought “Whoa, this looks cool and I want to make a personal website that looks just like this,” (someone else’s website, obviously, not this one 😜) then you’re not alone. I often got this feeling when I saw my friends’ personal websites but then quickly ran into two problems:

  1. There are no instructions for how they made it! Even when their website code/data/files are publicly shared (e.g. on GitHub), it’s not always clear to me how those pieces all fit together. I could conceivably copy their files and just make edits in place, but I don’t think I would learn the process that well.
  2. I would try search queries like “how to build a website,” but none of those examples quite match the design of the website I saw. The designs in these tutorials are also quite modern with stylish CSS/Javascript bits, which really isn’t what I’m going for.

So the purpose of this blog post is to outline in finer detail exactly the steps I took to get this website to its current state. This way if you want to make your own website that looks like this one and you don’t have a lot of experience (note, I also started with zero knowledge), you can refer to this to get started. I will assume that you have basic experience with GitHub, in the sense that you have an account and know how to create, clone, commit, and push to repositories. Everything else I will be covering in pretty explicit detail. There will, however, be a few places where I won’t spill all the details because some tinkering on your part will help you learn how these tools really work.

Step 1: Know what you want (and what you don’t want)

I knew I wanted a website where I could display my research, professional goals, and personal hobbies to the public. It needed to be able to at least handle text and images and be easy to modify. The idea is I could then provide a link to this website from my other profiles (e.g. Facebook, CV, etc.) and not have to keep track of multiple versions.

I also knew that I did not want to have to learn a lot of new code (e.g. HTML, CSS, Javascript) and would prefer to rely on skills I already knew. In this case, I had a lot of experience with Markdown as I already used it extensively in Jupyter notebooks and READMEs in GitHub repositories. I also like the style of Markdown, as I think the font and color choice are very appealing in a minimalist way, so I figured it shouldn’t be too hard to stitch a few Markdown pages together to create a website. Oh, and because I’m a poor graduate student, I needed the site hosting to be free. 😁

Step 2: GitHub Pages to the rescue

For those who don’t know, GitHub Pages allows you to create a free website linked to your GitHub account. Accounts with username user will have a website with the URL https://user.github.io. If you have your own custom domain name, you can use that in place of the default. I was aware of GitHub Pages for quite some time but never seriously considered it. However, when I looked into it further and realized that you can create fairly complete websites using pure Markdown, I became intrigued.

I already had a GitHub account and was fairly proficient in Markdown, so it was pretty easy to create a repository following the instructions in the previous link. I then cloned the (empty) repo to my computer so I could edit the website locally and push those changes when I was ready. Now all I needed to create my first webpage was to figure out how to get the correct files set up in the repo…

Step 3: Installing Jekyll (but not Hyde)

In reading through various setup instructions, I kept hearing the name “Jekyll” pop up. Combing through the main Jekyll website, it seemed to offer the functionality I needed without being too clunky to work with. I saw there was the option to either start with a template or start from scratch, and I wanted to try the latter because none of the existing themes (including the already-set-up minima theme) appealed to me.

I first followed their installation instructions to install Jekyll and its dependencies on my Windows laptop. Note that a long time ago I had Cygwin synced up with the Windows Command Prompt so some of the command line commands referenced in the Jekyll documentation might be easier for me to call than it will be for you. I then followed their Quickstart guide verbatim, with the myblog folder created on my Desktop.

Step 4: Creating your first page

If all went well, you should see some initialization output in your terminal, with one line in particular saying something similar to

Server address: http://127.0.0.1:4000/

Copy+paste that line into your web browser and actually go to that site. The 127.0.0.1 or whatever appears for you is the address for a local server that is hosting a version of your website. It allows you to make changes on your personal computer and visualize those changes in real time as if they appeared on your live website (which is hosted on a remote server, like GitHub). Nifty!

When you look inside the myblog folder, you’ll see several files, one of which is index.markdown (we’ll discuss the rest later). In website design, it’s common to name the main page index, so think of index.markdown as your homepage. I would not recommend changing this file’s name unless you know what you’re doing. This is where the default server address, without any extensions, will redirect to; and it is what people first see when they go to https://[user].github.io.

Start by adding some text to this Markdown file (don’t change its name, but you should edit the file contents), saving it, and refreshing your browser. You should see your changes propagate to your website on the local server. Congratulations on making your first webpage in Markdown! Hooray! 🎉

Protip: As you use Markdown to format your website, have a cheat sheet like this one open. It can definitely save you a lot of time. Otherwise, I’ll leave it up to you for what content you want to have.

Step 5: Publishing your website on GitHub

This step can come after any of the following steps, but since we have a minimal working example now, we can see what happens if we put it on GitHub.

First, close the tab and local server (you can kill the process with Ctrl+C in the terminal) and copy all of the files and folders into the repo you cloned from GitHub. Now each time you edit your website, navigate to the git repo and use the same

bundle exec jekyll serve

command from that directory so you can more easily save those changes to GitHub. When you have everything moved into the git repo, add those files to git (e.g. git add . from the root folder), commit your changes (e.g. git commit -m "what did you change?"), and push those changes (e.g. git push origin master). Now if you navigate to https://[user].github.io, you should see the live version of your index.markdown file!

Step 6: Configuring your page format

Now that you have the basic setup working (hopefully it’s working…), there’s a lot you can do to customize your website to your liking. If you followed the above instructions, you’ll note that the site is currently using the most basic minima theme. While this definitely gets the job done, there were a few things I wanted to improve…

_config.yml file

.yml is a YAML file extension, which is a common file type for storing configuration data in human-readable form. This is where you can personalize your website with a title, description, your email, and social media handles. The only thing I changed was the title to be my name in both English and Chinese. You’ll notice this appears in the top left corner of my website and on the tab in your browser. I left the rest untouched but this is also where you can set the Jekyll theme (you can see minima is the current one).

Front matter

You’ll notice at the top of the index page there is a section delineated with two --- signs. This section is the “front matter” in Jekyll websites and has some of the page metadata including the layout and title. I gave my index.markdown file layout: page for consistency with other pages (see Step 7 below) and title: Home for the menu bar (next subsection).

I’m of the opinion that having a menu bar greatly improves website navigation, particularly if your content is spread across multiple pages. I don’t like menu bars with dropdown selections because then it means I have to dig through many sub-pages. In order to get a menu bar similar to the one I have in the top right corner, you should follow the instructions in the README in the Minima repo. This is a nice exercise to see the interplay between _config.yml and the metadata stored in your page front matter.

The page layout has a header that I found a little annoying so I removed it by doing the following. First, find the files for the minima theme (or whichever one you chose) on your local machine. Instructions for doing that can be found here. Then copy over the _layouts folder into the root directory of your git repo. Then inside _layouts/page.html, comment out the HTML tag for the header. Voila!

I found the default footer to be bloated and wanted it removed. Similar to the header, this time I copied over the _includes directory and created a blank footer.html file inside.

Favicon

Here’s a fun one that’s a little involved. A favicon is the little image you see in the tab of each website. To set your own, you first have to add an image to your git repo (see Step 9 below for details). Then you’ll want to add the following two lines inside the <head> tag in your _includes/head.html file:

<link rel="shortcut icon" href="/assets/fig/turtle.png" type="image/png">
<link rel="icon" href="/assets/fig/turtle.png" type="image/png">

You’ll have to replace the paths with your own image path (note the relative scope).

Page styles

Similar to the header and footer customizations, we can actually do a lot more with HTML hacking. Doing so requires about 10% skill, 40% courage, and 50% stupidity. Please familiarize yourself with the documentation and how all the pieces fit together. I only made slight adjustments to the color, fonts, and page width.

Step 7: Adding more pages

You’ll notice that there’s another file in your directory named about.markdown. This is another Page on your site that you can put information on. With the way Jekyll is configured, you have to put the main pages in the root directory, which is why about.markdown is where it is. Note that in the front matter there’s an extra variable permalink: /about/. This specifies which URL will be appended onto the main page for ease of navigation. Having intuitive links is really important from a user experience perspective and it will likely save you a lot of pain too. Also note that you can make as many extra pages as you want and selectively choose which ones you include in your menu bar.

Step 8: Adding blog posts

A blog post works pretty similarly to a page, but Jekyll does have some nicer bells and whistles included for styling, referencing, and the like. I would recommend following the above instructions for where to write your blog posts and how best to reference them to suit your preference. You can also add permalinks to blog posts to make them more easily referenced (e.g. this blog post has the permalink /website).

Step 9: Adding other files

If you want to put images, PDFs, JavaScript, and more on your website, you’ll want to put them into an assets folder as described here. For example, I would put my resume inside assets/files/resume.pdf. As you can see, you can reference these files with a relative link from the root directory.

Step 10: Explore. Dream. Discover.

Google is your friend. Otherwise you’re on your own.

I hope you found this blog post helpful. A pleasant surprise that I discovered is how nicely this framework renders emojis! 😊