feat: Add description_safe_mode config option (#283)

* feat: Add `description_safe_mode` config option
coveooss · Nov 29, 2024 · a17ce95 · a17ce95
1 parent dd28a3a
commit a17ce95
Show file tree

Hide file tree

Showing 99 changed files with 2,051 additions and 4,918 deletions.
diff --git a/config_schema.json b/config_schema.json
@@ -4,20 +4,15 @@
   "title": "JSON Schema for Humans configuration file",
   "description": "Choose how to generate JSON Schema for Humans documentation file.\n\nConfiguration parameters can be provided in several ways:\n\n- On the CLI using `--config parameter_name=value` (example: `--config template_name=flat`)\n- On the CLI using a config file `--config-file config.json`\n- From code, by providing a GenerationConfiguration object to the called generation method.",
   "properties": {
-    "minify": {
-      "type": "boolean",
-      "default": true,
-      "description": "[Deprecated]"
-    },
     "description_is_markdown": {
       "type": "boolean",
       "default": true,
-      "description": "Applies to HTML templates only. Whether to consider the description as Markdown and render it accordingly."
+      "description": "(HTML outputs only)\nWhether to consider the description as Markdown and render it accordingly."
     },
-    "allow_html_description": {
-      "type": "boolean",
-      "default": false,
-      "description": "Applies to HTML templates only. Don't escape HTML tags in descriptions. Can be needed when description is Markdown and contains already escaped blocks"
+    "description_safe_mode": {
+      "enum": [null, "escape", "replace"],
+      "default": "escape",
+      "description": "(HTML outputs only)\n(Only used with `description_is_markdown`)\nHow are HTML tags in descriptions handled. Correspond to the `safe_mode` option of the markdown2 library.\n\n- \"escape\": Escape all HTML tags in descriptions\n- \"replace\": Replace HTML tags with `[HTML_REMOVED]`\n- null: Allow HTML in descriptions"
     },
     "expand_buttons": {
       "type": "boolean",
@@ -52,7 +47,7 @@
     "deprecated_from_description": {
       "type": "boolean",
       "default": false,
-      "description": "Mark a property as deprecated (with a big red badge) if the description contains the string `[Deprecated`."
+      "description": "Mark a property as deprecated (with a big red badge) if the description contains the string `[\u200BDeprecated`."
     },
     "default_from_description": {
       "type": "boolean",
@@ -69,10 +64,6 @@
       "default": true,
       "description": "Copy `schema_doc.min.js` to the same directory as `RESULT_FILE` after generation.\n\nThis file contains the logic for the anchor links."
     },
-    "templates_directory": {
-      "type": "string",
-      "description": "[Deprecated]"
-    },
     "template_name": {
       "type": "string",
       "enum": [
@@ -171,6 +162,20 @@
       "type": "boolean",
       "description": "Whether the footer should display the generation time",
       "default": true
+    },
+    "allow_html_description": {
+      "type": "boolean",
+      "default": false,
+      "description": "[Deprecated]"
+    },
+    "minify": {
+      "type": "boolean",
+      "default": true,
+      "description": "[Deprecated]"
+    },
+    "templates_directory": {
+      "type": "string",
+      "description": "[Deprecated]"
     }
   }
 }
diff --git a/docs/Examples.md b/docs/Examples.md
@@ -1608,6 +1608,72 @@ the description of an attribute
 [examples/examples_md_nested_with_badges/geo.md](examples/examples_md_nested_with_badges/geo.md ':include')
 </details>
 
+## --html_in_description--
+### html_in_description
+
+
+<details>
+<summary>Json schema - Click here to expand source code...</summary>
+
+[examples/cases/html_in_description.json](examples/cases/html_in_description.json ':include :type=code')
+</details>
+
+
+<details>
+<summary>JS template - Click here to expand the rendered result...</summary>
+<a href="https://coveooss.github.io/json-schema-for-humans/examples/examples_js_default/html_in_description.html" target="_blank">Open it in full page</a>
+
+[examples/examples_js_default/html_in_description.html](examples/examples_js_default/html_in_description.html ':include :type=iframe width=100% height=400px')
+</details>
+
+
+<details>
+<summary>JS Offline template - Click here to expand the rendered result...</summary>
+<a href="https://coveooss.github.io/json-schema-for-humans/examples/examples_js_offline_default/html_in_description.html" target="_blank">Open it in full page</a>
+
+[examples/examples_js_offline_default/html_in_description.html](examples/examples_js_offline_default/html_in_description.html ':include :type=iframe width=100% height=400px')
+</details>
+
+
+<details>
+<summary>Flat template - Click here to expand the rendered result...</summary>
+<a href="https://coveooss.github.io/json-schema-for-humans/examples/examples_flat_default/html_in_description.html" target="_blank">Open it in full page</a>
+
+[examples/examples_flat_default/html_in_description.html](examples/examples_flat_default/html_in_description.html ':include :type=iframe width=100% height=400px')
+</details>
+
+
+<details>
+<summary>Markdown without badge template - Click here to expand the rendered result...</summary>
+<a href="https://github.com/coveooss/json-schema-for-humans/blob/main/docs/examples/examples_md_default/html_in_description.md" target="_blank">Open it in github</a>
+
+[examples/examples_md_default/html_in_description.md](examples/examples_md_default/html_in_description.md ':include')
+</details>
+
+
+<details>
+<summary>Markdown with badges template - Click here to expand the rendered result...</summary>
+<a href="https://github.com/coveooss/json-schema-for-humans/blob/main/docs/examples/examples_md_with_badges/html_in_description.md" target="_blank">Open it in github</a>
+
+[examples/examples_md_with_badges/html_in_description.md](examples/examples_md_with_badges/html_in_description.md ':include')
+</details>
+
+
+<details>
+<summary>Nested Markdown without badges template - Click here to expand the rendered result...</summary>
+<a href="https://github.com/coveooss/json-schema-for-humans/blob/main/docs/examples/examples_md_nested_default/html_in_description.md" target="_blank">Open it in github</a>
+
+[examples/examples_md_nested_default/html_in_description.md](examples/examples_md_nested_default/html_in_description.md ':include')
+</details>
+
+
+<details>
+<summary>Nested Markdown with badges template - Click here to expand the rendered result...</summary>
+<a href="https://github.com/coveooss/json-schema-for-humans/blob/main/docs/examples/examples_md_nested_with_badges/html_in_description.md" target="_blank">Open it in github</a>
+
+[examples/examples_md_nested_with_badges/html_in_description.md](examples/examples_md_nested_with_badges/html_in_description.md ':include')
+</details>
+
 ## --html_in_patterns--
 ### html_in_patterns
 

diff --git a/docs/examples/cases/html_in_description.json b/docs/examples/cases/html_in_description.json
@@ -0,0 +1,23 @@
+{
+  "$id": "https://example.com/html.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "HTML in descriptions",
+  "type": "object",
+  "properties": {
+    "raw_html": {
+      "type": "string",
+      "description": "<br/><br/><br/><br/><a href=\"https://example.com\">A link to example.com</a>",
+      "title": "Some raw HTML"
+    },
+    "html_in_markdown": {
+      "type": "string",
+      "description": "Here is some HTML:\n```html\n<br/><br/><br/><br/><a href=\"https://example.com\">A link to example.com</a>\n```",
+      "title": "Some HTML in Markdown"
+    },
+    "json_in_markdown": {
+      "type": "string",
+      "description": "Here is some JSON:\n```json\n{\n  \"property\": \"value\"\n}\n```",
+      "title": "Some JSON in Markdown"
+    }
+  }
+}