Prerequisites

  1. Install Git
  2. Install Ruby
  3. Install Bundler

Create a new public repository

Name the repository

  • For user or organization site named “username.github.io”.
  • For project site named in accordance with naming conventions.

Example:

user name or project repository name
whyen-wang whyen-wang.github.io
Nonie Nonie

Creating your site

git clone https://github.com/username/username.github.io
# or
git clone https://github.com/username/project.git

cd username.github.io
# or
cd project

mkdir docs
# creates a new folder called docs
cd docs

# create a new Jekyll site
jekyll new --skip-bundle .

Modify the configuration

  • Go to Gemfile
# Add "#" to the beginning of the line that starts with gem "jekyll"

# gem "jekyll" ... <- comment out this line


# Edit the line that starts with # gem "github-pages"

gem "github-pages", "~> GITHUB-PAGES-VERSION", group: :jekyll_plugins
# gem "github-pages"

Replace GITHUB-PAGES-VERSION with the latest supported version of the github-pages gem. You can find this version here: “Dependency versions.” ex. 231 Save and close the Gemfile.

  • Go to _config.yml
domain: my-site.github.io  # ex.whyen-wang.github.io

url: https://my-site.github.io  # ex. https://whyen-wang.github.io

baseurl: /REPOSITORY-NAME/  # ex. leave "" for user site and project name for project site ex. /Nonie/

Testing your GitHub Pages site locally with Jekyll

  • Install dependencies
bundle install
  • Run your Jekyll site locally.
Run your Jekyll site locally.

go to http://127.0.0.1:4000/ to preview your site.

Add, commit and push your work

git add .
git commit -m 'Initial GitHub pages site with Jekyll'
git push

Configure your publishing source.

  1. Go to repository settings
  2. Go to “Code and automation” > “Pages” > “Branch”
  3. Select the branch you pushed and select folder “/docs” and save

Deploy the site

  1. Go to repository actions
  2. Wait for the workflow run finished
  3. Once the workflow finished, go to “Settings” > “Code and automation” > “Pages” > “GitHub Pages” > “Visit site”
  4. Done!

References

GitHub Docs - GitHub Pages