From f0e921b6104473757271db4f3c1f097f2beefaaf Mon Sep 17 00:00:00 2001 From: YuvHayun Date: Tue, 19 Nov 2024 18:01:42 +0200 Subject: [PATCH] update documentation --- .../images_in_documentation_files.md | 78 +++---------------- docs/documentation/pack-docs.md | 3 +- 2 files changed, 12 insertions(+), 69 deletions(-) diff --git a/docs/documentation/images_in_documentation_files.md b/docs/documentation/images_in_documentation_files.md index cf4798cd9..f669cac9d 100644 --- a/docs/documentation/images_in_documentation_files.md +++ b/docs/documentation/images_in_documentation_files.md @@ -7,82 +7,26 @@ title: Images in Documentation Files Images in documentation markdown files are divided into 2 different types: - Images that appear in integration/script/playbook readmes. These images only appear in https://xsoar.pan.dev/. They do not appear in the Cortex XSOAR/XSIAM product UI. -- Images that appear in pack readmes and integration description files. These images appear in both https://xsoar.pan.dev/ and in the Cortex XSOAR/XSIAM product UI. +- Images that appear in pack readmes and integration description files. These images appear in both https://xsoar.pan.dev/ and in the Cortex XSOAR/XSIAM product UI. -## Integration/Script/Playbook Readme Images +## Rules for uploading images to markdown files: -When creating markdown `README` documents for playbooks, integrations, or scripts that appear in https://xsoar.pan.dev/ only, you can use a relative or absolute URL. +When creating markdown documentation files, you should use a relative path to the `doc_files` folder located in the pack's root path. -### Relative Image URLs for Integration/Script/Playbook Readmes -You can use relative URLs to documentation images stored in the `doc_files` or `doc_imgs` directories. To use relative URLs simply link the image using a relative path such as: +### Relative Image paths +You should use relative paths to documentation images stored in the `doc_files` directories. To use relative paths simply link the image using a relative path such as: ``` ![Setup Account](./../../doc_files/create-account.png) ``` -Make sure to view the `README.md` file in GitHub's web interface and validate that the images display properly. +Make sure to view the image by clicking the path to ensure you've typed in the right path, and view the `README.md` file in GitHub's web interface and validate that the images display properly. -**Documentation with Relative URL examples:** +**Documentation with Relative path 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 -### Absolute Image URLs for Integration/Script/Playbook Readmes +### Absolute URLs -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 `Download` button. -* 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 `master` branch. -* Note: if you click the `Download` button, 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: -``` -![Playbook Image](https://github.com/demisto/content/raw/2d6e082cfb181f823e5b1446ae71e10537591ea6/Packs/AutoFocus/doc_files/AutoFocusPolling.png) -``` -If you want more control on the image (for example setting width dimension) you can use the HTML `` tag, such as: - -``` - -``` -**Screenshot of `Download` button:** -![Github Download](/doc_imgs/integrations/github-download-button.png) - -**Absolute Image URL Examples:** -* URL to commit hash: https://github.com/demisto/content/raw/2d6e082cfb181f823e5b1446ae71e10537591ea6/Packs/AutoFocus/doc_files/AutoFocusPolling.png -* URL to `master` branch: https://github.com/demisto/content/raw/master/Packs/AutoFocus/doc_files/AutoFocusPolling.png -* URL after redirection (also valid): https://raw.githubusercontent.com/demisto/content/master/Packs/AutoFocus/doc_files/AutoFocusPolling.png - -:::note -To keep our main Content repo small we limit images to 2MB. For larger images, follow the instructions for [Videos](#videos) on how to store large media files in our [content-assets](https://github.com/demisto/content-assets) repository. -::: - -## Pack Readmes and Integration Description Files Images - -When creating a markdown pack `README` or an integration description file for XSOAR/XSIAM entities you must use an absolute URL. - -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 `Download` button. -* 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 `master` branch. -* Note: if you click the `Download` button, 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: -``` -![Playbook Image](https://github.com/demisto/content/raw/2d6e082cfb181f823e5b1446ae71e10537591ea6/Packs/AutoFocus/doc_files/AutoFocusPolling.png) -``` - -**Screenshot of `Download` button:** -![Github Download](/doc_imgs/integrations/github-download-button.png) - -**Absolute Image URL Examples:** -* URL to commit hash: https://github.com/demisto/content/raw/2d6e082cfb181f823e5b1446ae71e10537591ea6/Packs/AutoFocus/doc_files/AutoFocusPolling.png -* URL to `master` branch: https://github.com/demisto/content/raw/master/Packs/AutoFocus/doc_files/AutoFocusPolling.png -* URL after redirection (also valid): https://raw.githubusercontent.com/demisto/content/master/Packs/AutoFocus/doc_files/AutoFocusPolling.png - -:::note -To keep our main Content repo small we limit images to 2MB. For larger images, follow the instructions for [Videos](#videos) on how to store large media files in our [content-assets](https://github.com/demisto/content-assets) repository. -::: \ No newline at end of file +Note that this case is only relevant when dealing with larger file types (such as gif and mp4 files). +In the case, the file should be uploaded to `content-assets` repo. +For more information, please refer to [absolute image urls](../documentation/readme_file#absolute-image-urls). diff --git a/docs/documentation/pack-docs.md b/docs/documentation/pack-docs.md index 979af8c91..50fb0b719 100644 --- a/docs/documentation/pack-docs.md +++ b/docs/documentation/pack-docs.md @@ -74,8 +74,7 @@ Note that "Cortex XSOAR Developer Docs" should link **directly to the readme of ![image](https://user-images.githubusercontent.com/43602124/88673366-31d59c80-d0f1-11ea-9319-b7d9f2fb8625.png) ### Images -Images can provide a great addition to the Pack `README.md` and can help users to get a quick understanding of the Pack. Images can be included only as **absolute** urls. See the [following for instructions](../documentation/readme_file#absolute-image-urls). - +Images can provide a great addition to the Pack `README.md` and can help users to get a quick understanding of the Pack. Images can be included only as **relative** paths. See the [following for instructions](../documentation/images_in_documentation_files). ### Videos It is possible to add an image placeholder which links to an external video. For example to add an external video hosted on YouTube use the following snippet template (replace `[YOUTUBE_VIDEO_ID]` with the YouTube video ID): ```