Markup Guide

Within this doc­u­ment, ref­er­ences will be made to ele­ments and attrib­utes. It’s impor­tant to under­stand the dif­fer­ence, so con­sider this sam­ple code:

<a href="index.php">Home</a>

The base HTML ele­ment is the a in this case. The attribute is any addi­tional infor­ma­tion about that ele­ment within the ini­tial < > pair, or the href value in this case.

To view the exam­ple usage for any item within this doc­u­ment, please view its source.

This guide has been unashamedly copied from Dave Shea @ mezzoblue.com


Header Exam­ples

The main page header of this guide is an h1 ele­ment. Please reserve h1 for indi­vid­ual page titles only. Any header ele­ments may include links, as depicted in the example.

The sec­ondary header above is an h2 ele­ment, which may be used for any form of impor­tant page-level header. More than one may be used per page. Con­sider using an h2 unless you need a header level of less impor­tance, or as a sub-header to an exist­ing h2 ele­ment. Any header level may include links, as depicted in the example.

Third-Level Header

The header above is an h3 ele­ment, which may be used for any form of page-level header which falls below the h2 header in a doc­u­ment hier­ar­chy. More than one may be used per page.

Fourth-Level Header

For all head­ers below third-level, fol­low the guide­lines listed above. Only use lower header lev­els when necessary.

Fifth-Level Header

For all head­ers below third-level, fol­low the guide­lines listed above. Only use lower header lev­els when necessary.

Sixth-Level Header

For all head­ers below third-level, fol­low the guide­lines listed above. Only use lower header lev­els when necessary.


Para­graphs

All para­graphs are wrapped in p tags. Addi­tion­ally, p ele­ments can be wrapped with a blockquote ele­ment if the p ele­ment is indeed a quote. His­tor­i­cally, blockquote has been used purely to force indents, but this is now achieved using CSS. Reserve blockquote for quotes. Here’s an exam­ple of cor­rect usage:

Lorem ipsum dolor sit amet, con­sectetuer adip­isc­ing elit. Cras euis­mod fringilla arcu. Inte­ger posuere. Ali­quam ipsum. Donec eget massa ac orci tem­pus euis­mod. Donec quis neque nec neque con­se­quat sol­lic­i­tudin. Donec com­modo tem­por nulla. Sus­pendisse vene­natis. Ut ut leo. Nunc plac­erat urna at libero. Nunc sus­cipit lacus.

lipsum.com

Addi­tion­ally, you might wish to cite the source, as in the above exam­ple. (The cor­rect method involves the cite attribute directly applied to the blockquote ele­ment, but since no browser makes any use of that infor­ma­tion what­so­ever, it’s use­ful to also spec­ify the stand­alone cite element.)


Inline Text

You might have noticed all the mono­spaced text in this guide. There are a num­ber of inline HTML ele­ments you may use any­where within other ele­ments, includ­ing abbr, acronym, cite, code, del, em, ins, kbd, strong, and var.

abbr
Used for any abbre­vi­ated text, whether it be acronym, ini­tial­ism, or oth­er­wise. Gen­er­ally, it’s less work and use­ful (enough) to mark up only the first occurence of any par­tic­u­lar abbre­vi­a­tion on a page, and ignore the rest. Any text in the title attribute will appear when the user’s mouse hov­ers the abbre­vi­a­tion (although notably, this does not work in Inter­net Explorer for Win­dows). Exam­ple abbre­vi­a­tions and usage: NASA, HTML, and Mass.
acronym
Used for only spe­cific abbre­vi­a­tions. Like abbr, any text in the title attribute will appear when the user’s mouse hov­ers the acronym (unlike abbr, how­ever, this does work in Inter­net Explorer for Win­dows.) Accord­ing to Mir­riam Web­ster, acronyms are:

…a word (as NATO, radar […] ) formed from the ini­tial let­ter or let­ters of each of the suc­ces­sive parts or major parts of a com­pound term; also : an abbre­vi­a­tion (as FBI) formed from ini­tial letters.

If you think the dif­fer­ence between acronym and abbr is eso­teric, you’re prob­a­bly right.

code
Used for com­puter code sam­ples. Use­ful for technology-oriented sites, not so use­ful oth­er­wise. Exam­ple code and usage:

function getJello() {
	echo $aDeliciousSnack;
}

Inline usage: just like else­where in this doc­u­ment, HTML ele­ments like em or code can be con­sid­ered code, and marked up as such.

cite
Used for defin­ing a cita­tion or ref­er­ence to other infor­ma­tion sources. Exam­ple cited text and usage: More infor­ma­tion can be found in [ISO-0000]
del
Used for deleted or retracted text which still must remain on the page for some rea­son. Since the default style includes a strikethrough line, it’s prefer­able to the s ele­ment. The del ele­ment also has a datetime attribute which allows you to include a time­stamp directly in the ele­ment. Exam­ple deleted text and usage: She bought two five pairs of shoes.
em
Used for denot­ing empha­sized text. In most instances where you’d want to ital­i­cize text (using the HTML ele­ment i or oth­er­wise) you should use the em ele­ment instead. Notable excep­tions are styl­is­tic ital­i­ciz­ing of proper titles, for­eign lan­guages, etc. where ital­i­ciz­ing is used for dif­fer­en­ti­a­tion instead of empha­sis. In those cases, no proper HTML ele­ments exist, so an i ele­ment or a span ele­ment with a cus­tom class may be prefer­able. Exam­ple empha­sized text and usage: You sim­ply must try the negi­t­oro maki!
ins
Used for inserted text and coun­ter­part to the del ele­ment. Like del, ins has a datetime attribute which allows you to include a time­stamp directly in the ele­ment. Exam­ple inserted text and usage: She bought two five pairs of shoes.
kbd
Used for text which should be typed by the user. Mainly use­ful for com­puter instruc­tions. Exam­ple key­board text and usage: Please press Enter to continue.
strong
Used for denot­ing stronger empha­sis than the em ele­ment. In most instances where you’d want to bold text (using the HTML ele­ment b or oth­er­wise) you should use the strong ele­ment instead. Notable excep­tions are styl­is­tic bold­ing of exam­ples, first occurences of names in an arti­cle, etc. where bold­ing is used for dif­fer­en­ti­a­tion instead of empha­sis. In those cases, no proper HTML ele­ments exist, so b ele­ment or a span ele­ment with a cus­tom class may be prefer­able. Exam­ple strong text and usage: Don’t stick nails in the elec­tri­cal outlet.
var
Used for vari­ables within com­puter code snip­pets. Use­ful for technology-oriented sites, not so use­ful oth­er­wise. Exam­ple 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 num­ber­ing, or a bul­leted list). ol denotes an ordered list, and var­i­ous num­ber­ing schemes are avail­able through the CSS (includ­ing 1,2,3… a,b,c… i,ii,iii… and so on). Each item within the ul or ol requires a sur­round­ing <li> and </li> tag, to denote indi­vid­ual items within the list (as you may have guessed, li stands for list item).

Addi­tion­ally, dl is another list type called a def­i­n­i­tion list. Instead of list items, the con­tent of a dl con­sists of dt (Def­i­n­i­tion Term) and dd (Def­i­n­i­tion descrip­tion) pairs. Though it may be called a “def­i­n­i­tion list”, dl can apply to other sce­nar­ios where a parent/child rela­tion­ship is applic­a­ble. For exam­ple, it may be used for mark­ing up dia­logues, with each dt nam­ing a speaker, and each dd con­tain­ing his or her words.

Exam­ple lists and usage:

  • This is an unordered list.
  • It has two items.
  1. This is an ordered list.
  2. It has two items.
  3. No, I lied, it has three.
This is a term.
This is the def­i­n­i­tion of that term, which both live in a dl.
Here is another term.
And it gets a def­i­n­i­tion too, which is this line.
Here is term that shares a def­i­n­i­tion with the term below.
Here is a defined term.
dt terms may stand on their own with­out an accom­pa­ny­ing dd, but in that case they share descrip­tions with the next avail­able dt. You may not have a dd with­out a par­ent dt.

Also read...

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>