Custom menu in Jekyll for my collection of Java snippets

7 min. read

Caution! This article is 10 years old. It may be obsolete or show old techniques. It may also still be relevant, and you may find it useful! So it has been marked as deprecated, just in case.

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.