Mike West - Posts Only

JSLint needs some Bad Parts

2010-05-16T00:00:00+02:00

One of the few tools that I consider truly indispensable when developing websites is JSLint. A marvel of applied compiler theory, the program has saved me from stupid mistakes more times than I care to remember. I have it set up to automatically sanity-check my code every time I push a commit to SVN, and it’s generally my best friend in the whole wide world.

JSLint isn’t always perfect, however, especially when used to check CSS files. I think Douglas Crockford is a JavaScript wizard, but I'm somewhat less blindly acquiescent when it comes to his take on the Good Parts of style sheets. For better or worse, browsers are much less similar in their interpretation of what I mean when I write a particular style, and certain hacks and workarounds are par for the course when putting together a layout of any complexity. JSLint’s CSS checks do a good job warning about certain types of errors (missing semicolons, for instance), but a relatively terrible job when it comes to some of the necessary evils of practical development. In short, JSLint’s CSS mode needs some Bad Parts to be really usable for me.

In itself, this wouldn’t be an issue. Crockford has kindly released JSLint as open source (under a unique (to say the least) “Do no evil” license), and I'm generally able to puzzle out how to go about adding support for the features that I believe are necessary. Getting those patches into the mainline JSLint project is, unfortunately, often a miserable process. I have two issues with the current process:

First, there’s no public repository (that I've come across). Crockford is pretty good about announcing changes on the JSLint mailing list, and he keeps a timestamp in the current fulljslint.js file, but that’s hardly a solid basis for contributing patches. This isn’t a show stopper, it just makes things harder to follow than they could be, and more difficult to give back to the project than it should be. I asked about this in May 2009, and was met with silence. Ah well.

Second, the aforementioned list is easily the most (passive-)aggressive I've been on recently. The (true) warning that “JSLint will hurt your feelings” goes double for posting questions or suggestions, especially as a newbie. I almost fell off my chair when I saw this question (“I have this problem, and I've found this workaround. Why is it a problem in the first place?”) received this response (“Thanks for the report. JSLint now no longer accepts your workaround.”) Crockford is a smart guy, and he’s opinionated in the best possible way, but he couples that with a periodic lack of tact that’s really influenced the way the list as a whole works. It’s simply not a fun place to contribute ideas or code, and that’s a shame. Arguing about the validity of suggestions is simply not something I'm willing to do every single time I make a suggestion, especially when the suggestions are quite often met with silence from the one guy who actually has commit access to the mainline trunk.

So, to resolve these issues for myself, I'm forking JSLint. I fully expect this to be of interest to almost exclusively myself, but I’ll find it useful, and I’ll hold out hope that some of the patches will eventually make it back into JSLint proper.

To resolve the issue of a base “official” repository, I’ll pull down a copy of the current iteration of JSLint on a daily basis, and mirror it on GitHub (jslint/mirror). My patches will be pushed to jslint/master (along with QUnit-based regression tests), and I’ll do my best to keep master merged with the latest from mirror, and the changes continually rebased on top of mirror into jslint/rebased for ease of application (in the unlikely event that Crockford pays attention :) ).

I’ll keep the changelog up to date as I add the functionality I find that I need to do my job. If you find the idea useful, I hope you’ll help me out. Reasonable patches most humbly accepted (although my arbitration of “reasonable” might hurt your feelings too).

A JavaScript Detection Pattern

2010-03-06T00:00:00+01:00

Progressive enhancement of our sites and applications has become a relatively well accepted best practice for web development. It simply makes sense to implement core functionality in a universally accessible way before layering new behaviors and possibilities for interaction on top via JavaScript.

This implementation model has one drawback that we need to consider. If we render a basic version of a module before reworking it with JavaScript, it’s possible that visitors would briefly be exposed to the unenhanced module, only to see it morph into something new before their eyes. This distraction is especially likely when we consider the well-known performance benefits associated with loading JavaScript at the very bottom of a page. The page as a whole will load well before JavaScript is completely parsed and executed, leaving a space of time during which the raw versions of your modules are visible.

To avoid this issue, I'd suggest inserting the following code directly after opening your page’s body element:

<script>document.documentElement.className += " js";</script>

When a visitor comes to the site with JavaScript enabled, this snippet will add a js class to the document’s root node (in most cases, the html element). This gives us a styling hook that allows us to generate CSS rules that only take effect when JavaScript is present. Prefixing rules with a .js selector ensures that they only apply when this script has executed, meaning that the visitor must have JavaScript enabled in her browser. We can use this information to pre-style the widgets in preparation for the JavaScript manipulations we’ll do later on.

I've put together a demonstration of this JavaScript detection technique in action. It’s worth visiting that demonstration both with and without JavaScript enabled, simply to get a feel for what’s possible. It’s not a perfect solution (JavaScript could error out somewhere in the middle of the page, for instance), but I find it to be a reasonable compromise that avoids distracting flashes of incompletely styled content.

That demonstration, however, is pretty abstract. Let’s look at a more practical example of how this could improve a site’s usability. Take Twitter, for instance: with JavaScript enabled, clicking on the “Sign in” button in the top right-hand corner of the page exposes the login form, which is otherwise hidden away. Without JavaScript, the form doesn’t show up at all, users are instead directed to a separate page that just displays this form.

This is a reasonable fallback, all things considered (and certainly better than sites like CNN, whose login link goes nowhere without JavaScript). Still, I see it as a missed opportunity as the login form’s HTML code is delivered to the user on the homepage regardless, it’s simply hidden by default. I think a better decision would have been to design the page such that the login form shows up for all users, and is simply presented differently for users with JavaScript.

I've implemented a demonstration of how this might work by copying down the Twitter homepage’s code, adding the JavaScript detection snippet from above, moving the login form HTML lower down on the page, and adding a few lines of CSS to make things halfway usable (a caveat: the twitter demo looks good in Chrome/Webkit, decent in Firefox, and miserable in IE: Twitter’s HTML is dependent upon server-side browser detection, which I'm not going to attempt to recreate here.). I'm no designer, but it seems like a step in the right direction to me, and adds a bit of bulletproofing with next to no effort expended.

With this in your toolkit, I don’t think there’s any excuse for mandating a hard requirement for JavaScript for most interactive widgets. Certainly complex applications would be hard-pressed to come up with ways of presenting the same functionality to all users, but I think we can all agree that “simple” functionality (like logging in) should be equally available to everyone, and we should absolutely take that into account when building websites.

Update: Tim Huegdon mentioned, rightly, that class isn’t actually a valid attribute on the html element, and that it might be better to set the js class on the document’s body element instead. It’s a valid point, one which ought not be ignored out of hand. I'm sticking with document.documentElement for a simple reason: I know it works stably in every browser I've tested (IE6+, FF2+, Safari 2+, Opera 9.5+). I've heard anecdotal evidence of problems in IE caused by manipulating the document’s body while it’s loading (“Operation Aborted”, and the like), which I've never experienced with this technique, and which I'd like to avoid.

Update to the Update: Martijn van der Ven notes, also rightly, that HTML5 allows class attributes (as well as all other global attributes) on the html element. One more reason to switch over to the HTML5 doctype, if you ask me.

CSS Rules of Thumb

2010-02-22T00:00:00+01:00

Apropos of nothing, a few CSS tips that have nothing to do with browser incompatibilities, and everything to do with your own sanity when dealing with code you've written:

Comment your CSS files

This is incredibly basic advice that I don’t think is taken at all seriously enough. I've made an effort over the last few months to begin every CSS file I write with a comment block that looks something like:

/**
 *  Title of the CSS file
 *
 *  A Brief description of the CSS file's contents, and, if
 *  relevant, it's dependencies.  This should generally only
 *  be a sentence or three long, anything more, and the file's
 *  almost certainly attempting to do too much.
 *
 *  <pre><code>
 *      <div class="the markup this css file expects">
 *          You'll be ever so happy you included this part
 *          in about three months, when you come back to this
 *          project, having completely forgotten it's
 *          structure and purpose.
 *      </div>
 *  </code></pre>
 *
 *  @author     Mike West <mike@mikewest.org>
 *  @package    some_greppable_name
 */

This is the basis upon which you can start writing reasonable CSS rules that you have a good chance of understanding the next time you read them. Especially the expected markup. You may think that’s overly verbose, and simply overkill for most projects, but without it, you’ll get lost when trying to map the file’s CSS to anything at all on the actual website you’re coding.

It’s important to put as much context into the CSS file as possible, because CSS is a complex language when you use it the way you’re supposed to. The more you rely on the cascade to reuse code and concepts, the more you’ll come to rely on good documentation to keep your bearings.

Write many, highly specialized CSS files

The general rule of thumb about documenting your code has a corollary: you should use lots of CSS files. You should be able to pick up a small, focused chunk of code, read through it, and understand more or less how it fits into the site as a whole. If it depends on some other chunk of code, that code should be referenced, but not included in the same file. Here’s why: long CSS files are opaque, confused, and unstructured. I don’t care how disciplined you are: this is true 100% of the time, without fail.

If you find yourself sifting through a CSS file, trying to figure out where best to stick a new bit of code, you’re simply doing it wrong. The fewer CSS files you have, the larger they’ll be, and the more tempted you’ll be to simply stick some new rules on the end to save time. You’ll do this because your teammates are doing it, and they’ll do it because you’re doing it. This is the path to poor code quality, poor code reuse, and simple insanity.

In short, I see long CSS files as the broken windows of web development. The longer and more convoluted the file, the more likely even the best developers are to simply make it more confused.

Name your files well

To whatever extent possible, you should develop a naming convention to make a file’s purpose clear, minimizing the chance that you’ll have to go looking for a good home for new code.

For example, on my current project, I've written a lot of modules that are all based upon the same root class. The markup might look like:

<div class="basebox">
    [Module basics go here]
</div>

<div class="basebox special">
    [Module basics, plus "special" markup go here]
</div>

basebox.css defines the presentation of the features common to all “Basebox” style modules. In that file’s documentation block, I'd define a @package of “projectname_basebox”. The “special” presentation is then defined in basebox_special.css, with a @package of “projectname_basebox_special”. The filename makes dependencies clear when determining import order, and the @package marker makes dependencies clear inside the file (and available to grep).

Style guides are good

You should organize a style guide for your team, and stick to it. As with any language, it’s helpful when your whole team speaks the same dialect. Insofar as that’s true, I think it’s more important that you agree on a set of rules defining how you write CSS, rather than my set of rules. The more your CSS looks like your neighbors, the more likely she is to understand your rules quickly when she needs to change them (and the more likely you are to understand rules you wrote months ago…).

That said, you should of course all write CSS like I do. Because it’s the right way. Here’s how and why:

Selectors are to be written in order of specificity, and nested according to the site’s markup. Given a basebox module:
```
<div class="basebox">
    <div class="header"></div>
    <div class="body"></div>
    <div class="footer"></div>
</div>
```
I'd expect to see CSS code that looked something like:
```
.basebox {
    /* Properties go here */
}
    .basebox .header {
        /* Properties go here */
    }
    .basebox .body {
        /* Properties go here */
    }
    .basebox .footer {
        /* Properties go here */
    }
```
I'd argue for this format for the same reasons that indenting a “real” programming language makes sense: it’s easier to understand a file’s scope when selectors are nested (this, incidentally, is another reason that multiple CSS files are beneficial: each file’s “scope” begins anew at the left-hand column).

This also operates on the principle of least surprise. I expect to see the most general rules first, and to work towards more specific rules at the bottom of the file. I think most developers would agree.
Properties are written one per line. Period. I consider this self-evident, and I'm always shocked when otherwise intelligent people argue with me about it. Writing properties one per line has two distinct advantages:
1. Selectors with more than two or three properties don’t require horizontal scrolling. Nor do they require maintaining a parse tree in your head while reading code.
  
  To make this point more clearly, I’ll cherry-pick a horrid example out of Nicole’s OOCSS (Hi, Nicole! Sorry I'm picking on you! :) ):
```
/* This is unreadable */
.lastUnit{display:table-cell;float:none;width:auto;*display:block;*zoom:1;_position:relative;_left:-3px;_margin-right:-3px;} 

/* This is less so */
.lastUnit {
    display:        table-cell;
    float:          none;
    width:          auto;
    *display:       block;
    *zoom:          1;
    _position:      relative;
    _left:          -3px;
    _margin-right:  3px;
}
```
2. Properties written on more than one line make version control (which generally operates with line-based diff presentation) much more user friendly. If I ever had to resolve conflicts in a file with 100+ character lines, I think I'd simply rewrite the rule rather than spend the time to figure things out.
All that said, I do find single-line rulesets acceptable (and, in fact, preferable) when writing long runs of single-rule groups. Sprite definitions are the canonical example. It simply makes sense to write code like:
```
.sprited li {
    background: url(/path/to/sprite.png) no-repeat 0 0;
}
    .sprited .s1 { background-position: 0 -20px; }
    .sprited .s2 { background-position: 0 -40px; }
    .sprited .s3 { background-position: 0 -60px; }
    .sprited .s4 { background-position: 0 -80px; }
```

Properties are formatted for readability using 4-space tab stops. Readability improves when the eye has a clean line to jump to. Again using Nicole’s code as an example, would you rather read this:

.lastUnit {
    display: table-cell;
    float: none;
    width: auto;
    *display: block;
    *zoom: 1;
    _position: relative;
    _left: -3px;
    _margin-right: 3px;
}

Or this:

.lastUnit {
    display:        table-cell;
    float:          none;
    width:          auto;
    *display:       block;
    *zoom:          1;
    _position:      relative;
    _left:          -3px;
    _margin-right:  3px;
}

I don’t think it’s much of a contest.

Properties are written in alphabetical order. This also helps keep diffs sane, as you no longer get into fights about which rules should be written together.

Browser hacks are inline, and documented. Taking Nicole’s example above, I'd expect to see (at least) two comment blocks, explaining the rationale behind the various IE hacks:

.lastUnit {
    display:        table-cell;
    float:          none;
    width:          auto;

    /**
     *  @HACK:  Giving `haslayout` to IE 6 and 7 via the
     *          `zoom` and the star hack.
     */
    *display:       block;
    *zoom:          1;

    /**
     *  @HACK:  Something IE6 specific that I don't understand
     *          because it wasn't documented.  Maybe it's in a
     *          wiki somewhere?  Who knows.  Danger!
     */
    _position:      relative;
    _left:          -3px;
    _margin-right:  3px;
}

This is, of course, more verbose, and will take up some of your valuable time. I don’t care. Write the comments anyway. You’ll need them later on when you've forgotten why you wrote them. Labeling your hacks makes you think about and justify them, and makes them simple to remove when you decide to stop supporting broken browsers.

Write code for human consumption

Your code should first and foremost be human-readable. Of course you want to deliver a single combined and minified CSS file to the browser, and of course that means that you’ll have to do some work to transform the nicely readable code you've written into something lean and mean for performance and efficiency (a good place to start would be Tim Huegdon’s article “Website Builds Using Make”).

So don’t worry about the performance penalties to writing long comments, detailing every tricky piece of your CSS. And don’t worry about the performance penalties of splitting your code into many easily understood chunks. There aren’t any. Your build process will combine all your files, and compress them into a single file that’s completely incomprehensible to human eyes. This is a purely mechanical act, and it’s something that should be scripted. Your concern when writing code should be your understanding of that code, not the browser’s.

An Accessible Pagination Pattern

2010-02-09T00:00:00+01:00

Pagination is a basic building block of the web, appearing practically everywhere content is displayed. From a UI perspective, a pagination widget generally ends up being presented in a very straightforward manner as a horizontal list of links, framed by “previous” and “next” links to give the user clear calls to action. Flickr and CNN provide good examples of this general pattern:

Flickr marks this up as a flat series of a tags inside a div, CNN as a ul, containing one li for each page. And those certainly aren’t the only options: while doing a bit of research for a project at work, I came across a much wider than expected variety of markup, and no clear “best practice.”

After thinking about it a bit, and grilling my more intelligent friends, I've settled on a pattern that I think works pretty well. It’s nothing at all groundbreaking, but is certainly worth documenting as a markup pattern I'd advocate. The HTML is straightforward (and an example is available):

<p id="paginglabel" class="audible">Pagination</p>
<ul role="navigation" aria-labelledby="paginglabel">
    <li><a href="#"><span class="audible">%TYPE% Page</span>1</a></li>
    <li><a href="#" rel="prev"><span class="prev">Previous<span class="audible">: %TYPE% Page</span></span>2</a></li>
    <li><p><span class="audible">You're currently reading %TYPE% page </span>3</p></li>
    <li><a href="#" rel="next"><span class="next">Next<span class="audible">: %TYPE% Page</span></span>4</a></li>
    <li><a href="#"><span class="audible">%TYPE% Page </span>5</a></li>
</ul>

I see a few advantages to this markup:

Clear signposting

The widget uses the aria-labelledby attribute to instruct capable browsers to use the contents of the preceding paragraph as a label, and the role attribute to demarcate the ul as a navigation landmark on the page.

These are especially important for visitors making use of screenreaders or other assistive technologies, as they typically have the option of navigating through a page’s content by jumping directly from one list to the next, or from one landmark to the next. In such a scenario, the label and role will be announced before reading the contents of the list, providing essential information about its context and purpose which would otherwise be lacking.

Likewise, the previous and next pages are given rel attributes, making their relationship to the current page crystal clear, and available to any capable parser.
Clear link text

A link containing only the text “1” is more or less useless to a visitor who can’t visually link the text to it’s context. Adding that context is simply done, however, by placing some additional text inside the link. An addition as trivial as “Page 1” makes a huge difference in comprehension. This text can be hidden for sighted users by wrapping it in a span, and positioning it offscreen via CSS. The current page is called out in the same way, providing the visitor with additional context.
Deduplication

CNN and Flickr made the same choice when marking up the widget’s “Previous” and “Next” links. Even though these both link off to items which are also available in the list, the link has been duplicated, breaking the relationship between the visible page number, and the textual label. I'd argue that it’s better to group the two into the same a element, using one link for both elements.

The markup above does just that, placing the textual labels inside the link element itself, making it clear that the previous page is page 2. The presentation of the “previous” and “next” links to the left and right of the list, respectively, can be handled by positioning their containing spans absolutely. This requires approximate knowledge of the text’s size, and can usually be accommodated even in multi-language environments.
Sound over Semantics

For pagination, it seems like it would make perfect sense to use an ordered list rather than the unordered list I've chosen here. It’s almost certainly semantically correct, as the list of pages is indeed ordered, and that order is indeed meaningful.

In this case, however, I think it’s the wrong choice. NVDA (which is the only screen reader I have access to at the moment) reads ordered lists as “One. [List item content] Two. [List item content] …” An unordered list, on the other hand, doesn’t number the items as they’re read. Since I'm explicitly including the page number in the link, an ol simply sounds strange and repetitive: “One. Example Page one. Link. Two. Example page two. Link. …” Assuming other readers like Jaws and WindowEyes behave similarly, an unordered list simply sounds better.

(Thanks to Gareth for the good question that I'd neglected to address.)

I've put together a quick example of this markup at work. I hope you reach for it next time you need a pagination widget.

MacSpeech Dictate: First Impressions

2009-11-19T00:00:00+01:00

I suspect that the first thing any developer does when they get their hands on MacSpeech Dictate is to begin writing a review of MacSpeech Dictate in MacSpeech Dictate. I am no exception.

Over the last three months I've develop more pain than usual in my wrists and elbows. It’s not been painful enough to stop me from typing altogether, but certainly enough to make me stop and think about the amount of time I spend typing at the computer.

My dad has been playing with Dragon Naturally Speaking on and off for quite some time now, so speech recognition software has been on my radar for years. In fact, I suspect he personally financed the software’s research and development over the first few years of its life… Of course the software was initially more or less worthless, its output was simply miserable through the first few versions. But my dad continued to upgrade. Year after year he picked up a new version of Dragon, installed it, spent hours training at, and eventually began to actually get things done using the software. Now it’s my turn.

So, first impressions (beyond the fact that it’s simply strange to talk instead of type):

I'm a little surprised at the delay between my speech and its recognition. It shouldn’t be surprising when considering how much work is involved in this sort of thing, but it is. I speak, and about a second and a half later text appears on the screen. As long as I'm not actually paying attention to the screen, this doesn’t bother me at all. At the moment, however, I'm paying quite a bit of attention to the screen, so it’s a little distracting.

The text is generally correct, so that delay is easy enough to ignore. There is a slider in the preferences that offers a balance between speed and accuracy. I’ll play with that later, as I'm interested in the effect it has on the text produced.
I'm very surprised at the out-of-the-box accuracy. Dictate is doing a much better job than I expected it to, especially given my lack of experience with speech recognition software, and the seemingly insubstantial amount of text used to train the program. I read to it for about 10 minutes total and based on that small amount of training, I'm getting something like 90% accuracy. Reading back over the text that Dictate has produced, I certainly see some issues: it’s not perfect by any means. I’ll need to go back and edit a few portions, but overall I'm impressed.
I need to get used to the command structure. Specifically, I need to train myself to pause before and after commands. Dictate will delete the last phrase when I say “scratch that,” and delete the last word when I say “scratch word.” If I speak too fluidly, Dictate doesn’t recognize “scratch that” as a command. When I make a mistake I have to remember to pause a moment before correcting myself. That’ll take some time to get used to.
Dictate forces me to pay much more attention to the words I choose then I usually do. I normally write very fluidly, editing myself as I go. I’ll write half a sentence, jump back to the paragraph before to make a change, delete the sentence I'd started, rewrite the sentence, and start again. That process simply doesn’t work with speech recognition software. It’s much more difficult to jump around in the document, so it’s much more important for me to address a topic more linearly. I have to think before I speak, which is new to me.

Overall, I like this. I think it’s something I can get used to. It’s certainly better on my hands and wrists, and that’s something I very much appreciate at the moment. So far, it’s looking like a worthwhile purchase. Let’s see how I feel about a week or two.

A note on process: I dictated this document via Dictate in a bit more than half an hour, stopping relatively often to figure out exactly what I was doing. I then copied the text out of Dictate’s notepad, pasted into a real editor, and cleaned up the text. I'm not thrilled with workflow, but it’s not bad. Much less typing, which I'm certainly happy about.

My Jekyll Fork

2009-11-12T00:00:00+01:00

Jekyll is an interesting project, a well-architected throwback to a time before unnecessary dynamism reigned supreme. In contrast to blog engines like Wordpress or Textile, Jekyll doesn’t attempt to do anything other than push raw content through a few simple filters out into the world in the form of static HTML files. Jekyll’s publication philosophy is very much in line with my own, and I appreciate the work that’s gone into it. It’s relatively widely used, and therefore much more stable and well-tested than anything I'd write on my own. Given my recent experience, I want something that will Just Work™, and this looks like it. I finished moving this site to Jekyll yesterday, and I'm quite happy with how it’s working…

It doesn’t fit me perfectly, though. Here, I’ll point to a few features that I think are missing, and a few design decisions that I think are worth reconsideration. Happily, it’s an open source project, so I’ll also be able to point to my fork of the project where I'm busy addressing these shortcomings.

“Generated” Pages: Tags and Archives

The biggest gap I see in Jekyll’s feature set is support for “generated” pages (covered in Issue #16). HTML that Jekyll produces is tied one-to-one with files you create on the filesystem. This has the appeal of simplicity, fails in a number of ways to support two quasi-dynamic things that I consider essential to the kind of sites Jekyll aims to produce: tags, and archives.

Tags are a nice way of grouping content on a site, and surfacing that content to readers in an unobtrusive way. Jekyll, out of the box, does a miserable job of making them available in templates. site.tags gives you a list of all the site’s tags, page.tags gives you the tags for the current page, and that’s it. That’s simply not enough structured data to do anything useful with; I want more. “More”, in my case, meaning two things: a separate page for each tag at /tags/[TAG], listing each article that fits; and a page listing out all the tags on the site (in cloud form, if only because I'm so Web 2.0). The latter is (painfully) possible out of the box, the former is not.

My solution (based heavily on Matt Flores‘ fork) is available in the tag_index branch of my Jekyll fork. The implementation is very low-impact: simply add a tag_detail.html layout to your site’s _layouts directory. Jekyll will auto-generate pages using that layout for each tag on your site, providing page.tag as a variable inside each as they’re rendered. This allows you to dive into site.tags to pull out lists of articles in a very straightforward way. Once rendered into HTML, the result is placed into a directory you specify via a configuration variable (tag_root). This has worked brilliantly for me here on this site.

Archive pages listing out content written during a certain period are another nice way of dividing up posts on a site. Especially useful for sites with more than a few posts, it’s a mechanism for showing users posts that fit together temporally. It’s nice to be able to see all of 2007’s posts, for instance. Or all posts from November of 2008.

Again, I borrowed a bit of code from Matt Flores, brought it up to date with the latest Jekyll tag (0.5.4 at the time I'm writing this), and check it into the archive branch of my fork. Similarly to the tagging system above, archives depend on adding a few extra layouts. archive_yearly.html, archive_monthly.html, and archive_daily.html are supported, and offer page.year, page.month, and page.day, which can be used to reference posts in site.collated_posts. My archive_monthly.html is indicative of how this can work.

Generated pages are written to /[YEAR]/index.html, /[YEAR]/[MONTH]/index.html, and /[YEAR]/[MONTH]/[DAY]/index.html if posts exist over the specified time period.

Filters

Jekyll uses the Liquid templating engine, which isn’t exactly my first choice. It’s a solid engine, as far as it goes, but it’s no Jinja2. Regardless, Jekyll has built in a number of useful filters that can be used to perform operations on text before it’s rendered. textilize() is a good example of this, running text through a Textile parser, then writing the output instead of the original text. It’s great!

Except, of course, for the fact that Textile is hideous. :) I much prefer to write Markdown formatted text (it’s just easier for me to read, really), so I was a bit miffed when I discovered that a Markdown counterpart to textilize() was simply missing.

A more robust system is being discussed (slowly) in Issue #19. I decided not to wait for a perfect solution, and simply added markdownize() in the filters branch of my fork. A trivial, but very necessary change.

Default Configuration Values

I really like the way that Jekyll expects posts to be formatted. Each post lives in it’s own file, and each file begins with a YAML block specifying metadata such as titles, teasers, and layout style. This allows you to configure each post separately, and lends quite a bit of flexibility to the end product.

As Issue #25 points out, it'd be nice if layout in particular could be specified at the site level as a default value. Posts that need different layouts are (generally) few and far between, and a global configuration would make the most common case a bit simpler.

Henrik took a stab at a solution to the problem, which I ran off with and improved upon in the post_defaults branch of my fork. I'm waiting on someone to take a look at this work now, but I'm not holding my breath for it to be merged into the official release.

Problematic Design

Beyond gaps in the feature set, Jekyll does one or two things that I simply disagree with.

Jekyll tightly couples content and layout by assuming that both will exist together in a defined directory structure. Leaving a bit of complexity to the side, a typical Jekyll site contains a _posts subdirectory filled to the brim with lovely raw content, and a _layouts directory filled with Liquid-based HTML templates. The former is exclusively concerned with content, the latter exclusively with layout.

For the same reasons that we eventually started building websites without inline style information, separating the concerns of the site’s semantics from it’s layout and behavior, I don’t believe that these bits belong in the same repository. At a minimum, I'd like to be able to deploy a version of my website’s look and feel without worrying about whether or not I tagged the release before or after adding a post. The one activity has nothing to do with the other, and both ought be able to proceed in parallel. Jekyll’s current implementation encourages mixing the two, which I don’t appreciate. Instead, I prefer to run two distinct repositories: one containing pure content, the other containing site-specific layout and configuration. This feels cleaner to me.

The solution I've hacked together is available in the contentpath branch of my Jekyll fork. I've added a single configuration variable (content_root) that contains an absolute path to the directory containing the site’s content. That directory will be parsed in it’s entirety (e.g. no _posts subdirectory is required). If a _posts directory exists in the usual location ([SITE_ROOT]/_posts/) it will be parsed as well to ensure backwards compatibility.

I don’t expect this change to make it into the main tree, as it’s probably not interesting for Jekyll’s main audience of GitHub Pages users who do in fact very much want to deal with a single repository. Moreover, when dealing with potentially malicious users, it’s not a brilliant idea to give them the ability to generate publicly accessible pages from any readable directory on a system. For my use, however, it’s more or less perfect, and I’ll do my best to keep it rebased on top of the latest Jekyll tags for anyone else who’s of the same mind.

Fallow fields, revisited

2009-10-04T00:00:00+02:00

I'm currently in the process of gutting my website, and rebuilding it piece by piece. I suspect I'm doing this to distract myself from the fact that I don’t seem to have anything interesting floating around in my head to write about. “Surely it’s the site’s fault; raze it to the ground!”, the large, simple, and shouty part of my brain tells me. So I build anew (this is possibly ironic, but I'm ignoring that).

Happily, the small, quiet, and generally reasonable portion of my brain agrees with the plan, at least insofar as it’s clear that the current system (fallow) was a solid idea but poorly implemented. The system works, and I'm happy I wrote it. It was a good introduction to Ruby and Git, and a good reason to migrate off the almost-as-inefficient-as-wordpress Textpattern. But it’s failing me in a number of ways, the most important being that I literally forgot how to get content onto the site, and it took me 45 minutes of reading through painfully structured Ruby code to figure it out again. That’s the sort of thing that happens when you don’t touch a website for 6 months.

Rather that catalog the failings of the system I'm replacing (for they are legion), I'd like to touch on the carefully considered bits I'm keeping:

URL structure: Posts live at /[year]/[month]/[URLified Title] which seems more or less perfect to me. It’s meaningful, while containing just enough temporal context to make completely outdated information easy to spot. Moreover, it provides a natural /[year]/ and /[year]/[month]/ for yearly and monthly archive pages. Tag pages live under /tags/[tag], which makes sense, and ad hoc pages have ad hoc URLs (/is/, for instance). This strikes me as a clean setup, one which I can’t see any way to improve upon.
Content storage: The site’s content consists entirely of UTF-8 encoded text files on disk. Text files are simple to work with, and have a more or less infinite shelf life. A site like this one simply doesn’t need a database, a single flat text file per piece of content is good enough. Metadata (title, tags, etc.) is contained in a YAML block at the top of each file. It’s a format that is clear, human readable, and easily parsed, and I'm especially pleased to see that the format I'd decided upon for Fallow matches up quite well against more widely used systems like Jekyll.
Static HTML: Dynamic content doesn’t really exist on this site. I write an article, then post it online. That’s the extent of the processing that particular page needs. The server shouldn’t be working to rebuild an article from last week (or last year!) every time it’s requested, that’s simply wasteful. This site, therefore, generates a page once when it’s created, or when a template changes, and then simply serves that cached copy over and over again. Similarly, overview pages (like tag pages, or current archives) are regenerated when a new article is published, then served straight from disk. On a small VPS, I can serve upwards of 300 static requests per second through Nginx with extremely low load. Textpattern would fall over and die at those absurd traffic levels.
Historical redirects: The (miserable) /blog/id/[ID] URL structure I decided upon in 2005 still works for the content I've kept from that period. The (also bad) /archives/[Title]/ structure from 2007-8 works too. The (not so lovely) Tumblr-generated links for content that used to be at blog.mikewest.org will redirect nicely. All these old URLs will continue to generate nice, clean permanent redirects for the foreseeable future: why make the reader jump through hoops created by my lack of foresight?

So, those are the good bits I'd like to keep going as I rebuild. With the understanding that I'm about to make one of those dangerous “forward looking statements” that I never seem to follow through on as cleanly as I'd like, I expect mikewest.org to be running a new Jekyll-based backend sometime in October. With luck, no one will notice a thing but me. With even more luck, I’ll squeeze out a post or two about the bits of Jekyll I'm adjusting, and the places where it’s falling down completely.

Productivity Or My Lack Thereof

2009-09-23T00:00:00+02:00

I just spent the last half-hour screwing around with my Vim configuration to set up a “more perfect” writing environment. Fullscreen! Eighty columns! Proper line-wrapping! Large, readable font! Markdown syntax highlighting! Spellcheck! Etcetera, etcetera! Hilariously wrongheaded, of course, since I created this environment instead of writing anything. Likewise, I've played around with todo.sh quite a bit in the last week or two (it’s nice), trying to put together a good system for recording my ever-growing list of things I need to take care of. Perhaps there’s a reason that the list is ever-growing.

Building new bash scripts that make recording tasks easier might feel like Doing Important Work, but it isn’t. Not really. This is unfortunately true even when “write new bash scripts to make recording tasks easier” is on my newly created todo list.

This is a long way of saying that Marco Arment is dead on:

The best way to increase your productivity, hack your life, and be minimalist is to stop reading those sites.

Also, hello Internet. It’s been a while.

Mnot's Redbot

2009-05-23T00:00:00+02:00

Mark Nottingham has put together a really useful tool that aids in the analysis of the behavior of HTTP resources. Visit http://redbot.org/, type in a web address, and Redbot will report the resource’s cachability based on the returned headers, and provide a helpful list of recommendations for improvement.

Running it on http://mikewest.org/, for instance, flags the fact that I compress the response if the browser tells me that it can accept compressed content, but that I've neglected to send the proper Vary header to let caches know that the response needs to be negotiated, and cached based on the Accept-Encoding request header. This is useful, especially for actual applications for which it might matter.

So useful, in fact, that I'm forking it to submit some patches. Mark’s put the Redbot code up on GitHub (mnot/redbot), and I've started putting together a command line version based on the web version he’s built.

I've mentioned that I love GitHub, right? This is exactly why. :)

Playing with Placemaker

2009-05-21T00:00:00+02:00

Yahoo’s latest API is really quite cool: Placemaker takes your unstructured data (e.g. any HTML page, RSS feed, etc), and extracts a nice list of locations that your data refers to. It’s a brilliant tool, and I can think of quite a few ways I'd like to use it in the future. Along with their release of a ton of WhereOnEarth ID codes that allows you to make use of Yahoo’s various geo-services, this is a really good day to play with geocoding unstructured data.

So, let’s play:

Accessing Placemaker is simple: assuming that you've somehow managed to obtain an application id, you simply make an HTTP POST request to Yahoo!’s Placemaker endpoint with a tiny bit of data specifying the nature of the data you’re dealing with, and it’s URL. If you like curl on the command line, this might look like:

curl -d 'inputLanguage=en-US&documentType=text/html&documentURL=http://mikewest.org/&appid=[APPID]' http://wherein.yahooapis.com/v1/document

You’ll get back an XML document (RSS is also available as a response format). Digging into the contents yields:

Boilerplate:

<?xml version="1.0" encoding="utf-8"?>
<contentlocation xmlns:yahoo="http://www.yahooapis.com/v1/base.rng" xmlns="http://wherein.yahooapis.com/v1/schema" xml:lang="de-DE">
  <processingTime>0.380778</processingTime>
  <version> build 090508</version>
  <documentLength>15906</documentLength>

A (list of) document element(s) containing the extracted locations:
```
  <document>
```

A best guess at the document’s “scope” (the smallest region that “best describes” the document):

    <administrativeScope>
      <woeId>20071093</woeId>
      <type>County</type>
      <name><![CDATA[Munich, Bavaria, DE]]></name>
      <centroid>
        <latitude>48.1549</latitude>
        <longitude>11.5417</longitude>
      </centroid>
    </administrativeScope>
    <geographicScope>
      <woeId>29388625</woeId>
      <type>MMA</type>
      <name><![CDATA[MMA München, Bavaria, DE]]></name>
      <centroid>
        <latitude>48.1549</latitude>
        <longitude>11.5417</longitude>
      </centroid>
    </geographicScope>

Latitude/longitude for a bounding box that contains the places mentioned in the document (which makes it trivial to draw an “area of discussion” on a map):

    <extents>
      <center>
        <latitude>48.1364</latitude>
        <longitude>11.5775</longitude>
      </center>
      <southWest>
        <latitude>48.0417</latitude>
        <longitude>11.3771</longitude>
      </southWest>
      <northEast>
        <latitude>48.2292</latitude>
        <longitude>11.749</longitude>
      </northEast>
    </extents>

Detailed breakdown of the places mentioned in your document, giving you lat/long coordinates identifying the place’s center point. Moreover, it tells you where in your document the place was found (string offsets and XPath expressions, to each their own). This is helpful for those occasions when the text you've entered doesn’t exactly match the place’s name that Yahoo returns (“Munich” vs. “Munich, Bavaria, DE”, in this example) Annotating your documents with this data should be a piece of cake.

    <placeDetails>
      <place>
        <woeId>676757</woeId>
        <type>Town</type>
        <name><![CDATA[Munich, Bavaria, DE]]></name>
        <centroid>
          <latitude>48.1364</latitude>
          <longitude>11.5775</longitude>
        </centroid>
      </place>
      <matchType>0</matchType>
      <weight>1</weight>
      <confidence>7</confidence>
    </placeDetails>
    <referenceList>
      <reference>
        <woeIds>676757</woeIds>
        <start>50</start>
        <end>56</end>
        <isPlaintextMarker>0</isPlaintextMarker>
        <text><![CDATA[Munich]]></text>
        <type>xpathwithcounts</type>
        <xpath><![CDATA[/html[1]/body[1]/div[2]/div[1]/p[1]]]></xpath>
      </reference>
    </referenceList>

And some more boilerplate. :)
```
  </document>
</contentlocation>
```

Full documentation of the Placemaker query parameters and response format are available on YDN. Christian has put together a demo of a basic PHP implementation (though it’s XSSable, and shouldn’t ever be used in production).

In general, this is brilliant stuff. I'm looking forward to playing with it!