📚 DOCS: Clarify docs regarding security configuration (#296)

Co-authored-by: Chris Sewell <[email protected]>

README.md

@@ -17,7 +17,7 @@
 - Configurable syntax: you can add new rules and even replace existing ones.
 - Pluggable: Adds syntax extensions to extend the parser (see the [plugin list][md-plugins]).
 - High speed (see our [benchmarking tests][md-performance])
-- [Safe by default][md-security]
+- Easy to configure for [security][md-security]
 - Member of [Google's Assured Open Source Software](https://cloud.google.com/assured-open-source-software/docs/supported-packages)
 
 This is a Python port of [markdown-it], and some of its associated plugins.

docs/index.md

@@ -6,7 +6,7 @@
 - {fa}`check,text-success mr-1` Configurable syntax: you can add new rules and even replace existing ones.
 - {fa}`check,text-success mr-1` Pluggable: Adds syntax extensions to extend the parser (see the [plugin list](md/plugins))
 - {fa}`check,text-success mr-1` High speed (see our [benchmarking tests](md/performance))
-- {fa}`check,text-success mr-1` [Safe by default](md/security)
+- {fa}`check,text-success mr-1` Easy to configure for [security](md/security)
 - {fa}`check,text-success mr-1` Member of [Google's Assured Open Source Software](https://cloud.google.com/assured-open-source-software/docs/supported-packages)
 
 For a good introduction to [markdown-it] see the __[Live demo](https://markdown-it.github.io)__.

docs/security.md

@@ -2,27 +2,36 @@
 
 # Security
 
-Many people don't understand that markdown format does not care much about security.
-In many cases you have to pass output to sanitizers.
-`markdown-it` provides 2 possible strategies to produce safe output:
+By default, the `MarkdownIt` parser is initialised to comply with the [CommonMark spec](https://spec.commonmark.org/), which allows for parsing arbitrary HTML tags.
+This can be useful for many use cases, for example when writing articles for one's own blog or composing technical documentation for a software package.
 
-1. Don't enable HTML. Extend markup features with [plugins](md/plugins).
-   We think it's the best choice and use it by default.
-   - That's ok for 99% of user needs.
-   - Output will be safe without sanitizer.
-2. Enable HTML and use external sanitizer package(s).
+However, extra precautions are needed when parsing content from untrusted sources.
+Generally, the output should be run through sanitizers to ensure safety and prevent vulnerabilities like cross-site scripting (XSS).
+With `markdown-it`/`markdown-it-py`, there are two strategies for doing this:
 
-Also by default `markdown-it` prohibits some kind of links, which could be used
-for XSS:
+1. Enable HTML (as is needed for full CommonMark compliance), and then use external sanitizer package(s).
+2. Disable HTML, and then use [plugins](md/plugins) to selectively enable markup features.
+   This removes the need for further sanitizing.
+
+```{warning}
+Unlike the original `markdown-it` JavaScript project, which uses the second, safe-by-default strategy, `markdown-it-py` enables the more convenient, but less secure, CommonMark-compliant settings by default.
+
+This is not safe when using `markdown-it-py` in web applications that parse user-submitted content.
+In such cases, [using the `js-default` preset](using.md) is strongly recommended.
+For example:
+
+```python
+from markdown_it import MarkdownIt
+MarkdownIt("js-default").render("*user-submitted* text")
+```
+
+Note that even with the default configuration, `markdown-it-py` prohibits some kind of links which could be used for XSS:
 
 - `javascript:`, `vbscript:`
 - `file:`
-- `data:`, except some images (gif/png/jpeg/webp).
-
-So, by default `markdown-it` should be safe. We care about it.
+- `data:` (except some images: gif/png/jpeg/webp)
 
-If you find a security problem - contact us via <[email protected]>.
-Such reports are fixed with top priority.
+If you find a security problem, please report it to <[email protected]>.
 
 ## Plugins