Guidelines for creating better markup

I’ve mentioned several times here that I feel writing markup (or any other code, for that matter) is a craft. I take pride in writing as lean and clean code as possible. From the looks of things there aren’t a whole lot of other Web professionals that feel that way, but we do exist.

One of them is Garrett Dimon, who has touched upon this subject before, and in Markup as a Craft (published at Digital Web Magazine) provides twenty-one guidelines that will help you create better markup. That’s a lot of guidelines, but they are all relevant and contain very good advice. Highly recommended reading.

After reading Garrett’s article I couldn’t resist creating a list of what I think are the six most important guidelines for writing better markup:

  • Keep it simple. Keep your markup as simple as possible, which is often simpler than you may think at first.
  • No layout tables. This is obvious to anyone who has not been living in a cave for the last several years. Unfortunately, the caves seem full of Web developers. Tables are meant for marking up tabular data, not creating layouts. Use CSS instead.
  • Avoid classitis. Does every element you want to style with CSS have a class attribute? They almost certainly do not need to. Use descendant selectors instead.
  • Structure and meaning first, presentation later. Focus on semantics and document structure while you are writing markup. Save the presentational thinking for when you are writing your CSS.
  • Know all HTML elements and attributes. Go through the Index of Elements and the Index of Attributes in the HTML 4.01 Specification. You will probably make some new acquaintances. Read up on them and learn when to use them.
  • Validate, validate, validate. The markup validator is your friend, not your enemy. Anybody can make typos or mistakes. The validator will help you catch them and improve your markup.

What would your most important guidelines for writing better markup be?


This article has been translated into the following languages:

Posted on April 12, 2007 in (X)HTML, Quicklinks


  1. Nice tips :D

  2. Totally agree with point 3. I have been weaning myself off classitis for a while. Its so much more clean to use decendant selectors.

  3. Word.

    Can’t wait for HTML 5 or whatever. Just imagine, new elements! We won’t know what to do with ourselves.

  4. I think points 1 and 4 go hand in hand to be the most important. By keeping things simple and not thinking at all about presentation whilst writing your markup, what reasons could there be for creating bloated, invalid code?

    Nice tips, thanks!

  5. Much akin to the classitis guideline:

    Avoid divitis (and spanitis). Don’t use a semantically neutral element when a more meaningful one might be appropriate. Wrapping everything in a div or span just so you can later style those elements with CSS is strictly presentational thinking, and contributes nothing to the meaning of the content.

  6. When curing oneself of classitis, it’s always important to remember the effects of specificty on CSS rules. When you replace a singe ID or class name with a chain of descendants, it can have an impact on how the rules get applied.

  7. Very much agreed with learning all HTML elements and attributes! It’s actually kind of exciting to find out that a semantic element exists that you never knew about, like the or tags.

  8. April 13, 2007 by Chris O'Neill

    As well as avoiding extra IDs and CLASSes, something I overlooked for the longest time was the ability to use any old block-level element instead of wrapping markup inside superfluous DIVs.

    There is usually no need for a DIV if you’re already using a UL, for instance. Just zero in on it using descendant selectors and you’re away. Since natively-inline elements can be altered via display:block; you can usually achieve just about anything.

    When I worked that out, it was like realising my shirt had been on inside out all day.

  9. Even though I/we try to make layouts using without tables, it still sometimes brings us to a point where we try to figure out whether its really that important to spend more than an hour just to make the page compatible with IE !!! or just make a simple table layout and get the work done.

    Time is money.

  10. Mulitple body class names is a great way to avoid superfluous id’s and classes in the body of your document. Give a section class name to the body and a more specific body class inside your section and you’re set. Almost no need for non-body classes.

  11. “Unfortunately, the caves seem full of Web developers. “.


    Im a caveman..

  12. Thanks for the nice summary! If only my colleagues would read and heed ;-)

  13. Think these are good and valid points. After receiving a great example from a colleague I also found it very useful to use templates for your code which include several commonly used items and sections. e.g. your CSS would include sections for shared styles, typography, links etc. These can be easily divided using comments. This not only saves time but, once you’ve perfected it, means you are using consistent conventions which makes future editing easier.

    PS - tables are evil (and for displaying data).

  14. Some additional guidelines:

    1. If you tell people you write your markup using divs instead of tables, you don’t get it. Go read up on semantics.

    2. The DTD does NOT specify the type of document you’re writing. So no, that’s not XHTML, it’s malformed HTML. Learn about parsers and find out they don’t care about your DOCTYPE (don’t take named entities for granted).

    3. Know your character sets. If you’re not using UTF-8, know the implications. Which characters are supported, which are not? Am I actually saving my document using the UTF-8 encoding, or just plain ol’ Windows-1252? When using UTF-8, should I include the BOM?

  15. Writing good markup is a craft, writing good markup and style is an art, writing good markup and style that works in various MSIE versions is sheer impossible.

    Too bad ‘the blue e’ still dominates the browser market; I guess we developers will have to choose: (in order of my preference) 1. more or less drop MSIE support or 2. produce a little more kitsch and a little less art

  16. April 13, 2007 by Johan Kronberg

    I miss some notes on your (and fellow readers) current preferences when it comes to naming of ID’s and Classes. I’ve seen so many… If I get to choose I prefer as minimalistic names as possible - 3 to 4 letter - typed in lowercase.

  17. Use Firebug, Web developer toolbar and HTML validator. HTML validator is an excellent firefox extension to see whether a page is valid or not in the blink of an eye. For example, it says this page is valid, but the google ads are not.

    If something doesn’t display correctly on your site, validate first, then go bughunting.

  18. I would say one of the most important tips is to practice.

    When I first started there were spans, divs and classes everywhere. It wasn’t because I wasn’t trying, its because I didnt really appreciate the power of CSS and I didn’t have a strong knowledge of HTML elements and attributes.

    I have noticed as I have done more and more my markup has become leaner and more semantic. Now I am pretty good at it (if i do so say myself!)

    I find myself watching my colleagues make markup and i ask “Why are you putting a DIV round that?” The answer: Oh i need to do this style to the thing inside. I promptly correct them :p

  19. One of my rules would be to not be afraid of the DIV. Not an apology for diveritis, but some people avoid them as the plague and cry foul whenever they see a few spread around in someone else’s code.

    I often use it to group certain elements in my markup phase and not even for styling, but because I think that certain things should be grouped. For example a subchapter of something, containing a H# element and paragraphs. Then put a unique ID on that DIV and you have a portion that can be referred to in a URL.

  20. Reading the markup Technician Recommendations is very useful as is having the correct browsers to hand.

    The ‘Firefox HTML Validator’ is extremely useful; I spotted a few bugs so contacted Marc Gueury, and he said he was putting them onto his “bugs to solve” list - they were pretty significant findings if you use real XHTML.

  21. Your suggestion of structure and meaning first is, in my opinion, invaluable. It no only makes you think about the presentation of the unstyled page, but also allows you to utilise the mark-up that already exists before adding extra code for presentation.

  22. It’s funny how at first a list of tips like this at first seems obvious. However, when you really think about it, there’s quite a few ‘professionals’ that really need to read this. Nicely done!

  23. @Kris (#19), who said: “I often use it to group certain elements in my markup phase and not even for styling, but because I think that certain things should be grouped.”

    Bravo, that’s exactly what a div is for, and is correct semantic markup. A division simply means “these elements belong together and are separate from other elements.” It’s multipurpose and semantically neutral in that it doesn’t designate any specific type of content, but it’s not entirely meaningless.

  24. I for one only try to use divs to separate the sections of my page, this normally takes the form of header, nav, content, & footer. Anything on top of that I try my best to avoid.

    @16 When naming classes and ID’s you should ideally aim for a semantic name such as maindiv or header, names such as smallbluetext or biglink do not convey any semantic value, and can cause problems when you redesign.

  25. @24 Steve ‘header’ and ‘footer’ aren’t really that semantic - they imply position (at the head and foot of the page). Maybe something like ‘branding’ and ‘site infor’ could be used instead. If you think in terms of only using divs for these sections then you are constraining yourself - just use the div for any natural divisions in the document as Craig C (#23) says - it is for all divisions and has some meaning, so it should be used as appropriate.

    Using Tantek Celik’s compounds and microformats help to add more semantic meaning to your html and gives you more ‘hooks’ when it comes to styling the document.

    Microformats do add a lot of spans and classes, but I think that they are worth it for the extra information that they give.

  26. April 14, 2007 by Roger Johansson (Author comment)

    ‘header’ and ‘footer’ aren’t really that semantic - they imply position (at the head and foot of the page).

    To me they imply position at the start and end of the file, so I think “header” and “footer” are fine. I have never liked “branding” as an id, though I know there are many who use that.

  27. I take your point Roger about ‘header’ and ‘footer’ - and they are becoming ubiquitous in their usage, so maybe not such a bad thing. ‘branding’ does have a very corporate feel to it, are there any other possibilities?


  28. April 14, 2007 by Scott

    I have a guideline which I think is important but was not included in Garrett’s list:

    Write markup that is human-readable. Makes it a lot easier to go back and make improvements as you change your mind about the best way to do things.

    For those who argue that code should be condensed to reduce download times, you could do that for your live version but keep your development version readable.

    To those who complain about MSIE and want to stop supporting it, I mean no offense, but isn’t that attitude a little hypocritical? Not that much different from the people who only support MSIE to the exclusion of all others. We’re supposed to be creating markup that works cross-browser to give everyone a decent experience. That doesn’t mean it has to look identical in all browsers. I’m also not saying we should support all versions of every browser; the one or two most recent versions of the five or so most popular browsers is probably enough.

  29. April 15, 2007 by Normand Lamoureux

    Two more guidelines may be hepful:

    1. Separate CSS and Scripts from HTML.

    2. Indent and comment your code for future readability.


  30. April 15, 2007 by Roger Johansson (Author comment)


    ‘branding’ does have a very corporate feel to it, are there any other possibilities?

    “masthead” perhaps? I can’t think of any others.

  31. April 25, 2007 by Happy Harry

    Great list. However, here’s another little guideline.

    I know, it’s self-explanatory and implied in this discussion, but it’s REALLY important to “hand code”.

    There are a lot of great HTML editors out there, and most of you have one of these installed on your machines. Be that as it may, you must “resist” any temptation using them as long as you’re still learning to code (or thinking there’s room for improvement for you). Sure, you never cease to “learn”, no matter how good you are. But until you really get the hang of it, stick to hand coding. Use a simple text editor, such as Notepad or, better, EditPad Lite (which I am using) when creating websites.

    When you hand code using a simple text editor there’s no safety net: no auto-completion of tags, no hints, nothing to help you write your markup. So you’re on your own, and you start looking things up in books, finding solutions, improving your typing speed - all part of the learning process. Plus, chances are you’ll really dig the whole thing and become as obsessed with lean, clean and semantic markup as Roger. :)

    You don’t become a better HTML author by using Dreamweaver. YOu become a better HTML author by rolling up your sleeves and hitting the keys on your keyboard.

    So, take this advice: hand code, hand code, hand code. Give yourself this little treatment. You won’t regret it - I promise.

    And later on, when you’ve gotten REALLY good (and for projects) you can use powerful HTML editors, such as Dreamweaver, to automate and speed up the development process. But till then…well, you get the idea…

    Happy Harry

  32. Hi,

    a good list of principles to work after, I agree with you in all of the points.

    But someone (boss, customer,…) will ask:

    Why take the extra time and validate?

    I guess this has been discussed many a time before, but I still wonder what to answer…

Comments are disabled for this post (read why), but if you have spotted an error or have additional info that you think should be in this post, feel free to contact me.