Improve Octopress with Advanced Tweaks & Tips

by

Octopress is a framework design for Jekyll. It’s static site generator and that’s why it lacks of advance feature like WordPress (Read more about it if you would like to move from WordPress to Octopress). Jekyll support plugins so you can use it for improve your website that’s based on Octopress.
From last post, you’ve known some tips to help your blogging processes with Octopress easier than normal. In this post, I will continuing show you some advanced tweaks to improve Octopress power.

Adding Related Post to Octopress

If you’re not know too much about Ruby, I recommend you related_posts plugin instead a lot of customization below.

Jekyll has related posts functionality already, all you needed to do was to use it in the template. Open _layouts/post.html then edit

{% if site.related_posts.size > 1 %}
<article class="archives">
  <div class="related-posts">
    <h2>Related Posts</h2>
    {% for post in site.related_posts limit:site.recent_posts %}
      <article>
        <h3 class="title"><a href="{{ root_url }}{{ post.url }}">{{post.title}}</a></h3>
        <div class="meta">
          <span class="tags">{% include post/categories.html %}</span>
            {% if site.disqus_short_name and post.comments == true and site.disqus_show_comment_count == true %}
          <time datetime="{{ date | datetime | date_to_xmlschema }}" pubdate{% if post.updated %} data-updated="true"{% endif %}>{{ date | date: "%F" }}</time>
            {% endif %}
        </div>
      </article>
    {% endfor %}
  </div>
</article>
{% endif %}

Turn on Relate Post function

This function need enable in _config.yml: lsi: true
The lsi option performs a proper statistical analysis of the posts to determine the best related posts. You can place it anywhere in _config.yml file.
But if you regenerating your blog at this time, you will spend a lot of time to allow the system calculating for Related Posts. Let’s increase that process with GSL.

$ gem install gsl

After GSL installed, let’s regenerated your blog.

Sidebar category list

This plugin provides the category list and post count shown in the sidebar.

  • Save tag_cloud.rb to plugins/tag_cloud.rb.
  • Save category_list.html to source/_includes/custom/asides/category_list.html.
  • Append to default_asides in _config.yml:

Add to _config.yml:

default_asides: [asides/recent_posts.html, asides/github.html, asides/twitter.html, asides/delicious.html, asides/pinboard.html, asides/googleplus.html, custom/asides/category_list.html]

Migrating WordPress comments to Disqus

Octopress has not an own commenting system but it has excellent integration with Disqus, a hosted comment management system. After migrated from WordPress, you won’t get the post’s comments together. It’s a big problem and may it drives you comeback to WordPress. Don’t worry, you can’t move your comments from old WordPress to new Octopress with Disqus comment system.
Enable Disqus comment in _config.yml:

# Disqus Comments
disqus_short_name: your-domain-name
disqus_show_comment_count: false

Login to your Disqus account. Go to Admin > Migrate threads tab. Run domain migration wizard. It might take a full day to populate all comments in your blog.
If your old WordPress blog used raw permalinks as https://www.narga.net/?p=123 and in your new Octopress blog is using SEO friendly permalink as https://www.narga.net/year/month/post-name then all comment threads got pulled in. To fix this I created a simple Url map (CSV) and used the Disqus Url Mapping Tool to fix these links.

Speed up Octopress generating processes with isolation parameter

If you had a tons of post in source/_posts then it cost you several minutes when updating your blog. Obviously if you are just working on one post, there is no need to wait for the entire site to generate. What you are looking for is the rake isolate[partial_post_name] task.
Using rake isolate, you can “isolate” only that post you are working on and move all the others to the source/_stash folder.
The partial_post_name parameter is just some words in the file name for the post. For example:

rake isolate[test-single-post]

You can also do this while you are running rake preview. It will just detect a massive change and only regenerate that one post from then on.

Move all stashed posts back into the posts directory, ready for site generation

When you are ready to publish your site, just run rake integrate and it will pull all the posts from source/_stash and put them under source/_posts.
To know more parameter of rake command, you can use rake list -T to get a dump of all the tasks.

Use Picasa to host images and media files

From start, I hosted images and media files as local files until I found Picasa can help me host and manage its more than expected.

  • Images will be delivered from CDN (free)
  • Images will cache & resize on the fly.
  • You can create custom image sizes.
  • Optimize image by selecting image quality.

Resize images on the fly

Let’s view the Picasa image’s url

Add a List of Popular Posts

A popular posts(or a top posts) section is literally present on every blog on the internet. It recommends quality posts to your readers.
Add this line to your Gemfile: gem 'octopress-popular-posts'
Install it using Bundler: bundle install
You have to run installation commands to copy the plugin to your source: bundle exec octopress-popular-posts install
Once installed, the popular posts asides section will be generated whenever you run: rake generate
In your blog’s config.yml, add this line.

popular_posts_count: 5      # Posts in the sidebar Popular Posts section

Next, you need to add the popular post aside section.

default_asides: [custom/asides/about.html, custom/asides/subscribe.html, custom/asides/popular_posts.html, asides/recent_posts.html, asides/github.html, asides/twitter.html, asides/delicious.html, asides/pinboard.html, asides/googleplus.html]

Note the custom/asides/popular_posts.html that is added on the third entry of the array.

Display special characters in markdown on Octopress

Some special characters using by Octopress so you can’t make it display on your site as normal writing like {{, ^ ...
To do it, lets wrap your characters with {% raw %} and {% endraw %} blocks

{% raw %}
```
<ul id="beers-list">
    {{#beers}}
        <li>{{name}} - {{color}} - {{alcohol}}%</li>
    {{/beers}}
</ul>
```
{% endraw %}

Remove Octopress’ Default Blog/ Directory

By default, Octopress deploys your posts, categories and archives to a /blog/ subdirectory. You can remove it if you want by some steps below:

  • Replace all /blog occurences by / in _config.yml
  • Move source/blog/archives to source/ (you can delete blog/)
  • Edit source/_includes/custom/navigation.html, replace /blog/archives by /archives
  • Edit source/index.html then replace /blog/archives by /archives

Custom 404 Page

You won’t find any information about 404 Error of Octopress and me too. So, I did some research and found out it’s super easy to add a custom 404 page to Octopress. In your config.ru file, you should have:

not_found do
  send_sinatra_file('404.html') {"Sorry, I cannot find #{request.path}"}
end

To create the page, make a new file named 404.markdown in your /sources directory. Now, write your own 404 Error Page then deploy your website.

Conclusion

So that’s my experience with the WordPress to Octopress migration. Although not a smooth transition, it wasn’t terribly bad and I actually enjoyed the process using a variety of tools. After that, I got some experiences with Octopress and Ruby although I’m completely with Ruby. Hope these Octopress tips and tweaks can help you if you choose it like me.