Add documentation for markdown anchor post-processing (#36443)

See discussion in https://github.com/go-gitea/gitea/pull/36284.

---------

Signed-off-by: silverwind <me@silverwind.io>
Co-authored-by: wxiaoguang <wxiaoguang@gmail.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

web_src/js/markup/anchors.ts

@@ -1,6 +1,20 @@
 import {svg} from '../svg.ts';
 
-// FIXME: don't see why these tricks make sense. If these prefixes are not needed, they should be removed entirely by backend.
+// Rendered content from users have IDs prefixed with `user-content-` to avoid conflicts with other IDs on the page.
+// - security concern: elements with IDs can affect frontend logic, for example: sending requests.
+// To make end users have better experience, the prefixes are stripped from the href attributes of links.
+// The same as GitHub: backend generates anchor `id="user-content-faq"` but the link shown to users is `href="#faq"`.
+//
+// At the moment, the anchor processing works like this:
+// - backend adds `user-content-` prefix for elements like `<h1 id>` and `<a href>`
+// - js adds the `user-content-` prefix to user-generated `<a name>` targets
+// - js intercepts the hash navigation on page load and whenever a link is clicked
+//   to add the prefix so the correct prefixed `id`/`name` element is focused
+//
+// TODO: ideally, backend should be able to generate elements with necessary anchors,
+// backend doesn't need to add the prefix to `href`, then frontend doesn't need to spend
+// time on adding new elements or removing the prefixes.
+
 const addPrefix = (str: string): string => `user-content-${str}`;
 const removePrefix = (str: string): string => str.replace(/^user-content-/, '');
 const hasPrefix = (str: string): boolean => str.startsWith('user-content-');