docs: fix dark-mode code block contrast issues (#37736)

* docs: fix dark-mode code block contrast, plan plugin SDK reference migration

- Change the outgoing webhooks pseudo-JSON example to a `text` fence
  instead of `json`, since the malformed JSON caused Prism to
  misinterpret `//` inside a URL as a comment, rendering it as a
  distracting highlighted link in dark mode.
- Restore contrast for Prism's comment token and the active/hover
  table-of-contents link in dark mode, both of which were nearly
  invisible against the current dark background colors.
- Add a handoff plan for restoring the three plugin SDK reference pages
  that were left as migration placeholders (previously rendered by Hugo
  shortcodes parsing live Go/TS source).

* docs: remove migration plan doc from this PR

The plugin SDK reference migration plan is a separate piece of handoff
work, not part of this dark-mode contrast fix — drop it from this PR
(kept locally, untracked, for handing off separately).

---------

Co-authored-by: Hanzo Dev <[email protected]>

docs/develop/integrate/webhooks/outgoing/index.md

@@ -65,7 +65,7 @@ If you leave the channel field blank, the webhook will respond to trigger words
 2. Add a configurable *MATTERMOST_TOKEN* variable to your application and set it to the **Token** value from step 7. This value will be used by your application to confirm the HTTP POST request came from Mattermost.
 3. To have your application post a message back to `town-square`, it can respond to the HTTP POST request with a JSON response such as:
 
-    ```json
+    ```text
     {"text": "
     | Component  | Tests Run | Tests Failed                                   |
     |:-----------|:----------|:-----------------------------------------------|

docs/site/src/css/custom.css

@@ -472,11 +472,7 @@ h2, h3, h4 {
  * so it still needs lightening. #52607A (~2.9:1) is that lighter fill;
  * denim-400 below gives it a real border. Needed to go further than the
  * contrast ratio alone suggests — low-luminance colors require a bigger
- * jump than the formula implies to look distinct to the eye. Trade-off:
- * dracula's comment token (#6272a4, already its dimmest/de-emphasized one)
- * loses some contrast against this fill, acceptable since it stays
- * distinguishable via italics and this site's examples don't use inline
- * comments anyway. */
+ * jump than the formula implies to look distinct to the eye. */
 .theme-code-block .prism-code {
   font-size: 0.85rem;
   background: var(--mm-denim-50) !important;
@@ -485,6 +481,17 @@ h2, h3, h4 {
   background: #52607A !important;
 }
 
+/* Lightening the dark-mode code block fill above (#52607A) leaves
+ * dracula's comment token — already its dimmest/de-emphasized color
+ * (#6272a4) — at only ~1.35:1 contrast against it, i.e. nearly invisible.
+ * #D3DBF2 restores ~4.6:1 (WCAG AA) while staying a muted blue-lavender,
+ * distinguishable from the brighter default token colors but still legible.
+ * !important is required: prism-react-renderer sets each token's color via
+ * an inline `style` attribute, which otherwise beats this class selector. */
+[data-theme='dark'] .theme-code-block .prism-code .token.comment {
+  color: #D3DBF2 !important;
+}
+
 /* Copy button — denim border, marigold on hover */
 .clean-btn[class*="copyButton"] {
   border: 1px solid var(--mm-border-subtle) !important;
@@ -654,9 +661,14 @@ blockquote {
   padding: 0.4rem 0.75rem 0.4rem 1rem;
   font-size: 0.82rem;
 }
+/* --mm-color-denim is a fixed brand navy, not a semantic/theme-aware
+ * token — it never adapts for dark mode. Against the dark page background
+ * that's only ~1.45:1 contrast, i.e. the active TOC item nearly vanishes.
+ * --ifm-color-primary is already the theme-aware equivalent (denim in
+ * light mode, --mm-color-sky in dark, ~12:1 against the dark page). */
 .table-of-contents__link--active,
 .table-of-contents__link:hover {
-  color: var(--mm-color-denim);
+  color: var(--ifm-color-primary);
   font-weight: 600;
 }