(HTML) HTML Primer (Updated 2009-10-16)

[chaos**]

HTML Primer

Changelog:

Nov 24th, 2007 - Definition Lists and two additional "common mistakes" added.
Nov 23rd, 2007 - Document posted.

Sometimes it's easy to take for granted the power of the forum text editor. You press Enter; it makes a new line. You click bold; it bolds the current text. If only the real world was so convenient! Behind the scenes, the forum software is converting what you're doing to a language called HTML. No doubt if you're internet literate enough to be helping out with the site you have a basic understanding of what HTML is... but for those stragglers who don't, HTML is the language that specifies how a web page is to be formatted and laid out. This document aims to give you a basic understanding of translating plain text into a format acceptable for display on smogon.com. This is by no means all to say on the subject - in fact, it's a very limited subset.

Step one: know what it looks like!

Right click on this page, and select "View Source". Notice the plethora of <item></item> looking entities. These entities are called "tags", and are the basis of formatting a document in HTML. Note the similarities to the BBCode used to formatting text on the forums! Aye, formatting text in HTML is no different than formatting text for use on the forums - it involves surrounding text with tags that instruct the browser on how to display it.

The term "markup" will be used henceforth to refer to the action of surrounding text with a tag. For example:

Markup "text" with dog. - <dog>text</dog>
Markup the preceding text with a cat tag. - <cat><dog>text</dog></cat>

You may have noticed that sometimes tags look like this: <tag attribute="value"> as opposed to simply <tag>. For the sake of completeness, attributes are like "options" to the tag. Another BBCode analogy - the quote BBcode looks like this: [quote="chaos"]I'm awesome.[/quote]. Note the ="chaos" - it's similar to an attribute that tells the tag that the quoted user is in fact, me. An HTML-like equivalent would look something like <quote user="chaos">I'm awesome.</quote>.

Ok, enough with abstract nonsense. It's time to actually see some real world examples. Lets try formatting the following text in HTML.

The Trilogy of Bag Aeolus

We all know Aeolus meets the qualifications of bag, but does anyone know the history behind this?
Well... it started a few years ago. Bag Aeolus found a site called PokeRealm on the internet and teamed
up with Pokemon professional "Big Zero." He soon became admin of said site and propelled it into the
Pokemon limelight, where it attracted big name players like "Groundon80."

Groundon80 and Aeolus were fooling around playing some Pokemon one day when Groundon80 had the
brilliant idea of fooling around with each other instead. They touched each other inappropriately,
and finally Aeolus got so excited he wanted to try penetration. No condoms were available, so
he used a brown paper bag. Bag Aeolus.

Here's why Bag Aeolus shouldn't have done this:

* Condoms protect against HIV.
* Groundon80 has been with many a man.
* Big Zero is probably a bit jealous

I hope both parties don't get angry at me using this example for the HTML primer! It's originally from an Inside Scoop thread.
I needed some example text, and this fit the bill appropriately!

Step two: know your paragraphs!

Paragraphs should be marked up with p tags. There are 4 items in the example that should be marked up as "paragraphs."

<p>We all know Aeolus meets the qualifications of bag, but does anyone know the history behind this? 
Well... it started a few years ago. Bag Aeolus found a site called PokeRealm on the internet and teamed
up with Pokemon professional "Big Zero." He soon became admin of said site and propelled it into the 
Pokemon limelight, where it attracted big name players like "Groundon80."</p>

<p>Groundon80 and Aeolus were fooling around playing some Pokemon one day when Groundon80 had the
brilliant idea of fooling around with each other instead. They touched each other inappropriately,
and finally Aeolus got so excited he wanted to try penetration. No condoms were available, so
he used a brown paper bag. Bag Aeolus.</p>

<p>Here's why Bag Aeolus shouldn't have done this:</p>

<p>I hope both parties don't get angry at me using this example for the HTML primer! It's originally from an Inside Scoop thread.
I needed some example text, and this fit the bill appropriately!</p>

Newlines and/or additional whitespace in an HTML document are ignored and are not suitable for specifying paragraphs. Be sure to markup each and every paragraph with P tags or they won't display as desired.

<p>We all know Aeolus meets the qualifications of bag, but does anyone know the history behind this? 
Well... it started a few years ago. Bag Aeolus found a site called PokeRealm on the internet and teamed
up with Pokemon professional "Big Zero." He soon became admin of said site and propelled it into the 
Pokemon limelight, where it attracted big name players like "Groundon80."

Groundon80 and Aeolus were fooling around playing some Pokemon one day when Groundon80 had the
brilliant idea of fooling around with each other instead. They touched each other inappropriately,
and finally Aeolus got so excited he wanted to try penetration. No condoms were available, so
he used a brown paper bag. Bag Aeolus.</p>

displays as:

We all know Aeolus meets the qualifications of bag, but does anyone know the history behind this?
Well... it started a few years ago. Bag Aeolus found a site called PokeRealm on the internet and teamed
up with Pokemon professional "Big Zero." He soon became admin of said site and propelled it into the
Pokemon limelight, where it attracted big name players like "Groundon80." Groundon80 and Aeolus were fooling around playing some Pokemon one day when Groundon80 had the
brilliant idea of fooling around with each other instead. They touched each other inappropriately,
and finally Aeolus got so excited he wanted to try penetration. No condoms were available, so
he used a brown paper bag. Bag Aeolus.

Be careful :)

Step three: know your headers!

Headers are used to logically divide sections of a document. In forum posts, they are usually presented as larger and/or bolded text. In HTML, they are marked up with the tags h1, h2, h3, h4, h5, and h6. Large numbered headers are subheaders of smaller numbered headers: <h2> is a subheader of <h1>, <h3> is a subheader of <h2>, etc. Normally in an HTML document you would use <h1> as the first header, but in the SCMS we will be using <h2> as the first header on most occasions (<h1> is automatically added as the title of the page.)

In our example we have one header: "The Trilogy of Bag Aeolus". For this example's sake lets say the the SCMS title (and <h1> of this page) is "Aeolus" and "The Trilogy of Bag Aeolus" is merely a subheader.

<h2>The Trilogy of Bag Aeolus</h2>

Perfect.

Step four: know your lists!

There two types of lists in HTML: the ordered list <ol> and the unordered list <ul>. Ordered lists number each of their elements starting with 1. Unordered lists bullet each item. Items of both lists are marked up using the <li> tag. Lets translate our example into HTML. Usually in forum posts lists are denoted with *s (like our example), sequential numbers (in which an <ol> should be used!), or with real bullets if the poster was engaged enough to actually use them :)

<ul>
<li>Condoms protect against HIV.</li>
<li>Groundon80 has been with many a man.</li>
<li>Big Zero is probably a bit jealous</li>
</ul>

Note that lists can be nested like the majority of other HTML tags. Nested lists in forum text are usually presented with indentation:

* Item 1
  * Item 1.1
* Item 2

or with increasing amount of bullets:

* Item 1
** Item 1.1
* Item 2

Both examples are marked up by placing a <ul> inside of the parent <li> tag.

<ul>
<li>Item 1
    <ul>
    <li>Item 1.1</li>
    </ul>
</li>
<li>Item 2</li>
</ul>

In general, you won't put multiple paragraphs inside of list items, and therefore you will not place <p> tags inside list items. If the desire to do this manifests, rethink the structure of the document. It's bad style to put multiple paragraphs and <p> tags inside of list items. Contact me or another fluent HTML wizard for help on restructuring if a roadblock is encountered.

Step five: know your links!

A hyperlink (or in colloquial usage, "link") is a typically blue, underlined piece of text that when clicked, will take you to a different resource on the internet. Hyperlinks are created with the <a> tag and require the "href" attribute, which indicates which resource to link to. On the forum, links are specified normally in two manners (Assuming we are trying to link to www.smogon.com/dp/pokemon/ with the text "PokeDex"):

PokeDex

or

PokeDex http://www.smogon.com/dp/pokemon/

In either case, the result should be marked up as <a href="/dp/pokemon/">PokeDex</a>. Note the omission of http://www.smogon.com/ - a single / preceeding the link means the same thing. That style is called an absolute link. Absolute links work regardless of what file or what directory they are put in. Relative links, however, are directory specific and do not require any prefixes. Lets say the file we are working on is stored in /dp/. To create the same link as before, we could write <a href="pokemon/">PokeDex</a>. Since this link didn't start with the / prefix, it is assumed to be a relative link and therefore starts from the directory we are currently in.

Since our example text did not include any explicit links, we will pick some text to link. Since Aeolus and Groundon80 have forum profiles here, lets link to their pages in our example text.

<p><a href="/forums/member.php?u=526">Groundon80</a> and <a href="/forums/member.php?u=1385">Aeolus</a> were fooling around playing some Pokemon one day when Groundon80 had the
brilliant idea of fooling around with each other instead. They touched each other inappropriately,
and finally Aeolus got so excited he wanted to try penetration. No condoms were available, so
he used a brown paper bag. Bag Aeolus.</p>

Generally you'll only link to an item once in a document. Any more is unnecessary and clutters up the presentation of the document... not to mention it's a lot of work for the writer! There are a few exceptions - contact me if you have any questions.

Our final result

<h2>The Trilogy of Bag Aeolus</h2>

<p>We all know Aeolus meets the qualifications of bag, but does anyone know the history behind this? 
Well... it started a few years ago. Bag Aeolus found a site called PokeRealm on the internet and teamed
up with Pokemon professional "Big Zero." He soon became admin of said site and propelled it into the 
Pokemon limelight, where it attracted big name players like "Groundon80."</p>

<p><a href="/forums/member.php?u=526">Groundon80</a> and <a href="/forums/member.php?u=1385">Aeolus</a> were fooling around playing some Pokemon one day when Groundon80 had the
brilliant idea of fooling around with each other instead. They touched each other inappropriately,
and finally Aeolus got so excited he wanted to try penetration. No condoms were available, so
he used a brown paper bag. Bag Aeolus.</p>

<p>Here's why Bag Aeolus shouldn't have done this:</p>

<ul>
<li>Condoms protect against HIV.</li>
<li>Groundon80 has been with many a man.</li>
<li>Big Zero is probably a bit jealous</li>
</ul>

<p>I hope both parties don't get angry at me using this example for the HTML primer! It's originally from an Inside Scoop thread.
I needed some example text, and this fit the bill appropriately!</p>

Congrats, you've made it through the basics and should be able to convert basic documents to HTML with little to no trouble. However, if that's all you know I probably wouldn't trust you to be site staff or anything... ;) Keep reading.

Images

To insert an image, we use the <img> tag. It has two essential attributes - "src", which specifies where the image is located, and "alt", which is text to display if the browser doesn't support images. Normally I leave alt as "" because I feel as if there is no suitable text which conveys the meaning (in a non-redundant way) of the image. Regardless, alt must be present, even if its blank.

Other useful attributes are "width" and "height". If you know the width and height of the image you are adding (or, alternatively, if you can find out the width and the height... don't be lazy) it should be added to the tag to ease page loading. Ever had a page that, while loading, kept shifting around the location of the text making it hard to read? It's happened to me a bunch of times. That happens when lazy editors don't add width and height attributes to their tags.

Note that this is the first tag we have encountered on our journey that doesn't have a closing tag. We don't write <img></img>, but rather close the tag like this: <img />. The / at the end means it's closed; no additional closing tag is necessary.

<img src="/media/big_surgo.jpg" width="50000" height="6" alt="Surgo sure is massive." />

Note: Don't use the "border" or "align" attributes.

Character entities

<, > are reserved in HTML for tags. One may encode these symbols using character entities. A character entity is composed of an ampersand, the name of the entity, and finally a semicolon. To encode <, we would write &lt;. To encode >, we would write &gt;. It's very important to note that & is reserved in HTML as well! To encode a literal &, one writes &amp;. Exercise caution when writing hyperlinks. If a link is in the form of /page?item1=hello&item2=whatever, then the ampersand in that MUST be written as &amp;. For completeness, we would write this example as <a href="/page?item1=hello&amp;item2=whatever">.

Reference:

< - &lt;
> - &gt;
" - &quot; (When working inside attributes, you'll need this occasionally.)
& - &amp;

Handy entities to know:

é - &eacute; (Handy for those that don't remember the alt code or don't have editors that support Unicode)
— (em dash) - &mdash;
- (en dash) - &ndash;

Bold, italic, and other friends (introduction to semantic markup)

When you use the "B" button on the forums, is it simply for decoration? Can bold formatting be used anywhere one feels like without respect to the nature of the document you are formatting? Hopefully you answered "no" to both of those questions - Bold formatting should only be used when you want to add emphasis to text. When working with HTML, it's important to divorce the concept of emphasis and presentation of said emphasis (bolding, italics, etc). That's the very nature of semantic markup: formatting text based on what you mean instead of what you want it to look like. It's out of the scope of this document to give a full discussion on the advantages of semantic markup, so you'll just have to trust me (or use Google).

Reference: (non-exhaustive)

strong emphasis - <strong>
emphasis - <em>

inserted text - <ins>
deleted text - <del>

text the user should input on a keyboard - <kbd>
code (programming languages) - <code>
variables - <var>

short quoted passages - <q>
long quoted passages - <blockquote>

acronyms - <acronym>
abbreviations - <abbr>

... and for those who hate thinking semantically:

bold - <strong>
italic - <em>
underline - Don't use it. That's reserved for links only.
strikethrough - <del>
color - Don't use it.
different fonts - Don't use it.
different sized text - Don't use it. You have headers anyway.

Things I should never see in the SCMS (non-exhaustive)

If you want to use any of these damned tags talk to me first.

<b>, <i>, <u>, <font>, <strike>, <blink>, <marquee>

Definition Lists

There is one final variant of list that I neglected to mention before. Definition Lists are used to associate terms and their definitions (or information related to them). If we had a long list... like this:

Meteor Mash - A very inaccurate move.
Swift Swim - Hey guys, this increases speed!
Exegutor - Note that it's spelled Exeggutor...

we could mark it up using the <dl>, <dt>, and <dd> tags like so:

<dl>
<dt>Meteor Mash</dt>
<dd>A very inaccurate move</dd>

<dt>Swift Swim</dt>
<dd>Hey guys, this increases speed!</dd>

<dt>Exegutor</dt>
<dd>Note that it's spelled Exeggutor...</dd>
</dl>

The <dl> tag introduces a new Definition List. It can contain an arbitrary number of <dt>s and <dd>s. The terms are marked up in <dt> and their definitions or related text is marked up using <dd>.

Tables

Tables are used to format tabular data, i.e. data that fits naturally into the concept of columns and rows. Think spreadsheets. Anyway, to make a table we use the tags <table>, <thead>, <th>, <tbody>, <tr>, and <td>. There is additional JavaScript you must add currently as well to get sorting to work :) Since this would be impossible to explain in abstract, let's contrive a simple example: we have a table with two columns - User, and Pokemon. We want to insert the data (chaos, Ho-oh), (Steelicks, Steelix), and (Jumpman, Octillery).

First let's start off by creating the basic structure of the table.

<table class="sortable">
<thead>

</thead>
<tbody>

</tbody>
</table>

Note that you must always include class="sortable" even if you don't want your table to be sorted, as it adds style information to make your table "look right". <thead> will contain all of the rows of the table that are considered part of the table headers and <tbody> will contain the rows that are apart of the data of the table. Lets add the headers now.

<table class="sortable">
<thead>
<tr>
    <th>User</th>
    <th>Pokemon</th>
</tr>
</thead>
<tbody>

</tbody>
</table>

We introduced the two new tags here; <tr>, and <th>. <tr> creates a table row, be it in the table headers or the data of the table. <th> is used inside of a <tr> in the <thead> when we want the item to be a header. We can technically create multiple rows of headers, but that is fairly esoteric and if you have the need for this it's recommended to talk to me first. Let's finish this up and add the actual data.

<table class="sortable">
<thead>
<tr>
    <th>User</th>
    <th>Pokemon</th>
</tr>
</thead>
<tbody>
<tr>
    <td>chaos</td>
    <td>Ho-oh</td>
</tr>
<tr>
    <td>Steelicks</td>
    <td>Steelix</td>
</tr>
<tr>
    <td>Jumpman</td>
    <td>Octillery</td>
</tr>
</tbody>
</table>

We created three table rows (<tr>s) inside our <tbody>, so we have three rows of data in the table. Inside, we used the <td> (table data) tag to indicate that the item is data and not a header in the table. Be sure the number of <th>s and <td>s match in every row, or your table will turn out really funky!

Note: Those who already know tables might be accustomed to setting the attributes "cellspacing", "cellpadding", "border", and "valign" on tables. Not here, kid.
Note: If you want sorting, talk to me after your document is finished and in the SCMS.

Addendum: Common Mistakes

All tags should be lowercase

Don't write <P>, don't write <TABLE>, put everything in lower case. Same goes for attributes. No exceptions.

All tags must be closed

People in the past have tried to get away with not closing <p> and <li>. You must close them. Same goes with <img> - be sure to include the / at the end.

<p>A paragraph
<p>Another paragraph

See that? That doesn't fly.

Tags must be closed in order

Stuff like:

<strong>Hello <em>friends</strong></em>

doesn't fly either. Tags must be closed in order.

Try to avoid <br />

It's not necessary in 99% of cases - use a different way of formatting the document.

<li> can't appear in your document randomly

<li> exists ONLY in <ul> and <ol>. Likewise, you cant put random stuff in <ul>s, <ol>s, and <dl>s. <ul> and <ol> ONLY contain <li>s, and <dl> ONLY contains <dt>s and <dd>s. Note that arbitrary HTML can appear inside <li>, <dt>, and <dd>.

Conclusion

Any questions or comments should be posted in this thread and not PMed to me. Hope you enjoyed this - it took me forever and a half to write over Thanksgiving :)

Edit: Use this link to check your work: http://validator.w3.org/#validate_by_input

[Jumpman16**]

hey thanks very much for this busy chaos

[X-Act]

Thanks for this chaos.

I have a small question. Is there a special character to display the multiplication and division sign (× and ÷) in HTML? My guides use these characters a bit, and they appear strange when converted to HTML.

[chaos**]

X-Act: they shouldn't display strange in an HTML document that uses Unicode. All of the Smogon beta site, including the SCMS, uses Unicode. Just insert those characters literally.

If you really need those as entities, a quick Google search tells me they are &times; and &divide;

[X-Act]

Okay, I left them as is. My HTML previewer program must not be currently using Unicode characters then.

[Aeolus]

great. and, unfortunately, eerily accurate.

[timw06]

How are we supposed to set out pokemon and movesets. I was doing this like this:

<p>
<strong>Abra</strong> @ Choice Specs/Scarf
<br />
Synchronise
<br />
&bull; Psychic
<br />
&bull; Hidden Power [Fighting]
<br />
&bull; Energy Ball
<br />
&bull; Shadow Ball
</p>

<p> <strong>EVs:</strong> 236 SAtk / 196 Spd / 76 HP
<br />
<strong>Nature:</strong> Modest or Timid
</p>

but you have now posted not to use line breaks.

[chaos**]

I used to have a special tag the SCMS recognized for this kind of stuff. What do you need to format a moveset for? In all honesty, for something as sensitive to formatting as a moveset, I would wrap the whole thing in <pre> (preformatted text, all line breaks and whitespace are literal) and format it like that.

<pre>
Metagross @ Choice Band
~ Meteor Mash
~ Whatever
</pre>

[ryubahamut]

- Writing the author of the page
In most articles, the HTMLizer would be required to add the author's name, and the person who rewrote it as well. Tentative syntax for that is the following:

<div class="author">By <a href="/forums/member.php?u=99999">[Author's name here]</a>, rewritten by <a href="/forums/member.php?u=111111">[Rewriter's name here]</a>.</div>

In the above, the author's and user's names must be substituted. The numbers in the <a href="..."> section must be replaced by the author's/rewriter's user ID on the forums, which can be determined by placing the cursor over the user's name, which displays a link to the user's profile page in the statusbar. For example, if you hover over chaos' name in a post, you see "http://www.smogon.com/forums/member.php?u=1" in the statusbar. The bolded part (i.e. 1) is his user ID.

Please note that this method does not work with links to the users' profile pages on any forums index (such as the C&C main page, etc).

- Table of Contents
When writing a table of contents, an ordered list (<ol>) is to be used. However, this list is different from the others in the way that it has a class attribute, set to "toc":

<ol class="toc">

In order to create tables of contents, each header has to be "bookmarked", so to speak, which means adding an <a> tag with a name and no href, for instance:

<h2><a name="introduction">Introduction</a></h2>

This <a> tag must be properly closed as well. Once this is done for all headers (and subheaders if the HTMLizer deems it fit), we move on to the actual TOC creation, which is nothing but creating an ordered list on the following pattern:

<ol class="toc">
	<li><a href="#introduction">Introduction</a></li>
</ol>

See the difference between common links and this one? The # before introduction tells the browser to scroll down to the part of the page where the name="introduction" bookmark is placed.

Bookmark names are unique, so you can't use the same name for two bookmarks. Also, it is highly recommended to use sensible bookmark names. "introduction" or "battling" are sensible names, "section_1" or "1" are not.

I hope this is not too cryptic/hard to understand. If there is any question, please feel free to PM me/post it in this thread.

[ryubahamut]

HTMLizers are requested to note that it's preferable to include a table of contents in each article that has a scope its inclusion. Also, it is mandatory to include an author tag for every page that needs one. Instructions on that can be located in the HTML primer (last post).

Along with that, if HTMLizers with good prose skills could post a small writeup of the article to appear on the articles index page, it would automate the task of the site staff quite a lot.

EDIT: Please include a link back to the source material in your thread.