Automated scripts and rules

Overview

This guide provides comprehensive information about the automated processes and scripts used by the documentation team.

Cursor rules

Rules that point to internal docs

Some of our rules just point to our internal docs. Make sure they're set to Apply intelligently in your Cursor app. Cursor should generally pay attention to these when you are in cld_docs and you ask it to write doc content. These include:

• cloudinary-docs: Instructs cursor to apply our custom markdown.
• content-style: Instructs cursor to follow our style guide.

create-documentation-page rule

Set the rule to Apply Intelligently. It's applied whenever you ask Cursor to create a doc page for you.

The rule applies to 2 scenarios:

• Create a blank doc page - You provide some info about the page you want (or a spec or JIRA). Based on the info you provide, it creates a new markdown file (html.md), including all relevant front matter, adds it to the en.yml and adds it to the right place in the relevant menu. Works best if you're specific about what you want the filename to be, which product menu and where in the menu you want to place it, but if you don't give that info, it guesses.

• Create a new page with the content from a URL - You provide the URL (could be a KB article or other published web page that you want to convert to a doc page), tell it what product (the name displayed for the product in the top-menu) & the name of the guide where you want to add the new page, and it does all of what's described above + generates markdown identical to that of the URL you gave it, including applying standard markdown formatting for any formatting in the URL (it's strictly forbidden to summarize or otherwise improve the content on its own). It also adds the {autotoc} entry if the passed URL has one or more headings in the content.

  Only exceptions to the identical content rule should be:

  • For any links to our documentation, convert them to relative links (even if the original URL is absolute). For all other external links, leave them unchanged. The link text should be descriptive; for documentation links, use the title of the heading it links to.
  • For Cloudinary API or transformation code examples, use the appropriate transformation or multi-code widget to display the code.
  • For KB articles, follow the specific rules for embedding images and videos: images originally embedded via Zendesk's standard URL should be automatically mapped to a cloudinary-res URL under /docs/ts/.
  • For notes or tips, use our custom markdown tag notation. Also, remove introductory phrases like "Note that" from the beginning of such content.

Additionally, there are further guidelines specific to KB articles:

• It names the page as ts_<prod_prefix_if_not_img_vid_prod>_<URL filename minus any random id characters>. For example, if the URL is https://support.cloudinary.com/hc/en-us/articles/19651183073042-What-Are-the-Common-Errors-Encountered-in-the-Media-Library, the generated markdown file will be: ts_dam_what_are_the_common_errors_encountered_in_the_media_library.html.md
• It checks if there's already a parent Troubleshooting and Tips page for the relevant product and guide, and if there is, it adds the new page as a child page under that parent. If there isn't, it creates the parent page and add the new page as a child page under that parent. Afterwards:
  • It adds the new TS page as a new row in the table on the parent "Troubleshooting and Tips" page, including a link & short description of the page. The table row entry should look something like this:
  • It adds the new page to the menu file in the right location under the parent file (if needed it first adds the newly created parent page as the last top-level entry of the relevant guide), and add the new page to the en.yml file in the right location.

Cursor commands

To apply a Cursor command, type / and make sure you've passed whatever info the command expects.

branch command

Creates a new branch in the repo based on the passed JIRA ID and title.

migrate-kb command

Creates a new doc page from the supplied KB article, based on the provided URL, product name, and guide name. It strictly follows all page creation & KB-specific guidance in the create-documentation-page rule.

Scripts

Convert FIN spreadsheet conversations to HTML

You can run a python script to convert all or selected conversations from the FIN spreadsheet to HTML.

See FIN Analysis Process for more details.