Documentation Markdown Syntax

On this page

Page Setup
Headers
Emphasis
Lists
Links
Tables
Code
Callouts
Quotes
Images
Videos
Collapsible Text Block
Inpage Tabs

This page aims to serve as a comprehensive guide for the Markdown syntax used for Polypheny’s documentation website.

Page Setup

Every document should start with a YAML Front Matter, a specific header that contains certain meta information on this page. These meta information shall be enclosed within ---. For example:

---
layout: page
title: "Documentation Markdown Syntax"
toc: true
docs_area: "devs"
doc_type: doc
tags: windows,linux,more
search: false
lang: en
---  

The following parameters are currently supported:

layout: single word - The layout that should be used for the document.
title: string - The title of the page as it should appear in browser tab and page headings.
toc: boolean - Whether or not a table of contents should be automatically generated.
docs_area: single word - The documentation area categorization, useful for grouping related documents.
doc_type:: single word - Is used to define the page type. Additionally renders an icon during search.; Choose: [ doc for OR tutorial for ] (default: doc).
search: boolean - If set to true, site is not indexed and cannot we found via search (default: false).
lang: single word - The language of the document. (e.g., en)
tags: csv list - Tags that represent the content of the document. These are necessary for SEO and the internal search.
license: single word - The license under which the document is shared (e.g., cc_by-sa). Omit to use default (“All Rights Reserved.”) Pick one from thge list: license-agreement.yml

Headers

Headers are created using the # character. The number of # characters corresponds to the header level. For example:

## Section
### SubSection

Do not use level one headers (single #) in the Polypheny documentation, since this is used for the page heading.

Emphasis

To emphasize text, you can make it bold or italic.

Use * or _ for italics:
```
*This text will be italic*
_And this_
```
Output:

This text will be italic
And this
Use ** or __ for bold:
```
**This text will be bold**
__And this__
```
Output:

This text will be bold
And this

Lists

Create lists using *, -, or +:

Unordered lists

  * Item 1
  * Item 2
  * Item 3

Output:

Item 1
Item 2
Item 3

Ordered lists

Item 1
Item 2
Item 3

Output:

Item 1
Item 2
Item 3

Definition Lists

Definition lists are very helpful when defining or explaining multiple words.

Use this when explaining specific terms of a system

First Term
: This is the definition of the first term.

Second Term
: This is one definition of the second term.
: This is another definition of the second term.

First Term: This is the definition of the first term.
Second Term: This is one definition of the second term.; This is another definition of the second term.

Tasklists

- [x] tasklist_1
    - [x] tasklist1-2
- [ ]  tasklistt_2

Output:

tasklist_1
- tasklist1-2
tasklistt_2

Links

Links can be created as follows:

[Link text](https://polypheny.com)

Output: Link text

External Links

External links should open in a new tab. Use :target="_blank" to open a new tab with the link and redirect focus.

[Link text](https://polypheny.com){:target="_blank"}

Output: External Link text

Internal Links

Internal links can be created with relative paths. If it is a page in the same folder, the name of the file can be used (without the .md):

[Link text](name_of_page)

Furthermore, links can be created using either the complete path:

[Link text](/en/latest/concepts/data-models)

Or omitting the version and language:

[Link text](/concepts/data-models)

The latter has the advantage of always pointing to the page in the same version and language, and is thus (together with only relative style) the preferred way to create links. Paths including the language and the version should only be used in special situations.

Tables

Tables can be created as shown bellow. Make sure to have an empty line before and after the table definition!

| Type      | Description |
|-----------|-------------|
| 1.1       |     2. 1    |
| 1.2       |     2. 2    |

Type	Description
1.1	2. 1
1.2	2. 2

Without table heading

| Type      | Description |
| 1.1       |     2. 1    |
| 1.2       |     2. 2    |

Type	Description
1.1	2. 1
1.2	2. 2

Center content of cells in table

Simply add : at the beginning and end of the header line.

| Type      | Description |
|:---------:|:-----------:|
| 1.1       |     2. 1    |
| 1.2       |     2. 2    |

Type	Description
1.1	2. 1
1.2	2. 2

Adjust number of columns in table

new column |

| Type      | Description | new column |
|:---------:|:-----------:|:----------:|
| 1.1       |     2. 1    |
| 1.2       |     2. 2    |

Type	Description	new column
1.1	2. 1
1.2	2. 2

Code

Inline Code

Inline code can be wrapped in back-ticks “`”:

`This is inline code`

Code Blocks

Entire Code blocks can be created using triple back-ticks “```”:

```
This is a code block
```

Code blocks allow to specify the language used for syntax highlighting.

Prefix commands

For some languages you can increase the readability by perefix short statements with a single charcter that is typical for that platform like $ for bash and shell commands or > for queries.

whoami

SELECT * FROM dummy;

You just need to prepend {:.code-before} before starting the code block:

{:.code-before}
```bash
whoami
```

{:.code-before}
```sql
SELECT * FROM dummy;
```

Callouts

Callouts are used to highlight important content.

💡 Note
Your content

They are included using the following format:

{% include utils/callout.html use_heading = true content="This page is currently under going maintenance. Please come back later." %}

The level of the callout can be adjusted by adding a level parameter: level=""

Info:

ℹ Info
This page is currently under going maintenance. Please come back later.

  
  {% include utils/callout.html level="info" use_heading = true content="This page is currently under going maintenance. Please come back later." %}
  

Warning:

⚠ Warning
This page is currently under going maintenance. Please come back later.

  
  {% include utils/callout.html level="warning" use_heading = true content="This page is currently under going maintenance. Please come back later." %}
  

Error:

❗ Error
This page is currently under going maintenance. Please come back later.

  
  {% include utils/callout.html level="error" use_heading = true content="This page is currently under going maintenance. Please come back later." %}
  

Danger:

⚡ Danger
This page is currently under going maintenance. Please come back later.

  
  {% include utils/callout.html use_heading=true level="danger" content="This page is currently under going maintenance. Please come back later." %}
  

Custom Heading

If you don’t want to use the predefined headings like Note, Info, Warning, Error or Danger you can specify a custom_heading="" within the include:

{% include utils/callout.html level="info" use_heading=true content="This page is currently under going maintenance. Please come back later." custom_heading="Test" %}

🚀 Test
This page is currently under going maintenance. Please come back later.

No Heading

To simplify, highlighting a message you can omit the header information by setting use_heading=false or omitting the key use_heading entirely. This also ignores the custom_heading key.

{% include utils/callout.html level="info" content="This page is currently under going maintenance. Please come back later." %}

This page is currently under going maintenance. Please come back later.

Quotes

To create a blockquote, add a > in front of a paragraph.

> Lorem ipsum dolor sit amet, consetetur sadipscing elitr

The rendered output will look like this:

Lorem ipsum dolor sit amet, consetetur sadipscing elitr

Blockquotes with Multiple Paragraphs

Blockquotes can contain multiple paragraphs. Add a > on the blank lines between the paragraphs.

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

The rendered output will look like this:

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

Nested Blockquotes

Blockquotes can be nested. Add a » in front of the paragraph you want to nest.

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

The rendered output will look like this:

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore

et dolore magna aliquyam

Blockquotes with Other Elements

Blockquotes can contain other Markdown formatted elements. Not all elements can be used — you’ll need to experiment to see which ones work.

The quarterly results look great!

Revenue was off the chart.

Profits were higher than ever.

Everything is going according to plan.

Images

To add an image you can use this inline command: ![ALT Text](/path/to/image/file).

E.g.

![Polypheny Landscape Logo](/assets/images/logos/logo-landscape-transparent.png)

will render the following image:

Different Image sizes

To adjust the image size you can append one of the following css classes: small-image-scale | mid-image-scale | large-image-scale at the end of the inline command. Omitting the image scaling will render the image in its oriiginal size.

E.g:

![Polypheny Landscape Logo](/assets/images/logos/logo-landscape-transparent.png){:.small-image-scale}

small-image-scale:
mid-image-scale:
large-image-scale:

Side-by-side images

To get two images side by side you need to use a table.

Left            |  Right
:-------------------------:|:-------------------------:
![ALT Text](/path/to/image/file) | ![ALT Text](/path/to/image/file)

Left	Right

If you want to remove the table headlines:

:-------------------------:|:-------------------------:
![ALT Text](/path/to/image/file) | ![ALT Text](/path/to/image/file)

Linking images

[![Small sized Polypheny Landscape Logo with link](/assets/images/logos/logo-landscape-transparent.png)](https://polypheny.com/en/pricing)

Inline Icons

Sometimes it migth be necessary to include small icons into the text to enhance readability. Like displaying a tutorial icon. We can use include together with the src key (pointing to an image ) to do this.

Like displaying a {% include utils/inline-icon.html src="/assets/images/utils/tutorial.svg" %} tutorial icon.

Videos

Videos can be embedded using a video id from a source such as YouTube:

<div class="video_thumbnail">
<iframe class="responsive-iframe" src="https://www.youtube.com/embed/Your video id?modestbranding=1&rel=0" title="Alternative text" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</div>

Collapsible Text Block

Collapsible text blocks (or fold-out elements) can be created to hide longer explanations or additional details:

<details>

<summary>

Your summary

</summary>

Your content
</details>

Please replace “Your content”, “Your summary”, and “Your video id” with the content, summary, and video id that you want to use.

Example:

Your summary

Your content

Inpage Tabs

The usage of {:.tabset} beneath a heading will turn all nested parallel sections into tabs

bash

shutdown now

python

import os

Adapter Development

Quick Search Results

Page Setup

Headers

Emphasis

Lists

Unordered lists

Ordered lists

Definition Lists

Tasklists

Links

External Links

Internal Links

Tables

Without table heading

Center content of cells in table

Adjust number of columns in table

Code

Inline Code

Code Blocks

Prefix commands

Callouts

Custom Heading

No Heading

Quotes

Blockquotes with Multiple Paragraphs

Nested Blockquotes

Blockquotes with Other Elements

The quarterly results look great!

Images

Different Image sizes

Side-by-side images

Linking images

Inline Icons

Videos

Collapsible Text Block

Inpage Tabs

bash

python