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.
Before installing Jekyll, perform the following commands:
- 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:
- Login to GitHub.
- Navigate and click ‘+‘.
- Select the account from the drop-down menu.
- Give a name to your repository. It must be in username.github.io format.
- Select Public or Private option.
- Click checkbox Add a README file.
- Click Create repository.
Creating your own site
Perform the following instructions to create your site:
- 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: email@example.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
- Navigate to your site’s repository and click Settings –> Pages.
- Navigate to GitHub Pages and select None or Branch from the drop-down menu list.
- Click Save.
Your site is published!
Here is the site and repository example:
Jekyll Site: https://xenolinux.github.io/Quickstart.html
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/
As someone who hates Microsoft with a burning passion, I am grateful to you dear random internet user.
You can also achieve a similar result with sourcehut pages, which IMO is also way easier to experiment with than GitLab or GitHub because it allows you to just curl a tarball to a URL. SourceHut is “100% free and open source software” and is funded by its users.
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.
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)
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.
– 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)
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
– 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.
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.
Its much more easier with jekyll docker image.
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.
sudo Gem install commonmarker -v ‘0.17.13’ –source ‘https://rubygems.org/’
does not work for me.
error message: sudo: Gem: command not found
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’”]