Github Pages with Jekyll themes and Giscus

When starting a personal blog, there are three tools you should know: GitHub Pages, Jekyll, and Giscus.

• Github Pages: A free service from GitHub that allows you to deploy static websites directly from a repository. Just push your code to GitHub, and your blog will automatically go live on the Internet without needing your own server.

• Jekyll: A static site generator integrated with GitHub Pages. Jekyll makes it easy to create blogs from Markdown files, organize content using templates, and apply ready-to-use themes.

• Giscus: A modern comment system based on GitHub Discussions. Instead of using external services like Disqus, you can leverage GitHub to manage comments, keeping it lightweight and developer-friendly.

1 Requirements

• A Github account
• Basic knowledge of Markdown

2 Creating a Site Repository

Here, I use the Chirpy theme, a popular theme for GitHub Pages optimized for personal or technical blogging.

Steps:

• Log in to Github and go to the starter.
• Instead of forking, click Use this template and select Create a new repository to automatically create a Site Repository.
• Name the new repository <username>.github.io, replacing <username> with your GitHub username.

3 Setting up the Environment

There are two main reasons to set up a local development environment for your blog:

• After pushing code to the repository, GitHub Actions takes time to run before building and rendering the site on GitHub Pages.
• By developing directly on your local machine, you can see changes instantly—faster and more convenient.

3.1 Using Dev Containers (Recommended for Windows)

Dev Containers provide an isolated environment via Docker, preventing conflicts with your system and ensuring all dependencies are managed inside the container.

Steps:

1. Install Docker:
   • On Windows/macOS: install Docker Desktop.
   • On Linux: install Docker Engine.
2. Install VS Code and the Dev Containers extension.
3. Clone the repository:
   • If using Docker Desktop: open VS Code and clone the repo in a container volume.
   • If using Docker Engine: clone the repo locally, then open it in a container in VS Code.
4. Wait for the Dev Containers setup process to complete.

3.2 Setting up Natively (Recommended for Unix-like OS)

For Unix-like systems (Linux, macOS), you can set up the environment directly (natively) for better performance. Dev Containers are still available as an alternative.

Steps:

1. Follow the Jekyll installation guide and ensure Git is installed.
2. Clone the repository locally.
3. If you forked the theme, install Node.js and run bash tools/init.sh in the root folder to initialize the repo.
4. Run the following commands in the root folder to install gems into ./vendor/bundle/ within the project—no need for sudo and no changes to /var/lib/gems..

bundle config set --local path 'vendor/bundle'
bundle install

4 Usage

4.1 Start the Jekyll Server

To run the site locally, use:

bundle exec jekyll s

4.2 Configuration

Some variables to configure in _config.yml include:

• lang: set the website language
• url: your website URL
• title: main title shown under the avatar
• tagline: subtitle or site description
• avatar: supports local and CORS resources, including gif

4.3 Comment feature via Giscus

We’ll use Giscus as the comment system. Other free alternatives include Disqus and Utterances.

Steps:

1. Install giscus on GitHub.

2. In your repository Settings, go to General and enable Discussions so giscus can store comments.

3. Enter the repository name <username>/<username>.github.io. A green checkmark will appear when requirements are met.

4. Choose the discussion category and topic for your site.

5. Configure giscus in _config.yml:

   • provider: set to giscus
   • giscus: map the variables you set on giscus to the giscus section

4.4 Customize the Favicon

Create a custom favicon for your website instead of using the theme’s default.

Steps:

1. Go to Favicon Generator.

2. Click Browse to select your favicon file, then Create Favicon.

3. Click Download the generated favicon to get the files.

4. Extract the downloaded file and delete these two:

   • browserconfig.xml
   • site.webmanifest

5. Copy the remaining files into assets/img/favicons (create the folder if it doesn’t exist).

5 Extends

5.1 Remove meta tag in Footer

You can remove the line Using the Chirpy theme for Jekyll. with these steps:

1. Create a file at _data/locales/en.yml.
2. Copy the contents of en.yml and paste into the new file.
3. Change the value of meta to "".

5.2 Write a post

Check the rules for writing blog posts with this theme and use Live Preview to preview your content.