A Guide to HTML

Page Sections

Modern web pages are much more than just an “online article.” That may be the main part of the page, but the page will have all types of other content: a logo, search box, navigation links (primary and secondary), breadcrumbs, “share this” buttons for social media, comments, and so on. Moreover, they are placed in global sections of the page: the header, footer, left and right sidebars (which may not be on the left or right in mobile browsers), as well as the main content area (which may or may not have its own header or footer).

All of these things are now standard on web pages, and placed in standard locations on the page. You should try to follow these standards. Pay attention to Jakob’s Law of the Internet User Experience: “Users spend most of their time on other sites.” If your web page does something that differs from the popular standard, users are likely to just get confused, and probably leave. For an overview of a web page’s standard sections and content, I recommend Page Structure and Site Design, part of the Web Style Guide by Lynch and Horton.

Each of these types of content will need some sort of HTML tag to distinguish them. Unfortunately, the modern web page did not exist when HTML 4.01 or XHTML were standardized, so there is only one tag that is used to section the page: the <div> tag. HTML5 added new tags to address this situation. I’ll go over both approaches.

The <div> Tag

This tag is a generic container for content. It is rendered by browsers as a block-level element, with line breaks before and after its content. On its own, it has no semantic meaning whatsoever. Instead, you give it meaning by using its class and/or id attributes. (There is also an inline equivalent, the <span> tag; I’ll go over it in the section on text markup tags.)

By far, the most common use of the <div> tag is to wrap different sections of the page, and the different types of content that go in them. So, for example, the primary navigation links might be wrapped in this tag:

<div id="primary-navigation">

…while the footer section might be wrapped in this tag:

<div id="page-footer">

This is a lot of <div> tags, and unfortunately, it can get worse. Some web designers add even more, for customization purposes. An example: a few years ago, everyone wanted rounded corners, but Internet Explorer didn’t support them. One solution was to create images of these rounded corners (in Photoshop or whatever), and use them as the background image of a <div> tag. But each <div> tag could have only one background in Internet Explorer. This means that there was an extra <div> tag for each corner of every element that needed rounded corners.

CMS’s and frameworks are also somewhat notorious for their overuse of <div> tags. each part of the page is created by a different part of the software (and usually have separate templates), and they’re often individually <div>-wrapped.

This HTML anti-pattern is colloquially called div soup, as a “tribute” to the time when designers wrote tag soup. In some cases, the extra <div> tags could be replaced by tags that are more semantic (like a list); but in many cases they couldn’t. For example, there was no HTML tag to semantically define a page header.

HTML5 sought to change that, and added a lot of tags to mark up different page sections.

HTML5 Page Section Tags

These tags are meant to surround different sections of an HTML page. Of course, HTML5 is still semantic rather than presentational, so they didn’t create any tags that were specific to one type of presentation. For example, there are no “breadcrumbs” or “tabbed navigation” tags in HTML5, since these are different presentations of the same underlying semantic concept (navigation links).

This can lead to some head-scratching, because many of these tags are so semantically “generic,” that matching them to presentational concepts is not immediately obvious. And with certain tags, the semantic meaning of the tag may change depending upon context. This has led to mountains of debate among web designers, and will probably continue until well after the tags are in common use. I’ll go over any details when I talk about the tags themselves.

The <section> tag is a generic tag, which groups some content that is thematically related. Typically, the each section is identified by a heading tag.

In practice, “thematically related” could mean almost anything. It could be a section of a longer article; it could be the sidebar in a three-panel layout. In fact, both of these things are acceptable uses of the <section> tag.

You may think that this makes <section> a simple replacement for <div>, but you would be wrong. If you’re only grouping content for the purpose of CSS or JavaScript selection, then you should use <div> tag. The <section> tag should only be used for major sections that should be in the outline; I’ll discuss the outline below.

The contents of this tag should be an independent, self-contained part of a web page. Examples given by the W3C and WHATWG are a newspaper or magazine article, a blog entry, or a user-generated comment. The main idea is independence: it should be possible to separate the contents of an <article> tag from the rest of the page, and it will still make complete sense. Naturally, the contents of an <article> tag may have things like headers and footers that are separate from the main page’s headers and footers, and contain things like the author information or the time of publication.

If your web page’s content is nothing but one article, then including this tag is redundant. It is most useful when displaying a page with more than one article on it. Examples might be the front page of a blog or a news page, which display numerous recent posts or news items (or summaries of them).

This tag should not be used for sections of a single document; use the <section> tag for that.

This tag’s content is “content that is tangentially related” to the page around it. The WHATWG living standard says that this content is “often represented as sidebars in printed typography,” while the W3C specification says it “is sometimes formatted as a sidebar or annotation or footnote.”

This isn’t entirely unambiguous, and web designers often wonder whether the <aside> tag should be used for sidebars, or should be restricted to things like pull quotes. The W3C wiki entry for HTML structural elements seems to suggest that it might be used for a sidebar, but only if the sidebar’s contents are related to the main content (and not for things like site-wide navigation). If this is not the case (and it probably won’t be), use <section> instead.

<main> (non-standard)
The contents of this tag should be the primary content of the web page. It should be unique to that document, and not include things like primary navigation links, site-wide footers, logos, etc.

According to the W3C, there can only be one <main> section, and it cannot be nested inside a an <article>, <aside>, <footer>, <header> or <nav> element. But according to WHATWG, this is simply another kind of grouping tag; they even say that multiple <main> tags are allowed. The confusion arose because the tag serves the same purpose as the ARIA main role, and there is disagreement about how this role is supposed to work. (See below for a discussion of ARIA roles.)

This is one of the reasons this tag is not yet widely used (although those who do use it seem to follow the W3C spec). The other reason is because it is not supported by Internet Explorer.

This tag specifies introductory content or document navigational aids, usually rendered above the main content.

Each section of a page (and the page itself) can have a <header> tag, so the content should introduce that section’s content. If it’s a header that is shared among all pages in a website, it would include things like a logo, primary site navigation, and possibly a search form. On the other hand, if it’s the header to an <article>, it could contain the article’s title, breadcrumbs, and possibly author and date information.

This tag specifies information that should be in the footer section, usually rendered below the main content.

Like the <header> tag, each section of a page can have a separate <footer> tag. For example, each <article> could have a <footer> that includes author information and social media sharing buttons. But in addition, every page on the website could have a common <footer> that could include general copyright information, a blurb about the site’s owners, or a simple sitemap.

Oddly, the W3C recommends that you do not place actual footnotes in the <footer> tag. (These would be publishing footnotes, the kind you would see on Wikipedia or in an academic article.) Instead, it recommends that you put them in their own section. Sometimes, footnotes could appear as part of another piece of orgainized content, like the footer of a table, or the caption of a figure. I will talk about these things when I go over the HTML tags that orginize these types of content.

This element represents a section of the page that has a set of major navigation links. There can be more than one <nav> section, representing different sets of navigation links (primary navigation, tabbed navigation, etc). Each of these different navigation sections are usually given their own ID. Depending upon the type of navigation, it is usually part of a <header> section, or a section representing a sidebar.

Not all sets of links are considered “major navigation links.” Both the W3C and WHATWG standards give the example of links in the footer as not needing a <nav> tag.

How to actually mark up the navigation links is up for debate, but the consensus seems to be that you should use an unordered list. I will talk about unordered lists when I talk about structured text tags.

This tag defines content that is self-contained, and is usually used to annotate the article’s text with illustrations, diagrams, photos, charts, etc. It is a block element, so the browser will place an empty line before and after the figure, and most browsers indent it. However, its position is independent of the surrounding text flow. This makes it easy to target with CSS; for example, if users are viewing the page on a desktop, you could use CSS to position the figure to the right of the relevant text.
This tag provides a caption for a figure, and should be nested inside the <figure> element. If the figure has its own footnotes, it would be appropriate to put them here.

There should only be one caption per figure, and it should be either the first child or last child of the <figure> element. The caption will be displayed when it is encountered (so, above the figure if it is the first child element, and below the figure if it is the last).

There are a lot of page section tags, and even with the W3C and WHATWG recommendations, knowing which one to use can be confusing. To help with that, the good folks at HTML5 Doctor came up with this handy flowchart:

Sectioning Flowchart

An easy-to-understand HTML5 sectioning element flowchart to help you get to grips with some of the new elements in HTML5. Courtesy of HTML5 Doctor:

Headings, Sections, and Document Outlines

If you examine a document in the “real world” (like a book or journal article), it will usually have some kind of outline. You should be familiar with an outline: it is a shorthand for the information, containing only the most relevant parts. Those relevant parts are usually given in the headers of the document; the outline usually mirrors the table of contents.

HTML documents also have an outline structure. Prior to HTML5, it was not part of the standard, but it was always lurking in the background as a possibility. This changed with HTML5, and the W3C was seeking to make it part of the HTML standard as early as 2008.

In HTML 4.01 (and XHTML), the primary way you could create a document outline was through heading tags. As the name suggests, these tags specified that the text within them is a heading (like a headline in a newspaper article). The tag names are simply “h” followed by one of six “levels” of headings:

<h1>Heading Level One</h1>
<h2>Heading Level Two</h2>
<h6>Heading Level Six</h6>

All heading tags are block-level elements, so they render with an empty line before and after them by default. Each of the six levels represents a different rank. Each rank is used as the heading for a different-level section of the document. The headler for an entire article should be <h1>, the header for one section of an article should be <h2>, the header for a sub-section should be <h3>, and so forth.

It is generally a bad idea to skip ranks, for reasons which should become clear. Historically, bad web designers used header tags purely for their typographic effects, not their semantic meaning, so unfortunately this rule was not always followed. You shouldn’t make that same mistake. In particular, you should not use header tags to mark up “subheadings,” like alternate titles or taglines. The HTML 4.01 specification used the <hgroup> (header group) tag for this purpose. This tag is deprecated in HTML5, so you should use the <header> tag instead, or mark up the “subheading” in the header using some sort of inline tag (like a <span> tag).

Given the proper use of heading tags, it should be pretty easy to construct an outline of an HTML document. In fact, this was presented as a possibility in the HTML 4.01 spec: Heading information may be used by user agents, for example, to construct a table of contents for a document automatically.

This is about as far as HTML 4.01 got with outlines. The HTML5 spec expanded greatly upon them, and the official standard now includes an algorithm to produce document outlines. The W3C calls this sectioning the content. Heading tags still figure prominently in the algorithm, and work pretty much as you would expect. If a header tag is encountered that is of a lower rank than the last one, a new section is created that is a child of the current section. If the newly-encountered tag is of a higher rank, then the sections between the current rank and newly-encountered header’s rank are closed, and a new section is started. The result is a tree-like heirarchical structure, like the one that represents folders in a file system.

This structure is similar in concept to the DOM, but the two are not the same. The DOM includes all the HTML tags on a page. (In theory, browsers should even render “tag soup” as a DOM, but this will probably result in a DOM that is really wonky.) In contrast, the outline contains only “major” sections of the page; most HTML tags will not create a new section.

Most of the HTML5 page-section tags will create a new section, so that each <article> (for example) will have its own outline, which would be a child of the overall document’s outline. But other HTML tags won’t start a new section. Specifically, a <div> tag will not. This is the basis for creating the HTML5 <section> tag, and precisely why a <section> tag is not just a drop-in replacement for a <div> tag. (Incidentally, the <main> and <figure> tags don’t create a new section, either.)

I should be clear that an HTML outline is a theoretical concept; at present, web browsers don’t implement it in any way. But the outline is certainly useful for other user agents. For example, there are many pieces of software that will convert an HTML page (or pages) into an e-book, and most of them can create a table of contents from the outline. Another kind of software that uses the outline is accessibility software, like screen readers. This leads us to a discussion of WAI-ARIA, which we’ll discuss next.

Accessibility and ARIA Attributes

In order to make the web more accessible, the W3C created the WAI-ARIA standard (Web Accessibility Initiative – Accessible Rich Internet Applications). ARIA is the standard, and the WAI defines ARIA. The standard defines a set of tag attributes, which provide information for people who use assistive technologies like screen readers, or for keyboard-only navigation. (It is not strictly limited to HTML; for instance, some SVG editors also include ARIA attributes.) ARIA attributes are not designed to be targeted by CSS or JavaScript, and have no effect on the page’s visual appearance.

ARIA attributes start with the role attribute, which declares that the tag plays a specific ARIA role. It may be followed by other attributes that specify states, properties, or relationships; these have an aria- prefix.

One reason for the ARIA standard is because many web applications build custom UI “widgets” using HTML tags. Because these widgets often use HTML in a non-semantic way, there needs to be a way to make them have semantic meaning for machine readers. Unless you’re creating your own widgets, you won’t need to worry about this. (And if you know enough to do that, you don’t need this article.) Most of the aria-* attributes have to do with custom widgets.

But another reason is because tags can have a semantic role that isn’t covered by the HTML specification. These can be document structure roles, which describe structures that organize the page content; or landmark roles, which provide navigational landmarks that assistive technologies can jump to (or skip over).

There is a great deal of overlap between these ARIA roles, and HTML5 page section tags. All of the HTML5 tags have default ARIA attributes associated with them. If an HTML5 tag works for you, then you should use that tag, and you should not override its ARIA attributes. But there are two cases where you should still specify the ARIA roles:

  1. You don’t want to use HTML5 tags, because very old browsers won’t understand them; but you still want those roles to be understood by assistive technologies. In this case, you would spcify the role attribute in the relevant <div> tag.
  2. Your tag represents an ARIA role that is not represented by (or is too specific for) an HTML5 tag. In this case, you would use the most appropriate HTML5 tag, and specify its ARIA role, again using the role attribute.

Both these use cases are somewhat rare, but they do happen, especially if you’re not using HTML5. So I’ll list the various roles, but for brevity’s sake, I won’t give their definitions. (Most are self-explanatory.) All of these are possible values of the role attribute.

Document structure roles
article, definition, directory, document, group, heading, img, list, listitem, math, note, presentation, region, separator, toolbar
Landmark roles
application, banner, complementary, contentinfo, form, main, navigation, search

For more information on WAI-ARIA, I recommend these articles:
Using WAI-ARIA in HTML (W3C)
WAI-ARIA 1.0 Authoring Practices (W3C)
Using WAI-ARIA Landmarks – 2013 (Steve Faulkner, The Paciello Group)


About Karl

I live in the Boston area, and am currently studying for a BS in Computer Science at UMass Boston. I graduated with honors with an AS in Computer Science (Transfer Option) from BHCC, acquiring a certificate in OOP along the way. I also perform experimental electronic music as Karlheinz.
This entry was posted in HTML and tagged , . Bookmark the permalink.

4 Responses to A Guide to HTML

  1. Ben says:

    You probably know this, but the self-closing-ness of your tags are likely to be totally ignored by the browser unless you set the mime type to xhtml! For example, in most browsers this
    This is a paragraph
    will render exactly the same as this:
    This is a paragraph

    A common gotcha is thinking that you can use a self-closing script tag, e.g.

    instead of

    More on this on stackoverflow:

    So there can be arguments for doing this for style or tool support, but the browser really doesn’t care.

    • Ben says:

      wow, looks like wordpress doesn’t escape tags. Sorry, but hopefully the stackoverflow article explains well enough

      • Karl says:

        Also, about the tags – nope, WordPress does not excape HTML; you can use it to mark up comments (as I did just now), so it really can’t do that. For HTML tags, you have to use the &lt; and &gt; escape sequences. I also had to do this when I wrote the article, so I know how much of a PITA it is.

    • Karl says:

      Ben: First of all, thanks for taking the time to read the article. I need all the help I can get…

      The “self-closingness” issue applies only to tags that do not represent empty elements, and that includes the <script> tag. It’s supposed to contain text data (the actual JavaScript code). Trying to make these tags self-closing is not valid XHTML, and browsers will consider it “tag soup.”

      If the tag is actually self-closing – like the <br /> or <input /> tags – then the XHTML standard demands that they be properly terminated, or they won’t validate. The HTML standard (even HTML5) does not, but since XHTML is the one that has been used for years, I think it’s better to include the terminating slash.

      However, the Stack Overflow post did show something else that I wasn’t aware of: the <p> tag cannot contain other block-level tags, like <div>. (Inline tags are fine.) If you try to do this, the browser will consider it “tag soup” and automatically treat it as a tag with empty content. In other words, <p><div>Hello, world!</div></p> will turn into <p></p><div>Hello, world!</div><p></p>.

      I’ll update the article with this info. So, thank you for pointing this out. Please let me know if you find anything else in the article that needs work.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s