Preparing a GitHub repository to host a Jekyll website

In the previous post, I showed how to create a GitHub repository to be used as backing storage for a site hosted on GitHub Pages.
In this post, I will show the (few) steps needed to prepare the repository to work locally.

I will be using the new GitHub CLI and I assume that it’s already installed and properly configured.

Cloning the repository

The first step is to clone the repository on our computer. When cloning a repository, a remote is automatically created, so that we can push our changes to the remote server.

PS> gh repo clone kralizek.github.io MySite

Let’s analyize this command piece by piece:

• gh is the command used to invoke the GitHub CLI.
• repo clone is the command used to clone a repository
• kralizek.github.io is the repository I want to clone.
• MySite is the folder I want the repository to be cloned into. If it doesn’t exist, the CLI will create one for me.

You will notice I am not using the full identifier of the repository. This is because the CLI defaults to the user’s repositories if no user is specified.

Alternatively, I could have written:

PS> gh repo clone Kralizek/kralizek.github.io MySite

Once the repository is cloned, we can get into the folder containing it:

PS> cd MySite

If you followed the instructions of the previous post, the directory should contain only two files:

• the dummy index.html file used as a temporary front page,
• the CNAME file containing the custom domain used for the web site.

Git dotfiles

The next step is adding the proper dorfiles to configure git. This is especially important when working in a mixed environment with both Windows and Linux like when using Developer Containers.

.gitattributes

The .gitattributes file is used to configure how git tools should interpret files matching a certain set of paths.

In this case, the important part is instructing git about line endings. Since Windows and Linux use two differnt standards, working from a Linux and a Windows machine might create confusion and unnecessary commits.

Here is what I have set up for this site:

* text=auto eol=lf
*.{cmd,[cC][mM][dD]} text eol=crlf
*.{bat,[bB][aA][tT]} text eol=crlf

As explained before, each row sets certain settings for files matching the pattern specified at the beginning of the row.
Rows are processed top to bottom, for each file, the latest match wins over the previous ones.

The first row specifies that all files should be treated as text files by default and the Linux line ending strategy (lf) should be used.

The second and the third rows specify that files whose extension is either .cmd or .bat, regardless of the casing, should be treated as text files whose line ending is following the Windows strategy (crlf).

.gitignore

The next one to add is the .gitignore file: this file is used to specify files that git should not track. Typically it’s used to ignore build artifacts and personal customizations.

Here is the content of the .gitignore file for the repository backing this website.

_site
.sass-cache
.jekyll-cache
.jekyll-metadata
vendor

Each row represents a folder that git commands will ignore.

Here is a quick explaination of these rows

• _site is the folder that will contain the artifacts created by Jekyll’s build chain
• .jekyll-cache and .jekyll-metadata are used by Jekyll’s build chain
• .sass-cache are used by the SASS compiler
• vendor is a folder that contains different utilities by third-party tools

Pushing the changes

Once we have created these two files locally, we need to push them to GitHub.

This can be done with the following commands

PS> git add .
PS> git commit -m "Added dotfiles"
PS> git push

These three commands do the following:

• All modified or new files are added to the staging area
• All files in the staging area are committed with the specified message
• All pending commits are pushed to the default remote branch (typically origin/master)

Recap

In this post we have cloned the repository that will back our website, configured so that it can work in a Windows/Linux mixed environment and made sure build artifacts are ignored when working with git.

In the next post, we will configure Visual Studio Code so that we can use it as the editor for our Jekyll-based website.

Support this blog

If you liked this article, consider supporting this blog by buying me a pizza!