Make a Linked List With Octopress

Here’s a Twitter exchange that I woke up to this morning:

Fair warning: this is going to be one of those “how to code” type posts. I’ll return to the regularly scheduled film-related nonsense shortly.

Okay, so, “Daring Fireball-style Linked List posts,” for the uninitiated, refers to the publishing style of John Gruber’s Daring Fireball. For the most thorough explanation of how this works, see Shawn Blanc’s excellent 2009 article, “The Link Post,” in which he calls this kind of link “The Out and About”:

What especially sets The Out and About apart is its feed format. Because not only do the Link Post titles point directly to the linked-to content, but so do those in the RSS feed.

That’s basically how I implement link posts here on the candler blog. Regular posts feature unadorned headlines while link posts are denoted by an additional glyph at the end of the headline. I use the double arrow, ⇒ (⇒ in HTML).¹ The headlines of all link posts go to another site, both in your web browser and in your RSS application. They also feature a permalink at the bottom of the post so you can always find a way to get back to my site, which usually features commentary of some lasting value (I hope).

But how is it done in Octopress? It’s actually very simple. I got a great deal of help, when I was first setting up the site, from Connor Montgomery, who posted his own link post tutorial a few weeks ago. I have since refined the code on my site beyond what we worked out together.

The first thing to know is that Octopress will read anything you put into the YAML front matter of a post.² Just add a new line with a colon and then that content is readable by the rest of your theme. Here’s my YAML front matter on a link post:

{% codeblock lang:ruby Sample YAML Front Matter %}

layout: post title: “Extremely Smart and Incredibly Handsome” date: 2012-01-30 05:00 comments: true categories:

• Nerdfest externalurl: http://www.somewhereelse.com/whatever

{% endcodeblock %}

Notice the last line that says external-url. Now throughout the theme I can use post.external-url to let Octopress know what to do with any post that has that line in it. If you called that line foo then you would simply place post.foo throughout your theme.

Now we need to dig into the theme to make use of that fancy new external URL line. First up is /source/_includes/article.html. This is the file that determines what your posts look like. Let’s change the header so that it links out to the external-url we just set and add a glyph to the end of it.

{% codeblock lang:html Top of article.html %}

Octopress, which is based on Jekyll and the Liquid templating engine, makes quick work of turning just about anything from your YAML front matter into part of the theme. Once you tell the theme to treat links posts differently with {\% if post.external-url %}, then all you have to do is define your link out with <a href="{{ post.external-url }}">. That’s it. No scripting, no plugins. Just old-fashioned HTML. Neat.

We still need to add a permalink to the end of the post. Again, easy as pie. Let’s just head back into article.html only this time we’ll focus on the bottom portion. The following should be the last lines in your code. ³

{% codeblock lang html Bottom of Article.html %} {% if post.external-url %} Permalink {% endif %} {% if page.external-url %}

Same idea, only now we’re adding the permalink back to your site. This permalink appears both on the main list of posts and in the specific post page. I find this makes it easy for readers to find the direct URL no matter how they came to the page.

Finally, we need to get the RSS feed to link out and have permalinks back to the original posts. To do this, we need to make a few edits to /source/atom.xml. This certainly freaked me out more than editing plain old HTML, but it’s actually just as simple. Thanks to Octopress’s handy rake preview command, it’s easy enough to test your changes locally, even for the RSS feed. I test my site in Safari on a Mac, so I’m able to initiate the RSS feed in-browser.⁴

{% codeblock lang:xml Changes to Atom.xml %} {% for post in site.posts limit: 20 %} {% if post.external-url %} {% else %} {% endif%} {{ post.date | date_to_xmlschema }} {{ site.url }}{{ post.id }} {% if post.external-url %} {% else %} {% endif %} {% endfor %} {% endcodeblock %}

Again, it’s just a matter of placing that post.external-url in the right place. I’ve been deploying this site like this for weeks without incident.

I’m not really a coder, but I find that Octopress makes it pretty simple to implement any kind of customization. When I implemented a similar system on Wordpress it required installing a plugin (the excellent DFLL Plugin) and fiddling around with the site’s theme. I found the process on Octopress decidedly more enjoyable. Instead of being at the mercy of plugins (which add bloat and an extra layer of management to your site) I was able to get this running with a basic understanding of HTML. Better, the ability to test the site locally allowed me to screw up over and over again until I got it right. And I think I finally did.

So, did I leave any details out? Anything else you want to know about how this works? Ask me in the comments.