Custom menu in Jekyll for my collection of Java snippets

7 min. read

I just launched, a site for a repo where I plan to collect all my most used Java snippets and tricks, so that I don't have to be searching the web when I need something.

Check out the portfolio post.

Loading all the pages in a menu

Whenever I have a menu, I like to use the ul tag. Some people use links directly, but if you are browsing the site with stylesheets disabled or with a text browser (like lynx in linux terminals, for example), the links appear together with no separation between them, which make them difficult to read. You could use a separator like |, but then you need to put it between span tags to hide it from visual browsers like Firefox. The un-ordered list tag feels natural and more semantic as a way to list items in a menu (at least for me).

Now, the liquid syntax (used by Jekyll to generate the code of your site) allows you to use a for loop to list your pages so that you don't have to write or update them manually. The problem is that they are listed in alphabetical order (or anti-alpha order).

So, if I want to list my pages in a particular order, I have to do it by hand. For example, I wanted to have a "How to" page as the first item in the menu, so I placed it manually and then coded the automatic menu generation within the for loop for the rest of the pages.

  <li><a class="menu" href="{{ site.baseurl }}/howto/">How to</a></li>{% for page in site.pages %}{% if page.menuname %}
  <li><a class="menu" href="{{ page.url | prepend: site.baseurl }}">{{ page.menuname }}</a></li>{% endif %}{% endfor %}

I also prefer to use specific classes for the list items (class "menu") instead of playing inception with the tags (.class tag tag tag ...etc {...}), since it has less CSS specificity, so it's more performant.

I added yet another small twist: a Front Matter variable in every page, called menuname. In this variable I store a short name for the page in the menu. Otherwise, I would have to use something like the title, which is too long for the sidebar:

layout:    default
title:     "ProcessBuilder with multi-threading"
menuname:  "PB Multithread"
permalink: /pbmultithread/

The "How to" page doesn't have this variable in the Front Matter, to prevent the for loop from placing it again in the menu.

And that's all! I also used permalinks in the Front Matter to strip the html extension from the url (if it was hosted in another server, I could use an .htaccess file for that instead). Finally, I'm using prefix-free, prismjs and MathJax as usual.

Layouts folder

Just one default layout. The prismjs and MathJax libraries are included here instead of in the footer.

Includes folder

To keep it simple, I have a file for the head tag, another for the sidebar, and a footer. In the sidebar, there is a menu where I list all the pages I have in the site. I thought it made more sense to have the snippets in pages than to have them in blog posts.

Sass files

This is also the first time I use sass, so this Jekyll site has a _sass folder where all the partials are stored. This is the order in which they are loaded in my main.scss file, which lives inside the css folder:

/* Import partials from `sass_dir` (defaults to `_sass`) */

The first one is Nicolas Gallagher's famous reset stylesheet "normalize". Then I have basic styling stuff for html tags. The layout partial is where I have what I would call the actual theme, although the separation is not that sharp; part of the theme's styling can be found in the _base partial too. Then I have Lea Verou's syntax highlighter prism, and finally, the media queries for responsiveness, which I like to keep together in a separate file.

I think this is a good organization model and I might be using something very similar in future sites.

You can find the code of this site at GitHub.