diff --git a/web_src/js/markup/anchors.ts b/web_src/js/markup/anchors.ts
index 9b25821909..2522dcee95 100644
--- a/web_src/js/markup/anchors.ts
+++ b/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-');