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

We have a few rules that just point to our internal docs. Make sure they are 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

This rule should also be set to 'Apply Intelligently' It's applied whenever you ask Cursor to create a doc page for you.

{info}
To use this rule to generate markdown from a URL, first install the PlayWrite MCP server, which supports browsing to URLs and converting them to markdown.

Additionally, if using this rule to migrate KB articles, best to apply it using the migrate-kb command below.

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 & guide you want to add the new page to, 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 to if the passed URL has one or more subheadings.

  Only exceptions to the identical content rule should be:

  • For any links to our docs, it applies them as relative links (even though they are absolute links in the URL). For any other links, it applies them as is. Additionally, it's supposed to make the display text of the link either descriptive text or for doc links, the title of the heading it's linking to.
  • For any Cloudinary API or transformation code examples, it applies them using the transformation or multi code widget as appropriate.
  • Specifically for KB articles, there are rules about how to embed the images and videos. Images that were embedded in the KB article using zendesk's standard URL are auto-mapped to a cloudinary-res URL under /docs/ts/.
  • For any note or tip style content, it applies our custom markdown tag notation and removes words like "Note that" from the start of such text.

In addition to the above, there are some other special guidelines for KB articles:

• It names the page as ts_<URL filename minus any random id characters>.
• 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.
  • It adds the new 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.