loading...
Cover image for Jekyll stealth mode

Jekyll stealth mode

jmau111 profile image Julien Maury Originally published at blog.julien-maury.dev on ・4 min read

Lets Jekylling!

Why "Jekyll"?

First, read original blog post from Tom Preston-Werner. Then, the philosophy is excellent:

Jekyll does what you tell it to do — no more, no less. It doesn't try to outsmart users by making bold assumptions, nor does it burden them with needless complexity and configuration. Put simply, Jekyll gets out of your way and allows you to concentrate on what truly matters: your content.

It does what it says, nothing more, no unnecessary complexity. Nothing is perfect, but Jekyll is light and fun. I appreciate that. Besides, code and documentation are strikingly readable.

We'll see some cool features in the next sections \o/.

Where does the name come from?

If you are interested in this topic, let's talk about the name, if not, you can skip this non-technical section.

You know, naming things is hard. I always pay attention to that, whether or not it has some meaning.

I'm not sure about the details, but, IMHO, it obviously comes from the novel The Strange Case of Dr. Jekyll and Mr. Hyde, and the dual nature of Henry/Edward Hyde.

Jekyll transforms source files in markdown into static HTML files. That would make two folders for two different natures. Nevertheless, I don't see "good" and "evil"… at the end of the day, it's a tool. Maybe it's just an allusion.

Using live reload

Don't use plugins for that, there is a --livereload option:

bundle exec jekyll serve --livereload
Enter fullscreen mode Exit fullscreen mode

You can alternatively use the shortcut -l or even set livereload to true in your _config.yml.

Set up multiple environments

If you need different settings depending on the environment (local, staging, production), you can use your _config.yml for global settings across environments and override things in specific files:

_config.yml
_config_local.yml
_config_staging.yml
_config_prod.yml      
Enter fullscreen mode Exit fullscreen mode

This prevents unnecessary duplication, then run:

bundle exec jekyll serve --config _config.yml,_config_development.yml    
Enter fullscreen mode Exit fullscreen mode

Source

Besides, the global environment variable JEKYLL_ENV allows for specific usages in code:

{% if jekyll.environment == "prod" %}
    {% include tracking.html %}
{% endif %}  
Enter fullscreen mode Exit fullscreen mode

but don't forget to use it in your command:

JEKYLL_ENV=prod jekyll build

Enter fullscreen mode Exit fullscreen mode

By default, JEKYLL_ENV equals "development."

Skipping files and directories

If you don't use any YAML front matter, Jekyll does not apply any transformation to your file:

---
---
Enter fullscreen mode Exit fullscreen mode

So no Liquid parsing, etc. But, if you do not want your files or your directory to be copied in the destination folder, use an underscore or a tilde as name prefix:

_mydir/
_myfile.txt
~mydir/
~myfile.txt       
Enter fullscreen mode Exit fullscreen mode

Alternatively, you can use the exclude settings in your _config.yml:

exclude: ["mydir", "myfile.txt"]   
Enter fullscreen mode Exit fullscreen mode

How to disable Liquid

Just add render_with_liquid: false to the YAML front matter of your source file, and Liquid processing is disabled.

Simple as that.

How to create plugins

Any .rb file in _plugins is a custom plugin. Jekyll is pluggable. For example, you can add a custom converter if your source files are neither markdown nor textile.

Hooks are great too. You can use these event handlers to perform actions.

The documentation provides the following skeleton:

Jekyll::Hooks.register :posts, :post_render do |post|
    # code \o/
end       
Enter fullscreen mode Exit fullscreen mode

First, clean your installation:

bndle exec jekyll clean   
Enter fullscreen mode Exit fullscreen mode

Then I recommend the --trace and the --verbose options:

bundle exec jekyll serve --trace --verbose   
Enter fullscreen mode Exit fullscreen mode

To filter content object, you can use the following:

Jekyll::Hooks.register([:posts], :pre_render) do |doc|
    doc.content = doc.content.sub('\o/','╰(▔∀▔)╯')
end
Enter fullscreen mode Exit fullscreen mode

N.B: it's a quick and dirty example, please be extra cautious with those replacements.

The first argument is the container, the second argument is the event. If you need to target all collections use :documents instead of :posts as first argument.

Anyway, it's totally possible to filter post content on the fly before rendering.

If you are looking for some good practices regarding hooks, you can read the code of jemoji.

There are some coding standards.

What are unless and contains?

Liquid is nice. Contains is pretty self-explanatory:

{% if myvar contains "shopify.com" %}
    # code \o/
{% endif %}     
Enter fullscreen mode Exit fullscreen mode

Unless is a “reverse if”. Unless + contains equals “does not contain”:

{% unless myvar contains "shopify.com" %}
    it's not Shopify
{% endunless %}   
Enter fullscreen mode Exit fullscreen mode

Some developers assert it's not a programmer-friendly language. Well, Ruby is, for sure, but I don't have any problem with Liquid, it's fun and quite robust. If you have issues, please share.

Working with themes

Most of the themes are gem-based themes. In other words, it's like any other gem you can add to your Gemfile. By default, Jekyll uses the "minima" theme:

gem "minima", "~> 2.5"
Enter fullscreen mode Exit fullscreen mode

Indeed, you can remove this line or add another gem-based theme. You can also override specific parts of a theme in your main site folders. Jekyll looks first in the gem-based theme then on your site.

If you are a theme developer, please follow the guidelines.

Wrap up

I hope you enjoy those thoughts and tricks about Jekyll. Happy Jekylling!

Posted on by:

jmau111 profile

Julien Maury

@jmau111

Practise what you preach.

Discussion

pic
Editor guide