Python Web Style Guide

General design: on the left is a sidebar with links and a few graphics. At the very top is an image with the word "Python" in a random font (different on each page); this is also a link to the Python home page. To its right is a "site menu", a 2x4 table with the 8 most important subsections of the site. Both the sidebar and the site menu have a light blue background; a variant of the same color returns in the top left image. The sidebar has subsection headers using white text on a dark blue background. The main text (to the right of the sidebar and below the site menu) has a white background. Link colors are standard (darkish blue for links, purplish for followed links; red for active links).

Sidebar: under the Python image, the sidebar contains, from top to bottom: an index of the current section (usually); other links, labeled "See also"; more links and exits; a section labeled "Email us" with the webmaster email address; and, finally, the "Python powered" logo (which is a link back to the home page).

In general, the sidebar should repeat links that are also present elsewhere. in particular, the index.html page for a particular section should have a bulleted list (or some other structure) pointing to its subsections -- it shouldn't rely on the sidebar for listing the subsections. (The sidebar is fine for navigating between subsections.)

Right column: the big "python" logo is at the top of the main page (only).

The rest in the right column is fairly conventional.

Do's and don'ts

Use a number of simpler, smaller pages plus an intro page rather than cramming a lot of stuff on one page. Believe it or not, following a link is often a better navigational tool than scrolling!

Use bulleted lists of links, rather than several links embedded in a flowing paragraph.

Don't use a last changed date. It often fails to be updated (not everybody uses the same Emacs package for editing HTML) and when it's wrong, it's worse than when it's absent.

Off-site links: try to indicate these when it's not obvious, by adding the words "(off-site link)".

HTML style

Header levels: use h2 for the main header and subsequent section headers, and h3 for (rare) subheaders.

Don't use centered headers or text. Really, don't. It clashes with the general style of the web site. You may center images or tables.

Don't use tables to lay out text in the main part of the page.

Fonts: don't specify font names or text colors. Don't use underlined text (it is easily confused with links, since most browsers underline links by default). Use bold (strong) and italics (emph) sparingly. Use italics for emphasis, bold only for special occasions (such as warnings, or as in this paragraph). Don't use italics for email addresses (make them links instead). Use tt (code) very sparingly -- it is rarely necessary and the usual tt font is much too wide. Don't change the font size, except for legalese, which may be set in a smaller size to emphasize that it's "small print".

Tables: don't use borders on tables. See the SIGS page for examples of table lay out -- use the same color as the sidebar background. Don't center columns or column headers, except for very narrow data columns.

Other HTML elements: don't use <HR> (horizontal rules). Don't use <DL> (display lists). When using <UL> and <LI> (bulleted lists), sometimes it looks better with a <p> tag at the end of each item (which inserts white space between the items).

XML well-formedness: We try to keep the pages as well-formed XHTML. This means that all tag names must be written in lowercase, and empty elements such as <br> and <img> should be written as <br /> and <img />.

Template files

A template file is a file with a .ht extension; it is used by a Python script (ht2html.py) as input for the generation of the .html file. The script is generally invoked from a Makefile; it's best to copy an example Makefile. You normally won't have to worry about this. Coordinate with webmaster at python dot org for details on setting this up or changing it.

The template file contains the HTML for the page minus boilerplate; in particular, the script adds the sidebar and site menu. (Note how the .ht extension is extremely filename completion friendly.)

The template starts with one or more headers in RFC-822 (email headers) style. The most important gives the page's title, e.g.:

Title: Python Web Style Guide

Another important header is the content-type. The ht2html conversion script assumes that pages are written in HTML, but reStructuredText is also supported when you include the following header:

Content-type: text/x-rst

The headers are separated from the template body by a blank line. The body normally begins with an <h2> header (the <HEAD> section and the <BODY> tag are supplied by the ht2html.py script).

Sidebar contents: the script looks in two places for text to go in the sidebar. First it looks for a file links.h in the same directory as the .ht file (see below for a way to specify an alternate file). Then it looks for a header named Other-links. It inserts the concatenation of the links.h file and the Other-links header in the sidebar; the "Email us" section and all that follows is automatically supplied. Both should contain stylized HTML that should only use the following elements: H3 to indicate a section header; LI to indicate an item in the section (no UL should be present though!); A to indicate a link; IMG to include an image in the sidebar (see e.g. the Windows 95/98/NT download page). The conversion script massages these items quite a bit, so keep it stylized (follow the example of other pages).

Alternate links file(s): If you add a header of the form:

Links: filename ...

this specifies one or more files to be used instead of the default links.h. Note that in the presence of this header, links.h is not used by default; you must include it explicitly if you want it (normally you do). All listed filenames must exist.

Long or wide pages: it's possible to truncate the sidebar by adding the HTML comment:

<!--table-stop-->

at the point where you want the wide body to start. This must be typed exactly as shown (no spaces inside the comment) and should only appear at the outermost HTML level; i.e. don't stick a table-stop in the middle of a list.

You can also get rid of the sidebar altogether (the random Python image and the site menu stay) by adding the following header to the template:

Wide-page: yes

Other headers: The following additional headers can help you customize your .ht file for your purposes.

• Author: used to specify a different email address for the "Email Us" section. By default this will be webmaster at python dot org so you probably want to use this header to specify your email address.
• Author-email: Some people's email addresses are really long, and this would cause the sidebar to take up too much space on the page. You can specify the address to use for the mailto URL separately from the text inside the link by using this header. Normally, both the mailto URL and the text are taken from the value of the Author: header. If you include the Author-email: header, then the mailto URL address is taken from Author-email: and only the text inside the link is taken from Author:
• Meta: used to stick additional META information into the HEAD tag.
• Sitemap-Ignore: used to omit this page from the automatically generated site map.