Setting up Jekyll (Part I) – including Flattr integration, comments etc.
»jekyll«
Blogging, Jekyll, Flattr
Having fun with Jekyll
As already announced in the first post I will explain a few key points on setting up Jekyll today. Pleaser refer to the »technical aspects« of my blog if you don’t have a clue what I’m talking about. Part I of the »Jekyll Setup post« contains information about installing Jekyll, including Flattr, adding comments, tweaking the site navigation and improving syntax highlighting within your blog posts. Part II will take care of GitHub specific stuff (Hosting, Plugins, etc.).
Install Jekyll
Jekyll is written in Ruby. So you need to have Ruby installed on your machine which is the case on Mac OS X by default. You just have to fire up your terminal and type the following to install Jekyll globally:
gem install jekyll
If your are using the default Ruby on OS X you will probably get the following error message:
ERROR: While executing gem ... (Gem::FilePermissionError)
You don't have write permissions for the /Library/Ruby/Gems/2.0.0 directory.
You can easily fix that by executing the same command using superuser privileges via:
sudo gem install jekyll
Local installation including default theme
The default theme is a clean and responsive one column layout which adapts nicely down to your smart phone.
jekyll new my-awesome-site
cd my-awesome-site
This will create the directory my-awesome-site
and install all files needed for your blog which is ready to run from that moment on. But we are going to inspect the content of my-awesome-site
first.
.my-awesome-site
├── _config.yml // The main config file
├── _includes // Partials for your layouts
| ├── footer.html
| ├── head.html
| └── header.html
├── _layouts // Layouts for your pages
| ├── default.html
| ├── page.html
| └── post.html
├── _posts // Your posts
| └── 2014-09-07-welcome-to-jekyll.markdown
├── _sass // Sass includes
| ├── _base.scss // imported by main.scss
| ├── _layout.scss
| └── _syntax-highlighting.scss
├── about.md // A page
├── css // Main Sass file
| └── main.scss
├── feed.xml // Your feed
└── index.html // The homepage
See »Directory structure« on the Jekyll docs for details.
Checking the installation
jekyll serve
Will build your sources into the directory _site
and will start a server at http://localhost:4000
running you blog. See »Basic Usage« on the Jekyll docs for a complete list of available commands.
Important note:
Additional files in the root of your blog are copied o the root of _site
when the site is built.
Make use of Drafts
Create a directory called _drafts
in the root of your site. This is the place for writing your post before publishing them via the _posts
directory. Use the following command to build and serve your blog including the drafts.
jekyll serve --watch --drafts
--watch
watches for changes, and regenerates files automatically. This works for content as well as for Sass and JavaScript.
Hide specific pages from the navigation
You may wish to exclude pages from the menu at the top righ corner of your page. Especially if you live in Germany and have the need for all those annoying legal stuff.
No problem Just extend the so called »Front Matter« of pages you wish to include in the site navigation with an own custom variable.
Let’s take the »about« page about.md
for example and change the default front matter block from:
---
layout: page
title: About
permalink: /about/
---
to:
---
layout: page
title: About
permalink: /about/
menu: true
---
Change the rendering of the navigation
Open header.html
and replace
{% if page.title %}
<a class="page-link" href="{{ page.url | prepend: site.baseurl }}">
{{ page.title }}
</a>
{% endif %}
with
{% if page.menu == true %}
<a class="page-link" href="{{ page.url | prepend: site.baseurl }}">
{{ page.title }}
</a>
{% endif %}
Custom sorting of pages within the navigation
Jekyll sorts your menu items alphabetically without giving you a simple possibilty to change that. So we have to dig deep in our bag of tricks to accomplish such a basic desire.
Rename pages within your file system
Just prefix your pages with a numeric index. For example
index.html → 00-index.html
about.md → 01-about.md
Update the rendering of the navigation
You have to change some code within header.html
in addition to the renaming.
Before:
{% if page.menu == true %}
<a class="page-link" href="{{ page.url | prepend: site.baseurl }}">
{{ page.title }}
</a>
{% endif %}
After:
{% assign sorted_pages = site.pages | sort:"name" %}
{% for node in sorted_pages %}
{% if node.menu == true %}
<a class="page-link" href="{{ node.url | prepend: site.baseurl }}">
{{ node.title }}
</a>
{% endif %}
{% endfor %}
Enhance syntax highlighting in your blog posts
First off all we like to use the so called GitHub Flavored Markdown to make use of Fenced code blocks including the abbility to add languages to code blocks for language specific syntax highlighting. We need to add two lines to the build settings of _config.yml
to accomplish this.
Before:
# Build settings
markdown: kramdown
After:
# Build settings
markdown: kramdown
kramdown:
input: GFM
Now we can use:
```javascript
var foo = 'foo';
```
Instead of using these liquid tags
{% highlight javascript %}
var foo = 'foo';
{% endhighlight %}
Using the beautiful prism syntax highligter
- Go to http://prismjs.com/ and download Prism according to your needs (in terms of needed languages, plugins and a theme of your choice)
- Place
prism.js
in the/js
directory - Reference
/js/prism.js
from the bottom offooter.html
:<script src="/assets/js/prism.js"></script>
- Replace the content of
_syntax-highlighting.scss
with the content ofprism.css
That’s it.
Flattr Integration
Integrating Flattr on the pages containing your posts is pretty straight forward. First of all add a file called flattr.js
to your /js
directory.
Copy the following content into that file:
(function() {
var s = document.createElement('script');
var t = document.getElementsByTagName('script')[0];
s.type = 'text/javascript';
s.async = true;
s.src = '//api.flattr.com/js/0.6/load.js?mode=auto' +
'&uid=YourUserName' +
'&button=compact' +
'&html5-key-prefix=data-flattr';
t.parentNode.insertBefore(s, t);
})();
See Embedded buttons on the Flattr docs for further information.
Add and configure Flattr buttons on your posts
Open post.html
and add the following snippet wherever you like to place your Flattr button:
<a class="FlattrButton"
title="{{page.title}}"
data-flattr-tags="{{page.tags}}"
data-flattr-category="text"
data-flattr-language="{{page.lang}}"
href="{{site.url}}{{page.url}}">
{{page.excerpt}}
</a>
Make sure you’ve set page.lang
and page.excerpt
via »Front Matter« on top of your posting. See the following example of my first post 2014-09-07-welcome-to-jekyll.markdown
---
layout: post
lang: en_GB
title: "„Welcome“ aka „This is the first post on my blog“"
date: 2014-09-01 21:53:08
category: blogging
tags: "blogging, jekyll"
excerpt: "Teaser text …"
---
Now you’ve got Flattr buttons automatically add to all your post with the page excerpt on the Flattr page of your »thing«.
##Adding comments
If you like to have comments on a static blog generated by Jekyll you have to depend on a third party tool which appends comments with heavy use of JavaScript. Yes, there are alternatives to Disqus when it comes to comments. But I choose Disqus mainly because I already had an account and I had not time for checking out the other vendors.
Here we go with short explanation of adding comments provided by Disqus:
First of all you need to register a site add Disqus and add the URL of your website within the admin settings. I left the other settings pretty much untouched but you can go really wild over there.
Then you can add the following snippet to post.html
:
<div id="disqus_thread"></div>
<script type="text/javascript">
/* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */
var disqus_shortname = 'YourWebsitesShortname',
disqus_identifier = '{{page.disqusIdentifier}}',
disqus_title = '{{page.title}}',
disqus_url = '{{site.url}}{{page.url}}';
/* * * DON'T EDIT BELOW THIS LINE * * */
(function() {
var dsq = document.createElement('script');
dsq.type = 'text/javascript'; dsq.async = true;
dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
(document.getElementsByTagName('head')[0]
|| document.getElementsByTagName('body')[0]).appendChild(dsq);
})();
</script>
<noscript>Please enable JavaScript to view the comments</noscript>
See Setup Instructions from Disqus.
Make sure you’ve set page.disqusIdentifier
via »Front Matter« on top of your posting. See the following example of my first post 2014-09-07-welcome-to-jekyll.markdown
---
layout: post
lang: en_GB
title: "„Welcome“ aka „This is the first post on my blog“"
date: 2014-09-01 21:53:08
category: blogging
tags: "blogging, jekyll"
excerpt: "Teaser text …"
disqusIdentifier: 2014-09-01welcome-first-post
---
You could omit the use of the disqus_identifier
in the snippet as well as in the Front Matter. But I recommend using it, because you comments keep connected to the post when you decide to change your URL scheme. Or in the words of Disqus:
You’ll be able to reference the same thread regardless of the URL where it is loaded.
Bottom line
Setting up a blog powered by Jekyll is pretty easy. Your blog will be up and running in a couple of hours if you’re happy with the default theme. As mentioned before, there will be a follow up post regarding GitHub specific stuff (Hosting, Plugins, etc.). So please return after you have adjust the default theme according to your needs
Related posts
- How to flash ESP8266 (and ESP32) to use Espruino firmware on macOS
- Helpers and tips for npm run scripts
- JSConf Budapest 2017 – A personal recap
Comments
Comments are removed for now. Feel free to contact me via Twitter in case you’d like to talk about this blog post: @mkuehnel.