> ## Documentation Index
> Fetch the complete documentation index at: https://tyk.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Markdown in Developer Portal

> Markdown capabilities, supported features, and known limitations when writing content in the Tyk Enterprise Developer Portal

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.

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

### 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](/5.12/portal/customization/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](/5.12/portal/api-products#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](/5.12/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](/5.12/image-url)](link-url)`                 |

<Note>
  Markdown images (`![alt](url)`) do not support specifying width or height. To control image dimensions, use an HTML `<img>` tag instead: `<img src="url" width="400" height="200" alt="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.
</Note>

### Lists

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

```markdown theme={null}
- 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:

````markdown theme={null}
```python
def hello():
    print("Hello, World!")
```
````

<Note>
  Code blocks render in monospace but without syntax color highlighting in the default theme.
</Note>

### Blockquotes

```markdown theme={null}
> This is a blockquote
> > Nested blockquotes work too
```

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

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

### Tables

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

```markdown theme={null}
| Left aligned | Center aligned | Right aligned |
|:-------------|:--------------:|--------------:|
| Value        | Value          | Value         |
```

<Note>
  The default theme does not render table borders. See [Table styling workarounds](/5.12/#table-styling) below for workarounds.
</Note>

### Horizontal Rules

Any of these syntaxes produce a horizontal rule:

```markdown theme={null}
---
***
___
```

### Other Supported Features

| Feature       | Details                                                                                                                                     |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Escaping      | `\*` renders a literal asterisk                                                                                                             |
| HTML entities | `&copy;` 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

```html theme={null}
<span style="color: red;">Colored text</span>
<sup>superscript</sup> and <sub>subscript</sub>
```

### Media Embedding

**YouTube video:**

```html theme={null}
<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:**

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

**HTML5 video and audio:**

```html theme={null}
<video controls><source src="video.mp4" type="video/mp4"></video>
<audio controls><source src="audio.ogg" type="audio/ogg"></audio>
```

### Custom Layouts

```html theme={null}
<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**

```html theme={null}
<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**

```markdown theme={null}
<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.