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/automation/playbook and made available for customers as part of the reference docs of the Cortex XSOAR Developer Hub.
This document guides you through the generation of the README files from entity YML files. When writing the actual entity descriptions, make sure to follow our Documentation Best Practices.
- If the content entity is new then you are required to create new documentation.
- If the content entity is existing but missing documentation then please create new documentation.
- If the content entity is existing and some of it has changed. For example, a new command was added, context was changed, or anything else; please update the documentation.
demisto-sdk generate-docs command to generate documentation for your content entity. Documentation for the command is available here.
To automatically generate example output (human readable and context), you should create a text file containing command examples, one per line. The command examples should appear the same way they would as in the CLI in Cortex XSOAR, for example
Commands will be executed one at a time, in the order in which they appear in the file. If there are duplicates of a command included in the text file, only the output of the command's first execution will be included in the generated documentation output.
command_examples.txt file in the same directory as the Integration. Make sure to check this file in to git, so if needed to regenerate the documentation in the future, the commands are easily available. Example for
A larger example of such a file is available here.
Make sure to set your environment variables:
demisto-sdk will be able to connect to the Server to run the commands. Run the
generate-docs command with an input of the content entity's yml file and the
command_examples.txt file in case you are documenting an integration. For example:
If you are connecting to a Server with a self signed certificate, make sure to pass the
--insecure option to the
Images in the documentation should be added to the relevant pack under a
doc_imgs directory. Images may be included with absolute or relative URLs.
You may use relative URLs to documentation images stored in the
doc_imgs directories. To use relative URLs simply link to the image using a relative path such as (if the
doc_files dir is located at the top level Pack directory):
Or for example as (if the
doc_files dir is located at the same level as the README.md file):
Make sure to view the README.md file in GitHub's web interface and validate that the images display properly.
Documentation with Relative URL examples:
- Google Calendar: https://github.com/demisto/content/blob/master/Packs/GoogleCalendar/Integrations/GoogleCalendar/README.md
- G Suite Admin: https://github.com/demisto/content/blob/master/Packs/GSuiteAdmin/Integrations/GSuiteAdmin/README.md
To obtain an absolute URL to an image from GitHub:
- Commit the image and push to GitHub.
- View the file in the GitHub web interface.
- Copy the URL from the
- Make sure the URL you are copying is not referring to a branch which will be deleted after the PR is merged. The URL should refer to a commit hash or the
- Note: if you click the
Downloadbutton, GitHub will perform a redirect and the url in the browser will point to the domain:
raw.githubusercontent.com. You may also use this URL as the absolute URL.
Embed the image in the README.md using a Markdown Image Link, such as:
Or if you want more control on the image (for example setting width dimension) you can use the HTML
<img> tag, such as:
Absolute Image URL Examples:
- URL to commit hash: https://github.com/demisto/content/raw/2d6e082cfb181f823e5b1446ae71e10537591ea6/Packs/AutoFocus/doc_files/AutoFocusPolling.png
- URL to
- URL after redirection (also valid): https://raw.githubusercontent.com/demisto/content/master/Packs/AutoFocus/doc_files/AutoFocusPolling.png
A video can provide a great addition to the documentation either as a demo video or tutorial. The preferred video format is
Because of their size and in order to keep our main Content repo small, we store large media files in a separate repository: content-assets.
To add the video file, open a pull request with the video file at content-assets repository. The file should be placed in the directory:
All videos should be included with absolute URLs. To obtain a URL to a video from GitHub follow the same steps as detailed for images only now this is being done in the content-assets repository.
Include the video using the HTML
<video> tag, such as:
Note: GitHub markdown preview will not display the video (it will show the
browser not supported message). Rest assured, the dev docs site will display the video properly as can be seen at the following example.
Steps for adding a large file:
- Clone or fork the content-assets repository.
- Make sure you have git-lfs installed. See instructions here.
- Install git-lfs in the repo:
git lfs install
- Copy the video file to the proper directory:
- Add the video as a tracked file:
git lfs track Assets/<PackName>/<video_file_name>.mp4.
- Add the file to git:
git add Assets/<PackName>/<video_file_name>.mp4
- Add the
git add .gitattributes
- Commit and push using:
- Open a pull a request
You can also embed videos from external services such as YouTube via an iframe. From the external service choose to share the video and choose the Embed option. Then choose to Copy the embed snippet.
Screenshots from YouTube:
Paste the embed snippet in the README documentation page. Make sure to change the
allowfullscreen option to include
allowfullscreen="true". For example:
- Azure Sentinel: Shows how the commands and examples should be presented.
- Slack v2: Shows an example of the troubleshooting section.
- Autofocus Query Samples and Sessions Playbook: show an embedded playbook image.
- JSON Feed: Shows use of embedding a video.
- Zoom Feed: Shows use of embedding a YouTube video.
The documentation should be posted in the content entity's directory as a
README.md file. If the content entity is not in the Directory Structure, name the documentation file the same as the yml file without the
.yml extension and with an ending of:
_README.md. For example: integration-mcafeeDam_README.md.
Once the PR with the documentation README file is merged into master, it will become available as part of the Cortex XSOAR Developer Hub. The site is updated with the latest content on a daily basis. When the deployment is complete, the documentation will be available at the reference docs section. 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.
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:
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:
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 complaint. Meaning all html tags need to contain a closing tag. For example don't use:
<br/>. Additionally, html entities
< >, not in code blocks, need to be encoded. Use
> to encode. As part of the CircleCI build, the README.md file will be validated that it is MDX complaint.