MaTeS Syntax

Learn how to build web pages and HTML5 slide decks.

About MaTeS Motivation, design philosophy and use cases

MaTeS is a tool to easily create web pages and web-based presentations. It uses a variant of the Markdown language which has been around for some time to structure documents in a lightweight syntax. The difference to traditional markup, e.g. HTML or XML, is that MaTeS keeps the focus on the text.

Grid system Rock the standard 940px


The grid inherited from Bootstrap [2] is 940px wide and split into 16 cells. The entire documents is vertically split into rows which are horizontally split in spans. Usage of the grid system (i.e. rows and spans) is optional.


A newline followed by #row opens a new row. Rows are stacked vertically as you might have expected. If you do not issue a #row command, a row will be opened automatically for you.


A newline followed by #span3 will open a span that covers four grid cells. Subsequent spans will be added to the right. To achieve a formatting as in this document you must use #span3 and #span9 as follows:
 ### Heading left

 Some text ... 

 #### Heading right
 Some text ...
The total number of span cells in each row should add up to no more than 16. It is not a fatal error if your spans cover more than 16 cells. The page will grow to the right, but this breaks the layout idea somehow.
If you do not use spans at all, then the text of your row will implicitly be hosted inside a #span12 environment. Rows and spans result in HTML <div> elements which can be styled by using the normal paragraph styling. This is usually not required, but it is sometimes useful to add some spacing or borders.

Page Structure Skeleton of a document

Page Header

Optionally, you can specify a page header which is just a row that can be styled differenly.

Structuring a page

The page header is usually the first row in your document. However, you are free to use it anywhere. A page header is declared by #page, otherwise it behaves exactly like a row. In the default style, the page header is shown in a light grey whereas rows have a white background.
A complete document may look like this:
 ## Page heading
 Some text following the heading. The background is grey here.

 ## Content heading
 This text and heading feature the normal white background.
However, you can leave the #page header out and simply write
 ## Heading
 Some text
In this example the row and span has been opened implicitly and no page header is shown. There is no need to write it down explicitly if you have no special layout wishes.


The first line(s) of the document are dedicated to meta-data. The displayable content starts with the first newline followed by a hashtag. Thus, at least the first line always contains meta data, which is used to define titles, templates, etc.

Meta-data values

Meta-data appears at the beginning of the document. All lines up to the first line starting with # is treated as meta-data. Each meta-data line denotes a key-value pair. The :-symbol separates the key from the value. The meta-data values are processed by the MaTeS compiler and can influence the navigation bar or determine the output format.


The title: value defines the web page title shown in the browser. You should always define a title, otherwise the short title is used. If this is empty as well, the title remains empty.

Short title

When a menu structure for navigation is produced, then the property short-title: is used in the navigation menu. If no short title is specified, then the title: property is used instead.


To distinguish between web pages and slide shows, you can specify the schema: property. By default, the schema is that of a web page.


Sometimes you may want to change the look of the generated HTML, e.g. use a different navigation bar, use some custom CSS roles or even introduce use some special commands, e.g. #paper, #title, #author, #abstract to render a scientific paper. All of this can be achieved by a so called page template. You can specify such a template using the template: meta-data, followed by the name of a page template file, e.g. template:templates/ This is optional, however. The structure of page templates is explained later in this document since it is not essential to getting started.


You can link to CSS files to style the HTML. Just use the css: property. The value right of the column can be any kind of URL or relative path. Use the CSS property multiple times to link multiple CSS files.


You can link to JavaScript files to add functionality to your web pages and slides. Just use the script: property. The value right of the column can be any kind of URL or relative path. Use the script property multiple times to link multiple script files.


A complete document might look as follows. However, the line schema:page is usually left out because this is the default. Furthermore, most pages will have no need to link additional CSS and JavaScript files.
 title:Hello World

 ## Hello World

Typography Headings, paragraphs, lists, and other inline type elements


A heading is introduced by a newline followed by two, three, four or five hash symbols (#). The heading text can span multiple lines. It is terminated with the beginning of the next section

Heading 1

Heading 2

Heading 3

Heading 4

Syntax for headings

There are four different heading available. If you really have a good usecase for more headings, let us know.
 ## Heading 1
 ### Headnig 2
 #### Heading 3
 ##### Heading 4


A paragraph is introduced by an empty line, or a newline followed by the #-symbol. A paragraph can span multiple lines, but an empty lines starts a new paragraph. A paragraph is automatically terminated with the beginning of the next section, e.g. a heading, enumeration etc. pp.

Syntax for paragraphs

The following example shows how to start new paragraph using the #-symbol.
 ## Heading 1
 # The paragraph starts here ...
 and continues here
 # This starts a new paragraph
 Yet another paragraph.
To simplify the syntax, a new paragraph is started by one or more empty lines. Thus, the above example can be rewritten as
 ## Heading 1
 The paragraph starts here ...
 and continues here
 This starts a new paragraph
 Yet another paragraph.


Ordered and unordered lists are supported. They can be arbitrarily nested. There is no special syntax for opening or closing a list. Just write down the list items. A list item is terminated by the next newline that is followed by a hash symbol, i.e. when a new item or a new paragraph etc. begins.

Unordered lists

Each list item must begin with a newline and an asterisk (*) followed by white space. Sub-lists are created by providing multiple asterisk symbols.
 - Item 1
 -- Item 1.1
 -- Item 1.2
 - Item 2

Ordered lists

Each list item must begin with a newline and a dash (-) followed by white space. Sub-lists are created by providing multiple dash symbols.
 * Item 1
 ** Item 1.1
 ** Item 1.2
 * Item 2

Mixed lists

It is possible to mix ordered an unordered lists.
 * Item 1
 *- Item 1.1. has no numbering
 *- Item 1.2. has no numbering
 * Item 2

List example

The example to the left is displayed as:
  1. Item 1
    • Item 1.1. has no numbering
    • Item 1.2. has no numbering
  2. Item 2


Code can either be shown in an extra block or inlined in the text. By default, Google's prettify [1] is used to style code blocks.

Inlining code

In all places where you can use normal text, you can mark code using the back-tick symbol.
 In Go an increment like `number++` is a statement.
This results in the output: In Go an increment like number++ is a statement.

Code blocks

Entire code blocks must start with a newline followed by #code and some white space. It is terminated by the first occurrence of a newline followed by a hash symbol.
 void main() {
Note that the enclosed code can contain the # symbol. To avoid that it terminates the code block, you must indent it. Hence, it is good practice to indent all code by at least one character.

Syntax highlighting in code blocks

By default, code blocks use syntax highlighting. The system tries to guess the programming language, but you can optionally set it using a HTML class as shown here:
  <h1>This is HTML<h1>
  class Foo {
The above example is shown as
 <h1>This is HTML<h1>
 class Foo {
To get a full list of supported languages, have a look at Google's Prettify JS project [1]. If you do not want syntax highlighting, you can write #code;nosyntax.

Line numbers in code blocks

Using the linenums HTML class, a code block can be extended with line numbers. If the line numbering should not start by 1, you can add the initial line number behind a colon, e.g. linenums:4. The following example
  class Foo {
is rendered as
 class Foo {


Entire paragraphs and text slices can be easily styled. Some default styles to mark text as <strong> or <small> are provided. For all other matters, the full spectrum of CSS styles can be used. In addition, CSS classes can be used which allows to style these elements via a CSS file.

Styling a paragraph

Style information can be applied to each MaTeS that starts with newline and #, - or *. This way you can style headings, paragraphs, list elements, table cells, etc. To generate a green heading just type: ##;color:green. Styling a paragraph works exactly the same, just write #;color:red to start a red paragraph. This is the reason why there are two ways of starting a new paragraph: empty line or #. The first option is easier to the eye, the second options allows to style a paragraph using CSS. As in CSS multiple values can be concatenated by ;. Whitespace is not allowed between or inside CSS values, because everything following white space is treated as normal text. If you really need a white space, you must escape it with a backslash.
 Large red heading
You can influence the HTML class that is being generated via the class: property.
 A very important heading
This is preferable, because it allows to style important headings via CSS. As a shortcut, you can omit the class: prefix. The compiler will treat all values with a : as a CSS style and all others as a class. Thus, the above example can be rewritten as:
 A very important heading
There are three exemptions from the general rules of styling. Three predefined styles allow for typing less. The style value * means bold, _ means small and / means italic.

Styling text slices

The curly bracket { indicates a style change. After the bracket you can use the same syntax as for paragraph styling. For example we can mark a word as bold by writing {*word}. The closing bracket } reverts to the default style of the current paragraph or heading.
Note that there is no need to close a bracket once it has been opened. The following is perfectly valid
 This is {color:green GREEN {color:red RED {color:blue BLUE}.
In fact, the closing bracket } is just a short-cut for { . Note that each occurrence of { overwrites the current style, thus the expression {color:green GREEN {*BOLD} shows the word BOLD in black, because {* sets the style to bold and in all other aspects to the default value of the paragraph.
Note how spaces are treated when changing the style. As with paragraph styling the first white-space marks the end of styles. Everything that follows is treated as text. For simplicity, the styles * and _ are handled differently. Here the style ends right after this character. Thus, you can write {*bold} whereas in {color:green Green} you need to provide a space character. The shortcuts * and _ can be used in paragraph styling as well.

Navigation Navigation bars for large documents


The MaTeS compiler automatically generates a navigation bar that spans the top of the generated web page.

Influencing the navigation bar

When running the MaTeS compiler, you pass to it a number of MaTeS documents. Each of these has either a short title or title in its meta-data. Based on these titles the navigation bar is constructed. Thus, the MaTeS compiler ensures that the navigation bar is always up to date. The first MaTeS document passed to the compiler is usually called, i.e. the source for index.html. The title of this document is shown in a bigger font on the left of the navigation bar. Thus, the title of is usually the name of your project.

Sub-Navigation Bar

While the navigation bar helps to navigate between documents, a sub-navigation bar allows the user to navigate inside a document. Just use the #subnav command. It will list all level-1 headings if they have a menu: attribute, e.g.

 ##;menu:Intro Introduction

 Some nice words ...

 ##;menu:Experiment Experimental setup and results

 ## Conclusions
will create a sub-navigation bar consisting of two entries: Intro and Experiment. Note that the conclusions heading is not part of the subnav, because it has no menu: attribute. Furthermore, the entry in the subnav uses the word following menu:. If you need a space there, you must escape it with a backslash, e.g. #;menu:Pics\ &\ Figures.

Links and Bibliography Hyperlinks, internal references and bibliography


Hyperlinks can lead to any URL, point to a section inside the document, or point to a bibliographic reference.

External links

There are two kinds of hyperlinks. The first kind hides the URL and shows some text to click on. This is what the <a> tag in HTML does. The second kind shows the URL and when you click on it, the browser opens this URL. The second kind is very useful when writing the bibliography entries.
 This is a {a: clickable link}.
 This URL is clickable: ~a: .
The above example shows that the HTML <a> behavior can be achieved by applying the style a:. Every text using this style is therefore clickable.
The second kind of link uses a different syntax since it is not a style. The ~ symbol indicates an embedded object, such as a link, image, video, etc. Note that the space after the URL is not displayed. It just marks the end of the URL. Alternatively you can terminate the URL with a second tilde symbol, i.e. ~a: shows the dot right after the link.

Internal links

Using relative URLs you can point to locations inside a document. For example the link ~a:#grid~ points to a location labeled #grid. In HTML this means that some HTML element has an id of the same name. In MaTeS you must use the label: value that can appear wherever styles may appear.
 ##label:intro Introduction
 # ...
 # As shown in the {a:#intro Introduction}, we assume that ...


Using bibliography you can list all cited books, papers, and links at the end of the document. Inside the text you can refer to these bibliographic entries. MaTeS ensures that the bibliographic entries are numbered correctly, comparable to BibTeX.


A bibliographic entry is just a paragraph with a special bibliographic label.
 Weis, et. al.: "World domination for dummies", in Proc. of 1st World Domination Conference
 Google Inc.: ~a:
The above example is rendered as
[1] Weis, et. al.: "World domination for dummies", in Proc. of 1st World Domination Conference
[2] Google Inc.:
Note that the value following bib: is the label used to identify the bibliographic entry. It is required to reference it. Unlike BibTeX there is no special syntax for bibliographic references. Style them as you like. Furthermore, MaTeS will display all references in the bibliography no matter whether they have been referred to from the text. In contrast, BibTeX shows only those entries that have been referenced. This is by intention and will not change. However, future versions of MaTeS might issue a warning when an entry has not been referenced in the text.


A reference is just a special kind of link, because it points to a bibliographic entry. It has the syntax ~bib:weis2009~ and is rendered as [1]. In addition, you can cite multiple sources together, e.g. ~bib:weis2009,google~ which is rendered as [1,2].

Images and Captions Pictures, media gallery and captions


Images can be embedded in the normal text flow or shown in a media gallery

Images in the text flow

The syntax for embedding an image is ~img:
TODO: CSS styles can be attached to format the image, e.g. ~img:;width:100px~.

Media Gallery

A media gallery shows a sequence of images flowing from left to right and top to bottom. All images have a border and upon a click they open in a new browser tab.

Images in a gallery

The media gallery is just a special paragraph that is opened with #media. Inside the media gallery only images are allowed. Everything else is ignored.


Captions are useful after media galleries, tables, or code blocks. They are formatted differently from normal text (grey, smaller font, italic). Furthermore, they automatically number figures, tables, and code blocks. Note that an entire media gallery counts as a single figure.

Figure, table, and code sample captions

A caption is a paragraph that starts with #caption. It should follow either a code block, media gallery or table, but you can use it anywhere. When a caption is used, then the figure, code sample or table is numbered.
 Two logos in blue
This example above is rendered as:
Media 1: Two logos in blue
The same can be done to code blocks.
 func foo() {
 A simple function in Go
This example is rendered as:
func foo() {
Sample 1: A simple function in Go

Tables For, you guessed it, tabular data

Building Tables

A table consists of cells and rows. Cells are separated by |. If a newline follows the | symbol, this indicates the end of a row. The first row is always treated as the table header. There are various styles for influencing the table appearance.

Tables by example

A simple table with a caption
 Ranking   |  Country     | Location       |
 1         |  Spain       | Johannesburg   |
 2         |  Netherlands | Johannesburg   |
 3         |  Germany     | Port Elizabeth |
 Results of the Soccer WM 2010 in South Africa.
This is shown as
Ranking Country Location
1 Spain Johannesburg
2 Netherlands Johannesburg
3 Germany Port Elizabeth
Table 1: Results of the Soccer WM 2010 in South Africa.
Inside a table you can use MaTeS as well, but it is not possible to create new paragraphs inside a table cell. Tables are for showing data, not for fancy layout. Use the grid system for table-like layout. We can change the appearance of the table by applying different CSS classes.
 Ranking   |  Country     | {font-style:italic Location |
This is rendered as
Ranking Country Location
1 Spain Johannesburg
2 Netherlands Johannesburg
3 Germany Port Elizabeth
Table 2: Results of the Soccer WM 2010 in South Africa.
Note that the styles must follow the table keyword and not the other way round. Other table CSS classes are table-bordered and table-condensed.

Multi column

A cell can span multiple columns. The number of | symbols in sequence denotes the number of columns a cell spans.

Table with multi column cells

A cell covers as many columns as there are | symbols terminating the cell. Note that in this case there must not by any space between the | symbols.
 Number    | First Name  | Last Name  |
 1         | Joe         | Doe        |
 2         | Ed, only Ed             ||
This is shown as
Number First Name Last Name
1 Joe Doe
2 Ed, only Ed

Mathematics and Definitions Showing pretty formulas


Formulas use the convenient TeX syntax. Using MathJax[3] the formulas are rendered in the browser looking pretty even when being scaled. Formulas can be embedded in the normal text flow or in separate paragraphs.

Inline formulas

A formula can be embedded in the normal text flow using the $ symbol. The next unescaped $ terminates the formula.
TODO Escaping special characters needs to be implemented
The sum $\sum_{i=0}^n\ x_i$ converges, if ...
The formula is shown as \(\sum_{i=0}^n\ x_i\). Alternatively, a formula or a sequence of formulas can be put in their own paragraph, which is called a display-math in TeX. A display-math section is started with #math and terminates upon the next line starting with the hash symbol.
 \sum_{i=0}^n x_i
Note that the $ symbol is not required here. This is shown as
\[ \sum_{i=0}^n x_i \]
This syntax is especially useful for showing a sequence of equations or large and important formulas.

Definition Lists

Definitions are useful to define a list of terms, for example in a glossary.

Syntax of definition lists

A definition list is started by #deflist. After that you can use the two commands #deft and #defd to first define the topic (hence #deft) and then describe it (hence #defd). You can put any number of #deft/#defd pairs in a list. The list is implicitly terminated when a new section is opened. Thus, an empty line terminates the #deflist. Note that there is no special syntax to implicitly terminate a deflist.
The following example
 #deft JPEG
 #defd A format for pictures
 #deft MP3
 #defd A file format for audio files
 #deft Foo
 #defd Most likely the prefix of bar
is rendered as:
A format for pictures
A file format for audio files
Most likely the prefix of bar
If you want to define a set of mathematical symbols, you should use the dl-horizontal class as shown below. This is purely optional. In many cases ist just looks better.
 #deft $n$ =
 #defd The number of iterations
 #deft $a_i$ =
 #defd The value for iteration step $i$.
 #deft $\frac{1}{n} \sum a_i$ =
 #defd The average of all iterations
\(n\) =
The number of iterations
\(a_i\) =
The value for iteration step \(i\).
\(\frac{1}{n} \sum a_i\) =
The averge of all iterations

Notes & Comments Working collaboratively on a document


You can write comments in a MaTeS file which are only visible in the editor but ignored by the MaTeS compiler.

Comments in MaTeS source code

Every line starting with % is treated as a comment and ignored by the compiler.
 This is the beginning of a paragraph ...
 % This text is ignored
 ... and the paragraph continues here ...


Labels can highlight text of they are useful tools to insert comments in text, which is especially useful when working on some text or slides collaboratively.

Marking text with labels

To highlight a span of text, you can show the text as a label. Essentially this is no special MaTeS feature. The label style is supported by the bootstrap CSS. To mark text as being a label, just apply the label HTML class.
 This is a {class:label Label}
which is shown as: This is a Label and this is an important label. There is a set of different labels as shown in the table below:
Labels MaTeS Shortcut
Default {class:label Default}
Success {class:label,label-success Success}
Warning {class:label,label-warning Warning} {? Warning}
Important {class:label,label-important Important} {! Important}
Info {class:label,label-info Info} {@ Info}
Inverse {class:label,label-inverse Inverse}


Badges are small, simple components for displaying an indicator or count of some sort.

Highlighting numbers with badges

Essentially this is no special MaTeS feature. The badge style is supported by the bootstrap CSS. To mark text as being a badge, just apply the badge HTML class. The following table shows the available HTML classes. Unlike labels, there is no shortcut syntax yet since this feature is most likely used rarely only.
Name Badges MaTeS
Default 1 {class:badge 1}
Success 2 {class:badge,badge-success 2}
Warning 4 {class:badge,badge-warning 4}
Important 6 {class:badge,badge-important 6}
Info 8 {class:badge,badge-info 8}
Inverse 10 {class:badge,badge-inverse 10}


Alerts are text boxes with a special color. They can denote an information, warning, or critical problem. A typical use of alerts is during collaborative text writing to alert other authors. However, you can use it as well to draw the attention of normal readers to important pieces of information.

Warnings in a box

The following kind of alerts are available: #warn, #important, #info, #success and they look like this:
Warning: Use alerts carefully
Error: The reactor is overheating
Info: It is important to cool down the reactor
Success: Luckily someone turned the beast off.
The source code for the above boxes is:
 {*Warning:} Use alerts carefully
 {*Error:} The reactor is overheating
 {*Info:} It is important to cool down the reactor
 {*Success:} Luckily someone turned the beast off.

Progress bars

Progress bars can be used to show a percentage number in a nice visual style.

Progress bars and their styles

A progress bar is simply a paragraph with some special styles attached to it. They come in different styles and colors. To create a progress bar use #progress followed by a colon and a percentage, e.g. #progress:60%. All text following this command will be shown inside the progress bar. Note that excessive text will be invisible, so make sure that all the text is visible in the bar.


Default progress bar with a vertical gradient
 #progress:60% 60%


Uses a gradient to create a striped effect (no IE).
 #progress:60%;striped 60%


Takes the striped example and animates it (no IE).
 #progress:60%;active 60%

Progress bars with colors

Progress bars use some of the same button and alert classes for consistent styles.

Examples with colors

Examples with stripes & colors

Charts Displaying numeric data

Pie Charts

Pie charts can be used to display one series of numerical data

Examples of Pie Charts and Donuts

Pie charts come in different styles. For example they can be displayed as a filled circle (the classic choice) or as a donut. The data shown in the pie chart is written like a table. Thus, a pie chart (and every other chart type) is just a table with a fance graphical presentation.

A pie chart with a legend

 Label   | Y   |
 Germany | 80  |
 France  | 60  |
 Italy   | 50  |
 Spain   | 40  |

A pie chart shown as a donut

 Label   | Y   |
 Germany | 80  |
 France  | 60  |
 Italy   | 50  |
 Spain   | 40  |

A pie chart without a legend

 Label   | Y   |
 Germany | 80  |
 France  | 60  |
 Italy   | 50  |
 Spain   | 40  |

A pie with labels outside the pie

 Label   | Y   |
 Germany | 80  |
 France  | 60  |
 Italy   | 50  |
 Spain   | 40  |

Bar and Line Charts

Syntax for line charts

Just like pie charts, these chart types use a table to get their values from. Use the #chart command to begin a new chart table. Each chart must have exactly one X column and one or more Y column. For each row of data (e.g. for each line on the chart) you must provide one Y column. The X column is detected by the compiler by its name, e.g. the table header must read X. If you want to use arbitrary strings instead of numbers on the x-axis, use a Label column instead of an X column. Y column are detected by the fact that their first non-space character is Y. Columns that do not match either of these are ignored. To put some useful text in the legend of the chart, you can write the name of the column right behind the Y, e.g. Y Series A to denote that this column holds the values for the Series A data points.
The data to plot is given in terms of X,Y pairs. If you have multiple data columns, it might happen that you do not have Y values for different X points, e.g. you have the points (1,3),(3,6),(5,9) for one data columns and the points (1,10),(2,11),(6,20). In this case your X column should contain all X values, e.g. 1, 2, 3, 5, 6. In the Y column you can just leave a cell empty, e.g. in the first column there is no Y value for X=2 and X=6.
Using the attributes lines and points you can determine whether you want to see just lines, just points, or both. Using the legend attribute you can specify that a legend should be displayed in the chart. The position can be adjusted by setting legend-position to nw, sw, se or ne (default). Use the attribute fill to fill the area enclosed by lines.

A line chart with strings on the x-axis

 Label | Y Series A | Y Series B |
 \     | 3          | 5          |
 Mon   | 4          | 4          |
 \     | 12         | 3          |
 Wed   | 8          | 6          |
 \     | 5          | 4          |
 Fri   | 11         | 7          |
 \     | 5          | 4          |

A line chart with three data columns

 X |Y Series A  |Y Series B |Y Series C |
 1 | 1          | 10        | 1         |
 2 | 4          | 9         | 2         |
 3 | 9          | 8         | 3         |
 4 | 16         | 7         | 4         |
 5 | 9          | 6         | 5         |
 6 |            | 5         | 6         |
 7 | 1          | 4         | 7         |

Syntax for bar charts

The syntax is basically the same. Just use the bars attribute to show bars. Note that it is valid to use a Label and X column together. The rare use case for this is to show the same data as bars and lines at the same time. But usually you will use only one of these two column types.
If you have multiple data columns, they are just printed above each other. This is ok for line and point charts but not for bar charts. In this case you can arrange them vertically or horizontally. For vertical alignment, simply use the stack attribute. For horizontal alignment, you must trick with the x-axis. For each x-value, only one column has a value, the others are empty, as shown in the example below.

A vertically stacked bar chart

 Label | Y Series A | Y Series B |
 Foo   | 10         | 14         |
 Bar   | 20         | 19         |
 Baz   | 15         | 11         |

A bar chart with two data columns

 Label | Y Series A | Y Series B |
 Foo A | 10         |            |
 Foo B |            | 14         |
 Bar A | 20         |            |
 Bar B |            | 19         |

Bibliography Further reading and related work

[1] Google Code Prettify,

[2] Bootstrap,

[3] MathJax,