Custom Markdown Syntax

Overview

Our documentation site uses custom markdown syntax and special notations to create rich, interactive content. This guide covers all the custom syntax available for creating transformation widgets, styled boxes, reusable content, and more.

General Markdown Preferences

Unordered Lists

• Use * rather than - for unordered lists.
• Leave a blank line before and after the list.

For example:

This renders as:

This is my list:

• Item 1
• Item 2
• Item 3

Ordered Lists

• Use 1. for every bullet of a numbered list.
• Leave a blank line before and after the list.

For example:

This renders as:

This is my ordered list:

1. Item 1
2. Item 2
3. Item 3

Bold

Use ** to indicate bold.

For example:

This renders as:

This is a bold word.

Italics

Use _ to indicate italics.

For example:

This renders as:

This is a work in italics.

Transformation Widget Syntax

The transformation widget automatically generates interactive code examples showing image transformations with multiple SDK options.

Basic Syntax

This creates a widget that includes:

• The transformed image (if using demo account)
• URL and SDK code tabs
• All framework tabs configured as "all"

This is how it looks:

Widget Options

Add options after the URL, inside quotes, delimited by commas (e.g. "with_image:false, with_code:false"):

This renders without the image or code, so only the URL:

Available Options

Option	Values	Description
with_url	true (default for demo), false (default for other accounts)	Whether to show the URL tab
with_code	true (default for demo), false (default for other accounts)	Whether to show SDK tabs
with_image	true (default), false	Whether to show the transformed asset
url_code	true, false (default)	Return "cloudinary_url" code instead of image tag code
thumb	e.g. c_scale,w_500/dpr_2.0	Transformation parameters for thumbnail display only
frameworks	url, secure_url, nodejs, react_2, react, vue_2, vue, angular_2, angular, js, js_2, python, php_2, php, java, go, ruby, csharp, dart, objectivec, swift, android, kotlin, flutter, jquery, endpoint, curl	Specific frameworks to show (must be last parameter)
secure	true, false (default)	Whether to include secure parameter in SDK tabs
popup	true (default for demo), false (default for other accounts)	Whether image opens in new tab when clicked
poster	URL to poster image	Videos only. Custom poster for video tags (must be last parameter)
caption	Text string	Images only. Caption text below the image (plain text only)
disable_all_tab	true, false (default)	Deprecated. Whether to hide the 'All' tab

Example with Multiple Options

This is how it looks:

Manual Multi-Code Widget

For manually created code examples with multiple language tabs:

For example:

This renders as:

Supported Languages

Currently supported languages can be found in the content_renderer repository.

Adding Unsupported Languages

To add unsupported languages, use curly braces as the last language in your block:

For syntax highlighting, specify a supported language:

Styled Boxes

Create informational boxes with different styles and purposes.

Basic Syntax

For example:

This is how it looks:

Box Parameters

• :no-icon - Remove the icon
• :no-title - Remove title and icon
  
• :single-line - Render on single line with custom title
• :multi-line - Render on multiple lines without custom title
• :title=Custom Title - Set custom title

Example with parameters:

This is how it looks:

Available Box Types

Type	Syntax	Usage	Default Title
Auto TOC	{autotoc}	Automatically generate page TOC from H2s	"On this page:"
Manual TOC	{toc}	Manually created TOC with custom links	"On this page:"
Note	{note}	Single note (multiple paragraphs OK)	"Note"
Notes	{notes}	Multiple notes (use bullets)	"Notes"
Tip	{tip}	Suggestions and best practices	"Tip"
Caution	{warning}	Risk warnings	"Caution"
Important	{info}	Important information	"Important"
Related Topics	{reading}	Links to other topics	"Related topics"
Code/Syntax	{code}	Syntax examples with links Code snippet file names, like in the SDK quick starts (for this also add the page name to app/assets/stylesheets/partials/_content.scss)	N/A

The default texts are defined in the content renderer, in en.yml under the section special_ui_default_titles https://github.com/CloudinaryLtd/content_renderer/blob/master/config/locales/en.yml

Box Type Examples

Auto TOC

This renders the table of contents that you can see on this page. Adding multiple autotocs doesn't work!

Manual TOC

This renders as:

Note

This renders as:

Notes

This renders as:

Tip

This renders as:

Caution

This renders as:

Important

This renders as:

Related Topics

This renders as:

Code/Syntax

This renders as:

Table Styling

Per-table Styling

Default doc table with no styling:

Outputs as:

Heading 1	Heading 2
Data 1	Data 2

Add an already defined custom class to table header as follows. When prefixing the table with a class, you can't add a vertical bar before the first column heading.

Outputs as:

Heading 1	Heading 2
Data 1	Data 2

To create a new table style:

Define the css for it in: app/assets/stylesheets/partials/_tables.scss in the //table-specific styles section as follows

Custom table style guidelines

• Add new table classes to the _tables.scss file in the //table-specific styles section using the #main designation.
• Give the styles descriptive names so that other people can use the same table style in their docs as needed.
• Use hyphens and not underscores for the style names.

Page-level Table Override

When a page-level override is defined for a specific doc page, all tables in the page without a custom style will use the style overrides defined for the listed pages.

Add page class to app/assets/stylesheets/partials/_tables.scss:

We have a few special pages (mostly old manually maintained references) using this, but in most cases, it works better to use per-table custom styles.

Reusable Snippets (Partials)

Create reusable content snippets that can be included across multiple pages.

Creating Partials

1. Create a file in /documentation folder starting with _partial, e.g., _partial_tutorial_contents.html.md
2. Add any valid markdown content
3. Reference in other files using:

{partialdoc}partial_tutorial_contents{partialdoc}

Variables

Use variables for content that changes based on context.

Defining Variables in en.yml

Add variables to the variables section:

Setting Page-Level Variables

Add to front matter:

Using Variables in Markdown

Variable Markdown Links

Create dynamic links that can be overridden per page:

In partial:

In document front matter:

Video Player Syntax

Embed Cloudinary video players with custom configuration.

Basic Syntax

{videoplayer:id=yourId}
{
   publicId,
   player-config,
   video-config
}
{/videoplayer}

Required Parameters

• id - Player ID (camelCase, no underscores)
• publicId - Video public ID

Optional Player Config

• cloudname - Override default 'demo' account
• playerWidth - Player width (default: 600px)
• adaptive - Enable HLS adaptive streaming (boolean)

Optional Video Config

Any constructor parameters from the Video Player API reference.

You may also need to include videoPlayer: true in the front matter of the page.

Defaults

• muted - true
• controls - true
• bigPlayButton - init
• cloudname - demo
• playerWidth - 600px
• autoplay - false
• adaptive - false
• playbackRates (auto-added to player controls with the following values: 0.5, 1, 1.25, 1.5, 2)
• Dark skin (cannot change this)

Player version

The player version is defined in the content_renderer repo, but can be overwritten within the docs repo using by setting the video_player_version parameter in en.yml.

Video Player Custom Config Example

This renders the Video Player as follows:

Links and Navigation

Use links in the documentation to provide more context or background information, quick access to areas in the Console, external references, related reading topics, and more.

Link types

• Inline links:

• Separate paragraphs such as “Learn more”:

  [Learn more](cloudinary_ai_content_analysis_addon#ai_based_image_captioning)**

• Separate style boxes pointing to one or more links. Usually you'll use the {reading} block for this:

  The default title for the {reading} block is Related topics if you don’t provide a custom one (such as the "See also" shown above).

Link notes

• External links automatically open in a new browser tab. Specify the full URL - including for Cloudinary.com links outside the doc site. For example: [Cedar documentation](https://docs.cedarpolicy.com/)

• Relative links automatically open in the same tab. Use relative links only for links to other doc pages. For example: [Get subfolders](admin_api#get_subfolders)

  Exception: Occasionally you may want a link to another doc page to intentionally open in another tab. In this case, just specify the link as an external URL (keeping in mind that it will then always open the production doc page even if you're working within the dev env/staging/nightly).

• Anchors:

  • To use a heading link that’s different from the heading name, use an anchor with this syntax. In this example, the heading is “Syntax” but the link to it is get_root_folders_syntax: #### Syntax {anchor:get_root_folders_syntax}
    
  • If you’re changing a heading name:
    
  • Search the docs for links to the old heading and update.
    
  • Preserve a link to the old heading (in case it’s referenced from somewhere outside of the docs like blog posts) by adding an anchor directly above the heading using this syntax: <a class="anchor" name="media_library_options"></a>

• Redirects:

  • If you’re moving a heading to another page, add a “redirect” in the front matter of the page where the heading no longer exists, using this syntax:
    redirects: <old_heading_name>: <new_page_name#new_heading_name>

    Here’s an example of the entire front matter:

  • If you’re removing a page, add a “redirect” in the object-redirects.json file using the following syntax:

  For example:

Markdown link auto-completion

By default, Cursor/VS Code automatically completes page and heading links with hyphens (-) whereas our pages & headings contain underscores (_). To enable use of autocomplete when adding links so you don’t have to type out or copy paste the whole link, use this custom extension and these settings:

1. Download this VSIX file: https://res.cloudinary.com/nb90/raw/upload/v1706194619/markdown-all-in-one-3.6.2.vsix
   
2. Install it. (From the Extensions 3-dot menu on the top right, select Install from VSIX…)
   
3. Open the extension settings and set the Slugify Mode to “cld”. Make sure you also have the auto completion option enabled if you don’t already.
   
4. To get the underscore autocomplete option only (instead of both underscores and hyphens), open your Cursor/VS Code settings and search for “path” and filter to markdown. Scroll down to Markdown > Suggest > Paths:Enabled. Deselect this option.

Page Configuration

Front Matter Options

Page Scripts

Add custom JavaScript to specific pages:

Collapsible drop-down sections

If you write content that you don't think all people reading a particular doc page need to see, you can put it into a collapsed drop-down section.

Drop-down guidelines

• The collapsed content isn't physically rendered when the page is loaded. This means that collapsing content also has a page load performance benefit.
• The fact that content isn't rendered also means that you can't link to content inside it. Additionally, linking to a heading that's collapsed currently doesn't cause it to expand (though someday we hope to implement that)
• Don't add a collapsed section within a parent collapsed section. It sometimes works, but can cause other things to break.
• You can use drop-downs on a heading or add it within a section. If adding within a section, make sure the text helps a reader understand what they will find inside a drop-down so it's easier to decide if they want to expand. In most cases, avoid using more generic drop-down texts like "More info".

How to create drop-downs

• To add to a heading, add {collapsed} after the heading text. If the heading also has a custom {anchor}, put the anchor entry first and then the collapsed entry.
• To add a drop-down within a section, use {collapsed:title=More info about configuration...}
• In either case, add {/collapsed} on a separate line after the last line that should be included inside the drop-down. For headings, it's best to collapse everything under that level heading, including any lower-level headings inside it, etc.

Miscellaneous Syntax

Markdown Comments

Create comments that don't appear in HTML:

Responsive Image Galleries

Create responsive image layouts:

For example:

Image Comparison Slider

Use the twentytwenty slider for before/after comparisons:

{partialdoc}partial_twentytwenty_comparison_slider{partialdoc}

Example:

Here's how it looks:

Best Practices

Content Organization

• Use {autotoc} near the top of pages but not right at the top, there should be content above it
• Group related information in styled boxes
  
• Use partials for content repeated across pages
• Set appropriate variables for dynamic content

Performance Considerations

• Use with_code:false and with_url:false for images that don't need code examples
• Optimize image thumbnails with thumb parameter and dpr_2
• Include f_auto/q_auto for automatic optimization

Accessibility

• Always include alt and title attributes for images
• Use descriptive link text
• Provide captions for complex diagrams or screenshots