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.
  • exclude - When set to true, excludes the page from the portal build. To prevent broken links or potential build failures, make sure to remove any entries for the excluded page from your sidebars.yaml file. If other MD or MDX pages have links pointing to the excluded page, you should remove or modify them prior to building the portal.
  • excludeFromSearch - When set to true, the page will be excluded from the search index and will not be accessible from the search results.
  • image - Sets a rich metadata image for the page. This image is displayed when sharing the link to the page on social media. You must provide the path to an existing image in your portal project, e.g. image: /path/to/image-file.png.
  • keywords - Sets the contents of the <meta name="keywords"> tag for the page. Provide the keywords as a comma-separated list, e.g. keywords: documentation, api, openapi.
  • lang - Sets the language attribute for the page to indicate the language in which the content is written. Provide the lang value as a language tag with optional subtags (for example, en-US for United States English, es for Spanish).
  • 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.
  • showPrevButton - When set to false, hides the "Back 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

Customizable images

Important

Markdown image resizing and styling is supported from version 1.0.0-beta.151.

When inserting images into your Markdown pages, you can specify their size and optionally style them with CSS properties.

Supported image size parameters are width and height, and you can set both or just one for each image. For image styling, you can use any of the CSS properties supported by the gatsby-remark-image-attributes plugin.

To customize an image, add a space, then a string with a leading # symbol after the image file name, followed by the size parameters and/or CSS properties you want to use. The following examples illustrate different ways to customize images in your Markdown files.

Example with custom widthExample with custom width and heightExample with custom CSS styling
Let's insert an image.

![Alt text for the image](./path/to/image.png '#width=500px;')
Let's insert an image.

![Alt text for the image](./path/to/image.png '#width=200px;height=200px;')
Let's insert an image.

![Alt text for the image](./path/to/image.png '#width=500px;height:250px;box-shadow: 2px 2px 6px 0px;float: right;')

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>