- Set up a GitHub Pages repository
- Set up a Jekyll and Jekyll project
- Choose and setup a themes
- Configure custom domain
- Add DISQUS comments
- Add Google Analytics
- Future steps
Prerequisites: GitHub account and Git client of your choice (instructions use command line git)
Set up a GutHub Pages repository
Go to https://pages.github.com/ and follow the guide for user/organization site or project site. I choose a user site. Assuming
git-username is your git username, create a new repository called
git-username.github.io in your GitHub account. If you have a payed account, you can choose a Private repo.
I’m going to use a command line Git client in
mkdir ~/work cd ~/work #the following line might differ based on your git setup preference git clone firstname.lastname@example.org:git-username/git-username.github.io.git cd git-username.github.io/ echo "hello from GitHub Pages" > index.html git add . git commit -m "added index.html" git push open https://git-username.github.io
At this point GitHub Pages is serving your static website from the master branch of your repository. If you’d like to evolve your website as static HTML site, this might be all that you need. You can also go to Configure DNS section if you want to serve your site under your custom domain.
If you choose to write your pages/posts in markdown and have GitHub Pages generate a website continue reading on setting up Jekyll.
Set up a Jekyll and Jekyll project
I choose to use Jekyll to handle my GitHub Pages website. This is for several reasons:
- I will write my posts in plain markdown and Jekyll will generate the website pages for me following a theme chosen by me
- GitHub Pages supports Jekyll internally, so that I push my
*.mdfiles only and it will be pure GitHub Pages generating website for me
- Jekyll/GitHub Pages support themes to choose from; internal and 3rd party
- Jekyll has a lot plugins; GitHub Pages supports only limited set of plugins for security reasons, but it does have support for
So roughly following this guide: https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/
ruby --version #should be 2.1.0 or higher, if not "brew install ruby" or https://www.ruby-lang.org/en/downloads/ gem install bundler #in the root directory of your local Jekyll site repository echo "source 'https://rubygems.org'" > Gemfile echo "gem 'github-pages', group: :jekyll_plugins" >> Gemfile bundle install #preserve GitHub Pages version of `Gemfile`, delete `index.html` example from section 1 cp Gemfile Gemfile.githubpages rm index.html bundle exec jekyll _3.3.0_ new . --force cp Gemfile Gemfile.jekyll mv Gemfile.githubpages Gemfile bundle exec jekyll serve
The last command will generate and start Jekyll site locally on port
4000. Open http://localhost:4000/ to see the your site locally before you push it to the GitHub repo and therefore publish it.
Notice one post
Welcome to Jekyll! that was generated by default.
While Jekyll is running locally you can make changes to your site and it will pick them up as soon as you save the file.
Note that the
Welcome to Jekyll!auto-generated post contains
date: 2018-03-19 18:17:35 -0400at the top of the markdown separated by
---. Avoid having time set there! The links to the posts contain dates. Depending on when the site is generated from markdown, the link can be
/2018/03/20/welcome-to-jekyll.html. Set the
dateto date only, like
2018-03-19without time and zone. Or even better remove it from your post header and and let the date of the post be deduced from the filename
2018-02-19-my-first-post.md. It’s a good idea to name you post files according to this default best practice anyways as it helps in sorting and organizing.
Global site configuration
In the root directory of you Jekyll site there’s a
_config.yml file that contains site-wide configuration, like title, owner’s email. It can also contain settings used by your theme or even custom variable that can be referred in the templates.
You definitely want to set your site’s
description used by all themes, your
url which you must set if you want to use
title: Your awesome title email: email@example.com description: Write an awesome description for your new site here. You can edit this line in _config.yml. It will appear in your document head meta (for Google search results) and in your feed.xml site description. baseurl: "" # the subpath of your site, e.g. /blog url: "https://git-username.github.io" # or your custom domain, e.g. http://your-name.com twitter_username: jekyllrb github_username: jekyll
Add a post in markdown
Make sure that you are in the root directory of your local Jekyll site repository and create a post as an
.md file using the following command or your favorite text editor:
#in the root directory of your local Jekyll site cat <<EOT >> _posts/2018-02-19-my-first-post.md --- layout: post title: "My first post" --- # My first awesome post How cool is that? - Use [Markdown!](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) - *Easy to create* as plain text - And **beautiful** when rendered as website - [Here's how we did it](http://www.novytskyy.com/2018/02/19/setting-up-a-blog-with-github-pages-and-jekyll.html "Setting up a blog with GitHub Pages and Jekyll") EOT
Don’t forget to push your changes to GitHub
Choose a themes
GitHub Pages supports official and third-party themes. They are applied in slightly different way.
- GitHub Pages Supported Themes https://pages.github.com/themes/
- A list of 3rd party themes on GitHub https://github.com/topics/jekyll-theme
Apply and configure a theme
So I’ve chosen the So Simple theme.
_config.yml in the root of you GitHub Pages Jekyll site to contain:
remote_theme: "mmistakes/so-simple-theme" author: name: Your Name twitter: twitter-username picture: /images/author.jpg
Put your author picture in
./images/author.jpg relative to the root folder,
So Simple theme will style it in a nice circle.
Additional setup for the
so-simple-theme can be found at https://github.com/mmistakes/so-simple-theme
Configure custom domain
You will need your domain name registered and have access to DNS configuration for it. Let’s assume your custom domain is
your-name.com and your GitHub Pages domain is
git-username.github.io (the one that you get anyways with GitHub Pages).
Go to your registrar’s DNS configuration for
your-name.com to do the following:
- add a record with type
git-username.github.ioas the value
- add a record with type
git-username.github.ioas the value
Add a file name
CNAME in the root of your site with your custom domain:
echo 'www.your-name.com' > CNAME
Git add / commit / push.
DNS changes may take time to propagate
Add DISQUS comments
Create a DISQUS account and set up your site in Disqus. In your site configuration in Disqus you are going to choose your website name that is going to be your
shortname. Also you need to enter your
Website URL that must match the domain name that you’ve chosen to serve your domain under. Otherwise Disqus will not initialize the comment section for security reasons.
Following current example I’m editing
_config.yml file in the root directory of your Jekyll site to contain and using
disqus-username as my
https://git-username.github.io as my
url that matches
Website URL configured in Disqus and the
domain under which the site will available:
url: "https://git-username.github.io" disqus: shortname: disqus-username
Add Google Analytics
If you are using
mmistakes/so-simple-theme theme, as I am, provides support for Google Analytics out of the box. Just add the following to your
- tags/labels on posts and listing
- investigate content section generated by headers
- customizing theme/css
- add LinkIn, Twitter, other buttons to follow an author and to share a post