In my Hello Internet post I announced my intention to write a post on how I set up this blog and how you can do the same. The time has now finally come, and the original idea has morphed into a two-part series. Enjoy!
This tutorial is primarily meant for beginners. It explains cloning this blog from Github, personalizing it with custom icons, name and color, and finally publishing it with Github pages. Part 2 goes further into the technical details of the blog.
Before we dive into building a static website, it is helpful to quickly look at what a static website actually is.
Well, it turns out there’re quite a lot of advantages to static sites, if all you have is static content. Static sites are…
- faster: only HTML, CSS, JS and images are served
- safer: no login systems, etc. means a minimal attack surface
- more accessible: an old browser and a slow internet connection is fine
- cheaper: free hosting available, e.g. with Github Pages or Netlify
… than their dynamic counterparts.
A static site doesn’t necessarily mean being limited in functionality, or having a site consisting of only text and images. There are a lot of possibilities on the front-end, ranging from embedded YouTube videos and RSS feeds to a comment system (more on this later on and in Part 2).
When creating your static blog, it can be helpful to use a Static Site Generator (SSG). An SSG helps to make the development and editing process comfortable. Instead of writing your posts in plain HTML, you can write them in Markdown and have the SSG convert your posts to HTML files.
This is a similar idea to the concept of compiling code from a higher level language (such as C or Rust) to machine code, allowing you to write fast code in a simpler and human-readable form. The process of “compiling” your website will be referred to as building in the following.
Before we get started with the setup, make sure you have the following prerequisites:
- git: You can find installation instructions for all platforms here
- github: You can create an account here
- node: You can download node from here
Start by cloning my blog from the Github repository. In a terminal, run:
git clone https://github.com/umcconnell/umcconnell.github.io.git blog
This will clone the code into the folder
In the blog root folder, install the required dependencies using npm:
The installation might take a minute or two.
Once the installation has finished, you are ready to run the build process and serve the blog on your localhost. Run:
npm run dev
You should be able to navigate to localhost:8080and see the blog as it appears here.
Now the blog is ready for customization. To do that, you will need to change four files:
package.json file describes your node project. It mainly contains information about the project’s source code and package dependencies.
You can add your name to the
author field and change the
description field to your liking.
repository.url fields should contain your project name and source code repository. The project name should be
GH_USERNAME.github.io, the repository url
http://github.com/GH_USERNAME/GH_USERNAME.github.io accordingly. Replace
GH_USERNAME with your Github username.
LICENSE file to mention your name as the Copyright owner in the first line.
src/site.webmanifest file describes the web app behavior of your blog. This controls how the website will be presented when a user adds the blog to their home screen, i.e. installing the web app.
Here, you can change the
Finally, the last file to personalize is
src/data/meta.json. This file contains important meta-information about the blog, such as the author, the source and comment repositories for the blog, etc.
Make sure to change the
author fields, which will for example change the footer or the about page of the blog.
url should contain the final URL of the website, i.e.
GH_USERNAME is your Github username.
If you do not want to use a custom domain name for your website, such as
example.com, set the
custom_domain field to
If you own a domain and want to set it up for your blog, you can specify your custom domain in this field. This then generates a CNAME file in the build output for you to configure with Github pages. See this articlein the Github docs on for instructions on how to set up a custom domain for your site.
Most importantly however, change the fields in the
code section of the webmanifest:
repoentry should point to the Github repository of the website (
commentsfield points to the repository that will save user comments from the blog. This should be
GH_USERNAME/comments. We’ll create this repo later.
Once you’ve saved the files, you should be able to see your name appear on the blog.
To change the icons that appear in the header, when installing the web app, etc., navigate to
The avatar, displayed in the header of the website, can be changed by replacing the
avatar.png file with your own image. You may also change the
email.png image, which is displayed in the about page as your contact information.
The icons used for the web app are located in the
favicon/ subfolder. When replacing these icons with your own, custom icons, make sure to keep the naming and size of the individual files.
If you want, you can further personalize the blog with custom colors, styles, and more. All styles and related configurations are located in the
src/assets/styles/ folder. Stylesheets are written in SCSS. Note that all valid CSS is valid SCSS, which means you can style the blog in plain CSS if that is more familiar to you.
More specifically, the colors used throughout the web page can be changed in the
utils/_variables.scss file. The main theme color is defined by the
$brand-color-primary variable.These variables are used in all the other styles, which means it should be enough to change the colors in this file.
The last thing to do personalize your new blog is to activate the comments functionality. The blog uses a free service called utterances, which takes care of managing your comments. It will display a widget at the bottom of your blog post, that lets users leave a comment. Note that the comments widget is not displayed when you are in development mode and serving your blog on localhost (
npm run dev). It will appear in the online version.
The comments are stored in a Github repository, which means you don’t need to worry about storing your comments. To be able to store comments in a Github repository on your behalf, you will need to install the the utterances Github app. Follow the link and click the install button. You will need to grant the app access to your repositories. You can later restrict access to the comments repo only in your settings.
Your new blog should probably contain a introductory post. All posts are written in Markdown and located in
Go ahead and delete the posts already in the folder (all files ending with
.md). Next, create a file called
DD refers to the current date (e.g. 2021-03-14).
You place the following text into the file and modify it to your liking. Changes you make to the file should be reflected instantaneously in your web browser.
title: Hello World
Hello World introductory post.
This is my _brand new_ blog. **Enjoy**!
That’s it! You’re blog is ready to go online.
After customizing the blog, we are now ready to publish our blog. We will publish the blog on Github pages. After following these steps, your page will be available at
Start by committing all your customization changes to git. In the root folder of the blog, run:
git add .
git commit -av
Next, we’ll create the Git repositories that will hold the source code of your blog and the comments to your posts.
In your web browser, navigate to github.com/newto create a new repository.
For the comments repo, enter
comments as the repository name. Make sure, the repo visibility is set to “Public”, before hitting the “Create repository” button.
Repeat this step for the repo that is going to hold the blog’s source code. Enter
GH_USERNAME.github.io as repo name (where
GH_USERNAME is your Github username) and select the visibility “Public”. Then, create the repository.
You should see a set of instructions to publish your code. Note the instructions to “push an existing repository from the command line”. When executing these instructions in the root folder of your blog, you will need to change one command. Because you have cloned the original blog code from Github, it already has a remote git origin set. You will need to use
set-url instead of
git remote set-url origin https://github.com/GH_USERNAME/GH_USERNAME.github.io.git
git branch -M main
git push -u origin main
The last step is to publish your pages using Github pages. In your repository containing the blog source, navigate to the “Settings” tab. Almost at the bottom of the page, you should find a “Github pages section”.
From the source drop-down, select the “gh-pages” branch. After hitting the save button, your site should be available online.
My friend Boldizsar Zopcsak and I recorded a video tutorial about this whole procedure a little while ago. The video goes through the basics of cloning, personalizing and publishing your next blog. Feel free to have a look:
For a look at the technical details of this blog, head over to Part 2 of this series.