Kickstarting Chirpy with a Fork

This post is about kickstarting a new blogging website using Chirpy (an awesome Jekyll theme), but doing it the complicated way – forking the repository for the enhanced ability to modify features or UI. It’s not recommended unless you’re familiar with Jekyll (it presents plenty of challenges during upgrades), but if you’re a fan of customizations and keen to learn new things – I believe it is definitely worth the journey.

If you prefer to take it easy albeit with much less customizability, you can always opt for the Starter theme – skip this post completely and read more on Chirpy’s documentation. If you wish to have full access to all the bits and bytes, continue reading here! The steps below may seem a little different compared to the official documentation, but here’s how it worked for me.

Forking the Theme

As already described in Chirpy’s documentation:

1. Sign in to GitHub.
2. Fork the theme repository.
3. Name the new repository <username>.github.io, replacing username with your lowercase GitHub username.

GitHub Actions

1. Open your newly forked repository, which should be in: https://github.com/<username>/<username>.github.io
2. Navigate to the Settings tab.
3. Click on Pages in the left-hand menu.
4. Under Build and Deployment section, change the Source to GitHub Actions.
5. Navigate to the Actions tab and click to enable workflows.

   Since the repository already contains workflows (written by someone else), GitHub automatically disables them for security measures. It is good practice to review workflows before you run them.

   

Modifications to config.yml

1. Within GitHub files browser, open the _config.yml file, it should be located in the root directory of your repository.
2. Click to edit the file and change the url section – it should be https://<username>.github.io, note that it does not end with a front-slash /.

    # Fill in the protocol & hostname for your site.
    # E.g. 'https://username.github.io', note that it does not end with a '/'.
    url: "https://synvani.github.io"
   

3. Change the title to reflect the name of your new website/blog, the rest can be left as is for now, as we just want to get the website up and running to make sure everything works smoothly.

    title: Synvan # the main title
   

4. Commit the changes made to _config.yml, make sure to follow the commitlint rules otherwise your commit would fail – write something along the lines of style: update to _config.yml.
5. You’ll notice that once the commit is accepted and applied, nothing really happens and your website is not up and online just yet (reminder, your url should be https://<username>.github.io). That’s because the workflow to Deploy and Build the website isn’t part of our available workflows!

Adding Deployment Workflow

1. Within GitHub files browser, navigate to .github directory, then workflows, then starter.
2. Inside starter directory you’ll find pages-deploy.yml – the missing workflow!
3. Move or copy pages-deploy.yml file one directory up, so it is within the workflows directory.
   • Move file – refer to GitHub Docs to learn how to move a file via GitHub’s web interface.
   • Copy file – can simply download pages-deploy.yml to your local machine and then upload it to starter directory.
4. Don’t forget to write a valid commit according to commitlint rules, for example: fix: move pages-deploy.yml to workflows directory
5. You’ll notice that our commit failed – that’s because our website is missing critical files that need to be compiled by us. This is mentioned in Chirpy’s FAQ, although it may not be super clear to non-Jekyll experts where exactly this part should be added or performed…

Adding npm Install & Build Stuff

1. Navigate to .github/workflows directory and open pages-deploy.yml.
2. Edit the file – the following lines should be added:

  - name: npm build
    run: npm install && npm run build

The new lines should be placed between the name: Setup Ruby and name: Build site blocks, as below:

  - name: Setup Ruby
    uses: ruby/setup-ruby@v1
    with:
      ruby-version: 3.3
      bundler-cache: true

  - name: npm build
    run: npm install && npm run build

  - name: Build site
    run: bundle exec jekyll b -d "_site${{ steps.pages.outputs.base_path }}"
    env:
      JEKYLL_ENV: "production"

Finally, commit the changes and don’t forget to write a valid commit message, for example: fix: adding npm compilation to pages-deploy.yml`

Checking Out Our Website

A few minutes after our last commit you should be able to see your new website proudly deployed to https://<username>.github.io!

The next step is to create a local development environment so you could start working on your website conveniently and efficiently. Chirpy’s documentation has a great section on that which you can follow-up on here. Good luck!