Skip to main content
Use this guide when you need to update en/automation/crmscript/reference/, the generated CRMScript class library reference.

​
Source of truth

The reference isn’t hand-written. It’s generated from hand-maintained DocFx YamlMime:ManagedReference YAML files in api-sources/crmscript/. Each YAML file describes one class, namespace, or enum, and produces exactly one .mdx file with the same name. Three tools do the work:
  • tools/transform-crmscript.ps1 converts the YAML into the reference .mdx files.
  • tools/generate-crmscript-nav.ps1 lists the generated .mdx files, classifies each one by namespace and by its source YAML type: field (Namespace/Class/Enum), and writes config/nav-crmscript-ref.json — a nested Mintlify nav structure (Global functions, Basic data types, Data Structures, Native, and NetServer split into Classes/Enums sub-groups, matching the old DocFx site’s taxonomy) that nav-en.json’s CRMScript Reference tab pulls in as $ref.
  • tools/regenerate-crmscript-reference.ps1 runs both of the above, then tools/verify-nav-paths.py, in one step: the command to reach for in the how-tos below unless you specifically need just one stage.
transform-crmscript.ps1 always reprocesses every file in api-sources/crmscript/: there’s no option to target a single file. It preserves each output file’s existing date and version frontmatter by reading the current .mdx before overwriting it, so a file you didn’t mean to touch should come out byte-identical. Run git diff --stat after every regeneration, and treat any change outside the files you intended to edit as something to investigate, not something to commit blindly.

​
Edit an existing method, property, or class

  1. Edit the relevant .yml file in api-sources/crmscript/.
  2. Run tools/regenerate-crmscript-reference.ps1 from the repo root.
  3. Check git diff --stat: only the one .mdx file for the class you edited should show a change.
  4. Run markdownlint-cli2 against the regenerated file.
  5. Commit the source .yml and the generated .mdx together.

​
Add a new class

  1. Add the new .yml file to api-sources/crmscript/.
  2. Run tools/regenerate-crmscript-reference.ps1. It generates the new .mdx file, regenerates config/nav-crmscript-ref.json (the new page is classified into the correct group automatically — by its filename’s namespace prefix, and by its source YAML’s type: field for the NetServer Classes/Enums split — and sorted case-insensitively within that group: no manual nav edit needed), and confirms every nav entry resolves to a real file.
en/automation/crmscript/reference/index.mdx is hand-written, not generated. It only curates the Global, Data Structures, and Native sections. Add a link there only if the new class belongs in one of those three groups. NetServer and other classes are reachable through the left-hand sidebar nav’s own named groups alone and don’t need an index.mdx edit.

​
Remove a class

  1. Delete the .yml file from api-sources/crmscript/.
  2. Delete the corresponding .mdx file from en/automation/crmscript/reference/ by hand. transform-crmscript.ps1 only generates and updates files: it never deletes orphaned output.
  3. Either re-run tools/generate-crmscript-nav.ps1 to regenerate config/nav-crmscript-ref.json without the removed page, or remove that one entry from the file by hand (it now lives inside one of the nested pages arrays, not a single flat list — find it by group first). Both are equally valid: the script is a convenience for the common case, not the only way to update the file.
  4. Remove any hand-written link from index.mdx if the class was listed there.
  5. Run tools/verify-nav-paths.py config/nav-crmscript-ref.json to confirm nothing still points at the removed page.

​
Preview or validate the reference locally

CRMScript reference content previews normally with mint dev/mint validate. If you hit an EMFILE: too many open files error at this repo’s current page count, exclude a different content folder in .mintignore instead (for example, one of the language folders) rather than adding more exclusions on top, and don’t commit that change.

​
Automated drift check

A GitHub Action regenerates the reference from api-sources/crmscript/ on every pull request that touches that folder, the generated reference, or either generator script, and fails if the result doesn’t match what’s committed. This catches both directions of drift with one mechanism, since regeneration is deterministic: a source .yml edited without regenerating, and a generated .mdx hand-edited directly without touching its source (that edit is silently lost the next time someone else runs a real regeneration). The failure message names the specific api-sources/crmscript/<Name>.yml source file to check.
The YAML files in api-sources/crmscript/ aren’t only docs source material: many entries carry an so.intellisense key that feeds the CRMScript interpreter’s own built-in intellisense. Treat a drift-check failure as “go check both the doc and the source,” not as a formatting nit to wave through.
This doesn’t catch a .yml file being deleted without its .mdx counterpart: that’s a different kind of drift (a stale, orphaned generated page with no live source), tracked separately in issue #216.

​
Known gotchas

​
Garbled characters after regenerating

If a regenerated file shows corrupted multi-byte characters (smart quotes, accented or non-Latin names) in the diff, that’s a PowerShell read-encoding issue, not a real content change. Don’t commit it. See tools/README.md for the underlying cause and the write-side conventions these scripts follow.

​
HTML-escaped remarks

HTML markup embedded in a class’s <remarks> field (for example <ul><li>) is intentionally HTML-entity-escaped rather than rendered, so it displays as visible escaped tags on a handful of pages, such as CRMScript.Native.Ticket and CRMScript.NetServer.NSFieldMetadata. This is expected current behavior, not something to fix as part of a routine content update.

​
Out of scope

en/automation/trigger/reference/CRMScript.Event.Trigger.mdx and CRMScript.Event.mdx were a one-off manual conversion from raw DocFx YAML, done with the same tool pointed at different source and output paths. They aren’t wired into any repeatable pipeline run today. Treat them as hand-maintained pages, separate from the regeneration flow described above.