TOC page

An index or table of contents page provides a list of related articles. These may be one of two types: a table of contents for a virtual "book" such as the JavaScript Guide, or a list of API terms, such as the CSS Reference. The layout of each of these is the same, but the body content looks different. Let's start with the overall page layout.

Page layout

Summary

The page begins with a brief summary of the document suite for which this is an index or table of contents.

Index or TOC

Then comes a section entitled either "Index" or "Table of Contents". The contents of this section are as follows:

Index

For an index, this is a multi-column area divided up by letter of the alphabet, with items for each page in the suite. For an example, see the CSS Reference.

Table of contents

A table of contents is a simple <ol> (ordered list) of the chapters and, optionally, one or two heading levels deep, of the documents comprising the "book." For example:

1. Introduction to JavaScript (an article at en-US/docs/JavaScript/Guide/Intro)
2. JavaScript terminology (top of an article at en-US/docs/JavaScript/Guide/Terminology)
2.1 Object (the section "Object" in the article en-US/docs/JavaScript/Guide/Terminology)

(etc)

Related topics

A multi-column (when possible) list of other content related to this documentation. For the JavaScript Guide, this list might include the JavaScript Reference, the SpiderMonkey landing page, etc.

Recent changes

The recent changes list is a list of changes to articles in this set of content that have changed recently. For example, on the CSS Reference index page, this would be a list of recent changes to articles in that reference.

Editing

This section describes details of the editing experience for TOC/index pages.

Editing notes

• There is nothing on the sidebar(s) on landing pages that the user needs to be able to edit.

Editing features needed

Add "Related topics" box

This button would create the "Related topics" box at the bottom of the page. Only one such box is allowed per page.

"Link to all subpages" button

This button would insert appropriate KumaScript template to automatically insert links to all subpages. There are two forms of this: (1) a simple list of links, with the text being the title of the destination page; (2) a definition list with the titles being the page titles (linked to the pages) and the descriptions being the pages' summaries.

"Insert alphabetical index" button

This button would insert, in essence, the APIListAlpha template, which generates an alphabetical list of all subpages, <code> styled. This would be used for lists of API terms.

Definition list buttons

We need the buttons for creating <dl> elements, as well as for <dt> and <dd>. We also need to be sure that editing of and deleting these works reliably (it can be a little quirky right now) if we want to remove source editing eventually; currently you have to resort to source mode sometimes to fit problems with the lists. These lists would be used when we need to include pages that aren't subpages.

Bullet list button

We need a button for creating <ul>s, for the offsite link list, for example.

Insert image button

We need to be able to insert images, to use a product or technology logo somewhere on the page (most likely in the intro area).

Link/unlink buttons

We need to be able to create and remove links.

Bold/italic buttons

We should allow creating bold and italic text.

API/function name button(s)

We need buttons for styling text as the name of a class/interface/function name. Ideally these would have different classes on the <code> element for the different types of these, and would automatically create the appropriate link to that term's page, but that may be a long-term goal.

Editing features NOT needed

There are things we expressly do not want to have available in the editor:

• Blockquote
• Tables
• Foreground/background color
• Code samples
• <pre>
• Underline
• Anchor
• Justification (left/center/right)
• Bullet lists
• Ordered lists