Last updated 1 week ago

Supported Markdown features

When creating pages in your developer portal, use GitHub-flavored Markdown. All standard text formatting options (emphasis, inline code...), multimedia (inserting images and videos), and page elements (links, tables, code and quote blocks, lists, headings...) are supported.

This page highlights some of the special Markdown features you can use in your portal pages.

Front matter

By adding front matter to a Markdown page, you can set per-page options and override some of the site-wide portal settings. Front matter must be at the beginning of a Markdown file, in valid YAML format between triple-dashed lines (---).

Example

---
title: Markdown example
description: GitHub-flavored markdown example
enableToc: true
---

Supported front matter options

  • description - Sets a custom page description.
  • disableLastModified - When set to true, hides the "Last updated {time} ago" label at the top of the page.
  • enableToc - When set to true, overrides global portal settings and displays a table of contents (ToC) on the right side of the page. Read more about ToC configuration.
  • excludeFromSearch - When set to true, the page will be excluded from the search index and will not be accessible from the search results.
  • permission - Used with the RBAC feature to set per-page access permissions.
  • redirectFrom - Defines one or more URLs that will be redirected to the URL of the Markdown page. Each URL must be provided as an item in an array with a trailing slash at the end. Read more about using redirects.
  • requestLogin - When using a custom login component in the portal, setting this to true redirects to the portal login page if the user is not already logged in.
  • showNextButton - When set to false, hides the "Next to" navigation button at the bottom of each MD(X) page.
  • title - Sets the page title; equivalent of the HTML <title> tag. It's displayed in the browser's title bar and/or tab. If label is not defined for the page in sidebars.yaml, the value of title will be automatically used as the page name in the sidebar.
  • tocMaxDepth - Depends on enableToc: true. Sets the maximum depth (amount of heading levels) displayed in the page table of contents as an integer value. The default is 4.

Unordered lists

Examples

* API Reference
* Portal
* Workflows

Using a different character for list items:

- API Reference
- Portal
- Workflows

Both examples render like this:

  • API Reference
  • Portal
  • Workflows

To create a nested list, indent items:

+ API Reference
    + Hosted
    + On-premise
+ Developer portal
    + Hosted
    + On-premise
+ Workflows

The example above renders like this:

  • API Reference

    • Hosted
    • On-premise
  • Developer portal

    • Hosted
    • On-premise
  • Workflows

Numbered lists

Example

1. Wake up
2. Brush teeth
3. Exercise

The example above renders like this:

  1. Wake up
  2. Brush teeth
  3. Exercise

Numbered list with code snippets

Example

1. Code snippets in a list.
1. ```javascript
   javascript;
   ```

   ```python
   python
   ```

   ```cpp
   c++
   ```

The example above renders like this:

  1. Code snippets in a list.
  2. javascriptpythoncpp
    javascript;
    python
    c++

Free-form code samples

Code samples support syntax highlighting, as long as you specify the language at the beginning of your code block.

Example: Python code highlighting

```python
prices = {'apple': 0.40, 'banana': 0.50}
my_purchase = {
    'apple': 1,
    'banana': 6}
grocery_bill = sum(prices[fruit] * my_purchase[fruit]
                   for fruit in my_purchase)
print ('I owe the grocer $%.2f' % grocery_bill)
```

The example above renders like this:

prices = {'apple': 0.40, 'banana': 0.50}
my_purchase = {
    'apple': 1,
    'banana': 6}
grocery_bill = sum(prices[fruit] * my_purchase[fruit]
                   for fruit in my_purchase)
print ('I owe the grocer $%.2f' % grocery_bill)

Tabbed code samples

To make your code samples display in tabs, write them sequentially (one immediately after the other, without any text between) and specify the language at the beginning of each code block.

The language name is used as the default tab title. You can set a custom tab title by adding it after the language, or by replacing the language altogether with a custom string. Note that syntax highlighting will not work for tabs without a specified language.

```javascript
javascript;
```

```python
python
```

```java title
example text
```

```custom tab name
example text
```

The example above renders like this:

javascriptpythontitletab name
javascript;
python
example text
example text

Built with

Admonitions

Admonitions are text blocks with special formatting. Use them to highlight important information, warn users, or provide hints and tips. The icon to the left of the text is generated automatically according to the admonition type.

The following admonition types are supported: info, success, warning, danger, attention.

Here is how to insert each type of admonition, followed by an example of what it looks like when rendered in the portal.

Info

:::info Optional title

Just FYI

:::
Optional title

Just FYI

Success

:::success Success message

Hooyah!

:::
Success message

Hooyah!

Warning

:::warning Warning

I told you so!

:::
Warning

I told you so!

Danger

:::danger Danger

I really told you so!

:::
Danger

I really told you so!

Attention

:::attention Attention

Now that I have your attention...

:::
Attention

Now that I have your attention...

Legacy admonitions syntax

From version 1.0.0-beta.118 of the Developer portal, the HTML-based syntax for inserting admonitions is considered deprecated. We strongly recommend replacing it with the new syntax in your portal project, as it will be phased out soon.

Example legacy syntax for warnings

<div class="warning">Warning: I told you so!</div>