Edit the Article

Most content on MDN is this type of page. An article page is any article whose content is primarily text. These pages can of course also include images, tables, and so forth, in order to present information effectively.

Content layout

Article content

The article's content takes up most of the page.

Tables

There are several types of table. In general, tables should all use the same style as much as possible.

1. CSS property summaries.
2. Side-by-side sample output. These have two columns, one showing the output from a live sample, and another showing a still image screenshot of what it should look like (for users whose browser doesn't suppor tthe feature being demonstrated).
3. Compatibility tables.
4. Specification tables.
5. General tables as needed by content (these in particular should all have the same style as one another).

Lists

We are switching to consistently use <dl> lists for all lists of methods, properties, and attributes in documentation. Currently some of our documentation uses tables for this.

Image presentation

There are three use cases for images.

1. A standalone image is one that's by itself on a line between text blocks. We need to decide whether these should be left-justified or centered, then always present these images that way.
2. A floating image is one that has text wrapped around it. These may float either to the left or to the right edge of the content area.
3. A image strip is when multiple images are displayed side-by-side, wrapping to multiple lines if needed. Image strips are used, for example, to show multiple examples of what a given CSS property may look like depending on its value.

Images should be able to have a caption displayed with them.

Summary

The summary is a brief paragraph or two explaining the technology; this comes before the first section heading in the article.

Sidebar

Below the Edit and History buttons are the following boxes or areas.

Table of Contents

The page's TOC lists the sections in the article, each as a link to take you to that section. The depth of the TOC is, by default, to show H2-H4, but can be configured per-page to be different (or to leave off the TOC entirely).

The TOC box grows vertically to be as tall as needed to contain all its content. We should consider making it collapsible so the user can show and hide subtrees in the TOC as they wish (or at least offer a way for them to adjust how deep it goes for themselves).

Related

The "Related" box lists related pages. This box replaces the "See also" sections we currently show in-content on many pages. We could either have this box a seprate editable region in the editor or pull that content from a "See also" section in the article content to display in the box, removing it from the body at display time.

Languages (?)

Do we want to show a list of the languages you can read the page in here? Listing them instead of using a popup menu to choose the language has the advantage of being much more obvious, but it might take too much space.

Editing

This section provides details about editing functionality for article pages.

Editing notes

• The only sidebar area the user needs to be able to edit is the "Related pages" box. Exactly how we present this is TBD. Perhaps we actually have a separate editor area for that?

Editor features needed

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.

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 for screen shots, diagrams, and so forth. We need to take special care to ensure that SVG works well, and we should try to make it easy to get at these for localization purposes. How about a diagram localization tool that can help translate the strings in SVG files?

Link/unlink buttons

We need to be able to create and remove links, both in-site and off-site, easily.

Bold/italic/underline buttons

We should allow creating bold, underline, and italic text.

Strike-out button

We should allow striking out text, although we don't use it often.

Bullet/ordered list buttons

We will need the ability to do bullet and numbered lists.

<pre>

We need support for using preformatted text blocks, even if they're not being used as live samples, and we need to be able to choose a language for syntax highlighting (again, even if not being used for live samples).

Live sample buttons

We need controls for inserting live samples. This should include support for setting the size of the box, choosing additional CSS to apply, and probably other settings that aren't occurring to me.

H2-H6

We need headers. These should automatically be able to be linked to and should appear in the TOC as appropriate for the page's maximum TOC depth setting.

Blockquote

We don't use this much but there are legitimate use cases, so we should offer it.

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.

Note box and warning box

Easy access to insert note and warning boxes.

Multi-column lists

Ability to use multiple columns to display lists of links, names of items, and so forth.

SEO summary

Option to set a selection to be the page's SEO summary; this provides refinement over just defaulting to the opening paragraph or so.

Import from page

An option to display content from another page when the page is rendered; this should allow insertion of either the entire page or just a given section of it. Choosing the page and (optionally) section should be made as easy as possible, perhaps using two control areas side by side, one for picking a page, and the other for picking a section from the selected page.

Insert source link

An option to insert a link to a source file on MXR. We should provide support for selecting which branch to use (defaulting to mozilla-central), then either typing a path and validating that it exists, searching for a match (by either filename or identifier's definition) or choosing a path from a list. It could be extra helpful to offer support for doing a quick search based on the name of the page, since this would frequently be used on a page whose name exactly matches a given API.

Editing features NOT needed

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

• Foreground/background color
• Justification (left/center/right)