Adding Documentation Pages

Overview

This guide explains how to add new documentation pages to the site, including file creation, menu configuration, and metadata setup. Follow these steps to ensure proper integration with the site's navigation and functionality.

Quick Checklist

1. Create the new .html.md file in /app/views/documentation/
2. Add the page to the appropriate menu JSON file under /app/menus/submenus/
3. Define title, menu text, description, and metadata in /config/locales/en.yml
4. Test the page and navigation

Step-by-Step Process

Step 1: Create the Markdown File

1. Create a new .html.md file in /app/views/documentation/
2. Choose a descriptive, SEO-friendly filename that matches user search intent (often matches the H1 page name)
   Note

   You set page name as the title in the en.yml file. It doesn't show in markdown.
3. Add the {autotoc} notation near the top to build the TOC on the page

Example file structure:

Step 2: Add to Navigation Menu

Add the page to the menu JSON file under /app/menus/submenus/, depending on the appropriate category:

• Place developer content in programmable-media-menu.json
• Place Assets content in digital-assets-management-menu.json
• Place content related to integrations and other Cloudinary products in more-products-menu.json

Step 3: Configure Titles and Descriptions

Define the page metadata in /config/locales/en.yml under the docs: section:

If you need to Exclude the file from search indexing, add:

Title Configuration Guidelines

• title - Used for the H1 heading on the page (should be sentence case)
• meta_title - Displayed in search engines and browser tabs (~55 characters)
• menu_title - Appears in the left navigation panel (should be concise and sentence case)
• description - Meta description for search engines (~155 characters)

Minimum required configuration:

More info

• filename - Suggest all files in a guide have the same prefix
• menu_title (TOC) - Should be short and assume users know the context of the parent node
• title (H1) - In some cases, might be good to make it slightly more detailed than menu_title, so that users who arrive here via a link from a blog post/other external page/Google hit will understand the context without having to read the breadcrumbs.
• meta_title (Google) - More detail, effort on keywords, should interest both Cld & potential users, but still clearly "Doc" sounding titles & not marketing.

Special Page Types

Landing Pages for Guides

If the page is a new top-level get started, guide, or reference topic, add a card in the parent landing page that links to your new page.

For example, when adding a new developer guide, add a card to the Guides landing page.

1. Copy one of the existing cards on that page
2. Paste it within container: <div class="cards-ref-container">
3. Update the appropriate card elements to match your new guide

New Add-ons

Follow additional steps for add-on documentation:

1. Add cards to the cloudinary_add_ons page, as described in Landing Pages for Guides
2. Update relevant API references with new parameters and links

Page Configuration Options

Front Matter Options

Example:

Descriptions:

• categories: This section configures which searches return this page
  • media_type: Image, Video or both with a | separator
  • content_type: Feature guide, Reference, Tutorial, Overview (exactly one)
  • product: IMG, VID, DAM, INT (one or more with a | separator)
• module:
  • Required if product includes IMG or VID for product.
  • Use Upload, Delivery, Management, Optimization, Transformations, or N/A (exactly one)
  • Optionally add Image or Video if the page focuses on one (e.g., Delivery|Video)
  • Use N/A for high-level or cross-product topics
• variables: What value to replace for variables in partials on this page. For more information, see Variables.
• mediaType: Specifically for pages with partials that should display different content based on the image or video label.
• scripts: Add any custom scripts that you need to run videos or demos on the page. See Custom Page Scripts.
• canonical: Used for duplicate pages. See Duplicate menu entries.
• updated_date: Use the format mon-day-year (e.g., Jul-31-2025)

Special Configuration

Adding Page Icons

1. Upload SVG icon to Cloudinary account (cn:cloudinary) at the root level
2. Add the page to en.yml along with the icon parameter:

1. Add icon to the list in content.scss under @include icon-backgrounds

Custom Page Scripts

If you want to include JavaScript on a particular page (instead of adding it to ALL pages) you can use the scripts meta. Each entry has a key that defines the purpose of the script and the possible values are:

For example in page meta:

In assets.rb:

This PR shows it well

Menu Configuration

TBD - Add a sub-section here explaining all the menu options this json supports (children, external, hidden, etc)

Duplicate Menu Entries

If we want to include a virtually duplicate page in two places in the TOC, we have two options:

• Have an entry in the TOC that jumps to another location in the docs
• Create two different parent markdown pages, where the content is populated by one-or-more partials and uses variables for small differences as relevant

  In this case, if the page is 90% or more identical, we should consider using a canonical so that only the more relevant of the two pages will generally be found in a search engine & the search engine (i.e. Google) won't punish us for duplicate content, yet if the search is specific enough, the 2nd page can also be found.

To create a TOC jump

Same page name

• In xxx-menu.json find the place you want to add the duplicate entry
• Add the entry as you would with any other page.
• Add “duplicate”: true to the object after the id e.g. { "id": "video_player_api_reference", "duplicate": true }

Different (aka dummy) page names

Add a menu entry relevant menu.json page as follows:

• id - A 'dummy' ID (not an actual page) - Define the text value for the id in en.yml as shown below
• "duplicate": true - Results in a jump icon being added next to the entry path - The page you want the entry to jump to

To create separate duplicate pages

• Create a new markdown page & add to the xxx-menu.json and en.yml as with any other page
• Use the instructions for partials and variables to include the duplicate content.
• Decide whether you want to fully index both pages (if the variables, excluded partials, or other differences between the pages are significant enough, or whether they are so similar that it's better to define a custom canonical entry)
• To add the canonical entry in the generated HTML page, add the following to the metadata (yaml) content at the top of the secondary markdown page: canonical: /primary_markdown_file_name

Page Removal and Redirects

Sometimes old pages need to be removed or the content from those pages needs to be moved to a different page. In very rare situations, we may need to change the filename of an already published page. There’s a few steps to go through to ensure this doesn’t break anything on the existing site.

1. Remove or update the page metadata in the config > en.yml. If you’re renaming the filename ensure the new filename is here. Be careful when renaming pages, for the sake of SEO and redirects it’s often better to change the page title and keep the filename (URL) as is.
   

   Note

   For redirection purposes, ensure that the new filename does not start with the same value as the old name because the redirect definition matches the prefix for the redirect. If the page also matches the prefix of the old page, this causes an infinite redirection (for example, do not change page_name to page_name_new).

2. Remove or edit any references to the old page in menus > xxx-main.json.

3. Search through the entire repository for any links to the old page Or the anchored headings on that page. Either remove or update the links as relevant.

4. Add an entry to config > object-redirects.json to redirect the old page to the renamed page, or in the case of a removed page, to some other relevant existing doc page. Your entry should look like the below.

1. Always Test your redirect by deploying to the staging environment.
2. Delete the old file from the repository. Don’t be scared, we have source control, we can always get it back again. Keeping unused files in the /documentation folder can cause the jenkins build to fail.

Testing and Validation

This checklist isn't comprehensive and needs to include proofreading, verifying content, and viewing all markdown components in your dev environment (in both dark and light mode).

Before Publishing

1. Test navigation - Verify page appears correctly in menus
2. Check responsive design - Test on mobile and tablet
3. Validate links - Ensure all internal/external links work
4. Review SEO elements - Confirm titles and descriptions are appropriate
5. Test search functionality - Verify page is discoverable

Link Validation

If you changed any headings on your page, search the codebase for any links that might be affected by your changes:

Check:

1. Links to anchors on same page (#anchor)
2. Links to the page from other documentation
3. References in blog posts or external content

Auto-TOC Testing

For pages with {autotoc}:

• Verify TOC generates correctly
• Check that heading hierarchy is logical
• Ensure TOC updates after refresh when headings change
  Note

  Sometimes you need to refresh twice before the TOC headings reflect your changes.

Common Issues and Solutions

Menu Problems

• Page doesn't appear: Check JSON syntax in main.json
• Wrong hierarchy: Verify parent-child relationships in JSON

Styling Issues

• Missing table borders: Add page to table styling definitions (see Table styling).
• Broken responsive layout: Check HTML structure and CSS classes
  
• Icon not appearing: Verify SVG format, sprite definition, and public ID

SEO and Metadata

• Missing from search: Check noindex setting and search indexing
• Incorrect preview: Validate meta_title and description lengths

Best Practices

Content Organization

• Use descriptive, SEO-friendly filenames
• Maintain consistent heading hierarchy (H1 → H2 → H3)
• Include {autotoc} for pages with multiple sections
• Group related content logically

Navigation Design

• Keep menu titles concise but descriptive
• Consider user mental models when organizing hierarchy
• Use duplicate menu entries sparingly
• Test navigation flow from user perspective

Performance Optimization

• Optimize images with appropriate transformations
• Include only necessary scripts and styles
• Use partials for repeated content
• Consider page loading impact

SEO Considerations

• Coordinate with SEO team on titles and descriptions
• Use internal linking to improve page authority
• Ensure mobile-friendly responsive design
• Include structured data where appropriate