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 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~~ |
Links and Images
| Feature | Syntax |
|---|---|
| Inline link | [Text](url) |
| Reference link | [Text][ref] with [ref]: url |
| Autolink | https://example.com becomes clickable automatically |
| Image |  |
| Reference image | ![Alt][ref] with [ref]: url on a separate line |
| Image as link | [](link-url) |
Markdown images (
) 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.Lists
Bullet lists, numbered lists, and task lists are supported, with nesting up to 5 levels:Code
Inline code uses single backticks:`code`
Fenced code blocks use triple backticks with an optional language tag:
Code blocks render in monospace but without syntax color highlighting in the default theme.
Blockquotes
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:The default theme does not render table borders. See Table styling workarounds 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
Media Embedding
YouTube video:Custom Layouts
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 classBlockquotes 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 theblockquote element if needed.