I'm going meta on my first blog post: how to set up a Jekyll blog inside a Sinatra app. A few people have written on this topic, but I had some specific requirements that no one addressed. So my goal here is to write the post I wish existed when I started out. Here it goes.
I have an existing Sinatra site and I want to add a blog section to it. I don’t want Jekyll to take over my whole application, rather just a certain part of it (the /blog section). Thankfully, this is possible AND I can reuse my layout.haml (header, footer, styles, etc) for the blog pages. Here’s how:
First, you gotta install some stuff. I’ll assume you are using Bundler to handle your gems, because you should be.
Next, you will need to clone some basic setup files for Jekyll to a folder within your site. Daniel McGraw has a nice little Jekyll Base to get you started.
We will add these files to our primary git repo, so you can remove the .git folder that is generated when you clone Jekyll-Base. Keeping it will cause git to assume its a submodule, and your files won’t be added.
You should also check out _config.yml. It has all of your Jekyll configuration, which is worth understanding to get the most out of it. Here’s mine:
Once you get it configured, go ahead and run Jekyll for the first time to generate your static pages in to _site for the first time.
Jekyll also offers a built in web server for local development, but we shouldn’t need it with our Sinatra app. Once Jekyll generates our pages in _site, we can kill the process.
Note that whenever you make any change to your Jekyll files, including writing new posts, you will have to run the Jekyll command to re-generate your static files.
Next, we need to wire up our routes. In my case, I want Jekyll to handle everything under /blog.
Next, create a method to route our page requests correctly to Jekyll. Basically what I’m doing here is looking up the blog post file based on the URL, reading the file in to a string, and rendering that string like I would any .erb page.
We should now be ready to test this out. Go ahead an fire up your local webserver. I prefer Unicorn.
At this point, you should be up and running with the a basic Jekyll blog within your app. You can start writing posts now, or if you want to add more bells and whistles, read on.
Jekyll supports Markdown, which is a pretty robust and simple way to write content for the web. However, it doesn’t do everything for you. I also wanted to add commenting, sharing and code syntax highlighting.
Disqus is my choice for this. They offer a commenting service for free, have login integration with Twitter and other 3rd party apps and have great moderation tools. To wire it up to Jekyll, create a Disqus account and add this block of code (with your Disqus site ID) to _post.html in the _layouts folder.
Social media! Everyone loves it. An easy way to offer sharing links for your posts is by using a service called AddThis. Like Disqus, they are free. In fact, you don’t even need to create an account with them to get started. Just grab the code and place it in your _post.html file like we did with Disqus.
I like sharing code (like I’m doing in this post), and its important for readability to do syntax highlighting. Jekyll supports this via a Python library called Pygments.
In our Jekyll config, enable pygments.
Then we install Pygments and use it to generate our CSS.
I added this css file to my public/css/ folder and reference in my site header.
Then, regenerate Jekyll.
Scott Parker has a great little tutorial for adding additional features that don’t come out of the box with Jekyll, namely RSS, pagination and convenient image handling. I definitely recommend checking it out.
If you want to see all of these parts in action together, check out the code for this site on Github.