In order to get started with Jekyll, please have a look at the [official Jekyll website](http://jekyllrb.com) first. It basically explains everything you'll need to know how to **install Jekyll on your system** accordingly. Don't be afraid of the terminal or console by the way, it's really not as difficult as it might seems at first sight. I'll do my very best to guide you through rest of the theme setup process afterwards. Please feel free to send me an email to **hello[at]indiqo.eu** at any time if you should get stuck or have problems — *I'll see what I can do in order to help you out*. {% include media-image.html file="jekyll-website.jpg" title="Jekyll Website" caption="The documentation includes everything you need to know to install Jekyll — it's an excellent reference too" link="http://jekyllrb.com" %} Now that you got the latest version of Jekyll, it's time to build our first website. In order to do that, you'll have to **extract the theme archive first** to a directory of your choice. Depending on your operating system, an unarchiver might be preinstalled already or you can use applications like [WinZip](http://www.winzip.de) for Windows or [Archiver](http://archiverapp.com) for OSX. {% include media-image.html file="archiver-app-website.jpg" title="Archiver Website" caption="It's just a good old zip archive so any of them will work perfectly fine" link="http://archiverapp.com" %} **Good job!** As you can see, the theme includes various different files and folders. In order to understand the directory structure a little more and to get to know what each file and folder does, I'd like to refer you back to the [Jekyll documentation](http://jekyllrb.com/docs/structure/) which is rather useful and quite comprehensive. {% include media-image.html file="directory-structure.jpg" title="Directory Structure" caption="It should pretty much look like this now" link="http://jekyllrb.com/docs/structure/" %} To turn the theme and sample data into a static website now, please **open up your terminal or console** and change the directory (`cd`) you're currently in to your unzipped themes folder. {% include media-image.html file="change-directory.jpg" title="Change Directory" caption="Useful hint: Just enter 'cd' into the terminal or console and drag the theme folder into the window before hitting enter — works perfectly at least on OSX" %} Now let the magic happen and **build the site** by running `jekyll build` or start a local webserver via `jekyll serve`. A new folder called `_site` will be created which includes the entire website ready to be pushed to your webserver via FTP for example. Please keep in mind that Jekyll **sites are meant to run on webservers and not on file systems** which means that links and references are relative. If you open up one of the generated HTML pages locally, they most likely won't be styled at all, images won't show up and links can be broken at least particularly. **That's normal and intended so don't panic!** Just push the contents of the `_site` folder to your webserver or start a local one and you'll see that it works just the way it should. `jekyll serve` does that for you as well by the way and you can access it by opening `http://localhost:4000` in your browser.

Getting started

The concept of working with a static site generator using the terminal or console might be new to you, but I'll do my very best to guide you through the process.

Published May 9, 2014 in guides
Scroll

In order to get started with Jekyll, please have a look at the official Jekyll website first.

It basically explains everything you’ll need to know how to install Jekyll on your system accordingly.

Don’t be afraid of the terminal or console by the way, it’s really not as difficult as it might seems at first sight. I’ll do my very best to guide you through rest of the theme setup process afterwards.

Please feel free to send me an email to hello[at]indiqo.eu at any time if you should get stuck or have problems — I’ll see what I can do in order to help you out.

Jekyll Website

Jekyll Website

The documentation includes everything you need to know to install Jekyll — it's an excellent reference too

Visit Website

Now that you got the latest version of Jekyll, it’s time to build our first website.

In order to do that, you’ll have to extract the theme archive first to a directory of your choice. Depending on your operating system, an unarchiver might be preinstalled already or you can use applications like WinZip for Windows or Archiver for OSX.

Archiver Website

Archiver Website

It's just a good old zip archive so any of them will work perfectly fine

Visit Website

Good job! As you can see, the theme includes various different files and folders.

In order to understand the directory structure a little more and to get to know what each file and folder does, I’d like to refer you back to the Jekyll documentation which is rather useful and quite comprehensive.

Directory Structure

Directory Structure

It should pretty much look like this now

Visit Website

To turn the theme and sample data into a static website now, please open up your terminal or console and change the directory (cd) you’re currently in to your unzipped themes folder.

Change Directory

Change Directory

Useful hint: Just enter 'cd' into the terminal or console and drag the theme folder into the window before hitting enter — works perfectly at least on OSX

Now let the magic happen and build the site by running jekyll build or start a local webserver via jekyll serve.

A new folder called _site will be created which includes the entire website ready to be pushed to your webserver via FTP for example.

Please keep in mind that Jekyll sites are meant to run on webservers and not on file systems which means that links and references are relative. If you open up one of the generated HTML pages locally, they most likely won’t be styled at all, images won’t show up and links can be broken at least particularly.

That’s normal and intended so don’t panic!

Just push the contents of the _site folder to your webserver or start a local one and you’ll see that it works just the way it should. jekyll serve does that for you as well by the way and you can access it by opening http://localhost:4000 in your browser.

Posts

In order to add a new post to your site, just create a new file within the _posts directory with a suitable file extension, by default that should be .md or .markdown.

Naming conventions are important and so you should make sure to give it a file name with a structure like YYYY-MM-DD-my-first-post.md, similar to the example posts you can already tinker with.

Jekyll will order your articles by the date included in the file name, so it’s required that you choose a file name which follows this convention exactly.

Front-matter

Each file which shall be processed by Jekyll needs to start with so called front-matter which provides some kind of configuration to the processor, so it will be able to render each page properly.

Essentially, front-matter is written in YAML and starts and ends with three dashes followed by the posts content itself.

Basic front-matter

Basic front-matter

Example of basic front-matter required by each post and page — everything else is optional

  • layout: The layout will be always default so don’t think about it too much and feel free to copy and paste it into the front-matter area of each post.
  • title: The title will be what you can see on top of each page as well as in the overview on the homepage.
  • type: The type defines the format of each page — you can choose between post, page or home, but we’ll use post for now.

Please feel free to have a look at the existing posts and pages shipped with this theme in order to get an idea how it works.

Now that the configuration has been done, just write some Markdown below the second line of dashes, hit save, open up your terminal or console again and enter jekyll build once again to generate the output.

Useful hint

Nobody likes to enter the jekyll build command manually all of the time. In fact, jekyll build is just the most basic command it offers and let me say it as it is, it’s definitely not the most convenient solution.

For example, there’s an option which watches your folder for changes and automatically builds the new site for you immediately. Once again, please have a closer look at the Jekyll documentation for further details.

Pages

In general, pages work more or less just like posts — in fact, they even share the same front-matter.

The only difference might be the layout, because pages usually don’t have next or previous pages and so there’s no teaser at the bottom obviously and comments are just available for posts, but aside from that, they’re pretty much identical.

In order to create a page instead of a post, please create a new file in the root of this theme and add a file extension such as .html, .md or .markdown, depending on your own preference.

Considering that it’s a static page and not a sequence of posts, we don’t need a date in its file name anymore and so it could look like this for example: my-first-page.md

Add just the same front-matter, but instead of setting type to post, it should be page this time. Rebuild the site once again via jekyll build or a more advanced command and that’s it already!

Adding posts and pages

Posts and pages are slightly different in Jekyll, but adding them to your new website should be easy nevertheless. Especially writing contents in Markdown or Textile is a breeze compared to most clunky wysiwyg editors these days.

Published May 8, 2014 in guides