Creating site by github pages with jekyll

blog github-pages

This article is about creating a website by GitHub Pages with Jekyll.
Jekyll is a static site generator. GitHub Pages uses Jekyll by default to create and publish sites.

Environment

Windows 10 64-bit
Git for Windows 2.44.0
Ruby 3.2.3
Jekyll 4.3.3

Prerequisites

Git is installed.
You have a GitHub account.

Based on the following page:
Creating a GitHub Pages Site with Jekyll

1. Install Jekyll

For details on installing Jekyll, see here.

2. Create a site on GitHub Pages

For details on creating a GitHub Pages site, see here.

3. Clone the GitHub repository

You will use Jekyll to create the site.

Go to GitHub.
If you are not signed in, sign in.
Access the page of the repository you created.
Click “Code.”
Copy the URL for cloning.
Clone the GitHub repository.
Open Command Prompt or PowerShell and run the following:
Replace <directory path where to clone the repository> with your desired path, and
https://github.com/<username>/<repository>.git with the clone URL you copied.
```
> cd <directory path where to clone the repository>
> git clone https://github.com/<username>/<repository>.git
```

4. Create the site using Jekyll

Navigate to the repository directory.
Open Command Prompt or PowerShell and run:
```
> cd <path to the repository directory>
```
<path to the repository directory> is <directory where you cloned>/<repository name>.
Delete the README.md file.
If there is a README.md file in the root of the repository, delete it:
```
> git rm README.md
```
Create and move into the docs directory.
Create the directory where you’ll generate the site and navigate into it:
```
> mkdir docs
> cd docs
```
Create the site with Jekyll.
Generate a Jekyll site in the current directory (docs):
```
> jekyll new --skip-bundle .
```
Modify the Gemfile.
Open the generated Gemfile in a text editor and make the following changes:
Since GitHub Pages uses the github-pages gem, uncomment the following line:
```
gem "github-pages", group: :jekyll_plugins
```
Add a version constraint like this:
```
gem "github-pages", "~> <github-pages version>", group: :jekyll_plugins
```
Replace <github-pages version> with the version listed under Dependency versions.

Comment out the line that defines jekyll, as it is already included in github-pages:

#gem "jekyll", "~> <jekyll version>"

Modify _config.yml.
Open _config.yml in a text editor and update the following fields.
Comment out any fields you do not want to display on your site.

Field	Description
title	Enter your site’s title.
description	Enter a description for your site.
twitter_username	Enter your X (formerly Twitter) username.
github_username	Enter your GitHub username.

Install the gems.
To install the necessary gems, run:
```
> bundle install
```

5. Check the Site Locally

Start a local server.
Open Command Prompt or PowerShell and run the following:

> cd <path to the repository>/docs
> bundle add webrick # Run this if you are using Ruby 3.0 or later
> bundle exec jekyll serve

Access http://localhost:4000
The homepage will be displayed as shown below.
By default, the minima theme is used.
“Welcome to Jekyll!” is the page generated by the jekyll new command.

6. Commit and Push the Changes

Modify .gitignore
GitHub Pages does not install using Gemfile and Gemfile.lock.
So add the following lines to the generated .gitignore:
```
Gemfile
Gemfile.lock
```

Commit and push the changes.
Open Command Prompt or PowerShell and run the following:

> cd <path to the repository>
> git add docs/
> git commit -m "Add site created with Jekyll"
> git push origin main

7. Change the Repository Settings

Modify the repository settings.

Go to GitHub
Open the page for your created GitHub repository.
Click “Settings”
Click “Pages”
Under “Build and deployment,” change the root folder of the “Branch.”
Select /docs.