Skip to content

markdown.mdx

Latest commit

 

History

History
251 lines (180 loc) · 7.71 KB

markdown.mdx

File metadata and controls

251 lines (180 loc) · 7.71 KB
title Markdown in Developer Portal
description Markdown capabilities, supported features, and known limitations when writing content in the Tyk Enterprise Developer Portal
sidebarTitle Markdown

The Tyk Developer Portal supports Markdown for writing content. This page explains where Markdown can be used, which features are supported, and what limitations to be aware of.

Where Markdown Can Be Used

Markdown is supported in three areas of the portal. All three use the same rendering engine, so content behaves the same in Blog Posts, Pages, and Product Documentation.

Blog Posts

Blog posts can be written in Markdown. In the Admin UI under Blog → New Post, enable the "Display Markdown" checkbox to activate Markdown rendering for the post.

When Markdown is enabled for a blog post, the template uses the `markdownify` function to render the content. See the [blog post template data](/portal/customization/templates#blog-detail) for details on `MarkdownEnabled` and `MarkdownContent`.

Pages

Pages consist of multiple content blocks (e.g. header, text sections, image sections). Each content block can individually be switched to Markdown. This allows you to build landing pages where specific sections use Markdown while others use HTML.

See Customize Pages for how to create and edit pages and their content blocks.

Product Documentation (Getting Started Guides)

Each API Product has a "Getting started" tab where you can add documentation pages that support Markdown. These entries appear as sidebar navigation in the Live Portal.

This works well for API guides, authentication instructions, and quickstart tutorials. See Getting Started Guide for more details.

Where Markdown Does Not Work

  • Product "More info" (Overview tab): Markdown syntax is not rendered
  • API Description: No Markdown support
  • API Specification: No Markdown support. Uploaded specifications render in dedicated viewers instead. OpenAPI/Swagger specifications use Stoplight Elements. GraphQL SDL is rendered via GraphQL Playground for GraphQL APIs; in the default theme/setup, SDL attached to non-GraphQL APIs may fall back to Stoplight.

Supported Features

Text Formatting

Feature Syntax Result
Headings (H1–H6) # Title through ###### Small Rendered with automatic anchor IDs
Bold **bold** bold
Italic *italic* italic
Bold and Italic ***both*** both
Strikethrough ~~strikethrough~~ strikethrough

Links and Images

Feature Syntax
Inline link [Text](url)
Reference link [Text][ref] with [ref]: url
Autolink https://example.com becomes clickable automatically
Image ![Alt text](url)
Reference image ![Alt][ref] with [ref]: url on a separate line
Image as link [![Alt](image-url)](link-url)
Markdown images (`![alt](url)`) do not support specifying width or height. To control image dimensions, use an HTML `

` tag instead: `

description

`.

Reference-style images (![Alt][ref]) require a blank line between the image and the reference definition. If they are in the same paragraph, the reference is not resolved.

Lists

Bullet lists, numbered lists, and task lists are supported, with nesting up to 5 levels:

- Item one
  - Nested item
    - Deeply nested
1. First
2. Second
- [x] Completed task
- [ ] Open task

Task lists render with checkboxes.

Code

Inline code uses single backticks: `code`

Fenced code blocks use triple backticks with an optional language tag:

```python
def hello():
    print("Hello, World!")
```
Code blocks render in monospace but without syntax color highlighting in the default theme.

Blockquotes

> This is a blockquote
> > Nested blockquotes work too

Blockquotes support formatting inside them (bold, italic, links, code, lists).

The default theme does not apply visual styling (indentation or border) to blockquotes. They may appear as regular text.

Tables

Standard GitHub Flavored Markdown (GFM) table syntax is supported, including column alignment:

| Left aligned | Center aligned | Right aligned |
|:-------------|:--------------:|--------------:|
| Value        | Value          | Value         |
The default theme does not render table borders. See [Table styling workarounds](#table-styling) below for workarounds.

Horizontal Rules

Any of these syntaxes produce a horizontal rule:

---
***
___

Other Supported Features

Feature Details
Escaping \* renders a literal asterisk
HTML entities © renders ©
Frontmatter A YAML block (---...---) at the start is not hidden. The delimiters render as horizontal rules and the YAML content renders as text
Unicode Umlauts, emojis (😀🚀), CJK characters are all supported
Nesting Lists in blockquotes, blockquotes in lists, code in lists, etc.

Embedding HTML

HTML tags can be used directly within Markdown content for advanced formatting:

Text Formatting

<span style="color: red;">Colored text</span>
<sup>superscript</sup> and <sub>subscript</sub>

Media Embedding

YouTube video:

<iframe width="560" height="315"
  src="https://www.youtube.com/embed/VIDEO_ID"
  frameborder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowfullscreen>
</iframe>

Vimeo video:

<iframe src="https://player.vimeo.com/video/VIDEO_ID"
  width="640" height="360"
  frameborder="0"
  allow="autoplay; fullscreen"
  allowfullscreen>
</iframe>

HTML5 video and audio:

<video controls><source src="video.mp4" type="video/mp4"></video>
<audio controls><source src="audio.ogg" type="audio/ogg"></audio>

Custom Layouts

<div style="background: #f0f8ff; padding: 10px; border-radius: 4px;">
  This is a custom callout box.
</div>

<img src="image.png" width="400" height="200" alt="Sized image">

Not Supported

The portal does not render the following Markdown extensions:

Feature What Happens
Footnotes [^1] remains as plain text
Definition Lists Term followed by : Definition is not recognized
Emoji shortcodes :smile: remains as text (use Unicode emojis directly instead)
Math/LaTeX $E=mc^2$ is not rendered

Known Limitations and Workarounds

Table Styling

Markdown tables are generated correctly but the default theme does not display borders. You can work around this in two ways:

Option 1: HTML table with Bootstrap class

<table class="table">
  <thead>
    <tr><th>Column 1</th><th>Column 2</th></tr>
  </thead>
  <tbody>
    <tr><td>Value 1</td><td>Value 2</td></tr>
  </tbody>
</table>

Option 2: Markdown table with style wrapper

<style>
.nice-table table { border-collapse: collapse; width: 100%; }
.nice-table th, .nice-table td { border: 1px solid #ddd; padding: 8px; }
.nice-table th { background: #f5f5f5; }
</style>

<div class="nice-table">

| Column 1 | Column 2 |
|----------|----------|
| Value 1  | Value 2  |

</div>

Blockquotes Without Styling

Blockquotes are generated in the HTML output but the default theme does not display any indentation or border. They appear as regular text. Adjust your theme's CSS to style the blockquote element if needed.

Code Without Syntax Highlighting

Code blocks render in monospace font but without syntax color highlighting in the default theme.
⚡