Octopress

A blogging framework for hackers.

Theming & Customization

Shortly after the 2.0 release Octopress added the source/_includes/custom directory. If you don't have this, you'll want to update because it's really nice.

source/
  _includes/    # Main layout partials
    custom/     # <- Customize head, header, navigation, footer, and sidebar here
    asides/     # Theme sidebar partials
    post/       # post metadata, sharing & comment partials
  _layouts/     # layouts for pages, posts & category archives

Landing Page vs. Blog Index

By default Octopress generates your blog's post index at your site's root directory. If you'd rather publish your blog index somewhere else like blog/index.html do this in your terminal.

    mv source/index.html source/blog/index.html

    rake new_page[index.html]

Next you'll want to update your Rakefile to be sure your new blog index is preserved when you update Octopress.

    blog_index_dir = 'source/blog'

Then you may also need to update _config.yml to specify the pagination path in order to generate the list of blog posts on the index page.

    paginate_path: "blog/posts/:num"

Remember to update the main navigation for your site, since currently the blog link points to /. Skip down to the section on changing navigation, add a 'home' link and update the 'blog' link to point to /blog/.

Finally, source/index.html can become the landing page of your wildest dreams.

Changing the <HEAD>

If you want to add scripts or tags to the <HEAD> take a look at /source/_includes/custom/head.html.

<HEAD> (source/_includes/custom/head.html) 
{% comment %}

To customize the favicon, assign it to "/url/to/favicon.png"

{% endcomment %}

{% assign favicon = false %}

<!--Fonts from Google's Web font directory at http://google.com/webfonts -->

<link href='http://fonts.googleapis.com/css?family=PT+Serif:regular,italic,bold,bolditalic' rel='stylesheet' type='text/css'>

<link href='http://fonts.googleapis.com/css?family=PT+Sans:regular,italic,bold,bolditalic' rel='stylesheet' type='text/css'>

Here you can easily change or remove the Google Webfonts, insert javascripts, etc.

If you'd rather inject scripts at the bottom of the page, you can add that to /source/_includes/custom/after_footer.html.

Changing the sidebar

Octopress integrates with some 3rd party services like Twitter, Pinboard and Delicious which appear in the sidebar. In the _config.yml you can rearrange these, create custom sidebars for each layout, and add your own sidebar sections.

Sidebar configuration (_config.yml) 
default_asides:   [asides/recent_posts.html, asides/twitter.html, asides/delicious.html, asides/pinboard.html]

# blog_index_asides:

# post_asides:

# page_asides:

If you want to add a section to your sidebar, create a new file in source/_includes/custom/asides/. Since many people probably want to add an About Me section, there's already an about.html file in there waiting to be added. Here's a look.

About Me (source/_includes/custom/asides/about.html) 
<section>

    <h1>About Me</h1>

    <p>A little something about me.</p>

</section>

Whenever you add a section to the sidebar, follow this pattern, with a <section> block and an <h1> for a title. To add it to the sidebar, edit the _config.yml and add it to the list of asides.

Sidebar configuration (_config.yml) 
default_asides:     [asides/recent_posts.html, asides/twitter.html, asides/delicious.html, asides/pinboard.html]

blog_index_asides:  [custom/asides/about.html, asides/recent_posts.html, asides/twitter.html, asides/delicious.html, asides/pinboard.html]

post_asides:        [custom/asides/about.html, asides/recent_posts.html, asides/twitter.html, asides/delicious.html, asides/pinboard.html]

# page_asides:

In the configuration above I've added the about page to the blog index and post pages. Since page_asides isn't being set, it will inherit from the default list.

Changing the Header, Navigation & Footer

These are sections of the site that are most likely to be customized. You can edit each in /source/_includes/custom/ and your changes will be preserved across updates.

Changing the Header

The header title and subtitle should be configured in the _config.yml If you want to make other changes to the header, edit /source/_includes/custom/header.html which looks like this:

Header (source/_includes/custom/header.html) 
<hgroup>

  <h1><a href="{{ root_url }}/">{{ site.title }}</a></h1>

  {% if site.subtitle %}

    <h2>{{ site.subtitle }}</h2>

  {% endif %}

</hgroup>

Changing the Navigation

To change or add links to the main navigation, edit /source/_includes/custom/navigation.html which looks like this:

Navigation (source/_includes/custom/navigation.html) 
<ul class="main-navigation">

  <li><a href="{{ root_url }}/">Blog</a></li>

  <li><a href="{{ root_url }}/archives/">Archives</a></li>

</ul>

The href for each link begins with {{ root_url }} (this helps Octopress write urls differently if a site is deployed to a subdirectory). If you're deploying your site to a subdirectory like yoursite.com/octopress you'll want to add this to any links you add.

Changing the Footer

You can customize the footer in source/_includes/custom/footer.html which looks like this:

Footer (source/_includes/custom/footer.html) 
<p>

  Copyright &copy; {{ site.time | date: "%Y" }} - {{ site.author }} -

  <span class="credit">Powered by <a href="http://octopress.org">Octopress</a></span>

</p>

Change this however you like, but be cool and keep the Octopress link in there.