Jekyll for Company Websites

X @urre
A very old post. Things are outdated. Static websites is still a good thing though :). Written working with the great Kollegorna team.

Recently we made two small company websites for Blendow Group – blendow.se and bgpublishing.se. We decided to build them using Jekyll and host them on GitHub Pages. Since our client is pretty tech-savvy and knows their way around Markdown and HTML we could choose this solution knowing they could update and edit their sites easily themselves. Both sites also require very little change as they’re basically just promoting the digital products that Blendow offers (like BG Play and Legal Career that we’ve previously built for them).

GitHub pages

GitHub Pages are public web pages hosted for free through GitHub. In add-on to supporting regular HTML pages, GitHub pages also supports Jekyll - the simple static site generator.

The good stuff

  • Free - Hosting a website on GitHub Pages costs nothing.
  • Uptime - GitHub is very seldom down
  • Speed - fast response time
  • Backup - source code always safe in git
  • Private repos - private repos is now supported.
  • Fast and easy deployment

Any downsides?

  • Not all Jekyll plugins are supported. Such as our favorite plugin Jekyll Assets.
  • SSL is not fully supported. You can use https on project pages with the *.github.io domain. But you can’t use a custom domain name with a fully secured HTTPS connection. At least not yet.

gh-pages branch

For serving content via GitHub Pages you need to create a branch called gh-pages and set this as default.

This branch will hold all of your website files.

Gulp

Of course you can just use the built-in Sass-compiler in Jekyll, but Gulp is our weapon of choice when it comes to compiling assets (using for example gulp-sass, running tasks and make builds so we decided to run Jekyll as a child process in Gulp, together with BrowserSync. Which will give us file watching, CSS injecting, browser synchronization, and auto-rebuild the Jekyll site.

There are two ways of running child processes in Node, spawn and exec. Here we are using spawn.

This is the Gulp task that builds the site using the config.yml file given. (We can use separate config.yml here for dealing with dev/staging/production builds, or other things we want to be different specified as YAML front matter.

gulp.task("jekyll-build", function (done) {
	gulp.task("jekyll- browserSync.notify(messages.jekyllBuild);
		return cp.spawn("jekyll", ["build", "--config", "_config.yml"], {stdio: "inherit"})
	.on("close", done);
});

An example of what the jekyll-rebuild, watch and default tasks could look like:

gulp.task("jekyll-rebuild", ["jekyll-build"], function () {
    browserSync.reload();
});

gulp.task("watch", function () {
    gulp.watch("_scss/**/*.scss", ["sass"]);
    gulp.watch(["js/app.js"], ["js"], ["bs-reload"]);
    gulp.watch(["index.html", "_layouts/*.html", "_includes/*.html", "_posts/*"], ["jekyll-rebuild"]);
});

gulp.task("default", ["browser-sync", "watch"]);

This workflow is inspired from shakyShane.

Development mode

We just run $ gulp and fire up a browser at http://localhost:3000 and/or the external ip address provided by BrowserSync (if using the xip.io setting that is).

Using a custom domain

First you will need to create a new file in your GitHub repo called CNAME that contains the domain name (or subdomain) that you wish to use. This file should be placed in the gh-pages branch, which we created earlier.

If you want to use a root domain (such as mywebsite.se) for your website you will need to setup a new A record that points to the IP address 192.30.252.153.

Read more.

Deploy to GitHub pages

git push origin gh-pages

Easy as pie!

Edit content on GitHub or Prose

For editing content Markdown and HTML files, we just edit the files in our text editor and push to GitHub. But what about our client?

GitHub has a good editor for this, making this easy. Clicking the pencil icon takes us to the editor.

When finished, clicking the “commit changes” will commit directly to the gh-pages branch.

Prose is another alternative – a content editor for GitHub. Prose provides a beatifully simple content authoring environment for CMS-free websites Prose has advanced support for Jekyll sites and Markdown content. Prose detects Markdown posts in Jekyll sites and provides syntax highlighting, a formatting toolbar, and draft previews in the site’s full layout.

Overall we’re very happy with what we get by using Jekyll directly on GitHub Pages. This is not the last time we’ll be using it as we’re big fans of static site generators like Jekyll and Middleman.

Last but not least: check out our Jekyll boilerplate and Middleman boilerplate on GitHub.