April 10, 2013

With Posterous shutting down on April 30th, you may find yourself trying to decide where to move your blog postings. Move to Blogger, Tumbler, or WordPress? Build your own blogging engine in Erlang?

Thanks to a suggestion from Chase Seibert, I decided to checkout GitHub Pages. If you visit http://pages.github.com to find documentation, you might be confused given that there's no quick 1-2-3 process. In fact, what you have to do is create a GitHub repository first! If you want a personalized blog for yourself, you repo must be named "[username].github.io". You can also host a blog within an existing repo by simply creating a gh-pages branch, or you can use the "Automatic Page Generator" button in the repo's Settings page to do so. More details/documentation are available at this GitHub page.

Using the GitHub Pages templates, you may find yourself extremely limited in choices. These CSS/HTML templates are usually only 1-2 columns, and there is little guidance about how to implement pagination, search, and archive listings. GitHub Pages operates under the assumption that you're going to use a Ruby package called Jekyll, which was built by Tom Preston-Warner of GitHub fame and many other individuals. Jekyll provides support for code syntax highlighting, clean markup language, and the benefits of using the same GitHub pull-request workflow model, but you may not have the fancy aspects of WYSWYG editing and image uploads since the blog is generated via static pages.

Instead of a WYSWYG editor that inserts all the HTML markup yourself, you end up writing mostly in your favorite editor of choice (i.e. vi/Emacs) and running Jekyll to generate your postings into static HTML files that can be hosted. When you push to the gh-pages branches, you're essentially triggering GitHub to run Jekyll to generate the files. If you want to host the pages elsewhere, you can do a "sudo gem install jekyll", run "jekyll", and push the generated files in the _sites/ directory to S3. It still makes sense to have Jekyll installed locally so you can actually see how your pages will be rendered.

Here are some areas of the process that I thought might be useful to share:

  • This blog was built using the Jekyll Bootstrap package, which comes with the pagination and archiving support out of the box. If you're going to host the page off a repository instead of your main username, you'll want to make adjustments to the BASE_PATH inside the _config.yml. This BASE_PATH is needed since your URL's are no longer relative '/' but rather some combination of your GitHub username and the repo name. If you find that your CSS or images are not loading correctly, chances are that you need to update this BASE_PATH configuration! We also switched to using the rdiscount markdown instead of the included because of this known issue with embedding iFrame links with the default version.

    BASE_PATH : http://hearsaycorp.github.io/hearsay-blog
    markdown: rdiscount

  • Jekyll also comes with a dev server (jekyll --server --auto), which can also regenerate files if there are file changes. This Stack Overflow article has this command-line that appears to downgrade the 1.5.1 version to an older version that makes the reloading correctly work. Otherwise, you may be wondering why pages are not being refreshed in spite of the auto: true setting inside the _config.yml file.

    sudo gem uninstall directory_watcher && sudo gem install directory_watcher -v 1.4.1

  • Pagination on the main page could be implemented by simply defining this section inside index.html and defining "paginate: 3" inside the _config.yml. (To implement the paginated Previous/Next links on the main page, you can take the section from the _includes/themes/twitter/post.html file.)

    {% for post in paginator.posts %}
    {% include post.html %}
    {% endfor %} 

  • To migrate our postings from Posterous, I followed the documentation at https://github.com/mojombo/jekyll/wiki/blog-migrations. The key is that you need to be signed into posterous.com and need to get an API token from https://posterous.com/api by clicking the view token link. You would then run the following command:

    ruby -rubygems -e 'require "jekyll/migrators/posterous"; Jekyll::Posterous.process(<my_email>, <my_pass>, <api_token>)'

    ...which will download everything into the _posts/ directory. The key thing to note is that every HTML file downloaded will be prefixed with a YAML header which is used by Jekyll to determine whether and how the posting should be processed:

    ---
    layout: post
    title: My posting
    published: true
    ---

  • Multiple authors support can be added by following this Gist article. I modified the Rakefile to add an extra author: entry whenever generating a new posting (i.e. rake post title="My Title Here" date="2012-12-05").

    open(filename, 'w') do |post|
    post.puts "---"
    post.puts "layout: post"
    post.puts "title: \"#{title.gsub(/-/,' ')}\""
    post.puts 'description: ""'
    post.puts "author: "
    post.puts "category: "
    post.puts "tags: []"
    post.puts "---"

    You can also update the _includes/post.html file to add the author by-line:

    <div class="meta">
      Posted on <a href="{{ BASE_PATH}}{{ post.url }}">{{ post.date | date: "%B %e, %Y"}} {% if author %}by {{ author.display_name }}{% endif %}
    </div>
  • For code snippets to show you how to use Jekyll's templating language (Liquid), I added this Jekyll plug-in by downloading it to the _plugins/ directory. It basically adds a raw tag to disable Jekyll from processing the section. You still have to escape the HTML tags yourself since Jekyll is not going to be handling this aspect! (i.e. changing < and > to use their ampersand equivalents).

  • Take advantage of GitHub's ability to handle custom domains via CNAME's. You can simply create a file in the root directory with the URL you wish to use (i.e. engineering.hearsaysocial.com). Once this file is created, you just need to change your DNS to point to your (i.e. [GitHub username/org name].github.io) host. In our case, it was hearsaycorp.github.io. For more information, see: https://help.github.com/articles/setting-up-a-custom-domain-with-pages.



blog comments powered by Disqus