To main heading

Smallsite Design

Online editing help

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. The menu bars are created when the page is rendered and facilitate rapid discoverability and access. There is a menu bar 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.

Sample section details are:
Sample section detailsabcde
The section details are:
#FieldDescription
a3 Section 6Article/section child number before, and the element's child status after
bHeadingHeading for the section. Cannot be changed to one that already exists
cNavigationShort version of the Heading to be used in the menu bar links
dIntroductionDescription of what the section is about
eLinked fromDetails 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 or its glossary or subsections.

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.

Clicking the Articles checkbox in the Linked from row shows the list of articles like:
where:
#AreaDescription
aIDID for this section, followed by the number of links in the current article that would be affected by changing the Heading
bArticleCalling 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
cFragmentID 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
dThe 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.

Warning
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 minimise such situations, do not assign an article for editing until just before edits are to be done.

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.

There are some functional limitations of glossaries in a general article compared to a standalone glossary article, being that they don't:

  1. a.Allow more than 20 entries.
  2. b.Have a navigation bar providing links to every fifth entry.

None of these limit the utility of the entries themselves, which still allow formatting and links in their descriptions.

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 is that it can contain up to three levels and that 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 a glossary is fulfilling its purpose well, though if the existing 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:

  1. 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.
  2. b.Click on the Subsite links jump in the same row to open the Links page.
  3. c.Add the new glossary article.
    The new link will appear on a line above the now hidden link.
  4. d.Repeat for each other subsite to use the same article.

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 ordered 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.

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 article 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 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:

  1. a.A picture or short video of the author, or something about them.
  2. b.Significant quotes from the main text.
  3. c.An image that is related to the text but not critical to its understanding.
  4. d.Audio, video or presentation that is optional for the reader to use as an experiential aspect of the description in the main text.
  5. e.An image with labels for which a table or list 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.

  • Table element
  • Sequence element
  • Procedure article element
  • Contact   Glossary   Policies
  • Categories   Feed   Site map

  • This site doesn't store cookies or other files on your device when visiting public pages.
    External sites: Open in a new tab or window, and might store cookies or other files on your device. Visit them at your own risk.
    Powered by: Smallsite Design©Patanjali Sokaris