3 General article element

A general article has the most flexible content model, allowing most blocks, a glossary and sections, with those able to contains their own.

General articles and their sections and subsections can have up to 50 blocks, such as paragraphs, lists, tables or asides, and one glossary. An article can have up to 20 sections with up to nine subsections in each. Thus a general article can have a lot of content but still be relatively easy to navigate around. While an article can have so much content, actually filling it with that much may overload a web server's capacity to serve it.

Sections and subsections can have numbering before the heading in the form of 1 and 1-1 respectively, which can be useful for terms and conditions pages or other legal instruments. They are set by the Numbering attribute on the article element.

Section / subsection△

Sections and subsections allow for hierarchical information presentation.

Sections and subsections help to break up a detailed article into readable blocks that can be individually accessed. They are what can make a body of knowledge usable as a reference. There is a menu bar created at rendering time under the article header with links to all its sections, and if they have any subsections, they have their own menu bar under their header with links to all of them.

The section details are:
#	Field	Description
a	3 Section 6	Article/section child number before, and the element's child status after
b	Heading	Heading for the section. Cannot be changed to one that already exists
c	Navigation	Short version of the Heading to be used in the menu bar links
d	Introduction	Description of what the section is about
e	Linked from	Details of what links will be affected if this section is renamed. See Linked from

The identifier used by links is derived from the master locale Heading by converting it all to lowercase, then converting each sequence of non-alphanumeric characters to a single -. For example, the identifier for this section is section-subsection. The derived identifier must also be unique within the article. Subsection (and glossary entry) identifiers must be unique to their parent section, but will be prefixed with the parent section's identifier and -- in links to make them unique to the article.

If there is no text specified for links, they will use the text of their target's heading. To maximise avoiding having to use text in links, make heading text use sentence case, where only the first letter of the heading is capitalised, other than where the language usually uses capitals in body text, such as proper nouns in English and all nouns in German. Links have a First letter attribute which allows changing the case of the first letter so that the heading can be used for the link's text with a case that suits its context.

Like most introductions, those for sections and subsections are meant to be indicative of the content, so that a reader can decide whether the content is useful for them, but it should not be relied upon for critical information, as it will probably be ignored after that decision is made. Thus any important information should be after the introduction, with any critical information that defines how the section should be viewed put in the first in-line block after the introduction.

Each section or subsection can have a basic aside, consisting of a heading and a paragraph, or introduction and image and an optional quote. These can provide some simple visual embellishment to make a page more varied and attractive. However, images in basic asides cannot have labels, so cannot link to inline tables or lists.

Linked from△

The Linked from row provides a list of what links in the current article and other articles refer to the current section, subsection or glossary entry.

The information in this row shows the extent of links that are dependent upon the ID and that may deter making changes that may be too disruptive to the contexts of the source links. This row is also present for other elements with an ID that can be a link target, being a subsection, glossary entry in a general article or a glossary page, or custom section of a policies page. Any links to these will display a pop-in when hovered over.

Sample section Linked from list — Clicking the Articles checkbox in the Linked from row shows the list of articles like:

where:
#	Area	Description
a	ID	ID for this section, followed by the number of links Internal to the current article and other Articles that would be affected by changing the Heading
b	article	Calling article's ID as a jump to the title cell of the Inline row of the Links to section of the Article head page for the article
c	fragment	ID of the element pointed to by the article's links as a jump to its corresponding line in the Target details column of the Inline row of the Links to section table of the Article head page for that article
d	✎	The article is currently being edited. Any links in that article's latest WIP version that point to the current element or its descendants with IDs will have to be updated manually as part of their current edits after the new ID is saved with the current article's release

If editing the master locale Heading creates a new ID, any links to it in the current article are updated immediately to use the new ID as their fragment, except if the section has a duplicate ID, such as may occur if appending or inserting from spikes. However, links in other articles are not updated in their latest release by being overwritten until the current article is released.

Warnings:

a.Non-release versions for any articles currently being edited are not updated, as they may be overwritten by edits currently in progress. Ensure any affected links are updated manually in those articles as part of their current editing sessions. That can only be done after the current document is released, as the updated link fragments will not show up in the target selection lists for those links until then. Those links will appear as ʘ?ʘ in the Article body page and when viewed. To avoid such situations, do not assign dependent articles for editing until after releasing the current article.
b.Any changes to the positions of elements with ids using the spikes or To facility will not automatically trigger updates to links to them. After moving elements around, click the Check button on the Check links page to see what issues might have been created. If an inline internal link has problems with the fragment it targets, within the article it will be followed by ?, except, if it has no Text, ʘ?ʘ will be shown instead. Use the Check links page to target the link host articles for editing to correct their links.

Glossary△

While a glossary structure in a general article could be used for terms, it is more useful than that.

A general article can have a hierarchical structure with its section / subsections. This gives an opportunity to use a glossary at each level, allowing a three-tier descriptive listing, and with up to 20 entries per glossary allows a total entry count of over 4,000 entries. Each entry can be enhanced with a picture. The obvious use for this is with a company staff listing, with management in the base article area, division heads and support staff in their own sections, and section heads and their staff in subsections under them.

The entry headings allow a maximum of 40 characters and a paragraph worth of rich-text content, so some attention needs to be paid to the structure used in them. If all position titles are short, the heading could have both the position and occupant name. Otherwise, put the position in the heading to allow links to it, and put the occupant's name as an emphasis element followed by a break to keep it on its own line. However, having the occupant's name in the heading means that any links in other articles would have to be updated whenever a position has a new occupant.

The hierarchical structure can be extended downwards and laterally by linking to further such articles in the entry body, so quite sophisticated or voluminous structures can be easily accommodated. Entries can also appear in pop-ins, so in the staff list scenario, a link to a person's position in another article can show a picture and a description when hovered over for a second.

Note that the glossary entries also have link target identifiers derived from their headings and those must be unique to their parent element, meaning that sections/subsections and glossary entries cannot have headings with the same identifier within the same parent element.

What a glossary in a general article can have compared to a standalone glossary article are:

a.It is limited to 20 entries.
b.An entry heading can be a link to an article, category or an external page.
c.The navigation bar providing links to every fifth entry is at the end of the introduction.
d.Every third entry has a △ as a link to the first letter of the introduction.
e.Up to two paragraphs or lists can be appended, to show after the list of entries. Useful for some remarks about the glossary, or specific entries in it. See also Modifying the glossary.

Subsite structured glossary△

Another use for glossaries in articles is to build a structured glossary that could be used instead of a subsite's standard glossary.

The advantage of a structured glossary is that it can contain up to three levels and that means a possible 4,000 entries in total compared to the 99 in a standard glossary. However, back-fitting this to replace an existing glossary may involve a lot of updating to articles with links to the current glossary, which may be quite extensive if the current glossary is linked to a lot, though if that glossary remains listed, those updates could be phased in over time.

If wanting to use an article built as a structured glossary instead of the standard subsite glossary:

a.Disable the Glossary checkbox in the Subsite links row of the Links to section table on the Subsite page for the subsite.
This hides the link to any current subsite glossary.
b.Click on the Subsite links jump in the same row to open the Links page.
c.Add the new glossary article.
The new link will appear on a line above the now hidden link.
d.Repeat for each other subsite to use the same article.

Modifying the glossary△

Sometimes it is useful to move content from a verbose glossary entry to a paragraph after the glossary.

Glossary entries are meant to be fairly concise, so that their information can be read and understood quickly. In general, all entries will tend to be of roughly the same size. However, an occasional entry might be quite verbose, so that it appears too visually distinct, overshadowing the other entries. Retaining the initial sentence, the rest could be put into a paragraph after the glossary.

If the entry is all plain text, then adding a paragraph and cut-and-pasting the excess text into it is a simple solution. However, if the entry is formatted, putting the entry on a spike, and then appending it to the glossary as a paragraph, as per Substitutions, would appear to be the obvious solution. The snag is that an entry cannot be appended to a glossary as a paragraph because the entry is a native child of the glossary, and that precludes it being substituted as something else. The solution is to append a blank paragraph to the glossary, and then replace it with the entry from the spike.

If there are more than one such verbose entries, a list can be appended to the glossary, and its items can be directly substituted by those entries from a spike. Using paragraphs or a list, the entries will lose their headings, and so their opening text will have to be edited to make sure they are clear about which entry they apply to.

Aside△

An aside is a bordered headed area off to the side, but it is still a topic of debate as to what it is meant to contain.

An aside is a bordered area to the end-side of the page with a heading. It is often used for pictures or other media. Though not considered essential to the article, they can provide some extra related information. Any following free-flowing elements will render to its starting side then go full-width after it, except for tables, which will stay narrowed.

An aside's position indicates that it might be able to be safely ignored. Certainly, the preponderance of pages with advertising down the side has predisposed readers to ignoring anything that is not obviously part of the main flow. This makes putting anything in an aside that might be important rather precarious.

As Smallsite Design does not allow any third-party ads, readers will ascertain fairly quickly that asides are more likely to contain some useful information relevant to the article. Some sites have put loosely-related content, like related articles in asides, but as Smallsite Design provides a separate area at the end of articles for those, readers will further expect asides to be more closely related to the article itself.

Asides have been used for tangentially-related information, but Smallsite Design allows footnotes which are better suited for that, especially since they are bidirectionally linked to the specific block of text of the article to which they refer.

So, given that many of the uses for which asides have been used are catered for by better-suited elements, what does that leave asides for? For that, look to that an aside is walled off to the minor side of the main text, indicating that it is likely of lesser importance or less tightly-coupled to the main text.

That leaves asides to be used for:

a.A picture or short video of the author, or something about them.
b.Significant quotes from the main text.
c.An image that is related to the text but not critical to its understanding.
d.Audio, video or presentation that is optional for the reader to use as an experiential aspect of the description in the main text.
e.An image with labels for which a table or list within the main part of the article provides descriptions. This may be stretching the loosely-related criterion, but it does allow them to be side-by-side for easier visual comparisons or reference, especially if the image is long.

In any case, keep the content of an aside to only one aspect or topic to avoid it becoming too much of a distraction, which might detract from the article itself. It should only ever be considered a supplement, otherwise its content should be in the main flow of the article, perhaps in its own section or subsection.

Warning
An aside is a floating element that displaces the content next to it, forcing that content to wrap around the aside. Many elements, like a paragraph, can have an image that floats to its end side, displacing the element's text. Having two floating elements in the same area can sometimes produce odd results, such as one appearing within the next element after both elements. In general, avoid having an element with a floating image next to an aside.