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.