CloudCannon uses Rails for our backend and I can say that it is an absolute joy to work with. In this showcase, we'll deconstruct the Ruby on Rails marketing website to see what makes it tick.
Ruby on Rails is a heavily influential web application framework powering some of the largest businesses in the world. It was created in 2003 by David Heinemeier Hansson (DHH) to power 37signal’s first commercial product, Basecamp. Since then it has won the hearts of developers around the world including my own.
The Rails marketing site is a good example of keeping things super simple. When you look through the main navigation, you’ll see all the pages link to external locations. So what’s actually part of the Jekyll site? The home page, Code of conduct, Doctrine and other tightly scoped supporting pages. The front matter for all the pages is straightforward, simply setting the title and description for SEO, the layout, and a permalink for making the URL a little bit prettier.
The body of the pages is pure HTML. There’s no liquid for loops or fancy Jekyll implementations here.
The home page is the only page with a top navigation so again, pure HTML, no magic.
With the sheer number of frameworks and libraries available to developers these days, it can be tempting to use a site like this as a testbed for the latest tools. The Rails team has done a great job of assessing their needs for the marketing site and creating the simplest solution possible. It’s easy to maintain, easy to contribute to, future Jekyll updates are unlikely to break this site, and no one needs to document how it all fits together. It just works.
Most of the pages outside the homepage use the page layout. This adds the rails logo and a link back to the home page.
The final layout is for the doctrine page. This page is unique because it’s translated into five languages. We’ll dive into how the translation works in the next section.
Delivering translated website can require highly complex processes. True to the nature of this website, the Rails team has made the translation process as simple as possible.
As a user, clicking on the Doctrine page takes me to the English version. On the right side, there’s a language picker to switch languages. Each translation of the page is its own page, with its own URL.
:focus CSS property, it’s possible to do the same thing in pure CSS but that’s just getting nitpicky.
So how do the translated pages work? Well, they’re other pages that happen to have the same content and structure as the source page:
For a single page with straightforward content, this works great. Translators can make a copy of the English page and translate each piece of content.
If there were multiple pages to translate, this strategy would soon get unwieldy. Let’s say you wanted to adjust the structure of the logo in the header. You would have to make this change on every translated page. One minor improvement to address this is taking the header section, turning it into an include, and populating the content from variables.
Then the content file would use the include like this:
Now anytime you want to adjust the structure of the header, you can do it in one place, which will change it across all the translations.
A more scalable way of doing this is using a translation system. CloudCannon has an open-source tool called Rosey, which takes a lot of the complexity out of translations. The way it works is you build your website in one language, then set a key for each piece of content using HTML attributes. For example:
When you run Rosey on your static output, it will generate a JSON file with all your keys and their source language values. You can set up a process to automatically send this file to your translation service (Smartling for example) or translate them manually. When the translation is complete, you’ll have a version of this file for every language you’re translating to. Rosey takes these translated files and generates a multilingual version of your site. Again, for the Rails site, this would be overkill. If their translations requirements increase in the future, it might be something to look at.
The Rails site uses the GitHub Pages gem, which is a gem that gives you access to all the Jekyll plugins whitelisted for GitHub Pages. The plugins actually used on this site are pretty typical for a Jekyll site:
I can’t see anywhere they’re creating redirects, so
jekyll-redirect-from is likely unnecessary here.
jekyll-seo-tag does a lot with minimal configuration. They’re setting the default title, description, image, andTwitter handle for the SEO plugin in their
On the homepage, without any extra configuration, this creates the following meta-tag structure:
This is a must have plugin for any Jekyll site. I can tell you first hand that creating this meta-tag block by hand, sucks.
jekyll-sitemap typically doesn’t require any extra configuration. On the Rails site the output looks like this:
Google won’t have any issues finding all the pages on this site. Interesting it picks up the PDF license for their font. Probably not intentional, whoops.
The Rails team has a well-constructed marketing site that I’m sure will serve them for years to come. Their implementation is so simple that there’s virtually no risk of the site becoming unmaintainable or the build breaking in a future Jekyll update. If it is a problem, they could probably switch to another static site generator like Hugo in under 15 minutes.
As a learning resource, this is a great site to look at when you’re starting out with Jekyll. It highlights the simplicity that Jekyll brings. It’s a small step from a purely static website that makes a world of difference when it comes to maintenance.