These guidelines describe how markdown specifications are to be written. The following clauses will describe the elements markdown specifications can be composed of.
## Headings
Clause headings **shall be added** by adding as many "#" symbols as the required clause level. Example:
### My level 3 clause
## Paragraphs
## Table of contents
Table of contents **shall NOT be added**. Gitlab provides already a dynamic generation of Table of Content when viewing the specification in the repository (available for both render and raw views, functionning only for render view).
The **Contents** clause **SHALL BE present** in the specification as level 1 for the automated pipelines:
# Contents
## Figures
Figures can be specified by adding the corresponding image file to the media folder, and by inserting a reference to the given figure. Figures **shall be composed of** the figure reference and the figure caption. It **shall conform** to the following format:
**Figure <Clause number>-<Figure number in clause>: <Figure title>**
E.g.
**Figure 1.2-2: My figure title**
**.png, .jpg and .svg** are supported as image files.
## Tables
Tables can be specified by using two different approaches:
1. Pipe tables. This kind of tables can be used for simple tables (no merge cells). Rows (header and body) are defined by using "|" to separate cells. Header and body
must be separated by a line containing the same number of pipes and "-" symbol between pipes. Note that "-" can define the width of columns. By using just one "-", default
width is justified
E.g.
|Title 1|**Title 2**|Title 3|
|-|-|-|
|Row 1 Cell 1|Row 1 Cell 2|Row 1 Cell 3|
|Row 2 Cell 1|Row 2 Cell 2|Row 2 Cell 3|
2. Grid tables. This kind of tables can be used for complex tables where merge cells are needed. Grid tables use separator lines between data rows (header and body).
Separator lines are composed of "+" symbols and "-" or "=" between the "+" symbols. "="s are used to separate header and body. Columns MUST be aligned, meaning that
position of "+" must be the same for every separator line, unless merged columns are being used. Body rows are defined as pipe tables rows, by using "|" to separate cells.
However, separator lines can be defined for certain columns, which make possible to define merge cells.
E.g.
+------------+------------+------------+
|Title 1 |__Title 2__ |Title 3 |
+============+============+============+
|Merged |Row 1 Cell 2|Row 1 Cell 3|
| +-------------------------+
|Rows |Merged columns |
+------------+-------------------------+
> Note: Grid tables are not supported by GitLab, so they will not be rendered (Title 2 not rendered in italic)
Text formatting (bold, italic, links), lists, multiline can be used in both pipe and grid tables.
Table caption **shall be used** and **shall preceed** the table (one blank line between table caption and table definition) and shall follow the format:
**Table <Clause Number>-<Table number in clause>: <Table title>**<aname="table_<Clause number>-<Table number in clause"></a>
E.g. ****Table 1.2.3-1: My nice table**<aname="table_1.2.3-1"></a>
Alignment can be used in both pipe and grid tables by inserting ":" in the header separator lines either on the left (for left alignment) or on the right (for right alignment), default alignment is center:
More detailed information can be found at [Pandoc documentation](https://pandoc.org/MANUAL.html#extension-grid_tables)
## Diagrams
Diagrams can be specified by using UML diagrams. The recommendation is to generate the PlantUML diagram image by using any PlantUML online servers ([ETSI PlantUML server](http://tools.etsi.org/plant)), and adding both the source code (.puml) and the image files to the media folder. Then, the diagram can be added as a normal figure as described at [Figures](#-figures).
