5 Top Tips to Beautify Your HTML and Enrich Your Content

It may be surprising at first, but some of the biggest differentiators of good code and great code are actually all the little things. The absence of such “little things” can turn what would otherwise be beautiful markup into something that looks like it came from a Microsoft Word export. Here are 5 of the more-important-than-you-think things to help your markup go from decent to gorgeous.

Key Takeaways

• Use the shortest URI possible to improve portability and optimization of your code, and to increase the likelihood of reusable code in the future.
• Consistent use of markup patterns can improve code legibility, functionality, and reusability, while minimizing the use of class and id attributes can keep your markup leaner and style sheets easier to understand.
• Enrich your content by adding title attributes and other metadata to provide supplemental information and enhance user interaction.
• Improve code readability and ease maintenance by using comments to denote closing tags of elements and maintaining consistent whitespace throughout your code.

Use the shortest URI you can

Whenever you make a link, add an image, or write anything that references a different file on the Web, should you use a relative URI, an absolute one, fully-qualified URIs, or…? Variations of URIs are so common that people rightfully ask “which one should we use?”

A simple rule of thumb is to use the shortest value you can. Shorter URIs are likely to be more portable and they have optimization benefits, too. There’s little reason to encode a link with a URI such as http://example.com/my-page/ when /my-page/ will do. If your domain name changes in the future and you’ve used a fully-qualified URI, you’ll end up with a broken link. If you’re linking to a remote domain, then unless your own content will be published over multiple protocols (like https: in addition to http:), you can even safely omit the scheme portion of a URI.

In this sense, a URI can be thought of as a mini-language of its own. Using the shortest one you can benefits you by providing a higher likelihood of reusable code later on, a phenomenon explained by the Rule of Least Power.

Use markup patterns consistently

Patterns are an extremely powerful technique that improves code reuse, legibility, and functionality. At their core, microformats are simply well-established and widely-understood markup patterns. Their functionality is actually derived from the ability to send batches of these patterns to processing tools.

Even if you don’t use microformats in your own markup, you’ll benefit by using your own patterns consistently. For a dramatic example, just imagine the nuisance of having to deal with a site’s logo marked up differently on each page. On the home page you might have <h1 id="logo">…</h1> and on an article page maybe you have <img id="sitelogo" … />. You’ll likely end up grouping CSS rules to cover both cases and adding extra code into scripts in an effort to remain unobtrusive. That’s nightmarish!

So a pattern can begin as humbly as using the same markup for a site’s logo, but it can become more valuable to you the more conventions you stick to. If you’re going to use <div id="Header">, then you shouldn’t use <div id="ftr">. At SitePoint, for example, blocks of code are always marked up the same way (using <pre><code>…</code></pre>), making it possible to layer style and behavior on top of those elements in a uniform way, site-wide.

Minimize uses of class and id attributes

One benefit of patterns that can be easily overlooked is that—when they’re well designed—they radically improve the structure of your markup. This, in turn, reduces the need for you to use IDs or classes in elements in order to style them, which keeps your markup leaner. It also keeps your style sheets easier to understand, since your CSS selectors will use the structural context of the markup to provide the same context in CSS files.

In fact, avoiding IDs and classes all together can be a very instructive exercise. If your markup is well structured, then you can achieve a surprising amount of the styling you need to using the humble descendant combinator. As support for CSS selectors that use structural context improves (like :last-child, and :only-child), the need for arbitrary styling hooks is further reduced.

This has an inherent tension with the previous tip: if you rely too heavily on the structural context of your markup, then you may find yourself adding unnecessary elements to accommodate your style sheet. Walking the line between these two extremes is precisely the challenge of creating well-structured, semantic markup.

Add title attributes and other metadata to enrich content

Despite its limitations, HTML provides a number of mechanisms with which you can add metadata or additional content inside your markup. Few web pages take full advantage of them, but on those that do, the user is treated to rich, layered interaction using nothing fancier than core HTML elements and attributes. A prime example of this is the title attribute.

Links (that is, anchors, or a elements) aren’t the only things that can be given a title attribute. It can be applied to elements like blockquote, ul, pre, and myriad others. Just as they do for links, title attributes often show up as tooltips when the user hovers their cursor over the element, and in all cases they are intended to provide some kind of supplemental information to the element.

You can make use of this metadata in a variety of ways, including semantics of course, but also for interaction possibilities. For example, if you’re quoting a speech, consider using markup like this:

<blockquote title="Text of Barack Obama's Inaugural Address" cite="http://news.yahoo.com/s/ap/20090120/ap_on_go_pr_wh/inauguration_obama_text">
    <p>My fellow citizens:</p>
    <p>I stand here today humbled by the task before us, grateful for the trust you have bestowed, mindful of the sacrifices borne by our ancestors. I thank President Bush for his service to our nation, as well as the generosity and cooperation he has shown throughout this transition.</p>
    …
</blockquote>

When the user’s cursor hovers over this quotation on your page, they’ll be presented with a tooltip that reads, “Text of Barack Obama’s Inaugural Address,” adding some depth to their experience. It’s as though you’re inviting them to actively explore and uncover more about your content. Further, with a CSS rule such as the following, you can extract the metadata in the title attribute and display it visually.

blockquote[title]::before { content: attr(title); display: block; text-align: center; } 

Another attribute you can use is the rel attribute. For instance, using rel="external" is a simple pattern with which you can mark links to remote sites. If you’ve written a piece that’s cut up into multiple discrete chunks, such as a series of articles, you can also use the rel attribute inside a link element within your page’s head to provide hints for correct sequential navigation:

<head>
    <title>My Fantastic Article - Page 2</title>
    <link rel="prev" href="/page-1/">
    <link rel="next" href="/page-3/">
    <link rel="index" href="/article-index/">
</head>

Using these additional elements will trigger interfaces such as Opera’s Navigation Bar.

Use comments and whitespace to help readability and ease maintenance

Regardless of a project’s size, hard to read code is one of the most demoralizing things to see. It’s arguably more important that your fellow humans can read your code than can your machines. Therefore, it’s really helpful to pay attention not just to what you code, but how you code, too.

Comments in HTML aren’t often used but they can be to great effect. One simple example is using them to denote the closing tags of elements. For instance, many typical blog templates have lots of nested div elements, like this overly simplified example:

<div id="Wrapper">
    <div id="MainContent">
        <div id="post-1" class="hentry">
            <p>Main article content here.</p>
        </div>
    </div>
</div><!-- Which element does this tag close, again? -->

Of course, in reality closing tags are rarely in close proximity to their opening tags, so it’s often difficult to immediately know which closing tags close which elements. To find out you might spend 30 seconds scrolling up in the file. That may not sound like much, but if you do this 100 times a day, then you’ll spend nearly an hour (50 minutes) doing nothing but scrolling up in text files.

This issue gets even worse if your templates are split across multiple files where a tag is opened in one file but closed in another. Now you’re spending even more time searching for opening tags. Such a case is a perfect situation to use HTML comments:

<div id="Wrapper">
    <div id="MainContent">
        <div id="post-1" class="hentry">
            <p>Main article content here.</p>
        </div><!-- .hentry -->
    </div><!-- #MainContent -->
</div><!-- #Wrapper -->

Consistent whitespace is also important. This isn’t a matter of tabs versus spaces, it’s another example of picking (or inventing) some convention that works for you and your team and then sticking to it religiously throughout the project’s life-cycle. Finally, remember that any whitespace you use in a source template can be compressed in a production version if you use intelligent/automated build systems.

Ultimately, the difference between good code and great code is that all the “little things” are so consistently well-executed that you wouldn’t even notice them. If any of these tips aren’t already habits for you when you write markup, they should be!

Frequently Asked Questions (FAQs) about Beautifying HTML and Enriching Content