How to publish your content using GitHub Pages and Jekyll

github-pages-and-jekyll

GitHub, MIT, via Wikimedia Commons; Tom Preston-Werner, CC BY 4.0, via Wikimedia Commons; Photo by Ilya Pavlov on Unsplash

In this article, we are going to see how to use GitHub Pages and Jekyll to create a static web site or blog on Fedora. Whether you are a developer, administrator, or technical writer you can use GitHub pages and Jekyll to create your blog or site.

Understanding GitHub Pages and Jekyll

You can create public web pages using GitHub, These are called GitHub Pages. Jekyll is a ruby gem, that is used to create a static site. GitHub Pages team up well with Jekyll. You can use Jekyll to publish your static site or a blog. 

Prerequisites

Before installing Jekyll, perform the following commands:

  1. Install ruby and dependencies:
$ sudo dnf install ruby ruby-devel openssl-devel redhat-rpm-config @development-tools
$ sudo dnf install gcc-c++
$ sudo Gem install commonmarker -v ‘0.17.13’ --source ‘https://rubygems.org/’

2. Install bundler:

$ sudo gem install bundler

3. Initialize the bundle:

$ bundle init

4. Add parameter gem ‘unf_ext’ in Gemfile at the bottom of the file.

Setting up Git

Follow instructions here to install and set up git.

Creating your repository for your site

You must have your repository before creating your own site. Perform the following instructions to create your repository:

  1. Login to GitHub.
  2. Navigate and click ‘+‘.
  3. Select the account from the drop-down menu.
  4. Give a name to your repository. It must be in username.github.io format.
  5. Select Public or Private option.
  6. Click checkbox Add a README file.
  7. Click Create repository.

Creating your own site

Perform the following instructions to create your site:

  1. Create a folder to store your source files generated for your site.
$ mkdir my-jekyll-site

2. Change the directory to the newly created directory:

$ cd my-jekyll-site

3. Initialize the Git repository you created:

$ git init <username>.github.io

4. Add your repository as a remote:

$ git remote add origin https://github.com/username/repository.git

5. Change the directory to your repository name:

$ cd your-repo-name

6. Create publishing source and change the directory to the publishing source:

$ mkdir publishing-source
$ cd publishing-source

7. Create Jekyll site:

$ jekyll new --skip-bundle .

8. Open Gemfile that Jekyll created.

9. Comment out the line starting with gem “jekyll” by adding # at the start of the line.

10. Edit the line starting with # gem "github-pages" as follows.

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

GITHUB-PAGES-VERSION is the latest version of the github-pages gem.

11. Save the changes and close the Gemfile.

12. Run the following command:

$ bundle install

13. Open and edit _config.yml with the following parameters:

domain: my-site.github.io       # if you want to force HTTPS, specify the domain without the http at the start, e.g. example.com
url: https://my-site.github.io  # the base hostname and protocol for your site, e.g. http://example.com
baseurl: /REPOSITORY-NAME/      # place folder name if the site is served in a subfolder

14. Example _config.yml file:

title: Getting Started with Owncloud
email: sdudhgao@redhat.com
description: >- # this means to ignore newlines until "baseurl:"
  Owncloud is an open-source file sync, share and content collaboration software that lets teams work on data easily from anywhere, on any device. It provides access to your data through a web interface while providing a platform to view, sync and share across devices easily.


baseurl: "" # the subpath of your site, e.g. /blog
url: "https://xenolinux.github.io/" # the base hostname & protocol for your site, e.g. http://example.com
twitter_username: jekyllrb
github_username: jekyll

# Build settings
theme: minima
plugins:
  - jekyll-feed
  - jekyll-titles-from-headings
titles_from_headings:
  enabled:     true
  strip_title: true
  collections: true

15. Add your file and commit the changes you made.

$ git add .
$ git commit -m "commit changes"

16. Push the changes.

$ git push -u origin <branch>

Replace your branch name with <branch>

Setting a publishing source for your site

  1. Navigate to your site’s repository and click Settings –> Pages.
  2. Navigate to GitHub Pages and select None or Branch from the drop-down menu list.
  3. Click Save.

Your site is published!

Here is the site and repository example:

Jekyll Site: https://xenolinux.github.io/Quickstart.html
Repository: https://github.com/xenolinux/xenolinux.github.io

Fedora Project community

11 Comments

  1. Jasper Vinkenvleugel

    It might be useful to know that this can also easily be done with GitLab, if you want to use an open source alternative. Check out GitLab Pages: https://docs.gitlab.com/ee/user/project/pages/

  2. Anon Ymous

    I was looking at Hugo, which by several measures seems to be far superior to Jekyll. If anyone is familiar with both, can you pls point out what im missing.. i.e what are any advantages Jekyll has over Hugo? Nowadays so much seems to have a severe case of over engineering. Something as simple as a static site generator should be super easy to use and learn, its funny that there is actually a rather huge learning curve for most static site generators… so much so it is often easier to hand code the html and css.

    • John Smith

      I agree that it is funny that some static generators are difficult to learn. The way around it is to use just something like AsciiDoctor (which is also written in Ruby) to make extremely nice websites which look great on all sorts of different screensizes: https://asciidoctor.org/ , although AsciiDoctor can also be combined with Jekyl.

      I am always happy to see Ruby-based software; Ruby is such a fantastically easy to learn scripting language (in comparison to the more clunky Python)

    • Z

      I am familiar with a lot of static site generators and when comparing generators for beginners I don’t see why Jekyll is still recommended. Hugo by all means is far superior but is a lot newer. Jekyll has been around since 2008 compared to Hugo which was released in 2013 and didn’t has as many features then. Hugo has outgrown Jekyll by a lot now but there is still many people familiar with Jekyll and with experience find it easier to use than Hugo.

      I would always recommend hugo over jekyll to beginners but there is cases where jekyll still makes sense. However for anyone with a bit of experience I recommend you look into Eleventy. its a more traditional static site approach like hugo and jekyll but is similar in power to frameworks like next.js. There is a learning curve but once you get past that, it will be a breeze to use. I am currently using it to make an serverless eshop for my business and sites like google developers are created using it.

    • Kedar Bahulkar

      Hugo
      – Single installation package (slight advantage).
      – There is no bundling step in Hugo. Simply refer your config.toml to the theme, and you’re ready to go.
      – There is only one content directory in Hugo.
      – Hugo does not yet have a plugin API, so adding that kind of functionality will be more difficult.
      – Hugo supports TOML and JSON markdown in content files (supporting SASS and SCSS might require some additional setup)

      hugo new site my-awesome-site

      command only generates the folder structure and an archetype file.
      – Blogs with thousands of entries or a large number of images will create HTML more quickly (because of the Go language’s emphasis on concurrency, the speed difference is noticeable even at low page counts, but it becomes significant if you’re building a hundred pages of content)
      – Hugo’s speed and features will make your development process go more smoothly if you plan on writing a lot of content.
      – Hugo themes may be found at themes.gohugo.io

      Jekyll
      – RubyGems way of installing necessitates the presence of a properly installed and configured Ruby environment on your machine.
      – To ensure that the theme is handled with the site in Jekyll, there is an additional step of using RubyGems’ bundle.
      – In Jekyll, you have separate _drafts and _posts directories for storing your work in progress and your completed content pages, respectively.
      – Because of its plugin API, Jekyll presently leads in terms of extensibility. One can easily add functionality to your Jekyll-generated site like pieces of code, snippets, gifs, images, etc. – Jekyll offers support for CoffeeScript and SASS/SCSS.

      jekyll new my-awesome-site

      command installs a basic theme.
      – When you first start, it’s easy to use, but once you’ve processed a few hundred pages, it can get slow.
      – Jekyll themes can be found at jekyllthemes.org.

  3. Can

    Its much more easier with jekyll docker image.

  4. Sofia

    Sorry for the basic question but I remember reading a post about Pelican here. Is Jekyll superior to Pelican? If anyone is familiar with both, please share your thoughts.

  5. Jaap

    this command
    sudo Gem install commonmarker -v ‘0.17.13’ –source ‘https://rubygems.org/’
    does not work for me.
    error message: sudo: Gem: command not found

  6. Jaap

    When I do sudo gem (without capital)
    sudo gem install commonmarker -v ‘0.17.13’ –source ‘https://rubygems.org/’
    ERROR: While executing gem … (Gem::Requirement::BadRequirementError)
    Illformed requirement [“‘0.17.13’”]

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

The opinions expressed on this website are those of each author, not of the author's employer or of Red Hat. Fedora Magazine aspires to publish all content under a Creative Commons license but may not be able to do so in all cases. You are responsible for ensuring that you have the necessary permission to reuse any work on this site. The Fedora logo is a trademark of Red Hat, Inc. Terms and Conditions

%d bloggers like this: