How I Deployed a GitHub Pages Site Using the Jekyll Chirpy Theme

A complete walkthrough based on my real setup experience.

Setting up a GitHub Pages site with the Chirpy Jekyll theme taught me a lot about how static sites work, from repositories and config files to Markdown, front matter, and asset management. This guide combines everything I learned into one clear process.

---

1. Create the GitHub Repository

Before anything else, I made sure I had a GitHub account ready.

1. Go to the Chirpy Starter repository: https://github.com/cotes2020/chirpy-starter
2. Select Use this template → Create a new repository.
3. Name the repository:

   yourusername.github.io

   GitHub Pages uses this naming format to automatically recognise it as a site.

---

2. Enable GitHub Pages

Once the repo was created:

1. Go to Settings → Pages.
2. Set the Source to the main branch.
3. Save the settings.

GitHub will now build and serve the site automatically.

---

3. Configure _config.yml

This file defines your site’s identity and core settings. It’s also extremely sensitive, one stray character can break the entire build.

Here are the minimum changes I made:

title: "Your Blog Title"
tagline: "A short description or tagline"
url: "https://yourusername.github.io"
author:
  name: "Your Name"
  avatar: "/assets/img/avatar.png"
lang: "en"
timezone: "Australia/Sydney"

Tip: If your site fails to build, check _config.yml first. YAML is unforgiving.

---

4. Writing Posts in Markdown

Every Jekyll post needs two things:

A) The correct filename

Inside the _posts directory:

YYYY-MM-DD-title.md

Example:

2025-08-30-chirpy.md

B) YAML front matter

This block goes at the top of every post:

---
title: "Post Title"
date: 2025-08-30 20:00:00 +1000
categories: [setup, jekyll, chirpy]
tags: [jekyll, github, chirpy, tutorial]
---

After that, the rest of the file is standard Markdown.

---

5. Uploading Images (Avatar, Icons, etc.)

GitHub doesn’t let you create empty folders, so uploading images requires a small workaround.

Steps I followed:

1. Go to the repository.
2. Select Add file → Create new file.
3. In the filename field, type the folder path you want, for example:

   assets/img/avatar/README.md

   This forces GitHub to create the directory.
4. Commit the file.
5. Navigate to the new folder.
6. Select Add file → Upload files.
7. Upload avatar.png.
8. Delete the temporary README.md if you don’t need it.

This same process works for any asset directory.

---

6. Adding Favicons

Favicons make your site look polished and professional.

A) Create the favicon files

I used: https://realfavicongenerator.net/

1. Upload a square image (512×512px recommended).
2. Keep the default settings.
3. Generate the favicon package.
4. Download the files.

B) Clean up the favicon package

I deleted:

• browserconfig.xml
• site.webmanifest

Chirpy doesn’t need them.

C) Upload the favicons

I created:

assets/img/favicons/

Then uploaded all .png and .ico files into that folder and committed the changes.

It took a little while for GitHub Pages to update, but the icons eventually appeared.

---

7. Your Site Is Live

Once everything was configured:

• GitHub Pages built the site
• Chirpy handled the layout
• Markdown posts rendered cleanly
• Favicons and avatar loaded correctly

The site was fully deployed.

---

Front Matter for Jekyll Posts

When using GitHub Pages with Jekyll, each post starts with a YAML front matter block:

---
title: "My First Post"
date: 2025-08-30 20:00:00 +1000
categories: [blog, example]
tags: [markdown, github, tutorial]
---

Everything after this block is standard Markdown content.

Once you commit and push your .md file to GitHub, it will automatically render the Markdown into formatted HTML on the site or repository page.

Final Thoughts

Setting up a Jekyll site on GitHub Pages taught me a lot:

• how static sites are structured
• how YAML and Markdown work together
• how themes like Chirpy expect files to be organised
• how GitHub handles assets and directories
• how small mistakes can break a build

It’s a powerful setup! Especially if you enjoy tinkering. And now you have the entire process in one place.

---

Bonus: How to Write in Markdown for GitHub

GitHub uses Markdown (.md files) for README files, documentation, and static site content. Markdown is a lightweight formatting language that turns plain text into structured HTML.

Basic Structure

Create a file ending in .md, for example README.md or 2025-08-30-post.md, and write your content using Markdown syntax.

Headings

Use # symbols at the start of a line:

# Heading 1
## Heading 2
### Heading 3

Bold and Italic

**Bold text**

*Italic text*

Lists

Unordered list:

- Item one
- Item two
- Item three

Ordered list:

1. First step
2. Second step
3. Third step

Links

[Link text](https://example.com)

Images

Upload the image to your repository, then reference its path:

![Alt text](/assets/img/avatar.png)

Code Blocks

For inline code, wrap text in backticks:

Use the `git status` command.

For multi-line code blocks:

```bash
git add .
git commit -m "Update post"
git push
```