If you are a developer and are looking for a plug and play solution to start your own blog jekyll is a good alternative, and coupled with github you’ll be able to deploy and host it with no pain. jekyll-github-pages

/!\ This post was updated on Jul 30, 2019 and tested with these packages:

jekyll 3.8.6
ruby 2.6.3

Find an issue? please drop a line on comment, I'll fix it ASAP

Getting started

Install jekyll and libraries

$ gem install jekyll bundler

if you face a permission error like below, means you need to install a new version of ruby

You don’t have write permissions…

$ gem install jekyll
Fetching: liquid-3.0.6.gem (100%)
ERROR:  While executing gem ... (Gem::FilePermissionError)
    You don't have write permissions for the /Library/Ruby/Gems/2.0.0 directory.

That is the version of Ruby installed by Apple, for their own use. While it’s OK to make minor modifications, it’s not a good idea to continue along that track.

I’ll strongly suggest you look into using either rbenv or RVM to manage a separate Ruby, installed into a sandbox in your home directory, that you can modify/fold/spindle/change without worrying about messing up the system Ruby.

rbenv takes a more “hands-off” approach to managing your Ruby installation. RVM has a lot of features and is very powerful, but, as a result is more intrusive.

Source: http://stackoverflow.com/a/14607772/4982169

$ brew install rbenv
Verify that rbenv is properly set up using this rbenv-doctor script:
$ curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor | bash
$ rbenv install -l
$ ruby -v
ruby 2.3.7p456 (2018-03-28 revision 63024) [universal.x86_64-darwin18]
$ rbenv install 2.6.3
$ gem install jekyll bundler

Create your site

jekyll new my-awesome-site
~ $ cd my-awesome-site
~/my-awesome-site $ bundle exec jekyll serve

Tips’n Tricks

Add internal link in post

[previous post]({% post_url 2015-06-06-how-easily-create-mobile-app-phonegap %})

kramdown supports the automatic generation of header IDs if the option auto_ids is set to true (which is the default). This is done by converting the untransformed, i.e. plain, header text

So for ## Section 1, it would generate the following id: id="section-1", then in plain kramdown/markdown the anchor is linked to via:

[Section 1](#section-1)

Render Tables with kramdown

A line starting with a pipe character | starts a table row. However, if the pipe characters is immediately followed by a dash (-), a separator line is created

Source: http://kramdown.gettalong.org/quickref.html#tables

Line break

We should use the “secret” MD’s two-space line breaks. Digit two empty space and a break-line (enter).

Most Markdown engines I’ve seen allow plain HTML

<a href="http://example.com/" target="_blank">Hello, world!</a>

Source: http://stackoverflow.com/questions/4425198/markdown-target-blank

Writing Liquid Template in Markdown Code Blocks

When I was writing another blog post on listing blog posts by tags in Jekyll, I came across a curious problem when I try to write liquid template code in my markdown file. Evidently, when Jekyll compiles the static web files, it tries to process all the double curly brackets like {% and %}, which of course leads to errors.

One option is to use Liquid’s raw tag. Raw temporarily disables tag processing. The markdown code would then be something like this:

jekyll-raw-tag

Source

Code Highlighting: Embedded GitHub Gists

Improve Code Highlighting in a Jekyll-based Blog Site

Install gem jekyll-gist

$ gem install jekyll-gist

Add the following to your site’s _config.yml:

gems: [jekyll-gist]

Here’s an example of how to embed a Gist on GitHub Pages:

{% gist 5555251 %}

All you need to do is copy and paste the Gist’s ID from the URL (here 5555251), and add it to a gist tag surrounded by {% and %}.

JS hook

Add following snippet on /assets/js/app.js, all links on posts will open on new window. It includes internal links.

// prevent line-breaks in links and make open in new tab
$('div.article_body a')
	.not('[rel="footnote"], [rev="footnote"]')
	.html(function(i, str) {
		return str.replace(/ /g,'&nbsp;');
	})
	.attr('target','_blank');

Source: http://mrloh.se/2015/05/bending-markdown-for-jekyll-and-github-pages/

Comment

Kramdown comment syntax

{::comment}
 here's my comment
{:/comment}

Jekyll Themes

Furthermore


Victor Dias

Sharing mobile Experiences

Follow me