Jekyll

Sep 19, 2016

This blog uses Jekyll which is a static site generator. Jekyll is written in the ruby programming language. A static site is a collection of webpages that do not use a database. A static site generator is a tool to create such sites.

It uses the liquid templating language (which should be very familar to those Shopify users out there) and you can use markdown in the posts. A templating language lets you substitute values into the webpage. Markdown lets you format raw data and control its appearance.

I’m hosting my blog in Amazon S3. Did you know that means it can’t be seen in China? AWS S3 is blocked there. Ruby gems for example has to be mirrored over at http://ruby.taobao.org

Jekyll is pretty nice once you have it set up, but there is a fair amount you need to know to do that. I’ll explain why.

For a windows machine, you will want to install virtualbox/vmware, install a linux image, and then install the Jekyll requirements onto that. That’s a fair bit of work. Ideally you will want to have done that before.

Anyway when that is all done. You still have to create your website with Jekyll.

So why Jekyll?

1. The sites produced are fast!
2. Since its a static site generator the results are stable
3. Its less complex than many alternatives
4. Its open source and has a community
5. You have a lot of control over the result

Its aimed at developers. However if you are a new developer or reasonably technical you should be okay. You do need to know your way around the command line, gems and version control. However you can learn the basics of these very quickly.

If your wondering what a static site generator means, it produces a website that does not use a database. So you have HTTP, CSS and Javascript which gives you a lot to work with, but avoid a lot of security problems.

What about the unoffical way?

There is a way to get it running on windows, but since it is not officially supported, I would not recommend it. When its not officially supported it can turn into a bit of a hobby to keep it running.

Getting Started with Jekyll

1. Open the command line, go to the folder where you want to create the site.
2. You have two options for creating a new site depending on how you plan to style it. You can type into the command line ‘Jekyll new mySiteName’ if you intend to use a theme (someone elses design). You can use ‘Jekyll new mySiteName –blank’ If you want to make your own design.
3. cd mySiteName
4. If you use Jekyll new mySiteName enter into the command line ‘bundle install’ hit return. Then type bundle exec and hit return
5. Type into the command line ‘Jekyll serve’ and press enter
6. Open your browser of choice and type in http://localhost:4000 or you can copy this from the command line when the server starts after Jekyll serve

Be aware that this running version is visible only on your machine. You can safely make the changes you want to until you feel its ready for release.

Writing posts

Yours posts will be written in markdown, then transformed via your layout template into your site.

1. Open the command line and go into the _posts directory in your site.
2. Create a file and name it YEAR-MONTH-DAY-title.md, add your content to that file.
3. Save the file.
4. Open your index.html file (this should not be in the _posts folder), and in that file add a index in the liquid format

<ul>
    
  {% for post in site.posts %}
    
    <li>
      <a href="{{ post.url }}">{{ post.title }}</a>
    </li>
    
  {% endfor %}
    
</ul>`

When this is finished you should be able to view the posts you added in the browser. In GitHub pages its served from the repository, but you can host it elsewhere cheaply.

Between the documents and the talk group, there is a lot of help getting set up. If you have any problems just ask.

Useful commands