• Help on editing Articles

This documentation is written using Markdown syntax. Every page or "article" is a Markdown (.md) file located here in the official SUMO GitHub repository. The static html pages are then generated using Mkdocs.

Feel free to contribute and improve the SUMO Documentation. All changes need to be via Pull requests. You can click on the "Edit on GitHub" button in the top right corner of every page, or just simply press the e key on your keyboard.

Creating an article#

To create a new article (or page) just create a Markdown (.md) file in the documentation directory.

The very first 3 lines of each page should be:

---
title: Name of the Article
---

If you want to create an fresh new article, please consider first seeing the source code of any existing article, to learn and get some basic notions.

Sections and subsections#

Sections and subsections in a document are marked by using the # character.

# is equivalent to a <h1> section, ## to an <h2> and so on.

Example#

#### This is a sub section, equivalent to <h4>

will display:

This is a sub section, equivalent to <h4>#

CSS classes, IDs and key/value pairs#

Markdown allows to use css classes, ids and key/value pairs: https://python-markdown.github.io/extensions/attr_list/

Custom classes:

• .cellNoWrap : Avoid a line break (useful in tables).

Example#

{: #someid .someclass somekey='some value' }

Styling text#

Markdown is compatible with the <sub> and <sup> html-Tags.

• η<sub>recup</sub>=e<sup>x</sup> η_recup=e^x

Example#

Lorem *ipsum* dolor sit amet, *consetetur sadipscing elitr*, sed diam **nonumy** eirmod **tempor invidunt ut labore** et ~~dolore~~ magna ***aliquyam erat, sed diam*** voluptua.

will display:

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.

Escape character#

Use the escape character in order to display literal characters which would have special meaning in Markdown. The escape character is \ (backslash). When writing text inside the `` marks (inline code) or in a code block, no escape character are required.

Here are some expressions that need an escape character:

• @ : if not, it would be taken as a GitHub username
• # : if not, it would be taken as a Header or a GitHub issue
• | : when using it inside a table
• >
• {
• }
• *

Example#

`<TEST1>` using code. No escape character is required here.
<TEST2> not using the escape character. Here the element disappears.
<TEST3\> using the escape character

will display:

<TEST1> using code. No escape character is required here.
not using the escape character. Here the element disappears.
<TEST3> using the escape character

Images#

All images must be saved in the images directory. To insert an image, just use the usual Markdown syntax:

![<alt>](images/Wikicommons_rail_fast.jpg "<title>")

replace <alt> with the alternate text and <title> with the title to show on Mouseover.

Example#

![](images/Wikicommons_rail_fast.jpg)

will display:

Tables#

See this Online Tables generator to get help creating a Table in Markdown, or to convert an existing spreadsheet (e.g. Microsoft Excel) into Markdown.

A table has a Header (the first row), which is separated by hyphens - from the rest of the Table. To separate columns, just use a pipe |.

Example#

|   |   |   |   |   |
|---|---|---|---|---|
|   |   |   |   |   |
|   |   |   |   |   |
|   |   |   |   |   |

will display:

Math#

In order to insert Mathematical expressions (symbols or equations), you should write them in LaTeX format. Math elements are being displayed as images, using a html <img> element. Just replace <HERE> with your math expression in the following html element:

<img src="https://latex.codecogs.com/gif.latex?<HERE>" border="0" style="margin:0;"/>

Example#

<img src="https://latex.codecogs.com/gif.latex?R" border="0" style="margin:0;"/>

will display:

<img src="https://latex.codecogs.com/gif.latex?F(x)=\int^a_b\frac{1}{3}x^3" border="0" style="margin:0;"/>

will display:

Macros / Variables#

In order to make writing this Documentation easier, we implemented some Macros. Macros replace some special text with other content.

Example#

{{SUMO}} {{DT_FILE}} {{DT_STR}} {{Version}}

will display:

<SUMO_HOME> <FILE> <STRING> 1.21.0

Links#

When linking to a page within this Documentation, please consider the absolute path to the Markdown file. Do not forget to add the .md extension to every internal link.

Links to external pages will display an arrow at the end (e.g. DLR).

Links to files in the SUMO GitHub repo#

Using the {{Source}} Macro, linking to files in the official SUMO repository on GitHub is as easy as:

• [Read the gitignore file]({{Source}}.gitignore) Read the gitignore file

• [{{SUMO}}/src/sumo_main.cpp]({{Source}}src/sumo_main.cpp) <SUMO_HOME>/src/sumo_main.cpp

Internal Links#

Internal links are used to refer a special section of an article. You can obtain the internal link to a section by hovering the cursor next to the section title (an # character will appear).

Linking to a section within the same page is as easy as this: Read about Math [Read about Math](#math)

To reference a section on another page, do not forget to put the absolute path and the .md extension, like this: Read about SUMO input [Read about SUMO input](sumo.md#input)

Some characters are being ignored (deleted) or replaced when generating an internal link:

• . is ignored
• : is ignored
• ? is ignored
• ' is ignored
• " is ignored
• / is ignored
• > is ignored
• ( is converted to _
• ) is converted to _
• (space) is converted to _

Here are some practical examples:

Example#

Go to [sumo-gui](sumo-gui.md), [netconvert options](netconvert.md#options) or [Notation](Basics/Notation.md)

<https://www.dlr.de> or [DLR](https://www.dlr.de)

• [Read the gitignore file]({{Source}}.gitignore)
• [{{SUMO}}/src/sumo_main.cpp]({{Source}}src/sumo_main.cpp)

will display:

Go to sumo-gui, netconvert options or Notation

https://www.dlr.de or DLR

• Read the gitignore file
• <SUMO_HOME>/src/sumo_main.cpp

GitHub issues, commits and users#

In order to use the # and @ characters freely, please use the escape character.

Example#

The issue #5697 was reported by @angelobanse. @behrisch committed 3aa106d1bf3221031cca75cfe259913d9d3e88ae to close that issue.

will display:

The issue #5697 was reported by @angelobanse. @behrisch committed 3aa106d to close that issue.

Notes#

The NOTE and CAUTION elements are useful for highlighting important information. You can also use a custom note type.

Inside a Note element you can use Markdown syntax to insert links, stylize text and even insert images.

Example#

!!! note
    When citing SUMO in general please use our current reference
    publication: ["Microscopic Traffic Simulation using SUMO"](https://elib.dlr.de/124092/);
    Pablo Alvarez Lopez, Michael Behrisch, Laura Bieker-Walz, Jakob Erdmann, Yun-Pang Flötteröd,
    Robert Hilbrich, Leonhard Lücken, Johannes Rummel, Peter Wagner, and Evamarie Wießner.
    IEEE Intelligent Transportation Systems Conference (ITSC) 2018.

!!! caution
    The list of not allowed characters is incomplete

!!! incomplete "Missing:"
    This is just a test

{{Outdated}}

will display:

See also#

• Markdown Cheatsheet
• GitHub Guide on Mastering Markdown
• SUMO Documentation images
• Online Markdown Tables generator
• LaTeX Mathematics

• How to Build this Documentation