docs: Add custom markdownlint rule to ignore rule md014 in text code blocks

[cwhite911]

Issue identified in PR #1332 where fenced markdown code blocks trigger markdownlint rule MD014: Dollar signs used before commands without showing output.

To address this we can create a custom rule to ignore cases where the code block is text or some other custom language fence.

Custom Rules: https://github.com/DavidAnson/markdownlint/blob/main/doc/CustomRules.md

To do this we need to create a new directory

mkdir -p .markdownlint/rules

and then add our custom rule:

touch .markdownlint/rules/gs-md014-ignore-text-code-blocks.js

Here is a start to the rule that needs refinment.

"use strict";

module.exports = {
  names: ["gs-ignore-md014-in-text-code-blocks"],
  description: "Extends MD014 but ignores `text` code blocks",
  tags: ["dollar-sign", "code-block"],
  function: function MD014Extended(params, onError) {
    let insideTextBlock = false;

    params.tokens.forEach((token, index) => {
      // Detect fenced code blocks
      if (token.type === "fence") {
        const language = token.info ? token.info.trim() : "";
        insideTextBlock = language === "text"; // Track if it's a `text` block
      }

      // Skip checking MD014 inside `text` code blocks
      if (insideTextBlock) {
        return;
      }

      // Check inline text and paragraphs for unescaped `$`
      if ((token.type === "inline" || token.type === "paragraph") && token.content.includes("$")) {
        const dollarIndex = token.content.indexOf("$");

        onError({
          lineNumber: token.lineNumber,
          detail: "Dollar sign used without escaping (MD014).",
          context: token.content.substring(
            Math.max(0, dollarIndex - 5),
            dollarIndex + 5
          ),
        });
      }

      // Reset the insideTextBlock flag when leaving a fenced code block
      if (token.type === "fence" && insideTextBlock) {
        insideTextBlock = false;
      }
    });
  },
};

Once this is done we can update .pre-commit-config.yaml to run with the custom rules.

    - repo: https://github.com/igorshubovych/markdownlint-cli
        rev: v0.44.0
        hooks:
          - id: markdownlint-fix
            args: [--rules, ".markdownlint/rules/"]

[wenzeslaus]

Seems like it would be easier to open an issue for markdownlint showing false positive.