This tutorial covers how to use Jekyll and GitHub Pages to host a free blog like this one. Bash commands are applicable to macOS Sierra version 10.12.4.
By default git is not installed in macOS Sierra. The Xcode command line tools can be installed or you can install Git directly from a git mirror. The advantage of installing it from the mirror is Xcode lags behind the most up to date git version. Download and install the newest git version from the link below.
Newer versions of macOS have a security protocol that causes some issues installing programs from unidentified developers and location of the install. Run the PKG file downloaded from Sourceforge and macOS will not install.
The workaround is to open computer Settings, go to Security & Privacy, and Click the lock to make changes. Once OK is clicked on the below menu the Security & Privacy window updates with an Open Anyway option. Now proceed through the git install with the default location.
At the Terminal now type
which git. If it returns
/usr/bin/git it need to be changed to
/usr/local/bin/git instead. To do this the
$PATH variable needs to have the latter path before the first. Either edit or add this line to your
~/.bash_profile file in your home directory using the terminal commands below.
Add this line which concatenates the local path to the very beginning of
Now exit nano using
^X and make sure it is saved by pressing
Y. Restart Terminal and type
which git now should return the git path being in the local directory.
Xcode Command Line Tools
The Xcode command line tools also must be installed to install other things like Jekyll. Open the terminal and type the following. A new series of dialogs will pop up, just follow the prompts to install.
Jekyll can be installed using Rubygems but macOS Sierra has new security features not allowing installs in default gem install location. This can be worked around by providing an install path as the last option when installing. Bundle needs to be installed first then Jekyll.
gem install bundle /usr/local/bin gem install jekyll /usr/local/bin
Go to GitHub and create a new repository and do not initialize a README file. On the next page copy the link to your repository and clone it locally. This will create an empty directory in the Documents called
cd ~/Documents git clone https://github.com/aricbeaver/tutorial.git
Now go to the settings of your repository and change the GitHub Pages to use the master branch. Alternatively, you can create a new branch called
gh-pages and GitHub will automatically assume it is a Pages branch.
Create Jekyll Blog
Creating a Jekyll Blog is very easy.
cd ~/Documents jekyll new tutorial cd tutorial jekyll serve
By default Jekyll will serve port 4000 on
localhost so it can be access easily by typing the following into your browser’s address bar.
Now the initial Jekyll project will be deleted and a new one pulled from the Jekyll Clean Dark theme repository to be forked into my own custom blog.
cd ~/Documents rm -rf tutorial/ git clone https://github.com/aricbeaver/tutorial.git cd tutorial git pull https://github.com/streetturtle/jekyll-clean-dark.git git push -u origin master
_config.yml needs to be edited to get the theme fully functional. The
baseurl need to be updated.
url: https://<insert_your_github_username>.github.io baseurl: ''
Now add, commit, and push the files to GitHub.
cd ~/Documents/tutorial git add . git status # Not required but shows commit queue git commit -m 'modified configuration to work with GitHub Pages' git push
Accessing the blog at https://insert_your_github_username.github.io/tutorial/ should show the dark theme’s example blog.
To add posts just create a new file in the
_posts directory that uses the header format defined in the other example posts. Here is an example of this blog post. Be careful to not use a date that is in the future or it will not render that page when using Jekyll serve.
--- layout: post title: "Jekyll and Github Pages Blog Setup" date: 2017-04-30 01:50:00 description: Tutorial on how this blog was setup. tags: - blog - code --- # Preface This tutorial covers how to use Jekyll and GitHub Pages to host a free blog like this one. Bash commands are applicable to macOS Sierra version 10.12.4. # Installs ## Git By default git is not installed in macOS Sierra. The Xcode command line tools can be installed or you can install Git directly from a git mirror. The advantage of installing it from the mirror is Xcode lags behind the most up to date git version. Download and install the newest git version from the link below.
- A custom domain name can be created by purchasing your domain and setting this up in GitHub Pages settings. There are instructions on GitHub on this process.
- If a custom domain name is used HTTPS is not possible through GitHub Pages settings but Cloudflare can be used to set this up. There are instructions on a few other blogs about this.