Aspyct.org

Custom page layout with Jekyll and Octopress

| Comments

When you write a Jekyll (or Octopress) page, you may chose to use a custom layout. For example, the page for Praliné sports a few buttons at the top, linking to important project resources. Let’s walk through an example with this project layout.

Creating the custom layout

First, let’s create our custom layout. Since it is pretty similar to a simple page, we’ll just copy the page layout first. The following commands assume you’re working with octopress, but they should be pretty similar for jekyll.

1
cp source/_layouts/page.html source/_layouts/project.html

We also need to select the project layout in our project page. In my case, we’re talking about praline/index.markdown. So change the layout attribute in the yaml front-matter.

1
2
layout: project
title: "Praliné"

Now, next time you generate the article, the project layout will be used instead of page. Go ahead and do a simple test by writing some funny text in the new layout.

Adding data to your page

Of course, you probably want to add some metadata to your page, and use it to render the final html. In my case, I wanted to add custom links. Simply add this information in the yaml front-matter.

1
2
3
4
5
6
7
8
layout: project
title: "Praliné"
date: 2012-09-15 00:53
links:
  - Source: https://github.com/aspyct/praline
  - Documentation: http://rubydoc.info/gems/praline/frames
  - Rubygems: https://rubygems.org/gems/praline
  - Zipball: https://github.com/aspyct/praline/zipball/master

And this data can be retreived through the page object in your layout. For example, to access the links, I need to access page.links. I’m using these links to create buttons in my layout with the following code:

1
2
3
4
5
6
7
<ul class="project-links">
  {% for link_hash in page.links %}
    {% for link in link_hash %}
      <li><a class="button" href="{{ link[1] }}">{{ link[0] }}</a></li>
    {% endfor %}
  {% endfor %}
</ul>

Do it with style

But these links do not look good, definitely… We need to add some css styling. The easiest way to do so is edit the sass/custom/_styles.scss file, and add the following:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
ul.project-links {
    margin-top: 10px;
    list-style-type: none;

    li {
        display: inline;
    }

    a {
        background: darken($main-bg, 5);
        display: inline-block;
        padding: .4em .8em;
        margin-right: .5em;
        border: 1px solid lighten($link-color-hover, 10);
        text-decoration: none;
        color: mix($text-color, $text-color-light);
        @extend .serif;
        @include transition(background-color .5s);
        &:hover {
          background: $link-color-hover;
          text-shadow: none;
          color: $main-bg;
        }
    }
}

But if you want to do it clean, I invite you to create your own style pack. Look around in the sass directory for directions.

A last note

We worked directly in the source and sass directories of Octopress. That way, we had instant feedback on our work. But if you try to install another theme, all your good work could be lost instantly. You should definitely save it into the .themes directory.

Hope this is useful :)

Comments