Style and conventions

Extended Markdown

Basics

All the common Markdown features are supported. Showdown is used to convert Markdown to HTML, so the showdown demo is a perfect example of the basic features:

http://showdownjs.github.io/demo/

Noteworthy Markdown features

Highlighted code in quotes

The following syntax allows to integrate highlighted code in a quote:

> my quote

> ```python
> import sys
> ```

Anchors

Which objects have an anchor?

• titles
• figure legends
• api

The anchors of the titles and the figure legends are generated by converting their content using the slugify function. The API anchor is directly used as anchor.

Slugify function

The slugify function is replacing some text (e.g. "My C++ snippet.") to a string compatible with URL links (e.g. "my-cpp-snippet"). It is defined here:

https://github.com/omichel/webots-doc/blob/gh-pages/scripts/showdown-extensions.js#L2

Extensions

Some extensions have been written to manage particular cases.

Variables

Dynamic variables can be used following this pattern:

{{ variableName }}

The supported variables are:

{
  webots : {
    version : {
      major : 8,
      minor : 4,
      bugfix : 1
    }
  },
  date : {
    year : 2016
  }
}

For example:

{{webots.version.major}}.{{webots.version.minor}}.{{webots.version.bugfix}}

is converted to:

8.4.1

Figures

Figures with legends can be used following this pattern:

%figure "My legend."

![my image](path/to/my/image.png)

%end

The legend converted to an anchor thanks to the slugify function (e.g. #my-legend is a valid anchor here)

Charts

You can add FlowCharts and Sequence Diagrams with this pattern:

%chart
graph TD
    Start --> Stop
%end

or:

%chart
sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
%end

It is recommended to put your chart inside a figure:

%figure "This is an awesome chart!"
%chart
graph TD
    Start --> Stop
%end
%end

API

API blocks can be created following this pattern:

%api "anchor"

content

%end

The API anchor can be used to refer this API in particular.