1.7. Creating content in markdown

Online tutorials and cheatsheets are available to help with the markdown formatting.

1.7.1. Markdown source style guide

We are following the Google Developer Documentation Style Guide.

In short this instructs:

  • Don’t use tabs to indent text; use spaces only. Different text editors interpret tabs differently, and some Markdown features expect spaces and not tabs.

  • Indent by 2 spaces per indentation level.

  • Use all-lowercase for elements and attributes.

  • Don’t leave trailing spaces at the end of a line. (Except as needed for Markdown.)

Line length of 80 characters except in following cases:

  • The metadata tags at the top of files (such as page.metaDescription) have to be all on one line, so those lines can be as long as needed.

  • If a URL in a link has a line break, the link won’t work. If a URL is longer than 80 characters (quite common), you’re stuck with it. In that case, put the URL on its own line with the href attribute to make it easier to review the text before and after.

The fold command can be used to limit a file’s line length folding at whitespace, e.g.:

fold -s -w80 <file_with_long_lines> > <file_with_80char_lines>

1.7.2. Embedding reStructuredText

Embedded reStructuredText can also be added to the markdown files to accomplish commands that markdown does not yet encompass. This is accomplished using a code block followed by the term eval_rst. This ensures that the code within the code block is parsed as rst. For example:

```eval_rst
 ... (rst code)
```

The following are examples where this is useful for formatting in documents:

  • Insert the contents of a txt file inline:

    ```eval_rst
    .. literalinclude:: inlinetextfromfile.txt
    ```
    
  • Create a table:

    ```eval_rst
      ============= ============
      Property      Description
      ============= ============
      Item1         Description1
      Item2         Description2
      Item3         Description3
      ============= ============
    ```
    

For a complete list of reStructuredText Directives available for use in an embedded reStructuredText block see reStructuredText Directives.

1.7.3. Creating large tables

As described in the previous section, simple tables can be created by embedding reStructuredText into your source .md file. For larger tables with single table cells containing multiple rows of text it is recommended to use the reStructuredText list-table directive, as this provides more control over table formatting. For an example of this in use see table in section Quick start guide.

When using the list-table directive it is important that the complete contents of a cell appear on a single line in the source .md file, i.e. it must break the markdown source style guide 80 character line length limit if the cell’s content requires. If cell contents span source .md file lines then a build warning will occur and the table will not display correctly when the html is viewed in a browser. If you want to add a line-break into a table cell use role:: raw-html(raw), see below.

To high-light cell contents and/or make the table easier to read, the text colour of a cell can be modified using the role directive to specify the colour to make available within the current eval_rst block. E.g. the following is the source of the table header and 1st row of table used in the Quick start guide:

```eval_rst
  .. role:: blue

  .. list-table::
     :widths: 5 25 70
     :header-rows: 1

     * - :blue:`Step`
       - Instruction
       - More information
     * - :blue:`1`
       - ``make vp_plugins``
       - If not previously done build and install GenerateCD VP plug-in, requires access to Java compilier compatible with Java version in use by Visual Paradigm.
```

Which produces the following with text of first column coloured blue:

Step

Instruction

More information

1

make vp_plugins

If not previously done build and install GenerateCD VP plug-in, requires access to Java compilier compatible with Java version in use by Visual Paradigm.

The colours available for use as an argument for the .. role:: directive are dependent upon the contents of the custom CSS code contained in the file gda-documentation/common/_static/cutom.css. Currently this defines the following colours:

  • blue

  • green

  • grey

  • orange

To add a line-break/newline within the contents of a list-table cell without breaking the rule that the complete contents of a cell must appear on a single line in the source .md file, use the role:: raw-html(raw) directive together with :raw-html:`<br />`, e.g.:

```eval_rst
  .. role:: raw-html(raw)
    :format: html

  .. list-table::
     :widths: 5 25 70
     :header-rows: 1

     * - Step
       - Instruction
       - More information
     * - 1
       - Information with line-break
       - This is information with line-break: :raw-html:`<br />` to add :raw-html:`<br />` one or :raw-html:`<br />` :raw-html:`<br />` more line-breaks in a table cell.
```

The above produces the following table:

Step

Instruction

More information

1

Information with line-break

This is information with line-break:
to add
one or

more line-breaks in a table cell.

1.7.4. Indexing and searching

Sphinx has been configured to automatically create an Index which is easy to navigate to from the sidebar of the built html. The index shows key items or tasks that readers may want to reference and provides a link straight to the relevant page. This is different from the the ‘search’ feature which is simply a text based search of the whole document and so may not always be useful if the reader wants to go straight to a definition or look up.

To add an item that you are documenting to the index, simply add the following below the item in your markdown file:

```eval_rst
.. index:: <index name>
```

It is also possible to have multiple index links under a common object, for example, ‘Device’ could have a link to a Definition and an Example etc. This can be achieved using the following:

```eval_rst
.. index:: <category>; <index name>
```

E.g.

```eval_rst
.. index:: Device; Definition
```

In this case, ‘Definition’ will be the link under the name ‘Device’ (which is not linked). See here for how this ‘Device’ example is rendered during the html build.