Documentation Index

Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt

Use this file to discover all available pages before exploring further.

Internal
Menu

Content Creation Guidelines

Last updated: May-20-2026

Overview

This guide covers the additional content creation processes, focusing on specific workflows for SDKs, add-ons, and video tutorials.

On this page:

Adding a New SDK or Integrations Guide

  1. Follow instructions for Adding a new documentation page

  2. Add logo for integration & home page

    • Get an svg image for the new framework - ideally, it should be well cropped to the logo. If not, you can use https://svgcrop.com/ to crop it.
    • Assign the relevant sprite tag & regenerate the sprite using the API

  3. Add the new page & icon to the relevant SDK, integration, or 3rd party partials page

  4. Make sure the JIRA Epic for the new SDK includes tasks (for SDK/front-end team) to update welcome email, dashboard quick links, and onboarding widget. Give them the main doc page for the SDK framework that they should link to.

  5. Add link to SDK from the following locations:

Source file File usage To do
documentation/image_transformation Doc file All SDKs currently mentioned 2x. Once to main section and once specifically to section about image_tag.
documentation/_client_libraries Snippet that's called from many of the haml-based add-on help pages Add/update as needed

Documenting New Add-ons

Every new Add-on should have an Epic in JIRA. That epic should include user stories for:

  • Docs Write Snippet - (JIRA that's generated from the Dev Snippet issue) write text for snippet & provide dev with the link they should use to the docs. This JIRA is in our doc sprint. When done, copy-paste the text & link to the CLD issue & then mark the Docs issue as done.

  • Snippet Graphics - Prepare svg icon & a graphic for within the snippet

  • Dev implement Snippet - Create the snippet itself.

Note
Important - make sure that Dev doesn't deploy the snippet until the add-on docs are ready to be deployed.

  • Add-on development - CLD issue assigned to dev for actually creating the add-on

    • Should be marked as impacts doc, which will generate the Doc Add-on issue.

  • Document add-on - DOC issue generated from CLD issue. See Add-on Help Page below for full checklist.

  • Console Settings - For some add-ons, there are settings in the console. If relevant, there should be JIRA issues for these (and we should document as appropriate)

    • If it's an on-the-fly transformation add-on, the add-on should be in the "Allow unsigned add-on transformations" option under Security
    • If it's an add-on that's activated on Upload, the add-on needs to be added to the upload preset settings
    • If it's a moderation add-on, needs to get added to the Moderation drop-down in the Moderation view.
    • There may be other special settings for specific add-ons - if so, make sure our docs cover these - Just add notes to your main "Document the add-on" JIRA issue and/or link these settings JIRA to your "Document the add-on" JIRA issue. No need for separate doc issue for these.

Videos

Related topics
These are all the references to videos in the internal docs:

Content Creation Guidelines

Custom Markdown Syntax

Automated scripts and rules

Videos with speech (like tutorials)

Upload the video using this page: https://cloudinary-devs.github.io/cld-docs-assets/upload/tutorial-uploads.html.

This uses the auto-tutorial upload preset to automatically upload it to the training folder in the cloudinary product environment and generate captions, subtitles and chapters.

(Or, if you're in the cloudinary product environment, navigate to the training folder and use the upload preset, auto-tutorial-signed.)

Use the Video Player JavaScript to render the video on the page with chapters, subtitles and captions. Copy the code from e.g. upload_programmatically_tutorial.html.md:

Put videoPlayer: true in the front matter.

Note
No jQuery required: Video tutorial pages and partial cards use pure JavaScript (via the buildTutorialVideoTag function in app/assets/javascripts/docs-tutorial-video-tag.js). You don't need to include the cloudinaryjQuery script in the frontmatter.

Then, use this code to render the Video Player (for some reason it doesn't display in docs-dev), replacing the public ID in publicID and posterOptions:

To add a new Video Tutorial page to the corresponding Video Tutorial library, use the add-video-tutorial Cursor command. This should do all the code for you.

Videos without speech (like teasers)

Upload the video to the cloudinary product environment, using the upload preset docs_videos.

Use the videoplayer markdown syntax.

Video transformation examples

Use the transformation widget syntax, e.g.:

Dev Hints videos

Adding Existing Dev Hints

Dev Hints videos should have already been uploaded to the training folder in the cloudinary product environment using https://cloudinary-devs.github.io/cld-docs-assets/upload/tutorial-uploads.html.

In the JIRA ticket, add the public ID of the video to the description or a comment.

Use the add-video-tutorial Cursor command to add a new Video Tutorial page to the corresponding Video Tutorial library.

Creating New Tutorials

You can use Camtasia to create video tutorials.

For a demo of how we use it in Cloudinary, see https://Cloudinary.zoom.us/rec/share/CLc-SNGCw36Fqw98qZFqfrdEvJTAvj5XZDM8iKo7FQNftyLT1QuGSO5rk6HA0WAK.TTwSH-2lz_IqiPft

Plus, there are lots of video editing tutorials here: https://www.techsmith.com/learn/tutorials/camtasia/

Import the Cloudinary brand assets library from here: https://drive.google.com/file/d/1Xxy2cenWfKjH7KoVIajWgLX7MIQAdIFA/view?usp=sharing

Use BetterDisplay to set your screen up for a 16:9 recording.

Better Display

Better Display

Better Display

Better Display

Better Display

Better Display

Better Display

Better Display

It's also good to hide the menu bar and Dock (you can do this in your Mac settings), then you have the full 16:9 screen for the app you want to show. If you start recording with the video tool with the full screen, then the project settings should automatically set themselves to FHD (1920 x 1080), which is what you want to export the video at.

Better Display

See Videos with speech for adding them to the docs.

Detailed doc, that Becky wrote for the training team: https://cloudinary.atlassian.net/wiki/spaces/CE/pages/1940062820/How+to+Migrate+a+Video+into+the+Docs+Video+Library

Code Explorers Integration

Embedding Code Explorers

TO BE UPDATED WITH NEW PROCESS: DOC-10964

Adding Sandboxes to the Code Explorers Page

TO BE UPDATED WITH NEW PROCESS: DOC-10964 - LEAVING EXISTING CONTENT FOR REFERENCE SINCE SOME OF THESE INSTRUCTIONS MIGHT STILL BE PART OF THE NEW PROCESS

To include a sandbox in the Try it! Code Explorers page:

  1. Add the sandbox title to sandboxOptions (around line 12 in code-explorers.js)

    • Find the array for your language (e.g., javascript, react, angular, vue, node, python, go, Rest)
    • Add your sandbox title as a new string entry in the array
    • The title should match the title property you'll use in sandboxMapping

  2. Add a new entry to sandboxMapping (starting around line 83 in code-explorers.js)

    • Create a key by taking your title, converting it to lowercase, replacing spaces with hyphens, and appending a hyphen followed by the first letter of the language (e.g., -j for JavaScript, -r for React, -a for Angular, -v for Vue, -n for Node, -p for Python, -g for Go, -R for REST)
    • Example key: 'my-new-sandbox-title-j' for a JavaScript sandbox

  3. Configure the sandbox entry properties:

    • url: The sandbox embed URL for the iframe in the Code Explorers page (include ?ctl=1&embed=1&file=... parameters)
    • source: The platform hosting the sandbox (e.g., 'StackBlitz', 'CodeSandbox', 'GitHub')
    • title: The display title (must match the entry in sandboxOptions)
    • gaTitle: Google Analytics tracking ID in format <language>-<hyphenated-description> (e.g., 'javascript-upload-widget')
    • blurb: A short description of what the sandbox demonstrates
    • context: The doc page anchor link (e.g., 'upload_widget#sample_app_upload_widget_example')
    • contextWording: The link text for the context link (e.g., 'Upload widget guide')
    • githubUrl: Link to the GitHub repository (leave empty string '' if none)

Example entry:

Images & Videos in Docs & Posts

Legal Requirements

  • All media must be legally distributable (CC0 license, purchased by Cloudinary, created by a Cloudinary graphic artist)

  • Good sources of CC0 images & videos:

Images

Icons

Videos

Storage Guidelines

  • All media should be delivered via Cloudinary:

  • For media you use to demonstrate Cloudinary features, store the original in the /docs folder in the Demo account & tag it with "CC0"

  • All other media - i.e. diagram images, logos, blog top images, etc, store them in the /docs folder in the Cloudinary account

CC0 Graphics Sources

Images

Icons

Videos

Related topics

✔️ Feedback sent!

Rate this page:

one star two stars three stars four stars five stars