README files for content entities - Developer Guide - Cortex XSIAM - Cortex - Security Operations

Cortex XSIAM Developer Guide
Product
Cortex XSIAM
Creation date
2023-05-01
Last date published
2024-06-04
Category
Developer Guide
Abstract

Create and deploy entity README files that include images and videos.

Documentation is a critical step that assists customers who may use your integration/script/playbook by providing insight into how the content entity is supposed to work. From creating custom playbooks, to providing background information to assist in debugging, it is important to ensure that the documentation explains every aspect of the integration. Documentation is maintained as README.md per integration/script/playbook and made available for customers as part of the reference docs of the Cortex XSIAM Developer Hub.

We recommend reviewing the HelloWorld integration README file as you create the README files for your content entities.

Note

Images and videos can be added to documentation.

Documentation must be generated if:

  • If the content entity is new.

  • If the content entity exists but is missing documentation.

  • If the content entity exists and some of it has changed. For example, a new command was added or context was changed.

Documentation examples
Documentation Deployment

After the pull request with the documentation README file is merged into master, it becomes available as part of the Developer Hub, and can be viewed in the reference docs section. The site is updated with the latest content on a daily basis. If you wish to preview how the documentation looks at the Developer Hub, before merging to master, you can either run locally the content-docs project to preview the Reference Docs site locally or create a PR at the content-docs repo.

Preview by generating reference docs locally (recommended)

Clone or download the content-docs repo. Follow the instructions at the project's README to run the site locally and generate Reference Docs for the content repo you have locally. For example run in the content-docs checkout dir:

CONTENT_REPO_DIR=~/dev/demisto/content npm run reference-docs && npm start

Preview by creating a PR at the content docs repo

Create a PR at the content-docs repo with the same branch name as the PR you are working on in the content repo. Mention in the PR that it is related to a PR from the content repo. Your PR in the content-docs repo will include a preview link in the GitHub Checks section from deploy/netlify. You can perform a dummy white space change for the PR that will re-trigger the build and create a new preview. Example screenshot for preview link:

doc-preview-check.png
MDX to generate the Markdown file

We use MDX for the Markdown generation. MDX is a superset of standard Markdown, but it requires that any HTML used in the document must be JSX compliant. This means all HTML tags need to contain a closing tag. For example don't use <br>, use <br/>. Additionally, HTML entities < >, not in code blocks need to be encoded. Use &lt; and &gt; to encode. As part of the CircleCI build, the README.md file is validated that it is MDX compliant.