HTML Abstractions

 Jade, Markdown, and Others for Fun and Profit

So picture this horrendous scenario: you are wrapping up some front-end work on a moderately sized website, say 10-20 pages of content, a few standardized layouts between them, and you were even wise enough to create a standard style library for use across the whole site. Smart cookie! You assumed because the client didn’t need dynamic content as this was an informational “brochure” type site that you didn’t need to work about partials, includes, or any other that other node/express nonsense. Deployment is tomorrow and the client gets a look at the latest build and decides to arbitrarily to change the layout arrangement of the content on 3 of the product detail pages and, oh, he wants a picture of his cats in the footer on every page! He’s also sending new content for all of the page descriptions, and is PowerPoint alright? Uh oh, you didn’t anticipate that his brother’s psychic was a UX expert/copywriter/designer and wanted to weigh in!

Cats all the way down.

Sure you can change all of the markup before deployment. But that’s a lot of rearranging content and dangerous copying and pasting, especially when its 1:30am and you are looking at what has turned into a hairy nest of tags within tags within tags, hastily written and rewritten to maintain semantic integrity. You think back to when you first scaffolded the project, foolishly dismissing using a templating language like Jade for structuring content, or Markdown for enforcing formatting rules for content types. Let’s rub some salt in those wounds try and prevent this in the future shall we?

 Jade: A Machete to Cut Through the Jungle of Tags

First things first: let’s look at a quick visual comparison of a typical Jade document up against its HTML counterpart:

Jade versus HTML
Note the document length along the side. The Jade document is considerably shorter. Jade’s whitespace-awareness cuts down on nesting headaches even if Sublime Text keyboard shortcuts flow through you like The Force.

Let’s run through a few quick code examples that show off the ease of writing like this.

doctype html 
        meta(name = "description" content="Totally rad description of the page!")
        link(rel = "stylesheet" href="css/main.css")
        h1 Its time for a header!
        p Here's some body content! Red Button!

Outputs to:

<!DOCTYPE html>  
        <meta name="description" content="Totally rad description of the page!">  
        <link rel="stylesheet" href="css/main.css">  
        <h1>Its time for a header!</h1>  
        <p>Here's some body content!</p>  
        <button class="red">Red Button!</button>  

You can see that even in a simple document, Jade’s markup is considerably tidier. Inserting attributes has a standard layout and order that is easily visible and there is no need for closing tags. Indentation is important and helps enforce a clean document structure.

 Modular Site Design: Designing Systems, Not Pages

Another feature of Jade (and its templating friends HAML and Angular templates) is that you can break layouts up into more manageable chunks.
Using something like this is a big improvement:

doctype html
  include includes/head
  include includes/header
  h1 My Super Modular Site
  p Hot diggity dog!
  include includes/foot  

Using something like this helps manage a standard document head, global navigation, and a global footer. This solves your client’s cat conundrum in one quick code update and any lingering style or metadata issues in another.

Diagram of Jade's include system

This keeps code chunks manageable. In the print world, this would be akin to using a lot of linked resources in something like an InDesign document. Magazines, books, etc. are beasts from an asset/content management standpoint. It helps to break everything up into manageable blocks and work in a modular fashion and have one central document where the blocks are pulled in when it comes to publishing.

Extending this analogy back to the web, it is easy to see that with a bit of dynamic content insertion, it would be possible to even change the layout of certain pages using this system. In short, you are designing a system, not a page:

Modular site design using templating

If you are feeling particularly ambitious, you could even break larger layouts into smaller chunks and dynamically pull in chunks of content.

 Gotta Markdown to Markup

Going back to our nightmare scenario posed earlier, how would you tackle having to plug in content changes when the client or content strategist is providing copy in oddly-formatted ways? There are various strategies for enforcing content standards and this article isn’t going to go into the messy politics of educating clients other than to say that these kinds of projects lend themselves to collaborative environments. A good first step to working with writers or content providers is to write content in properly formatted Markdown documents.

If you are not familiar with it, Markdown is an abstraction of HTML. That is, much like Jade, it provides a very accessible, clean, and distraction-free way to dive into generating content without messing with tags, elements, or any of that fun stuff. In the end, it provides easy-to-parse content that can be easily styled and incorporated into a site without having to fix or rewrite any lost semantic meaning on import. The easiest way to get a feel for it is to check out a good cheatsheet like Adam P’s Markdown Reference.

 There’s an Easier Way

This is all a pretty basic introduction to some of the concepts of abstraction and modular design. Here are some additional resources to help add more tabs to your already overburdened browser window:


Now read this

Graceful Degradation vs. Progressive Enhancement

Browsers or Content I’ll admit it: I came from a world and a time where some of my first experiences designing for the web were soured by having to tweak my oh-so-perfect layout to “dumb it down” for older browsers. I’d get so frustrated... Continue →