Introducing Jekyll Framework with Lanyon Theme

#ruby   #jekyll   #html   #css

Jekyll is a blog-aware static site generator in Ruby. Official documentation you may find there: Jekyll. It is easy to host on GitHub Pages for free. The inbuild option of GitHub Pages is assortment of few simple Jekyll themes. There is a few free Jekyll themes on the internet.

Going through many themes I found the best for me - Lanyon theme. Very simle, minimalistic and elegant. Fallen in love from the first sight. The representative version of theme you may find there: lanyon blog, and find its GitHub there: Lanyon GitHub.

Contents:
1. Set up Ruby environment and run blog,
2. Blog deployment on GitHub Pages.

1. Launching Lanyon Jekyll theme in Ruby on local server

1.1. Ruby installation

Having in mind future blog deployment on GitHub Pages, go on GitHub Pages website where current versions of libraries may be seen, which are dependencies of GitHub Pages.

Pay attention particularly to Ruby version (2.5.3 while writing this text), and jekyll version (3.8.5).

Go on Ruby page and download “Ruby+Devkit Installer” which match Ruby version from GitHub Pages, for example 2.5.3. We may choose x64 or x86 version. I have choosen x86 version, which worked for me.

After simple installation process (tips there), click on windows reading glass, and type “ruby”, and you should see some app called like a “Start Command Prompt with Ruby”.

After installation:

• check ruby version C:\user> ruby -v
  
• check if gem is installed C:\user> gem -v Gem is a package manager for Ruby, something like pip for Python.
  
• install jekyll C:\user> gem install jekyll bundler
  
• check Jekyll version C:\user> jekyll -v
  Remember GitHub Pages dependencies checkup? If version not match reinstall it:
• uninstall jekyll C:\user> gem uninstall Jekyll
• install proper version C:\user> gem install jekyll -v 3.8.5

1.2. Downloading repository with Lanyon Jekyll theme

You may download repository from GitHub manually, or using git bash. You may found it there.

When you finally install it, click on windows reading glass, and type “git bash”.

After running this application, move to the proper place when you want to download repository, by typing $ cd path/where/you/want/download

And then run git clone with link to GitHub repository, which you may find after click on “Clone or download” button on proper git repository webpage.
$ git clone https://github.com/poole/lanyon.git

1.3. Run blog on local server

• go to Ruby prompt
  
• in Ruby prompt go to the root folder with your Lanyon blog downloaded from github C:\user> cd 'path/to/local/blog/root-folder'
  
• run blog on local server C:\user> jekyll server --watch
  

On the screen of your Ruby console you should see information, under which local adress you may run blog. It may looks like that:
http://127.0.0.1:4000/

• Copy your adress from console, and paste to google chrome, or whatever internet browser you use.

Et voilà !

Edit files from your blog catalog, and see changes showing on new page. During this process console is blocked, and you may see there informations about changes done to files, if you do so.

1.4. Debuging process

During this work, it may occurs many bugs including:

Dependency Error

After running C:\user> jekyll server --watch there may occur an error which suggest that you do not have jekyll-paginate:

Solution:

• Install jekyll-paginate C:\user> gem install jekyll-paginate
  
  

Deprecation

After running C:\user> jekyll server --watch the message may be shown:

Solution:

• go to _cofig.yml file
  
• paste to the file additional code below

plugins:
  - jekyll-paginate
paginate: 5

2. Deploying Jekyll blog on GitHub Pages

2.1. Deployment

To deploy blog on GitHub Pages you need first to:

• create empty repository on github.
• upload files manually or with git command line (instructions you may find there.)
• go to repository settings, scroll down to “GitHub Pages” section, below “Source” you may set “master branch”.
• after refreshing page, link to jekyll blog should appear in the repository settings in “GitHub Pages” section

2.2. Debuding process

Baseurl issue

Text is visible, but with no nice formatting - probably css styles are not active.

Solution:

• open _config.yml file, which should be located in the root catalog.
• change baseurl parameter to ‘/name_of_your_gh_repo’. While running blog locally, this pool may be empty, but on GitHub Pages it need to be specified like above.

Broken links

Toggle bar other “About”-like sections links don’t work.

Solution:

• go to _includes catalog to sidebar.html file

• change code below:

<a class="sidebar-nav-item{% if page.url == node.url %} 
active{% endif %}" href="{{ node.url }}">{{ node.title }}</a>

to code below:

<a class="sidebar-nav-item{% if page.url == node.url %} 
active{% endif %}" href="{{site.baseurl}}{{ node.url }}">{{ node.title }}</a>

Annotation