Essential Tools

Overview

This guide covers the essential tools and setup needed for documentation team productivity. It focuses on the IDE, extensions, and source control basics you'll need for day-to-day work.

For information on setting up and running the documentation site locally, see Dev Environment Setup Guide.

Text Editors and IDEs

Cursor (Primary Choice)

Cursor is our primary recommended IDE for documentation work. It provides enhanced AI-powered editing capabilities while maintaining full compatibility with VS Code extensions and settings.

Key Benefits:

• AI-powered assistance - Context-aware code and content suggestions
• VS Code compatibility - Import existing VS Code settings and extensions seamlessly
• Enhanced productivity - Built-in AI chat and code generation
• Familiar interface - Same UI as VS Code with additional AI features

Install the Cloudinary-licensed version of Cursor using this invitation link.

VS Code (Alternative Option)

VS Code remains a solid alternative choice. Anyone using VS Code can easily migrate their settings and extensions to Cursor.

Essential Extensions

Markdown All in One

Enhanced markdown editing and preview capabilities essential for efficient documentation writing. Recommend using the fork of this which enables Cloudinary specific anchor link slug autocompletion.

Download the VSIX file

To install the VSIX file, open the Extensions view in the VS Code left sidebar (or Cmd+Shift+P > Extensions: Show All Extensions), click the ... menu at the top of the Extensions pane, select "Install from VSIX...", and select the downloaded VSIX for the Markdown All in One extension.

• Allows you to hover over the partial name in the markdown to see the content of the markdown and a link to that partial.
• Evaluates variables on the page

Update Markdown extension preferences:

After you download the extension, in the top menu bar, select Code > Preferences > Settings or for Cursor: Cursor > Settings > VS Code Settings.

Expand Extensions and scroll to Markdown All in One.

Near the bottom of that section, clear the checkboxes for Ordered list, Plain text for TOC, and TOC autoupdate on save.

Vale

Style and grammar linting extension that ensures consistency and quality across all documentation.

See Vale Linting/Spellcheck for more details.

cld_docs_extension

Cloudinary documentation-specific tooling that streamlines workflow with project-specific features.

Get extension here.

Download the VSIX file for the latest version from the releases page.

To install the VSIX file, open the Extensions view in the VS Code left sidebar (or Cmd+Shift+P > Extensions: Show All Extensions), click the ... menu at the top of the Extensions pane, select "Install from VSIX...", and select the downloaded VSIX for the Cloudinary Docs extension.

• Allows you to hover over the partial name in the markdown to see the content of the markdown and a link to that partial.
• Evaluates variables on the page

More to come.

Cloudinary Extension

Manage Cloudinary media assets from within the documentation.

Follow the instructions in the Cloudinary VS Code Extension guide to install and set up the extension.

Update your configuration with all the product environments you use (personal account, demo, cloudinary etc). You can now easily upload images to the relevant account and use them in the documentation.

Replacement MacBook Tips

Migrate VS Code settings - under Preferences, there's an option to enable "Settings sync". You can sign in with GitHub and to automatically sync all of your settings and extensions, so when you enable "Settings sync" on your new mac it automatically works just like your old one.

Other Tools

Chrome Extensions

Cloudinary Media Inspector

Analyze and inspect Cloudinary media assets and transformations directly in the browser.

Install from the Chrome Web Store.

Debugger for Google Analytics 4 (GA4 Debugger)

Debug and monitor Google Analytics 4 tracking implementation on documentation pages.

Install from the Chrome Web Store.

MCP Servers

1. Required for KB migration - Install the Playwright MCP server. This provides advanced browsing tools which can better extract existing KB article content.
2. Install the Cloudinary MCP servers if planning to use the MCP servers for testing.

Source Control

Git

It's each to their own when it comes to git. Main options:

1. Command Line - old school for those that really know what they're doing.
2. Built in git in Cursor/VS Code.
3. SourceTree - a GUI for git.
4. Other GUI options.

Git Branch Naming and JIRA-Git Auto Transitioning

Each JIRA that requires changes to Git files should have its own branch in cld_docs. The branch name should be in the format: DOC-XYZ_Short_Description.

As long as you follow this naming guideline, the JIRA automatically change statuses with your GIT activity:

• When you create a branch & push it to remote, the JIRA issue automatically moves from New to In Progress
• When you create a pull request, the issue automatically moves to In Review
• When you merge (or merge & squash) a PR, the issue automatically moves to Done

If you commit a small JIRA into a branch that's not named in the format mentioned above (or you commit it in a branch of another JIRA number) and you still comment the JIRA commit with the name of your JIRA, then although it won't move through the stages of In Progress & In Review, the JIRA still automatically moves to done when you merge the parent branch to master.

Quality Assurance

Vale Linting/Spellcheck

The Vale linter provides spellchecking, repeated words check and terms checks. The linter runs when a PR is open and when any changes are committed. The build will fail if there's any errors found and the file with the errors will have annotations.

Recommend installing the Vale CLI locally and optionally the VSCode plugin.

Vale CLI

Once installed, you can run a check locally against the whole of the documentation folder. Change to the dev/cld_docs directory and enter the following command:

Vale VSCode Plugin

1. Install & enable the plugin & restart VS Code
2. Open any doc .md file & show the VS Console (Problems tab)
3. You can click any error/warning/suggestion to jump to it and fix it
4. After fixing an error, save the file, and the error/suggestion should disappear from the console

Exceptions

Spelling Exceptions

If any spelling errors found aren't legitimate errors (e.g. it's a param or cld term etc), you will need to add an exception to the following file: .github/styles/config/vocabularies/cld/accept.txt

This text file contains a list which is roughly organized into categories and alphabetically sorted. You can add an exception to this file by adding the word to the relevant category. By default the file is case-sensitive, you can use this to enforce a certain case, but it many instances you will want to allow different cases, you can use some patterns for this:

• Adding both cases of a letter in square brackets e.g. [Ww]ord
• Adding (?i) before a word to allow any casing at all

You can also allow plurals of a word/term by adding the s in brackets with a ? after. E.g. word(s)?

Once updated, it's best to run Vale locally and verify you have no errors before committing and pushing.

Other exceptions

In general, we should try to keep error/warning/suggestion exceptions to a minimum. First think carefully whether there's a better way to write the sentence to match our style guidelines -- i.e. try to change passive to active voice, future to present, etc, even if it means rewriting the sentence and not just the highlighted phrase. Keep a phrase as two words instead of a contraction only if really essential to highlight a "not" or similar.

Only apply exceptions if you strongly feel that the sentence is the most correct when written as is.

To apply an exception for a block or inline, use the specific vale exclude syntax:

Wrap the relevant line(s) or text in {valeExclude}...{/valeExclude} tags.

For example: