Folder and Page Structure
This page aims to describe the preferred general structure of how files (pages, images, downloads etc.) should be arranged and named, along with the preferred structure of the individual pages.
By being consistent with these, it will be a) a better user experience, and b) be easier to maintain the documentation.
Please ensure to follow the standards below when creating or updating documentation to ensure the look and feel of the website remains consistent.
The elements of the documentation fall into the following broad categories:
Folders follow the basic structure:
getting-started.rst or overview.rst
… .rst (as needed)
Every folder SHOULD have a ‘index.rst’ file which is the primary navigation point for the pages in the folder
There are exceptions to this rule, but use them carefully.
Every folder SHOULD have either a ‘getting-started.rst’ OR and ‘overview.rst’ file which is the second navigation point for the pages in the folder
There are exceptions to this rule (e.g. the Throttle options), but use them carefully.
Pages generally follow the basic structure:
Page Name (.rst file)
Product Icon (where appropriate)
On This Page - Table of Contents (on longer pages with multiple headings)
The meta keywords help search entries find find the page based on key words.
By using the recommended includes (below) several key meta keywords are included in all pages. i.e.
DCC-EX DCC DCC++ EX DCC++EX
Generally each page should start with any additional meta keywords that are appropriate to the page.
For example, the meta tags for levels.rst are:
.. meta:: :keywords: Comfort Levels Conductor Tinkerer Engineer
All pages MUST include two standard include files.
/include/include.rst and, depending on the depth in the folder structure, one of following as the second file:
.. include:: /include/include.rst .. include:: /include/include-l2.rst .. include:: /include/include-description.rst
The ‘include-description.rst’ will add a generic HTML meta description to the page. You can alternately make use of one the the other include files,or create a new one, to have different description for the page.
If the page specifically, and only, relates to one of the DCC-EX products, then specify the product icon immediately after include files, by using the appropriate expansion:
.. include:: /include/include.rst .. include:: /include/include-l3.rst .. include:: /include/include-description.rst |EX-CS-LOGO| ***************************************
Each page must have a Main Heading. Main Headings MUST have asterisks above and below them:
************* Main Heading *************
See below for more information about heading.
On our Choose Your Comfort Level page, we refer to Conductor, Tinkerer, and Engineer level users, and where possible, we should be using these logos to help users understand what level the documentation is targeted at.
There are two types of logos available, one suitable for callouts or panels which are simply a square graphic, and one suitable for page headings that contains the graphic and the text.
Where possible, use the expansions for the level images:
Where possible, use the Team and Product names the expansions (not possible in headings)
|DCC-EX| for DCC-EX
|EX-CS| for EX‑CommandStation
|EX-I| for EX‑Installer
|EX-R| for EX‑RAIL
|EX-TT| for EX‑Turntable
|EX-DCCI| for EX‑DCCInspector
|BSC| for BaseStationClassic (DCC++)
Where possible, use the expansions for the level text
Only if really necessary use image tags:
.. image:: /_static/images/conductor.png :alt: Conductor Level :scale: 40% .. image:: /_static/images/conductor-level.png :alt: Conductor Level :scale: 40%
Pages with multiple headings should generally have a Table of Contents. The depth of the table is a subjective decision.
.. sidebar:: .. contents:: On this page :depth: 4 :local:
Page content can include:
After the heading, the page should start with an explanation of the purpose of the page.
Main Headings have asterisks above and below them:
************ Main Heading ************
Subheadings are underlined with equals signs:
The next level is underlined with hyphens:
Next level ----------
And the next level is underlined with carets:
Next level ^^^^^^^^^^
The next one we use is underlined with tildes:
Next level ~~~~~~~~~~
The last one we use is underlined with underscores:
Next level __________
All heading underlines and overlines must be at least as long as the text of the heading text.
Click next to learn how to enhance your content with links, tales, images, etc.