Clarify sanitizer documentation

Signed-off-by: Alexander Scheel <[email protected]>

docs/content/doc/advanced/config-cheat-sheet.en-us.md

@@ -646,7 +646,7 @@ Two special environment variables are passed to the render command:
 Gitea supports customizing the sanitization policy for rendered HTML. The example below will support KaTeX output from pandoc.
 
 ```ini
-[markup.sanitizer.1]
+[markup.sanitizer.TeX]
 ; Pandoc renders TeX segments as <span>s with the "math" class, optionally
 ; with "inline" or "display" classes depending on context.
 ELEMENT = span
@@ -658,11 +658,41 @@ REGEXP = ^\s*((math(\s+|$)|inline(\s+|$)|display(\s+|$)))+
  - `ALLOW_ATTR`: The attribute this policy allows. Must be non-empty.
  - `REGEXP`: A regex to match the contents of the attribute against. Must be present but may be empty for unconditional whitelisting of this attribute.
 
-You must define `ELEMENT`, `ALLOW_ATTR`, and `REGEXP` in each numbered section.
+**Note**: The above section naming policy is new; previously the section was `[markup.sanitizer]` and keys could be redefined.
+Now, a unique identifier must appear in the section name (e.g., `[markup.sanitizer.TeX]`) in order to parse multiple rules.
+This was changed because the implementation with the ini parser used was flawed; the following configs were indistinguishable after parsing:
 
-To define multiple entries, increment the number in the section (e.g., `[markup.sanitizer.1]` and `[markup.sanitizer.2]`).
+```ini
+[markup.sanitizer]
+ELEMENT = a
+ALLOW_ATTR = target
+REGEXP = $1
+ELEMENT = a
+ALLOW_ATTR = rel
+REGEXP = $2
+ELEMENT = img
+ALLOW_ATTR = src
+REGEXP = $3
+```
+
+and
+
+```ini
+[markup.sanitizer]
+ELEMENT = a
+ALLOW_ATTR = target
+REGEXP = $1
+ELEMENT = img
+ALLOW_ATTR = rel
+REGEXP = $2
+ELEMENT = img
+ALLOW_ATTR = src
+REGEXP = $3
+```
+
+Because of limitations in the ini library, we are unable to automatically migrate configurations.
 
-**Note**: The above section numbering policy is new; previously the section was `[markup.sanitizer]` and keys could be redefined.
+We will still parse the first rule from a `[markup.sanitizer]` section if present, but multiple rules must be manually migrated.
 
 ## Time (`time`)
 

docs/content/doc/advanced/external-renderers.en-us.md

@@ -73,7 +73,7 @@ IS_INPUT_FILE = false
 If your external markup relies on additional classes and attributes on the generated HTML elements, you might need to enable custom sanitizer policies. Gitea uses the [`bluemonday`](https://godoc.org/github.com/microcosm-cc/bluemonday) package as our HTML sanitizier. The example below will support [KaTeX](https://katex.org/) output from [`pandoc`](https://pandoc.org/).
 
 ```ini
-[markup.sanitizer.1]
+[markup.sanitizer.TeX]
 ; Pandoc renders TeX segments as <span>s with the "math" class, optionally
 ; with "inline" or "display" classes depending on context.
 ELEMENT = span
@@ -86,9 +86,10 @@ FILE_EXTENSIONS = .md,.markdown
 RENDER_COMMAND = pandoc -f markdown -t html --katex
 ```
 
-You must define `ELEMENT`, `ALLOW_ATTR`, and `REGEXP` in each numbered section.
+You must define `ELEMENT`, `ALLOW_ATTR`, and `REGEXP` in each section.
 
-To define multiple entries, increment the number in the section (e.g., `[markup.sanitizer.1]` and `[markup.sanitizer.2]`).
+To define multiple entries, define different section names (e.g., `[markup.sanitizer.1]` and `[markup.sanitizer.2]`).
+These can be numbers, identifying names, or anything else.
 
 Once your configuration changes have been made, restart Gitea to have changes take effect.