GitHub Pages is a great way to create a free static website. Jekyll is a popular static site generator that can be used with GitHub Pages to create a beautiful and responsive website in just a few minutes.

In this guide, we’ll show you how to use GitHub Pages with the Beautiful Jekyll theme.

Introduction to GitHub Pages

GitHub Pages is a free service that allows you to create a website to showcase your projects, documentation, and more. You can create a website for yourself, your organization, or your project. You can also create a website for your GitHub Pages repository.

Part 1: Fork the Beautiful Jekyll Theme

Jekyll is a static site generator, which means that it converts your Markdown files into HTML files. Static sites are fast, secure, and easy to deploy. Jekyll is a popular choice for creating blogs, personal websites, and documentation sites.

In a browser, login to your GitHub account.
Go to the Beautiful Jekyll GitHub page and click on the Fork button in the top right corner of the screen. This will create a copy of the theme in your GitHub account.

Beautiful Jekyll is a popular Jekyll theme that is easy to customize. There are many other Jekyll themes that you can use to create your website. You can find a list of Jekyll themes on the Jekyll Themes website.
Rename the repository “<GitHub username>.github.io” using your GitHub username. Naming it this way will allow GitHub to automatically create a website for you.
Click on the Create fork button to create your forked repository.
Click on the Settings tab of your repository. Click on the Pages tab. In the Source drop-down menu, select Deploy from a branch. In the Branch drop-down menu, select main.

GitHub Pages will automatically build and deploy your website from the main branch of your repository. If you want to use a different branch, you can select it from the Branch drop-down menu.
Click Save.

Part 2: Clone the Repository to Your Local Machine

Cloning a repository downloads a copy of the repository to the folder in your computer, which allows you to work on your website locally and then push your changes to GitHub when you are ready.

Follow the instructions in the Git lab to configure Git.

In your Terminal, navigate to the directory where you want to store your website files and clone the repository to your local machine.

 export GITHUB_USERNAME=<GitHub username> # temporarily set the GITHUB_USERNAME environment variable to your GitHub username

 git clone https://github.com/$GITHUB_USERNAME/$GITHUB_USERNAME.github.io.git # clone the repository to your local machine
 cd $GITHUB_USERNAME.github.io # change to the root directory of the repository
 export GITHUB_PAGES_DIR=$(pwd) # temporarily set the GITHUB_PAGES_DIR environment variable to the current directory

Create and switch to a new branch called new-gh-pages to work on your website.
```
 git checkout -b new-gh-pages
```

Part 3: Customize the Theme

The _config.yml file contains all of the settings for the website. Open the _config.yml file with an IDE or text editor and modify the title of your website and other settings.

To open the _config.yml file in VS Code, run the following command:
```
code _config.yml
```
The index.md file is the homepage of your website and includes content such as text, images, and links. Open the index.md file with an IDE or text editor and modify the content of the homepage.
For more information on how to customize the theme, check out the Beautiful Jekyll documentation and README file.
- _data: This directory contains YAML files that can be used to store data for your website.
- _includes: This directory contains HTML snippets that can be included in your pages.
- _layouts: This directory contains the page layouts for your website.
- _posts: This directory contains your blog posts. Blog posts should be named in the format YYYY-MM-DD-title.md.
- assets: This directory contains all of your website’s assets, including images, stylesheets, and Javascript files.
- _config.yml: This file contains all of the settings for your website.
- index.md: This file is the homepage of your website.

Part 4: Push Your Changes to GitHub

In Terminal, add all of your changes to the staging area.
```
git add .
```
Commit your changes with a message describing the changes you made.
```
git commit -m "Customizes the default Jekyll theme"
```
Push your changes to GitHub.
```
git push
```
In your browser, go to your repository on GitHub and click on the Pull requests tab.
Click on the New pull request button.
Write a title and description for your pull request. Click on the Create pull request button.

Jekyll may automatically check your pull request for errors. This process may take a few minutes.
Click on the Merge pull request button. Click on the Confirm merge button. The changes you made to your website will be merged into the master branch of your repository.
Click on the Delete branch button to delete the branch you created to work on your website.

GitHub Actions will automatically build and deploy your website, but it may take a few minutes for your website to be live.
In Terminal, open your website in your browser.
```
open https://$GITHUB_USERNAME.github.io
```
The open command is only available on macOS.

Review your website to make sure that it looks the way you want it to.

In Terminal, switch back to the master branch and pull the changes from GitHub.

git checkout master # switch to the master branch
git pull # pull the changes from GitHub
git branch -d new-gh-pages # delete the branch you created to work on your website

Local Jekyll Development

Pushing your changes to GitHub will automatically build and deploy your website, but it may take a few minutes for your website to be live. Also, if you want to test changes you make to your website locally before pushing them to GitHub, you will need to install Jekyll on your local machine.

Part 1: Ignore Local Build Folders

Open the _config.yml file. Under the exclude section, add the following line to exclude the _site and vendor directories from your repository.

The _site and vendor directories contain files that are generated by Jekyll and will interfere with the build process if they are included in your repository.
```
# Exclude these files from production site
exclude:
- CHANGELOG.md
- CNAME
- Gemfile
- Gemfile.lock
- LICENSE
- README.md
- screenshot.png
- docs/
- _site/
- vendor/
```
In Terminal, ensure that you are in the root directory of your repository. Add vendor/ and _site to .gitignore.
```
cd $GITHUB_PAGES_DIR
echo "vendor/" >> .gitignore
echo "_site/" >> .gitignore
```
You should ignore local build folders in .gitignore because they are usually large and contain files that are specific to your local development environment. When you push your code to a remote repository, you don’t want to include these files because they will not be necessary for other developers to build and run your application.
Also, you generally should ignore files that should not be public such as sensitive configuration files and private keys.

Part 2: Install Jekyll Locally

From the root directory, install Jekyll and its dependencies listed in the beautiful-jekyll-theme.gemspec file into a testing bundle.
```
bundle install --path vendor/bundle
```
You should always use a testing bundle, especially when you work on a project with other developers because it allows you to specify the exact versions of the dependencies that you are using.
This will prevent issues that may arise from using different versions of the dependencies and will make it easier to debug issues. It also allows you to install dependencies locally without having to install them globally on your computer, which may cause conflicts with other projects.
When you install dependencies globally, the dependencies are installed in the /usr/local/lib/ruby/gems/2.6.0 directory. When you install dependencies with a testing bundle, the dependencies are installed in the project’s specified directory, which in this case is the /vendor/bundle/ directory.
Build and serve your website locally.
```
bundle exec vendor/bundle/ruby/2.6.0/bin/jekyll serve --livereload
```
If the above command does not work, verify the path to the Jekyll executable. The path may be different depending on your operating system and version of Ruby.

Ruby is a programming language that is used to build Jekyll. It is installed by default on macOS and Linux, but you may need to install it on Windows. Although we use the system Ruby in this guide, it is recommended that you to install a separate version of Ruby. However, Ruby is notoriously difficult to install and manage, which is why we opted to use the system Ruby in this guide.
In the next section, we will show you how to use Docker to run Jekyll in a container, which will allow you to run Jekyll without having to install Ruby on your local machine.
In your browser, go to http://localhost:4000 to view your website.
Close the Jekyll server by pressing Ctrl+C in your Terminal.
Remove the _site and vendor directories.
```
rm -rf _site/ vendor/
```

Jekyll in a Docker Container

Docker is a containerization platform that allows you to package your application and its dependencies into a single image.This makes it easy to deploy your application to any environment that supports Docker.

A Jekyll Docker container is a software image that has Jekyll and many of its dependencies ready to use for you in an encapsulated format. This makes it easy to run your Jekyll site locally without having to install any Jekyll dependencies on your machine.

Part 1: Build and Run a Jekyll Docker Container

Build and run a Jekyll Docker container.
```
docker run --detach `# run in background` \
    --rm `# remove container when it exits, optional` \
    --name jekyll `# name the container` \
    --env JEKYLL_ENV=docker `# set the JEKYLL_ENV environment variable to docker` \
    --publish 4000:4000 `# publish port 4000 for serving the site, this can be changed to any available port` \
    --publish 35729:35729 `# publish port 35729 for live reloading` \
    --volume "$GITHUB_PAGES_DIR":/srv/jekyll `# mount the GitHub Pages directory to the /srv/jekyll directory in the container` \
    --restart unless-stopped `# restart unless stopped manually` \
    jekyll/jekyll:latest `# image name` \
    jekyll serve --livereload `# start the Jekyll server with the --livereload option`
```
The --livereload option will automatically refresh your browser when you make changes to your website. There are other options that you can use to customize your build process.
You can use the --watch option to rebuild your website when you make changes to your website. You can instead use the --incremental option to rebuild only the files that have changed, but this option does not always rebuild edited content that is referenced by other files. The --force_polling option will force Jekyll to use polling instead of the default native file system events. By default, Jekyll uses port 4000, but you can specify a different port with the --port option.
By default, Jekyll uses the _site directory to store the generated website files, but you can specify a different directory with the --destination option.
By default, Jekyll uses the _config.yml file to store the configuration settings, but you can specify a different configuration file with the --config option.
By default, Jekyll is only accessible from your local machine, but you can make it accessible from other devices on your network by specifying your network IP address with the --host option.
By default, JEKYLL_ENV is set to “development” in Docker and “production” in GitHub Pages, but you can set it to any value with the --env option. Setting it to “development” causes Jekyll some issues when building the site, so I recommend setting it to “docker” instead.
Repeat step 27 to view your website.

If you are using Docker Desktop, you can also go to http://host.docker.internal:4000 to view your website.

If you are having trouble running your Jekyll site in a Docker container, you can check the Docker logs for more information.
```
docker logs jekyll
```

Part 2: Test Your Website with Live Reload

Repeat step 9 but with a branch name of “docker-gh-pages”.
Edit the post at _posts/2020-02-28-sample-markdown.md. Save your changes.
Notice that the Jekyll server automatically rebuilds your website and refreshes your browser.

Live reload does not work for changes to the _config.yml file. You will need to restart the Jekyll server for changes to the _config.yml file to take effect.

You can then add conditional statements to your HTML files to conditionally include or exclude content based on the environment. Edit the head file at __includes/head.html to only include the analytics code if the environment is production.

{% if jekyll.environment == "production" %}
    // analytics code
    {% include gtag.html %}
    {% include gtm_head.html %}
    {% include google_analytics.html %}
    {% include cloudflare_analytics.html %}
{% endif %}

Save your changes.

After completing your changes and are ready to push your changes to GitHub, repeat steps 13 to 22 to merge your changes into the master branch of your repository.
In Terminal, stop the Jekyll server.
```
docker stop jekyll
```
If you used the --rm option when you ran the Jekyll container, you do not need to remove the container manually. Stopping the container will automatically remove it.
Repeat step 29 to remove the _site and vendor directories.

GitHub Pages

free github-hosted personal website