Jekyll Cheat Sheet

Building this blog with Jekyll has been a lot of fun for me. But while I was building it, I had to research a ton of stuff to improve my workflow and make this static site as functional as possible. So now I'd like to share some information that might be useful to anyone else new to Jekyll and would like to give it a try.

Jekyll and Browsersync

If you want to use Browsersync with Jekyll, you may be a bit confused at first because both of them start their own servers. But luckily, Jekyll has different options on how it generates files. To make Jekyll play nice with Browsersync, use the jekyll build --watch command instead of jekyll serve. And then tell Browsersync to serve files from the _site folder. I also installed gulp-shell to have Gulp execute jekyll build --watch for me.

Then, add the code below to the area where you want the comments to appear. An even better way to do this would be to place this code in a separate include file. Note that the disqus_shortname you defined in your config file is already being passed in, so you don't need to edit anything.

Adding a Formspree Contact Form

To add a contact form to a static site, you can use Formspree. You don't need to sign up for anything, you just need to send your form to their URL and they'll forward it to your email. They also provide special name attributes you can use in your form that have specific functions when using their service. You can learn more by going to their site. If you looked at their examples and noticed that I did not add an action attribute to this form, this will be explained later on.

One issue with using Formspree is that your plaintext email would be lying around exposed in your code. This could potentially lead to a lot of spam. My solution was to obfuscate my email with JavaScript. The code below takes your base-64 encoded email, converts it back to plaintext, and concatenates it to the Formspree URL. You can then set your form's action attribute or submit your form using AJAX. To get your base-64 encoded email, run your plaintext email through the btoa() function.

Lastly, once the form is submitted the page will be redirected to Formspree's "Thank You" page. It would be preferable if the user stayed on your site after submitting the form. One solution would be to redirect the user to an alternative page within your site by using _next in Formspree's name attributes.

Sharing Posts to Other Sites

If you follow any major blogs or news sites on Facebook you've probably noticed that they usually display with images and neatly presented information. If you want pages of your Jekyll site to display like that, you need to add Open Graph tags which are recognized by both Facebook and Google+, and Summary Card tags for Twitter.

Metadata in the <head>

The block of code below contains most of the necessary tags for both. Note that most of the information is being pulled in from _config.yml so you should check first whether the options used below exist in your config file.

If you want to make sure the tags you added are valid, each of the sites have their own validators where you can paste your URLs to have them checked.

Share Links

Now that your pages display nicely when they're shared, you should also make them easier to share so that the user doesn't have to copy the URL, open another browser tab, and paste the link. Below is a snippet of sharing links for Facebook, Twitter, and Google+.

Quick Note About Kramdown and Rouge

Jekyll uses Kramdown as its markdown engine, which uses Rouge as its code highlighter. If for some reason you don't want to use Rouge and use something else like Prism, that's a problem because Kramdown applies the class highlighter-rouge to code blocks which doesn't work with Prism. You can disable this behavior by adding the option below to your config file.