Marking up your XHTML code correctly
Within this document, references will be made to elements and attributes. It's important to understand the difference, so consider this sample code:
<a href="index.html" title="Environmental Protection Agency home page">Home</a>
The base HTML element is the link anchor (a
). The attribute is any additional information about that element within the initial <> pair, such as the href
and title
values in this case.
To view the example usage for any item within this document, please view its source.
Header Examples
The main page header of this guide is an h1
element. Please reserve h1
for individual page titles only (like "Markup Guide" above).
The secondary header ("Header Examples") is an h2
element, which may be used for any form of important page-level header. More than one may be used per page. Consider using an h2
unless you need a header level of less importance, or as a sub-header to an existing h2
element. Any header level may include links.
Third-Level Header
The header above is an h3
element, which may be used for any form of page-level header which falls below the h2
header in a document hierarchy. More than one may be used per page.
Fourth-Level Header
For all headers below third-level, follow the guidelines listed above. Only use lower header levels when necessary. I tend to use h4
in place of <p><strong>Your text here</strong></p>.
Fifth-Level Header
For all headers below third-level, follow the guidelines listed above. Only use lower header levels when necessary.
Sixth-Level Header
For all headers below third-level, follow the guidelines listed above. Only use lower header levels when necessary.
Link Examples
External and internal links are handled differently.
- External links
- Internal links
- Code EPA internal links as before.
title
attributes are not necessary, but helpful. - Example:
<a href="http://www.epa.gov/internalURLhere/" />
- Internal PDF links
- Links to PDF documents. For more info, see EPA's PDF linking standard.
- Anchor links
- For links within pages, use
id
attributes, notname
attributes (name
is deprecated).
As an example of an anchor link, consider the "jump lists" in the "table of contents" above. Each link in the box is written <a href="#linkexamples">Link Examples</a>
. Clicking on "Link Examples" brings you to the Link Examples heading, which is coded as <h2 id="linkexamples">Link Examples</h2>
.
Paragraphs
All paragraphs are wrapped in p
tags. (If you have a quote, paragraphs can be wrapped within a blockquote
element. EPA has a pull-quote standard, which can be use for the same purpose.)
Blockquotes
Historically, blockquote
has been used purely to force indents, but this can now be achieved using CSS. Reserve blockquote
for quotes. Here's an example of correct usage:
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Cras euismod fringilla arcu. Integer posuere. Aliquam ipsum. Donec eget massa ac orci tempus euismod. Donec quis neque nec neque consequat sollicitudin. Donec commodo tempor nulla. Suspendisse venenatis. Ut ut leo. Nunc placerat urna at libero. Nunc suscipit lacus.
Additionally, you might wish to cite the source, as in the above example. (The correct method involves the cite
attribute directly applied to the blockquote
element, but since no browser makes any use of that information whatsoever, it's useful to also specify the standalone cite
element.)
EPA has a pull-quote standard, which can be used for the same purpose.
Inline Text
You might have noticed all the monospaced text in this guide. There are a number of inline HTML elements you may use anywhere within other elements, including abbr, acronym, cite, code
, del, em, ins, kbd, strong, and var.
- abbr
-
Used for any abbreviated text, whether it be acronym, initialism, or otherwise. Generally, it's less work and useful (enough) to mark up only the first occurence of any particular abbreviation on a page, and ignore the rest. Any text in the
title
attribute will appear when the user's mouse hovers the abbreviation (although notably, this does not work in Internet Explorer for Windows). Example abbreviations and usage: NASA, HTML, and Mass. - acronym
-
Used for only specific abbreviations. Like
abbr
, any text in thetitle
attribute will appear when the user's mouse hovers the acronym (unlikeabbr
, however, this does work in Internet Explorer for Windows.) According to Mirriam Webster , acronyms are:...a word (as NATO, radar [...] ) formed from the initial letter or letters of each of the successive parts or major parts of a compound term; also : an abbreviation (as FBI) formed from initial letters.
If you think the difference between
acronym
andabbr
is esoteric, you're right. code
-
Used for computer code samples. Useful for technology-oriented sites, not so useful otherwise. Example code and usage:
function getJello() { echo $billCosbyWillMug; }
Inline usage: just like elsewhere in this document, HTML elements like
em
orcode
can be considered code, and marked up as such. - cite
-
Used for defining a citation or reference to other information sources. Example cited text and usage: More information can be found in [ISO-0000].
del-
Used for deleted or retracted text which still must remain on the page for some reason. Since the default style includes a strikethrough line, it's preferable to the
s
element. Thedel
element also has adatetime
attribute which allows you to include a timestamp directly in the element. Example deleted text and usage: She boughttwofive pairs of shoes. (Write the datestamp as so: datetime="2005-09-12".) - em
-
Used for denoting emphasized text. In most instances where you'd want to italicize text (using the HTML element
i
or otherwise) you should use theem
element instead. Notable exceptions are stylistic italicizing of proper titles, foreign languages, etc. where italicizing is used for differentiation instead of emphasis. In those cases, no proper HTML elements exist, so ani
element or aspan
element with a custom class may be preferable. Example emphasized text and usage: You simply must try the negitoro maki! - ins
- Reserved for the "new!" javascript function.
- kbd
-
Used for text which should be typed by the user. Mainly useful for computer instructions. Example keyboard text and usage: Please press Enter to continue.
- strong
-
Used for denoting stronger emphasis than the
em
element. In most instances where you'd want to bold text (using the HTML elementb
or otherwise) you should use thestrong
element instead. Notable exceptions are stylistic bolding of examples, first occurences of names in an article, etc. where bolding is used for differentiation instead of emphasis. In those cases, no proper HTML elements exist, sob
element or aspan
element with a custom class may be preferable. Example strong text and usage: Don't stick nails in the electrical outlet. - var
-
Used for variables within computer code snippets. Useful for technology-oriented sites, not so useful otherwise. Example code and usage: Add 5 to $result and recalculate.
Lists
Then there are the lists. ul
denotes an unordered list (ie. a list of loose items that don't require numbering, or a bulleted list). ol
denotes an ordered list, and various numbering schemes are available through the CSS (including 1,2,3... a,b,c... i,ii,iii... and so on). Each item within the ul
or ol
requires a surrounding <li>
and </li>
tag, to denote individual items within the list (as you may have guessed, li
stands for list item).
Example lists and usage:
- This is an unordered list.
- It has two items.
- This is an ordered list.
- It has two items.
- No, I lied, it has three.
The Area Navigation (sidebar), the breadcrumbs, and the global footer are marked up as a list of links. You can see that it is possible to style each list in alternative ways.
Lists within lists are written as follows:
<ul> <li>List item <ul> <li>Sub-list item</li> </ul> </li> </ul>
EPA has a standard for simple lists within the content.
Additionally, dl
is another list type called a definition list. Instead of list items, the content of a dl
consists of dt
(Definition Term) and dd
(Definition description) pairs. Though it may be called a "definition list", dl
can apply to other scenarios where a parent/child relationship is applicable. For example, it may be used for marking up dialogues, with each dt
naming a speaker, and each dd
containing his or her words.
- This is a term.
- This is the definition of that term, which both live in a
dl
. - Here is another term.
- And it gets a definition too, which is this line.
- Here is term that shares a definition with the term below.
- Here is a defined term.
dt
terms may stand on their own without an accompanyingdd
, but in that case they share descriptions with the next availabledt
. You may not have add
without a parentdt
.
Created by Dave Shea ; edited by Michael Hessling.